@ultimat3/http 29.3.2 → 30.0.0

package/src/object-response.ts

@@ -0,0 +1,134 @@
+// Single responsibility: the one correct answer to a GET for an object held elsewhere — its stored
+// type, its validator, one `Range:` window, the sandbox for a type a browser would run. `/_storage`,
+// `/media`, a download and an app's own route for an object a stranger may fetch all answer here.
+// Structural, because this package imports no storage: anything with these fields is servable.
+
+import {
+  contentRangeOf,
+  parseByteRange,
+  RANGE_UNSATISFIABLE,
+  type RequestedRange,
+} from './byte-range';
+import type { CacheHint } from './response';
+import { applyCacheHeaders } from './response';
+import { storedObjectHeaders } from './stored-object-headers';
+
+/** What the answer needs to know before it opens anything. `StorageObject` is one of these. */
+export interface ServableObject {
+  /** The STORED type. An extension in the URL is the only party that can lie. */
+  readonly contentType: string;
+  readonly size: number;
+  /** The object's own validator. Absent or `''` (unknowable): no `etag` header, and no 304. */
+  readonly etag?: string | undefined;
+  /** Omitted, never invented: a made-up date is a validator a cache would go on to trust. */
+  readonly lastModified?: Date | undefined;
+}
+
+export interface ObjectSource {
+  readonly object: ServableObject;
+  /**
+   * Exactly those bytes, or the whole object with no range. Opened only once a body will be sent: a
+   * 304 and a 416 open nothing. Takes the range so a disk can serve a window, not drop a prefix.
+   */
+  readonly open: (range?: RequestedRange) => BodyInit | Promise<BodyInit>;
+}
+
+/** The one thing asked of the request, so a test or a non-pipeline caller needs no `Request`. */
+export interface ObjectRequest {
+  header(name: string): string | null;
+}
+
+export interface ObjectResponseOptions {
+  /** Applied to every answer. Omitted, the route's declared `meta.cache` decides as for any route. */
+  readonly cache?: CacheHint | undefined;
+  /** Replaces the stored-object sandbox rule, for a caller with its own, as a download has. */
+  readonly headers?: Readonly<Record<string, string>> | undefined;
+}
+
+/** `*`, a weak validator and a comma list all count — the etag is what has to match. */
+export function etagMatches(header: string | null, etag: string): boolean {
+  if (header === null) return false;
+  if (header.trim() === '*') return true;
+  return header.split(',').some((candidate) => candidate.trim().replace(/^W\//, '') === etag);
+}
+
+/**
+ * The 304 for a client already holding `etag`, or nothing for the caller to go on and answer. It
+ * repeats the validator and whatever posture `headers` carry (RFC 9110 §15.4.5).
+ */
+export function notModified(
+  request: ObjectRequest,
+  etag: string,
+  headers?: HeadersInit,
+): Response | undefined {
+  if (!etagMatches(request.header('if-none-match'), etag.replace(/^W\//, ''))) return undefined;
+  const answer = new Headers(headers);
+  answer.set('etag', etag);
+  return new Response(null, { status: 304, headers: answer });
+}
+
+/**
+ * Whether `if-range` still names these bytes. Compared strongly, and a date only if it is exactly
+ * the object's: a window of an older revision spliced onto this one is two files in one download.
+ */
+function ifRangeHolds(header: string | null, etag: string | undefined, modified?: Date): boolean {
+  if (header === null) return true;
+  const validator = header.trim();
+  if (validator.startsWith('W/')) return false;
+  if (validator.startsWith('"')) return etag === validator;
+  return modified?.toUTCString() === validator;
+}
+
+/** A provider's etag may arrive already quoted, and quoting it again answers an invalid header. */
+const quotedEtag = (etag: string): string =>
+  etag.startsWith('"') || etag.startsWith('W/"') ? etag : `"${etag}"`;
+
+/**
+ * Revalidation costs a request and no bytes, which is the trade an authorized response wants: the
+ * bytes do not change under a validator, but the actor's permission to read them can be revoked.
+ * The size is the object's description, so the length declared is the length `open` must deliver.
+ */
+export async function objectResponse(
+  request: ObjectRequest,
+  source: ObjectSource,
+  options: ObjectResponseOptions = {},
+): Promise<Response> {
+  const { object } = source;
+  const headers = new Headers({
+    'content-type': object.contentType,
+    'accept-ranges': 'bytes',
+    // A type a browser would RUN (html, svg, xml) is a download, never a page on this origin.
+    ...(options.headers ?? storedObjectHeaders(object.contentType)),
+  });
+  if (object.lastModified !== undefined) {
+    headers.set('last-modified', object.lastModified.toUTCString());
+  }
+  const answer = (body: BodyInit | null, status: number): Response => {
+    const response = new Response(body, { status, headers });
+    return options.cache === undefined ? response : applyCacheHeaders(response, options.cache);
+  };
+
+  const etag =
+    object.etag === undefined || object.etag === '' ? undefined : quotedEtag(object.etag);
+  if (etag !== undefined) {
+    headers.set('etag', etag);
+    if (notModified(request, etag) !== undefined) return answer(null, 304);
+  }
+
+  const { size } = object;
+  // A range of another revision is no range at all: the whole object, never a 416 either.
+  const range = ifRangeHolds(request.header('if-range'), etag, object.lastModified)
+    ? parseByteRange(request.header('range'), size)
+    : undefined;
+  if (range === RANGE_UNSATISFIABLE) {
+    headers.set('content-range', `bytes */${String(size)}`);
+    return answer(null, 416);
+  }
+  if (range === undefined) {
+    headers.set('content-length', String(size));
+    return answer(await source.open(), 200);
+  }
+  headers.set('content-range', contentRangeOf(range, size));
+  headers.set('content-length', String(range.end - range.start + 1));
+  return answer(await source.open(range), 206);
+}

package/src/overlay.ts

@@ -75,7 +75,16 @@ export const renderOverlay = (error: unknown, meta: OverlayMeta = {}): string =>
     dev: true,
   });
   const where = `${meta.method ?? ''} ${meta.path ?? ''}`.trim();
-  return `<style>${OVERLAY_STYLE}</style>
+  // A whole document, `lang` and `<title>` included: an e2e test's accessibility audit reads the
+  // overlay like any page, and a fragment has neither.
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>${escapeHtml(`${facts.code} ${facts.title}`)}</title>
+<style>${OVERLAY_STYLE}</style>
+</head>
+<body>
 <main>
   <section class="card">
     <h1>${escapeHtml(facts.code)} <span class="title">${escapeHtml(facts.title)}</span></h1>
@@ -105,7 +114,9 @@ export const renderOverlay = (error: unknown, meta: OverlayMeta = {}): string =>
     <h2>json</h2>
     <pre>${escapeHtml(JSON.stringify(problem, null, 2))}</pre>
   </section>
-</main>`;
+</main>
+</body>
+</html>`;
 };
 
 export const overlayResponse = (error: unknown, meta: OverlayMeta = {}): Response =>

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,