@ultimat3/query 29.3.2 → 29.4.0

package/src/download-token.ts

@@ -0,0 +1,216 @@
+/**
+ * A download's `_token`: who the policy admitted, for which query and input, until when — SEALED
+ * with core's `seal()` (AES-256-GCM under the master key, the query's name as the purpose).
+ * Sealed, not signed: it carries the minting actor, and the AEAD tag is the signature.
+ */
+
+import type { Actor, ActorInit, ActorKind } from '@ultimat3/core';
+import {
+  agentActor,
+  anonymousActor,
+  fingerprint,
+  isActorKind,
+  isJsonObject,
+  open,
+  SealInvalidError,
+  SealKeyUnknownError,
+  seal,
+  serviceActor,
+  userActor,
+} from '@ultimat3/core';
+import {
+  type DownloadTokenProblem,
+  QueryDownloadTokenExpiredError,
+  QueryDownloadTokenInvalidError,
+} from './download-errors';
+
+/** The search key the token rides under — `_`-prefixed like the page controls, so no input owns it. */
+export const DOWNLOAD_GRANT_PARAM = '_token';
+
+/** Bumped when the claims change shape: an old token is then refused, never misread. */
+const TOKEN_VERSION = 1;
+
+/**
+ * The minting actor, minus `facts`. Facts are app values resolved per request — often not JSON at
+ * all — so they are not carried: the policy decided WITH them at mint, and the handler runs under
+ * the actor's identity, tenancy and grants.
+ */
+interface ReplayActor {
+  readonly k: ActorKind;
+  readonly i: string;
+  readonly o?: string;
+  readonly r: readonly string[];
+  readonly s: readonly string[];
+  readonly p: readonly string[];
+  readonly b?: { readonly actorId: string; readonly actorKind: ActorKind };
+  readonly l?: string;
+  readonly z?: string;
+}
+
+interface Claims {
+  readonly v: number;
+  /** The query's name — also the seal's purpose, and checked again here. */
+  readonly q: string;
+  /** `fingerprint()` of the PARSED input: a URL whose input was edited no longer matches. */
+  readonly f: string;
+  /** Expiry, epoch milliseconds, on the context's clock. */
+  readonly e: number;
+  readonly a: ReplayActor;
+}
+
+const purposeOf = (query: string): string => `ultimate.query.download:${query}`;
+
+function replayOf(actor: Actor): ReplayActor {
+  return {
+    k: actor.kind,
+    i: actor.id,
+    ...(actor.orgId === undefined ? {} : { o: actor.orgId }),
+    r: actor.roles,
+    s: actor.scopes,
+    p: actor.permissions,
+    ...(actor.onBehalfOf === undefined ? {} : { b: actor.onBehalfOf }),
+    ...(actor.locale === undefined ? {} : { l: actor.locale }),
+    ...(actor.tz === undefined ? {} : { z: actor.tz }),
+  };
+}
+
+/** Seal the claims for one admitted call. `input` is the PARSED input the policy decided about. */
+export function mintDownloadToken(
+  query: string,
+  input: unknown,
+  actor: Actor,
+  expiresAtMs: number,
+): Promise<string> {
+  const claims: Claims = {
+    v: TOKEN_VERSION,
+    q: query,
+    f: fingerprint(input),
+    e: expiresAtMs,
+    a: replayOf(actor),
+  };
+  return seal(JSON.stringify(claims), { purpose: purposeOf(query) });
+}
+
+/** What an opened token grants: the actor to run as, and the input it was minted for. */
+export interface DownloadGrant {
+  readonly actor: Actor;
+  /** `fingerprint()` of the parsed input the policy admitted. */
+  readonly input: string;
+}
+
+/**
+ * The grant a token carries — or a refusal, in the order `@ultimat3/storage` checks a signed URL
+ * in: the seal (forged, truncated, another query's, a retired key) BEFORE the expiry, so an
+ * expired forgery is answered as a forgery. Opened BEFORE the input is parsed, so a holder of no
+ * genuine token learns nothing about the read's schema from an `X_INPUT_INVALID`.
+ */
+export async function openDownloadToken(
+  query: string,
+  token: string,
+  nowMs: number,
+): Promise<DownloadGrant> {
+  const claims = await claimsOf(query, token);
+  if (claims.e <= nowMs) {
+    throw new QueryDownloadTokenExpiredError(query, new Date(claims.e).toISOString());
+  }
+  return { actor: actorOf(query, claims.a), input: claims.f };
+}
+
+/** The URL's parsed input against the one the token was minted for: an edited URL is refused. */
+export function assertGrantedInput(query: string, grant: DownloadGrant, input: unknown): void {
+  if (grant.input !== fingerprint(input)) throw refused(query, 'other-input');
+}
+
+const refused = (query: string, problem: DownloadTokenProblem): QueryDownloadTokenInvalidError =>
+  new QueryDownloadTokenInvalidError(query, problem);
+
+async function claimsOf(query: string, token: string): Promise<Claims> {
+  let text: string;
+  try {
+    text = new TextDecoder().decode(await open(token, { purpose: purposeOf(query) }));
+  } catch (error) {
+    // A tag that does not verify, a string that is no sealed value, or a key this process no
+    // longer declares: every one is "not a token this app can honour". A MISSING master key is
+    // the server's fault, not the URL's, and keeps its own code (`X_SEAL_KEY_MISSING`, a 500).
+    if (error instanceof SealInvalidError || error instanceof SealKeyUnknownError) {
+      throw refused(query, error instanceof SealKeyUnknownError ? 'unauthenticated' : 'malformed');
+    }
+    throw error;
+  }
+  const claims = parseClaims(text);
+  if (claims === undefined) throw refused(query, 'malformed');
+  if (claims.q !== query) throw refused(query, 'other-query');
+  return claims;
+}
+
+const isStrings = (value: unknown): value is readonly string[] =>
+  Array.isArray(value) && value.every((item) => typeof item === 'string');
+
+/** The claims, or `undefined` for any shape this version did not write. Rebuilt, never cast. */
+function parseClaims(text: string): Claims | undefined {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  if (!isJsonObject(raw) || raw['v'] !== TOKEN_VERSION) return undefined;
+  const { q, f, e } = raw;
+  if (typeof q !== 'string' || typeof f !== 'string') return undefined;
+  if (typeof e !== 'number' || !Number.isSafeInteger(e)) return undefined;
+  const a = replayFrom(raw['a']);
+  return a === undefined ? undefined : { v: TOKEN_VERSION, q, f, e, a };
+}
+
+const optionalText = (value: unknown): value is string | undefined =>
+  value === undefined || typeof value === 'string';
+
+function replayFrom(a: unknown): ReplayActor | undefined {
+  if (!isJsonObject(a)) return undefined;
+  const { k, i, o, r, s, p, b, l, z } = a;
+  if (!isActorKind(k) || typeof i !== 'string') return undefined;
+  if (!isStrings(r) || !isStrings(s) || !isStrings(p)) return undefined;
+  if (!optionalText(o) || !optionalText(l) || !optionalText(z)) return undefined;
+  let behalf: ReplayActor['b'];
+  if (b !== undefined) {
+    if (!isJsonObject(b)) return undefined;
+    const { actorId, actorKind } = b;
+    if (typeof actorId !== 'string' || !isActorKind(actorKind)) return undefined;
+    behalf = { actorId, actorKind };
+  }
+  return {
+    k,
+    i,
+    r,
+    s,
+    p,
+    ...(o === undefined ? {} : { o }),
+    ...(behalf === undefined ? {} : { b: behalf }),
+    ...(l === undefined ? {} : { l }),
+    ...(z === undefined ? {} : { z }),
+  };
+}
+
+function actorOf(query: string, replay: ReplayActor): Actor {
+  if (replay.k === 'anonymous') return anonymousActor();
+  const init: ActorInit = {
+    id: replay.i,
+    orgId: replay.o,
+    roles: replay.r,
+    scopes: replay.s,
+    permissions: replay.p,
+    onBehalfOf: replay.b,
+    locale: replay.l,
+    tz: replay.z,
+  };
+  switch (replay.k) {
+    case 'user':
+      return userActor(init);
+    case 'service':
+      return serviceActor(init);
+    case 'agent':
+      return agentActor(init);
+    default:
+      throw refused(query, 'malformed');
+  }
+}

package/src/download.ts

@@ -0,0 +1,242 @@
+/**
+ * `query({ input, policy, download })` — a read whose answer is a FILE, served at a short-lived
+ * signed URL. Still a `query`: the same input parse, the same policy, the same declared limit, the
+ * same audit, one name in the registry and the manifest. Only the answer differs, so the rows
+ * projections (`live`, `page`, `as`, MCP, `explain`) are refused by the `sql` this file stores.
+ *
+ * Two calls make a download. `url(input)` runs the read's front half as the caller and seals a
+ * token naming the caller, the input and an expiry. `GET <url>` opens the token, re-parses the
+ * input from the URL and runs `handle` as the minting actor — the policy decided at mint, and the
+ * token is what it decided. That is what lets a `<video src>` or a link handed to someone without
+ * the session's headers fetch the bytes, and what keeps a URL from outliving `expiresInMs`.
+ */
+
+import type { Ctx, Deprecation } from '@ultimat3/core';
+import { queryPath, useContext } from '@ultimat3/core';
+import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import type { DownloadUrl, QueryCallOptions, QueryClientOptions } from './client';
+import { downloadClientFor } from './client';
+import { QueryDownloadInvalidError, QueryDownloadOnlyError } from './download-errors';
+import {
+  assertGrantedInput,
+  DOWNLOAD_GRANT_PARAM,
+  mintDownloadToken,
+  openDownloadToken,
+} from './download-token';
+import type { QueryPolicy } from './policy-gate';
+import type { AnyQuery, AnyQueryDef, QueryDescriptor, QueryOptions, QueryRateLimit } from './query';
+import { admittedCall, defOf, queryName, stashDef } from './read';
+import { searchOf } from './search-string';
+
+export type { DownloadUrl } from './client';
+
+/** How long a minted URL works when the declaration names nothing: long enough to start a player. */
+export const DEFAULT_DOWNLOAD_TTL_MS = 300_000;
+/** The floor and ceiling of `expiresInMs`. A URL is a bearer capability; an hour is the most. */
+export const MIN_DOWNLOAD_TTL_MS = 1_000;
+export const MAX_DOWNLOAD_TTL_MS = 3_600_000;
+
+/** The written reason the token's serve skips the policy — `admit`'s escape, never a boolean. */
+const TOKEN_IS_THE_GRANT =
+  'a download token is sealed only by url(), after this query admitted the minting actor; the token is that decision';
+
+/** What `handle` answers. Bytes, never a base64 string — that is the +33 % this exists to remove. */
+export interface DownloadFile {
+  /**
+   * A `Uint8Array` or a `Blob` (a `Bun.file`, a slice) is range-served from its own length; a
+   * `ReadableStream` is range-served only with `size`, else whole with `accept-ranges: none`.
+   */
+  readonly body: Uint8Array | Blob | ReadableStream<Uint8Array>;
+  readonly contentType: string;
+  /** The name a browser saves it under — `content-disposition`'s `filename` and `filename*`. */
+  readonly filename: string;
+  /** `attachment` (default) saves it; `inline` lets a tab render it. `<video>` ignores both. */
+  readonly disposition?: 'attachment' | 'inline' | undefined;
+  /** The stream's length in bytes. Ignored for a `Uint8Array` or a `Blob`, which know theirs. */
+  readonly size?: number | undefined;
+}
+
+export interface DownloadArgs<TInput extends StandardSchemaV1> {
+  readonly input: InferOutput<TInput>;
+  readonly ctx: Ctx;
+}
+
+export interface QueryDownload<TInput extends StandardSchemaV1> {
+  /** How long a minted URL works: 1 000 … 3 600 000 ms. Default `DEFAULT_DOWNLOAD_TTL_MS` (5 min). */
+  readonly expiresInMs?: number | undefined;
+  /**
+   * The file, for an input the policy already admitted. Runs as the actor that MINTED the URL;
+   * decrypt a sealed object here (`open()` from `@ultimat3/core`) — an AES-GCM envelope opens whole,
+   * so a sealed object is buffered, bounded by its disk's `maxGetBytes`.
+   */
+  handle(args: DownloadArgs<TInput>): Promise<DownloadFile>;
+}
+
+type RowsOnly = 'sql' | 'live' | 'single' | 'subscribes' | 'rows' | 'cache' | 'mcp';
+
+/** A download declares no rows option: each is a type error here and `X_QUERY_DOWNLOAD_INVALID` at runtime. */
+export type DownloadQueryDef<TInput extends StandardSchemaV1> = {
+  readonly input: TInput;
+  readonly policy: QueryPolicy;
+  readonly download: QueryDownload<TInput>;
+  /** Spent at MINT — one URL is one admitted read, however many `Range:` requests a player makes. */
+  readonly rateLimit?: QueryRateLimit;
+  readonly deprecated?: Deprecation;
+  /** Records the MINT: the decision of who may read what. A ranged GET is not a second read. */
+  readonly audit?: boolean;
+} & { readonly [K in RowsOnly]?: never };
+
+/** `client.recording.url(input)` — the browser half: the server mints, this prefixes the base. */
+export interface DownloadClientMethod<TInput extends StandardSchemaV1> {
+  url(input: InferInput<TInput>, options?: QueryCallOptions): Promise<DownloadUrl>;
+}
+
+export interface DownloadQuery<TInput extends StandardSchemaV1 = StandardSchemaV1>
+  extends AnyQuery {
+  /** The file, in-process: the same parse and policy as `url()`, then `handle` as this caller. */
+  (input: InferInput<TInput>, options?: QueryOptions): Promise<DownloadFile>;
+  readonly input: TInput;
+  readonly download: true;
+  /** Mint a signed URL — a PATH, `/_x/query/<kebab>?…&_token=…` — for this caller and this input. */
+  url(input: InferInput<TInput>, options?: QueryOptions): Promise<DownloadUrl>;
+  client(options: QueryClientOptions): DownloadClientMethod<TInput>;
+  named(name: string): DownloadQuery<TInput>;
+}
+
+const isFunction = (value: unknown): value is (...args: never[]) => unknown =>
+  typeof value === 'function';
+
+/** The declaration, judged where it is written: an untyped caller can still pass `sql` beside it. */
+export function assertDownloadDef(def: Readonly<Record<string, unknown>>): void {
+  const download = def['download'];
+  if (typeof download !== 'object' || download === null) {
+    throw new QueryDownloadInvalidError('download is not an object with a handle');
+  }
+  const rows = (['sql', 'live', 'single', 'subscribes', 'rows', 'cache', 'mcp'] as const).filter(
+    (key) => def[key] !== undefined,
+  );
+  if (rows.length > 0) {
+    throw new QueryDownloadInvalidError(`it also declares ${rows.join(', ')}, which answer rows`);
+  }
+  if (!isFunction(Reflect.get(download, 'handle'))) {
+    throw new QueryDownloadInvalidError('download.handle is not a function');
+  }
+  const ttl: unknown = Reflect.get(download, 'expiresInMs');
+  const whole = typeof ttl === 'number' && Number.isSafeInteger(ttl);
+  if (ttl !== undefined && !(whole && ttl >= MIN_DOWNLOAD_TTL_MS && ttl <= MAX_DOWNLOAD_TTL_MS)) {
+    throw new QueryDownloadInvalidError(
+      `download.expiresInMs is ${String(ttl)}, not a whole number of ms from ${MIN_DOWNLOAD_TTL_MS} to ${MAX_DOWNLOAD_TTL_MS}`,
+    );
+  }
+}
+
+/** `describe` is handed in, so this file never value-imports `query.ts` (which imports it). */
+export function buildDownloadQuery<TInput extends StandardSchemaV1>(
+  def: DownloadQueryDef<TInput>,
+  name: string,
+  describe: (target: AnyQuery) => QueryDescriptor,
+): DownloadQuery<TInput> {
+  const refuse = (): Promise<never> => Promise.reject(new QueryDownloadOnlyError(queryName(self)));
+  const callable = (input: InferInput<TInput>, options: QueryOptions = {}): Promise<DownloadFile> =>
+    readDownloadFile(self, input, options);
+  const self: DownloadQuery<TInput> = Object.assign(callable, {
+    kind: 'query' as const,
+    isLive: false,
+    download: true as const,
+    input: def.input,
+    policy: def.policy,
+    ...(def.rateLimit === undefined ? {} : { rateLimit: def.rateLimit }),
+    ...(def.deprecated === undefined ? {} : { deprecated: def.deprecated }),
+    describe: (): QueryDescriptor => describe(self),
+    named: (next: string): DownloadQuery<TInput> => buildDownloadQuery(def, next, describe),
+    as: refuse,
+    page: refuse,
+    live: refuse,
+    url: (input: InferInput<TInput>, options: QueryOptions = {}) =>
+      mintDownloadUrl(self, input, options),
+    client: (options: QueryClientOptions): DownloadClientMethod<TInput> => ({
+      url: downloadClientFor<TInput>(queryName(self), options).url,
+    }),
+  });
+  Object.defineProperty(self, 'name', { value: name, configurable: true });
+  const stored: AnyQueryDef = {
+    input: def.input,
+    policy: def.policy,
+    ...(def.rateLimit === undefined ? {} : { rateLimit: def.rateLimit }),
+    ...(def.deprecated === undefined ? {} : { deprecated: def.deprecated }),
+    ...(def.audit === undefined ? {} : { audit: def.audit }),
+    download: def.download,
+    // Every rows projection ends here — one refusal, wherever the rows were asked from.
+    sql: () => {
+      throw new QueryDownloadOnlyError(queryName(self));
+    },
+  };
+  stashDef(self, stored);
+  return self;
+}
+
+function handlerOf(target: AnyQuery): QueryDownload<StandardSchemaV1> {
+  const download = defOf(target).download;
+  if (download === undefined) throw new QueryDownloadOnlyError(queryName(target));
+  return download;
+}
+
+/** The in-process read: admitted as the caller, answered by `handle`. */
+export function readDownloadFile(
+  target: AnyQuery,
+  raw: unknown,
+  options: QueryOptions,
+): Promise<DownloadFile> {
+  const download = handlerOf(target);
+  return admittedCall(target, raw, options, (input, ctx) => download.handle({ input, ctx }));
+}
+
+/**
+ * Admit the caller exactly as a read would, then seal the decision. The URL carries the input as
+ * it was HANDED in (the route re-parses it to the same value) and the token binds the PARSED one.
+ */
+export function mintDownloadUrl(
+  target: AnyQuery,
+  raw: unknown,
+  options: QueryOptions,
+): Promise<DownloadUrl> {
+  const name = queryName(target);
+  const ttl = handlerOf(target).expiresInMs ?? DEFAULT_DOWNLOAD_TTL_MS;
+  return admittedCall(target, raw, options, async (input, ctx) => {
+    const expiresAtMs = ctx.now().getTime() + ttl;
+    const token = await mintDownloadToken(name, input, ctx.actor, expiresAtMs);
+    const search = searchOf(raw);
+    const tokenParam = `${DOWNLOAD_GRANT_PARAM}=${encodeURIComponent(token)}`;
+    return {
+      url: `${queryPath(name)}?${search === '' ? '' : `${search}&`}${tokenParam}`,
+      expiresAt: new Date(expiresAtMs).toISOString(),
+    };
+  });
+}
+
+/**
+ * The file a token grants: the token opened against THIS query and THIS input on the context's
+ * clock, then `handle` as the minting actor. The input is still parsed — `handle` is owed the
+ * schema's output — and the policy is not re-run: it ran at mint, with facts this token cannot
+ * carry, and the written reason above is what `admit` logs for the skip.
+ */
+export async function serveDownloadFile(
+  target: AnyQuery,
+  raw: unknown,
+  token: string,
+  options: QueryOptions,
+): Promise<DownloadFile> {
+  const name = queryName(target);
+  const download = handlerOf(target);
+  const now = (options.ctx ?? useContext()).now().getTime();
+  const grant = await openDownloadToken(name, token, now);
+  return admittedCall(
+    target,
+    raw,
+    { ...options, actor: grant.actor, unenforced: TOKEN_IS_THE_GRANT },
+    (input, ctx) => {
+      assertGrantedInput(name, grant, input);
+      return download.handle({ input, ctx });
+    },
+  );
+}

package/src/errors.ts

@@ -31,6 +31,10 @@ const OWNED_TITLES: Readonly<Record<string, string>> = {
   X_QUERY_AUDIT_SINK_MISSING: 'a query declares audit: true and no audit sink is installed',
   X_QUERY_AUDIT_SINK_FAILED:
     'an audited read was refused because the audit sink rejected its record',
+  X_QUERY_DOWNLOAD_INVALID: 'a query declares a download it cannot serve',
+  X_QUERY_DOWNLOAD_ONLY: 'rows were asked of a query that answers a file',
+  X_QUERY_DOWNLOAD_TOKEN_INVALID: 'a download URL carries a token this app did not mint for it',
+  X_QUERY_DOWNLOAD_TOKEN_EXPIRED: 'a download URL is past its expiry',
 };
 
 /**

package/src/http.ts

@@ -12,6 +12,7 @@ import type { RateLimitDecision, Route, RouteMeta, UltimateRequest } from '@ulti
 import { publishRateLimit, toBucket } from '@ultimat3/http';
 import { admitsAnonymous, policyCapability } from '@ultimat3/policy';
 import { coerceQuery } from '@ultimat3/schema';
+import { toDownloadRoute } from './download-http';
 import { QueryDeprecationInvalidError, QueryInputInvalidError } from './errors';
 import { absentArraysOf } from './input-shape';
 import { PAGE_FIRST_KEY, pageControlsOf } from './page-controls';
@@ -30,6 +31,7 @@ export function toQueryRoute(target: AnyQuery): Route {
   // Rendered ONCE, at projection: a date that cannot become a header is a mount-time refusal,
   // not a surprise on the first read.
   const sunsetting = deprecationHeadersFor(name, target.deprecated);
+  if (target.download === true) return toDownloadRoute(target, name, sunsetting);
   const answer = recordAnswerFor(target.rows);
   const answerRow = recordRowAnswerFor(target.rows);
 
@@ -137,7 +139,7 @@ export function toQueryRoute(target: AnyQuery): Route {
 }
 
 /** Validates the declaration through the limiter's own conversion, then hands the route its flag. */
-function rateLimitedByHandler(name: string, limit: QueryRateLimit): 'handler' {
+export function rateLimitedByHandler(name: string, limit: QueryRateLimit): 'handler' {
   toBucket(name, limit);
   return 'handler';
 }

package/src/index.ts

@@ -47,6 +47,7 @@ export {
   requestMemo,
 } from './cache';
 export type {
+  DownloadUrl,
   FetchLike,
   QueryCallOptions,
   QueryClient,
@@ -58,7 +59,7 @@ export type {
   QuerySingleClientMethod,
 } from './client';
 /** `queryClient` is the map-wide read client; `queryClientMethodFor` is what `.client()` binds. */
-export { queryClient, queryClientMethodFor } from './client';
+export { downloadClientFor, queryClient, queryClientMethodFor } from './client';
 /**
  * `isNull` is the one definition of SQL NULL a custom `SqlSource` has to agree with, and
  * `totalOrder` is the one definition of the order it must serve a page in. `compareRows`,
@@ -67,6 +68,30 @@ export { queryClient, queryClientMethodFor } from './client';
  */
 export type { KindOf } from './column-kinds';
 export { kindsOf } from './column-kinds';
+/**
+ * `query({ download })` — a read answered by a FILE at a short-lived signed URL. Still a `query`:
+ * one policy, one name, one route (`GET /_x/query/<kebab>`: mint without `_token`, serve with it).
+ */
+export type {
+  DownloadArgs,
+  DownloadClientMethod,
+  DownloadFile,
+  DownloadQuery,
+  DownloadQueryDef,
+  QueryDownload,
+} from './download';
+export {
+  DEFAULT_DOWNLOAD_TTL_MS,
+  MAX_DOWNLOAD_TTL_MS,
+  MIN_DOWNLOAD_TTL_MS,
+} from './download';
+export type { DownloadTokenProblem } from './download-errors';
+export {
+  QueryDownloadInvalidError,
+  QueryDownloadOnlyError,
+  QueryDownloadTokenExpiredError,
+  QueryDownloadTokenInvalidError,
+} from './download-errors';
 export {
   CursorValueUnsupportedError,
   MatcherUnsupportedError,

package/src/input-shape.ts

@@ -16,6 +16,7 @@
 // input cannot be written.
 
 import { type SchemaNode, tryIntrospect } from '@ultimat3/schema';
+import { DOWNLOAD_GRANT_PARAM } from './download-token';
 import { QueryInputUnencodableError } from './errors';
 import { PAGE_CONTROL_KEYS } from './page-controls';
 
@@ -34,6 +35,9 @@ function unencodable(node: SchemaNode): string | undefined {
     if (PAGE_CONTROL_KEYS.includes(key)) {
       return `${key} is reserved — the route reads it as a page control (see query.page())`;
     }
+    if (key === DOWNLOAD_GRANT_PARAM) {
+      return `${key} is reserved — a download's route reads it as the signed token (see query.url())`;
+    }
     // Required AND nullable: `searchOf` sends nothing for a `null`, and absence is what the far
     // side then sees — so the value the caller explicitly chose fails validation on arrival.
     // Optional or defaulted, absence is already the schema's own answer and nothing is lost.

package/src/openapi.ts

@@ -26,6 +26,7 @@ import { MAX_PAGE_SIZE } from '@ultimat3/entity';
 import { policyCapability } from '@ultimat3/policy';
 import type { SchemaNode } from '@ultimat3/schema';
 import { nodeToJsonSchema, tryIntrospect } from '@ultimat3/schema';
+import { DOWNLOAD_GRANT_PARAM } from './download-token';
 import { PAGE_AFTER_KEY, PAGE_FIRST_KEY } from './page-controls';
 import type { AnyQuery } from './query';
 import { queryName } from './read';
@@ -90,6 +91,7 @@ export function queryOpenApiPaths(
  */
 export function toQueryOpenApiOperation(target: AnyQuery): Record<string, unknown> {
   const name = queryName(target);
+  if (target.download === true) return downloadOperation(target, name);
   if (target.single === true) return singleOperation(target, name);
   return {
     operationId: name,
@@ -168,6 +170,68 @@ function singleOperation(target: AnyQuery, name: string): Record<string, unknown
   };
 }
 
+/**
+ * A download: one URL, two answers decided by `_token` — the mint (`{ url, expiresAt }`, JSON) and
+ * the file (bytes, a `Range:` window as 206). No page controls, no rows, no MCP tool.
+ */
+function downloadOperation(target: AnyQuery, name: string): Record<string, unknown> {
+  return {
+    operationId: name,
+    tags: [QUERY_TAG],
+    summary: name,
+    ...(target.deprecated === undefined ? {} : { deprecated: true }),
+    parameters: [
+      ...inputParameters(target.input),
+      {
+        name: DOWNLOAD_GRANT_PARAM,
+        in: 'query',
+        required: false,
+        description: 'absent: mint a signed URL for this input; present: the file that URL grants',
+        schema: { type: 'string' },
+      },
+    ],
+    responses: {
+      '200': {
+        description: `without ${DOWNLOAD_GRANT_PARAM}, the minted URL; with it, the file`,
+        content: {
+          'application/json': { schema: MINTED_URL },
+          // The file's own type — whatever `handle` answered — so any media type, as bytes.
+          '*/*': { schema: FILE_BYTES },
+        },
+      },
+      '206': {
+        description: 'the one byte range the Range header named, with content-range',
+        content: { '*/*': { schema: FILE_BYTES } },
+      },
+      '400': problemResponse('X_INPUT_INVALID'),
+      '401': problemResponse(
+        'X_UNAUTHENTICATED — a mint with no session, under a policy that needs one',
+      ),
+      '403': problemResponse('policy denied, or X_QUERY_DOWNLOAD_TOKEN_INVALID'),
+      '410': problemResponse('X_QUERY_DOWNLOAD_TOKEN_EXPIRED — mint again'),
+      '416': { description: 'the Range header starts past the end of the file' },
+    },
+    'x-ultimate': {
+      capability: policyCapability(target.policy),
+      live: false,
+      download: true,
+      cacheTags: [],
+      tool: null,
+    },
+  };
+}
+
+const FILE_BYTES: Readonly<Record<string, unknown>> = { type: 'string', format: 'binary' };
+
+const MINTED_URL: Readonly<Record<string, unknown>> = {
+  type: 'object',
+  required: ['url', 'expiresAt'],
+  properties: {
+    url: { type: 'string', description: `this path, with the input and ${DOWNLOAD_GRANT_PARAM}` },
+    expiresAt: { type: 'string', format: 'date-time' },
+  },
+};
+
 /** One row. Its members are not published — a query declares no output schema, as `ANSWERS` says. */
 const SINGLE_ANSWER: Readonly<Record<string, unknown>> = { type: 'object' };