@ultimat3/http 23.0.0 → 25.0.0

package/CLAUDE.md

@@ -13,8 +13,9 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 ## Rules — configuration
 
 - **Every numeric knob `defineHttpConfig` resolves is screened** (`port`, `bodyLimitBytes`,
-  `requestTimeoutMs`, `maxInflight`, `drainTimeoutMs`, `trustedProxyHops`) → `X_CONFIG_INVALID`
-  (borrowed). Helpers carry `Finite` (`assertFiniteCount`, `assertFiniteKeyCap`,
+  `requestTimeoutMs`, `maxInflight`, `trustedProxyHops`) → `X_CONFIG_INVALID`
+  (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
@@ -27,22 +28,25 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `trustedProxyHops`, `rateLimit.scope`) is a type error where an app writes it. `mergeHttpConfig`
   merges `security.csp.extend` per directive. `type-pins.ts` refuses a key on `HttpConfig` missing
   from `HttpConfigInput`.
-- **`config.drainTimeoutMs` defaults to `null`**: `createServer` calls `configureLifecycle({
-  deadlineMs })` only when declared. **`ServerOptions.drain`** (`app.config.ts`'s `drain`) passes
-  `readinessGraceMs` to core the same way.
+- **No drain deadline here**: `drain.deadlineMs` is the one budget (core, per role). Key
+  `drainTimeoutMs` (deleted 25.0.0) is `X_CONFIG_INVALID` via `refuseDeletedHttpKeys`.
+  **`ServerOptions.drain`** passes only `readinessGraceMs`, and only when declared.
 - **`cors.origins: ['*']` with `credentials: true` is `X_CORS_CONFIG_INVALID`.** A refused origin
   still gets `vary: origin`.
 - **A `security.csp.extend` entry must emit only the directive it names**
   (`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
 
 - **`asCtx` is a WIDENING the compiler checks, never a cast** (`RequestContext extends Ctx`;
   `_RequestContextIsACtx` in `type-pins.ts`). `ctx.buildId` is the process's build;
   `ctx.clientBuildId` is the client's claim, read only by `assertBuild()`.
-- **`createRequestContext` COMPOSES `createContext()`** — no assertion in this file, and
+- **`requestContext` COMPOSES `ctxOf()`** — no assertion in this file, and
   `defineService` factories and the service spread are core's. Services go on FIRST so a service
   named `actor` loses to the request's field (`context.test.ts`).
 - **A request's registered services are LAZY and bound to the authenticated actor**
@@ -64,8 +68,16 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   handler, policy, idempotency; adds the credential (bearer only, `WWW-Authenticate` on 401), the
   cut (outside the token's scopes = `X_ROUTE_NOT_FOUND`, the MCP rule), and a per-token bucket
   keyed by a SHA-256 of the token. Bad prefix / unknown name / double claim:
-  `X_BEARER_MOUNT_INVALID` at construction.
+  `X_BEARER_MOUNT_INVALID` at construction. **The cut is decided in the `auth` stage** — one
+  authenticator per route, closed over its scope — so an out-of-scope token is 404 before `body`
+  (422) and `authz` (403) could describe the primitive. **The prefix is opaque**: `<prefix>/*rest`
+  for every method (`opaquePrefix`) answers no token / a bad token with the same 401 challenge a
+  served path gives, and a valid token with the same 404 — never 404-vs-401 or a 405 naming methods.
+  That 404 SPENDS the token's allowance (once; a served call is charged in the handler), so a
+  token cannot walk the cut for free.
 - **`hooks.devNotices` is called only inside the `config.dev && wantsOverlay` branch.**
+- **A dev 4xx asks `hooks.errorPage` first; a 5xx is always the overlay** (#492): the app's file
+  when it has one, else the overlay. Production asks for every status (`stages-error-page.test.ts`).
 
 ## Rules — the pipeline
 
@@ -82,28 +94,35 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 - **The two inbound ids are read BEFORE the context and the span** (`correlation.ts`, core's
   `parseTraceparent`). `x-request-id` is gated on `trustProxy`; `traceparent` deliberately is not.
 - **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
+  `entries.length - hops`, never `[0]`; a short chain trusts nothing. **Except `x-forwarded-proto`**
+  (`forwardedProto`): proxies usually OVERWRITE it, so a list shorter than `hops` reads its first
+  entry (an overwrite erased the client's value; what is left a trusted hop wrote) — HSTS behind
+  two hops. A full-length list is read like an address. `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 +139,21 @@ 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`). App code writes one
+  only via `setCookie`/`deleteCookie` (core's serializer; `bun run set-cookie-literals`).
+- **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
+  `httpRouter` 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 +167,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.
@@ -152,8 +180,11 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   vocabulary; what the caller sent rides in `meta`; the parser's message goes through `renderThrowable`.
 - **A browser failing `auth: 'required'` is redirected; an agent gets the problem document**
   (`auth-redirect.ts`, in `error-map` before the overlay). `config.signInPath` is `null` until named.
-  `nextAfterSignIn` is the ONE `?next=` reader: same-origin paths only, a control character is
-  off-site, re-parsed against an unreachable origin, never throws.
+  `nextAfterSignIn` is the ONE `?next=` reader: same-origin paths only, decoded ONCE (by the
+  caller's parser, never again here — `%26` stays `%26`), any C0/DEL refused, non-ASCII
+  percent-encoded for `Location`, re-parsed against an unreachable origin, never throws. It
+  returns the RESOLVED path (never the raw string) and refuses one starting `//`; `locationFor`
+  never emits a same-origin pathname starting `//` (`/.//…` instead).
 - **A pathname in a `fix:` goes through `renderFixShellArg`** (`routeNotFound`). **A `code` is gated by
   core's `FRAMEWORK_CODE`** before `x errors explain <code>`, else `x errors list --json`. **A supplied
   `fix:` is taken only from a branded error** (`isUltimateError`).
@@ -169,15 +200,22 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN`. Headers report the bucket closest to refusing.
 - **The memory store is bounded** (`forgetAtMs` sweep, `DEFAULT_MAX_RATE_LIMIT_KEYS`, evicting the
   entries closest to FULL first — never LRU).
-- **The limiter takes a `Clock`** (`createRateLimiter({ clock })`); `deps.limiter` is the one seam.
+- **The limiter takes a `Clock`** (`rateLimiter({ clock })`); `deps.limiter` is the one seam.
 - **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
+  `X_RATE_LIMIT_SCOPE_UNSET`; `assertRateLimitScope` (in `httpPipeline`) refuses `'shared'` over a
+  per-process store (`X_RATE_LIMIT_NOT_SHARED`). Install through `httpServer({ rateLimitStore })`.
+- **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`
-  into the table in `createServer` and `createPipeline`; any disagreement is
+  into the table in `httpServer` and `httpPipeline`; any disagreement is
   `X_RATE_LIMIT_BUCKET_CONFLICT`. **The installed limiter must hold it too** — `RateLimiter.buckets`
   is declared and `assertRouteBuckets` refuses, never rebinds.
 
@@ -199,32 +237,38 @@ 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`, `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 |
-| `context.ts` | `RequestContext` (core's `Ctx` plus the request's own), composed from `createContext`, the single `Ctx` adapter (`asCtx`) and the inbound-header readers |
+| `context.ts` | `RequestContext` (core's `Ctx` plus the request's own), composed from `ctxOf`, the single `Ctx` adapter (`asCtx`) and the inbound-header readers |
 | `redirect.ts` | the intent slot a handler that cannot return a `Response` fills |
+| `set-cookie.ts` | `setCookie`/`deleteCookie`: one line each onto `ctx.headers` |
 | `auth-redirect.ts` | where an unauthenticated browser goes, and where it comes back to |
 | `cache-policy.ts` | the default `CacheHint` for a route that declared none — route AND actor — and the review of a declared one (`reviewedHint`) |
 | `error-log-level.ts` | the level of the `error-map` stage's one line: `error` for 5xx, `warn` for 401/403/429, `info` for the rest |
-| `route-cache.ts` | the screen a `Route.cache` hint gets where it is DECLARED, thrown from `createRouter`; the response path's `finiteDeltaSeconds` is the total half of the same rule |
+| `route-cache.ts` | the screen a `Route.cache` hint gets where it is DECLARED, thrown from `httpRouter`; the response path's `finiteDeltaSeconds` is the total half of the same rule |
 | `rate-limit.ts` | the token-bucket maths, the store interface, the memory driver and `toBucket` |
 | `rate-limit-postgres.ts` | the SHARED store: one table, one `insert … on conflict` per take, over a structural `PgExecutor` |
-| `rate-limit-errors.ts` | every refusal a rate limit produces — the 429 and the six declaration faults. Split off `errors.ts` at the ceiling; the codes and titles stay there, one registry |
+| `rate-limit-errors.ts` | every refusal a rate limit produces — the 429 and the six declaration faults. Split off `errors.ts` at the ceiling |
+| `error-titles.ts` | the owned codes, their titles and the two `retry-after` classes, registered at import — the one module `sideEffects` lists, imported bare by the barrel and `errors.ts`. Server realm only: a browser reads an http refusal's title off the body and its delay off `Retry-After` (core's decoders), so no http module rides into an island |
 | `correlation.ts` | the inbound request id and trace, read before the context and the span exist |
 | `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 core's `readCookie`, imported, never re-exported |
 | `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 |
+| `request-facts.ts` | `RequestFacts`, any token resolver's frozen 2nd arg; address = `ctx.ip` |
 | `app-config.ts` | the app's own HTTP declaration (`configureHttp`) and the layering that keeps a boot fact above it |
 
 ## Commands

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 |
@@ -87,21 +87,31 @@ What the lifecycle refuses on the caller's behalf, `As of 2026-08`:
 | 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 |
 | a cross-origin request from an origin the allow-list refuses | no `access-control-allow-origin`, but always `vary: origin`, so a shared cache never answers an allowed origin out of the refusal's slot |
 | `cors.origins: ['*']` with `credentials: true` | `X_CORS_CONFIG_INVALID` at `defineHttpConfig`, because a browser accepts that pair from nobody |
-| `?next=` carrying anything but a same-origin path | the fallback — including a value whose TAB/CR/LF a browser strips back into `//evil.test` |
+| `?next=` carrying anything but a same-origin path | the fallback — including a value whose TAB/CR/LF a browser strips back into `//evil.test`, and any other control character. `nextAfterSignIn` takes the value its caller's parser already decoded and never decodes it again, `As of 2026-10`: `?q=a%26b` lands as `?q=a%26b`, not `?q=a&b`. A code point above U+007F is percent-encoded so a `Location` header can carry it. The answer is the normalised path (`/a/../b` → `/b`), and one whose pathname starts `//` (`/.//evil.test`) is refused; `x-ultimate-location` never carries a same-origin pathname starting `//` either |
 | HSTS | emitted only when the connection is affirmatively https (`ctx.https`); never by the zero-argument default |
-| `rateLimit.scope: 'shared'` on a per-process store | `X_RATE_LIMIT_NOT_SHARED` at `createServer`, because N replicas each holding their own counters enforce N × every configured number |
-| a route's own bucket and a configured bucket of that name disagreeing | `X_RATE_LIMIT_BUCKET_CONFLICT` at `createServer`, because the loser would be a number someone read and nothing applied |
+| `rateLimit.scope: 'shared'` on a per-process store | `X_RATE_LIMIT_NOT_SHARED` at `httpServer`, because N replicas each holding their own counters enforce N × every configured number |
+| a route's own bucket and a configured bucket of that name disagreeing | `X_RATE_LIMIT_BUCKET_CONFLICT` at `httpServer`, because the loser would be a number someone read and nothing applied |
 | a `rateLimit.tenantBucket` naming a bucket nothing declares | `X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN` at `defineHttpConfig`, because the name would fall through to `default` and a whole tenant's cap would silently be the 120-burst read bucket |
-| 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 |
+| an injected limiter that does not hold a bucket a route declares | `X_RATE_LIMIT_BUCKET_UNBOUND` at `httpPipeline`, 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 |
+| 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 `httpServer({ …, 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,9 +127,14 @@ 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,
+  httpServer,
   defineHttpConfig,
   type RateLimitStore,
   type Route,
@@ -128,7 +143,7 @@ import {
 declare const routes: readonly Route[];
 declare const myStore: RateLimitStore;   // postgresRateLimitStore({ executor }), say
 
-createServer({
+httpServer({
   routes,
   config: defineHttpConfig({ rateLimit: { scope: 'shared' } }), // this limit is the fleet's
   rateLimitStore: myStore,                                      // whose own scope is 'shared'
@@ -149,7 +164,7 @@ the one nobody declared. A limiter with `enabled: false` owes no declaration: no
 so nothing can be wrong.
 
 `rateLimitStore` feeds the `PipelineDeps.limiter` seam rather than sitting beside it: the bucket
-maths stays in `createRateLimiter`, so every driver agrees on the numbers.
+maths stays in `rateLimiter`, so every driver agrees on the numbers.
 
 **One request spends a LIST of keys, `As of 2026-08-24`** — the caller's (`actor`, else `org`,
 else `ip`) and, when the app declared `rateLimit.tenantBucket`, that caller's tenant. The key
@@ -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`.
@@ -172,7 +187,7 @@ line over the client the boot already opened; **never `Bun.sql`**, whose `.query
 ```ts
 import { db, type SqlFragment } from '@ultimat3/db';
 import {
-  createServer,
+  httpServer,
   defineHttpConfig,
   type PgExecutor,
   postgresRateLimitStore,
@@ -189,7 +204,7 @@ const executor: PgExecutor = {
     client.query<R>({ text, values } satisfies SqlFragment),
 };
 
-createServer({
+httpServer({
   routes,
   config: defineHttpConfig({ rateLimit: { scope: 'shared' } }),
   rateLimitStore: postgresRateLimitStore({ executor }),
@@ -202,7 +217,7 @@ rule. `nowMs` is required and must come from the same clock the takes use — me
 server's clock instead, the offset between the two reads as refill and deletes buckets a throttled
 caller is still sitting in.
 
-The maths reads an injected `Clock`, defaulting to `systemClock`: `createRateLimiter({ config,
+The maths reads an injected `Clock`, defaulting to `systemClock`: `rateLimiter({ config,
 clock })`. **Breaking, `As of 2026-08-19`** — it took `now?: () => number` before and read
 `Date.now()` when nothing passed one, which both production call sites did, so the limiter that
 actually throttles a request could not be frozen. Replace `now: () => t` with
@@ -212,7 +227,7 @@ actually throttles a request could not be frozen. Replace `now: () => t` with
 ### A route may bring its own bucket
 
 `meta.rateLimit` names a bucket; `meta.rateLimitBucket` is the numbers that bucket must hold.
-`withRouteBuckets` registers them at construction — `createServer` and `createPipeline` both apply
+`withRouteBuckets` registers them at construction — `httpServer` and `httpPipeline` both apply
 it, idempotently — because `defineHttpConfig` runs before any route exists and cannot have them.
 Without that half, a name nothing defined fell through `bucketFor` to `default`: an action
 declaring `limit: 5` ran on 120 burst, and the number reached the OpenAPI document all the same.
@@ -238,7 +253,7 @@ the same rule as `RateLimitStore.scope` — and `assertRouteBuckets` compares it
 at construction. A limiter passed to `PipelineDeps.limiter` that cannot enforce a declared bucket
 is refused rather than rebound: a `RateLimiter` is opaque, so rebinding would mean discarding the
 store it carries, and a caller who built their own limiter may have meant their own numbers. Pass
-the **store** — `createServer({ routes, rateLimitStore })` — and the pipeline builds the limiter
+the **store** — `httpServer({ routes, rateLimitStore })` — and the pipeline builds the limiter
 from the merged table for you.
 
 ## Routing
@@ -249,19 +264,25 @@ flip. `HEAD` falls back to the `GET` route. `meta.auth` is **required** — a ro
 cannot forget to declare its auth posture.
 
 ```ts
-import { createServer, defineHttpConfig, json } from '@ultimat3/http';
+import { httpServer, defineHttpConfig, jsonResponse } from '@ultimat3/http';
 
-const handle = createServer({
+const handle = httpServer({
   routes: [{ method: 'GET', path: '/posts/:id', meta: { name: 'posts.show', auth: 'public' },
-             handler: (req) => json({ id: req.param('id') }) }],
+             handler: (req) => jsonResponse({ id: req.param('id') }) }],
   config: defineHttpConfig({ port: 3000 }),
   role: 'web',
 }).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
@@ -306,6 +327,12 @@ exactly three things. Apps declare it through `defineApi({ http: { mounts } })`
 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.
 
+`resolveToken(token, facts)` (`As of 2026-10`): `facts` is `RequestFacts` — `{ address, userAgent,
+origin, path }`, frozen, built by `requestFacts()`. `address` is `ctx.ip`, the pipeline's
+trusted-hop answer, never a forwarding header. `@ultimat3/mcp` hands its resolver the same object
+(`McpRequestFacts`), so one resolver can bind a token to a network or refuse a browser `Origin` on
+both doors. A one-argument resolver still works.
+
 ## Inbound webhooks
 
 `verifyWebhookSignature(request, { secret })` is the receiving half of the framework's webhook
@@ -348,7 +375,10 @@ well formed and carried a credential, and the credential is what failed. Neither
 sign-in redirect, which keys on `X_UNAUTHENTICATED` alone.
 
 The sending half is `webhook()` in `@ultimat3/jobs`. Neither package may import the other, so the
-canonical string is stated in both and pinned by one literal vector asserted in both test files.
+wire format — the canonical string, `WEBHOOK_ID_HEADER`, `WEBHOOK_SIGNATURE_HEADER`,
+`WEBHOOK_TOPIC_HEADER`, `WEBHOOK_SIGNATURE_VERSION` — is `@ultimat3/core`'s
+(`webhook-signature.ts`), and a receiver imports the names from there: 25.0.0 dropped this
+package's re-exports of them, and of `escapeHtml` and `readCookie` (`X_HELPER_COPY`).
 
 ## The exact body bytes
 
@@ -383,6 +413,39 @@ export const ingestSesEvent = action({
 | one reader | `bodyRaw()` and `bodyBytes()` share one capped read, so an action that reads both reads the stream once |
 | off HTTP | `X_NO_REQUEST`: a job or an MCP call has no body bytes |
 
+## Setting a cookie
+
+`As of 2026-10-06`. A route handler, a page `load()` or an action cannot hand the pipeline a
+`Response` of its own, so it calls `setCookie` on the request in scope. The line is
+`@ultimat3/core`'s `serializeSetCookie` — the one serializer — appended to the context's response
+headers, which the `response` stage appends to whatever is sent.
+
+```ts
+import { action, t } from '@ultimat3/action';
+import { deleteCookie, setCookie } from '@ultimat3/http';
+import { allow } from '@ultimat3/policy';
+
+export const choosePreferences = action({
+  input: t.object({ theme: t.string.max(16), reset: t.boolean }),
+  output: t.object({ ok: t.boolean }),
+  policy: allow('public'),
+  handle({ input }) {
+    if (input.reset) deleteCookie('theme', { path: '/' });
+    else setCookie('theme', input.theme, { httpOnly: false, maxAge: 60 * 60 * 24 * 365 });
+    return { ok: true };
+  },
+});
+```
+
+| | |
+|---|---|
+| defaults | `Path=/; HttpOnly; Secure; SameSite=Lax` — core's; every option is `SetCookieOptions` |
+| two calls | two `Set-Cookie` lines, in call order. The same name on two paths is two cookies; nothing overwrites |
+| clearing | **`deleteCookie(name, { path, domain })` is the one way**: empty value, `Max-Age=0`, the `Path`/`Domain` (and `Partitioned`) the cookie was set with. `setCookie` with `maxAge: 0`, or an `expires` at or before `ctx.now()`, is `X_COOKIE_INVALID` naming `deleteCookie` |
+| an invalid cookie | `X_COOKIE_INVALID` (core) before anything is appended: a non-token name, `__Host-` without `Secure`, a pair over 4096 octets |
+| off HTTP | `X_NO_REQUEST` in a job, a task or an impersonated child context; `X_NO_CONTEXT` outside any |
+| by hand | refused: `bun run set-cookie-literals` fails the build on a `Set-Cookie` attribute spelled in a literal anywhere but `packages/core/src/cookie.ts` (`X_SET_COOKIE_HAND_BUILT`) |
+
 ## Errors
 
 `X_ROUTE_NOT_FOUND` · `X_METHOD_NOT_ALLOWED` · `X_BODY_INVALID` · `X_UNAUTHENTICATED`

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@ultimat3/http",
-  "version": "23.0.0",
+  "version": "25.0.0",
   "description": "Owned request lifecycle over Bun.serve: router, ordered pipeline, problem+json errors",
   "license": "MIT",
   "type": "module",
+  "sideEffects": [
+    "./src/error-titles.ts"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/developerz-ai/ultimate.git",
@@ -25,16 +28,16 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "23.0.0",
-    "@ultimat3/i18n": "23.0.0",
-    "@ultimat3/schema": "23.0.0",
-    "@ultimat3/time": "23.0.0"
+    "@ultimat3/core": "25.0.0",
+    "@ultimat3/i18n": "25.0.0",
+    "@ultimat3/schema": "25.0.0",
+    "@ultimat3/time": "25.0.0"
   }
 }

package/src/app-config.ts

@@ -4,7 +4,7 @@
 // hold this package's types, so an `http` block on `AppConfig` would be a second declaration of
 // `HttpConfigInput` in a package that can never check it against this one.
 
-import type { HttpConfigInput } from './config';
+import { type HttpConfigInput, refuseDeletedHttpKeys } from './config';
 import type { RateLimitConfig } from './rate-limit';
 
 /**
@@ -47,6 +47,8 @@ export type AppHttpConfig = Omit<HttpConfigInput, BootOwnedHttpKey | 'rateLimit'
 let declared: AppHttpConfig | undefined;
 
 export const configureHttp = (config: AppHttpConfig): void => {
+  // At the declaration, so the stack names the app's own line — not the boot that merged it.
+  refuseDeletedHttpKeys(config);
   declared = config;
 };