@ultimat3/http 30.9.0 → 31.0.0

package/src/compress.ts

@@ -32,6 +32,9 @@ const COMPRESSIBLE_TYPES: ReadonlySet<string> = new Set([
   'application/rss+xml',
   'application/atom+xml',
   'text/vtt',
+  // Exports and feeds: usually streamed with no declared length, so coded by `codedStream`.
+  'application/x-ndjson',
+  'text/csv',
 ]);
 
 /**
@@ -68,7 +71,10 @@ const compressibleKind = (headers: Headers, anonymous: boolean): boolean => {
   );
 };
 
-/** HEAD is GET's headers with no body (RFC 9110 §9.3.2), so it is coded exactly as GET is. */
+/**
+ * HEAD is GET's headers with no body (RFC 9110 §9.3.2): coded as GET is when the handler hands it
+ * GET's body to measure. A HEAD answered with no body has nothing to measure and stays identity.
+ */
 const CODED_METHODS: ReadonlySet<string> = new Set(['GET', 'HEAD']);
 
 /** RFC 9110 §12.5.3, `gzip` by name. A `*` is not read as consent to a coding it never named. */
@@ -91,18 +97,57 @@ const inBounds = (length: string | null): length is string =>
 const rebuilt = (response: Response, body: BodyInit | null, headers: Headers): Response =>
   new Response(body, { status: response.status, statusText: response.statusText, headers });
 
-const coded = (response: Response, bytes: Uint8Array<ArrayBuffer>, head: boolean): Response => {
-  const gzipped = Bun.gzipSync(bytes, { level: GZIP_LEVEL });
+/**
+ * A feed delivers each line as it is written, and `CompressionStream` emits only its header until
+ * the source closes — so an undeclared feed is never coded. Declared, it is a document.
+ */
+const FEED_TYPES: ReadonlySet<string> = new Set(['application/x-ndjson']);
+
+const isFeed = (contentType: string | null): boolean =>
+  FEED_TYPES.has(contentType?.split(';')[0]?.trim().toLowerCase() ?? '');
+
+/** Past the ceiling: coded as the client pulls (`CompressionStream`), never on the event loop. */
+const pastCeiling = (length: string): boolean =>
+  DECLARED_LENGTH.test(length) && Number(length) > COMPRESS_MAX_BYTES;
+
+/** The headers of a gzip answer: everything that described the identity bytes, corrected. */
+const codedHeaders = (response: Response, length: number | null): Headers => {
   const headers = new Headers(response.headers);
   headers.set('content-encoding', 'gzip');
-  headers.set('content-length', String(gzipped.byteLength));
+  if (length === null) headers.delete('content-length');
+  else headers.set('content-length', String(length));
   // A byte offset into the identity bytes means nothing in these.
   headers.delete('accept-ranges');
   headers.delete('transfer-encoding');
   const etag = headers.get('etag');
   // A strong validator promises these exact bytes, and the identity answer has other ones.
   if (etag !== null && !etag.startsWith('W/')) headers.set('etag', `W/${etag}`);
-  return rebuilt(response, head ? null : gzipped, headers);
+  return headers;
+};
+
+const coded = (response: Response, bytes: Uint8Array<ArrayBuffer>, head: boolean): Response => {
+  const gzipped = Bun.gzipSync(bytes, { level: GZIP_LEVEL });
+  return rebuilt(response, head ? null : gzipped, codedHeaders(response, gzipped.byteLength));
+};
+
+/** Bytes over a plain `ArrayBuffer`, the only kind the coder's `BufferSource` side accepts. */
+const ownsPlainBuffer = (chunk: Uint8Array): chunk is Uint8Array<ArrayBuffer> =>
+  chunk.buffer instanceof ArrayBuffer;
+
+const codedStream = (response: Response, body: ReadableStream<Uint8Array>): Response => {
+  // A chunk over shared memory is copied; every other one passes through untouched.
+  const plain = body.pipeThrough(
+    new TransformStream<Uint8Array, Uint8Array<ArrayBuffer>>({
+      transform(chunk, controller) {
+        controller.enqueue(ownsPlainBuffer(chunk) ? chunk : new Uint8Array(chunk));
+      },
+    }),
+  );
+  return rebuilt(
+    response,
+    plain.pipeThrough(new CompressionStream('gzip')),
+    codedHeaders(response, null),
+  );
 };
 
 /** Identity after a read began. Never the declared length: the failed read just disproved it. */
@@ -116,6 +161,30 @@ const identity = (
   return rebuilt(response, body, headers);
 };
 
+/**
+ * No declared length (`new Response(string)` declares none in Bun): read up to the floor first. A
+ * body that ends under it leaves identity, whole, with its length; one that reaches it is coded as
+ * a stream, the bytes already read first. A feed is never read. Bounded by the request's deadline.
+ */
+const codeUndeclared = async (
+  response: Response,
+  body: ReadableStream<Uint8Array>,
+  signal: AbortSignal | undefined,
+): Promise<Response> => {
+  if (isFeed(response.headers.get('content-type'))) return response;
+  const reader = body.getReader();
+  const drained = await drainCounted(reader, COMPRESS_MIN_BYTES - 1, signal);
+  if (drained.complete) return identity(response, concatChunks(drained.chunks));
+  const rest = replayDrained(drained.chunks, reader, drained.pending);
+  if (drained.reason === 'longer-than-declared') return codedStream(response, rest);
+  logger.warn('http.compress_failed', {
+    reason: drained.reason,
+    declaredBytes: null,
+    ...(drained.failure === undefined ? {} : { error: drained.failure }),
+  });
+  return identity(response, rest);
+};
+
 export interface CompressContext {
   /** `isAnonymous(ctx.actor)`. Declared, never defaulted: a forgotten actor must not code. */
   readonly anonymous: boolean;
@@ -143,12 +212,14 @@ export const compressResponse = async (
     !acceptsGzip(request.headers.get('accept-encoding')) ||
     response.headers.has('content-encoding') ||
     response.headers.has('content-range') ||
-    !inBounds(length) ||
     response.body === null ||
     response.bodyUsed
   ) {
     return response;
   }
+  if (length === null) return codeUndeclared(response, response.body, signal);
+  if (pastCeiling(length)) return codedStream(response, response.body);
+  if (!inBounds(length)) return response;
   const reader = response.body.getReader();
   const drained = await drainCounted(reader, Number(length), signal);
   if (!drained.complete) {

package/src/config.ts

@@ -9,6 +9,7 @@ import {
   MAX_TIMER_MS,
   tryResolveEnvironment,
 } from '@ultimat3/core';
+import { DEFAULT_MAX_REQUEST_BODY_BYTES } from './body-ceiling';
 import { assertCorsConfig, type CorsConfig, DEFAULT_CORS } from './cors';
 import { type CsrfConfig, DEFAULT_CSRF } from './csrf';
 import {
@@ -24,7 +25,8 @@ import {
   type LocaleConfig,
   type TimeZoneConfig,
 } from './locale';
-import { type RateLimitConfig, resolveRateLimitConfig } from './rate-limit';
+import type { RateLimitConfig } from './rate-limit';
+import { resolveRateLimitConfig } from './rate-limit-config';
 import { assertCspExtend, DEFAULT_SECURITY, type SecurityConfig } from './security-headers';
 
 export interface HttpConfig {
@@ -70,6 +72,13 @@ export interface HttpConfig {
    */
   readonly healthDetailPeers: readonly string[];
   readonly bodyLimitBytes: number;
+  /**
+   * The most this process reads in ONE request, for any route — `bodyLimitBytes` is the parsed
+   * RPC body's cap, this is the transport's (a signed upload reads past the first, never past
+   * this). Over it is `X_BODY_TOO_LARGE` (413), declared or streamed. Never below
+   * `bodyLimitBytes`; defaults to 128 MiB, Bun's own former default.
+   */
+  readonly maxRequestBodyBytes: number;
   /**
    * How long one request may run before it is aborted and answered `X_TIMEOUT` (504). `0`
    * disables it, which is a deployment saying it would rather hold a connection forever than
@@ -103,6 +112,7 @@ export interface HttpConfigInput {
   readonly trustClientCertHeader?: boolean;
   readonly healthDetailPeers?: readonly string[];
   readonly bodyLimitBytes?: number;
+  readonly maxRequestBodyBytes?: number;
   readonly requestTimeoutMs?: number;
   readonly maxInflight?: number;
   readonly locale?: Partial<LocaleConfig>;
@@ -258,6 +268,13 @@ export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
   // judged, and a directive name that is not a token would otherwise be a bare `TypeError` out of
   // the first response's header build — or worse, a second directive nobody declared.
   assertCspExtend(csp.extend);
+  const bodyLimitBytes = assertFiniteCount(
+    'bodyLimitBytes',
+    input.bodyLimitBytes ?? 1_048_576,
+    Number.MAX_SAFE_INTEGER,
+    'a whole number of bytes',
+    'bodyLimitBytes: 1_048_576',
+  );
   return {
     // `Number.parseInt(env('PORT'), 10)` is `NaN` for `PORT=web`, and a config that carries NaN
     // into `Bun.serve` binds a port nobody asked for.
@@ -283,12 +300,17 @@ export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
     healthDetailPeers: assertHealthDetailPeers(
       input.healthDetailPeers === undefined ? DEFAULT_HEALTH_DETAIL_PEERS : input.healthDetailPeers,
     ),
-    bodyLimitBytes: assertFiniteCount(
-      'bodyLimitBytes',
-      input.bodyLimitBytes ?? 1_048_576,
-      Number.MAX_SAFE_INTEGER,
-      'a whole number of bytes',
-      'bodyLimitBytes: 1_048_576',
+    bodyLimitBytes,
+    // Never below the parsed-body cap: a body `bodyLimitBytes` allows is never refused under it.
+    maxRequestBodyBytes: Math.max(
+      bodyLimitBytes,
+      assertFiniteCount(
+        'maxRequestBodyBytes',
+        input.maxRequestBodyBytes ?? DEFAULT_MAX_REQUEST_BODY_BYTES,
+        Number.MAX_SAFE_INTEGER,
+        'a whole number of bytes',
+        `maxRequestBodyBytes: ${DEFAULT_MAX_REQUEST_BODY_BYTES}`,
+      ),
     ),
     // 30s: longer than any request a browser waits out, shorter than the 15s drain budget times
     // two, so a rolling restart cannot be held open by work started just before SIGTERM.

package/src/context.ts

@@ -9,12 +9,12 @@ import {
   ctxOf,
   isAnonymous,
   type Logger,
+  liveClock,
   traceId as newTraceId,
   type Role,
   readCookie,
   runWithContext,
   type ServiceBag,
-  systemClock,
   useContext,
   uuidV7,
   withChildContext,
@@ -176,7 +176,8 @@ export interface RequestContextInit {
 }
 
 export const requestContext = (init: RequestContextInit): RequestContext => {
-  const clock = init.clock ?? systemClock;
+  // The `clock` port's clock as of THIS request, never one captured at boot.
+  const clock = init.clock ?? liveClock;
   const requestId = init.requestId ?? uuidV7(clock);
   // core's `traceId()`, never `uuid()`: a dashed UUIDv7 is not a 32-hex W3C trace id, and a
   // collector rejects the span that carries one — while the log lines beside it, which quote the

package/src/cors.ts

@@ -74,6 +74,26 @@ export const assertCorsConfig = (config: CorsConfig): void => {
       "list the scheme too: configureHttp({ cors: { origins: ['http://localhost:3000'] } })",
     );
   }
+  for (const origin of config.origins) {
+    if (origin === '*') continue;
+    const canonical = canonicalOrigin(origin);
+    if (canonical === origin) continue;
+    throw corsConfigInvalid(
+      `origins includes ${JSON.stringify(origin)}, which no browser sends as an Origin — it is compared byte for byte, so it matches nothing`,
+      `configureHttp({ cors: { origins: ['${canonical}'] } })   # scheme, lower-case host, a port only when not the scheme's default — no path, no trailing slash`,
+    );
+  }
+};
+
+/**
+ * What a browser would send for this entry: `URL.origin`. A bare host gets `https://` prefixed so
+ * the fix names a value rather than a rule; an entry that does not parse at all keeps the shape.
+ */
+const canonicalOrigin = (origin: string): string => {
+  const parsed = URL.parse(origin);
+  if (parsed !== null && parsed.origin !== OPAQUE_ORIGIN) return parsed.origin;
+  const withScheme = URL.parse(`https://${origin}`);
+  return withScheme === null ? 'https://<host>[:port]' : withScheme.origin;
 };
 
 /**

package/src/error-facts.ts

@@ -15,7 +15,7 @@ import {
   stringField,
 } from '@ultimat3/core';
 import type { ValidationIssue } from '@ultimat3/schema';
-import { issueRuleFacts } from '@ultimat3/schema';
+import { issueRuleFacts, MAX_ISSUES } from '@ultimat3/schema';
 import { declaredStatusFor, statusFor } from './error-status';
 import { HTTP_ERROR_TITLES } from './errors';
 import { type ProblemMeta, problemMetaKeysFor, wireMeta } from './problem-meta';
@@ -140,11 +140,10 @@ export function retryAfterOf(error: unknown): number | undefined {
 }
 
 /**
- * A list this long is not a form's worth of rejections; it is a body meant to be expensive. The
- * same bound `@ultimat3/action`'s `issuesFromWire` applies on arrival, restated because that
- * package is tier 3 and this one is tier 2 — `error-facts.test.ts` pins the number on this side.
+ * A list this long is not a form's worth of rejections; it is a body meant to be expensive. Schema's
+ * own `MAX_ISSUES` — where validation stops collecting — imported, never restated (tier 0).
  */
-const MAX_PROBLEM_ISSUES = 100;
+const MAX_PROBLEM_ISSUES = MAX_ISSUES;
 
 /**
  * The rejections a validation failure carried, addressed by path — or `undefined`.
@@ -184,9 +183,8 @@ function issuesOf(error: unknown): readonly ValidationIssue[] | undefined {
     //
     // TOO LONG is `undefined` too, and dropped WHOLE rather than truncated: a subset is the
     // silent-drop this reader refuses everywhere else. The typed client bounds the same list at
-    // `MAX_WIRE_ISSUES` and would refuse it on arrival anyway (`packages/action/src/wire-issues.ts`),
-    // so sending it is a body that costs the wire and answers nothing — and that package is tier 3,
-    // so the number is restated here rather than imported.
+    // schema's `MAX_ISSUES` and would refuse it on arrival anyway (`packages/action/src/wire-issues.ts`),
+    // so sending it is a body that costs the wire and answers nothing.
     if (!Array.isArray(raw) || raw.length === 0 || raw.length > MAX_PROBLEM_ISSUES) {
       return undefined;
     }
@@ -287,6 +285,13 @@ export interface ProblemDocument {
    * `[]` says "validated clean", which is a different and false claim.
    */
   readonly issues?: readonly ValidationIssue[] | undefined;
+  /**
+   * `true` when validation stopped at `MAX_ISSUES` and `issues` is a prefix — off the error's
+   * `meta.issuesTruncated`, which action's and query's `X_INPUT_INVALID` both set. ABSENT unless
+   * `issues` is carried AND the mark is literally `true`: it qualifies a list, so it never rides
+   * without one, and a client that renders `issues` instead of `cause` must not call a prefix whole.
+   */
+  readonly issuesTruncated?: true | undefined;
   /**
    * The keys of the error's `meta` that `registerProblemMeta` declared for its code, JSON-safe
    * and bounded — and nothing else off `meta`, which is the operator-only bag the rest of this
@@ -352,6 +357,7 @@ export const toProblem = (
   // withhold — it names the fields and the expectations of something the caller was never meant to
   // see the inside of. `X_INPUT_INVALID` is a declared 4xx, so it is never opaque.
   const issues = hidden ? undefined : issuesOf(error);
+  const truncated = issues !== undefined && issuesTruncatedOf(error);
   // The same condition, for the same reason: a code nobody classified cannot have declared any
   // key either, so this is the belt on `registerProblemMeta`'s "both registrations are needed".
   const carried = opaque ? undefined : metaOf(error, facts.code);
@@ -378,10 +384,23 @@ export const toProblem = (
     retry: retryOf(error),
     requestId: meta.requestId,
     ...(issues === undefined ? {} : { issues }),
+    ...(truncated ? { issuesTruncated: true as const } : {}),
     ...(carried === undefined ? {} : { meta: carried }),
   };
 };
 
+/** `meta.issuesTruncated === true`, read totally — `issuesOf`'s reason: a value http did not build. */
+function issuesTruncatedOf(error: unknown): boolean {
+  if (typeof error !== 'object' || error === null) return false;
+  try {
+    const meta: unknown = (error as Record<string, unknown>)['meta'];
+    if (typeof meta !== 'object' || meta === null) return false;
+    return (meta as Record<string, unknown>)['issuesTruncated'] === true;
+  } catch {
+    return false;
+  }
+}
+
 /** The exact three lines the terminal prints, reused by the overlay and `--json`. */
 export const renderErrorLines = (error: unknown): string => {
   const facts = factsOf(error);

package/src/error-log-level.ts

@@ -1,12 +1,26 @@
 // Single responsibility: the log level of the one line the `error-map` stage writes per failed
 // request. Every 4xx was logged at `error`, so an alert keyed on error lines paged for a typo'd URL.
 
+/**
+ * Refusals that are routine by construction: `unauthenticated()` — a signed-in page asked by
+ * nobody, mostly scanners in production. Marked at the factory, so the same CODE raised by a
+ * credential checker that rejected something (`@ultimat3/auth`'s wrong password) stays `warn`.
+ */
+const routine = new WeakSet<object>();
+
+/** Marks a refusal the `error-map` line logs at `info` whatever its status. Returns it. */
+export const routineRefusal = <E extends object>(error: E): E => {
+  routine.add(error);
+  return error;
+};
+
 /**
  * `error` for 5xx — the server failed. `warn` for 401/403/429 — a refused credential, a refused
  * permission or a limit, each worth seeing in bulk. `info` for every other 4xx — the caller's own
- * mistake, which the problem document already explained to them.
+ * mistake, which the problem document already explained to them — and for a `routineRefusal`.
  */
-export const errorLogLevel = (status: number): 'error' | 'warn' | 'info' => {
+export const errorLogLevel = (status: number, error?: unknown): 'error' | 'warn' | 'info' => {
   if (status >= 500) return 'error';
+  if (typeof error === 'object' && error !== null && routine.has(error)) return 'info';
   return status === 401 || status === 403 || status === 429 ? 'warn' : 'info';
 };

package/src/error-map-http.ts

@@ -96,4 +96,6 @@ export const HTTP_ERROR_STATUS = {
   X_ROUTE_NAVIGATION_INVALID: 500,
   // @ultimat3/http — an exercise entry's request is not one a browser could send
   X_EXERCISE_REQUEST_INVALID: 500,
+  // @ultimat3/http — request body over the transport ceiling
+  X_BODY_TOO_LARGE: 413,
 } satisfies Readonly<Record<string, number>>;

package/src/error-map-tier-1.ts

@@ -42,9 +42,9 @@ export const TIER_1_ERROR_STATUS = {
   // not an attacker — reporting it as 403 sends the on-call hunting somebody who is not there.
   X_STORAGE_URL_UNVERIFIABLE: 500,
   // 409, not the 500 it fell through to: the object exists and the request is well formed — the
-  // STATE is wrong. A validated upload lands under the quarantine segment and `promoteAttachment`
-  // refuses it until the app's own scanner calls `releaseQuarantine`, which is a thing the caller
-  // can do. A 500 would have read as "the server broke" for a workflow working exactly as built.
+  // STATE is wrong. The app's `uploadScanner` answered `hold` (a review, an async vendor scan), so
+  // `promoteAttachment` keeps the upload pending until it answers clean, and a retry then succeeds.
+  // A 500 would have read as "the server broke" for a workflow working exactly as built.
   X_STORAGE_QUARANTINED: 409,
   // 409 for the same reason: `promoteAttachment` on a key that is not a pending upload — promoted
   // twice, or never uploaded — is a state the caller can see and fix, not a server fault.
@@ -106,4 +106,12 @@ export const TIER_1_ERROR_STATUS = {
   X_MONEY_INPUT_INVALID: 422,
   // @ultimat3/seo — a route meta og declares both image and capture
   X_SEO_OG_IMAGE_CONFLICT: 500,
+  // @ultimat3/money — a fromDecimal input that is not a plain decimal string
+  X_MONEY_NOT_DECIMAL: 422,
+  // @ultimat3/storage — the upload scanner found malware in the file
+  X_STORAGE_UPLOAD_INFECTED: 422,
+  // @ultimat3/storage — the upload scanner could not give a verdict
+  X_STORAGE_SCAN_UNAVAILABLE: 503,
+  // @ultimat3/storage — a targeted upload grant would bypass the upload scanner
+  X_STORAGE_TARGET_UNSCANNED: 500,
 } satisfies Readonly<Record<string, number>>;

package/src/error-map-tier-2.ts

@@ -137,4 +137,14 @@ export const TIER_2_ERROR_STATUS = {
   X_PASSKEY_STEP_UP_REQUIRED: 401,
   // @ultimat3/entity — a read-only entity was asked to write a row
   X_ENTITY_READ_ONLY: 500,
+  // @ultimat3/entity — a custom driver was asked for a capability it does not declare
+  X_DRIVER_UNSUPPORTED: 501,
+  // @ultimat3/entity — a custom driver returned a row outside the plan it was given
+  X_DRIVER_ROW_OUT_OF_SCOPE: 500,
+  // @ultimat3/auth — a saml response failed its signature, wrapping, audience, recipient, time, InResponseTo or replay check
+  X_SAML_RESPONSE_INVALID: 400,
+  // @ultimat3/auth — saml IdP metadata has no entity id, HTTP-Redirect sign-on endpoint or signing certificate
+  X_SAML_METADATA_INVALID: 500,
+  // @ultimat3/auth — the URL named an identity provider the sso routes were not given
+  X_IDENTITY_PROVIDER_UNKNOWN: 404,
 } satisfies Readonly<Record<string, number>>;

package/src/error-map-tier-3.ts

@@ -127,4 +127,18 @@ export const TIER_3_ERROR_STATUS = {
   X_METER_EXCEEDED: 429,
   // @ultimat3/action — an action's meter cannot be counted against
   X_METER_INVALID: 500,
+  // @ultimat3/realtime — a channel's catch-up read decides with another policy
+  X_CHANNEL_CATCHUP_POLICY_MISMATCH: 500,
+  // @ultimat3/jobs — withLock could not take the lock within its wait bound
+  X_LOCK_NOT_ACQUIRED: 409,
+  // @ultimat3/jobs — a lock withLock held expired before its work finished
+  X_LOCK_LOST: 409,
+  // @ultimat3/jobs — withLock found no lease store to hold the lock in
+  X_LOCK_STORE_MISSING: 500,
+  // @ultimat3/jobs — a ledger posting does not sum to zero in every currency
+  X_LEDGER_UNBALANCED: 422,
+  // @ultimat3/jobs — a ledger entry is not a whole-minor Money amount on a named account
+  X_LEDGER_ENTRY_INVALID: 422,
+  // @ultimat3/jobs — a ledger posting key is already stored with other entries
+  X_LEDGER_POSTING_CONFLICT: 409,
 } satisfies Readonly<Record<string, number>>;

package/src/error-map-tier-4.ts

@@ -180,4 +180,19 @@ export const TIER_4_ERROR_STATUS = {
   X_MCP_TENANT_REQUIRED: 400,
   // @ultimat3/mcp — the tenant of an MCP call could not be resolved
   X_MCP_TENANT_UNRESOLVED: 500,
+  // @ultimat3/scraping — pdf() has no origin to render the route on
+  X_SCRAPE_PDF_ORIGIN_MISSING: 500,
+  // @ultimat3/scraping — a pdf() route is not a path on this app
+  X_SCRAPE_PDF_ROUTE_INVALID: 500,
+  // @ultimat3/scraping — the route pdf() printed answered an error status
+  X_SCRAPE_PDF_ROUTE_FAILED: 502,
+  // @ultimat3/scraping — the raw-CDP browser (`@ultimat3/scraping/cdp`), reached by a request
+  // through pdf(): no browser on this host and one that never started are this server's 503; a
+  // refused call is the upstream browser's 502, an unanswered one its 504.
+  X_CDP_BROWSER_MISSING: 503,
+  X_CDP_LAUNCH_FAILED: 503,
+  X_CDP_CALL_FAILED: 502,
+  X_CDP_TIMEOUT: 504,
+  // @ultimat3/scraping — every pdf() render slot stayed busy past the queue deadline
+  X_SCRAPE_PDF_BUSY: 503,
 } satisfies Readonly<Record<string, number>>;

package/src/error-titles.ts

@@ -39,6 +39,7 @@ export const HTTP_OWNED_ERROR_CODES = [
   'X_BEARER_MOUNT_INVALID',
   'X_RATE_LIMIT_STORE_TIMEOUT',
   'X_EXERCISE_REQUEST_INVALID',
+  'X_BODY_TOO_LARGE',
 ] as const;
 
 export type HttpOwnedErrorCode = (typeof HTTP_OWNED_ERROR_CODES)[number];
@@ -75,6 +76,7 @@ export const HTTP_ERROR_TITLES: Readonly<Record<HttpOwnedErrorCode, string>> = {
   X_BEARER_MOUNT_INVALID: 'a bearer mount declaration cannot be served as written',
   X_RATE_LIMIT_STORE_TIMEOUT: 'the shared rate-limit store did not answer inside its own deadline',
   X_EXERCISE_REQUEST_INVALID: "an exercise entry's request is not one a browser could send",
+  X_BODY_TOO_LARGE: 'request body over the transport ceiling',
 };
 
 // Registered at module load, unconditionally, in one call, so core's registry renders OUR title

package/src/errors.ts

@@ -6,6 +6,7 @@ import { deniedCallerFix, renderFixShellArg, renderThrowable, UltimateError } fr
 // `sideEffects` lists, imported bare here and from the barrel — so this module is side-effect-free
 // and a chunk keeps only the classes it constructs. Re-exported: every name still reads from here.
 import './error-titles';
+import { routineRefusal } from './error-log-level';
 import { HTTP_OWNED_ERROR_CODES } from './error-titles';
 
 export {
@@ -143,12 +144,15 @@ export const bearerMountInvalid = (prefix: string, reason: string): HttpError =>
     fix: "declare mounts: [{ prefix: '/v1', scopes: { 'cases:read': ['caseList'] }, resolveToken }] in defineApi({ http }) — a prefix of lowercase segments that is not /api or /_x, naming only registered actions and queries (x routes --json lists them)",
   });
 
+/** No actor on a required route: the routine login wall, logged at `info` (`routineRefusal`). */
 export const unauthenticated = (pathname: string): HttpError =>
-  new HttpError({
-    code: 'X_UNAUTHENTICATED',
-    cause: `${pathname} declares auth: 'required' and no actor was resolved`,
-    fix: "send a session cookie or Authorization header, or set meta.auth to 'public'",
-  });
+  routineRefusal(
+    new HttpError({
+      code: 'X_UNAUTHENTICATED',
+      cause: `${pathname} declares auth: 'required' and no actor was resolved`,
+      fix: "send a session cookie or Authorization header, or set meta.auth to 'public'",
+    }),
+  );
 
 /**
  * `x policy explain` resolves a policy SUBJECT — a permission, an action name or a query name.

package/src/hooks.ts

@@ -4,6 +4,7 @@
 // found. All three are declared structurally, which keeps the import boundary intact and keeps
 // the pipeline testable.
 import type { Actor, UltimateError } from '@ultimat3/core';
+import { assert, finiteCount } from '@ultimat3/core';
 import type { RequestContext } from './context';
 import type { OverlayNotice } from './overlay';
 import type { UltimateRequest } from './request';
@@ -79,15 +80,57 @@ export type Authenticator = NonNullable<ServerHooks['authenticate']>;
  * place both are in scope, and that is where the wire belongs.
  */
 let configured: Authenticator | undefined;
+let credentialTtl: number | undefined;
 
-export const configureAuthenticator = (authenticate: Authenticator): void => {
+/**
+ * The longest `credentialTtlMs` may be: the `sync` node's own re-check window. The option may only
+ * SHORTEN how long a websocket grant stands — a longer one turns off the re-check that makes
+ * `logout`, `revokeSession` and `disableUser` close a socket, for as long as the token lives.
+ */
+export const MAX_CREDENTIAL_TTL_MS = 5 * 60_000;
+
+export interface AuthenticatorOptions {
+  /**
+   * How long an identity this authenticator resolved may stand on a LONG-LIVED connection — a
+   * websocket, which carries no request to re-authenticate — before the host asks again. The
+   * credential's lifetime is this function's fact (it knows what a token is worth), so it is
+   * declared here and not as a second authenticator on the boot. Omitted, the host's own default
+   * (the `sync` node's five minutes). A whole number of milliseconds, 1 to `MAX_CREDENTIAL_TTL_MS`.
+   */
+  readonly credentialTtlMs?: number;
+}
+
+/**
+ * Declare the app's authenticator, and with it what its credentials are worth. A second call
+ * replaces the first WHOLE — a lifetime left over from an earlier declaration would be a fact
+ * about a function that no longer answers.
+ */
+export const configureAuthenticator = (
+  authenticate: Authenticator,
+  options: AuthenticatorOptions = {},
+): void => {
+  // Screened BEFORE the swap, so a refused call leaves the previous declaration standing.
+  const ttl =
+    options.credentialTtlMs === undefined
+      ? undefined
+      : finiteCount('configureAuthenticator', 'credentialTtlMs', options.credentialTtlMs, 1);
+  assert(
+    ttl === undefined || ttl <= MAX_CREDENTIAL_TTL_MS,
+    `configureAuthenticator credentialTtlMs is ${String(ttl)}, past the ${String(MAX_CREDENTIAL_TTL_MS)}ms re-check window — a longer grant keeps a revoked actor's websocket open for as long as the token lives`,
+    `credentialTtlMs: ${String(MAX_CREDENTIAL_TTL_MS)}   # or less: it shortens the sync re-check, never lengthens it`,
+  );
   configured = authenticate;
+  credentialTtl = ttl;
 };
 
 /** What a host passes as `hooks.authenticate`. `undefined` means every request is anonymous. */
 export const configuredAuthenticator = (): Authenticator | undefined => configured;
 
+/** The declared `credentialTtlMs`, or `undefined` for "the host's default". */
+export const configuredCredentialTtlMs = (): number | undefined => credentialTtl;
+
 /** Test seam. Production configures once at boot and never unconfigures. */
 export const resetAuthenticator = (): void => {
   configured = undefined;
+  credentialTtl = undefined;
 };