prooflane-sdk 0.1.0

package/README.md

@@ -0,0 +1,39 @@
+# prooflane-sdk
+
+**The evidence gateway for AI agents that move money — built on the [CooL SDK](https://github.com/Northwind-Cipher/cool-sdk).**
+
+Wrap any consequential agent tool. Every call is checked against policy and sealed into an independently verifiable CooL receipt **before** the tool runs; the result is sealed under the same execution id. Blocked calls throw with a signed refusal. No receipt, no action.
+
+```bash
+npm i prooflane-sdk
+```
+
+```ts
+import { ProofLane, ProofLaneBlockedError } from "prooflane-sdk";
+
+const proof = new ProofLane({
+  apiKey: process.env.PROOFLANE_API_KEY!, // create a workspace at https://prooflane-mvp.vercel.app/console
+  agent: "payments-agent",
+  onReceipt: (receipt, vault) => db.save(receipt.record.record_id, vault), // keep plaintext for disclosures
+});
+
+const releasePayment = proof.guard("payment.release", bank.releasePayment, (args) => ({
+  id: args.approval_id,
+  approvers: args.approvers,
+}));
+
+try {
+  await releasePayment({ amount: 48200, currency: "USD", beneficiary: "Acme Ltd", approval_id: "APR-1", approvers: ["alice@acme.example"] });
+} catch (e) {
+  if (e instanceof ProofLaneBlockedError) console.log(e.decision.rule, e.receipt); // e.g. PAY-003, signed refusal
+}
+```
+
+Give `releasePayment` to your OpenAI / Anthropic / LangChain / MCP agent as its tool — it's just an async function.
+
+- `baseUrl` defaults to `https://prooflane-mvp.vercel.app`; pass your own deployment's URL to change it.
+- `proof.share(label)` creates an auditor evidence-room link; `approveDisclosure` / `denyDisclosure` answer field requests.
+
+Docs, architecture, and the live demo: https://github.com/charansaiponnada/prooflane-mvp
+
+MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * ProofLane SDK — put an evidence gateway in front of any consequential agent tool.
+ *
+ *   const proof = new ProofLane({ apiKey, agent: "payments-agent" });
+ *   const releasePayment = proof.guard("payment.release", rawReleasePayment, (args) => ({
+ *     id: args.approvalId,
+ *     approvers: args.approvers,
+ *   }));
+ *   await releasePayment({ amount: 48200, beneficiary: "…", approvalId: "APR-1", approvers: ["a", "b"] });
+ *
+ * Every call is authorized against policy and sealed into a CooL receipt BEFORE
+ * the tool runs, then its result is sealed under the same execution id. If
+ * ProofLane cannot seal the authorization, the tool never runs.
+ *
+ * Framework-free: works with OpenAI / Anthropic tool calls, LangChain tools, MCP
+ * handlers — anything that is an async function.
+ */
+import type { ReceiptV2 } from "cool-nwc";
+/** Plaintext the caller keeps. ProofLane receipts only carry its commitments. */
+export type Vault = {
+    input?: string;
+    output?: string;
+    state?: string;
+};
+export type ProofLaneOptions = {
+    apiKey: string;
+    /** Name of the agent recorded in every receipt. */
+    agent: string;
+    baseUrl?: string;
+    software?: {
+        name: string;
+        version: string;
+    };
+    /** Called with each sealed receipt and the plaintext it commits to — store the vault to answer disclosure requests later. */
+    onReceipt?: (receipt: ReceiptV2, vault: Vault) => void;
+};
+export type PolicyDecision = {
+    decision: string;
+    rule: string | null;
+    policy_hash: string;
+};
+export declare class ProofLaneBlockedError extends Error {
+    readonly decision: PolicyDecision;
+    readonly receipt: ReceiptV2;
+    constructor(decision: PolicyDecision, receipt: ReceiptV2);
+}
+export declare class ProofLane {
+    private readonly options;
+    constructor(options: ProofLaneOptions);
+    request<T>(path: string, body?: unknown): Promise<T>;
+    /** Wrap a tool. No receipt, no action. */
+    guard<A extends {
+        amount: number;
+    }, R>(action: "payment.release", tool: (args: A) => Promise<R>, approval: (args: A) => {
+        id: string;
+        approvers: string[];
+    }): (args: A) => Promise<R>;
+    /** Open one committed field for an auditor. The server checks it against the sealed commitment. */
+    approveDisclosure(requestId: string, value: string): Promise<unknown>;
+    denyDisclosure(requestId: string): Promise<unknown>;
+    /** Create an evidence-room link for an auditor. */
+    share(label: string, recordIds?: string[]): Promise<{
+        share: {
+            token: string;
+        };
+    }>;
+}

package/dist/index.js

@@ -0,0 +1,72 @@
+export class ProofLaneBlockedError extends Error {
+    decision;
+    receipt;
+    constructor(decision, receipt) {
+        super(`ProofLane blocked the action: ${decision.decision} (${decision.rule ?? "no rule matched"})`);
+        this.decision = decision;
+        this.receipt = receipt;
+        this.name = "ProofLaneBlockedError";
+    }
+}
+export class ProofLane {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async request(path, body) {
+        const res = await fetch(`${this.options.baseUrl ?? "https://prooflane-mvp.vercel.app"}${path}`, {
+            method: body === undefined ? "GET" : "POST",
+            headers: {
+                authorization: `Bearer ${this.options.apiKey}`,
+                "content-type": "application/json",
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const data = await res.json();
+        if (!res.ok)
+            throw new Error(`ProofLane ${res.status}: ${data.error}`);
+        return data;
+    }
+    /** Wrap a tool. No receipt, no action. */
+    guard(action, tool, approval) {
+        return async (args) => {
+            const input = JSON.stringify(args);
+            const appr = approval(args);
+            const auth = await this.request("/api/v1/actions/authorize", {
+                action,
+                agent: this.options.agent,
+                software: this.options.software,
+                input,
+                approval: appr,
+            });
+            this.options.onReceipt?.(auth.receipt, { input, state: appr.id });
+            if (!auth.allowed)
+                throw new ProofLaneBlockedError(auth.decision, auth.receipt);
+            const finish = async (output, status) => {
+                const done = await this.request(`/api/v1/actions/${auth.executionId}/complete`, { output, status });
+                this.options.onReceipt?.(done.receipt, { output });
+            };
+            let result;
+            try {
+                result = await tool(args);
+            }
+            catch (error) {
+                await finish(JSON.stringify({ error: String(error) }), "failed");
+                throw error;
+            }
+            await finish(JSON.stringify(result ?? null), "succeeded");
+            return result;
+        };
+    }
+    /** Open one committed field for an auditor. The server checks it against the sealed commitment. */
+    approveDisclosure(requestId, value) {
+        return this.request(`/api/v1/disclosure-requests/${requestId}`, { decision: "approve", value });
+    }
+    denyDisclosure(requestId) {
+        return this.request(`/api/v1/disclosure-requests/${requestId}`, { decision: "deny" });
+    }
+    /** Create an evidence-room link for an auditor. */
+    share(label, recordIds) {
+        return this.request("/api/v1/shares", { label, record_ids: recordIds });
+    }
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "prooflane-sdk",
+  "version": "0.1.0",
+  "description": "Evidence gateway for AI agents: policy-check and seal every consequential tool call into a verifiable CooL receipt.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist"],
+  "engines": { "node": ">=20" },
+  "repository": { "type": "git", "url": "git+https://github.com/charansaiponnada/prooflane-mvp.git", "directory": "packages/sdk" },
+  "homepage": "https://prooflane-mvp.vercel.app",
+  "keywords": ["ai-agents", "audit", "evidence", "policy", "receipts", "cool-nwc"],
+  "scripts": { "build": "tsc", "prepublishOnly": "npm run build" },
+  "dependencies": { "cool-nwc": "^3.0.0" },
+  "devDependencies": { "typescript": "^5" }
+}