@erenthedeveloper0/zen-middleware 0.1.0-alpha.1

package/src/rate-limit.ts

@@ -0,0 +1,217 @@
+import {
+  definePlugin, parseDuration, Codes, TooManyRequests, ZenError,
+  type Duration, type Plugin, type Reply,
+} from '@erenthedeveloper0/zen-core'
+import { MemoryStore, type Store, type Tally } from './store.ts'
+import type { Answering, RawReading, Staging } from './shared.ts'
+
+/**
+ * Rate limiting — rfcs/0001 §9.2, §19.2, §19.4, Annex B `ZEN_RATE_LIMITED`.
+ *
+ * ### Why it is a hook, and why that is the whole feature
+ *
+ * §9.2 states the defect this design exists to avoid, in the paragraph that
+ * made global `onRequest` hooks run on unmatched requests: *"a rate limiter
+ * that only sees matched routes is bypassed by requesting a path that does not
+ * exist."* Every framework whose rate limiter is route middleware has that
+ * hole, and it is not theoretical — `GET /aaaa` is unmatched, so the limiter
+ * never runs, so a 404 flood is free. A global `onRequest` hook counts it.
+ *
+ * §4.2 stage 5 puts it before body intake as well, so a request that is going
+ * to be refused is refused **without its body being read**. A limiter that
+ * counted after parsing would have already paid the expensive part.
+ *
+ * ### `Codes.RATE_LIMITED` was already here
+ *
+ * `TooManyRequests` and `ZEN_RATE_LIMITED` have been exported from
+ * `@erenthedeveloper0/zen-core` since 0.1 and read by nothing — the same state `COERCION_DEFAULTS`
+ * and `Codes.CONFIG_INVALID` were in before the two features that needed them.
+ * Using it rather than inventing a 429 means the refusal is an ordinary
+ * `HttpError`: it goes through the error engine, the RFC 9457 envelope, the
+ * registered `onError` hooks and `onSend`, and it appears in the same error
+ * dashboards as everything else. A rate limiter that answers with its own
+ * hand-built response is one whose refusals no error rate counts.
+ *
+ * ### What it does not do
+ *
+ * It is a **fixed-window counter**, and `store.ts` explains what that costs at
+ * the boundary. It is not distributed unless the `Store` is (§3.5). It does not
+ * read `X-Forwarded-For` — that is `ctx.ip`, and §19.4 makes it a deliberate
+ * `trustProxy` decision — but it *does* notice when the combination is the one
+ * §19.4 warns about, once, at the moment it is provably real. See {@link warnProxy}.
+ */
+
+export interface RateLimitOptions {
+  /** Requests per window, per key. */
+  readonly limit?: number | undefined
+  /** Window length. Fixed, not sliding — see `store.ts`. */
+  readonly window?: Duration | undefined
+  /**
+   * What to count by. Defaults to `ctx.ip`.
+   *
+   * Return `null` to exempt a request entirely — that is how an authenticated
+   * service account or an internal health poller opts out, and it is a
+   * deliberate hole rather than a second allowlist option nobody would find.
+   */
+  readonly key?: ((ctx: RateLimitContext) => string | null) | undefined
+  /** Where counters live. Defaults to an in-process {@link MemoryStore}. */
+  readonly store?: Store | undefined
+  /** Also emit `X-RateLimit-*`. Off by default: they were never standardised and they double the header cost. */
+  readonly legacyHeaders?: boolean | undefined
+  /** Emit `RateLimit` / `RateLimit-Policy` (IETF draft). On by default. */
+  readonly standardHeaders?: boolean | undefined
+  /** Message on the 429. The status, code and envelope are not configurable. */
+  readonly message?: string | undefined
+}
+
+export interface RateLimitContext {
+  readonly ip: string
+  readonly method: string
+  readonly path: string
+  readonly id: string
+  readonly raw: { header(name: never): string | undefined }
+}
+
+const DEFAULTS = { limit: 100, window: '1m' } as const
+
+export function rateLimit(options: RateLimitOptions = {}): Plugin<void, {}> {
+  return definePlugin<void, {}>({
+    name: 'rate-limit',
+    version: '0.1.0',
+    config: { namespace: 'rateLimit', defaults: { limit: DEFAULTS.limit, window: DEFAULTS.window } },
+
+    setup(app) {
+      // §16.1 layer order: an explicit option beats the plugin's own layer-2
+      // defaults, which a deployment can beat from configuration. Readable at
+      // setup because §16.2 resolved the environment before any plugin ran.
+      const namespace = (app.config['rateLimit'] ?? {}) as { limit?: unknown; window?: unknown }
+      const limit = options.limit ?? numberOr(namespace.limit, DEFAULTS.limit)
+      const windowMs = parseDuration(options.window ?? (namespace.window as Duration | undefined) ?? DEFAULTS.window)
+
+      if (!Number.isInteger(limit) || limit < 1) {
+        throw new ZenError(
+          Codes.CONFIG_INVALID,
+          `rateLimit needs a positive whole limit; got ${JSON.stringify(limit)}.`,
+          {
+            status: 500,
+            expose: false,
+            hint: 'Pass rateLimit({ limit: 100, window: "1m" }), or set rateLimit.limit in configuration.',
+            consequence: 'A limit below one refuses every request, including the health probes an orchestrator uses to decide the pod is broken.',
+          },
+        )
+      }
+
+      // Annotated `Store`, not inferred: the inferred union of the supplied
+      // store and `MemoryStore` drops the optional members, so `store.close?.()`
+      // below would stop type-checking the moment the default is in play — for
+      // an interface whose whole point is that the two are interchangeable.
+      const store: Store = options.store ?? new MemoryStore({ windowMs })
+      const keyOf = options.key ?? ((ctx: RateLimitContext) => ctx.ip)
+      const standard = options.standardHeaders !== false
+      const legacy = options.legacyHeaders === true
+      const policy = `${limit};w=${Math.floor(windowMs / 1000)}`
+      const message = options.message ?? `Rate limit exceeded: ${limit} requests per ${options.window ?? namespace.window ?? DEFAULTS.window}.`
+
+      // One warning per process, not per request — §12.7's rule applied to a
+      // runtime condition. See `warnProxy`.
+      let warned = false
+
+      app.hook('onRequest', function rateLimit(
+        ctx: RateLimitContext & RawReading & Staging & Answering,
+      ): Reply | undefined | Promise<Reply | undefined> {
+        const key = keyOf(ctx)
+        if (key === null) return undefined
+
+        if (!warned && options.key === undefined) warned = warnProxy(ctx)
+
+        const tally = store.hit(key, Date.now())
+        // The in-memory store is synchronous and must stay on §8.4's fast path;
+        // a Redis store is a round trip. Branching on the *value* rather than
+        // declaring the hook async is what lets one implementation serve both
+        // without making every app that uses the default await a resolved
+        // promise per request.
+        return isThenable(tally)
+          ? tally.then((settled) => verdict(ctx, settled))
+          : verdict(ctx, tally)
+      }, 'rate-limit')
+
+      app.hook('onClose', async () => { await store.close?.() })
+
+      function verdict(ctx: Staging & Answering, tally: Tally): Reply | undefined {
+        const remaining = Math.max(0, limit - tally.count)
+        const resetSeconds = Math.max(0, Math.ceil((tally.resetAt - Date.now()) / 1000))
+
+        // Staged, not stamped: the headers have to be on the 429 *and* on the
+        // 200, and the 429 leaves through the error engine rather than through
+        // this hook's return value. `ctx.res` is downstream of both (§13.6).
+        if (standard) {
+          ctx.res.header('ratelimit', `limit=${limit}, remaining=${remaining}, reset=${resetSeconds}`)
+          ctx.res.header('ratelimit-policy', policy)
+        }
+        if (legacy) {
+          ctx.res.header('x-ratelimit-limit', String(limit))
+          ctx.res.header('x-ratelimit-remaining', String(remaining))
+          ctx.res.header('x-ratelimit-reset', String(Math.ceil(tally.resetAt / 1000)))
+        }
+
+        if (tally.count <= limit) return undefined
+
+        ctx.res.header('retry-after', String(resetSeconds))
+        // Thrown, not returned. A returned `Reply` would leave the error engine,
+        // the problem-details envelope and every registered `onError` hook out
+        // of the one response class an operator most wants counted.
+        throw new TooManyRequests(message, { retryable: true })
+      }
+
+      return { exports: { limit, windowMs, store } }
+    },
+  })
+}
+
+/**
+ * §19.4's detection, without the traffic sampling.
+ *
+ * The dangerous combination is: rate limiting keyed on the client IP,
+ * `trustProxy` off, and a proxy in front adding `X-Forwarded-For`. Then
+ * `ctx.ip` is the load balancer for every request, every caller shares one
+ * counter, and the limiter is globally throttling the service instead of
+ * limiting anybody — which looks exactly like the service being slow.
+ *
+ * §19.4 assigns this to `zen doctor` "with traffic samples", and that is the
+ * right home for the general check. But the specific one costs a header read on
+ * the first request that could possibly exhibit it, and it fires only when the
+ * misconfiguration is **already real**: a forwarding header is present and is
+ * being ignored. A boot-time version could not do that — at boot, "trustProxy
+ * is off" is also the correct configuration for a directly-exposed server, so a
+ * warning then would fire on every correct app until people turned it off.
+ *
+ * Returns `true` so the caller latches it: one line per process, naming the fix.
+ */
+function warnProxy(ctx: RateLimitContext & RawReading): boolean {
+  const forwarded = ctx.raw.header('x-forwarded-for')
+  if (forwarded === undefined) return false
+  // `ctx.ip` falls back to the socket address when trustProxy is off (§19.4),
+  // so the two disagreeing *is* the condition — no need to read the option.
+  const claimed = forwarded.split(',')[0]?.trim()
+  if (claimed === undefined || claimed === ctx.ip) return false
+
+  console.warn(
+    `[zen] ${Codes.RATE_LIMITED}: rate limiting is keyed on ctx.ip, this request carried ` +
+      `X-Forwarded-For: ${claimed}, and trustProxy is off — so it was counted as ${ctx.ip}. ` +
+      'fix: set trustProxy to the number of proxies in front of the app — trustProxy: 1 for one ' +
+      'load balancer — so ctx.ip is the address your proxy saw; not `true`, which reads the ' +
+      'leftmost entry, and a client that writes its own X-Forwarded-For then gets a fresh budget ' +
+      'per request. Or pass rateLimit({ key }) to count by something you control. ' +
+      'also: until then every caller behind the proxy shares one counter, which throttles the ' +
+      'whole service at the configured limit instead of limiting anyone. Reported once per process.',
+  )
+  return true
+}
+
+function numberOr(value: unknown, fallback: number): number {
+  return typeof value === 'number' ? value : fallback
+}
+
+function isThenable(value: unknown): value is Promise<Tally> {
+  return typeof (value as { then?: unknown } | null)?.then === 'function'
+}

package/src/request-id.ts

@@ -0,0 +1,129 @@
+import { definePlugin, Codes, ZenError, type Plugin } from '@erenthedeveloper0/zen-core'
+import type { RawReading, Staging } from './shared.ts'
+
+/**
+ * Request id — rfcs/0001 §19.4, §31.1.
+ *
+ * Zen already generates one: the dispatcher assigns `ctx.id` before the first
+ * hook runs, so `ctx.log` and the RFC 9457 problem document already carry a
+ * correlation key with no plugin at all. This adds the two halves that need a
+ * decision rather than a default.
+ *
+ * ### Echoing it
+ *
+ * The id is useless to a caller who cannot see it. `x-request-id` on the reply
+ * is what turns "something failed at 14:02" into a log query, and staging it
+ * through `ctx.res` means it is on the 500 as well as the 200 — which is the
+ * only response anybody actually needs it on.
+ *
+ * ### Accepting one, which is a trust decision
+ *
+ * Continuing a caller's trace id is the reason people reach for this plugin,
+ * and it is **off by default** for the same reason `trustProxy` is (§19.4): an
+ * inbound `X-Request-Id` is attacker-controlled. It lands in every log line
+ * this request produces, in the problem document, and in whatever index those
+ * are shipped to — so an unbounded, unvalidated value is log injection with a
+ * framework helpfully doing the writing, and a value chosen to collide with a
+ * real id is a way to make one request's trail read as another's.
+ *
+ * So `trustHeader` is opt-in, and even opted in the value must survive
+ * {@link ACCEPTABLE}: 8–128 characters of `[A-Za-z0-9._-]`. That admits every
+ * id anybody actually sends — ULIDs, UUIDs, hex, W3C trace ids — and admits no
+ * newline, no space and no control character. A value that fails is not an
+ * error; the request gets a fresh id, because refusing traffic over the shape
+ * of a correlation header would be a worse failure than the one being avoided.
+ * `x-request-id-rejected: 1` says it happened, so the caller can find out
+ * without reading the server's logs.
+ */
+
+/**
+ * The one field this plugin writes.
+ *
+ * `ctx.id` is `readonly` on `BaseContext` and is a plain field on both twins,
+ * assigned once by the dispatcher. Overwriting it is a same-type store on an
+ * existing field, so it changes no hidden class and I2 is untouched (§7.6) —
+ * but it is the only place in this package that writes to a context, and
+ * naming the type is how that stays deliberate.
+ *
+ * The alternative was a second id on a slot, and it is worse in the way that
+ * matters: two ids means every log line, every problem document and every
+ * downstream header has to say which one it means, and the first one that gets
+ * it wrong is discovered during an incident.
+ */
+interface MutableId {
+  id: string
+}
+
+export interface RequestIdOptions {
+  /** Header to echo on the reply. `false` echoes nothing. */
+  readonly header?: string | false | undefined
+  /**
+   * Adopt an inbound id when it is well-formed. Off by default — see above.
+   *
+   * `true` reads the same header as `header`. A string reads that one instead,
+   * which is what a deployment behind a load balancer that stamps its own
+   * (`x-amzn-trace-id`, `x-cloud-trace-context`) needs.
+   */
+  readonly trustHeader?: boolean | string | undefined
+  /** Header carrying the rejection notice. `false` stays silent. */
+  readonly rejectedHeader?: string | false | undefined
+}
+
+/**
+ * 8–128 of `[A-Za-z0-9._-]`.
+ *
+ * Anchored, no alternation, no nested quantifier: linear in the input and
+ * therefore inside §19.3's bounded-work rule, which forbids backtracking
+ * regexes anywhere on the request path. The upper bound is part of the
+ * validation, not a courtesy — an id is copied into every log line for the
+ * request, so an unbounded one is an amplification the caller chooses.
+ */
+const ACCEPTABLE = /^[A-Za-z0-9._-]{8,128}$/
+
+export function requestId(options: RequestIdOptions = {}): Plugin<void, {}> {
+  const echo = options.header === undefined ? 'x-request-id' : options.header
+  const trust =
+    options.trustHeader === undefined || options.trustHeader === false ? null
+    : options.trustHeader === true
+      ? (echo === false ? 'x-request-id' : echo)
+      : options.trustHeader
+  const rejected = options.rejectedHeader === undefined ? 'x-request-id-rejected' : options.rejectedHeader
+
+  if (echo === false && trust === null) {
+    throw new ZenError(
+      Codes.CONFIG_INVALID,
+      'requestId() was configured to neither echo an id nor adopt one, which leaves it with nothing to do.',
+      {
+        status: 500,
+        expose: false,
+        hint: 'Drop the registration — Zen assigns ctx.id with or without this plugin — or turn one of the two back on.',
+        consequence: 'As configured it registers a hook on every route that returns immediately.',
+      },
+    )
+  }
+
+  return definePlugin<void, {}>({
+    name: 'request-id',
+    version: '0.1.0',
+    // First in the pack: a preflight answered by `cors` and a 429 refused by
+    // `rate-limit` both short-circuit, and both should still carry the id that
+    // the log line for them will be filed under.
+    before: ['cors', 'rate-limit', 'security-headers'],
+
+    setup(app) {
+      app.hook('onRequest', function requestId(ctx: RawReading & Staging & MutableId): undefined {
+        if (trust !== null) {
+          const inbound = ctx.raw.header(trust)
+          if (inbound !== undefined) {
+            if (ACCEPTABLE.test(inbound)) ctx.id = inbound
+            else if (rejected !== false) ctx.res.header(rejected, '1')
+          }
+        }
+        if (echo !== false) ctx.res.header(echo, ctx.id)
+        return undefined
+      }, 'request-id')
+
+      return { exports: { header: echo, trusts: trust } }
+    },
+  })
+}

package/src/security.ts

@@ -0,0 +1,161 @@
+import { definePlugin, type Plugin } from '@erenthedeveloper0/zen-core'
+import { assertCorsCorpConsistent } from './consistency.ts'
+import type { CorsExports } from './cors.ts'
+import type { Staging } from './shared.ts'
+
+/**
+ * Security response headers — rfcs/0001 §19.2.
+ *
+ * The header set is §19.2's table, and the table is the specification: every
+ * default here appears there with the sentence explaining why it is not looser.
+ * Nothing is invented in this file.
+ *
+ * ### Staged, so failures carry them too
+ *
+ * Same reason as `cors.ts`: an `after` middleware never runs on the error path
+ * (§4.6) or on an unmatched request, so a service that stamps `nosniff` in
+ * middleware does not have it on its 404s, its 500s or its validation errors —
+ * which are precisely the responses most likely to contain reflected input.
+ * `ctx.res` stages, and `prepareForWire` applies at egress on every path.
+ *
+ * ### It runs first, and that is a correctness requirement
+ *
+ * Staging is only half the answer. `cors` answers a preflight by returning a
+ * `Reply`, and `rate-limit` refuses by throwing — both short-circuit the
+ * `onRequest` chain, so a hook registered after them does not run at all on the
+ * responses that need it most. The first draft of this pack ordered
+ * `securityHeaders` last and every preflight and every 429 went out without
+ * `nosniff`; the manual end-to-end check found it before any test did, which is
+ * convention #2 again. Hence `before:` on all three siblings.
+ *
+ * ### The contradiction it can catch that a library cannot
+ *
+ * See `consistency.ts`. Both this plugin and `cors` call the same check with
+ * whatever the other has published, so whichever is registered second finds
+ * both halves — the ordering above means that is normally `cors`.
+ */
+
+export type ReferrerPolicy =
+  | 'no-referrer'
+  | 'no-referrer-when-downgrade'
+  | 'origin'
+  | 'origin-when-cross-origin'
+  | 'same-origin'
+  | 'strict-origin'
+  | 'strict-origin-when-cross-origin'
+  | 'unsafe-url'
+
+export interface SecurityHeadersOptions {
+  /** `X-Content-Type-Options: nosniff`. Off is not a supported configuration; the flag exists for tests. */
+  readonly noSniff?: boolean | undefined
+  /** `X-Frame-Options`. `false` omits it — do that only when a CSP `frame-ancestors` replaces it. */
+  readonly frameOptions?: 'DENY' | 'SAMEORIGIN' | false | undefined
+  readonly referrerPolicy?: ReferrerPolicy | false | undefined
+  /** `Cross-Origin-Opener-Policy`. */
+  readonly crossOriginOpener?: 'same-origin' | 'same-origin-allow-popups' | 'unsafe-none' | false | undefined
+  /**
+   * `Cross-Origin-Resource-Policy`. Defaults to `same-site` rather than
+   * `same-origin`: `same-origin` is the stricter reading of §19.2's
+   * "conservative", and it is also the value that silently breaks a CDN
+   * subdomain serving the same site's assets. `same-site` blocks the
+   * cross-*site* read that CORP exists to prevent and leaves the arrangement
+   * every real deployment has intact.
+   */
+  readonly crossOriginResource?: 'same-origin' | 'same-site' | 'cross-origin' | false | undefined
+  /**
+   * `Strict-Transport-Security`. **Off by default**, and this is the one
+   * default in the table that looks wrong until you have been bitten by it.
+   *
+   * §19.2 says "HSTS on when `secure: true`". A framework cannot tell whether
+   * it is behind TLS — `ctx.secure` reads `X-Forwarded-Proto`, which §19.4
+   * refuses to trust unless `trustProxy` is configured — so "on when secure"
+   * resolves to "on when a header we do not trust says so". And HSTS is not a
+   * header you can take back: a browser that has seen `max-age=31536000`
+   * refuses plain HTTP to that host for a year, including on the developer's
+   * own machine if it ever reached one. So it is opt-in, one line, in the file
+   * that already knows it is behind a load balancer.
+   */
+  readonly hsts?: { readonly maxAge?: number; readonly includeSubDomains?: boolean; readonly preload?: boolean } | false | undefined
+  /**
+   * `Content-Security-Policy`, verbatim. **Not set by default** — §19.2: "a
+   * wrong CSP is worse than none; we prompt instead of guessing." There is no
+   * builder here for the same reason: a policy assembled from options reads as
+   * if the framework vouched for it.
+   */
+  readonly contentSecurityPolicy?: string | false | undefined
+  /** Extra headers, staged with the rest. */
+  readonly headers?: Readonly<Record<string, string>> | undefined
+}
+
+/** One resolved header, so the set is data and the hook is a loop over it. */
+type Pair = readonly [name: string, value: string]
+
+export function securityHeaders(options: SecurityHeadersOptions = {}): Plugin<void, {}> {
+  return definePlugin<void, {}>({
+    name: 'security-headers',
+    version: '0.1.0',
+    // Before everything that can short-circuit. `cors` answers preflights and
+    // `rate-limit` throws 429s; a hook that runs after either is absent from
+    // exactly the responses §19.2 most wants these headers on. Hints on
+    // unregistered plugins are ignored (§10.5 step 4), so this costs nothing
+    // when the siblings are not installed.
+    before: ['cors', 'rate-limit'],
+    config: { namespace: 'security' },
+
+    setup(app) {
+      const pairs = resolve(options)
+      const corp = options.crossOriginResource ?? 'same-site'
+      assertCorsCorpConsistent(corp, app.exportsOf('cors') as CorsExports | undefined, app.pluginName)
+
+      // Unrolled at boot into a fixed array; the hook is one loop over a frozen
+      // list of string pairs, with no option reads and no branches per request.
+      app.hook('onRequest', function securityHeaders(ctx: Staging): undefined {
+        for (let i = 0; i < pairs.length; i++) {
+          const pair = pairs[i] as Pair
+          ctx.res.header(pair[0], pair[1])
+        }
+        return undefined
+      }, 'security-headers')
+
+      return { exports: { headers: pairs.map(([name]) => name), crossOriginResource: corp } }
+    },
+  })
+}
+
+function resolve(options: SecurityHeadersOptions): readonly Pair[] {
+  const out: Pair[] = []
+
+  if (options.noSniff !== false) out.push(['x-content-type-options', 'nosniff'])
+
+  const frame = options.frameOptions ?? 'DENY'
+  if (frame !== false) out.push(['x-frame-options', frame])
+
+  const referrer = options.referrerPolicy ?? 'no-referrer'
+  if (referrer !== false) out.push(['referrer-policy', referrer])
+
+  const coop = options.crossOriginOpener ?? 'same-origin'
+  if (coop !== false) out.push(['cross-origin-opener-policy', coop])
+
+  const corp = options.crossOriginResource ?? 'same-site'
+  if (corp !== false) out.push(['cross-origin-resource-policy', corp])
+
+  const hsts = options.hsts
+  if (hsts !== undefined && hsts !== false) {
+    const maxAge = hsts.maxAge ?? 15_552_000 // 180 days
+    out.push([
+      'strict-transport-security',
+      `max-age=${maxAge}` +
+        (hsts.includeSubDomains === true ? '; includeSubDomains' : '') +
+        (hsts.preload === true ? '; preload' : ''),
+    ])
+  }
+
+  const csp = options.contentSecurityPolicy
+  if (typeof csp === 'string' && csp.length > 0) out.push(['content-security-policy', csp])
+
+  for (const [name, value] of Object.entries(options.headers ?? {})) {
+    out.push([name.toLowerCase(), value])
+  }
+
+  return Object.freeze(out)
+}

package/src/shared.ts

@@ -0,0 +1,61 @@
+import type { ReplyBuilder, Reply, LowercaseName } from '@erenthedeveloper0/zen-core'
+
+/**
+ * What this pack touches on a context, declared structurally — §10.4.
+ *
+ * `Registrar.hook` takes a `Function` on purpose: a plugin is written before
+ * the application's decoration set exists, so pinning its hooks to
+ * `Context<never, X>` would reject the pattern for an `X` the author cannot
+ * know. The convention the examples already follow is to declare exactly the
+ * surface the hook uses (`examples/openapi/src/plugins/request-id.ts` declares
+ * `{ id: string }` and nothing else), and the point of doing it is that a
+ * middleware cannot quietly start depending on `ctx.user` later.
+ *
+ * These are split by concern rather than merged into one context type for the
+ * same reason: `securityHeaders` may not read the request, and the type says so.
+ */
+
+/** Reading the request without materialising the header record. */
+export interface RawReading {
+  readonly method: string
+  readonly raw: { header(name: LowercaseName): string | undefined }
+}
+
+/** Staging response metadata (§13.6) — applied at egress on every path. */
+export interface Staging {
+  readonly res: ReplyBuilder
+}
+
+/** Producing a reply from a hook, which is how a phase short-circuits (§9.2). */
+export interface Answering {
+  empty(status?: 204 | 205 | 304): Reply<null>
+  json<T>(body: T, init?: { status?: number }): Reply<T>
+}
+
+export type CorsRequest = RawReading & Answering
+
+/**
+ * `ctx.raw.header` rather than `ctx.headers[name]`.
+ *
+ * `ctx.headers` is lazy and memoised, but the first touch walks every header
+ * the adapter received and builds a record (`buildHeaders`, §7.2). These hooks
+ * run on *every* request in the application, including the ones whose handlers
+ * never look at a header, so making them the reason that record exists would be
+ * a cost the application did not ask for — §9.4's rule applied to a plugin
+ * rather than to the compiler.
+ */
+export function headerOf(ctx: RawReading, name: LowercaseName): string | undefined {
+  return ctx.raw.header(name)
+}
+
+/**
+ * A CORS preflight — an `OPTIONS` carrying `Access-Control-Request-Method`.
+ *
+ * Both halves are required by the Fetch standard and both are load-bearing
+ * here: an `OPTIONS` without the header is an ordinary request for a resource's
+ * options and may well have a route, and answering it with 204 would shadow
+ * that route with something the application did not write.
+ */
+export function isPreflight(ctx: RawReading): boolean {
+  return ctx.method === 'OPTIONS' && ctx.raw.header('access-control-request-method') !== undefined
+}