@antasphere/chassis-server 1.0.0

package/src/api/export.ts

@@ -0,0 +1,482 @@
+import type { OpenAPIHono } from '@hono/zod-openapi';
+import { Readable } from 'node:stream';
+import { finished } from 'node:stream/promises';
+import { and, asc, eq, gt, isNull, sql } from 'drizzle-orm';
+import { ZipFile } from 'yazl';
+import {
+  apiKeys,
+  auditLog,
+  files,
+  instanceSettings,
+  invitations,
+  projectMembers,
+  projects,
+  projectTeams,
+  user as userTable,
+  workspaceMembers,
+  workspaces,
+  workspaceTeamMembers,
+  workspaceTeams,
+  type Db
+} from '@antasphere/chassis-db';
+import type { Env } from '../env.js';
+import type { ScopeRoutes } from './scope-routes.js';
+import type { Logger } from '../logger.js';
+import type { AuditService } from '../audit/service.js';
+import { blobKey, type StorageDriver } from '../storage/driver.js';
+import { requireAuth, requireNonGuest, requireRole } from '../middleware/auth-context.js';
+import { rateLimit, type RateLimiters } from '../middleware/rate-limit.js';
+import type { ClientIpFn } from '../middleware/rate-limit.js';
+
+/**
+ * GET /workspace/export — the GDPR/portability bundle: every workspace table
+ * as JSON, the audit log as NDJSON, and every live blob, streamed as one zip
+ * (yazl; modeled on the files-content streaming precedent in files.ts).
+ * Secrets never leave: invitations drop tokenHash, api-keys drop secretHash.
+ */
+
+const AUDIT_BATCH = 500;
+
+export interface ExportRouteDeps {
+  db: Db;
+  env: Pick<Env, 'EDITION' | 'APP_VERSION'>;
+  storage: StorageDriver;
+  audit: AuditService;
+  limiters: RateLimiters;
+  clientIp: ClientIpFn;
+  logger: Logger;
+  /** The export route the tool instantiated: its OpenAPI summary names the tool's export scope. */
+  workspaceExportRoute: ScopeRoutes['workspaceExportRoute'];
+  /** The tool's `api.exportEntries` slot, already bound to its domain. Absent = the chassis sections only. */
+  exportEntries?: ExportEntriesFn;
+}
+
+/** One entry a tool adds to the bundle: written as `<name>.json`, its rows as a JSON array. */
+export interface ExportEntry {
+  name: string;
+  rows: unknown[];
+}
+
+/**
+ * What the `api.exportEntries` slot returns: the tool's entries for ONE
+ * workspace. It reads with the handle the route itself reads with (`db`, no
+ * transaction), and it filters on `workspaceId` itself.
+ */
+export type ExportEntriesFn = (db: Db, workspaceId: string) => Promise<ExportEntry[]>;
+
+/**
+ * The entry names the chassis writes itself, without their extension. A tool
+ * entry that lands on one of them is refused: never a silent overwrite, never
+ * two zip entries of one name. (`files/…` needs no line here: a sanitized name
+ * holds no `/`.) `audit-log` is reserved although its file is `.ndjson`, so
+ * that the bundle never holds two audit logs.
+ */
+export const RESERVED_EXPORT_ENTRY_NAMES = [
+  'manifest',
+  'workspace',
+  'members',
+  'invitations',
+  'api-keys',
+  'projects',
+  'project_members',
+  'teams',
+  'team_members',
+  'project_teams',
+  'audit-log',
+  'files',
+  'skipped-blobs'
+] as const;
+
+/** A tool entry, ready to write: its zip entry name and its bytes. */
+export interface ResolvedExportEntry {
+  entryName: string;
+  buffer: Buffer;
+}
+
+/**
+ * Tool entries → zip entries, BEFORE the stream starts: every name goes
+ * through `sanitizeEntryName`, every `rows` through `jsonBuffer`, and a name
+ * that collides (compared without case, since the bundle is extracted on
+ * case-insensitive disks too) with a chassis entry or with another tool entry
+ * throws. Order is the tool's.
+ */
+export function resolveExportEntries(entries: ExportEntry[]): ResolvedExportEntry[] {
+  if (!Array.isArray(entries)) throw new Error('export entries: the tool must return an array of entries');
+  const taken = new Set<string>(RESERVED_EXPORT_ENTRY_NAMES);
+  return entries.map((entry) => {
+    if (typeof entry?.name !== 'string' || !Array.isArray(entry.rows)) {
+      throw new Error('export entries: every entry is { name: string, rows: unknown[] }');
+    }
+    const name = sanitizeEntryName(entry.name);
+    const key = name.toLowerCase();
+    if (taken.has(key)) {
+      throw new Error(`export entries: the name "${name}" is already an entry of the bundle`);
+    }
+    taken.add(key);
+    return { entryName: `${name}.json`, buffer: jsonBuffer(entry.rows) };
+  });
+}
+
+/**
+ * Zip-slip guard: entry names embed the user-supplied originalName, so strip
+ * path separators (`/`, `\`) and control chars, and cap the length — an
+ * uploaded name like `../../etc/cron.d/x` must never place an entry outside
+ * the extraction directory.
+ */
+export function sanitizeEntryName(name: string): string {
+  // eslint-disable-next-line no-control-regex
+  const cleaned = name.replace(/[/\\\u0000-\u001f\u007f]/g, '_');
+  return (cleaned || 'file').slice(0, 150);
+}
+
+function jsonBuffer(value: unknown): Buffer {
+  return Buffer.from(JSON.stringify(value, null, 2) + '\n', 'utf8');
+}
+
+/** Keyset walk of the audit log, one NDJSON line per row (never buffers the table). */
+async function* auditNdjson(db: Db, workspaceId: string): AsyncGenerator<string> {
+  let lastId = 0;
+  for (;;) {
+    const rows = await db
+      .select()
+      .from(auditLog)
+      .where(and(eq(auditLog.workspaceId, workspaceId), gt(auditLog.id, lastId)))
+      .orderBy(asc(auditLog.id))
+      .limit(AUDIT_BATCH);
+    if (rows.length === 0) return;
+    for (const row of rows) {
+      yield JSON.stringify({ ...row, createdAt: row.createdAt.toISOString() }) + '\n';
+      lastId = row.id;
+    }
+    if (rows.length < AUDIT_BATCH) return;
+  }
+}
+
+export function registerExportRoutes(api: OpenAPIHono, deps: ExportRouteDeps): void {
+  const { db, env, storage, audit, limiters, clientIp, logger } = deps;
+
+  // Gates, in order: rate limit (IP AND user — exports are expensive) →
+  // authenticated → admin+. Machine principals additionally passed the
+  // fail-closed export-scope gate in authContext before landing here.
+  api.use(
+    '/workspace/export',
+    rateLimit(limiters.workspaceExport, clientIp, async (c) => {
+      const principal = c.get('principal');
+      return principal ? [`u:${principal.userId}`] : [];
+    })
+  );
+  api.use('/workspace/export', requireAuth());
+  // Guest capability limit (D2): the whole-workspace export is the named
+  // workspace-scope surface guests must never reach. Defense in depth in
+  // front of the admin gate — a guest is minted role 'member' and the role
+  // is locked (api/members.ts), but export is exactly the surface where a
+  // second, origin-keyed wall is cheap and the failure catastrophic.
+  api.use('/workspace/export', requireNonGuest());
+  api.use('/workspace/export', requireRole('admin'));
+
+  api.openapi(deps.workspaceExportRoute, async (c) => {
+    const principal = c.get('principal')!;
+    const workspaceId = principal.workspaceId;
+
+    const [instance] = await db.select().from(instanceSettings).limit(1);
+    const [{ liveFiles }] = (await db
+      .select({ liveFiles: sql<number>`count(*)::int` })
+      .from(files)
+      .where(and(eq(files.workspaceId, workspaceId), isNull(files.deletedAt)))) as [{ liveFiles: number }];
+
+    // The tool's entries (the `api.exportEntries` slot), computed and
+    // serialized BEFORE the audit row and before the first byte: a
+    // contribution that throws, or whose name collides, answers the standard
+    // 500 with no audit row (the middleware writes none on a 4xx/5xx, and the
+    // session row below is not reached) and never a truncated zip. They are
+    // held in memory until their place in the pump: bounded tables only, the
+    // same stance as the chassis sections of step 2. No slot: nothing runs.
+    const toolEntries = deps.exportEntries
+      ? resolveExportEntries(await deps.exportEntries(db, workspaceId))
+      : [];
+
+    // Exactly one audit row either way: machine reads are audited by the
+    // middleware (it picks this up from c.set), session GETs are not
+    // (audit/service.ts) — so sessions write directly here.
+    const auditInfo = {
+      action: 'workspace.export',
+      resourceType: 'workspace',
+      resourceId: workspaceId,
+      metadata: { files: liveFiles }
+    };
+    c.set('audit', auditInfo);
+    if (principal.via === 'session') {
+      await audit.write({
+        workspaceId,
+        principal,
+        ...auditInfo,
+        requestId: c.get('requestId'),
+        ip: clientIp(c)
+      });
+    }
+
+    const zip = new ZipFile();
+    // @types/yazl types outputStream as the legacy NodeJS.ReadableStream; at
+    // runtime it is a real Readable (a PassThrough), which destroy/toWeb need.
+    const output = zip.outputStream as Readable;
+
+    // A client abort must tear down the source stream and the zip output or
+    // every cancelled download leaks a descriptor/S3 socket (files.ts rule).
+    let currentBlobStream: Readable | null = null;
+    c.req.raw.signal.addEventListener('abort', () => {
+      currentBlobStream?.destroy();
+      output.destroy(new Error('client aborted the export download'));
+    });
+
+    // Sequential pump, started before returning: entries are added in a
+    // fixed order while the output already streams. An error mid-pump
+    // destroys the output stream → the client sees a truncated (invalid)
+    // zip rather than a silently incomplete "valid" one — accepted: HTTP has
+    // no way to fail a 200 that already started streaming.
+    void (async () => {
+      // 1. Manifest first (no skip list here — it is not known yet; the
+      //    skips land in skipped-blobs.json, written last).
+      zip.addBuffer(
+        jsonBuffer({
+          formatVersion: 1,
+          exportedAt: new Date().toISOString(),
+          instance: {
+            instanceId: instance?.instanceId ?? null,
+            name: instance?.name ?? null,
+            edition: env.EDITION,
+            version: env.APP_VERSION
+          },
+          workspaceId
+        }),
+        'manifest.json'
+      );
+
+      // 2. The small bounded tables. Secrets are excluded by SELECTION, not
+      //    by post-filtering: invitations.tokenHash and apiKeys.secretHash
+      //    are simply never queried.
+      const [workspace] = await db
+        .select({ id: workspaces.id, name: workspaces.name, createdAt: workspaces.createdAt })
+        .from(workspaces)
+        .where(eq(workspaces.id, workspaceId))
+        .limit(1);
+      zip.addBuffer(jsonBuffer(workspace ?? null), 'workspace.json');
+
+      const memberRows = await db
+        .select({
+          id: workspaceMembers.id,
+          userId: workspaceMembers.userId,
+          email: userTable.email,
+          name: userTable.name,
+          role: workspaceMembers.role,
+          isActive: workspaceMembers.isActive,
+          createdAt: workspaceMembers.createdAt,
+          lastSeenAt: workspaceMembers.lastSeenAt
+        })
+        .from(workspaceMembers)
+        .innerJoin(userTable, eq(workspaceMembers.userId, userTable.id))
+        .where(eq(workspaceMembers.workspaceId, workspaceId))
+        .orderBy(asc(workspaceMembers.createdAt), asc(workspaceMembers.id));
+      zip.addBuffer(jsonBuffer(memberRows), 'members.json');
+
+      const invitationRows = await db
+        .select({
+          id: invitations.id,
+          email: invitations.email,
+          role: invitations.role,
+          invitedBy: invitations.invitedBy,
+          expiresAt: invitations.expiresAt,
+          acceptedAt: invitations.acceptedAt,
+          revokedAt: invitations.revokedAt,
+          createdAt: invitations.createdAt
+        })
+        .from(invitations)
+        .where(eq(invitations.workspaceId, workspaceId))
+        .orderBy(asc(invitations.createdAt), asc(invitations.id));
+      zip.addBuffer(jsonBuffer(invitationRows), 'invitations.json');
+
+      // PINNED keys only (workspace_id = this workspace): keys are USER
+      // credentials under the user-scoped model — an unpinned key belongs
+      // to its holder, not to any one workspace's export.
+      const apiKeyRows = await db
+        .select({
+          id: apiKeys.id,
+          keyId: apiKeys.keyId,
+          name: apiKeys.name,
+          scopes: apiKeys.scopes,
+          createdBy: apiKeys.createdBy,
+          createdAt: apiKeys.createdAt,
+          lastUsedAt: apiKeys.lastUsedAt,
+          revokedAt: apiKeys.revokedAt,
+          expiresAt: apiKeys.expiresAt
+        })
+        .from(apiKeys)
+        .where(eq(apiKeys.workspaceId, workspaceId))
+        .orderBy(asc(apiKeys.createdAt), asc(apiKeys.id));
+      zip.addBuffer(jsonBuffer(apiKeyRows), 'api-keys.json');
+
+      // Projects and their members, archived projects included (a project is
+      // never deleted). What a tool links to a project is the tool's entry.
+      const projectRows = await db
+        .select({
+          id: projects.id,
+          name: projects.name,
+          description: projects.description,
+          metadata: projects.metadata,
+          archivedAt: projects.archivedAt,
+          createdBy: projects.createdBy,
+          createdAt: projects.createdAt,
+          updatedAt: projects.updatedAt
+        })
+        .from(projects)
+        .where(eq(projects.workspaceId, workspaceId))
+        .orderBy(asc(projects.createdAt), asc(projects.id));
+      zip.addBuffer(jsonBuffer(projectRows), 'projects.json');
+
+      const projectMemberRows = await db
+        .select({
+          id: projectMembers.id,
+          projectId: projectMembers.projectId,
+          memberId: projectMembers.memberId,
+          userId: workspaceMembers.userId,
+          role: projectMembers.role,
+          addedBy: projectMembers.addedBy,
+          createdAt: projectMembers.createdAt
+        })
+        .from(projectMembers)
+        .innerJoin(projects, eq(projectMembers.projectId, projects.id))
+        .innerJoin(workspaceMembers, eq(projectMembers.memberId, workspaceMembers.id))
+        .where(eq(projects.workspaceId, workspaceId))
+        .orderBy(asc(projectMembers.createdAt), asc(projectMembers.id));
+      zip.addBuffer(jsonBuffer(projectMemberRows), 'project_members.json');
+
+      // The teams (PRDCT-2813): the tool's own and the hub's projections
+      // alike (`hubTeamId` tells them apart), their seats, and their places
+      // on projects (PRDCT-2794). The same three tables on both editions.
+      const teamRows = await db
+        .select({
+          id: workspaceTeams.id,
+          hubTeamId: workspaceTeams.hubTeamId,
+          slug: workspaceTeams.slug,
+          name: workspaceTeams.name,
+          createdBy: workspaceTeams.createdBy,
+          createdAt: workspaceTeams.createdAt,
+          updatedAt: workspaceTeams.updatedAt
+        })
+        .from(workspaceTeams)
+        .where(eq(workspaceTeams.workspaceId, workspaceId))
+        .orderBy(asc(workspaceTeams.createdAt), asc(workspaceTeams.id));
+      zip.addBuffer(jsonBuffer(teamRows), 'teams.json');
+
+      const teamMemberRows = await db
+        .select({
+          id: workspaceTeamMembers.id,
+          teamId: workspaceTeamMembers.teamId,
+          memberId: workspaceTeamMembers.memberId,
+          userId: workspaceMembers.userId,
+          addedBy: workspaceTeamMembers.addedBy,
+          createdAt: workspaceTeamMembers.createdAt
+        })
+        .from(workspaceTeamMembers)
+        .innerJoin(workspaceTeams, eq(workspaceTeamMembers.teamId, workspaceTeams.id))
+        .innerJoin(workspaceMembers, eq(workspaceTeamMembers.memberId, workspaceMembers.id))
+        .where(eq(workspaceTeams.workspaceId, workspaceId))
+        .orderBy(asc(workspaceTeamMembers.createdAt), asc(workspaceTeamMembers.id));
+      zip.addBuffer(jsonBuffer(teamMemberRows), 'team_members.json');
+
+      const projectTeamRows = await db
+        .select({
+          id: projectTeams.id,
+          projectId: projectTeams.projectId,
+          teamId: projectTeams.teamId,
+          role: projectTeams.role,
+          addedBy: projectTeams.addedBy,
+          createdAt: projectTeams.createdAt
+        })
+        .from(projectTeams)
+        .innerJoin(projects, eq(projectTeams.projectId, projects.id))
+        .where(eq(projects.workspaceId, workspaceId))
+        .orderBy(asc(projectTeams.createdAt), asc(projectTeams.id));
+      zip.addBuffer(jsonBuffer(projectTeamRows), 'project_teams.json');
+
+      // 3. Audit log as NDJSON, keyset-batched (this table is unbounded).
+      zip.addReadStream(Readable.from(auditNdjson(db, workspaceId)), 'audit-log.ndjson');
+
+      // 4. Files metadata — ALL rows including soft-deleted (deletedAt set;
+      //    createdBy may be null after an account delete).
+      const fileRows = await db
+        .select()
+        .from(files)
+        .where(eq(files.workspaceId, workspaceId))
+        .orderBy(asc(files.createdAt), asc(files.id));
+      zip.addBuffer(
+        jsonBuffer(
+          fileRows.map((f) => ({
+            id: f.id,
+            sha256: f.sha256,
+            sizeBytes: f.sizeBytes,
+            contentType: f.contentType,
+            originalName: f.originalName,
+            createdBy: f.createdBy,
+            createdAt: f.createdAt.toISOString(),
+            deletedAt: f.deletedAt?.toISOString() ?? null
+          }))
+        ),
+        'files.json'
+      );
+
+      // 4b. The tool's entries, in the tool's order (none without the slot).
+      for (const entry of toolEntries) zip.addBuffer(entry.buffer, entry.entryName);
+
+      // 5. Blobs, strictly one at a time: await each stream's end before
+      //    opening the next so file descriptors / S3 sockets never pile up
+      //    (yazl keeps accepting entries while piping until end()).
+      const skipped: Array<{ fileId: string; sha256: string; reason: string }> = [];
+      for (const f of fileRows) {
+        // Destroying yazl's output does NOT stop the pump: the ZipFile only
+        // latches errors emitted on itself, so entries added after an abort
+        // are still opened and fully drained. Check the signal explicitly or
+        // a cancelled multi-GB export keeps consuming disk/S3 bandwidth.
+        if (c.req.raw.signal.aborted) throw new Error('client aborted the export download');
+        if (f.deletedAt) {
+          skipped.push({ fileId: f.id, sha256: f.sha256, reason: 'soft-deleted' });
+          continue;
+        }
+        const key = blobKey(f.workspaceId, f.sha256);
+        if (!(await storage.exists(key))) {
+          skipped.push({ fileId: f.id, sha256: f.sha256, reason: 'blob-missing' });
+          continue;
+        }
+        const stream = await storage.getStream(key);
+        currentBlobStream = stream;
+        // compress: false — media/binary blobs don't deflate; JSON entries
+        // above keep yazl's default compression.
+        zip.addReadStream(stream, `files/${f.id}-${sanitizeEntryName(f.originalName)}`, {
+          compress: false
+        });
+        await finished(stream);
+        currentBlobStream = null;
+      }
+
+      // 6. The skip list last (this is why the manifest carries none).
+      zip.addBuffer(jsonBuffer(skipped), 'skipped-blobs.json');
+      zip.end();
+    })().catch((err: unknown) => {
+      // A client cancel is routine, not an operational error.
+      if (c.req.raw.signal.aborted) {
+        logger.info({ workspaceId }, 'workspace export cancelled by the client');
+      } else {
+        logger.error({ err, workspaceId }, 'workspace export pump failed — download truncated');
+      }
+      currentBlobStream?.destroy();
+      output.destroy(err instanceof Error ? err : new Error(String(err)));
+    });
+
+    const stamp = new Date().toISOString().slice(0, 10).replace(/-/g, '');
+    return c.body(Readable.toWeb(output) as unknown as ReadableStream, 200, {
+      'content-type': 'application/zip',
+      'content-disposition': `attachment; filename="export-${instance?.instanceId ?? 'instance'}-${stamp}.zip"`,
+      'x-content-type-options': 'nosniff',
+      'cache-control': 'no-store'
+    });
+  });
+}

package/src/api/files.ts

@@ -0,0 +1,200 @@
+import type { OpenAPIHono } from '@hono/zod-openapi';
+import type { Context } from 'hono';
+import { Readable } from 'node:stream';
+import type { ReadableStream as WebReadableStream } from 'node:stream/web';
+import type { SQL } from 'drizzle-orm';
+import { fileGetRoute, filesListRoute, fileUploadRoute } from '@antasphere/chassis-contract/routes';
+import type { Principal } from '@antasphere/chassis-contract';
+import type { DbConn, FileRow } from '@antasphere/chassis-db';
+import type { Env } from '../env.js';
+import type { ScopeRoutes } from './scope-routes.js';
+import type { Logger } from '../logger.js';
+import type { PlatformRegistry } from '../platform/registry.js';
+import type { FileService } from '../files/service.js';
+import { FileTooLargeError } from '../files/spool.js';
+import { serveBlob } from '../files/serve.js';
+import type { StorageDriver } from '../storage/driver.js';
+import { isUuid } from '../pagination.js';
+import { requireAuth, requireNonGuest } from '../middleware/auth-context.js';
+
+const err = (code: string, message: string) => ({ error: { code, message } });
+
+const toWire = (f: FileRow) => ({
+  id: f.id,
+  sha256: f.sha256,
+  sizeBytes: f.sizeBytes,
+  contentType: f.contentType,
+  originalName: f.originalName,
+  createdBy: f.createdBy,
+  createdAt: f.createdAt.toISOString()
+});
+
+export interface FileRouteDeps {
+  service: FileService;
+  storage: StorageDriver;
+  registry: PlatformRegistry;
+  env: Pick<Env, 'MAX_FILE_SIZE_MB'>;
+  logger: Logger;
+  /**
+   * ADR 011 blob-delete guard: true when the blob is referenced by a live
+   * version manifest of the tool's resource — DELETE answers 409 file_in_use instead
+   * of removing it. Runs inside the delete transaction (files module stays
+   * tool-agnostic; the wiring point injects the tool's check).
+   */
+  blobInUse: (tx: DbConn, workspaceId: string, sha256: string) => Promise<boolean>;
+  /**
+   * ADR 013 per-blob read scope (SL-B1): a WHERE predicate over the `files`
+   * row, or `undefined` for the workspace admin/owner operator view. Injected
+   * for the same reason as `blobInUse` — the files module stays
+   * tool-agnostic and the wiring point supplies the tool's policy.
+   */
+  blobReadScope: (principal: Principal) => SQL | undefined;
+  /**
+   * The delete route the tool instantiated (its OpenAPI 409 carries the tool's
+   * wording), and the tool's message of that 409 `file_in_use`
+   * (`copy.fileInUse`): what references a blob is the tool's to name.
+   */
+  fileDeleteRoute: ScopeRoutes['fileDeleteRoute'];
+  fileInUse: string;
+}
+
+export function registerFileRoutes(api: OpenAPIHono, deps: FileRouteDeps): void {
+  const { service, storage, registry, env, logger } = deps;
+  const maxBytes = env.MAX_FILE_SIZE_MB * 1024 * 1024;
+
+  api.use('/files', requireAuth());
+  api.use('/files/*', requireAuth());
+  // Guest capability limit (D2, both editions): the generic files surface is
+  // a WORKSPACE-level surface (ADR 006) — an inventory of the tenant's blobs
+  // with a delete on it. Its READS are now per-resource authorized like every
+  // other content read (SL-B1: `deps.blobReadScope`, ADR 013), but the
+  // surface as a whole still belongs to the workspace, and an external guest
+  // has no business there: they were invited to ONE resource, not to the host
+  // tenant's file cabinet. Guests push and pull its bytes through the ADR
+  // 013-gated routes of the tool instead (its asset upload and its
+  // per-resource asset download).
+  api.use('/files', requireNonGuest());
+  api.use('/files/*', requireNonGuest());
+
+  api.openapi(filesListRoute, async (c) => {
+    const principal = c.get('principal')!;
+    const { cursor, limit } = c.req.valid('query');
+    const { files: rows, nextCursor } = await service.list(principal.workspaceId, {
+      ...(cursor !== undefined ? { cursor } : {}),
+      limit,
+      // ADR 013 (SL-B1): a plain member pages the blobs they uploaded plus
+      // those referenced by resources they can read; admins/owners keep the
+      // whole-workspace operator view.
+      visibility: deps.blobReadScope(principal)
+    });
+    return c.json({ files: rows.map(toWire), nextCursor }, 200);
+  });
+
+  api.openapi(fileUploadRoute, async (c) => {
+    const principal = c.get('principal')!;
+    const { name } = c.req.valid('query');
+    const contentType = c.req.header('content-type') ?? 'application/octet-stream';
+
+    // The declared-size check and the usage event are the entitlement gate's
+    // (the billing rail, §7): a tool declares `files.upload` on this route in
+    // its contract and the chassis gate runs it before this handler; the hard
+    // cap is still enforced mid-stream below. Nothing is checked or emitted
+    // by hand here.
+    if (!c.req.raw.body) {
+      return c.json(err('empty_body', 'Request body required'), 400);
+    }
+
+    try {
+      const { file, deduplicated } = await service.upload({
+        workspaceId: principal.workspaceId,
+        createdBy: principal.userId,
+        originalName: name,
+        contentType,
+        body: Readable.fromWeb(c.req.raw.body as WebReadableStream),
+        maxBytes
+      });
+
+      c.set('audit', {
+        action: 'file.upload',
+        resourceType: 'file',
+        resourceId: file.id,
+        metadata: { name, sizeBytes: file.sizeBytes, deduplicated }
+      });
+      registry.events.emit('file.uploaded', {
+        workspaceId: principal.workspaceId,
+        fileId: file.id,
+        sizeBytes: file.sizeBytes
+      });
+
+      return c.json({ file: toWire(file), deduplicated }, 201);
+    } catch (e) {
+      if (e instanceof FileTooLargeError) {
+        return c.json(err('file_too_large', e.message), 413);
+      }
+      logger.error({ err: e }, 'file upload failed');
+      return c.json(err('upload_failed', 'Upload failed'), 400);
+    }
+  });
+
+  api.openapi(fileGetRoute, async (c) => {
+    const principal = c.get('principal')!;
+    const { id } = c.req.valid('param');
+    // 404, never 403, when the scope excludes the blob (ADR 013): a blob a
+    // principal cannot read must not be probeable by id either.
+    const file = await service.get(principal.workspaceId, id, deps.blobReadScope(principal));
+    if (!file) return c.json(err('not_found', 'File not found'), 404);
+    return c.json(toWire(file), 200);
+  });
+
+  api.openapi(deps.fileDeleteRoute, async (c) => {
+    const principal = c.get('principal')!;
+    const { id } = c.req.valid('param');
+    // Same scope on the mutation: a member must not be able to delete (or
+    // probe) a blob they may not read.
+    const file = await service.get(principal.workspaceId, id, deps.blobReadScope(principal));
+    if (!file) return c.json(err('not_found', 'File not found'), 404);
+    const outcome = await service.delete(file, (tx, row) => deps.blobInUse(tx, row.workspaceId, row.sha256));
+    if (outcome === 'in_use') {
+      return c.json(err('file_in_use', deps.fileInUse), 409);
+    }
+    c.set('audit', { action: 'file.delete', resourceType: 'file', resourceId: file.id });
+    return c.json(toWire(file), 200);
+  });
+
+  // ── Content: streamed, Range-capable. Registered as plain Hono routes (a
+  // byte endpoint, not part of the JSON OpenAPI surface); guarded by the
+  // same requireAuth + scope machinery as everything else under /files.
+  // The streaming machinery itself (ETag/304/Range/safe-serving) is shared
+  // with the tool's asset download — files/serve.ts.
+  const contentHandler = async (c: Context, headOnly: boolean) => {
+    const principal = c.get('principal')!;
+    const id = c.req.param('id') ?? '';
+    // Plain Hono route (no contract param schema): reject a non-UUID id here
+    // or it reaches Postgres' uuid cast and surfaces as a sanitized 500.
+    if (!isUuid(id)) return c.json(err('not_found', 'File not found'), 404);
+    // The byte route carries the ADR 013 scope too (SL-B1) — this was the
+    // whole-tenant read: `workspace_id` alone served ANY resource's content to
+    // any member and to any read-scope key.
+    const file = await service.get(principal.workspaceId, id, deps.blobReadScope(principal));
+    if (!file) return c.json(err('not_found', 'File not found'), 404);
+
+    return serveBlob(c, {
+      storage,
+      logger,
+      workspaceId: file.workspaceId,
+      sha256: file.sha256,
+      sizeBytes: file.sizeBytes,
+      contentType: file.contentType,
+      filename: file.originalName,
+      headOnly
+    });
+  };
+
+  // ONE registration for both verbs. Hono rewrites HEAD to GET before routing
+  // (verified against the pinned version: a HEAD request runs the GET handler
+  // and the HEAD registration never fires), so a separate `api.on('HEAD', …)`
+  // is dead code and every HEAD would silently stream the whole body. Read
+  // the verb off the request instead — that is the only signal that survives
+  // the rewrite. Never add an `api.on('HEAD', …)` route on this app.
+  api.get('/files/:id/content', (c) => contentHandler(c, c.req.method === 'HEAD'));
+}