@gilhrpenner/convex-files-control 0.1.1 → 0.2.0

package/src/client/index.ts

@@ -31,12 +31,11 @@ import {
   normalizePathPrefix,
   uploadFormFields,
 } from "../shared";
-import type { R2Config, StorageProvider } from "../shared/types";
+import type { R2Config, StorageProvider, UploadResult } from "../shared/types";
 import {
   corsResponse,
   jsonError,
   jsonSuccess,
-  parseJsonStringArray,
   parseOptionalTimestamp,
   sanitizeFilename,
   statusCodeForDownloadError,
@@ -101,13 +100,66 @@ const requireR2Config = (input?: R2ConfigInput, context?: string): R2Config => {
   );
 };
 
+const normalizeOptionalHeaderName = (value?: string) => {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+};
+
+const getOrigin = (request: Request) =>
+  request.headers.get("Origin") ?? undefined;
+
+const withCors = (
+  response: Response,
+  origin?: string,
+  allowHeaders?: string[],
+) => {
+  const headers = new Headers(response.headers);
+  const cors = corsHeaders(origin, allowHeaders);
+  for (const [key, value] of cors.entries()) {
+    headers.set(key, value);
+  }
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+};
+
+const resolveUploadProvider = (
+  value: FormDataEntryValue | null,
+  fallback: StorageProvider,
+): StorageProvider => {
+  const providerValue = typeof value === "string" ? value : "";
+  return isStorageProvider(providerValue) ? providerValue : fallback;
+};
+
+function bytesToBase64(bytes: Uint8Array): string {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(bytes).toString("base64");
+  }
+  if (typeof btoa === "function") {
+    if (typeof TextDecoder === "function") {
+      try {
+        return btoa(new TextDecoder("latin1").decode(bytes));
+      } catch {
+        // Fallback below for environments without latin1 support.
+      }
+    }
+    let binary = "";
+    const chunkSize = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunkSize) {
+      binary += String.fromCharCode(...bytes.subarray(i, i + chunkSize));
+    }
+    return btoa(binary);
+  }
+  throw new Error("Base64 encoding is not available in this environment.");
+}
+
 export interface RegisterRoutesOptions {
   /** Prefix for HTTP routes, defaults to "/files". */
   pathPrefix?: string;
-  /** Require accessKey query param for downloads. */
+  /** Require accessKey for downloads (via checkDownloadRequest hook). */
   requireAccessKey?: boolean;
-  /** Query parameter name for accessKey. */
-  accessKeyQueryParam?: string;
   /**
    * Query parameter name for password. Note: query params can leak into logs or
    * caches; prefer headers or POST flows when possible.
@@ -122,13 +174,45 @@ export interface RegisterRoutesOptions {
   /** R2 credentials for server-side upload/download/cleanup. */
   r2?: R2ConfigInput;
   /**
-   * Optional hook for rate limiting or request validation. Return a Response to
-   * short-circuit the request (e.g. 429).
+   * Required hook for upload authentication when enableUploadRoute is true.
+   * Return { accessKeys } to proceed with the upload, or a Response to reject.
+   *
+   * @example
+   * ```ts
+   * checkUploadRequest: async (ctx) => {
+   *   const userId = await getAuthUserId(ctx);
+   *   if (!userId) {
+   *     return new Response(JSON.stringify({ error: "Unauthorized" }), {
+   *       status: 401,
+   *       headers: { "Content-Type": "application/json" },
+   *     });
+   *   }
+   *   return { accessKeys: [userId] };
+   * }
+   * ```
+   */
+  checkUploadRequest?: (
+    ctx: RunHttpActionCtx,
+    args: UploadRequestArgs,
+  ) => UploadRequestResult | Promise<UploadRequestResult>;
+  /**
+   * Optional hook called after a successful upload + finalizeUpload.
+   * Return a Response to override the default JSON response.
+   */
+  onUploadComplete?: (
+    ctx: RunHttpActionCtx,
+    args: UploadCompleteArgs,
+  ) => UploadCompleteResult | Promise<UploadCompleteResult>;
+  /**
+   * Optional hook for rate limiting, request validation, or authentication.
+   * Return a Response to short-circuit the request (e.g. 401, 429).
+   * Return { accessKey: string } to set the accessKey for non-public links.
+   * Return void to proceed without setting an accessKey.
    */
   checkDownloadRequest?: (
-    ctx: RunMutationCtx,
+    ctx: RunHttpActionCtx,
     args: DownloadRequestArgs,
-  ) => void | Response | Promise<void | Response>;
+  ) => void | Response | { accessKey: string } | Promise<void | Response | { accessKey: string }>;
 }
 
 /**
@@ -165,65 +249,92 @@ export function registerRoutes(
   const {
     pathPrefix = DEFAULT_PATH_PREFIX,
     requireAccessKey = false,
-    accessKeyQueryParam = "accessKey",
     passwordQueryParam = "password",
     passwordHeader = "x-download-password",
     enableUploadRoute = false,
     enableDownloadRoute = true,
     defaultUploadProvider = "convex",
     r2,
+    checkUploadRequest,
+    onUploadComplete,
     checkDownloadRequest,
   } = options;
 
   const normalizedPrefix = normalizePathPrefix(pathPrefix);
+  const passwordHeaderName = normalizeOptionalHeaderName(passwordHeader);
+  const passwordQueryKey = normalizeOptionalHeaderName(passwordQueryParam);
+  const downloadCorsAllowHeaders = passwordHeaderName
+    ? [passwordHeaderName]
+    : undefined;
   const uploadPath = `${normalizedPrefix}/upload`;
   const downloadPath = `${normalizedPrefix}/download`;
 
   if (enableUploadRoute) {
+    if (!checkUploadRequest) {
+      throw new Error(
+        "checkUploadRequest is required when enableUploadRoute is true. " +
+          "This hook must authenticate the request and return { accessKeys }.",
+      );
+    }
+
     http.route({
       path: uploadPath,
       method: "OPTIONS",
-      handler: httpActionGeneric(async () => corsResponse()),
+      handler: httpActionGeneric(async (_ctx, request) => {
+        const origin = getOrigin(request);
+        return corsResponse(origin);
+      }),
     });
 
     http.route({
       path: uploadPath,
       method: "POST",
       handler: httpActionGeneric(async (ctx, request) => {
+        const origin = getOrigin(request);
         const contentType = request.headers.get("Content-Type") ?? "";
         if (!contentType.includes("multipart/form-data")) {
-          return jsonError("Content-Type must be multipart/form-data", 415);
+          return jsonError("Content-Type must be multipart/form-data", 415, origin);
         }
 
         const formData = await request.formData();
         const file = formData.get(uploadFormFields.file);
         if (!(file instanceof Blob)) {
-          return jsonError("Missing or invalid 'file' field", 400);
-        }
-
-        const accessKeysRaw = formData.get(uploadFormFields.accessKeys);
-        if (typeof accessKeysRaw !== "string") {
-          return jsonError("Missing 'accessKeys' field", 400);
-        }
-
-        const accessKeys = parseJsonStringArray(accessKeysRaw);
-        if (!accessKeys) {
-          return jsonError("'accessKeys' must be a JSON array of strings", 400);
+          return jsonError("Missing or invalid 'file' field", 400, origin);
         }
 
         const expiresAt = parseOptionalTimestamp(
           formData.get(uploadFormFields.expiresAt),
         );
         if (expiresAt === "invalid") {
-          return jsonError("'expiresAt' must be a number or null", 400);
+          return jsonError("'expiresAt' must be a number or null", 400, origin);
+        }
+
+        const provider = resolveUploadProvider(
+          formData.get(uploadFormFields.provider),
+          defaultUploadProvider,
+        );
+
+        // Call the auth hook to get access keys
+        const hookResult = await checkUploadRequest(ctx, {
+          file,
+          expiresAt: expiresAt ?? undefined,
+          provider,
+          request,
+        });
+
+        // If hook returns a Response, wrap it with CORS headers
+        if (hookResult instanceof Response) {
+          return withCors(hookResult, origin);
         }
 
-        const providerRaw = formData.get(uploadFormFields.provider);
-        const providerValue =
-          typeof providerRaw === "string" ? providerRaw : "";
-        const provider = isStorageProvider(providerValue)
-          ? providerValue
-          : defaultUploadProvider;
+        if (!hookResult || typeof hookResult !== "object") {
+          return jsonError("checkUploadRequest must return accessKeys", 500, origin);
+        }
+
+        const { accessKeys } = hookResult;
+        if (!accessKeys || accessKeys.length === 0) {
+          return jsonError("checkUploadRequest must return accessKeys", 500, origin);
+        }
 
         let r2Config: R2Config | undefined = undefined;
         if (provider === "r2") {
@@ -233,6 +344,7 @@ export function registerRoutes(
             return jsonError(
               error instanceof Error ? error.message : "R2 configuration missing.",
               500,
+              origin,
             );
           }
         }
@@ -250,7 +362,7 @@ export function registerRoutes(
         });
 
         if (!uploadResponse.ok) {
-          return jsonError("File upload failed", 502);
+          return jsonError("File upload failed", 502, origin);
         }
 
         let storageId = presetStorageId ?? null;
@@ -262,17 +374,46 @@ export function registerRoutes(
         }
 
         if (!storageId) {
-          return jsonError("Upload did not return storageId", 502);
+          return jsonError("Upload did not return storageId", 502, origin);
         }
 
+        // Compute file metadata from the blob for HTTP action uploads.
+        // This is necessary because R2 uploads don't have metadata in Convex's
+        // system database, and even for Convex uploads we already have the blob.
+        const fileBuffer = await file.arrayBuffer();
+        const fileBytes = new Uint8Array(fileBuffer);
+        const digest = await crypto.subtle.digest("SHA-256", fileBytes);
+        const sha256 = bytesToBase64(new Uint8Array(digest));
+        const metadata = {
+          size: fileBytes.byteLength,
+          sha256,
+          contentType: file.type || null,
+        };
+
         const result = await ctx.runMutation(component.upload.finalizeUpload, {
           uploadToken,
           storageId,
           accessKeys,
           expiresAt: expiresAt ?? undefined,
+          metadata,
         });
 
-        return jsonSuccess(result);
+        if (onUploadComplete) {
+          const hookResult = await onUploadComplete(ctx, {
+            file,
+            provider,
+            accessKeys,
+            expiresAt: expiresAt ?? null,
+            request,
+            result,
+          });
+
+          if (hookResult instanceof Response) {
+            return withCors(hookResult, origin);
+          }
+        }
+
+        return jsonSuccess(result, origin);
       }),
     });
   }
@@ -281,29 +422,36 @@ export function registerRoutes(
     http.route({
       path: downloadPath,
       method: "OPTIONS",
-      handler: httpActionGeneric(async () => corsResponse()),
+      handler: httpActionGeneric(async (_ctx, request) => {
+        const origin = getOrigin(request);
+        return corsResponse(origin, downloadCorsAllowHeaders);
+      }),
     });
 
     http.route({
       path: downloadPath,
       method: "GET",
       handler: httpActionGeneric(async (ctx, request) => {
+        const origin = getOrigin(request);
         const url = new URL(request.url);
         const downloadToken = url.searchParams.get("token");
         if (!downloadToken) {
-          return jsonError("Missing 'token' query parameter", 400);
+          return jsonError(
+            "Missing 'token' query parameter",
+            400,
+            origin,
+            downloadCorsAllowHeaders,
+          );
         }
 
-        const accessKey = url.searchParams.get(accessKeyQueryParam) ?? undefined;
-        if (requireAccessKey && !accessKey) {
-          return jsonError("Missing required accessKey", 401);
-        }
+        // For downloads, accessKey should come from checkDownloadRequest hook
+        let accessKey: string | undefined;
 
-        const passwordFromHeader = passwordHeader
-          ? request.headers.get(passwordHeader)
+        const passwordFromHeader = passwordHeaderName
+          ? request.headers.get(passwordHeaderName)
           : null;
-        const passwordFromQuery = passwordQueryParam
-          ? url.searchParams.get(passwordQueryParam)
+        const passwordFromQuery = passwordQueryKey
+          ? url.searchParams.get(passwordQueryKey)
           : null;
         const password = passwordFromHeader ?? passwordFromQuery ?? undefined;
 
@@ -315,10 +463,23 @@ export function registerRoutes(
             request,
           });
           if (result instanceof Response) {
-            return result;
+            return withCors(result, origin, downloadCorsAllowHeaders);
+          }
+          // If hook returns { accessKey }, use it
+          if (result && typeof result === "object" && "accessKey" in result) {
+            accessKey = result.accessKey;
           }
         }
 
+        if (requireAccessKey && !accessKey) {
+          return jsonError(
+            "Missing required accessKey. Provide it via checkDownloadRequest hook.",
+            401,
+            origin,
+            downloadCorsAllowHeaders,
+          );
+        }
+
         const result = await ctx.runMutation(
           component.download.consumeDownloadGrantForUrl,
           {
@@ -333,16 +494,18 @@ export function registerRoutes(
           return jsonError(
             "Download unavailable",
             statusCodeForDownloadError(result.status),
+            origin,
+            downloadCorsAllowHeaders,
           );
         }
 
         const fileResponse = await fetch(result.downloadUrl);
         if (!fileResponse.ok || !fileResponse.body) {
-          return jsonError("File not available", 404);
+          return jsonError("File not available", 404, origin, downloadCorsAllowHeaders);
         }
 
         const filename = sanitizeFilename(url.searchParams.get("filename"));
-        const headers = corsHeaders();
+        const headers = corsHeaders(origin, downloadCorsAllowHeaders);
         headers.set("Cache-Control", "no-store");
         headers.set("Content-Disposition", `attachment; filename="${filename}"`);
 
@@ -366,7 +529,6 @@ export interface BuildDownloadUrlOptions {
   baseUrl: string;
   downloadToken: string;
   pathPrefix?: string;
-  accessKey?: string;
   filename?: string;
 }
 
@@ -378,13 +540,13 @@ export interface BuildDownloadUrlOptions {
  *
  * Note: Avoid placing passwords in query params; they can leak into logs or
  * caches. Prefer headers or POST flows when possible.
+ * Access keys are not included in the URL; enforce them via checkDownloadRequest.
  *
  * @example
  * ```ts
  * const url = buildDownloadUrl({
  *   baseUrl: "https://your-app.convex.site",
  *   downloadToken,
- *   accessKey: "user_123",
  *   filename: "report.pdf",
  * });
  * ```
@@ -393,7 +555,6 @@ export function buildDownloadUrl({
   baseUrl,
   downloadToken,
   pathPrefix = DEFAULT_PATH_PREFIX,
-  accessKey,
   filename,
 }: BuildDownloadUrlOptions): string {
   const normalizedBase = normalizeBaseUrl(baseUrl);
@@ -403,7 +564,6 @@ export function buildDownloadUrl({
     "download",
   );
   const params = new URLSearchParams({ token: downloadToken });
-  if (accessKey) params.set("accessKey", accessKey);
   if (filename) params.set("filename", filename);
   return `${endpoint}?${params.toString()}`;
 }
@@ -456,6 +616,15 @@ type RunActionCtx = {
   runAction: GenericActionCtx<GenericDataModel>["runAction"];
 };
 
+/**
+ * Context type for HTTP action hooks. Includes auth for authentication
+ * and runMutation for calling component mutations.
+ */
+export type RunHttpActionCtx = {
+  auth: GenericActionCtx<GenericDataModel>["auth"];
+  runMutation: GenericActionCtx<GenericDataModel>["runMutation"];
+};
+
 type FinalizeUploadArgs = {
   uploadToken: Id<"pendingUploads">;
   storageId: string;
@@ -494,7 +663,29 @@ type DownloadConsumeArgs = {
   r2Config?: R2Config;
 };
 
-type DownloadRequestArgs = {
+export type UploadRequestArgs = {
+  file: Blob;
+  expiresAt?: number;
+  provider: StorageProvider;
+  request: Request;
+};
+
+export type UploadRequestResult =
+  | { accessKeys: string[] }
+  | Response;
+
+export type UploadCompleteArgs = {
+  file: Blob;
+  provider: StorageProvider;
+  accessKeys: string[];
+  expiresAt: number | null;
+  request: Request;
+  result: UploadResult;
+};
+
+export type UploadCompleteResult = void | Response;
+
+export type DownloadRequestArgs = {
   downloadToken: string;
   accessKey?: string;
   password?: string;

package/src/component/_generated/component.ts

@@ -131,12 +131,14 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           expiresAt?: null | number;
           maxUses?: null | number;
           password?: string;
+          shareableLink?: boolean;
           storageId: string;
         },
         {
           downloadToken: string;
           expiresAt: null | number;
           maxUses: null | number;
+          shareableLink: boolean;
           storageId: string;
         },
         Name

package/src/component/download.ts

@@ -47,12 +47,14 @@ export const createDownloadGrant = mutation({
     maxUses: v.optional(v.union(v.null(), v.number())),
     expiresAt: v.optional(v.union(v.null(), v.number())),
     password: v.optional(v.string()),
+    shareableLink: v.optional(v.boolean()),
   },
   returns: v.object({
     downloadToken: v.id("downloadGrants"),
     storageId: v.string(),
     expiresAt: v.union(v.null(), v.number()),
     maxUses: v.union(v.null(), v.number()),
+    shareableLink: v.boolean(),
   }),
   handler: async (ctx, args) => {
     const now = Date.now();
@@ -92,11 +94,13 @@ export const createDownloadGrant = mutation({
           passwordAlgorithm: passwordRecord.algorithm,
         }
       : {};
+    const shareableLink = args.shareableLink ?? false;
     const downloadToken = await ctx.db.insert("downloadGrants", {
       storageId: args.storageId,
       expiresAt: expiresAt ?? undefined,
       maxUses: maxUses ?? null,
       useCount: 0,
+      shareableLink,
       ...passwordFields,
     });
 
@@ -105,6 +109,7 @@ export const createDownloadGrant = mutation({
       storageId: args.storageId,
       expiresAt,
       maxUses: maxUses ?? null,
+      shareableLink,
     };
   },
 });
@@ -212,32 +217,48 @@ async function consumeDownloadGrantCore(
   const filePromise = findFileByStorageId(ctx, grant.storageId);
   const accessKey = normalizeAccessKey(args.accessKey);
 
-  if (!accessKey) {
+  // Shareable links bypass access key validation
+  if (grant.shareableLink) {
     const file = await filePromise;
     if (!file) {
       await ctx.db.delete(grant._id);
       return { status: "file_missing" };
     }
-    return { status: "access_denied" };
-  }
+  } else {
+    // Regular grants require a valid access key
+    if (!accessKey) {
+      const file = await filePromise;
+      if (!file) {
+        await ctx.db.delete(grant._id);
+        return { status: "file_missing" };
+      }
+      return { status: "access_denied" };
+    }
+
+    const [file, hasAccess] = await Promise.all([
+      filePromise,
+      hasAccessKey(ctx, {
+        accessKey,
+        storageId: grant.storageId,
+      }),
+    ]);
+
+    if (!file) {
+      await ctx.db.delete(grant._id);
+      return { status: "file_missing" };
+    }
 
-  const [file, hasAccess] = await Promise.all([
-    filePromise,
-    hasAccessKey(ctx, {
-      accessKey,
-      storageId: grant.storageId,
-    }),
-  ]);
+    if (!hasAccess) {
+      return { status: "access_denied" };
+    }
+  }
 
+  const file = await filePromise;
   if (!file) {
     await ctx.db.delete(grant._id);
     return { status: "file_missing" };
   }
 
-  if (!hasAccess) {
-    return { status: "access_denied" };
-  }
-
   if (grant.passwordHash) {
     const password = args.password;
     if (!password || password.trim() === "") {

package/src/component/schema.ts

@@ -25,6 +25,7 @@ export default defineSchema({
     expiresAt: v.optional(v.number()),
     maxUses: v.union(v.null(), v.number()),
     useCount: v.number(),
+    shareableLink: v.optional(v.boolean()),
     passwordHash: v.optional(v.string()),
     passwordSalt: v.optional(v.string()),
     passwordIterations: v.optional(v.number()),

package/src/react/index.ts

@@ -17,11 +17,11 @@ export type HttpUploadOptions = {
   uploadUrl?: string;
   baseUrl?: string;
   pathPrefix?: string;
+  authToken?: string;
 };
 
 export type UploadFileArgs = {
   file: File;
-  accessKeys: string[];
   expiresAt?: number | null;
   method?: UploadMethod;
   http?: HttpUploadOptions;
@@ -69,7 +69,7 @@ function resolveUploadUrl(http?: HttpUploadOptions) {
  * import { useUploadFile } from "@gilhrpenner/convex-files-control/react";
  *
  * const { uploadFile } = useUploadFile(api.filesControl, { method: "presigned" });
- * await uploadFile({ file, accessKeys: ["user_123"] });
+ * await uploadFile({ file });
  * ```
  */
 export function useUploadFile<Api extends UploadApi>(
@@ -81,7 +81,7 @@ export function useUploadFile<Api extends UploadApi>(
 
   const uploadViaPresignedUrl = useCallback(
     async (args: UploadFileArgs): Promise<UploadResult> => {
-      const { file, accessKeys, expiresAt } = args;
+      const { file, expiresAt } = args;
       const provider = args.provider ?? options.provider ?? "convex";
       const { uploadUrl, uploadToken, storageId: presetStorageId } =
         await generateUploadUrl({ provider });
@@ -112,7 +112,7 @@ export function useUploadFile<Api extends UploadApi>(
       return await finalizeUpload({
         uploadToken,
         storageId,
-        accessKeys,
+        fileName: file.name,
         expiresAt,
       });
     },
@@ -121,9 +121,10 @@ export function useUploadFile<Api extends UploadApi>(
 
   const uploadViaHttpAction = useCallback(
     async (args: UploadFileArgs): Promise<UploadResult> => {
-      const { file, accessKeys, expiresAt } = args;
+      const { file, expiresAt } = args;
       const provider = args.provider ?? options.provider ?? "convex";
-      const uploadUrl = resolveUploadUrl(args.http ?? options.http);
+      const httpConfig = args.http ?? options.http;
+      const uploadUrl = resolveUploadUrl(httpConfig);
       if (!uploadUrl) {
         throw new Error(
           "Missing HTTP upload URL. Provide http.uploadUrl or http.baseUrl.",
@@ -132,10 +133,6 @@ export function useUploadFile<Api extends UploadApi>(
 
       const formData = new FormData();
       formData.append(uploadFormFields.file, file);
-      formData.append(
-        uploadFormFields.accessKeys,
-        JSON.stringify(accessKeys),
-      );
       formData.append(uploadFormFields.provider, provider);
       if (expiresAt !== undefined) {
         formData.append(
@@ -147,6 +144,10 @@ export function useUploadFile<Api extends UploadApi>(
       const uploadResponse = await fetch(uploadUrl, {
         method: "POST",
         body: formData,
+        credentials: "include",
+        headers: httpConfig?.authToken
+          ? { Authorization: `Bearer ${httpConfig.authToken}` }
+          : undefined,
       });
 
       let payload: unknown = null;