@atlasauth/pca-a2a 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atlas Authorization
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# @atlasauth/pca-a2a
+
+A2A (Agent2Agent) adapter for Proof-Carrying Authority (PCA). A2A defines how agents discover each other and exchange tasks; it does not prove that a relayed request is authorized by the principal behind it. This package binds PCA proofs onto three A2A surfaces, failing closed throughout:
+
+1. **Proof-carrying tasks** - attach a PCActn (a signed single-action proof with its capability chain) to a Task or Message under a namespaced `metadata` key, and verify it on receipt.
+2. **Signed Agent Cards** - issue and validate an A2A `AgentCardSignature` (a detached JWS, via `jose`) whose protected header commits to the agent's PCA passport id.
+3. **AP2 payment profile** - map a PCActn to an AP2-shaped Payment Mandate that carries its authority by reference to the proof.
+
+## Install
+
+```sh
+npm i @atlasauth/pca-a2a
+```
+
+Depends on `@atlasauth/pca` and `jose` (installed transitively). For the full AP2 Intent/Cart/Payment chain and settlement hooks, see `@atlasauth/pca-ap2`.
+
+## Usage
+
+```ts
+import { buildPCActn } from '@atlasauth/pca';
+import {
+  attachPcaToA2ATask, pcaA2AMiddleware,
+  issueSignedAgentCard, verifyAgentCard,
+  a2aPaymentMandateFromPca, verifyA2APaymentMandate,
+} from '@atlasauth/pca-a2a';
+
+// Sender: build a PCActn with @atlasauth/pca, then ride it on the task.
+const pcActn = buildPCActn({ grant, chain: [grant], plan, nodeId: 'buy-1', counter: 1,
+                             signerSecret: agentSecret, aud: 'my-rs' });
+const task = attachPcaToA2ATask({ id: 't1', status: { state: 'submitted' } }, pcActn);
+
+// Receiver: guard incoming tasks. Pin the principal you trust.
+const guard = pcaA2AMiddleware({ aud: 'my-rs', expectedRootIssuer: principalPublicKey });
+const verdict = await guard(task);       // { ok: true, result, pcActn } | { ok: false, reason }
+
+// Signed Agent Card (key is a jose KeyLike, Uint8Array or JWK).
+const card = await issueSignedAgentCard({ name: 'Buyer', url: 'https://a.example' }, privateKey,
+                                        { passport: { id: 'pp_1' } });
+await verifyAgentCard(card, { key: publicKey });  // { ok: true, passportRef: 'pp_1', ... }
+
+// Payment mandate that points at the PCActn.
+const mandate = a2aPaymentMandateFromPca(pcActn, {
+  amount: { currency: 'USD', value: 120 }, paymentMethod: { type: 'card' }, merchant: 'acme',
+});
+await verifyA2APaymentMandate(mandate, pcActn, { aud: 'my-rs', expectedRootIssuer: principalPublicKey });
+```
+
+By default a guard requires a proof (`require: true`); with `require: false` a task without a proof passes, but a proof that is present and invalid is still rejected. Always pin `expectedRootIssuer` (or `grant`): otherwise the chain root is taken from the proof itself and only proves internal consistency, not that a principal you trust issued it.
+
+## API
+
+- Tasks: `attachPcaToA2ATask`, `attachPcaToA2AMessage`, `extractPca`, `extractPcaFromMessage`, `verifyA2ATask`, `pcaA2AMiddleware`, `PCA_A2A_EXTENSION_URI`.
+- Agent Cards: `issueSignedAgentCard`, `verifyAgentCard` (verify with a single `key` or a `jwks`).
+- Payments: `a2aPaymentMandateFromPca`, `pcaBindingFromA2APaymentMandate`, `verifyA2APaymentMandate`, `A2A_AP2_CONTEXT`.
+
+## Status
+
+Experimental. The A2A object model here is structural and permissive, not a full A2A SDK. The Payment Mandate shape follows the AP2 vocabulary but its JSON-LD context is a placeholder and PCA-specific fields live in a non-standard `x_pca` extension; validate against the official AP2 schemas before production use. The cryptography is unaudited.
+
+Source and issues: https://github.com/Atlas-Authorization/pca
+
+## License
+
+MIT - see LICENSE

package/package.json

@@ -1,7 +1,27 @@
 {
   "name": "@atlasauth/pca-a2a",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A2A (Agent2Agent) adapter for PCA: verify/attach proof-carrying actions on A2A task send/receive, validate Signed Agent Cards, and an AP2 payment-mandate profile.",
+  "keywords": [
+    "a2a",
+    "agent2agent",
+    "agent card",
+    "ap2",
+    "agent authorization",
+    "proof-carrying authority",
+    "pca",
+    "ai agents"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/Atlas-Authorization/pca#readme",
+  "bugs": {
+    "url": "https://github.com/Atlas-Authorization/pca/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Atlas-Authorization/pca.git",
+    "directory": "packages/pca-a2a"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -13,7 +33,7 @@
   },
   "dependencies": {
     "jose": "^5.9.6",
-    "@atlasauth/pca": "0.1.0"
+    "@atlasauth/pca": "0.3.0"
   },
   "devDependencies": {
     "typescript": "^5.6.3",
@@ -21,8 +41,12 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
+  "engines": {
+    "node": ">=20"
+  },
   "publishConfig": {
     "access": "public"
   },