ingenium 0.0.1 → 0.0.2

package/src/jwt/middleware.ts

@@ -1,6 +1,6 @@
 import { Buffer } from 'node:buffer'
 import type { KeyObject } from 'node:crypto'
-import { IngeniumUnauthorizedError } from '../errors.ts'
+import { IngeniumError, IngeniumUnauthorizedError } from '../errors.ts'
 import type { IngeniumMiddleware } from '../middleware/types.ts'
 import type { IngeniumContext } from '../context/context.ts'
 import type {
@@ -17,6 +17,10 @@ import { verifyJwt, type KidTaggedKey, type VerifyKeyMaterial } from './verify.t
 import { fetchJwks } from './jwks.ts'
 
 const DEFAULT_ALGORITHMS: readonly JwtAlgorithm[] = ['HS256']
+// When the caller wires up JWKS (always asymmetric) but doesn't pin an
+// algorithm, defaulting to the HMAC `HS256` would be a footgun — fall back to
+// the most common asymmetric default instead.
+const DEFAULT_ASYMMETRIC_ALGORITHMS: readonly JwtAlgorithm[] = ['RS256']
 const DEFAULT_JWKS_TTL_MS = 10 * 60 * 1000
 const SUPPORTED: ReadonlySet<JwtAlgorithm> = new Set([
   'HS256', 'HS384', 'HS512',
@@ -25,6 +29,25 @@ const SUPPORTED: ReadonlySet<JwtAlgorithm> = new Set([
   'ES256', 'ES384', 'ES512',
 ])
 
+/**
+ * 500 — the configured algorithm allowlist and the supplied key material are
+ * from different families (an HMAC alg paired with an asymmetric PEM / public
+ * key, or vice versa). Allowing this is the canonical algorithm-confusion
+ * footgun: an attacker forges `HS256` tokens using the server's *public* key
+ * as the HMAC secret. We refuse the configuration at construction time so the
+ * mistake surfaces at boot, not as a silent auth bypass.
+ */
+export class IngeniumJwtKeyAlgMismatchError extends IngeniumError {
+  constructor(message: string) {
+    super(500, 'JWT_KEY_ALG_MISMATCH', message)
+  }
+}
+
+/** True for the HMAC (symmetric) algorithm family. */
+function isHmacAlg(alg: JwtAlgorithm): boolean {
+  return alg === 'HS256' || alg === 'HS384' || alg === 'HS512'
+}
+
 /** Default token reader — `Authorization: Bearer <token>`. */
 const defaultGetToken: JwtTokenReader = (ctx) => {
   const raw = ctx.headers['authorization']
@@ -102,7 +125,13 @@ export function jwtMiddleware<T = Record<string, unknown>>(
     }
   }
 
-  const algorithms = (opts.algorithms ?? DEFAULT_ALGORITHMS).slice() as JwtAlgorithm[]
+  // Algorithm defaulting is family-aware. The historical `HS256` default is
+  // only safe for symmetric (string-secret) setups; when the caller leans on
+  // JWKS (always asymmetric) without pinning an algorithm, defaulting to an
+  // HMAC alg would silently invite the key-confusion bypass. In that case we
+  // default to `RS256` instead so the families can never disagree by accident.
+  const defaultAlgorithms = hasJwks ? DEFAULT_ASYMMETRIC_ALGORITHMS : DEFAULT_ALGORITHMS
+  const algorithms = (opts.algorithms ?? defaultAlgorithms).slice() as JwtAlgorithm[]
   if (algorithms.length === 0) {
     throw new Error('jwtMiddleware: `algorithms` must contain at least one algorithm')
   }
@@ -118,6 +147,7 @@ export function jwtMiddleware<T = Record<string, unknown>>(
 
   const required = opts.required ?? true
   const clockSkewSeconds = opts.clockSkewSeconds ?? 5
+  const requireExp = opts.requireExp ?? true
   const jwksCacheMs = opts.jwksCacheMs ?? DEFAULT_JWKS_TTL_MS
   const jwksUrl = hasJwks ? opts.jwksUrl! : null
   const getToken = opts.getToken ?? defaultGetToken
@@ -133,6 +163,26 @@ export function jwtMiddleware<T = Record<string, unknown>>(
       ? (opts.secret as JwtSecretResolver<T>)
       : null
 
+  // ── Key/algorithm family confinement ─────────────────────────────────────
+  // If the allowlist contains an HMAC alg, none of the STATIC key material may
+  // be asymmetric (a PEM string/Buffer or a public/private KeyObject). Pairing
+  // those is the algorithm-confusion bypass: an attacker forges `HS256` tokens
+  // using the asymmetric *public* key as the HMAC secret. Refuse at boot.
+  // (A function resolver / JWKS is checked per-request by the verifier, which
+  // never runs HMAC against an asymmetric key.)
+  if (algorithms.some(isHmacAlg)) {
+    for (const k of staticKeys) {
+      if (staticKeyIsAsymmetric(k)) {
+        throw new IngeniumJwtKeyAlgMismatchError(
+          'jwtMiddleware: an HMAC algorithm (HS256/384/512) was paired with an ' +
+            'asymmetric key (PEM or public/private KeyObject). This enables an ' +
+            'algorithm-confusion forgery — use an asymmetric algorithm (RS*/PS*/ES*) ' +
+            'for asymmetric keys, or a raw shared secret for HMAC.',
+        )
+      }
+    }
+  }
+
   return async (ctx, next) => {
     const token = await getToken(ctx)
     if (!token) {
@@ -171,7 +221,7 @@ export function jwtMiddleware<T = Record<string, unknown>>(
     }
 
     // Build VerifyOptions without spreading undefined keys (exactOptionalPropertyTypes).
-    const verifyOpts: Parameters<typeof verifyJwt>[2] = { algorithms, clockSkewSeconds }
+    const verifyOpts: Parameters<typeof verifyJwt>[2] = { algorithms, clockSkewSeconds, requireExp }
     if (opts.audience !== undefined) verifyOpts.audience = opts.audience
     if (opts.issuer !== undefined) verifyOpts.issuer = opts.issuer
     if (opts.maxAgeSeconds !== undefined) verifyOpts.maxAgeSeconds = opts.maxAgeSeconds
@@ -230,6 +280,27 @@ function coerceJwtKey(k: JwtKey): VerifyKeyMaterial | KidTaggedKey {
   throw new Error('jwtMiddleware: invalid `secret` entry — expected string, Buffer, KeyObject, or { kid, key }')
 }
 
+/**
+ * Classify a normalised static key as asymmetric (PEM blob or a public/private
+ * KeyObject). Used by the construction-time family guard — a `kid`-tagged entry
+ * is inspected by its inner `key`.
+ */
+function staticKeyIsAsymmetric(entry: VerifyKeyMaterial | KidTaggedKey): boolean {
+  const key: VerifyKeyMaterial =
+    typeof entry === 'object' && entry !== null && !Buffer.isBuffer(entry) && 'key' in entry
+      ? (entry as KidTaggedKey).key
+      : (entry as VerifyKeyMaterial)
+  if (typeof key === 'string') return looksLikePem(key)
+  if (Buffer.isBuffer(key)) return looksLikePem(key.toString('latin1'))
+  // KeyObject: 'public' / 'private' are asymmetric; 'secret' is HMAC-eligible.
+  return (key as KeyObject).type === 'public' || (key as KeyObject).type === 'private'
+}
+
+/** A PEM-armored blob is asymmetric key material, never an HMAC secret. */
+function looksLikePem(s: string): boolean {
+  return s.trimStart().startsWith('-----BEGIN')
+}
+
 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

package/src/jwt/types.ts

@@ -44,6 +44,7 @@ export type JwtVerifyError =
   | { error: 'unsupported_alg' }
   | { error: 'bad_signature' }
   | { error: 'expired' }
+  | { error: 'missing_exp' }
   | { error: 'not_yet_valid' }
   | { error: 'too_old' }
   | { error: 'aud_mismatch' }
@@ -107,6 +108,17 @@ export interface JwtOptions<T = Record<string, unknown>> {
   maxAgeSeconds?: number
   /** Leeway for `nbf` / `exp` checks, in seconds. Default `5`. */
   clockSkewSeconds?: number
+  /**
+   * Require a numeric `exp` claim. Default `true`.
+   *
+   * Why default-on: a token that omits `exp` (or carries a non-numeric one)
+   * would otherwise verify forever — a stolen token never stops working. We
+   * refuse those by default and only relax it for callers who deliberately
+   * issue non-expiring tokens (set this to `false`). Either way a present
+   * `exp`/`nbf`/`iat` that is not a finite number is treated as malformed, not
+   * silently skipped.
+   */
+  requireExp?: boolean
   /**
    * If `true` (default), missing tokens raise `IngeniumUnauthorizedError`.
    * If `false`, missing tokens just call `next()` with no `ctx.jwt`.

package/src/jwt/verify.ts

@@ -65,6 +65,11 @@ export interface VerifyOptions {
   issuer?: string | readonly string[]
   maxAgeSeconds?: number
   clockSkewSeconds?: number
+  /**
+   * Require a finite numeric `exp`. Default `true` — a token without an
+   * expiry would otherwise verify forever (see middleware `requireExp`).
+   */
+  requireExp?: boolean
   /** Override "now" for deterministic tests. Returns seconds since epoch. */
   nowSeconds?: () => number
 }
@@ -86,6 +91,27 @@ function decodeJsonSegment<T = unknown>(segment: string): T | null {
   }
 }
 
+/**
+ * Does this key material belong to the symmetric (HMAC) family?
+ *
+ * This is the load-bearing guard against the classic algorithm-confusion
+ * attack: a server configured for an asymmetric alg but tricked into running
+ * HMAC verifies the forgery with the PUBLIC key as the shared secret. A PEM
+ * (or any asymmetric `KeyObject`) is therefore NEVER eligible as an HMAC key.
+ * Only a raw string/Buffer secret, or a `secret`-type `KeyObject`, qualifies.
+ */
+function isSymmetricKey(key: VerifyKeyMaterial): boolean {
+  if (typeof key === 'string') return !looksLikePem(key)
+  if (Buffer.isBuffer(key)) return !looksLikePem(key.toString('latin1'))
+  // KeyObject: only the 'secret' type is HMAC-eligible; 'public'/'private' are not.
+  return (key as KeyObject).type === 'secret'
+}
+
+/** A PEM-armored blob is asymmetric key material, never an HMAC secret. */
+function looksLikePem(s: string): boolean {
+  return s.trimStart().startsWith('-----BEGIN')
+}
+
 /**
  * Constant-time HMAC verification.
  *
@@ -94,6 +120,12 @@ function decodeJsonSegment<T = unknown>(segment: string): T | null {
  * 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).
+ *
+ * The caller MUST have already established via {@link isSymmetricKey} that
+ * `secret` is HMAC-eligible — a public/private `KeyObject` would throw inside
+ * `export({format:'buffer'})`, and a PEM string would be silently (and
+ * dangerously) used as a shared secret. This function additionally try/catches
+ * so a mis-typed key degrades to `false` (bad_signature) rather than a 500.
  */
 function hmacVerifies(
   digest: string,
@@ -101,14 +133,18 @@ function hmacVerifies(
   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)
+  try {
+    // HMAC accepts string or Buffer; a 'secret' KeyObject exports to a buffer.
+    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)
+  } catch {
+    return false
+  }
 }
 
 /**
@@ -173,6 +209,15 @@ function asymmetricVerifies(
   }
 }
 
+/**
+ * A JWT temporal claim (`exp`/`nbf`/`iat`) is only meaningful as a finite
+ * number of seconds. `NaN`/`Infinity` would defeat the `<=` comparisons, so
+ * they're rejected the same as a missing claim.
+ */
+function isFiniteNumber(v: unknown): v is number {
+  return typeof v === 'number' && Number.isFinite(v)
+}
+
 /** 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
@@ -268,12 +313,20 @@ export function verifyJwt<T = Record<string, unknown>>(
 
   let signatureOk = false
   for (const candidate of candidates) {
+    // Bind the algorithm family to the key family. An HMAC alg must never be
+    // attempted against an asymmetric key (the algorithm-confusion / key-as-
+    // secret forgery), and an asymmetric alg must never run against a raw
+    // symmetric secret. A mismatched candidate is simply skipped — if NONE of
+    // the supplied keys are family-compatible we fall through to bad_signature.
+    const candidateIsSymmetric = isSymmetricKey(candidate)
     if (spec.family === 'hmac') {
+      if (!candidateIsSymmetric) continue
       if (hmacVerifies(spec.digest, candidate, signingInput, sig)) {
         signatureOk = true
         break
       }
     } else {
+      if (candidateIsSymmetric) continue
       if (asymmetricVerifies(spec, candidate, signingInput, sig)) {
         signatureOk = true
         break
@@ -287,14 +340,25 @@ export function verifyJwt<T = Record<string, unknown>>(
   const skew = opts.clockSkewSeconds ?? 5
   const claims = payload as Record<string, unknown>
 
-  if (typeof claims.exp === 'number') {
+  // A present-but-non-numeric temporal claim is an attempt to slip past the
+  // numeric checks below (e.g. `exp: "9999999999"` as a string). Treat any
+  // such claim as malformed rather than silently skipping the comparison.
+  if ('exp' in claims && !isFiniteNumber(claims.exp)) return { error: 'malformed' }
+  if ('nbf' in claims && !isFiniteNumber(claims.nbf)) return { error: 'malformed' }
+  if ('iat' in claims && !isFiniteNumber(claims.iat)) return { error: 'malformed' }
+
+  const requireExp = opts.requireExp ?? true
+  if (isFiniteNumber(claims.exp)) {
     if (claims.exp <= now - skew) return { error: 'expired' }
+  } else if (requireExp) {
+    // No usable expiry — refuse rather than accept a non-expiring token.
+    return { error: 'missing_exp' }
   }
-  if (typeof claims.nbf === 'number') {
+  if (isFiniteNumber(claims.nbf)) {
     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 (!isFiniteNumber(claims.iat)) return { error: 'too_old' }
     if (claims.iat + opts.maxAgeSeconds <= now - skew) return { error: 'too_old' }
   }
   if (opts.audience !== undefined) {

package/src/problem/serialize.ts

@@ -6,6 +6,12 @@ import {
 } from '../errors.ts'
 import type { ProblemDetails, ResolvedProblemDetailsOptions } from './types.ts'
 
+/**
+ * Read once at module load so V8 dead-code-eliminates the dev-only branch in
+ * production builds. See CLAUDE.md "Dev-mode diagnostics" rule.
+ */
+const IS_DEV = process.env.NODE_ENV !== 'production'
+
 /**
  * Maps known framework error codes to short, human-readable titles. Falls
  * back to the standard HTTP reason phrase, then to the error's own message.
@@ -101,13 +107,23 @@ export function toProblemDetails(
     return problem
   }
 
-  // Unknown error — generic 500.
+  // Unknown error — generic 500. Unlike IngeniumError (whose `message` is
+  // developer-authored and safe to surface), an arbitrary thrown value's
+  // message can leak internal infrastructure detail (DB DSNs with hostnames /
+  // credentials, file paths, driver internals). In production we therefore
+  // replace it with a generic phrase and only expose the raw message in dev or
+  // when the explicit `includeStack` debug opt-in is enabled.
+  const exposeMessage = IS_DEV || opts.includeStack
   const message = (err as Error)?.message
+  const detail =
+    exposeMessage && typeof message === 'string' && message.length > 0
+      ? message
+      : 'Internal Server Error'
   const problem: ProblemDetails = {
     type: 'about:blank',
     title: STATUS_REASON[500]!,
     status: 500,
-    detail: typeof message === 'string' && message.length > 0 ? message : 'Internal Server Error',
+    detail,
   }
 
   const instance = opts.instance(ctx)

package/src/proxy/trust.ts

@@ -16,6 +16,17 @@
  * (`fc00::/7`) form. Single addresses without `/` match exactly.
  */
 
+const IS_DEV = process.env.NODE_ENV !== 'production'
+
+/**
+ * `trust: true` fully trusts a client-supplied `X-Forwarded-For` header, so any
+ * caller can spoof `ctx.ip`. We warn exactly once (dev only) rather than change
+ * the default, because the boolean form is documented Express-compatible behavior
+ * and silently altering it would break apps that legitimately sit behind a single
+ * trusted reverse proxy.
+ */
+let warnedTrustTrue = false
+
 export type TrustProxy =
   | boolean
   | number
@@ -65,6 +76,17 @@ export function resolveForwarded(
 
   let trustedIp = remoteAddress
   if (typeof trust === 'boolean' && trust === true) {
+    if (IS_DEV && !warnedTrustTrue) {
+      warnedTrustTrue = true
+      try {
+        process.emitWarning(
+          "trustProxy: true fully trusts the client-supplied X-Forwarded-For header, so ctx.ip can be spoofed by any caller. This bypasses IP rate-limits/allowlists and poisons audit logs. For production, set trustProxy to a hop count (e.g. 1) or a CIDR/subnet trust list (e.g. ['loopback', '10.0.0.0/8']) so only your reverse proxy is trusted.",
+          { code: 'INGENIUM_TRUST_PROXY_TRUE' },
+        )
+      } catch {
+        // Worker runtimes can throw on emitWarning; the warning is best-effort.
+      }
+    }
     trustedIp = fullChain[0] ?? remoteAddress
   } else if (typeof trust === 'number') {
     // Skip `trust` hops from the right (the rightmost is the immediate peer).

package/src/session/middleware.ts

@@ -7,6 +7,12 @@ import type { Session, SessionCookieOptions, SessionOptions, SessionStore } from
 
 // ───── Constants ────────────────────────────────────────────────────────────
 
+/**
+ * Read once at module load so the dev-only warning branch is dead-code
+ * eliminated in production builds. See `context/context.ts` for the pattern.
+ */
+const IS_DEV = process.env.NODE_ENV !== 'production'
+
 const DEFAULT_COOKIE_NAME = 'ingenium.sid'
 const DEFAULT_MAX_AGE_SECONDS = 60 * 60 * 24 * 7 // 7 days
 /** ID byte length — 18 bytes → 24 base64url chars, ~144 bits of entropy. */
@@ -248,8 +254,10 @@ class SessionImpl implements Session {
  * - HMAC-SHA-256 over the session id, base64url-encoded; verified with
  *   `timingSafeEqual`.
  * - 144-bit (18-byte) random ids.
- * - Defaults: `HttpOnly`, `SameSite=Lax`, `Path=/`. Set `secure: true`
- *   behind TLS to enable `Secure`.
+ * - Defaults: `HttpOnly`, `SameSite=Lax`, `Path=/`. `Secure` defaults ON in
+ *   production (`NODE_ENV==='production'`) and OFF in dev so http://localhost
+ *   keeps working; set `cookie.secure: false` to force it off in production
+ *   (a dev warning fires), or `true` to force it on everywhere.
  * - Tampered or unknown cookies silently issue a fresh session — never an
  *   error response, since this is an attacker-influenced surface.
  */
@@ -265,9 +273,34 @@ export function sessionMiddleware(opts: SessionOptions): IngeniumMiddleware {
   const cookieName = opts.cookieName ?? DEFAULT_COOKIE_NAME
   const maxAgeSeconds = opts.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS
   const rolling = opts.rolling ?? false
-  const cookieOpts: SessionCookieOptions = opts.cookie ?? {}
+  const baseCookieOpts: SessionCookieOptions = opts.cookie ?? {}
   const store: SessionStore = opts.store ?? new MemoryStore()
 
+  // Safe-by-default `Secure`: when the caller didn't say either way, enable it
+  // outside dev so a session cookie can't ride a plaintext-HTTP request and be
+  // sniffed. An explicit `secure: false` still wins — that's the escape hatch
+  // for serving over http in local/dev environments. We resolve this once and
+  // bake it into the cookie options so every Set-Cookie below is consistent.
+  const resolvedSecure = baseCookieOpts.secure ?? !IS_DEV
+  const cookieOpts: SessionCookieOptions = { ...baseCookieOpts, secure: resolvedSecure }
+
+  // In production, a session cookie without `Secure` is a real exposure; surface
+  // it loudly but exactly once. The IS_DEV gate is inverted here on purpose —
+  // we only care about the missing flag when NOT in dev.
+  if (!IS_DEV && resolvedSecure === false) {
+    try {
+      process.emitWarning(
+        'ingenium: sessionMiddleware is issuing a session cookie WITHOUT the Secure ' +
+          'attribute in production (cookie.secure === false). The cookie can be sent ' +
+          'over plaintext HTTP and intercepted. Remove `cookie.secure: false` to use ' +
+          'the safe production default, or terminate TLS in front of the app.',
+        { type: 'IngeniumSessionInsecureCookieWarning' },
+      )
+    } catch {
+      /* worker contexts may throw on emitWarning */
+    }
+  }
+
   return async (ctx, next) => {
     const cookies = parseCookieHeader(ctx.headers.cookie as string | undefined)
     const raw = cookies[cookieName]

package/src/session/types.ts

@@ -15,7 +15,20 @@ export interface SessionCookieOptions {
   httpOnly?: boolean
   /** Cookie `SameSite` attribute. @default 'lax' */
   sameSite?: 'lax' | 'strict' | 'none'
-  /** Cookie `Secure` attribute. @default false */
+  /**
+   * Cookie `Secure` attribute.
+   *
+   * When left undefined, {@link sessionMiddleware} resolves it safely: ON in
+   * production (`NODE_ENV==='production'`) so the cookie cannot ride plaintext
+   * HTTP, OFF in dev so `http://localhost` keeps working. Set `false`
+   * explicitly to opt out in production (emits a dev warning), or `true` to
+   * force it on in every environment.
+   *
+   * Note: the raw {@link serializeCookie} helper still treats `undefined` as
+   * off — only the middleware applies the environment-aware default.
+   *
+   * @default undefined (production → Secure, dev → not Secure)
+   */
   secure?: boolean
 }
 

package/src/static/middleware.ts

@@ -34,6 +34,28 @@ function mimeFor(file: string): string {
   return MIME_TYPES[ext] ?? 'application/octet-stream'
 }
 
+/**
+ * Root confinement: `target` must be `absRoot` itself or a descendant of it.
+ * Factored out because it must run on the FINAL resolved target — after the
+ * `extensions` and `index` retry loops mutate `target` — not just the decoded
+ * request path. A user-configurable `index`/`extensions` value containing `..`
+ * (or any join that escapes) would otherwise slip past the up-front check.
+ */
+function isUnderRoot(absRoot: string, target: string): boolean {
+  return target === absRoot || target.startsWith(absRoot + path.sep)
+}
+
+/**
+ * True if any path segment of `target` below `absRoot` begins with a dot.
+ * Re-checked on the final target so an `index`/`extensions` value that resolves
+ * to a dotfile (e.g. `index: '.env'`) is still subject to the dotfile policy.
+ */
+function hasDotfileSegment(absRoot: string, target: string): boolean {
+  const rel = path.relative(absRoot, target)
+  if (rel.length === 0) return false
+  return rel.split(/[/\\]/).some((s) => s.length > 0 && s.startsWith('.'))
+}
+
 function makeEtag(stats: Stats): string {
   // Express-style weak etag: W/"<size>-<mtimeMs-as-hex>"
   return `W/"${stats.size.toString(16)}-${Math.floor(stats.mtimeMs).toString(16)}"`
@@ -112,19 +134,13 @@ export function staticMiddleware(root: string, opts: StaticOptions = {}): Ingeni
     // Path-traversal protection: resolve, then ensure it stays under root.
     const joined = path.join(absRoot, urlPath)
     const resolved = path.resolve(joined)
-    const isUnderRoot =
-      resolved === absRoot ||
-      resolved.startsWith(absRoot + path.sep)
-    if (!isUnderRoot) {
+    if (!isUnderRoot(absRoot, resolved)) {
       ctx.status(403).text('Forbidden')
       return
     }
 
     // Dotfile policy: check every segment of the path BELOW root.
-    const rel = path.relative(absRoot, resolved)
-    const segments = rel.length === 0 ? [] : rel.split(/[/\\]/)
-    const hasDot = segments.some((s) => s.length > 0 && s.startsWith('.'))
-    if (hasDot) {
+    if (hasDotfileSegment(absRoot, resolved)) {
       if (dotfiles === 'deny') {
         ctx.status(403).text('Forbidden')
         return
@@ -182,6 +198,25 @@ export function staticMiddleware(root: string, opts: StaticOptions = {}): Ingeni
       return next()
     }
 
+    // Re-run confinement + dotfile policy on the FINAL target. The extensions
+    // and index retry loops above mutate `target` (appending `.ext` or joining
+    // a user-configurable index name), so the up-front checks on `resolved` are
+    // not authoritative for what we are about to stream.
+    if (!isUnderRoot(absRoot, target)) {
+      ctx.status(403).text('Forbidden')
+      return
+    }
+    if (hasDotfileSegment(absRoot, target)) {
+      if (dotfiles === 'deny') {
+        ctx.status(403).text('Forbidden')
+        return
+      }
+      if (dotfiles === 'ignore') {
+        return next()
+      }
+      // 'allow' falls through.
+    }
+
     // ───── Cacheable response headers ─────
     const etag = makeEtag(stats)
     const lastModified = new Date(stats.mtimeMs).toUTCString()

package/src/ws/index.ts

@@ -41,6 +41,8 @@ import type {
 export type {
   WebSocketHandler,
   WebSocketHandlerOptions,
+  WebSocketOriginOption,
+  WebSocketOriginVerifier,
   WsIntegrator,
   WsRegistrar,
   WebSocket,

package/src/ws/middleware.ts

@@ -14,10 +14,17 @@ import type { HttpMethod } from '../router/types.ts'
 import type {
   WebSocketHandler,
   WebSocketHandlerOptions,
+  WebSocketOriginOption,
   WsRegistrar,
   WsRoute,
 } from './types.ts'
 
+/**
+ * Read once at module load so V8 dead-code-eliminates the dev warning in
+ * production builds (`if (false) { ... }`). See CLAUDE.md.
+ */
+const IS_DEV = process.env.NODE_ENV !== 'production'
+
 /**
  * Attempt to detect whether `ws` is installed. Used by the test suite to
  * `describe.skipIf` the WS suite when the optional peer dep is missing.
@@ -53,6 +60,21 @@ export function createWebSocketRegistrar(): WsRegistrar {
     if (routes.has(path)) {
       throw new Error(`ingenium.ws: path "${path}" already has a WebSocket handler`)
     }
+    // WS handlers run OUTSIDE the middleware pipeline, so a route with no
+    // `origin` policy is open to Cross-Site WebSocket Hijacking — a browser
+    // attaches the victim's cookies to a cross-origin upgrade. Nudge the
+    // developer to opt into an Origin check (or authenticate explicitly).
+    if (IS_DEV && options.origin === undefined) {
+      try {
+        process.emitWarning(
+          `ingenium.ws: WebSocket route "${path}" registered without an \`origin\` option. ` +
+            'WS handlers run outside the middleware pipeline and the browser sends the ' +
+            "user's cookies on cross-origin upgrades — restrict the Origin (e.g. " +
+            '`{ origin: true }` for same-origin) or authenticate inside the handler to ' +
+            'prevent Cross-Site WebSocket Hijacking (CSWSH).',
+        )
+      } catch { /* worker runtimes can throw on emitWarning */ }
+    }
     routes.set(path, { path, handler, options })
   }
 
@@ -79,6 +101,19 @@ export function createWebSocketRegistrar(): WsRegistrar {
         return
       }
 
+      // CSWSH defense: enforce the Origin policy BEFORE `handleUpgrade`, so a
+      // rejected cross-origin request never completes the handshake. We reply
+      // with a real `403` handshake response (not a bare destroy) so the
+      // browser surfaces the rejection rather than a generic socket error.
+      if (route.options.origin !== undefined) {
+        const origin = req.headers.origin
+        if (!isOriginAllowed(route.options.origin, origin, req)) {
+          socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n')
+          socket.destroy()
+          return
+        }
+      }
+
       // Lazy-load `ws`. On the first upgrade, dynamically import. If `ws`
       // isn't installed, give a clear actionable error and tear the socket
       // down — apps that wired `app.ws(...)` without installing the peer
@@ -160,6 +195,41 @@ export function createWebSocketRegistrar(): WsRegistrar {
   return { add, attach, close }
 }
 
+/**
+ * Decide whether an upgrade Origin passes the configured policy. Centralized
+ * so the listener stays readable and the boolean/string/array/function arms
+ * are tested in one place.
+ *
+ * `true` means same-origin: the `Origin` URL's host (incl. port) must match
+ * the request `Host` header. A missing `Origin` (non-browser clients never
+ * send one) is rejected under `true` because we cannot prove same-origin —
+ * browser-facing sockets are the threat model here; trusted backend clients
+ * should use an explicit allowlist or a custom verifier instead.
+ */
+function isOriginAllowed(
+  policy: WebSocketOriginOption,
+  origin: string | undefined,
+  req: IncomingMessage,
+): boolean {
+  if (typeof policy === 'function') return policy(origin, req)
+
+  if (policy === false) return true // explicitly disabled — allow all
+  if (policy === true) {
+    if (origin === undefined) return false
+    let originHost: string
+    try {
+      originHost = new URL(origin).host
+    } catch {
+      return false // malformed Origin header
+    }
+    return originHost === req.headers.host
+  }
+
+  // string | string[] — exact allowlist match against the raw Origin header.
+  if (origin === undefined) return false
+  return Array.isArray(policy) ? policy.includes(origin) : policy === origin
+}
+
 /**
  * Build a minimal `IngeniumContext` for a WebSocket handler. We don't run the
  * full request pipeline (no middleware, no decorators) because the upgrade