@kya-os/checkpoint-nextjs 1.0.1 → 1.1.0

package/dist/edge-runtime-loader.js

@@ -145,6 +145,13 @@ var EdgeRuntimeAgentShield = class {
       { pattern: /gemini/i, name: "Google Gemini", confidence: 0.85 },
       { pattern: /perplexity/i, name: "Perplexity", confidence: 0.85 },
       // Fallback
+      // UA-context-only pattern — `\b` is the correct anchor for UA
+      // substring matching. PR #2591's tightened `[\s;()]` form
+      // dropped `/`, which broke legit UA shapes like `you.com/1.0`
+      // and `+https://you.com)` (cursor catch on the same PR — see
+      // sibling agents.ts comment for the full rationale + UA shapes).
+      // CodeQL js/regex/missing-regexp-anchor speculates about URL
+      // misuse; this codebase only applies the pattern to UA strings.
       { pattern: /\byou\.com\b/i, name: "You.com", confidence: 0.8 },
       { pattern: /\bphind\b/i, name: "Phind", confidence: 0.8 }
     ];

package/dist/edge-runtime-loader.mjs

@@ -143,6 +143,13 @@ var EdgeRuntimeAgentShield = class {
       { pattern: /gemini/i, name: "Google Gemini", confidence: 0.85 },
       { pattern: /perplexity/i, name: "Perplexity", confidence: 0.85 },
       // Fallback
+      // UA-context-only pattern — `\b` is the correct anchor for UA
+      // substring matching. PR #2591's tightened `[\s;()]` form
+      // dropped `/`, which broke legit UA shapes like `you.com/1.0`
+      // and `+https://you.com)` (cursor catch on the same PR — see
+      // sibling agents.ts comment for the full rationale + UA shapes).
+      // CodeQL js/regex/missing-regexp-anchor speculates about URL
+      // misuse; this codebase only applies the pattern to UA strings.
       { pattern: /\byou\.com\b/i, name: "You.com", confidence: 0.8 },
       { pattern: /\bphind\b/i, name: "Phind", confidence: 0.8 }
     ];

package/dist/index.js

@@ -56,21 +56,28 @@ function applyHeaders(res, headers) {
 }
 
 // src/translate.ts
-function nextRequestToHttpLike(req) {
+async function nextRequestToHttpLike(req, opts = {}) {
   const url = new URL(req.url);
+  const body = await tryDrainJsonBody(req, opts);
   return {
     method: req.method,
     // Path + query only — orchestrator's URL parsing expects no scheme/host.
     url: url.pathname + url.search,
     headers: headersToRecord(req.headers),
-    // NextRequest.body is a ReadableStream; we don't drain it here.
-    // The orchestrator routes to PlainHttp when body is falsy, which
-    // is the right call for streaming middlewares that don't want to
-    // buffer the request body just to detect agents.
-    body: null,
+    body,
     remoteAddress: extractRemoteAddress(req)
   };
 }
+async function tryDrainJsonBody(req, opts) {
+  if (opts.drainJsonBody === false) return null;
+  const contentType = req.headers.get("content-type") ?? "";
+  if (!contentType.toLowerCase().includes("application/json")) return null;
+  try {
+    return await req.clone().text();
+  } catch {
+    return null;
+  }
+}
 function headersToRecord(headers) {
   const out = {};
   headers.forEach((value, key) => {
@@ -91,8 +98,9 @@ function extractRemoteAddress(req) {
 // src/middleware-node.ts
 function withCheckpoint(config) {
   const opts = buildVerifyOpts(config);
+  const translateOpts = { drainJsonBody: config.drainJsonBody };
   return async function checkpointMiddleware(req) {
-    const httpLike = nextRequestToHttpLike(req);
+    const httpLike = await nextRequestToHttpLike(req, translateOpts);
     const result = await orchestrator.verifyRequest(httpLike, opts);
     await dispatchOnResult(config, result, req);
     const rendered = orchestrator.renderDecisionAsResponse(result);
@@ -110,7 +118,8 @@ function buildVerifyOpts(config) {
     tenantHost: config.tenantHost,
     enforcementMode: config.enforcementMode ?? "enforce",
     reputationBaseline: config.reputationBaseline,
-    argusUrl: config.argusUrl
+    argusUrl: config.argusUrl,
+    legacyEnvelopeFallback: config.legacyEnvelopeFallback ?? false
   };
 }
 async function dispatchOnResult(config, result, req) {
@@ -973,7 +982,13 @@ async function applyPolicy(request, detection, config) {
     const context = createContextFromDetection(detection, request);
     const decision = checkpointShared.evaluatePolicy(policy, context);
     if (config.onPolicyDecision) {
-      await config.onPolicyDecision(request, decision, context);
+      try {
+        await config.onPolicyDecision(request, decision, context);
+      } catch (error) {
+        if (config.debug) {
+          console.error("[Checkpoint] onPolicyDecision callback failed:", error);
+        }
+      }
     }
     return await handlePolicyDecision(request, decision, config, detection);
   } catch (error) {

package/dist/index.mjs

@@ -55,21 +55,28 @@ function applyHeaders(res, headers) {
 }
 
 // src/translate.ts
-function nextRequestToHttpLike(req) {
+async function nextRequestToHttpLike(req, opts = {}) {
   const url = new URL(req.url);
+  const body = await tryDrainJsonBody(req, opts);
   return {
     method: req.method,
     // Path + query only — orchestrator's URL parsing expects no scheme/host.
     url: url.pathname + url.search,
     headers: headersToRecord(req.headers),
-    // NextRequest.body is a ReadableStream; we don't drain it here.
-    // The orchestrator routes to PlainHttp when body is falsy, which
-    // is the right call for streaming middlewares that don't want to
-    // buffer the request body just to detect agents.
-    body: null,
+    body,
     remoteAddress: extractRemoteAddress(req)
   };
 }
+async function tryDrainJsonBody(req, opts) {
+  if (opts.drainJsonBody === false) return null;
+  const contentType = req.headers.get("content-type") ?? "";
+  if (!contentType.toLowerCase().includes("application/json")) return null;
+  try {
+    return await req.clone().text();
+  } catch {
+    return null;
+  }
+}
 function headersToRecord(headers) {
   const out = {};
   headers.forEach((value, key) => {
@@ -90,8 +97,9 @@ function extractRemoteAddress(req) {
 // src/middleware-node.ts
 function withCheckpoint(config) {
   const opts = buildVerifyOpts(config);
+  const translateOpts = { drainJsonBody: config.drainJsonBody };
   return async function checkpointMiddleware(req) {
-    const httpLike = nextRequestToHttpLike(req);
+    const httpLike = await nextRequestToHttpLike(req, translateOpts);
     const result = await verifyRequest(httpLike, opts);
     await dispatchOnResult(config, result, req);
     const rendered = renderDecisionAsResponse(result);
@@ -109,7 +117,8 @@ function buildVerifyOpts(config) {
     tenantHost: config.tenantHost,
     enforcementMode: config.enforcementMode ?? "enforce",
     reputationBaseline: config.reputationBaseline,
-    argusUrl: config.argusUrl
+    argusUrl: config.argusUrl,
+    legacyEnvelopeFallback: config.legacyEnvelopeFallback ?? false
   };
 }
 async function dispatchOnResult(config, result, req) {
@@ -972,7 +981,13 @@ async function applyPolicy(request, detection, config) {
     const context = createContextFromDetection(detection, request);
     const decision = evaluatePolicy(policy, context);
     if (config.onPolicyDecision) {
-      await config.onPolicyDecision(request, decision, context);
+      try {
+        await config.onPolicyDecision(request, decision, context);
+      } catch (error) {
+        if (config.debug) {
+          console.error("[Checkpoint] onPolicyDecision callback failed:", error);
+        }
+      }
     }
     return await handlePolicyDecision(request, decision, config, detection);
   } catch (error) {

package/dist/middleware-edge.js

@@ -57,21 +57,28 @@ function applyHeaders(res, headers) {
 }
 
 // src/translate.ts
-function nextRequestToHttpLike(req) {
+async function nextRequestToHttpLike(req, opts = {}) {
   const url = new URL(req.url);
+  const body = await tryDrainJsonBody(req, opts);
   return {
     method: req.method,
     // Path + query only — orchestrator's URL parsing expects no scheme/host.
     url: url.pathname + url.search,
     headers: headersToRecord(req.headers),
-    // NextRequest.body is a ReadableStream; we don't drain it here.
-    // The orchestrator routes to PlainHttp when body is falsy, which
-    // is the right call for streaming middlewares that don't want to
-    // buffer the request body just to detect agents.
-    body: null,
+    body,
     remoteAddress: extractRemoteAddress(req)
   };
 }
+async function tryDrainJsonBody(req, opts) {
+  if (opts.drainJsonBody === false) return null;
+  const contentType = req.headers.get("content-type") ?? "";
+  if (!contentType.toLowerCase().includes("application/json")) return null;
+  try {
+    return await req.clone().text();
+  } catch {
+    return null;
+  }
+}
 function headersToRecord(headers) {
   const out = {};
   headers.forEach((value, key) => {
@@ -101,7 +108,8 @@ function buildVerifyOpts(config) {
     tenantHost: config.tenantHost,
     enforcementMode: config.enforcementMode ?? "enforce",
     reputationBaseline: config.reputationBaseline,
-    argusUrl: config.argusUrl
+    argusUrl: config.argusUrl,
+    legacyEnvelopeFallback: config.legacyEnvelopeFallback ?? false
   };
 }
 
@@ -109,8 +117,9 @@ function buildVerifyOpts(config) {
 function withCheckpoint(config) {
   void edge.initEngineEdge();
   const opts = buildVerifyOpts(config);
+  const translateOpts = { drainJsonBody: config.drainJsonBody };
   return async function checkpointMiddlewareEdge(req) {
-    const httpLike = nextRequestToHttpLike(req);
+    const httpLike = await nextRequestToHttpLike(req, translateOpts);
     const result = await edge.verifyRequestEdge(httpLike, opts);
     await dispatchOnResult(config, result, req);
     const rendered = edge.renderDecisionAsResponse(result);

package/dist/middleware-edge.mjs

@@ -56,21 +56,28 @@ function applyHeaders(res, headers) {
 }
 
 // src/translate.ts
-function nextRequestToHttpLike(req) {
+async function nextRequestToHttpLike(req, opts = {}) {
   const url = new URL(req.url);
+  const body = await tryDrainJsonBody(req, opts);
   return {
     method: req.method,
     // Path + query only — orchestrator's URL parsing expects no scheme/host.
     url: url.pathname + url.search,
     headers: headersToRecord(req.headers),
-    // NextRequest.body is a ReadableStream; we don't drain it here.
-    // The orchestrator routes to PlainHttp when body is falsy, which
-    // is the right call for streaming middlewares that don't want to
-    // buffer the request body just to detect agents.
-    body: null,
+    body,
     remoteAddress: extractRemoteAddress(req)
   };
 }
+async function tryDrainJsonBody(req, opts) {
+  if (opts.drainJsonBody === false) return null;
+  const contentType = req.headers.get("content-type") ?? "";
+  if (!contentType.toLowerCase().includes("application/json")) return null;
+  try {
+    return await req.clone().text();
+  } catch {
+    return null;
+  }
+}
 function headersToRecord(headers) {
   const out = {};
   headers.forEach((value, key) => {
@@ -100,7 +107,8 @@ function buildVerifyOpts(config) {
     tenantHost: config.tenantHost,
     enforcementMode: config.enforcementMode ?? "enforce",
     reputationBaseline: config.reputationBaseline,
-    argusUrl: config.argusUrl
+    argusUrl: config.argusUrl,
+    legacyEnvelopeFallback: config.legacyEnvelopeFallback ?? false
   };
 }
 
@@ -108,8 +116,9 @@ function buildVerifyOpts(config) {
 function withCheckpoint(config) {
   void initEngineEdge();
   const opts = buildVerifyOpts(config);
+  const translateOpts = { drainJsonBody: config.drainJsonBody };
   return async function checkpointMiddlewareEdge(req) {
-    const httpLike = nextRequestToHttpLike(req);
+    const httpLike = await nextRequestToHttpLike(req, translateOpts);
     const result = await verifyRequestEdge(httpLike, opts);
     await dispatchOnResult(config, result, req);
     const rendered = renderDecisionAsResponse(result);

package/dist/middleware-node.d.mts

@@ -58,6 +58,41 @@ interface CheckpointConfig {
      * response.
      */
     onResult?: (result: VerifyResult, req: NextRequest) => void | Promise<void>;
+    /**
+     * Accept legacy `KYA-Delegation`-header envelope form alongside the
+     * canonical `_meta.proof.jws` body form. Default `false`.
+     *
+     * **When to enable** — customers whose agents pre-date Envelope-1
+     * (#2537) and ship MCP-I proofs as `{protected,payload,signature}`
+     * JSON in a `KYA-Delegation` HTTP header. Post-Envelope-1 agents
+     * ship compact JWS in the request body's `_meta.proof.jws` field;
+     * those don't need this flag.
+     *
+     * Forwarded to the orchestrator's `VerifyRequestOpts.legacyEnvelopeFallback`.
+     * Both transports (header + body) are honored when this is `true`;
+     * the orchestrator's detection order is body first, then header
+     * (`packages/checkpoint-wasm-runtime/src/engine/orchestrator/build-agent-request.ts`).
+     *
+     * SDK-Envelope-Plumbing-1 (#2594). Added in `@kya-os/checkpoint-nextjs@1.1.0`.
+     */
+    legacyEnvelopeFallback?: boolean;
+    /**
+     * Read the request body when `content-type` is `application/json` so
+     * the orchestrator can extract an MCP-I envelope from
+     * `_meta.proof.jws`. Default `true`.
+     *
+     * **When to disable** — streaming middlewares that can't tolerate
+     * the `req.clone()` memory overhead (one full-body copy is buffered
+     * during the read). For those, set `false` and route MCP-I
+     * envelopes through the `KYA-Delegation` header transport instead
+     * (requires `legacyEnvelopeFallback: true`).
+     *
+     * The clone preserves `req.body` for downstream handlers — disabling
+     * is a performance optimization, not a correctness fix.
+     *
+     * SDK-Envelope-Plumbing-1 (#2594). Added in `@kya-os/checkpoint-nextjs@1.1.0`.
+     */
+    drainJsonBody?: boolean;
 }
 /**
  * Build the Checkpoint middleware. Returns a function `(req) => NextResponse`
@@ -84,6 +119,7 @@ declare function buildVerifyOpts(config: CheckpointConfig): {
     enforcementMode: EnforcementMode;
     reputationBaseline: number | undefined;
     argusUrl: string | undefined;
+    legacyEnvelopeFallback: boolean;
 };
 
 export { type CheckpointConfig, buildVerifyOpts as _buildVerifyOpts, withCheckpoint };

package/dist/middleware-node.d.ts

@@ -58,6 +58,41 @@ interface CheckpointConfig {
      * response.
      */
     onResult?: (result: VerifyResult, req: NextRequest) => void | Promise<void>;
+    /**
+     * Accept legacy `KYA-Delegation`-header envelope form alongside the
+     * canonical `_meta.proof.jws` body form. Default `false`.
+     *
+     * **When to enable** — customers whose agents pre-date Envelope-1
+     * (#2537) and ship MCP-I proofs as `{protected,payload,signature}`
+     * JSON in a `KYA-Delegation` HTTP header. Post-Envelope-1 agents
+     * ship compact JWS in the request body's `_meta.proof.jws` field;
+     * those don't need this flag.
+     *
+     * Forwarded to the orchestrator's `VerifyRequestOpts.legacyEnvelopeFallback`.
+     * Both transports (header + body) are honored when this is `true`;
+     * the orchestrator's detection order is body first, then header
+     * (`packages/checkpoint-wasm-runtime/src/engine/orchestrator/build-agent-request.ts`).
+     *
+     * SDK-Envelope-Plumbing-1 (#2594). Added in `@kya-os/checkpoint-nextjs@1.1.0`.
+     */
+    legacyEnvelopeFallback?: boolean;
+    /**
+     * Read the request body when `content-type` is `application/json` so
+     * the orchestrator can extract an MCP-I envelope from
+     * `_meta.proof.jws`. Default `true`.
+     *
+     * **When to disable** — streaming middlewares that can't tolerate
+     * the `req.clone()` memory overhead (one full-body copy is buffered
+     * during the read). For those, set `false` and route MCP-I
+     * envelopes through the `KYA-Delegation` header transport instead
+     * (requires `legacyEnvelopeFallback: true`).
+     *
+     * The clone preserves `req.body` for downstream handlers — disabling
+     * is a performance optimization, not a correctness fix.
+     *
+     * SDK-Envelope-Plumbing-1 (#2594). Added in `@kya-os/checkpoint-nextjs@1.1.0`.
+     */
+    drainJsonBody?: boolean;
 }
 /**
  * Build the Checkpoint middleware. Returns a function `(req) => NextResponse`
@@ -84,6 +119,7 @@ declare function buildVerifyOpts(config: CheckpointConfig): {
     enforcementMode: EnforcementMode;
     reputationBaseline: number | undefined;
     argusUrl: string | undefined;
+    legacyEnvelopeFallback: boolean;
 };
 
 export { type CheckpointConfig, buildVerifyOpts as _buildVerifyOpts, withCheckpoint };

package/dist/middleware-node.js

@@ -56,21 +56,28 @@ function applyHeaders(res, headers) {
 }
 
 // src/translate.ts
-function nextRequestToHttpLike(req) {
+async function nextRequestToHttpLike(req, opts = {}) {
   const url = new URL(req.url);
+  const body = await tryDrainJsonBody(req, opts);
   return {
     method: req.method,
     // Path + query only — orchestrator's URL parsing expects no scheme/host.
     url: url.pathname + url.search,
     headers: headersToRecord(req.headers),
-    // NextRequest.body is a ReadableStream; we don't drain it here.
-    // The orchestrator routes to PlainHttp when body is falsy, which
-    // is the right call for streaming middlewares that don't want to
-    // buffer the request body just to detect agents.
-    body: null,
+    body,
     remoteAddress: extractRemoteAddress(req)
   };
 }
+async function tryDrainJsonBody(req, opts) {
+  if (opts.drainJsonBody === false) return null;
+  const contentType = req.headers.get("content-type") ?? "";
+  if (!contentType.toLowerCase().includes("application/json")) return null;
+  try {
+    return await req.clone().text();
+  } catch {
+    return null;
+  }
+}
 function headersToRecord(headers) {
   const out = {};
   headers.forEach((value, key) => {
@@ -91,8 +98,9 @@ function extractRemoteAddress(req) {
 // src/middleware-node.ts
 function withCheckpoint(config) {
   const opts = buildVerifyOpts(config);
+  const translateOpts = { drainJsonBody: config.drainJsonBody };
   return async function checkpointMiddleware(req) {
-    const httpLike = nextRequestToHttpLike(req);
+    const httpLike = await nextRequestToHttpLike(req, translateOpts);
     const result = await orchestrator.verifyRequest(httpLike, opts);
     await dispatchOnResult(config, result, req);
     const rendered = orchestrator.renderDecisionAsResponse(result);
@@ -110,7 +118,8 @@ function buildVerifyOpts(config) {
     tenantHost: config.tenantHost,
     enforcementMode: config.enforcementMode ?? "enforce",
     reputationBaseline: config.reputationBaseline,
-    argusUrl: config.argusUrl
+    argusUrl: config.argusUrl,
+    legacyEnvelopeFallback: config.legacyEnvelopeFallback ?? false
   };
 }
 async function dispatchOnResult(config, result, req) {

package/dist/middleware-node.mjs

@@ -54,21 +54,28 @@ function applyHeaders(res, headers) {
 }
 
 // src/translate.ts
-function nextRequestToHttpLike(req) {
+async function nextRequestToHttpLike(req, opts = {}) {
   const url = new URL(req.url);
+  const body = await tryDrainJsonBody(req, opts);
   return {
     method: req.method,
     // Path + query only — orchestrator's URL parsing expects no scheme/host.
     url: url.pathname + url.search,
     headers: headersToRecord(req.headers),
-    // NextRequest.body is a ReadableStream; we don't drain it here.
-    // The orchestrator routes to PlainHttp when body is falsy, which
-    // is the right call for streaming middlewares that don't want to
-    // buffer the request body just to detect agents.
-    body: null,
+    body,
     remoteAddress: extractRemoteAddress(req)
   };
 }
+async function tryDrainJsonBody(req, opts) {
+  if (opts.drainJsonBody === false) return null;
+  const contentType = req.headers.get("content-type") ?? "";
+  if (!contentType.toLowerCase().includes("application/json")) return null;
+  try {
+    return await req.clone().text();
+  } catch {
+    return null;
+  }
+}
 function headersToRecord(headers) {
   const out = {};
   headers.forEach((value, key) => {
@@ -89,8 +96,9 @@ function extractRemoteAddress(req) {
 // src/middleware-node.ts
 function withCheckpoint(config) {
   const opts = buildVerifyOpts(config);
+  const translateOpts = { drainJsonBody: config.drainJsonBody };
   return async function checkpointMiddleware(req) {
-    const httpLike = nextRequestToHttpLike(req);
+    const httpLike = await nextRequestToHttpLike(req, translateOpts);
     const result = await verifyRequest(httpLike, opts);
     await dispatchOnResult(config, result, req);
     const rendered = renderDecisionAsResponse(result);
@@ -108,7 +116,8 @@ function buildVerifyOpts(config) {
     tenantHost: config.tenantHost,
     enforcementMode: config.enforcementMode ?? "enforce",
     reputationBaseline: config.reputationBaseline,
-    argusUrl: config.argusUrl
+    argusUrl: config.argusUrl,
+    legacyEnvelopeFallback: config.legacyEnvelopeFallback ?? false
   };
 }
 async function dispatchOnResult(config, result, req) {

package/dist/policy.js

@@ -144,7 +144,13 @@ async function applyPolicy(request, detection, config) {
     const context = createContextFromDetection(detection, request);
     const decision = checkpointShared.evaluatePolicy(policy, context);
     if (config.onPolicyDecision) {
-      await config.onPolicyDecision(request, decision, context);
+      try {
+        await config.onPolicyDecision(request, decision, context);
+      } catch (error) {
+        if (config.debug) {
+          console.error("[Checkpoint] onPolicyDecision callback failed:", error);
+        }
+      }
     }
     return await handlePolicyDecision(request, decision, config, detection);
   } catch (error) {

package/dist/policy.mjs

@@ -143,7 +143,13 @@ async function applyPolicy(request, detection, config) {
     const context = createContextFromDetection(detection, request);
     const decision = evaluatePolicy(policy, context);
     if (config.onPolicyDecision) {
-      await config.onPolicyDecision(request, decision, context);
+      try {
+        await config.onPolicyDecision(request, decision, context);
+      } catch (error) {
+        if (config.debug) {
+          console.error("[Checkpoint] onPolicyDecision callback failed:", error);
+        }
+      }
     }
     return await handlePolicyDecision(request, decision, config, detection);
   } catch (error) {

package/dist/translate.d.mts

@@ -16,18 +16,45 @@ import { IncomingHttpLike } from '@kya-os/checkpoint-wasm-runtime/orchestrator';
  * `x-forwarded-for` first IP).
  */
 
+/**
+ * Options controlling translator side effects.
+ *
+ * `drainJsonBody` (default `true`) controls whether the translator
+ * reads the request body so the orchestrator can extract an MCP-I
+ * envelope from `_meta.proof.jws` (the canonical spec-form transport).
+ *
+ * Trade-off — body draining consumes the request stream. We use
+ * `req.clone().text()` so the original `req.body` stream is preserved
+ * for downstream Next.js handlers. Cloning has memory overhead
+ * proportional to the body size; for large request bodies (>1 MB) or
+ * streaming-sensitive routes, set `drainJsonBody: false` and verify
+ * envelopes via the `KYA-Delegation` header transport instead (the
+ * legacy form, requires `legacyEnvelopeFallback: true` on
+ * `withCheckpoint`).
+ */
+interface NextRequestToHttpLikeOpts {
+    /**
+     * Read the request body when `content-type` is `application/json` so
+     * the orchestrator can extract an MCP-I envelope from
+     * `_meta.proof.jws`. Default `true`. Set `false` for streaming
+     * middlewares that can't tolerate the clone/read overhead.
+     */
+    drainJsonBody?: boolean;
+}
 /**
  * Translate a Next.js `NextRequest` into the orchestrator's
  * `IncomingHttpLike` shape.
  *
- * The body is passed through as-is — the orchestrator's
- * `buildAgentRequest` decides whether to parse JSON (looking for an
- * MCP-I `_meta.proof.jws` envelope) or treat the request as PlainHttp.
- * On Next.js middleware the body is typically not pre-parsed; consumers
- * who want to inspect the body for routing decisions should `await
- * req.json()` themselves and pass the parsed result via a second
- * `verifyRequest` call (not common).
+ * When `opts.drainJsonBody !== false` and the request is JSON, the
+ * translator clones the request and reads the body into a string so
+ * the orchestrator's `buildAgentRequest` can extract a
+ * `_meta.proof.jws` envelope. The original `req.body` stream is
+ * preserved for downstream handlers via `req.clone()`.
+ *
+ * When the body can't be read (drain disabled, non-JSON, or a stream
+ * error) we pass `body: null` and the orchestrator routes to
+ * PlainHttp — same behavior as the pre-1.1.0 default.
  */
-declare function nextRequestToHttpLike(req: NextRequest): IncomingHttpLike;
+declare function nextRequestToHttpLike(req: NextRequest, opts?: NextRequestToHttpLikeOpts): Promise<IncomingHttpLike>;
 
-export { nextRequestToHttpLike };
+export { type NextRequestToHttpLikeOpts, nextRequestToHttpLike };

package/dist/translate.d.ts

@@ -16,18 +16,45 @@ import { IncomingHttpLike } from '@kya-os/checkpoint-wasm-runtime/orchestrator';
  * `x-forwarded-for` first IP).
  */
 
+/**
+ * Options controlling translator side effects.
+ *
+ * `drainJsonBody` (default `true`) controls whether the translator
+ * reads the request body so the orchestrator can extract an MCP-I
+ * envelope from `_meta.proof.jws` (the canonical spec-form transport).
+ *
+ * Trade-off — body draining consumes the request stream. We use
+ * `req.clone().text()` so the original `req.body` stream is preserved
+ * for downstream Next.js handlers. Cloning has memory overhead
+ * proportional to the body size; for large request bodies (>1 MB) or
+ * streaming-sensitive routes, set `drainJsonBody: false` and verify
+ * envelopes via the `KYA-Delegation` header transport instead (the
+ * legacy form, requires `legacyEnvelopeFallback: true` on
+ * `withCheckpoint`).
+ */
+interface NextRequestToHttpLikeOpts {
+    /**
+     * Read the request body when `content-type` is `application/json` so
+     * the orchestrator can extract an MCP-I envelope from
+     * `_meta.proof.jws`. Default `true`. Set `false` for streaming
+     * middlewares that can't tolerate the clone/read overhead.
+     */
+    drainJsonBody?: boolean;
+}
 /**
  * Translate a Next.js `NextRequest` into the orchestrator's
  * `IncomingHttpLike` shape.
  *
- * The body is passed through as-is — the orchestrator's
- * `buildAgentRequest` decides whether to parse JSON (looking for an
- * MCP-I `_meta.proof.jws` envelope) or treat the request as PlainHttp.
- * On Next.js middleware the body is typically not pre-parsed; consumers
- * who want to inspect the body for routing decisions should `await
- * req.json()` themselves and pass the parsed result via a second
- * `verifyRequest` call (not common).
+ * When `opts.drainJsonBody !== false` and the request is JSON, the
+ * translator clones the request and reads the body into a string so
+ * the orchestrator's `buildAgentRequest` can extract a
+ * `_meta.proof.jws` envelope. The original `req.body` stream is
+ * preserved for downstream handlers via `req.clone()`.
+ *
+ * When the body can't be read (drain disabled, non-JSON, or a stream
+ * error) we pass `body: null` and the orchestrator routes to
+ * PlainHttp — same behavior as the pre-1.1.0 default.
  */
-declare function nextRequestToHttpLike(req: NextRequest): IncomingHttpLike;
+declare function nextRequestToHttpLike(req: NextRequest, opts?: NextRequestToHttpLikeOpts): Promise<IncomingHttpLike>;
 
-export { nextRequestToHttpLike };
+export { type NextRequestToHttpLikeOpts, nextRequestToHttpLike };