@atlasauth/pca-ap2 0.3.0 → 0.4.0

package/README.md

@@ -1,8 +1,10 @@
 # @atlasauth/pca-ap2
 
-A mandate chain for Proof-Carrying Authority (PCA) modelled on AP2 (Agent Payments Protocol, FIDO Alliance). AP2 models agentic payments as a chain of mandates: an intent, then a checkout, then a payment. That chain closely mirrors PCA's attenuating capability chain, and this package maps one onto the other as signed credentials named IntentMandate, CartMandate and PaymentMandate. These credentials are a PCA rendition of the concepts and are not the SD-JWT mandate format that the current AP2 schemas define (see Status).
+AP2 (Agent Payments Protocol) mandates as real SD-JWT credentials, bound to a Proof-Carrying Authority (PCA) grant.
 
-PCA governs: it decides who may spend, how much, until when, and when a human must co-sign. AP2 is the mandate wire other parties verify. Settlement rails (x402, Stripe Shared Payment Tokens) move the value, fed by PCA's decision. This is a bridge, not a replacement.
+AP2 models agentic payments as a chain of mandates: an open mandate signed by the user's trusted surface that delegates to an agent key and carries constraints, then a closed mandate signed by the agent that settles one concrete purchase. This package issues and verifies the checkout and payment mandates (`mandate.checkout.1`, `mandate.checkout.open.1`, `mandate.payment.1`, `mandate.payment.open.1`) in the SD-JWT format defined by the official AP2 JSON Schemas: integer minor-unit amounts, selective disclosure, ES256 (P-256) keys, and a key-binding JWT at each hop.
+
+PCA governs: it decides who may spend, how much, until when, and when a human must co-sign. The AP2 mandates are the wire other parties verify, and each one carries PCA's proof of the grant (open mandate) or of the individual charge (closed payment mandate). Settlement rails (x402, Stripe Shared Payment Tokens) move the value.
 
 ## Install
 
@@ -10,73 +12,47 @@ PCA governs: it decides who may spend, how much, until when, and when a human mu
 npm i @atlasauth/pca-ap2
 ```
 
-Depends on `@atlasauth/pca` and `@atlasauth/pca-payments` (installed transitively; you will usually import `buildPaymentMandate` from the latter).
-
-## Usage
-
-```ts
-import { encodeKey, generateKeyPair } from '@atlasauth/pca';
-import { buildPaymentMandate, authorizeCharge } from '@atlasauth/pca-payments';
-import {
-  toAP2IntentMandate, toAP2CartMandate, toAP2PaymentMandate,
-  chainMandates, fromAP2Mandate, x402Settlement, stripeSptSettlement,
-} from '@atlasauth/pca-ap2';
-
-const principal = generateKeyPair(), merchantKey = generateKeyPair();
-const payerKey = generateKeyPair(), agentKey = generateKeyPair();
-const pub = (k: { publicKey: Uint8Array }) => encodeKey(k.publicKey);
-
-// 1. A PCA payment mandate (the authority layer).
-const mandate = buildPaymentMandate({
-  principalSecret: principal.secretKey, principalPublic: pub(principal), agentPublic: pub(agentKey),
-  merchants: ['acme'], currency: 'USD',
-  perTransactionCap: 500, autoApproveThreshold: 50, cumulativeCap: 1000,
-});
-
-// 2. Map it down the AP2 chain; each step narrows, never widens.
-const intent = toAP2IntentMandate(mandate, { issuerPublic: pub(principal), issuerSecret: principal.secretKey });
-const cart = toAP2CartMandate(
-  intent,
-  { merchant: 'acme', items: [{ sku: 'seat', name: 'Seat', quantity: 1, unit_price: { currency: 'USD', value: 120 } }] },
-  { issuerPublic: pub(merchantKey), issuerSecret: merchantKey.secretKey },
-);
-const decision = authorizeCharge(mandate, { merchant: 'acme', amount: 120, currency: 'USD' }); // step-up, t = 3
-const payment = toAP2PaymentMandate(cart, {
-  issuerPublic: pub(payerKey), issuerSecret: payerKey.secretKey,
-  paymentMethod: { type: 'card' }, pcaTier: decision.t, intent,
-});
-
-// 3. Verify the chain is a non-amplifying narrowing.
-chainMandates(intent, cart, payment).verify(); // { ok: true, reasons: [] }
-
-// 4. Parse back toward PCA terms.
-fromAP2Mandate(intent); // { type: 'IntentMandate', merchants: ['acme'], perTransactionCap: 500, ... }
-
-// 5. Build the rail's wire shape from the payment mandate (structural, no network).
-x402Settlement.settle(payment, { resourceUrl: 'https://api.example.com/report', payTo: '0xabc', network: 'base' });
-stripeSptSettlement.settle(payment, { payTo: 'acct_merchant' });
-```
+Depends on `@atlasauth/pca` and `@atlasauth/pca-payments` (installed transitively; you will usually build the PCA payment mandate with `buildPaymentMandate` from the latter).
+
+## What it provides
+
+- **Issue**: `issueOpenPaymentMandate`, `issueOpenCheckoutMandate`, `presentClosedCheckout`, `presentClosedPayment`; or from a PCA mandate directly, `openPaymentMandateFromPca` and `openCheckoutMandateFromPca`.
+- **Verify**: `verifyCheckoutChain`, `verifyPaymentChain`, and `verifyPurchase` (checkout and payment verified together: the payment must reference the open checkout, settle the closed checkout's `checkout_hash`, and match the quoted payee, currency and total). A verifier must name its own audience and nonce.
+- **Constraints**: `checkPaymentConstraints` and `checkCheckoutConstraints` evaluate amount ranges, allowed payees, budgets, recurrence, references and acceptable line items from the disclosed claims. A disclosure the agent withholds cannot widen an open mandate.
+- **PCA binding**: `buildPcaPaymentBinding` and `verifyPcaBinding`.
+- **Low level**: SD-JWT parsing and strict disclosure processing (`parseSdJwtHop`, `processDisclosures`, `splitChain`), schema-level validators (`paymentMandateProblems` and the three siblings), and `toMinorUnits` / `fromMinorUnits`.
+- **Settlement shapes**: `x402Settlement`, `stripeSptSettlement` (the `SettlementBackend` interface).
 
-### Human-present mapping
+## PCA binding
 
-| PCA decision | AP2 `human_present` |
-| --- | --- |
-| tier 1: autonomous (within the auto-approve threshold and budget) | `false` |
-| tier 3: human step-up or co-sign required | `true` |
+The PCA proof travels inside the mandate as a namespaced `x_pca` claim, so it is covered by the issuer's or agent's signature and by the next hop's `sd_hash`:
 
-## API
+| Mandate | `x_pca` | Meaning |
+| --- | --- | --- |
+| open (checkout or payment) | `{ v, grant, terms }` | the principal-signed PCA grant and the terms it was minted from |
+| closed payment | `{ v, charge, pcactn }` | the agent-signed PCA action proof that authorises exactly this charge |
 
-- Mapping: `toAP2IntentMandate`, `toAP2CartMandate`, `toAP2PaymentMandate`, `fromAP2Mandate`.
-- Signing and chain: `signMandate`, `verifyMandate`, `mandateHash`, `chainMandates`, `verifyAP2Chain`.
-- Settlement hooks: `x402Settlement`, `stripeSptSettlement` (the `SettlementBackend` interface).
+The PCActn's signed nonce commits to the transaction id, payee, amount, instrument, the open mandate's `sd_hash` and the thumbprint of the agent's AP2 key, so replaying the proof under another mandate, charge or agent key fails. The official schemas do not forbid additional mandate claims and the reference SDK ignores unknown ones; both are tested, so `x_pca` does not affect schema validity or reference verification. Verifiers that do not know PCA simply ignore it. A charge above the auto-approve threshold carries a threshold co-signature in the PCActn.
+
+`verifyPcaBinding` checks the grant signature and expected principal, that the `x_pca` terms agree with the grant envelope and with the AP2 constraints (AP2 constraints wider than the PCA terms are refused), the PCActn chain and signature, and the commitment above. When the charge's risk needs a threshold of t > 1, the `hooks.threshold` verifier must report that it enforced at least that `t` (build it with `createThresholdVerifier({ signerSet, t })`); a hook built for a smaller `t` is refused, as in the core verifier (breaking).
+
+**The policy decision always runs on the verifier's own state (breaking).** `mandate` (the PCA mandate state you hold, with its live budget) is required, and `recentChargeTimes` (from your own records) is required when the mandate limits the charge count; otherwise `verifyPcaBinding` throws `PcaBindingError` (`mandate_required` / `charge_history_required`). The mandate must be bound to the verified grant (`authorizeCharge` refuses a different grant or terms), so the cumulative budget and the charge-count rate limit are always enforced.
 
 ## Status
 
-Experimental, and **not wire-compatible with the current AP2 specification**. The official AP2 JSON Schemas (github.com/google-agentic-commerce/AP2 at commit e1ea56d, 2026-04-29) define SD-JWT mandates (`mandate.checkout.1`, `mandate.payment.1` and the open variants) with integer minor-unit amounts. This package emits Ed25519-signed, W3C-style credentials with decimal amounts, so its output fails those schemas (the tests pin exactly which required claims are missing). Use it to express a PCA grant as an Intent, Cart and Payment chain between parties that both use this package; do not present its output to an AP2 verifier. PCA-specific terms that AP2 has no field for are carried in a namespaced, non-standard `x_pca` extension.
+Experimental. Mandates are checked against the official AP2 JSON Schemas and documentation at github.com/google-agentic-commerce/AP2, commit `e1ea56db72a6385bce3e5c1112b3a56ce60acb43` (2026-04-29; still the head of `main` when this package was last updated). The schemas and example payloads are committed with source URLs and sha256.
+
+What is verified, and how:
+
+- Every mandate this package issues validates against the official schemas (Ajv, JSON Schema 2020-12).
+- The six encoded SD-JWT examples in the AP2 documentation are parsed and re-serialised byte for byte; their disclosure digests, `sd_hash`, `checkout_hash`, `transaction_id` and payment reference recompute to the published values, and the closed hops' ES256 signatures (made by Google's reference code) verify under the open mandate's `cnf.jwk` with this verifier. The documentation never publishes the issuer key, so the documented open mandates' root signatures cannot be checked.
+- Cross-implementation, in both directions: purchases issued here are accepted by Google's official AP2 Python SDK (`MandateClient`, payment and checkout chains) and by the independent `@sd-jwt/core` library; purchases issued by the official SDK are verified here with the real root signature.
+- The documentation's decoded JSON blocks differ from its encoded tokens; the encoded tokens are treated as the source of truth.
+- Adversarial tests: an exhaustive single-character mutation of a valid purchase is never accepted, structure fuzzing never throws or accepts, and withheld disclosures cannot widen an open mandate. Where this package is stricter than the reference SDK (for example acceptable-items, quantities and budgets) the tests say so.
 
-Validated: the official schemas and the example payloads from the AP2 documentation are committed with source URLs and sha256 and checked with Ajv (the documented closed and open payment mandates validate, and the encoded SD-JWT examples are internally consistent). The chain's own signature, hash-binding and non-amplifying-narrowing checks are covered by the package tests.
+Limits: only the P-256/ES256 and SHA-2 `_sd_alg` paths are implemented. Payment budgets are converted from major units the way the AP2 SDK does (a fixed x100), so they are refused for currencies whose exponent is not 2. Issuer key trust (`kid` / `x5c` resolution) is the caller's job. The cryptography is unaudited.
 
-The settlement backends are structural only: they turn a payment mandate into an x402 HTTP-402 challenge or a Stripe Shared-Payment-Token charge shape (minor units) and perform no network I/O. The x402 output is checked against the x402 v1 specification (field set, atomic-unit `maxAmountRequired`, `maxTimeoutSeconds`, standard-base64 `X-PAYMENT`); the `X-PAYMENT` payload is a placeholder envelope, not a signed authorization, and `asset` should be supplied as the token contract address. The Stripe shape has no official vector behind it. Settlement backends assume the mandate has already been verified. The cryptography is unaudited.
+The settlement backends are structural only: they turn a payment mandate into an x402 HTTP-402 challenge or a Stripe Shared-Payment-Token charge shape and perform no network I/O. The x402 output is checked against the x402 v1 specification (field set, atomic-unit `maxAmountRequired`, `maxTimeoutSeconds`, standard-base64 `X-PAYMENT`); the `X-PAYMENT` payload is a placeholder envelope, not a signed authorization, and `asset` should be supplied as the token contract address. The Stripe shape has no official vector behind it. Settlement backends assume the mandate has already been verified.
 
 ## License
 

package/dist/chain.d.ts

@@ -0,0 +1,217 @@
+/**
+ * AP2 mandate issuance, presentation and verification.
+ *
+ * Wire format (AP2 `docs/ap2`, `ap2.sdk.sdjwt`): a mandate is the single object in an SD-JWT's
+ * `delegate_payload` array, itself an array-element disclosure. An *open* mandate is signed by the
+ * issuer (the user's trusted surface / agent provider) and names the agent's key in `cnf.jwk`. A
+ * *closed* mandate is a KB-SD-JWT hop (`typ: kb+sd-jwt`) signed by that agent key, carrying `iat`,
+ * `aud`, `nonce` and an `sd_hash` over the preceding hop. Hops are joined by `~~`. That hop is AP2's
+ * key-binding mechanism; no trailing RFC 9901 KB-JWT is used or accepted.
+ */
+import type { KeyObject } from 'node:crypto';
+import { type JsonObject, type JwtHeader, type P256Jwk, type SdAlg, type SdJwtHop } from './sdjwt';
+import { type CheckoutConstraint, type CheckoutMandateClaims, type Merchant, type OpenCheckoutMandateClaims, type OpenPaymentMandateClaims, type PaymentConstraint, type PaymentInstrument, type PaymentMandateClaims, type Pisp } from './mandates';
+import { type MandateContext, type UcpCheckout } from './constraints';
+/** The signer of an open mandate: the user's trusted surface or agent provider (an ES256 key). */
+export interface MandateIssuer {
+    privateKey: KeyObject;
+    /** `kid` header; a verifier's key resolver maps it to the public key. */
+    kid?: string;
+    /** Optional `x5c` header (base64 DER certificates); chain validation is the resolver's job. */
+    x5c?: string[];
+}
+export interface OpenMandateCommon {
+    issuer: MandateIssuer;
+    /** The agent's public key; becomes `cnf.jwk` and is the only key that can sign the closed mandate. */
+    agentJwk: P256Jwk;
+    /** Issued-at, epoch seconds. */
+    iat: number;
+    /** Expiry, epoch seconds (required: an open mandate must be bounded in time). */
+    exp: number;
+    /** `x_pca` claim (PCA's proof of the grant); see `pca.ts`. */
+    pca?: JsonObject;
+    sdAlg?: SdAlg;
+    /** Salt source (tests inject a deterministic one). */
+    salt?: () => string;
+    /** Root `typ` header; the reference SDK imposes none. */
+    typ?: string;
+}
+export interface OpenPaymentMandateInput extends OpenMandateCommon {
+    constraints: PaymentConstraint[];
+    payee?: Merchant;
+    paymentAmount?: {
+        amount: number;
+        currency: string;
+    };
+    paymentInstrument?: PaymentInstrument;
+    pisp?: Pisp;
+    executionDate?: string;
+}
+/** Issue an open Payment Mandate (`mandate.payment.open.1`) as a signed SD-JWT. */
+export declare function issueOpenPaymentMandate(input: OpenPaymentMandateInput): string;
+export interface OpenCheckoutMandateInput extends OpenMandateCommon {
+    constraints: CheckoutConstraint[];
+}
+/** Issue an open Checkout Mandate (`mandate.checkout.open.1`) as a signed SD-JWT. */
+export declare function issueOpenCheckoutMandate(input: OpenCheckoutMandateInput): string;
+export interface ClosedHopCommon {
+    /** The preceding token (an open mandate, or a chain ending in an intermediate hop). */
+    open: string;
+    /** The agent's key pair: its public key must be the open mandate's `cnf.jwk`. */
+    agentKey: {
+        privateKey: KeyObject;
+        publicJwk: P256Jwk;
+    };
+    /** Audience of this hop (the merchant for a checkout, the credential provider for a payment). */
+    aud: string;
+    /** Verifier-supplied nonce; the verifier checks it on receipt. */
+    nonce: string;
+    /** Issued-at, epoch seconds. */
+    iat: number;
+    /** Optional mandate-level expiry, epoch seconds. */
+    exp?: number;
+    pca?: JsonObject;
+    /** Binding claim: `sd_hash` (default; pins the preceding hop's disclosures) or `issuer_jwt_hash`. */
+    hashMode?: 'sd_hash' | 'issuer_jwt_hash';
+    salt?: () => string;
+}
+export interface ClosedPaymentInput extends ClosedHopCommon {
+    /** Hash of the closed checkout's `checkout_jwt` (= the closed checkout mandate's `checkout_hash`). */
+    transactionId: string;
+    payee: Merchant;
+    paymentAmount: {
+        amount: number;
+        currency: string;
+    };
+    paymentInstrument: PaymentInstrument;
+    pisp?: Pisp;
+    executionDate?: string;
+    riskData?: JsonObject;
+}
+/** Present a closed Payment Mandate (`mandate.payment.1`) on top of an open payment mandate. */
+export declare function presentClosedPayment(input: ClosedPaymentInput): string;
+export interface ClosedCheckoutInput extends ClosedHopCommon {
+    /** The merchant-signed checkout JWT (compact). */
+    checkoutJwt: string;
+}
+/** Present a closed Checkout Mandate (`mandate.checkout.1`) on top of an open checkout mandate. */
+export declare function presentClosedCheckout(input: ClosedCheckoutInput): string;
+export declare const TYP_TERMINAL: readonly string[];
+export declare const TYP_INTERMEDIATE: readonly string[];
+export interface VerifiedHop {
+    index: number;
+    kind: 'root' | 'intermediate' | 'terminal';
+    hop: SdJwtHop;
+    /** Hop-level claims after disclosure processing. */
+    claims: JsonObject;
+    /** The single mandate object disclosed in `delegate_payload`. */
+    mandate: JsonObject;
+}
+export interface VerifyChainOptions {
+    /** Resolve the root hop's public key from its header (`kid` / `x5c`); return undefined to refuse. */
+    resolveIssuerKey: (header: JwtHeader) => P256Jwk | undefined;
+    /** The terminal hop's `aud` must equal this. Required: a verifier that does not name itself cannot detect redirection. */
+    expectedAudience: string;
+    /** The terminal hop's `nonce` must equal this. Required: it is the replay defence. */
+    expectedNonce: string;
+    /** Verification time, epoch seconds (default: now). */
+    now?: number;
+    /** Tolerated clock skew in seconds (default 60). */
+    clockSkewSeconds?: number;
+}
+export type ChainResult = {
+    ok: true;
+    hops: VerifiedHop[];
+} | {
+    ok: false;
+    reason: string;
+};
+/** Split a `~~`-joined chain into hops, each restored to `<jwt>~<d>...~`. */
+export declare function splitChain(token: string): string[];
+/** Verify one key-binding hop against its predecessor (signature, typ, binding hash, times, aud/nonce). */
+export declare function verifyKbHop(hop: SdJwtHop, prev: {
+    hop: SdJwtHop;
+    mandate: JsonObject;
+}, o: {
+    terminal: boolean;
+    expectedAudience?: string;
+    expectedNonce?: string;
+    now: number;
+    skew: number;
+}, label: string): VerifiedHop;
+/** Verify a whole chain: root signature, then every hop in order. Never throws; reports the reason. */
+export declare function verifyDelegationChain(token: string, o: VerifyChainOptions): ChainResult;
+export type CheckoutChainResult = {
+    ok: true;
+    open: OpenCheckoutMandateClaims;
+    closed: CheckoutMandateClaims;
+    checkoutJwt: string;
+    checkout: UcpCheckout;
+    /** `sd_hash` of the open checkout mandate token: the value an open payment mandate's `payment.reference` must hold. */
+    openHash: string;
+    hops: VerifiedHop[];
+} | {
+    ok: false;
+    reason: string;
+    violations?: string[];
+};
+export interface VerifyCheckoutOptions extends VerifyChainOptions {
+    /** Resolve the merchant's key for the `checkout_jwt` signature; return undefined to refuse. */
+    resolveMerchantKey: (header: JwtHeader) => P256Jwk | undefined;
+}
+/** Verify an open+closed checkout chain, the merchant-signed checkout, its hash, and the open constraints. */
+export declare function verifyCheckoutChain(token: string, o: VerifyCheckoutOptions): CheckoutChainResult;
+export type PaymentChainResult = {
+    ok: true;
+    open: OpenPaymentMandateClaims;
+    closed: PaymentMandateClaims;
+    openHash: string;
+    hops: VerifiedHop[];
+} | {
+    ok: false;
+    reason: string;
+    violations?: string[];
+};
+export interface VerifyPaymentOptions extends VerifyChainOptions {
+    /** `sd_hash` of the open checkout mandate (from `verifyCheckoutChain().openHash`); checked against `payment.reference`. */
+    openCheckoutHash: string;
+    /** Usage state under this open mandate (needed for `payment.budget` and recurrence). */
+    context?: MandateContext;
+    /** The `checkout_hash` this payment must settle (from the closed checkout mandate). */
+    expectedTransactionId?: string;
+}
+/** Verify an open+closed payment chain and every open payment constraint. */
+export declare function verifyPaymentChain(token: string, o: VerifyPaymentOptions): PaymentChainResult;
+export interface VerifyPurchaseOptions {
+    resolveIssuerKey: VerifyChainOptions['resolveIssuerKey'];
+    resolveMerchantKey: VerifyCheckoutOptions['resolveMerchantKey'];
+    checkout: {
+        expectedAudience: string;
+        expectedNonce: string;
+    };
+    payment: {
+        expectedAudience: string;
+        expectedNonce: string;
+    };
+    context?: MandateContext;
+    now?: number;
+    clockSkewSeconds?: number;
+}
+export type PurchaseResult = {
+    ok: true;
+    checkout: Extract<CheckoutChainResult, {
+        ok: true;
+    }>;
+    payment: Extract<PaymentChainResult, {
+        ok: true;
+    }>;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Verify a complete purchase: the checkout chain, then the payment chain bound to it (the payment's
+ * `payment.reference` is the open checkout hash; its `transaction_id` is the closed checkout's
+ * `checkout_hash`), and that the payment settles what the merchant quoted (payee, currency, total).
+ */
+export declare function verifyPurchase(checkoutToken: string, paymentToken: string, o: VerifyPurchaseOptions): PurchaseResult;