ingenium 0.0.1

package/src/jwt/jwks.ts

@@ -0,0 +1,143 @@
+import { createPublicKey, type KeyObject } from 'node:crypto'
+
+/**
+ * In-memory JWKS cache.
+ *
+ * One entry per URL. Each entry holds the parsed `Map<kid, KeyObject>` and
+ * the absolute timestamp at which it expires. A `pending` promise is stored
+ * alongside so concurrent callers for the same URL share a single in-flight
+ * fetch — we never stampede the upstream IdP.
+ */
+interface CacheEntry {
+  keys: Map<string, KeyObject>
+  expiresAt: number
+  pending: Promise<Map<string, KeyObject>> | null
+}
+
+const cache = new Map<string, CacheEntry>()
+
+/** JWK shape we accept. We tolerate extra fields and ignore unsupported `kty`. */
+interface Jwk {
+  kty?: string
+  kid?: string
+  use?: string
+  alg?: string
+  n?: string
+  e?: string
+  crv?: string
+  x?: string
+  y?: string
+  // RSA private parts / EC `d` are intentionally ignored — verifier-only.
+  [k: string]: unknown
+}
+
+interface JwksResponse {
+  keys?: Jwk[]
+}
+
+/**
+ * Fetch + cache a JWKS. Returns a `Map<kid, KeyObject>`.
+ *
+ * Concurrency: if a fetch is already in flight for `url` we await the same
+ * promise, ensuring a thundering-herd of requests collapses to one upstream
+ * call. After the fetch resolves, all waiters get the same keys.
+ *
+ * Failure mode: any thrown error (network, JSON parse, malformed JWK, empty
+ * keyset) bubbles as a generic `Error('jwks_fetch_failed')` — the caller is
+ * responsible for translating to a wire-safe `IngeniumUnauthorizedError`. We
+ * deliberately do NOT serve a stale cache on failure: stale public keys can
+ * mean accepting tokens that the IdP has rotated away from.
+ */
+export async function fetchJwks(url: string, ttlMs: number): Promise<Map<string, KeyObject>> {
+  const now = Date.now()
+  const entry = cache.get(url)
+
+  // Fresh cache hit — return synchronously-resolved map.
+  if (entry && entry.expiresAt > now && !entry.pending) {
+    return entry.keys
+  }
+
+  // In-flight coalescing: another caller already triggered the fetch.
+  if (entry?.pending) {
+    return entry.pending
+  }
+
+  const pending = doFetch(url).then(
+    (keys) => {
+      cache.set(url, { keys, expiresAt: Date.now() + ttlMs, pending: null })
+      return keys
+    },
+    (err) => {
+      // Drop the failed entry so the next caller retries (instead of being
+      // pinned to a rejected promise forever).
+      cache.delete(url)
+      throw err
+    },
+  )
+
+  // Park the in-flight promise so concurrent callers within this tick share it.
+  // Preserve the existing `keys` map so reads during refresh have something
+  // to fall back on if needed (currently unused — we always await `pending`).
+  cache.set(url, {
+    keys: entry?.keys ?? new Map(),
+    expiresAt: entry?.expiresAt ?? 0,
+    pending,
+  })
+
+  return pending
+}
+
+/** Reset the in-process cache. Tests use this; production code shouldn't need it. */
+export function clearJwksCache(): void {
+  cache.clear()
+}
+
+async function doFetch(url: string): Promise<Map<string, KeyObject>> {
+  let res: Response
+  try {
+    res = await fetch(url)
+  } catch {
+    throw new Error('jwks_fetch_failed')
+  }
+  if (!res.ok) throw new Error('jwks_fetch_failed')
+
+  let body: unknown
+  try {
+    body = await res.json()
+  } catch {
+    throw new Error('jwks_fetch_failed')
+  }
+
+  if (!body || typeof body !== 'object') throw new Error('jwks_fetch_failed')
+  const jwks = body as JwksResponse
+  if (!Array.isArray(jwks.keys) || jwks.keys.length === 0) {
+    throw new Error('jwks_fetch_failed')
+  }
+
+  const out = new Map<string, KeyObject>()
+  for (const jwk of jwks.keys) {
+    if (!jwk || typeof jwk !== 'object') continue
+    if (typeof jwk.kid !== 'string' || jwk.kid.length === 0) continue
+    if (jwk.kty !== 'RSA' && jwk.kty !== 'EC') continue
+    // EC: only accept the JWT-spec curves. P-521 (note: 521, not 512) is
+    // the curve name JOSE uses for ES512 — yes, the off-by-one is in the spec.
+    if (jwk.kty === 'EC' && jwk.crv !== 'P-256' && jwk.crv !== 'P-384' && jwk.crv !== 'P-521') {
+      continue
+    }
+    try {
+      // node:crypto accepts JWK directly when format is 'jwk'. For RSA it
+      // needs `n` + `e`; for EC it needs `crv` + `x` + `y`. Private fields
+      // are ignored when we createPublicKey.
+      const key = createPublicKey({ key: jwk as never, format: 'jwk' })
+      out.set(jwk.kid, key)
+    } catch {
+      // Skip individual bad keys rather than failing the whole keyset —
+      // an IdP rolling a new (broken) key shouldn't blow up verification of
+      // tokens signed with the still-valid old keys.
+      continue
+    }
+  }
+
+  if (out.size === 0) throw new Error('jwks_fetch_failed')
+  return out
+}

package/src/jwt/middleware.ts

@@ -0,0 +1,313 @@
+import { Buffer } from 'node:buffer'
+import type { KeyObject } from 'node:crypto'
+import { IngeniumUnauthorizedError } from '../errors.ts'
+import type { IngeniumMiddleware } from '../middleware/types.ts'
+import type { IngeniumContext } from '../context/context.ts'
+import type {
+  JwtAlgorithm,
+  JwtHeader,
+  JwtKey,
+  JwtOptions,
+  JwtSecret,
+  JwtSecretResolver,
+  JwtTokenReader,
+  JwtVerified,
+} from './types.ts'
+import { verifyJwt, type KidTaggedKey, type VerifyKeyMaterial } from './verify.ts'
+import { fetchJwks } from './jwks.ts'
+
+const DEFAULT_ALGORITHMS: readonly JwtAlgorithm[] = ['HS256']
+const DEFAULT_JWKS_TTL_MS = 10 * 60 * 1000
+const SUPPORTED: ReadonlySet<JwtAlgorithm> = new Set([
+  'HS256', 'HS384', 'HS512',
+  'RS256', 'RS384', 'RS512',
+  'PS256', 'PS384', 'PS512',
+  'ES256', 'ES384', 'ES512',
+])
+
+/** Default token reader — `Authorization: Bearer <token>`. */
+const defaultGetToken: JwtTokenReader = (ctx) => {
+  const raw = ctx.headers['authorization']
+  if (!raw) return undefined
+  const value = Array.isArray(raw) ? raw[0] : raw
+  if (!value) return undefined
+  // Bearer scheme is case-insensitive per RFC 6750 §2.1.
+  const space = value.indexOf(' ')
+  if (space < 0) return undefined
+  const scheme = value.slice(0, space)
+  if (scheme.toLowerCase() !== 'bearer') return undefined
+  const token = value.slice(space + 1).trim()
+  return token.length > 0 ? token : undefined
+}
+
+/**
+ * Bearer-token JWT verification middleware.
+ *
+ * Attaches the verified token at `ctx.jwt`. Callers should module-augment
+ * `IngeniumContext` for typed access (the framework purposely doesn't ship a
+ * baked-in `jwt` field — payload shape is application-specific).
+ *
+ * @example
+ * ```ts
+ * declare module 'ingenium' {
+ *   interface IngeniumContext {
+ *     jwt?: import('ingenium').JwtVerified<{ sub: string; roles: string[] }>
+ *   }
+ * }
+ *
+ * import { ingenium } from 'ingenium'
+ * const app = ingenium()
+ * // HMAC
+ * app.use(ingenium.jwt({ secret: process.env.JWT_SECRET! }))
+ * // RSA via JWKS (Auth0, Okta, Cognito, Clerk, Supabase, ...)
+ * app.use(ingenium.jwt({
+ *   secret: [],
+ *   algorithms: ['RS256'],
+ *   jwksUrl: 'https://example.auth0.com/.well-known/jwks.json',
+ *   issuer: 'https://example.auth0.com/',
+ *   audience: 'https://api.example.com',
+ * }))
+ * ```
+ *
+ * Security choices:
+ * - Default leeway (`clockSkewSeconds`) is **5 seconds** — enough for typical
+ *   multi-host clock drift, small enough that an expired token does not stay
+ *   usable for long.
+ * - HMAC signature comparison uses `crypto.timingSafeEqual` after an explicit
+ *   length check inside {@link verifyJwt}; asymmetric verification uses
+ *   `crypto.verify` (constant-time within OpenSSL).
+ * - The algorithm allowlist is enforced at verify time. Even if an attacker
+ *   crafts `alg: 'RS256'` and we have a matching JWKS key, verification fails
+ *   unless `RS256` appears in `algorithms`. This is the canonical defence
+ *   against algorithm-confusion attacks.
+ * - `'none'` is rejected unconditionally, regardless of the allowlist.
+ * - The wire-facing error is always `IngeniumUnauthorizedError('Invalid token')`
+ *   regardless of which check failed (signature vs exp vs aud) — this avoids
+ *   handing attackers an oracle. Detailed reasons go to `opts.logger` (or
+ *   `process.emitWarning` if no logger is supplied).
+ */
+export function jwtMiddleware<T = Record<string, unknown>>(
+  opts: JwtOptions<T>,
+): IngeniumMiddleware {
+  // ── Construction-time validation ─────────────────────────────────────────
+  if (opts == null) {
+    throw new Error('jwtMiddleware: options object is required')
+  }
+  // `secret` may be an empty array when the caller is leaning entirely on
+  // `jwksUrl` for key material — treat that as a valid configuration.
+  const hasJwks = typeof opts.jwksUrl === 'string' && opts.jwksUrl.length > 0
+  if ((opts.secret as unknown) === undefined || opts.secret === null) {
+    if (!hasJwks) {
+      throw new Error('jwtMiddleware: `secret` (or `jwksUrl`) is required')
+    }
+  }
+
+  const algorithms = (opts.algorithms ?? DEFAULT_ALGORITHMS).slice() as JwtAlgorithm[]
+  if (algorithms.length === 0) {
+    throw new Error('jwtMiddleware: `algorithms` must contain at least one algorithm')
+  }
+  for (const alg of algorithms) {
+    // 'none' is never permitted, even if a caller adds it to the allowlist.
+    if ((alg as unknown as string) === 'none') {
+      throw new Error('jwtMiddleware: `alg: "none"` is forbidden')
+    }
+    if (!SUPPORTED.has(alg)) {
+      throw new Error(`jwtMiddleware: unsupported algorithm ${String(alg)}`)
+    }
+  }
+
+  const required = opts.required ?? true
+  const clockSkewSeconds = opts.clockSkewSeconds ?? 5
+  const jwksCacheMs = opts.jwksCacheMs ?? DEFAULT_JWKS_TTL_MS
+  const jwksUrl = hasJwks ? opts.jwksUrl! : null
+  const getToken = opts.getToken ?? defaultGetToken
+  const logger = opts.logger ?? ((event) => {
+    process.emitWarning(`jwt verification failed: ${event.reason}`, 'IngeniumJwtWarning')
+  })
+
+  const staticKeys = opts.secret != null && typeof opts.secret !== 'function'
+    ? normaliseStaticKeys(opts.secret as JwtKey | JwtKey[])
+    : []
+  const keyResolver =
+    typeof opts.secret === 'function'
+      ? (opts.secret as JwtSecretResolver<T>)
+      : null
+
+  return async (ctx, next) => {
+    const token = await getToken(ctx)
+    if (!token) {
+      if (required) {
+        // Missing token IS allowed to leak (no secret material involved).
+        throw new IngeniumUnauthorizedError('Missing token')
+      }
+      await next()
+      return
+    }
+
+    // Peek the header so resolvers / JWKS can route by `kid`. Malformed
+    // tokens still reach the verifier so they get the canonical error.
+    const peeked = peekHeader(token)
+
+    // Build the candidate key list for this request.
+    let keys: (VerifyKeyMaterial | KidTaggedKey)[]
+    try {
+      keys = await collectKeys({
+        peeked,
+        staticKeys,
+        keyResolver,
+        jwksUrl,
+        jwksCacheMs,
+      })
+    } catch (err) {
+      if (err instanceof IngeniumUnauthorizedError) throw err
+      const reason = err instanceof Error ? err.message : 'key_resolution_failed'
+      logger({ reason })
+      throw new IngeniumUnauthorizedError('Invalid token')
+    }
+
+    if (keys.length === 0) {
+      logger({ reason: 'no_keys_available' })
+      throw new IngeniumUnauthorizedError('Invalid token')
+    }
+
+    // Build VerifyOptions without spreading undefined keys (exactOptionalPropertyTypes).
+    const verifyOpts: Parameters<typeof verifyJwt>[2] = { algorithms, clockSkewSeconds }
+    if (opts.audience !== undefined) verifyOpts.audience = opts.audience
+    if (opts.issuer !== undefined) verifyOpts.issuer = opts.issuer
+    if (opts.maxAgeSeconds !== undefined) verifyOpts.maxAgeSeconds = opts.maxAgeSeconds
+    const result = verifyJwt<T>(token, keys, verifyOpts)
+
+    if ('error' in result) {
+      logger({ reason: result.error })
+      throw new IngeniumUnauthorizedError('Invalid token')
+    }
+
+    ;(ctx as IngeniumContext & { jwt?: JwtVerified<T> }).jwt = result
+    await next()
+  }
+}
+
+/**
+ * Normalise the static `secret` option to a flat array of either raw key
+ * material or kid-tagged entries that `verifyJwt` understands.
+ *
+ * Accepts string / Buffer / KeyObject and the `{ kid, key }` wrapper.
+ */
+function normaliseStaticKeys(secret: JwtKey | JwtKey[]): (VerifyKeyMaterial | KidTaggedKey)[] {
+  const list = Array.isArray(secret) ? secret : [secret]
+  if (list.length === 0) {
+    // An empty literal array IS allowed when paired with jwksUrl; the
+    // top-level construction-time check already validated that constraint.
+    return []
+  }
+  const out: (VerifyKeyMaterial | KidTaggedKey)[] = []
+  for (const k of list) {
+    out.push(coerceJwtKey(k))
+  }
+  return out
+}
+
+function coerceJwtKey(k: JwtKey): VerifyKeyMaterial | KidTaggedKey {
+  if (typeof k === 'string') {
+    if (k.length === 0) {
+      throw new Error('jwtMiddleware: secret string must not be empty')
+    }
+    return k
+  }
+  if (Buffer.isBuffer(k)) return k
+  if (isKeyObject(k)) return k
+  if (typeof k === 'object' && k !== null && 'kid' in k && 'key' in k) {
+    if (typeof k.kid !== 'string' || k.kid.length === 0) {
+      throw new Error('jwtMiddleware: keyed entry requires a non-empty `kid`')
+    }
+    const key = k.key
+    if (typeof key === 'string') {
+      if (key.length === 0) throw new Error('jwtMiddleware: keyed entry `key` must not be empty')
+      return { kid: k.kid, key }
+    }
+    if (Buffer.isBuffer(key) || isKeyObject(key)) return { kid: k.kid, key }
+  }
+  throw new Error('jwtMiddleware: invalid `secret` entry — expected string, Buffer, KeyObject, or { kid, key }')
+}
+
+function isKeyObject(v: unknown): v is KeyObject {
+  // Avoid a hard import-time check; KeyObjects from node:crypto carry a
+  // distinctive `asymmetricKeyType` getter or `type` property of
+  // 'public' | 'private' | 'secret'.
+  if (typeof v !== 'object' || v === null) return false
+  const t = (v as { type?: unknown }).type
+  return t === 'public' || t === 'private' || t === 'secret'
+}
+
+interface CollectKeysCtx<T> {
+  peeked: JwtHeader | null
+  staticKeys: (VerifyKeyMaterial | KidTaggedKey)[]
+  keyResolver: JwtSecretResolver<T> | null
+  jwksUrl: string | null
+  jwksCacheMs: number
+}
+
+async function collectKeys<T>(ctx: CollectKeysCtx<T>): Promise<(VerifyKeyMaterial | KidTaggedKey)[]> {
+  const out: (VerifyKeyMaterial | KidTaggedKey)[] = ctx.staticKeys.slice()
+
+  if (ctx.keyResolver) {
+    const resolved = await ctx.keyResolver(ctx.peeked ?? ({ alg: '' } as JwtHeader))
+    if (resolved == null) {
+      throw new Error('secret_resolver_returned_empty')
+    }
+    if (typeof resolved === 'string') {
+      if (resolved.length === 0) throw new Error('secret_resolver_returned_empty')
+      out.push(resolved)
+    } else {
+      out.push(coerceJwtKey(resolved as JwtKey))
+    }
+  }
+
+  if (ctx.jwksUrl) {
+    let jwks: Map<string, KeyObject>
+    try {
+      jwks = await fetchJwks(ctx.jwksUrl, ctx.jwksCacheMs)
+    } catch {
+      // Don't leak upstream details to clients OR to the logger reason —
+      // a single canonical reason is enough for ops.
+      throw new IngeniumUnauthorizedError('Token key fetch failed')
+    }
+    const headerKid = ctx.peeked && typeof ctx.peeked.kid === 'string' ? ctx.peeked.kid : null
+    if (headerKid) {
+      const match = jwks.get(headerKid)
+      if (match) out.push({ kid: headerKid, key: match })
+      // No-match isn't fatal here; verifier returns kid_unknown if the
+      // entire candidate set is empty after key selection.
+    } else {
+      // No kid on the token — try every key in the JWKS as a tagged entry.
+      for (const [kid, key] of jwks) {
+        out.push({ kid, key })
+      }
+      // Also expose them untagged so the verifier's `selectCandidates` will
+      // try them when the header lacks `kid`.
+      for (const [, key] of jwks) {
+        out.push(key)
+      }
+    }
+  }
+
+  return out
+}
+
+/** Best-effort header peek for resolver routing. Returns null on malformed tokens. */
+function peekHeader(token: string): JwtHeader | null {
+  const dot = token.indexOf('.')
+  if (dot <= 0) return null
+  try {
+    const buf = Buffer.from(token.slice(0, dot), '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 JwtHeader
+  } catch {
+    return null
+  }
+}
+
+// Backwards-compat re-exports for downstream code that imported these names.
+export type { JwtSecret, JwtSecretResolver }

package/src/jwt/types.ts

@@ -0,0 +1,137 @@
+import type { KeyObject } from 'node:crypto'
+import type { Buffer } from 'node:buffer'
+import type { IngeniumContext } from '../context/context.ts'
+
+/**
+ * Supported JWT signing algorithms.
+ *
+ * - `HSxxx` — HMAC with the supplied shared secret.
+ * - `RSxxx` — RSASSA-PKCS1-v1_5 with the supplied RSA public key (PEM / JWK / KeyObject).
+ * - `PSxxx` — RSASSA-PSS (MGF1, salt length = digest length).
+ * - `ESxxx` — ECDSA on P-256 / P-384 / P-521 (raw r||s, NOT DER — per the JWT spec).
+ *
+ * `alg: 'none'` is intentionally absent from this union and is hard-rejected
+ * at the verifier — never accept unsigned tokens, even with an empty allowlist.
+ */
+export type JwtAlgorithm =
+  | 'HS256' | 'HS384' | 'HS512'
+  | 'RS256' | 'RS384' | 'RS512'
+  | 'ES256' | 'ES384' | 'ES512'
+  | 'PS256' | 'PS384' | 'PS512'
+
+/** Decoded JWT header. The `alg` field is required by the spec. */
+export interface JwtHeader {
+  alg: string
+  typ?: string
+  kid?: string
+  [k: string]: unknown
+}
+
+/**
+ * A successfully verified JWT. `payload` carries the typed claims object,
+ * `header` carries the decoded protected header, and `raw` is the original
+ * compact-serialization string the client sent (useful for re-emitting).
+ */
+export interface JwtVerified<T = Record<string, unknown>> {
+  header: JwtHeader
+  payload: T
+  raw: string
+}
+
+/** Internal — verifier failure mode. Public surface only ever sees `'Invalid token'`. */
+export type JwtVerifyError =
+  | { error: 'malformed' }
+  | { error: 'unsupported_alg' }
+  | { error: 'bad_signature' }
+  | { error: 'expired' }
+  | { error: 'not_yet_valid' }
+  | { error: 'too_old' }
+  | { error: 'aud_mismatch' }
+  | { error: 'iss_mismatch' }
+  | { error: 'kid_unknown' }
+  | { error: 'jwks_fetch_failed' }
+
+/**
+ * A single signing/verification key. For HMAC algorithms (HSxxx) this is the
+ * shared secret as a string; for asymmetric algorithms it's the PUBLIC key in
+ * PEM (string / Buffer) or as a pre-built `KeyObject`.
+ *
+ * Wrapping with `{ kid, key }` enables header-based key selection — the
+ * verifier picks the entry whose `kid` matches `header.kid`.
+ */
+export type JwtKey =
+  | string
+  | Buffer
+  | KeyObject
+  | { kid: string; key: string | Buffer | KeyObject }
+
+/**
+ * Resolve a per-request key. Receives the decoded JWT header so callers can
+ * implement `kid`-based JWKS-style routing without parsing the token themselves.
+ */
+export type JwtSecretResolver<_T = Record<string, unknown>> = (
+  header: JwtHeader,
+) => JwtKey | Promise<JwtKey>
+
+/** All ways `secret` can be supplied. */
+export type JwtSecret<T = Record<string, unknown>> =
+  | JwtKey
+  | JwtKey[]
+  | JwtSecretResolver<T>
+
+/** Signature for pulling the raw compact-serialization out of the request. */
+export type JwtTokenReader = (
+  ctx: IngeniumContext,
+) => string | undefined | Promise<string | undefined>
+
+/** Optional structured logger for redacted verification diagnostics. */
+export type JwtLogger = (event: { reason: string; alg?: string }) => void
+
+export interface JwtOptions<T = Record<string, unknown>> {
+  /**
+   * Verification key material. Accepts:
+   * - A single key (string secret, PEM, Buffer, or `KeyObject`).
+   * - `{ kid, key }` for explicit key-id tagging.
+   * - An array of any of the above (rotation / multi-key — the verifier
+   *   picks by `kid` if present, else tries each in order).
+   * - A function `(header) => key | Promise<key>` for fully custom routing.
+   */
+  secret: JwtSecret<T>
+  /** Allowed signing algorithms. Default `['HS256']`. */
+  algorithms?: readonly JwtAlgorithm[]
+  /** Required `aud` claim. Token's `aud` must match (or include) one of these. */
+  audience?: string | readonly string[]
+  /** Required `iss` claim. */
+  issuer?: string | readonly string[]
+  /** Reject tokens whose `iat` is older than N seconds. */
+  maxAgeSeconds?: number
+  /** Leeway for `nbf` / `exp` checks, in seconds. Default `5`. */
+  clockSkewSeconds?: number
+  /**
+   * If `true` (default), missing tokens raise `IngeniumUnauthorizedError`.
+   * If `false`, missing tokens just call `next()` with no `ctx.jwt`.
+   */
+  required?: boolean
+  /**
+   * Custom token reader. Default reads `Authorization: Bearer <token>`.
+   * Return `undefined` to indicate "no token in this request".
+   */
+  getToken?: JwtTokenReader
+  /**
+   * Optional sink for redacted verification failure reasons. Useful for
+   * observability without leaking the failure type to the wire (which would
+   * be an oracle for attackers).
+   */
+  logger?: JwtLogger
+  /**
+   * Optional JWKS endpoint URL. When set, the middleware fetches the keys
+   * from this URL on demand and looks them up by `header.kid`. Cached for
+   * `jwksCacheMs` (default 10 minutes) per URL with a single in-flight
+   * request coalesced across concurrent callers.
+   */
+  jwksUrl?: string
+  /** JWKS cache TTL in milliseconds. Default `600_000` (10 minutes). */
+  jwksCacheMs?: number
+  /** Phantom — narrows `ctx.jwt.payload` for typed handlers. */
+  _payload?: T
+}