@cedarjs/uploads 7.0.0-canary.3114

package/README.md

@@ -0,0 +1,24 @@
+# @cedarjs/uploads
+
+File uploads and storage for CedarJS apps.
+
+- **Named storage targets** backed by providers for S3 (`@cedarjs/uploads/s3`),
+  the local filesystem, and the database, all implementing one small
+  `StorageProvider` contract.
+- **Upload profiles** that the server owns: clients name a profile, the server
+  signs its constraints into a short-lived, user-bound upload token.
+- **A Fastify plugin** with token-gated routes for filesystem uploads,
+  signed-URL file serving, and S3 event webhooks.
+- **GraphQL directives** (`@requireUploadToken`, `@withSignedUrl`,
+  `@withDataUri`) and service helpers for issuing tokens, presigning direct
+  uploads, and confirming them.
+- **Lifecycle utilities** (`storeFile`, `deleteFile`, `cleanupStaleUploads`) for
+  server-generated files and explicit cleanup.
+- **Web hooks and components** at `@cedarjs/uploads/web`, built on Uppy.
+
+```bash
+yarn cedar setup uploads
+```
+
+See the [uploads documentation](https://cedarjs.com/docs/uploads) for the full
+guide.

package/dist/authenticator.d.ts

@@ -0,0 +1,38 @@
+import type { FastifyRequest } from 'fastify';
+import type { Decoder } from '@cedarjs/api';
+/** The identity an upload route resolves for a request. */
+export interface UploadRequestUser {
+    id: string;
+    organizationId?: string;
+}
+export type UploadAuthenticator = (req: FastifyRequest) => Promise<UploadRequestUser | null>;
+export interface CreateUploadAuthenticatorOptions {
+    /** The app's auth decoder, for example from `@cedarjs/auth-dbauth-api`. */
+    authDecoder: Decoder | Decoder[];
+    /**
+     * The app's `getCurrentUser`, as exported from `api/src/lib/auth`. It
+     * receives the decoded session exactly as the GraphQL server passes it.
+     */
+    getCurrentUser: (decoded: unknown, raw: {
+        type: string;
+        schema: string;
+        token: string;
+    }, req: {
+        event: Request;
+        request: Request;
+    }) => Promise<unknown>;
+    /**
+     * Picks the organization id off the current user, for multi-tenant apps.
+     * Defaults to a top-level `organizationId` property when present.
+     */
+    getOrganizationId?: (currentUser: unknown) => string | undefined;
+}
+/**
+ * Builds the `authenticate` callback for the upload plugin from the same
+ * pieces the GraphQL server uses: the request's auth header is decoded with
+ * the app's auth decoder and the result handed to the app's
+ * `getCurrentUser`. With it in place the upload routes reject a token whose
+ * `sub` belongs to someone other than the requester.
+ */
+export declare function createUploadAuthenticator({ authDecoder, getCurrentUser, getOrganizationId, }: CreateUploadAuthenticatorOptions): UploadAuthenticator;
+//# sourceMappingURL=authenticator.d.ts.map

package/dist/authenticator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authenticator.d.ts","sourceRoot":"","sources":["../src/authenticator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAG7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAE3C,2DAA2D;AAC3D,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,MAAM,mBAAmB,GAAG,CAChC,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAA;AAEtC,MAAM,WAAW,gCAAgC;IAC/C,2EAA2E;IAC3E,WAAW,EAAE,OAAO,GAAG,OAAO,EAAE,CAAA;IAChC;;;OAGG;IACH,cAAc,EAAE,CACd,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EACpD,GAAG,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,KACtC,OAAO,CAAC,OAAO,CAAC,CAAA;IACrB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAAC,WAAW,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAA;CACjE;AAkCD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,WAAW,EACX,cAAc,EACd,iBAAyC,GAC1C,EAAE,gCAAgC,GAAG,mBAAmB,CA+BxD"}

package/dist/authenticator.js

@@ -0,0 +1,51 @@
+import { getAuthenticationContext } from "@cedarjs/api";
+function toWebRequest(req) {
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (typeof value === "string") {
+      headers.set(name, value);
+    } else if (Array.isArray(value)) {
+      headers.set(name, value.join(", "));
+    }
+  }
+  const host = req.headers.host ?? "localhost";
+  return new Request(`${req.protocol}://${host}${req.url}`, {
+    method: "GET",
+    headers
+  });
+}
+function defaultOrganizationId(user) {
+  if (typeof user === "object" && user !== null && "organizationId" in user && typeof user.organizationId === "string") {
+    return user.organizationId;
+  }
+  return void 0;
+}
+function createUploadAuthenticator({
+  authDecoder,
+  getCurrentUser,
+  getOrganizationId = defaultOrganizationId
+}) {
+  return async (req) => {
+    const request = toWebRequest(req);
+    const authContext = await getAuthenticationContext({
+      authDecoder,
+      event: request
+    });
+    if (!authContext) {
+      return null;
+    }
+    const [decoded, raw] = authContext;
+    const user = await getCurrentUser(decoded, raw, { event: request, request });
+    if (typeof user !== "object" || user === null || !("id" in user) || typeof user.id !== "string" && typeof user.id !== "number") {
+      return null;
+    }
+    const organizationId = getOrganizationId(user);
+    return {
+      id: String(user.id),
+      ...organizationId ? { organizationId } : {}
+    };
+  };
+}
+export {
+  createUploadAuthenticator
+};

package/dist/cleanupStaleUploads.d.ts

@@ -0,0 +1,50 @@
+import type { StorageTargets, UploadDatabase, UploadRecord } from './types.js';
+export interface CleanupStaleUploadsOptions {
+    db: UploadDatabase;
+    targets: StorageTargets;
+    /**
+     * Rows still `pending` after this many milliseconds are claimed as
+     * `failed`. Defaults to one hour, well past the five-minute validity of a
+     * presigned upload URL.
+     */
+    olderThan?: number;
+    /**
+     * `failed` rows that changed within this many milliseconds are re-checked
+     * and their bytes deleted if they landed after the claim. Measured from
+     * the row's last update (the claim, or the last failed attempt), so a row
+     * claimed long after it was created still gets its retries. Defaults to
+     * one day.
+     */
+    retryWindow?: number;
+    /** Largest batch of rows to process per call. Defaults to 500. */
+    batchSize?: number;
+    /**
+     * Called for each row whose storage operation failed. Defaults to
+     * `console.error`. The sweep continues with the next row either way.
+     */
+    onError?: (error: unknown, upload: UploadRecord) => void;
+}
+export interface CleanupStaleUploadsResult {
+    /** Rows moved from `pending` to `failed` by this run. */
+    claimed: number;
+    /** Objects deleted from storage by this run. */
+    deleted: number;
+    /** Rows whose storage operation failed and will be retried next run. */
+    errors: number;
+}
+/**
+ * Sweeps stale uploads. Presigned uploads that were issued but never
+ * completed, and route uploads that crashed between row creation and write,
+ * leave `pending` rows behind. This claims them with a conditional
+ * `pending` to `failed` update, deletes any bytes that did land, and keeps
+ * the rows as `failed` tombstones so byte deletion can be retried on the
+ * next run. A row that completes mid-sweep is skipped because its claim
+ * matches zero rows, and a claimed row can no longer complete.
+ *
+ * Once a tombstone's bytes are confirmed gone its `storageKey` is cleared,
+ * which drops it from the next run's re-check. A row whose target is
+ * unknown or whose provider fails is reported through `onError` and left
+ * for the next run; it never aborts the sweep. Run it from a recurring job.
+ */
+export declare function cleanupStaleUploads({ db, targets, olderThan, retryWindow, batchSize, onError, }: CleanupStaleUploadsOptions): Promise<CleanupStaleUploadsResult>;
+//# sourceMappingURL=cleanupStaleUploads.d.ts.map

package/dist/cleanupStaleUploads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanupStaleUploads.d.ts","sourceRoot":"","sources":["../src/cleanupStaleUploads.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAK9E,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,cAAc,CAAA;IAClB,OAAO,EAAE,cAAc,CAAA;IACvB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,KAAK,IAAI,CAAA;CACzD;AAED,MAAM,WAAW,yBAAyB;IACxC,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAA;IACf,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAA;IACf,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,EACxC,EAAE,EACF,OAAO,EACP,SAAoB,EACpB,WAAqB,EACrB,SAAe,EACf,OAC0E,GAC3E,EAAE,0BAA0B,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAmFjE"}

package/dist/cleanupStaleUploads.js

@@ -0,0 +1,80 @@
+import { resolveTarget } from "./targets.js";
+const ONE_HOUR = 60 * 60 * 1e3;
+const ONE_DAY = 24 * ONE_HOUR;
+async function cleanupStaleUploads({
+  db,
+  targets,
+  olderThan = ONE_HOUR,
+  retryWindow = ONE_DAY,
+  batchSize = 500,
+  onError = (error, upload) => console.error(`[cedar uploads] cleanup failed for ${upload.id}:`, error)
+}) {
+  const now = Date.now();
+  let claimed = 0;
+  let deleted = 0;
+  let errors = 0;
+  const claimedIds = /* @__PURE__ */ new Set();
+  const reclaim = async (upload) => {
+    if (!upload.storageKey) {
+      return false;
+    }
+    try {
+      const provider = resolveTarget(targets, upload.target);
+      const existed = await provider.exists(upload.storageKey);
+      if (existed) {
+        await provider.delete(upload.storageKey);
+      }
+      await db.upload.updateMany({
+        where: { id: upload.id, status: "failed" },
+        data: { storageKey: null }
+      });
+      return existed;
+    } catch (e) {
+      errors += 1;
+      onError(e, upload);
+      return false;
+    }
+  };
+  const stale = await db.upload.findMany({
+    where: { status: "pending", createdAt: { lt: new Date(now - olderThan) } },
+    omit: { data: true },
+    orderBy: { createdAt: "asc" },
+    take: batchSize
+  });
+  for (const upload of stale) {
+    const { count } = await db.upload.updateMany({
+      where: { id: upload.id, status: "pending" },
+      data: { status: "failed" }
+    });
+    if (count !== 1) {
+      continue;
+    }
+    claimed += 1;
+    claimedIds.add(upload.id);
+    if (await reclaim(upload)) {
+      deleted += 1;
+    }
+  }
+  const tombstones = await db.upload.findMany({
+    where: {
+      status: "failed",
+      storageKey: { not: null },
+      updatedAt: { gte: new Date(now - retryWindow) }
+    },
+    omit: { data: true },
+    orderBy: { createdAt: "asc" },
+    take: batchSize
+  });
+  for (const upload of tombstones) {
+    if (claimedIds.has(upload.id)) {
+      continue;
+    }
+    if (await reclaim(upload)) {
+      deleted += 1;
+    }
+  }
+  return { claimed, deleted, errors };
+}
+export {
+  cleanupStaleUploads
+};

package/dist/constants.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Values shared by the api and web entry points. This module must stay free
+ * of Node-only imports because the web bundle includes it.
+ */
+/** Header the client sends an upload token in. */
+export declare const UPLOAD_TOKEN_HEADER = "x-upload-token";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,kDAAkD;AAClD,eAAO,MAAM,mBAAmB,mBAAmB,CAAA"}

package/dist/constants.js

@@ -0,0 +1,4 @@
+const UPLOAD_TOKEN_HEADER = "x-upload-token";
+export {
+  UPLOAD_TOKEN_HEADER
+};

package/dist/deleteFile.d.ts

@@ -0,0 +1,14 @@
+import type { StorageProvider, UploadDatabase, UploadRecord } from './types.js';
+export interface DeleteFileOptions {
+    db: UploadDatabase;
+    upload: Pick<UploadRecord, 'id' | 'storageKey'>;
+}
+/**
+ * Deletes a stored file: bytes first, then the `Upload` row. Bytes-first
+ * ordering means a crash between the two steps leaves a row whose object is
+ * gone, which the app can see and fix by calling again, whereas the reverse
+ * order would leave an unreachable object nothing references. A missing
+ * object or row is tolerated, so the call is idempotent.
+ */
+export declare function deleteFile(target: StorageProvider, { db, upload }: DeleteFileOptions): Promise<void>;
+//# sourceMappingURL=deleteFile.d.ts.map

package/dist/deleteFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deleteFile.d.ts","sourceRoot":"","sources":["../src/deleteFile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE/E,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,cAAc,CAAA;IAClB,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,YAAY,CAAC,CAAA;CAChD;AAQD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,eAAe,EACvB,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,iBAAiB,GAChC,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/deleteFile.js

@@ -0,0 +1,18 @@
+function isRecordNotFound(e) {
+  return typeof e === "object" && e !== null && "code" in e && e.code === "P2025";
+}
+async function deleteFile(target, { db, upload }) {
+  if (upload.storageKey) {
+    await target.delete(upload.storageKey);
+  }
+  try {
+    await db.upload.delete({ where: { id: upload.id } });
+  } catch (e) {
+    if (!isRecordNotFound(e)) {
+      throw e;
+    }
+  }
+}
+export {
+  deleteFile
+};

package/dist/directives.d.ts

@@ -0,0 +1,55 @@
+import type { TransformerDirective, ValidatorDirective } from '@cedarjs/graphql-server';
+import type { ContentDisposition, StorageTargets, UploadDatabase } from './types.js';
+import type { UploadTokenPayload } from './uploadToken.js';
+/** Context key `@requireUploadToken` stores the validated token under. */
+export declare const UPLOAD_TOKEN_CONTEXT_KEY = "uploadTokenPayload";
+/**
+ * Reads the validated upload token `@requireUploadToken` attached to the
+ * GraphQL context. Throws when the resolver runs without the directive.
+ */
+export declare function getUploadTokenPayload(context: Record<string, unknown>): UploadTokenPayload;
+/** The GraphQL context, as directives receive it. */
+export type DirectiveContext = Record<string, unknown>;
+export interface RequireUploadTokenDirectiveOptions {
+    /** Secret upload tokens were signed with. */
+    secret: string;
+    /**
+     * Resolves the organization the request is acting under, for multi-tenant
+     * apps. Defaults to `context.currentUser.organizationId`.
+     */
+    getOrganizationId?: (context: DirectiveContext) => string | null | undefined;
+}
+export declare const requireUploadTokenSchema: import("graphql").DocumentNode;
+/**
+ * Builds the `@requireUploadToken` validator directive. It verifies the
+ * token in the `x-upload-token` header, rejects a token issued to a
+ * different user or organization, and attaches the claims to the context
+ * for `getUploadTokenPayload()`.
+ */
+export declare function createRequireUploadTokenDirective({ secret, getOrganizationId, }: RequireUploadTokenDirectiveOptions): ValidatorDirective;
+export interface UploadUrlDirectiveOptions {
+    db: UploadDatabase;
+    targets: StorageTargets;
+}
+export interface WithSignedUrlDirectiveOptions extends UploadUrlDirectiveOptions {
+    /** Lifetime of generated URLs, in seconds. Provider default when unset. */
+    expiresIn?: number;
+    /** Defaults to `attachment`. */
+    disposition?: ContentDisposition;
+}
+export declare const withSignedUrlSchema: import("graphql").DocumentNode;
+/**
+ * Builds the `@withSignedUrl` transformer directive. It turns an Upload id
+ * stored in a field into a signed URL from the row's target, or a `data:`
+ * URI when the target is the DB provider. Lookups are batched per request
+ * and never fetch inline `data` for object-storage rows.
+ */
+export declare function createWithSignedUrlDirective({ db, targets, expiresIn, disposition, }: WithSignedUrlDirectiveOptions): TransformerDirective;
+export declare const withDataUriSchema: import("graphql").DocumentNode;
+/**
+ * Builds the `@withDataUri` transformer directive. It reads the file from
+ * whichever target holds it and returns a base64 `data:` URI. Use it for
+ * small files only; every resolved field embeds the whole file.
+ */
+export declare function createWithDataUriDirective({ db, targets, }: UploadUrlDirectiveOptions): TransformerDirective;
+//# sourceMappingURL=directives.d.ts.map

package/dist/directives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directives.d.ts","sourceRoot":"","sources":["../src/directives.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAEnB,MAAM,yBAAyB,CAAA;AAKhC,OAAO,KAAK,EACV,kBAAkB,EAClB,cAAc,EACd,cAAc,EAEf,MAAM,YAAY,CAAA;AAGnB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAE1D,0EAA0E;AAC1E,eAAO,MAAM,wBAAwB,uBAAuB,CAAA;AAE5D;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,kBAAkB,CAcpB;AAID,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AA8CtD,MAAM,WAAW,kCAAkC;IACjD,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAC7E;AAED,eAAO,MAAM,wBAAwB,gCAMnC,CAAA;AAEF;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,EAChD,MAAM,EACN,iBAAiB,GAClB,EAAE,kCAAkC,GAAG,kBAAkB,CA8CzD;AAED,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,cAAc,CAAA;IAClB,OAAO,EAAE,cAAc,CAAA;CACxB;AAED,MAAM,WAAW,6BAA8B,SAAQ,yBAAyB;IAC9E,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gCAAgC;IAChC,WAAW,CAAC,EAAE,kBAAkB,CAAA;CACjC;AAED,eAAO,MAAM,mBAAmB,gCAM9B,CAAA;AA6BF;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,EAC3C,EAAE,EACF,OAAO,EACP,SAAS,EACT,WAAW,GACZ,EAAE,6BAA6B,GAAG,oBAAoB,CA2BtD;AAED,eAAO,MAAM,iBAAiB,gCAM5B,CAAA;AAEF;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,EAAE,EACF,OAAO,GACR,EAAE,yBAAyB,GAAG,oBAAoB,CAsBlD"}

package/dist/directives.js

@@ -0,0 +1,174 @@
+import { parse } from "graphql";
+import { getEventHeader } from "@cedarjs/api";
+import {
+  AuthenticationError,
+  createTransformerDirective,
+  createValidatorDirective,
+  ForbiddenError
+} from "@cedarjs/graphql-server";
+import { UploadError } from "./errors.js";
+import { toDataUri } from "./serialize.js";
+import { resolveTarget } from "./targets.js";
+import { loadUpload } from "./uploadLoader.js";
+import { UPLOAD_TOKEN_HEADER, verifyUploadToken } from "./uploadToken.js";
+const UPLOAD_TOKEN_CONTEXT_KEY = "uploadTokenPayload";
+function getUploadTokenPayload(context) {
+  const payload = context[UPLOAD_TOKEN_CONTEXT_KEY];
+  if (!payload) {
+    throw new UploadError(
+      "INVALID_TOKEN",
+      "No validated upload token on the GraphQL context. Add the `@requireUploadToken` directive to this field."
+    );
+  }
+  return payload;
+}
+function isLambdaEvent(value) {
+  return typeof value === "object" && value !== null && "headers" in value && typeof value.headers === "object";
+}
+function requestSourceOf(context) {
+  if (context.request instanceof Request) {
+    return context.request;
+  }
+  if (isLambdaEvent(context.event)) {
+    return context.event;
+  }
+  return null;
+}
+function currentUserOf(context) {
+  const user = context.currentUser;
+  if (!user || typeof user !== "object" || !("id" in user)) {
+    return null;
+  }
+  const id = user.id;
+  if (typeof id !== "string" && typeof id !== "number") {
+    return null;
+  }
+  const organizationId = "organizationId" in user && typeof user.organizationId === "string" ? user.organizationId : null;
+  return { id, organizationId };
+}
+const requireUploadTokenSchema = parse(`
+  """
+  Use to require a valid upload token in the x-upload-token request header.
+  The token is bound to the user it was issued to.
+  """
+  directive @requireUploadToken on FIELD_DEFINITION
+`);
+function createRequireUploadTokenDirective({
+  secret,
+  getOrganizationId
+}) {
+  const validate = ({ context }) => {
+    const source = requestSourceOf(context);
+    const header = source ? getEventHeader(source, UPLOAD_TOKEN_HEADER) : null;
+    if (!header) {
+      throw new AuthenticationError("Missing upload token.");
+    }
+    let payload;
+    try {
+      payload = verifyUploadToken(header, { secret });
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      throw new AuthenticationError(message);
+    }
+    const user = currentUserOf(context);
+    if (!user) {
+      throw new AuthenticationError(
+        "You must be logged in to use an upload token."
+      );
+    }
+    if (String(user.id) !== payload.sub) {
+      throw new ForbiddenError("Upload token was issued to a different user.");
+    }
+    const organizationId = getOrganizationId ? getOrganizationId(context) : user.organizationId;
+    if (payload.organizationId && payload.organizationId !== organizationId) {
+      throw new ForbiddenError(
+        "Upload token was issued for a different organization."
+      );
+    }
+    context[UPLOAD_TOKEN_CONTEXT_KEY] = payload;
+  };
+  return createValidatorDirective(requireUploadTokenSchema, validate);
+}
+const withSignedUrlSchema = parse(`
+  """
+  Use on a field that holds an Upload id to resolve it to a time-limited URL
+  for the stored file.
+  """
+  directive @withSignedUrl on FIELD_DEFINITION
+`);
+async function loadCompletedUpload(context, db, resolvedValue) {
+  if (typeof resolvedValue !== "string" || resolvedValue.length === 0) {
+    return null;
+  }
+  const upload = await loadUpload(context, db, resolvedValue);
+  if (upload?.status !== "completed") {
+    return null;
+  }
+  return upload;
+}
+async function loadInlineData(db, upload) {
+  const row = await db.upload.findUnique({ where: { id: upload.id } });
+  return row?.data ?? null;
+}
+function createWithSignedUrlDirective({
+  db,
+  targets,
+  expiresIn,
+  disposition
+}) {
+  return createTransformerDirective(
+    withSignedUrlSchema,
+    async ({ context, resolvedValue }) => {
+      const upload = await loadCompletedUpload(context, db, resolvedValue);
+      if (!upload) {
+        return null;
+      }
+      const target = resolveTarget(targets, upload.target);
+      if (target.providerType === "db") {
+        const data = await loadInlineData(db, upload);
+        return data ? toDataUri(upload.mimeType, data) : null;
+      }
+      if (!upload.storageKey) {
+        return null;
+      }
+      return target.getSignedReadUrl(upload.storageKey, {
+        expiresIn,
+        disposition
+      });
+    }
+  );
+}
+const withDataUriSchema = parse(`
+  """
+  Use on a field that holds an Upload id to resolve it to a data: URI of the
+  file's bytes. Suitable for small files only.
+  """
+  directive @withDataUri on FIELD_DEFINITION
+`);
+function createWithDataUriDirective({
+  db,
+  targets
+}) {
+  return createTransformerDirective(
+    withDataUriSchema,
+    async ({ context, resolvedValue }) => {
+      const upload = await loadCompletedUpload(context, db, resolvedValue);
+      if (!upload) {
+        return null;
+      }
+      const target = resolveTarget(targets, upload.target);
+      const data = target.providerType === "db" ? await loadInlineData(db, upload) : upload.storageKey ? await target.read(upload.storageKey) : null;
+      return data ? toDataUri(upload.mimeType, data) : null;
+    }
+  );
+}
+export {
+  UPLOAD_TOKEN_CONTEXT_KEY,
+  createRequireUploadTokenDirective,
+  createWithDataUriDirective,
+  createWithSignedUrlDirective,
+  getUploadTokenPayload,
+  requireUploadTokenSchema,
+  withDataUriSchema,
+  withSignedUrlSchema
+};

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+export type UploadErrorCode = 'CONFIGURATION' | 'UNKNOWN_TARGET' | 'UNKNOWN_PROFILE' | 'UNAUTHENTICATED' | 'INVALID_TOKEN' | 'TOKEN_USER_MISMATCH' | 'TOKEN_ORGANIZATION_MISMATCH' | 'MIME_TYPE_NOT_ALLOWED' | 'FILE_TOO_LARGE' | 'TOO_MANY_FILES' | 'PRESIGN_NOT_SUPPORTED' | 'NOT_SUPPORTED' | 'NOT_FOUND' | 'FORBIDDEN' | 'NOT_PENDING' | 'NOT_IN_STORAGE' | 'SIZE_MISMATCH' | 'INVALID_KEY';
+/**
+ * Thrown by every part of the uploads package when a request cannot be
+ * honored. `code` is stable for programmatic handling and `statusCode` is the
+ * HTTP status the Fastify routes respond with.
+ */
+export declare class UploadError extends Error {
+    code: UploadErrorCode;
+    statusCode: number;
+    constructor(code: UploadErrorCode, message: string, cause?: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GACvB,eAAe,GACf,gBAAgB,GAChB,iBAAiB,GACjB,iBAAiB,GACjB,eAAe,GACf,qBAAqB,GACrB,6BAA6B,GAC7B,uBAAuB,GACvB,gBAAgB,GAChB,gBAAgB,GAChB,uBAAuB,GACvB,eAAe,GACf,WAAW,GACX,WAAW,GACX,aAAa,GACb,gBAAgB,GAChB,eAAe,GACf,aAAa,CAAA;AAuBjB;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,IAAI,EAAE,eAAe,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;gBAEN,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAMpE"}

package/dist/errors.js

@@ -0,0 +1,33 @@
+const STATUS_CODES = {
+  CONFIGURATION: 500,
+  UNKNOWN_TARGET: 500,
+  UNKNOWN_PROFILE: 400,
+  UNAUTHENTICATED: 401,
+  INVALID_TOKEN: 401,
+  TOKEN_USER_MISMATCH: 403,
+  TOKEN_ORGANIZATION_MISMATCH: 403,
+  MIME_TYPE_NOT_ALLOWED: 415,
+  FILE_TOO_LARGE: 413,
+  TOO_MANY_FILES: 400,
+  PRESIGN_NOT_SUPPORTED: 400,
+  NOT_SUPPORTED: 400,
+  NOT_FOUND: 404,
+  FORBIDDEN: 403,
+  NOT_PENDING: 409,
+  NOT_IN_STORAGE: 409,
+  SIZE_MISMATCH: 409,
+  INVALID_KEY: 400
+};
+class UploadError extends Error {
+  code;
+  statusCode;
+  constructor(code, message, cause) {
+    super(message, cause === void 0 ? void 0 : { cause });
+    this.name = "UploadError";
+    this.code = code;
+    this.statusCode = STATUS_CODES[code];
+  }
+}
+export {
+  UploadError
+};

package/dist/fastify/plugin.d.ts

@@ -0,0 +1,49 @@
+import type { FastifyInstance } from 'fastify';
+import type { UploadAuthenticator } from '../authenticator.js';
+import type { StorageTargets, UploadDatabase } from '../types.js';
+import type { FetchCertificate } from '../webhooks/sns.js';
+export interface UploadPluginOptions {
+    /** Secret upload tokens and serve URLs are signed with. */
+    tokenSecret: string;
+    /** The app's storage targets. */
+    targets: StorageTargets;
+    db: UploadDatabase;
+    /** Route prefix. Defaults to `/upload`. */
+    prefix?: string;
+    /**
+     * Hard outer ceiling on upload request size. Defaults to 500 MB. The
+     * effective bound per request comes from the token (`maxFiles` times
+     * `maxFileSize` plus a multipart envelope allowance), so this only needs
+     * to sit above the largest profile's aggregate.
+     */
+    bodyLimit?: number;
+    /**
+     * Resolves the requesting user. When configured, the upload routes reject
+     * unauthenticated requests and tokens issued to someone else. Build it
+     * with `createUploadAuthenticator()`. Without it the token itself is the
+     * only identity on the route, so configure it in any app with auth.
+     */
+    authenticate?: UploadAuthenticator;
+    /**
+     * Enables `POST {prefix}/webhook/s3` for S3 event notifications delivered
+     * through SNS. `topicArn` is the only topic accepted.
+     */
+    s3Webhook?: {
+        topicArn: string;
+        fetchCertificate?: FetchCertificate;
+        fetch?: typeof fetch;
+    };
+    /** `Cache-Control` for served files. Defaults to `private, max-age=3600`. */
+    serveCacheControl?: string;
+}
+/**
+ * Registers the upload routes on a Fastify server. Register it on the
+ * `server` returned by `createServer()` in `api/src/server.ts`:
+ *
+ * - `POST {prefix}/fs` accepts multipart uploads for object-storage targets
+ * - `GET {prefix}/serve?token=...` serves files behind signed URLs
+ * - `POST {prefix}/webhook/s3` receives S3 event notifications (opt-in)
+ * - `GET {prefix}/health` answers liveness checks
+ */
+export declare function cedarUploadsPlugin(fastify: FastifyInstance, options: UploadPluginOptions): Promise<void>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/fastify/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/fastify/plugin.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAgC,MAAM,SAAS,CAAA;AAE5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAgB9D,OAAO,KAAK,EAEV,cAAc,EACd,cAAc,EAEf,MAAM,aAAa,CAAA;AAIpB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AA2B1D,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAA;IACnB,iCAAiC;IACjC,OAAO,EAAE,cAAc,CAAA;IACvB,EAAE,EAAE,cAAc,CAAA;IAClB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,mBAAmB,CAAA;IAClC;;;OAGG;IACH,SAAS,CAAC,EAAE;QACV,QAAQ,EAAE,MAAM,CAAA;QAChB,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;QACnC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;KACrB,CAAA;IACD,6EAA6E;IAC7E,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAgCD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAwQf"}