@ultimat3/query 29.3.2 → 30.0.0

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,237 @@
+/**
+ * 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,
+  jsonResponse,
+  type ObjectRequest,
+  objectResponse,
+  publishRateLimit,
+  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(request, file);
+  };
+
+  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 ||
+      typeof body === 'function',
+    'a download handle() answered a body that is not a Uint8Array, a Blob, a ReadableStream or a function',
+    "return { body: bytes, contentType: 'video/mp4', filename: 'run.mp4' }   // bytes, never a base64 string",
+  );
+  assert(
+    typeof body !== 'function' || size !== undefined,
+    'a download handle() answered a function body with no size, so no Range: can be judged',
+    "return { body: (range) => open(range), size: object.size, contentType: 'video/mp4', filename: 'run.mp4' }",
+  );
+  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 | Promise<BodyInit> {
+  const { body } = file;
+  if (typeof body === 'function') return body(range);
+  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:`, by `objectResponse`'s rules.
+ * The headers are the file's own and stand in for its sandbox rule. A file of unknown size has no
+ * window to serve, so it answers whole; there is no etag on a file either, so no 304.
+ */
+export async function fileResponse(request: ObjectRequest, file: DownloadFile): Promise<Response> {
+  assertFile(file);
+  const own = {
+    '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) {
+    return new Response(await bodyOf(file), {
+      headers: { 'content-type': file.contentType, 'accept-ranges': 'none', ...own },
+    });
+  }
+  const response = await objectResponse(
+    request,
+    {
+      object: { contentType: file.contentType, size },
+      open: (range) => bodyOf(file, range),
+    },
+    { headers: own },
+  );
+  // Nothing opened it, and nothing else will read it: a stream the handler started is let go.
+  if (response.status === 416 && file.body instanceof ReadableStream) {
+    void file.body.cancel().catch(() => undefined);
+  }
+  return response;
+}

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');
+  }
+}