ingenium 0.0.1

package/src/context/cookies.ts

@@ -0,0 +1,282 @@
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import { Buffer } from 'node:buffer'
+import type { IngeniumContext } from './context.ts'
+import { IngeniumError } from '../errors.ts'
+
+/**
+ * Options accepted by {@link IngeniumCookies.set}. Maps 1:1 to RFC 6265 cookie
+ * attributes plus a few modern extensions (`Priority`, `Partitioned`).
+ *
+ * `sameSite: true` is normalized to `'strict'` (Express compatibility);
+ * `sameSite: false` omits the attribute entirely so the browser falls back
+ * to its default policy.
+ */
+export interface CookieSetOptions {
+  /** `Domain=` attribute. Omitted when undefined. */
+  domain?: string
+  /** `Path=` attribute. Defaults to `'/'`. */
+  path?: string
+  /** `Expires=` attribute. Serialized via `Date.toUTCString()`. */
+  expires?: Date
+  /** `Max-Age=` (seconds). Floored to an integer. */
+  maxAge?: number
+  /** `HttpOnly` flag. */
+  httpOnly?: boolean
+  /** `Secure` flag. */
+  secure?: boolean
+  /** `SameSite=` attribute. `true` → `'strict'`; `false`/omitted → no attr. */
+  sameSite?: 'strict' | 'lax' | 'none' | true | false
+  /** `Priority=` attribute (CHIPS / RFC 9220). Capitalized on the wire. */
+  priority?: 'low' | 'medium' | 'high'
+  /** `Partitioned` flag (CHIPS). */
+  partitioned?: boolean
+  /**
+   * When `true`, the cookie value is HMAC-SHA-256 signed with the app's
+   * `cookieSecrets[0]`. On the wire: `name=value.signature`. Throws
+   * `IngeniumError(500, 'COOKIE_SECRET_MISSING')` if no secrets are configured.
+   */
+  signed?: boolean
+}
+
+/** Options accepted by {@link IngeniumCookies.get}. */
+export interface CookieGetOptions {
+  /**
+   * When `true`, the cookie value is treated as `value.signature` and the
+   * HMAC is verified against every configured secret (rotation-safe).
+   * Returns `null` on tamper, missing signature, or no configured secrets.
+   */
+  signed?: boolean
+}
+
+/**
+ * First-class cookie API exposed via `ctx.cookies`. Pool-bound and lazy —
+ * the holder is allocated on first access and dropped to `null` on context
+ * reset, so routes that never touch cookies pay zero overhead.
+ *
+ * Read side parses `ctx.headers.cookie` once and caches the resulting record.
+ * Write side appends to the response `set-cookie` header, preserving prior
+ * values (a single response may carry multiple `Set-Cookie` headers).
+ */
+export interface IngeniumCookies {
+  /**
+   * Read a cookie by name. With `{ signed: true }`, verifies the HMAC
+   * suffix and returns `null` on mismatch. Returns `null` when the cookie
+   * is absent.
+   */
+  get(name: string, opts?: CookieGetOptions): string | null
+  /**
+   * Snapshot of all parsed cookies. Signed cookies appear with their raw
+   * `value.signature` suffix — call `.get(name, { signed: true })` to verify.
+   */
+  all(): Record<string, string>
+  /**
+   * Write a `Set-Cookie` header. Multiple calls accumulate (the response
+   * carries one `Set-Cookie` header per call). With `{ signed: true }`,
+   * the value is HMAC-SHA-256 signed.
+   */
+  set(name: string, value: string, opts?: CookieSetOptions): void
+  /**
+   * Expire a cookie. Emits `Max-Age=0` plus an `Expires` in the past, and
+   * mirrors `path` / `domain` so the browser actually removes the right
+   * cookie (a `Set-Cookie` only matches the existing cookie on those attrs).
+   */
+  clear(name: string, opts?: Pick<CookieSetOptions, 'domain' | 'path'>): void
+}
+
+// ───── Parser (RFC 6265 §5.2, defensive) ────────────────────────────────────
+
+/**
+ * Parse a `Cookie` request header into a name → value map. Mirrors the
+ * `parseCookieHeader` helper in `session/middleware.ts` but kept inline here
+ * so the cookie holder has no cross-module dependency on the session module.
+ *
+ * - First occurrence wins (RFC 6265 §5.4 typical browser behavior).
+ * - Quoted values: surrounding `"` are stripped.
+ * - Percent-encoded values are decoded via `decodeURIComponent`; bad encodings
+ *   fall back to the raw value rather than throwing — this parser is exposed
+ *   to attacker-controlled input and must never crash dispatch.
+ */
+function parseCookieHeader(header: string | undefined): Record<string, string> {
+  const out: Record<string, string> = Object.create(null) as Record<string, string>
+  if (!header) return out
+
+  const parts = header.split(';')
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i]!
+    const eq = part.indexOf('=')
+    if (eq < 0) continue
+    const name = part.slice(0, eq).trim()
+    if (!name || name in out) continue
+    let value = part.slice(eq + 1).trim()
+    if (
+      value.length >= 2 &&
+      value.charCodeAt(0) === 0x22 &&
+      value.charCodeAt(value.length - 1) === 0x22
+    ) {
+      value = value.slice(1, -1)
+    }
+    try {
+      out[name] = decodeURIComponent(value)
+    } catch {
+      out[name] = value
+    }
+  }
+  return out
+}
+
+// ───── Serializer ───────────────────────────────────────────────────────────
+
+/** Capitalize the first character; the rest stays as-is. */
+function cap(s: string): string {
+  return s.length === 0 ? s : s[0]!.toUpperCase() + s.slice(1)
+}
+
+/**
+ * Serialize a single `Set-Cookie` value per RFC 6265 §4.1.1. The value is
+ * `encodeURIComponent`-escaped so semicolons, whitespace, and control chars
+ * cannot break the header (the read side mirrors this with `decodeURIComponent`).
+ */
+function serializeSetCookie(name: string, value: string, opts: CookieSetOptions): string {
+  const segments: string[] = [`${name}=${encodeURIComponent(value)}`]
+  if (opts.domain) segments.push(`Domain=${opts.domain}`)
+  segments.push(`Path=${opts.path ?? '/'}`)
+
+  if (opts.expires) {
+    segments.push(`Expires=${opts.expires.toUTCString()}`)
+  }
+  if (typeof opts.maxAge === 'number') {
+    // Max-Age must be an integer; floor to match RFC behaviour.
+    segments.push(`Max-Age=${Math.floor(opts.maxAge)}`)
+  }
+  if (opts.httpOnly) segments.push('HttpOnly')
+  if (opts.secure) segments.push('Secure')
+
+  if (opts.sameSite !== undefined && opts.sameSite !== false) {
+    // `true` → 'strict' for Express compat. Otherwise lowercase → Capitalized.
+    const ss = opts.sameSite === true ? 'strict' : opts.sameSite
+    segments.push(`SameSite=${cap(ss)}`)
+  }
+  if (opts.priority) segments.push(`Priority=${cap(opts.priority)}`)
+  if (opts.partitioned) segments.push('Partitioned')
+
+  return segments.join('; ')
+}
+
+/**
+ * Append a `Set-Cookie` value to the response, preserving any existing
+ * values. The header bag normalizes to an array on the second `.set()` so
+ * the transport writes multiple `Set-Cookie` lines (per RFC 7230 §3.2.2,
+ * `Set-Cookie` is the canonical exception to header-folding rules).
+ */
+function appendSetCookie(ctx: IngeniumContext<unknown>, value: string): void {
+  const existing = ctx.getHeader('set-cookie')
+  if (!existing) {
+    ctx.set('set-cookie', value)
+  } else if (Array.isArray(existing)) {
+    ctx.set('set-cookie', [...existing, value])
+  } else {
+    ctx.set('set-cookie', [existing, value])
+  }
+}
+
+// ───── HMAC sign / verify ───────────────────────────────────────────────────
+
+/** HMAC-SHA-256(secret, value), base64url-encoded. */
+function sign(value: string, secret: string): string {
+  return createHmac('sha256', secret).update(value).digest('base64url')
+}
+
+/**
+ * Verify a `value.signature` cookie against any of the provided secrets.
+ * Returns the un-signed value or `null`. Uses {@link timingSafeEqual} to
+ * defeat byte-wise timing oracles. Splits on the LAST `.` so the underlying
+ * value may itself contain dots.
+ */
+function verifySigned(raw: string, secrets: readonly string[]): string | null {
+  const dot = raw.lastIndexOf('.')
+  if (dot <= 0 || dot >= raw.length - 1) return null
+  const value = raw.slice(0, dot)
+  const sig = raw.slice(dot + 1)
+  const sigBuf = Buffer.from(sig, 'base64url')
+  if (sigBuf.length === 0) return null
+
+  for (let i = 0; i < secrets.length; i++) {
+    const expected = Buffer.from(sign(value, secrets[i]!), 'base64url')
+    if (expected.length !== sigBuf.length) continue
+    if (timingSafeEqual(expected, sigBuf)) return value
+  }
+  return null
+}
+
+// ───── Factory ──────────────────────────────────────────────────────────────
+
+/**
+ * Build the lazy cookie holder bound to `ctx`. The parsed-cookies cache is
+ * populated on first read; the closed-over `parsed` reference is local to
+ * the holder so a context that's reset and re-acquired gets a fresh holder
+ * (because `ctx._cookies` is nulled on `reset()`).
+ *
+ * Secrets are read from `ctx._cookieSecrets`, which the app stamps at
+ * dispatch entry when configured — same pattern as `_trustProxy`. The read
+ * happens at sign/verify time (NOT at holder construction) so an app that
+ * registers secrets after the holder is allocated still picks them up.
+ */
+export function makeIngeniumCookies<Params>(ctx: IngeniumContext<Params>): IngeniumCookies {
+  let parsed: Record<string, string> | null = null
+
+  const requireSecrets = (): readonly string[] => {
+    const secrets = ctx._cookieSecrets
+    if (!secrets || secrets.length === 0) {
+      throw new IngeniumError(
+        500,
+        'COOKIE_SECRET_MISSING',
+        'Signed cookies require `cookieSecrets` to be configured on the app.',
+      )
+    }
+    return secrets
+  }
+
+  return {
+    get(name, opts) {
+      if (!parsed) parsed = parseCookieHeader(ctx.headers.cookie as string | undefined)
+      const raw = parsed[name]
+      if (raw === undefined) return null
+      if (opts?.signed) {
+        // Verify uses ALL secrets so rotation (new key first, old keys kept)
+        // doesn't lock existing clients out mid-deploy.
+        const secrets = requireSecrets()
+        return verifySigned(raw, secrets)
+      }
+      return raw
+    },
+    all() {
+      if (!parsed) parsed = parseCookieHeader(ctx.headers.cookie as string | undefined)
+      return parsed
+    },
+    set(name, value, opts) {
+      let wireValue = value
+      if (opts?.signed) {
+        // First secret signs; remaining secrets are verify-only (rotation).
+        const secrets = requireSecrets()
+        wireValue = `${value}.${sign(value, secrets[0]!)}`
+      }
+      appendSetCookie(ctx, serializeSetCookie(name, wireValue, opts ?? {}))
+    },
+    clear(name, opts) {
+      // Max-Age=0 + an Expires in the distant past. Browsers only match on
+      // (name, domain, path) when expiring, so mirror those from the caller.
+      appendSetCookie(
+        ctx,
+        serializeSetCookie(name, '', {
+          // exactOptionalPropertyTypes: only include `domain` when the caller
+          // actually supplied one — an explicit `undefined` isn't assignable to
+          // the optional `domain?: string` field.
+          ...(opts?.domain !== undefined ? { domain: opts.domain } : {}),
+          path: opts?.path ?? '/',
+          maxAge: 0,
+          expires: new Date(0),
+        }),
+      )
+    },
+  }
+}

package/src/context/pool.ts

@@ -0,0 +1,32 @@
+import { IngeniumContext } from './context.ts'
+
+/**
+ * A bounded free-list of `IngeniumContext` objects. Acquire on each request,
+ * release back when the response has been written. If the pool is empty,
+ * a fresh context is allocated; if the pool is full on release, the
+ * context is discarded (GC handles it). Never blocks.
+ */
+export class IngeniumContextPool {
+  private readonly pool: IngeniumContext[] = []
+  private readonly max: number
+
+  constructor(maxSize = 1024) {
+    this.max = maxSize
+  }
+
+  /** Acquire a context. Caller must call `release()` when done. */
+  acquire(): IngeniumContext {
+    return this.pool.pop() ?? new IngeniumContext()
+  }
+
+  /** Reset and return the context to the free list (or discard if full). */
+  release(ctx: IngeniumContext): void {
+    ctx.reset()
+    if (this.pool.length < this.max) this.pool.push(ctx)
+  }
+
+  /** Current free-list size. Useful for tests and metrics. */
+  get size(): number {
+    return this.pool.length
+  }
+}

package/src/cors/middleware.ts

@@ -0,0 +1,182 @@
+import type { IngeniumMiddleware } from '../middleware/types.ts'
+import type { IngeniumContext } from '../context/context.ts'
+import type { CorsOptions, CorsOrigin } from './types.ts'
+
+const DEFAULT_METHODS: readonly string[] = [
+  'GET',
+  'HEAD',
+  'PUT',
+  'PATCH',
+  'POST',
+  'DELETE',
+]
+
+/**
+ * Append a value to the `Vary` response header, de-duplicating field names
+ * (case-insensitive).
+ */
+function appendVary(ctx: IngeniumContext, field: string): void {
+  const existing = ctx.getHeader('vary')
+  if (!existing) {
+    ctx.set('vary', field)
+    return
+  }
+  const cur = Array.isArray(existing) ? existing.join(', ') : existing
+  const seen = cur
+    .split(',')
+    .map((s) => s.trim().toLowerCase())
+    .filter((s) => s.length > 0)
+  if (seen.includes(field.toLowerCase())) return
+  ctx.set('vary', cur.length > 0 ? `${cur}, ${field}` : field)
+}
+
+/**
+ * Resolve the `origin` option against the request's `Origin` header.
+ * Returns the literal value to put on `Access-Control-Allow-Origin`, or
+ * `null` to omit the header (request is denied / had no `Origin`).
+ *
+ * Also returns `reflected` — `true` when the value mirrors the request's
+ * `Origin`, so the caller knows to add `Vary: Origin`.
+ */
+async function resolveOrigin(
+  spec: CorsOrigin,
+  reqOrigin: string | undefined,
+  ctx: IngeniumContext,
+): Promise<{ value: string | null; reflected: boolean }> {
+  // Static wildcard: never depends on the request, never reflects.
+  if (spec === '*') return { value: '*', reflected: false }
+  if (spec === false) return { value: null, reflected: false }
+
+  // Anything below requires an Origin header on the request.
+  if (typeof reqOrigin !== 'string' || reqOrigin.length === 0) {
+    return { value: null, reflected: false }
+  }
+
+  if (spec === true) return { value: reqOrigin, reflected: true }
+
+  if (typeof spec === 'string') {
+    return spec === reqOrigin
+      ? { value: reqOrigin, reflected: true }
+      : { value: null, reflected: true }
+  }
+
+  if (Array.isArray(spec)) {
+    return spec.includes(reqOrigin)
+      ? { value: reqOrigin, reflected: true }
+      : { value: null, reflected: true }
+  }
+
+  if (spec instanceof RegExp) {
+    return spec.test(reqOrigin)
+      ? { value: reqOrigin, reflected: true }
+      : { value: null, reflected: true }
+  }
+
+  if (typeof spec === 'function') {
+    const result = await spec(reqOrigin, ctx)
+    if (result === true) return { value: reqOrigin, reflected: true }
+    if (result === false) return { value: null, reflected: true }
+    if (typeof result === 'string') {
+      // Custom string — not a literal reflection; only Vary if it's not '*'.
+      return { value: result, reflected: result !== '*' }
+    }
+    return { value: null, reflected: true }
+  }
+
+  return { value: null, reflected: false }
+}
+
+/**
+ * CORS middleware. Implements the standard CORS protocol (Fetch spec
+ * §3.2.4) for both simple requests and preflight (`OPTIONS` +
+ * `Access-Control-Request-Method`).
+ *
+ * @example
+ *   app.use(ingenium.cors())
+ *   app.use(ingenium.cors({ origin: ['https://app.example.com'], credentials: true }))
+ */
+export function corsMiddleware(opts: CorsOptions = {}): IngeniumMiddleware {
+  const origin: CorsOrigin = opts.origin ?? '*'
+  const methods = opts.methods ?? DEFAULT_METHODS
+  const allowedHeaders = opts.allowedHeaders
+  const exposedHeaders = opts.exposedHeaders
+  const credentials = opts.credentials ?? false
+  const maxAge = opts.maxAge
+  const optionsSuccessStatus = opts.optionsSuccessStatus ?? 204
+
+  // Construction-time validation: `credentials: true` + wildcard origin is
+  // forbidden by the CORS spec — browsers reject the response.
+  if (credentials && origin === '*') {
+    throw new Error(
+      "ingenium.cors: `credentials: true` is incompatible with `origin: '*'`. " +
+        'Specify an explicit origin (string, array, regex, or function) instead.',
+    )
+  }
+
+  const methodsHeader = methods.join(',')
+  const exposedHeader = exposedHeaders && exposedHeaders.length > 0
+    ? exposedHeaders.join(',')
+    : undefined
+  const allowedHeader = allowedHeaders && allowedHeaders.length > 0
+    ? allowedHeaders.join(',')
+    : undefined
+  const maxAgeHeader = typeof maxAge === 'number' ? String(maxAge) : undefined
+
+  return async (ctx, next) => {
+    const reqOrigin = ctx.headers.origin
+    const reqOriginStr = typeof reqOrigin === 'string' ? reqOrigin : undefined
+
+    const { value: allowOrigin, reflected } = await resolveOrigin(
+      origin,
+      reqOriginStr,
+      ctx,
+    )
+
+    if (reflected) appendVary(ctx, 'Origin')
+
+    if (allowOrigin !== null) {
+      ctx.set('access-control-allow-origin', allowOrigin)
+      if (credentials) {
+        ctx.set('access-control-allow-credentials', 'true')
+      }
+    }
+
+    // Detect preflight: OPTIONS + Access-Control-Request-Method header.
+    const acrm = ctx.headers['access-control-request-method']
+    const isPreflight =
+      ctx.method === 'OPTIONS' && typeof acrm === 'string' && acrm.length > 0
+
+    if (isPreflight) {
+      ctx.set('access-control-allow-methods', methodsHeader)
+
+      if (allowedHeader !== undefined) {
+        ctx.set('access-control-allow-headers', allowedHeader)
+      } else {
+        const acrh = ctx.headers['access-control-request-headers']
+        if (typeof acrh === 'string' && acrh.length > 0) {
+          ctx.set('access-control-allow-headers', acrh)
+          // The reflected headers vary with the request, so signal it.
+          appendVary(ctx, 'Access-Control-Request-Headers')
+        }
+      }
+
+      if (maxAgeHeader !== undefined) {
+        ctx.set('access-control-max-age', maxAgeHeader)
+      }
+
+      // Preflight terminates here — no body, no downstream handlers.
+      ctx.status(optionsSuccessStatus)
+      ctx.set('content-length', '0')
+      ctx._body = { kind: 'none' }
+      ctx._written = true
+      return
+    }
+
+    // Simple / actual request: expose headers, then continue the chain.
+    if (exposedHeader !== undefined) {
+      ctx.set('access-control-expose-headers', exposedHeader)
+    }
+
+    return next()
+  }
+}

package/src/cors/types.ts

@@ -0,0 +1,79 @@
+import type { IngeniumContext } from '../context/context.ts'
+
+/**
+ * Function form of the `origin` option. Receives the request's `Origin`
+ * header value (always a string — never called when no `Origin` is present)
+ * and the active `IngeniumContext`. May return:
+ *
+ * - `true`  — allow the request, reflect the request's `Origin` back.
+ * - `false` — deny the request (no `Access-Control-Allow-Origin` header set).
+ * - `string` — allow the request, use this exact value as the
+ *   `Access-Control-Allow-Origin` header (use `'*'` for the wildcard).
+ *
+ * May be sync or async.
+ */
+export type CorsOriginFn = (
+  origin: string,
+  ctx: IngeniumContext,
+) => boolean | string | Promise<boolean | string>
+
+/**
+ * Spec for the `origin` option.
+ *
+ * - `boolean` — `true` reflects any request `Origin`; `false` disables CORS.
+ * - `'*'` — wildcard: `Access-Control-Allow-Origin: *`.
+ * - any other `string` — exact match against the request's `Origin`.
+ * - `string[]` — allowlist; matched exactly.
+ * - `RegExp` — tested against the request's `Origin`.
+ * - `CorsOriginFn` — fully custom predicate (see above).
+ */
+export type CorsOrigin =
+  | boolean
+  | string
+  | string[]
+  | RegExp
+  | CorsOriginFn
+
+/**
+ * Options for `ingenium.cors`. All fields are optional. See README for details.
+ */
+export interface CorsOptions {
+  /** Origin policy. Default: `'*'`. */
+  origin?: CorsOrigin
+
+  /**
+   * Methods advertised on `Access-Control-Allow-Methods` for preflight.
+   * Default: `['GET','HEAD','PUT','PATCH','POST','DELETE']`.
+   */
+  methods?: string[]
+
+  /**
+   * Headers advertised on `Access-Control-Allow-Headers` for preflight.
+   * If `undefined`, the value of `Access-Control-Request-Headers` from the
+   * preflight request is mirrored back. Default: `undefined`.
+   */
+  allowedHeaders?: string[]
+
+  /**
+   * Headers advertised on `Access-Control-Expose-Headers` for simple
+   * responses. Default: `undefined` (header omitted).
+   */
+  exposedHeaders?: string[]
+
+  /**
+   * If `true`, sets `Access-Control-Allow-Credentials: true`.
+   * Incompatible with `origin: '*'` — throws at construction time.
+   * Default: `false`.
+   */
+  credentials?: boolean
+
+  /**
+   * `Access-Control-Max-Age` (seconds). Default: `undefined` (header omitted).
+   */
+  maxAge?: number
+
+  /**
+   * Status code for successful preflight responses. Default: `204`.
+   */
+  optionsSuccessStatus?: number
+}