@kya-os/checkpoint-wasm-runtime 1.1.1 → 1.1.2

package/dist/index.d.mts

@@ -1,7 +1,74 @@
-import { I as IDetectorOptions, a as IDetector } from './rules-detector-DjbTJ1-Q.mjs';
-export { C as CONFIDENCE, D as DetectionClass, F as ForgeabilityRisk, b as ICustomerPolicy, c as IDetectedAgent, d as IDetectionInput, e as IDetectionResult, f as IPathRule, g as IPolicyLoader, h as IWasmBindings, i as IWasmLoader, P as PolicyLoadError, j as PolicyLoader, k as PolicyLoaderConfig, R as RulesDetector, V as VerificationMethod, W as WasmDetector, l as createPolicyLoader, m as createRulesDetector } from './rules-detector-DjbTJ1-Q.mjs';
-export { S as StaticWasmLoader, c as createStaticLoader } from './static-loader-Ds4iNw7c.mjs';
-export { D as DynamicWasmLoader, c as createDynamicLoader } from './dynamic-loader-qGJacfEC.mjs';
+import { h as IWasmLoader, l as IWasmBindings, a as IDetectorOptions, I as IDetector } from './rules-detector-ZIKHN-_y.mjs';
+export { C as CONFIDENCE, D as DetectionClass, c as DynamicWasmLoader, F as ForgeabilityRisk, d as ICustomerPolicy, e as IDetectedAgent, b as IDetectionInput, f as IDetectionResult, m as IPathRule, g as IPolicyLoader, n as PolicyLoadError, P as PolicyLoader, o as PolicyLoaderConfig, R as RulesDetector, V as VerificationMethod, W as WasmDetector, i as createDynamicLoader, j as createPolicyLoader, k as createRulesDetector } from './rules-detector-ZIKHN-_y.mjs';
+
+/**
+ * Static WASM Loader for Edge Runtime
+ *
+ * This loader is designed for environments that require static WASM imports,
+ * such as Vercel Edge Runtime and Cloudflare Workers.
+ *
+ * Usage:
+ * ```typescript
+ * // In your middleware.ts:
+ * import wasmModule from '@kya-os/checkpoint-wasm-runtime/wasm?module';
+ * import { StaticWasmLoader, WasmDetector } from '@kya-os/checkpoint-wasm-runtime/edge';
+ *
+ * const loader = new StaticWasmLoader(wasmModule);
+ * const detector = new WasmDetector(loader);
+ * ```
+ *
+ * The `?module` suffix tells bundlers (webpack, esbuild) to import the WASM
+ * as a pre-compiled WebAssembly.Module, which is required for Edge Runtime.
+ */
+
+/**
+ * Static WASM Loader
+ *
+ * For Edge Runtime environments that require pre-compiled WASM modules.
+ * The consumer must provide the WASM module via a static import with `?module` suffix.
+ *
+ * This loader uses the wasm-bindgen generated JS glue code to properly
+ * initialize the WASM module with all required imports.
+ */
+declare class StaticWasmLoader implements IWasmLoader {
+    private readonly wasmModule;
+    private bindings;
+    private loadPromise;
+    private wasmExports;
+    /**
+     * Create a new StaticWasmLoader
+     * @param wasmModule - Pre-compiled WebAssembly.Module from static import
+     */
+    constructor(wasmModule: WebAssembly.Module);
+    /**
+     * Load and instantiate the WASM module
+     */
+    load(): Promise<void>;
+    /**
+     * Internal load implementation using wasm-bindgen initSync
+     */
+    private doLoad;
+    /**
+     * Get the WASM bindings after loading
+     */
+    getBindings(): IWasmBindings;
+    /**
+     * Check if WASM is loaded
+     */
+    isLoaded(): boolean;
+    /**
+     * Get the loading strategy name
+     */
+    getStrategy(): string;
+    /**
+     * Create bindings wrapper using wasm-bindgen exports
+     */
+    private createBindings;
+}
+/**
+ * Create a static loader with validation
+ */
+declare function createStaticLoader(wasmModule: WebAssembly.Module): StaticWasmLoader;
 
 /**
  * Create a detector with automatic runtime selection
@@ -55,4 +122,4 @@ declare function createEdgeDetector(wasmModule: WebAssembly.Module, options?: ID
  */
 declare function createFallbackDetector(): IDetector;
 
-export { IDetector, IDetectorOptions, createDetector, createEdgeDetector, createFallbackDetector };
+export { IDetector, IDetectorOptions, IWasmBindings, IWasmLoader, StaticWasmLoader, createDetector, createEdgeDetector, createFallbackDetector, createStaticLoader };

package/dist/index.d.ts

@@ -1,7 +1,74 @@
-import { I as IDetectorOptions, a as IDetector } from './rules-detector-DjbTJ1-Q.js';
-export { C as CONFIDENCE, D as DetectionClass, F as ForgeabilityRisk, b as ICustomerPolicy, c as IDetectedAgent, d as IDetectionInput, e as IDetectionResult, f as IPathRule, g as IPolicyLoader, h as IWasmBindings, i as IWasmLoader, P as PolicyLoadError, j as PolicyLoader, k as PolicyLoaderConfig, R as RulesDetector, V as VerificationMethod, W as WasmDetector, l as createPolicyLoader, m as createRulesDetector } from './rules-detector-DjbTJ1-Q.js';
-export { S as StaticWasmLoader, c as createStaticLoader } from './static-loader-C1hUlksK.js';
-export { D as DynamicWasmLoader, c as createDynamicLoader } from './dynamic-loader-cS-pUisw.js';
+import { h as IWasmLoader, l as IWasmBindings, a as IDetectorOptions, I as IDetector } from './rules-detector-ZIKHN-_y.js';
+export { C as CONFIDENCE, D as DetectionClass, c as DynamicWasmLoader, F as ForgeabilityRisk, d as ICustomerPolicy, e as IDetectedAgent, b as IDetectionInput, f as IDetectionResult, m as IPathRule, g as IPolicyLoader, n as PolicyLoadError, P as PolicyLoader, o as PolicyLoaderConfig, R as RulesDetector, V as VerificationMethod, W as WasmDetector, i as createDynamicLoader, j as createPolicyLoader, k as createRulesDetector } from './rules-detector-ZIKHN-_y.js';
+
+/**
+ * Static WASM Loader for Edge Runtime
+ *
+ * This loader is designed for environments that require static WASM imports,
+ * such as Vercel Edge Runtime and Cloudflare Workers.
+ *
+ * Usage:
+ * ```typescript
+ * // In your middleware.ts:
+ * import wasmModule from '@kya-os/checkpoint-wasm-runtime/wasm?module';
+ * import { StaticWasmLoader, WasmDetector } from '@kya-os/checkpoint-wasm-runtime/edge';
+ *
+ * const loader = new StaticWasmLoader(wasmModule);
+ * const detector = new WasmDetector(loader);
+ * ```
+ *
+ * The `?module` suffix tells bundlers (webpack, esbuild) to import the WASM
+ * as a pre-compiled WebAssembly.Module, which is required for Edge Runtime.
+ */
+
+/**
+ * Static WASM Loader
+ *
+ * For Edge Runtime environments that require pre-compiled WASM modules.
+ * The consumer must provide the WASM module via a static import with `?module` suffix.
+ *
+ * This loader uses the wasm-bindgen generated JS glue code to properly
+ * initialize the WASM module with all required imports.
+ */
+declare class StaticWasmLoader implements IWasmLoader {
+    private readonly wasmModule;
+    private bindings;
+    private loadPromise;
+    private wasmExports;
+    /**
+     * Create a new StaticWasmLoader
+     * @param wasmModule - Pre-compiled WebAssembly.Module from static import
+     */
+    constructor(wasmModule: WebAssembly.Module);
+    /**
+     * Load and instantiate the WASM module
+     */
+    load(): Promise<void>;
+    /**
+     * Internal load implementation using wasm-bindgen initSync
+     */
+    private doLoad;
+    /**
+     * Get the WASM bindings after loading
+     */
+    getBindings(): IWasmBindings;
+    /**
+     * Check if WASM is loaded
+     */
+    isLoaded(): boolean;
+    /**
+     * Get the loading strategy name
+     */
+    getStrategy(): string;
+    /**
+     * Create bindings wrapper using wasm-bindgen exports
+     */
+    private createBindings;
+}
+/**
+ * Create a static loader with validation
+ */
+declare function createStaticLoader(wasmModule: WebAssembly.Module): StaticWasmLoader;
 
 /**
  * Create a detector with automatic runtime selection
@@ -55,4 +122,4 @@ declare function createEdgeDetector(wasmModule: WebAssembly.Module, options?: ID
  */
 declare function createFallbackDetector(): IDetector;
 
-export { IDetector, IDetectorOptions, createDetector, createEdgeDetector, createFallbackDetector };
+export { IDetector, IDetectorOptions, IWasmBindings, IWasmLoader, StaticWasmLoader, createDetector, createEdgeDetector, createFallbackDetector, createStaticLoader };

package/dist/index.js

@@ -2,6 +2,8 @@
 
 var checkpointShared = require('@kya-os/checkpoint-shared');
 
+// ../../node_modules/.pnpm/tsup@8.5.0_@swc+core@1.15.32_jiti@2.6.1_postcss@8.5.8_tsx@4.21.0_typescript@5.9.3_yaml@2.8.3/node_modules/tsup/assets/cjs_shims.js
+
 // src/types.ts
 var CONFIDENCE = {
   /** Minimum confidence for isAgent=true */

package/dist/node.d.mts

@@ -1,6 +1,5 @@
-import { a as IDetector, I as IDetectorOptions, d as IDetectionInput } from './rules-detector-DjbTJ1-Q.mjs';
-export { C as CONFIDENCE, D as DetectionClass, F as ForgeabilityRisk, b as ICustomerPolicy, c as IDetectedAgent, e as IDetectionResult, g as IPolicyLoader, i as IWasmLoader, j as PolicyLoader, R as RulesDetector, V as VerificationMethod, W as WasmDetector, l as createPolicyLoader, m as createRulesDetector } from './rules-detector-DjbTJ1-Q.mjs';
-export { D as DynamicWasmLoader, c as createDynamicLoader } from './dynamic-loader-qGJacfEC.mjs';
+import { I as IDetector, a as IDetectorOptions, b as IDetectionInput } from './rules-detector-ZIKHN-_y.mjs';
+export { C as CONFIDENCE, D as DetectionClass, c as DynamicWasmLoader, F as ForgeabilityRisk, d as ICustomerPolicy, e as IDetectedAgent, f as IDetectionResult, g as IPolicyLoader, h as IWasmLoader, P as PolicyLoader, R as RulesDetector, V as VerificationMethod, W as WasmDetector, i as createDynamicLoader, j as createPolicyLoader, k as createRulesDetector } from './rules-detector-ZIKHN-_y.mjs';
 
 /**
  * Create a detector for Node.js with dynamic WASM loading

package/dist/node.d.ts

@@ -1,6 +1,5 @@
-import { a as IDetector, I as IDetectorOptions, d as IDetectionInput } from './rules-detector-DjbTJ1-Q.js';
-export { C as CONFIDENCE, D as DetectionClass, F as ForgeabilityRisk, b as ICustomerPolicy, c as IDetectedAgent, e as IDetectionResult, g as IPolicyLoader, i as IWasmLoader, j as PolicyLoader, R as RulesDetector, V as VerificationMethod, W as WasmDetector, l as createPolicyLoader, m as createRulesDetector } from './rules-detector-DjbTJ1-Q.js';
-export { D as DynamicWasmLoader, c as createDynamicLoader } from './dynamic-loader-cS-pUisw.js';
+import { I as IDetector, a as IDetectorOptions, b as IDetectionInput } from './rules-detector-ZIKHN-_y.js';
+export { C as CONFIDENCE, D as DetectionClass, c as DynamicWasmLoader, F as ForgeabilityRisk, d as ICustomerPolicy, e as IDetectedAgent, f as IDetectionResult, g as IPolicyLoader, h as IWasmLoader, P as PolicyLoader, R as RulesDetector, V as VerificationMethod, W as WasmDetector, i as createDynamicLoader, j as createPolicyLoader, k as createRulesDetector } from './rules-detector-ZIKHN-_y.js';
 
 /**
  * Create a detector for Node.js with dynamic WASM loading

package/dist/orchestrator-edge.d.mts

@@ -1,9 +1,203 @@
 export { initEngineEdge } from './engine-edge.mjs';
-import { V as VerifyResult } from './types-D0j85fF0.mjs';
-import { V as VerifyRequestOpts, I as IncomingHttpLike } from './render-decision-C1a-iuiW.mjs';
-export { B as BuildAgentRequestOpts, R as RenderedResponse, b as buildAgentRequest, e as extractAgentDid, a as extractCredentialStatusUrl, c as extractIssuer, h as hasMalformedJwsBody, r as renderDecisionAsResponse } from './render-decision-C1a-iuiW.mjs';
+import { E as EnforcementMode, A as AgentRequest, V as VerifyResult } from './types-D0j85fF0.mjs';
+import { DidResolverAdapter, StatusListCacheAdapter, ReputationOracleAdapter, PolicyEvaluatorAdapter, ClockAdapter } from './adapters.mjs';
 import '@kya-os/checkpoint-shared';
-import './adapters.mjs';
+
+/**
+ * Orchestrator-layer types — Phase C, host-side only.
+ *
+ * Nothing here crosses the WASM boundary. The engine ABI types live
+ * in `../types.ts`; the adapter interfaces live in
+ * `../adapters/index.ts`. This file is the host-wrapper-facing
+ * surface — what Phase D (Next.js) and Phase E (Express) import.
+ */
+
+/**
+ * Framework-agnostic HTTP request shape.
+ *
+ * Next.js / Express / Cloudflare Workers / Hono adapters marshal
+ * their native request type into this shape before calling
+ * `verifyRequest`. The shape is intentionally minimal — only what
+ * the engine needs to make a verdict.
+ */
+interface IncomingHttpLike {
+    method: string;
+    /** Path + query string (no scheme + host). */
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+    /**
+     * Parsed body if the framework has already parsed it (Next.js
+     * with `await req.json()`, Express with `body-parser`). Falsy if
+     * the caller hasn't materialised the body — the orchestrator
+     * treats that as "no MCP-I envelope present" and routes to
+     * PlainHttp.
+     */
+    body?: Buffer | string | object | null;
+    /** Client IP if the framework surfaces one (Express `req.ip`). */
+    remoteAddress?: string;
+}
+/**
+ * Options the host wrapper passes per-`verifyRequest`-construction.
+ * The five adapters + clock + tenant identifier + enforcement mode.
+ */
+interface VerifyRequestOpts {
+    didResolver: DidResolverAdapter;
+    statusListCache: StatusListCacheAdapter;
+    reputationOracle: ReputationOracleAdapter;
+    policyEvaluator: PolicyEvaluatorAdapter;
+    clock: ClockAdapter;
+    /** Tenant identifier — the host customer this request targets. */
+    tenantHost: string;
+    enforcementMode: EnforcementMode;
+    /** Returned to the PolicyEvaluator when the request has no agent DID. Default 1.0. */
+    reputationBaseline?: number;
+    /**
+     * **Envelope-1 (#2537) coordination flag.** Pre-Envelope-1 the TS
+     * bouncer ships MCP-I proofs as `{protected,payload,signature}` JSON
+     * in a `KYA-Delegation` header. Post-Envelope-1 they ship compact
+     * JWS in `_meta.proof.jws` of the body. When this flag is true the
+     * orchestrator also accepts the legacy header form. **Default off.**
+     * Delete this flag once Envelope-1 ships end-to-end.
+     */
+    legacyEnvelopeFallback?: boolean;
+    /**
+     * Argus URL — passed only so the orchestrator can detect "Argus
+     * not configured" at construction time and log the one-shot
+     * warning. The actual reputation fetch goes through `reputationOracle`.
+     */
+    argusUrl?: string;
+    /** Injectable for the once-only Argus configuration warning. */
+    logger?: (msg: string) => void;
+}
+/**
+ * Transport-agnostic response shape `renderDecisionAsResponse`
+ * produces. Host wrappers adapt this to their framework's response
+ * type (NextResponse / Express `res` / Cloudflare Response).
+ *
+ * `status === null` means "pass through" — the request continues to
+ * the next handler. Happens in two cases:
+ *   1. `Decision::Permit` (no block in Enforce mode).
+ *   2. **Any verdict in Observe mode** — Observe never blocks, but
+ *      the response headers still carry the would-have-been verdict.
+ */
+interface RenderedResponse {
+    status: number | null;
+    headers: Record<string, string>;
+    body?: string | object;
+}
+
+/**
+ * HTTP-to-`AgentRequest` translator — Phase C.1.
+ *
+ * Detects which engine protocol the request belongs to and builds
+ * the typed `AgentRequest` the WASM consumes. Conservative
+ * detection: never escalates an ambiguous request into a higher
+ * verification tier. Anonymous PlainHttp is the default.
+ *
+ * **What this layer parses and what it doesn't.** It parses *only
+ * what's needed to drive conditional pre-fetch* — header presence,
+ * the MCP-I envelope's payload segment (to extract `iss` + `sub` +
+ * optional credentialStatus URL). It does **not** verify
+ * signatures, decode VC chains for revocation bits, or evaluate
+ * scope. Those live in the engine (H-1's parser + Stages 2-5).
+ *
+ * **Buffer-portability note.** This module uses `Buffer.from(...)` and
+ * `Buffer.isBuffer(...)` at multiple call sites (the JWS preflight
+ * `hasMalformedJwsBody`, both `tryBuildMcpIFromBody` variants, the
+ * legacy-header reconstitution path, and `bodyAsBytes`). All of these
+ * assume the Node `Buffer` global is available — provided natively by
+ * the Node runtime, polyfilled on Vercel Edge, and gated behind
+ * `nodejs_compat` on Cloudflare Workers. Bare-Edge and pure-browser
+ * embedders would need a `Buffer` polyfill or a refactor to
+ * `TextEncoder` / `Uint8Array.from`. Tracked as a follow-up since
+ * Phase D's Vercel Node + Vercel Edge targets are both covered today.
+ */
+
+interface BuildAgentRequestOpts {
+    /** See `VerifyRequestOpts.legacyEnvelopeFallback`. */
+    legacyEnvelopeFallback?: boolean;
+}
+/**
+ * Translate an HTTP-like request into the engine's `AgentRequest`.
+ *
+ * Detection order (conservative — never escalate ambiguous input):
+ *   1. MCP-I L2 detached proof in `_meta.proof.jws` (spec form).
+ *   2. (Legacy, opt-in) MCP-I in `KYA-Delegation` header
+ *      (Envelope-1 #2537 transition window only).
+ *   3. RFC 9421 HTTP Message Signatures (`Signature-Input` header).
+ *   4. PlainHttp (default — anonymous traffic).
+ */
+declare function buildAgentRequest(req: IncomingHttpLike, opts?: BuildAgentRequestOpts): AgentRequest;
+/**
+ * Preflight check — does the request body carry a `_meta.proof.jws`
+ * string that `parseJwsPayloadStruct` cannot project into a typed
+ * `McpIPayload`?
+ *
+ * The caller declared intent (an MCP-I envelope) by including the
+ * JWS field; structural failure to extract the payload means the
+ * envelope is malformed, not absent. Without this preflight, the
+ * orchestrator would silently fall through to PlainHttp — pre-#2560
+ * that happened to also Block (engine returned `Block(ParseError)`
+ * for every PlainHttp), so the regression was invisible; post-#2560
+ * the engine's Stage 1 + stub policy returns `Permit` for anonymous
+ * PlainHttp and tampered envelopes would be silently accepted.
+ *
+ * Returns `true` when the orchestrator should synthesize
+ * `Block(ParseError)` BEFORE calling `buildAgentRequest`.
+ */
+declare function hasMalformedJwsBody(req: IncomingHttpLike): boolean;
+/**
+ * Issuer DID — Stage 1 (identity resolution) targets this. `null`
+ * for PlainHttp (anonymous → no DID to resolve).
+ */
+declare function extractIssuer(request: AgentRequest): string | null;
+/**
+ * Agent DID — used by ReputationOracle. Defaults to `payload.sub`
+ * for MCP-I (subject = the agent the proof is *about*).
+ */
+declare function extractAgentDid(request: AgentRequest): string | null;
+/**
+ * Status-list URL for revocation pre-fetch. Pulled from the JWS
+ * payload's `vc.credentialStatus.id` (W3C VC Data Model 1.1).
+ * `null` when the envelope is L1 (no VC chain) — Stage 3 will skip.
+ */
+declare function extractCredentialStatusUrl(request: AgentRequest): string | null;
+
+/**
+ * Transport-agnostic `Decision` → HTTP renderer — Phase C.3.
+ *
+ * Translates a `VerifyResult` into a framework-neutral
+ * `{ status, headers, body }` shape. Phase D (Next.js) adapts this
+ * to `NextResponse`; Phase E (Express) adapts it to `res.status().set().send()`.
+ * One source of truth for the verdict→HTTP mapping.
+ *
+ * Mapping table (§ 4.5 of Phase C kickoff):
+ *
+ * | Decision                          | HTTP | Notes                                   |
+ * |-----------------------------------|------|-----------------------------------------|
+ * | Permit                            | null | Pass through to next handler            |
+ * | Block(Unauthenticated)            | 401  | WWW-Authenticate header                 |
+ * | Block(InvalidSignature)           | 403  |                                          |
+ * | Block(Revoked)                    | 403  |                                          |
+ * | Block(Expired)                    | 401  | Refresh-the-credential semantics        |
+ * | Block(OutOfScope)                 | 403  | Body carries requested + granted        |
+ * | Block(LowReputation)              | 403  | Body carries score + threshold          |
+ * | Block(PolicyDenied)               | 403  | Body carries detail                     |
+ * | Block(ParseError)                 | 400  | Body carries detail                     |
+ * | Challenge                         | 401  | Body carries ChallengeParams            |
+ * | Redirect                          | 302  | Location header                         |
+ * | Instruct                          | 422  | application/problem+json body           |
+ *
+ * Observe mode overrides: every verdict renders as `status: null`
+ * (pass through) with an `X-Checkpoint-Would-Have-Been` header
+ * carrying the verdict kind, plus the standard attribution headers.
+ *
+ * Every response carries the Phase 0.1 attribution headers:
+ * `X-Checkpoint-Engine`, `X-Checkpoint-Engine-Version`, and
+ * (when present) `X-Checkpoint-Ruleset-Hash`.
+ */
+
+declare function renderDecisionAsResponse(result: VerifyResult): RenderedResponse;
 
 /**
  * `verifyRequestEdge` async-init orchestrator — Edge-WASM-2 (folded into
@@ -46,4 +240,4 @@ declare function makeVerifyRequestEdge(opts: VerifyRequestOpts): (req: IncomingH
  */
 declare function verifyRequestEdge(req: IncomingHttpLike, opts: VerifyRequestOpts): Promise<VerifyResult>;
 
-export { IncomingHttpLike, VerifyRequestOpts, makeVerifyRequestEdge, verifyRequestEdge };
+export { type BuildAgentRequestOpts, type IncomingHttpLike, type RenderedResponse, type VerifyRequestOpts, buildAgentRequest, extractAgentDid, extractCredentialStatusUrl, extractIssuer, hasMalformedJwsBody, makeVerifyRequestEdge, renderDecisionAsResponse, verifyRequestEdge };

package/dist/orchestrator-edge.d.ts

@@ -1,9 +1,203 @@
 export { initEngineEdge } from './engine-edge.js';
-import { V as VerifyResult } from './types-D0j85fF0.js';
-import { V as VerifyRequestOpts, I as IncomingHttpLike } from './render-decision-Dsjwt96g.js';
-export { B as BuildAgentRequestOpts, R as RenderedResponse, b as buildAgentRequest, e as extractAgentDid, a as extractCredentialStatusUrl, c as extractIssuer, h as hasMalformedJwsBody, r as renderDecisionAsResponse } from './render-decision-Dsjwt96g.js';
+import { E as EnforcementMode, A as AgentRequest, V as VerifyResult } from './types-D0j85fF0.js';
+import { DidResolverAdapter, StatusListCacheAdapter, ReputationOracleAdapter, PolicyEvaluatorAdapter, ClockAdapter } from './adapters.js';
 import '@kya-os/checkpoint-shared';
-import './adapters.js';
+
+/**
+ * Orchestrator-layer types — Phase C, host-side only.
+ *
+ * Nothing here crosses the WASM boundary. The engine ABI types live
+ * in `../types.ts`; the adapter interfaces live in
+ * `../adapters/index.ts`. This file is the host-wrapper-facing
+ * surface — what Phase D (Next.js) and Phase E (Express) import.
+ */
+
+/**
+ * Framework-agnostic HTTP request shape.
+ *
+ * Next.js / Express / Cloudflare Workers / Hono adapters marshal
+ * their native request type into this shape before calling
+ * `verifyRequest`. The shape is intentionally minimal — only what
+ * the engine needs to make a verdict.
+ */
+interface IncomingHttpLike {
+    method: string;
+    /** Path + query string (no scheme + host). */
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+    /**
+     * Parsed body if the framework has already parsed it (Next.js
+     * with `await req.json()`, Express with `body-parser`). Falsy if
+     * the caller hasn't materialised the body — the orchestrator
+     * treats that as "no MCP-I envelope present" and routes to
+     * PlainHttp.
+     */
+    body?: Buffer | string | object | null;
+    /** Client IP if the framework surfaces one (Express `req.ip`). */
+    remoteAddress?: string;
+}
+/**
+ * Options the host wrapper passes per-`verifyRequest`-construction.
+ * The five adapters + clock + tenant identifier + enforcement mode.
+ */
+interface VerifyRequestOpts {
+    didResolver: DidResolverAdapter;
+    statusListCache: StatusListCacheAdapter;
+    reputationOracle: ReputationOracleAdapter;
+    policyEvaluator: PolicyEvaluatorAdapter;
+    clock: ClockAdapter;
+    /** Tenant identifier — the host customer this request targets. */
+    tenantHost: string;
+    enforcementMode: EnforcementMode;
+    /** Returned to the PolicyEvaluator when the request has no agent DID. Default 1.0. */
+    reputationBaseline?: number;
+    /**
+     * **Envelope-1 (#2537) coordination flag.** Pre-Envelope-1 the TS
+     * bouncer ships MCP-I proofs as `{protected,payload,signature}` JSON
+     * in a `KYA-Delegation` header. Post-Envelope-1 they ship compact
+     * JWS in `_meta.proof.jws` of the body. When this flag is true the
+     * orchestrator also accepts the legacy header form. **Default off.**
+     * Delete this flag once Envelope-1 ships end-to-end.
+     */
+    legacyEnvelopeFallback?: boolean;
+    /**
+     * Argus URL — passed only so the orchestrator can detect "Argus
+     * not configured" at construction time and log the one-shot
+     * warning. The actual reputation fetch goes through `reputationOracle`.
+     */
+    argusUrl?: string;
+    /** Injectable for the once-only Argus configuration warning. */
+    logger?: (msg: string) => void;
+}
+/**
+ * Transport-agnostic response shape `renderDecisionAsResponse`
+ * produces. Host wrappers adapt this to their framework's response
+ * type (NextResponse / Express `res` / Cloudflare Response).
+ *
+ * `status === null` means "pass through" — the request continues to
+ * the next handler. Happens in two cases:
+ *   1. `Decision::Permit` (no block in Enforce mode).
+ *   2. **Any verdict in Observe mode** — Observe never blocks, but
+ *      the response headers still carry the would-have-been verdict.
+ */
+interface RenderedResponse {
+    status: number | null;
+    headers: Record<string, string>;
+    body?: string | object;
+}
+
+/**
+ * HTTP-to-`AgentRequest` translator — Phase C.1.
+ *
+ * Detects which engine protocol the request belongs to and builds
+ * the typed `AgentRequest` the WASM consumes. Conservative
+ * detection: never escalates an ambiguous request into a higher
+ * verification tier. Anonymous PlainHttp is the default.
+ *
+ * **What this layer parses and what it doesn't.** It parses *only
+ * what's needed to drive conditional pre-fetch* — header presence,
+ * the MCP-I envelope's payload segment (to extract `iss` + `sub` +
+ * optional credentialStatus URL). It does **not** verify
+ * signatures, decode VC chains for revocation bits, or evaluate
+ * scope. Those live in the engine (H-1's parser + Stages 2-5).
+ *
+ * **Buffer-portability note.** This module uses `Buffer.from(...)` and
+ * `Buffer.isBuffer(...)` at multiple call sites (the JWS preflight
+ * `hasMalformedJwsBody`, both `tryBuildMcpIFromBody` variants, the
+ * legacy-header reconstitution path, and `bodyAsBytes`). All of these
+ * assume the Node `Buffer` global is available — provided natively by
+ * the Node runtime, polyfilled on Vercel Edge, and gated behind
+ * `nodejs_compat` on Cloudflare Workers. Bare-Edge and pure-browser
+ * embedders would need a `Buffer` polyfill or a refactor to
+ * `TextEncoder` / `Uint8Array.from`. Tracked as a follow-up since
+ * Phase D's Vercel Node + Vercel Edge targets are both covered today.
+ */
+
+interface BuildAgentRequestOpts {
+    /** See `VerifyRequestOpts.legacyEnvelopeFallback`. */
+    legacyEnvelopeFallback?: boolean;
+}
+/**
+ * Translate an HTTP-like request into the engine's `AgentRequest`.
+ *
+ * Detection order (conservative — never escalate ambiguous input):
+ *   1. MCP-I L2 detached proof in `_meta.proof.jws` (spec form).
+ *   2. (Legacy, opt-in) MCP-I in `KYA-Delegation` header
+ *      (Envelope-1 #2537 transition window only).
+ *   3. RFC 9421 HTTP Message Signatures (`Signature-Input` header).
+ *   4. PlainHttp (default — anonymous traffic).
+ */
+declare function buildAgentRequest(req: IncomingHttpLike, opts?: BuildAgentRequestOpts): AgentRequest;
+/**
+ * Preflight check — does the request body carry a `_meta.proof.jws`
+ * string that `parseJwsPayloadStruct` cannot project into a typed
+ * `McpIPayload`?
+ *
+ * The caller declared intent (an MCP-I envelope) by including the
+ * JWS field; structural failure to extract the payload means the
+ * envelope is malformed, not absent. Without this preflight, the
+ * orchestrator would silently fall through to PlainHttp — pre-#2560
+ * that happened to also Block (engine returned `Block(ParseError)`
+ * for every PlainHttp), so the regression was invisible; post-#2560
+ * the engine's Stage 1 + stub policy returns `Permit` for anonymous
+ * PlainHttp and tampered envelopes would be silently accepted.
+ *
+ * Returns `true` when the orchestrator should synthesize
+ * `Block(ParseError)` BEFORE calling `buildAgentRequest`.
+ */
+declare function hasMalformedJwsBody(req: IncomingHttpLike): boolean;
+/**
+ * Issuer DID — Stage 1 (identity resolution) targets this. `null`
+ * for PlainHttp (anonymous → no DID to resolve).
+ */
+declare function extractIssuer(request: AgentRequest): string | null;
+/**
+ * Agent DID — used by ReputationOracle. Defaults to `payload.sub`
+ * for MCP-I (subject = the agent the proof is *about*).
+ */
+declare function extractAgentDid(request: AgentRequest): string | null;
+/**
+ * Status-list URL for revocation pre-fetch. Pulled from the JWS
+ * payload's `vc.credentialStatus.id` (W3C VC Data Model 1.1).
+ * `null` when the envelope is L1 (no VC chain) — Stage 3 will skip.
+ */
+declare function extractCredentialStatusUrl(request: AgentRequest): string | null;
+
+/**
+ * Transport-agnostic `Decision` → HTTP renderer — Phase C.3.
+ *
+ * Translates a `VerifyResult` into a framework-neutral
+ * `{ status, headers, body }` shape. Phase D (Next.js) adapts this
+ * to `NextResponse`; Phase E (Express) adapts it to `res.status().set().send()`.
+ * One source of truth for the verdict→HTTP mapping.
+ *
+ * Mapping table (§ 4.5 of Phase C kickoff):
+ *
+ * | Decision                          | HTTP | Notes                                   |
+ * |-----------------------------------|------|-----------------------------------------|
+ * | Permit                            | null | Pass through to next handler            |
+ * | Block(Unauthenticated)            | 401  | WWW-Authenticate header                 |
+ * | Block(InvalidSignature)           | 403  |                                          |
+ * | Block(Revoked)                    | 403  |                                          |
+ * | Block(Expired)                    | 401  | Refresh-the-credential semantics        |
+ * | Block(OutOfScope)                 | 403  | Body carries requested + granted        |
+ * | Block(LowReputation)              | 403  | Body carries score + threshold          |
+ * | Block(PolicyDenied)               | 403  | Body carries detail                     |
+ * | Block(ParseError)                 | 400  | Body carries detail                     |
+ * | Challenge                         | 401  | Body carries ChallengeParams            |
+ * | Redirect                          | 302  | Location header                         |
+ * | Instruct                          | 422  | application/problem+json body           |
+ *
+ * Observe mode overrides: every verdict renders as `status: null`
+ * (pass through) with an `X-Checkpoint-Would-Have-Been` header
+ * carrying the verdict kind, plus the standard attribution headers.
+ *
+ * Every response carries the Phase 0.1 attribution headers:
+ * `X-Checkpoint-Engine`, `X-Checkpoint-Engine-Version`, and
+ * (when present) `X-Checkpoint-Ruleset-Hash`.
+ */
+
+declare function renderDecisionAsResponse(result: VerifyResult): RenderedResponse;
 
 /**
  * `verifyRequestEdge` async-init orchestrator — Edge-WASM-2 (folded into
@@ -46,4 +240,4 @@ declare function makeVerifyRequestEdge(opts: VerifyRequestOpts): (req: IncomingH
  */
 declare function verifyRequestEdge(req: IncomingHttpLike, opts: VerifyRequestOpts): Promise<VerifyResult>;
 
-export { IncomingHttpLike, VerifyRequestOpts, makeVerifyRequestEdge, verifyRequestEdge };
+export { type BuildAgentRequestOpts, type IncomingHttpLike, type RenderedResponse, type VerifyRequestOpts, buildAgentRequest, extractAgentDid, extractCredentialStatusUrl, extractIssuer, hasMalformedJwsBody, makeVerifyRequestEdge, renderDecisionAsResponse, verifyRequestEdge };