@ultimat3/http 11.3.0 → 13.0.0

package/CLAUDE.md

@@ -20,7 +20,28 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 ## Rules
 
 - Route `meta.auth` is required. Never default a route to public.
-- **`asCtx` is a WIDENING the compiler checks, never a cast.** `RequestContext extends Ctx`, and
+- **An app declares its half of `HttpConfig` through `configureHttp()`, and the boot lays its own
+  facts over it** (`As of 2026-08-24`). Until 12.0.0 the entire tuning surface was **unreachable
+  from a shipped app**: `AppConfig` has never had an `http` key, `RuntimeOverrides` carries none,
+  and the only construction any shipped process made was one fixed literal in
+  `packages/cli/src/dev-roles.ts` passing eight boot facts — so `DEFAULT_CORS.origins` was `[]` in
+  every deployment (an SPA on `app.example.com` calling `api.example.com` could not work, ever),
+  `bodyLimitBytes` was 1 MiB for a 4 MB CSV endpoint, `requestTimeoutMs` 30s for a five-minute
+  export, and `rateLimit.buckets` was 120 burst / 2 rps for a bank and a blog alike. Fourteen
+  `fix:` lines told the reader to edit `http.<key>` in `app.config.ts`, which has never held one.
+  It is a registration and not a config key for `configureAuthenticator`'s reason, stated in
+  `hooks.ts`: `@ultimat3/core` is tier 0 and cannot 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. `AppHttpConfig` is `Omit<HttpConfigInput, BootOwnedHttpKey>`,
+  **derived, never listed**: a key the boot always overwrites (`port`, `hostname`, `dev`,
+  `buildId`, `signInPath`, `trustProxy`, `trustedProxyHops`, `rateLimit.scope`) is a type error
+  where an app writes it, rather than a value silently discarded at every boot. `mergeHttpConfig`
+  merges one level down — `security.csp.extend` per DIRECTIVE, because the app's CDN source and
+  the boot's inline-script hash are each the whole answer for something, and either alone breaks a
+  page. `type-pins.ts` holds the other half: a key on `HttpConfig` and not on `HttpConfigInput` is
+  a build error, which `scripts/config-readers.ts` cannot see — that ratchet walks `AppConfig` and
+  asks whether a key is READ, and this is the mirror question.
+- **`asCtx` is a WIDENING the compiler checks, never a cast.** `RequestContext extends Ctx` and
   `asCtx` is the identity function. It used to be `ctx as unknown as Ctx` over an object that set
   none of `clock`, `now`, `logger`, `signal` or `services` — so `ctx.now()` threw
   `TypeError: ctx.now is not a function` on every audited action served over HTTP,
@@ -30,6 +51,46 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   and it is a type-pin rather than a `.test.ts` because `tsconfig.json` excludes tests.
   `ctx.buildId` is core's meaning — the build this PROCESS serves; the CLIENT's claim is
   `ctx.clientBuildId`, read only by `assertBuild()`.
+
+  **`RequestContext extends Ctx` again, and this file no longer BUILDS a context — it composes
+  one** (`As of 2026-08-24`). `Ctx extends CtxServices`, and `CtxServices` is the seam an app
+  augments (`declare module '@ultimat3/core'`) to declare `ctx.posts` — so in an APP's program
+  every service it declared became a REQUIRED member of `createRequestContext`'s object literal,
+  and this file failed to compile inside `examples/dummy` with `TS2739: missing posts, orgs` while
+  the framework's own gate, which augments nothing, stayed green. The framework cannot set members
+  only the app's boot knows about.
+
+  `createRequestContext` now spreads `createContext()`'s result. Those members arrive WITH the
+  base, so the literal is checked in full and there is **no assertion left in this file** —
+  `withServices`, which existed for one release, is gone. `packages/core/src/context.ts` keeps the
+  framework's one irreducible `as Ctx` and its header states, with the four measured alternatives,
+  why it cannot be removed below a major.
+
+  Composing is also one constructor for one shape instead of two. This file used to re-derive
+  `clock`, `now`, the logger child, `signal`, `deadlineAt` and the service bag, so core could fix
+  any of them and this surface would keep the old answer — which is exactly what happened to the
+  bag (see the bullet below). `defineService` factories now install here too, for the same reason:
+  they are `createContext`'s, and this is `createContext`.
+
+  `type-pins.ts` carries `_RequestContextIsACtx`, because `asCtx` is a function body and a future
+  edit answering a failure there with a cast would delete the enforcement and leave the comment.
+  The reverse direction is FALSE by design — core's `Ctx` carries no `requestHeaders`, which is
+  what `assertInRequest` proves one way at runtime.
+- **`defineService` used to be a job-and-CLI feature, and nothing said so** (`As of 2026-08-24`).
+  Two halves, and together they made services unreachable on the surface an app spends its life
+  on. This file built its own service bag from `RequestContextInit.services` alone and never
+  called core's `installedServices()`; `pipeline.ts:224` passes NO `services` at all. So a
+  `defineService('posts', …)` an app registered at boot was installed for a job, a task and a CLI
+  command and for nothing else — over HTTP `ctx.services` was `{}` and `useService('posts')` threw
+  `X_SERVICE_MISSING`. And the bag, even when one was passed, was never spread ONTO the context,
+  so `ctx.posts` — the spelling `docs/architecture/15-adding-a-feature.md` writes in its worked
+  example — read `undefined` beside a populated `ctx.services`.
+
+  Composing `createContext` fixes both at once, which is the argument for composing: the installer
+  is core's and so is the spread. Services go on FIRST so a service an app named `actor` or
+  `logger` loses to the request's own field and stays reachable as `ctx.services['actor']`; the
+  context's meaning never depends on what an app named a service. `context.test.ts` pins the
+  factory install, the spread and the collision order.
 - **The two inbound ids are read BEFORE the context and the span, in `correlation.ts`.** `startSpan`
   resolves its parent from `currentSpanContext()`, which reads `ctx.traceId`, so a `traceparent`
   parsed by a stage arrived one frame after the span's context was already frozen: the caller's
@@ -60,6 +121,14 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   with `AbortSignal.any`, which is what `context.ts` had documented and nothing wired — a closed
   tab held its handler, its pool slot and its vendor connection for the whole 30s. `expired` stays
   the timer's alone: it answers the SOCKET, and a caller that hung up has no socket to answer.
+  **And it leaves this process on the next hop's headers, `As of 2026-08-24`**:
+  `Deadline.deadlineAt` is published as core's `ctx.deadlineAt`, and `traceHeaders()` (tier 0, the
+  one thing both typed clients spread before the caller's own headers) sends what is LEFT as
+  `x-request-timeout-ms`. Before that the header had exactly one reader — `resolveTimeoutMs`, in
+  this file — and **zero writers anywhere in the tree**, so gateway → A (30s) → B meant a call made
+  at t=29 started B on a FRESH 30s: real work, holding a pool slot and a vendor connection, half a
+  minute after A's socket was answered `X_TIMEOUT`. A spent budget sends no header at all rather
+  than `0`, because `resolveTimeoutMs` ignores anything under 1ms and falls back to its own.
   With `requestTimeoutMs: 0` the caller's signal is handed through as-is rather than the shared
   never-aborted singleton, which every such request used to share — one `abort` listener per
   request, accumulating for the life of the process. Always `deadline.clear()` in the `finally` —
@@ -95,6 +164,38 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `error-map` stage is the one call site that can see the config, and every degraded `problem()` in
   the tail must stay opaque. The real text is not lost — it is the log field and the error report,
   both keyed by the request id the caller was given.
+- **The problem document carries the ISSUE LIST, and the opacity rule applies to it**
+  (`As of 2026-08-24`). `ProblemDocument.issues` is a top-level extension member — RFC 9457 §3.2
+  puts extension members at the document root and every Ultimate extension already is one
+  (`code`, `cause`, `fix`, `docs`, `requestId`); there is no bag. `@ultimat3/action` has attached
+  the list to `meta.issues` since `InputInvalidError` grew its third parameter and **nothing
+  carried it**, so every app in this framework recovered per-field form errors by splitting
+  `cause` on `'; '` — guesswork the moment a message contains the separator.
+
+  Four rules, and the third is the one most likely to be dropped by a later edit.
+  `issuesOf` is TOTAL and module-private, written in `retryAfterOf`'s shape and for its reason:
+  `meta` is a property read on a value this package did not build, in the frame that decides what
+  the caller sees. It is **all-or-nothing** — a client that finds `issues` uses it INSTEAD of
+  `cause`, so one unreadable entry drops the whole list back to the prose line rather than
+  shipping a subset, which would be a rejection the user never sees and a form reporting itself
+  valid. The member is **absent** when there is none, never `undefined` and never `[]`:
+  `JSON.stringify` drops an `undefined`, but this interface is read directly by `error-page.ts`
+  and by tests, and `[]` claims "validated clean" about a request that was just refused — which
+  the first implementation of this reader emitted, because `Array.isArray([])` is true and the
+  loop simply does not run. A list past `MAX_PROBLEM_ISSUES` (100) is dropped WHOLE for the same
+  all-or-nothing reason, and because `@ultimat3/action`'s `issuesFromWire` bounds it identically
+  on arrival: sending it is a body that costs the wire and answers nothing. That package is tier 3,
+  so the number is restated here and pinned on this side. And it is **dropped under exactly the condition
+  that blanks `title`/`detail`/`cause`** — an issue list on an unclassified 5xx is precisely the
+  internal detail `INTERNAL_CAUSE` exists to withhold, because it names the fields and the
+  expectations of something the caller was never meant to see inside. `X_INPUT_INVALID` is a
+  declared 4xx and so is never opaque.
+
+  `received` is forced to `''` and every entry is rebuilt member by member, never spread. Not
+  redundancy with `toValidationIssues`, which forces the same thing: this is the boundary where
+  the value LEAVES the process, a conforming library's own issue object is first-class here and
+  routinely carries the rejected value, and `@ultimat3/schema`'s `describeValue` exists because a
+  password-strength rule once wrote mistyped passwords into the log index.
 - **A rejected value is a log FIELD, never part of the message.** `logger.emit()` redacts `bound`,
   `contextFields` and `fields` — and never `msg` — so `logger.error(\`${code}: ${cause}\`)` in the
   `error-map` stage wrote a rejected password verbatim into the log store, at 4xx, which is logged
@@ -242,6 +343,14 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `lastResort` spells its one `type` as a literal because that function calls nothing, and
   `pipeline-finalize.test.ts` pins the literal against `problemTypeFor('X_INTERNAL')` so the two
   cannot drift. Never assert either value as a copied string — import the constant.
+- **`error-map.ts` answers the status; `error-facts.ts` renders the throwable** (`As of
+  2026-08-24`). One file did both and reached 501 lines, over the ceiling. The seam between
+  them is `declaredStatusFor(code)` — `number | undefined`, exported to this package only —
+  because the two questions are genuinely different: `statusFor` always answers a number, while
+  "did ANYBODY classify this code" is what decides whether a 5xx may carry the throwable's own
+  words back to the caller (`isUnclassifiedFailure`). Imports go one way, `error-facts.ts` →
+  `error-map.ts`; a status read from the facts file would be the second table this package
+  spent a release deleting.
 - Statuses live in `error-map.ts` only. No other file writes a status number. The framework's
   table (`ERROR_STATUS`) is closed; an app declares its own codes' statuses with
   `registerErrorStatus()`, which refuses a code the framework already holds. Without that half,
@@ -309,8 +418,24 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `X_INTERNAL`, built with no call that could fail in turn, and the renderer's own failure goes to
   the log as `pipeline.problem_failed` — a last resort sharing a code path with what just broke is
   not one.
+- **One request spends a LIST of rate-limit keys, and the tenant's is the second** (`As of
+  2026-08-24`). `rateLimitKey` picked ONE subject — actor > org > ip, exclusive — and `actorView`
+  answers `null` for anonymous, so `orgId` was consulted only for a caller with an org and no id:
+  **no authenticated request ever touched an org bucket**. A tenant with 8,000 seats whose
+  integration entered a retry loop therefore took 8,000 × the per-actor burst against one shared
+  pool, every bucket inside its own limit, and no number an operator could set would have refused
+  it — while `@ultimat3/jobs` has had `perTenant` since it shipped. `rateLimitSpends` answers the
+  caller's key **and** `tenant|org:<id>` when the app declared `rateLimit.tenantBucket`; the stage
+  spends them in order and stops at the first refusal, so a caller its own bucket already refused
+  costs its tenant nothing. The tenant key is deliberately NOT scoped to the route — a per-route
+  tenant bucket is the same number multiplied by the route table, which is not a cap. `null` is
+  the default because one tenant is a person and the next is five thousand seats (axiom 8), and a
+  name nothing declares is `X_RATE_LIMIT_TENANT_BUCKET_UNKNOWN` at `defineHttpConfig`, never a
+  silent fall-through to `default`. The headers report the bucket **closest to refusing**: telling
+  a client `remaining: 99` off its own bucket while its tenant's holds 2 is a number that plans a
+  caller into a 429.
 - **The memory rate-limit store is bounded, and the eviction order is part of the guarantee.**
-  The key falls back to the connection address (`rateLimitKey`), so a scan rotating through an
+  The key falls back to the connection address (`rateLimitSpends`), so a scan rotating through an
   IPv6 /64 mints one entry per request — an unbounded map hands the flood the process. Every
   entry carries `forgetAtMs`, the instant a refilled bucket becomes indistinguishable from a
   missing one, and the sweep drops those for free. `DEFAULT_MAX_RATE_LIMIT_KEYS` is the backstop,
@@ -378,6 +503,33 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   is opaque, so rebinding means discarding the caller's limiter and the store it carries, and a
   caller who built their own may have meant their own numbers. A limiter that declares no table
   is refused too — what cannot be shown to hold is not assumed to hold.
+- **`verifyWebhookSignature` is a FUNCTION, never a pipeline stage** (`As of 2026-08-24`). The
+  secret is per SENDER, and only the route knows which sender it is serving; a stage would need one
+  secret for the whole app or a table this package has no business holding. It reads the body
+  through core's `readWithinLimit` — the same counting reader `UltimateRequest.#read` uses — so it
+  composes with the cap rather than defeating it, and it answers the raw text so the caller parses
+  the bytes that were signed rather than a re-serialisation of them.
+
+  The order inside it is load-bearing: the mac is checked BEFORE the freshness window, so
+  `X_WEBHOOK_SIGNATURE_STALE` means *authentic and old* and never *unreadable and old* — an
+  operator reading it goes to a clock or a replay, which is the only reason the second code exists.
+  The window is `Math.abs`, both directions: a sender whose clock runs ahead is the same replay
+  window pointed the other way, and accepting the future half doubles it. The timestamp is parsed
+  digits-only because `Number('nope')` is `NaN` and `NaN > toleranceMs` is FALSE — the one guard
+  whose failure mode is "the check does not run". `:` is refused in the id and the topic because
+  one mac over `v1:t:evt:01HZ:orders.paid:<body>` would otherwise authenticate two different
+  id/topic splits. The comparison is `timingSafeEqual` and may never become `===`; `bun run
+  secret-compare` is the mechanical half and `mac`/`signature` are names it reads.
+
+  **The FORMAT is `@ultimat3/core`'s and is not re-declared here** (`As of 2026-08-24`).
+  `packages/core/src/webhook-signature.ts` owns the canonical string, the mac and the parse;
+  this file owns the POLICY — what counts as fresh, how large a body may be, and which refusal a
+  receiver answers with. It shipped for one release as two implementations, here and in
+  `@ultimat3/jobs`, held together by a hex literal asserted in two test files: this package is
+  tier 2 and may not reach tier 3, that one's boundary forbids `http`, so the one copy lives at
+  the tier both can reach — the argument `timing-safe-equal.ts` makes for itself. The two literal
+  vectors stay until `scripts/webhook-round-trip.test.ts` replaces them. **Never re-declare the
+  canonical string here.**
 - Never throw a bare `Error` — use a factory from `errors.ts`.
 - No `any`. Validation goes through Standard Schema (`validate.ts`), not a vendor API.
 - Health endpoints answer outside the pipeline, on purpose.
@@ -402,12 +554,13 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `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 |
-| `error-map.ts` | code → status table + `factsOf()` |
+| `error-map.ts` | the code → status table, closed, plus the app's half (`registerErrorStatus`) |
+| `error-facts.ts` | every RENDERING of a throwable: `factsOf()`, the problem document (including the issue list and the opacity rule over it), the three terminal lines |
 | `hooks.ts` | the seams: `authenticate`, `authorize`, `devNotices` + the app's `configureAuthenticator()` |
 | `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` + the single `Ctx` adapter (`asCtx`) + the inbound-header readers |
+| `context.ts` | `RequestContext` (core's `Ctx` plus the request's own), composed from `createContext`, the single `Ctx` adapter (`asCtx`) and the inbound-header readers |
 | `redirect.ts` | the intent slot a handler that cannot return a `Response` fills |
 | `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 |
@@ -419,8 +572,10 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `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 |
+| `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 |
 | `rate-limit-buckets.ts` | the one point routes and config meet: a route's own bucket, registered or refused |
+| `app-config.ts` | the app's own HTTP declaration (`configureHttp`) and the layering that keeps a boot fact above it |
 
 ## Commands
 

package/README.md

@@ -13,8 +13,10 @@ to skip.
 | the ordered request lifecycle | `pipeline.ts` |
 | typed request (params, query, body) | `request.ts` |
 | response constructors + `problem()` | `response.ts` |
-| code → status, `factsOf()` | `error-map.ts` |
+| code → status, closed table | `error-map.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` |
 | the request deadline and `ctx.signal` | `deadline.ts` |
@@ -22,6 +24,37 @@ to skip.
 | the inbound request id and trace, read before the span | `correlation.ts` |
 | dev error overlay | `overlay.ts` |
 
+## What an app declares: `configureHttp()`
+
+```ts
+// apps/web/app/http.ts — module scope, imported by the app like any other module
+import { configureHttp } from '@ultimat3/http';
+
+configureHttp({
+  cors: { origins: ['https://app.example.com'], credentials: true },
+  bodyLimitBytes: 8 * 1024 * 1024,   // this API takes a 4 MB CSV
+  requestTimeoutMs: 300_000,          // and an export that really does take five minutes
+  rateLimit: {
+    tenantBucket: 'tenant',
+    buckets: { tenant: { capacity: 5_000, refillPerSecond: 100 } },
+  },
+});
+```
+
+One registration, read once by whatever process starts the web role — the same seam
+`configureAuthenticator()` is. **Breaking, `As of 2026-08-24`**: before it, the only `HttpConfig`
+any shipped process built was a fixed literal inside `@ultimat3/cli`, so none of the four values
+above could be set from an app at all — `cors.origins` was `[]` in every deployment, which refuses
+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.
+
+`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.
+`mergeHttpConfig(configuredHttp(), boot)` is the layering, and it merges `security.csp.extend` per
+directive: the app's CDN source and the boot's inline-script hash are each the whole answer for
+something.
+
 ## The pipeline is the guarantee
 
 ```
@@ -57,6 +90,7 @@ What the lifecycle refuses on the caller's behalf, `As of 2026-08`:
 | 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 |
+| 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 |
 | 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 |
@@ -79,6 +113,16 @@ thing that knows where its counters live, and a framework that inferred the answ
 environment would get it wrong on the first deployment that scaled differently.
 
 ```ts
+import {
+  createServer,
+  defineHttpConfig,
+  type RateLimitStore,
+  type Route,
+} from '@ultimat3/http';
+
+declare const routes: readonly Route[];
+declare const myStore: RateLimitStore;   // postgresRateLimitStore({ executor }), say
+
 createServer({
   routes,
   config: defineHttpConfig({ rateLimit: { scope: 'shared' } }), // this limit is the fleet's
@@ -102,6 +146,18 @@ 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.
 
+**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
+builder used to pick exactly ONE subject and consult `orgId` only when there was no actor id,
+which no authenticated request ever satisfies: a tenant with 8,000 seats took 8,000 × the
+per-actor burst against one shared pool, every bucket inside its own limit, and no number an
+operator could set would have refused it. The tenant key is `tenant|org:<id>` and is deliberately
+NOT scoped to the route — a per-route tenant bucket is the same allowance once per route. The
+spend stops at the first refusal, so a caller its own bucket refused costs its tenant nothing, and
+the `ratelimit-*` headers report the bucket closest to refusing. `tenantBucket` defaults to `null`:
+one tenant is a person and the next is five thousand seats, so there is no allowance a framework
+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,
 `scope: 'shared'` was a declaration nothing in the framework could satisfy while `x new` scaffolded
@@ -188,6 +244,8 @@ 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';
+
 const handle = createServer({
   routes: [{ method: 'GET', path: '/posts/:id', meta: { name: 'posts.show', auth: 'public' },
              handler: (req) => json({ id: req.param('id') }) }],
@@ -199,11 +257,56 @@ const handle = createServer({
 Static paths are registered in Bun's native `routes` table; param/wildcard paths fall
 through to `fetch`. Method resolution stays ours so a 405 still carries problem+json.
 
+## Inbound webhooks
+
+`verifyWebhookSignature(request, { secret })` is the receiving half of the framework's webhook
+mechanism. It is a plain function and not a pipeline stage, because the secret is **per sender**
+and only the route knows which one applies.
+
+```ts
+// apps/web/api/webhooks/partner/route.ts
+import { verifyWebhookSignature } from '@ultimat3/http';
+
+declare const env: { readonly PARTNER_WEBHOOK_SECRET: string };   // the app's defineEnv() result
+// The seen-set and the dispatch are the app's — this package has nowhere to keep either.
+declare function alreadyHandled(eventId: string): Promise<boolean>;
+declare function handle(topic: string, payload: unknown, eventId: string): Promise<void>;
+
+export async function POST(request: Request): Promise<Response> {
+  const { eventId, topic, body } = await verifyWebhookSignature(request, {
+    secret: env.PARTNER_WEBHOOK_SECRET,
+  });
+  // Parse the bytes that were SIGNED. Never `request.json()` — the stream is spent, and a
+  // re-serialisation would not be the bytes the mac covers.
+  const payload: unknown = JSON.parse(body);
+  if (await alreadyHandled(eventId)) return new Response(null, { status: 200 });
+  await handle(topic, payload, eventId);
+  return new Response(null, { status: 202 });
+}
+```
+
+| Property | How |
+|---|---|
+| constant time | the mac is compared with `@ultimat3/core`'s `timingSafeEqual`, never `===` — where two macs first differ is exactly what a timing oracle forges one byte at a time |
+| a replay expires | the signature's timestamp is checked against `toleranceMs` (5 minutes by default), **both** directions — a sender whose clock runs ahead is the same window pointed the other way |
+| 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 |
+| 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
+well formed and carried a credential, and the credential is what failed. Neither triggers the
+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.
+
 ## Errors
 
 `X_ROUTE_NOT_FOUND` · `X_METHOD_NOT_ALLOWED` · `X_BODY_INVALID` · `X_UNAUTHENTICATED`
 · `X_FORBIDDEN` · `X_RATE_LIMITED` · `X_BUILD_SKEW` · `X_ROUTE_CONFLICT`
-· `X_CORS_CONFIG_INVALID` · `X_RATE_LIMIT_NOT_SHARED`
+· `X_CORS_CONFIG_INVALID` · `X_RATE_LIMIT_NOT_SHARED` · `X_WEBHOOK_SIGNATURE_INVALID`
+· `X_WEBHOOK_SIGNATURE_STALE`
 
 One `factsOf()` feeds three renderings — terminal, `application/problem+json`, dev
 overlay — so the `code`/`cause`/`fix` strings can never diverge.
@@ -217,7 +320,7 @@ in a table row and a table row has no anchor. Assert against `problemTypeFor` an
 
 ## Boundaries
 
-Tier 2. Imports `@ultimat3/core` and `@ultimat3/schema` only. Authentication and
-policy evaluation arrive through `ServerHooks`, declared structurally, because
-`@ultimat3/policy` is a sibling tier. There is no plugin API: `Middleware` wraps a
-handler, the pipeline is everything else.
+Tier 2. Imports `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/i18n` and `@ultimat3/time` —
+tiers 0 and 1, which is the whole rule. Authentication and policy evaluation arrive through
+`ServerHooks`, declared structurally, because `@ultimat3/policy` is a sibling tier. There is no
+plugin API: `Middleware` wraps a handler, the pipeline is everything else.

package/package.json

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

package/src/app-config.ts

@@ -0,0 +1,146 @@
+// The app's own HTTP declaration, and the layering that keeps a boot fact above it. One
+// registration site, read once by whatever process starts the web role — the same seam
+// `configureAuthenticator()` is, and for the same reason: `@ultimat3/core` is tier 0 and cannot
+// 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 { RateLimitConfig } from './rate-limit';
+
+/**
+ * The keys the BOOT owns, and the reason this type is an `Omit` rather than a hand-written list of
+ * what an app may say. Each of these is a fact about the PROCESS — the port it was told to bind,
+ * the build it serves, whether it is `x dev`, how many proxies the deployment puts in front of it,
+ * `auth.signInPath` from `app.config.ts` — so a value an app wrote for one of them would be
+ * overwritten at every boot: a switch with no wire, which is the defect this whole surface exists
+ * to remove. Refused at the type level, which is the build error that enforces it.
+ */
+export type BootOwnedHttpKey =
+  | 'port'
+  | 'hostname'
+  | 'dev'
+  | 'buildId'
+  | 'signInPath'
+  | 'trustProxy'
+  | 'trustedProxyHops';
+
+/**
+ * What an app declares. `rateLimit.scope` is boot-owned for the same reason as the keys above:
+ * `startWeb` DERIVES it from the store it installed, so a literal here would be a second
+ * declaration quietly contradicting the object beside it — and `assertRateLimitScope` compares
+ * exactly those two halves.
+ */
+export type AppHttpConfig = Omit<HttpConfigInput, BootOwnedHttpKey | 'rateLimit'> & {
+  readonly rateLimit?: Omit<Partial<RateLimitConfig>, 'scope'> | undefined;
+};
+
+/**
+ * The app's declaration, if it made one. A single value and not a list, exactly as
+ * `configuredAuthenticator` is: two answers to "how does this server bind and what does it admit"
+ * is two configurations, and the one that ran first wins.
+ *
+ * Process-global for the reason that one is: the app has exactly one boot, and every host that
+ * starts a server (`x dev`, `apps/web/server.ts`) would otherwise need its own way to be handed
+ * the same values — which is what left the whole tuning surface unreachable, since the only
+ * shipped construction was a fixed literal inside the CLI.
+ */
+let declared: AppHttpConfig | undefined;
+
+export const configureHttp = (config: AppHttpConfig): void => {
+  declared = config;
+};
+
+/** What the boot layers its own facts over. `undefined` means the locked defaults stand. */
+export const configuredHttp = (): AppHttpConfig | undefined => declared;
+
+/** Test seam. Production configures once at module scope and never unconfigures. */
+export const resetHttpConfig = (): void => {
+  declared = undefined;
+};
+
+type SecurityInput = NonNullable<HttpConfigInput['security']>;
+type CspInput = NonNullable<SecurityInput['csp']>;
+type CspExtend = NonNullable<CspInput['extend']>;
+
+/**
+ * Per directive, both lists. The app's `script-src` is a CDN it serves scripts from and the boot's
+ * is the sha256 of the hydration runtime this process emits inline — each is the whole answer for
+ * something, so a merge that let either win breaks a page: the CDN script, or every island.
+ *
+ * Built through a `Map`, never by assigning `out[directive]`: a directive named `__proto__` sets
+ * the PROTOTYPE rather than a key, which is a source silently dropped from the one header this
+ * package locks down hardest.
+ */
+const mergeCspExtend = (
+  app: CspExtend | undefined,
+  boot: CspExtend | undefined,
+): CspExtend | undefined => {
+  if (app === undefined) return boot;
+  if (boot === undefined) return app;
+  const merged = new Map<string, readonly string[]>(Object.entries(app));
+  for (const [directive, sources] of Object.entries(boot)) {
+    merged.set(directive, [...(merged.get(directive) ?? []), ...sources]);
+  }
+  return Object.fromEntries(merged);
+};
+
+const mergeSecurity = (
+  app: SecurityInput | undefined,
+  boot: SecurityInput | undefined,
+): SecurityInput | undefined => {
+  if (app === undefined) return boot;
+  if (boot === undefined) return app;
+  const extend = mergeCspExtend(app.csp?.extend, boot.csp?.extend);
+  const csp: CspInput = {
+    ...app.csp,
+    ...boot.csp,
+    ...(extend === undefined ? {} : { extend }),
+  };
+  return { ...app, ...boot, csp };
+};
+
+/**
+ * The app's declaration with the boot's own facts laid OVER it — the one order that can be right.
+ * `buildId`, the port, the CSP hashes of what this process emits and the scope of the store it
+ * installed are all things the boot measured; an app can only have guessed at them. Everything
+ * else the app said survives, which is the whole point of it having said anything.
+ *
+ * Sections merge one level down rather than being replaced whole: `security: { csp: { extend } }`
+ * from the boot would otherwise delete an app's `hsts`, `frameAncestors` and its own extends, and
+ * `rateLimit: { scope }` would delete every bucket it declared.
+ */
+export const mergeHttpConfig = (
+  app: AppHttpConfig | undefined,
+  boot: HttpConfigInput,
+): HttpConfigInput => {
+  if (app === undefined) return boot;
+  // `rateLimit` is lifted out of the spread rather than overwritten by it: `AppHttpConfig` types
+  // it WITHOUT `scope` and `HttpConfigInput` types it with, so under `exactOptionalPropertyTypes`
+  // the spread of the narrower optional is not assignable to the wider one. The merged value is
+  // computed below and put back.
+  const { rateLimit: appRateLimit, ...appRest } = app;
+  const cors =
+    app.cors === undefined && boot.cors === undefined ? undefined : { ...app.cors, ...boot.cors };
+  const csrf =
+    app.csrf === undefined && boot.csrf === undefined ? undefined : { ...app.csrf, ...boot.csrf };
+  const locale =
+    app.locale === undefined && boot.locale === undefined
+      ? undefined
+      : { ...app.locale, ...boot.locale };
+  const tz = app.tz === undefined && boot.tz === undefined ? undefined : { ...app.tz, ...boot.tz };
+  const rateLimit: Partial<RateLimitConfig> | undefined =
+    appRateLimit === undefined && boot.rateLimit === undefined
+      ? undefined
+      : { ...appRateLimit, ...boot.rateLimit };
+  const security = mergeSecurity(app.security, boot.security);
+  return {
+    ...appRest,
+    ...boot,
+    ...(cors === undefined ? {} : { cors }),
+    ...(csrf === undefined ? {} : { csrf }),
+    ...(locale === undefined ? {} : { locale }),
+    ...(tz === undefined ? {} : { tz }),
+    ...(rateLimit === undefined ? {} : { rateLimit }),
+    ...(security === undefined ? {} : { security }),
+  };
+};

package/src/config.ts

@@ -1,5 +1,8 @@
-// The HTTP slice of `app.config.ts`. One resolver, so a value is either a locked
-// default or an explicit override — never "whatever the first caller passed".
+// The resolver every HTTP config goes through, so a value is either a locked default or an
+// explicit override — never "whatever the first caller passed". It is NOT a slice of
+// `app.config.ts`, which this file claimed for four majors while `AppConfig` has never carried an
+// `http` key: an app declares its half through `configureHttp()` (`app-config.ts`) and the boot
+// lays its own facts over it before calling this.
 import { DEFAULT_ENVIRONMENT, tryResolveEnvironment } from '@ultimat3/core';
 import { assertCorsConfig, type CorsConfig, DEFAULT_CORS } from './cors';
 import { type CsrfConfig, DEFAULT_CSRF } from './csrf';