ingenium 0.0.1

package/src/plugin/types.ts

@@ -0,0 +1,189 @@
+import type { IngeniumContext } from '../context/context.ts'
+import type { IngeniumHandler, IngeniumMiddleware } from '../middleware/types.ts'
+import type { RouteBuilder, Router } from '../router/router.ts'
+import type { HttpMethod } from '../router/types.ts'
+
+/**
+ * Payload fired to `onRoute` hooks each time a route is registered into the
+ * trie during composition. Plugins can observe — they MUST NOT mutate.
+ */
+export interface RegistrationEvent {
+  /** HTTP method (uppercase). */
+  readonly method: HttpMethod
+  /** Final composed route path (after all prefixes). */
+  readonly path: string
+}
+
+/**
+ * The shape a plugin can rely on regardless of whether it's registered onto
+ * the root `IngeniumApp` or onto a `ScopedApp` (via `app.scope(...).register(...)`).
+ *
+ * Both root and scoped registration targets implement this interface. Plugins
+ * that previously took `(app: IngeniumApp, opts)` are source-compatible:
+ * `IngeniumApp` implements every member of `PluginTarget`. The only practical
+ * difference at the call site is that `target.scope(...)`, `target.use(mw)`,
+ * and the verb methods become prefix-relative when `target` is a `ScopedApp`.
+ *
+ * # Scoping semantics for plugin authors
+ *
+ * - `target.use(mw)` / `target.use(subprefix, mw)` — middleware is scoped to
+ *   the target's prefix at compose time. On the root, this is "global". In a
+ *   scope, it's "applies only to paths under the scope's prefix".
+ * - `target.get/post/...` and `target.method(...)` — paths are prefix-
+ *   relative; the scope prepends its absolute prefix at registration time.
+ * - `target.register(plugin, opts)` — runs the plugin against the SAME
+ *   target. Nested scopes compose as expected.
+ * - `target.hooks` — lifecycle hooks are GLOBAL even when called inside a
+ *   scope. Hooks fire per request, before route dispatch; making them
+ *   scope-aware would require runtime path-prefix checks on every request.
+ *   If a plugin needs scope-aware behavior, it should inspect `ctx.path`
+ *   inside the hook body.
+ * - `target.decorate(...)` / `target.decorateRequest(...)` — decorators are
+ *   GLOBAL even when called inside a scope (see {@link IngeniumPlugin} JSDoc
+ *   for the rationale). `ScopedApp.decorate` emits a one-shot
+ *   `process.emitWarning` in non-production environments to surface this
+ *   footgun.
+ */
+export interface PluginTarget {
+  /** Lifecycle hooks (global — see interface JSDoc). */
+  readonly hooks: Hooks
+
+  /** Add middleware that runs for every request below this target. */
+  use(mw: IngeniumMiddleware): this
+  /** Mount middleware or a sub-router at a path prefix (relative to this target). */
+  use(prefix: string, mw: IngeniumMiddleware | Router): this
+
+  /** Register a route under any HTTP method (path is relative to this target). */
+  method(method: HttpMethod, path: string, handler: IngeniumHandler): this
+  method(
+    method: HttpMethod,
+    path: string,
+    ...args: [...IngeniumMiddleware[], IngeniumHandler]
+  ): this
+
+  /**
+   * Chainable per-path builder. Same path-joining rules as the bare verbs —
+   * inside a `ScopedApp`, the builder's emitted routes are prefix-relative.
+   */
+  route<P extends string>(path: P): RouteBuilder<P>
+
+  /** Convenience verb shortcuts (paths are relative to this target). */
+  get(path: string, handler: IngeniumHandler): this
+  get(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this
+  post(path: string, handler: IngeniumHandler): this
+  post(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this
+  put(path: string, handler: IngeniumHandler): this
+  put(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this
+  patch(path: string, handler: IngeniumHandler): this
+  patch(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this
+  delete(path: string, handler: IngeniumHandler): this
+  delete(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this
+  head(path: string, handler: IngeniumHandler): this
+  head(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this
+  options(path: string, handler: IngeniumHandler): this
+  options(path: string, ...args: [...IngeniumMiddleware[], IngeniumHandler]): this
+
+  /**
+   * Pre-handler / post-handler middleware (paths are relative to this target).
+   * Inside a `ScopedApp` these are confined to the scope prefix — `s.before(h)`
+   * only fires for requests under the scope, mirroring `s.use`.
+   */
+  before(handler: IngeniumMiddleware): this
+  before(pattern: string, handler: IngeniumMiddleware): this
+  after(handler: IngeniumMiddleware): this
+  after(pattern: string, handler: IngeniumMiddleware): this
+
+  /** Decorator registration. NOTE: GLOBAL even when called inside a scope. */
+  decorate<T>(name: string, factory: LazyDecorator<T>): this
+  decorateRequest<T>(name: string, factory: EagerDecorator<T>): this
+
+  /**
+   * Register a plugin against this target. Plugins may be async and the
+   * caller should `await` the returned promise.
+   */
+  register<O>(plugin: IngeniumPlugin<O>, opts: O): Promise<this>
+  register(plugin: IngeniumPlugin<void>): Promise<this>
+
+  /**
+   * Open a nested registration scope. All registrations inside `registrar`
+   * are prefix-relative to `prefix` (and inherit any outer scope prefix).
+   */
+  scope(prefix: string, registrar: (scope: PluginTarget) => void): this | Promise<this>
+}
+
+/**
+ * A plugin is a function that mutates a registration target: it can register
+ * routes, middleware, decorators, and hook handlers. Plugins are registered
+ * before `compose()` runs; they may be async.
+ *
+ * The `target` parameter is `PluginTarget` — implemented by both `IngeniumApp`
+ * (the root) and `ScopedApp` (created by `app.scope(prefix, ...)`). When a
+ * plugin is registered inside a scope, its `target.use(...)` / `target.get(...)`
+ * are automatically prefix-scoped at compose time.
+ *
+ * # Scoped-decorator caveat (V1)
+ *
+ * Decorators (`target.decorate`, `target.decorateRequest`) install onto the
+ * pooled `IngeniumContext` at request start; the registry is per-app, not
+ * per-path. That means a plugin registered inside `app.scope('/api', ...)`
+ * that calls `target.decorate('user', ...)` will decorate EVERY request,
+ * not just `/api/*` requests. The first such call inside a scope emits a
+ * `process.emitWarning` in non-production environments. Plugin authors who
+ * want per-scope decorator behavior should make the decorator's factory
+ * inspect `ctx.path` and return a sentinel for out-of-scope requests.
+ *
+ * @example
+ * const myPlugin: IngeniumPlugin<{ secret: string }> = async (target, opts) => {
+ *   target.hooks.onRequest((ctx) => { ... })
+ *   target.use((ctx, next) => next())          // scoped if target is a ScopedApp
+ *   target.get('/whoami', (ctx) => ...)        // path is relative to scope
+ * }
+ *
+ * await app.register(myPlugin, { secret: 'shh' })
+ * app.scope('/api', (s) => s.register(myPlugin, { secret: 'shh' }))
+ */
+export type IngeniumPlugin<O = void> = (
+  target: PluginTarget,
+  opts: O,
+) => void | Promise<void>
+
+/** Fires once per route as the trie is built (during `compose()`). */
+export type OnRouteHook = (registration: RegistrationEvent) => void
+
+/** Fires before composition runs. May be async. */
+export type OnComposeHook = () => void | Promise<void>
+
+/** Fires at the start of every request, before middleware dispatch. */
+export type OnRequestHook = (ctx: IngeniumContext) => void | Promise<void>
+
+/** Fires after the handler resolves successfully. */
+export type OnResponseHook = (ctx: IngeniumContext) => void | Promise<void>
+
+/**
+ * Fires when the handler chain throws. OBSERVATION ONLY — the framework's
+ * error boundary still owns the response. Throwing inside an `onError` hook
+ * is swallowed; this is by design so observers can't mask the original error.
+ */
+export type OnErrorHook = (err: unknown, ctx: IngeniumContext) => void | Promise<void>
+
+/**
+ * Public hooks API exposed on `app.hooks`. Each method appends a listener;
+ * listeners are invoked in registration order, sequentially (`await`-ed in
+ * a loop) for predictable ordering.
+ */
+export interface Hooks {
+  onRoute(fn: OnRouteHook): void
+  onCompose(fn: OnComposeHook): void
+  onRequest(fn: OnRequestHook): void
+  onResponse(fn: OnResponseHook): void
+  onError(fn: OnErrorHook): void
+}
+
+/** Lazy decorator — computed on first access, then cached on the ctx. */
+export type LazyDecorator<T = unknown> = (ctx: IngeniumContext) => T
+
+/** Eager decorator — evaluated at request start, value assigned directly. */
+export type EagerDecorator<T = unknown> = (ctx: IngeniumContext) => T
+
+/** Generic decorator factory shape (covers both lazy and eager). */
+export type Decorator<T = unknown> = (ctx: IngeniumContext) => T

package/src/problem/middleware.ts

@@ -0,0 +1,55 @@
+import type { IngeniumMiddleware } from '../middleware/types.ts'
+import { toProblemDetails } from './serialize.ts'
+import type {
+  ProblemDetailsOptions,
+  ResolvedProblemDetailsOptions,
+} from './types.ts'
+
+const PROBLEM_CONTENT_TYPE = 'application/problem+json; charset=utf-8'
+
+/**
+ * RFC 7807 Problem Details middleware. Wraps downstream handlers in a
+ * try/catch and serializes any `IngeniumError` (or unknown error) as
+ * `application/problem+json` instead of the framework's default
+ * `{ error, code, fields? }` shape.
+ *
+ * Composition notes:
+ * - This sits as a regular middleware in front of user handlers, NOT in
+ *   place of `app.onError`. If `app.onError` is configured AND it re-throws
+ *   (or the user handler throws past the onError), this middleware catches
+ *   the error before it reaches the default boundary.
+ * - Composes cleanly with other middleware (e.g. idempotency) — the
+ *   try/catch is the only thing it does on the way out.
+ *
+ * @example
+ *   app.use(ingenium.problemDetails({
+ *     typeBaseUrl: 'https://api.example.com/errors/',
+ *     includeStack: process.env.NODE_ENV !== 'production',
+ *   }))
+ */
+export function problemDetailsMiddleware(opts: ProblemDetailsOptions = {}): IngeniumMiddleware {
+  const resolved: ResolvedProblemDetailsOptions = {
+    typeBaseUrl: opts.typeBaseUrl ?? 'about:blank',
+    includeStack: opts.includeStack ?? false,
+    instance: opts.instance ?? ((ctx) => ctx.path),
+  }
+
+  return async (ctx, next) => {
+    try {
+      await next()
+    } catch (err) {
+      // If something downstream already wrote a response (e.g. handler
+      // partially wrote then threw), don't clobber it.
+      if (ctx._written) throw err
+
+      const problem = toProblemDetails(err, resolved, ctx)
+
+      // Force the problem+json content-type even if a handler pre-set
+      // application/json on the context.
+      ctx.set('content-type', PROBLEM_CONTENT_TYPE)
+      ctx._statusCode = problem.status
+      ctx._body = { kind: 'string', data: JSON.stringify(problem) }
+      ctx._written = true
+    }
+  }
+}

package/src/problem/serialize.ts

@@ -0,0 +1,121 @@
+import type { IngeniumContext } from '../context/context.ts'
+import {
+  IngeniumError,
+  IngeniumMethodNotAllowedError,
+  IngeniumValidationError,
+} from '../errors.ts'
+import type { ProblemDetails, ResolvedProblemDetailsOptions } from './types.ts'
+
+/**
+ * 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.
+ */
+const TITLES: Readonly<Record<string, string>> = Object.freeze({
+  NOT_FOUND: 'Not Found',
+  UNAUTHORIZED: 'Unauthorized',
+  METHOD_NOT_ALLOWED: 'Method Not Allowed',
+  PAYLOAD_TOO_LARGE: 'Payload Too Large',
+  VALIDATION_FAILED: 'Validation Failed',
+  BAD_REQUEST: 'Bad Request',
+  RATE_LIMITED: 'Too Many Requests',
+  INTERNAL_ERROR: 'Internal Server Error',
+})
+
+/** Generic HTTP status reason phrases for common codes (fallback for unknown errors). */
+const STATUS_REASON: Readonly<Record<number, string>> = Object.freeze({
+  400: 'Bad Request',
+  401: 'Unauthorized',
+  403: 'Forbidden',
+  404: 'Not Found',
+  405: 'Method Not Allowed',
+  409: 'Conflict',
+  413: 'Payload Too Large',
+  415: 'Unsupported Media Type',
+  422: 'Unprocessable Entity',
+  429: 'Too Many Requests',
+  500: 'Internal Server Error',
+  502: 'Bad Gateway',
+  503: 'Service Unavailable',
+  504: 'Gateway Timeout',
+})
+
+/** UPPER_SNAKE_CASE → kebab-case path segment for `type` URIs. */
+function codeToSlug(code: string): string {
+  return code.toLowerCase().replace(/_/g, '-')
+}
+
+/**
+ * Build the `type` field. Returns `'about:blank'` (RFC 7807 default) when
+ * no `typeBaseUrl` is configured, otherwise prefixes the slugified code.
+ */
+function buildType(code: string, baseUrl: string): string {
+  if (baseUrl === 'about:blank' || baseUrl === '') return 'about:blank'
+  // Avoid double-slash when caller forgot the trailing slash.
+  return baseUrl.endsWith('/')
+    ? `${baseUrl}${codeToSlug(code)}`
+    : `${baseUrl}/${codeToSlug(code)}`
+}
+
+/**
+ * Convert a thrown value into an RFC 7807 ProblemDetails object. Handles
+ * `IngeniumError` and its subclasses with rich extensions; unknown errors are
+ * reported as a generic 500 with `type: 'about:blank'`.
+ *
+ * Side effect: for `IngeniumMethodNotAllowedError`, the `Allow` header is set
+ * on the response so it matches the framework's default boundary behavior.
+ */
+export function toProblemDetails(
+  err: unknown,
+  opts: ResolvedProblemDetailsOptions,
+  ctx: IngeniumContext,
+): ProblemDetails {
+  if (err instanceof IngeniumError) {
+    const title = TITLES[err.code] ?? STATUS_REASON[err.statusCode] ?? err.message
+    const problem: ProblemDetails = {
+      type: buildType(err.code, opts.typeBaseUrl),
+      title,
+      status: err.statusCode,
+      detail: err.message,
+    }
+
+    const instance = opts.instance(ctx)
+    if (instance !== undefined) problem.instance = instance
+
+    // Carry the framework error code as a non-standard extension so clients
+    // can program against it without parsing the `type` URI.
+    problem.code = err.code
+
+    if (err instanceof IngeniumValidationError) {
+      problem.fields = err.fields
+    }
+
+    if (err instanceof IngeniumMethodNotAllowedError) {
+      problem.allowed = err.allowed
+      ctx.set('allow', err.allowed.join(', '))
+    }
+
+    if (opts.includeStack && typeof err.stack === 'string') {
+      problem.stack = err.stack
+    }
+
+    return problem
+  }
+
+  // Unknown error — generic 500.
+  const message = (err as Error)?.message
+  const problem: ProblemDetails = {
+    type: 'about:blank',
+    title: STATUS_REASON[500]!,
+    status: 500,
+    detail: typeof message === 'string' && message.length > 0 ? message : 'Internal Server Error',
+  }
+
+  const instance = opts.instance(ctx)
+  if (instance !== undefined) problem.instance = instance
+
+  if (opts.includeStack && err instanceof Error && typeof err.stack === 'string') {
+    problem.stack = err.stack
+  }
+
+  return problem
+}

package/src/problem/types.ts

@@ -0,0 +1,68 @@
+import type { IngeniumContext } from '../context/context.ts'
+
+/**
+ * RFC 7807 Problem Details for HTTP APIs.
+ *
+ * The five standard members are reserved by the spec; arbitrary additional
+ * extension members are permitted via the index signature. See
+ * https://datatracker.ietf.org/doc/html/rfc7807#section-3.1.
+ */
+export interface ProblemDetails {
+  /**
+   * A URI reference that identifies the problem type. When dereferenced it
+   * SHOULD provide human-readable documentation. Default per spec is
+   * `'about:blank'`, indicating that no specific problem-type URL exists
+   * (in which case `title` is conventionally the HTTP status reason phrase).
+   */
+  type: string
+
+  /**
+   * A short, human-readable summary of the problem type. SHOULD NOT change
+   * from occurrence to occurrence (use `detail` for instance-specific info).
+   */
+  title: string
+
+  /** HTTP status code generated by the origin server. */
+  status: number
+
+  /** Human-readable explanation specific to this occurrence of the problem. */
+  detail?: string
+
+  /** A URI reference identifying the specific occurrence of the problem. */
+  instance?: string
+
+  /** RFC 7807 permits arbitrary extension members. */
+  [key: string]: unknown
+}
+
+/** Options accepted by `ingenium.problemDetails(...)`. */
+export interface ProblemDetailsOptions {
+  /**
+   * Prefix used when constructing the `type` URI from an error's `code`.
+   * Example: `'https://api.example.com/errors/'` + `NOT_FOUND` →
+   * `'https://api.example.com/errors/not-found'`.
+   *
+   * Default `'about:blank'` (per spec — no problem-specific docs URL).
+   */
+  typeBaseUrl?: string
+
+  /**
+   * If true, attaches the error's `stack` as an extension member. Useful in
+   * development; never enable in production — stack traces leak source paths
+   * and internal structure. Default `false`.
+   */
+  includeStack?: boolean
+
+  /**
+   * Override how the `instance` URI is derived. Default returns `ctx.path`.
+   * Return `undefined` to omit the field entirely.
+   */
+  instance?: (ctx: IngeniumContext) => string | undefined
+}
+
+/** Options after defaults have been applied. Internal use. */
+export interface ResolvedProblemDetailsOptions {
+  typeBaseUrl: string
+  includeStack: boolean
+  instance: (ctx: IngeniumContext) => string | undefined
+}

package/src/proxy/trust.ts

@@ -0,0 +1,247 @@
+/**
+ * Trust-proxy resolution for `X-Forwarded-*` headers.
+ *
+ * Mirrors Express's `app.set('trust proxy', ...)` semantics:
+ * - `false` (default): never trust XFF — `ctx.ip` always reflects the immediate
+ *   socket peer.
+ * - `true`: trust the entire `X-Forwarded-For` chain — last entry wins.
+ * - `number n`: trust `n` upstream hops — return chain entry `n` from the right.
+ * - `string` (single CIDR/IP/keyword) or `string[]` (list): trust connections
+ *   from these addresses; walk the chain skipping trusted IPs.
+ * - `(ip, hopIdx) => boolean`: custom predicate, called per chain entry.
+ *
+ * Supported keywords: `'loopback'` (127.0.0.0/8, ::1), `'linklocal'`
+ * (169.254.0.0/16, fe80::/10), `'uniquelocal'` (10/8, 172.16/12, 192.168/16,
+ * fc00::/7). CIDRs accepted in IPv4 dotted (`10.0.0.0/8`) and IPv6
+ * (`fc00::/7`) form. Single addresses without `/` match exactly.
+ */
+
+export type TrustProxy =
+  | boolean
+  | number
+  | string
+  | string[]
+  | ((ip: string, hopIdx: number) => boolean)
+
+export interface ForwardedInfo {
+  /** The resolved client IP after walking the trusted hop chain. */
+  ip: string
+  /** Full forwarded chain, left-to-right (closest to client first), plus the immediate peer at the end. */
+  ips: readonly string[]
+  /** Best-effort protocol: `http` or `https`. */
+  protocol: 'http' | 'https'
+  /** Best-effort hostname (no port). */
+  hostname: string
+}
+
+/**
+ * Resolve forwarded info from raw headers + the immediate socket peer.
+ *
+ * @param trust          The `trustProxy` configuration.
+ * @param remoteAddress  The socket-level peer address (always present).
+ * @param headers        Lowercased request headers (Node convention).
+ * @param defaultProtocol The protocol of the underlying transport (`http` for `node:http`,
+ *                        `https` for TLS, `http` for h2c, `https` for h2/TLS).
+ */
+export function resolveForwarded(
+  trust: TrustProxy,
+  remoteAddress: string,
+  headers: Readonly<Record<string, string | string[] | undefined>>,
+  defaultProtocol: 'http' | 'https' = 'http',
+): ForwardedInfo {
+  if (trust === false || trust === 0 || trust === undefined || trust === null) {
+    return {
+      ip: remoteAddress,
+      ips: [remoteAddress],
+      protocol: defaultProtocol,
+      hostname: parseHost(headers, false),
+    }
+  }
+
+  const xffHeader = headers['x-forwarded-for']
+  const xff = parseHeaderList(xffHeader)
+  // Append the immediate peer at the end so the chain is complete.
+  const fullChain: string[] = [...xff, remoteAddress]
+
+  let trustedIp = remoteAddress
+  if (typeof trust === 'boolean' && trust === true) {
+    trustedIp = fullChain[0] ?? remoteAddress
+  } else if (typeof trust === 'number') {
+    // Skip `trust` hops from the right (the rightmost is the immediate peer).
+    const idx = Math.max(0, fullChain.length - 1 - trust)
+    trustedIp = fullChain[idx] ?? remoteAddress
+  } else if (typeof trust === 'function') {
+    trustedIp = walkChainPredicate(fullChain, trust)
+  } else {
+    const matchers = typeof trust === 'string' ? [trust] : trust
+    const compiled = matchers.map(compileTrustEntry)
+    const predicate = (ip: string): boolean => compiled.some((m) => m(ip))
+    trustedIp = walkChainPredicate(fullChain, (ip) => predicate(ip))
+  }
+
+  const protoHeader = headers['x-forwarded-proto']
+  const proto = parseHeaderList(protoHeader)[0]?.toLowerCase()
+  const protocol: 'http' | 'https' = proto === 'https' ? 'https' : proto === 'http' ? 'http' : defaultProtocol
+
+  const hostHeader = headers['x-forwarded-host']
+  const xfhFirst = parseHeaderList(hostHeader)[0]
+  const hostname = xfhFirst ? stripPort(xfhFirst) : parseHost(headers, false)
+
+  return { ip: trustedIp, ips: fullChain, protocol, hostname }
+}
+
+/**
+ * Walk the chain right-to-left while the predicate keeps trusting the
+ * current hop. Return the first untrusted address encountered (the real
+ * client). If the predicate trusts every hop, return the leftmost entry.
+ */
+function walkChainPredicate(
+  chain: readonly string[],
+  isTrusted: (ip: string, hopIdx: number) => boolean,
+): string {
+  for (let i = chain.length - 1, hop = 0; i >= 0; i--, hop++) {
+    const ip = chain[i]!
+    if (!isTrusted(ip, hop)) return ip
+  }
+  return chain[0] ?? ''
+}
+
+/** Parse a comma-separated header (or array) into a trimmed list. */
+function parseHeaderList(value: string | string[] | undefined): string[] {
+  if (!value) return []
+  const flat = Array.isArray(value) ? value.join(',') : value
+  return flat
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0)
+}
+
+function parseHost(
+  headers: Readonly<Record<string, string | string[] | undefined>>,
+  trustForwarded: boolean,
+): string {
+  if (trustForwarded) {
+    const xfh = parseHeaderList(headers['x-forwarded-host'])[0]
+    if (xfh) return stripPort(xfh)
+  }
+  const host = headers['host']
+  const flat = Array.isArray(host) ? host[0] : host
+  if (!flat) return 'localhost'
+  return stripPort(flat)
+}
+
+function stripPort(host: string): string {
+  // IPv6 literals are bracketed: [::1]:8080
+  if (host[0] === '[') {
+    const end = host.indexOf(']')
+    return end >= 0 ? host.slice(1, end) : host
+  }
+  const idx = host.lastIndexOf(':')
+  return idx > 0 ? host.slice(0, idx) : host
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// CIDR / keyword matchers
+// ───────────────────────────────────────────────────────────────────────────
+
+type IpMatcher = (ip: string) => boolean
+
+const KEYWORDS: Record<string, string[]> = {
+  loopback: ['127.0.0.0/8', '::1/128'],
+  linklocal: ['169.254.0.0/16', 'fe80::/10'],
+  uniquelocal: ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16', 'fc00::/7'],
+}
+
+function compileTrustEntry(entry: string): IpMatcher {
+  const expanded = KEYWORDS[entry] ?? [entry]
+  const matchers = expanded.map(compileSingle)
+  return (ip) => matchers.some((m) => m(ip))
+}
+
+function compileSingle(entry: string): IpMatcher {
+  if (entry.includes('/')) return compileCidr(entry)
+  return (ip) => ip === entry
+}
+
+function compileCidr(cidr: string): IpMatcher {
+  const slash = cidr.indexOf('/')
+  const network = cidr.slice(0, slash)
+  const prefix = Number(cidr.slice(slash + 1))
+  if (network.includes(':')) return compileCidrV6(network, prefix)
+  return compileCidrV4(network, prefix)
+}
+
+function compileCidrV4(network: string, prefix: number): IpMatcher {
+  const netBits = ipV4ToInt(network)
+  if (netBits === null) return () => false
+  const mask = prefix === 0 ? 0 : (~0 << (32 - prefix)) >>> 0
+  const target = (netBits & mask) >>> 0
+  return (ip) => {
+    const bits = ipV4ToInt(stripIpv6Wrap(ip))
+    if (bits === null) return false
+    return ((bits & mask) >>> 0) === target
+  }
+}
+
+function compileCidrV6(network: string, prefix: number): IpMatcher {
+  const netBytes = ipV6ToBytes(network)
+  if (!netBytes) return () => false
+  return (ip) => {
+    const bytes = ipV6ToBytes(ip)
+    if (!bytes) return false
+    return cmpPrefix(netBytes, bytes, prefix)
+  }
+}
+
+function cmpPrefix(a: Uint8Array, b: Uint8Array, prefix: number): boolean {
+  const fullBytes = prefix >>> 3
+  for (let i = 0; i < fullBytes; i++) if (a[i] !== b[i]) return false
+  const rem = prefix & 7
+  if (rem === 0) return true
+  const shift = 8 - rem
+  return (a[fullBytes]! >> shift) === (b[fullBytes]! >> shift)
+}
+
+function ipV4ToInt(ip: string): number | null {
+  const parts = ip.split('.')
+  if (parts.length !== 4) return null
+  let n = 0
+  for (const p of parts) {
+    const v = Number(p)
+    if (!Number.isInteger(v) || v < 0 || v > 255) return null
+    n = (n << 8) | v
+  }
+  return n >>> 0
+}
+
+/** ::ffff:1.2.3.4 → 1.2.3.4 (so v4 matchers work on v4-mapped addresses). */
+function stripIpv6Wrap(ip: string): string {
+  if (ip.startsWith('::ffff:')) return ip.slice(7)
+  return ip
+}
+
+function ipV6ToBytes(ip: string): Uint8Array | null {
+  // Very small implementation: handles standard `a:b:...:h` and `::` shorthand.
+  const cleaned = stripIpv6Wrap(ip)
+  if (cleaned.includes('.')) return null // v4-mapped already stripped above; bare v4 not v6
+  const out = new Uint8Array(16)
+  let parts: string[]
+  if (ip.includes('::')) {
+    const [head, tail] = ip.split('::')
+    const headParts = head ? head.split(':') : []
+    const tailParts = tail ? tail.split(':') : []
+    const fillCount = 8 - (headParts.length + tailParts.length)
+    if (fillCount < 0) return null
+    parts = [...headParts, ...new Array<string>(fillCount).fill('0'), ...tailParts]
+  } else {
+    parts = ip.split(':')
+  }
+  if (parts.length !== 8) return null
+  for (let i = 0; i < 8; i++) {
+    const v = parseInt(parts[i]!, 16)
+    if (!Number.isInteger(v) || v < 0 || v > 0xffff) return null
+    out[i * 2] = (v >> 8) & 0xff
+    out[i * 2 + 1] = v & 0xff
+  }
+  return out
+}