@atlasauth/pca-ap2 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +45 -31
  3. package/package.json +28 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Atlas Authorization
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,69 +1,83 @@
1
1
  # @atlasauth/pca-ap2
2
2
 
3
- AP2 (Agent Payments Protocol) wire-compatibility for PCA. AP2 — donated to the FIDO Alliance, v0.2 shape (2026-04-28) — models agentic payments as a chain of signed Verifiable Digital Credentials: **IntentMandate → CartMandate → PaymentMandate**. That chain is a near-isomorphism of PCA's attenuating capability chain, so this package bridges the two.
3
+ AP2 (Agent Payments Protocol, FIDO Alliance) wire-compatibility for Proof-Carrying Authority (PCA). AP2 models agentic payments as a chain of signed Verifiable Digital Credentials: IntentMandate, then CartMandate, then PaymentMandate. That chain closely mirrors PCA's attenuating capability chain, and this package maps one onto the other (v0.2 shape).
4
4
 
5
- **PCA governs. AP2 is the payment-mandate wire. x402 / Stripe Shared Payment Tokens settle. Compose them.**
5
+ 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.
6
6
 
7
- - **PCA** (`@atlasauth/pca`, `@atlasauth/pca-payments`) = the authority / budget layer: who may spend, how much, until when, and when a human must co-sign.
8
- - **AP2** = the Intent→Cart→Payment VDC chain other parties verify.
9
- - **x402 / Stripe SPT** = the settlement rails that actually move value, fed by PCA's governance.
7
+ ## Install
10
8
 
11
- This is a bridge, not a replacement.
12
-
13
- ## ⚠️ Verify against the AP2 schemas before production
9
+ ```sh
10
+ npm i @atlasauth/pca-ap2
11
+ ```
14
12
 
15
- AP2 is a moving target and its mandate field-level signing roles differ between secondary sources (e.g. whether a cart is co-signed by both merchant and user, and whether the step is called "Cart" or "Checkout"), and it layers over UCP (`ucp.dev`), whose dated releases move the payment token between `payment_data.token` and `payment.instruments[*].credential.token`. This package models the v0.2 Intent/Cart/Payment chain **to the best public understanding** and **must be validated against the AP2 repository `schemas/` and the official spec at [ap2-protocol.org](https://ap2-protocol.org) before any production wire use.** PCA-native terms that AP2 has no field for are carried in a namespaced `x_pca` extension (so the chain round-trips back to PCA terms); those fields are non-standard by construction.
13
+ Depends on `@atlasauth/pca` and `@atlasauth/pca-payments` (installed transitively; you will usually import `buildPaymentMandate` from the latter).
16
14
 
17
15
  ## Usage
18
16
 
19
17
  ```ts
18
+ import { encodeKey, generateKeyPair } from '@atlasauth/pca';
20
19
  import { buildPaymentMandate, authorizeCharge } from '@atlasauth/pca-payments';
21
20
  import {
22
21
  toAP2IntentMandate, toAP2CartMandate, toAP2PaymentMandate,
23
22
  chainMandates, fromAP2Mandate, x402Settlement, stripeSptSettlement,
24
23
  } from '@atlasauth/pca-ap2';
25
24
 
25
+ const principal = generateKeyPair(), merchantKey = generateKeyPair();
26
+ const payerKey = generateKeyPair(), agentKey = generateKeyPair();
27
+ const pub = (k: { publicKey: Uint8Array }) => encodeKey(k.publicKey);
28
+
26
29
  // 1. A PCA payment mandate (the authority layer).
27
30
  const mandate = buildPaymentMandate({
28
- principalSecret, principalPublic, agentPublic,
31
+ principalSecret: principal.secretKey, principalPublic: pub(principal), agentPublic: pub(agentKey),
29
32
  merchants: ['acme'], currency: 'USD',
30
33
  perTransactionCap: 500, autoApproveThreshold: 50, cumulativeCap: 1000,
31
34
  });
32
35
 
33
- // 2. Map it down the AP2 VDC chain (each step narrows, never amplifies).
34
- const intent = toAP2IntentMandate(mandate, { issuerPublic, issuerSecret }); // user signs
35
- const cart = toAP2CartMandate(intent,
36
- { merchant: 'acme', items: [{ name: 'Seat', quantity: 1, unit_price: { currency: 'USD', value: 120 } }] },
37
- { issuerPublic: merchantPublic, issuerSecret: merchantSecret }); // merchant signs
38
-
39
- // The human-present signal maps from the PCA decision: tier-3 human step-up ⇒ human_present = true.
40
- const decision = authorizeCharge(mandate, { merchant: 'acme', amount: 120, currency: 'USD' });
36
+ // 2. Map it down the AP2 chain; each step narrows, never widens.
37
+ const intent = toAP2IntentMandate(mandate, { issuerPublic: pub(principal), issuerSecret: principal.secretKey });
38
+ const cart = toAP2CartMandate(
39
+ intent,
40
+ { merchant: 'acme', items: [{ sku: 'seat', name: 'Seat', quantity: 1, unit_price: { currency: 'USD', value: 120 } }] },
41
+ { issuerPublic: pub(merchantKey), issuerSecret: merchantKey.secretKey },
42
+ );
43
+ const decision = authorizeCharge(mandate, { merchant: 'acme', amount: 120, currency: 'USD' }); // step-up, t = 3
41
44
  const payment = toAP2PaymentMandate(cart, {
42
- issuerPublic: payerPublic, issuerSecret: payerSecret,
45
+ issuerPublic: pub(payerKey), issuerSecret: payerKey.secretKey,
43
46
  paymentMethod: { type: 'card' }, pcaTier: decision.t, intent,
44
47
  });
45
48
 
46
- // 3. Assemble + verify the chain is a non-amplifying narrowing (mirrors PCA attenuation).
47
- const chain = chainMandates(intent, cart, payment);
48
- chain.verify(); // { ok: true, reasons: [] }
49
+ // 3. Verify the chain is a non-amplifying narrowing.
50
+ chainMandates(intent, cart, payment).verify(); // { ok: true, reasons: [] }
49
51
 
50
52
  // 4. Parse back toward PCA terms.
51
53
  fromAP2Mandate(intent); // { type: 'IntentMandate', merchants: ['acme'], perTransactionCap: 500, ... }
52
54
 
53
- // 5. Hand the verified payment mandate to a settlement rail (structural; no network here).
54
- x402Settlement.settle(payment, { resourceUrl, payTo, network: 'base' });
55
+ // 5. Build the rail's wire shape from the payment mandate (structural, no network).
56
+ x402Settlement.settle(payment, { resourceUrl: 'https://api.example.com/report', payTo: '0xabc', network: 'base' });
55
57
  stripeSptSettlement.settle(payment, { payTo: 'acct_merchant' });
56
58
  ```
57
59
 
58
60
  ### Human-present mapping
59
61
 
60
- | PCA decision | AP2 `human_present` |
61
- | --------------------------------------------- | ------------------- |
62
- | tier 1 — autonomous (amount ≤ Y, budget OK) | `false` (human-not-present) |
63
- | tier 3 — human step-up / co-sign required | `true` (human-present) |
62
+ | PCA decision | AP2 `human_present` |
63
+ | --- | --- |
64
+ | tier 1: autonomous (within the auto-approve threshold and budget) | `false` |
65
+ | tier 3: human step-up or co-sign required | `true` |
66
+
67
+ ## API
68
+
69
+ - Mapping: `toAP2IntentMandate`, `toAP2CartMandate`, `toAP2PaymentMandate`, `fromAP2Mandate`.
70
+ - Signing and chain: `signMandate`, `verifyMandate`, `mandateHash`, `chainMandates`, `verifyAP2Chain`.
71
+ - Settlement hooks: `x402Settlement`, `stripeSptSettlement` (the `SettlementBackend` interface).
72
+
73
+ ## Status
74
+
75
+ Experimental. AP2 is still evolving, and secondary sources disagree on field-level signing roles (for example who co-signs a cart) and on where UCP-layer payment tokens live. This package models the v0.2 Intent/Cart/Payment chain to the best public understanding; validate it against the official AP2 schemas and spec at https://ap2-protocol.org before production wire use. PCA-specific terms that AP2 has no field for are carried in a namespaced, non-standard `x_pca` extension.
76
+
77
+ 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. They assume the mandate has already been verified. The cryptography is unaudited.
64
78
 
65
- ### Settlement backends
79
+ Source and issues: https://github.com/Atlas-Authorization/pca
66
80
 
67
- `x402Settlement` and `stripeSptSettlement` implement `SettlementBackend` and are **structural only** — they turn a (presumed-verified) Payment Mandate into the rail's wire shape (x402's HTTP-402 challenge + `X-PAYMENT` header; Stripe's Shared-Payment-Token charge in minor units). They perform no network I/O; they are the hooks a real integration fills in, fed by PCA's governance decision.
81
+ ## License
68
82
 
69
- Part of Proof-Carrying Authority — see `@atlasauth/pca`.
83
+ MIT - see LICENSE
package/package.json CHANGED
@@ -1,7 +1,27 @@
1
1
  {
2
2
  "name": "@atlasauth/pca-ap2",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "AP2 (Agent Payments Protocol, FIDO) wire-compatibility for PCA: map the grant/budget to Intent/Cart/Payment mandate VDCs; PCA governs, x402 / Stripe Shared-Payment-Tokens settle.",
5
+ "keywords": [
6
+ "ap2",
7
+ "agent payments protocol",
8
+ "mandates",
9
+ "payments",
10
+ "agent authorization",
11
+ "proof-carrying authority",
12
+ "pca",
13
+ "ai agents"
14
+ ],
15
+ "license": "MIT",
16
+ "homepage": "https://github.com/Atlas-Authorization/pca#readme",
17
+ "bugs": {
18
+ "url": "https://github.com/Atlas-Authorization/pca/issues"
19
+ },
20
+ "repository": {
21
+ "type": "git",
22
+ "url": "git+https://github.com/Atlas-Authorization/pca.git",
23
+ "directory": "packages/pca-ap2"
24
+ },
5
25
  "main": "./dist/index.js",
6
26
  "types": "./dist/index.d.ts",
7
27
  "exports": {
@@ -12,8 +32,8 @@
12
32
  "./package.json": "./package.json"
13
33
  },
14
34
  "dependencies": {
15
- "@atlasauth/pca": "0.1.0",
16
- "@atlasauth/pca-payments": "0.1.0"
35
+ "@atlasauth/pca": "0.2.0",
36
+ "@atlasauth/pca-payments": "0.2.0"
17
37
  },
18
38
  "devDependencies": {
19
39
  "typescript": "^5.6.3",
@@ -21,8 +41,12 @@
21
41
  },
22
42
  "files": [
23
43
  "dist",
24
- "README.md"
44
+ "README.md",
45
+ "LICENSE"
25
46
  ],
47
+ "engines": {
48
+ "node": ">=20"
49
+ },
26
50
  "publishConfig": {
27
51
  "access": "public"
28
52
  },