@lanes-sh/link 0.1.0

package/src/secrets/system.ts

@@ -0,0 +1,173 @@
+import {
+  assertKeyLength,
+  blobDocumentIO,
+  envOnlyKeySource,
+  fileDocumentIO,
+  fileKeySource,
+  generateKey,
+  open,
+  seal,
+  type DocumentIO,
+  type KeySource,
+} from './document.ts';
+import { assertValidSecretRef, type SecretRef, type SecretStore } from './index.ts';
+import type { BlobStore } from '#stores/blobs';
+
+/**
+ * The **system** store — what the system holds in order to do its job.
+ *
+ * OAuth refresh tokens, OAuth client secrets, the profile API token. These
+ * authorise the system itself, and they are NEVER reachable from MCP, in any
+ * form, for any client. If an agent could read the Gmail refresh token it would
+ * simply call Google directly, and the entire policy layer would become
+ * decorative.
+ *
+ * Its sibling is `./vault.ts` — the owner's own passwords and API keys, which an
+ * agent may legitimately be granted access to under policy. They share this
+ * component, the document format, and the adapters. They share no key, no
+ * document, and no path from a `ProviderContext` — see the two tests named in
+ * `./index.ts`.
+ *
+ * WHAT THIS DOES NOT DO, stated because the security model says so rather than
+ * implying a guarantee the code does not deliver: encryption at rest protects
+ * stored credentials from someone reading the file. It does not protect a
+ * credential while a process is using it — the plaintext is in memory whenever
+ * a provider makes a call. That limit is inherent.
+ */
+
+const MAGIC = 'lanes-link-credentials';
+const KEY_ENV = 'LANES_LINK_CREDENTIAL_KEY';
+const DEFAULT_BLOB_KEY = 'credentials.enc';
+
+export interface FileSystemSecretsOptions {
+  /** Path to the encrypted file, e.g. `./data/personal/credentials.enc`. */
+  readonly path: string;
+  /**
+   * 32-byte key. When omitted, read from `LANES_LINK_CREDENTIAL_KEY` (base64),
+   * else from a sibling `.key` file, which is created on first use at 0600.
+   */
+  readonly key?: Uint8Array;
+  readonly env?: Record<string, string | undefined>;
+}
+
+export function createFileSecretStore(options: FileSystemSecretsOptions): SecretStore {
+  const keyPath = `${options.path}.key`;
+  const env = options.env ?? (process.env as Record<string, string | undefined>);
+
+  return new DocumentSecretStore(
+    fileDocumentIO(options.path, keyPath),
+    fileKeySource({ keyPath, envVar: KEY_ENV, env, explicit: options.key }),
+  );
+}
+
+export interface BlobSecretsOptions {
+  /** Where the document lives. Scope it before passing it in. */
+  readonly store: BlobStore;
+  readonly key?: string;
+  readonly encryptionKey?: Uint8Array;
+  readonly env?: Record<string, string | undefined>;
+}
+
+export function createBlobSecretStore(options: BlobSecretsOptions): SecretStore {
+  const key = options.key ?? DEFAULT_BLOB_KEY;
+  const env = options.env ?? (process.env as Record<string, string | undefined>);
+
+  return new DocumentSecretStore(
+    blobDocumentIO(options.store, key),
+    envOnlyKeySource({
+      envVar: KEY_ENV,
+      env,
+      explicit: options.encryptionKey,
+      label: key,
+      remedy: 'openssl rand -base64 32',
+    }),
+  );
+}
+
+/**
+ * A `SecretStore` over one encrypted document.
+ *
+ * The whole document is rewritten on every change, which is right for something
+ * holding tens of entries and would not be for something holding millions.
+ * Per-entry encryption with plaintext keys would be marginally more convenient
+ * and would leak which accounts exist.
+ */
+class DocumentSecretStore implements SecretStore {
+  readonly #io: DocumentIO;
+  readonly #keySource: KeySource;
+  #key: Uint8Array | undefined;
+  #cache: Map<string, string> | undefined;
+
+  constructor(io: DocumentIO, keySource: KeySource) {
+    this.#io = io;
+    this.#keySource = keySource;
+  }
+
+  async get(ref: SecretRef): Promise<string | null> {
+    assertValidSecretRef(ref);
+    return (await this.#load()).get(ref) ?? null;
+  }
+
+  async has(ref: SecretRef): Promise<boolean> {
+    assertValidSecretRef(ref);
+    return (await this.#load()).has(ref);
+  }
+
+  async set(ref: SecretRef, value: string): Promise<void> {
+    assertValidSecretRef(ref);
+    const entries = await this.#load();
+    entries.set(ref, value);
+    await this.#save(entries);
+  }
+
+  async delete(ref: SecretRef): Promise<void> {
+    assertValidSecretRef(ref);
+    const entries = await this.#load();
+    if (entries.delete(ref)) await this.#save(entries);
+  }
+
+  async list(prefix?: string): Promise<SecretRef[]> {
+    const entries = await this.#load();
+    return [...entries.keys()].filter((ref) => !prefix || ref.startsWith(prefix)).sort();
+  }
+
+  /**
+   * Drop the decrypted copy from memory.
+   *
+   * Named for the interface it satisfies rather than for the hygiene it also
+   * provides. It was `forget()` and nothing ever called it, which is precisely
+   * how a rotated token stayed invisible to a running endpoint.
+   */
+  refresh(): void {
+    this.#cache = undefined;
+  }
+
+  async #resolveKey(): Promise<Uint8Array> {
+    return (this.#key ??= await this.#keySource());
+  }
+
+  async #load(): Promise<Map<string, string>> {
+    if (this.#cache) return this.#cache;
+
+    const text = await this.#io.read();
+    if (text === null) return (this.#cache = new Map());
+
+    const entries = open<Record<string, string>>(
+      MAGIC,
+      await this.#resolveKey(),
+      text,
+      this.#io,
+      KEY_ENV,
+    );
+    return (this.#cache = new Map(Object.entries(entries)));
+  }
+
+  async #save(entries: Map<string, string>): Promise<void> {
+    await this.#io.write(seal(MAGIC, await this.#resolveKey(), Object.fromEntries(entries)));
+    this.#cache = entries;
+  }
+}
+
+export { assertKeyLength };
+/** A fresh credential-store key, base64, printed once and stored by the operator. */
+export const generateCredentialKey = generateKey;

package/src/secrets/vault.ts

@@ -0,0 +1,336 @@
+import {
+  blobDocumentIO,
+  envOnlyKeySource,
+  fileDocumentIO,
+  fileKeySource,
+  secretDocumentIO,
+  generateKey,
+  open,
+  seal,
+  type DocumentIO,
+  type KeySource,
+} from './document.ts';
+import type { BlobStore } from '#stores/blobs';
+
+/**
+ * The **vault** store — the owner's own passwords and API keys.
+ *
+ * Its sibling is `./system.ts`, and the difference between them is the whole
+ * point of both: system credentials authorise Lanes Link itself and are
+ * unreachable from MCP; vault items belong to the owner and an agent may be
+ * granted one, by name, under policy.
+ *
+ * They share this component, the document format in `./document.ts`, and the
+ * adapters. They share **no key, no document, and no environment variable** —
+ * `LANES_LINK_VAULT_KEY` against `LANES_LINK_CREDENTIAL_KEY`. One master secret
+ * reused across purposes turns any single compromise into a total one, which is
+ * why the merge stopped where it did: two implementations of one format was
+ * duplication worth removing, two keys is the security model.
+ *
+ * The shapes differ too, and honestly so. A system credential is a ref and a
+ * string. A vault item carries a description and belongs to a connection,
+ * because each one becomes its own `vault.get.<id>` capability — which is what
+ * makes per-item policy expressible without teaching the policy engine about
+ * arguments (ADR-012 §3).
+ */
+
+const MAGIC = 'lanes-link-vault';
+const DEFAULT_BLOB_KEY = 'vault.enc';
+
+/**
+ * The environment variable the key arrives in, and where the sealed document
+ * sits when the target keeps it in its credential store.
+ *
+ * Exported because a deploy has to wire both: it mints the key into the store
+ * and tells the platform to mount it under this name. Spelling either of them a
+ * second time in `deployments/` is how they drift, and the failure that causes
+ * is a revision whose vault reads fail with the key sitting right there.
+ */
+export const VAULT_KEY_ENV = 'LANES_LINK_VAULT_KEY';
+export const DEFAULT_SECRET_REF = 'vault/document';
+
+/**
+ * Where the key itself lives, for a target whose credential store can hold it.
+ *
+ * Beside the document rather than somewhere else, which reads wrong and is not:
+ * ADR-022 put the ciphertext in Secret Manager *because* the key already came
+ * from there, and a key the deploy cannot reach is one an operator has to carry
+ * by hand forever. What keeps them apart is that this one is mounted as an
+ * environment variable and the document is not — an attacker holding the
+ * document alone still holds ciphertext.
+ */
+export const VAULT_KEY_REF = 'vault/key';
+
+const KEY_ENV = VAULT_KEY_ENV;
+
+/** Item ids become part of a capability name, so they are held to its grammar. */
+export const VAULT_ITEM_ID = /^[a-z0-9][a-z0-9_]*$/;
+
+export interface VaultItem {
+  readonly id: string;
+  readonly value: string;
+  readonly description?: string;
+  readonly updatedAt: string;
+}
+
+/**
+ * Storage for vault items, scoped by connection.
+ *
+ * `ids` returns names only — there is no operation that enumerates values,
+ * which is the one property this and the system store genuinely share.
+ */
+export interface VaultStore {
+  get(connectionId: string, id: string): Promise<VaultItem | null>;
+  put(connectionId: string, item: Omit<VaultItem, 'updatedAt'>): Promise<void>;
+  delete(connectionId: string, id: string): Promise<boolean>;
+  /** Every `<connection>/<item>` pair held, so the runtime can register reads. */
+  ids(): Promise<ReadonlyArray<{ connectionId: string; id: string; description?: string }>>;
+}
+
+type Entries = Record<string, { value: string; description?: string; updatedAt: string }>;
+
+export interface FileVaultStoreOptions {
+  /** Path to the encrypted file, e.g. `./data/personal/vault.enc`. */
+  readonly path: string;
+  /**
+   * 32-byte key. When omitted, read from `LANES_LINK_VAULT_KEY` (base64), else
+   * from a sibling `.key` file created on first use at 0600.
+   */
+  readonly key?: Uint8Array;
+  readonly env?: Record<string, string | undefined>;
+}
+
+export function createFileVaultStore(options: FileVaultStoreOptions): VaultStore {
+  const keyPath = `${options.path}.key`;
+  const env = options.env ?? (process.env as Record<string, string | undefined>);
+
+  return new DocumentVaultStore(
+    fileDocumentIO(options.path, keyPath),
+    fileKeySource({ keyPath, envVar: KEY_ENV, env, explicit: options.key }),
+  );
+}
+
+export interface BlobVaultStoreOptions {
+  /** Where the document lives. Scope it before passing it in. */
+  readonly store: BlobStore;
+  /** Object key. One document, so one key. */
+  readonly key?: string;
+  /** 32-byte key. When omitted, `LANES_LINK_VAULT_KEY` — and nothing else. */
+  readonly encryptionKey?: Uint8Array;
+  readonly env?: Record<string, string | undefined>;
+}
+
+/**
+ * The vault in blob storage — what a deployed instance uses.
+ *
+ * The file adapter was unconditional before ADR-014: a deployed instance wrote
+ * its vault to a container filesystem, and every item in it was discarded by the
+ * next revision without an error to say so.
+ */
+export function createBlobVaultStore(options: BlobVaultStoreOptions): VaultStore {
+  const key = options.key ?? DEFAULT_BLOB_KEY;
+  const env = options.env ?? (process.env as Record<string, string | undefined>);
+
+  return new DocumentVaultStore(
+    blobDocumentIO(options.store, key),
+    envOnlyKeySource({
+      envVar: KEY_ENV,
+      env,
+      explicit: options.encryptionKey,
+      label: key,
+      remedy: 'lanes link vault key generate',
+    }),
+  );
+}
+
+export interface SecretVaultStoreOptions {
+  /** The target's own secret store. */
+  readonly store: {
+    get(ref: string): Promise<string | null>;
+    set(ref: string, value: string): Promise<void>;
+  };
+  /** Where the document lives. One document, so one ref. */
+  readonly ref?: string;
+  /** 32-byte key. When omitted, `LANES_LINK_VAULT_KEY` — and nothing else. */
+  readonly encryptionKey?: Uint8Array;
+  readonly env?: Record<string, string | undefined>;
+}
+
+/**
+ * The vault as a single entry in the secret store — what a deployment uses.
+ *
+ * This looks like the merge the file above spends three paragraphs forbidding,
+ * and it is not. What must never be shared is the **key**, and it is not: the
+ * document is sealed under `LANES_LINK_VAULT_KEY` before it gets here, so the
+ * secret store holds ciphertext it cannot read. Separate document, separate
+ * key, separate environment variable — the three things `./index.ts` names.
+ * The backend was never on that list, and the two stores have shared adapters
+ * since they were merged.
+ *
+ * **Why the bucket arrangement it replaces was backwards.** `blob` put the
+ * vault in object storage so reading it took two things: bucket access *and*
+ * the key. But the key already arrives from Secret Manager via `--set-secrets`,
+ * and anyone with Secret Manager read access already holds every OAuth refresh
+ * token — the whole of Gmail, Drive, and iCloud. The vault is the smaller
+ * asset and it was the one behind the taller fence. See ADR-022.
+ *
+ * Item *names* stay encrypted because they are inside the document, which is
+ * why this is one secret rather than one per item.
+ *
+ * The cost, stated: a secret store that versions writes gains a version per
+ * `vault put`. That is a few cents a month on Secret Manager and `vault put` is
+ * a rare human action, so nothing prunes them — a prune would need
+ * `secretmanager.versions.destroy`, which is deliberately not granted to the
+ * identity a deployment runs as.
+ */
+export function createSecretVaultStore(options: SecretVaultStoreOptions): VaultStore {
+  const ref = options.ref ?? DEFAULT_SECRET_REF;
+  const env = options.env ?? (process.env as Record<string, string | undefined>);
+
+  return new DocumentVaultStore(
+    secretDocumentIO(options.store, ref),
+    envOnlyKeySource({
+      envVar: KEY_ENV,
+      env,
+      explicit: options.encryptionKey,
+      label: ref,
+      remedy: 'lanes link vault key generate',
+    }),
+  );
+}
+
+class DocumentVaultStore implements VaultStore {
+  readonly #io: DocumentIO;
+  readonly #keySource: KeySource;
+  #key: Uint8Array | undefined;
+  #cache: Entries | undefined;
+
+  constructor(io: DocumentIO, keySource: KeySource) {
+    this.#io = io;
+    this.#keySource = keySource;
+  }
+
+  async get(connectionId: string, id: string): Promise<VaultItem | null> {
+    const entry = (await this.#load())[keyFor(connectionId, id)];
+    if (!entry) return null;
+
+    return {
+      id,
+      value: entry.value,
+      ...(entry.description ? { description: entry.description } : {}),
+      updatedAt: entry.updatedAt,
+    };
+  }
+
+  async put(connectionId: string, item: Omit<VaultItem, 'updatedAt'>): Promise<void> {
+    assertItemId(item.id);
+    const entries = { ...(await this.#load()) };
+
+    entries[keyFor(connectionId, item.id)] = {
+      value: item.value,
+      ...(item.description ? { description: item.description } : {}),
+      updatedAt: new Date().toISOString(),
+    };
+
+    await this.#save(entries);
+  }
+
+  async delete(connectionId: string, id: string): Promise<boolean> {
+    const entries = { ...(await this.#load()) };
+    const key = keyFor(connectionId, id);
+    if (!(key in entries)) return false;
+
+    delete entries[key];
+    await this.#save(entries);
+    return true;
+  }
+
+  async ids(): Promise<ReadonlyArray<{ connectionId: string; id: string; description?: string }>> {
+    return listIds(await this.#load());
+  }
+
+  async #resolveKey(): Promise<Uint8Array> {
+    return (this.#key ??= await this.#keySource());
+  }
+
+  async #load(): Promise<Entries> {
+    if (this.#cache) return this.#cache;
+
+    const text = await this.#io.read();
+    if (text === null) return (this.#cache = {});
+
+    return (this.#cache = open<Entries>(MAGIC, await this.#resolveKey(), text, this.#io, KEY_ENV));
+  }
+
+  async #save(entries: Entries): Promise<void> {
+    await this.#io.write(seal(MAGIC, await this.#resolveKey(), entries));
+    this.#cache = entries;
+  }
+}
+
+/** An in-memory store, for tests and for a target that persists nothing. */
+export function createMemoryVaultStore(seed: Entries = {}): VaultStore {
+  const entries: Entries = { ...seed };
+
+  return {
+    async get(connectionId, id) {
+      const entry = entries[keyFor(connectionId, id)];
+      if (!entry) return null;
+      return {
+        id,
+        value: entry.value,
+        ...(entry.description ? { description: entry.description } : {}),
+        updatedAt: entry.updatedAt,
+      };
+    },
+    async put(connectionId, item) {
+      assertItemId(item.id);
+      entries[keyFor(connectionId, item.id)] = {
+        value: item.value,
+        ...(item.description ? { description: item.description } : {}),
+        updatedAt: new Date().toISOString(),
+      };
+    },
+    async delete(connectionId, id) {
+      const key = keyFor(connectionId, id);
+      if (!(key in entries)) return false;
+      delete entries[key];
+      return true;
+    },
+    async ids() {
+      return listIds(entries);
+    },
+  };
+}
+
+function listIds(
+  entries: Entries,
+): ReadonlyArray<{ connectionId: string; id: string; description?: string }> {
+  return Object.entries(entries)
+    .map(([key, entry]) => {
+      const slash = key.indexOf('/');
+      return {
+        connectionId: key.slice(0, slash),
+        id: key.slice(slash + 1),
+        ...(entry.description ? { description: entry.description } : {}),
+      };
+    })
+    .sort((a, b) => `${a.connectionId}/${a.id}`.localeCompare(`${b.connectionId}/${b.id}`));
+}
+
+function keyFor(connectionId: string, id: string): string {
+  return `${connectionId}/${id}`;
+}
+
+export function assertItemId(id: string): void {
+  if (!VAULT_ITEM_ID.test(id)) {
+    throw new Error(
+      `Vault item id ${JSON.stringify(id)} must be lowercase letters, digits and "_". ` +
+        'The id becomes part of the capability name — "vault.get.github_token" — which is what ' +
+        'lets policy grant one item without granting the rest (ADR-012).',
+    );
+  }
+}
+
+/** Generate a fresh vault key, distinct from the system store's. */
+export const generateVaultKey = generateKey;

package/src/server/attachments.ts

@@ -0,0 +1,197 @@
+import { mergeCapabilities, type ProfileRuntime } from './mcp/index.ts';
+import type { Principal } from '#auth';
+
+/**
+ * Handing the endpoint some bytes, so a later call can name them.
+ *
+ * The one thing the protocol cannot do. A tool argument carries JSON, so a file
+ * in a tool call is base64 in the model's output — which for a 239 KB PDF is
+ * around 320,000 characters, past what a model can write in one message. There is
+ * no client-to-server binary channel in any released version of MCP, and `roots`
+ * never carried bytes even before it was deprecated. So the bytes come in over
+ * ordinary HTTP, out of band, and what travels through the model afterwards is a
+ * handle. That is also the shape the protocol's own draft file-transfer work
+ * settles on.
+ *
+ * This is what makes attachments work when the endpoint is not on the caller's
+ * machine. A `path` names the filesystem the *server* can see, which on a hosted
+ * deployment is a container and not the operator's Mac; a handle does not care
+ * where either end is.
+ *
+ * **Staged for one connection, not for the profile.** A blob store handed to a
+ * provider is already namespaced by provider and connection, and the point of
+ * that is that one account's bytes are not reachable from another. Staging into a
+ * shared area would quietly widen it. So an upload names its target, the
+ * principal has to be able to reach that target, and the handle resolves only
+ * from there.
+ *
+ * This file does HTTP and authorization; the write itself is
+ * `Dispatcher.stageAttachment`. Not a split for its own sake — `server` may not
+ * reach a store, and should not: how blobs are namespaced is not something a
+ * component that speaks HTTP should know, and putting the write behind the
+ * dispatcher is also what gets it into the audit log.
+ */
+
+export const ATTACHMENTS_PATH = '/attachments';
+
+/**
+ * Largest upload accepted.
+ *
+ * Above every mail host's own ceiling — 35 MiB is the largest here — so this is
+ * never the binding limit on a legitimate send, and well under Bun's 128 MiB
+ * default body cap so a refusal is ours and legible rather than the runtime's.
+ */
+const MAX_UPLOAD_BYTES = 64 * 1024 * 1024;
+
+export interface StageOptions {
+  readonly profiles: ReadonlyMap<string, ProfileRuntime>;
+  readonly primary: string;
+  readonly principal: Principal;
+  readonly request: Request;
+  readonly clientLabel?: string | undefined;
+}
+
+export async function stageAttachment(options: StageOptions): Promise<Response> {
+  const { request } = options;
+
+  if (request.method !== 'POST') {
+    return problem(405, 'Stage an attachment with POST.');
+  }
+
+  const url = new URL(request.url);
+  const profileName = url.searchParams.get('profile') ?? options.primary;
+  const target = url.searchParams.get('connection');
+
+  if (!target) {
+    return problem(
+      400,
+      'Name the connection this is for, as ?connection=<provider>.<account> — a staged file belongs to one account, not to the endpoint.',
+    );
+  }
+
+  const runtime = options.profiles.get(profileName);
+  if (!runtime) {
+    return problem(404, `No profile "${profileName}" on this endpoint.`);
+  }
+
+  const [providerId, ...rest] = target.split('.');
+  const connectionId = rest.join('.');
+  if (!providerId || !connectionId) {
+    return problem(400, `"${target}" is not a connection. Use <provider>.<account>.`);
+  }
+
+  // The same policy that decides which connections a tool may name. Staging into
+  // an account the caller cannot act on would be a write they are not permitted
+  // to make, even though nothing is sent by it.
+  if (!reachable(runtime, options, profileName, target)) {
+    return problem(
+      403,
+      `Connection "${target}" is not reachable for this token in profile "${profileName}".`,
+    );
+  }
+
+  const bytes = await readCapped(request);
+  if (!bytes) {
+    return problem(413, `An attachment must be smaller than ${MAX_UPLOAD_BYTES} bytes.`);
+  }
+  if (bytes.byteLength === 0) {
+    return problem(400, 'The request body was empty, so there is nothing to stage.');
+  }
+
+  const filename = filenameFrom(request.headers.get('x-filename'));
+  const contentType = request.headers.get('content-type') ?? 'application/octet-stream';
+
+  const staged = await runtime.dispatcher.stageAttachment({
+    principal: options.principal,
+    providerId,
+    connectionId,
+    bytes,
+    filename,
+    contentType,
+    clientLabel: options.clientLabel,
+  });
+
+  return Response.json({
+    handle: staged.handle,
+    filename,
+    bytes: bytes.byteLength,
+    content_type: contentType,
+    sha256: staged.sha256,
+    expires_at: new Date(staged.expiresAt).toISOString(),
+    connection: target,
+    profile: profileName,
+    hint: `Pass it as an attachment: { "handle": "${staged.handle}" }`,
+  });
+}
+
+/** Whether this principal can reach that connection for anything at all. */
+function reachable(
+  runtime: ProfileRuntime,
+  options: StageOptions,
+  profileName: string,
+  target: string,
+): boolean {
+  const merged = mergeCapabilities({
+    profiles: new Map([[profileName, runtime]]),
+    principal: options.principal,
+  });
+
+  for (const capability of merged.values()) {
+    for (const connections of capability.reachable.values()) {
+      if (connections.includes(target)) return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Read the body, refusing past the cap.
+ *
+ * Streamed rather than buffered-then-measured, so an oversized upload costs the
+ * bytes it takes to notice rather than all of them.
+ */
+async function readCapped(request: Request): Promise<Uint8Array | null> {
+  const declared = Number(request.headers.get('content-length') ?? Number.NaN);
+  if (Number.isFinite(declared) && declared > MAX_UPLOAD_BYTES) return null;
+
+  if (!request.body) return new Uint8Array();
+
+  const reader = request.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > MAX_UPLOAD_BYTES) {
+      await reader.cancel().catch(() => {});
+      return null;
+    }
+    chunks.push(value);
+  }
+
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+
+/**
+ * A filename safe to record and to put in a MIME header.
+ *
+ * Basename only, and no traversal: the value is echoed into a
+ * `Content-Disposition` and stored beside the bytes, and neither wants a path.
+ */
+function filenameFrom(header: string | null): string {
+  const candidate = (header ?? '').split(/[/\\]/).pop()?.trim() ?? '';
+  return candidate === '' || candidate === '.' || candidate === '..' ? 'attachment' : candidate;
+}
+
+function problem(status: number, message: string): Response {
+  return Response.json({ error: message }, { status });
+}