@ultimat3/http 24.0.0 → 25.1.0

package/CLAUDE.md

@@ -13,7 +13,7 @@ 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`
+  `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
@@ -28,9 +28,9 @@ 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**
@@ -46,7 +46,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 - **`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**
@@ -68,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
 
@@ -86,7 +94,10 @@ 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 `trustClientCertHeader` is declared (appending to
   XFF is no promise of stripping a client-sent cert header), and is never an actor.
@@ -131,12 +142,13 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   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`).
+  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, so their body is a stranger's: `{ state, ready,
@@ -168,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`).
@@ -185,10 +200,10 @@ 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 })`.
+  `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.
@@ -200,7 +215,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   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.
 
@@ -210,8 +225,8 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `readWithinLimit` and returns the raw text. The mac is checked BEFORE freshness
   (`X_WEBHOOK_SIGNATURE_STALE` means authentic and old); the window is `Math.abs`; the timestamp is
   digits-only; `:` is refused in id and topic; the comparison is `timingSafeEqual`
-  (`bun run secret-compare`). **The FORMAT is core's** (`packages/core/src/webhook-signature.ts`) —
-  never re-declared here.
+  (`bun run secret-compare`). **An empty `secret` is `X_CONFIG_INVALID`.**
+  **The FORMAT is core's** (`packages/core/src/webhook-signature.ts`) — never re-declared here.
 - Tests must not touch the network — the preload seals `fetch`. Socket tests live in `e2e/` (`bun test
   packages/http/e2e`), sealed; `start()` calls core's `markListening()`. Never unseal.
 
@@ -231,26 +246,29 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `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 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. It negotiates nothing; the cookie is read by `@ultimat3/core`'s `readCookie`, which `index.ts` re-exports |
+| `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

@@ -87,12 +87,12 @@ 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 |
 | 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 |
@@ -100,7 +100,7 @@ What the lifecycle refuses on the caller's behalf, `As of 2026-08`:
 | 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 |
@@ -134,7 +134,7 @@ reads (refill applied, **no write and no row** — a key never taken is full; `r
 
 ```ts
 import {
-  createServer,
+  httpServer,
   defineHttpConfig,
   type RateLimitStore,
   type Route,
@@ -143,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'
@@ -164,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
@@ -185,9 +185,9 @@ and one `insert … on conflict` per take (a peek is one `select`), so N replica
 line over the client the boot already opened; **never `Bun.sql`**, whose `.query` is `undefined`.
 
 ```ts
-import { db, type SqlFragment } from '@ultimat3/db';
+import { baseClient, dbExecutor } from '@ultimat3/db';
 import {
-  createServer,
+  httpServer,
   defineHttpConfig,
   type PgExecutor,
   postgresRateLimitStore,
@@ -196,15 +196,11 @@ import {
 
 declare const routes: readonly Route[];
 
-// The client this process already opened, wrapped in one line. `@ultimat3/cli`'s `pgExecutorFor`
-// is this exact function, and it is what the boot passes when it installs the store for you.
-const client = db();
-const executor: PgExecutor = {
-  query: <R>(text: string, values: readonly unknown[]): Promise<readonly R[]> =>
-    client.query<R>({ text, values } satisfies SqlFragment),
-};
+// The pool this process already opened, never a request's open transaction — the boot builds
+// the same executor when it installs the store for you.
+const executor: PgExecutor = dbExecutor(baseClient);
 
-createServer({
+httpServer({
   routes,
   config: defineHttpConfig({ rateLimit: { scope: 'shared' } }),
   rateLimitStore: postgresRateLimitStore({ executor }),
@@ -217,7 +213,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
@@ -227,7 +223,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.
@@ -253,7 +249,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
@@ -264,11 +260,11 @@ 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();
@@ -327,6 +323,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
@@ -362,6 +364,7 @@ export async function POST(request: Request): Promise<Response> {
 | a replay is detectable | `eventId` is signed and returned, so it cannot be moved in transit; the seen-set is your table, because the framework has nowhere to keep one |
 | moving the timestamp breaks it | the timestamp is inside the canonical string, so editing `t=` on a captured request invalidates the mac |
 | the raw bytes are what is verified | the body is read through core's counting reader — the same one `UltimateRequest` uses — so a sender that declares no length cannot make this handler hold an unbounded payload |
+| no secret is refused, never verified against | an empty or non-string `secret` (an unset `process.env.X`) throws `X_CONFIG_INVALID` before the request is read — a mac under an empty key is one anyone can compute. Only empty is refused, not short: the sender signs with any non-empty secret |
 | the mac is checked BEFORE the window | `X_WEBHOOK_SIGNATURE_STALE` means *authentic and old*, never *unreadable and old*, so an operator reading it goes to a clock or a replay |
 
 `X_WEBHOOK_SIGNATURE_INVALID` and `X_WEBHOOK_SIGNATURE_STALE` are both **401**: the request is
@@ -369,7 +372,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
 
@@ -404,6 +410,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": "24.0.0",
+  "version": "25.1.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": "24.0.0",
-    "@ultimat3/i18n": "24.0.0",
-    "@ultimat3/schema": "24.0.0",
-    "@ultimat3/time": "24.0.0"
+    "@ultimat3/core": "25.1.0",
+    "@ultimat3/i18n": "25.1.0",
+    "@ultimat3/schema": "25.1.0",
+    "@ultimat3/time": "25.1.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;
 };
 

package/src/auth-redirect.ts

@@ -41,33 +41,48 @@ export function signInRedirect(input: {
 /**
  * The other half of the round trip: where to send someone once they HAVE signed in.
  *
+ * `raw` is the value a query or form parser already decoded ONCE — `props.query.next`, an action's
+ * `next` input, `url.searchParams.get('next')` — so it is screened as it arrived and never
+ * decoded again. A second decode changed the destination: `signInRedirect` carried
+ * `/search?q=a%26b`, the parser handed back exactly that, and decoding it again landed on
+ * `?q=a&b`, a different query; `?label=100%25done` threw and fell back. Normalising (below) removes
+ * dot segments only; it never decodes, so `%26` is still `%26`.
+ *
  * Everything except a same-origin path is refused and `fallback` is used instead. `?next=`
  * arrives from the URL bar, so it is attacker-controlled by definition — an unchecked value here
  * is an open redirect on a page whose entire job is to hold a session, which is the exact shape
  * phishing wants: a real domain, a real login, a hop to somewhere else.
  *
  * Refused: an absolute URL (`https://evil.test/x`), a scheme-relative one (`//evil.test`), a
- * backslash the browser normalises to a slash (`/\evil.test`), a value carrying a TAB, CR or LF,
- * and anything not starting `/`.
+ * backslash the browser normalises to a slash (`/\evil.test`), a value carrying any control
+ * character, and anything not starting `/`. A percent-encoded `%2F%2F`, `%5C` or `%09` is NOT
+ * refused, because it is not decoded: a browser resolves a `Location` without decoding it, so
+ * each is an ordinary path segment on this origin — and the final parse below proves it.
  *
  * The control characters are not cosmetic. A browser DELETES tab, CR and LF from a `Location`
- * before it parses one, so `/%09/evil.test` decodes to `/\t/evil.test` — which starts with a
- * single slash, passes a prefix check, and is then parsed as `//evil.test`. The URL parser
- * strips them the same way, which is why the last word here is the parse: whatever a client
- * would actually resolve has to still be a path on this origin.
+ * before it parses one, so `/\t/evil.test` — which starts with a single slash and passes a prefix
+ * check — is parsed as `//evil.test`. NUL, ESC and DEL are not stripped, they are refused by
+ * `Headers`, which is a 500 on the sign-in page. The URL parser strips the first three the same way
+ * a browser does, which is why the last word here is the parse: whatever a client would actually
+ * resolve has to still be a path on this origin.
+ *
+ * The answer is the RESOLVED path, query and fragment — dot segments removed, never the raw
+ * string: a value checked by its resolution and returned unresolved let `/.//evil.test` pass as
+ * same-origin and reach the client router as `//evil.test`. A resolved pathname starting `//` is
+ * refused outright.
+ *
+ * Before the parse, a code point above U+007F is percent-encoded as UTF-8. The parser hands `/日本`
+ * over decoded, `Headers` refuses anything above U+00FF, and a Latin-1 byte in a `Location` is read
+ * as UTF-8 by the browser — so the raw form is not a destination any client can follow. A lone
+ * surrogate has no UTF-8 encoding and falls back.
  */
 export function nextAfterSignIn(raw: string | null | undefined, fallback: string): string {
   if (raw === null || raw === undefined || raw === '') return fallback;
-  // `?next=%` is a bare `URIError`, and this runs while the pipeline is already rendering a 401.
-  let value: string;
-  try {
-    value = decodeURIComponent(raw);
-  } catch {
-    return fallback;
-  }
-  if (!value.startsWith('/')) return fallback;
-  if (value.startsWith('//') || value.startsWith('/\\')) return fallback;
-  if (/[\t\r\n]/.test(value)) return fallback;
+  if (!raw.startsWith('/')) return fallback;
+  if (raw.startsWith('//') || raw.startsWith('/\\')) return fallback;
+  if (hasControlCharacter(raw)) return fallback;
+  const value = encodeNonAscii(raw);
+  if (value === undefined) return fallback;
   // An origin no relative path could reach, so any value that resolves off it left this origin.
   const base = 'http://x.invalid';
   let resolved: URL;
@@ -77,5 +92,29 @@ export function nextAfterSignIn(raw: string | null | undefined, fallback: string
     return fallback;
   }
   if (resolved.origin !== base) return fallback;
-  return value;
+  // Dot segments can hide a `//`: `/.//evil.test` resolves on this origin with the pathname
+  // `//evil.test`, which is another host the moment anything re-reads it without the base.
+  if (resolved.pathname.startsWith('//')) return fallback;
+  // The CHECKED string is the returned one. Returning `value` after checking its resolution let
+  // the two differ, and the router re-resolved the difference off-site.
+  return `${resolved.pathname}${resolved.search}${resolved.hash}`;
+}
+
+/** C0 controls and DEL — the bytes a browser strips from a `Location` or a header refuses. */
+function hasControlCharacter(value: string): boolean {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+}
+
+/** Every run outside printable ASCII as UTF-8 percent-encoding, or `undefined` for a lone surrogate. */
+function encodeNonAscii(value: string): string | undefined {
+  try {
+    // Controls are already refused, so everything this class matches is above U+007E.
+    return value.replace(/[^ -~]+/g, (run) => encodeURI(run));
+  } catch {
+    return undefined;
+  }
 }