@kya-os/checkpoint-nextjs 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,170 @@
 # @kya-os/checkpoint-nextjs
 
+## 1.1.0 — 2026-05-17
+
+Closes [SDK-Envelope-Plumbing-1 (#2594)](https://github.com/Know-That-Ai/agent-shield/issues/2594).
+Wires MCP-I envelope verification through Next.js middleware — Bench-Before-After-1's
+`verified_mcp_i` traffic case was provably blocked by SDK glue (not engine
+capability — the engine verifies at 47µs Criterion local p50). All three transports
+the orchestrator supports now work from a Next.js consumer.
+
+### New config (additive — no breaking changes)
+
+- `CheckpointConfig.legacyEnvelopeFallback?: boolean` (default `false`) — accept
+  envelopes via the legacy `KYA-Delegation` HTTP header alongside the canonical
+  body form. Use for agents that pre-date Envelope-1 (#2537).
+- `CheckpointConfig.drainJsonBody?: boolean` (default `true`) — read the request
+  body when `content-type` is `application/json` so the orchestrator can extract
+  `_meta.proof.jws`. The translator uses `req.clone()` to preserve the original
+  stream for downstream handlers. Set `false` for streaming-sensitive routes
+  that can't tolerate the clone overhead; in that case route envelopes through
+  the `KYA-Delegation` header transport instead.
+
+### New supported transports
+
+| Transport                             | Form                                              | Config required                           |
+| ------------------------------------- | ------------------------------------------------- | ----------------------------------------- |
+| Canonical body (spec form)            | `_meta.proof.jws` field in a JSON request body    | none — `drainJsonBody` defaults to `true` |
+| Legacy header (Envelope-1 transition) | `KYA-Delegation` HTTP header carrying compact JWS | `legacyEnvelopeFallback: true`            |
+
+Both transports work end-to-end against the Rust `kya-os-engine` via WASM,
+including DID resolution (did:web + did:key), Ed25519 signature verification,
+JCS canonicalization, policy + reputation checks. See the engine's Criterion
+suite at `rust/crates/kya-os-engine/benches/bouncer_verify.rs` for the per-stage
+cost breakdown.
+
+### Factory clarity
+
+`createCheckpointWasmMiddleware` JSDoc updated to clearly document it as
+**pattern-detection only** (no envelope verification). Customers needing
+verification are pointed to `withCheckpoint` (the orchestrator-capable factory)
+in the JSDoc + example block.
+
+### Bench-Before-After-1 follow-up
+
+This release unblocks the verified_mcp_i measurement deferred in
+`docs/benchmarks/bench-before-after-1.md` §3.7. After upgrading
+`sites/nextjs-checkpoint/` to 1.1.0 and redeploying bench-new, sub-phase 3 will
+be re-run with the actual verify-success path exercised. The §3.8 "Verify-success
+measurement" section will then be appended to the report.
+
+### Migration
+
+No code changes required for existing 1.0.x consumers — both new fields are
+optional with safe defaults. Consumers wanting envelope verification should:
+
+```diff
+  export default withCheckpoint({
+    tenantHost: 'acme.checkpoint.example',
++   // Accept legacy KYA-Delegation-header envelopes (Envelope-1 transition)
++   legacyEnvelopeFallback: true,
+    // drainJsonBody defaults to true; canonical _meta.proof.jws body works out of the box
+  });
+```
+
+The body-drain default of `true` is a meaningful behavior change for streaming
+middlewares — those should explicitly set `drainJsonBody: false`. Reason for
+defaulting on: the alternative (silent fall-through to PlainHttp for every JSON
+request) is the bug `#2594` was filed to fix; a config default that preserves
+the bug isn't a fix.
+
+---
+
+## 1.0.1 — 2026-05-17
+
+Security + rename-completeness patch on top of 1.0.0. **All 1.0.0 users
+should upgrade.**
+
+### Security fixes (from #2587)
+
+- **`withCheckpointApi` fail-open bypass via observability callback.**
+  Severity: HIGH. The `onAgentDetected` callback was awaited inside the
+  outer middleware fail-open `try/catch`. A throwing callback (telemetry
+  flap, logging backend down, downstream timeout) would bubble up to the
+  fail-open path and return `NextResponse.next()` (200) **even when the
+  API had already returned `decision.action === 'block'`**. An attacker
+  who could induce failures in a customer's observability layer could
+  bypass enforcement. Fix: local `try/catch` around the callback so
+  enforcement continues regardless. Regression test added.
+- **`getCheckpointApiClient` shared singleton across distinct configs.**
+  Severity: HIGH for multi-tenant deploys (single Next.js app hosting
+  middleware for several customer routes). The first call's
+  `apiKey`/`baseUrl` were cached and reused for all subsequent calls
+  even when callers passed different configs — leaking audit/billing
+  into the wrong account and evaluating requests against the wrong
+  policy. Fix: config-keyed cache, distinct configs → distinct clients.
+  Regression test added.
+
+**Cross-version advisory:** Bug 1 (`await config.onAgentDetected(...)`
+inside the fail-open `try/catch`) **also exists in `withAgentShield` in
+`@kya-os/agentshield-nextjs@0.3.x`** (verified at
+`packages/agentshield-nextjs/src/api-middleware.ts:403-405` pre-rename).
+Anyone still on the legacy SDK is exposed to the same fail-open bypass.
+Recommended migration: upgrade to `@kya-os/checkpoint-nextjs@1.0.1`.
+
+### Rename-completeness (no behavior change)
+
+The 1.0.0 rename from `agentshield` → `checkpoint` left stragglers in
+log strings and runtime env-var lookups. Cleaning these up so the
+package no longer reads any `AGENTSHIELD_*` env var at runtime:
+
+- Log prefix `[AgentShield]` → `[Checkpoint]` across api-client,
+  api-middleware, policy, edge, storage, and the WASM setup guide.
+- Runtime env vars renamed:
+  - `AGENTSHIELD_API_URL` → `CHECKPOINT_API_URL`
+  - `AGENTSHIELD_USE_EDGE` → `CHECKPOINT_USE_EDGE`
+  - `AGENTSHIELD_DEBUG` → `CHECKPOINT_DEBUG`
+  - `AGENTSHIELD_SECRET` → `CHECKPOINT_SECRET`
+- Error message: `"AgentShield API key is required..."` →
+  `"Checkpoint API key is required..."` (the `CHECKPOINT_API_KEY` env
+  var name in that message is unchanged — it was already correct in
+  1.0.0).
+- Docs (`QUICKSTART.md`, `SESSION_TRACKING_GUIDE.md`) aligned with
+  source: `AGENTSHIELD_API_KEY` and `AGENTSHIELD_SECRET` references
+  swapped for the `CHECKPOINT_*` forms the source actually reads.
+
+#### Breaking-in-a-patch caveat (intentional)
+
+Per-spirit-of-semver this is technically a breaking config change. We're
+shipping it as a 1.0.x patch because:
+
+1. `@kya-os/checkpoint-nextjs@1.0.0` shipped on 2026-05-15 — a two-day
+   migration window with effectively no adopters yet at scale.
+2. The 1.0.0 release notes already documented `CHECKPOINT_API_KEY` as
+   the canonical env-var name; the leftover `AGENTSHIELD_*` lookups
+   were an oversight, not a documented API.
+3. Customers actively reading the docs as written were already setting
+   `CHECKPOINT_*` env vars; the change makes the package read what the
+   docs say.
+
+If you have `AGENTSHIELD_API_URL` / `AGENTSHIELD_USE_EDGE` /
+`AGENTSHIELD_DEBUG` / `AGENTSHIELD_SECRET` in your env, rename them to
+the `CHECKPOINT_*` equivalents on upgrade.
+
+#### Deliberately NOT renamed (would break live sessions)
+
+- Cookie name `__agentshield_session` — renaming would invalidate every
+  customer's live agent-detection sessions on deploy.
+- Encryption-key fallback `'agentshield-default-key'` — same reason
+  (would silently fail to decrypt sessions encrypted with the old
+  default).
+
+These are tracked for a future major and not in scope here.
+
+### Migration
+
+```diff
+- AGENTSHIELD_API_URL=https://detect.checkpoint-gateway.ai
++ CHECKPOINT_API_URL=https://detect.checkpoint-gateway.ai
+
+- AGENTSHIELD_SECRET=my-encryption-key
++ CHECKPOINT_SECRET=my-encryption-key
+```
+
+No code changes required.
+
+---
+
 ## 1.0.0 — 2026-05-15
 
 E-tracks Phase D — package rename + engine refactor + dual-runtime support.