@cosmicdrift/kumiko-framework 0.1.0

package/src/files/__tests__/storage-tracking.integration.ts

@@ -0,0 +1,153 @@
+// tenant_storage_usage MSP — aggregates upload sizes per tenant.
+//
+// Proves:
+//   1. Two uploads from the same tenant end up on a single row with the
+//      sums and counts incremented atomically.
+//   2. Uploads from different tenants land on separate rows — no cross-
+//      tenant leakage through the UPSERT.
+//   3. The table column types survive round-trip (bigint → number via
+//      Drizzle's mode:"number", so arithmetic in assertions Just Works).
+
+import { eq, sql } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import type { SessionUser } from "../../engine";
+import { createTestUser, setupTestStack, type TestStack, TestUsers } from "../../stack";
+import {
+  createInMemoryFileProvider,
+  filesStorageTrackingFeature,
+  type InMemoryFileProvider,
+  tenantStorageUsageTable,
+} from "..";
+
+let stack: TestStack;
+let provider: InMemoryFileProvider;
+
+const admin = TestUsers.admin;
+// Second tenant — a different UUID in the valid v4 range. The MSP must
+// key on event.tenantId, so this row should never cross over with admin's.
+const otherAdmin = createTestUser({
+  tenantId: "00000000-0000-4000-8000-000000000042",
+  roles: ["Admin"],
+});
+
+// Two tiny payloads with distinct lengths so the sum assertion can tell
+// them apart without relying on the underlying bytes.
+const SMALL = new Uint8Array([0x89, 0x50, 0x4e, 0x47, ...Array(16).fill(0)]); // 20 bytes, PNG-ish
+const LARGE = new Uint8Array([0x89, 0x50, 0x4e, 0x47, ...Array(96).fill(0)]); // 100 bytes
+
+beforeAll(async () => {
+  provider = createInMemoryFileProvider();
+  stack = await setupTestStack({
+    features: [filesStorageTrackingFeature],
+    files: { storageProvider: provider },
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  provider.clear();
+  stack.events.reset();
+  // Reset events + storage-usage row + consumer cursors + file_refs so
+  // each test starts from zero. kumiko_event_consumers registration is
+  // re-asserted below; truncating it forces ensureRegistered to seed the
+  // cursor at event.id = 0.
+  await stack.db.execute(
+    sql`TRUNCATE kumiko_events, kumiko_event_consumers, file_refs, read_tenant_storage_usage RESTART IDENTITY CASCADE`,
+  );
+  await stack.eventDispatcher?.ensureRegistered();
+});
+
+async function upload(user: SessionUser, name: string, content: Uint8Array): Promise<void> {
+  const token = await stack.jwt.sign(user);
+  const formData = new FormData();
+  formData.append("file", new File([Buffer.from(content)], name, { type: "image/png" }));
+  const res = await stack.app.request("/api/files", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}` },
+    body: formData,
+  });
+  expect(res.status).toBe(201);
+}
+
+async function usageFor(tenantId: string): Promise<{ totalBytes: number; fileCount: number }> {
+  const [row] = await stack.db
+    .select({
+      totalBytes: tenantStorageUsageTable.totalBytes,
+      fileCount: tenantStorageUsageTable.fileCount,
+    })
+    .from(tenantStorageUsageTable)
+    .where(eq(tenantStorageUsageTable.tenantId, tenantId));
+  return row ?? { totalBytes: 0, fileCount: 0 };
+}
+
+describe("tenant-storage-usage MSP", () => {
+  test("single upload writes a row with totalBytes = size, fileCount = 1", async () => {
+    await upload(admin, "a.png", SMALL);
+    await stack.eventDispatcher?.runOnce();
+
+    const usage = await usageFor(admin.tenantId);
+    expect(usage).toEqual({ totalBytes: SMALL.length, fileCount: 1 });
+  });
+
+  test("two uploads same tenant — row increments atomically (UPSERT)", async () => {
+    await upload(admin, "a.png", SMALL);
+    await upload(admin, "b.png", LARGE);
+    await stack.eventDispatcher?.runOnce();
+
+    const usage = await usageFor(admin.tenantId);
+    expect(usage).toEqual({
+      totalBytes: SMALL.length + LARGE.length,
+      fileCount: 2,
+    });
+
+    // Exactly one row per tenant — the UPSERT must not insert a second
+    // row for the second upload.
+    const rows = await stack.db
+      .select()
+      .from(tenantStorageUsageTable)
+      .where(eq(tenantStorageUsageTable.tenantId, admin.tenantId));
+    expect(rows).toHaveLength(1);
+  });
+
+  test("two tenants — separate rows, no cross-leakage", async () => {
+    await upload(admin, "a.png", SMALL);
+    await upload(otherAdmin, "b.png", LARGE);
+    await stack.eventDispatcher?.runOnce();
+
+    const adminUsage = await usageFor(admin.tenantId);
+    const otherUsage = await usageFor(otherAdmin.tenantId);
+
+    expect(adminUsage).toEqual({ totalBytes: SMALL.length, fileCount: 1 });
+    expect(otherUsage).toEqual({ totalBytes: LARGE.length, fileCount: 1 });
+  });
+
+  test("lastUpdatedAt is set and advances on subsequent uploads", async () => {
+    await upload(admin, "a.png", SMALL);
+    await stack.eventDispatcher?.runOnce();
+
+    const [first] = await stack.db
+      .select({ at: tenantStorageUsageTable.lastUpdatedAt })
+      .from(tenantStorageUsageTable)
+      .where(eq(tenantStorageUsageTable.tenantId, admin.tenantId));
+    expect(first?.at).toBeInstanceOf(Temporal.Instant);
+
+    // Postgres NOW() resolution is microseconds; a second upload a beat
+    // later must produce a strictly later timestamp (or at least not an
+    // older one). We assert >= rather than > to keep the test tolerant
+    // of same-clock-tick runs.
+    await new Promise((r) => setTimeout(r, 10));
+    await upload(admin, "b.png", LARGE);
+    await stack.eventDispatcher?.runOnce();
+
+    const [second] = await stack.db
+      .select({ at: tenantStorageUsageTable.lastUpdatedAt })
+      .from(tenantStorageUsageTable)
+      .where(eq(tenantStorageUsageTable.tenantId, admin.tenantId));
+    expect(second?.at).toBeInstanceOf(Temporal.Instant);
+    if (!first?.at || !second?.at) throw new Error("missing rows");
+    expect(Temporal.Instant.compare(second.at, first.at)).toBeGreaterThanOrEqual(0);
+  });
+});

package/src/files/content-disposition.ts

@@ -0,0 +1,55 @@
+// RFC-6266 + RFC-5987 compliant Content-Disposition builder.
+//
+// fileName reaches this module from the client's multipart upload — it is
+// effectively attacker-controlled. A name like
+// `foo.pdf"; filename*=utf-8''evil.exe` would break the `filename="..."`
+// header quoting and inject a second parameter if we interpolated the raw
+// string. Two-step fix:
+//
+//   1. ASCII fallback for `filename="..."` — strip anything outside a safe
+//      token set, keeping the name readable for legacy clients that don't
+//      understand RFC 5987.
+//   2. Percent-encoded UTF-8 for `filename*=UTF-8''...` — the modern
+//      parameter that every current browser honours. RFC 5987 requires a
+//      handful of reserved chars that encodeURIComponent leaves alone
+//      ('()*) to also be escaped.
+//
+// Lives in its own module so the sanitisation is unit-testable in
+// isolation — the HTTP route exercises integration; edge cases around
+// encoding + fallback live in content-disposition.test.ts.
+
+const MAX_FALLBACK_LENGTH = 100;
+const SAFE_FALLBACK_CHARS = /[^A-Za-z0-9.\-_()]/g;
+const RFC_5987_EXTRA_ESCAPES = /['()*]/g;
+
+export function buildContentDispositionHeader(fileName: string): string {
+  const asciiFallback = toAsciiFallback(fileName);
+  const encoded = encodeRFC5987(fileName);
+  return `attachment; filename="${asciiFallback}"; filename*=UTF-8''${encoded}`;
+}
+
+// Collapse everything outside a safe token set (letters, digits, dot, dash,
+// underscore, parens) to underscore. Bounded length so a giant client-
+// supplied name can't balloon the header.
+//
+// Falls back to "download" in two cases: (1) the stripped result is empty,
+// and (2) nothing alphanumeric survived — a filename like "_______.png" is
+// legal but useless. "download" is readable; the original bytes still
+// reach the browser losslessly via filename* in the surrounding header.
+export function toAsciiFallback(name: string): string {
+  const stripped = name.replace(SAFE_FALLBACK_CHARS, "_").slice(0, MAX_FALLBACK_LENGTH);
+  if (stripped.length === 0) return "download";
+  if (!/[A-Za-z0-9]/.test(stripped)) return "download";
+  return stripped;
+}
+
+// encodeURIComponent handles the UTF-8 → percent-encoding step but leaves
+// a handful of characters unescaped that RFC 5987 calls out as reserved
+// ( ' ( ) * ). Escape those explicitly so the output is strictly
+// conformant and safe to drop into the `ext-value` production.
+export function encodeRFC5987(value: string): string {
+  return encodeURIComponent(value).replace(
+    RFC_5987_EXTRA_ESCAPES,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}

package/src/files/file-handle.ts

@@ -0,0 +1,63 @@
+// FileHandle — a thin pointer-object around a storage key.
+//
+// The contract the framework exposes to hook/handler code: a FileHandle lets
+// you read/write/delete the binary behind a storage key without ever passing
+// the binary through event payloads, job queues, or hook signatures. Events
+// carry the key, hooks reach for `ctx.files.ref(key)` when they actually need
+// the bytes, and big files stay in the storage layer where they belong.
+//
+// `derive(suffix)` is the primitive for thumbnail/variant keys: it inserts a
+// suffix before the file extension — `foo/bar.jpg` + `"medium"` →
+// `foo/bar.medium.jpg`. Stable, reversible, no extra lookup tables.
+
+import type { FileStorageProvider } from "./types";
+
+export type FileHandle = {
+  readonly key: string;
+  read(): Promise<Uint8Array>;
+  write(data: Uint8Array, mimeType?: string): Promise<void>;
+  delete(): Promise<void>;
+  exists(): Promise<boolean>;
+  // Produce a handle for a derived key (e.g. a thumbnail). Does not touch
+  // storage; only computes the key. Writing to the derived handle is the
+  // caller's job.
+  derive(suffix: string): FileHandle;
+};
+
+// The `ctx.files` service — a factory that materialises a FileHandle for a
+// storage key. One per app, wrapped around whichever FileStorageProvider the
+// app boot registered.
+export type FileContext = {
+  ref(key: string): FileHandle;
+};
+
+export function createFileHandle(key: string, provider: FileStorageProvider): FileHandle {
+  return {
+    key,
+    read: () => provider.read(key),
+    write: (data, mimeType) => provider.write(key, data, mimeType),
+    delete: () => provider.delete(key),
+    exists: () => provider.exists(key),
+    derive: (suffix) => createFileHandle(deriveKey(key, suffix), provider),
+  };
+}
+
+export function createFileContext(provider: FileStorageProvider): FileContext {
+  return {
+    ref: (key) => createFileHandle(key, provider),
+  };
+}
+
+// Inserts a suffix before the file extension. Keys without an extension get
+// the suffix appended with a dot: `foo/bar` + `"small"` → `foo/bar.small`.
+// Keys with a dot earlier in the path (e.g. `archive.v2/foo.jpg`) correctly
+// split on the LAST segment only.
+export function deriveKey(key: string, suffix: string): string {
+  const lastSlash = key.lastIndexOf("/");
+  const lastSegment = lastSlash === -1 ? key : key.slice(lastSlash + 1);
+  const lastDot = lastSegment.lastIndexOf(".");
+  if (lastDot === -1) return `${key}.${suffix}`;
+  const prefix = key.slice(0, key.length - lastSegment.length + lastDot);
+  const ext = lastSegment.slice(lastDot);
+  return `${prefix}.${suffix}${ext}`;
+}

package/src/files/file-ref-table.ts

@@ -0,0 +1,22 @@
+import { sql } from "drizzle-orm";
+import { instant, integer, table as pgTable, text, uuid } from "../db/dialect";
+
+// `id` is a UUID (not serial): it doubles as the aggregate-id for the
+// `fileRef` event stream — every upload appends exactly one
+// `files:event:uploaded` event keyed by this id. UUIDs also close the
+// enumeration-attack vector on /files/:id URLs.
+export const fileRefsTable = pgTable("file_refs", {
+  id: uuid("id").primaryKey(),
+  tenantId: uuid("tenant_id").notNull(),
+  storageKey: text("storage_key").notNull(),
+  fileName: text("file_name").notNull(),
+  mimeType: text("mime_type").notNull(),
+  size: integer("size").notNull(),
+  entityType: text("entity_type"),
+  // entityId references any entity (mostly UUID-keyed under ES). Text keeps
+  // the column backward-compat with older integer-keyed entities too.
+  entityId: text("entity_id"),
+  fieldName: text("field_name"),
+  insertedAt: instant("inserted_at").default(sql`now()`).notNull(),
+  insertedById: text("inserted_by_id"),
+});

package/src/files/file-routes.ts

@@ -0,0 +1,353 @@
+import { and, eq } from "drizzle-orm";
+import { Hono } from "hono";
+import { z } from "zod";
+import { getUser } from "../api/auth-middleware";
+import type { DbConnection } from "../db/connection";
+import type { EventDef } from "../engine/types";
+import { isFileField, type Registry, type SessionUser, type TenantId } from "../engine/types";
+import { append as appendEvent } from "../event-store/event-store";
+import { generateId } from "../utils";
+import { buildContentDispositionHeader } from "./content-disposition";
+import { fileRefsTable } from "./file-ref-table";
+import type { FileStorageProvider } from "./types";
+import { buildStorageKey, validateFile } from "./types";
+
+// Decision returned by a FileAccessGuard — distinct from boolean so callers
+// can't accidentally negate or default it.
+export type FileAccessDecision = "allow" | "deny";
+
+export type FileRef = {
+  id: string;
+  tenantId: TenantId;
+  storageKey: string;
+  fileName: string;
+  mimeType: string;
+  size: number;
+  entityType: string | null;
+  entityId: string | null;
+  fieldName: string | null;
+  insertedById: string | null;
+};
+
+// Event emitted after a successful upload. Downstream hooks / MSPs subscribe
+// on `fileUploadedEvent.name` via an r.multiStreamProjection apply map. The
+// payload carries metadata + the storage key — never the binary itself.
+// Consumers that need the bytes call `ctx.files.ref(payload.storageKey).read()`.
+//
+// Packaged as a framework-owned EventDef so consumers can narrow the raw
+// StoredEvent.payload via `typedPayload(event, fileUploadedEvent)` instead
+// of hand-casting. Schema version starts at 1; bump in lockstep with an
+// r.eventMigration when the shape breaks.
+export const fileUploadedPayloadSchema = z.object({
+  fileRefId: z.uuid(),
+  storageKey: z.string().min(1),
+  fileName: z.string().min(1),
+  mimeType: z.string().min(1),
+  size: z.number().int().nonnegative(),
+  entityType: z.string().nullable(),
+  entityId: z.string().nullable(),
+  fieldName: z.string().nullable(),
+  insertedById: z.string().min(1),
+});
+
+export type FileUploadedPayload = z.infer<typeof fileUploadedPayloadSchema>;
+
+export const fileUploadedEvent: EventDef<FileUploadedPayload> = {
+  name: "files:event:uploaded",
+  schema: fileUploadedPayloadSchema,
+  version: 1,
+};
+
+// Convenience re-export so apps that only reach for the event name (e.g. as
+// an apply-map key) don't have to dereference `.name` everywhere.
+export const FILE_UPLOADED_EVENT_TYPE = fileUploadedEvent.name;
+
+// Checks whether `user` may read/delete the given file. The default guard
+// (ownerOrPrivilegedGuard) approves uploaders + any role in privilegedRoles.
+// Apps can supply a custom guard to layer entity-level access (e.g. "drivers
+// can read files attached to orders assigned to them").
+export type FileAccessGuard = (args: {
+  readonly fileRef: FileRef;
+  readonly user: SessionUser;
+  readonly operation: "read" | "delete";
+}) => FileAccessDecision | Promise<FileAccessDecision>;
+
+export type FileRoutesOptions = {
+  readonly db: DbConnection;
+  readonly storageProvider: FileStorageProvider;
+  readonly registry?: Registry;
+  readonly maxUploadSize?: string; // global default, e.g. "10mb"
+  // Roles that bypass the default owner-check on entity-attached files.
+  // Defaults to ["Admin", "SystemAdmin"]; override to match your app's roles.
+  readonly privilegedRoles?: readonly string[];
+  // Replaces the default guard entirely. When set, privilegedRoles is ignored
+  // — the app takes full responsibility for the decision.
+  readonly accessGuard?: FileAccessGuard;
+};
+
+const DEFAULT_PRIVILEGED_ROLES = ["Admin", "SystemAdmin"] as const;
+
+// 15 minutes — long enough for a download to start, short enough that a
+// leaked URL (e.g. from a browser history screenshot) isn't a long-lived
+// credential. Matches the security-checklist in core-files.md.
+const SIGNED_URL_DEFAULT_EXPIRY_SECONDS = 15 * 60;
+
+// Default guard: on attached files, allow the uploader or a privileged role.
+// Unattached files are tenant-wide (the tenant boundary is already enforced
+// by the query).
+function createDefaultGuard(privilegedRoles: readonly string[]): FileAccessGuard {
+  return ({ fileRef, user }) => {
+    if (fileRef.entityType === null || fileRef.entityId === null) return "allow";
+    if (fileRef.insertedById === user.id) return "allow";
+    for (const role of privilegedRoles) {
+      if (user.roles.includes(role)) return "allow";
+    }
+    return "deny";
+  };
+}
+
+export function createFileRoutes(options: FileRoutesOptions): Hono {
+  const { db, storageProvider } = options;
+  const privilegedRoles = options.privilegedRoles ?? DEFAULT_PRIVILEGED_ROLES;
+  const guard: FileAccessGuard = options.accessGuard ?? createDefaultGuard(privilegedRoles);
+  const api = new Hono();
+
+  // POST /files — multipart upload.
+  api.post("/files", async (c) => {
+    const user = getUser(c);
+    const body = await c.req.parseBody();
+    const file = body["file"];
+
+    if (!file || !(file instanceof File)) {
+      return c.json({ error: "missing_file: expected multipart field 'file'" }, 400);
+    }
+
+    const entityType = typeof body["entityType"] === "string" ? body["entityType"] : undefined;
+    // Post-ES migration entities use UUID ids; we accept the raw string and
+    // store it in the text entityId column.
+    const entityId = typeof body["entityId"] === "string" ? body["entityId"] : undefined;
+    const fieldName = typeof body["fieldName"] === "string" ? body["fieldName"] : undefined;
+
+    // Validate against entity field definition if available.
+    let maxSize = options.maxUploadSize ?? "10mb";
+    let accept: readonly string[] | undefined;
+
+    if (options.registry && entityType && fieldName) {
+      const entity = options.registry.getEntity(entityType);
+      if (entity) {
+        const fieldDef = entity.fields[fieldName];
+        if (isFileField(fieldDef)) {
+          if (fieldDef.maxSize) maxSize = fieldDef.maxSize;
+          if (fieldDef.accept) accept = fieldDef.accept;
+        }
+      }
+    }
+
+    const validationError = validateFile(
+      { fileName: file.name, mimeType: file.type, size: file.size },
+      { maxSize, accept },
+    );
+    if (validationError) {
+      return c.json({ error: validationError }, 400);
+    }
+
+    const fileRefId = generateId();
+    const storageKey = buildStorageKey(
+      user.tenantId,
+      entityType ?? "unattached",
+      entityId ?? "",
+      fieldName ?? "file",
+      file.name,
+      generateId(),
+    );
+
+    // Write binary FIRST (outside the tx — network/disk I/O doesn't belong
+    // inside a PG connection's tx window). On DB-tx rollback below the bytes
+    // are orphaned in the provider; cleanup-jobs sweep those later. Losing a
+    // row on append-failure is acceptable; corrupting a committed row with a
+    // missing binary is not.
+    const data = new Uint8Array(await file.arrayBuffer());
+    await storageProvider.write(storageKey, data, file.type);
+
+    // Atomic: insert FileRef + append files:event:uploaded in one tx. Either
+    // both land or neither — no dangling FileRef without event, no event
+    // referencing a row that doesn't exist.
+    await db.transaction(async (tx) => {
+      await tx.insert(fileRefsTable).values({
+        id: fileRefId,
+        tenantId: user.tenantId,
+        storageKey,
+        fileName: file.name,
+        mimeType: file.type,
+        size: file.size,
+        entityType: entityType ?? null,
+        entityId: entityId ?? null,
+        fieldName: fieldName ?? null,
+        insertedById: user.id,
+      });
+
+      const payload: FileUploadedPayload = {
+        fileRefId,
+        storageKey,
+        fileName: file.name,
+        mimeType: file.type,
+        size: file.size,
+        entityType: entityType ?? null,
+        entityId: entityId ?? null,
+        fieldName: fieldName ?? null,
+        insertedById: user.id,
+      };
+      await appendEvent(tx, {
+        aggregateId: fileRefId,
+        aggregateType: "fileRef",
+        tenantId: user.tenantId,
+        expectedVersion: 0,
+        type: fileUploadedEvent.name,
+        // EventToAppend wants a Record — payload is typed through the
+        // EventDef so the cast collapses to a single boundary, not a
+        // double-`as unknown as` at the call site.
+        payload: payload as Record<string, unknown>, // @cast-boundary engine-payload
+        metadata: { userId: user.id },
+      });
+    });
+
+    return c.json(
+      {
+        id: fileRefId,
+        fileName: file.name,
+        mimeType: file.type,
+        size: file.size,
+        storageKey,
+      },
+      201,
+    );
+  });
+
+  // GET /files/:id — download.
+  //
+  // Authorization stack:
+  //   1. tenantId must match (hard isolation, never crossable).
+  //   2. The configured FileAccessGuard decides read access. Default:
+  //      unattached → allow; attached → uploader or privileged role.
+  //      Apps override via options.accessGuard to layer entity-level rules.
+  api.get("/files/:id", async (c) => {
+    const user = getUser(c);
+    const id = c.req.param("id");
+    const fileRef = await loadFileForTenant(id, user.tenantId);
+    if (!fileRef) return c.json({ error: "not_found" }, 404);
+
+    const decision = await guard({ fileRef, user, operation: "read" });
+    if (decision === "deny") {
+      // 404 rather than 403 so the existence of the file isn't confirmed to
+      // an unauthorised caller — matches the tenant-miss response.
+      return c.json({ error: "not_found" }, 404);
+    }
+
+    const data = await storageProvider.read(fileRef.storageKey);
+    return new Response(Buffer.from(data), {
+      headers: {
+        "Content-Type": fileRef.mimeType,
+        "Content-Disposition": buildContentDispositionHeader(fileRef.fileName),
+        "Content-Length": String(fileRef.size),
+      },
+    });
+  });
+
+  // DELETE /files/:id — same guard, "delete" operation. Apps can differentiate
+  // read vs delete in their custom guard (e.g. only uploaders delete).
+  api.delete("/files/:id", async (c) => {
+    const user = getUser(c);
+    const id = c.req.param("id");
+    const fileRef = await loadFileForTenant(id, user.tenantId);
+    if (!fileRef) return c.json({ error: "not_found" }, 404);
+
+    const decision = await guard({ fileRef, user, operation: "delete" });
+    if (decision === "deny") return c.json({ error: "not_found" }, 404);
+
+    // Tombstone-Reihenfolge: DB-Row löschen FIRST, Bytes danach. Wenn der
+    // Storage-Call hängt oder fehlschlägt, sieht der User trotzdem den
+    // konsistenten "weg"-Zustand (kein Read findet die Row mehr) und der
+    // Cleanup-Job sweept die orphan'd bytes wie beim fehlgeschlagenen
+    // Upload. Umgekehrt liesse ein storage-success + db-fail eine Row mit
+    // permanent-broken Reference zurück — aus Sicht der API "Datei
+    // existiert" aber jeder Read 404t aus dem Provider.
+    await db.delete(fileRefsTable).where(eq(fileRefsTable.id, id));
+    await storageProvider.delete(fileRef.storageKey);
+    return c.json({ ok: true });
+  });
+
+  // GET /files/:id/download-url — returns a short-lived provider URL so the
+  // client can download directly (offloads bandwidth from the API, enables
+  // browser caching). Same auth + tenant + guard as GET /files/:id; the
+  // signed URL is only handed out after access is approved.
+  //
+  // Shape: JSON { url, expiresAt } rather than a 302 redirect. Redirects
+  // break browser `fetch()` on cross-origin URLs (CORS preflight semantics)
+  // and hide the expiry from the caller — JSON lets SPAs cache the URL
+  // until `expiresAt` without re-hitting the API.
+  //
+  // 501 when the wired provider doesn't support signed URLs (filesystem
+  // dev providers). Clients should fall back to the streaming endpoint.
+  api.get("/files/:id/download-url", async (c) => {
+    if (!storageProvider.getSignedUrl) {
+      return c.json(
+        {
+          error:
+            "signed_urls_not_supported: this provider does not support signed URLs — use GET /files/:id to stream",
+        },
+        501,
+      );
+    }
+
+    const user = getUser(c);
+    const id = c.req.param("id");
+    const fileRef = await loadFileForTenant(id, user.tenantId);
+    if (!fileRef) return c.json({ error: "not_found" }, 404);
+
+    const decision = await guard({ fileRef, user, operation: "read" });
+    if (decision === "deny") return c.json({ error: "not_found" }, 404);
+
+    const expiresInSeconds = SIGNED_URL_DEFAULT_EXPIRY_SECONDS;
+    const url = await storageProvider.getSignedUrl(fileRef.storageKey, expiresInSeconds, {
+      // Hint the provider to set Content-Disposition so the browser prompts
+      // with the original filename instead of the UUID-based storage key.
+      // Sanitised via buildContentDispositionHeader — the same attacker-
+      // controlled fileName reaches the provider's presigned response.
+      contentDisposition: buildContentDispositionHeader(fileRef.fileName),
+    });
+    const expiresAt = new Date(Date.now() + expiresInSeconds * 1000).toISOString();
+    return c.json({ url, expiresAt });
+  });
+
+  // GET /files/:id/meta — metadata without the bytes. Guarded exactly like
+  // download (meta leaks fileName/mimeType/size).
+  api.get("/files/:id/meta", async (c) => {
+    const user = getUser(c);
+    const id = c.req.param("id");
+    const fileRef = await loadFileForTenant(id, user.tenantId);
+    if (!fileRef) return c.json({ error: "not_found" }, 404);
+
+    const decision = await guard({ fileRef, user, operation: "read" });
+    if (decision === "deny") return c.json({ error: "not_found" }, 404);
+
+    return c.json({
+      id: fileRef.id,
+      fileName: fileRef.fileName,
+      mimeType: fileRef.mimeType,
+      size: fileRef.size,
+      entityType: fileRef.entityType,
+      entityId: fileRef.entityId,
+      fieldName: fileRef.fieldName,
+    });
+  });
+
+  async function loadFileForTenant(id: string, tenantId: TenantId): Promise<FileRef | null> {
+    const [row] = await db
+      .select()
+      .from(fileRefsTable)
+      .where(and(eq(fileRefsTable.id, id), eq(fileRefsTable.tenantId, tenantId)));
+    return (row as FileRef | undefined) ?? null;
+  }
+
+  return api;
+}