ingenium 0.0.1

package/src/csrf/middleware.ts

@@ -0,0 +1,224 @@
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+import { Buffer } from 'node:buffer'
+import { IngeniumError } from '../errors.ts'
+import type { IngeniumMiddleware } from '../middleware/types.ts'
+import type { IngeniumContext } from '../context/context.ts'
+import type { CsrfCookieOptions, CsrfOptions, CsrfValueReader } from './types.ts'
+
+/** 403 Forbidden — CSRF token missing or mismatched. */
+export class IngeniumCsrfError extends IngeniumError {
+  constructor(message = 'CSRF token validation failed') {
+    super(403, 'CSRF_FAILED', message)
+  }
+}
+
+const TOKEN_BYTES = 18
+const SAFE_METHODS_DEFAULT: readonly string[] = ['GET', 'HEAD', 'OPTIONS', 'TRACE']
+const COOKIE_NAME_DEFAULT = 'ingenium.csrf'
+const HEADER_NAMES_DEFAULT: readonly string[] = ['x-csrf-token', 'x-xsrf-token']
+
+interface ResolvedOptions {
+  secrets: string[]                   // first signs, all verify (rotation)
+  storage: 'cookie' | 'session'
+  cookie: Required<CsrfCookieOptions>
+  ignoreMethods: Set<string>
+  value: CsrfValueReader
+  skip: ((ctx: IngeniumContext) => boolean | Promise<boolean>) | null
+}
+
+/**
+ * CSRF protection middleware. Two modes:
+ *
+ * - `storage: 'cookie'` (default) — double-submit cookie pattern. A
+ *   randomly-generated token is HMAC-signed, written to a non-HttpOnly
+ *   cookie on safe requests, and the client must echo the cookie value
+ *   back in a header (`X-CSRF-Token`) on unsafe requests. The signature
+ *   prevents client-side forgery; the same-origin policy prevents
+ *   cross-origin sites from reading the cookie.
+ *
+ * - `storage: 'session'` — synchronizer pattern. The token is stored on
+ *   `ctx.session` and matched against the submitted token. Requires
+ *   `sessionMiddleware` to run before this middleware.
+ *
+ * Use `ctx.state.csrfToken` (or call `(ctx as IngeniumContext & { csrfToken(): string }).csrfToken()`)
+ * to read the current token to embed in HTML forms or send to a JS client.
+ */
+export function csrfMiddleware(opts: CsrfOptions = {}): IngeniumMiddleware {
+  const resolved = resolveOptions(opts)
+  if (resolved.storage === 'cookie' && resolved.secrets.length === 0) {
+    throw new Error("csrfMiddleware: `secret` is required when storage is 'cookie'")
+  }
+
+  return async (ctx, next) => {
+    if (resolved.skip && (await resolved.skip(ctx))) {
+      await next()
+      return
+    }
+
+    // Resolve / mint the expected token for this request.
+    let expected = readExpectedToken(ctx, resolved)
+    let mintedThisRequest = false
+    if (!expected) {
+      expected = mintToken(resolved)
+      mintedThisRequest = true
+    }
+
+    // Expose token to handlers via ctx.state.csrfToken AND a method.
+    ctx.state.csrfToken = expected
+    ;(ctx as IngeniumContext & { csrfToken: () => string }).csrfToken = () => expected as string
+
+    const isUnsafe = !resolved.ignoreMethods.has(ctx.method)
+    if (isUnsafe) {
+      const submitted = await resolved.value(ctx)
+      if (!submitted || !tokenMatches(submitted, expected)) {
+        throw new IngeniumCsrfError()
+      }
+    }
+
+    await next()
+
+    // Issue (or refresh) the cookie on cookie-storage mode.
+    if (resolved.storage === 'cookie' && (mintedThisRequest || isUnsafe)) {
+      writeCookie(ctx, expected, resolved.cookie)
+    } else if (resolved.storage === 'session' && mintedThisRequest) {
+      writeSession(ctx, expected)
+    }
+  }
+}
+
+// ───── Token mint / verify ─────────────────────────────────────────────────
+
+function mintToken(opts: ResolvedOptions): string {
+  const raw = randomBytes(TOKEN_BYTES).toString('base64url')
+  if (opts.storage === 'session' || opts.secrets.length === 0) return raw
+  // Signed for double-submit so a forged cookie value can't pass verification.
+  const sig = signToken(raw, opts.secrets[0]!)
+  return `${raw}.${sig}`
+}
+
+function signToken(raw: string, secret: string): string {
+  return createHmac('sha256', secret).update(raw).digest('base64url')
+}
+
+function tokenMatches(submitted: string, expected: string): boolean {
+  const a = Buffer.from(submitted)
+  const b = Buffer.from(expected)
+  // Length-mismatch already rules out a match; timingSafeEqual requires equal length.
+  if (a.length !== b.length) return false
+  return timingSafeEqual(a, b)
+}
+
+function verifySignedToken(token: string, secrets: readonly string[]): boolean {
+  const dot = token.lastIndexOf('.')
+  if (dot <= 0) return false
+  const raw = token.slice(0, dot)
+  const sig = token.slice(dot + 1)
+  for (const secret of secrets) {
+    const expected = signToken(raw, secret)
+    if (expected.length !== sig.length) continue
+    if (timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) return true
+  }
+  return false
+}
+
+// ───── Storage ─────────────────────────────────────────────────────────────
+
+function readExpectedToken(ctx: IngeniumContext, opts: ResolvedOptions): string | null {
+  if (opts.storage === 'cookie') {
+    const cookies = parseCookies(ctx.headers['cookie'])
+    const token = cookies[opts.cookie.name]
+    if (!token) return null
+    if (opts.secrets.length > 0 && !verifySignedToken(token, opts.secrets)) return null
+    return token
+  }
+  // Session storage
+  const session = (ctx as IngeniumContext & { session?: { get: (k: string) => unknown } }).session
+  if (!session) {
+    throw new Error("csrfMiddleware: storage='session' requires sessionMiddleware to run first")
+  }
+  const token = session.get('csrfToken')
+  return typeof token === 'string' && token.length > 0 ? token : null
+}
+
+// TODO: migrate to ctx.cookies — kept inline because csrf uses the
+// double-submit pattern with a non-HttpOnly cookie + HMAC value, which the
+// generic cookie API doesn't model directly.
+function writeCookie(ctx: IngeniumContext, token: string, cookie: Required<CsrfCookieOptions>): void {
+  const parts: string[] = [`${cookie.name}=${encodeURIComponent(token)}`]
+  parts.push(`Path=${cookie.path}`)
+  if (cookie.domain) parts.push(`Domain=${cookie.domain}`)
+  parts.push(`Max-Age=${cookie.maxAgeSeconds}`)
+  parts.push(`SameSite=${cookie.sameSite[0]!.toUpperCase() + cookie.sameSite.slice(1)}`)
+  if (cookie.secure) parts.push('Secure')
+  if (cookie.httpOnly) parts.push('HttpOnly')
+  appendSetCookie(ctx, parts.join('; '))
+}
+
+function writeSession(ctx: IngeniumContext, token: string): void {
+  const session = (ctx as IngeniumContext & { session?: { set: (k: string, v: unknown) => void } }).session
+  if (!session) return
+  session.set('csrfToken', token)
+}
+
+function appendSetCookie(ctx: IngeniumContext, value: string): void {
+  const existing = ctx._headers['set-cookie']
+  if (!existing) {
+    ctx._headers['set-cookie'] = [value]
+  } else if (Array.isArray(existing)) {
+    existing.push(value)
+  } else {
+    ctx._headers['set-cookie'] = [existing, value]
+  }
+}
+
+function parseCookies(header: string | string[] | undefined): Record<string, string> {
+  const out: Record<string, string> = {}
+  if (!header) return out
+  const flat = Array.isArray(header) ? header.join('; ') : header
+  for (const piece of flat.split(';')) {
+    const eq = piece.indexOf('=')
+    if (eq < 0) continue
+    const k = piece.slice(0, eq).trim()
+    const v = piece.slice(eq + 1).trim()
+    if (!k || k in out) continue // first occurrence wins
+    try {
+      out[k] = decodeURIComponent(v)
+    } catch {
+      out[k] = v
+    }
+  }
+  return out
+}
+
+// ───── Options resolution ──────────────────────────────────────────────────
+
+function resolveOptions(opts: CsrfOptions): ResolvedOptions {
+  const secrets =
+    typeof opts.secret === 'string'
+      ? [opts.secret]
+      : Array.isArray(opts.secret)
+        ? [...opts.secret]
+        : []
+  const storage = opts.storage ?? 'cookie'
+  const cookie: Required<CsrfCookieOptions> = {
+    name: opts.cookie?.name ?? COOKIE_NAME_DEFAULT,
+    path: opts.cookie?.path ?? '/',
+    domain: opts.cookie?.domain ?? '',
+    sameSite: opts.cookie?.sameSite ?? 'lax',
+    secure: opts.cookie?.secure ?? false,
+    httpOnly: opts.cookie?.httpOnly ?? false,
+    maxAgeSeconds: opts.cookie?.maxAgeSeconds ?? 7 * 24 * 60 * 60,
+  }
+  const ignoreMethods = new Set((opts.ignoreMethods ?? SAFE_METHODS_DEFAULT).map((m) => m.toUpperCase()))
+  const value = opts.value ?? defaultValueReader
+  return { secrets, storage, cookie, ignoreMethods, value, skip: opts.skip ?? null }
+}
+
+const defaultValueReader: CsrfValueReader = (ctx) => {
+  for (const name of HEADER_NAMES_DEFAULT) {
+    const v = ctx.headers[name]
+    if (v) return Array.isArray(v) ? v[0] : v
+  }
+  const q = ctx.query.get('_csrf')
+  return q ?? undefined
+}

package/src/csrf/types.ts

@@ -0,0 +1,65 @@
+import type { IngeniumContext } from '../context/context.ts'
+
+/**
+ * Where the CSRF token lives between requests.
+ *
+ * - `'cookie'` (default): double-submit cookie pattern. Token is generated
+ *   on safe requests, written to a non-HttpOnly cookie, and the client must
+ *   echo it back via a header on unsafe requests. No session required.
+ * - `'session'`: synchronizer pattern. Token is stored on `ctx.session`
+ *   and validated against the submitted token on unsafe requests. Requires
+ *   `sessionMiddleware` to run before this middleware.
+ */
+export type CsrfStorage = 'cookie' | 'session'
+
+/** How to extract the submitted token from an incoming request. */
+export type CsrfValueReader = (ctx: IngeniumContext) => string | undefined | Promise<string | undefined>
+
+export interface CsrfCookieOptions {
+  /** Cookie name. Default `ingenium.csrf`. */
+  name?: string
+  /** Restrict cookie to a single subpath. Default `/`. */
+  path?: string
+  /** Restrict cookie to a domain. Default unset. */
+  domain?: string
+  /** SameSite policy. Default `'lax'`. */
+  sameSite?: 'lax' | 'strict' | 'none'
+  /** Mark cookie Secure. Default `false`; set `true` behind TLS. */
+  secure?: boolean
+  /**
+   * Mark cookie HttpOnly. **Default `false`** — clients must read the cookie
+   * to copy the value into the request header. Setting `true` would break the
+   * double-submit pattern; only enable with a custom value reader that pulls
+   * the token from elsewhere.
+   */
+  httpOnly?: boolean
+  /** Cookie max-age (seconds). Default 7 days. */
+  maxAgeSeconds?: number
+}
+
+export interface CsrfOptions {
+  /**
+   * HMAC secret used to sign the token. Required for the cookie storage
+   * mode (signed double-submit). For session storage the secret is optional
+   * — the session id already authenticates the binding.
+   */
+  secret?: string | string[]
+  /** Token storage strategy. Default `'cookie'`. */
+  storage?: CsrfStorage
+  /** Cookie options when `storage === 'cookie'`. */
+  cookie?: CsrfCookieOptions
+  /** Methods that bypass validation. Default `['GET', 'HEAD', 'OPTIONS', 'TRACE']`. */
+  ignoreMethods?: readonly string[]
+  /**
+   * How to extract the submitted token. Default reads (in order):
+   *   1. `X-CSRF-Token` header
+   *   2. `X-XSRF-Token` header (Angular convention)
+   *   3. `_csrf` query string parameter
+   */
+  value?: CsrfValueReader
+  /**
+   * Per-request opt-out. Return `true` to skip validation entirely for
+   * this request (and skip token issuance).
+   */
+  skip?: (ctx: IngeniumContext) => boolean | Promise<boolean>
+}

package/src/errors.ts

@@ -0,0 +1,148 @@
+/**
+ * Base error class for all framework-emitted errors. Errors that extend
+ * `IngeniumError` are caught by the global error boundary and serialized to the
+ * client according to their `statusCode` and `code`.
+ */
+export class IngeniumError extends Error {
+  /**
+   * @param statusCode HTTP status code to send to the client.
+   * @param code Machine-readable error code (UPPER_SNAKE_CASE convention).
+   * @param message Human-readable error message.
+   * @param cause Optional underlying error.
+   */
+  constructor(
+    public readonly statusCode: number,
+    public readonly code: string,
+    message: string,
+    public override readonly cause?: unknown,
+  ) {
+    super(message)
+    this.name = new.target.name
+  }
+}
+
+/** 404 — no route matched. */
+export class IngeniumNotFoundError extends IngeniumError {
+  constructor(message = 'Not Found') {
+    super(404, 'NOT_FOUND', message)
+  }
+}
+
+/** 401 — authentication required or invalid. */
+export class IngeniumUnauthorizedError extends IngeniumError {
+  constructor(message = 'Unauthorized') {
+    super(401, 'UNAUTHORIZED', message)
+  }
+}
+
+/**
+ * 405 — path matched but method did not. Includes the list of allowed methods,
+ * which the framework writes into the `Allow` response header automatically.
+ */
+export class IngeniumMethodNotAllowedError extends IngeniumError {
+  constructor(public readonly allowed: readonly string[], message = 'Method Not Allowed') {
+    super(405, 'METHOD_NOT_ALLOWED', message)
+  }
+}
+
+/** 413 — request body exceeded the configured `maxBytes` limit. */
+export class IngeniumPayloadTooLargeError extends IngeniumError {
+  constructor(message = 'Payload Too Large') {
+    super(413, 'PAYLOAD_TOO_LARGE', message)
+  }
+}
+
+/**
+ * 422 — request body parsed successfully but failed validation. The `fields`
+ * map is serialized into the response body so clients can render field-level
+ * error messages.
+ */
+export class IngeniumValidationError extends IngeniumError {
+  constructor(public readonly fields: Record<string, string>, message = 'Validation Failed') {
+    super(422, 'VALIDATION_FAILED', message)
+  }
+}
+
+/** 400 — request was malformed (bad JSON, invalid content-type, etc). */
+export class IngeniumBadRequestError extends IngeniumError {
+  constructor(message = 'Bad Request', cause?: unknown) {
+    super(400, 'BAD_REQUEST', message, cause)
+  }
+}
+
+/**
+ * 500 — caller attempted to write a header name or value containing CR or
+ * LF. Node would eventually reject these at the wire level, but the late
+ * throw produces a useless stack — we fail fast at the call site so the
+ * offending header (and the route that set it) shows up in the trace.
+ */
+export class IngeniumHeaderInjectionError extends IngeniumError {
+  constructor(message = 'Header value contains CR/LF (possible header injection)') {
+    super(500, 'HEADER_INJECTION', message)
+  }
+}
+
+/**
+ * 500 — `ctx.json` (or `respondJsonWithEtag`) was handed a value that
+ * `JSON.stringify` cannot serialize: a circular structure, a `BigInt`, or
+ * any other unsupported shape. The original `TypeError` is attached as
+ * `cause` and emitted via `process.emitWarning` for diagnostics.
+ */
+export class IngeniumUnserializableError extends IngeniumError {
+  constructor(message: string, cause?: unknown) {
+    super(500, 'UNSERIALIZABLE_RESPONSE', message, cause)
+  }
+}
+
+/**
+ * Sinatra-style `halt` short-circuit. Thrown by `ctx.halt(status, body?)`;
+ * caught by the default error boundary and serialized according to `bodyShape`:
+ *
+ * - `'none'`  → boundary uses default `{ error, code: 'HALT' }` JSON shape.
+ * - `'text'`  → boundary writes `body` as `text/plain` verbatim.
+ * - `'json'`  → boundary writes `body` as `application/json`.
+ *
+ * The body shape is decided at the call site (string ⇒ text, object ⇒ json,
+ * undefined ⇒ none) so the boundary can branch without re-inspecting types.
+ * Custom `app.onError` handlers still receive the error and can override it
+ * (e.g. add a header, reshape the body) by writing the response themselves.
+ */
+export class IngeniumHaltError extends IngeniumError {
+  /** What the default error boundary should do with `body`. */
+  readonly bodyShape: 'none' | 'text' | 'json'
+  /** The body argument from `ctx.halt(status, body?)`. */
+  readonly body: string | Record<string, unknown> | undefined
+
+  constructor(statusCode: number, body?: string | Record<string, unknown>) {
+    let shape: 'none' | 'text' | 'json'
+    let message: string
+    if (body === undefined) {
+      shape = 'none'
+      message = `Halted with status ${statusCode}`
+    } else if (typeof body === 'string') {
+      shape = 'text'
+      message = body
+    } else {
+      shape = 'json'
+      // Best-effort message for ctx.error / logging; the JSON body is the
+      // wire-level payload regardless.
+      message = typeof body['error'] === 'string' ? (body['error'] as string) : 'HALT'
+    }
+    super(statusCode, 'HALT', message)
+    this.bodyShape = shape
+    this.body = body
+  }
+}
+
+/**
+ * 503 — handler exceeded the configured `requestTimeoutMs` ceiling. The
+ * orphaned handler is NOT cancelled (JavaScript can't safely cancel a
+ * Promise); the framework just stops waiting for it. Late writes from the
+ * orphaned handler are guarded by the per-request epoch counter on the
+ * context and discarded with a `process.emitWarning`.
+ */
+export class IngeniumTimeoutError extends IngeniumError {
+  constructor(timeoutMs: number, message?: string) {
+    super(503, 'REQUEST_TIMEOUT', message ?? `Request exceeded ${timeoutMs}ms`)
+  }
+}

package/src/idempotency/middleware.ts

@@ -0,0 +1,197 @@
+import { Buffer } from 'node:buffer'
+import type { IngeniumContext, ResponseBody } from '../context/context.ts'
+import type { IngeniumMiddleware } from '../middleware/types.ts'
+import type { HttpMethod } from '../router/types.ts'
+import { IdempotencyMemoryStore } from './store.ts'
+import type {
+  CachedResponse,
+  IdempotencyOptions,
+  ResolvedIdempotencyOptions,
+} from './types.ts'
+
+const DEFAULT_METHODS: readonly HttpMethod[] = ['POST', 'PATCH', 'DELETE']
+
+/**
+ * Default cacheable predicate: cache 2xx/3xx/4xx, NOT 5xx. Stripe
+ * convention — a transient 500 must not be replayed forever.
+ */
+const DEFAULT_CACHEABLE = (status: number): boolean => status >= 200 && status < 500
+
+/** Authorization-header-derived scope; falls back to `'anon'`. */
+function defaultScope(ctx: IngeniumContext): string {
+  const auth = ctx.headers['authorization']
+  if (typeof auth === 'string' && auth.length > 0) return auth
+  if (Array.isArray(auth) && auth.length > 0 && typeof auth[0] === 'string') return auth[0]
+  return 'anon'
+}
+
+/** Pull a header value as a single string (first element if it came as an array). */
+function readHeader(ctx: IngeniumContext, lowerName: string): string | undefined {
+  const v = ctx.headers[lowerName]
+  if (typeof v === 'string') return v
+  if (Array.isArray(v)) return typeof v[0] === 'string' ? v[0] : undefined
+  return undefined
+}
+
+/**
+ * Snapshot whatever the handler wrote to `ctx`. Streams are NOT cached —
+ * we cannot rewind a `Readable`, so a streamed response makes the request
+ * non-idempotent (the second call will run the handler again).
+ *
+ * Returns `null` to signal "do not cache" (stream / nothing written).
+ */
+function snapshot(ctx: IngeniumContext): CachedResponse | null {
+  if (!ctx._written) return null
+  const body = ctx._body
+  let serialized: string | Buffer | null
+  switch (body.kind) {
+    case 'none':
+      serialized = null
+      break
+    case 'string':
+      serialized = body.data
+      break
+    case 'buffer':
+      // Copy the buffer — caller may reuse the underlying memory.
+      serialized = Buffer.from(body.data)
+      break
+    case 'stream':
+      return null
+  }
+  // Shallow-copy headers; values are strings or string[] (immutable in practice).
+  const headersCopy: Record<string, string | string[]> = Object.create(null)
+  for (const k of Object.keys(ctx._headers)) {
+    const v = ctx._headers[k]
+    if (v === undefined) continue
+    headersCopy[k] = Array.isArray(v) ? [...v] : v
+  }
+  return { statusCode: ctx._statusCode, headers: headersCopy, body: serialized }
+}
+
+/** Replay a cached response onto a fresh `ctx`. */
+function replay(ctx: IngeniumContext, cached: CachedResponse): void {
+  ctx._statusCode = cached.statusCode
+  // Replace, not merge — replayed response is authoritative.
+  ctx._headers = Object.create(null) as Record<string, string | string[]>
+  for (const k of Object.keys(cached.headers)) {
+    const v = cached.headers[k]
+    if (v === undefined) continue
+    ctx._headers[k] = Array.isArray(v) ? [...v] : v
+  }
+  ctx._headers['idempotent-replayed'] = 'true'
+  let nextBody: ResponseBody
+  if (cached.body === null) {
+    nextBody = { kind: 'none' }
+  } else if (typeof cached.body === 'string') {
+    nextBody = { kind: 'string', data: cached.body }
+  } else {
+    nextBody = { kind: 'buffer', data: Buffer.from(cached.body) }
+  }
+  ctx._body = nextBody
+  ctx._written = true
+}
+
+/**
+ * Idempotency-Key middleware (per Stripe / IETF idempotency-key draft).
+ *
+ * Behavior:
+ * - Non-mutating method or missing header → pass through.
+ * - Mutating method WITH header:
+ *   1. Build cache key: `<scope>:<method>:<path>:<idempotency-key>`.
+ *   2. Cache hit → replay the cached (status, headers, body) and set
+ *      `Idempotent-Replayed: true`. Handler does NOT run.
+ *   3. Cache miss → run handler. If the response is cacheable (i.e. not a
+ *      stream and something was written), persist it under the key with
+ *      the configured TTL.
+ *   4. Concurrent in-flight requests for the same key are coordinated via
+ *      an in-process Promise map: the second request awaits the first and
+ *      replays its result.
+ *
+ * Note: the cache key intentionally does NOT include the request body —
+ * the spec assumes the client guarantees byte-for-byte identical retries,
+ * and reading the body at middleware-entry time would defeat lazy parsing.
+ *
+ * @example
+ *   app.use(ingenium.idempotency({
+ *     store: new IdempotencyMemoryStore(),
+ *     ttlSeconds: 86_400,
+ *   }))
+ */
+export function idempotencyMiddleware(opts: IdempotencyOptions = {}): IngeniumMiddleware {
+  const resolved: ResolvedIdempotencyOptions = {
+    header: (opts.header ?? 'Idempotency-Key').toLowerCase(),
+    store: opts.store ?? new IdempotencyMemoryStore(),
+    ttlMs: (opts.ttlSeconds ?? 86_400) * 1000,
+    scope: opts.scope ?? defaultScope,
+    methodSet: new Set(opts.methods ?? DEFAULT_METHODS),
+    cacheable: opts.cacheable ?? DEFAULT_CACHEABLE,
+  }
+
+  if (resolved.ttlMs <= 0) {
+    throw new Error('idempotency: ttlSeconds must be > 0')
+  }
+
+  // Per-key in-flight map. The promise resolves once the first handler
+  // finishes and its response has been snapshotted (or with `null` if the
+  // response wasn't cacheable — second request then runs the handler).
+  const inflight: Map<string, Promise<CachedResponse | null>> = new Map()
+
+  return async (ctx, next) => {
+    if (!resolved.methodSet.has(ctx.method)) {
+      return next()
+    }
+
+    const headerValue = readHeader(ctx, resolved.header)
+    if (!headerValue || headerValue.length === 0) {
+      return next()
+    }
+
+    const scope = resolved.scope(ctx)
+    const cacheKey = `${scope}:${ctx.method}:${ctx.path}:${headerValue}`
+
+    // 1. Persisted cache hit?
+    const existing = await resolved.store.get(cacheKey)
+    if (existing) {
+      replay(ctx, existing)
+      return
+    }
+
+    // 2. In-flight from a concurrent request?
+    const pending = inflight.get(cacheKey)
+    if (pending) {
+      const result = await pending
+      if (result) {
+        replay(ctx, result)
+        return
+      }
+      // First request wasn't cacheable — fall through and run the handler.
+    }
+
+    // 3. Cache miss + no in-flight: take ownership.
+    let resolveInflight!: (value: CachedResponse | null) => void
+    const ownPromise = new Promise<CachedResponse | null>((res) => { resolveInflight = res })
+    inflight.set(cacheKey, ownPromise)
+
+    try {
+      await next()
+      const captured = snapshot(ctx)
+      // Honor the `cacheable` predicate — by default 5xx is NOT cached so a
+      // transient failure can't poison the key for the entire TTL. When
+      // skipped, resolve the in-flight promise with `null` so any waiter
+      // re-runs the handler instead of replaying a stale failure.
+      if (captured && resolved.cacheable(captured.statusCode)) {
+        await resolved.store.set(cacheKey, captured, resolved.ttlMs)
+        resolveInflight(captured)
+      } else {
+        resolveInflight(null)
+      }
+    } catch (err) {
+      // Don't cache failures — clear the in-flight slot so retries can run
+      // the handler fresh, and let the error propagate.
+      resolveInflight(null)
+      throw err
+    } finally {
+      inflight.delete(cacheKey)
+    }
+  }
+}