ingenium 0.0.1 → 0.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ingenium",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Express DX, Hono/Fastify throughput. A Node.js HTTP framework.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -13,7 +13,12 @@
       "require": "./dist/index.cjs"
     }
   },
-  "files": ["dist", "src", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
@@ -22,22 +27,32 @@
   "engines": {
     "node": ">=20.0.0"
   },
-  "keywords": ["http", "express", "framework", "router", "fast"],
+  "keywords": [
+    "http",
+    "express",
+    "framework",
+    "router",
+    "fast"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Contra-Collective/ingenium.git",
+    "url": "git+https://github.com/IngeniumFramework/Ingenium.git",
     "directory": "packages/ingenium"
   },
-  "homepage": "https://github.com/Contra-Collective/ingenium#readme",
-  "bugs": "https://github.com/Contra-Collective/ingenium/issues",
+  "homepage": "https://github.com/IngeniumFramework/Ingenium#readme",
+  "bugs": "https://github.com/IngeniumFramework/Ingenium/issues",
   "peerDependencies": {
     "zod": "^3.23.0",
     "ws": "^8.18.0"
   },
   "peerDependenciesMeta": {
-    "zod": { "optional": true },
-    "ws": { "optional": true }
+    "zod": {
+      "optional": true
+    },
+    "ws": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "zod": "^3.23.0",

package/src/app.ts

@@ -1041,8 +1041,14 @@ export class IngeniumApp implements PluginTarget {
       throw miss
     }
     const applicable: IngeniumMiddleware[] = [...flat.globalMiddleware]
+    // Collapse runs of '/' before the prefix check so a non-normalized request
+    // path (e.g. `//admin/x`) can't slip past a deny-by-default / audit / security
+    // gate scoped to `/admin`: `pathStartsWith('//admin/x', '/admin')` is false.
+    // Matched routes bake their chain at compose time, so this only matters on the
+    // trie-miss fallback. Local-only — ctx.path is left untouched.
+    const normalizedPath = ctx.path.includes('//') ? ctx.path.replace(/\/{2,}/g, '/') : ctx.path
     for (const scoped of flat.scopedMiddleware) {
-      if (pathStartsWith(ctx.path, scoped.prefix)) applicable.push(scoped.mw)
+      if (pathStartsWith(normalizedPath, scoped.prefix)) applicable.push(scoped.mw)
     }
     if (applicable.length === 0) {
       throw miss

package/src/body/multipart.ts

@@ -165,7 +165,15 @@ export function parseMultipart(
   const allowed = opts.allowedMimePrefixes
 
   const boundary = extractBoundary(contentType)
-  const result: MultipartResult = { fields: {}, files: {} }
+  // Use null-prototype maps so an attacker-chosen part name (`__proto__`,
+  // `constructor`, `prototype`) is stored as plain own-data instead of tripping
+  // the `__proto__` setter — which would otherwise reparent the maps' prototype
+  // and corrupt the membership/lookup logic in `appendField`. Mirrors the query
+  // parser's `toShallowArrayObject` in context.ts.
+  const result: MultipartResult = {
+    fields: Object.create(null),
+    files: Object.create(null),
+  }
 
   // Empty body → empty result. (No boundary delimiter at all.)
   if (buffer.length === 0) return result

package/src/cors/middleware.ts

@@ -1,6 +1,9 @@
 import type { IngeniumMiddleware } from '../middleware/types.ts'
 import type { IngeniumContext } from '../context/context.ts'
 import type { CorsOptions, CorsOrigin } from './types.ts'
+import { IngeniumError } from '../errors.ts'
+
+const IS_DEV = process.env.NODE_ENV !== 'production'
 
 const DEFAULT_METHODS: readonly string[] = [
   'GET',
@@ -52,7 +55,16 @@ async function resolveOrigin(
     return { value: null, reflected: false }
   }
 
-  if (spec === true) return { value: reqOrigin, reflected: true }
+  // `origin: true` reflects whatever the request sends — except the literal
+  // string "null". Browsers send `Origin: null` for sandboxed iframes, `file://`
+  // pages, and redirected/data-URL contexts; reflecting it back hands those
+  // untrusted, un-attributable contexts a same-origin-equivalent grant. It is
+  // only honoured when an explicit allowlist array opts into it (handled below).
+  if (spec === true) {
+    return reqOrigin === 'null'
+      ? { value: null, reflected: true }
+      : { value: reqOrigin, reflected: true }
+  }
 
   if (typeof spec === 'string') {
     return spec === reqOrigin
@@ -107,12 +119,55 @@ export function corsMiddleware(opts: CorsOptions = {}): IngeniumMiddleware {
   // Construction-time validation: `credentials: true` + wildcard origin is
   // forbidden by the CORS spec — browsers reject the response.
   if (credentials && origin === '*') {
-    throw new Error(
+    throw new IngeniumError(
+      500,
+      'CORS_CREDENTIALS_WILDCARD',
       "ingenium.cors: `credentials: true` is incompatible with `origin: '*'`. " +
         'Specify an explicit origin (string, array, regex, or function) instead.',
     )
   }
 
+  // `credentials: true` + `origin: true` reflects *any* request Origin while
+  // setting `Access-Control-Allow-Credentials: true`. That is the classic
+  // credentialed-reflection vulnerability: any website can read authenticated
+  // responses. Unlike `origin: '*'` the browser does NOT reject this, so we must
+  // reject it ourselves at construction rather than silently shipping it.
+  if (credentials && origin === true) {
+    throw new IngeniumError(
+      500,
+      'CORS_CREDENTIALS_WILDCARD',
+      'ingenium.cors: `credentials: true` is incompatible with `origin: true` ' +
+        '(reflecting any Origin with credentials lets any site read authenticated ' +
+        'responses). Specify an explicit allowlist (string, array, regex, or function).',
+    )
+  }
+
+  // A function or RegExp origin combined with credentials can still reflect an
+  // untrusted Origin if the predicate is too permissive. We can't statically
+  // prove the predicate is safe, so warn (dev only) instead of throwing.
+  if (
+    IS_DEV &&
+    credentials &&
+    (typeof origin === 'function' || origin instanceof RegExp)
+  ) {
+    try {
+      process.emitWarning(
+        'ingenium.cors: `credentials: true` with a function/RegExp origin reflects ' +
+          'the request Origin when the predicate matches. Ensure it never matches ' +
+          'untrusted origins, or you expose authenticated responses to them.',
+        { code: 'INGENIUM_CORS_CREDENTIALS_REFLECT' },
+      )
+    } catch {
+      // Worker runtimes can throw on emitWarning; diagnostics are best-effort.
+    }
+  }
+
+  // A function origin can return '*' for some requests and a specific origin
+  // for others. Without `Vary: Origin` a shared cache could serve one caller's
+  // allowed-origin response to a different origin (cache poisoning), so we force
+  // the header on every response when the origin is computed per-request.
+  const originIsFunction = typeof origin === 'function'
+
   const methodsHeader = methods.join(',')
   const exposedHeader = exposedHeaders && exposedHeaders.length > 0
     ? exposedHeaders.join(',')
@@ -132,7 +187,7 @@ export function corsMiddleware(opts: CorsOptions = {}): IngeniumMiddleware {
       ctx,
     )
 
-    if (reflected) appendVary(ctx, 'Origin')
+    if (reflected || originIsFunction) appendVary(ctx, 'Origin')
 
     if (allowOrigin !== null) {
       ctx.set('access-control-allow-origin', allowOrigin)

package/src/cors/types.ts

@@ -20,7 +20,9 @@ export type CorsOriginFn = (
 /**
  * Spec for the `origin` option.
  *
- * - `boolean` — `true` reflects any request `Origin`; `false` disables CORS.
+ * - `boolean` — `true` reflects any request `Origin` (but never the literal
+ *   `"null"`, and rejected at construction when `credentials: true`); `false`
+ *   disables CORS.
  * - `'*'` — wildcard: `Access-Control-Allow-Origin: *`.
  * - any other `string` — exact match against the request's `Origin`.
  * - `string[]` — allowlist; matched exactly.
@@ -62,8 +64,9 @@ export interface CorsOptions {
 
   /**
    * If `true`, sets `Access-Control-Allow-Credentials: true`.
-   * Incompatible with `origin: '*'` — throws at construction time.
-   * Default: `false`.
+   * Incompatible with `origin: '*'` and `origin: true` — both throw at
+   * construction time, because reflecting credentials to an unrestricted set of
+   * origins lets any site read authenticated responses. Default: `false`.
    */
   credentials?: boolean
 

package/src/csrf/middleware.ts

@@ -1,6 +1,6 @@
 import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
 import { Buffer } from 'node:buffer'
-import { IngeniumError } from '../errors.ts'
+import { IngeniumError, IngeniumHeaderInjectionError } 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'
@@ -12,6 +12,11 @@ export class IngeniumCsrfError extends IngeniumError {
   }
 }
 
+const IS_DEV = process.env.NODE_ENV !== 'production'
+
+/** CR/LF detector — config-supplied cookie attributes must not inject headers. */
+const CRLF_RE = /[\r\n]/
+
 const TOKEN_BYTES = 18
 const SAFE_METHODS_DEFAULT: readonly string[] = ['GET', 'HEAD', 'OPTIONS', 'TRACE']
 const COOKIE_NAME_DEFAULT = 'ingenium.csrf'
@@ -24,6 +29,7 @@ interface ResolvedOptions {
   ignoreMethods: Set<string>
   value: CsrfValueReader
   skip: ((ctx: IngeniumContext) => boolean | Promise<boolean>) | null
+  sessionBinding: ((ctx: IngeniumContext) => string | undefined) | null
 }
 
 /**
@@ -55,11 +61,34 @@ export function csrfMiddleware(opts: CsrfOptions = {}): IngeniumMiddleware {
       return
     }
 
+    // Per-session binding (cookie mode only). When present, the token's
+    // signature covers this value so a token minted for one session can't be
+    // replayed against another. `undefined` falls back to plain double-submit.
+    const binding =
+      resolved.storage === 'cookie' && resolved.sessionBinding
+        ? resolved.sessionBinding(ctx)
+        : undefined
+    if (
+      IS_DEV &&
+      resolved.storage === 'cookie' &&
+      resolved.secrets.length > 0 &&
+      binding === undefined
+    ) {
+      try {
+        process.emitWarning(
+          'csrfMiddleware: cookie-mode token has no session binding. Double-submit without binding assumes no XSS and a strict SameSite cookie — any token the server mints is globally valid. Provide `sessionBinding` to tie the token to a session/user.',
+          { type: 'IngeniumCsrfUnboundTokenWarning' },
+        )
+      } catch {
+        // process.emitWarning can throw in unusual runtimes (workers); swallow.
+      }
+    }
+
     // Resolve / mint the expected token for this request.
-    let expected = readExpectedToken(ctx, resolved)
+    let expected = readExpectedToken(ctx, resolved, binding)
     let mintedThisRequest = false
     if (!expected) {
-      expected = mintToken(resolved)
+      expected = mintToken(resolved, binding)
       mintedThisRequest = true
     }
 
@@ -88,16 +117,26 @@ export function csrfMiddleware(opts: CsrfOptions = {}): IngeniumMiddleware {
 
 // ───── Token mint / verify ─────────────────────────────────────────────────
 
-function mintToken(opts: ResolvedOptions): string {
+function mintToken(opts: ResolvedOptions, binding: string | undefined): 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]!)
+  // When a binding is present it's folded into the signature so the token is
+  // only valid for the session/user it was minted for.
+  const sig = signToken(raw, opts.secrets[0]!, binding)
   return `${raw}.${sig}`
 }
 
-function signToken(raw: string, secret: string): string {
-  return createHmac('sha256', secret).update(raw).digest('base64url')
+/**
+ * HMAC the token body. The binding (when present) is mixed into the signed
+ * message so the same `raw` value produces a different signature per session —
+ * a token can't be lifted from one user's cookie and replayed by another.
+ * The binding is never stored in the token; it's re-derived from the request
+ * at verify time, so it doesn't leak the session id to the client.
+ */
+function signToken(raw: string, secret: string, binding?: string | undefined): string {
+  const message = binding === undefined ? raw : `${raw}.${binding}`
+  return createHmac('sha256', secret).update(message).digest('base64url')
 }
 
 function tokenMatches(submitted: string, expected: string): boolean {
@@ -108,13 +147,17 @@ function tokenMatches(submitted: string, expected: string): boolean {
   return timingSafeEqual(a, b)
 }
 
-function verifySignedToken(token: string, secrets: readonly string[]): boolean {
+function verifySignedToken(
+  token: string,
+  secrets: readonly string[],
+  binding: string | undefined,
+): 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)
+    const expected = signToken(raw, secret, binding)
     if (expected.length !== sig.length) continue
     if (timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) return true
   }
@@ -123,12 +166,19 @@ function verifySignedToken(token: string, secrets: readonly string[]): boolean {
 
 // ───── Storage ─────────────────────────────────────────────────────────────
 
-function readExpectedToken(ctx: IngeniumContext, opts: ResolvedOptions): string | null {
+function readExpectedToken(
+  ctx: IngeniumContext,
+  opts: ResolvedOptions,
+  binding: string | undefined,
+): 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
+    // Verify against the current request's binding: a token signed for another
+    // session won't match this request's binding and is rejected here, forcing
+    // a fresh mint rather than silently trusting a cross-session token.
+    if (opts.secrets.length > 0 && !verifySignedToken(token, opts.secrets, binding)) return null
     return token
   }
   // Session storage
@@ -161,6 +211,13 @@ function writeSession(ctx: IngeniumContext, token: string): void {
 }
 
 function appendSetCookie(ctx: IngeniumContext, value: string): void {
+  // This write goes straight to the header bag, bypassing ctx.set's guard, so
+  // re-assert the same CR/LF check here on the fully-composed value.
+  if (CRLF_RE.test(value)) {
+    throw new IngeniumHeaderInjectionError(
+      'csrfMiddleware: Set-Cookie value contains CR/LF (possible header injection)',
+    )
+  }
   const existing = ctx._headers['set-cookie']
   if (!existing) {
     ctx._headers['set-cookie'] = [value]
@@ -205,13 +262,41 @@ function resolveOptions(opts: CsrfOptions): ResolvedOptions {
     path: opts.cookie?.path ?? '/',
     domain: opts.cookie?.domain ?? '',
     sameSite: opts.cookie?.sameSite ?? 'lax',
-    secure: opts.cookie?.secure ?? false,
+    // Secure-by-default: a plaintext CSRF cookie is readable by a network
+    // attacker, who can then forge the double-submit header.
+    secure: opts.cookie?.secure ?? true,
     httpOnly: opts.cookie?.httpOnly ?? false,
     maxAgeSeconds: opts.cookie?.maxAgeSeconds ?? 7 * 24 * 60 * 60,
   }
+  // Config-supplied cookie attributes are interpolated raw into Set-Cookie;
+  // reject CR/LF here so they can't bypass the framework's header-injection
+  // guard (which the rest of the framework enforces via ctx.set).
+  if (CRLF_RE.test(cookie.path) || CRLF_RE.test(cookie.domain) || CRLF_RE.test(cookie.name)) {
+    throw new IngeniumHeaderInjectionError(
+      'csrfMiddleware: cookie name/path/domain contains CR/LF (possible header injection)',
+    )
+  }
+  if (storage === 'cookie' && cookie.secure === false && IS_DEV) {
+    try {
+      process.emitWarning(
+        'csrfMiddleware: CSRF cookie issued with Secure=false — the token is sent over plaintext HTTP and can be read by a network attacker. Only disable Secure for local HTTP development.',
+        { type: 'IngeniumCsrfInsecureCookieWarning' },
+      )
+    } catch {
+      // process.emitWarning can throw in unusual runtimes (workers); swallow.
+    }
+  }
   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 }
+  return {
+    secrets,
+    storage,
+    cookie,
+    ignoreMethods,
+    value,
+    skip: opts.skip ?? null,
+    sessionBinding: opts.sessionBinding ?? null,
+  }
 }
 
 const defaultValueReader: CsrfValueReader = (ctx) => {

package/src/csrf/types.ts

@@ -24,7 +24,12 @@ export interface CsrfCookieOptions {
   domain?: string
   /** SameSite policy. Default `'lax'`. */
   sameSite?: 'lax' | 'strict' | 'none'
-  /** Mark cookie Secure. Default `false`; set `true` behind TLS. */
+  /**
+   * Mark cookie Secure. **Default `true`** so the CSRF cookie is never sent
+   * over plaintext HTTP where a network attacker could read it and forge the
+   * double-submit header. Override to `false` only for local HTTP development;
+   * doing so emits a dev-mode warning.
+   */
   secure?: boolean
   /**
    * Mark cookie HttpOnly. **Default `false`** — clients must read the cookie
@@ -48,6 +53,22 @@ export interface CsrfOptions {
   storage?: CsrfStorage
   /** Cookie options when `storage === 'cookie'`. */
   cookie?: CsrfCookieOptions
+  /**
+   * Bind a cookie-mode token to a per-session/per-user identifier (e.g. a
+   * session id or authenticated user id derived from `ctx`).
+   *
+   * Without binding, a signed double-submit token is only proven to have been
+   * minted by *this server* — any token the server ever issued is globally
+   * valid for any user, so a leaked or shared token defeats the protection.
+   * When this returns a stable value, the token is HMAC'd over
+   * `raw + '.' + binding` and the binding is re-verified on unsafe requests,
+   * so a token minted for one session cannot be replayed against another.
+   *
+   * Returning `undefined` (e.g. before login) falls back to plain
+   * double-submit and emits a dev-mode warning. Has no effect in session
+   * storage mode, where the session id already authenticates the binding.
+   */
+  sessionBinding?: (ctx: IngeniumContext) => string | undefined
   /** Methods that bypass validation. Default `['GET', 'HEAD', 'OPTIONS', 'TRACE']`. */
   ignoreMethods?: readonly string[]
   /**

package/src/idempotency/middleware.ts

@@ -9,6 +9,12 @@ import type {
   ResolvedIdempotencyOptions,
 } from './types.ts'
 
+/**
+ * Module-scope so V8 dead-code-eliminates the `if (IS_DEV)` diagnostic
+ * bodies in production builds. Read once at load — never per request.
+ */
+const IS_DEV = process.env.NODE_ENV !== 'production'
+
 const DEFAULT_METHODS: readonly HttpMethod[] = ['POST', 'PATCH', 'DELETE']
 
 /**
@@ -17,14 +23,46 @@ const DEFAULT_METHODS: readonly HttpMethod[] = ['POST', 'PATCH', 'DELETE']
  */
 const DEFAULT_CACHEABLE = (status: number): boolean => status >= 200 && status < 500
 
-/** Authorization-header-derived scope; falls back to `'anon'`. */
-function defaultScope(ctx: IngeniumContext): string {
+/**
+ * Sentinel returned by `defaultScope` for an unauthenticated request. A
+ * unique symbol (not the string `'anon'`) so the middleware can reliably
+ * distinguish "the framework couldn't isolate this client" from any string
+ * a user-supplied scope function might legitimately return. We must NOT
+ * cache across anonymous clients: the cache key is
+ * `<scope>:<method>:<path>:<key>`, so collapsing every anonymous caller to
+ * one constant lets client B reuse client A's idempotency key on the same
+ * route and be served A's full cached response — body AND Set-Cookie. IP
+ * is not a safe discriminator (shared NAT / spoofable), so we bypass.
+ */
+const ANON_SCOPE = Symbol('ingenium.idempotency.anon')
+
+/**
+ * Authorization-header-derived scope. Returns the `ANON_SCOPE` sentinel
+ * (not a string) when there is no Authorization header so the caller can
+ * detect the un-isolatable case and skip caching entirely.
+ */
+function defaultScope(ctx: IngeniumContext): string | typeof ANON_SCOPE {
   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'
+  return ANON_SCOPE
 }
 
+/**
+ * Response headers that carry per-client secrets/session state and must
+ * NEVER be replayed from a cached entry onto a different request. Even with
+ * correct scoping these are dangerous to copy verbatim; stripping them is
+ * defense-in-depth so a misconfigured scope can't leak another client's
+ * session cookie or bearer credential.
+ */
+const SENSITIVE_REPLAY_HEADERS: readonly string[] = [
+  'set-cookie',
+  'authorization',
+  'proxy-authorization',
+  'www-authenticate',
+  'proxy-authenticate',
+]
+
 /** 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]
@@ -76,6 +114,9 @@ function replay(ctx: IngeniumContext, cached: CachedResponse): void {
   for (const k of Object.keys(cached.headers)) {
     const v = cached.headers[k]
     if (v === undefined) continue
+    // Never replay per-client secrets onto a different request — a cached
+    // Set-Cookie / Authorization would hand one client another's session.
+    if (SENSITIVE_REPLAY_HEADERS.includes(k.toLowerCase())) continue
     ctx._headers[k] = Array.isArray(v) ? [...v] : v
   }
   ctx._headers['idempotent-replayed'] = 'true'
@@ -118,11 +159,17 @@ function replay(ctx: IngeniumContext, cached: CachedResponse): void {
  *   }))
  */
 export function idempotencyMiddleware(opts: IdempotencyOptions = {}): IngeniumMiddleware {
+  // When the user supplies their own scope function we trust it to isolate
+  // clients and never bypass. Only the built-in `defaultScope` can yield the
+  // un-isolatable anonymous sentinel, so we capture whether it's in play.
+  const usingDefaultScope = opts.scope === undefined
+  const scopeFn: (ctx: IngeniumContext) => string | typeof ANON_SCOPE = opts.scope ?? defaultScope
+
   const resolved: ResolvedIdempotencyOptions = {
     header: (opts.header ?? 'Idempotency-Key').toLowerCase(),
     store: opts.store ?? new IdempotencyMemoryStore(),
     ttlMs: (opts.ttlSeconds ?? 86_400) * 1000,
-    scope: opts.scope ?? defaultScope,
+    scope: scopeFn as (ctx: IngeniumContext) => string,
     methodSet: new Set(opts.methods ?? DEFAULT_METHODS),
     cacheable: opts.cacheable ?? DEFAULT_CACHEABLE,
   }
@@ -131,6 +178,10 @@ export function idempotencyMiddleware(opts: IdempotencyOptions = {}): IngeniumMi
     throw new Error('idempotency: ttlSeconds must be > 0')
   }
 
+  // Warn at most once per process — the bypass is correct but the developer
+  // almost certainly wants an explicit `scope` for unauthenticated routes.
+  let anonBypassWarned = false
+
   // 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).
@@ -146,7 +197,29 @@ export function idempotencyMiddleware(opts: IdempotencyOptions = {}): IngeniumMi
       return next()
     }
 
-    const scope = resolved.scope(ctx)
+    const scope = scopeFn(ctx)
+
+    // Anonymous + default scope: there is no per-client discriminator, so
+    // caching here would serve one client's response (body + Set-Cookie) to
+    // another that happens to reuse the same Idempotency-Key on this route.
+    // Bypass entirely — run the handler without replay/store. (Only the
+    // built-in defaultScope can produce ANON_SCOPE; an explicit user scope
+    // never reaches this branch and keeps its prior behavior.)
+    if (scope === ANON_SCOPE) {
+      if (IS_DEV && usingDefaultScope && !anonBypassWarned) {
+        anonBypassWarned = true
+        try {
+          process.emitWarning(
+            'idempotency: request to a cacheable route has no Authorization header, so the default scope cannot isolate clients. Idempotency caching was bypassed for this request to avoid serving one client the cached response of another. Supply an explicit `scope` function for unauthenticated endpoints.',
+            { type: 'IngeniumIdempotencyWarning' },
+          )
+        } catch {
+          // process.emitWarning can throw in unusual runtimes (workers); swallow.
+        }
+      }
+      return next()
+    }
+
     const cacheKey = `${scope}:${ctx.method}:${ctx.path}:${headerValue}`
 
     // 1. Persisted cache hit?

package/src/index.ts

@@ -155,7 +155,7 @@ export type {
 } from './idempotency/types.ts'
 
 // ───── JWT middleware ──────────────────────────────────────────────────────
-export { jwtMiddleware } from './jwt/middleware.ts'
+export { jwtMiddleware, IngeniumJwtKeyAlgMismatchError } from './jwt/middleware.ts'
 export { verifyJwt } from './jwt/verify.ts'
 export { fetchJwks, clearJwksCache } from './jwt/jwks.ts'
 export type {