@ultimat3/http 29.3.2 → 30.0.0

package/CLAUDE.md

@@ -12,14 +12,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 
 ## Rules — configuration
 
-- **Every numeric knob `defineHttpConfig` resolves is screened** (`port`, `bodyLimitBytes`,
-  `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
-  refusals (`X_TRUST_PROXY_UNSET`, `X_CONFIG_INVALID`), with no `?? 0` behind it.
+- **Every numeric knob `defineHttpConfig` resolves is screened** (`port`, `bodyLimitBytes`, `requestTimeoutMs`, `maxInflight`, `trustedProxyHops`) → `X_CONFIG_INVALID` (borrowed). Full rule: `docs/history/http.md`.
 - **`MAX_PROXY_HOPS` is exported** — `@ultimat3/cli`'s `trustedHopsFromEnv` imports it; one ceiling.
 - Route `meta.auth` is required. Never default a route to public.
 - **An app declares its half of `HttpConfig` through `configureHttp()`**, and the boot lays its own
@@ -31,8 +24,9 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 - **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
+- **`cors.origins: ['*']` with `credentials: true`, or `'null'` in the list, is `X_CORS_CONFIG_INVALID`.** A refused origin
   still gets `vary: origin`.
+- **`DEFAULT_CORS` is what `clientTransport` sends and reads**, off core's constants; `cors.test.ts` observes the transport's real traffic, so a new header fails it. `date` alone stays hidden: this server writes delta-seconds. An app's list replaces the default whole.
 - **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
@@ -52,6 +46,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 - **A request's registered services are LAZY and bound to the authenticated actor**
   (`request-services.ts`, `installServices: false` + `bindRequestServices`): built on first read,
   rebuilt only if actor, locale or tz changed. `request-services.test.ts`.
+- **A shared document renders in `withAnonymousRequest(ctx, url, fn)`**. Full rule: `docs/history/http.md`.
 - **A member's saved locale and zone apply, re-resolved after `auth`**
   (`resolvePreferences`; cookie beats a saved locale, a saved zone beats the cookie).
   `member-preferences.test.ts`.
@@ -64,17 +59,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 - **`hooks.authenticate` has one declaration site: `configureAuthenticator()`.** A route may
   REPLACE it with `meta.authenticate` (never run beside it): `bearerMount` sets it so a session
   cookie authenticates nothing on `/v1/*`.
-- **`bearerMount` re-serves existing `Route`s, never re-projects them** (`bearer-mount.ts`): same
-  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. **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.
+- **`bearerMount` re-serves existing `Route`s, never re-projects them** (`bearer-mount.ts`): the cut is decided in the `auth` stage, outside the scopes is `X_ROUTE_NOT_FOUND`, the prefix is opaque. The token allowance is spent once, in the authenticator, for every resolved token in scope or not (a 422 or 403 before the handler pays). A declared `rateLimit` REPLACES `default` on the mount's routes (`rateLimitedBy: 'handler'`); a route's own `meta.rateLimit` and the tenant allowance stay. A successor `Link` is rewritten in a `finally` to the mounted path when in the cut under a scope the token holds, else removed (`bearer-mount-wire.test.ts`). Full rule: `docs/history/http.md`.
 - **`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`).
@@ -93,20 +78,8 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   the boot's `csp.extend` of that origin exactly. `security.hsts` merges key by key.
 - **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. **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.
-- **One deadline per request** (`deadline.ts`): `requestTimeoutMs` (30 s, `0` off; Bun's
-  `idleTimeout` derives from it, `idle-timeout.ts`), shortened 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. `deadlineAt` is published as core's
-  `ctx.deadlineAt` (`traceHeaders()` sends it on). `deadline.clear()` in the `finally`. **A handler
-  outliving its 504 is held in core's in-flight count** (`beginWork()`, `pipeline-inflight.test.ts`).
+- **Every proxy-supplied header goes through `forwardedElement(header, hops)`**, the entry at `entries.length - hops`, never `[0]`, except `x-forwarded-proto` (`forwardedProto`). `ctx.peer` is `null` unless trusted AND `trustClientCertHeader` is declared, and is never an actor. Full rule: `docs/history/http.md`.
+- **One deadline per request** (`deadline.ts`): `requestTimeoutMs` (30 s, `0` off; Bun's `idleTimeout` derives from it, `idle-timeout.ts`), shortened by `x-request-timeout-ms`, never lengthened. Full rule: `docs/history/http.md`.
 - **`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`
@@ -114,8 +87,10 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 - **`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'`. **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).
+  `mode: 'token'`. **Anonymous is not an exemption** (login CSRF): exempt are `Authorization:
+  Bearer` (cached Basic is ambient), and an anonymous request with NEITHER `Origin` nor `sec-fetch-site` (not a browser).
+  **`meta.csrf: 'cookieless'`** (`/oauth/*`) exempts an ANONYMOUS caller only; `httpRouter`
+  refuses it without `meta.authenticate` (`assertRouteCsrf`).
 - **`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
@@ -157,11 +132,14 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `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()`).
+- **`compress` is the last stage and has no option** (`compress.ts`, its counted read `compress-read.ts`). A signed-in answer is coded only when `immutable` (`compressResponse(..., { anonymous })`, declared, never defaulted). The ceiling is 256 KiB, measured. A response that fails the rule is the SAME object with its body unread. `cache-control` with `private`, `no-store`, `no-cache` or `no-transform` is identity (BREACH); `vary: accept-encoding` goes on every answer past the type and cache conditions, coded or not. `content-length` is the bound: `html`, `textResponse`, `jsonResponse` declare it, `stream` never. A read that overruns, fails or passes `ctx.signal`, and a `gzipSync` throw, log `http.compress_failed` and answer identity, whole: never a request failure.
 
 ## Rules — errors and the problem document
 
-- Statuses live in `error-map.ts` only; the framework table is closed and an app declares its codes
-  with `registerErrorStatus()` (refuses a framework code). No projection of the app's half.
+- Statuses live in `error-map.ts` only; the framework table is closed. The app's half lives in core
+  (`error-status-declared.ts`, `@ultimat3/core/internal/error-status`): an app's own code declares
+  its status with core's `defineError`; `registerErrorStatus()` keeps its refusals (a framework code)
+  and writes there, for codes an app re-raises but does not declare. No projection of the app's half.
   **`error-facts.ts` renders the throwable**; the seam is `declaredStatusFor(code)`, imports one way.
 - **A problem's `type` is `problemTypeFor(code)` = `urn:ultimate:error:<CODE>`; its `docs` is core's
   `ERROR_DOCS_URL`.** `finalize.ts`'s `lastResort` literal is pinned against `problemTypeFor('X_INTERNAL')`.
@@ -178,13 +156,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 - **A rejected value is a log FIELD, never the message** — the `error-map` line's message is the code alone.
 - **A rejected BODY names only what the framework chose**: `bodyInvalid`'s `issues` are a fixed
   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, 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 browser failing `auth: 'required'` is redirected; an agent gets the problem document** (`auth-redirect.ts`, in `error-map` before the overlay). Full rule: `docs/history/http.md`.
 - **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`).
@@ -192,6 +164,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `X_UNAUTHENTICATED`, …); `factsOf` reads a borrowed code's title off the error.
 - Never throw a bare `Error` — use a factory from `errors.ts`. No `any`. Validation goes through
   Standard Schema (`validate.ts`).
+- **Every document carries `retry` at its root** (core's `errorRetry`, through the total `retryOf`); a hidden 5xx answers the class and no cause. `finalize.ts`'s `lastResort` literal is pinned against `toProblem`'s answer for `X_INTERNAL`.
 
 ## Rules — rate limiting
 
@@ -204,12 +177,7 @@ 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 `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.
+- **A failed `auth: 'required'` is metered in the `auth` stage**. Full rule: `docs/history/http.md`.
 - **`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;
@@ -227,6 +195,8 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   digits-only; `:` is refused in id and topic; the comparison is `timingSafeEqual`
   (`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.
+- **`verifyWebhookSignature` and `verifyBodyHmac` share ONE secret screen** (`assertWebhookSecrets`)
+  and one pair of refusals (`webhookSecretMissing`, `webhookSignatureInvalid`), each naming its caller.
 - 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.
 
@@ -249,6 +219,8 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `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` |
+| `object-response.ts` | `objectResponse`, the one answer for an object held elsewhere, structural (no storage import); `notModified`, the one `if-none-match` answer |
+| `stored-object-headers.ts` | inline only for raster images, audio, video; else `attachment` + `sandbox`. Private to `objectResponse` |
 | `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 |
@@ -263,6 +235,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `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 |
+| `webhook-hmac.ts` | `verifyBodyHmac`: a vendor's HMAC-SHA256 over named bytes, UTF-8 secret, rotation list, constant-time; answers `{ bytes, text }` |
 | `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 |
@@ -270,6 +243,8 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `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 |
+| `compress.ts` | the `compress` stage's rule: which answers leave gzipped |
+| `compress-read.ts` | the one body read that rule does: counted, deadline-bound, replayable |
 
 ## Commands
 

package/README.md

@@ -4,6 +4,14 @@ A thin, **owned** layer over `Bun.serve`. Not a framework-agnostic HTTP kit —
 lifecycle belongs to us so ALS context, tracing, locale/tz and authz are impossible
 to skip.
 
+`bun add @ultimat3/http` · guide: [Routes And Render Modes](https://github.com/developerz-ai/ultimate/wiki/Routes-And-Render-Modes)
+
+```ts
+import { configureHttp } from '@ultimat3/http';
+
+configureHttp({ bodyLimitBytes: 8 * 1024 * 1024, requestTimeoutMs: 300_000 });
+```
+
 ## What it owns
 
 | Concern | Module |
@@ -49,6 +57,11 @@ above could be set from an app at all — `cors.origins` was `[]` in every deplo
 every cross-origin browser call, permanently. `AppConfig` has never carried an `http` key and does
 not gain one: `@ultimat3/core` is tier 0 and cannot hold this package's types.
 
+`cors.allowHeaders` and `cors.exposeHeaders` default to what the typed clients send and read, off
+core's constants (`idempotency-key`, `x-request-timeout-ms`, `traceparent`; `x-ultimate-records`,
+`x-ultimate-dates`, `x-ultimate-replayed`, `ratelimit-*`, `deprecation`, `sunset`, `link`), so
+listing an origin is the whole declaration. A list of the app's own replaces the default whole.
+
 `AppHttpConfig` is `Omit<HttpConfigInput, BootOwnedHttpKey>` — `port`, `hostname`, `dev`,
 `buildId`, `signInPath`, `trustProxy`, `trustedProxyHops` and `rateLimit.scope` are the boot's, and
 writing one here is a **type error** rather than a value silently overwritten at the next boot.
@@ -60,17 +73,17 @@ something.
 
 ```
 request-id → admit → trace → context → locale → auth → rate-limit → csrf → body → authz
-           → handler → cache-headers → (error-map) → response
+           → handler → cache-headers → (error-map) → response → compress
 ```
 
 Exported as `PIPELINE_STAGES`, each entry carrying a `why`. `pipeline.test.ts`
-asserts the order; `/_x` renders it. Ordering rules worth restating:
+asserts the order. 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. 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 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. A route declaring `meta.csrf: 'cookieless'` (an RFC 6749 token endpoint) passes an anonymous caller; it needs its own `meta.authenticate`, or `httpRouter` refuses it `X_CONFIG_INVALID` |
 | 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 |
@@ -116,6 +129,7 @@ What the lifecycle refuses on the caller's behalf, `As of 2026-08`:
 | `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 |
+| a public text answer, 1 KiB to 256 KiB, with a declared length | gzip on the wire, from the last stage (`compress`), `vary: accept-encoding` and a weak `etag`. A private answer, a signed-in one that is not `immutable`, `no-transform`, a range or an undeclared length stays identity and unread. HEAD carries GET's coded headers. `html`, `textResponse`, `jsonResponse` declare their bytes; `stream` never does. Exported: `isCompressibleType(contentType)`, `COMPRESS_MIN_BYTES`, `COMPRESS_MAX_BYTES` |
 
 `handle()` resolves to a Response, always — a stage that throws after the handler, or while
 rendering another stage's throw, degrades to `X_PIPELINE_FINALIZE_FAILED` (500, the stage named in
@@ -305,6 +319,12 @@ every stage (middleware, finalize, security headers), and an upgraded request mu
 halves above cannot carry a case, the fallback is a long-poll `action` (`GET`-shaped, returning
 `{ frames, cursor }` and re-called on return), which is what the app that asked shipped.
 
+A client that is **not a browser** (a device agent) is the one exception, and it is declared, not
+hand-written: `deviceSocket()` from `@ultimat3/realtime/server` ([Realtime](../../wiki/Realtime.md#device-sockets)).
+Several mounts on one listener — the sync node's beside a device socket's — are joined by
+`joinWebSocketMounts(mounts)`: routed by path at the upgrade, and each socket's events back to the
+mount that upgraded it, keyed by the `data` object it upgraded with (`As of 2026-11-06`).
+
 ### A second door: `bearerMount` (`/v1/*`)
 
 `As of 22.6.0`. `bearerMount({ prefix, routes, scopes, resolveToken, rateLimit?, rateLimitStore? })`
@@ -318,7 +338,9 @@ exactly three things. Apps declare it through `defineApi({ http: { mounts } })`
 | no / unresolved token | 401, `WWW-Authenticate: Bearer` / `Bearer error="invalid_token"` |
 | a primitive outside the token's `scopes` | 404 `X_ROUTE_NOT_FOUND`, identical to an unknown path — MCP's hidden-tool rule |
 | per-token allowance | `RateLimit-Limit/-Remaining/-Reset` on every answer, 429 + `Retry-After` past it; keyed by a SHA-256 of the token |
-| paths | `/api/<x>` → `<prefix>/<x>`, `/_x/query/<x>` → `GET <prefix>/<x>` (`mountedPath`) |
+| paths | `/api/<x>` → `<prefix>/<x>`, `/_x/query/<x>` → `GET <prefix>/<x>` (`mountedPath`); a pinned `:param` template keeps its params — `/orders/:id/refund` → `<prefix>/orders/:id/refund`. Only the prefix is parameter-free |
+| `rateLimit` declared | spent once per request in the mount's authenticator, before `body` and `authz`, so a 422 or a 403 pays too; it REPLACES `default` on the mount's routes (`rateLimitedBy: 'handler'`); a route's own `meta.rateLimit` and the tenant allowance still apply. Not declared: `default` stands |
+| `Link: rel="successor-version"` | the mounted path when the successor is in the cut and this token holds its scope, success or refusal; otherwise removed. Any other `Link` is the handler's |
 
 `RouteMeta.authenticate` is the mechanism: a route that states one is reached only through it.
 
@@ -338,8 +360,9 @@ mechanism. It is a plain function and not a pipeline stage, because the secret i
 and only the route knows which one applies.
 
 ```ts
-// apps/web/webhooks/partner.ts — mounted as a plain HTTP route through the `routes` runtime
-// override (apps/web/runtime.ts); `api/` holds no route file
+// The check alone. Mounted, it is the `verify` of a `webhookReceiver()` from @ultimat3/jobs —
+// verify(inbound) { return verifyWebhookSignature(inbound.request(), { secret }) } — which
+// queues durably before it acks; a hand-mounted route like this one acks before anything is kept.
 import { verifyWebhookSignature } from '@ultimat3/http';
 
 declare const env: { readonly PARTNER_WEBHOOK_SECRET: string };   // the app's defineEnv() result
@@ -380,6 +403,36 @@ wire format — the canonical string, `WEBHOOK_ID_HEADER`, `WEBHOOK_SIGNATURE_HE
 (`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`).
 
+### A vendor's hmac: `verifyBodyHmac`
+
+Every other sender signs its own way, so no vendor verifier ships. `verifyBodyHmac` is the one
+shared step: HMAC-SHA256 under a UTF-8 secret over the bytes you name, compared in constant time,
+under any secret of a rotation list. Which bytes (`body`, `${t}.${body}`) and which header are the
+vendor's, and yours to pass. A secret the vendor hands out encoded (Svix's base64 `whsec_`) is not
+this helper's: the mail receivers decode their own. It answers `{ bytes, text }` — read the event
+id from `text`, never from an unsigned header.
+
+```ts
+import { verifyBodyHmac } from '@ultimat3/http';
+
+declare const bytes: Uint8Array;            // the exact body — `webhookReceiver`'s inbound.bytes
+declare const headers: Headers;
+
+const { text } = verifyBodyHmac({
+  bytes,
+  secret: [Bun.env['VENDOR_SECRET'] ?? '', Bun.env['VENDOR_SECRET_PREVIOUS'] ?? ''],
+  given: headers.get('x-hub-signature-256'),
+  encoding: 'hex',                          // or 'base64'
+  prefix: 'sha256=',                        // compared, never stripped
+});
+```
+
+| Answer | When |
+|---|---|
+| `{ bytes, text }` | one secret's mac, behind `prefix`, equals `given`; `text` is `null` when the bytes are not UTF-8 |
+| `X_WEBHOOK_SIGNATURE_INVALID` (401) | no signature, or none matches. The cause names the encoding, the prefix and the secret count — never a mac, a secret or a byte |
+| `X_CONFIG_INVALID` | an empty or unset secret, an empty list, or one empty entry in it |
+
 ## The exact body bytes
 
 `As of 2026-09-24`. `UltimateRequest#bodyBytes()` returns the body exactly as it was sent,
@@ -413,6 +466,27 @@ 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 |
 
+## Serving a stored object
+
+`As of 2026-11-02`. `objectResponse(request, { object, open }, { cache?, headers? })` is the one
+correct answer to a GET for bytes held elsewhere: `/_storage`, `/media`, a query's download, and your
+own route for an object a stranger may fetch.
+
+| Argument | Is |
+|---|---|
+| `request` | anything with `header(name)` |
+| `object` | `{ contentType, size, etag?, lastModified? }`. Structural: this package imports no storage, and a `StorageObject` fits. No etag (or `''`): no `etag` header, no 304 |
+| `open(range?)` | exactly those bytes as a `BodyInit`, or a promise of them. A 304 and a 416 open nothing |
+| `cache` | a `CacheHint` applied to every status. Omitted, the route's `meta.cache` decides |
+| `headers` | replaces the stored-object rule (`attachment` + `sandbox` for any type but a raster image, audio or video), for a caller with its own |
+
+A failing `if-range` (another etag, a weak one, a date that is not exact) ignores the range and
+answers the whole object, so no window of an older revision is spliced onto this one.
+
+`notModified(request, etag, headers?)` is the 304 alone, or `undefined`, for bytes not yet in hand: a
+route that would have to decode to answer asks it first. `*`, a weak validator and a comma list all
+count.
+
 ## Setting a cookie
 
 `As of 2026-10-06`. A route handler, a page `load()` or an action cannot hand the pipeline a
@@ -446,6 +520,22 @@ export const choosePreferences = action({
 | 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`) |
 
+## Rendering a shared document
+
+`withAnonymousRequest(ctx, url, (scope) => …)`: run as this request with nobody behind it. What
+`@ultimat3/cli` renders `isr` and `static` in, so a stored document holds no visitor's answer.
+
+| | |
+|---|---|
+| the actor | anonymous, with registered services rebuilt for it |
+| the inbound headers | none: no header is in a stored page's key, and `accept-language` is already `ctx.locale` |
+| `url` | the one handed in: the document's address, already narrowed to its key |
+| `tz` | the app's default; `locale` stays, because it is in the key |
+| `ip`, `peer`, `clientBuildId`, `authz`, `rateLimit`, `readBody` | empty |
+| a redirect | `setRedirect()` lands on `scope`: read it with `takeRedirect(scope)` |
+| the response headers | `scope.headers` is `ctx.headers` |
+| the outer `ctx` | unchanged: the pipeline still answers the identified request privately |
+
 ## Errors
 
 `X_ROUTE_NOT_FOUND` · `X_METHOD_NOT_ALLOWED` · `X_BODY_INVALID` · `X_UNAUTHENTICATED`
@@ -456,6 +546,11 @@ export const choosePreferences = action({
 One `factsOf()` feeds three renderings — terminal, `application/problem+json`, dev
 overlay — so the `code`/`cause`/`fix` strings can never diverge.
 
+Every problem document carries `retry` (`terminal`, `retryable` or `retry-after`, core's
+`errorRetry`) at its root, a 401 and a scope 404 included. A hidden 5xx answers the class and
+nothing else about the failure. It is what a client maps to an exception, so no app carries a
+middleware to add it.
+
 A problem document's `type` and `docs` answer different questions and are two different
 values. `type` is `problemTypeFor(code)` — `urn:ultimate:error:X_BODY_INVALID`, the RFC-9457
 identifier a client switches on, per code, with no host to resolve or rot. `docs` is
@@ -490,6 +585,11 @@ as is `issues`, which has its own top-level home. `@ultimat3/action`'s typed cli
 member back on the rebuilt error's `meta`, so an island reads `error.meta.sessionId` where it
 used to run a regex over `cause`.
 
+A framework code's public keys are not an app's call: they are one reviewed table,
+`problem-meta-framework.ts`, held by its test to a 4xx code and keys an app's declaration could
+carry, none secret-shaped. One row, `As of 2026-11`: `X_METER_EXCEEDED` carries
+`meta: { meter, limit, resetsAt }` (its delay is the `Retry-After` header).
+
 ### Error classes
 
 Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
@@ -511,3 +611,16 @@ nothing for: the error it returns is thrown in place of `X_ROUTE_NOT_FOUND`, `un
 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).
+
+## Supporting exports
+
+`As of 2026-11-02`.
+
+Types of `objectResponse`.
+
+| Name | What |
+|---|---|
+| `ServableObject` | what the answer needs before it opens anything. `StorageObject` is one |
+| `ObjectSource` | `{ object, open }`: `open(range?)` returns the body |
+| `ObjectRequest` | the one thing asked of the request, `header(name)`, so a test needs no `Request` |
+| `ObjectResponseOptions` | `cache` and `headers`. `cache` omitted, the route's declared `meta.cache` decides |

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@ultimat3/http",
-  "version": "29.3.2",
+  "version": "30.0.0",
   "description": "Owned request lifecycle over Bun.serve: router, ordered pipeline, problem+json errors",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "http",
+    "router",
+    "server",
+    "problem-json"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/Routes-And-Render-Modes",
   "license": "MIT",
   "type": "module",
   "sideEffects": [
@@ -35,9 +45,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "29.3.2",
-    "@ultimat3/i18n": "29.3.2",
-    "@ultimat3/schema": "29.3.2",
-    "@ultimat3/time": "29.3.2"
+    "@ultimat3/core": "30.0.0",
+    "@ultimat3/i18n": "30.0.0",
+    "@ultimat3/schema": "30.0.0",
+    "@ultimat3/time": "30.0.0"
   }
 }

package/src/bearer-mount.ts

@@ -4,10 +4,18 @@
 // so there is no second projection of an action to drift from the first. What the mount adds is
 // the credential (only the bearer token authenticates here; a session cookie reaches nothing), the
 // cut (a primitive outside the caller's scopes answers 404, the way MCP answers an unknown tool),
-// and a per-token allowance with `RateLimit-*` and `Retry-After`.
+// and a per-token allowance with `RateLimit-*` and `Retry-After`, which replaces `default`. A route
+// path may be a `:param` template (an action's `http: { path: '/orders/:id/refund' }`): only the
+// PREFIX is parameter-free, and `/v1/orders/:id/refund` is matched by the router as any route is.
 
 import type { Actor, Clock } from '@ultimat3/core';
-import { ACTION_PATH_PREFIX, QUERY_PATH_PREFIX, systemClock } from '@ultimat3/core';
+import {
+  ACTION_PATH_PREFIX,
+  QUERY_PATH_PREFIX,
+  successorLink,
+  successorPathOf,
+  systemClock,
+} from '@ultimat3/core';
 import type { RequestContext } from './context';
 import { bearerMountInvalid, routeNotFound } from './errors';
 import type { RateLimitDecision, RateLimitStore } from './rate-limit';
@@ -58,7 +66,11 @@ export interface BearerMountInput {
    */
   readonly scopes: Readonly<Record<string, readonly string[]>>;
   readonly resolveToken: BearerResolver;
-  /** Requests per window per TOKEN (keyed by a hash of the token itself, never the user). */
+  /**
+   * Requests per window per TOKEN (keyed by a hash of the token itself, never the user). Declared,
+   * it REPLACES the `default` bucket on the mount's routes, which would otherwise cap it at 120 a
+   * minute; absent, `default` stands. A route's own `meta.rateLimit` and the tenant allowance stay.
+   */
   readonly rateLimit?: BearerMountRateLimit | undefined;
   /** Where the per-token buckets live. Defaults to per-process memory; a fleet passes a shared one. */
   readonly rateLimitStore?: RateLimitStore | undefined;
@@ -147,7 +159,7 @@ export function bearerMount(input: BearerMountInput): readonly Route[] {
   const clock = input.clock ?? systemClock;
   // The caller each request resolved to, keyed by ITS context — never a module-level slot two
   // concurrent requests could share.
-  const callers = new WeakMap<RequestContext, { caller: BearerCaller; key: string }>();
+  const callers = new WeakMap<RequestContext, { caller: BearerCaller }>();
 
   // One authenticator per mounted route, closed over ITS scope, so the cut is decided in the `auth`
   // stage — before `body` and `authz`. Decided in the handler, an out-of-scope token was answered
@@ -171,14 +183,15 @@ export function bearerMount(input: BearerMountInput): readonly Route[] {
       }
       // Hidden, never forbidden: a 403 would confirm the primitive exists to a token that was
       // not issued for it — the enumeration MCP's catalog refuses the same way.
-      // And never free: the refusal spends the token's allowance as a served call does (which the
-      // handler charges, once, so the two paths never both spend) — else a token walks the cut
-      // unmetered, and `RateLimit-*` on one 404 but not another tells hidden from unknown.
+      // And never free: every resolved token pays HERE, once, in scope or not. The handler spent
+      // it once, so a body the `body` stage refused or a policy `authz` denied went unmetered.
+      // Out of scope, a token walking the cut would go unmetered too, and `RateLimit-*` on one
+      // 404 but not another would tell hidden from unknown.
+      await spend(tokenKey(token), ctx);
       if (scope === null || !caller.scopes.has(scope)) {
-        await spend(tokenKey(token), ctx);
         throw routeNotFound(ctx.method, ctx.url.pathname);
       }
-      callers.set(ctx, { caller, key: tokenKey(token) });
+      callers.set(ctx, { caller });
       return caller.actor;
     };
 
@@ -200,6 +213,8 @@ export function bearerMount(input: BearerMountInput): readonly Route[] {
 
   const mounted: Route[] = [];
   const seen = new Map<string, string>();
+  // Filled by the loop below, read per request: the whole cut, by the path `/api` serves it at.
+  const cut: Cut = new Map();
   for (const [name, scope] of [...scopeOf.entries()].sort(([a], [b]) => (a < b ? -1 : 1))) {
     for (const route of byName.get(name) ?? []) {
       const path = mountedPath(prefix, route.path);
@@ -209,10 +224,20 @@ export function bearerMount(input: BearerMountInput): readonly Route[] {
         throw bearerMountInvalid(prefix, `${name} and ${owner} would both be served at ${slot}`);
       }
       seen.set(slot, name);
+      cut.set(route.path, (cut.get(route.path) ?? new Set<string>()).add(scope));
       mounted.push({
         method: route.method,
         path,
-        meta: { ...route.meta, auth: 'required', authenticate: authenticatorOf(scope) },
+        meta: {
+          ...route.meta,
+          auth: 'required',
+          authenticate: authenticatorOf(scope),
+          // The authenticator spends the allowance, so the stage spends no `default` beside it: a
+          // mount declaring 12,000 a minute was capped at 120 per route, silently.
+          ...(bucket !== undefined && route.meta.rateLimit === undefined
+            ? { rateLimitedBy: 'handler' as const }
+            : {}),
+        },
         handler: async (request: UltimateRequest, ctx: RequestContext) => {
           const resolved = callers.get(ctx);
           // The authenticator already answered an out-of-scope token; this is the fail-closed
@@ -220,8 +245,12 @@ export function bearerMount(input: BearerMountInput): readonly Route[] {
           if (resolved === undefined || !resolved.caller.scopes.has(scope)) {
             throw routeNotFound(ctx.method, ctx.url.pathname);
           }
-          await spend(resolved.key, ctx);
-          return await route.handler(request, ctx);
+          try {
+            return await route.handler(request, ctx);
+          } finally {
+            // A `finally`: a deprecated route that refuses still announces its retirement.
+            followableSuccessor(ctx.headers, prefix, cut, resolved.caller.scopes);
+          }
         },
       });
     }
@@ -229,6 +258,32 @@ export function bearerMount(input: BearerMountInput): readonly Route[] {
   return [...mounted, ...opaquePrefix(prefix, authenticatorOf(null))];
 }
 
+/** The mount's cut: a route's `/api` path → the scopes that reach it. */
+type Cut = Map<string, Set<string>>;
+
+/**
+ * A successor link the route rendered names the `/api` door, which refuses a bearer caller. In the
+ * cut, under a scope this token holds, it becomes the mounted path. Otherwise it goes: the caller
+ * cannot follow it, and naming a primitive outside its scopes confirms what the cut answers 404
+ * for. Any other `Link` is the handler's own and is not this mount's to touch.
+ */
+const followableSuccessor = (
+  headers: Headers,
+  prefix: string,
+  cut: Cut,
+  held: ReadonlySet<string>,
+): void => {
+  const link = headers.get('link');
+  const served = link === null ? undefined : successorPathOf(link);
+  if (served === undefined) return;
+  const reaching = cut.get(served);
+  if (reaching !== undefined && [...reaching].some((scope) => held.has(scope))) {
+    headers.set('link', successorLink(mountedPath(prefix, served)));
+  } else {
+    headers.delete('link');
+  }
+};
+
 /** Every method a client can send. HEAD is GET's (`router.ts`'s `routeFor`), never its own route. */
 const CATCH_ALL_METHODS = HTTP_METHODS.filter((method) => method !== 'HEAD');