@atlasauth/pca-anthropic 0.0.0-stage → 0.2.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,3 +1,62 @@
-# Temporary Holding Version
+# @atlasauth/pca-anthropic
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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 @atlasauth/pca
+npm i @anthropic-ai/sdk
+```
+
+`@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 { 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 when declined, unhandled or thrown
+// Append them to your next user message's content.
+```
+
+`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
+
+MIT - see LICENSE

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Anthropic (Claude) adapter for Proof-Carrying Authority.
+ *
+ * Claude's tool use is a conversation: an assistant message carries content blocks, and a
+ * `tool_use` block (`{ type, id, name, input }`) asks your app to run a tool. Your app runs it and
+ * replies with a user message containing a matching `tool_result` block (`{ tool_use_id, content }`).
+ * This adapter sits in that gap: it turns a `tool_use` block into a PCActn (via the core
+ * `bridgeToolCall`), runs your handler with the proof in hand, and hands back the `tool_result` to
+ * append to the next message — including the error-shaped result Claude expects when a tool refuses.
+ *
+ * Structurally compatible with the `@anthropic-ai/sdk` package (declared as an OPTIONAL peer
+ * dependency). We model only the block shapes we touch, so this works across SDK minor versions
+ * without importing its runtime — nothing here requires the SDK to be installed.
+ *
+ * HONEST: this does not authorize — it attaches a proof-carrying action; the resource server's
+ * verifier decides. A handler that forgets to forward the proof just means the downstream action
+ * lacks a valid PCActn and fails server-side.
+ */
+import { type Agent, type PcaCall, pcaHeaders } from '@atlasauth/pca';
+/** A Claude `tool_use` content block (what the model emits to call a tool). */
+export interface ToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+/** A Claude `tool_result` content block (what your app replies with). */
+export interface ToolResultBlock {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+    is_error?: boolean;
+}
+/** How a Claude tool name + input maps onto a PCA (verb, resource). Return null to decline the tool. */
+export type ToolMapping = (block: {
+    name: string;
+    input: Record<string, unknown>;
+}) => {
+    verb: string;
+    resource: string;
+} | null;
+/** Your tool implementation: gets the model's input and the PCActn so it can carry the proof downstream. */
+export type ToolHandler = (input: Record<string, unknown>, pca: import('@atlasauth/pca').PcaCall) => Promise<unknown> | unknown;
+/**
+ * Handle one `tool_use` block: build its PCActn, run the mapped handler, and return the `tool_result`.
+ *
+ * If the mapping declines the tool (returns null), we never run the handler — we return a
+ * `tool_result` with `is_error: true` so Claude sees the refusal. If the handler throws, we likewise
+ * return an error-shaped `tool_result`. On success, `content` is `JSON.stringify(result)`, falling
+ * back to `{ pca: <encoded> }` when the handler returns nothing.
+ */
+export declare function handleToolUse(agent: Agent, block: ToolUseBlock, map: ToolMapping, handlers: Record<string, ToolHandler>, opts?: {
+    aud?: string;
+    counter?: number;
+    now?: number;
+}): Promise<ToolResultBlock>;
+/** Handle many `tool_use` blocks (e.g. all of them from one assistant turn), preserving order. */
+export declare function handleToolUses(agent: Agent, blocks: ToolUseBlock[], map: ToolMapping, handlers: Record<string, ToolHandler>, opts?: {
+    aud?: string;
+    counter?: number;
+    now?: number;
+}): Promise<ToolResultBlock[]>;
+/** Pull the `tool_use` blocks out of an assistant message's `content` array (ignoring text/other blocks). */
+export declare function extractToolUses(content: Array<{
+    type: string;
+    [k: string]: unknown;
+}>): ToolUseBlock[];
+export { pcaHeaders, type PcaCall };

package/dist/index.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Anthropic (Claude) adapter for Proof-Carrying Authority.
+ *
+ * Claude's tool use is a conversation: an assistant message carries content blocks, and a
+ * `tool_use` block (`{ type, id, name, input }`) asks your app to run a tool. Your app runs it and
+ * replies with a user message containing a matching `tool_result` block (`{ tool_use_id, content }`).
+ * This adapter sits in that gap: it turns a `tool_use` block into a PCActn (via the core
+ * `bridgeToolCall`), runs your handler with the proof in hand, and hands back the `tool_result` to
+ * append to the next message — including the error-shaped result Claude expects when a tool refuses.
+ *
+ * Structurally compatible with the `@anthropic-ai/sdk` package (declared as an OPTIONAL peer
+ * dependency). We model only the block shapes we touch, so this works across SDK minor versions
+ * without importing its runtime — nothing here requires the SDK to be installed.
+ *
+ * HONEST: this does not authorize — it attaches a proof-carrying action; the resource server's
+ * verifier decides. A handler that forgets to forward the proof just means the downstream action
+ * lacks a valid PCActn and fails server-side.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pcaHeaders = void 0;
+exports.handleToolUse = handleToolUse;
+exports.handleToolUses = handleToolUses;
+exports.extractToolUses = extractToolUses;
+const pca_1 = require("@atlasauth/pca");
+Object.defineProperty(exports, "pcaHeaders", { enumerable: true, get: function () { return pca_1.pcaHeaders; } });
+/**
+ * Handle one `tool_use` block: build its PCActn, run the mapped handler, and return the `tool_result`.
+ *
+ * If the mapping declines the tool (returns null), we never run the handler — we return a
+ * `tool_result` with `is_error: true` so Claude sees the refusal. If the handler throws, we likewise
+ * return an error-shaped `tool_result`. On success, `content` is `JSON.stringify(result)`, falling
+ * back to `{ pca: <encoded> }` when the handler returns nothing.
+ */
+async function handleToolUse(agent, block, map, handlers, opts) {
+    const pca = (0, pca_1.bridgeToolCall)(agent, { name: block.name, arguments: block.input }, (b) => map({ name: b.name, input: b.arguments }), opts);
+    if (!pca) {
+        return {
+            type: 'tool_result',
+            tool_use_id: block.id,
+            content: `No proof-carrying authority is mapped for tool "${block.name}".`,
+            is_error: true,
+        };
+    }
+    const handler = handlers[block.name];
+    if (!handler) {
+        return {
+            type: 'tool_result',
+            tool_use_id: block.id,
+            content: `No handler registered for tool "${block.name}".`,
+            is_error: true,
+        };
+    }
+    try {
+        const result = await handler(block.input, pca);
+        return {
+            type: 'tool_result',
+            tool_use_id: block.id,
+            content: JSON.stringify(result ?? { pca: pca.encoded }),
+        };
+    }
+    catch (err) {
+        return {
+            type: 'tool_result',
+            tool_use_id: block.id,
+            content: err instanceof Error ? err.message : String(err),
+            is_error: true,
+        };
+    }
+}
+/** Handle many `tool_use` blocks (e.g. all of them from one assistant turn), preserving order. */
+async function handleToolUses(agent, blocks, map, handlers, opts) {
+    const uses = blocks.filter((b) => b.type === 'tool_use');
+    return Promise.all(uses.map((b) => handleToolUse(agent, b, map, handlers, opts)));
+}
+/** Pull the `tool_use` blocks out of an assistant message's `content` array (ignoring text/other blocks). */
+function extractToolUses(content) {
+    return content.filter((b) => b.type === 'tool_use');
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAwCH,sCA6CC;AAGD,wCASC;AAGD,0CAEC;AApGD,wCAAsF;AAsG7E,2FAtG0C,gBAAU,OAsG1C;AAxEnB;;;;;;;GAOG;AACI,KAAK,UAAU,aAAa,CACjC,KAAY,EACZ,KAAmB,EACnB,GAAgB,EAChB,QAAqC,EACrC,IAAuD;IAEvD,MAAM,GAAG,GAAG,IAAA,oBAAc,EACxB,KAAK,EACL,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,KAAK,EAAE,EAC5C,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,EAChD,IAAI,CACL,CAAC;IACF,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO;YACL,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE,KAAK,CAAC,EAAE;YACrB,OAAO,EAAE,mDAAmD,KAAK,CAAC,IAAI,IAAI;YAC1E,QAAQ,EAAE,IAAI;SACf,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO;YACL,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE,KAAK,CAAC,EAAE;YACrB,OAAO,EAAE,mCAAmC,KAAK,CAAC,IAAI,IAAI;YAC1D,QAAQ,EAAE,IAAI;SACf,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC/C,OAAO;YACL,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE,KAAK,CAAC,EAAE;YACrB,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;SACxD,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE,KAAK,CAAC,EAAE;YACrB,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;YACzD,QAAQ,EAAE,IAAI;SACf,CAAC;IACJ,CAAC;AACH,CAAC;AAED,kGAAkG;AAC3F,KAAK,UAAU,cAAc,CAClC,KAAY,EACZ,MAAsB,EACtB,GAAgB,EAChB,QAAqC,EACrC,IAAuD;IAEvD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAqB,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;IAC5E,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;AACpF,CAAC;AAED,6GAA6G;AAC7G,SAAgB,eAAe,CAAC,OAAsD;IACpF,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAA+C,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;AACnG,CAAC"}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@atlasauth/pca-anthropic",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.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": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@atlasauth/pca": "0.2.0"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/sdk": "^0.30 || ^0.40 || ^0.50"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }