@nifrajs/middleware 0.1.0-alpha.1

package/src/rate-limit.ts

@@ -0,0 +1,248 @@
+import type { Middleware } from "@nifrajs/core"
+
+export interface RateLimitResult {
+  /** Hits recorded in the current window, including this one. */
+  readonly count: number
+  /** Epoch-ms when the current window resets. */
+  readonly resetAt: number
+}
+
+/**
+ * Counter backend. Production deploys MUST use a shared store (Redis, etc.) so the
+ * limit holds across instances — that's a user dependency, not ours, hence the
+ * interface. {@link MemoryStore} is for dev / single-instance only.
+ */
+export interface RateLimitStore {
+  hit(key: string, windowMs: number): Promise<RateLimitResult>
+}
+
+export interface MemoryStoreOptions {
+  /** Allow the in-memory store in production. Off by default — a per-instance limiter is unsafe across instances. */
+  readonly allowInProduction?: boolean
+  /** Hard cap on tracked client keys; expired keys are evicted first, then oldest active keys. Default `100_000`.
+   * Bounds memory against an unbounded key space (bot scans, per-IP buckets). */
+  readonly maxKeys?: number
+  /** Minimum interval (ms) between amortized sweeps of expired windows. Default `30_000`. */
+  readonly sweepIntervalMs?: number
+}
+
+/** Max entries scanned (oldest-first) per eviction looking for an expired victim before falling back
+ * to evicting the oldest-inserted. Bounds eviction to O(1) per insertion instead of a full O(n) sweep
+ * under a distinct-key flood — the abuse the key cap defends against. */
+const MAX_EVICTION_SCAN = 64
+
+/**
+ * In-process fixed-window store. Refuses to run in production unless explicitly allowed.
+ *
+ * Bounded against unbounded growth: expired windows are swept lazily (amortized, at most once per
+ * `sweepIntervalMs`) and the key set is hard-capped at `maxKeys` (expired keys are evicted first,
+ * then oldest active keys).
+ * Without this, expired entries for keys never seen again — and the unbounded key space of a bot scan
+ * — would accumulate in the map forever and OOM a single-instance deploy.
+ */
+export class MemoryStore implements RateLimitStore {
+  private readonly windows = new Map<string, { count: number; resetAt: number }>()
+  private readonly maxKeys: number
+  private readonly sweepIntervalMs: number
+  private lastSweep = 0
+  private evictionScans = 0
+
+  /** Cumulative entries inspected by the eviction scan since construction — an eviction-pressure
+   * gauge. The bounded scan keeps this ~O(1) per over-cap insert (≤ {@link MAX_EVICTION_SCAN}); a
+   * regressed full O(n) sweep would make it ~maxKeys per insert (what the regression test asserts). */
+  get evictionScanCount(): number {
+    return this.evictionScans
+  }
+
+  constructor(options: MemoryStoreOptions = {}) {
+    if (options.allowInProduction !== true && process.env.NODE_ENV === "production") {
+      throw new Error(
+        "MemoryStore is per-instance and unsafe in production (each instance limits separately). " +
+          "Use a shared store (e.g. Redis), or pass { allowInProduction: true } for a single-instance deploy.",
+      )
+    }
+    this.maxKeys = options.maxKeys ?? 100_000
+    if (!Number.isInteger(this.maxKeys) || this.maxKeys < 1) {
+      throw new Error("MemoryStore: maxKeys must be a positive integer")
+    }
+    this.sweepIntervalMs = options.sweepIntervalMs ?? 30_000
+    if (!Number.isFinite(this.sweepIntervalMs) || this.sweepIntervalMs < 0) {
+      throw new Error("MemoryStore: sweepIntervalMs must be a non-negative number")
+    }
+  }
+
+  hit(key: string, windowMs: number): Promise<RateLimitResult> {
+    const now = Date.now()
+    // Amortized GC: at most once per sweepIntervalMs, drop every window whose reset has passed. This
+    // bounds memory to ~the active key set instead of leaking an entry per distinct key ever seen.
+    if (now - this.lastSweep >= this.sweepIntervalMs) {
+      this.sweepExpired(now)
+      this.lastSweep = now
+    }
+    const current = this.windows.get(key)
+    if (current === undefined || now >= current.resetAt) {
+      const fresh = { count: 1, resetAt: now + windowMs }
+      this.windows.set(key, fresh)
+      this.enforceMaxKeys(now)
+      return Promise.resolve({ count: fresh.count, resetAt: fresh.resetAt })
+    }
+    current.count += 1
+    return Promise.resolve({ count: current.count, resetAt: current.resetAt })
+  }
+
+  private sweepExpired(now: number): void {
+    for (const [k, v] of this.windows) if (now >= v.resetAt) this.windows.delete(k)
+  }
+
+  private enforceMaxKeys(now: number): void {
+    if (this.windows.size <= this.maxKeys) return
+    // Prefer evicting an expired window over an active user's, but bound the work. A full sweep on
+    // every insertion is O(n)/request under a distinct-key flood — the exact abuse the cap defends
+    // against. Scan only a small fixed budget (oldest-first, where expired entries cluster) for a
+    // victim; if none is found, evict the oldest-inserted (O(1)). Expired entries beyond the budget
+    // are still reclaimed by the amortized sweep in `hit`.
+    while (this.windows.size > this.maxKeys) {
+      let victim: string | undefined
+      let scanned = 0
+      for (const [k, v] of this.windows) {
+        this.evictionScans++
+        if (now >= v.resetAt) {
+          victim = k
+          break
+        }
+        if (++scanned >= MAX_EVICTION_SCAN) break
+      }
+      if (victim === undefined) victim = this.windows.keys().next().value
+      if (victim === undefined) break
+      this.windows.delete(victim)
+    }
+  }
+}
+
+export interface RateLimitOptions {
+  /** Where counters live. `MemoryStore` for dev; a shared store in production. */
+  readonly store: RateLimitStore
+  /** Max requests allowed per window. */
+  readonly max: number
+  /** Window length, in milliseconds. */
+  readonly windowMs: number
+  /**
+   * How many trusted reverse proxies sit in front of the app and append to `X-Forwarded-For`.
+   * Default `0`.
+   *
+   * The default key reads the client IP from `X-Forwarded-For` as the address your **edge** proxy
+   * observed — the entry `trustedProxies` from the right (1 proxy → the rightmost hop; 2 → the
+   * second-from-right; …). Your proxies append on the right, so a client can only inject fake hops on
+   * the *left*, which this skips → not spoofable when `trustedProxies` matches your topology.
+   *
+   * ⚠️ With the default `0`, `X-Forwarded-For` is treated as fully client-controlled and **ignored**.
+   * Reading the
+   * *first* XFF hop — the old behavior — let any client mint a fresh bucket per request and defeat the
+   * limiter. Set `trustedProxies` (only safe behind a proxy you control that appends XFF), configure a
+   * trusted single-IP {@link header}, or supply a custom {@link key} (e.g. an authenticated user id).
+   */
+  readonly trustedProxies?: number
+  /** Exact trusted single-IP header, e.g. an infra-set `x-real-ip`. Not read unless configured. */
+  readonly header?: string
+  /**
+   * Allow one shared bucket when no per-request key can be derived. Off by default because it lets one
+   * client consume the quota for everyone. Enable only for intentional global throttles.
+   */
+  readonly allowGlobalKey?: boolean
+  /**
+   * Bucket key for a request. Overrides the default XFF-based key entirely — set this for accurate
+   * per-client limiting (e.g. an authenticated user id, or a header your proxy sets). A `Middleware`
+   * can't see the socket IP (that needs the server instance).
+   */
+  readonly key?: (req: Request) => string
+}
+
+function defaultKey(
+  req: Request,
+  trustedProxies: number,
+  header: string | undefined,
+  allowGlobalKey: boolean,
+): string | null {
+  if (header !== undefined) {
+    const ip = req.headers.get(header)
+    if (ip !== null && ip.trim() !== "") return ip.trim()
+  }
+  if (trustedProxies > 0) {
+    const xff = req.headers.get("x-forwarded-for")
+    if (xff !== null) {
+      const parts = xff.split(",")
+      // The leftmost of the trusted suffix (your proxies append on the right) = the address your edge
+      // proxy observed = the real client. A client can only prepend fakes further left, which this
+      // index skips. A chain shorter than `trustedProxies` (misconfig) → undefined → fall through.
+      const ip = parts[parts.length - trustedProxies]?.trim()
+      if (ip !== undefined && ip !== "") return ip
+    }
+  }
+  // No trusted proxy (or XFF absent/too-short): XFF isn't trustworthy, so don't derive a per-client key
+  // from it. A shared bucket is only safe when the app deliberately asked for a global throttle.
+  return allowGlobalKey ? "global" : null
+}
+
+/**
+ * Rate limiting as a {@link Middleware}. Runs in `onRequest` (before routing, so it
+ * also covers 404s); over the limit → `429` + `Retry-After`. Every response carries
+ * `RateLimit-Limit/Remaining/Reset` (added in `onResponse`, keyed off the request).
+ */
+export function rateLimit(options: RateLimitOptions): Middleware {
+  const { store, max, windowMs } = options
+  if (!Number.isInteger(max) || max < 1)
+    throw new Error("rateLimit: max must be a positive integer")
+  if (!Number.isFinite(windowMs) || windowMs <= 0) {
+    throw new Error("rateLimit: windowMs must be a positive number")
+  }
+  const trustedProxies = options.trustedProxies ?? 0
+  if (!Number.isInteger(trustedProxies) || trustedProxies < 0) {
+    throw new Error("rateLimit: trustedProxies must be a non-negative integer")
+  }
+  const header = options.header?.trim().toLowerCase()
+  if (header !== undefined && header.trim() === "") throw new Error("rateLimit: header is empty")
+  const allowGlobalKey = options.allowGlobalKey === true
+  if (
+    options.key === undefined &&
+    header === undefined &&
+    trustedProxies === 0 &&
+    !allowGlobalKey
+  ) {
+    throw new Error(
+      "rateLimit: configure key, header, or trustedProxies; pass allowGlobalKey: true only for an intentional shared bucket",
+    )
+  }
+  const keyOf =
+    options.key ?? ((req: Request) => defaultKey(req, trustedProxies, header, allowGlobalKey))
+  const quota = new WeakMap<Request, { remaining: number; resetSeconds: number }>()
+
+  return {
+    name: "rate-limit",
+    async onRequest(req) {
+      const key = keyOf(req)
+      if (typeof key !== "string" || key.trim() === "") {
+        return Response.json({ ok: false, error: "rate_limit_key_unavailable" }, { status: 500 })
+      }
+      const { count, resetAt } = await store.hit(key, windowMs)
+      const resetSeconds = Math.max(0, Math.ceil((resetAt - Date.now()) / 1000))
+      quota.set(req, { remaining: Math.max(0, max - count), resetSeconds })
+      if (count > max) {
+        return new Response(JSON.stringify({ ok: false, error: "rate_limited" }), {
+          status: 429,
+          headers: { "content-type": "application/json", "retry-after": String(resetSeconds) },
+        })
+      }
+      return undefined
+    },
+    onResponse(res, req) {
+      const info = quota.get(req)
+      if (info === undefined) return res
+      quota.delete(req)
+      const headers = new Headers(res.headers)
+      headers.set("RateLimit-Limit", String(max))
+      headers.set("RateLimit-Remaining", String(info.remaining))
+      headers.set("RateLimit-Reset", String(info.resetSeconds))
+      return new Response(res.body, { status: res.status, statusText: res.statusText, headers })
+    },
+  }
+}

package/src/request-id.ts

@@ -0,0 +1,30 @@
+import { definePlugin } from "@nifrajs/core"
+
+export interface RequestIdOptions {
+  /** Header read for an inbound id (trace propagation) + echoed on the response. Default `"x-request-id"`. */
+  readonly header?: string
+  /** Generate an id when the inbound header is absent. Default `crypto.randomUUID()`. */
+  readonly generate?: () => string
+}
+
+/**
+ * A {@link definePlugin} plugin that gives every request a stable id: it reuses an inbound
+ * `x-request-id` (or generates one), exposes it on the handler context as **`c.requestId`** (typed,
+ * threaded by `derive`), and echoes it on the response header. Idempotent — applying it twice is a
+ * no-op.
+ *
+ * ```ts
+ * app.use(requestId())          // c.requestId available downstream; X-Request-Id on responses
+ * ```
+ */
+export function requestId(options: RequestIdOptions = {}) {
+  const header = options.header ?? "x-request-id"
+  const generate = options.generate ?? (() => crypto.randomUUID())
+  return definePlugin("requestId", (app) =>
+    app.derive((c) => {
+      const id = c.req.headers.get(header) ?? generate()
+      c.set.headers[header] = id // echo on the response (route handlers)
+      return { requestId: id }
+    }),
+  )
+}

package/src/security-headers.ts

@@ -0,0 +1,51 @@
+import type { Middleware } from "@nifrajs/core"
+import { withHeaders } from "./_utils.ts"
+
+export interface SecurityHeadersOptions {
+  /** `Strict-Transport-Security`. Off by default — opt in once you're sure you're HTTPS-only. */
+  readonly hsts?: {
+    readonly maxAge: number
+    readonly includeSubDomains?: boolean
+    readonly preload?: boolean
+  }
+  /** `Content-Security-Policy` value. Off by default (app-specific). */
+  readonly contentSecurityPolicy?: string
+  /** `X-Frame-Options`. Default `"DENY"`. */
+  readonly frameOptions?: "DENY" | "SAMEORIGIN"
+  /** `Referrer-Policy`. Default `"no-referrer"`. */
+  readonly referrerPolicy?: string
+}
+
+/**
+ * A safe-by-default set of response security headers (`onResponse`, so they cover
+ * errors and 404s too): `X-Content-Type-Options: nosniff`, `X-Frame-Options`, and
+ * `Referrer-Policy` always; `Strict-Transport-Security` and `Content-Security-Policy`
+ * only when configured (both are environment-/app-specific).
+ */
+export function securityHeaders(options: SecurityHeadersOptions = {}): Middleware {
+  const frameOptions = options.frameOptions ?? "DENY"
+  const referrerPolicy = options.referrerPolicy ?? "no-referrer"
+  const csp = options.contentSecurityPolicy
+
+  let hstsValue: string | undefined
+  if (options.hsts !== undefined) {
+    const parts = [`max-age=${options.hsts.maxAge}`]
+    if (options.hsts.includeSubDomains) parts.push("includeSubDomains")
+    if (options.hsts.preload) parts.push("preload")
+    hstsValue = parts.join("; ")
+  }
+
+  return {
+    name: "security-headers",
+    // Mutate in place on the common (mutable-headers) response; clone only for an immutable one
+    // (see withHeaders — the old always-clone was ~3% of a realistic request).
+    onResponse: (res) =>
+      withHeaders(res, (headers) => {
+        headers.set("X-Content-Type-Options", "nosniff")
+        headers.set("X-Frame-Options", frameOptions)
+        headers.set("Referrer-Policy", referrerPolicy)
+        if (hstsValue !== undefined) headers.set("Strict-Transport-Security", hstsValue)
+        if (csp !== undefined) headers.set("Content-Security-Policy", csp)
+      }),
+  }
+}

package/src/timing.ts

@@ -0,0 +1,133 @@
+import { definePlugin } from "@nifrajs/core"
+import { withHeaders } from "./_utils.ts"
+
+export interface TimingMetric {
+  readonly name: string
+  readonly duration: number
+  readonly description?: string
+}
+
+export interface TimingControls {
+  mark(name: string): void
+  measure(name: string, start: string, end?: string): void
+  metric(name: string, duration: number, description?: string): void
+}
+
+export interface TimingOptions {
+  /** Name for the automatic total request metric. Default `"total"`; set `false` to disable. */
+  readonly total?: string | false
+  /** Decimal places for durations. Default `1`. */
+  readonly precision?: number
+  /** Only emit timing for matching requests. Default `true`. */
+  readonly enabled?: boolean | ((request: Request) => boolean)
+}
+
+interface TimingState {
+  readonly start: number
+  readonly marks: Map<string, number>
+  readonly metrics: TimingMetric[]
+}
+
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/
+
+function assertMetricName(name: string): void {
+  if (!TOKEN.test(name)) throw new Error(`timing: invalid metric name "${name}"`)
+}
+
+function assertDuration(duration: number): void {
+  if (!Number.isFinite(duration) || duration < 0) {
+    throw new Error("timing: duration must be a finite non-negative number")
+  }
+}
+
+function quoteDescription(value: string): string {
+  let out = ""
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i)
+    if (code < 0x20 || code === 0x7f) continue
+    const ch = value[i] ?? ""
+    out += ch === "\\" || ch === '"' ? `\\${ch}` : ch
+  }
+  return out
+}
+
+function formatMetric(metric: TimingMetric, precision: number): string {
+  let out = `${metric.name};dur=${metric.duration.toFixed(precision)}`
+  if (metric.description !== undefined) out += `;desc="${quoteDescription(metric.description)}"`
+  return out
+}
+
+/**
+ * Adds a `Server-Timing` response header and typed `c.timing` controls for custom metrics.
+ * Put request-rewriting middleware (for example `methodOverride`) before `timing()` so timing is
+ * attached to the final routed request.
+ */
+export function timing(options: TimingOptions = {}) {
+  const totalName = options.total === undefined ? "total" : options.total
+  if (totalName !== false) assertMetricName(totalName)
+  const precision = options.precision ?? 1
+  if (!Number.isInteger(precision) || precision < 0 || precision > 6) {
+    throw new Error("timing: precision must be an integer from 0 to 6")
+  }
+  const enabled = options.enabled ?? true
+  const isEnabled = typeof enabled === "function" ? enabled : enabled ? () => true : () => false
+  const states = new WeakMap<Request, TimingState>()
+
+  const controls = (req: Request): TimingControls => ({
+    mark(name) {
+      assertMetricName(name)
+      const state = states.get(req)
+      if (state !== undefined) state.marks.set(name, performance.now())
+    },
+    measure(name, start, end) {
+      assertMetricName(name)
+      const state = states.get(req)
+      if (state === undefined) return
+      const startAt = state.marks.get(start)
+      const endAt = end === undefined ? performance.now() : state.marks.get(end)
+      if (startAt === undefined || endAt === undefined) {
+        throw new Error("timing: unknown mark")
+      }
+      const duration = endAt - startAt
+      assertDuration(duration)
+      state.metrics.push({ name, duration })
+    },
+    metric(name, duration, description) {
+      assertMetricName(name)
+      assertDuration(duration)
+      const state = states.get(req)
+      if (state !== undefined) {
+        state.metrics.push(
+          description === undefined ? { name, duration } : { name, duration, description },
+        )
+      }
+    },
+  })
+
+  return definePlugin("timing", (app) =>
+    app
+      .onRequest((req) => {
+        if (!isEnabled(req)) return undefined
+        states.set(req, { start: performance.now(), marks: new Map(), metrics: [] })
+        return undefined
+      })
+      .derive((c) => ({ timing: controls(c.req) }))
+      .onResponse((res, req) => {
+        const state = states.get(req)
+        if (state === undefined) return res
+        states.delete(req)
+
+        const metrics =
+          totalName === false
+            ? state.metrics
+            : [{ name: totalName, duration: performance.now() - state.start }, ...state.metrics]
+        if (metrics.length === 0) return res
+
+        const value = metrics.map((metric) => formatMetric(metric, precision)).join(", ")
+        return withHeaders(res, (headers) => {
+          const existing = headers.get("server-timing")
+          headers.set("server-timing", existing === null ? value : `${existing}, ${value}`)
+        })
+      }),
+  )
+}

package/src/token-auth.ts

@@ -0,0 +1,172 @@
+import { definePlugin, type NifraPlugin } from "@nifrajs/core"
+
+type MaybePromise<T> = T | Promise<T>
+
+/**
+ * A token-auth plugin (`bearer` / `apiKey`). Apply it with `app.use(auth)` — it rejects unauthorized
+ * requests to **routes defined after it** with `401` (unless `optional`). Read the verified principal
+ * inside a handler/loader via {@link AuthPlugin.principal} (nullable) or
+ * {@link AuthPlugin.requirePrincipal} (throws `401` when absent). The principal is verified once per
+ * request and cached, so reading it is free.
+ *
+ * `beforeHandle` is **order-scoped**: place `app.use(auth)` before the routes it should guard. Hold the
+ * returned instance to read the principal (mirrors `@nifrajs/auth`'s `sessions.get(c)` and
+ * `@nifrajs/better-auth`'s `getSession(auth, req)`):
+ *
+ * ```ts
+ * const auth = bearer({ verify: (t) => lookupUser(t) }) // P = User (inferred)
+ * const app = server().use(auth).get("/me", (c) => auth.requirePrincipal(c.req))
+ * ```
+ */
+export type AuthPlugin<P> = NifraPlugin & {
+  /** The verified principal for this request, or `null` (no/invalid token in `optional` mode). */
+  principal(request: Request): P | null
+  /** The verified principal, or **throws a `401` `Response`** when absent. */
+  requirePrincipal(request: Request): P
+}
+
+interface TokenAuthConfig<P> {
+  readonly name: string
+  /** Pull the credential out of the request (e.g. the `Bearer` token or an `x-api-key` header). */
+  readonly extract: (request: Request) => string | undefined
+  /** Verify the credential → a principal (truthy) or `null`/`undefined` (rejected). */
+  readonly verify: (token: string) => MaybePromise<P | null | undefined>
+  readonly optional: boolean
+  /** `WWW-Authenticate` challenge value sent on `401` (bearer only). */
+  readonly challenge?: string
+}
+
+function createTokenAuth<P>(config: TokenAuthConfig<P>): AuthPlugin<P> {
+  // Per-request principal cache: verify runs once (in beforeHandle), reads are free + can't desync.
+  const store = new WeakMap<Request, P>()
+  const reject = (): Response =>
+    Response.json(
+      { ok: false, error: "unauthorized" },
+      {
+        status: 401,
+        headers: config.challenge !== undefined ? { "www-authenticate": config.challenge } : {},
+      },
+    )
+  const plugin = definePlugin(config.name, (app) =>
+    app.beforeHandle(async (c: { readonly req: Request }) => {
+      const token = config.extract(c.req)
+      // Empty string is treated as "no credential" — never passed to verify.
+      const principal = token !== undefined && token !== "" ? await config.verify(token) : null
+      if (principal !== null && principal !== undefined) {
+        store.set(c.req, principal)
+        return undefined // authorized — continue to the handler
+      }
+      return config.optional ? undefined : reject() // 401 short-circuits (skips the handler)
+    }),
+  )
+  return Object.assign(plugin, {
+    principal: (request: Request): P | null => store.get(request) ?? null,
+    requirePrincipal: (request: Request): P => {
+      const principal = store.get(request)
+      if (principal === undefined) throw reject()
+      return principal
+    },
+  }) as AuthPlugin<P>
+}
+
+export interface BearerOptions<P> {
+  /** Verify a bearer token → a principal (truthy) or `null`/`undefined` (rejected). May be async
+   * (DB/JWT lookup). For a constant-secret comparison, use a constant-time compare — never `===`. */
+  readonly verify: (token: string) => MaybePromise<P | null | undefined>
+  /** When `true`, requests without a valid token pass through (`principal` is `null`) instead of `401`. */
+  readonly optional?: boolean
+  /** `realm` for the `WWW-Authenticate: Bearer` header on `401`. Default `"api"`. */
+  readonly realm?: string
+}
+
+/**
+ * `Authorization: Bearer <token>` authentication. Parses the header, runs `verify`, and rejects with
+ * `401` (+ `WWW-Authenticate: Bearer`) when the token is missing/invalid (unless `optional`). The
+ * verified principal is read via the returned instance — see {@link AuthPlugin}.
+ */
+export function bearer<P>(options: BearerOptions<P>): AuthPlugin<P> {
+  const realm = options.realm ?? "api"
+  return createTokenAuth({
+    name: "bearer",
+    extract: (request) => {
+      const header = request.headers.get("authorization")
+      return header?.startsWith("Bearer ") === true ? header.slice(7).trim() : undefined
+    },
+    verify: options.verify,
+    optional: options.optional === true,
+    challenge: `Bearer realm="${realm}"`,
+  })
+}
+
+export interface ApiKeyVerifyOptions<P> {
+  /** Verify an API key → a principal or `null`/`undefined` (rejected). May be async. */
+  readonly verify: (key: string) => MaybePromise<P | null | undefined>
+  /** Header carrying the key. Default `"x-api-key"`. */
+  readonly header?: string
+  readonly optional?: boolean
+}
+
+export interface ApiKeyStaticOptions {
+  /** A fixed set of valid keys. Compared in **constant time** (see below); the matched key becomes the
+   * principal. Use `verify` instead for DB-backed / per-tenant keys. */
+  readonly keys: readonly string[]
+  readonly header?: string
+  readonly optional?: boolean
+}
+
+const textEncoder = new TextEncoder()
+
+async function sha256(input: string): Promise<Uint8Array> {
+  return new Uint8Array(await crypto.subtle.digest("SHA-256", textEncoder.encode(input)))
+}
+
+/** Constant-time byte compare. Inputs here are always 32-byte SHA-256 digests, so the early
+ * length check never leaks key length (digests are fixed-width). */
+function timingSafeEqualBytes(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false
+  let diff = 0
+  for (let i = 0; i < a.length; i++) diff |= (a[i] ?? 0) ^ (b[i] ?? 0)
+  return diff === 0
+}
+
+/**
+ * Build a constant-time verifier for a fixed key set. Each valid key is hashed once (SHA-256, fixed
+ * 32 bytes); per request the candidate is hashed and compared against every digest **without early
+ * exit**, so timing depends only on the (public) key count — never on the secret value or which key
+ * matched. Portable across all runtimes via WebCrypto.
+ */
+function staticKeyVerify(keys: readonly string[]): (candidate: string) => Promise<string | null> {
+  const validDigests = Promise.all(keys.map((key) => sha256(key)))
+  return async (candidate) => {
+    const candidateDigest = await sha256(candidate)
+    let matched = false
+    for (const digest of await validDigests) {
+      // No early `break`: every comparison runs so total time is independent of which key (if any) hit.
+      if (timingSafeEqualBytes(candidateDigest, digest)) matched = true
+    }
+    return matched ? candidate : null
+  }
+}
+
+/**
+ * API-key authentication via a header (default `x-api-key`). Two forms:
+ * - `apiKey({ keys })` — a fixed key set, compared in **constant time**; the matched key is the principal.
+ * - `apiKey({ verify })` — custom (e.g. DB-backed) verification returning a typed principal.
+ *
+ * Rejects missing/invalid keys with `401` (unless `optional`). Read the principal via the returned
+ * instance — see {@link AuthPlugin}.
+ */
+export function apiKey(options: ApiKeyStaticOptions): AuthPlugin<string>
+export function apiKey<P>(options: ApiKeyVerifyOptions<P>): AuthPlugin<P>
+export function apiKey<P>(
+  options: ApiKeyStaticOptions | ApiKeyVerifyOptions<P>,
+): AuthPlugin<P | string> {
+  const header = (options.header ?? "x-api-key").toLowerCase()
+  const verify = "keys" in options ? staticKeyVerify(options.keys) : options.verify
+  return createTokenAuth<P | string>({
+    name: "apiKey",
+    extract: (request) => request.headers.get(header) ?? undefined,
+    verify,
+    optional: options.optional === true,
+  })
+}