@ultimat3/http 1.2.0 → 3.0.0

package/src/security-headers.ts

@@ -1,6 +1,9 @@
-// Locked security headers. The CSP is written to work with the three things the
-// framework actually ships — a service worker, streamed HTML with a hydration
-// nonce, and wasm — and nothing else, so widening it is a visible config change.
+// Locked security headers. The CSP admits exactly what the framework itself emits — a service
+// worker, wasm, and the inline `<style>` every document carries — so widening it is a visible
+// config change. Inline style is admitted by sha256 hash, never `'unsafe-inline'`: a prerendered
+// document is a file on disk, so no per-response nonce can reach it, but its body is fixed.
+
+import { OVERLAY_STYLE } from './overlay-style';
 
 export interface SecurityConfig {
   readonly csp: {
@@ -32,12 +35,30 @@ export const DEFAULT_SECURITY: SecurityConfig = {
   hsts: { maxAgeSeconds: 63_072_000, includeSubdomains: true, preload: false },
 };
 
-/** Directive -> sources. `'nonce-*'` is injected per response, never stored here. */
+/**
+ * `'sha256-<base64>'` for the exact text an inline `<style>` or `<script>` holds, ready to
+ * concatenate into a directive. A hash and not a nonce because the two documents that most need
+ * covering cannot receive one: a prerendered page is a file on disk, and a response's `<style>` is
+ * built by the handler, after the stage that would have had to choose the nonce.
+ */
+export const cspHashSource = (body: string): string =>
+  `'sha256-${new Bun.CryptoHasher('sha256').update(body).digest('base64')}'`;
+
+/** Directive -> sources. Inline bodies are admitted by hash; `config.csp.extend` adds the rest. */
 const baseline = (config: SecurityConfig): Record<string, readonly string[]> => ({
   'default-src': ["'self'"],
   // 'wasm-unsafe-eval' only: no 'unsafe-inline', no 'unsafe-eval'.
   'script-src': ["'self'", "'wasm-unsafe-eval'"],
-  'style-src': ["'self'"],
+  // The dev overlay is the one document this package renders itself, so its hash is the one
+  // `style-src` source that is not the caller's to supply. Unconditional rather than gated on
+  // `dev`: a header that changes with a runtime branch is a header a CDN caches for the wrong
+  // document, and admitting a stylesheet the framework wrote grants an attacker nothing.
+  'style-src': ["'self'", cspHashSource(OVERLAY_STYLE)],
+  // ATTRIBUTES ONLY, and the one relaxation in this file. Every layout composite sizes itself
+  // with `style="--shell-sidebar: 16rem"`, computed per render, so there is no fixed text to
+  // hash and `'unsafe-hashes'` cannot express it. `style-src` still governs `<style>` ELEMENTS,
+  // so a `defineTheme()` value carrying `</style>` is still a refusal and not an injection.
+  'style-src-attr': ["'unsafe-inline'"],
   'img-src': ["'self'", 'data:', 'blob:'],
   'font-src': ["'self'"],
   // ws:/wss: are required by the realtime tiers; blob: by streamed responses.
@@ -51,14 +72,11 @@ const baseline = (config: SecurityConfig): Record<string, readonly string[]> =>
   'object-src': ["'none'"],
 });
 
-export const buildCsp = (config: SecurityConfig, nonce?: string): string => {
+export const buildCsp = (config: SecurityConfig): string => {
   const directives = baseline(config);
   for (const [name, sources] of Object.entries(config.csp.extend)) {
     directives[name] = [...(directives[name] ?? []), ...sources];
   }
-  if (nonce !== undefined) {
-    directives['script-src'] = [...(directives['script-src'] ?? []), `'nonce-${nonce}'`];
-  }
   const parts = Object.entries(directives).map(([name, sources]) => `${name} ${sources.join(' ')}`);
   if (config.csp.reportUri !== null) parts.push(`report-uri ${config.csp.reportUri}`);
   return parts.join('; ');
@@ -66,21 +84,24 @@ export const buildCsp = (config: SecurityConfig, nonce?: string): string => {
 
 export const securityHeaders = (
   config: SecurityConfig,
-  options: { nonce?: string; https?: boolean } = {},
+  options: { https?: boolean } = {},
 ): Record<string, string> => {
   const cspHeader = config.csp.reportOnly
     ? 'content-security-policy-report-only'
     : 'content-security-policy';
   const headers: Record<string, string> = {
-    [cspHeader]: buildCsp(config, options.nonce),
+    [cspHeader]: buildCsp(config),
     'x-content-type-options': 'nosniff',
     'referrer-policy': config.referrerPolicy,
     'permissions-policy': config.permissionsPolicy,
     'cross-origin-opener-policy': config.coop,
     'cross-origin-resource-policy': config.corp,
   };
-  // HSTS over plaintext is ignored by browsers and confuses local dev, so skip it.
-  if (config.hsts !== null && options.https !== false) {
+  // HSTS over plaintext is ignored by browsers and confuses local dev, so it is emitted only when
+  // the caller AFFIRMS https. `!== false` said the opposite of this comment: the zero-argument
+  // default — every caller that is not the pipeline, which passes `ctx.https` — sent a two-year
+  // `includeSubDomains` for a connection nothing had established was secure.
+  if (config.hsts !== null && options.https === true) {
     const parts = [`max-age=${config.hsts.maxAgeSeconds}`];
     if (config.hsts.includeSubdomains) parts.push('includeSubDomains');
     if (config.hsts.preload) parts.push('preload');

package/src/server.ts

@@ -21,6 +21,8 @@ import { serverNotStarted } from './errors';
 import type { ServerHooks } from './hooks';
 import type { Middleware } from './middleware';
 import { createPipeline, type Pipeline } from './pipeline';
+import { createRateLimiter, type RateLimitStore } from './rate-limit';
+import { withRouteBuckets } from './rate-limit-buckets';
 import { json } from './response';
 import { createRouter, describeRoutes, type Route, type RouteDescription } from './router';
 
@@ -39,6 +41,13 @@ export interface ServerOptions {
   readonly role?: Role;
   readonly hooks?: ServerHooks;
   readonly middleware?: readonly Middleware[];
+  /**
+   * Where the rate limiter keeps its counters. Omitted means `memoryRateLimitStore()`, which is
+   * one process' worth of state — correct for dev and tests, and N × every configured number for
+   * N replicas. An app that runs more than one process declares `rateLimit.scope: 'shared'` and
+   * passes a store that says the same, or `createServer` refuses here.
+   */
+  readonly rateLimitStore?: RateLimitStore;
 }
 
 export interface ServerHandle {
@@ -62,14 +71,26 @@ export interface ServerHandle {
 const roleFromEnv = (): Role => (Bun.env['ROLE'] ?? 'web') as Role;
 
 export const createServer = (options: ServerOptions): ServerHandle => {
-  const config = options.config ?? defineHttpConfig();
   const role = options.role ?? roleFromEnv();
   const table = createRouter(options.routes);
+  // Merged here as well as in `createPipeline`, and for the store's sake: the limiter below is
+  // built from `config.rateLimit`, so a table without the routes' own buckets would resolve a
+  // declared name to `default` — the very hole this closes. `withRouteBuckets` is idempotent, so
+  // the pipeline's second pass changes nothing. `handle.config` is the merged one for the same
+  // reason: `server.config.rateLimit.buckets` has to be what the limiter runs on.
+  const config = withRouteBuckets(options.config ?? defineHttpConfig(), table.routes);
+  // The store feeds the limiter seam `PipelineDeps` already had, rather than becoming a second
+  // one: the bucket maths stays in `createRateLimiter`, so every driver agrees on the numbers.
   const pipeline = createPipeline({
     table,
     config,
     ...(options.hooks === undefined ? {} : { hooks: options.hooks }),
     ...(options.middleware === undefined ? {} : { middleware: options.middleware }),
+    ...(options.rateLimitStore === undefined
+      ? {}
+      : {
+          limiter: createRateLimiter({ config: config.rateLimit, store: options.rateLimitStore }),
+        }),
   });
 
   // The one HTTP-owned knob feeds core's deadline, so there is a single drain budget.
@@ -132,6 +153,17 @@ export const createServer = (options: ServerOptions): ServerHandle => {
     describe: () => describeRoutes(table),
     fetch: (request) => dispatch(request),
     start() {
+      // FIRST, before the socket. `markReady()` refuses a process whose lifecycle already drained
+      // (`X_LIFECYCLE_DRAINED`), and a refusal that arrived after the bind would leave a listener
+      // this handle can never close: `drain()` memoized on the first drain, so `stop()` below never
+      // reaches the close hook — measured, a second server was still accepting connections after
+      // its own `stop()` returned, answering 503 to everything in between.
+      //
+      // The promotion moving above the bind costs nothing observable: `Bun.serve` is synchronous,
+      // and `/readyz` is served by the socket this line precedes. `x dev`'s only earlier listener
+      // is the metrics endpoint, which answers `METRICS_PATH` and nothing else.
+      markReady();
+
       server = Bun.serve({
         port: config.port,
         hostname: config.hostname,
@@ -170,17 +202,22 @@ export const createServer = (options: ServerOptions): ServerHandle => {
         { phase: 'close' },
       );
 
-      markReady();
       logger.info(`ultimate ${role} listening on ${server.url.origin}`);
       return handle;
     },
     async stop() {
       if (server === undefined) return;
-      // 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.
-      await drain('manual');
-      unregister?.();
-      unregisterClose?.();
+      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.
+        await drain('manual');
+      } finally {
+        // 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?.();
+      }
       // Idempotent: the close hook already released, unless the drain deadline cut it short.
       stopListening?.();
       stopListening = undefined;

package/src/stages.ts

@@ -0,0 +1,381 @@
+// One function per stage name: what each stage of the lifecycle DOES. The package's three-way
+// split, each file naming the other two — `pipeline.ts` owns the ORDER the stages run in and the
+// run itself, `finalize.ts` owns the promise that the tail cannot reject, and this file owns the
+// work. The vocabulary (`StageName`, `Stage`) lives here too, beside the fourteen implementations
+// it names, so `Record<StageName, StageRun>` below is the build error that catches a missing one.
+
+import {
+  anonymousActor,
+  inflightCount,
+  isAnonymous,
+  isDraining,
+  reportError,
+} from '@ultimat3/core';
+import { resolveLocale } from '@ultimat3/i18n';
+import { resolveTimeZone } from '@ultimat3/time';
+import { signInRedirect } from './auth-redirect';
+import { defaultCache } from './cache-policy';
+import { type HttpConfig, stripBasePath } from './config';
+import { actorView, elapsedMs, type RequestContext } from './context';
+import { corsHeaders, preflight } from './cors';
+import { checkCsrf, selfOrigin } from './csrf';
+import { factsOf } from './error-map';
+import {
+  bodyInvalid,
+  csrfBlocked,
+  draining,
+  forbidden,
+  methodNotAllowed,
+  overloaded,
+  pathInvalid,
+  rateLimited,
+  routeNotFound,
+  unauthenticated,
+} from './errors';
+import type { ServerHooks } from './hooks';
+import { readCookie } from './locale';
+import { compose, type Middleware } from './middleware';
+import { overlayResponse, wantsOverlay } from './overlay';
+import { type RateLimiter, rateLimitKey } from './rate-limit';
+import type { UltimateRequest } from './request';
+import { addVary, applyCacheHeaders, problem, redirect } from './response';
+import { matchRoute, type Route, type RouteHandler, type RouteTable } from './router';
+import { securityHeaders } from './security-headers';
+import { validate } from './validate';
+
+export type StageName =
+  | 'request-id'
+  | 'admit'
+  | 'trace'
+  | 'context'
+  | 'locale'
+  | 'auth'
+  | 'rate-limit'
+  | 'csrf'
+  | 'body'
+  | 'authz'
+  | 'handler'
+  | 'cache-headers'
+  | 'error-map'
+  | 'response';
+
+/**
+ * `request`  may short-circuit by returning a Response.
+ * `terminal` runs the route handler.
+ * `recover`  runs only when something above threw.
+ * `finalize` always runs, on success and on failure.
+ */
+export type StagePhase = 'request' | 'terminal' | 'recover' | 'finalize';
+
+export interface StageDoc {
+  readonly name: StageName;
+  readonly phase: StagePhase;
+  /** Why the stage sits at this index. Rendered verbatim by the dev dashboard. */
+  readonly why: string;
+}
+
+export type StageRun = (
+  request: UltimateRequest,
+  ctx: RequestContext,
+) => Response | undefined | Promise<Response | undefined>;
+
+export interface Stage extends StageDoc {
+  readonly run: StageRun;
+}
+
+/**
+ * A shed request must say when to come back, or it comes back immediately and the retry storm is
+ * the load it was shed to avoid. One second: long enough to matter across a fleet, short enough
+ * that a client is not parked past a rolling restart.
+ */
+const SHED_RETRY_AFTER_SECONDS = '1';
+
+/**
+ * The one label a request with no matched route may carry. Every 404 and every scan of `/wp-admin`
+ * would otherwise be its own rate-limit bucket and its own metric series — an attacker choosing
+ * the server's cardinality is how a Prometheus dies. Exported because `pipeline.ts` labels the
+ * request metric with it too, and two spellings of "unmatched" is two series.
+ */
+export const UNMATCHED_ROUTE = 'unmatched';
+
+/**
+ * Everything a stage may read, named one by one rather than as `PipelineDeps`: a stage body has no
+ * business seeing the constructor's input shape, and this list IS the answer to "what can a stage
+ * depend on".
+ */
+export interface StageRunnersInput {
+  readonly table: RouteTable;
+  readonly config: HttpConfig;
+  readonly limiter: RateLimiter;
+  readonly hooks: ServerHooks;
+  readonly middleware: readonly Middleware[];
+}
+
+/** The stage table, closed over one pipeline's config, routes, hooks and limiter. */
+export const stageRunners = (input: StageRunnersInput): Record<StageName, StageRun> => {
+  const { config, hooks, limiter } = input;
+  const wrapped = new Map<Route, RouteHandler>();
+  const wrap = compose(input.middleware);
+  for (const route of input.table.routes) wrapped.set(route, wrap(route.handler));
+
+  const table: Record<StageName, StageRun> = {
+    // Both ids are resolved in `correlation.ts`, before the context and the root span exist —
+    // this stage publishes what was decided there. It used to DECIDE, one frame after
+    // `withSpan` had already frozen the span's parent, so an inbound `traceparent` was read into
+    // `ctx.traceId` and the span kept a trace id nothing else in the request had ever seen.
+    'request-id': (_request, ctx) => {
+      ctx.headers.set('x-request-id', ctx.requestId);
+      return undefined;
+    },
+
+    admit: (_request, ctx) => {
+      // Before the trace, the route match, auth, the body — everything. A refusal that costs as
+      // much as a served request is not load shedding, and this is the stage that makes
+      // "reject 40% fast, serve 60% at p99" expressible at all.
+      if (isDraining()) {
+        ctx.headers.set('retry-after', SHED_RETRY_AFTER_SECONDS);
+        throw draining();
+      }
+      const ceiling = config.maxInflight;
+      // `beginWork()` in `server.ts` counted THIS request before the pipeline was entered, so the
+      // ceiling is compared against a number that already includes it.
+      if (ceiling > 0 && inflightCount() > ceiling) {
+        ctx.headers.set('retry-after', SHED_RETRY_AFTER_SECONDS);
+        throw overloaded(inflightCount(), ceiling);
+      }
+      return undefined;
+    },
+
+    trace: (_request, ctx) => {
+      ctx.headers.set('x-trace-id', ctx.traceId);
+      return undefined;
+    },
+
+    context: (request, ctx) => {
+      // A preflight carries no credentials, so answering it after `auth` would 401
+      // every legitimate cross-origin call.
+      const answered = preflight(request.raw, config.cors);
+      if (answered !== undefined) return answered;
+
+      ctx.clientBuildId = request.header(config.buildIdHeader);
+      request.assertBuild();
+
+      const pathname = stripBasePath(ctx.url.pathname, config.basePath);
+      const match = matchRoute(input.table, ctx.method, pathname);
+      if (!match.ok) {
+        if (match.reason === 'not-found') throw routeNotFound(ctx.method, pathname);
+        if (match.reason === 'path-invalid') throw pathInvalid(pathname, match.segment);
+        ctx.headers.set('allow', match.allow.join(', '));
+        throw methodNotAllowed(ctx.method, pathname, match.allow);
+      }
+      ctx.route = match.route;
+      ctx.params = match.params;
+      return undefined;
+    },
+
+    /**
+     * The two values land on `ctx.locale` / `ctx.tz` — core's own declared fields, which is what
+     * makes `currentLocale()` and `currentTimeZone()` answer for this request once `pipeline.ts`
+     * publishes the context into the ALS. This stage decides only WHERE to read them from; the
+     * owners decide what they mean, so `Accept-Language: zh-Hant-TW` and `x-timezone: eUrOpE/bErLiN`
+     * get one answer in the framework rather than one per package.
+     */
+    locale: (request, ctx) => {
+      const cookies = request.header('cookie');
+      ctx.locale = resolveLocale({
+        header: request.header('accept-language'),
+        cookie: readCookie(cookies, config.locale.cookie),
+      }).locale;
+      ctx.tz = resolveTimeZone({
+        cookie: readCookie(cookies, config.tz.cookie),
+        header: request.header(config.tz.header),
+      }).zone;
+      ctx.headers.set('content-language', ctx.locale);
+      return undefined;
+    },
+
+    auth: async (request, ctx) => {
+      if (hooks.authenticate !== undefined) {
+        // The hook says "anonymous" with null; the context says it with core's anonymous actor,
+        // because `asCtx` publishes this object as a `Ctx` and `Ctx.actor` is never null.
+        ctx.actor = (await hooks.authenticate(request, ctx)) ?? anonymousActor();
+      }
+      if (ctx.route?.meta.auth === 'required' && isAnonymous(ctx.actor)) {
+        throw unauthenticated(ctx.url.pathname);
+      }
+      return undefined;
+    },
+
+    'rate-limit': async (_request, ctx) => {
+      if (!config.rateLimit.enabled) return undefined;
+      const actor = actorView(ctx.actor);
+      const key = rateLimitKey({
+        actorId: actor?.id ?? null,
+        orgId: actor?.orgId ?? null,
+        ip: ctx.ip,
+        routeName: ctx.route?.meta.name ?? UNMATCHED_ROUTE,
+      });
+      const decision = await limiter.check(
+        key,
+        ctx.route?.meta.rateLimit ?? config.rateLimit.defaultBucket,
+      );
+      // Recorded before the throw so the 429 can carry Retry-After and the
+      // RateLimit-* headers rather than making the client guess.
+      ctx.rateLimit = decision;
+      for (const [name, value] of Object.entries(limiter.headers(decision))) {
+        ctx.headers.set(name, value);
+      }
+      if (!decision.allowed) throw rateLimited(key, decision.retryAfterSeconds);
+      return undefined;
+    },
+
+    csrf: (request, ctx) => {
+      const verdict = checkCsrf({
+        method: ctx.method,
+        // `ctx.https`, not `ctx.url.protocol`: behind a TLS-terminating ingress the internal hop
+        // is plain http while the browser's `Origin` says https, so comparing the raw URL would
+        // refuse every legitimate form post in the shape the framework's own chart ships.
+        selfOrigin: selfOrigin(ctx.url, ctx.https),
+        origin: request.header('origin'),
+        secFetchSite: request.header('sec-fetch-site'),
+        hasAuthorizationHeader: request.header('authorization') !== null,
+        anonymous: isAnonymous(ctx.actor),
+        cors: config.cors,
+        config: config.csrf,
+      });
+      if (!verdict.ok) throw csrfBlocked(ctx.url.pathname, verdict.reason);
+      return undefined;
+    },
+
+    body: async (request, ctx) => {
+      const schema = ctx.route?.meta.input;
+      if (schema === undefined) return undefined;
+      const outcome = await validate(schema, await request.bodyRaw());
+      if (!outcome.ok) throw bodyInvalid(ctx.url.pathname, outcome.issues);
+      ctx.input = outcome.value;
+      return undefined;
+    },
+
+    authz: async (request, ctx) => {
+      const route = ctx.route;
+      if (route === undefined || route.meta.policy === undefined) return undefined;
+      // The handler owns this route's single evaluation (`RouteMeta.enforcedBy`). Deciding
+      // here as well would be a second authz system holding strictly less than the first —
+      // no row — and it is the one that answers first, so it is the one that would win.
+      if (route.meta.enforcedBy === 'handler') return undefined;
+      if (hooks.authorize === undefined) {
+        // A declared policy with no evaluator is a wiring bug, and failing open
+        // here is exactly how a framework ends up with two authz systems.
+        throw forbidden(ctx.url.pathname, `no authorizer wired for policy ${route.meta.policy}`);
+      }
+      const decision = await hooks.authorize(route, request, ctx);
+      ctx.authz = decision;
+      if (!decision.allowed) throw forbidden(ctx.url.pathname, decision.reason);
+      return undefined;
+    },
+
+    handler: async (request, ctx) => {
+      const route = ctx.route;
+      if (route === undefined) throw routeNotFound(ctx.method, ctx.url.pathname);
+      const handler = wrapped.get(route) ?? route.handler;
+      return await handler(request, ctx);
+    },
+
+    'cache-headers': (_request, ctx) => {
+      const response = ctx.response;
+      if (response === undefined) return undefined;
+      if (!response.headers.has('cache-control')) {
+        applyCacheHeaders(
+          response,
+          ctx.cache ?? ctx.route?.meta.cache ?? defaultCache(ctx.route, ctx.actor),
+        );
+      }
+      return undefined;
+    },
+
+    'error-map': (request, ctx) => {
+      const error = ctx.error;
+      const facts = factsOf(error);
+      // This package's ONE error-reporting call site, and it is the framework's own — `onError`
+      // below stays the APP's sink. 5xx only: a 404 or a 422 is the caller's mistake, the problem
+      // document already told them, and a monitor that also holds those is a log nobody reads.
+      // The `operation` is the route PATTERN for the same reason `recordRequest` uses it.
+      if (facts.status >= 500) {
+        reportError(error, {
+          source: 'http',
+          scope: {
+            requestId: ctx.requestId,
+            traceId: ctx.traceId,
+            role: ctx.role,
+            operation: `${ctx.method} ${ctx.route?.path ?? UNMATCHED_ROUTE}`,
+            actorId: isAnonymous(ctx.actor) ? undefined : ctx.actor.id,
+          },
+        });
+      }
+      hooks.onError?.(error, ctx);
+      // FIELDS, never interpolation. `logger.emit()` redacts `bound`, `contextFields` and
+      // `fields` — never `msg` — so a cause baked into the message reached the log store past
+      // every rule that exists to stop it: a rejected `{"password":"hunter2"}` was logged
+      // verbatim, at 4xx, which is logged and not reported and therefore kept for the full
+      // retention. The message is the CODE alone; everything variable is a field.
+      // The other half of this is `@ultimat3/schema`'s, and it is the load-bearing one: an issue
+      // message must stop echoing the rejected value at all. This change makes the value
+      // redactable; it does not make it absent.
+      ctx.logger.error(facts.code, { cause: facts.cause, status: facts.status });
+      // Before the overlay and before the problem document: a browser with no session has not
+      // hit a defect to debug, it has hit a login wall, and the answer to that is the sign-in
+      // page. `signInPath` is null until an app declares one, so this is off by default.
+      const toSignIn = signInRedirect({
+        code: facts.code,
+        signInPath: config.signInPath,
+        request: request.raw,
+        ctx,
+      });
+      if (toSignIn !== undefined) return redirect(toSignIn.location, toSignIn.status);
+      if (config.dev && wantsOverlay(request.raw)) {
+        // Asked for inside the branch, never above it: the overlay is the only surface a notice
+        // has, so a production process — or an agent that asked for json — must not pay a
+        // diagnostic's per-request cost to produce findings nothing will render.
+        const notices = hooks.devNotices?.(ctx) ?? [];
+        return overlayResponse(error, {
+          requestId: ctx.requestId,
+          method: ctx.method,
+          path: ctx.url.pathname,
+          buildId: config.buildId,
+          ...(notices.length === 0 ? {} : { notices }),
+        });
+      }
+      const retryAfter =
+        facts.code === 'X_RATE_LIMITED' && ctx.rateLimit !== undefined
+          ? { 'retry-after': String(ctx.rateLimit.retryAfterSeconds) }
+          : {};
+      return problem(error, {
+        instance: ctx.url.pathname,
+        requestId: ctx.requestId,
+        headers: retryAfter,
+      });
+    },
+
+    response: (request, ctx) => {
+      const response = ctx.response;
+      if (response === undefined) return undefined;
+      for (const [name, value] of ctx.headers) response.headers.set(name, value);
+      for (const [name, value] of Object.entries(
+        corsHeaders(config.cors, request.header('origin')),
+      )) {
+        // `vary` is the one header two stages both contribute to, so it is added and never set:
+        // `set` here would drop the cache stage's key (`accept-language`, `cookie`) on the floor.
+        if (name === 'vary') addVary(response, [value]);
+        else response.headers.set(name, value);
+      }
+      for (const [name, value] of Object.entries(
+        securityHeaders(config.security, { https: ctx.https }),
+      )) {
+        response.headers.set(name, value);
+      }
+      response.headers.set('server-timing', `total;dur=${elapsedMs(ctx)}`);
+      return undefined;
+    },
+  };
+  return table;
+};

package/src/type-pins.ts

@@ -0,0 +1,48 @@
+// Compile-time pins for the shapes this package declares but never constructs. Source, not a
+// `.test.ts`, on purpose: `tsconfig.json` excludes `src/**/*.test.ts`, so `tsc -b` never reads a
+// test file and a claim written there can never fail. Nothing here emits or is imported — a
+// regression is a build error, the only enforcement that counts (axiom 3).
+
+import type { AuthzDecision } from './hooks';
+
+/** Fails to compile when `T` is anything but `true`. The whole mechanism. */
+type Assert<T extends true> = T;
+
+/**
+ * An allow carries nothing else. `hooks.authorize` is implemented at tier 3 by
+ * `@ultimat3/action`, which never sees this package's tests — so "an allowed decision needs no
+ * reason" has to be a type error at the declaration, not an assertion over a literal a test wrote.
+ */
+export type _AuthzAllowNeedsNothingElse = Assert<
+  { allowed: true } extends AuthzDecision ? true : false
+>;
+
+/**
+ * And carries nothing else, which the assignability pin above cannot say: an optional field added
+ * to the allow branch leaves `{ allowed: true }` assignable, so the claim in that comment would
+ * have gone on compiling while an allow grew somewhere to put a reason. `never` is wrapped in a
+ * tuple because a bare `never` on the left of `extends` short-circuits the conditional.
+ */
+type AuthzAllow = Extract<AuthzDecision, { allowed: true }>;
+
+export type _AuthzAllowCarriesNothingElse = Assert<
+  [Exclude<keyof AuthzAllow, 'allowed'>] extends [never] ? true : false
+>;
+
+/**
+ * A denial must carry its reason: it is what the pipeline renders and what an agent reads.
+ */
+export type _AuthzDenyNeedsAReason = Assert<
+  { allowed: false } extends AuthzDecision ? false : true
+>;
+
+/**
+ * `code` stays optional on a denial — a limiter denying with no framework code must not have to
+ * invent one, and `error-map.ts` defaults it. This is the pin that made
+ * `hooks.test.ts`'s `if (!decision.allowed) expect(decision.code).toBeUndefined()` deletable: that
+ * guard was statically true over a literal the test itself wrote, so it ran no production code and
+ * could not fail.
+ */
+export type _AuthzDenyCodeIsOptional = Assert<
+  { allowed: false; reason: string } extends AuthzDecision ? true : false
+>;

package/src/validate.ts

@@ -26,12 +26,23 @@ export const formatIssue = (issue: Issue): string => {
   return path.length > 0 ? `${path}: ${issue.message}` : issue.message;
 };
 
+/** A refusal still owes its reader a sentence, and a degenerate result gave none. */
+const NO_ISSUES_REPORTED = 'the schema reported a failure with no issues';
+
+/**
+ * A Standard Schema result is discriminated by the PRESENCE of `issues`, never by its length: a
+ * success result declares `issues?: undefined` and a failure result carries no `value` at all. A
+ * length test read `issues: []` as success and returned `value: undefined as Out` — an `undefined`
+ * the caller's types say cannot happen, which surfaced one frame later as a `TypeError` and a 500
+ * for a request that was simply invalid.
+ */
 const outcome = <Out>(result: {
   readonly value?: Out;
   readonly issues?: readonly Issue[] | undefined;
 }): ValidationOutcome<Out> => {
-  if (result.issues !== undefined && result.issues.length > 0) {
-    return { ok: false, issues: result.issues.map(formatIssue) };
+  if (result.issues !== undefined) {
+    const issues = result.issues.map(formatIssue);
+    return { ok: false, issues: issues.length > 0 ? issues : [NO_ISSUES_REPORTED] };
   }
   return { ok: true, value: result.value as Out };
 };