@nifrajs/core 1.13.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/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,

package/src/server/contract.ts

@@ -26,6 +26,8 @@ export interface ResponseDef {
 export interface OperationDef {
   readonly method: Method
   readonly path: string
+  /** Optional path-params schema (validated + coercible at the boundary; see {@link RouteSchema.params}). */
+  readonly params?: StandardSchemaV1
   readonly body?: StandardSchemaV1
   readonly query?: StandardSchemaV1
   readonly response?: StandardSchemaV1
@@ -35,6 +37,10 @@ export interface OperationDef {
   readonly idempotency?: IdempotencyConfig
   /** Highest data-sensitivity the response carries (see {@link RouteSchema.classification}). */
   readonly classification?: DataClassification
+  /** Inline route-assurance evidence this operation carries (see {@link RouteSchema.assurance}). */
+  readonly assurance?: readonly string[]
+  /** Mark this operation a dynamic route family (see {@link RouteSchema.family}). */
+  readonly family?: boolean
   /** Short summary (OpenAPI `summary`). */
   readonly summary?: string
   /** Longer description (OpenAPI `description`, CommonMark). */
@@ -68,21 +74,27 @@ type OpResponse<O extends OperationDef> = O extends { response: infer R extends
 
 /** The body types of a contract op's declared **non-2xx** `responses` (schema-bearing ones), keyed by status. */
 type OpErrorBodies<Rs extends Record<string, ResponseDef>> = {
-  [K in keyof Rs as K extends `2${string}` ? never : K]: Rs[K] extends {
+  // Non-2xx statuses, re-keyed from the contract's string keys ("404") to number literals (404) so
+  // the client's failure union discriminates on the numeric `status` it actually receives.
+  [K in keyof Rs as K extends `2${string}`
+    ? never
+    : K extends `${infer N extends number}`
+      ? N
+      : never]: Rs[K] extends {
     schema: infer S extends StandardSchemaV1
   }
     ? InferOutput<S>
     : never
 }
 
-/** The client-visible error union for a contract op — the union of its non-2xx `responses` body schemas,
- * or `unknown` when it declares none (mirrors an inline route with no `errors`). */
+/** The client-visible error bodies for a contract op as a status-keyed record (`{ 404: Body }`), or
+ * `unknown` when it declares none (mirrors an inline route with no `errors`). */
 type OpErrors<O extends OperationDef> = O extends {
   responses: infer Rs extends Record<string, ResponseDef>
 }
-  ? [OpErrorBodies<Rs>[keyof OpErrorBodies<Rs>]] extends [never]
+  ? [keyof OpErrorBodies<Rs>] extends [never]
     ? unknown
-    : OpErrorBodies<Rs>[keyof OpErrorBodies<Rs>]
+    : OpErrorBodies<Rs>
   : unknown
 
 /**
@@ -116,7 +128,8 @@ export type RegistryFor<C extends ContractShape> = {
 type SchemaForOp<O extends OperationDef> = (O extends { body: infer B extends StandardSchemaV1 }
   ? { body: B }
   : Record<never, never>) &
-  (O extends { query: infer Q extends StandardSchemaV1 } ? { query: Q } : Record<never, never>)
+  (O extends { query: infer Q extends StandardSchemaV1 } ? { query: Q } : Record<never, never>) &
+  (O extends { params: infer P extends StandardSchemaV1 } ? { params: P } : Record<never, never>)
 
 /**
  * The handler context for an op — identical to the inline `Context<Path, S>`, so a
@@ -251,19 +264,25 @@ export function implement<
     // once here at bind time, not per request — it just carries a reference to the op's existing schema.
     // A response-less op still yields `undefined`, byte-identical to before.
     const schema: RouteSchema | undefined =
+      op.params !== undefined ||
       op.body !== undefined ||
       op.query !== undefined ||
       op.response !== undefined ||
       op.capabilities !== undefined ||
       op.idempotency !== undefined ||
-      op.classification !== undefined
+      op.classification !== undefined ||
+      op.assurance !== undefined ||
+      op.family !== undefined
         ? {
+            ...(op.params !== undefined ? { params: op.params } : {}),
             ...(op.body !== undefined ? { body: op.body } : {}),
             ...(op.query !== undefined ? { query: op.query } : {}),
             ...(op.response !== undefined ? { response: op.response } : {}),
             ...(op.capabilities !== undefined ? { capabilities: op.capabilities } : {}),
             ...(op.idempotency !== undefined ? { idempotency: op.idempotency } : {}),
             ...(op.classification !== undefined ? { classification: op.classification } : {}),
+            ...(op.assurance !== undefined ? { assurance: op.assurance } : {}),
+            ...(op.family !== undefined ? { family: op.family } : {}),
           }
         : undefined
     return {

package/src/server/http.ts

@@ -0,0 +1,58 @@
+/**
+ * Dependency-free HTTP helpers shared by the kernel and the opt-in request lanes (idempotency,
+ * effect-ledger). Kept in a leaf module so a lane can reuse them without importing the server, and so
+ * the server can reuse them without pulling a lane's feature code into the base bundle.
+ */
+
+/** A uniform JSON error envelope: `{ ok: false, error }` at the given status. */
+export function jsonError(
+  status: number,
+  error: string,
+  headers?: Record<string, string>,
+): Response {
+  return Response.json(
+    { ok: false, error },
+    headers !== undefined ? { status, headers } : { status },
+  )
+}
+
+export interface UrlParts {
+  readonly pathname: string
+  readonly search: string
+}
+
+// Extract pathname + query WITHOUT a full WHATWG `new URL(req.url)` parse.
+// `req.url` from every supported runtime is an absolute, already-normalized URL, so the pathname is
+// the substring after `scheme://host[:port]` up to `?`/`#`. Query-schema routes also need the search
+// string; parsing both in one scanner avoids the old `pathnameOf()` + `searchOf()` double scan.
+export function urlPartsOf(url: string): UrlParts {
+  const schemeEnd = url.indexOf("://")
+  const start = schemeEnd === -1 ? url.indexOf("/") : url.indexOf("/", schemeEnd + 3)
+  if (start === -1) return { pathname: "/", search: "" }
+
+  let pathEnd = url.length
+  let searchStart = -1
+  let searchEnd = url.length
+  for (let i = start; i < url.length; i++) {
+    const c = url.charCodeAt(i)
+    if (c === 63 /* ? */ && searchStart === -1) {
+      pathEnd = i
+      searchStart = i
+    } else if (c === 35 /* # */) {
+      if (searchStart === -1) pathEnd = i
+      searchEnd = i
+      break
+    }
+  }
+
+  return {
+    pathname: url.slice(start, pathEnd),
+    search: searchStart === -1 ? "" : url.slice(searchStart, searchEnd),
+  }
+}
+
+// Extract the pathname WITHOUT a full WHATWG `new URL(req.url)` parse. Kept as a public-ish helper
+// for tests and callers that only need the path; the request hot path uses `urlPartsOf()` once.
+export function pathnameOf(url: string): string {
+  return urlPartsOf(url).pathname
+}