Ap2/verify cnf and reference binding

[mike-parkhill]

Harden AP2 Closed Mandate verification — close every gap where trust was silently deferred to the caller instead of enforced.

verifyClosedCheckoutMandate/verifyClosedPaymentMandate accumulated several places where a signature check passed but the thing that actually mattered wasn't verified. Since this package has no production usage yet, each gap is closed outright rather than kept as a fallback:

Caller-supplied-key fallback removed. publicKey/holderJwk options are gone; the verification key is always derived from the Open Mandate's own cnf.jwk. openMandatePresentation is now required.
Open Mandate issuer now verified. New required userPublicKey param — the caller's independently-resolved trusted key for the delegating User — checked against the Open Mandate's own envelope. Without this, an attacker could fabricate an entire Open + Closed Mandate chain naming their own key in cnf.jwk, and every other check would pass. resolveOpenCheckoutMandateContent/resolveOpenPaymentMandateContent gained a matching optional userPublicKey for direct callers.
Envelope typ now checked (kb+sd-jwt), rejecting an Open Mandate or other envelope type fed in where a Closed one is expected.
Replay protection: nonce is now enforced. New required expectedNonce param, checked against the envelope's nonce. Closed Mandate envelopes carry no exp of their own, so previously a validly-signed presentation could be replayed indefinitely — nonce was accepted at signing time but never checked at verification time.
Also:

verifyClosedPaymentMandate gained openCheckoutMandatePresentation (verifies the Open Payment Mandate's payment.reference binding, previously left to the caller) and resolveOpenCheckoutMandateContent was added (mirrors the payment-side resolver).
Docs: documented that AP2 v0.2 defines no revocation mechanism at all (confirmed against the spec — explicitly out of scope, exp is the only verifier-enforceable lifecycle control and is only RECOMMENDED, not required); added an example resolving userPublicKey from a DID.
Added .d.ts type declarations to this package and @docknetwork/crypto-utils (unrelated tooling fix, bundled in since both landed in this window).
Breaking: yes, but pre-1.0 and unreleased — no downstream consumers exist yet. Confirmed via repo-wide search across wallet-sdk (no usage), ap2-example-app (no direct usage, only via MCP calls to truvera-mcp-server), and truvera-mcp-server (3 call sites in wallet-server/truvera-api need updating — tracked separately, not part of this PR).

[Copilot]

Pull request overview

This PR hardens AP2 Closed Mandate verification by removing caller-trusted verification-key fallbacks and enforcing additional bindings/claims (issuer verification, typ, nonce, and reference binding), plus updating docs, examples, tests, and versioning to match the breaking API changes.

Changes:

• Make verifyClosedCheckoutMandate / verifyClosedPaymentMandate derive the verification key strictly from the referenced Open Mandate’s cnf.jwk, and require openMandatePresentation, userPublicKey, and expectedNonce.
• Add Open Checkout resolver (resolveOpenCheckoutMandateContent) and extend Closed Payment verification with optional checkout-reference binding (openCheckoutMandatePresentation → referenceVerified).
• Update README, add DID-based verification example, expand tests, and bump @docknetwork/ap2 to 0.5.0 with a corresponding changelog entry.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/ap2/src/mandates.js	Enforces stricter Closed Mandate verification (no caller key fallback), adds nonce + typ checks, issuer verification, Open Checkout resolver, and payment reference binding.
packages/ap2/tests/mandates.test.js	Updates existing tests for the new required verification inputs and adds extensive new coverage for the hardened checks.
packages/ap2/README.md	Documents the new required verification parameters, adds lifecycle/revocation clarification, and references the new DID example.
packages/ap2/examples/verify-mandate-with-did-user-key.mjs	Adds an example showing how to resolve userPublicKey from a DID document and use it during verification.
packages/ap2/package.json	Bumps version to 0.5.0 and adds an npm script to run the new DID example.
packages/ap2/CHANGELOG.md	Documents the breaking verification API changes and the new behaviors in 0.5.0.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (1)

packages/ap2/src/mandates.js:493

• requireUserPublicKey only checks for undefined, so null (or other obviously-invalid sentinels) will pass the precondition and then fail later inside verifyJWT with a less actionable error. Since userPublicKey is now required for security-critical issuer verification, it should reject null explicitly (and ideally any non-object-ish values) with the same clear "is required" message.

function requireUserPublicKey(userPublicKey) {
  if (userPublicKey === undefined) {
    throw new TypeError(
      '"userPublicKey" is required: without it, the Open Mandate\'s own issuer signature -- '
      + 'and therefore its cnf.jwk delegation -- is never verified, and the whole mandate chain '
      + 'could be entirely self-forged',
    );
  }