@atlasauth/pca-agent 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

@@ -1,6 +1,8 @@
 # @atlasauth/pca-agent
 
-Agent-side client for Proof-Carrying Authority: commit a plan, act with a PCActn + threshold share, handle step-up, delegate to sub-agents, verify receipts.
+Agent-side client for Proof-Carrying Authority (PCA). It commits a plan, builds and signs a PCActn (a proof-carrying action) for a plan node, posts it to a resource server, handles step-up approval, delegates attenuated authority to sub-agents, and checks ledger inclusion receipts.
+
+The client talks to a resource server that exposes the PCA HTTP surface: `POST /v1/pca/plans`, `POST /v1/pca/actions` and `GET /v1/pca/stepups/:id` (the hosted Atlas API does, and so can your own server). `act` emits a proof; it does not authorize anything on its own. The resource server's verifier decides allow, step-up or deny.
 
 ## Install
 
@@ -8,7 +10,7 @@ Agent-side client for Proof-Carrying Authority: commit a plan, act with a PCActn
 npm i @atlasauth/pca-agent
 ```
 
-Depends on the core `@atlasauth/pca` (installed transitively).
+Depends on `@atlasauth/pca` (installed transitively).
 
 ## Usage
 
@@ -16,25 +18,47 @@ Depends on the core `@atlasauth/pca` (installed transitively).
 import { createAgent } from '@atlasauth/pca-agent';
 
 const client = createAgent({
-  grant,                 // principal-signed Capability
-  agentSecret,           // Ed25519 secret (32 bytes) of the leaf holder
+  grant,                 // principal-signed Capability (see @atlasauth/pca)
+  agentSecret,           // Ed25519 secret key (32 bytes) of the leaf holder
   rsBaseUrl: 'https://api.example.com',
-  audience: 'ins_acme',  // the resource-server / Atlas instance id the PCActn is FOR
+  audience: 'ins_acme',  // required: the id the resource server verifies against
 });
 
 // 1. Commit the principal-authorised plan (once).
 await client.commitPlan([{ id: 'refund-1', verb: 'stripe.refund', resource: 'ch_123' }]);
 
-// 2. Act on a plan node — builds + signs a PCActn and POSTs it to the resource server.
+// 2. Act on a plan node: builds and signs a PCActn, then POSTs it.
 const res = await client.act('refund-1', { amount: 500 });
 
 if (res.status === 'allowed') {
-  client.verifyReceipt(res.receipt);        // check the ledger inclusion proof
+  client.verifyReceipt(res.receipt);                       // ledger inclusion proof -> boolean
 } else if (res.status === 'step_up') {
-  const outcome = await client.awaitStepUp(res.stepupId); // poll for human co-sign
+  const outcome = await client.awaitStepUp(res.stepupId);  // polls for human co-sign
+} else if (res.status === 'denied') {
+  console.log(res.verdict.reason);
 }
+
+// 3. Hand a narrower slice of authority to a sub-agent.
+const sub = client.delegate({
+  toPublic: subAgentPublicKey,
+  addedCaveats: [{ type: 'ttl', secs: 60 }],
+  agentSecret: subAgentSecret,
+});
 ```
 
-`act` emits a proof-carrying action; it does not authorize on its own. The resource server's verifier decides allow / step-up / deny.
+`audience` is required because a PCActn only verifies at the audience it names, which stops it being replayed at another server. A fresh random nonce is stamped on each action by default, and the per-action counter only moves forward. `act` resolves to `{ status: 'error', error }` (a `PcaAgentError`) for local failures such as calling before `commitPlan` or an unknown node id. Pass `fetch` to supply your own HTTP client.
+
+## API
+
+- `createAgent(options)` returns an `AgentClient` with `commitPlan`, `act`, `awaitStepUp`, `delegate`, `verifyReceipt`, plus `grant`, `chain`, `counter`, `budget`, `planRoot`.
+- Types: `ActResult`, `StepUpOutcome`, `Receipt`, `Verdict`, `ActSlots` (optional signed slots such as `caution`), `PcaAgentError`.
+
+## Status
+
+Experimental. The underlying cryptography in `@atlasauth/pca` has not been independently audited.
+
+Source and issues: https://github.com/Atlas-Authorization/pca
+
+## License
 
-Part of Proof-Carrying Authority — see `@atlasauth/pca`.
+MIT - see LICENSE

package/package.json

@@ -1,7 +1,27 @@
 {
   "name": "@atlasauth/pca-agent",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Agent-side client for Proof-Carrying Authority: commit a plan, act with a PCActn + threshold share, handle step-up, delegate to sub-agents, verify receipts.",
+  "keywords": [
+    "agent client",
+    "step-up",
+    "delegation",
+    "receipts",
+    "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-agent"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -12,7 +32,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@atlasauth/pca": "0.1.0"
+    "@atlasauth/pca": "0.3.0"
   },
   "devDependencies": {
     "typescript": "^5.6.3",
@@ -20,8 +40,12 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
+  "engines": {
+    "node": ">=20"
+  },
   "publishConfig": {
     "access": "public"
   },