@kya-os/checkpoint-nextjs 1.2.0 → 1.7.1

package/CHANGELOG.md

@@ -1,5 +1,164 @@
 # @kya-os/checkpoint-nextjs
 
+## 1.6.0 — Self-report SDK identity + runtime (version-gating)
+
+**Minor release — additive + a fix.** `withCheckpoint`'s detection reporter now
+self-reports `sdk: { name: '@kya-os/checkpoint-nextjs', version, runtime }` —
+with `runtime: 'node' | 'edge'` distinguishing the two entries — so the dashboard
+can version-gate "composed policy enforces here" on the actual installed SDK,
+and correctly show the **edge** runtime as opt-in (composed enforcement there
+needs `cedarWasmModule`, which detections can't observe) rather than falsely
+"Enforcing" (the @Policy version-gating work, #3076).
+
+### Fixed
+
+- **`VERSION` was stale (`0.1.0`)** — long drifted from `package.json`. It is now
+  single-sourced (re-exported from `middleware-node`) and pinned to
+  `package.json` by a unit test, so it can't drift again. This matters because
+  `VERSION` is now the SDK version the reporter self-reports for gating; the old
+  `0.1.0` would have failed the gate for every install.
+
+## 1.5.0 — Composed-policy (kya-os-engine) enforcement
+
+**Minor release — additive.** Makes a customer's `/policy-compose` output enforce
+IN-PROCESS via the shared composed-policy core
+(`@kya-os/checkpoint-wasm-runtime/composed-policy`), byte-for-byte the same as
+the DNS Gateway and `@kya-os/checkpoint-express@1.5.0` (engine = the detection +
+enforcement SSOT). Without the new `projectId` config the middleware behaves
+exactly as 1.4.0 (detection + structured policy only).
+
+### Added
+
+- **`projectId`** on `CheckpointConfig` — opt into composed-policy enforcement.
+  The project's policy is fetched from
+  `<dashboardUrl ?? baseUrl ?? default>/api/internal/policies/${projectId}`; when
+  it carries a deployed Cedar bundle with `engineEnforcementEnabled` on, the
+  engine decision is enforced in-process.
+  - **Shadow-first**: deployed-but-not-enforcing computes + logs divergence
+    (gated on `debug`) without acting.
+  - **Fail-open**: any compile/evaluation/fetch fault keeps the structured
+    decision — a policy fault never 5xxs.
+  - **Empty-Cedar guard**: blank source never reaches the evaluator.
+- **`composedPolicyEnforcer`** — advanced/testing seam to inject a pre-built
+  composed-policy context.
+- **`cedarWasmModule`** (Edge only) — the statically-imported cedar-web
+  `WebAssembly.Module` that enables composed enforcement under the Edge runtime.
+
+### Node vs Edge
+
+- **Node runtime (`./node`)** — composed enforcement is **default-on** (sync
+  `createPolicyEvaluator`; cedar loads lazily, never bundled to edge).
+- **Edge runtime (`./edge`)** — **consumer-opt-in**: the seam stays inert unless
+  the host wires `cedarWasmModule`:
+
+  ```ts
+  import cedarWasmModule from '@kya-os/checkpoint-wasm-runtime/wasm/kya-os-engine-cedar-web/kya_os_engine_bg.wasm?module';
+  export default withCheckpoint({ projectId, cedarWasmModule });
+  // next.config: experiments.asyncWebAssembly + a .wasm asset rule
+  ```
+
+  The ~2 MB cedar binary is deliberately NOT forced into every consumer's Edge
+  Middleware bundle (Vercel's plan-dependent size cap). Edge composed
+  enforcement is unproven on Vercel/webpack edge in-repo; flipping it to
+  default-on is gated on a real edge deploy measurement (follow-up). Until then,
+  edge without `cedarWasmModule` behaves exactly as 1.4.0.
+
+### Cross-runtime parity
+
+Built on the shared core, so the `VerifyResult → AuthorizeInput` projection
+(category map, verified-delegation allowlist, the `mcp_i_handshake`
+optimistic-detail override), the empty-Cedar guard, the compile cache, and the
+act-gate are identical across the DNS Gateway, Express, and Next.js. The composed
+seam runs BEFORE the detection reporter so the dashboard records the enforced
+decision (matching Express). Path comes from `req.nextUrl.pathname` (query-free,
+what verification saw); fetch base honors `dashboardUrl ?? baseUrl`.
+
+## 1.4.0 — 2026-05-26 — Detection reporter on `withCheckpoint` (closes latent bug)
+
+**Minor release.** Closes the same architectural gap as
+`@kya-os/checkpoint-express@1.4.0` — `withCheckpoint` (both Node and
+Edge variants) verified locally via WASM but had no path to ship
+detections back to the dashboard. The setup flow currently generates
+`withAgentShield` snippets (legacy `api-middleware.ts`, which has its
+own reporter), so this gap was latent in nextjs. Closing it now
+prevents the same silent-onboarding failure when customers migrate to
+the documented canonical API.
+
+### Added
+
+- **`apiKey`** on `CheckpointConfig` — wires the shared reporter from
+  `@kya-os/checkpoint-wasm-runtime/reporter`. Mirrors the express
+  config exactly. Resolve from `process.env.CHECKPOINT_API_KEY`.
+- **`baseUrl`** — override the dashboard host. Default
+  `https://kya.vouched.id`.
+- **`debug`** — surface reporter failures via `console.warn`. Default
+  `false`.
+
+Both `middleware-node.ts` and `middleware-edge.ts` wire the reporter
+from the same `_buildReporter` + `_extractReporterContext` seams, so
+Node and Edge runtimes ship byte-equivalent payloads to
+`/api/v1/log-detection`.
+
+## 1.3.0 — 2026-05-18
+
+**Minor release with BREAKING removals.** Closes the deprecation cycle
+opened in 1.1.2 via PR #2610 / AgentDetector-Deletion-1. Per project
+semver policy this is shipped as a minor bump (not a major) because:
+(a) the deprecation landed yesterday and was effectively one calendar
+day, (b) the package is pre-Adobe-trial with no external pins to
+`^1.x.0`, and (c) the workspace-wide deletion-gate test pins the absence
+structurally so re-introduction is mechanically blocked.
+
+### BREAKING — removals
+
+- **`useAgentDetection` hook removed** (`src/hooks.ts`). Wrapped the
+  legacy `AgentDetector` class that has now been removed from
+  `@kya-os/checkpoint@1.1.0`. **Migration path:** use `withCheckpoint`
+  from `@kya-os/checkpoint-nextjs` for server-side middleware
+  (engine-backed, returns canonical envelopes) or import
+  `KNOWN_AGENT_PATTERNS` directly from `@kya-os/checkpoint-shared` for
+  rare client-side pattern matching.
+- **`createWasmAgentShieldMiddleware` factory removed** along with the
+  whole `src/wasm-middleware.ts` file. It internally constructed a
+  legacy `AgentDetector` and never actually used the WASM instance for
+  detection (the `wasmInstance` arg only bumped confidence by 15%).
+  **Migration path:** `withCheckpoint` from `@kya-os/checkpoint-nextjs`
+  — engine-backed, runs the full orchestrator including envelope
+  verification.
+- **`./wasm-middleware` subpath export removed** from `package.json`
+  `exports`. Imports of
+  `@kya-os/checkpoint-nextjs/wasm-middleware` will fail to resolve.
+- **`instantiateWasm` helper removed** (was co-located in
+  `wasm-middleware.ts`). It was a one-line `WebAssembly.instantiate`
+  wrapper; customers loading WASM manually can call the Web API
+  directly. With `withCheckpoint`, manual WASM loading is no longer
+  needed at all — `@kya-os/checkpoint-wasm-runtime`'s loaders handle
+  resolution under Node and Edge runtimes.
+- **`useDetectionMonitor` continues to be exported** — it accepts any
+  `DetectionResult` and never depended on `AgentDetector`. Reusable
+  with engine-backed detection results.
+- **`middleware-wasm-100.ts` template removed** — the canonical starter
+  template is now `withCheckpoint` (see `README.md` and the templates
+  under `templates/` that already cover Node + Edge runtimes).
+
+### Removed tests
+
+- `src/__tests__/hooks.test.ts` — covered `useAgentDetection`
+  including the deprecation-warning regression test added in #2610.
+- `src/__tests__/wasm-middleware.test.ts` — covered
+  `createWasmAgentShieldMiddleware` including the deprecation-warning
+  regression test added in #2610.
+
+### Build config
+
+- `tsup.config.ts` entry list no longer references `src/wasm-middleware.ts`.
+
+### Coordination
+
+Ships alongside `@kya-os/checkpoint@1.1.0` (defining package — removes
+the `AgentDetector` class). No engine-surface change; cross-runtime
+parity gate is unaffected.
+
 ## 1.2.0 — 2026-05-18
 
 **Minor release** — peer to `@kya-os/checkpoint-wasm-runtime@1.4.0`.

package/EDGE_RUNTIME_WASM_SETUP.md

@@ -236,7 +236,7 @@ export function createAgentShieldMiddleware(options: {
         { pattern: /openai/i, name: 'OpenAI' },
         { pattern: /gpt-/i, name: 'GPT' },
         { pattern: /copilot/i, name: 'GitHub Copilot' },
-        { pattern: /bard/i, name: 'Google Bard' },
+        { pattern: /bard/i, name: 'Google Gemini' },
         { pattern: /gemini/i, name: 'Google Gemini' },
       ];
 

package/bin/setup-edge-wasm.js

@@ -310,7 +310,7 @@ function patternDetection(
     { pattern: /openai/i, name: 'OpenAI', confidence: 0.90 },
     { pattern: /gpt-crawler/i, name: 'GPT Crawler', confidence: 0.95 },
     { pattern: /copilot/i, name: 'GitHub Copilot', confidence: 0.85 },
-    { pattern: /bard/i, name: 'Google Bard', confidence: 0.85 },
+    { pattern: /bard/i, name: 'Google Gemini', confidence: 0.85 }, // legacy Bard UA → Gemini (brand retired 2024)
     { pattern: /gemini/i, name: 'Google Gemini', confidence: 0.85 },
     { pattern: /perplexity/i, name: 'Perplexity', confidence: 0.85 },
   ];

package/dist/api-middleware.d.mts

@@ -1,6 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
+import { ChallengeEnvelopeMode } from '@kya-os/checkpoint-shared';
 import { EnforcementDecision } from './api-client.mjs';
-import '@kya-os/checkpoint-shared';
 
 /**
  * API-based AgentShield Middleware for Next.js
@@ -76,6 +76,14 @@ interface CheckpointApiMiddlewareConfig {
      * @default 'instruct'
      */
     redirectMode?: 'instruct' | 'http';
+    /**
+     * Challenge-emission envelope mode (draft-kya-http-02 §8.1 fetcher-200).
+     * `negotiated` serves a body-readable HTTP 200 instruct response to
+     * cooperative agents (so fetchers that drop 4xx bodies can read it),
+     * keeping the spec 401 for everyone else. Defaults to `spec-401`.
+     * A cooperative-UX bridge, NOT an access control.
+     */
+    delegationChallengeMode?: ChallengeEnvelopeMode;
     /**
      * Custom blocked response
      */

package/dist/api-middleware.d.ts

@@ -1,6 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
+import { ChallengeEnvelopeMode } from '@kya-os/checkpoint-shared';
 import { EnforcementDecision } from './api-client.js';
-import '@kya-os/checkpoint-shared';
 
 /**
  * API-based AgentShield Middleware for Next.js
@@ -76,6 +76,14 @@ interface CheckpointApiMiddlewareConfig {
      * @default 'instruct'
      */
     redirectMode?: 'instruct' | 'http';
+    /**
+     * Challenge-emission envelope mode (draft-kya-http-02 §8.1 fetcher-200).
+     * `negotiated` serves a body-readable HTTP 200 instruct response to
+     * cooperative agents (so fetchers that drop 4xx bodies can read it),
+     * keeping the spec 401 for everyone else. Defaults to `spec-401`.
+     * A cooperative-UX bridge, NOT an access control.
+     */
+    delegationChallengeMode?: ChallengeEnvelopeMode;
     /**
      * Custom blocked response
      */

package/dist/api-middleware.js

@@ -237,7 +237,7 @@ function safeHostname(url) {
 // src/responses/agent-instruction.ts
 var MCP_I_DOCS_URL = "https://docs.knowthat.ai/mcp-i/getting-started";
 var DEFAULT_CONNECT_PATH = "/connect";
-function buildAgentInstructionResponse(request, decision, redirectUrl) {
+function buildAgentInstructionResponse(request, decision, redirectUrl, options) {
   const resolved = resolveUrl(redirectUrl ?? DEFAULT_CONNECT_PATH, request.url);
   const agentName = decision.agentName || decision.agentType || "unknown";
   if (!resolved.searchParams.has("agent")) {
@@ -288,8 +288,11 @@ It only takes a moment and you won't need to do it again. Once you're done, ask
       confidence: decision.confidence
     }
   };
-  const response = server.NextResponse.json(body, { status: 401 });
-  response.headers.set("WWW-Authenticate", `KYA realm="api", authorization_uri="${authUrl}"`);
+  const bodyReadable200 = options?.bodyReadable200 ?? false;
+  const response = server.NextResponse.json(body, { status: bodyReadable200 ? 200 : 401 });
+  if (!bodyReadable200) {
+    response.headers.set("WWW-Authenticate", `KYA realm="api", authorization_uri="${authUrl}"`);
+  }
   response.headers.set(
     "Link",
     `<${authUrl}>; rel="kya-authorize", <${MCP_I_DOCS_URL}>; rel="help"`
@@ -482,7 +485,14 @@ function withCheckpointApi(config = {}) {
             return buildRedirectResponse(request, decision, config);
           }
           const targetUrl = config.redirectUrl || decision.redirectUrl;
-          return buildAgentInstructionResponse(request, decision, targetUrl);
+          const bodyReadable200 = checkpointShared.selectBodyReadable200(
+            config.delegationChallengeMode ?? "spec-401",
+            request.headers,
+            result.data.detection?.detectionClass
+          );
+          return buildAgentInstructionResponse(request, decision, targetUrl, {
+            bodyReadable200
+          });
         }
         case "challenge": {
           return buildRedirectResponse(request, decision, config);

package/dist/api-middleware.mjs

@@ -1,5 +1,5 @@
 import { NextResponse } from 'next/server';
-import { matchPath } from '@kya-os/checkpoint-shared';
+import { selectBodyReadable200, matchPath } from '@kya-os/checkpoint-shared';
 
 // src/api-middleware.ts
 
@@ -235,7 +235,7 @@ function safeHostname(url) {
 // src/responses/agent-instruction.ts
 var MCP_I_DOCS_URL = "https://docs.knowthat.ai/mcp-i/getting-started";
 var DEFAULT_CONNECT_PATH = "/connect";
-function buildAgentInstructionResponse(request, decision, redirectUrl) {
+function buildAgentInstructionResponse(request, decision, redirectUrl, options) {
   const resolved = resolveUrl(redirectUrl ?? DEFAULT_CONNECT_PATH, request.url);
   const agentName = decision.agentName || decision.agentType || "unknown";
   if (!resolved.searchParams.has("agent")) {
@@ -286,8 +286,11 @@ It only takes a moment and you won't need to do it again. Once you're done, ask
       confidence: decision.confidence
     }
   };
-  const response = NextResponse.json(body, { status: 401 });
-  response.headers.set("WWW-Authenticate", `KYA realm="api", authorization_uri="${authUrl}"`);
+  const bodyReadable200 = options?.bodyReadable200 ?? false;
+  const response = NextResponse.json(body, { status: bodyReadable200 ? 200 : 401 });
+  if (!bodyReadable200) {
+    response.headers.set("WWW-Authenticate", `KYA realm="api", authorization_uri="${authUrl}"`);
+  }
   response.headers.set(
     "Link",
     `<${authUrl}>; rel="kya-authorize", <${MCP_I_DOCS_URL}>; rel="help"`
@@ -480,7 +483,14 @@ function withCheckpointApi(config = {}) {
             return buildRedirectResponse(request, decision, config);
           }
           const targetUrl = config.redirectUrl || decision.redirectUrl;
-          return buildAgentInstructionResponse(request, decision, targetUrl);
+          const bodyReadable200 = selectBodyReadable200(
+            config.delegationChallengeMode ?? "spec-401",
+            request.headers,
+            result.data.detection?.detectionClass
+          );
+          return buildAgentInstructionResponse(request, decision, targetUrl, {
+            bodyReadable200
+          });
         }
         case "challenge": {
           return buildRedirectResponse(request, decision, config);

package/dist/composed-policy.d.mts

@@ -0,0 +1,115 @@
+import { ComposedPolicyCompile } from '@kya-os/checkpoint-wasm-runtime/composed-policy';
+import { Decision, VerifyResult } from '@kya-os/checkpoint-wasm-runtime/engine';
+import { PolicyFetcher } from '@kya-os/checkpoint-shared';
+
+/**
+ * Composed-policy (kya-os-engine) wiring for the Next.js middleware.
+ *
+ * A THIN layer on top of the shared core
+ * (`@kya-os/checkpoint-wasm-runtime/composed-policy`): the core owns all the
+ * logic (empty-Cedar deny-all guard, compile-once LRU cache, act-gate,
+ * divergence, and the `verifyResultToAuthorizeInput` parity projection), so this
+ * module only fetches the project's `PolicyConfig`, drives the core once per
+ * request, maps the tagged outcome to a decision-swap signal, and logs
+ * (debug-gated). Runtime-neutral — the caller injects the compiler:
+ *   - Node: `(language, source) => createPolicyEvaluator(source)` (`./policy`)
+ *   - Edge: `(language, source) => evaluatePolicy(language, source)` (`./policy-edge`)
+ *
+ * This is the SDK sibling of `@kya-os/checkpoint-express`'s composed-policy
+ * wiring; both consume the same core so the DNS Gateway, Express, and Next.js
+ * produce the same decision for the same composed Cedar bundle.
+ */
+
+/** Dashboard the composed-policy fetch defaults to when no base URL is set. */
+declare const DEFAULT_DASHBOARD_URL = "https://kya.vouched.id";
+/**
+ * Telemetry sink. The shadow-divergence signal is the go/no-go instrument for
+ * flipping a project to ENFORCE. Defaults to a no-op so the SDK never logs
+ * unprompted — `withCheckpoint({ debug: true })` wires the console logger.
+ */
+interface ComposedPolicyLogger {
+    shadowDivergence(info: ShadowDivergenceInfo): void;
+    evaluationError(projectId: string, error: unknown): void;
+}
+interface ShadowDivergenceInfo {
+    projectId: string;
+    path?: string;
+    engineDecision: Decision['kind'];
+    structuredDecision: Decision['kind'];
+    detectionClass: string;
+    verificationMethod?: string;
+    confidence: number;
+    agentName?: string;
+}
+/** Result of one composed-policy evaluation: the decision to enforce + whether it replaced the baseline. */
+interface ComposedPolicyApplyResult {
+    decision: Decision;
+    acted: boolean;
+    /**
+     * SSOT-served revision pin (sha256 of the evaluated bundle, byte-identical
+     * to `policy_revisions.composed_blob_hash`) — set ONLY when `acted`, echoed
+     * from `PolicyConfig.policySourceHash` (#3246 PR5). Absent on structured
+     * decisions and when the dashboard predates the field.
+     */
+    composedBlobHash?: string;
+}
+interface ComposedPolicyContext {
+    /**
+     * Evaluate the project's composed policy for one request. Reads
+     * `result.decision` as the structured baseline for the divergence comparison;
+     * the caller applies `acted ? decision` afterwards. Never throws.
+     */
+    apply(result: VerifyResult, path: string | undefined): Promise<ComposedPolicyApplyResult>;
+    /**
+     * Resolve the org's trusted Layer-2 delegation root DIDs from the project's
+     * policy payload (P2 / DR-1). The middleware forwards these into the engine's
+     * `ContextSpec.trustedDelegationRoots` on delegation requests. Optional so an
+     * injected `composedPolicyEnforcer` (advanced/testing) need not implement it —
+     * absence ⇒ no roots ⇒ the engine's open default. Never throws (a fetch fault
+     * resolves to `[]`).
+     */
+    trustedDelegationRoots?(): Promise<string[]>;
+}
+interface MakeComposedPolicyContextOptions {
+    projectId: string;
+    /** Fetches the project's `PolicyConfig` (carries the composed-policy fields). */
+    fetcher: PolicyFetcher;
+    /** Target compiler — Node `createPolicyEvaluator`-backed or edge `evaluatePolicy`. */
+    compile: ComposedPolicyCompile;
+    logger?: ComposedPolicyLogger;
+    cacheMax?: number;
+}
+declare function makeComposedPolicyContext(opts: MakeComposedPolicyContextOptions): ComposedPolicyContext;
+/**
+ * Resolves the org's trusted delegation roots (empty when none). Built per
+ * middleware factory from whatever source can supply them — the composed
+ * context's accessor, or (when no context exists, e.g. Edge without
+ * `cedarWasmModule`) a `projectId`-only policy fetch.
+ */
+type TrustedDelegationRootsResolver = () => Promise<string[]>;
+/**
+ * Resolve the org trusted-delegation roots to inject into the engine for THIS
+ * request (P2 / DR-1). Returns `undefined` — leaving `VerifyRequestOpts`
+ * byte-identical to pre-P2 — unless (a) a resolver is configured and (b) the
+ * request actually carries a delegation-proof header (so the human /
+ * no-delegation hot path never pays the early policy fetch). Shared by the Node
+ * and Edge middleware entries.
+ */
+declare function resolveTrustedDelegationRootsForRequest(resolver: TrustedDelegationRootsResolver | null, headers: Headers): Promise<string[] | undefined>;
+/**
+ * The per-request seam shared by both middleware entries. Evaluates the composed
+ * policy and swaps `result.decision` IN PLACE when the engine acts — so the
+ * swap happens BEFORE the detection reporter fires and before
+ * `renderDecisionAsResponse`, exactly like the Express runtime (the reporter
+ * records the enforced decision). Fail-OPEN: any fault keeps the structured
+ * decision; a policy fault never breaks the response.
+ */
+declare function applyComposedPolicy(context: ComposedPolicyContext | null, result: VerifyResult, path: string | undefined): Promise<void>;
+/**
+ * Debug logger mirroring the worker's `console.warn`/`console.error` shadow +
+ * fail-open telemetry. Wired by `withCheckpoint` only when `config.debug` is
+ * set, so the default SDK posture stays silent.
+ */
+declare const consoleComposedPolicyLogger: ComposedPolicyLogger;
+
+export { type ComposedPolicyApplyResult, type ComposedPolicyContext, type ComposedPolicyLogger, DEFAULT_DASHBOARD_URL, type MakeComposedPolicyContextOptions, type ShadowDivergenceInfo, type TrustedDelegationRootsResolver, applyComposedPolicy, consoleComposedPolicyLogger, makeComposedPolicyContext, resolveTrustedDelegationRootsForRequest };

package/dist/composed-policy.d.ts

@@ -0,0 +1,115 @@
+import { ComposedPolicyCompile } from '@kya-os/checkpoint-wasm-runtime/composed-policy';
+import { Decision, VerifyResult } from '@kya-os/checkpoint-wasm-runtime/engine';
+import { PolicyFetcher } from '@kya-os/checkpoint-shared';
+
+/**
+ * Composed-policy (kya-os-engine) wiring for the Next.js middleware.
+ *
+ * A THIN layer on top of the shared core
+ * (`@kya-os/checkpoint-wasm-runtime/composed-policy`): the core owns all the
+ * logic (empty-Cedar deny-all guard, compile-once LRU cache, act-gate,
+ * divergence, and the `verifyResultToAuthorizeInput` parity projection), so this
+ * module only fetches the project's `PolicyConfig`, drives the core once per
+ * request, maps the tagged outcome to a decision-swap signal, and logs
+ * (debug-gated). Runtime-neutral — the caller injects the compiler:
+ *   - Node: `(language, source) => createPolicyEvaluator(source)` (`./policy`)
+ *   - Edge: `(language, source) => evaluatePolicy(language, source)` (`./policy-edge`)
+ *
+ * This is the SDK sibling of `@kya-os/checkpoint-express`'s composed-policy
+ * wiring; both consume the same core so the DNS Gateway, Express, and Next.js
+ * produce the same decision for the same composed Cedar bundle.
+ */
+
+/** Dashboard the composed-policy fetch defaults to when no base URL is set. */
+declare const DEFAULT_DASHBOARD_URL = "https://kya.vouched.id";
+/**
+ * Telemetry sink. The shadow-divergence signal is the go/no-go instrument for
+ * flipping a project to ENFORCE. Defaults to a no-op so the SDK never logs
+ * unprompted — `withCheckpoint({ debug: true })` wires the console logger.
+ */
+interface ComposedPolicyLogger {
+    shadowDivergence(info: ShadowDivergenceInfo): void;
+    evaluationError(projectId: string, error: unknown): void;
+}
+interface ShadowDivergenceInfo {
+    projectId: string;
+    path?: string;
+    engineDecision: Decision['kind'];
+    structuredDecision: Decision['kind'];
+    detectionClass: string;
+    verificationMethod?: string;
+    confidence: number;
+    agentName?: string;
+}
+/** Result of one composed-policy evaluation: the decision to enforce + whether it replaced the baseline. */
+interface ComposedPolicyApplyResult {
+    decision: Decision;
+    acted: boolean;
+    /**
+     * SSOT-served revision pin (sha256 of the evaluated bundle, byte-identical
+     * to `policy_revisions.composed_blob_hash`) — set ONLY when `acted`, echoed
+     * from `PolicyConfig.policySourceHash` (#3246 PR5). Absent on structured
+     * decisions and when the dashboard predates the field.
+     */
+    composedBlobHash?: string;
+}
+interface ComposedPolicyContext {
+    /**
+     * Evaluate the project's composed policy for one request. Reads
+     * `result.decision` as the structured baseline for the divergence comparison;
+     * the caller applies `acted ? decision` afterwards. Never throws.
+     */
+    apply(result: VerifyResult, path: string | undefined): Promise<ComposedPolicyApplyResult>;
+    /**
+     * Resolve the org's trusted Layer-2 delegation root DIDs from the project's
+     * policy payload (P2 / DR-1). The middleware forwards these into the engine's
+     * `ContextSpec.trustedDelegationRoots` on delegation requests. Optional so an
+     * injected `composedPolicyEnforcer` (advanced/testing) need not implement it —
+     * absence ⇒ no roots ⇒ the engine's open default. Never throws (a fetch fault
+     * resolves to `[]`).
+     */
+    trustedDelegationRoots?(): Promise<string[]>;
+}
+interface MakeComposedPolicyContextOptions {
+    projectId: string;
+    /** Fetches the project's `PolicyConfig` (carries the composed-policy fields). */
+    fetcher: PolicyFetcher;
+    /** Target compiler — Node `createPolicyEvaluator`-backed or edge `evaluatePolicy`. */
+    compile: ComposedPolicyCompile;
+    logger?: ComposedPolicyLogger;
+    cacheMax?: number;
+}
+declare function makeComposedPolicyContext(opts: MakeComposedPolicyContextOptions): ComposedPolicyContext;
+/**
+ * Resolves the org's trusted delegation roots (empty when none). Built per
+ * middleware factory from whatever source can supply them — the composed
+ * context's accessor, or (when no context exists, e.g. Edge without
+ * `cedarWasmModule`) a `projectId`-only policy fetch.
+ */
+type TrustedDelegationRootsResolver = () => Promise<string[]>;
+/**
+ * Resolve the org trusted-delegation roots to inject into the engine for THIS
+ * request (P2 / DR-1). Returns `undefined` — leaving `VerifyRequestOpts`
+ * byte-identical to pre-P2 — unless (a) a resolver is configured and (b) the
+ * request actually carries a delegation-proof header (so the human /
+ * no-delegation hot path never pays the early policy fetch). Shared by the Node
+ * and Edge middleware entries.
+ */
+declare function resolveTrustedDelegationRootsForRequest(resolver: TrustedDelegationRootsResolver | null, headers: Headers): Promise<string[] | undefined>;
+/**
+ * The per-request seam shared by both middleware entries. Evaluates the composed
+ * policy and swaps `result.decision` IN PLACE when the engine acts — so the
+ * swap happens BEFORE the detection reporter fires and before
+ * `renderDecisionAsResponse`, exactly like the Express runtime (the reporter
+ * records the enforced decision). Fail-OPEN: any fault keeps the structured
+ * decision; a policy fault never breaks the response.
+ */
+declare function applyComposedPolicy(context: ComposedPolicyContext | null, result: VerifyResult, path: string | undefined): Promise<void>;
+/**
+ * Debug logger mirroring the worker's `console.warn`/`console.error` shadow +
+ * fail-open telemetry. Wired by `withCheckpoint` only when `config.debug` is
+ * set, so the default SDK posture stays silent.
+ */
+declare const consoleComposedPolicyLogger: ComposedPolicyLogger;
+
+export { type ComposedPolicyApplyResult, type ComposedPolicyContext, type ComposedPolicyLogger, DEFAULT_DASHBOARD_URL, type MakeComposedPolicyContextOptions, type ShadowDivergenceInfo, type TrustedDelegationRootsResolver, applyComposedPolicy, consoleComposedPolicyLogger, makeComposedPolicyContext, resolveTrustedDelegationRootsForRequest };

package/dist/composed-policy.js

@@ -0,0 +1,102 @@
+'use strict';
+
+var composedPolicy = require('@kya-os/checkpoint-wasm-runtime/composed-policy');
+var checkpointShared = require('@kya-os/checkpoint-shared');
+
+// src/composed-policy.ts
+var DEFAULT_DASHBOARD_URL = "https://kya.vouched.id";
+var NOOP_LOGGER = {
+  shadowDivergence: () => {
+  },
+  evaluationError: () => {
+  }
+};
+function makeComposedPolicyContext(opts) {
+  const { projectId, fetcher } = opts;
+  const cache = composedPolicy.makeComposedPolicyCache({ compile: opts.compile, cacheMax: opts.cacheMax });
+  const logger = opts.logger ?? NOOP_LOGGER;
+  return {
+    async apply(result, path) {
+      const structured = { decision: result.decision, acted: false };
+      const policy = await fetcher.getPolicy(projectId);
+      const outcome = await composedPolicy.evaluateComposedPolicy({
+        cache,
+        projectId,
+        flags: {
+          policyLanguage: policy.policyLanguage,
+          policySourceText: policy.policySourceText,
+          engineEnforcementEnabled: policy.engineEnforcementEnabled,
+          enabled: policy.enabled
+        },
+        authorizeInput: composedPolicy.verifyResultToAuthorizeInput(result, { tenantId: projectId, path }),
+        baselineDecisionKind: result.decision.kind
+      });
+      if ((outcome.status === "acting" || outcome.status === "shadow") && outcome.diverged) {
+        logger.shadowDivergence({
+          projectId,
+          path,
+          engineDecision: outcome.engineDecision.kind,
+          structuredDecision: result.decision.kind,
+          detectionClass: result.detectionDetail.detectionClass.type,
+          verificationMethod: result.detectionDetail.verificationMethod,
+          confidence: result.detectionDetail.confidence,
+          agentName: result.detectionDetail.detectedAgent?.name
+        });
+      }
+      if (outcome.status === "error") {
+        logger.evaluationError(projectId, outcome.error);
+        return structured;
+      }
+      if (outcome.status === "acting") {
+        return {
+          decision: outcome.engineDecision,
+          acted: true,
+          // Echo the SSOT revision pin with the decision it produced (#3246
+          // PR5). Conditional spread: absent upstream stays absent here.
+          ...policy.policySourceHash ? { composedBlobHash: policy.policySourceHash } : {}
+        };
+      }
+      return structured;
+    },
+    async trustedDelegationRoots() {
+      const policy = await fetcher.getPolicy(projectId);
+      return policy.trustedDelegationRoots ?? [];
+    }
+  };
+}
+async function resolveTrustedDelegationRootsForRequest(resolver, headers) {
+  if (!resolver) return void 0;
+  if (!checkpointShared.requestCarriesDelegationProof(headers)) return void 0;
+  const roots = await resolver();
+  return roots.length > 0 ? roots : void 0;
+}
+async function applyComposedPolicy(context, result, path) {
+  if (!context) return;
+  try {
+    const outcome = await context.apply(result, path);
+    if (outcome.acted) {
+      result.decision = outcome.decision;
+      if (outcome.composedBlobHash) {
+        result.composedBlobHash = outcome.composedBlobHash;
+      }
+    }
+  } catch {
+  }
+}
+var consoleComposedPolicyLogger = {
+  shadowDivergence(info) {
+    console.warn("[checkpoint/composed-policy] shadow-divergence", info);
+  },
+  evaluationError(projectId, error) {
+    console.error(
+      `[checkpoint/composed-policy] evaluation failed for ${projectId}; using structured decision:`,
+      error
+    );
+  }
+};
+
+exports.DEFAULT_DASHBOARD_URL = DEFAULT_DASHBOARD_URL;
+exports.applyComposedPolicy = applyComposedPolicy;
+exports.consoleComposedPolicyLogger = consoleComposedPolicyLogger;
+exports.makeComposedPolicyContext = makeComposedPolicyContext;
+exports.resolveTrustedDelegationRootsForRequest = resolveTrustedDelegationRootsForRequest;