feat(ap2): real VC-signature verification - fail-closed pipeline [AK-1] (#101)

New src/ap2-vc.ts: Ap2MandateVc envelope (W3C VC 2.0 shape), pinned
proof-suite list (reference-SDK SD-JWT/ES256 + eddsa-jcs-2022), offline-only
DID resolution (did:key + operator-pinned did:web cache, no network fetch),
operator trust-anchor list failing CLOSED when empty, 8-step ordered
verification pipeline with distinct AP2_* error codes, and replay protection
keyed (mandateId, cartHash) with an id-reuse-hash-mismatch tamper rule.

Ap2Adapter.settleVc() verifies BEFORE translation/signing - an unverifiable
envelope never reaches the x402 rail. Legacy settle() receipts are now
marked mandateVerification: 'not-performed' (translation-only honesty).

Spec pin (T1): google-agentic-commerce/AP2 @ e1ea56db72a6 (SD-JWT, ES256,
_sd_alg sha-256, delegate_payload wrapping) - recorded in the module
docstring. Python parity gap documented in packages/python/README.md.

89 new tests (adversarial-heavy: forged/wrong-key signature, 3x field
tamper, expired, not-yet-valid, untrusted/empty anchors, unknown suite,
alg-none downgrade, unresolvable DID, key confusion, replay, id-reuse
mismatch, malformed/oversize/null-byte envelopes). Full suite 539 green;
coverage ap2-vc.ts 87.7% / ap2.ts 98.5%; lint + type-check clean;
quickstart smoke passed against the live host.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: RBKunnela

README.md

@@ -505,24 +505,46 @@ engine.getQueueStatistics();                                      // BatchStatis
 
 ## AP2 + MPP
 
-paybot is a clean x402 settlement engine, so a Google **AP2** (A2A x402-extension) mandate can settle through it directly. The adapter **translates and settles only — it does not yet verify the AP2 verifiable-credential signature** (see the trust-boundary note below; cryptographic mandate verification is in active development). **MPP** (Stripe/Tempo) is still preview — the SDK ships only a detect-and-route capability seam, not a full client.
+paybot is a clean x402 settlement engine, so a Google **AP2** (A2A x402-extension) mandate can settle through it directly. **MPP** (Stripe/Tempo) is still preview — the SDK ships only a detect-and-route capability seam, not a full client.
 
 ```typescript
-import { Ap2Adapter, detectMppCapability } from 'paybot-sdk';
+import { Ap2Adapter, detectMppCapability, InMemoryReplayStore } from 'paybot-sdk';
 
 const ap2 = new Ap2Adapter(handler);              // handler: X402Handler
+
+// Verified path (recommended): full AP2 mandate VC envelope.
+// Fail-closed 8-step pipeline: envelope shape -> pinned proof suite ->
+// offline DID/key resolution -> operator trust anchors -> signature ->
+// temporal validity -> replay -> cart/intent linkage.
+const receipt = await ap2.settleVc(mandateVc, {
+  verify: {
+    trustedIssuers: ['did:key:z6Mk...'],          // EMPTY LIST = NOTHING TRUSTED
+    replayStore: new InMemoryReplayStore(),        // per-process; core is authoritative
+  },
+});
+receipt.mandateVerification; // 'verified'
+
+// Legacy path: translation-only settlement slice (NO authenticity check).
 if (ap2.validateMandate(mandate).valid) {
-  const receipt = await ap2.settle(mandate);      // signs + submits via x402
+  const r = await ap2.settle(mandate);            // signs + submits via x402
+  r.mandateVerification;                          // always 'not-performed'
 }
 
 detectMppCapability(responseHeaders);             // { supported, mode: 'detect-only'|'none', specVersion? }
 // createMppSeam().settle(...) throws MPP_NOT_IMPLEMENTED (501) — full MPP deferred until GA
 ```
 
-> The AP2 adapter is a mandate **envelope** adapter: it settles the payment but does **not**
-> yet verify the AP2 verifiable-credential signature — `validateMandate()` checks structure
-> and expiry only, not authenticity. Verify the VC out-of-band before calling `settle()`.
-> Built-in signature verification is in progress (see Roadmap).
+> **What our AP2 support means (honesty note).** `settleVc()` cryptographically
+> verifies an AP2 mandate VC envelope before settlement: pinned proof suites
+> (the reference SDK's SD-JWT/ES256 shape and W3C `eddsa-jcs-2022`), offline-only
+> DID resolution (`did:key` + operator-pinned `did:web` documents — never a
+> network fetch), an operator trust-anchor list that fails closed when empty,
+> and replay protection keyed `(mandateId, cartHash)`. The legacy
+> `settle(mandate)` slice path remains translation-only: its opaque `signature`
+> field is **not** verified and its receipts are always marked
+> `mandateVerification: 'not-performed'`. PayBot is the consumer side of AP2
+> mandates — it does not issue them. SD-JWT key-binding presentations and
+> delegation chains are not yet supported and are rejected fail-closed.
 
 ## Python SDK
 
@@ -565,7 +587,7 @@ For AI agent frameworks, use [paybot-mcp](https://github.com/RBKunnela/paybot-mc
 | ✅ **OpenTelemetry hooks** (opt-in, zero new deps) | T1.5 |
 | ✅ **Multi-bot pool + spend treasury** | T1.6 |
 | ✅ **EURC + token registry** (per-token EIP-712 domains) | T2.2 |
-| ✅ **AP2 mandate envelope adapter** (settlement only — VC signature verification in progress) · 🔭 thin **MPP capability seam** (deferred to GA) | T2.3 |
+| ✅ **AP2 settlement adapter** · 🔭 thin **MPP capability seam** (deferred to GA) | T2.3 |
 | ✅ **Python SDK 0.1.0** (real EIP-3009 signing) | T3.2 (partial) |
 | ✅ **Network expansion** — Optimism, Arbitrum One, Polygon PoS (+ Base, Base Sepolia) | T2.1 |
 | ✅ **CLI** — `paybot` command (register/balance/pay/health/networks/tokens) | T3.4 |
@@ -594,7 +616,7 @@ Prioritized by internal gap severity × external leverage (EU-bank credibility,
 
 **Phase C — Strategic / opportunistic:** full MPP (on GA) · more language ports (Go/Rust) · L402/Lightning shim · more MCP tools.
 
-**Strategic posture:** the moat is *self-hosted, non-custodial, MIT, trust-layer-in-the-SDK* — which custodial/portal-locked rivals (Coinbase Agentic Wallets, Circle, Crossmint, Payman) structurally cannot copy. Being a clean x402 settlement engine makes paybot AP2-pluggable (settlement only — see the AP2 trust-boundary note above) and AgentCore-compatible today — so MPP can wait for GA.
+**Strategic posture:** the moat is *self-hosted, non-custodial, MIT, trust-layer-in-the-SDK* — which custodial/portal-locked rivals (Coinbase Agentic Wallets, Circle, Crossmint, Payman) structurally cannot copy. Being a clean x402 settlement engine makes paybot AP2-pluggable and AgentCore-compatible today — so MPP can wait for GA.
 
 ## Deployment Options
 

packages/python/README.md

@@ -54,7 +54,8 @@ asyncio.run(main())
 | `src/x402-v2.ts` | `paybot_sdk/x402_v2.py` | ✅ `X402Handler` — 402 parse, x402/MPP/dual signing, `upto` scheme + capture validation, PAYMENT-SIGNATURE/RESPONSE headers, submit/verify |
 | `src/telemetry.ts` | `paybot_sdk/telemetry.py` | ✅ Opt-in `PayBotTracer`/`PayBotSpan` protocols + `with_span`, no OTel dependency |
 | `src/micropayment-engine.ts` | `paybot_sdk/micropayment_engine.py` | ✅ `MicropaymentEngine` — queue, thresholds, signed batch, stats |
-| `src/ap2.ts` | `paybot_sdk/ap2.py` | ✅ `Ap2Adapter` (does NOT verify the AP2 VC signature — documented trust boundary) |
+| `src/ap2.ts` | `paybot_sdk/ap2.py` | ✅ `Ap2Adapter` legacy slice (translation-only; does NOT verify the AP2 VC signature) |
+| `src/ap2-vc.ts` | — | ⚠️ **Parity gap (AK-1):** AP2 mandate VC verification (`verifyMandate`, `settleVc`, replay store, trust anchors) is **TypeScript-only for now**. Python callers needing verified AP2 settlement must verify out-of-band or settle through paybot core. Port tracked as an AK-1 follow-up. |
 | `src/mpp-seam.ts` | `paybot_sdk/mpp_seam.py` | ✅ `detect_mpp_capability` + `create_mpp_seam` (`settle` raises `MPP_NOT_IMPLEMENTED` — full MPP deferred to GA) |
 | `src/webhook.ts` | `paybot_sdk/webhook.py` | ✅ Full (`verify_webhook_signature`, HMAC-SHA256, replay guard) |
 | `src/index.ts` | `paybot_sdk/__init__.py` | ✅ Full exports |