@atlasauth/pca-anthropic 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,39 +1,62 @@
 # @atlasauth/pca-anthropic
 
-Anthropic (Claude) adapter for Proof-Carrying Authority: turn a tool_use block into a PCActn and build the tool_result with the proof attached.
+Anthropic (Claude) adapter for Proof-Carrying Authority (PCA). It sits between a Claude `tool_use` block and the `tool_result` you send back: it turns the block into a PCActn (a signed proof-carrying action) using a PCA `Agent`, runs your handler with the proof in hand, and returns the `tool_result` block, including the error-shaped result Claude expects when a tool is declined or throws.
+
+It does not authorize anything itself: it attaches a proof, and the resource server's verifier decides. A handler that forgets to forward the proof just produces a downstream call without a valid PCActn, which fails server-side.
 
 ## Install
 
 ```sh
-npm i @atlasauth/pca-anthropic
-# peer dependency, install alongside:
+npm i @atlasauth/pca-anthropic @atlasauth/pca
 npm i @anthropic-ai/sdk
 ```
 
-`@anthropic-ai/sdk` is an optional peer dependency.
+`@anthropic-ai/sdk` is an optional peer dependency; the adapter models only the block shapes it touches and does not import the SDK at runtime.
 
 ## Usage
 
 ```ts
-import { handleToolUse, extractToolUses } from '@atlasauth/pca-anthropic';
-
-// For each tool_use block in the assistant message:
-for (const block of extractToolUses(message.content)) {
-  const toolResult = await handleToolUse(
-    agent,                                 // core @atlasauth/pca Agent
-    block,                                 // { type: 'tool_use', id, name, input }
-    ({ name, input }) =>                   // map tool → catalog { verb, resource }; null declines
-      name === 'refund' ? { verb: 'stripe.refund', resource: `ch_${input.chargeId}` } : null,
-    {
-      refund: async (input, pca) => {      // pca carries the signed proof to forward downstream
-        return doRefund(input);
-      },
+import { agent, generateKeyPair } from '@atlasauth/pca';
+import { handleToolUses, extractToolUses } from '@atlasauth/pca-anthropic';
+
+const pcaAgent = agent({
+  principal: generateKeyPair(),
+  goal: 'issue refunds',
+  permissions: { stripe: ['refund'] },
+  limits: { refund: '$500/day' },
+  aud: 'ins_acme',                       // the id your resource server verifies against
+});
+
+// After each assistant turn, answer every tool_use block:
+const toolResults = await handleToolUses(
+  pcaAgent,
+  extractToolUses(message.content),
+  ({ name, input }) =>                   // map tool -> { verb, resource }; return null to decline
+    name === 'refund' ? { verb: 'stripe.refund', resource: `charge:${input.chargeId}` } : null,
+  {
+    refund: async (input, pca) => {      // pca.headers / pca.encoded carry the signed proof
+      return doRefund(input, pca.headers);
     },
-  );
-  // → { type: 'tool_result', tool_use_id, content } (is_error:true on a declined/failed tool)
-}
+  },
+);
+// -> [{ type: 'tool_result', tool_use_id, content }]; is_error: true when declined, unhandled or thrown
+// Append them to your next user message's content.
 ```
 
-`handleToolUse` builds a PCActn and attaches the proof; it does not authorize on its own — the resource server's verifier decides.
+`handleToolUse` does the same for a single block. On success `content` is the JSON of your handler's return value (or `{ pca: <encoded> }` if it returns nothing).
+
+## API
+
+- `handleToolUse(agent, block, map, handlers, opts?)`, `handleToolUses(agent, blocks, map, handlers, opts?)`, `extractToolUses(content)`.
+- Types: `ToolUseBlock`, `ToolResultBlock`, `ToolMapping`, `ToolHandler`.
+- Re-exports from `@atlasauth/pca`: `pcaHeaders`, `PcaCall`.
+
+## 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,26 @@
 {
   "name": "@atlasauth/pca-anthropic",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Anthropic (Claude) adapter for Proof-Carrying Authority: turn a tool_use block into a PCActn and build the tool_result with the proof attached.",
+  "keywords": [
+    "anthropic",
+    "claude",
+    "tool use",
+    "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-anthropic"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -12,7 +31,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@atlasauth/pca": "0.1.0"
+    "@atlasauth/pca": "0.3.0"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": "^0.30 || ^0.40 || ^0.50"
@@ -28,8 +47,12 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
+  "engines": {
+    "node": ">=20"
+  },
   "publishConfig": {
     "access": "public"
   },