@ultimat3/http 22.15.0 → 24.0.0

package/CLAUDE.md

@@ -14,7 +14,8 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 
 - **Every numeric knob `defineHttpConfig` resolves is screened** (`port`, `bodyLimitBytes`,
   `requestTimeoutMs`, `maxInflight`, `drainTimeoutMs`, `trustedProxyHops`) → `X_CONFIG_INVALID`
-  (borrowed). Helpers carry `Finite` (`assertFiniteCount`, `assertFiniteKeyCap`,
+  (borrowed). `requestTimeoutMs` tops out at `MAX_TIMER_MS` (2^31−1): past it a timer arms ~1 ms.
+  `buildId: null` is a declaration (`=== undefined`, never `??`); `hostname` never reads `HOSTNAME`. Helpers carry `Finite` (`assertFiniteCount`, `assertFiniteKeyCap`,
   `assertFiniteBodyLimit`) so `bun run finite-bounds` sees them; `webhook-verify.ts` and
   `rate-limit.ts` screen their own. **The floor is per option**: `requestTimeoutMs: 0` and
   `maxInflight: 0` are "off"; `trustedProxyHops` floors at 1. `resolveTrustedProxyHops` owns both
@@ -36,6 +37,9 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   (`X_CSP_DIRECTIVE_INVALID`); `buildCsp` builds through a `Map`.
 - **The security headers are built once per `(SecurityConfig, https)`** (`responseSecurityHeaders`, a
   `WeakMap`); a config is never mutated after `defineHttpConfig`. HSTS only when `ctx.https` is affirmed.
+- **A `content-security-policy` the handler set is kept**: the `response` stage APPENDS the app's
+  policy beside it (two policies, both enforced), so a handler can narrow — `sandbox` on a served
+  upload — and never widen. Every other security header is set over the handler's (`stages-csp.test.ts`).
 
 ## Rules — the context
 
@@ -84,26 +88,30 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 - **Every proxy-supplied header goes through `forwardedElement(header, hops)`** — the entry at
   `entries.length - hops`, never `[0]`; a short chain trusts nothing. `trustProxy` defaults to false
   and requires `trustedProxyHops`. `x-forwarded-proto` (HSTS) and Envoy XFCC (`peer-identity.ts`) ride
-  it; `ctx.peer` is `null` unless trusted and is never an actor.
+  it; `ctx.peer` is `null` unless trusted AND `trustClientCertHeader` is declared (appending to
+  XFF is no promise of stripping a client-sent cert header), and is never an actor.
 - **One deadline per request** (`deadline.ts`): `requestTimeoutMs` (30 s, `0` disables), shortenable
   by `x-request-timeout-ms`, never lengthened. `ctx.signal` is the deadline OR the caller going away
   (`AbortSignal.any` with `Request.signal`); `expired` is the timer's alone. `Deadline.deadlineAt` is
   published as core's `ctx.deadlineAt`, which `traceHeaders()` sends onward. Always `deadline.clear()`
-  in the `finally`.
+  in the `finally`. An ask above `MAX_TIMER_MS` is ignored. **A handler that outlives its 504 is held
+  in core's in-flight count** (`beginWork()` in `execute`) until it settles (`pipeline-inflight.test.ts`).
 - **`admit` is the second stage and refuses before ANY work**: past `maxInflight` (1000) is
   `X_OVERLOADED` with `retry-after`, counted by core's `inflightCount()`. **A DRAINING process
   serves** with `connection: close`; only `lifecycleState() === 'stopped'` answers `X_DRAINING`
   (`pipeline-hardening.test.ts`).
-- **`csrf` sits after `auth` and before `body`**: an ambient-credential unsafe request needs
+- **`csrf` sits after `auth` and before `body`**: an unsafe request needs
   `sec-fetch-site: same-origin`, an `Origin` equal to this app (from `ctx.https`), or one EXACTLY in
   `cors.origins` (`originListed`, never `allowedOrigin`); else `X_CSRF_BLOCKED` (403). No
-  `mode: 'token'`.
+  `mode: 'token'`. **Anonymous is not an exemption** (login CSRF): exempt are an `Authorization`
+  header, and an anonymous request with NEITHER `Origin` nor `sec-fetch-site` (not a browser).
 - **`meta.enforcedBy` says who evaluates `meta.policy`**: `'pipeline'` (default) decides via
   `hooks.authorize`; `'handler'` stands the `authz` stage down.
 - **A 403's `fix:` names the POLICY** (`route.meta.policy`), degrading to `x routes --json` for a
   composite.
 - **The body cap is enforced while reading** (`UltimateRequest.#read`'s counting reader, cancelling
-  past `bodyLimitBytes`); multipart goes through the same capped bytes.
+  past `bodyLimitBytes`); multipart goes through the same capped bytes. **Bytes with no
+  `content-type` are `X_BODY_INVALID`** from `bodyRaw()`, never "no body"; `bodyBytes()` reads them.
 - **A repeated field is a LIST in all three parsers** (`collectFields`).
 - **`matchRoute` never throws**: `router.ts`'s `decodeSegment` answers `path-invalid` →
   `X_PATH_INVALID` (400).
@@ -120,13 +128,20 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 - **The `cache-headers` stage is the ONE owner of the final cache answer**: `offersSharedCache` turns a
   shared answer for an identified request into `PRIVATE_CACHE` and gives an anonymous one
   `SHARED_CACHE_VARY` (`accept-language, cookie`); `immutable` is left alone. `vary` is added, never
-  set (`addVary`).
+  set (`addVary`). An offer is `public`, `s-maxage`, or any `max-age` / `must-revalidate` /
+  `proxy-revalidate` without `private`/`no-store` (RFC 9111 §3).
+- **`Set-Cookie` is appended by the `response` stage, every other context header is `set`** —
+  it is the one header that is a list of lines (`pipeline-cookies.test.ts`).
+- **A redirect the framework writes stays on this origin**: the default-locale redirect goes
+  through `normalizePath`; `locationFor` hands over `http:`/`https:` only, else the requested path.
 - **A `cache-control` age is delta-seconds or DROPPED** (`finiteDeltaSeconds`, total, always the
   shorter direction; logs `http.cache_hint_not_delta_seconds`). Its boot half is `route-cache.ts`:
   `createRouter` refuses a bad `Route.cache` with `X_CONFIG_INVALID`. Both accept the same set; zero
   is legal. `ctx.cache` is not screened.
 - **A handler's own `Response.status` is never rewritten** (`pipeline-handler-status.test.ts`).
-- Health endpoints answer outside the pipeline. **Lifecycle belongs to core** (`beginWork()`,
+- Health endpoints answer outside the pipeline, so their body is a stranger's: `{ state, ready,
+  role }` unless the peer is in `healthDetailPeers` (default `['loopback']`; socket AND trusted
+  forwarded caller must both be listed — `health-disclosure.ts`). **Lifecycle belongs to core** (`beginWork()`,
   `markReady()`, `drain()`, the payloads) — never a private state or in-flight counter.
 - **`stop()` hands its two hooks back ABOVE its early return** (`packages/http/e2e/server.e2e.test.ts`
   reads `shutdownHookCount()`).
@@ -140,7 +155,8 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `ERROR_DOCS_URL`.** `finalize.ts`'s `lastResort` literal is pinned against `problemTypeFor('X_INTERNAL')`.
 - **A 5xx cause is withheld unless its code opts in** (`hasPublicCause`, `problem-meta.ts`;
   `registerProblemMeta({ CODE: { publicCause: true } })`). `toProblem(error, { dev })` defaults `dev`
-  to false. An unclassified 5xx carries nothing off the throwable.
+  to false. An unclassified 5xx carries nothing off the throwable. **A hidden cause hides the `fix`
+  too**: `callerFix`, else `x errors explain <CODE> --json` — never `facts.fix` outside dev.
 - **The document carries the ISSUE LIST** as a top-level `issues` member: `issuesOf` is total,
   all-or-nothing, absent (never `[]`) when none, dropped past `MAX_PROBLEM_ISSUES` (100), dropped under
   the opacity condition; `received` forced to `''`, entries rebuilt member by member.
@@ -173,7 +189,14 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 - **The scope is DECLARED, with no default**: an enabled limiter without `scope` is
   `X_RATE_LIMIT_SCOPE_UNSET`; `assertRateLimitScope` (in `createPipeline`) refuses `'shared'` over a
   per-process store (`X_RATE_LIMIT_NOT_SHARED`). Install through `createServer({ rateLimitStore })`.
-- **`postgresRateLimitStore({ executor })` is the shared store**, over a structural `PgExecutor`. The
+- **A failed `auth: 'required'` is metered in the `auth` stage** (`spendUnauthenticated`,
+  `rate-limit-stage.ts`): `defaultBucket` under `unauthenticated|ip:<address>`, not route-scoped,
+  spent only on failure — the 401 leaves before `rate-limit`. Covers the bearer mount's bad tokens.
+  Spent, it REFUSES the address before `authenticate()` (`refuseExhaustedAddress`, via the store's
+  read-only `peek` — never a take: that was an upsert per signed-in page),
+  a valid credential included; no `ctx.ip`, no gate. Signed-in callers behind that NAT wait too.
+- **`postgresRateLimitStore({ executor })` is the shared store**, over `@ultimat3/core`'s structural
+  `PgExecutor` (re-exported here). The
   refill expression is repeated inside `on conflict do update` on purpose; `spent` is a stored column;
   `purgeExpired(nowMs)` takes the caller's clock.
 - **A bucket a route names must be registered**: `withRouteBuckets` merges `meta.rateLimitBucket`
@@ -199,11 +222,12 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `pipeline.ts` | the ORDER the stages run in — the framework's guarantee — and the one loop that drives a request through them |
 | `stages.ts` | what each stage DOES, one entry per `StageName`, plus the stage vocabulary the other two import |
 | `finalize.ts` | the tail of that lifecycle, guarded: a throw after the handler degrades, never rejects |
-| `router.ts` | trie matcher, precedence static > param > wildcard, `path-invalid` for a segment that will not decode |
+| `router.ts` | trie matcher, precedence static > param > wildcard, `path-invalid` for a segment that will not decode. A request segment is decoded ONCE; a static child is looked up raw, then decoded (`/precios-espa%C3%B1a` is `/precios-españa`). A wildcard takes an EMPTY rest after the node's own routes (`/docs` → `/docs/*path` with `path: ''`, the path `@ultimat3/render`'s static build writes) — `router-spelling.test.ts` |
 | `navigation.ts` | the client router's server half: the gate `context` runs after the match (a prefetch to a route whose `meta.navigation` did not opt in → `204`; a soft GET to anything but a page of the router's `<app>:<surface>` → `204` + `x-ultimate-location`, before auth or app code) and the `response` stage's rewrite of a 3xx to a router request into the same hand-over, cookies kept |
-| `error-map.ts` | the code → status table, closed, plus the app's half (`registerErrorStatus`) |
+| `error-map.ts` | the code → status table, closed: COMPOSES the slices and holds no row of its own |
+| `error-map-http.ts`, `error-map-tier-<0-4>.ts` | the rows, one slice per owning tier (this package's own apart). `bun run new-error-code` appends to the slice its `--package` maps to; a code in two slices is refused there and by `error-map.test.ts` |
 | `error-facts.ts` | every RENDERING of a throwable: `factsOf()`, the problem document (including the issue list and the opacity rule over it), the three terminal lines |
-| `hooks.ts` | the seams: `authenticate`, `authorize`, `devNotices` + the app's `configureAuthenticator()` |
+| `hooks.ts` | the seams: `authenticate`, `authorize`, `devNotices`, `errorPage`, `explainMiss` (asked ONLY on a `not-found` match, synchronously, with the request line alone; its error replaces `X_ROUTE_NOT_FOUND`) + the app's `configureAuthenticator()` |
 | `type-pins.ts` | compile-time claims about `AuthzDecision`'s shape — source, because `tsc` never reads a `.test.ts` |
 | `overlay.ts` | the dev error page: the same code/cause/fix as the terminal, plus any notices |
 | `overlay-style.ts` | the overlay's one stylesheet, split out so `security-headers.ts` hashes it |
@@ -220,10 +244,12 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `forwarded.ts` | one hop-indexed reader for every header a trusted proxy writes |
 | `peer-identity.ts` | Envoy XFCC -> `ctx.peer`, on that same trust rule |
 | `deadline.ts` | the per-request `AbortController`, the timer and `X_TIMEOUT` |
-| `csrf.ts` | the origin proof an unsafe method from a credentialed browser must carry |
+| `csrf.ts` | the origin proof an unsafe method from a browser must carry, signed in or not |
 | `webhook-verify.ts` | the INBOUND webhook: the canonical string, the constant-time mac check and the replay window. The outbound half is `webhook()` in `@ultimat3/jobs`, which this package can never import |
-| `locale.ts` | WHERE the request's locale and zone are read from — header and cookie NAMES only, plus `readCookie`. It negotiates nothing |
+| `locale.ts` | WHERE the request's locale and zone are read from — header and cookie NAMES only. It negotiates nothing; the cookie is read by `@ultimat3/core`'s `readCookie`, which `index.ts` re-exports |
 | `rate-limit-buckets.ts` | the one point routes and config meet: a route's own bucket, registered or refused |
+| `rate-limit-stage.ts` | what the pipeline spends and when: the `rate-limit` stage's list of keys, and the address-keyed allowance the `auth` stage spends for a failed credential |
+| `health-disclosure.ts` | WHO the web role's `/healthz` and `/readyz` tell the detail to: the `healthDetailPeers` config key, its screen, and the trusted-proxy half. The body rule and the peer match are core's (`health-disclosure.ts` there), shared with the sync node |
 | `bearer-mount.ts` | a second door onto existing routes: `Authorization: Bearer` on a prefix, the scope cut, the per-token allowance |
 | `app-config.ts` | the app's own HTTP declaration (`configureHttp`) and the layering that keeps a boot fact above it |
 

package/README.md

@@ -8,17 +8,17 @@ to skip.
 
 | Concern | Module |
 |---|---|
-| server lifecycle, drain, `/healthz` + `/readyz` | `server.ts` |
+| server lifecycle, drain, `/healthz` + `/readyz` | `server.ts`; `health-disclosure.ts` owns the `healthDetailPeers` key, its screen and the proxy half — the body rule is `@ultimat3/core`'s |
 | route table, matcher, `describeRoutes()` | `router.ts` |
 | the ordered request lifecycle | `pipeline.ts` |
 | typed request (params, query, body) | `request.ts` |
 | response constructors + `problem()` | `response.ts` |
-| code → status, closed table | `error-map.ts` |
+| code → status, closed table | `error-map.ts`, composing `error-map-http.ts` + `error-map-tier-<n>.ts` |
 | `factsOf()`, the problem document, the terminal lines | `error-facts.ts` |
 | token-bucket limiting, `toBucket` | `rate-limit.ts` |
 | the app's own HTTP declaration, and the boot's facts over it | `app-config.ts` |
 | CORS, CSP/HSTS | `cors.ts`, `security-headers.ts` |
-| CSRF (origin proof for a credentialed write) | `csrf.ts` |
+| CSRF (origin proof for an unsafe request a browser sent) | `csrf.ts` |
 | the request deadline and `ctx.signal` | `deadline.ts` |
 | the caller's real address behind a proxy | `forwarded.ts` |
 | the inbound request id and trace, read before the span | `correlation.ts` |
@@ -68,8 +68,8 @@ asserts the order; `/_x` renders it. Ordering rules worth restating:
 | Rule | Reason |
 |---|---|
 | 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 |
+| auth before rate-limit | limiter keys per actor/tenant, not per NAT address. A request that FAILS `auth: 'required'` leaves here, so this stage spends `rateLimit.defaultBucket` for it under `unauthenticated\|ip:<address>` — one key per address across every route, the bearer mount's bad tokens included; a signed-in caller behind that address spends nothing from it |
+| csrf after auth | it has to know who is calling: a bearer caller is exempt (not ambient); an anonymous write is judged like a signed-in one once it carries `Origin` or `sec-fetch-site`, because a forged sign-in lands the visitor in the attacker's account. Anonymous with neither header — a webhook, a server-to-server call — passes |
 | csrf before body | a forged write never makes the server allocate its payload |
 | rate-limit before body | a limited request never allocates its payload |
 | body before authz | policies take parsed input as their subject |
@@ -95,13 +95,23 @@ What the lifecycle refuses on the caller's behalf, `As of 2026-08`:
 | an injected limiter that does not hold a bucket a route declares | `X_RATE_LIMIT_BUCKET_UNBOUND` at `createPipeline`, because the name would fall through to `default` — measured at 120 burst for a route declaring 5 |
 | a config that never declared `rateLimit.scope` | `X_RATE_LIMIT_SCOPE_UNSET` at `defineHttpConfig`. **Breaking, `As of 2026-08`**: `'process'` used to be the default, so "nobody asked" and "the app said one replica" were the same value while the chart runs three |
 | `trustProxy: true` with no `trustedProxyHops` | `X_TRUST_PROXY_UNSET` at `defineHttpConfig`. **Breaking, `As of 2026-08`**: `trustProxy` now defaults to `false`, and `x-forwarded-for` is read at `entries.length - hops` — never at `[0]`, which is whatever the client typed |
-| 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 |
+| an unsafe method from a browser — signed in, or anonymous with `Origin`/`sec-fetch-site` — 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. A handler still running after the 504 stays in core's in-flight count until it settles, so a drain waits for it instead of closing the pool under it |
+| a budget above `2_147_483_647` ms | no timer holds it: `requestTimeoutMs` past it is `X_CONFIG_INVALID`, and an `x-request-timeout-ms` past it is ignored — it used to arm a ~1 ms timer |
 | 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 | 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 |
+| `x-forwarded-client-cert` without `trustClientCertHeader: true` | `ctx.peer` is `null`. **Breaking**: `trustProxy` alone used to read it, and an ingress that appends to `x-forwarded-for` need not strip a certificate header the client sent |
+| `/healthz`, `/readyz` from a peer `healthDetailPeers` does not list | `{ state, ready, role }` and the same status code; `buildId`, `inflight`, `uptimeMs`, `checks` and `registered` go to a listed peer only (default `['loopback']`), and behind a declared proxy the forwarded caller must be listed too |
+| a `/<default-locale>/…` URL | `301`/`308` to the unprefixed path, normalised as the router matches it — `//host/x` after the prefix is `/host/x`, never a scheme-relative `Location` |
+| a 3xx to a client-router request whose target is not `http:`/`https:` | `x-ultimate-location` names the REQUESTED url as a path; the target is never handed over, and one that will not parse is treated the same |
+| a handler's `cache-control` carrying `max-age`, `must-revalidate` or `proxy-revalidate` with no `private`/`no-store` | an offer to a shared cache (RFC 9111 §3): `private, max-age=0` for a request carrying an identity, `vary`-keyed for an anonymous one. `immutable` stays exempt |
+| a body with no `content-type` | `X_BODY_INVALID` from `bodyRaw()` / the `body` stage — it used to read as "no body", so an all-optional schema validated a request nobody parsed. `bodyBytes()` still reads it |
+| two cookies set in one request | two `Set-Cookie` lines: the `response` stage appends them, where `headers.set` in a loop kept the last and dropped any on the handler's own Response |
+| a 5xx whose cause is withheld | its `fix` is the error's `callerFix`, else `x errors explain <CODE> --json` — never the developer's `fix:`, which is written from the same statement, row or path the cause was |
+| `buildId: null` | skew detection off, whatever `BUILD_ID` says; `hostname` never defaults from `HOSTNAME` (the container id under Docker) |
 | 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 |
 
@@ -117,6 +127,11 @@ The app declares which it needs and passes the store that provides it — the st
 thing that knows where its counters live, and a framework that inferred the answer from the
 environment would get it wrong on the first deployment that scaled differently.
 
+A store answers three calls: `take(key, bucket, cost, nowMs)` spends, `peek(key, bucket, nowMs)`
+reads (refill applied, **no write and no row** — a key never taken is full; `rateLimitPeek` and
+`refilledTokens` do the arithmetic) and `reset(key)`. `peek` is required, `As of 2026-10`: the
+`auth` stage asks it on every request to an `auth: 'required'` route.
+
 ```ts
 import {
   createServer,
@@ -164,7 +179,7 @@ one tenant is a person and the next is five thousand seats, so there is no allow
 can pick for you.
 
 **A shared store ships, `As of 2026-08`** — `postgresRateLimitStore({ executor })`, one table
-and one `insert … on conflict` per take, so N replicas count against one bucket. Until it landed,
+and one `insert … on conflict` per take (a peek is one `select`), so N replicas count against one bucket. Until it landed,
 `scope: 'shared'` was a declaration nothing in the framework could satisfy while `x new` scaffolded
 `replicas: 2`. `executor` is a `PgExecutor` — anything speaking `query(text, values)`, which is one
 line over the client the boot already opened; **never `Bun.sql`**, whose `.query` is `undefined`.
@@ -259,9 +274,15 @@ const handle = createServer({
 }).start();
 ```
 
-Static paths are registered in Bun's native `routes` table; param/wildcard paths fall
+Static paths are registered in Bun's native `routes` table (keyed `encodeURI`'d: `Bun.serve`
+refuses a non-ASCII key); param/wildcard paths, and any other spelling of a static one, fall
 through to `fetch`. Method resolution stays ours so a 405 still carries problem+json.
 
+`As of 2026-10-02`: a literal segment matches its percent-encoded request spelling, either hex
+case (`/precios-espa%C3%B1a` reaches `/precios-españa`), and a wildcard matches an empty rest —
+`/docs` and `/docs/` reach `/docs/*path` with `path: ''`, after a static `/docs` route if one is
+declared. A malformed escape is still `X_PATH_INVALID` or a 404, never a thrown `URIError`.
+
 ### No WebSocket upgrade on the `web` role, and no hand-written `api/` route
 
 `As of 2026-09-05`, and stated because an app went looking for both. The `web` role's
@@ -303,6 +324,9 @@ exactly three things. Apps declare it through `defineApi({ http: { mounts } })`
 
 `RouteMeta.authenticate` is the mechanism: a route that states one is reached only through it.
 
+For API keys, `resolveToken` is `@ultimat3/auth`'s `apiKeyResolver(() => store)` — a live key is
+`{ actor, scopes }`, every wrong one is the same `null`, and a store fault stays a throw.
+
 ## Inbound webhooks
 
 `verifyWebhookSignature(request, { secret })` is the receiving half of the framework's webhook
@@ -439,3 +463,9 @@ Tier 2. Imports `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/i18n` and `@ult
 tiers 0 and 1, which is the whole rule. Authentication and policy evaluation arrive through
 `ServerHooks`, declared structurally, because `@ultimat3/policy` is a sibling tier. There is no
 plugin API: `Middleware` wraps a handler, the pipeline is everything else.
+
+`hooks.explainMiss(method, pathname)` is the same kind of seam for a request the router matched
+nothing for: the error it returns is thrown in place of `X_ROUTE_NOT_FOUND`, `undefined` keeps the
+plain miss. Synchronous, given only the request line, never asked about a matched route or a 405.
+`@ultimat3/action` answers it for a path that is one of its actions under a `pathStyle` this server
+does not serve (`X_CONTRACT_DRIFT`, 404).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "22.15.0",
+  "version": "24.0.0",
   "description": "Owned request lifecycle over Bun.serve: router, ordered pipeline, problem+json errors",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -31,9 +32,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.15.0",
-    "@ultimat3/i18n": "22.15.0",
-    "@ultimat3/schema": "22.15.0",
-    "@ultimat3/time": "22.15.0"
+    "@ultimat3/core": "24.0.0",
+    "@ultimat3/i18n": "24.0.0",
+    "@ultimat3/schema": "24.0.0",
+    "@ultimat3/time": "24.0.0"
   }
 }

package/src/cache-policy.ts

@@ -16,14 +16,22 @@ export const PRIVATE_CACHE: CacheHint = { mode: 'private', maxAgeSeconds: 0 };
 // for every signed-in user.
 const OFFERS_SHARED = /(?:^|,)\s*(?:public\b|s-maxage=)/i;
 const IMMUTABLE = /(?:^|,)\s*immutable\b/i;
+// RFC 9111 §3: a shared cache may store a response to a request without `Authorization` — which
+// is every cookie session — as soon as it carries explicit freshness or a revalidation rule. So
+// `max-age=3600` alone is an offer too, unless the same header withholds it.
+const STATES_FRESHNESS = /(?:^|,)\s*(?:max-age=|must-revalidate\b|proxy-revalidate\b)/i;
+const WITHHOLDS = /(?:^|,)\s*(?:private\b|no-store\b)/i;
 
 /**
  * Whether a `cache-control` a HANDLER wrote offers the response to a shared cache. A render mode
  * states the MODE's intent — `ssr` offers an ungated page to a CDN for 30 seconds — and the actor
  * is the half it cannot see, so the stage reviews the declaration rather than deferring to it.
  */
-export const offersSharedCache = (declared: string): boolean =>
-  OFFERS_SHARED.test(declared) && !IMMUTABLE.test(declared);
+export const offersSharedCache = (declared: string): boolean => {
+  if (IMMUTABLE.test(declared)) return false;
+  if (OFFERS_SHARED.test(declared)) return true;
+  return STATES_FRESHNESS.test(declared) && !WITHHOLDS.test(declared);
+};
 
 /**
  * Authenticated responses are never shared-cacheable; that default is not overridable.

package/src/config.ts

@@ -7,6 +7,7 @@ import { DEFAULT_ENVIRONMENT, tryResolveEnvironment } from '@ultimat3/core';
 import { assertCorsConfig, type CorsConfig, DEFAULT_CORS } from './cors';
 import { type CsrfConfig, DEFAULT_CSRF } from './csrf';
 import { httpCountInvalid, trustProxyUnset } from './errors';
+import { assertHealthDetailPeers, DEFAULT_HEALTH_DETAIL_PEERS } from './health-disclosure';
 import {
   DEFAULT_LOCALE_CONFIG,
   DEFAULT_TZ_CONFIG,
@@ -45,6 +46,20 @@ export interface HttpConfig {
    * `0` when nothing is trusted.
    */
   readonly trustedProxyHops: number;
+  /**
+   * Read Envoy's `x-forwarded-client-cert` into `ctx.peer`. Its OWN declaration, `false` until an
+   * app makes it: `trustProxy` says the proxy appends to `x-forwarded-for`, which is no promise
+   * that it strips or overwrites a certificate header the client sent — and this one names an
+   * identity. Read at `trustedProxyHops`, so it does nothing without `trustProxy`.
+   */
+  readonly trustClientCertHeader: boolean;
+  /**
+   * Who `/healthz` and `/readyz` tell more than the verdict: each entry an address class
+   * (`'loopback'`, `'private'`, …) or one exact address. Everyone else gets `state`, `ready` and
+   * `role` — the endpoints answer outside the pipeline, so the build id, the in-flight count and
+   * the readiness check names were otherwise any stranger's to read. `[]` tells nobody.
+   */
+  readonly healthDetailPeers: readonly string[];
   readonly bodyLimitBytes: number;
   /**
    * How long one request may run before it is aborted and answered `X_TIMEOUT` (504). `0`
@@ -89,6 +104,8 @@ export interface HttpConfigInput {
   readonly signInPath?: string | null;
   readonly trustProxy?: boolean;
   readonly trustedProxyHops?: number;
+  readonly trustClientCertHeader?: boolean;
+  readonly healthDetailPeers?: readonly string[];
   readonly bodyLimitBytes?: number;
   readonly requestTimeoutMs?: number;
   readonly maxInflight?: number;
@@ -170,6 +187,13 @@ const assertFiniteCount = (
 
 const MAX_PORT = 65_535;
 
+/**
+ * The longest delay a timer holds: a signed 32-bit count of milliseconds, about 24.8 days. Past
+ * it `setTimeout` arms ~1 ms, so a "longer" request budget timed every request out at once.
+ * `requestTimeoutMs` is screened against it and `deadline.ts` reads the inbound header by it.
+ */
+export const MAX_TIMER_MS = 2_147_483_647;
+
 /**
  * Nobody has 64 proxies in front of one process; a bigger number is a typo, not a topology.
  *
@@ -241,14 +265,22 @@ export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
       'a whole port number from 0 to 65535, where 0 asks the OS for a free one',
       'port: 3000',
     ),
-    hostname: input.hostname ?? env('HOSTNAME') ?? '0.0.0.0',
+    // Never `HOSTNAME`: Docker sets it to the container id, which is not an address to bind. The
+    // boot passes what `HOST` says (`@ultimat3/cli`'s `hostnameFromEnv`); an embedder passes its own.
+    hostname: input.hostname ?? '0.0.0.0',
     basePath: input.basePath ?? '/',
-    buildId: input.buildId ?? env('BUILD_ID') ?? null,
+    // `undefined` falls back to the environment; an explicit `null` is the declaration that
+    // switches skew detection off, and `??` would have read it as unset.
+    buildId: input.buildId === undefined ? (env('BUILD_ID') ?? null) : input.buildId,
     buildIdHeader: input.buildIdHeader ?? 'x-ultimate-build',
     dev,
     signInPath: input.signInPath ?? null,
     trustProxy,
     trustedProxyHops,
+    trustClientCertHeader: input.trustClientCertHeader === true,
+    healthDetailPeers: assertHealthDetailPeers(
+      input.healthDetailPeers === undefined ? DEFAULT_HEALTH_DETAIL_PEERS : input.healthDetailPeers,
+    ),
     bodyLimitBytes: assertFiniteCount(
       'bodyLimitBytes',
       input.bodyLimitBytes ?? 1_048_576,
@@ -261,8 +293,8 @@ export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
     requestTimeoutMs: assertFiniteCount(
       'requestTimeoutMs',
       input.requestTimeoutMs ?? 30_000,
-      Number.MAX_SAFE_INTEGER,
-      'a whole number of milliseconds, where 0 means no deadline',
+      MAX_TIMER_MS,
+      `a whole number of milliseconds up to ${MAX_TIMER_MS} (the longest a timer holds), where 0 means no deadline`,
       'requestTimeoutMs: 30_000',
     ),
     maxInflight: assertFiniteCount(

package/src/context.ts

@@ -11,6 +11,7 @@ import {
   type Logger,
   traceId as newTraceId,
   type Role,
+  readCookie,
   type ServiceBag,
   systemClock,
   useContext,
@@ -21,7 +22,6 @@ import { timeConfig } from '@ultimat3/time';
 import type { HttpConfig } from './config';
 import { noRequest } from './errors';
 import type { AuthzDecision } from './hooks';
-import { readCookie } from './locale';
 import type { PeerIdentity } from './peer-identity';
 import type { RateLimitDecision } from './rate-limit';
 import { bindRequestServices } from './request-services';

package/src/csrf.ts

@@ -1,5 +1,5 @@
-// Whether an unsafe request carrying an AMBIENT credential came from somewhere allowed to make
-// it. CORS does not answer this: `application/x-www-form-urlencoded` is a CORS-simple content
+// Whether an unsafe request a BROWSER sent — with the session cookie, or to obtain one — came
+// from somewhere allowed to make it. CORS does not answer this: `application/x-www-form-urlencoded` is a CORS-simple content
 // type, so `<form method="post">` on evil.test is SENT and EXECUTED with the session cookie
 // attached — `cors.origins: []` only stops the attacker reading the reply, long after the refund
 // went through. `setRedirect` exists so those form posts work without JS, which makes them a
@@ -34,7 +34,11 @@ export interface CsrfCheckInput {
   readonly secFetchSite: string | null;
   /** A bearer token is not ambient: a cross-site page cannot make the browser attach one. */
   readonly hasAuthorizationHeader: boolean;
-  /** Anonymous callers have no credential to ride, so nothing to forge. */
+  /**
+   * No session resolved. NOT an exemption: a sign-in form is forgeable too (login CSRF — the
+   * visitor ends up in the attacker's account), so an anonymous write that carries browser
+   * evidence is judged exactly as a credentialed one. See `checkCsrf` for the one thing it buys.
+   */
   readonly anonymous: boolean;
   readonly cors: CorsConfig;
   readonly config: CsrfConfig;
@@ -50,12 +54,17 @@ export type CsrfVerdict =
  * `Origin` second, so an app that lists a sibling origin in `cors.origins` keeps working. A
  * request with neither — a non-browser client with a cookie, or a browser too old to send
  * either — is refused: "we could not tell" is the case this exists for.
+ *
+ * An ANONYMOUS request carrying neither is the one case let through: there is no ambient
+ * credential to ride and no browser evidence to judge, which is an inbound webhook or a
+ * server-to-server call, never a page a hostile site can drive — every browser that can submit a
+ * cross-site form sends `Origin` on it. Either header present, and it is judged like any other.
  */
 export const checkCsrf = (input: CsrfCheckInput): CsrfVerdict => {
   if (input.config.mode === 'off') return { ok: true };
   if (SAFE_METHODS.has(input.method)) return { ok: true };
-  if (input.anonymous) return { ok: true };
   if (input.hasAuthorizationHeader) return { ok: true };
+  if (input.anonymous && input.origin === null && input.secFetchSite === null) 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.
@@ -79,8 +88,8 @@ 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.
+ * A write a browser sent — with its ambient credential, or anonymously to obtain one — that could
+ * not be shown to come from this app. Never a 401: who is calling was never the question.
  *
  * 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
@@ -95,11 +104,11 @@ export const csrfBlocked = (
   ip !== null && classifyAddress(ip) === 'loopback'
     ? new HttpError({
         code: 'X_CSRF_BLOCKED',
-        cause: `${pathname} refused a credentialed write: ${reason}`,
+        cause: `${pathname} refused a write it could not show came from this app: ${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}`,
+        cause: `${pathname} refused a write it could not show came from this app: ${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/deadline.ts

@@ -5,7 +5,7 @@
 // never finish.
 
 import { REQUEST_TIMEOUT_HEADER, systemClock } from '@ultimat3/core';
-import type { HttpConfig } from './config';
+import { type HttpConfig, MAX_TIMER_MS } from './config';
 import { requestTimedOut } from './errors';
 
 /**
@@ -46,13 +46,18 @@ const NO_DEADLINE: Deadline = {
   clear: () => undefined,
 };
 
-/** The configured budget, or the caller's if theirs is shorter. `0` means "no deadline". */
+/**
+ * The configured budget, or the caller's if theirs is shorter. `0` means "no deadline".
+ *
+ * An ask above `MAX_TIMER_MS` is no ask: no timer can hold it — the runtime arms such a delay as
+ * ~1 ms, so "a very long deadline" was `X_TIMEOUT` within a tick — and a caller may only shorten.
+ */
 export const resolveTimeoutMs = (headers: Headers, config: HttpConfig): number => {
   const configured = config.requestTimeoutMs;
   const raw = headers.get(REQUEST_TIMEOUT_HEADER);
   if (raw === null) return configured;
   const asked = Number.parseInt(raw, 10);
-  if (!Number.isFinite(asked) || asked < 1) return configured;
+  if (!Number.isFinite(asked) || asked < 1 || asked > MAX_TIMER_MS) return configured;
   return configured > 0 ? Math.min(configured, asked) : asked;
 };
 

package/src/error-facts.ts

@@ -5,6 +5,7 @@
 import {
   ERROR_DOCS_URL,
   FRAMEWORK_CODE,
+  hasPublicCause,
   isUltimateError,
   renderCauseValue,
   singleLine,
@@ -13,7 +14,7 @@ import {
 import type { ValidationIssue } from '@ultimat3/schema';
 import { declaredStatusFor, statusFor } from './error-status';
 import { HTTP_ERROR_TITLES } from './errors';
-import { hasPublicCause, type ProblemMeta, problemMetaKeysFor, wireMeta } from './problem-meta';
+import { type ProblemMeta, problemMetaKeysFor, wireMeta } from './problem-meta';
 
 /** Everything a renderer (problem+json, overlay, terminal) needs from a throwable. */
 export interface ErrorFacts {
@@ -270,6 +271,14 @@ export interface ProblemDocument {
   readonly meta?: ProblemMeta | undefined;
 }
 
+/**
+ * The fix a hidden document carries: the code's own registry entry, nothing off the throwable.
+ * `FRAMEWORK_CODE` gates it for `factsOf`'s reason — this is a command a reader pastes, and `code`
+ * is a string field off a value this package did not build.
+ */
+const explainFix = (code: string): string =>
+  FRAMEWORK_CODE.test(code) ? `x errors explain ${code} --json` : 'x errors list --json';
+
 /** The title a caller gets for a failure the framework cannot name. */
 const INTERNAL_TITLE = 'unhandled server error';
 
@@ -331,7 +340,14 @@ export const toProblem = (
     // The CALLER's fix outside dev: a production client cannot run `x policy explain`, and the
     // developer's line stays in the log this request wrote. Dev keeps the developer's, because the
     // reader of a dev response is the developer.
-    fix: meta.dev === true ? facts.fix : (facts.callerFix ?? facts.fix),
+    // HIDDEN, the developer's fix is withheld with the cause it was built beside: a driver or repo
+    // error writes its fix from the statement, the row or the path it failed on, so serving it
+    // under a blanked cause put back what the blanking took out. A declared `callerFix` is
+    // authored FOR the caller and still goes; otherwise the line names the code and nothing else.
+    fix:
+      meta.dev === true
+        ? facts.fix
+        : (facts.callerFix ?? (hidden ? explainFix(facts.code) : facts.fix)),
     docs: facts.docs,
     requestId: meta.requestId,
     ...(issues === undefined ? {} : { issues }),