@nifrajs/core 1.12.0 → 2.0.0

package/src/mcp.ts

@@ -0,0 +1,65 @@
+/**
+ * The opt-in MCP runtime plugin.
+ *
+ * `.use(mcp())` enables `.tool()`, `.resource()`, and `.prompt()`. Without it those methods throw at
+ * registration (fail-closed), so an ordinary HTTP app never evaluates or bundles the MCP wiring. This
+ * is the same install seam as `.use(idempotency())` / `.use(effectLedger())` - one consistent `.use()`
+ * opt-in, not a side-effect import.
+ */
+import { INSTALL_MCP } from "./server/install.ts"
+import type { McpRuntime } from "./server/mcp-hook.ts"
+import type { IdentityPlugin } from "./server/plugin.ts"
+import type { AnyServer } from "./server/server.ts"
+
+const MCP_RUNTIME: McpRuntime = {
+  tool(name, config, handler) {
+    const path = `/_nifra/tool/${name}`
+    return {
+      path,
+      schema:
+        config.output !== undefined
+          ? { body: config.input, response: config.output }
+          : { body: config.input },
+      run: (context) => handler(context.body, context),
+      descriptor: {
+        name,
+        description: config.description,
+        ...(config.annotations !== undefined ? { annotations: config.annotations } : {}),
+      },
+    }
+  },
+  resource(uri, config, read) {
+    return {
+      uri,
+      name: config.name,
+      ...(config.description !== undefined ? { description: config.description } : {}),
+      ...(config.mimeType !== undefined ? { mimeType: config.mimeType } : {}),
+      read,
+    }
+  },
+  prompt(name, config, handler) {
+    return {
+      name,
+      description: config.description,
+      ...(config.arguments !== undefined ? { arguments: config.arguments } : {}),
+      handler,
+    }
+  },
+}
+
+/** The install seam a server exposes so the `mcp()` plugin can hand it the runtime. */
+interface McpInstallable {
+  [INSTALL_MCP](runtime: McpRuntime): void
+}
+
+/**
+ * Enable MCP declarations on a server: `.use(mcp())` turns on `.tool()`, `.resource()`, and
+ * `.prompt()`. Applying it twice is a no-op (named plugin dedupe).
+ */
+export function mcp(): IdentityPlugin {
+  const apply = <S extends AnyServer>(app: S): S => {
+    ;(app as unknown as McpInstallable)[INSTALL_MCP](MCP_RUNTIME)
+    return app
+  }
+  return Object.assign(apply, { pluginName: "nifra:mcp" }) as IdentityPlugin
+}

package/src/node-direct.ts

@@ -0,0 +1,37 @@
+/**
+ * The opt-in Node-direct renderer plugin.
+ *
+ * `.use(nodeDirect())` enables `app.resolveNode()` for callers that invoke it themselves. Normal
+ * `@nifrajs/node` serving supplies the renderer directly, so it never needs this; only direct
+ * `resolveNode()` callers do. Same `.use()` install seam as `mcp()` / `idempotency()`.
+ */
+import { INSTALL_NODE_DIRECT } from "./server/install.ts"
+import { nodeOutcomeFromResponse, toNodeOutcome } from "./server/node-outcome.ts"
+import type { NodeOutcomeRuntime } from "./server/node-outcome-hook.ts"
+import type { IdentityPlugin } from "./server/plugin.ts"
+import type { AnyServer } from "./server/server.ts"
+
+const NODE_OUTCOME_RUNTIME: NodeOutcomeRuntime = {
+  toOutcome: toNodeOutcome,
+  fromResponse: nodeOutcomeFromResponse,
+  timeout: () => ({
+    kind: "response",
+    response: Response.json({ ok: false, error: "request_timeout" }, { status: 503 }),
+  }),
+}
+
+/** The install seam a server exposes so the `nodeDirect()` plugin can hand it the renderer. */
+interface NodeDirectInstallable {
+  [INSTALL_NODE_DIRECT](runtime: NodeOutcomeRuntime): void
+}
+
+/** Enable `app.resolveNode()` for direct callers. Applying it twice is a no-op (named plugin dedupe). */
+export function nodeDirect(): IdentityPlugin {
+  const apply = <S extends AnyServer>(app: S): S => {
+    ;(app as unknown as NodeDirectInstallable)[INSTALL_NODE_DIRECT](NODE_OUTCOME_RUNTIME)
+    return app
+  }
+  return Object.assign(apply, { pluginName: "nifra:node-direct" }) as IdentityPlugin
+}
+
+export type { NodeServeOutcome } from "./server/node-outcome.ts"

package/src/reflection.ts

@@ -40,6 +40,8 @@ export interface SchemaReflection {
 export interface ReflectedRouteSchema {
   readonly body?: SchemaReflection
   readonly query?: SchemaReflection
+  /** Path-params schema — constraints (uuid format, integer min/max) declared via `params: t.object(…)`. */
+  readonly params?: SchemaReflection
   readonly response?: SchemaReflection
   readonly errors?: Readonly<Record<string, SchemaReflection>>
   /** The SSE event-payload schema of a typed streaming route (`app.sse()`). */
@@ -52,6 +54,9 @@ export interface ReflectedRoute {
   readonly schema?: ReflectedRouteSchema
   readonly assurance?: readonly AssuranceEvidence[]
   readonly capabilities?: readonly string[]
+  /** Set when the route is a declared dynamic route family (a runtime-resolved template like
+   * `/api/:slug/:resource`) - so the assurance gate treats it as one classified family, not a single route. */
+  readonly family?: boolean
   /** Field-level response classification plus the highest sensitivity present. */
   readonly classification?: ResponseClassification
   readonly tool?: {
@@ -167,6 +172,7 @@ const reflectedRouteSchema = (value: unknown): ReflectedRouteSchema | undefined
   return {
     ...(schema.body !== undefined ? { body: reflectSchema(schema.body) } : {}),
     ...(schema.query !== undefined ? { query: reflectSchema(schema.query) } : {}),
+    ...(schema.params !== undefined ? { params: reflectSchema(schema.params) } : {}),
     ...(schema.response !== undefined ? { response: reflectSchema(schema.response) } : {}),
     ...(Object.keys(reflectedErrors).length > 0 ? { errors: reflectedErrors } : {}),
     ...(schema.sse !== undefined ? { sse: reflectSchema(schema.sse) } : {}),
@@ -218,6 +224,7 @@ export function reflectRoutes(source: unknown): readonly ReflectedRoute[] {
       ...(schema !== undefined ? { schema } : {}),
       ...(assurance !== undefined ? { assurance } : {}),
       ...(capabilities.length > 0 ? { capabilities } : {}),
+      ...(route.family === true ? { family: true } : {}),
       ...(classification !== undefined ? { classification } : {}),
       ...(tool !== undefined ? { tool } : {}),
     })

package/src/router/pattern.ts

@@ -0,0 +1,176 @@
+import { RouteConfigError } from "../errors.ts"
+
+const PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
+const RESERVED_PARAM_NAMES = new Set(["__proto__", "constructor", "prototype"])
+const COMPILED_ROUTE_PATTERN: unique symbol = Symbol("nifra.compiled-route-pattern")
+
+export type RoutePatternSegment =
+  | { readonly kind: "static"; readonly value: string }
+  | { readonly kind: "param"; readonly name: string }
+  | { readonly kind: "wildcard"; readonly name: string }
+
+/**
+ * Compiled route grammar shared by runtime routers, browser navigation, mocks, and adapters.
+ *
+ * The result, its two arrays, and every segment are frozen because consumers share one instance. In
+ * particular, a segment must not diverge from the lazily cached regex after first match. The measured
+ * sub-microsecond cost per route is paid only at registration and preserves that runtime invariant.
+ */
+export interface CompiledRoutePattern {
+  readonly [COMPILED_ROUTE_PATTERN]: true
+  readonly pattern: string
+  readonly segments: readonly RoutePatternSegment[]
+  readonly paramNames: readonly string[]
+}
+
+export type RoutePatternMatch =
+  | { readonly matched: true; readonly params: Record<string, string> }
+  | { readonly matched: false; readonly reason: "not-found" | "malformed" }
+
+/**
+ * Regex per compiled pattern, derived on first use. The core trie matches by descending segments and
+ * never asks for one, so building it during {@link compileRoutePattern} would charge every server's
+ * boot for the browser/mock adapters alone. Keyed by the frozen pattern, so the cache dies with it.
+ */
+const REGEX_CACHE = new WeakMap<CompiledRoutePattern, RegExp>()
+
+function regexOf(compiled: CompiledRoutePattern): RegExp {
+  let regex = REGEX_CACHE.get(compiled)
+  if (regex === undefined) {
+    if (compiled[COMPILED_ROUTE_PATTERN] !== true) {
+      throw new TypeError("route pattern was not produced by compileRoutePattern()")
+    }
+    const parts = compiled.segments.map((segment) =>
+      segment.kind === "static"
+        ? escapeRegex(segment.value)
+        : segment.kind === "param"
+          ? "([^/]+)"
+          : "(.+)",
+    )
+    regex = new RegExp(parts.length === 0 ? "^/$" : `^/${parts.join("/")}$`)
+    REGEX_CACHE.set(compiled, regex)
+  }
+  return regex
+}
+
+function validParamName(name: string): boolean {
+  return PARAM_NAME.test(name) && !RESERVED_PARAM_NAMES.has(name)
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^()|[\]\\{}$]/g, "\\$&")
+}
+
+/** Parse and validate Nifra's strict route grammar once. Trailing slashes remain significant. */
+export function compileRoutePattern(pattern: string): CompiledRoutePattern {
+  if (pattern.length === 0 || pattern.charCodeAt(0) !== 47 /* / */) {
+    throw new RouteConfigError("INVALID_PATH", `path must start with "/": "${pattern}"`)
+  }
+  const raw = pattern === "/" ? [] : pattern.slice(1).split("/")
+  const segments: RoutePatternSegment[] = []
+  const paramNames: string[] = []
+  for (let i = 0; i < raw.length; i++) {
+    const value = raw[i]!
+    if (value.charCodeAt(0) === 58 /* : */) {
+      const name = value.slice(1)
+      if (!validParamName(name)) {
+        throw new RouteConfigError(
+          "INVALID_PARAM_NAME",
+          `invalid parameter ":${name}" in "${pattern}"`,
+        )
+      }
+      if (paramNames.includes(name)) {
+        throw new RouteConfigError(
+          "DUPLICATE_PARAM",
+          `duplicate parameter ":${name}" in "${pattern}"`,
+        )
+      }
+      paramNames.push(name)
+      segments.push(Object.freeze({ kind: "param", name }))
+      continue
+    }
+    if (value.charCodeAt(0) === 42 /* * */) {
+      if (i !== raw.length - 1) {
+        throw new RouteConfigError(
+          "WILDCARD_NOT_LAST",
+          `wildcard must be the final segment in "${pattern}"`,
+        )
+      }
+      const name = value.length === 1 ? "*" : value.slice(1)
+      if (name !== "*" && !validParamName(name)) {
+        throw new RouteConfigError(
+          "INVALID_PARAM_NAME",
+          `invalid wildcard "*${name}" in "${pattern}"`,
+        )
+      }
+      if (paramNames.includes(name)) {
+        throw new RouteConfigError(
+          "DUPLICATE_PARAM",
+          `duplicate parameter "${name}" in "${pattern}"`,
+        )
+      }
+      paramNames.push(name)
+      segments.push(Object.freeze({ kind: "wildcard", name }))
+      continue
+    }
+    segments.push(Object.freeze({ kind: "static", value }))
+  }
+  const compiled = Object.freeze({
+    [COMPILED_ROUTE_PATTERN]: true,
+    pattern,
+    segments: Object.freeze(segments),
+    paramNames: Object.freeze(paramNames),
+  }) as CompiledRoutePattern
+  return compiled
+}
+
+/** Core precedence: static > param > wildcard at the first differing segment, independent of order. */
+export function compareRoutePatternSpecificity(
+  left: CompiledRoutePattern,
+  right: CompiledRoutePattern,
+): number {
+  const length = Math.max(left.segments.length, right.segments.length)
+  for (let i = 0; i < length; i++) {
+    const a = left.segments[i]
+    const b = right.segments[i]
+    if (a === undefined || b === undefined) return b === undefined ? -1 : 1
+    const aWeight = a.kind === "static" ? 3 : a.kind === "param" ? 2 : 1
+    const bWeight = b.kind === "static" ? 3 : b.kind === "param" ? 2 : 1
+    if (aWeight !== bWeight) return bWeight - aWeight
+  }
+  return 0
+}
+
+/** Decode router captures under one rule. Plain values take the zero-allocation path; malformed
+ * escapes return `null`, allowing HTTP to emit 400 while client navigation declines the match. */
+export function decodeRouteParams(raw: Record<string, string>): Record<string, string> | null {
+  let out: Record<string, string> | undefined
+  for (const key in raw) {
+    const value = raw[key]!
+    if (!value.includes("%")) continue
+    try {
+      out ??= { ...raw }
+      out[key] = decodeURIComponent(value)
+    } catch {
+      return null
+    }
+  }
+  return out ?? raw
+}
+
+/** Match one compiled pattern and return decoded captures. The caller decides cross-pattern order. */
+export function matchRoutePattern(
+  compiled: CompiledRoutePattern,
+  pathname: string,
+): RoutePatternMatch {
+  const match = regexOf(compiled).exec(pathname)
+  if (match === null) return { matched: false, reason: "not-found" }
+  const params: Record<string, string> = {}
+  for (let i = 0; i < compiled.paramNames.length; i++) {
+    params[compiled.paramNames[i]!] = match[i + 1] ?? ""
+  }
+  const decoded = decodeRouteParams(params)
+  return decoded === null
+    ? { matched: false, reason: "malformed" }
+    : { matched: true, params: decoded }
+}

package/src/router/router.ts

@@ -1,4 +1,5 @@
 import { RouteConfigError } from "../errors.ts"
+import { type CompiledRoutePattern, compileRoutePattern } from "./pattern.ts"
 
 /** HTTP methods the router accepts. */
 export const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"] as const
@@ -11,24 +12,7 @@ function isMethod(value: string): value is Method {
   return METHOD_SET.has(value)
 }
 
-/** Parameter names must be valid identifiers — mirrors the global identifier rule. */
-const PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
-
-/** Object-prototype keys are rejected as param names: a route like `/:__proto__` could let a captured
- * value reach a prototype-polluting key. Param *names* come from the route pattern (never from request
- * input) and are validated here at registration, so a reserved key can never reach `buildParams` —
- * this boot-time guard is the whole protection. The runtime params object stays a plain `{}` (only
- * user-controlled *values* land in it, under these validated keys), keeping the param path
- * allocation-cheap; a null-prototype object would add cost for no added safety. */
-const RESERVED_PARAM_NAMES = new Set(["__proto__", "constructor", "prototype"])
-
-/** A param name is valid when it's an identifier AND not a reserved object-prototype key. */
-const validParamName = (name: string): boolean =>
-  PARAM_NAME.test(name) && !RESERVED_PARAM_NAMES.has(name)
-
 const SLASH = 47
-const COLON = 58
-const STAR = 42
 export const EMPTY_PARAMS: Record<string, string> = Object.freeze({})
 const DYNAMIC_MATCH_CACHE_MAX = 2048
 
@@ -245,7 +229,7 @@ export class Router<T> {
    * (boot-time, L2) on a duplicate route, a malformed pattern, or conflicting
    * parameter names for the same path shape.
    */
-  add(method: Method, path: string, payload: T): void {
+  add(method: Method, pattern: string | CompiledRoutePattern, payload: T): void {
     DYNAMIC_MATCH_CACHES.delete(this)
     const upper = method.toUpperCase()
     // The `Method` parameter type is the compile-time guard; this re-checks at
@@ -253,66 +237,24 @@ export class Router<T> {
     if (!isMethod(upper)) {
       throw new RouteConfigError("INVALID_METHOD", `unsupported HTTP method "${method}"`)
     }
-    if (path.length === 0 || path.charCodeAt(0) !== SLASH) {
-      throw new RouteConfigError("INVALID_PATH", `path must start with "/": "${path}"`)
-    }
-
-    const segments = path === "/" ? [] : path.slice(1).split("/")
-    const paramNames: string[] = []
-    let isStatic = true
+    const compiled = typeof pattern === "string" ? compileRoutePattern(pattern) : pattern
+    const path = compiled.pattern
+    const paramNames = compiled.paramNames
+    const isStatic = paramNames.length === 0
     let node = this.root
 
-    for (let i = 0; i < segments.length; i++) {
-      const seg = segments[i]!
-      const marker = seg.charCodeAt(0)
-
-      if (marker === COLON) {
-        isStatic = false
-        const name = seg.slice(1)
-        if (!validParamName(name)) {
-          throw new RouteConfigError(
-            "INVALID_PARAM_NAME",
-            `invalid parameter ":${name}" in "${path}"`,
-          )
-        }
-        if (paramNames.includes(name)) {
-          throw new RouteConfigError(
-            "DUPLICATE_PARAM",
-            `duplicate parameter ":${name}" in "${path}"`,
-          )
-        }
-        paramNames.push(name)
+    for (const segment of compiled.segments) {
+      if (segment.kind === "param") {
         node.paramChild ??= createNode<T>()
         node = node.paramChild
-      } else if (marker === STAR) {
-        isStatic = false
-        if (i !== segments.length - 1) {
-          throw new RouteConfigError(
-            "WILDCARD_NOT_LAST",
-            `wildcard must be the final segment in "${path}"`,
-          )
-        }
-        const name = seg.length === 1 ? "*" : seg.slice(1)
-        if (name !== "*" && !validParamName(name)) {
-          throw new RouteConfigError(
-            "INVALID_PARAM_NAME",
-            `invalid wildcard "*${name}" in "${path}"`,
-          )
-        }
-        if (paramNames.includes(name)) {
-          throw new RouteConfigError(
-            "DUPLICATE_PARAM",
-            `duplicate parameter "${name}" in "${path}"`,
-          )
-        }
-        paramNames.push(name)
+      } else if (segment.kind === "wildcard") {
         node.wildcardChild ??= createNode<T>()
         node = node.wildcardChild
       } else {
-        let child = node.staticChildren.get(seg)
+        let child = node.staticChildren.get(segment.value)
         if (child === undefined) {
           child = createNode<T>()
-          node.staticChildren.set(seg, child)
+          node.staticChildren.set(segment.value, child)
         }
         node = child
       }

package/src/server/client-ip.ts

@@ -0,0 +1,60 @@
+/**
+ * Deriving the caller's IP (`c.clientIp`), correctly and vendor-neutrally.
+ *
+ * The default is the raw socket peer the serving adapter observed - the only value that cannot be
+ * forged by a client, since the client never controls who the TCP connection comes from. Behind a
+ * reverse proxy or CDN the socket peer is the proxy, not the caller, so a `Forwarded`/`X-Forwarded-For`
+ * value must be consulted - but ONLY as far as you actually trust the hops in front of you, because a
+ * directly-reachable app lets any client forge those headers. The trust is therefore an explicit,
+ * opt-in declaration; with none set, `c.clientIp` is the socket peer and no header is ever believed.
+ *
+ * No vendor names live here: a Cloudflare/Fastly/nginx deployment declares its own header or hop count.
+ */
+
+/**
+ * How much of the forwarding chain to trust when deriving `c.clientIp`. Omit for the safe default
+ * (socket peer only, no header believed).
+ *
+ * - `{ trustedHops: n }` - trust `n` reverse-proxy hops in front of the app. The caller is taken from
+ *   `X-Forwarded-For` counted from the right past the `n` trusted hops (the socket peer is hop 0). Use
+ *   this when the app sits behind `n` proxies **you operate**. Fewer entries than trusted hops means
+ *   the header is too short to trust, so `c.clientIp` is `undefined` (fail closed).
+ * - `{ header: name }` - trust a single named header's first value (e.g. a CDN that overwrites it at
+ *   the edge). Only declare this when the app is reachable **exclusively** through that edge; a
+ *   directly-reachable app lets any client forge the header.
+ */
+export type ClientIpTrust = { readonly trustedHops: number } | { readonly header: string }
+
+function firstHeaderValue(req: Request, header: string): string | undefined {
+  const raw = req.headers.get(header)
+  if (raw === null) return undefined
+  const first = raw.split(",", 1)[0]?.trim()
+  return first === undefined || first === "" ? undefined : first
+}
+
+/**
+ * Resolve the caller IP from the raw socket `peer` (adapter-observed), the request's forwarding
+ * headers, and the app's `trust` declaration. Pure and synchronous.
+ */
+export function resolveClientIp(
+  peer: string | undefined,
+  req: Request,
+  trust: ClientIpTrust | undefined,
+): string | undefined {
+  if (trust === undefined) return peer
+  if ("header" in trust) return firstHeaderValue(req, trust.header)
+
+  // trustedHops: walk `X-Forwarded-For` (client-most first) plus the socket peer as the closest hop.
+  const xff = req.headers.get("x-forwarded-for")
+  const forwarded =
+    xff === null
+      ? []
+      : xff
+          .split(",")
+          .map((entry) => entry.trim())
+          .filter((entry) => entry !== "")
+  const chain = peer !== undefined ? [...forwarded, peer] : forwarded
+  // The caller sits just left of the `trustedHops` trusted proxies at the tail of the chain.
+  const index = chain.length - 1 - trust.trustedHops
+  return index >= 0 ? chain[index] : undefined
+}

package/src/server/context.ts

@@ -78,6 +78,34 @@ export interface RouteSchema {
    * and read by downstream policy (e.g. a partner-API surface refusing to expose `pii`/`secret`).
    */
   readonly classification?: DataClassification
+  /**
+   * Inline **route-assurance evidence**: the enforcement posture this route carries, declared adjacent to
+   * the handler (e.g. `[NIFRA_ASSURANCE.AUTHENTICATED]`). Each id becomes route-scoped `declared` evidence
+   * in reflection, so a `nifra.assurance.ts` policy `require:` clause is satisfiable WITHOUT rewriting an
+   * in-handler guard into a `withRouteAssurance`-marked middleware. Ids are lowercase dot/dash segments
+   * (invalid ids throw at registration). Reflected for the assurance gate; never read on the hot path.
+   *
+   * This is an author ASSERTION (recorded as `source: "declared"`), not runtime proof - like every
+   * assurance marker it is trusted by the static gate, which matches on the evidence id, not its source.
+   * Declare an id only on a route whose guard actually enforces it; a false declaration silently satisfies
+   * the policy. (`source` is retained in reflection, so a stricter policy or reviewer can still tell
+   * declared evidence from enforcement-module evidence.)
+   */
+  readonly assurance?: readonly string[]
+  /**
+   * Mark this route a **dynamic route family**: a template (`/api/:slug/:resource`) whose concrete
+   * resources are resolved at runtime (auto-CRUD over tenant-defined tables, a catch-all dispatcher).
+   * Purely declarative - it does not change dispatch. It surfaces in reflection so the assurance gate and
+   * tooling treat the one templated route as a deliberate family whose evidence covers every runtime-
+   * resolved resource, instead of reading it as a single forgotten route.
+   */
+  readonly family?: boolean
+  /** Optional **path-params schema**. Path params arrive as strings (`/users/:id` -> `c.params.id`);
+   * declaring a schema validates them at the boundary (a malformed `:id` is a `422` before the handler,
+   * like `body`/`query`) and can coerce them (use `t.query({ id: t.integer() })` for a numeric param).
+   * The schema must cover every path param; with the strict default an undeclared path param is rejected.
+   * When omitted, `c.params` stays the path-inferred `Record<name, string>`. */
+  readonly params?: StandardSchemaV1
   readonly body?: StandardSchemaV1
   readonly query?: StandardSchemaV1
   /** Optional **response contract**. When declared: the handler's return is type-checked against it
@@ -117,7 +145,7 @@ export interface RouteSchema {
   readonly onValidationError?: (
     issues: ReadonlyArray<StandardIssue>,
     ctx: Context,
-    kind: "body" | "query",
+    kind: "body" | "query" | "params",
   ) => Response | unknown | Promise<Response | unknown>
 }
 
@@ -131,6 +159,13 @@ type QueryOf<S extends RouteSchema> = S extends { query: infer Q extends Standar
   ? InferOutput<Q>
   : URLSearchParams
 
+/** The validated params type when a params schema is declared, else the path-inferred `Params<Path>`. */
+type ParamsOf<S extends RouteSchema, Path extends string> = S extends {
+  params: infer P extends StandardSchemaV1
+}
+  ? InferOutput<P>
+  : Params<Path>
+
 /** Mutable response controls a handler may write to before returning. */
 export interface ResponseControls {
   status?: number
@@ -159,6 +194,10 @@ export interface Platform<Env = unknown> {
   readonly env?: Env
   /** Extend the response's lifetime for background work (Workers `ctx.waitUntil`). */
   readonly waitUntil?: (promise: Promise<unknown>) => void
+  /** The raw socket peer address the serving adapter observed, if any (`listen()`, `@nifrajs/node`,
+   * `@nifrajs/deno` set it). The server applies the app's `clientIp` trust declaration to this before
+   * exposing {@link Context.clientIp}; read `c.clientIp`, not this. */
+  readonly clientIp?: string | undefined
 }
 
 /**
@@ -174,7 +213,7 @@ export interface Context<Path extends string = string, S extends RouteSchema = R
    * everywhere (no more `c.req` vs `ctx.request` mismatch).
    */
   readonly request: Request
-  readonly params: Params<Path>
+  readonly params: ParamsOf<S, Path>
   readonly query: QueryOf<S>
   readonly body: BodyOf<S>
   /** The request's cookies, parsed from the `Cookie` header (values URL-decoded). Parsed lazily on
@@ -198,6 +237,15 @@ export interface Context<Path extends string = string, S extends RouteSchema = R
    * (`c.env: Env`); otherwise `unknown`. Validate at the trust boundary before use either way.
    */
   readonly env: unknown
+  /**
+   * The caller's IP. By default the raw socket peer the serving adapter observed (`listen()`,
+   * `@nifrajs/node`, `@nifrajs/deno`) — the one address a client cannot forge — or `undefined` when the
+   * runtime exposes no socket (Workers) and no trust is declared. Behind a proxy/CDN, set the
+   * `clientIp` server option (`{ trustedHops }` or `{ header }`) to derive the real caller from the
+   * forwarding chain as far as you trust it; unset, no forwarded header is ever believed. Safe to key
+   * rate limits and audit logs on.
+   */
+  readonly clientIp: string | undefined
   /**
    * Schedule background work. On edge runtimes it extends the response lifetime (Workers
    * `ctx.waitUntil`); off-edge it runs the promise fire-and-forget (a rejection is swallowed,