@ultimat3/http 29.4.0 → 30.0.0

package/src/pipeline.ts

@@ -93,7 +93,12 @@ export const PIPELINE_STAGES: readonly StageDoc[] = [
   {
     name: 'response',
     phase: 'finalize',
-    why: 'last: a redirect answered to a client-router request becomes 204 + x-ultimate-location (the router follows it once, never fetch), then CORS, security headers, server-timing and the accumulated context headers are merged onto whatever the stages produced',
+    why: 'after every stage that decides a header: a redirect answered to a client-router request becomes 204 + x-ultimate-location (the router follows it once, never fetch), then CORS, security headers, server-timing and the accumulated context headers are merged onto whatever the stages produced',
+  },
+  {
+    name: 'compress',
+    phase: 'finalize',
+    why: 'last: it reads the final cache-control, so a private answer can never be coded (BREACH), and rebuilds the response with every header already on it. Only a public text answer with a declared length is ever read, so no other response pays for this stage',
   },
 ];
 

package/src/preferences.ts

@@ -31,7 +31,11 @@ export function resolvePreferences(
   });
   ctx.tz = resolveTimeZone({
     cookie: readCookie(cookies, config.tz.cookie),
+    // Documented as a source (`?tz=` for share links) and never read until 2026-11, as `?locale=`.
+    query: ctx.url.searchParams.get('tz'),
     header: request.header(config.tz.header),
+    // A document navigation sends no header: this is the browser's zone on a first `app/` page.
+    detected: readCookie(cookies, config.tz.detectedCookie),
     user: ctx.actor.tz ?? null,
   }).zone;
   ctx.headers.set('content-language', ctx.locale);

package/src/problem-meta-framework.ts

@@ -0,0 +1,21 @@
+// The FRAMEWORK's half of `problem-meta.ts`: per framework code, the `meta` keys its problem
+// document carries. A framework code's `meta` is operator-only by default (`problem-meta.ts`'s
+// header names what lives there), and `registerProblemMeta` refuses every framework code — so
+// without this table a refusal whose meta IS the caller's instruction never reached the caller.
+//
+// One reviewed table, never a per-class or per-instance option: an option on the error would let
+// any throw site publish any key, and the rule is that a key crosses only where a reviewer wrote
+// it here. `problem-meta-framework.test.ts` holds every row to the rules: a framework code, a 4xx,
+// a key an app's own declaration could carry, and no secret-shaped name.
+
+/**
+ * Code → the `meta` keys its document carries. A `Map`, read by own key (`APP_ERROR_STATUS`'s
+ * reason). A new row names the key's producer, so a rename there fails that package's test.
+ */
+export const FRAMEWORK_PROBLEM_META: ReadonlyMap<string, readonly string[]> = new Map([
+  // `@ultimat3/action`'s `MeterExceededError`: which allowance, its size, and when it resets — so a
+  // client can say "100 drafts a day, again at midnight UTC" without parsing `cause`. NOT
+  // `retryAfterSeconds` (already the `Retry-After` header) and not the counter's subject, which
+  // names a tenant (`meter-problem.test.ts` pins the producer's keys).
+  ['X_METER_EXCEEDED', Object.freeze(['meter', 'limit', 'resetsAt'])],
+]);

package/src/problem-meta.ts

@@ -15,9 +15,10 @@
 // The public-cause predicate and both of its tables are `@ultimat3/core`'s (`public-cause.ts`): the
 // MCP error data and the agent `tool_result` ask the question this package's problem document
 // does. This file only WRITES the app half — a reader imports `hasPublicCause` from core.
-import { registerPublicCause, resetPublicCauses } from '@ultimat3/core';
+import { registerPublicCause, renderCauseValue, resetPublicCauses } from '@ultimat3/core';
 import { ERROR_STATUS } from './error-map';
 import { problemMetaInvalid } from './errors';
+import { FRAMEWORK_PROBLEM_META } from './problem-meta-framework';
 
 /** What a problem document's `meta` member holds — JSON, and nothing JSON cannot carry. */
 export type ProblemMetaValue =
@@ -48,6 +49,18 @@ export const MAX_PROBLEM_META_BYTES = 4096;
 const KEY = /^[A-Za-z_$][\w$]*$/;
 const RESERVED_KEYS: ReadonlySet<string> = new Set(['issues', '__proto__']);
 
+/**
+ * Why `key` may not ride a document, or `undefined` when it may. The one rule for both halves: an
+ * app's `registerProblemMeta` throws on it, and the framework's table is held to it by a test.
+ */
+export function metaKeyRefusal(key: unknown): string | undefined {
+  if (typeof key !== 'string' || !KEY.test(key))
+    return `${renderCauseValue(key)} is not a meta key`;
+  if (key === 'issues') return '`issues` already rides at the top level of the document';
+  if (RESERVED_KEYS.has(key)) return `\`${key}\` is not a key a document may carry`;
+  return undefined;
+}
+
 /** Per app-owned code, the `meta` keys its documents carry. A `Map`, for `APP_ERROR_STATUS`'s reason. */
 const DECLARED = new Map<string, readonly string[]>();
 
@@ -73,7 +86,8 @@ const sameKeys = (left: readonly string[], right: readonly string[]): boolean =>
  *
  * Framework-owned codes are refused, exactly as `registerErrorStatus` refuses them: their `meta`
  * is where the framework keeps what a caller must not be handed, and an app that could declare
- * `X_RATE_LIMITED: ['key']` would publish the limiter's internal key on every 429.
+ * `X_RATE_LIMITED: ['key']` would publish the limiter's internal key on every 429. The framework's
+ * own public keys are `problem-meta-framework.ts`'s one reviewed table, never an app's call.
  */
 export const registerProblemMeta = (
   declarations: Readonly<Record<string, ProblemMetaDeclaration>>,
@@ -95,17 +109,8 @@ export const registerProblemMeta = (
       throw problemMetaInvalid(code, 'the key list is empty — omit the code instead');
     }
     for (const key of keys) {
-      if (typeof key !== 'string' || !KEY.test(key)) {
-        throw problemMetaInvalid(code, `${JSON.stringify(key)} is not a meta key`);
-      }
-      if (RESERVED_KEYS.has(key)) {
-        throw problemMetaInvalid(
-          code,
-          key === 'issues'
-            ? '`issues` already rides at the top level of the document'
-            : `\`${key}\` is not a key a document may carry`,
-        );
-      }
+      const refusal = metaKeyRefusal(key);
+      if (refusal !== undefined) throw problemMetaInvalid(code, refusal);
     }
     const existing = DECLARED.get(code);
     if (existing !== undefined && !sameKeys(existing, keys)) {
@@ -122,9 +127,12 @@ export const resetProblemMeta = (): void => {
   resetPublicCauses();
 };
 
-/** The keys declared for a code, or `undefined` when nothing was — which is every framework code. */
+/**
+ * The keys declared for a code, or `undefined` when nothing was: the framework's reviewed rows
+ * (`problem-meta-framework.ts`) first, then the app's. Every other framework code answers nothing.
+ */
 export const problemMetaKeysFor = (code: string): readonly string[] | undefined =>
-  DECLARED.get(code);
+  FRAMEWORK_PROBLEM_META.get(code) ?? DECLARED.get(code);
 
 /**
  * A code this package's table maps is the framework's. A `Set` of the table's own keys, for the

package/src/rate-limit-degrade.ts

@@ -22,8 +22,16 @@ import { isUltimateError, logger } from '@ultimat3/core';
 import type { RateLimitStore } from './rate-limit';
 import { memoryRateLimitStore } from './rate-limit';
 
-/** Codes `@ultimat3/db` raises when no connection could run the statement at all. */
-const UNREACHABLE_CODES: ReadonlySet<string> = new Set(['X_DB_UNAVAILABLE', 'X_DB_POOL_EXHAUSTED']);
+/**
+ * Codes `@ultimat3/db` raises when no connection could run the statement at all, and the store's
+ * own deadline (`rate-limit-store-deadline.ts`): a database that has not answered in time is one
+ * this decision cannot wait for.
+ */
+const UNREACHABLE_CODES: ReadonlySet<string> = new Set([
+  'X_DB_UNAVAILABLE',
+  'X_DB_POOL_EXHAUSTED',
+  'X_RATE_LIMIT_STORE_TIMEOUT',
+]);
 
 /**
  * SQLSTATEs that mean "this connection, right now", carried on `meta.sqlState` of an

package/src/rate-limit-postgres.ts

@@ -3,12 +3,13 @@
 // is a declaration nothing can satisfy while `docker/helm/values.yaml` runs `replicas: 3`.
 // Statements are spelled out so an agent can run the exact one it saw in a log.
 
-import type { PgExecutor } from '@ultimat3/core';
+import type { PgExecutor, Scheduler } from '@ultimat3/core';
 import type { RateLimitDecision, RateLimitScope, RateLimitStore } from './rate-limit';
 import { rateLimitDecision } from './rate-limit';
 import { degradedFallback, isRateLimitStoreUnreachable } from './rate-limit-degrade';
 import { rateLimitStoreUnavailable } from './rate-limit-errors';
 import { rateLimitPeek, refilledTokens } from './rate-limit-peek';
+import { storeDeadline } from './rate-limit-store-deadline';
 
 /**
  * Installed by the boot, not by an app migration — the same rule `SQL_IDEMPOTENCY_TABLE` follows,
@@ -124,6 +125,14 @@ interface TakeRow {
 
 export interface PostgresRateLimitStoreOptions {
   readonly executor: PgExecutor;
+  /**
+   * How long one `take` or `peek` may wait for the database before this decision degrades to the
+   * pod's memory. Default `RATE_LIMIT_STORE_DEADLINE_MS` (250), measured in
+   * `rate-limit-store-deadline.ts`. The pool's own bound is the app's work's; this one is the limiter's.
+   */
+  readonly deadlineMs?: number | undefined;
+  /** Injection seam for that deadline; production passes none. */
+  readonly schedule?: Scheduler | undefined;
 }
 
 export interface PostgresRateLimitStore extends RateLimitStore {
@@ -165,6 +174,7 @@ export function postgresRateLimitStore(
   options: PostgresRateLimitStoreOptions,
 ): PostgresRateLimitStore {
   const exec = options.executor;
+  const deadline = storeDeadline(options.deadlineMs, options.schedule);
   // Where a decision is taken while the database is unreachable (`rate-limit-degrade.ts`). Still
   // `scope: 'shared'` below: the store IS the fleet's, and the degraded window is logged, bounded
   // by the outage, and a weaker limit rather than none.
@@ -181,13 +191,16 @@ export function postgresRateLimitStore(
     async take(key, bucket, cost, nowMs): Promise<RateLimitDecision> {
       let rows: readonly TakeRow[];
       try {
-        rows = await exec.query<TakeRow>(SQL_RATE_LIMIT_TAKE, [
-          key,
-          bucket.capacity,
-          bucket.refillPerSecond,
-          cost,
-          Math.floor(nowMs),
-        ]);
+        rows = await deadline.bound(
+          'take',
+          exec.query<TakeRow>(SQL_RATE_LIMIT_TAKE, [
+            key,
+            bucket.capacity,
+            bucket.refillPerSecond,
+            cost,
+            Math.floor(nowMs),
+          ]),
+        );
       } catch (error) {
         return degrade(error, nowMs, () => fallback.store.take(key, bucket, cost, nowMs));
       }
@@ -202,7 +215,7 @@ export function postgresRateLimitStore(
     async peek(key, bucket, nowMs) {
       let rows: readonly PeekRow[];
       try {
-        rows = await exec.query<PeekRow>(SQL_RATE_LIMIT_PEEK, [key]);
+        rows = await deadline.bound('peek', exec.query<PeekRow>(SQL_RATE_LIMIT_PEEK, [key]));
       } catch (error) {
         return degrade(error, nowMs, () => fallback.store.peek(key, bucket, nowMs));
       }

package/src/rate-limit-store-deadline.ts

@@ -0,0 +1,60 @@
+// The shared rate-limit store's own deadline on one round trip. The pool's unanswered-statement
+// bound (statement_timeout + 5 s) is sized for the app's work; a limiter that waits it out spends
+// a request's whole budget deciding whether to admit it, then the request's own statement waits a
+// second bound. Past this deadline the store degrades (`rate-limit-degrade.ts`) instead.
+
+import { assert, finiteCount, MAX_TIMER_MS, type Scheduler } from '@ultimat3/core';
+import { HttpError } from './errors';
+
+/**
+ * Measured 2026-11-06, Bun 1.3, Postgres 17 on loopback, `web` pool (max 20), three runs each: a
+ * cold first statement (connect + SCRAM) 15–31 ms; a warm take p99 0.4 ms; 100 concurrent takes on
+ * ONE hot key (row-lock queue) max 11.3 ms. 250 ms is ~8x the worst cold connect and ~20x the
+ * worst contended take, and costs a blackholed request a quarter second instead of ~16 s.
+ */
+export const RATE_LIMIT_STORE_DEADLINE_MS = 250;
+
+/** Unreffed: a deadline guards work in flight and must never keep a finished process alive. */
+const unrefSchedule: Scheduler = (fn, ms) => {
+  const timer = setTimeout(fn, ms);
+  timer.unref?.();
+  return () => clearTimeout(timer);
+};
+
+export interface StoreDeadline {
+  /** `sending`'s answer, or `X_RATE_LIMIT_STORE_TIMEOUT` once `deadlineMs` passes first. */
+  bound<T>(statement: 'take' | 'peek', sending: Promise<T>): Promise<T>;
+}
+
+export const rateLimitStoreTimeout = (statement: string, deadlineMs: number): HttpError =>
+  new HttpError({
+    code: 'X_RATE_LIMIT_STORE_TIMEOUT',
+    cause: `the shared rate-limit store's ${statement} statement did not answer within ${String(deadlineMs)} ms, so this decision was taken from this pod's memory`,
+    fix: 'x doctor --json   # names the database binding this pod cannot reach; a database that is slow rather than gone takes postgresRateLimitStore({ executor, deadlineMs }) raised in the boot that builds it',
+    meta: { statement, deadlineMs },
+  });
+
+/**
+ * The abandoned statement is not cancelled — the executor has no seam for it — and the pool's own
+ * sweep still retires it at its bound; `Promise.race` keeps its late rejection handled meanwhile.
+ */
+export function storeDeadline(
+  deadlineMs: number = RATE_LIMIT_STORE_DEADLINE_MS,
+  schedule: Scheduler = unrefSchedule,
+): StoreDeadline {
+  finiteCount('postgresRateLimitStore', 'deadlineMs', deadlineMs, 1);
+  assert(
+    deadlineMs <= MAX_TIMER_MS,
+    `postgresRateLimitStore deadlineMs is ${String(deadlineMs)}, past the longest delay a timer holds, so it would fire at once`,
+    `postgresRateLimitStore({ executor, deadlineMs: ${String(RATE_LIMIT_STORE_DEADLINE_MS)} })   # or any whole number of ms up to ${String(MAX_TIMER_MS)}`,
+  );
+  return {
+    bound<T>(statement: 'take' | 'peek', sending: Promise<T>): Promise<T> {
+      let cancel: () => void = () => undefined;
+      const late = new Promise<never>((_, reject) => {
+        cancel = schedule(() => reject(rateLimitStoreTimeout(statement, deadlineMs)), deadlineMs);
+      });
+      return Promise.race([sending, late]).finally(() => cancel());
+    },
+  };
+}

package/src/response.ts

@@ -14,22 +14,46 @@ const withDefaults = (init: HeaderSource, defaults: Record<string, string>): Hea
   return headers;
 };
 
-export const jsonResponse = <T>(body: T, init?: ResponseInit): Response =>
-  new Response(JSON.stringify(body), {
+/** RFC 9110: these carry no content, so a `content-length` on one is a false statement. */
+const CONTENTLESS_STATUS: ReadonlySet<number> = new Set([204, 205, 304]);
+
+/**
+ * The length is the BYTES this body encodes to, declared because `new Response(string)` declares
+ * nothing and the `compress` stage never reads what it cannot bound. `stream` has none to declare.
+ * `string | undefined`: `JSON.stringify` answers `undefined` for a value it cannot render.
+ */
+const declaredLength = (body: string | undefined, init?: ResponseInit): Record<string, string> =>
+  body === undefined || (init?.status !== undefined && CONTENTLESS_STATUS.has(init.status))
+    ? {}
+    : { 'content-length': String(Buffer.byteLength(body)) };
+
+export const jsonResponse = <T>(body: T, init?: ResponseInit): Response => {
+  const text: string | undefined = JSON.stringify(body);
+  return new Response(text, {
     ...init,
-    headers: withDefaults(init, { 'content-type': 'application/json; charset=utf-8' }),
+    headers: withDefaults(init, {
+      'content-type': 'application/json; charset=utf-8',
+      ...declaredLength(text, init),
+    }),
   });
+};
 
 export const textResponse = (body: string, init?: ResponseInit): Response =>
   new Response(body, {
     ...init,
-    headers: withDefaults(init, { 'content-type': 'text/plain; charset=utf-8' }),
+    headers: withDefaults(init, {
+      'content-type': 'text/plain; charset=utf-8',
+      ...declaredLength(body, init),
+    }),
   });
 
 export const html = (markup: string, init?: ResponseInit): Response =>
   new Response(markup, {
     ...init,
-    headers: withDefaults(init, { 'content-type': 'text/html; charset=utf-8' }),
+    headers: withDefaults(init, {
+      'content-type': 'text/html; charset=utf-8',
+      ...declaredLength(markup, init),
+    }),
   });
 
 /**

package/src/router.ts

@@ -12,6 +12,7 @@
 // (`X_ROUTE_CONFLICT`) rather than a coin flip.
 import type { Actor, RenderMode } from '@ultimat3/core';
 import type { RequestContext } from './context';
+import { assertRouteCsrf } from './csrf';
 import { routeConflict } from './errors';
 import type { Bucket } from './rate-limit';
 import type { UltimateRequest } from './request';
@@ -120,6 +121,13 @@ export interface RouteMeta {
     request: UltimateRequest,
     ctx: RequestContext,
   ) => Promise<Actor | null> | Actor | null;
+  /**
+   * `'cookieless'`: the `csrf` stage does not judge this route while its caller is anonymous —
+   * an RFC 6749 token, revocation or registration endpoint, client-authenticated or PKCE-bound,
+   * that a cross-origin client is MEANT to POST to. Only with `authenticate` declared
+   * (`X_CONFIG_INVALID` from `httpRouter`), so the app's cookie authenticator never runs here.
+   */
+  readonly csrf?: 'cookieless';
 }
 
 export type RouteHandler = (
@@ -172,6 +180,7 @@ export const httpRouter = (routes: readonly Route[]): RouteTable => {
     // not on the response path — `cacheControl` is total there by design, so the alternative is a
     // log line once per request and a response that quietly falls back to heuristic caching.
     assertRouteCache(route.meta.cache, route.meta.name, route.path);
+    assertRouteCsrf(route.meta, route.path);
     let current = root;
     const segments = pathSegments(route.path);
     for (const [index, segment] of segments.entries()) {

package/src/server-websocket.ts

@@ -0,0 +1,35 @@
+// What `httpServer` serves for its `websocket:` option — one mount or a list — as the ONE shape its
+// listener dispatches: every owned path, one fetch, one handler set. A lone mount is handed through
+// unwrapped (no socket of the sync node's pays for a join it does not need); two or more are joined
+// by `joinWebSocketMounts`, which routes each upgrade, and each socket's frames, to its own mount.
+
+import type { WebSocketMount } from './server';
+import { type JoinedWebSocketMounts, joinWebSocketMounts } from './websocket-mounts';
+
+/** `ServerOptions.websocket`: the sync node's socket, a device link, or both on one listener. */
+export type WebSocketOption = WebSocketMount | readonly WebSocketMount[];
+
+const isList = (option: WebSocketOption): option is readonly WebSocketMount[] =>
+  Array.isArray(option);
+
+/**
+ * The served mounts, or `undefined` when there are none — then the listener opens no websocket at
+ * all, as it did before the option existed. `assertFree` is asked about EVERY path before anything
+ * is joined: a static route on the second mount's path shadows it exactly as it would the first.
+ */
+export function serverWebSockets(
+  option: WebSocketOption | undefined,
+  assertFree: (path: string) => void,
+): JoinedWebSocketMounts | undefined {
+  const mounts = option === undefined ? [] : isList(option) ? option : [option];
+  for (const mount of mounts) assertFree(mount.path);
+  const [only] = mounts;
+  if (only === undefined) return undefined;
+  if (mounts.length > 1) return joinWebSocketMounts(mounts);
+  return {
+    paths: new Set([only.path]),
+    fetch: (request, server) => only.fetch(request, server),
+    // `never` is the mount's own socket type: the socket Bun hands back is the one its upgrade made.
+    websocket: only.websocket as JoinedWebSocketMounts['websocket'],
+  };
+}

package/src/server.ts

@@ -31,6 +31,7 @@ import { withRouteBuckets } from './rate-limit-buckets';
 import { adoptRateLimitStore } from './rate-limit-installed';
 import { jsonResponse } from './response';
 import { describeRoutes, httpRouter, type Route } from './router';
+import { serverWebSockets, type WebSocketOption } from './server-websocket';
 
 /**
  * Beside its one caller rather than in `errors.ts`, which is at the 500-line ceiling — the
@@ -86,8 +87,12 @@ export interface ServerOptions {
    * So a host may mount the socket on the port it already publishes, and the two-port topology
    * stays exactly as it was: `x dev` does BOTH, `docker/` keeps its own `sync` service, and a
    * client picks whichever origin it can actually reach.
+   *
+   * A LIST serves several on this one listener — the sync node's beside every declared
+   * `deviceSocket()` — each path checked free, each upgrade and its frames routed to its own mount
+   * (`server-websocket.ts`). An empty list is no websocket.
    */
-  readonly websocket?: WebSocketMount;
+  readonly websocket?: WebSocketOption;
   /**
    * `app.config.ts`'s `drain` section — pass `appConfig.drain`. Its `readinessGraceMs` is how long
    * `/readyz` answers 503 before the `accept` phase closes this listener. Omitted, core's own
@@ -208,7 +213,6 @@ const buildServer = (options: ServerOptions, releaseStore: () => void): ServerHa
   const readinessGraceMs = options.drain?.readinessGraceMs;
   if (readinessGraceMs !== undefined) configureLifecycle({ readinessGraceMs });
 
-  const mount = options.websocket;
   let server: BunServer | undefined;
   let unregister: (() => void) | undefined;
   let unregisterBodies: (() => void) | undefined;
@@ -304,7 +308,7 @@ const buildServer = (options: ServerOptions, releaseStore: () => void): ServerHa
         throw websocketPathTaken(path, `the route \`${description.name}\``);
     }
   };
-  if (mount !== undefined) assertMountPathFree(mount.path);
+  const mount = serverWebSockets(options.websocket, assertMountPathFree);
 
   const handle: ServerHandle = {
     role,
@@ -360,7 +364,7 @@ const buildServer = (options: ServerOptions, releaseStore: () => void): ServerHa
           : Bun.serve({
               ...listen,
               fetch: async (request, socket) =>
-                pathOf(request) === mount.path
+                mount.paths.has(pathOf(request))
                   ? await mount.fetch(request, socket as unknown as UpgradeTarget)
                   : await dispatch(request, socket),
               websocket: mount.websocket,

package/src/stages.ts

@@ -1,7 +1,7 @@
 // One function per stage name: what each stage of the lifecycle DOES. The package's three-way
 // split, each file naming the other two — `pipeline.ts` owns the ORDER the stages run in and the
 // run itself, `finalize.ts` owns the promise that the tail cannot reject, and this file owns the
-// work. The vocabulary (`StageName`, `Stage`) lives here too, beside the fourteen implementations
+// work. The vocabulary (`StageName`, `Stage`) lives here too, beside the fifteen implementations
 // it names, so `Record<StageName, StageRun>` below is the build error that catches a missing one.
 
 import {
@@ -15,6 +15,7 @@ import {
 } from '@ultimat3/core';
 import { signInRedirect } from './auth-redirect';
 import { finalizeCacheHeaders } from './cache-stage';
+import { compressResponse } from './compress';
 import { type HttpConfig, stripBasePath } from './config';
 import { elapsedMs, type RequestContext } from './context';
 import { corsHeaders, preflight } from './cors';
@@ -66,7 +67,8 @@ export type StageName =
   | 'handler'
   | 'cache-headers'
   | 'error-map'
-  | 'response';
+  | 'response'
+  | 'compress';
 
 /**
  * `request`  may short-circuit by returning a Response.
@@ -79,7 +81,7 @@ export type StagePhase = 'request' | 'terminal' | 'recover' | 'finalize';
 export interface StageDoc {
   readonly name: StageName;
   readonly phase: StagePhase;
-  /** Why the stage sits at this index. Rendered verbatim by the dev dashboard. */
+  /** Why the stage sits at this index, read by `pipeline.test.ts` and anyone reading the list. */
   readonly why: string;
 }
 
@@ -265,12 +267,15 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
         selfOrigin: selfOrigin(ctx.url, ctx.https),
         origin: request.header('origin'),
         secFetchSite: request.header('sec-fetch-site'),
-        hasAuthorizationHeader: request.header('authorization') !== null,
+        authorization: request.header('authorization'),
         anonymous: isAnonymous(ctx.actor),
+        cookieless: ctx.route?.meta.csrf === 'cookieless',
         cors: config.cors,
         config: config.csrf,
       });
-      if (!verdict.ok) throw csrfBlocked(ctx.url.pathname, verdict.reason, ctx.ip);
+      if (!verdict.ok) {
+        throw csrfBlocked(ctx.url.pathname, verdict.reason, ctx.ip, selfOrigin(ctx.url, ctx.https));
+      }
       return undefined;
     },
 
@@ -470,6 +475,14 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
       response.headers.set('server-timing', `total;dur=${elapsedMs(ctx)}`);
       return undefined;
     },
+
+    compress: (request, ctx) =>
+      ctx.response === undefined
+        ? undefined
+        : compressResponse(request.raw, ctx.response, {
+            anonymous: isAnonymous(ctx.actor),
+            signal: ctx.signal,
+          }),
   };
   return table;
 };

package/src/stored-object-headers.ts

@@ -0,0 +1,43 @@
+// How a stored object may be presented when the app's own origin serves it (plan 101, s1-sec L6):
+// inline only for a type a browser renders without running anything, a sandboxed download otherwise.
+// Read by `objectResponse`, the one way a stored object is answered.
+
+/**
+ * Raster images, audio and video: what an `<img>`, `<audio>` or `<video>` presents and nothing
+ * executes. NOT `image/svg+xml` (it carries `<script>`), `text/html`, `application/xml` or PDF —
+ * any of them opened from the app's origin runs with the app's cookies and its `'self'` sources.
+ */
+const INLINE_TYPES: ReadonlySet<string> = new Set([
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+  'image/avif',
+  'audio/mpeg',
+  'audio/ogg',
+  'audio/wav',
+  'audio/webm',
+  'video/mp4',
+  'video/webm',
+  'video/ogg',
+]);
+
+/** `image/PNG; charset=…` is `image/png`: parameters and case never widen the list. */
+const essenceOf = (contentType: string): string =>
+  (contentType.split(';')[0] ?? '').trim().toLowerCase();
+
+export const isInlineSafe = (contentType: string): boolean =>
+  INLINE_TYPES.has(essenceOf(contentType));
+
+/**
+ * The headers a stored object is served with beyond its type. `attachment` makes a navigation to an
+ * uploaded `text/html` a download instead of a page on the app's origin; an embedding element
+ * (`<img>`, `<video>`) ignores it, so nothing that displays an object inline stops working. The
+ * `sandbox` policy is for the browser that renders it anyway: an opaque origin, no script, no
+ * cookies. The security stage keeps it and adds the app's policy beside it.
+ */
+export function storedObjectHeaders(contentType: string): Readonly<Record<string, string>> {
+  return isInlineSafe(contentType)
+    ? {}
+    : { 'content-disposition': 'attachment', 'content-security-policy': 'sandbox' };
+}

package/src/webhook-hmac.ts

@@ -0,0 +1,73 @@
+// `verifyBodyHmac`: the one vendor-neutral check many inbound webhooks share — HMAC-SHA256 under a
+// UTF-8 secret over bytes the caller names, compared in constant time, under any secret of a
+// rotation list. It does not decode a secret (Svix's base64 `whsec_` key is the mail receivers'),
+// and the bytes and the header are the vendor's: no vendor verifier ships (axiom 8).
+
+import { hmac, timingSafeEqual } from '@ultimat3/core';
+import { webhookSignatureInvalid } from './errors';
+import { assertWebhookSecrets } from './webhook-verify';
+
+export interface BodyHmacOptions {
+  /** The bytes the vendor signed. A string is its UTF-8 encoding. */
+  readonly bytes: Uint8Array | string;
+  /** The shared secret, or the list a rotation keeps live — any one of them verifies. */
+  readonly secret: string | readonly string[];
+  /** The mac the request carried, header value as sent. Absent or empty is a refusal. */
+  readonly given: string | null | undefined;
+  readonly encoding: 'hex' | 'base64';
+  /** What precedes the mac in `given`: `sha256=` (GitHub), `v0=` (Slack). Compared, not stripped. */
+  readonly prefix?: string;
+}
+
+/**
+ * What a passing check answers: the bytes it verified, and their text when they are UTF-8. Read
+ * the event id from HERE, never from an unsigned header — an id outside the mac lets one captured
+ * signature replay under any id the attacker picks.
+ */
+export interface VerifiedBody {
+  readonly bytes: Uint8Array;
+  readonly text: string | null;
+}
+
+/** `fatal`: invalid UTF-8 is `null` text, never replacement characters an id could be read from. */
+const strictUtf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+
+/**
+ * Prove `given` is `prefix + HMAC-SHA256(secret, bytes)` for one of the secrets, and answer what
+ * was verified. Throws `X_WEBHOOK_SIGNATURE_INVALID` (401) on a mismatch and `X_CONFIG_INVALID`
+ * for no usable secret.
+ */
+export function verifyBodyHmac(options: BodyHmacOptions): VerifiedBody {
+  const secrets = assertWebhookSecrets(options.secret, 'verifyBodyHmac');
+  const given = options.given ?? '';
+  if (given === '') {
+    throw webhookSignatureInvalid(
+      'verifyBodyHmac',
+      'the request carried no signature',
+      'verifyBodyHmac',
+    );
+  }
+  const prefix = options.prefix ?? '';
+  let matched = false;
+  // Every secret is tried, even after a match: which one matched is not worth a timing signal.
+  for (const secret of secrets) {
+    const expected = `${prefix}${hmac('sha256', secret, options.bytes, options.encoding)}`;
+    if (timingSafeEqual(expected, given)) matched = true;
+  }
+  if (!matched) {
+    throw webhookSignatureInvalid(
+      'verifyBodyHmac',
+      `no ${options.encoding} sha256 mac${prefix === '' ? '' : ` behind the "${prefix}" prefix`} under the ${secrets.length} configured secret(s) matches the bytes`,
+      'verifyBodyHmac',
+    );
+  }
+  const bytes =
+    typeof options.bytes === 'string' ? new TextEncoder().encode(options.bytes) : options.bytes;
+  let text: string | null;
+  try {
+    text = typeof options.bytes === 'string' ? options.bytes : strictUtf8.decode(bytes);
+  } catch {
+    text = null;
+  }
+  return { bytes, text };
+}