@kya-os/checkpoint-nextjs 1.0.0 → 1.1.0

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);
@@ -130,5 +139,3 @@ Object.defineProperty(exports, "initEngineEdge", {
   get: function () { return edge.initEngineEdge; }
 });
 exports.withCheckpoint = withCheckpoint;
-//# sourceMappingURL=middleware-edge.js.map
-//# sourceMappingURL=middleware-edge.js.map

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);
@@ -125,5 +134,3 @@ async function dispatchOnResult(config, result, req) {
 }
 
 export { withCheckpoint };
-//# sourceMappingURL=middleware-edge.mjs.map
-//# sourceMappingURL=middleware-edge.mjs.map

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) {
@@ -123,5 +132,3 @@ async function dispatchOnResult(config, result, req) {
 
 exports._buildVerifyOpts = buildVerifyOpts;
 exports.withCheckpoint = withCheckpoint;
-//# sourceMappingURL=middleware-node.js.map
-//# sourceMappingURL=middleware-node.js.map

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) {
@@ -120,5 +129,3 @@ async function dispatchOnResult(config, result, req) {
 }
 
 export { buildVerifyOpts as _buildVerifyOpts, withCheckpoint };
-//# sourceMappingURL=middleware-node.mjs.map
-//# sourceMappingURL=middleware-node.mjs.map

package/dist/middleware.d.mts

@@ -1,5 +1,5 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { N as NextJSMiddlewareConfig } from './types-C-xCUNTr.mjs';
+import { N as NextJSMiddlewareConfig } from './types-D9RQvPNy.mjs';
 import '@kya-os/checkpoint-shared';
 import '@kya-os/checkpoint';
 

package/dist/middleware.d.ts

@@ -1,5 +1,5 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { N as NextJSMiddlewareConfig } from './types-C-xCUNTr.js';
+import { N as NextJSMiddlewareConfig } from './types-D9RQvPNy.js';
 import '@kya-os/checkpoint-shared';
 import '@kya-os/checkpoint';
 

package/dist/middleware.js

@@ -11,5 +11,3 @@ function agentShield(config = {}) {
 
 exports.agentShield = agentShield;
 exports.createAgentShieldMiddleware = createAgentShieldMiddleware;
-//# sourceMappingURL=middleware.js.map
-//# sourceMappingURL=middleware.js.map

package/dist/middleware.mjs

@@ -8,5 +8,3 @@ function agentShield(config = {}) {
 }
 
 export { agentShield, createAgentShieldMiddleware };
-//# sourceMappingURL=middleware.mjs.map
-//# sourceMappingURL=middleware.mjs.map

package/dist/nodejs-wasm-loader.js

@@ -91,5 +91,3 @@ exports.getWasmModule = getWasmModule;
 exports.isNodejsRuntime = isNodejsRuntime;
 exports.isWasmInitialized = isWasmInitialized;
 exports.loadWasmNodejs = loadWasmNodejs;
-//# sourceMappingURL=nodejs-wasm-loader.js.map
-//# sourceMappingURL=nodejs-wasm-loader.js.map

package/dist/nodejs-wasm-loader.mjs

@@ -81,5 +81,3 @@ function isWasmInitialized() {
 }
 
 export { getWasmModule, isNodejsRuntime, isWasmInitialized, loadWasmNodejs };
-//# sourceMappingURL=nodejs-wasm-loader.mjs.map
-//# sourceMappingURL=nodejs-wasm-loader.mjs.map

package/dist/policy.js

@@ -74,7 +74,7 @@ async function handlePolicyDecision(request, decision, config, detection) {
     case checkpointShared.ENFORCEMENT_ACTIONS.CHALLENGE:
       return buildChallengeResponse(request, decision, config, detection);
     case checkpointShared.ENFORCEMENT_ACTIONS.LOG:
-      console.log("[AgentShield] Policy decision (log):", {
+      console.log("[Checkpoint] Policy decision (log):", {
         path: request.nextUrl.pathname,
         action: decision.action,
         reason: decision.reason,
@@ -119,7 +119,7 @@ async function getPolicy(config) {
       return await fetcher.getPolicy(config.fetchPolicy.projectId);
     } catch (error) {
       if (config.debug) {
-        console.warn("[AgentShield] Policy fetch failed, using fallback:", error);
+        console.warn("[Checkpoint] Policy fetch failed, using fallback:", error);
       }
       return checkpointShared.PolicyConfigSchema.parse({
         ...checkpointShared.DEFAULT_POLICY,
@@ -144,12 +144,18 @@ 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) {
     if (config.debug) {
-      console.error("[AgentShield] Policy evaluation error:", error);
+      console.error("[Checkpoint] Policy evaluation error:", error);
     }
     if (config.failOpen !== false) {
       return null;
@@ -185,5 +191,3 @@ exports.createContextFromDetection = createContextFromDetection;
 exports.evaluatePolicyForDetection = evaluatePolicyForDetection;
 exports.getPolicy = getPolicy;
 exports.handlePolicyDecision = handlePolicyDecision;
-//# sourceMappingURL=policy.js.map
-//# sourceMappingURL=policy.js.map

package/dist/policy.mjs

@@ -73,7 +73,7 @@ async function handlePolicyDecision(request, decision, config, detection) {
     case ENFORCEMENT_ACTIONS.CHALLENGE:
       return buildChallengeResponse(request, decision, config, detection);
     case ENFORCEMENT_ACTIONS.LOG:
-      console.log("[AgentShield] Policy decision (log):", {
+      console.log("[Checkpoint] Policy decision (log):", {
         path: request.nextUrl.pathname,
         action: decision.action,
         reason: decision.reason,
@@ -118,7 +118,7 @@ async function getPolicy(config) {
       return await fetcher.getPolicy(config.fetchPolicy.projectId);
     } catch (error) {
       if (config.debug) {
-        console.warn("[AgentShield] Policy fetch failed, using fallback:", error);
+        console.warn("[Checkpoint] Policy fetch failed, using fallback:", error);
       }
       return PolicyConfigSchema.parse({
         ...DEFAULT_POLICY,
@@ -143,12 +143,18 @@ 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) {
     if (config.debug) {
-      console.error("[AgentShield] Policy evaluation error:", error);
+      console.error("[Checkpoint] Policy evaluation error:", error);
     }
     if (config.failOpen !== false) {
       return null;
@@ -161,5 +167,3 @@ async function applyPolicy(request, detection, config) {
 }
 
 export { applyPolicy, buildBlockedResponse, buildChallengeResponse, buildRedirectResponse, createContextFromDetection, evaluatePolicyForDetection, getPolicy, handlePolicyDecision };
-//# sourceMappingURL=policy.mjs.map
-//# sourceMappingURL=policy.mjs.map

package/dist/session-tracker.js

@@ -11,7 +11,7 @@ var EdgeSessionTracker = class {
       cookieName: config.cookieName || "__agentshield_session",
       cookieMaxAge: config.cookieMaxAge || 3600,
       // 1 hour default
-      encryptionKey: config.encryptionKey || process.env.AGENTSHIELD_SECRET || "agentshield-default-key"
+      encryptionKey: config.encryptionKey || process.env.CHECKPOINT_SECRET || "agentshield-default-key"
     };
   }
   /**
@@ -166,5 +166,3 @@ var StatelessSessionChecker = class {
 
 exports.EdgeSessionTracker = EdgeSessionTracker;
 exports.StatelessSessionChecker = StatelessSessionChecker;
-//# sourceMappingURL=session-tracker.js.map
-//# sourceMappingURL=session-tracker.js.map

package/dist/session-tracker.mjs

@@ -9,7 +9,7 @@ var EdgeSessionTracker = class {
       cookieName: config.cookieName || "__agentshield_session",
       cookieMaxAge: config.cookieMaxAge || 3600,
       // 1 hour default
-      encryptionKey: config.encryptionKey || process.env.AGENTSHIELD_SECRET || "agentshield-default-key"
+      encryptionKey: config.encryptionKey || process.env.CHECKPOINT_SECRET || "agentshield-default-key"
     };
   }
   /**
@@ -163,5 +163,3 @@ var StatelessSessionChecker = class {
 };
 
 export { EdgeSessionTracker, StatelessSessionChecker };
-//# sourceMappingURL=session-tracker.mjs.map
-//# sourceMappingURL=session-tracker.mjs.map

package/dist/signature-verifier.js

@@ -382,5 +382,3 @@ function isChatGPTSignature(headers) {
 exports.hasSignatureHeaders = hasSignatureHeaders;
 exports.isChatGPTSignature = isChatGPTSignature;
 exports.verifyAgentSignature = verifyAgentSignature;
-//# sourceMappingURL=signature-verifier.js.map
-//# sourceMappingURL=signature-verifier.js.map

package/dist/signature-verifier.mjs

@@ -358,5 +358,3 @@ function isChatGPTSignature(headers) {
 }
 
 export { hasSignatureHeaders, isChatGPTSignature, verifyAgentSignature };
-//# sourceMappingURL=signature-verifier.mjs.map
-//# sourceMappingURL=signature-verifier.mjs.map

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 };