ingenium 0.0.1

package/src/jwt/verify.ts

@@ -0,0 +1,370 @@
+import {
+  constants as cryptoConstants,
+  createHmac,
+  createPublicKey,
+  verify as cryptoVerify,
+  timingSafeEqual,
+  type KeyObject,
+} from 'node:crypto'
+import { Buffer } from 'node:buffer'
+import type {
+  JwtAlgorithm,
+  JwtHeader,
+  JwtVerified,
+  JwtVerifyError,
+} from './types.ts'
+
+/**
+ * Per-algorithm wire descriptor.
+ *
+ * `family` selects the verifier branch; the digest / openssl-name fields are
+ * only consulted by the matching family.
+ */
+interface AlgSpec {
+  family: 'hmac' | 'rsa' | 'rsa-pss' | 'ecdsa'
+  /** node:crypto digest name (`sha256`, `sha384`, `sha512`). HMAC + asymmetric both use it. */
+  digest: string
+  /** Expected raw signature length for ECDSA (r||s, two equal-sized halves). */
+  ecSigLen?: number
+}
+
+const ALG_SPEC: Readonly<Record<JwtAlgorithm, AlgSpec>> = {
+  HS256: { family: 'hmac', digest: 'sha256' },
+  HS384: { family: 'hmac', digest: 'sha384' },
+  HS512: { family: 'hmac', digest: 'sha512' },
+  RS256: { family: 'rsa', digest: 'sha256' },
+  RS384: { family: 'rsa', digest: 'sha384' },
+  RS512: { family: 'rsa', digest: 'sha512' },
+  PS256: { family: 'rsa-pss', digest: 'sha256' },
+  PS384: { family: 'rsa-pss', digest: 'sha384' },
+  PS512: { family: 'rsa-pss', digest: 'sha512' },
+  // ECDSA: r||s lengths come from the curve order — 32B for P-256,
+  // 48B for P-384, 66B for P-521 (the curve is 521 bits, padded to 528 = 66B).
+  ES256: { family: 'ecdsa', digest: 'sha256', ecSigLen: 64 },
+  ES384: { family: 'ecdsa', digest: 'sha384', ecSigLen: 96 },
+  ES512: { family: 'ecdsa', digest: 'sha512', ecSigLen: 132 },
+}
+
+/**
+ * A verification key as supplied by the caller (post-resolution).
+ * - `string` / `Buffer` for HMAC secrets and PEM blobs.
+ * - `KeyObject` for pre-built node:crypto keys (and JWKS-derived keys).
+ */
+export type VerifyKeyMaterial = string | Buffer | KeyObject
+
+/** Optional kid-tagged variant — what middleware passes after kid resolution. */
+export interface KidTaggedKey {
+  kid?: string
+  key: VerifyKeyMaterial
+}
+
+/** Options accepted by {@link verifyJwt}. Mirrors the relevant subset of `JwtOptions`. */
+export interface VerifyOptions {
+  algorithms: readonly JwtAlgorithm[]
+  audience?: string | readonly string[]
+  issuer?: string | readonly string[]
+  maxAgeSeconds?: number
+  clockSkewSeconds?: number
+  /** Override "now" for deterministic tests. Returns seconds since epoch. */
+  nowSeconds?: () => number
+}
+
+/**
+ * Decode a base64url-encoded JSON segment. Returns `null` on malformed input
+ * (so callers can fold it into the generic `'malformed'` failure mode).
+ */
+function decodeJsonSegment<T = unknown>(segment: string): T | null {
+  if (!segment) return null
+  try {
+    const buf = Buffer.from(segment, 'base64url')
+    if (buf.length === 0) return null
+    const parsed = JSON.parse(buf.toString('utf8')) as unknown
+    if (parsed === null || typeof parsed !== 'object') return null
+    return parsed as T
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Constant-time HMAC verification.
+ *
+ * `timingSafeEqual` requires equal-length buffers — feeding mismatched lengths
+ * would itself leak length info via the throw. So we compare `signingInput`'s
+ * computed signature against the supplied one only after the explicit length
+ * check; both branches return `false` in O(constant) time relative to the
+ * caller's view (the throw path never executes).
+ */
+function hmacVerifies(
+  digest: string,
+  secret: VerifyKeyMaterial,
+  signingInput: string,
+  sig: Buffer,
+): boolean {
+  // HMAC accepts string or Buffer; KeyObject would be unusual but handle it.
+  const secretInput: string | Buffer =
+    typeof secret === 'string' || Buffer.isBuffer(secret)
+      ? secret
+      : secret.export({ format: 'buffer' } as never)
+  const expected = createHmac(digest, secretInput).update(signingInput).digest()
+  if (sig.length !== expected.length) return false
+  return timingSafeEqual(sig, expected)
+}
+
+/**
+ * Asymmetric verification via OpenSSL. The key may be a PEM (string/Buffer)
+ * or a pre-built `KeyObject`; we normalise via `createPublicKey` once. RSA
+ * algorithms (RSxxx) use PKCS1-v1_5; PS* uses PSS (with MGF1 + salt = digest);
+ * ECDSA decodes from raw r||s (per JOSE) rather than DER.
+ *
+ * `crypto.verify` from OpenSSL is constant-time relative to the key — we
+ * don't add an extra timing shield ourselves.
+ */
+function asymmetricVerifies(
+  spec: AlgSpec,
+  keyMaterial: VerifyKeyMaterial,
+  signingInput: string,
+  sig: Buffer,
+): boolean {
+  let key: KeyObject
+  try {
+    key =
+      typeof keyMaterial === 'string' || Buffer.isBuffer(keyMaterial)
+        ? createPublicKey(keyMaterial)
+        : keyMaterial
+  } catch {
+    return false
+  }
+
+  // ECDSA: spec mandates raw r||s (concatenation of two fixed-length integers).
+  // node:crypto's default DSA encoding is DER; we have to set 'ieee-p1363' to
+  // get the JOSE wire format. Length-check up front so a malformed sig never
+  // hits openssl with garbage.
+  if (spec.family === 'ecdsa') {
+    if (typeof spec.ecSigLen === 'number' && sig.length !== spec.ecSigLen) return false
+    try {
+      return cryptoVerify(spec.digest, Buffer.from(signingInput, 'utf8'), {
+        key,
+        dsaEncoding: 'ieee-p1363',
+      }, sig)
+    } catch {
+      return false
+    }
+  }
+
+  if (spec.family === 'rsa-pss') {
+    try {
+      return cryptoVerify(spec.digest, Buffer.from(signingInput, 'utf8'), {
+        key,
+        padding: cryptoConstants.RSA_PKCS1_PSS_PADDING,
+        // RFC 7518 §3.5: salt length equals the digest output length.
+        saltLength: cryptoConstants.RSA_PSS_SALTLEN_DIGEST,
+      }, sig)
+    } catch {
+      return false
+    }
+  }
+
+  // Plain RSA-PKCS1-v1_5.
+  try {
+    return cryptoVerify(spec.digest, Buffer.from(signingInput, 'utf8'), key, sig)
+  } catch {
+    return false
+  }
+}
+
+/** Allowed claim resolution — both single value and array forms are common in spec. */
+function audienceMatches(claim: unknown, expected: string | readonly string[]): boolean {
+  const wanted = typeof expected === 'string' ? [expected] : expected
+  if (typeof claim === 'string') return wanted.includes(claim)
+  if (Array.isArray(claim)) {
+    for (const c of claim) {
+      if (typeof c === 'string' && wanted.includes(c)) return true
+    }
+  }
+  return false
+}
+
+function issuerMatches(claim: unknown, expected: string | readonly string[]): boolean {
+  if (typeof claim !== 'string') return false
+  return typeof expected === 'string' ? expected === claim : expected.includes(claim)
+}
+
+/**
+ * Pure JWT verifier. No I/O, no logging — returns either a `JwtVerified` or
+ * a tagged failure object. The middleware layer is responsible for collapsing
+ * every failure into the same `IngeniumUnauthorizedError('Invalid token')` so
+ * the wire never reveals which check tripped.
+ *
+ * `keys` is a flat array because key-resolution (rotation, kid-lookup, JWKS)
+ * is the caller's responsibility; this function just tries them in order.
+ * Each entry may carry an optional `kid` — when present AND `header.kid` is
+ * set, only matching entries are considered. Without a `header.kid`, every
+ * entry is tried.
+ *
+ * `alg: 'none'` is rejected unconditionally, even if for some reason the
+ * allowlist were extended to include it. Defence in depth.
+ */
+export function verifyJwt<T = Record<string, unknown>>(
+  token: string,
+  keys: readonly (VerifyKeyMaterial | KidTaggedKey)[],
+  opts: VerifyOptions,
+): JwtVerified<T> | JwtVerifyError {
+  if (typeof token !== 'string' || token.length === 0) return { error: 'malformed' }
+
+  // Compact serialization: header.payload.signature
+  const firstDot = token.indexOf('.')
+  if (firstDot <= 0) return { error: 'malformed' }
+  const secondDot = token.indexOf('.', firstDot + 1)
+  if (secondDot <= firstDot + 1) return { error: 'malformed' }
+  if (token.indexOf('.', secondDot + 1) !== -1) return { error: 'malformed' }
+  // The signature segment may legally be empty only for 'alg: none', which
+  // we reject anyway. Treat empty as malformed.
+  if (secondDot === token.length - 1) return { error: 'malformed' }
+
+  const headerB64 = token.slice(0, firstDot)
+  const payloadB64 = token.slice(firstDot + 1, secondDot)
+  const sigB64 = token.slice(secondDot + 1)
+
+  const header = decodeJsonSegment<JwtHeader>(headerB64)
+  if (!header || typeof header.alg !== 'string') return { error: 'malformed' }
+
+  // Hard-reject 'none' BEFORE the allowlist check — even if a buggy caller
+  // somehow lets it through. This is the canonical JWT-library footgun.
+  if (header.alg === 'none' || header.alg.toLowerCase() === 'none') {
+    return { error: 'unsupported_alg' }
+  }
+
+  const alg = header.alg as JwtAlgorithm
+  if (!opts.algorithms.includes(alg)) return { error: 'unsupported_alg' }
+  const spec = ALG_SPEC[alg]
+  if (!spec) return { error: 'unsupported_alg' }
+
+  const payload = decodeJsonSegment<T & Record<string, unknown>>(payloadB64)
+  if (!payload) return { error: 'malformed' }
+
+  const signingInput = `${headerB64}.${payloadB64}`
+
+  // Decode signature once.
+  let sig: Buffer
+  try {
+    sig = Buffer.from(sigB64, 'base64url')
+  } catch {
+    return { error: 'malformed' }
+  }
+  if (sig.length === 0) return { error: 'malformed' }
+
+  // Filter keys by kid when both sides advertise one. This both narrows the
+  // candidate set (perf) and is required for JWKS — the resolver may have
+  // returned the entire keyset.
+  const headerKid = typeof header.kid === 'string' ? header.kid : null
+  const candidates = selectCandidates(keys, headerKid)
+  if (candidates.length === 0) {
+    // If the caller supplied kid-tagged keys but none matched, we know
+    // nothing will verify — surface this as a distinct (internal) reason
+    // so the logger can be precise. The wire still gets 'Invalid token'.
+    return { error: headerKid ? 'kid_unknown' : 'bad_signature' }
+  }
+
+  let signatureOk = false
+  for (const candidate of candidates) {
+    if (spec.family === 'hmac') {
+      if (hmacVerifies(spec.digest, candidate, signingInput, sig)) {
+        signatureOk = true
+        break
+      }
+    } else {
+      if (asymmetricVerifies(spec, candidate, signingInput, sig)) {
+        signatureOk = true
+        break
+      }
+    }
+  }
+  if (!signatureOk) return { error: 'bad_signature' }
+
+  // Temporal claims.
+  const now = (opts.nowSeconds ?? (() => Math.floor(Date.now() / 1000)))()
+  const skew = opts.clockSkewSeconds ?? 5
+  const claims = payload as Record<string, unknown>
+
+  if (typeof claims.exp === 'number') {
+    if (claims.exp <= now - skew) return { error: 'expired' }
+  }
+  if (typeof claims.nbf === 'number') {
+    if (claims.nbf > now + skew) return { error: 'not_yet_valid' }
+  }
+  if (typeof opts.maxAgeSeconds === 'number') {
+    if (typeof claims.iat !== 'number') return { error: 'too_old' }
+    if (claims.iat + opts.maxAgeSeconds <= now - skew) return { error: 'too_old' }
+  }
+  if (opts.audience !== undefined) {
+    if (!audienceMatches(claims.aud, opts.audience)) return { error: 'aud_mismatch' }
+  }
+  if (opts.issuer !== undefined) {
+    if (!issuerMatches(claims.iss, opts.issuer)) return { error: 'iss_mismatch' }
+  }
+
+  return { header, payload, raw: token }
+}
+
+/**
+ * Reduce the supplied key array to the set worth trying:
+ * - If `header.kid` is set, prefer entries whose `kid` matches. If at least
+ *   one tagged key matches, ONLY those are tried (no fallback to untagged
+ *   keys — an attacker shouldn't be able to coerce a kid-tagged JWKS into
+ *   trying an unrelated rotation key).
+ * - If `header.kid` is set but no tagged key matches, AND the array contains
+ *   untagged keys, try the untagged ones (legacy / single-key callers).
+ * - If `header.kid` is absent, try every entry's `key`.
+ */
+function selectCandidates(
+  keys: readonly (VerifyKeyMaterial | KidTaggedKey)[],
+  headerKid: string | null,
+): VerifyKeyMaterial[] {
+  if (headerKid) {
+    const matched: VerifyKeyMaterial[] = []
+    let sawAnyTagged = false
+    const untagged: VerifyKeyMaterial[] = []
+    for (const k of keys) {
+      if (isKidTagged(k)) {
+        sawAnyTagged = true
+        if (k.kid === headerKid) matched.push(k.key)
+      } else {
+        untagged.push(k)
+      }
+    }
+    if (matched.length > 0) return matched
+    // No tag match — fall back to untagged only when nothing was tagged at
+    // all (caller didn't intend kid routing). If they tagged some but the
+    // header.kid matches none, refuse.
+    if (sawAnyTagged) return []
+    return untagged
+  }
+
+  const out: VerifyKeyMaterial[] = []
+  for (const k of keys) {
+    if (isKidTagged(k)) out.push(k.key)
+    else out.push(k)
+  }
+  return out
+}
+
+function isKidTagged(k: VerifyKeyMaterial | KidTaggedKey): k is KidTaggedKey {
+  return (
+    typeof k === 'object' &&
+    k !== null &&
+    !Buffer.isBuffer(k) &&
+    'key' in (k as object) &&
+    'kid' in (k as object)
+  )
+}
+
+/** Internal helper — exported for tests that want a stable digest map. */
+export function digestFor(alg: JwtAlgorithm): string {
+  return ALG_SPEC[alg].digest
+}
+
+/** Internal helper — surface the alg family for tests / introspection. */
+export function familyFor(alg: JwtAlgorithm): AlgSpec['family'] {
+  return ALG_SPEC[alg].family
+}

package/src/middleware/compose.ts

@@ -0,0 +1,94 @@
+import type { IngeniumContext } from '../context/context.ts'
+import { reflectReturn } from '../response/reflect.ts'
+import type { ComposedHandler, IngeniumMiddleware } from './types.ts'
+
+const NOOP: ComposedHandler = async () => {}
+
+/**
+ * Compose an array of middleware into a single async function. Composition
+ * runs ONCE at registration / first-request time; the returned function has
+ * no per-request `bind`, no index variable, and no `stack[n]` lookups.
+ *
+ * The dispatcher chain is pre-built bottom-up: `dispatchers[i]` runs
+ * `stack[i]` with a `next` that invokes `dispatchers[i + 1]`. Each
+ * middleware-level invocation still allocates one closure to capture `ctx`
+ * (unavoidable without dropping concurrency safety).
+ *
+ * Double-`next()` calls are detected only when `process.env.REX_DEBUG` is
+ * truthy, to keep the production hot path free of per-call guard variables.
+ */
+export function compose(stack: readonly IngeniumMiddleware[]): ComposedHandler {
+  const len = stack.length
+  if (len === 0) return NOOP
+
+  const debug = !!process.env.REX_DEBUG
+
+  // dispatchers[i] runs middleware[i] and threads control through middleware[i+1..]
+  // dispatchers[len] is the terminal noop.
+  const dispatchers: ComposedHandler[] = new Array(len + 1)
+  dispatchers[len] = NOOP
+
+  for (let i = len - 1; i >= 0; i--) {
+    const fn = stack[i]!
+    const nextDispatcher = dispatchers[i + 1]!
+    if (debug) {
+      dispatchers[i] = async (ctx) => {
+        let called = false
+        await fn(ctx, () => {
+          if (called) {
+            throw new Error(`next() called multiple times in middleware at index ${i}`)
+          }
+          called = true
+          return nextDispatcher(ctx)
+        })
+      }
+    } else {
+      dispatchers[i] = async (ctx) => {
+        await fn(ctx, () => nextDispatcher(ctx))
+      }
+    }
+  }
+
+  return dispatchers[0] ?? NOOP
+}
+
+/**
+ * Compose middleware then append a terminal handler that does not receive a
+ * `next` (so a route handler can be the leaf of the chain). The handler's
+ * return value is reflected to the response per the contract in
+ * `response/reflect.ts` — unless the handler called a `ctx.json/...` helper,
+ * in which case the return value is ignored.
+ *
+ * Hot-path optimization: when there are no middleware, we skip the
+ * dispatcher chain entirely and return a thin wrapper that calls the
+ * handler directly. We also detect synchronous handler return values
+ * (non-thenable) and avoid the `await` microtask in that case — measurable
+ * on JSON-returning routes that don't touch the body.
+ */
+export function composeWithHandler(
+  middleware: readonly IngeniumMiddleware[],
+  handler: (ctx: IngeniumContext) => unknown | Promise<unknown>,
+): ComposedHandler {
+  if (middleware.length === 0) {
+    return makeFastTerminal(handler)
+  }
+  const terminal: IngeniumMiddleware = async (ctx) => {
+    const result = await handler(ctx)
+    reflectReturn(ctx, result)
+  }
+  return compose([...middleware, terminal])
+}
+
+/** No-middleware fast path: skip compose, skip await when handler is sync. */
+function makeFastTerminal(
+  handler: (ctx: IngeniumContext) => unknown | Promise<unknown>,
+): ComposedHandler {
+  return async (ctx) => {
+    const r = handler(ctx)
+    if (r !== null && typeof r === 'object' && typeof (r as Promise<unknown>).then === 'function') {
+      reflectReturn(ctx, await r)
+    } else {
+      reflectReturn(ctx, r)
+    }
+  }
+}

package/src/middleware/types.ts

@@ -0,0 +1,37 @@
+import type { IngeniumContext } from '../context/context.ts'
+
+/**
+ * A function that runs as part of the middleware chain. Call `next()` to
+ * continue to the next middleware; omit it to short-circuit.
+ *
+ * @example
+ * const logger: IngeniumMiddleware = async (ctx, next) => {
+ *   const start = Date.now()
+ *   await next()
+ *   ctx.logger?.info(`${ctx.method} ${ctx.path} ${Date.now() - start}ms`)
+ * }
+ */
+export type IngeniumMiddleware = (ctx: IngeniumContext, next: () => Promise<void>) => unknown | Promise<unknown>
+
+/**
+ * A composed middleware chain plus terminal handler. Returned by `compose()`.
+ * Internally cached on each trie leaf.
+ */
+export type ComposedHandler = (ctx: IngeniumContext) => Promise<void>
+
+/**
+ * A user-facing route handler. Its return value is reflected to the wire by
+ * the response-helper dispatcher (see `response/helpers.ts`):
+ *
+ * - `undefined` → 204 (unless `ctx.json/...` was already called)
+ * - `string`    → 200 text/plain (or text/html if it starts with `<`)
+ * - object      → 200 application/json
+ * - `Buffer`/`Uint8Array` → 200 application/octet-stream
+ * - `Readable`  → streamed response
+ *
+ * For full control, call `ctx.json/text/html/stream/redirect` and return
+ * `void` (or any value — return value is ignored once a helper has run).
+ */
+export type IngeniumHandler<Params = Record<string, string>> = (
+  ctx: IngeniumContext<Params>,
+) => unknown | Promise<unknown>

package/src/negotiation/accept.ts

@@ -0,0 +1,159 @@
+/**
+ * Pure parsers and matchers for HTTP `Accept`-family headers.
+ *
+ * Implemented from scratch — no `negotiator` / `accepts` runtime dep.
+ * Used by `negotiate.ts`, `format.ts`, and downstream context helpers.
+ *
+ * Spec references:
+ *   - RFC 9110 §12.5.1 (Accept), §12.5.2 (Accept-Charset),
+ *     §12.5.4 (Accept-Encoding), §12.5.5 (Accept-Language).
+ */
+
+/** A single parsed media-range entry from an `Accept` header. */
+export interface ParsedAccept {
+  /** The full media-range string (lowercased), e.g. `text/html`, `text/\*`, `\*\/\*`. */
+  type: string
+  /** Quality factor from `;q=N`, default `1`. Out-of-range values are clamped. */
+  quality: number
+  /** Any other extension parameters (e.g. `level=1`). */
+  params: Record<string, string>
+}
+
+/**
+ * Express `accepts`-style shorthand → canonical media type.
+ * Kept intentionally tiny — covers the 99% case for body responses.
+ */
+const SHORTHAND: Readonly<Record<string, string>> = {
+  json: 'application/json',
+  html: 'text/html',
+  text: 'text/plain',
+  xml: 'application/xml',
+  form: 'application/x-www-form-urlencoded',
+  multipart: 'multipart/form-data',
+  csv: 'text/csv',
+  'octet-stream': 'application/octet-stream',
+}
+
+/** Resolve a shorthand (`'json'`) to its canonical mime, or pass through. */
+export function expandShorthand(token: string): string {
+  const lower = token.toLowerCase()
+  return SHORTHAND[lower] ?? lower
+}
+
+/**
+ * Parse a comma-separated `Accept`-family header into a list of entries.
+ * Empty / undefined input returns an empty array. Malformed entries are
+ * silently dropped (lenient parsing — same as Express).
+ *
+ * Result is **not** sorted; pass to `sortByPreference` if you need ordering.
+ */
+export function parseAcceptHeader(header: string | undefined): ParsedAccept[] {
+  if (!header) return []
+  const out: ParsedAccept[] = []
+  // Split on commas. Header values don't allow quoted commas in this set,
+  // so a plain split is safe.
+  const parts = header.split(',')
+  for (const raw of parts) {
+    const trimmed = raw.trim()
+    if (trimmed.length === 0) continue
+    const segments = trimmed.split(';')
+    const typeSeg = segments[0]?.trim().toLowerCase()
+    if (!typeSeg) continue
+    let quality = 1
+    const params: Record<string, string> = {}
+    for (let i = 1; i < segments.length; i++) {
+      const seg = segments[i]?.trim()
+      if (!seg) continue
+      const eq = seg.indexOf('=')
+      if (eq === -1) continue
+      const key = seg.slice(0, eq).trim().toLowerCase()
+      let value = seg.slice(eq + 1).trim()
+      // Strip surrounding quotes if present.
+      if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+        value = value.slice(1, value.length - 1)
+      }
+      if (key === 'q') {
+        const q = Number(value)
+        quality = Number.isFinite(q) ? Math.max(0, Math.min(1, q)) : 0
+      } else {
+        params[key] = value
+      }
+    }
+    out.push({ type: typeSeg, quality, params })
+  }
+  return out
+}
+
+/**
+ * Specificity score for a media-range. Higher is more specific.
+ *   `*​/*`        → 0
+ *   `type/*`     → 1
+ *   `type/sub`   → 2 (+ #params for tie-breaking)
+ */
+function specificity(entry: ParsedAccept): number {
+  if (entry.type === '*/*' || entry.type === '*') return 0
+  if (entry.type.endsWith('/*')) return 1
+  return 2 + Object.keys(entry.params).length
+}
+
+/**
+ * Stable sort by RFC preference: highest q first, then most-specific first.
+ * Returns a NEW array; does not mutate input.
+ */
+export function sortByPreference(entries: readonly ParsedAccept[]): ParsedAccept[] {
+  return [...entries]
+    .map((e, i) => ({ e, i }))
+    .sort((a, b) => {
+      if (b.e.quality !== a.e.quality) return b.e.quality - a.e.quality
+      const sb = specificity(b.e)
+      const sa = specificity(a.e)
+      if (sb !== sa) return sb - sa
+      return a.i - b.i // stable
+    })
+    .map((x) => x.e)
+}
+
+/** Does an offered concrete type match a parsed Accept entry (incl. wildcards)? */
+function entryMatches(entry: ParsedAccept, offered: string): boolean {
+  const offeredLower = offered.toLowerCase()
+  if (entry.type === '*/*' || entry.type === '*') return true
+  if (entry.type === offeredLower) return true
+  if (entry.type.endsWith('/*')) {
+    const prefix = entry.type.slice(0, -1) // keep trailing slash
+    return offeredLower.startsWith(prefix)
+  }
+  return false
+}
+
+/**
+ * Return the best match for `offered` against `acceptHeader`, or `false`.
+ *
+ * Matching algorithm:
+ *   1. If `acceptHeader` is missing/empty → first offered wins (Express behavior).
+ *   2. Walk parsed entries sorted by quality + specificity.
+ *   3. For each entry (in preference order), pick the first offered that matches.
+ *      Among ties at the same Accept entry, the offered's listed order wins.
+ *   4. Entries with `q=0` reject — never match.
+ */
+export function selectBest(
+  acceptHeader: string | undefined,
+  offered: readonly string[],
+): string | false {
+  if (offered.length === 0) return false
+  const expanded = offered.map(expandShorthand)
+  if (!acceptHeader || acceptHeader.trim() === '') {
+    return offered[0] ?? false
+  }
+  const sorted = sortByPreference(parseAcceptHeader(acceptHeader))
+  if (sorted.length === 0) return offered[0] ?? false
+
+  for (const entry of sorted) {
+    if (entry.quality === 0) continue
+    for (let i = 0; i < expanded.length; i++) {
+      if (entryMatches(entry, expanded[i] as string)) {
+        return offered[i] as string
+      }
+    }
+  }
+  return false
+}

package/src/negotiation/etag.ts

@@ -0,0 +1,30 @@
+/**
+ * `computeEtag(body, weak?)` — sha1-based entity tag for response bodies.
+ *
+ * Format: `W/"<sha1-base64-without-padding>"` (weak) or `"<sha1-base64-without-padding>"`.
+ * Weak is the default — fine for JSON where serialization may legitimately vary
+ * (key order, whitespace) without representing a different resource.
+ *
+ * The empty-body ETag is special-cased to a fixed constant so two empty
+ * bodies always compare equal without pumping through the hash.
+ */
+
+import { createHash } from 'node:crypto'
+import { Buffer } from 'node:buffer'
+
+/** Pre-computed sha1("") base64 → `2jmj7l5rSw0yVb/vlWAYkK/YBwk=`. */
+const EMPTY_HASH = '2jmj7l5rSw0yVb/vlWAYkK/YBwk='
+
+/**
+ * Compute an ETag for the given body. Strings are treated as UTF-8.
+ * @param body  Response body — usually `JSON.stringify(...)` or a `Buffer`.
+ * @param weak  Prefix the tag with `W/`. Defaults to `true` for JSON safety.
+ */
+export function computeEtag(body: string | Buffer, weak = true): string {
+  const len = typeof body === 'string' ? Buffer.byteLength(body, 'utf8') : body.length
+  if (len === 0) return weak ? `W/"${EMPTY_HASH}"` : `"${EMPTY_HASH}"`
+  const hash = createHash('sha1').update(body as Buffer | string).digest('base64')
+  // Trim trailing `=` padding for compactness — keeps tag URL-safe-ish and shorter.
+  const trimmed = hash.replace(/=+$/g, '')
+  return weak ? `W/"${trimmed}"` : `"${trimmed}"`
+}