castrum 0.7.0 → 0.9.0

package/src/ingress/headers/baked-templates.ts

@@ -0,0 +1,102 @@
+// src/ingress/headers/baked-templates.ts — Header-template builder (pre-baked
+// path).
+//
+// Precomputes the 32 header-variant templates used by the pre-baked handler
+// path (`ratelimit-*` header names, benchmark wire format).
+//
+// NOTE: this is the pre-baked-path template builder. The fast path has its own
+// builder (./fast-templates.ts) with a different wire format (x-ratelimit-*) —
+// do not unify them (see AGENTS.md).
+
+import { HV_JSON, HV_CORS_SIMPLE, HV_CORS_PREFLIGHT, HV_RATE_ACTIVE } from '../constants'
+
+/** Inputs needed to build the pre-baked header templates. */
+export interface BakedTemplateParams {
+  securityEntries: ReadonlyArray<[string, string]>
+  cors?: {
+    allowOrigin?: string[]
+    allowMethods?: string[]
+    allowHeaders?: string[]
+    exposeHeaders?: string[]
+    allowCredentials?: boolean
+    maxAge?: number
+  }
+  corsAllowMethods: string
+  corsAllowHeaders: string
+  corsExposeHeaders: string
+  corsMaxAge: string
+  rateLimitStr: string
+}
+
+/**
+ * Build the frozen, variant-indexed header templates.
+ *
+ * Returns two 32-entry sets:
+ * - `regular`: the base templates.
+ * - `terminal`: every regular template with `cache-control: no-store` appended
+ *   (the header set used for terminal/error responses). Baking it in means the
+ *   steady-state error path can return a frozen array with no per-response
+ *   allocation or copy.
+ */
+export function buildBakedHeaderTemplates(params: BakedTemplateParams): {
+  regular: ReadonlyArray<ReadonlyArray<[string, string]>>
+  terminal: ReadonlyArray<ReadonlyArray<[string, string]>>
+} {
+  const {
+    securityEntries,
+    cors,
+    corsAllowMethods,
+    corsAllowHeaders,
+    corsExposeHeaders,
+    corsMaxAge,
+    rateLimitStr,
+  } = params
+
+  const regular = Object.freeze(
+    Array.from({ length: 32 }, (_, variant) => {
+      const entries: [string, string][] = [...securityEntries]
+
+      if ((variant & HV_JSON) !== 0) {
+        entries.push(['content-type', 'application/json'])
+      }
+
+      if ((variant & HV_CORS_SIMPLE) !== 0) {
+        entries.push(['vary', 'Origin'])
+        if (cors?.allowCredentials) {
+          entries.push(['access-control-allow-credentials', 'true'])
+        }
+        if (corsExposeHeaders.length > 0) {
+          entries.push(['access-control-expose-headers', corsExposeHeaders])
+        }
+      }
+
+      if ((variant & HV_CORS_PREFLIGHT) !== 0) {
+        entries.push([
+          'vary',
+          'Origin, Access-Control-Request-Method, Access-Control-Request-Headers',
+        ])
+        if (cors?.allowCredentials) {
+          entries.push(['access-control-allow-credentials', 'true'])
+        }
+        entries.push(['access-control-allow-methods', corsAllowMethods])
+        entries.push(['access-control-allow-headers', corsAllowHeaders])
+        entries.push(['access-control-max-age', corsMaxAge])
+      }
+
+      if ((variant & HV_RATE_ACTIVE) !== 0) {
+        entries.push(['ratelimit-limit', rateLimitStr])
+      }
+
+      return Object.freeze(entries)
+    }),
+  )
+
+  const terminal = Object.freeze(
+    regular.map((t) => {
+      const entries: [string, string][] = [...t, ['cache-control', 'no-store']]
+      return Object.freeze(entries)
+    }),
+  )
+
+  return { regular, terminal }
+}

package/src/ingress/headers/cors.ts

@@ -0,0 +1,44 @@
+// src/ingress/headers/cors.ts — CORS static-string computation (fast path).
+//
+// Precomputes the static parts of the CORS policy (joined allow-lists, wildcard
+// detection, credentials flag) once per handler so per-request header building
+// never re-joins arrays.
+
+/** User-facing CORS configuration. */
+export interface CorsOptions {
+  allowOrigin?: string[]
+  allowMethods?: string[]
+  allowHeaders?: string[]
+  exposeHeaders?: string[]
+  allowCredentials?: boolean
+  maxAge?: number
+}
+
+/** Precomputed, immutable CORS policy strings. */
+export interface CorsStaticStrings {
+  readonly allowMethodsJoined: string
+  readonly allowHeadersJoined: string
+  readonly exposeHeadersJoined: string
+  readonly maxAgeString: string | null
+  readonly isWildcard: boolean
+  readonly credentials: boolean
+}
+
+/** Compute the static CORS strings for a config, or `null` when disabled. */
+export function buildCorsStaticStrings(cors: CorsOptions | undefined): CorsStaticStrings | null {
+  if (!cors) return null
+
+  const isWildcard =
+    !cors.allowOrigin || cors.allowOrigin.length === 0 || cors.allowOrigin.includes('*')
+
+  return {
+    allowMethodsJoined: cors.allowMethods?.length
+      ? cors.allowMethods.join(', ')
+      : 'GET, HEAD, POST',
+    allowHeadersJoined: cors.allowHeaders?.length ? cors.allowHeaders.join(', ') : '',
+    exposeHeadersJoined: cors.exposeHeaders?.length ? cors.exposeHeaders.join(', ') : '',
+    maxAgeString: typeof cors.maxAge === 'number' ? String(cors.maxAge) : null,
+    isWildcard,
+    credentials: cors.allowCredentials === true,
+  }
+}

package/src/ingress/headers/fast-templates.ts

@@ -0,0 +1,238 @@
+// src/ingress/headers/fast-templates.ts — Header-template system (fast path).
+//
+// Precomputes, per ingress handler, the full cross product of header variants
+// (HV_* bits) → header pairs, plus the per-request builder that applies the
+// dynamic parts (origin echo, rate-limit counters, dynamic HSTS, request-id).
+//
+// NOTE: this is the fast-path (x-ratelimit-* / {"error":{...}}) template
+// builder. The pre-baked path has its own builder (./baked-templates.ts) with
+// a different wire format — do not unify them (see AGENTS.md).
+
+import {
+  HV_COUNT,
+  HV_CORS_SIMPLE,
+  HV_CORS_PREFLIGHT,
+  HV_RATE_ACTIVE,
+  HV_RATE_LIMITED,
+} from '../constants'
+import { buildCorsStaticStrings, type CorsOptions, type CorsStaticStrings } from './cors'
+import { buildHstsValue, buildSecurityPairs, type SecurityHeadersOptions } from './hsts'
+import { secondsFromMs } from '../shared'
+
+/** A single precomputed header-variant template. */
+export interface HeaderTemplate {
+  readonly entries: ReadonlyArray<readonly [string, string]>
+  readonly needsOriginEcho: boolean
+  readonly needsRateDynamic: boolean
+  readonly needsRetryAfter: boolean
+  readonly needsDynamicHsts: boolean
+}
+
+/**
+ * Fallback used only when a variant template is unexpectedly absent. All 32
+ * variants are always built, so this never serves a real response.
+ */
+const EMPTY_HEADER_TEMPLATE: HeaderTemplate = Object.freeze({
+  entries: [],
+  needsOriginEcho: false,
+  needsRateDynamic: false,
+  needsRetryAfter: false,
+  needsDynamicHsts: false,
+})
+
+/** Precomputed per-handler response context. */
+export interface ResponseBuildContext {
+  readonly templates: HeaderTemplate[]
+  readonly corsStatic: CorsStaticStrings | null
+  readonly hstsValue: string | null
+}
+
+/**
+ * Build the full response context (header templates + static CORS strings +
+ * HSTS value) for a handler configuration.
+ */
+export function buildResponseContext(options: {
+  cors?: CorsOptions
+  security?: SecurityHeadersOptions
+  https?: boolean
+  enableSecurityHeaders?: boolean
+  rateLimit?: { limit?: number }
+}): ResponseBuildContext {
+  const templates = buildHeaderTemplates(options)
+  const corsStatic = buildCorsStaticStrings(options.cors)
+  const hstsValue = buildHstsValue(options.security ?? {})
+
+  return { templates, corsStatic, hstsValue }
+}
+
+function buildHeaderTemplates(options: {
+  cors?: CorsOptions
+  security?: SecurityHeadersOptions
+  https?: boolean
+  enableSecurityHeaders?: boolean
+  rateLimit?: { limit?: number }
+}): HeaderTemplate[] {
+  const templates: HeaderTemplate[] = new Array(HV_COUNT)
+
+  const sec = options.security ?? {}
+  const securityEnabled = options.enableSecurityHeaders !== false
+  const corsStatic = buildCorsStaticStrings(options.cors)
+  const hstsValue = buildHstsValue(sec)
+  const hstsIsDynamic = options.https === undefined && hstsValue !== null
+
+  // Single source of truth for security-option → header pairs (shared with the
+  // pre-baked handlers.ts path — see buildSecurityPairs in ./hsts.ts), so a
+  // security option can never be honored on one path and ignored on the other.
+  const securityPairs = buildSecurityPairs(sec, options.https, securityEnabled)
+
+  const corsVaryPairs: Array<[string, string]> = []
+
+  if (corsStatic) {
+    corsVaryPairs.push(['vary', 'Origin'])
+
+    if (!corsStatic.isWildcard) {
+      corsVaryPairs.push(['vary', 'Access-Control-Request-Method'])
+      corsVaryPairs.push(['vary', 'Access-Control-Request-Headers'])
+    }
+  }
+
+  const corsPolicyPairs: Array<[string, string]> = []
+
+  if (corsStatic) {
+    if (corsStatic.credentials) {
+      corsPolicyPairs.push(['access-control-allow-credentials', 'true'])
+    }
+
+    if (corsStatic.exposeHeadersJoined) {
+      corsPolicyPairs.push(['access-control-expose-headers', corsStatic.exposeHeadersJoined])
+    }
+  }
+
+  const corsPreflightPairs: Array<[string, string]> = []
+
+  if (corsStatic) {
+    corsPreflightPairs.push(['access-control-allow-methods', corsStatic.allowMethodsJoined])
+
+    if (corsStatic.allowHeadersJoined) {
+      corsPreflightPairs.push(['access-control-allow-headers', corsStatic.allowHeadersJoined])
+    }
+
+    if (corsStatic.maxAgeString) {
+      corsPreflightPairs.push(['access-control-max-age', corsStatic.maxAgeString])
+    }
+  }
+
+  const rateLimitCeiling: Array<[string, string]> = []
+
+  if (options.rateLimit?.limit && options.rateLimit.limit > 0) {
+    rateLimitCeiling.push(['x-ratelimit-limit', String(options.rateLimit.limit)])
+  }
+
+  for (let variant = 0; variant < HV_COUNT; variant++) {
+    const isCorsSimple = (variant & HV_CORS_SIMPLE) !== 0
+    const isCorsPreflight = (variant & HV_CORS_PREFLIGHT) !== 0
+    const isRateActive = (variant & HV_RATE_ACTIVE) !== 0
+    const isRateLimited = (variant & HV_RATE_LIMITED) !== 0
+
+    const entries: Array<[string, string]> = []
+
+    if (securityEnabled) {
+      for (const pair of securityPairs) {
+        entries.push(pair)
+      }
+    }
+
+    for (const pair of corsVaryPairs) {
+      entries.push(pair)
+    }
+
+    if (isCorsSimple || isCorsPreflight) {
+      for (const pair of corsPolicyPairs) {
+        entries.push(pair)
+      }
+    }
+
+    if (isCorsPreflight) {
+      for (const pair of corsPreflightPairs) {
+        entries.push(pair)
+      }
+    }
+
+    if (isRateActive) {
+      for (const pair of rateLimitCeiling) {
+        entries.push(pair)
+      }
+    }
+
+    templates[variant] = {
+      entries,
+      needsOriginEcho: isCorsSimple || isCorsPreflight,
+      needsRateDynamic: isRateActive,
+      needsRetryAfter: isRateLimited,
+      needsDynamicHsts: hstsIsDynamic,
+    }
+  }
+
+  return templates
+}
+
+/**
+ * Build the response headers for a decoded result, applying the dynamic parts
+ * (request-id, origin echo, rate-limit counters, retry-after, dynamic HSTS).
+ */
+export function headersForResult(
+  ctx: ResponseBuildContext,
+  r: {
+    readonly headerVariant: number
+    readonly corsAllowed: boolean
+    readonly rateRemaining: number
+    readonly rateResetMs: number
+    readonly retryAfterMs: number
+    readonly https: boolean
+  },
+  req: Request,
+  requestId: string,
+): Headers {
+  const template =
+    ctx.templates[r.headerVariant & 0x1f] ?? ctx.templates[0] ?? EMPTY_HEADER_TEMPLATE
+
+  const headers = new Headers()
+
+  for (const [name, value] of template.entries) {
+    headers.append(name, value)
+  }
+
+  if (requestId) {
+    headers.set('x-request-id', requestId)
+  }
+
+  if (template.needsOriginEcho && r.corsAllowed && ctx.corsStatic) {
+    const origin = req.headers.get('origin')
+
+    if (origin) {
+      if (ctx.corsStatic.isWildcard && !ctx.corsStatic.credentials) {
+        headers.set('access-control-allow-origin', '*')
+      } else {
+        headers.set('access-control-allow-origin', origin)
+      }
+    }
+  }
+
+  if (template.needsRateDynamic) {
+    headers.set('x-ratelimit-remaining', String(Math.max(0, r.rateRemaining)))
+
+    if (r.rateResetMs > 0) {
+      headers.set('x-ratelimit-reset', String(secondsFromMs(r.rateResetMs)))
+    }
+  }
+
+  if (template.needsRetryAfter && r.retryAfterMs > 0) {
+    headers.set('retry-after', String(Math.max(1, secondsFromMs(r.retryAfterMs))))
+  }
+
+  if (template.needsDynamicHsts && r.https && ctx.hstsValue) {
+    headers.set('strict-transport-security', ctx.hstsValue)
+  }
+
+  return headers
+}

package/src/ingress/headers/hsts.ts

@@ -0,0 +1,83 @@
+// src/ingress/headers/hsts.ts — Strict-Transport-Security value builder
+// (fast path).
+
+/** User-facing security-headers configuration. */
+export interface SecurityHeadersOptions {
+  contentSecurityPolicy?: string
+  hsts?: boolean
+  hstsMaxAge?: number
+  hstsIncludeSubdomains?: boolean
+  hstsPreload?: boolean
+  frameOptions?: string
+  nosniff?: boolean
+  referrerPolicy?: string
+  coep?: string
+  coop?: string
+  corp?: string
+  xssProtection?: string
+}
+
+/** Build the HSTS header value, or `null` when HSTS is not configured. */
+export function buildHstsValue(sec: SecurityHeadersOptions): string | null {
+  const wantHsts =
+    sec.hsts === true ||
+    sec.hstsMaxAge !== undefined ||
+    sec.hstsIncludeSubdomains === true ||
+    sec.hstsPreload === true
+
+  if (!wantHsts) return null
+
+  const maxAge = sec.hstsMaxAge ?? 31_536_000
+  let value = `max-age=${maxAge}`
+
+  if (sec.hstsIncludeSubdomains) value += '; includeSubDomains'
+  if (sec.hstsPreload) value += '; preload'
+
+  return value
+}
+
+/**
+ * Convert structured `security` options into ordered `[name, value][]` pairs.
+ *
+ * Shared by BOTH header-template paths (`fast-templates.ts` and the pre-baked
+ * `handlers.ts`) so a security option is honored consistently — it can never
+ * be applied on one path and silently ignored on the other (the historic
+ * "security-preheat gotcha"). `https === true` gates the static HSTS pair
+ * (dynamic HSTS — `https` undefined — is handled per-request by the fast-path
+ * response builder); `enabled === false` yields no pairs.
+ */
+export function buildSecurityPairs(
+  security: SecurityHeadersOptions | undefined,
+  https: boolean | undefined,
+  enabled: boolean,
+): Array<[string, string]> {
+  if (!enabled) return []
+  const sec = security ?? {}
+  const pairs: Array<[string, string]> = []
+
+  if (sec.nosniff !== false) {
+    pairs.push(['x-content-type-options', 'nosniff'])
+  }
+  pairs.push(['x-frame-options', sec.frameOptions ?? 'DENY'])
+  pairs.push(['referrer-policy', sec.referrerPolicy ?? 'no-referrer'])
+  if (sec.xssProtection) {
+    pairs.push(['x-xss-protection', sec.xssProtection])
+  }
+  if (sec.contentSecurityPolicy) {
+    pairs.push(['content-security-policy', sec.contentSecurityPolicy])
+  }
+  if (sec.coep) {
+    pairs.push(['cross-origin-embedder-policy', sec.coep])
+  }
+  if (sec.coop) {
+    pairs.push(['cross-origin-opener-policy', sec.coop])
+  }
+  if (sec.corp) {
+    pairs.push(['cross-origin-resource-policy', sec.corp])
+  }
+  const hstsValue = buildHstsValue(sec)
+  if (hstsValue !== null && https === true) {
+    pairs.push(['strict-transport-security', hstsValue])
+  }
+  return pairs
+}

package/src/ingress/health.ts

@@ -0,0 +1,67 @@
+// src/ingress/health.ts — Liveness / readiness / health probe route factories.
+//
+// Enterprise-grade operators need orchestrator probes (Kubernetes `livenessProbe`
+// / `readinessProbe`). These factories return route handlers compatible with the
+// pre-baked route spec — serve them from `createIngressServer` (Bun) or
+// `createIngressServerNode` (Node):
+//
+//   createIngressServer({ routes: {
+//     "/healthz": { read: livenessHandler() },
+//     "/readyz":  { read: readinessHandler(async () => db.ping() === "ok") },
+//     "/livez":   { read: healthHandler() },
+//   }});
+//
+// The liveness probe NEVER touches dependencies (process alive? -> 200).
+// The readiness probe runs the optional `check` (deps up? -> 200/503).
+// The health probe is an alias of liveness (process up) plus optional check.
+
+export interface ReadinessResult {
+  status: number
+  body: string
+}
+
+function jsonResponse(status: number, body: Record<string, unknown>): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+  })
+}
+
+/**
+ * Liveness probe: `200 {"status":"ok"}` as long as the process is alive.
+ * Never touches dependencies.
+ */
+export function livenessHandler() {
+  return (_req: Request): Response => jsonResponse(200, { status: 'ok' })
+}
+
+/**
+ * Readiness probe: runs the optional async `check` (dependency readiness).
+ * Returns `200 {"status":"ready"}` when the check passes (or no check is
+ * given), `503 {"status":"not_ready"}` when it throws or returns false.
+ */
+export function readinessHandler(check?: () => boolean | Promise<boolean>) {
+  return async (_req: Request): Promise<Response> => {
+    if (!check) return jsonResponse(200, { status: 'ready' })
+    try {
+      const ok = await check()
+      return ok
+        ? jsonResponse(200, { status: 'ready' })
+        : jsonResponse(503, { status: 'not_ready' })
+    } catch (err) {
+      return jsonResponse(503, {
+        status: 'not_ready',
+        error: err instanceof Error ? err.message : String(err),
+      })
+    }
+  }
+}
+
+/**
+ * Combined health probe: liveness by default, plus an optional readiness
+ * `check`. When a `check` is provided the response is 503 on failure
+ * (readiness semantics), otherwise always 200.
+ */
+export function healthHandler(check?: () => boolean | Promise<boolean>) {
+  return check ? readinessHandler(check) : livenessHandler()
+}