---
name: bijection-files-control
description: "Evaluate and integrate the Files Control component with Bijection."
---

# Files Control

A Bijection files control component for Bijection.

- Package: @bijectionhq/files-control
- Category: Storage
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/files-control/tree/97f66c96257b27900fa81e5fda9024e857bfbfcc
- Upstream: https://github.com/gilhrpenner/convex-files-control/tree/54c6c047b4a085f0d03f7ff8841316a1d0f85bab
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/files-control

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/files-control.git
cd files-control
git checkout 97f66c96257b27900fa81e5fda9024e857bfbfcc
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @gilhrpenner/convex-files-control. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Files Control. Follow the installation and configuration steps exactly.

# Files Control

## Instructions

Files Control provides secure file upload and download workflows with granular access control for Convex applications. It implements two-step uploads with presigned URLs, download grants with usage limits and expiration, and access-key based authorization. The component works with both Convex storage and Cloudflare R2, includes optional HTTP routes for direct uploads/downloads, and provides automated cleanup of expired files and grants.

### Installation

```bash
npm install @gilhrpenner/convex-files-control
```

Current npm version: `@gilhrpenner/convex-files-control@0.5.9`

## Use cases

- **Multi-tenant applications** that need to isolate file access by user ID, organization ID, or other access keys without exposing files across tenants
- **Document sharing workflows** where you need time-limited download links with usage caps, optional password protection, and both private and public sharing modes
- **Large file uploads** that require presigned URL flows to avoid hitting serverless function limits while maintaining security and validation
- **Hybrid storage architectures** that need to seamlessly transfer files between Convex storage and R2 based on usage patterns or cost optimization
- **Applications with strict file lifecycle management** requiring automated cleanup of expired uploads, unused grants, and temporary files

## How it works

The component uses a two-step upload process where you first call `generateUploadUrl` to get a presigned URL and upload token, upload the file directly to storage, then call `finalizeUpload` with access keys to register the file. Access control is enforced through normalized access keys (user IDs, tenant IDs, etc.) that you provide during finalization.

Download security works through grants created with `createDownloadGrant` that specify max uses, expiration times, and optional passwords. The `buildDownloadUrl` function generates secure URLs, while the optional HTTP router in `registerRoutes` handles direct upload/download requests with customizable auth hooks like `checkUploadRequest` and `checkDownloadRequest`.

The component stores its own access control metadata while your app maintains file records (names, owners, etc.) in separate tables. Built-in queries like `listFilesByAccessKeyPage` and `hasAccessKey` let you build file management UIs, while `cleanupExpired` removes expired uploads, grants, and files when run in scheduled jobs.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Files Control is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40gilhrpenner%2Fconvex-files-control)
- [GitHub repository](https://github.com/gilhrpenner/convex-files-control)
- [Live demo](https://convex-files-control-example.pages.dev/)
- [Convex Components Directory](https://www.convex.dev/components/files-control)
- [Convex documentation](https://docs.convex.dev)