@kya-os/checkpoint-nextjs 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # @kya-os/checkpoint-nextjs
 
+## 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.