castrum 0.9.7 → 0.9.9

package/src/ingress/routes/echo.ts

@@ -1,5 +1,6 @@
 // src/ingress/routes/echo.ts — Pre-baked echo handler.
 
+import { abortResponse, isAbortError } from '../abort'
 import { readBodyWithLimit } from '../body'
 import { HV_JSON } from '../constants'
 import { ERROR_BODIES } from '../response/error-bodies'
@@ -7,9 +8,40 @@ import { DEFAULT_BODY_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES, secondsFromMs } from '
 import type { OptimizedIngressHandler } from '../types'
 import { type BakedHandlerOptions, resolveIp } from './common'
 
+/**
+ * Content types safe to echo back for an attacker-supplied body. Anything else
+ * — notably `text/html`, `application/xhtml+xml`, `image/svg+xml` and XML — is
+ * coerced to `application/octet-stream`: reflecting an active type would let a
+ * `POST /echo` execute the request body as script in a browser.
+ */
+const SAFE_ECHO_CONTENT_TYPES = new Set([
+  'application/json',
+  'application/octet-stream',
+  'text/plain',
+])
+
+/** Lowercased media type with parameters stripped (`text/html; charset=x` → `text/html`). */
+function echoMediaTypeOf(contentType: string): string {
+  const semi = contentType.indexOf(';')
+  return (semi >= 0 ? contentType.slice(0, semi) : contentType).trim().toLowerCase()
+}
+
+/**
+ * Coerce a client Content-Type into a type that is safe to echo back.
+ *
+ * @param contentType - The raw request `Content-Type` header value.
+ * @returns The value unchanged when it is a safe non-active type, else
+ *   `application/octet-stream`.
+ */
+export function safeEchoContentType(contentType: string): string {
+  return SAFE_ECHO_CONTENT_TYPES.has(echoMediaTypeOf(contentType))
+    ? contentType
+    : 'application/octet-stream'
+}
+
 /**
  * Pre-baked echo handler: streams the request body back with the client's
- * Content-Type, bounded by `maxBodyBytes`.
+ * Content-Type (coerced to a non-active type), bounded by `maxBodyBytes`.
  */
 export function echoHandler(
   ingress: OptimizedIngressHandler,
@@ -22,6 +54,8 @@ export function echoHandler(
   return async (req, srv) => {
     const ip = resolveIp(req, srv, opts)
 
+    if (req.signal?.aborted) return abortResponse()
+
     const prep = ingress.run<{
       terminal?: Response
       headers?: ReadonlyArray<[string, string]>
@@ -48,9 +82,24 @@ export function echoHandler(
 
     if (prep.terminal) return prep.terminal
 
+    // The client may have disconnected while the native prep ran.
+    if (req.signal?.aborted) return abortResponse()
+
     const baseHeaders: ReadonlyArray<[string, string]> = prep.headers ?? []
 
-    const requestedContentType = req.headers.get('content-type') ?? 'application/octet-stream'
+    const requestedContentType = safeEchoContentType(
+      req.headers.get('content-type') ?? 'application/octet-stream',
+    )
+
+    // Content-Type + `nosniff` (unless the security config already emitted it),
+    // so the echoed body can never be sniffed into an active type.
+    const withEchoHeaders = (contentType: string): [string, string][] => {
+      const headers = ingress.withContentType(baseHeaders, contentType)
+      if (!headers.some(([name]) => name.toLowerCase() === 'x-content-type-options')) {
+        headers.push(['x-content-type-options', 'nosniff'])
+      }
+      return headers
+    }
 
     const contentLengthHeader = req.headers.get('content-length')
     const contentLength = contentLengthHeader === null ? NaN : Number(contentLengthHeader)
@@ -59,20 +108,20 @@ export function echoHandler(
       if (contentLength > maxBodyBytes) {
         return new Response(ERROR_BODIES.body_too_large, {
           status: 413,
-          headers: ingress.withContentType(baseHeaders, 'application/json'),
+          headers: withEchoHeaders('application/json'),
         })
       }
 
       if (contentLength <= 0 || req.body === null) {
         return new Response(null, {
           status: 200,
-          headers: ingress.withContentType(baseHeaders, requestedContentType),
+          headers: withEchoHeaders(requestedContentType),
         })
       }
 
       return new Response(req.body, {
         status: 200,
-        headers: ingress.withContentType(baseHeaders, requestedContentType),
+        headers: withEchoHeaders(requestedContentType),
       })
     }
 
@@ -82,11 +131,15 @@ export function echoHandler(
       // oversized or trickling body before rejecting it.
       const bodyBytes = await readBodyWithLimit(req, maxBodyBytes, true, bodyTimeoutMs)
 
+      // Disconnect during the read must not be answered with a body.
+      if (req.signal?.aborted) return abortResponse()
+
       return new Response(bodyBytes.byteLength > 0 ? bodyBytes : null, {
         status: 200,
-        headers: ingress.withContentType(baseHeaders, requestedContentType),
+        headers: withEchoHeaders(requestedContentType),
       })
     } catch (err) {
+      if (isAbortError(err)) return abortResponse()
       const code = (err as { code?: string } | null)?.code
       const isTooLarge = code === 'BODY_TOO_LARGE'
       const isTimeout = code === 'REQUEST_TIMEOUT'
@@ -99,7 +152,7 @@ export function echoHandler(
             : ERROR_BODIES.bad_request,
         {
           status: isTooLarge ? 413 : isTimeout ? 408 : 400,
-          headers: ingress.withContentType(baseHeaders, 'application/json'),
+          headers: withEchoHeaders('application/json'),
         },
       )
     }

package/src/ingress/routes/json-write.ts

@@ -2,6 +2,7 @@
 // (POST/PUT/PATCH).
 
 import { decodeUtf8 } from '../../shared/codec'
+import { abortResponse, isAbortError } from '../abort'
 import { readBodyWithLimit } from '../body'
 import { DEFAULT_BODY_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES } from '../shared'
 import type { OptimizedIngressHandler } from '../types'
@@ -23,6 +24,18 @@ function defaultJsonValid(bytes: Uint8Array): boolean {
   }
 }
 
+/**
+ * Whether a `Content-Type` header denotes JSON: the media type (the part before
+ * any parameters) is exactly `application/json`, or a `+json` structured suffix
+ * (e.g. `application/vnd.api+json`). A plain substring test would wrongly
+ * accept `text/plain; application/json`.
+ */
+function isJsonContentType(contentType: string): boolean {
+  const semi = contentType.indexOf(';')
+  const mediaType = (semi >= 0 ? contentType.slice(0, semi) : contentType).trim().toLowerCase()
+  return mediaType === 'application/json' || mediaType.endsWith('+json')
+}
+
 /**
  * Pre-baked JSON-write handler (POST/PUT/PATCH): enforces Content-Type,
  * content-length/body-size limits, JSON validity and (optionally) schema
@@ -46,21 +59,26 @@ export function jsonWriteHandler(
   return async (req, srv) => {
     const ip = resolveIp(req, srv, opts)
 
-    const contentType = req.headers.get('content-type') ?? ''
-    if (!contentType.includes('application/json')) {
-      return fallback.run(req, ip, null, (result, ctx) => {
-        const terminal = fallback.terminalResponse(req, result, ctx)
-        if (terminal) return terminal
+    // Client already gone: do no work (no content-type check, no body read,
+    // no native run). A disconnect DURING the body read is handled below.
+    if (req.signal?.aborted) return abortResponse()
 
-        return fallback.errorResponse(
+    const contentType = req.headers.get('content-type') ?? ''
+    if (!isJsonContentType(contentType)) {
+      // Always 415 for an unsupported media type. Do NOT short-circuit on the
+      // native terminal first: running with no body yields a "body required"
+      // 400, which previously masked the 415 (the native pipeline still applied
+      // rate limiting / CORS headers to this run).
+      return fallback.run(req, ip, null, (result, ctx) =>
+        fallback.errorResponse(
           req,
           result,
           415,
           'unsupported_media_type',
           'Content-Type must be application/json',
           ctx,
-        )
-      })
+        ),
+      )
     }
 
     // Content-Length / body-size enforcement happens INSIDE readBodyWithLimit
@@ -74,6 +92,9 @@ export function jsonWriteHandler(
       // never fully buffered first.
       bodyBytes = await readBodyWithLimit(req, maxBodyBytes, true, bodyTimeoutMs)
     } catch (err) {
+      // Client disconnect is NOT a bad request / timeout: return the cancelled
+      // response without running the native pipeline.
+      if (isAbortError(err)) return abortResponse()
       const code = (err as { code?: string } | null)?.code
       const isTooLarge = code === 'BODY_TOO_LARGE'
       return fallback.run(req, ip, null, (result, ctx) => {
@@ -91,6 +112,9 @@ export function jsonWriteHandler(
       })
     }
 
+    // The client may have disconnected while the body was streaming in.
+    if (req.signal?.aborted) return abortResponse()
+
     return ingress.run(req, ip, bodyBytes, (result, ctx) => {
       const terminal = ingress.terminalResponse(req, result, ctx)
       if (terminal) return terminal

package/src/ingress/routes/native.ts

@@ -21,6 +21,7 @@
 
 import { decoder } from '../../shared/bytes'
 import { generateRequestId } from '../../shared/request-id'
+import { abortResponse, isAbortError } from '../abort'
 import { readBodyWithLimit } from '../body'
 import type { NativeRoute } from '../native-route'
 import type { RouteWireResult } from '../packing/route-wire'
@@ -29,6 +30,7 @@ import { DEFAULT_BODY_TIMEOUT_MS, DEFAULT_MAX_BODY_BYTES } from '../shared'
 import type { NativeRequestContext, NativeResponder } from '../types'
 import type { BakedHandlerOptions } from './common'
 import { resolveIp } from './common'
+import { assignOwn, safeRecord } from './safe-record'
 
 /** Options for {@link nativeRouteHandler}. */
 export interface NativeRouteHandlerOptions extends BakedHandlerOptions {
@@ -36,11 +38,22 @@ export interface NativeRouteHandlerOptions extends BakedHandlerOptions {
   readBody?: boolean
 }
 
-/** The `+`-to-space / `%XX` decoding is done natively; keys are last-wins. */
-function pairsToRecord(pairs: ReadonlyArray<[string, string]>): Record<string, string> {
-  const out: Record<string, string> = {}
-  for (const [k, v] of pairs) out[k] = v
-  return out
+/**
+ * Build a prototype-safe record from native packed pairs. The `+`-to-space /
+ * `%XX` decoding is done natively; keys are last-wins. Keys are written as OWN
+ * data via {@link assignOwn}: `__proto__` is defined (never routed through the
+ * inherited setter), and other keys — including `constructor` / `prototype` —
+ * are plain own shadowing properties. The record keeps `Object.prototype`.
+ *
+ * Exported for the prototype-pollution tests.
+ *
+ * @param pairs - Decoded `[key, value]` pairs from the native route stack.
+ * @returns A record with `Object.prototype` preserved (last value wins per key).
+ */
+export function pairsToRecord(pairs: ReadonlyArray<[string, string]>): Record<string, string> {
+  const out = safeRecord()
+  for (const [k, v] of pairs) assignOwn(out, k, v)
+  return out as Record<string, string>
 }
 
 /**
@@ -78,6 +91,8 @@ export function nativeRouteHandler(
 
   return async (req, srv, _params) => {
     const ip = resolveIp(req, srv, opts)
+    // Client already gone: no request-id work, body read, or native run.
+    if (req.signal?.aborted) return abortResponse()
     const requestId = decoder.decode(generateRequestId())
 
     let body: Uint8Array | null = null
@@ -85,10 +100,14 @@ export function nativeRouteHandler(
       try {
         body = await readBodyWithLimit(req, maxBodyBytes, true, bodyTimeoutMs)
       } catch (err) {
+        // Client disconnect: the cancelled response, never a 400/408/413.
+        if (isAbortError(err)) return abortResponse()
         const code = (err as Error & { code?: string }).code
         const status = code === 'REQUEST_TIMEOUT' ? 408 : code === 'BODY_TOO_LARGE' ? 413 : 400
         return terminal(status, 'BAD_REQUEST', 'Request body read failed')
       }
+      // Disconnect while the body was streaming in.
+      if (req.signal?.aborted) return abortResponse()
     }
 
     // Extract the query substring + Cookie header (the only request inputs the

package/src/ingress/routes/options.ts

@@ -1,5 +1,6 @@
 // src/ingress/routes/options.ts — Pre-baked OPTIONS handler (CORS preflight).
 
+import { abortResponse } from '../abort'
 import type { OptimizedIngressHandler } from '../types'
 import { type BakedHandlerOptions, buildSuccessInit, resolveIp } from './common'
 
@@ -16,11 +17,14 @@ export function optionsHandler(
   ingress: OptimizedIngressHandler,
   opts: BakedHandlerOptions = {},
 ): (req: Request, srv?: unknown) => Response {
-  return (req, srv) =>
-    ingress.run<Response>(req, resolveIp(req, srv, opts), null, (result, ctx) => {
+  return (req, srv) => {
+    // Client already gone: no pipeline run, no pooled output buffer.
+    if (req.signal?.aborted) return abortResponse()
+    return ingress.run<Response>(req, resolveIp(req, srv, opts), null, (result, ctx) => {
       const terminal = ingress.terminalResponse(req, result, ctx)
       if (terminal) return terminal
 
       return new Response(null, buildSuccessInit(ingress, result, ctx, 204))
     })
+  }
 }

package/src/ingress/routes/responder.ts

@@ -16,6 +16,7 @@
 
 import { decoder } from '../../shared/bytes'
 import { generateRequestId } from '../../shared/request-id'
+import { abortResponse, isAbortError } from '../abort'
 import { readBodyWithLimit } from '../body'
 import type { BakedIngressResult } from '../decode/baked-result'
 import { errorCodeName, errorMessage } from '../errors'
@@ -45,7 +46,7 @@ export interface ResponderRouteOptions extends BakedHandlerOptions {
 }
 
 /** ignex framework security posture for terminal responses. */
-const IGNGEX_SECURITY_HEADERS: [string, string][] = [
+const IGNEX_SECURITY_HEADERS: [string, string][] = [
   ['x-frame-options', 'DENY'],
   ['x-content-type-options', 'nosniff'],
   ['referrer-policy', 'no-referrer'],
@@ -55,7 +56,7 @@ const IGNGEX_SECURITY_HEADERS: [string, string][] = [
 function buildIgngexTerminal(result: BakedIngressResult, _ctx: BakedContext): Response {
   const preflightAllowed = result.isPreflight && result.corsAllowed
   if (preflightAllowed) {
-    return new Response(null, { status: 204, headers: IGNGEX_SECURITY_HEADERS })
+    return new Response(null, { status: 204, headers: IGNEX_SECURITY_HEADERS })
   }
   const status = safeTerminalStatus(result)
   const body = JSON.stringify({
@@ -63,17 +64,30 @@ function buildIgngexTerminal(result: BakedIngressResult, _ctx: BakedContext): Re
     status,
     code: errorCodeName(result.errorCode),
   })
-  const headers = new Headers(IGNGEX_SECURITY_HEADERS)
+  const headers = new Headers(IGNEX_SECURITY_HEADERS)
   headers.set('content-type', 'application/json; charset=utf-8')
   return new Response(body, { status, headers })
 }
 
-/** Parse a `queryJson()`/`cookiesJson()` section into an object (empty on failure). */
-function parseSection(json: string): Record<string, unknown> {
+/**
+ * Parse a `queryJson()`/`cookiesJson()` section into a record (empty on
+ * failure).
+ *
+ * Prototype-safe by construction: `JSON.parse` creates `__proto__` as an OWN
+ * enumerable data property (it never invokes the setter), so the returned
+ * object keeps `Object.prototype` and carries `__proto__` as inert own data.
+ *
+ * Exported for the prototype-pollution tests.
+ *
+ * @param json - The section JSON emitted by the native pipeline.
+ * @returns The decoded object, or an empty record for a non-object / malformed
+ *   section.
+ */
+export function parseSection(json: string): Record<string, unknown> {
   try {
-    const v: unknown = JSON.parse(json)
-    return v !== null && typeof v === 'object' && !Array.isArray(v)
-      ? (v as Record<string, unknown>)
+    const parsed: unknown = JSON.parse(json)
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
       : {}
   } catch {
     return {}
@@ -97,6 +111,8 @@ export function nativeResponderRoute(
 
   return async (req, srv, _params) => {
     const ip = resolveIp(req, srv, opts)
+    // Client already gone: no request-id work, body read, or native run.
+    if (req.signal?.aborted) return abortResponse()
     // The request-id the framework surfaces (same source as the pre-baked path's
     // `ctx.requestIdHeader`): the baked result does not carry it, so generate it
     // here — the native pipeline uses the same rid for its internal frame.
@@ -109,13 +125,17 @@ export function nativeResponderRoute(
       try {
         body = await readBodyWithLimit(req, maxBodyBytes, true, bodyTimeoutMs)
       } catch (err) {
+        // Client disconnect: the cancelled response, never a 400/408/413.
+        if (isAbortError(err)) return abortResponse()
         const code = (err as Error & { code?: string }).code
         const status = code === 'REQUEST_TIMEOUT' ? 408 : code === 'BODY_TOO_LARGE' ? 413 : 400
         const payload = JSON.stringify({ error: 'Bad Request', status, code: 'BAD_REQUEST' })
-        const headers = new Headers(IGNGEX_SECURITY_HEADERS)
+        const headers = new Headers(IGNEX_SECURITY_HEADERS)
         headers.set('content-type', 'application/json; charset=utf-8')
         return new Response(payload, { status, headers })
       }
+      // Disconnect while the body was streaming in.
+      if (req.signal?.aborted) return abortResponse()
     }
 
     let terminal: Response | null = null

package/src/ingress/routes/safe-record.ts

@@ -0,0 +1,57 @@
+// src/ingress/routes/safe-record.ts — prototype-safe key assignment for
+// request-derived objects.
+//
+// PURE: no addon and no pooled-buffer state. Request keys are attacker
+// controlled, so a key of `__proto__` must not invoke the inherited setter on a
+// plain object. `assignOwn` writes `__proto__` with `Object.defineProperty` (an
+// own enumerable data property) and every other key with plain assignment,
+// which is already safe: `constructor` / `prototype` just become own shadowing
+// properties.
+//
+// Scope: this protects the RECORD itself — it keeps `Object.prototype` (so
+// `hasOwnProperty` / `instanceof Object` still work), gains an own `__proto__`
+// data key, and is never mutated through the setter. It does NOT protect a
+// consumer that blindly merges the record into another object, e.g.
+// `Object.assign({}, rec)`: the own `__proto__` key is still enumerable, so a
+// merge target's inherited setter can fire there. Such consumers must guard
+// their own merge.
+
+/** A request-derived key that would invoke the inherited `__proto__` setter. */
+const PROTO_KEY = '__proto__'
+
+/**
+ * Create an empty plain record (`Object.prototype` is preserved, so
+ * `hasOwnProperty` / `instanceof Object` keep working). Safety comes from
+ * {@link assignOwn}, not from the container.
+ *
+ * @returns A fresh, empty `Record<string, unknown>`.
+ */
+export function safeRecord(): Record<string, unknown> {
+  return {}
+}
+
+/**
+ * Assign a request-derived key as an OWN enumerable data property.
+ *
+ * Only `__proto__` is written with `Object.defineProperty` — a plain
+ * `target[key] = value` would invoke the inherited `__proto__` setter and
+ * mutate the prototype. Every other key (including `constructor` /
+ * `prototype`) uses plain assignment: faster, and it merely shadows on the
+ * object.
+ *
+ * @param target - Record to write into (normally from {@link safeRecord}).
+ * @param key - Request-derived key (may be `__proto__` / `constructor`).
+ * @param value - Request-derived value.
+ */
+export function assignOwn(target: Record<string, unknown>, key: string, value: unknown): void {
+  if (key === PROTO_KEY) {
+    Object.defineProperty(target, key, {
+      value,
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    })
+    return
+  }
+  target[key] = value
+}

package/src/ingress/server-error.ts

@@ -0,0 +1,111 @@
+// src/ingress/server-error.ts — request-handler fault containment.
+//
+// User-supplied route handlers (a raw `spec.read`, a `responder`, a `native`
+// responder) run OUTSIDE the native pipeline. On Bun a sync throw / async
+// rejection would otherwise escape to Bun's default handler (which is not
+// castrum-controlled and may surface stack/internal detail); on Node it hit a
+// local generic-500 construction. This module provides ONE masked-500 responder
+// shared by both runtimes plus a guard that contains sync throws and async
+// rejections. The response body is the pre-encoded internal error body — the
+// thrown message/stack is NEVER placed on the wire (info-leak rule).
+
+import { memoizedHeaders } from './headers/memoized-headers'
+import { ERROR_BODIES } from './response/error-bodies'
+import type { RouteHandler } from './server'
+
+/** Options for {@link createServerErrorHandler}. */
+export interface ServerErrorOptions {
+  /**
+   * Observability hook for an escaped handler error. Receives the real `Error`
+   * (unmasked — server-side only). Never throws: a failing hook is swallowed so
+   * it cannot break the masked response.
+   */
+  onError?: (info: { error: Error; request?: Request }) => void
+  /**
+   * Structured-log sink: one JSON line per escaped error (message only, no
+   * stack, no response leak). Never throws.
+   */
+  logger?: (line: string) => void
+}
+
+/** Coerce an unknown thrown value to an `Error` for the hook/logger. */
+function toError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(String(value))
+}
+
+const INTERNAL_HEADERS: readonly [string, string][] = [
+  ['content-type', 'application/json; charset=utf-8'],
+]
+
+/**
+ * Build a masked-500 responder. The returned function never throws, always
+ * answers with the pre-encoded internal error body, and runs the optional
+ * `onError`/`logger` hooks in a contained way.
+ *
+ * @param opts - Optional observability hooks.
+ * @returns A `(error, req?) => Response` responder for escaped handler errors.
+ * @example
+ * ```ts
+ * const onServerError = createServerErrorHandler({ onError: console.error })
+ * onServerError(new Error('boom')) // Response(500)
+ * ```
+ */
+export function createServerErrorHandler(
+  opts: ServerErrorOptions,
+): (error: unknown, req?: Request) => Response {
+  const headers = memoizedHeaders(INTERNAL_HEADERS)
+  return (error, req) => {
+    const err = toError(error)
+    if (opts.onError) {
+      try {
+        opts.onError({ error: err, request: req })
+      } catch {
+        // Observability must never break the response.
+      }
+    }
+    if (opts.logger) {
+      try {
+        opts.logger(
+          JSON.stringify({
+            level: 'error',
+            msg: 'unhandled_handler_error',
+            error: err.message,
+          }),
+        )
+      } catch {
+        // Logging must never break the response.
+      }
+    }
+    return new Response(ERROR_BODIES.internal, { status: 500, headers })
+  }
+}
+
+/**
+ * Wrap a route handler so a sync throw or an async rejection is contained and
+ * turned into the shared masked 500. The success path is passed through
+ * unchanged.
+ *
+ * @param handler - The route handler to guard.
+ * @param onServerError - The masked-500 responder (see
+ *   {@link createServerErrorHandler}).
+ * @returns A `RouteHandler` with the same signature and success semantics.
+ */
+export function guardRouteHandler(
+  handler: RouteHandler,
+  onServerError: (error: unknown, req?: Request) => Response,
+): RouteHandler {
+  return (req, srv, params) => {
+    try {
+      const out = handler(req, srv, params)
+      // Duck-type thenables (cross-realm Promises/custom thenables fail
+      // `instanceof Promise`). A `Response` never exposes `then`.
+      const thenable = out as Promise<Response> | null | undefined
+      if (thenable !== null && thenable !== undefined && typeof thenable.then === 'function') {
+        return thenable.catch((e) => onServerError(e, req))
+      }
+      return out
+    } catch (e) {
+      return onServerError(e, req)
+    }
+  }
+}