@atlasauth/pca-llamaindex 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,52 @@
-# Temporary Holding Version
+# @atlasauth/pca-llamaindex
 
-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.
+LlamaIndex.TS adapter for Proof-Carrying Authority (PCA). `withPCA` wraps a `FunctionTool` so every call first builds a signed PCActn (failing fast if the agent's own grant does not permit it), hands you the proof to forward to the resource server, and then runs the original tool.
+
+## Install
+
+```sh
+npm i @atlasauth/pca-llamaindex @atlasauth/pca
+npm i llamaindex   # optional peer dependency (^0.8 || ^0.9 || ^0.10)
+```
+
+## Usage
+
+```ts
+import { agent, generateKeyPair } from '@atlasauth/pca';
+import { withPCA } from '@atlasauth/pca-llamaindex';
+
+const pcaAgent = agent({
+  principal: generateKeyPair(),
+  goal: 'process refunds',
+  permissions: { stripe: ['refund'] },
+  limits: { refund: '$500/day' },
+  aud: 'ins_acme',
+});
+
+const guardedRefund = withPCA(
+  pcaAgent,
+  {
+    verb: 'stripe.refund',
+    resource: (args) => `charge:${args.charge}`,
+    onProof: (pca, args) => {
+      // forward pca.headers (PCA-Action) to the resource server with your request
+    },
+  },
+  refundTool, // your LlamaIndex FunctionTool
+);
+```
+
+The wrapped tool has the same shape (`metadata` and other fields preserved; only `call` is wrapped), so it drops into your agent's `tools` array. If the agent's local dry-run denies the action, the call throws `PcaDenied` before the tool runs (disable with `failFast: false`).
+
+## API
+
+- `withPCA(agent, spec, tool)` - spec is `{ verb, resource, aud?, failFast?, onProof? }`.
+- Re-exports `bridgeToolCall`, `pcaHeaders`, and the `PcaCall` type from `@atlasauth/pca`.
+
+## Status
+
+This package does not authorize anything. It attaches a proof-carrying action; the resource server's verifier (see `@atlasauth/pca`) decides. The `llamaindex` package is matched structurally and never imported. PCA cryptography has not been independently audited.
+
+## License
+
+MIT - see LICENSE

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * LlamaIndex.TS adapter for Proof-Carrying Authority.
+ *
+ * Wrap a LlamaIndex FunctionTool so every call first builds a PCActn (via the core `guard`) — fast-failing
+ * on the agent's local dry-run and handing the proof to your `onProof` so it can forward it to the resource
+ * server — then runs the original tool. Drop-in: the wrapped tool has the SAME shape, so it slots straight
+ * into the `tools` array you hand to a LlamaIndex agent.
+ *
+ * Structurally compatible with the `llamaindex` package (declare `llamaindex` as a peer dependency). We touch
+ * only `call` and preserve `metadata` and every other field, so this works across minor versions without
+ * importing the SDK's runtime.
+ *
+ * HONEST: this does not authorize — it attaches a proof-carrying action; the resource server's verifier
+ * decides. A bypassed wrapper just means the action lacks a valid PCActn and fails server-side.
+ */
+import { type Agent, type PcaCall, bridgeToolCall, pcaHeaders } from '@atlasauth/pca';
+/**
+ * Minimal structural shape of a LlamaIndex FunctionTool. `call` is a METHOD (not an arrow property) on
+ * purpose: method signatures are bivariant, so a tool with concrete argument types assigns cleanly to the
+ * general `LlamaIndexTool` when collected in a `tools` array — no `any`, no casts.
+ */
+export interface LlamaIndexTool<ARGS = Record<string, unknown>, RESULT = unknown> {
+    metadata: {
+        name: string;
+        description?: string;
+        parameters?: unknown;
+    };
+    call(input: ARGS): Promise<RESULT> | RESULT;
+    [k: string]: unknown;
+}
+export interface GuardToolSpec<ARGS> {
+    /** Catalog verb this tool maps to (e.g. `stripe.refund`). */
+    verb: string;
+    /** Resource for the call: fixed, or derived from the tool args. */
+    resource: string | ((args: ARGS) => string);
+    /** Audience (resource-server / instance id); falls back to the agent's default. */
+    aud?: string;
+    /** Fast-fail on the local dry-run before executing (default true). */
+    failFast?: boolean;
+    /** Receive the PCActn so `call` can forward it (e.g. as request headers) to the resource server. */
+    onProof?: (pca: PcaCall, args: ARGS) => void;
+}
+/** Wrap a LlamaIndex FunctionTool so each call emits + attaches a PCActn before the original `call` runs. */
+export declare function withPCA<ARGS extends Record<string, unknown>, RESULT>(agent: Agent, spec: GuardToolSpec<ARGS>, tool: LlamaIndexTool<ARGS, RESULT>): LlamaIndexTool<ARGS, RESULT>;
+export { bridgeToolCall, pcaHeaders, type PcaCall };

package/dist/index.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * LlamaIndex.TS adapter for Proof-Carrying Authority.
+ *
+ * Wrap a LlamaIndex FunctionTool so every call first builds a PCActn (via the core `guard`) — fast-failing
+ * on the agent's local dry-run and handing the proof to your `onProof` so it can forward it to the resource
+ * server — then runs the original tool. Drop-in: the wrapped tool has the SAME shape, so it slots straight
+ * into the `tools` array you hand to a LlamaIndex agent.
+ *
+ * Structurally compatible with the `llamaindex` package (declare `llamaindex` as a peer dependency). We touch
+ * only `call` and preserve `metadata` and every other field, so this works across minor versions without
+ * importing the SDK's runtime.
+ *
+ * HONEST: this does not authorize — it attaches a proof-carrying action; the resource server's verifier
+ * decides. A bypassed wrapper just means the action lacks a valid PCActn and fails server-side.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pcaHeaders = exports.bridgeToolCall = void 0;
+exports.withPCA = withPCA;
+const pca_1 = require("@atlasauth/pca");
+Object.defineProperty(exports, "bridgeToolCall", { enumerable: true, get: function () { return pca_1.bridgeToolCall; } });
+Object.defineProperty(exports, "pcaHeaders", { enumerable: true, get: function () { return pca_1.pcaHeaders; } });
+/** Wrap a LlamaIndex FunctionTool so each call emits + attaches a PCActn before the original `call` runs. */
+function withPCA(agent, spec, tool) {
+    const run = (0, pca_1.guard)(agent, {
+        verb: spec.verb,
+        resource: spec.resource,
+        ...(spec.aud !== undefined ? { aud: spec.aud } : {}),
+        ...(spec.failFast !== undefined ? { failFast: spec.failFast } : {}),
+    }, async (args, pca) => {
+        spec.onProof?.(pca, args);
+        return (await tool.call(args));
+    });
+    return { ...tool, call: (input) => run(input) };
+}
+//# 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;;;;;;;;;;;;;;GAcG;;;AA6BH,0BAmBC;AA9CD,wCAA6F;AAgDpF,+FAhD0B,oBAAc,OAgD1B;AAAE,2FAhDiC,gBAAU,OAgDjC;AAtBnC,6GAA6G;AAC7G,SAAgB,OAAO,CACrB,KAAY,EACZ,IAAyB,EACzB,IAAkC;IAElC,MAAM,GAAG,GAAG,IAAA,WAAK,EACf,KAAK,EACL;QACE,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpE,EACD,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAClB,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC1B,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAW,CAAC;IAC3C,CAAC,CACF,CAAC;IACF,OAAO,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC,KAAW,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;AACxD,CAAC"}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@atlasauth/pca-llamaindex",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "LlamaIndex.TS adapter for Proof-Carrying Authority: wrap a FunctionTool so each call emits a PCActn before it runs.",
+  "keywords": [
+    "llamaindex",
+    "tool calling",
+    "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-llamaindex"
+  },
+  "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": {
+    "llamaindex": "^0.8 || ^0.9 || ^0.10"
+  },
+  "peerDependenciesMeta": {
+    "llamaindex": {
+      "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"
+  }
 }