@ultimat3/query 29.3.2 → 29.4.0

package/CLAUDE.md

@@ -38,6 +38,11 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
 | `policy-gate.ts` | **the only** file that touches `@ultimat3/policy` |
 | `audit-gate.ts` | `audit: true` — **the only** file that calls an `AuditSink` (core's): one record per call, an audited source per `execute()` |
 | `audit-errors.ts` | `X_QUERY_AUDIT_SINK_MISSING` / `X_QUERY_AUDIT_SINK_FAILED` (titles in `errors.ts`) |
+| `download.ts` | `query({ download })`: the build, the in-process file, the mint, the serve — through `admittedCall` |
+| `download-token.ts` | the `_token`: claims `seal()`ed under the master key, opened against one query, one input, the clock |
+| `download-http.ts` | the download route: mint JSON without `_token`, the file with it (`Range:`, `content-disposition`) |
+| `download-errors.ts` | the four `X_QUERY_DOWNLOAD_*` classes (titles in `errors.ts`) |
+| `search-string.ts` | `searchOf`: the input as a search string — the client's request and a minted URL, one encoding |
 
 ## Invariants — the read path
 
@@ -113,6 +118,20 @@ Owns the `query` primitive: reads, live reads, cursors, the incremental matcher.
   `toLiveQuery`): a change row carries none, so the window would be read once and never patched.
   The refusal names the column, never the filter's value.
 
+## Invariants — download
+
+- **A download is a `query`, never a ninth primitive** (`docs/history/primitive-factories.md`):
+  `download:` replaces `sql:` and every rows option is refused beside it (`X_QUERY_DOWNLOAD_INVALID`).
+- **Its stored `sql` throws `X_QUERY_DOWNLOAD_ONLY`** — the ONE refusal every rows projection meets.
+  Never add a per-projection `download` check.
+- **Mint and in-process call go through `admittedCall`** (`read.ts`, the front half `buildSource`
+  shares). The serve re-parses through it as `unenforced` with a written reason: the token IS the
+  policy's decision. Never re-run the policy at serve — the token carries no `facts`.
+- **The token is SEALED, never signed**: it carries the actor. Seal before expiry before input —
+  an expired forgery is a forgery. `X_SEAL_KEY_MISSING` stays a 500 (the server's fault).
+- **`audit: true` records the mint, `rateLimit:` spends at the mint** — a player's `Range:` GETs
+  are one admitted read.
+
 ## Invariants — audit
 
 - **`audit: true` observes the read path, never forks it**: `buildSource` fills the trace (`input`,

package/README.md

@@ -216,6 +216,11 @@ forgetting the policy, and the reason is what tells the next reader which of the
 | `source.ts` | the `SqlSource` contract + `from()`, the in-memory reference |
 | `column-kinds.ts` | `kindsOf(relation)` — the declared kind of each column, which every comparison is decided by |
 | `sealed-shape.ts` | a live read may not filter or order on a `.sealed()` column — refused at subscribe |
+| `download.ts` | `query({ download })` — the declaration, the in-process file, the mint and the serve |
+| `download-token.ts` | the `_token`: claims sealed with core's `seal()`, opened against one query, one input, the clock |
+| `download-http.ts` | the route's two answers — mint JSON or the file: `content-disposition`, one `Range:` window, `no-store` |
+| `download-errors.ts` | `X_QUERY_DOWNLOAD_INVALID` / `_ONLY` / `_TOKEN_INVALID` / `_TOKEN_EXPIRED` |
+| `search-string.ts` | the input as a search string — what the client sends and a minted URL carries |
 
 ## Live queries
 
@@ -665,12 +670,70 @@ before the parse; a sink refusing a **denied/failed** record is logged (`audit.s
 original error still reaches the caller; a sink refusing an **allowed** record withholds the rows,
 `X_QUERY_AUDIT_SINK_FAILED` — a read commits nothing, so a retry is safe.
 
+## `download:` — a file at a short-lived signed URL
+
+A read whose answer is BYTES — a recording, an export, an attachment — is still a `query`: one
+input, one policy, one name, one route. `download:` replaces `sql:`; every rows option (`sql`,
+`live`, `single`, `rows`, `subscribes`, `cache`, `mcp`) beside it is a type error and
+`X_QUERY_DOWNLOAD_INVALID`.
+
+```ts
+import { open } from '@ultimat3/core';
+import { can } from '@ultimat3/policy';
+import { query, t } from '@ultimat3/query';
+import { disk } from '@ultimat3/storage';
+
+export const runRecording = query({
+  input: t.object({ runId: t.uuid, index: t.number.int().min(0) }),
+  policy: can('recording:watch'),
+  download: {
+    expiresInMs: 600_000, // 1 000 … 3 600 000; default 300 000
+    async handle({ input }) {
+      const key = `runs/${input.runId}/recordings/${input.index}`;
+      const { bytes } = await disk('debug').get(key);
+      // A SEALED object opens whole (one AES-GCM envelope), then is served as plain bytes.
+      const plain = await open(new TextDecoder().decode(bytes), { purpose: `run-debug:${key}` });
+      return { body: plain, contentType: 'video/mp4', filename: `run-${input.runId}.mp4` };
+    },
+  },
+});
+```
+
+| Call | Answers |
+|---|---|
+| `client.runRecording.url(input)` (browser, `queryClient`/`.client()`) | `{ url, expiresAt }` — `url` absolute on the client's `baseUrl` |
+| `await runRecording.url(input, { ctx })` (server) | the same, `url` a path: `/_x/query/run-recording?runId=…&index=0&_token=…` |
+| `GET <url>` | the file — to ANY requester holding the URL until `expiresAt`; no session needed |
+| `await runRecording(input, { ctx })` | the `DownloadFile` in-process, as the caller |
+
+| Rule | |
+|---|---|
+| The route | `GET /_x/query/<kebab>` — the read's own. No `_token`: MINT (`application/json`). `_token`: SERVE (the bytes). `auth: 'public'`, `enforcedBy: 'handler'`, `cache: no-store` |
+| Policy | evaluated at MINT, exactly as for a rows read: actor half, the declared `rateLimit:`, the parse, the predicate. A refusal is the policy's own 401/403 |
+| The token | `seal()`ed (`@ultimat3/core`, AES-256-GCM under the app master key, purpose `ultimate.query.download:<name>`) claims: the query, `fingerprint()` of the PARSED input, the expiry on `ctx.now()`, the minting actor minus `facts`. The ACTOR is ciphertext — no id, role or grant readable; the query's path and its input are plain in the URL, as on any read |
+| The serve | the seal first (forged, truncated, another query's, a retired key → `X_QUERY_DOWNLOAD_TOKEN_INVALID`, 403), then the expiry (`X_QUERY_DOWNLOAD_TOKEN_EXPIRED`, 410), then the URL's input re-parsed against the bound fingerprint (edited → 403). `handle` runs as the MINTING actor; the policy is not re-run — it decided at mint, with `facts` the token cannot carry |
+| `handle`'s answer | `{ body: Uint8Array \| Blob \| ReadableStream, contentType, filename, disposition?: 'attachment' \| 'inline', size? }` — bytes, never base64. Anything else is a 500 (`X_INVARIANT`) naming the fix |
+| Headers | `content-type`, `content-disposition` (`attachment` default; ASCII `filename` + exact `filename*=UTF-8''…`), `x-content-type-options: nosniff`, `content-security-policy: default-src 'none'; img-src 'self'; media-src 'self'; sandbox`, `referrer-policy: no-referrer`, `cache-control: no-store`; `content-length` only when the size is known — a `Uint8Array`, a `Blob`, or a stream with `size` |
+| `Range:` | one `bytes=` window, 206 + `content-range`; past the end 416. A `Uint8Array`/`Blob` always (a `Blob` slices lazily); a `ReadableStream` only with `size`, else `accept-ranges: none` and the whole body |
+| Rows | `.live()`, `.page()`, `.as()`, `sourceFor`, `explain`, an MCP tool: `X_QUERY_DOWNLOAD_ONLY`. `describeSql` lists it with `sql: null` |
+| Audit | `audit: true` records the MINT — the decision of who may read what. A serve, and every `Range:` a player sends, is not a second read |
+| Manifest / OpenAPI | `download: true` on the `QueryFact` (rows ↔ download is breaking); one GET with `_token`, `200` as JSON or `application/octet-stream`, `206`, `410`, `416` |
+
+**A sealed object is buffered.** WebCrypto's AES-GCM opens a whole envelope or nothing, so a
+sealed recording is read with `get()` (bounded by the disk's `maxGetBytes`) and opened before a
+byte is served; ranges are then sliced from the plaintext. A PLAIN object can be a `Bun.file`
+or a stream with `size`, served without buffering.
+
 ## Errors
 
 | Code | When | Fix |
 |---|---|---|
 | `X_QUERY_AUDIT_SINK_MISSING` | `audit: true` and no audit sink installed — refused before the parse | `setAuditSink(sink)` from `@ultimat3/core` at boot |
 | `X_QUERY_AUDIT_SINK_FAILED` | the sink refused the record of an allowed read; the rows were withheld | fix the sink, then retry the read |
+| `X_QUERY_DOWNLOAD_INVALID` | `download:` beside a rows option, a `handle` that is not a function, `expiresInMs` outside 1 000 … 3 600 000 | declare `download: { handle }` alone |
+| `X_QUERY_DOWNLOAD_ONLY` | rows asked of a download (`.live()`, `.page()`, `.as()`, `sourceFor`) | `await q.url(input)`, or `await q(input)` for the file |
+| `X_QUERY_DOWNLOAD_TOKEN_INVALID` | a `_token` forged, truncated, another query's, under a retired key, or bound to other input — 403 | mint again: `client.<name>.url(input)` |
+| `X_QUERY_DOWNLOAD_TOKEN_EXPIRED` | a genuine `_token` past `expiresAt` — 410 | mint again right before the request |
 | `X_QUERY_DUPLICATE` | two queries under one name | rename one export |
 | `X_QUERY_DEPRECATION_INVALID` | `deprecated:` with a `since`/`sunset` that is not a date | use an ISO-8601 instant |
 | `X_QUERY_POLICY_MISSING` | registration without `policy:` | add `policy: can('…')` |
@@ -700,6 +763,10 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `QueryAuditSinkMissingError` | `X_QUERY_AUDIT_SINK_MISSING` | `src/audit-errors.ts` |
 | `QueryDeniedError` | the policy denial's own code (`X_FORBIDDEN`, `X_UNAUTHENTICATED`, …), kept on `.denial` | `src/errors.ts` |
 | `QueryDeprecationInvalidError` | `X_QUERY_DEPRECATION_INVALID` | `src/errors.ts` |
+| `QueryDownloadInvalidError` | `X_QUERY_DOWNLOAD_INVALID` | `src/download-errors.ts` |
+| `QueryDownloadOnlyError` | `X_QUERY_DOWNLOAD_ONLY` | `src/download-errors.ts` |
+| `QueryDownloadTokenExpiredError` | `X_QUERY_DOWNLOAD_TOKEN_EXPIRED` | `src/download-errors.ts` |
+| `QueryDownloadTokenInvalidError` | `X_QUERY_DOWNLOAD_TOKEN_INVALID` | `src/download-errors.ts` |
 | `QueryDuplicateError` | `X_QUERY_DUPLICATE` | `src/errors.ts` |
 | `QueryForeignError` | `X_QUERY_FOREIGN` | `src/errors.ts` |
 | `QueryInputInvalidError` | `X_INPUT_INVALID` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/query",
-  "version": "29.3.2",
+  "version": "29.4.0",
   "description": "The query primitive: a policy-checked read, optionally live, with cursor pagination and an incremental matcher",
   "license": "MIT",
   "type": "module",
@@ -37,11 +37,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "29.3.2",
-    "@ultimat3/core": "29.3.2",
-    "@ultimat3/entity": "29.3.2",
-    "@ultimat3/http": "29.3.2",
-    "@ultimat3/policy": "29.3.2",
-    "@ultimat3/schema": "29.3.2"
+    "@ultimat3/cache": "29.4.0",
+    "@ultimat3/core": "29.4.0",
+    "@ultimat3/entity": "29.4.0",
+    "@ultimat3/http": "29.4.0",
+    "@ultimat3/policy": "29.4.0",
+    "@ultimat3/schema": "29.4.0"
   }
 }

package/src/client.ts

@@ -18,12 +18,13 @@
 
 import type { ClientFlight, ClientRetry } from '@ultimat3/core';
 import type { FetchLike, RecordEnvelope } from '@ultimat3/core/page';
-import { clientTransport, isJsonObject, queryPath } from '@ultimat3/core/page';
+import { clientTransport, queryPath } from '@ultimat3/core/page';
 import type { InferInput, StandardSchemaV1 } from '@ultimat3/schema';
+import type { DownloadClientMethod, DownloadQuery } from './download';
 import type { PageControls } from './page-controls';
-import { PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-keys';
 import type { Page } from './pagination';
 import type { Query } from './query';
+import { searchOf } from './search-string';
 
 /** Core's, re-exported under the name this package always exported it by — one declaration. */
 export type { FetchLike } from '@ultimat3/core/page';
@@ -78,6 +79,15 @@ export interface QueryClientMethod<TInput extends StandardSchemaV1, TRow extends
   ): Promise<Page<TRow>>;
 }
 
+/**
+ * A download query's signed URL, as `url()` answers it. `url` is a PATH on the server and absolute
+ * from a client with a `baseUrl`; `expiresAt` is an ISO instant — mint again past it.
+ */
+export interface DownloadUrl {
+  readonly url: string;
+  readonly expiresAt: string;
+}
+
 /**
  * A `single: true` read's method: the route answers the row itself, or 404 `X_NOT_FOUND` — which
  * the transport rejects with, as it does every problem document. No `page`: the route refuses the
@@ -112,13 +122,11 @@ export type QueryMap = Record<string, QueryLike>;
 
 /** `queries.publicPost({ slug })`, with the input schema and the row type both inferred. */
 export type QueryClient<TQueries extends QueryMap> = {
-  readonly [K in keyof TQueries]: TQueries[K] extends Query<
-    infer TInput,
-    infer TRow,
-    infer TSingle extends boolean
-  >
-    ? QueryClientMethodOf<TInput, TRow, TSingle>
-    : never;
+  readonly [K in keyof TQueries]: TQueries[K] extends DownloadQuery<infer TInput>
+    ? DownloadClientMethod<TInput>
+    : TQueries[K] extends Query<infer TInput, infer TRow, infer TSingle extends boolean>
+      ? QueryClientMethodOf<TInput, TRow, TSingle>
+      : never;
 };
 
 /**
@@ -152,11 +160,33 @@ export function queryClient<TQueries extends QueryMap>(
   return proxy as QueryClient<TQueries>;
 }
 
-/** One query's method — what `query.client()` returns, and what `queryClient` proxies to. */
+/**
+ * One query's method — what `query.client()` returns, and what `queryClient` proxies to. It
+ * carries `url` too, the download half; the declaration's TYPE decides which half a caller sees.
+ */
 export function queryClientMethodFor<TInput extends StandardSchemaV1, TRow extends object>(
   name: string,
   options: QueryClientOptions,
 ): QueryClientMethod<TInput, TRow> {
+  return methodsOf<TInput, TRow>(name, options);
+}
+
+/**
+ * A download query's client half: `url(input)` asks the server to mint. A GET with no `_token` IS
+ * the mint, so the request is the plain read's and only the answer — `{ url, expiresAt }` — differs.
+ */
+export function downloadClientFor<TInput extends StandardSchemaV1>(
+  name: string,
+  options: QueryClientOptions,
+): DownloadClientMethod<TInput> {
+  return { url: methodsOf<TInput, object>(name, options).url };
+}
+
+/** The rows call, `page` and `url` over one base — `url` typed only on a download's method. */
+function methodsOf<TInput extends StandardSchemaV1, TRow extends object>(
+  name: string,
+  options: QueryClientOptions,
+) {
   const base = options.baseUrl.replace(/\/+$/, '');
   // Erased at the wire seam; the row type is this query's by construction.
   const rows = (input: InferInput<TInput>, callOptions: QueryCallOptions = {}) =>
@@ -166,7 +196,14 @@ export function queryClientMethodFor<TInput extends StandardSchemaV1, TRow exten
     args: PageControls,
     callOptions: QueryCallOptions = {},
   ) => read(base, options, name, input, callOptions, args) as Promise<Page<TRow>>;
-  return Object.assign(rows, { page });
+  const url = async (
+    input: InferInput<TInput>,
+    callOptions: QueryCallOptions = {},
+  ): Promise<DownloadUrl> => {
+    const minted = (await read(base, options, name, input, callOptions)) as DownloadUrl;
+    return { ...minted, url: base + minted.url };
+  };
+  return Object.assign(rows, { page, url });
 }
 
 /**
@@ -199,43 +236,3 @@ function read(
     ...(options.fetch === undefined ? {} : { fetchImpl: options.fetch }),
   });
 }
-
-/**
- * Input as a query string. Keys are sorted so the same input always produces the
- * same URL — a GET is a cache key, and an unstable one caches nothing.
- *
- * The page controls come LAST, after the sorted input and in a fixed order, so a paged URL is the
- * plain URL with a suffix — the same dedup key for the same page, and a log line a reader can
- * split at `_first=` to recover the read underneath.
- *
- * An EMPTY array sends nothing, and the route reads a required array nobody sent as `[]`
- * (`absentArraysOf`, `input-shape.ts`) — the two halves of one rule, so `{ tags: [] }` arrives.
- */
-function searchOf(input: unknown, page?: PageControls): string {
-  const params = new URLSearchParams();
-  if (isJsonObject(input)) {
-    for (const key of Object.keys(input).sort()) {
-      const value = input[key];
-      if (value === undefined || value === null) continue;
-      for (const item of Array.isArray(value) ? (value as readonly unknown[]) : [value]) {
-        params.append(key, wireText(item));
-      }
-    }
-  }
-  if (page !== undefined) {
-    params.append(PAGE_FIRST_KEY, String(page.first));
-    if (page.after !== undefined) params.append(PAGE_AFTER_KEY, page.after);
-  }
-  return params.toString();
-}
-
-/**
- * One value as the characters `coerceQuery` reads back. A `Date` is its ISO instant: through
- * `JSON.stringify` it arrived wrapped in quotes, which `t.date` refuses on the far side. An
- * Invalid Date has no instant, and `toISOString()` throws a bare `RangeError` on it, so it is sent
- * as the text it prints and the read's own schema says what is wrong with it.
- */
-function wireText(item: unknown): string {
-  if (item instanceof Date) return Number.isNaN(item.getTime()) ? String(item) : item.toISOString();
-  return typeof item === 'object' ? JSON.stringify(item) : String(item);
-}

package/src/download-errors.ts

@@ -0,0 +1,65 @@
+/**
+ * The four ways a download query is refused, in their own module for `audit-errors.ts`'s reason:
+ * the TITLES are registered in `errors.ts` with every code this package owns, and a read that
+ * declares no download never constructs one of these.
+ */
+
+import { UltimateError } from '@ultimat3/core';
+
+/** `query({ download })` written wrong — refused where it is declared, never on the first request. */
+export class QueryDownloadInvalidError extends UltimateError {
+  constructor(problem: string) {
+    super({
+      code: 'X_QUERY_DOWNLOAD_INVALID',
+      cause: `a download query cannot be built: ${problem}`,
+      fix: 'query({ input, policy, download: { expiresInMs: 300_000, handle: async ({ input, ctx }) => ({ body, contentType, filename }) } })   // no sql and no rows option beside download',
+      meta: { problem },
+    });
+  }
+}
+
+/**
+ * Rows asked of a query that answers a file. Every rows projection reaches `sql`, and a download
+ * stores one that throws this — so `.live()`, `.page()`, `.as()`, `sourceFor`, `explain` and an MCP
+ * tool are refused by ONE line rather than each remembering to check.
+ */
+export class QueryDownloadOnlyError extends UltimateError {
+  constructor(query: string) {
+    super({
+      code: 'X_QUERY_DOWNLOAD_ONLY',
+      cause: `"${query}" is a download query: it answers a file at a signed URL, and has no sql to read rows with`,
+      fix: 'await recording.url(input)   # a download query mints its signed URL; await recording(input) is the file in-process',
+      meta: { query },
+    });
+  }
+}
+
+/** Why a token was refused. Kept in `meta`, never on the wire beyond the code: 403 is the answer. */
+export type DownloadTokenProblem = 'malformed' | 'unauthenticated' | 'other-query' | 'other-input';
+
+/**
+ * A `_token` this app did not mint for THIS query and THIS input. One code for every reason, so a
+ * caller probing tokens learns nothing about which part of a forgery was wrong.
+ */
+export class QueryDownloadTokenInvalidError extends UltimateError {
+  constructor(query: string, problem: DownloadTokenProblem) {
+    super({
+      code: 'X_QUERY_DOWNLOAD_TOKEN_INVALID',
+      cause: `the download URL for "${query}" carries a token this app did not mint for it and this input`,
+      fix: `await queryClient<Api['queries']>({ baseUrl }).${query}.url(input)   # a fresh URL; request it unchanged`,
+      meta: { query, problem },
+    });
+  }
+}
+
+/** A genuine token past its expiry: the one refusal a fresh mint repairs, so it has its own code. */
+export class QueryDownloadTokenExpiredError extends UltimateError {
+  constructor(query: string, expiresAt: string) {
+    super({
+      code: 'X_QUERY_DOWNLOAD_TOKEN_EXPIRED',
+      cause: `the download URL for "${query}" expired at ${expiresAt}`,
+      fix: `await queryClient<Api['queries']>({ baseUrl }).${query}.url(input)   # right before the request; or raise download.expiresInMs (at most 3_600_000)`,
+      meta: { query, expiresAt },
+    });
+  }
+}

package/src/download-http.ts

@@ -0,0 +1,226 @@
+/**
+ * A download query's route — the same `GET /_x/query/<kebab>` every read answers on, so the typed
+ * client, `x routes`, the manifest and OpenAPI need no second URL rule. Without `_token` it MINTS
+ * (`{ url, expiresAt }`, the policy deciding as for any read); with one it SERVES the file: bytes,
+ * `content-disposition`, one `Range:` window, and `no-store` — the bytes are one actor's.
+ */
+
+import { assert, queryPath, useContext } from '@ultimat3/core';
+import type { RateLimitDecision, Route, RouteMeta, UltimateRequest } from '@ultimat3/http';
+import {
+  byteWindow,
+  contentRangeOf,
+  jsonResponse,
+  parseByteRange,
+  publishRateLimit,
+  RANGE_UNSATISFIABLE,
+  type RequestedRange,
+} from '@ultimat3/http';
+import { policyCapability } from '@ultimat3/policy';
+import { coerceQuery } from '@ultimat3/schema';
+import type { DownloadFile } from './download';
+import { mintDownloadUrl, serveDownloadFile } from './download';
+import { DOWNLOAD_GRANT_PARAM } from './download-token';
+import { QueryInputInvalidError } from './errors';
+import { rateLimitedByHandler } from './http';
+import { absentArraysOf } from './input-shape';
+import { pageControlsOf } from './page-controls';
+import type { AnyQuery } from './query';
+
+/** The route for `target`, whose `download` is declared. `sunsetting` is `toQueryRoute`'s. */
+export function toDownloadRoute(
+  target: AnyQuery,
+  name: string,
+  sunsetting: Readonly<Record<string, string>> | undefined,
+): Route {
+  const handler = async (request: UltimateRequest): Promise<Response> => {
+    if (sunsetting !== undefined) {
+      for (const [header, value] of Object.entries(sunsetting)) {
+        request.ctx.headers.set(header, value);
+      }
+    }
+    const { values, token } = tokenOf(name, request.queryRaw());
+    // A page of a file is not a thing: `_first`/`_after` are refused as on a single read.
+    const { input: rest, page } = pageControlsOf(name, values);
+    if (page !== undefined) {
+      throw new QueryInputInvalidError(name, 'a download answers one file — it takes no _first');
+    }
+    const input = absentArraysOf(target.input, coerceQuery(target.input, rest));
+    if (token === undefined) {
+      const minted = await mintDownloadUrl(target, input, {
+        surface: 'http',
+        clientAddress: request.ctx.ip,
+        onRateLimit: (decision: RateLimitDecision) =>
+          publishRateLimit(request.ctx, decision, useContext().now().getTime()),
+      });
+      return jsonResponse(minted);
+    }
+    const file = await serveDownloadFile(target, input, token, { surface: 'http' });
+    return fileResponse(file, request.header('range'));
+  };
+
+  const meta: RouteMeta = {
+    name,
+    // PUBLIC, and not unguarded: the mint runs this read's policy inside the handler like every
+    // read (`enforcedBy`), and a serve is authorized by the sealed token the policy minted — the
+    // reason a URL works in a `<video>` or a tab with no session header at all.
+    auth: 'public',
+    policy: policyCapability(target.policy),
+    enforcedBy: 'handler',
+    primitive: 'query',
+    // One actor's bytes under a URL that names no actor: nothing may keep a copy.
+    cache: { mode: 'no-store' },
+    tags: ['query', 'download'],
+    ...(target.rateLimit === undefined
+      ? {}
+      : { rateLimitedBy: rateLimitedByHandler(name, target.rateLimit) }),
+  };
+  return { method: 'GET', path: queryPath(name), handler, meta };
+}
+
+/** `_token` out of the search string — one string, or a refusal: two tokens are two grants. */
+function tokenOf(
+  name: string,
+  values: Readonly<Record<string, string | readonly string[] | undefined>>,
+): {
+  readonly values: Record<string, string | readonly string[] | undefined>;
+  readonly token: string | undefined;
+} {
+  const rest: Record<string, string | readonly string[] | undefined> = Object.create(null);
+  for (const [key, value] of Object.entries(values)) {
+    if (key !== DOWNLOAD_GRANT_PARAM) rest[key] = value;
+  }
+  const token = values[DOWNLOAD_GRANT_PARAM];
+  if (token === undefined || typeof token === 'string') return { values: rest, token };
+  throw new QueryInputInvalidError(name, `${DOWNLOAD_GRANT_PARAM} was sent ${token.length} times`);
+}
+
+/**
+ * A lone UTF-16 surrogate has no UTF-8 form, so `encodeURIComponent` throws a bare `URIError` on it.
+ * Spelled out because `String#isWellFormed` is ES2024 and the lib is ES2023 (core's cookie rule).
+ */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+
+/**
+ * What a served file may load: nothing from anywhere, but its own bytes as an image or a video —
+ * the tab a browser renders an image or a film in fetches that one URL. `sandbox` alone still let
+ * an inline HTML file fetch `<img src="https://elsewhere">` and carry this bearer URL in `Referer`.
+ */
+export const DOWNLOAD_CSP = "default-src 'none'; img-src 'self'; media-src 'self'; sandbox";
+
+/** A C0 control or DEL — what turns one header value into two. */
+const hasControl = (text: string): boolean =>
+  [...text].some((char) => char.charCodeAt(0) < 0x20 || char.charCodeAt(0) === 0x7f);
+
+/**
+ * The handler's answer, held to its type before a header is written: a `contentType` or a
+ * `filename` carrying a CR/LF would be a second header, and a body that is not bytes is a 500 the
+ * handler's author has to see named.
+ */
+function assertFile(file: DownloadFile): void {
+  const { body, contentType, filename, disposition, size } = file;
+  assert(
+    body instanceof Uint8Array || body instanceof Blob || body instanceof ReadableStream,
+    'a download handle() answered a body that is not a Uint8Array, a Blob or a ReadableStream',
+    "return { body: bytes, contentType: 'video/mp4', filename: 'run.mp4' }   // bytes, never a base64 string",
+  );
+  assert(
+    typeof contentType === 'string' && contentType !== '' && !hasControl(contentType),
+    'a download handle() answered a contentType that is empty, not a string, or carries a control character',
+    "return { body, contentType: 'video/mp4', filename }",
+  );
+  assert(
+    typeof filename === 'string' &&
+      filename !== '' &&
+      !hasControl(filename) &&
+      !LONE_SURROGATE.test(filename),
+    'a download handle() answered a filename that is empty, not a string, or carries a control character or a lone UTF-16 surrogate',
+    "return { body, contentType, filename: 'run.mp4' }",
+  );
+  assert(
+    disposition === undefined || disposition === 'attachment' || disposition === 'inline',
+    `a download handle() answered disposition ${String(disposition)}`,
+    "disposition: 'attachment' (the default) or 'inline'",
+  );
+  assert(
+    size === undefined || (Number.isSafeInteger(size) && size >= 0),
+    `a download handle() answered size ${String(size)}, which is not a whole number of bytes`,
+    'size: stream.byteLength   // the stream’s length in bytes, or omit it to serve it whole',
+  );
+}
+
+/**
+ * `attachment; filename="run_1.mp4"; filename*=UTF-8''run%E2%80%931.mp4` — the quoted name ASCII
+ * with every other character `_` (a quote or a backslash would end it), the starred one exact.
+ */
+export function contentDisposition(file: DownloadFile): string {
+  const ascii = file.filename.replace(/[^\u0020-\u007e]|["\\]/g, '_');
+  const exact = encodeURIComponent(file.filename).replace(
+    /['()*]/g,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+  return `${file.disposition ?? 'attachment'}; filename="${ascii}"; filename*=UTF-8''${exact}`;
+}
+
+/** The body's length when it can be known without reading it. */
+function sizeOf(file: DownloadFile): number | undefined {
+  if (file.body instanceof Uint8Array) return file.body.byteLength;
+  if (file.body instanceof Blob) return file.body.size;
+  return file.size;
+}
+
+/**
+ * A view `Response` accepts. A `Uint8Array` over a `SharedArrayBuffer` is not a body, so only that
+ * case is copied; every other view is re-wrapped over its own buffer, no byte moved.
+ */
+function bytesBody(bytes: Uint8Array): Uint8Array<ArrayBuffer> {
+  const { buffer } = bytes;
+  return buffer instanceof ArrayBuffer
+    ? new Uint8Array(buffer, bytes.byteOffset, bytes.byteLength)
+    : bytes.slice();
+}
+
+function bodyOf(file: DownloadFile, range?: RequestedRange): BodyInit {
+  const { body } = file;
+  if (body instanceof Uint8Array) {
+    const whole = bytesBody(body);
+    return range === undefined ? whole : whole.subarray(range.start, range.end + 1);
+  }
+  if (body instanceof Blob) {
+    return range === undefined ? body : body.slice(range.start, range.end + 1);
+  }
+  return range === undefined ? body : byteWindow(body, range);
+}
+
+/** Status, headers and body for one file and the request's `Range:`, if it named one we serve. */
+export function fileResponse(file: DownloadFile, rangeHeader: string | null): Response {
+  assertFile(file);
+  const headers = new Headers({
+    'content-type': file.contentType,
+    'content-disposition': contentDisposition(file),
+    'x-content-type-options': 'nosniff',
+    // Loads nothing but itself, in an opaque origin with no script — and names no URL on the way
+    // out: the one this file is served at is a bearer grant until it expires.
+    'content-security-policy': DOWNLOAD_CSP,
+    'referrer-policy': 'no-referrer',
+  });
+  const size = sizeOf(file);
+  if (size === undefined) {
+    headers.set('accept-ranges', 'none');
+    return new Response(bodyOf(file), { headers });
+  }
+  headers.set('accept-ranges', 'bytes');
+  const range = parseByteRange(rangeHeader, size);
+  if (range === RANGE_UNSATISFIABLE) {
+    if (file.body instanceof ReadableStream) void file.body.cancel().catch(() => undefined);
+    headers.set('content-range', `bytes */${String(size)}`);
+    return new Response(null, { status: 416, headers });
+  }
+  if (range === undefined) {
+    headers.set('content-length', String(size));
+    return new Response(bodyOf(file), { headers });
+  }
+  headers.set('content-range', contentRangeOf(range, size));
+  headers.set('content-length', String(range.end - range.start + 1));
+  return new Response(bodyOf(file, range), { status: 206, headers });
+}