@nifrajs/core 2.11.0 → 2.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/core",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "Bun-native, contract-first HTTP framework - the router, server, and route descriptor.",
   "keywords": [
     "bun",
@@ -67,11 +67,21 @@
       "types": "./dist/diff.d.ts",
       "default": "./dist/diff.js"
     },
+    "./evidence": {
+      "bun": "./src/evidence.ts",
+      "types": "./dist/evidence.d.ts",
+      "default": "./dist/evidence.js"
+    },
     "./assurance": {
       "bun": "./src/assurance.ts",
       "types": "./dist/assurance.d.ts",
       "default": "./dist/assurance.js"
     },
+    "./replay": {
+      "bun": "./src/replay.ts",
+      "types": "./dist/replay.d.ts",
+      "default": "./dist/replay.js"
+    },
     "./binary": {
       "bun": "./src/binary.ts",
       "types": "./dist/binary.d.ts",
@@ -226,6 +236,21 @@
       "bun": "./src/server/response-contract-lane.ts",
       "types": "./dist/server/response-contract-lane.d.ts",
       "default": "./dist/server/response-contract-lane.js"
+    },
+    "./tool-contract": {
+      "bun": "./src/tool-contract.ts",
+      "types": "./dist/tool-contract.d.ts",
+      "default": "./dist/tool-contract.js"
+    },
+    "./tool-catalog": {
+      "bun": "./src/tool-catalog.ts",
+      "types": "./dist/tool-catalog.d.ts",
+      "default": "./dist/tool-catalog.js"
+    },
+    "./execution-policy": {
+      "bun": "./src/execution-policy.ts",
+      "types": "./dist/execution-policy.d.ts",
+      "default": "./dist/execution-policy.js"
     }
   },
   "files": [

package/src/assurance.ts

@@ -11,23 +11,32 @@ import {
   type CapabilityZone,
   defineCapabilityPolicy,
 } from "./capabilities.ts"
+import {
+  type DataClassification,
+  classificationAtLeast as isClassificationAtLeast,
+  isDataClassification,
+} from "./classification.ts"
 import type {
+  AssuranceAttachment,
   AssuranceDeclaration,
   AssuranceEvidence,
   AssuranceScope,
 } from "./internal/route-assurance.ts"
 import {
+  evidenceProvenance,
   NIFRA_ASSURANCE_IDS,
+  normalizeAssuranceDeclarations,
   routeGlob,
   validEvidenceId,
   validMethod,
   withRouteAssurance,
 } from "./internal/route-assurance.ts"
+import type { SealedEffectLedger } from "./ledger.ts"
 import type { NifraManifestSigner } from "./manifest.ts"
 import { type ReflectedRoute, reflectRoutes } from "./reflection.ts"
 import type { Method } from "./router/router.ts"
 
-export type { AssuranceDeclaration, AssuranceEvidence, AssuranceScope }
+export type { AssuranceAttachment, AssuranceDeclaration, AssuranceEvidence, AssuranceScope }
 export { withRouteAssurance }
 
 /** Isolated request executor used by adversarial contract verification. */
@@ -36,6 +45,57 @@ export type InvariantExecutor = (request: Request) => Response | Promise<Respons
 /** Canonical evidence ids emitted by Nifra's official middleware modules. */
 export const NIFRA_ASSURANCE = NIFRA_ASSURANCE_IDS
 
+/** The seam `assure()` writes through: an evidence-only middleware bundle, applied like any other. */
+interface AssurableServer {
+  use(middleware: object): unknown
+}
+
+/**
+ * Publish enforcement evidence from OUTSIDE the plugin chain - the deployment shell that wraps the
+ * app, the mount site, or the call that hands it to `serve`. When the thing doing the enforcing is
+ * not a nifra plugin (a gateway, a service mesh, an outer framework), the alternative is switching
+ * the affected rules off; this records what covers the routes instead, so the policy keeps running.
+ *
+ *   const app = buildApp()                 // no assurance-bearing plugin in its .use() chain
+ *   assure(app, { id: NIFRA_ASSURANCE.AUTHENTICATED, source: "edge-gateway" })
+ *   serve(app)
+ *
+ * `scope` defaults to `global`: the shell runs after every route is registered, so the evidence is
+ * retroactive and app-wide. Narrow it with `methods`/`paths` (absolute globs), or pass
+ * `scope: "subsequent"` to cover only routes registered after the call.
+ *
+ * Provenance is always `declared` - nifra did not install this enforcement and cannot observe it, so
+ * a rule with `requireProvenance: "runtime"` still rejects the route, by design.
+ */
+export function assure(
+  app: unknown,
+  evidence: AssuranceAttachment | readonly AssuranceAttachment[],
+): void {
+  const values: readonly AssuranceAttachment[] = Array.isArray(evidence)
+    ? (evidence as readonly AssuranceAttachment[])
+    : [evidence as AssuranceAttachment]
+  const declarations = normalizeAssuranceDeclarations(
+    values.map((item) => ({
+      ...item,
+      scope: item.scope ?? "global",
+      provenance: "declared" as const,
+    })),
+  )
+  for (const declaration of declarations) {
+    if (declaration.scope === "plugin") {
+      throw new Error('assure(): scope "plugin" may only annotate a plugin function')
+    }
+  }
+  const target = app as Partial<AssurableServer>
+  if (typeof target.use !== "function") {
+    throw new TypeError("assure(): expected a nifra server")
+  }
+  // An evidence-only bundle: `use()` already reads declarations off what it applies, and a bundle
+  // with no hooks registers nothing on any lifecycle array - so the kernel needs no seam of its own,
+  // the request path is untouched, and an app that never calls `assure()` carries none of this.
+  target.use(withRouteAssurance({}, declarations))
+}
+
 export interface AssuranceRouteSelector {
   /** Omit for every method. */
   readonly methods?: readonly Method[]
@@ -73,6 +133,8 @@ export interface AssuranceRouteSelector {
    * match a route that only writes an audit log.
    */
   readonly zone?: CapabilityZone
+  /** Match routes whose response classification is at least this sensitivity. */
+  readonly classificationAtLeast?: DataClassification
 }
 
 /** Extra inputs an assurance evaluation needs beyond the routes themselves. */
@@ -109,6 +171,19 @@ export interface AssuranceRule {
   readonly require?: readonly string[]
   /** Evidence ids the route must not carry (useful for public webhooks and health routes). */
   readonly forbid?: readonly string[]
+  /**
+   * Provenance required for every id in require. any (default) preserves compatibility with
+   * existing policies; runtime rejects schema.assurance author assertions and accepts only
+   * evidence installed by middleware/plugins or framework runtime policy. declared is useful for
+   * explicitly reviewing in-handler assertions and should not be used as an enforcement gate.
+   */
+  readonly requireProvenance?: "any" | "runtime" | "declared"
+  /**
+   * When true, an authenticated route selected by this rule must also carry runtime CSRF evidence.
+   * Enable this on rules covering cookie/session-authenticated browser routes; bearer-only APIs
+   * should use a separate rule because they do not have browser ambient-authority exposure.
+   */
+  readonly requireCsrfWithAuthenticated?: boolean
 }
 
 export interface AssurancePolicy {
@@ -161,6 +236,23 @@ export interface AssuranceReport {
   readonly capabilities?: CapabilityAssuranceReport
 }
 
+/** Application-supplied verification rules. The CLI validates the executable rule shape at runtime. */
+export interface AssuranceRulePack {
+  readonly name: string
+  readonly rules: readonly unknown[]
+}
+
+export interface IdempotencyWorkload {
+  readonly name: string
+  readonly run: () => Promise<SealedEffectLedger> | SealedEffectLedger
+}
+
+export interface AssuranceSizeBudget {
+  readonly outDir?: string
+  readonly maxBytes?: number
+  readonly maxGzipBytes?: number
+}
+
 export interface AssuranceConfig {
   readonly source: unknown
   readonly policy: AssurancePolicy
@@ -176,6 +268,14 @@ export interface AssuranceConfig {
   readonly invariants?: {
     readonly executor: InvariantExecutor
   }
+  /** Optional application-supplied rule packs appended after built-in verification rules. */
+  readonly rulePacks?: readonly AssuranceRulePack[]
+  /** Optional sink for an assurance bundle. The CLI validates the callable shape at runtime. */
+  readonly assureSink?: unknown
+  /** Optional deterministic effect workloads for the tests gate. */
+  readonly idempotency?: readonly IdempotencyWorkload[]
+  /** Optional output-size budget for the assurance bundle's size gate. */
+  readonly size?: AssuranceSizeBudget
 }
 
 const nonEmpty = (value: string): boolean => value.trim() !== ""
@@ -229,7 +329,15 @@ export function defineAssurancePolicy(policy: AssurancePolicy): AssurancePolicy
     // silence - and a selector that loses its only constraint matches EVERY route, making the rule
     // swallow everything after it. A misspelled key is a policy hole, so it is refused here.
     const unknown = Object.keys(rule.match).filter(
-      (key) => !["methods", "paths", "tools", "capabilities", ...CLASS_SELECTOR_KEYS].includes(key),
+      (key) =>
+        ![
+          "methods",
+          "paths",
+          "tools",
+          "capabilities",
+          ...CLASS_SELECTOR_KEYS,
+          "classificationAtLeast",
+        ].includes(key),
     )
     if (unknown.length > 0) {
       throw new Error(
@@ -271,8 +379,40 @@ export function defineAssurancePolicy(policy: AssurancePolicy): AssurancePolicy
         `route assurance: rule ${JSON.stringify(name)} zone selector must be "domain" or "operational"`,
       )
     }
+    if (
+      rule.match.classificationAtLeast !== undefined &&
+      !isDataClassification(rule.match.classificationAtLeast)
+    ) {
+      throw new Error(
+        "route assurance: rule " +
+          JSON.stringify(name) +
+          ' classificationAtLeast must be "public", "pii", or "secret"',
+      )
+    }
     const required = normalizeEvidenceIds(rule.require, "required")
     const forbidden = normalizeEvidenceIds(rule.forbid, "forbidden")
+    if (
+      rule.requireProvenance !== undefined &&
+      rule.requireProvenance !== "any" &&
+      rule.requireProvenance !== "runtime" &&
+      rule.requireProvenance !== "declared"
+    ) {
+      throw new Error(
+        "route assurance: rule " +
+          JSON.stringify(name) +
+          ' requireProvenance must be "any", "runtime", or "declared"',
+      )
+    }
+    if (
+      rule.requireCsrfWithAuthenticated !== undefined &&
+      typeof rule.requireCsrfWithAuthenticated !== "boolean"
+    ) {
+      throw new Error(
+        "route assurance: rule " +
+          JSON.stringify(name) +
+          " requireCsrfWithAuthenticated must be boolean",
+      )
+    }
     const overlap = required.find((id) => forbidden.includes(id))
     if (overlap !== undefined) {
       throw new Error(
@@ -288,9 +428,16 @@ export function defineAssurancePolicy(policy: AssurancePolicy): AssurancePolicy
         ...(capabilities !== undefined ? { capabilities: Object.freeze([...capabilities]) } : {}),
         ...(access !== undefined ? { access } : {}),
         ...(zone !== undefined ? { zone } : {}),
+        ...(rule.match.classificationAtLeast !== undefined
+          ? { classificationAtLeast: rule.match.classificationAtLeast }
+          : {}),
       }),
       require: required,
       forbid: forbidden,
+      ...(rule.requireProvenance !== undefined
+        ? { requireProvenance: rule.requireProvenance }
+        : {}),
+      ...(rule.requireCsrfWithAuthenticated === true ? { requireCsrfWithAuthenticated: true } : {}),
     })
   })
   return Object.freeze({
@@ -312,6 +459,57 @@ export function defineAssuranceConfig(config: AssuranceConfig): AssuranceConfig
   if (config.invariants !== undefined && typeof config.invariants.executor !== "function") {
     throw new Error("route assurance: invariant executor must be a function")
   }
+  if (config.rulePacks !== undefined) {
+    if (!Array.isArray(config.rulePacks))
+      throw new TypeError("route assurance: rulePacks must be an array")
+    const names = new Set<string>()
+    for (const pack of config.rulePacks) {
+      if (typeof pack.name !== "string" || pack.name.trim() === "")
+        throw new TypeError("route assurance: rule pack name must be non-empty")
+      if (names.has(pack.name)) throw new Error(`route assurance: duplicate rule pack ${pack.name}`)
+      names.add(pack.name)
+      if (!Array.isArray(pack.rules))
+        throw new TypeError(`route assurance: invalid rules in ${pack.name}`)
+    }
+  }
+  if (config.assureSink !== undefined) {
+    if (
+      typeof config.assureSink !== "object" ||
+      config.assureSink === null ||
+      Array.isArray(config.assureSink)
+    )
+      throw new TypeError("route assurance: assureSink must be an object")
+    const record = Object.fromEntries(Object.entries(config.assureSink))
+    if (typeof record.record !== "function")
+      throw new TypeError("route assurance: assureSink.record must be a function")
+  }
+  if (config.idempotency !== undefined) {
+    if (!Array.isArray(config.idempotency))
+      throw new TypeError("route assurance: idempotency must be an array")
+    for (const workload of config.idempotency) {
+      if (
+        typeof workload.name !== "string" ||
+        workload.name.trim() === "" ||
+        typeof workload.run !== "function"
+      )
+        throw new TypeError("route assurance: idempotency workloads require name and run")
+    }
+  }
+  if (config.size !== undefined) {
+    if (typeof config.size !== "object" || config.size === null || Array.isArray(config.size))
+      throw new TypeError("route assurance: size must be an object")
+    for (const [name, value] of Object.entries(config.size)) {
+      if (name !== "outDir" && name !== "maxBytes" && name !== "maxGzipBytes")
+        throw new TypeError(`route assurance: unknown size key ${name}`)
+      if (name === "outDir" && typeof value !== "string")
+        throw new TypeError("route assurance: size.outDir must be a string")
+      if (
+        (name === "maxBytes" || name === "maxGzipBytes") &&
+        (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+      )
+        throw new TypeError(`route assurance: size.${name} must be a non-negative number`)
+    }
+  }
   const policy = defineAssurancePolicy(config.policy)
   const capabilities =
     config.capabilities !== undefined ? defineCapabilityPolicy(config.capabilities) : undefined
@@ -344,6 +542,12 @@ export function defineAssuranceConfig(config: AssuranceConfig): AssuranceConfig
     ...(config.invariants !== undefined
       ? { invariants: Object.freeze({ executor: config.invariants.executor }) }
       : {}),
+    ...(config.rulePacks !== undefined ? { rulePacks: Object.freeze([...config.rulePacks]) } : {}),
+    ...(config.assureSink !== undefined ? { assureSink: config.assureSink } : {}),
+    ...(config.idempotency !== undefined
+      ? { idempotency: Object.freeze([...config.idempotency]) }
+      : {}),
+    ...(config.size !== undefined ? { size: Object.freeze({ ...config.size }) } : {}),
   })
 }
 
@@ -355,15 +559,21 @@ export function defineAssuranceConfig(config: AssuranceConfig): AssuranceConfig
  * accept user policy must reject that combination up front - `defineAssuranceConfig` does.
  */
 export function matchesAssuranceSelector(
-  route: Pick<ReflectedRoute, "method" | "path" | "tool" | "capabilities">,
+  route: Pick<ReflectedRoute, "method" | "path" | "tool" | "capabilities" | "classification">,
   selector: AssuranceRouteSelector,
   definitions?: ReadonlyMap<string, CapabilityDefinition>,
 ): boolean {
-  const { methods, paths, tools, capabilities, access, zone } = selector
+  const { methods, paths, tools, capabilities, access, zone, classificationAtLeast } = selector
   if (methods !== undefined && !methods.includes(route.method as Method)) return false
   if (paths !== undefined && !paths.some((pattern) => routeGlob(pattern).test(route.path)))
     return false
   if (tools !== undefined && (route.tool !== undefined) !== tools) return false
+  if (
+    classificationAtLeast !== undefined &&
+    (route.classification === undefined ||
+      !isClassificationAtLeast(route.classification.max, classificationAtLeast))
+  )
+    return false
   const declared = route.capabilities ?? []
   if (capabilities !== undefined && !capabilities.some((token) => declared.includes(token)))
     return false
@@ -434,8 +644,25 @@ export function evaluateRouteAssurance(
       continue
     }
 
-    const missing = (rule.require ?? []).filter((id) => !evidenceIds.has(id))
+    const requiredProvenance = rule.requireProvenance ?? "any"
+    let missing = (rule.require ?? []).filter((id) => {
+      if (!evidenceIds.has(id)) return true
+      if (requiredProvenance === "any") return false
+      return !evidence.some(
+        (item) => item.id === id && evidenceProvenance(item) === requiredProvenance,
+      )
+    })
     const forbidden = (rule.forbid ?? []).filter((id) => evidenceIds.has(id))
+    if (
+      rule.requireCsrfWithAuthenticated === true &&
+      evidenceIds.has(NIFRA_ASSURANCE_IDS.AUTHENTICATED) &&
+      !evidence.some(
+        (item) => item.id === NIFRA_ASSURANCE_IDS.CSRF && evidenceProvenance(item) === "runtime",
+      )
+    ) {
+      const id = NIFRA_ASSURANCE_IDS.CSRF
+      if (!missing.includes(id)) missing = [...missing, id]
+    }
     for (const id of missing) {
       findings.push({
         code: "missing-evidence",
@@ -443,7 +670,10 @@ export function evaluateRouteAssurance(
         path: route.path,
         rule: rule.name,
         evidence: id,
-        message: `${route.method} ${route.path} (${rule.name}) is missing ${id}`,
+        message:
+          requiredProvenance === "any"
+            ? `${route.method} ${route.path} (${rule.name}) is missing ${id}`
+            : `${route.method} ${route.path} (${rule.name}) is missing ${requiredProvenance} evidence for ${id}`,
       })
     }
     for (const id of forbidden) {

package/src/capabilities.ts

@@ -91,6 +91,14 @@ export interface CapabilityImportRule {
   /** Exact module specifier, or a trailing `/*` prefix rule. */
   readonly specifier: string
   readonly capabilities: readonly string[]
+  /**
+   * Allow this seam to be absent. A rule that matches no import anywhere in the project is reported
+   * as `unmatched-provenance-seam` by default, because a specifier written differently from the
+   * import it means to govern (`"./db/client.ts"` vs `import "./db/client"`) governs nothing and
+   * every route touching that effect still passes. Set this only for a policy shared across projects
+   * where some of them genuinely do not use the seam.
+   */
+  readonly optional?: boolean
 }
 
 export interface ForbiddenCapabilityImport {
@@ -156,6 +164,7 @@ export type CapabilityFindingCode =
   | "missing-durable-idempotency"
   | "forbidden-effect-import"
   | "provenance-truncated"
+  | "unmatched-provenance-seam"
 
 export interface CapabilityFinding {
   readonly code: CapabilityFindingCode
@@ -270,7 +279,11 @@ export function defineCapabilityPolicy(policy: CapabilityPolicy): CapabilityPoli
     for (const id of capabilities) {
       if (!ids.has(id)) throw new Error(`capability assurance: import references unknown ${id}`)
     }
-    return Object.freeze({ specifier: rule.specifier, capabilities })
+    return Object.freeze({
+      specifier: rule.specifier,
+      capabilities,
+      ...(rule.optional === true ? { optional: true as const } : {}),
+    })
   })
   const forbiddenImports = policy.provenance.forbiddenImports.map(
     (rule): ForbiddenCapabilityImport => {

package/src/diff.ts

@@ -32,6 +32,7 @@ export interface SchemaSnapshot {
 }
 
 export interface RouteSnapshotSchema {
+  readonly headers?: SchemaSnapshot
   readonly body?: SchemaSnapshot
   readonly query?: SchemaSnapshot
   readonly response?: SchemaSnapshot
@@ -53,7 +54,7 @@ export interface RouteChange {
   readonly method: string
   readonly path: string
   /** Which part of the contract changed; "route" for add/remove of the whole route. */
-  readonly section: "route" | "body" | "query" | "response" | "sse" | "errors"
+  readonly section: "route" | "headers" | "body" | "query" | "response" | "sse" | "errors"
   /** The top-level field (or error status) the change is about, when field-granular. */
   readonly field?: string
   readonly message: string
@@ -98,10 +99,12 @@ const snapshotRoute = (route: ReflectedRoute): RouteSnapshot => {
     if (snapped !== undefined) errors[status] = snapped
   }
   const body = schemaSnapshot(schema.body)
+  const headers = schemaSnapshot(schema.headers)
   const query = schemaSnapshot(schema.query)
   const response = schemaSnapshot(schema.response)
   const sse = schemaSnapshot(schema.sse)
   const snapped: RouteSnapshotSchema = {
+    ...(headers !== undefined ? { headers } : {}),
     ...(body !== undefined ? { body } : {}),
     ...(query !== undefined ? { query } : {}),
     ...(response !== undefined ? { response } : {}),
@@ -353,7 +356,7 @@ export function diffRouteSnapshots(
     const path = beforeRoute.path
     const beforeSchema = beforeRoute.schema ?? {}
     const afterSchema = afterRoute.schema ?? {}
-    for (const section of ["body", "query"] as const) {
+    for (const section of ["headers", "body", "query"] as const) {
       diffSchemaSection(
         { method, path, section, direction: "request", changes },
         beforeSchema[section],

package/src/errors.ts

@@ -26,6 +26,7 @@ export type RouteConfigErrorCode =
   | "INVALID_METHOD"
   | "INVALID_ASSURANCE"
   | "INVALID_IDEMPOTENCY"
+  | "INVALID_BODY_LIMIT"
 
 /**
  * Thrown at route registration when a route is misconfigured. This is the