@gilhrpenner/convex-files-control 0.1.1 → 0.3.0

package/README.md

@@ -1,90 +1,114 @@
 # Convex Files Control
 
-A robust, secure file management component for Convex, featuring access control,
-temporary download links, and automatic cleanup.
+A Convex component for secure file uploads, access control, download grants, and
+lifecycle cleanup. Works with Convex storage and Cloudflare R2, and ships with
+an optional HTTP upload/download router plus a React upload hook.
+
+**[Live Demo →](https://convex-files-control-example.pages.dev)**
 
 ## Features
 
-- **Secure Uploads**: Support for both presigned URLs (client-side) and HTTP
-  actions (server-side).
-- **Access Control**: Granular file access using "Access Keys" (e.g., User IDs,
-  Tenant IDs).
-- **Secure Downloads**: Generate temporary, single-use, or limited-use download
+- Two-step uploads (presigned URL) with access keys and optional expiration.
+- Optional HTTP upload/download routes with auth hooks.
+- Download grants with max uses, expiration, optional password, and shareable
   links.
-- **Expiration & Cleanup**: Built-in support for file expiration and automatic
-  background cleanup.
-- **Metadata**: Computes and returns SHA-256 checksums, size, and MIME type.
+- Access-key based authorization (user IDs, tenant IDs, etc.).
+- Built-in cleanup for expired uploads, grants, and files.
+- Transfer files between Convex and R2.
+- React hook for presigned or HTTP uploads.
 
-## Installation
+## Install
 
 ```bash
 npm install @gilhrpenner/convex-files-control
 ```
 
-## Setup
-
-### 1. Configure Component
+## Quick start
 
-Add the component to your `convex.config.ts`:
+### 1) Add the component
 
-```typescript
+```ts
 // convex.config.ts
 import { defineApp } from "convex/server";
-import filesControl from "@gilhrpenner/convex-files-control/convex.config";
+import convexFilesControl from "@gilhrpenner/convex-files-control/convex.config";
 
 const app = defineApp();
-app.use(filesControl);
+app.use(convexFilesControl);
 
 export default app;
 ```
 
-### 2. Expose the API
+### 2) Create wrapper functions in your app
 
-Create a file (e.g., `convex/files.ts`) with server-side wrappers that call into
-the component. Only export the functions you actually want callable from the client.
+The component stores access control and download grants. Your app should store
+its own file metadata (name, owner, etc.) and enforce auth. The wrappers below
+mirror the example app in `example/convex/files.ts`.
 
-```typescript
+```ts
 // convex/files.ts
-import { v } from "convex/values";
+import { ConvexError, v } from "convex/values";
 import { mutation } from "./_generated/server";
 import { components } from "./_generated/api";
 
-// Expose only the client-facing download operation (with your auth rules)
-export const createDownloadGrant = mutation({
+export const generateUploadUrl = mutation({
   args: {
-    storageId: v.id("_storage"),
-    maxUses: v.optional(v.union(v.null(), v.number())),
-    expiresAt: v.optional(v.union(v.null(), v.number())),
+    provider: v.union(v.literal("convex"), v.literal("r2")),
   },
   handler: async (ctx, args) => {
-    // Example auth: const identity = await ctx.auth.getUserIdentity();
-    // if (!identity) throw new Error("Unauthorized");
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) throw new ConvexError("Unauthorized");
+
     return await ctx.runMutation(
-      components.convexFilesControl.download.createDownloadGrant,
-      args,
+      components.convexFilesControl.upload.generateUploadUrl,
+      {
+        provider: args.provider,
+        // r2Config: { accountId, accessKeyId, secretAccessKey, bucketName },
+      },
     );
   },
 });
 
-// Wrap other component functions in server-side mutations/actions as needed.
-// For example, upload support via presigned URLs:
-export const generateUploadUrl = mutation({
-  args: {},
-  handler: async (ctx) => {
-    return await ctx.runMutation(
-      components.convexFilesControl.upload.generateUploadUrl,
-      {},
+export const finalizeUpload = mutation({
+  args: {
+    uploadToken: v.string(),
+    storageId: v.string(),
+    fileName: v.string(),
+    expiresAt: v.optional(v.union(v.null(), v.number())),
+    metadata: v.optional(
+      v.object({
+        size: v.number(),
+        sha256: v.string(),
+        contentType: v.union(v.string(), v.null()),
+      }),
+    ),
+  },
+  handler: async (ctx, args) => {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) throw new ConvexError("Unauthorized");
+
+    const { fileName, ...componentArgs } = args;
+    const result = await ctx.runMutation(
+      components.convexFilesControl.upload.finalizeUpload,
+      {
+        ...componentArgs,
+        accessKeys: [identity.subject],
+      },
     );
+
+    // Store your own file record (name, owner, etc.) here.
+    // await ctx.db.insert("files", { ... });
+
+    return result;
   },
 });
 ```
 
-### 3. Setup HTTP Routes (Optional)
+### 3) Optional HTTP routes
 
-If you want to support direct HTTP uploads or downloads (proxied through
-Convex), register the routes in `convex/http.ts`.
+If you want `/files/upload` and `/files/download`, register the router in
+`convex/http.ts`. Access keys are provided by your hook (not via the form).
 
-```typescript
+```ts
 // convex/http.ts
 import { httpRouter } from "convex/server";
 import { registerRoutes } from "@gilhrpenner/convex-files-control";
@@ -93,236 +117,272 @@ import { components } from "./_generated/api";
 const http = httpRouter();
 
 registerRoutes(http, components.convexFilesControl, {
-  pathPrefix: "/files", // Routes will be /files/download (upload is opt-in)
-  requireAccessKey: false, // Set to true to enforce accessKey param on downloads
-  enableUploadRoute: true, // Opt-in to /files/upload
+  pathPrefix: "files",
+  enableUploadRoute: true,
+
+  // Required when enableUploadRoute is true
+  checkUploadRequest: async (ctx) => {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) {
+      return new Response(JSON.stringify({ error: "Unauthorized" }), {
+        status: 401,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+
+    return { accessKeys: [identity.subject] };
+  },
+
+  // Optional: persist file metadata after a successful HTTP upload
+  onUploadComplete: async (ctx, { result, file, formData }) => {
+    const fileNameFromForm = formData.get("fileName");
+    const fileName =
+      typeof fileNameFromForm === "string"
+        ? fileNameFromForm
+        : (file as File).name ?? "untitled";
+    // await ctx.runMutation(api.files.recordUpload, { ...result, fileName });
+  },
+
+  // Optional: provide accessKey for downloads
+  checkDownloadRequest: async (ctx) => {
+    const identity = await ctx.auth.getUserIdentity();
+    if (identity) return { accessKey: identity.subject };
+  },
 });
 
 export default http;
 ```
 
-## Usage
+HTTP upload requires `multipart/form-data` with fields:
+
+- `file` (required)
+- `provider` (optional, "convex" | "r2")
+- `expiresAt` (optional, timestamp or `null`)
+
+Access keys are not accepted via the form; they must come from
+`checkUploadRequest`. Additional form fields are available on
+`onUploadComplete` via `formData`.
 
-### Uploading Files
+Useful route options:
 
-#### Option A: Presigned URL (Recommended)
+- `pathPrefix` (default: `/files`)
+- `defaultUploadProvider` (`\"convex\"` or `\"r2\"`)
+- `enableDownloadRoute` (default: `true`)
+- `requireAccessKey` (force `checkDownloadRequest` to return an access key)
+- `passwordHeader` / `passwordQueryParam` (override or disable password inputs)
 
-This is the most efficient method, uploading directly from the client to Convex
-storage.
+## Uploading files
 
-1.  **Generate Upload URL**: Call your exposed `generateUploadUrl` mutation.
-2.  **Upload File**: POST the file to the returned `uploadUrl`.
-3.  **Finalize**: Call `finalizeUpload` with the `uploadToken` and `storageId`.
+### Presigned URL flow
 
-```typescript
-// Client-side example
-const { uploadUrl, uploadToken } = await generateUploadUrl();
+```ts
+// Client-side
+const { uploadUrl, uploadToken } = await generateUploadUrl({
+  provider: "convex",
+});
 
-const result = await fetch(uploadUrl, {
+const uploadResponse = await fetch(uploadUrl, {
   method: "POST",
-  body: fileBlob, // your file object
-  headers: { "Content-Type": fileBlob.type },
+  body: file,
+  headers: { "Content-Type": file.type || "application/octet-stream" },
 });
-const { storageId } = await result.json();
 
-const fileParams = {
+const { storageId } = await uploadResponse.json();
+
+const result = await finalizeUpload({
   uploadToken,
   storageId,
-  accessKeys: ["user_123"], // Who can access this file?
-  expiresAt: Date.now() + 24 * 60 * 60 * 1000, // Optional expiration
-};
-
-const metadata = await finalizeUpload(fileParams);
-console.log("File uploaded:", metadata);
-```
-
-#### Option B: HTTP Action
-
-Upload directly via your configured HTTP endpoint.
-
-```typescript
-const formData = new FormData();
-formData.append("file", fileBlob);
-formData.append("accessKeys", JSON.stringify(["user_123"]));
-// Optional: formData.append("expiresAt", timestamp);
-
-await fetch("https://<your-convex-site>/files/upload", {
-  method: "POST",
-  body: formData,
+  fileName: file.name,
+  expiresAt: Date.now() + 60 * 60 * 1000,
 });
 ```
 
-### React Hook (Optional)
-
-If you're using React, the component exports a `useUploadFile` hook that supports
-both upload methods with a single API. The HTTP method requires `registerRoutes`
-to be set up in `convex/http.ts`.
+### React hook
 
 ```tsx
 import { useUploadFile } from "@gilhrpenner/convex-files-control/react";
 import { api } from "../convex/_generated/api";
 
-const convexSiteUrl = import.meta.env.VITE_CONVEX_URL.replace(".cloud", ".site");
+const convexSiteUrl = import.meta.env.VITE_CONVEX_URL.replace(
+  ".cloud",
+  ".site",
+);
 
 const { uploadFile } = useUploadFile(api.files, {
+  method: "presigned",
   http: { baseUrl: convexSiteUrl },
 });
 
-// Presigned URL upload
-await uploadFile({
-  file,
-  accessKeys: ["user_123"],
-  expiresAt: Date.now() + 60 * 60 * 1000,
-  method: "presigned",
-});
+// Presigned
+await uploadFile({ file, provider: "convex" });
 
-// HTTP action upload
+// HTTP route
 await uploadFile({
   file,
-  accessKeys: ["user_123"],
   method: "http",
+  provider: "convex",
+  http: {
+    baseUrl: convexSiteUrl,
+    // authToken: useAuthToken() from @convex-dev/auth/react
+  },
 });
 ```
 
-The hook returns the same metadata you get from `finalizeUpload`/HTTP upload, so
-you can persist it in your own tables if needed.
+`uploadFile` accepts:
 
-### Downloading Files
+- `file` (required)
+- `provider` ("convex" | "r2")
+- `expiresAt` (timestamp or `null`)
+- `method` ("presigned" | "http")
 
-To download a file securely, you create a "Download Grant". This generates a
-token that can be exchanged for the file content.
+## Downloading files
 
-1.  **Create Grant**: Call `createDownloadGrant` with the `storageId`.
-2.  **Build URL**: Use the helper to construct the download link.
+### Create a grant + build a URL
 
-```typescript
+```ts
 import { buildDownloadUrl } from "@gilhrpenner/convex-files-control";
 
-// Server-side (Mutation)
-export const generateLink = mutation({
-  args: { storageId: v.id("_storage") },
-  handler: async (ctx, args) => {
-    // 1. Create a grant (e.g., valid for 1 use)
-    const grant = await ctx.runMutation(api.files.createDownloadGrant, {
-      storageId: args.storageId,
-      maxUses: 1, // Optional: limit uses
-      expiresAt: Date.now() + 60 * 1000, // Optional: limit time
-    });
-
-    // 2. Build the URL
-    // You'll need your Convex HTTP site URL e.g. from process.env.CONVEX_SITE_URL
-    return buildDownloadUrl({
-      baseUrl: "https://<your-convex-site>",
-      downloadToken: grant.downloadToken,
-      filename: "report.pdf", // Optional: force filename
-      // accessKey: "user_123" // Optional: if you want to embed the key (less secure)
-    });
+const grant = await ctx.runMutation(
+  components.convexFilesControl.download.createDownloadGrant,
+  {
+    storageId,
+    maxUses: 1,
+    expiresAt: Date.now() + 10 * 60 * 1000,
+    shareableLink: false,
   },
+);
+
+const url = buildDownloadUrl({
+  baseUrl: "https://<your-convex-site>",
+  downloadToken: grant.downloadToken,
+  filename: "report.pdf",
+  // pathPrefix: "/files", // Optional if you changed the HTTP route prefix
 });
 ```
 
-The user then visits this URL. The component validates the grant and redirects
-to the secure storage URL.
+Access keys are not placed in the URL. For private grants, supply them via
+`checkDownloadRequest` (HTTP route) or pass `accessKey` when calling
+`consumeDownloadGrantForUrl`.
 
-#### Password-Protected Download Grants
+### Shareable links
 
-You can optionally protect a grant with a password. The component hashes the
-password using PBKDF2-SHA256 with a per-grant salt and only stores the hash.
+Set `shareableLink: true` to allow unauthenticated downloads (no access key
+required). This is how the example app generates public links. If you enable
+`requireAccessKey` on the HTTP route, shareable links will still require
+`checkDownloadRequest` to return an access key.
 
-```typescript
-// Server-side (Mutation)
-export const generatePasswordLink = mutation({
-  args: { storageId: v.id("_storage") },
-  handler: async (ctx, args) => {
-    const grant = await ctx.runMutation(api.files.createDownloadGrant, {
-      storageId: args.storageId,
-      password: "secret-passphrase",
-    });
-
-    return buildDownloadUrl({
-      baseUrl: "https://<your-convex-site>",
-      downloadToken: grant.downloadToken,
-      filename: "report.pdf",
-    });
-  },
-});
+### Password-protected grants
+
+```ts
+const grant = await ctx.runMutation(
+  components.convexFilesControl.download.createDownloadGrant,
+  { storageId, password: "secret-passphrase" },
+);
 ```
 
-To consume a password-protected grant, pass the password to
-`consumeDownloadGrantForUrl`:
+To consume a password-protected grant, pass `password` to
+`consumeDownloadGrantForUrl`, or send it to the HTTP route via the
+`x-download-password` header (preferred) or the `password` query param. Query
+params can leak into logs, so headers or POST flows are safer.
+
+## Access control & queries
+
+Access keys are normalized (trimmed) and must contain at least one non-empty
+value.
+
+- `accessControl.addAccessKey(storageId, accessKey)`
+- `accessControl.removeAccessKey(storageId, accessKey)`
+- `accessControl.updateFileExpiration(storageId, expiresAt)`
+- `queries.hasAccessKey(storageId, accessKey)`
+- `queries.listAccessKeysPage(storageId, paginationOpts)`
+- `queries.listFilesPage(paginationOpts)`
+- `queries.listFilesByAccessKeyPage(accessKey, paginationOpts)`
+- `queries.listDownloadGrantsPage(paginationOpts)`
+- `queries.getFile({ storageId })`
+
+Pagination uses `{ numItems: number, cursor: string | null }`.
+
+## Cleanup
+
+Use `cleanUp.cleanupExpired` to delete expired uploads, grants, and files. The
+example app wraps this in a mutation and runs it in a cron job.
+
+```ts
+// convex/crons.ts
+import { cronJobs } from "convex/server";
+import { internal } from "./_generated/api";
 
-```typescript
-const result = await ctx.runMutation(
-  components.convexFilesControl.download.consumeDownloadGrantForUrl,
-  { downloadToken, accessKey, password: "secret-passphrase" },
+const crons = cronJobs();
+crons.hourly(
+  "cleanup-expired-files",
+  { minuteUTC: 0 },
+  internal.files.cleanupExpiredFiles,
+  {},
 );
+export default crons;
 ```
 
-If you use the HTTP GET download route, you can send the password via the
-`x-download-password` header (preferred) or a `password` query param. Note that
-query params can appear in logs and caches, so headers or POST flows are safer.
+## Server-side helper (FilesControl)
 
-#### Rate Limiting Downloads
+If you prefer a class wrapper around component calls, use `FilesControl`:
 
-If you want to rate limit downloads, use the `checkDownloadRequest` hook when
-registering routes and call your preferred rate limiter there.
+```ts
+import { FilesControl } from "@gilhrpenner/convex-files-control";
+import { components } from "./_generated/api";
 
-```typescript
-registerRoutes(http, components.convexFilesControl, {
-  checkDownloadRequest: async (_ctx, { request }) => {
-    const ip =
-      request.headers.get("x-forwarded-for") ??
-      request.headers.get("cf-connecting-ip") ??
-      "unknown";
-
-    // Call your rate limiter here. Return a Response to short-circuit.
-    if (ip === "blocked") {
-      return new Response(JSON.stringify({ error: "Too many requests" }), {
-        status: 429,
-        headers: { "Content-Type": "application/json" },
-      });
-    }
-  },
+const files = new FilesControl(components.convexFilesControl, {
+  // r2: { accountId, accessKeyId, secretAccessKey, bucketName },
 });
+
+await files.generateUploadUrl(ctx, { provider: "convex" });
 ```
 
-### Managing Files
+`FilesControl.clientApi()` also returns a ready-to-export API surface with
+optional hooks if you want the component to generate your Convex mutations and
+queries for you.
 
-#### Access Control
+## R2 configuration
 
-Files are protected by "Access Keys". A user can only access a file if they have
-a matching key (e.g., their User ID).
+Provide R2 credentials when you use R2 for uploads, downloads, deletes, or
+transfers. You can pass `r2Config` to the component calls or supply env vars for
+the HTTP routes:
 
-- `addAccessKey(storageId, accessKey)`
-- `removeAccessKey(storageId, accessKey)`
-- `hasAccessKey(storageId, accessKey)`
-- `listAccessKeysPage(storageId, paginationOpts)`
+- `R2_ACCOUNT_ID`
+- `R2_ACCESS_KEY_ID`
+- `R2_SECRET_ACCESS_KEY`
+- `R2_BUCKET_NAME`
 
-#### File Listings (Paginated)
+## Transfer between providers
 
-- `listFilesPage(paginationOpts)`: List files using cursor-based pagination.
-- `listFilesByAccessKeyPage(accessKey, paginationOpts)`: List files for a specific user.
+```ts
+const result = await ctx.runAction(
+  components.convexFilesControl.transfer.transferFile,
+  { storageId, targetProvider: "r2", r2Config },
+);
+```
 
-`paginationOpts` is the standard Convex pagination object:
-`{ numItems: number, cursor: string | null }`.
+The transfer preserves access keys and download grants, updates the file record,
+and deletes the original storage object.
 
-#### Cleanup
+## Testing helper
 
-The component includes a `cleanupExpired` mutation. It is recommended to
-schedule this to run periodically (e.g., via Convex Crons) to remove expired
-files and unused grants.
+```ts
+import { convexTest } from "convex-test";
+import { register } from "@gilhrpenner/convex-files-control/test";
 
-```typescript
-// convex/crons.ts
-import { cronJobs } from "convex/server";
-import { api } from "./_generated/api";
+const t = convexTest(schema, modules);
+register(t, "convexFilesControl");
+```
 
-const crons = cronJobs();
+## Example app
 
-// Run cleanup every hour
-crons.hourly("cleanup-files", { minutes: 0 }, api.files.cleanupExpired, {
-  limit: 100,
-});
+**[Live Demo →](https://convex-files-control-example.pages.dev)**
 
-export default crons;
-```
+A full Convex + React + Convex Auth implementation lives in `example/`. It
+demonstrates:
+
+- presigned and HTTP uploads
+- authenticated downloads and shareable links
+- access key management
+- transfer between Convex and R2
+- scheduled cleanup

package/dist/client/http.d.ts

@@ -1,7 +1,7 @@
-export declare function corsHeaders(): Headers;
-export declare function corsResponse(): Response;
-export declare function jsonSuccess(data: unknown): Response;
-export declare function jsonError(message: string, status: number): Response;
+export declare function corsHeaders(origin?: string, allowHeaders?: string[]): Headers;
+export declare function corsResponse(origin?: string, allowHeaders?: string[]): Response;
+export declare function jsonSuccess(data: unknown, origin?: string, allowHeaders?: string[]): Response;
+export declare function jsonError(message: string, status: number, origin?: string, allowHeaders?: string[]): Response;
 export declare function parseJsonStringArray(value: string): string[] | null;
 export declare function parseOptionalTimestamp(value: FormDataEntryValue | null): number | null | undefined | "invalid";
 export declare function sanitizeFilename(value: string | null): string;

package/dist/client/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/client/http.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,IAAI,OAAO,CAMrC;AAED,wBAAgB,YAAY,IAAI,QAAQ,CAEvC;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,CAKnD;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAKnE;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAenE;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,kBAAkB,GAAG,IAAI,GAC/B,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,SAAS,CAiBvC;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAO7D;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EACF,SAAS,GACT,WAAW,GACX,cAAc,GACd,eAAe,GACf,mBAAmB,GACnB,kBAAkB,GAClB,MAAM,GACT,MAAM,CAcR"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/client/http.ts"],"names":[],"mappings":"AAyBA,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAU7E;AAED,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,QAAQ,CAK/E;AAED,wBAAgB,WAAW,CACzB,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,MAAM,EAAE,GACtB,QAAQ,CAKV;AAED,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,MAAM,EAAE,GACtB,QAAQ,CAKV;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAenE;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,kBAAkB,GAAG,IAAI,GAC/B,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,SAAS,CAiBvC;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAO7D;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EACF,SAAS,GACT,WAAW,GACX,cAAc,GACd,eAAe,GACf,mBAAmB,GACnB,kBAAkB,GAClB,MAAM,GACT,MAAM,CAcR"}