@ultimat3/http 21.0.0 → 22.1.0

package/README.md

@@ -67,7 +67,7 @@ asserts the order; `/_x` renders it. Ordering rules worth restating:
 
 | Rule | Reason |
 |---|---|
-| admit second | a draining or saturated process refuses before any work — no route match, no auth, no body |
+| admit second | a stopped or saturated process refuses before any work — no route match, no auth, no body; a DRAINING one serves and closes the connection |
 | auth before rate-limit | limiter keys per actor/tenant, not per NAT address |
 | csrf after auth | only a caller holding an AMBIENT credential can be forged into; bearer and anonymous are exempt |
 | csrf before body | a forged write never makes the server allocate its payload |
@@ -80,7 +80,8 @@ What the lifecycle refuses on the caller's behalf, `As of 2026-08`:
 | Guard | Answer |
 |---|---|
 | a body past `bodyLimitBytes` | read through the stream and abandoned the instant the running total crosses the limit — `content-length` or not, multipart included — as `X_BODY_INVALID` |
-| a request carrying an identity on an `auth: 'public'` route | `cache-control: private`, never `s-maxage`; an anonymous one is shared-cacheable and keyed `vary: accept-language, cookie, x-timezone`. **Whatever the handler wrote**, `As of 2026-08-23`: the `cache-headers` stage REVIEWS a declared `cache-control` instead of standing down, because `@ultimat3/render`'s `ssrHeaders` offers every page without a `policy` to a CDN for 30s. An `immutable` answer is left alone — a content-addressed body is a function of its URL |
+| a request carrying an identity on an `auth: 'public'` route | `cache-control: private`, never `s-maxage`; an anonymous one is shared-cacheable and keyed `vary: accept-language, cookie, x-timezone`. **Whatever the handler wrote**, `As of 2026-08-23`: the `cache-headers` stage REVIEWS a declared `cache-control` instead of standing down, because `@ultimat3/render`'s `ssrHeaders` offers every page without a `policy` to a CDN for 30s. An `immutable` answer is left alone — a content-addressed body is a function of its URL. **A declared hint too**, `As of 2026-09-23`: `meta.cache` / `ctx.cache` with `mode: 'public'` becomes `private` for a signed-in actor (`reviewedHint`) |
+| any 5xx whose code did not opt in with `registerProblemMeta({ CODE: { publicCause: true } })` | `As of 2026-09-23`, not only an undeclared one — `X_DB_STATEMENT_FAILED` has a status row and served the Postgres message and the SQL. The framework opts in `X_DRAINING`, `X_OVERLOADED`, `X_FLIGHT_GATE_OVERLOADED` and `X_TIMEOUT`, whose cause is the instruction. The rest: |
 | a 5xx nobody declared a status for | the code, the request id and a `fix:`; never the exception's own text. `error-page.ts` locked the browser out of it, and the problem document handed the same string to an agent — a driver's DSN, the row Postgres rejected. The real text goes to the log and the error report. `dev: true` renders it in full |
 | a `security.csp.extend` key that is not a CSP token, or a source carrying `;`, `,` or a space | `X_CSP_DIRECTIVE_INVALID` at `defineHttpConfig` — `{ 'x; script-src *': [] }` is a second directive nobody declared |
 | a repeated form field | a LIST, exactly as a repeated query parameter is. One collector for query, urlencoded and multipart; `Object.fromEntries` kept the last value, so a checkbox group reached the schema as one string |
@@ -97,7 +98,11 @@ What the lifecycle refuses on the caller's behalf, `As of 2026-08`:
 | a credentialed unsafe method that cannot be shown to be same-origin | `X_CSRF_BLOCKED` (403). `sec-fetch-site: same-origin`, `Origin` equal to this app, or an EXACT listing in `cors.origins` — anything else is refused before the body is read. `origins: ['*']` lists nobody here: `'*'` is a value for the response header, not a per-origin allowance |
 | a request past `requestTimeoutMs` (30s) | `ctx.signal` aborts and the socket is answered `X_TIMEOUT` (504); a caller may shorten the deadline with `x-request-timeout-ms`, never lengthen it |
 | the caller going away mid-request | `ctx.signal` aborts on the inbound `Request.signal` too, so a closed tab unwinds cooperative work instead of holding its pool slot for the rest of the budget. Both halves are one signal (`AbortSignal.any`), and `requestTimeoutMs: 0` still delivers the caller's |
-| a request while the process is draining | `X_DRAINING` (503) + `retry-after`, which is what `isDraining()` was always documented to do here and had no reader for |
+| a request while the process is draining | SERVED, with `connection: close` so the client's next request lands on another pod, `As of 2026-09-23` — refusing it failed 598 of 7,690 requests across one helm upgrade on kind, every one on a kept-alive connection inside the readiness grace. Only a STOPPED process (resources closed) answers `X_DRAINING` (503) + `retry-after` |
+| SIGTERM | `/readyz` answers 503 at once, the listener stays open for `drain.readinessGraceMs` (core; 5000 ms outside development/test, 0 inside), then closes and the drain runs. Pass `createServer({ …, drain: appConfig.drain })` so `app.config.ts`'s value is the one applied; omitted, core's default holds and a `configureLifecycle({ readinessGraceMs })` stands |
+| `?locale=es` | the locale source that outranks the cookie and the header (`resolveLocale`'s order), `As of 2026-09-23` — documented in `wiki/I18n.md` and never read before |
+| a 4xx | logged at `warn` (401, 403, 429) or `info` (every other 4xx); only a 5xx is an `error` line |
+| an `x-forwarded-client-cert` value in quotes | unescaped ONCE, after the pairs are split — `Subject="O=Acme; Inc,CN=svc-one"` is that whole subject, not `O=Acme` |
 | a request past `maxInflight` (1000) | `X_OVERLOADED` (503) + `retry-after`, shed in the `admit` stage before any work |
 
 `handle()` resolves to a Response, always — a stage that throws after the handler, or while
@@ -354,6 +359,9 @@ import { registerErrorStatus, registerProblemMeta } from '@ultimat3/http';
 
 registerErrorStatus({ X_SESSION_CHECKOUT_BUSY: 409 });
 registerProblemMeta({ X_SESSION_CHECKOUT_BUSY: ['sessionId', 'title', 'state'] });
+// A 5xx whose cause is written for the caller, and may be shown in production:
+registerProblemMeta({ X_BILLING_DOWN: { publicCause: true } });
+// Both at once: { keys: ['sessionId'], publicCause: true }
 ```
 
 The document then carries `meta: { sessionId, title, state }` — the declared keys that are set,
@@ -366,6 +374,15 @@ as is `issues`, which has its own top-level home. `@ultimat3/action`'s typed cli
 member back on the rebuilt error's `meta`, so an island reads `error.meta.sessionId` where it
 used to run a regex over `cause`.
 
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `HttpError` | any `HttpErrorCode` — `HTTP_ERROR_CODES` | `src/errors.ts` |
+
 ## Boundaries
 
 Tier 2. Imports `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/i18n` and `@ultimat3/time` —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "21.0.0",
+  "version": "22.1.0",
   "description": "Owned request lifecycle over Bun.serve: router, ordered pipeline, problem+json errors",
   "license": "MIT",
   "type": "module",
@@ -31,9 +31,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "21.0.0",
-    "@ultimat3/i18n": "21.0.0",
-    "@ultimat3/schema": "21.0.0",
-    "@ultimat3/time": "21.0.0"
+    "@ultimat3/core": "22.1.0",
+    "@ultimat3/i18n": "22.1.0",
+    "@ultimat3/schema": "22.1.0",
+    "@ultimat3/time": "22.1.0"
   }
 }

package/src/cache-policy.ts

@@ -40,3 +40,12 @@ export const defaultCache = (route: Route | undefined, actor: Actor): CacheHint
   if (!isAnonymous(actor)) return PRIVATE_CACHE;
   return { mode: 'public', maxAgeSeconds: 0, sMaxAgeSeconds: 60, staleWhileRevalidateSeconds: 600 };
 };
+
+/**
+ * A DECLARED hint — `meta.cache` or `ctx.cache` — reviewed against the actor, as a handler's own
+ * header is. `mode: 'public'` on a route answered `public, s-maxage=3600` over a body carrying the
+ * signed-in actor's id, so a CDN served one user's document to every later visitor. `immutable`
+ * is exempt for the reason `offersSharedCache` gives: its body is a function of the URL alone.
+ */
+export const reviewedHint = (hint: CacheHint, actor: Actor): CacheHint =>
+  hint.mode === 'public' && !isAnonymous(actor) ? PRIVATE_CACHE : hint;

package/src/csrf.ts

@@ -5,8 +5,10 @@
 // went through. `setRedirect` exists so those form posts work without JS, which makes them a
 // first-class surface here rather than a legacy one.
 
+import { classifyAddress, proveSameOrigin } from '@ultimat3/core';
 import type { CorsConfig } from './cors';
 import { originListed } from './cors';
+import { HttpError } from './errors';
 
 export type CsrfMode = 'origin' | 'off';
 
@@ -24,9 +26,6 @@ export const DEFAULT_CSRF: CsrfConfig = { mode: 'origin' };
 /** Methods with no side effects, per RFC 9110. A CSRF check on these is a check on nothing. */
 const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS', 'TRACE']);
 
-/** The complete `Sec-Fetch-Site` vocabulary. Anything else was written by a non-browser. */
-const KNOWN_SITES = new Set(['same-origin', 'same-site', 'cross-site', 'none']);
-
 export interface CsrfCheckInput {
   readonly method: string;
   /** The origin this app was reached on — scheme from `ctx.https`, host from the request URL. */
@@ -58,31 +57,49 @@ export const checkCsrf = (input: CsrfCheckInput): CsrfVerdict => {
   if (input.anonymous) return { ok: true };
   if (input.hasAuthorizationHeader) return { ok: true };
 
-  const site = input.secFetchSite;
-  if (site === 'same-origin' || site === 'none') return { ok: true };
-  if (input.origin === input.selfOrigin) return { ok: true };
+  // The rule itself is core's, shared with the sync node's upgrade: one answer to "did this
+  // come from this app?" on every surface an ambient credential reaches.
+  //
   // `originListed`, never `allowedOrigin`: that one answers the RESPONSE header, and for
   // `origins: ['*'], credentials: false` — the only wildcard `assertCorsConfig` admits — its
   // answer is `'*'`, which is not null and so read as "this origin is one we allow". A
   // credentialed cross-site POST from evil.test was therefore accepted by the check that exists
   // to refuse exactly it. An exact match is the only allowance a write may be built on.
-  if (originListed(input.cors, input.origin)) return { ok: true };
-  // Only the four values a browser can send are quoted back. Anything else is a client that
-  // wrote the header itself, and echoing what it wrote is how a rejected value reaches the log
-  // store and the response body — the same defect the error-map stage's log line had.
-  if (site !== null) {
-    const known = KNOWN_SITES.has(site) ? site : 'a value no browser sends';
-    return { ok: false, reason: `the request reported sec-fetch-site: ${known}` };
-  }
-  return {
-    ok: false,
-    reason:
-      input.origin === null
-        ? 'the request carried neither sec-fetch-site nor origin, so it cannot be shown to be same-origin'
-        : 'the origin it declares is not this app and is not listed in http.cors.origins',
-  };
+  return proveSameOrigin({
+    selfOrigins: [input.selfOrigin],
+    origin: input.origin,
+    secFetchSite: input.secFetchSite,
+    listed: (origin) => originListed(input.cors, origin),
+    listName: 'http.cors.origins',
+  });
 };
 
 /** The origin a browser compares against — the PUBLIC one, so a TLS-terminating proxy agrees. */
 export const selfOrigin = (url: URL, https: boolean): string =>
   `${https ? 'https' : 'http'}://${url.host}`;
+
+/**
+ * A write that arrived with the browser's ambient credential and could not be shown to come from
+ * this app. Never a 401: the caller IS signed in, which is precisely the problem.
+ *
+ * From a LOOPBACK `ip` the caller is `curl` against `x dev`: it sends neither
+ * header, and the remedies below name a token or a config change dev does not need. The header a
+ * browser would send is the whole repair there, and it is safe to hand out: CSRF defends a BROWSER
+ * from a hostile page, and a client that can set headers is not one a page can drive.
+ */
+export const csrfBlocked = (
+  pathname: string,
+  reason: string,
+  ip: string | null = null,
+): HttpError =>
+  ip !== null && classifyAddress(ip) === 'loopback'
+    ? new HttpError({
+        code: 'X_CSRF_BLOCKED',
+        cause: `${pathname} refused a credentialed write: ${reason}`,
+        fix: "curl -H 'sec-fetch-site: same-origin' -X POST http://localhost:3000/the-path-above   # a local client proves same-origin the way a browser does; the session cookie still decides who is calling",
+      })
+    : new HttpError({
+        code: 'X_CSRF_BLOCKED',
+        cause: `${pathname} refused a credentialed write: ${reason}`,
+        fix: "call it with an Authorization header instead of the session cookie, add the calling origin to configureHttp({ cors: { origins } }), or configureHttp({ csrf: { mode: 'off' } }) if this app has no cookie session at all",
+      });

package/src/error-facts.ts

@@ -11,9 +11,9 @@ import {
   stringField,
 } from '@ultimat3/core';
 import type { ValidationIssue } from '@ultimat3/schema';
-import { declaredStatusFor, statusFor } from './error-map';
+import { declaredStatusFor, statusFor } from './error-status';
 import { HTTP_ERROR_TITLES } from './errors';
-import { type ProblemMeta, problemMetaKeysFor, wireMeta } from './problem-meta';
+import { hasPublicCause, type ProblemMeta, problemMetaKeysFor, wireMeta } from './problem-meta';
 
 /** Everything a renderer (problem+json, overlay, terminal) needs from a throwable. */
 export interface ErrorFacts {
@@ -300,11 +300,17 @@ export const toProblem = (
 ): ProblemDocument => {
   const facts = factsOf(error);
   const opaque = meta.dev !== true && isUnclassifiedFailure(facts.code, facts.status);
+  // Wider than `opaque`: EVERY 5xx cause is the server's own business unless its code declared it
+  // public (`hasPublicCause`). A status row made `X_DB_STATEMENT_FAILED` "classified", so its cause
+  // — the Postgres message and the statement — was served in production 500 bodies. The title
+  // stays: a registered title is framework prose, never the server's words.
+  const hidden =
+    opaque || (meta.dev !== true && facts.status >= 500 && !hasPublicCause(facts.code));
   // Dropped under EXACTLY the condition that blanks `title`, `detail` and `cause`. An issue list
   // on a failure nobody classified is precisely the internal detail `INTERNAL_CAUSE` exists to
   // 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 = opaque ? undefined : issuesOf(error);
+  const issues = hidden ? undefined : issuesOf(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);
@@ -312,10 +318,10 @@ export const toProblem = (
     type: problemTypeFor(facts.code),
     title: opaque ? INTERNAL_TITLE : facts.title,
     status: facts.status,
-    detail: opaque ? INTERNAL_CAUSE : facts.cause,
+    detail: hidden ? INTERNAL_CAUSE : facts.cause,
     instance: meta.instance,
     code: facts.code,
-    cause: opaque ? INTERNAL_CAUSE : facts.cause,
+    cause: hidden ? INTERNAL_CAUSE : facts.cause,
     fix: facts.fix,
     docs: facts.docs,
     requestId: meta.requestId,

package/src/error-log-level.ts

@@ -0,0 +1,12 @@
+// 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.
+
+/**
+ * `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.
+ */
+export const errorLogLevel = (status: number): 'error' | 'warn' | 'info' => {
+  if (status >= 500) return 'error';
+  return status === 401 || status === 403 || status === 429 ? 'warn' : 'info';
+};

package/src/error-map.ts

@@ -1,8 +1,8 @@
 // The one place a framework error code becomes an HTTP status. A table, not a
 // switch chain: adding a code elsewhere in the framework means adding a row here,
 // and a missing row is a loud 500 rather than a silently wrong 200.
-// Rendering a throwable for a reader is `error-facts.ts`; this file answers only the status.
-import { errorStatusInvalid } from './errors';
+// Rendering a throwable for a reader is `error-facts.ts`; reading this table, and the app's own
+// half of it, is `error-status.ts`. This file is the table.
 
 /**
  * code -> status. Codes owned by other packages are listed here on purpose: HTTP
@@ -215,6 +215,12 @@ export const ERROR_STATUS = {
   // 500, and it should page: a queue holding rows this build cannot read is an operator's
   // problem, and nothing the caller sent is wrong.
   X_JOB_ROW_STATUS_UNKNOWN: 500,
+  // A requeue of a job that is still live — the admin panel's retry, `x jobs retry` over HTTP. The
+  // job's STATE is wrong, not the server: 409, like `X_STORAGE_QUARANTINED`.
+  X_JOB_NOT_REQUEUEABLE: 409,
+  // Thrown by `job()` at declaration, while modules load; no request is answered with it. The row
+  // exists for `X_ACTION_JOB_UNBRIDGED`'s reason: the table is closed, and it is a 500 anyway.
+  X_JOB_DECLARATION_INVALID: 500,
   // Thrown by `registerJobs()` while the app's modules load, so no request is ever answered with
   // it either — the row exists for the reason `X_CORS_CONFIG_INVALID`'s does: this table is the
   // closed one, and a code with no row is a 500 anyway.
@@ -277,6 +283,9 @@ export const ERROR_STATUS = {
   // paging failure that is NOT the caller's: the fix is an edit to the read's own select, nothing
   // the client sends changes the answer, and the report to the on-call monitor is the point.
   X_QUERY_NOT_PAGEABLE: 500,
+  // A read filtering or sorting on a column its loader never selected: the fix is the loader's
+  // `select`, nothing the caller sends changes it — the same server-side decision as the row above.
+  X_QUERY_COLUMN_UNSELECTED: 500,
   // @ultimat3/i18n — a well-formed tag outside the set this app ships, asserted on a value the
   // caller supplied (`assertSupportedLocale`). 400 rather than 406: the http `locale` stage
   // negotiates `Accept-Language` and never throws, so the tag that reaches here came from a path,
@@ -320,6 +329,9 @@ export const ERROR_STATUS = {
   // 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.
   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.
+  X_STORAGE_NOT_PENDING: 409,
   // 404, deliberately NOT 403: the org check fires before anything is read, so answering
   // "forbidden" would confirm that a key exists to the one caller who must not learn it.
   X_STORAGE_ORG_MISMATCH: 404,
@@ -411,6 +423,13 @@ export const ERROR_STATUS = {
   X_LOCAL_STORE_UNAVAILABLE: 500,
   X_MUTATOR_CLOCK_MISSING: 500,
   X_REALTIME_UNINSTALLED: 500,
+  // Boot-time: a realtime config and its environment that disagree refuse before any request.
+  X_REALTIME_TOPOLOGY: 500,
+  // The replicator's own Postgres connection failed TLS. A role that never answers a request, so the
+  // row keeps the table closed at 500, beside `X_REALTIME_TOPOLOGY`.
+  X_REPLICATION_TLS: 500,
+  // A browser page on a foreign origin asked for a socket — refused, not unauthenticated: 403.
+  X_SOCKET_ORIGIN_REFUSED: 403,
   X_RECORD_KEY_MISSING: 500,
   X_RECORD_REJECTED: 500,
   X_SYNC_UNCONFIGURED: 500,
@@ -420,80 +439,3 @@ export const ERROR_STATUS = {
   // has to be a compile error rather than an `undefined` a test then asserts `toBeNumber()` on.
   // Read it by a code the framework did not mint through `statusFor`, never by index.
 } satisfies Readonly<Record<string, number>>;
-
-export const DEFAULT_STATUS = 500;
-
-/**
- * The framework's row for a code, or `undefined` — through `Object.hasOwn`, never `[code]`.
- *
- * `code` is a STRING read off a throwable this package did not build, and `ERROR_STATUS` is an
- * object literal, so it holds every name on `Object.prototype`: an app throwing
- * `{ code: 'toString' }` read a FUNCTION out of this table. `statusFor` handed it to
- * `new Response(body, { status })` — a `RangeError` raised inside `recoverWith`'s fallback, the
- * one frame with nothing above it, so `Pipeline.handle` REJECTED against its own contract.
- * `scripts/error-map.ts` reads the same table this way already.
- */
-const BY_CODE: Readonly<Record<string, number>> = ERROR_STATUS;
-
-const frameworkStatus = (code: string): number | undefined =>
-  Object.hasOwn(BY_CODE, code) ? BY_CODE[code] : undefined;
-
-/**
- * Statuses for codes the APP owns. The table above is closed — it has to be, it is the
- * framework's own contract — and every code outside it fell to 500, so a wrong password was an
- * incident: `pipeline.ts` reports `status >= 500` to the error monitor, and a user's typo paged
- * whoever was on call. This is the app's half of the same table, kept separate so a registration
- * can never move `X_FORBIDDEN` off 403.
- */
-const APP_ERROR_STATUS = new Map<string, number>();
-
-/**
- * Declare the status for the codes this app throws. Call it once at boot, beside the module
- * that declares the codes — importing that module IS the registration, the convention
- * `registerActions` and `registerErrorCodes` already use.
- *
- * ```ts
- * registerErrorStatus({ X_CREDENTIALS_INVALID: 401, X_SIGNUP_CLOSED: 403 });
- * ```
- */
-export const registerErrorStatus = (statuses: Readonly<Record<string, number>>): void => {
-  for (const [code, status] of Object.entries(statuses)) {
-    if (!Number.isInteger(status) || status < 100 || status > 599) {
-      throw errorStatusInvalid(code, `${String(status)} is not an HTTP status (100-599)`);
-    }
-    // The framework's own codes are not negotiable: an app that could map `X_UNAUTHENTICATED`
-    // to 200 would be an app whose 401 contract every client already depends on, changed.
-    // Through `frameworkStatus`, so this refusal cannot answer for a code the framework does not
-    // own: `registerErrorStatus({ toString: 401 })` was rejected with a cause reading `the
-    // framework already maps it to function toString() { [native code] }`.
-    const framework = frameworkStatus(code);
-    if (framework !== undefined) {
-      throw errorStatusInvalid(code, `the framework already maps it to ${framework}`);
-    }
-    const existing = APP_ERROR_STATUS.get(code);
-    if (existing !== undefined && existing !== status) {
-      throw errorStatusInvalid(code, `already registered as ${existing} by this app`);
-    }
-    APP_ERROR_STATUS.set(code, status);
-  }
-};
-
-/** Test seam. Production registers once at boot and never unregisters. */
-export const resetErrorStatus = (): void => APP_ERROR_STATUS.clear();
-
-/**
- * The status SOMEBODY declared for a code — the framework or the app — or `undefined` when
- * nobody did. The two questions `statusFor` used to answer at once are separate on purpose:
- * "what do we answer" is always a number, and "did anyone classify this" is what `error-facts.ts`
- * reads to decide whether a 5xx may carry the throwable's own words back to the caller.
- *
- * Framework table first: `registerErrorStatus` already refuses those codes, so the order is
- * belt-and-braces — but it is the belt that makes "the framework's statuses are fixed" true
- * even if a future caller reaches the map some other way.
- * `APP_ERROR_STATUS` is a `Map`, which is why its half never had `frameworkStatus`'s defect —
- * prefer one for anything keyed by a value a caller chose.
- */
-export const declaredStatusFor = (code: string): number | undefined =>
-  frameworkStatus(code) ?? APP_ERROR_STATUS.get(code);
-
-export const statusFor = (code: string): number => declaredStatusFor(code) ?? DEFAULT_STATUS;

package/src/error-page.ts

@@ -124,9 +124,17 @@ const hrefFor = (copy: ErrorPageCopy, input: ErrorPageInput): string => {
     return input.signInPath;
   // A retry has to be the page the visitor was on; with no request behind the page there is no
   // such address, so it degrades to the one link that is always right.
-  return (copy.action === 'retry' ? input.path : undefined) ?? '/';
+  return copy.action === 'retry' && input.path !== undefined ? sameOriginPath(input.path) : '/';
 };
 
+/**
+ * The path as a link that cannot leave this origin. A request for `//evil.com/x` has that
+ * pathname, and `href="//evil.com/x"` is protocol-relative — the retry button on the 503 served
+ * while draining sent the visitor to another host. A browser reads `\` as `/` in an http href,
+ * so the leading run of either collapses to one `/`.
+ */
+const sameOriginPath = (path: string): string => path.replace(/^[/\\]*/, '/');
+
 const link = (href: string, label: string): string =>
   `<a href="${escapeHtml(href)}">${escapeHtml(label)}</a>`;
 

package/src/error-status.ts

@@ -0,0 +1,82 @@
+// Reading the status table: the framework's row for a code through `Object.hasOwn`, the app's
+// own codes beside it (`registerErrorStatus`), and the answer a response gets. The table itself is
+// `error-map.ts`; split out when the table outgrew the file that also read it.
+import { ERROR_STATUS } from './error-map';
+import { errorStatusInvalid } from './errors';
+
+export const DEFAULT_STATUS = 500;
+
+/**
+ * The framework's row for a code, or `undefined` — through `Object.hasOwn`, never `[code]`.
+ *
+ * `code` is a STRING read off a throwable this package did not build, and `ERROR_STATUS` is an
+ * object literal, so it holds every name on `Object.prototype`: an app throwing
+ * `{ code: 'toString' }` read a FUNCTION out of this table. `statusFor` handed it to
+ * `new Response(body, { status })` — a `RangeError` raised inside `recoverWith`'s fallback, the
+ * one frame with nothing above it, so `Pipeline.handle` REJECTED against its own contract.
+ * `scripts/error-map.ts` reads the same table this way already.
+ */
+const BY_CODE: Readonly<Record<string, number>> = ERROR_STATUS;
+
+const frameworkStatus = (code: string): number | undefined =>
+  Object.hasOwn(BY_CODE, code) ? BY_CODE[code] : undefined;
+
+/**
+ * Statuses for codes the APP owns. The table above is closed — it has to be, it is the
+ * framework's own contract — and every code outside it fell to 500, so a wrong password was an
+ * incident: `pipeline.ts` reports `status >= 500` to the error monitor, and a user's typo paged
+ * whoever was on call. This is the app's half of the same table, kept separate so a registration
+ * can never move `X_FORBIDDEN` off 403.
+ */
+const APP_ERROR_STATUS = new Map<string, number>();
+
+/**
+ * Declare the status for the codes this app throws. Call it once at boot, beside the module
+ * that declares the codes — importing that module IS the registration, the convention
+ * `registerActions` and `registerErrorCodes` already use.
+ *
+ * ```ts
+ * registerErrorStatus({ X_CREDENTIALS_INVALID: 401, X_SIGNUP_CLOSED: 403 });
+ * ```
+ */
+export const registerErrorStatus = (statuses: Readonly<Record<string, number>>): void => {
+  for (const [code, status] of Object.entries(statuses)) {
+    if (!Number.isInteger(status) || status < 100 || status > 599) {
+      throw errorStatusInvalid(code, `${String(status)} is not an HTTP status (100-599)`);
+    }
+    // The framework's own codes are not negotiable: an app that could map `X_UNAUTHENTICATED`
+    // to 200 would be an app whose 401 contract every client already depends on, changed.
+    // Through `frameworkStatus`, so this refusal cannot answer for a code the framework does not
+    // own: `registerErrorStatus({ toString: 401 })` was rejected with a cause reading `the
+    // framework already maps it to function toString() { [native code] }`.
+    const framework = frameworkStatus(code);
+    if (framework !== undefined) {
+      throw errorStatusInvalid(code, `the framework already maps it to ${framework}`);
+    }
+    const existing = APP_ERROR_STATUS.get(code);
+    if (existing !== undefined && existing !== status) {
+      throw errorStatusInvalid(code, `already registered as ${existing} by this app`);
+    }
+    APP_ERROR_STATUS.set(code, status);
+  }
+};
+
+/** Test seam. Production registers once at boot and never unregisters. */
+export const resetErrorStatus = (): void => APP_ERROR_STATUS.clear();
+
+/**
+ * The status SOMEBODY declared for a code — the framework or the app — or `undefined` when
+ * nobody did. The two questions `statusFor` used to answer at once are separate on purpose:
+ * "what do we answer" is always a number, and "did anyone classify this" is what `error-facts.ts`
+ * reads to decide whether a 5xx may carry the throwable's own words back to the caller.
+ *
+ * Framework table first: `registerErrorStatus` already refuses those codes, so the order is
+ * belt-and-braces — but it is the belt that makes "the framework's statuses are fixed" true
+ * even if a future caller reaches the map some other way.
+ * `APP_ERROR_STATUS` is a `Map`, which is why its half never had `frameworkStatus`'s defect —
+ * prefer one for anything keyed by a value a caller chose.
+ */
+export const declaredStatusFor = (code: string): number | undefined =>
+  frameworkStatus(code) ?? APP_ERROR_STATUS.get(code);
+
+export const statusFor = (code: string): number => declaredStatusFor(code) ?? DEFAULT_STATUS;

package/src/errors.ts

@@ -440,17 +440,6 @@ export const overloaded = (inflight: number, ceiling: number): HttpError =>
     fix: 'retry after the Retry-After header; to serve more at once call configureHttp({ maxInflight: 2000 }) at module scope in a file under apps/*/, and add replicas to match',
   });
 
-/**
- * A write that arrived with the browser's ambient credential and could not be shown to come from
- * this app. Never a 401: the caller IS signed in, which is precisely the problem.
- */
-export const csrfBlocked = (pathname: string, reason: string): HttpError =>
-  new HttpError({
-    code: 'X_CSRF_BLOCKED',
-    cause: `${pathname} refused a credentialed write: ${reason}`,
-    fix: "call it with an Authorization header instead of the session cookie, add the calling origin to configureHttp({ cors: { origins } }), or configureHttp({ csrf: { mode: 'off' } }) if this app has no cookie session at all",
-  });
-
 /**
  * The request ran past its deadline. `X_TIMEOUT` is borrowed (see `HTTP_BORROWED_ERROR_CODES`)
  * and already maps to 504. The abort fires first for cooperative code; this is what the socket

package/src/index.ts

@@ -16,7 +16,7 @@ export type { AppHttpConfig, BootOwnedHttpKey } from './app-config';
 export { configuredHttp, configureHttp, mergeHttpConfig, resetHttpConfig } from './app-config';
 export { NEXT_PARAM, nextAfterSignIn, signInRedirect } from './auth-redirect';
 export type { HttpConfig, HttpConfigInput } from './config';
-export { defineHttpConfig, MAX_PROXY_HOPS, stripBasePath } from './config';
+export { defineHttpConfig, MAX_PROXY_HOPS } from './config';
 export type { ActorView, RequestContext, RequestContextInit } from './context';
 export {
   actorView,
@@ -29,11 +29,10 @@ export {
   useRequestHeaders,
 } from './context';
 export type { InboundCorrelation } from './correlation';
-export { readCorrelation } from './correlation';
 export type { CorsConfig } from './cors';
 export { allowedOrigin, corsHeaders, DEFAULT_CORS, originListed, preflight } from './cors';
 export type { CsrfCheckInput, CsrfConfig, CsrfMode, CsrfVerdict } from './csrf';
-export { checkCsrf, DEFAULT_CSRF, selfOrigin } from './csrf';
+export { checkCsrf, csrfBlocked } from './csrf';
 export type { Deadline } from './deadline';
 export { REQUEST_TIMEOUT_HEADER, resolveTimeoutMs, startDeadline } from './deadline';
 export type { ErrorFacts, ProblemDocument } from './error-facts';
@@ -44,13 +43,7 @@ export {
   retryAfterOf,
   toProblem,
 } from './error-facts';
-export {
-  DEFAULT_STATUS,
-  ERROR_STATUS,
-  registerErrorStatus,
-  resetErrorStatus,
-  statusFor,
-} from './error-map';
+export { ERROR_STATUS } from './error-map';
 export type {
   ErrorPageAction,
   ErrorPageCopy,
@@ -64,11 +57,16 @@ export {
   renderErrorPage,
   resolveErrorPageCopy,
 } from './error-page';
+export {
+  DEFAULT_STATUS,
+  registerErrorStatus,
+  resetErrorStatus,
+  statusFor,
+} from './error-status';
 export type { HttpErrorCode } from './errors';
 export {
   bodyInvalid,
   buildSkew,
-  csrfBlocked,
   draining,
   errorStatusInvalid,
   finalizeFailed,
@@ -94,29 +92,24 @@ export {
 export type { ForwardedInput, ForwardedSplit } from './forwarded';
 export {
   clientAddress,
-  clientUsedHttps,
-  FORWARDED_CLIENT_CERT,
-  FORWARDED_FOR,
-  FORWARDED_PROTO,
   forwardedElement,
-  forwardedValue,
 } from './forwarded';
 export type { Authenticator, AuthzDecision, ServerHooks } from './hooks';
 export { configureAuthenticator, configuredAuthenticator, resetAuthenticator } from './hooks';
-export { acceptsHtml, escapeHtml } from './html-render';
+export { escapeHtml } from './html-render';
 export type { LocaleConfig, TimeZoneConfig } from './locale';
-export { DEFAULT_LOCALE_CONFIG, DEFAULT_TZ_CONFIG, readCookie } from './locale';
+export { DEFAULT_LOCALE_CONFIG, readCookie } from './locale';
 export type { Middleware } from './middleware';
 export { compose } from './middleware';
 export type { OverlayMeta, OverlayNotice } from './overlay';
-export { overlayResponse, renderOverlay, wantsOverlay } from './overlay';
+export { overlayResponse, wantsOverlay } from './overlay';
 export { OVERLAY_STYLE } from './overlay-style';
 export type { PeerIdentity } from './peer-identity';
 export { peerIdentity } from './peer-identity';
 export type { HandleInit, Pipeline, PipelineDeps } from './pipeline';
 export { createPipeline, PIPELINE_STAGES } from './pipeline';
-export type { ProblemMeta, ProblemMetaValue } from './problem-meta';
-export { MAX_PROBLEM_META_BYTES, registerProblemMeta, resetProblemMeta } from './problem-meta';
+export type { ProblemMeta, ProblemMetaDeclaration, ProblemMetaValue } from './problem-meta';
+export { MAX_PROBLEM_META_BYTES, registerProblemMeta } from './problem-meta';
 export type {
   Bucket,
   MemoryRateLimitStore,
@@ -138,7 +131,6 @@ export {
   rateLimitDecision,
   rateLimitSpends,
   resolveRateLimitConfig,
-  TENANT_SCOPE,
   toBucket,
 } from './rate-limit';
 export { assertRouteBuckets, withRouteBuckets } from './rate-limit-buckets';
@@ -159,10 +151,7 @@ export type {
 } from './rate-limit-postgres';
 export {
   postgresRateLimitStore,
-  SQL_RATE_LIMIT_PURGE,
-  SQL_RATE_LIMIT_RESET,
   SQL_RATE_LIMIT_TABLE,
-  SQL_RATE_LIMIT_TAKE,
 } from './rate-limit-postgres';
 export { setRedirect, takeRedirect } from './redirect';
 export type { QueryValues } from './request';
@@ -196,7 +185,6 @@ export {
   describeRoutes,
   HTTP_METHODS,
   matchRoute,
-  normalizePath,
 } from './router';
 export type { SecurityConfig } from './security-headers';
 export { buildCsp, cspHashSource, DEFAULT_SECURITY, securityHeaders } from './security-headers';