@agent-custody/receipts 0.1.0

package/dist/config.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+const FactSchema = z.object({
+    /** key under context.facts */
+    name: z.string().min(1),
+    /** upstream tool the gateway calls to obtain the fact */
+    tool: z.string().min(1),
+    /** argument template; values of the form "$args.<key>" are taken from the intercepted call */
+    args: z.record(z.string(), z.string()),
+    /** which intercepted tools trigger this lookup */
+    forTools: z.array(z.string().min(1)).min(1),
+});
+export const GatewayConfigSchema = z.object({
+    identity: z.object({ keyFile: z.string() }),
+    upstream: z.object({
+        command: z.string(),
+        args: z.array(z.string()).default([]),
+        env: z.record(z.string(), z.string()).optional(),
+    }),
+    grantFile: z.string(),
+    trustedPrincipalKeys: z.array(z.string()).min(1),
+    policyFile: z.string(),
+    facts: z.array(FactSchema).default([]),
+    receiptsDir: z.string(),
+    logFile: z.string(),
+});
+/** Loads a config file and resolves every path relative to the file's directory. */
+export function loadConfig(path) {
+    const cfg = GatewayConfigSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+    const base = dirname(resolve(path));
+    const r = (p) => resolve(base, p);
+    return {
+        ...cfg,
+        identity: { keyFile: r(cfg.identity.keyFile) },
+        grantFile: r(cfg.grantFile),
+        trustedPrincipalKeys: cfg.trustedPrincipalKeys.map(r),
+        policyFile: r(cfg.policyFile),
+        receiptsDir: r(cfg.receiptsDir),
+        logFile: r(cfg.logFile),
+    };
+}
+export const SdkConfigSchema = z.object({
+    /** identity the receipts will name; nothing checks it, so it is recorded as claimed */
+    agentId: z.string().min(1),
+    principalId: z.string().min(1).optional(),
+    identity: z.object({ keyFile: z.string() }),
+    /** optional Cedar policy; when present, wrapped tools and PreToolUse hooks can deny */
+    policyFile: z.string().optional(),
+    receiptsDir: z.string(),
+    logFile: z.string(),
+    /** free-text label of the host framework, e.g. "claude-code", "openai-agents" */
+    framework: z.string().optional(),
+});
+export function loadSdkConfig(path) {
+    const cfg = SdkConfigSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+    const base = dirname(resolve(path));
+    const r = (p) => resolve(base, p);
+    return {
+        ...cfg,
+        identity: { keyFile: r(cfg.identity.keyFile) },
+        ...(cfg.policyFile ? { policyFile: r(cfg.policyFile) } : {}),
+        receiptsDir: r(cfg.receiptsDir),
+        logFile: r(cfg.logFile),
+    };
+}

package/dist/crypto.d.ts

@@ -0,0 +1,42 @@
+import type { KeyObject } from "node:crypto";
+/** Deterministic JSON: sorted keys, no whitespace, undefined dropped. Not full RFC 8785, but stable across runs. */
+export declare function canonicalize(value: unknown): string;
+export declare function sha256Hex(data: string | Uint8Array): string;
+/** sha256 over the canonical JSON of a value. */
+export declare function digestOf(value: unknown): string;
+export interface PublicKeyRef {
+    publicKey: KeyObject;
+    keyid: string;
+}
+export interface KeyPair extends PublicKeyRef {
+    privateKey: KeyObject;
+}
+/** keyid = sha256 of the SPKI DER encoding of the public key. */
+export declare function keyidOf(publicKey: KeyObject): string;
+export declare function generateKeyPair(): KeyPair;
+/** Writes <dir>/<name>.key (PKCS8 PEM, mode 0600) and <dir>/<name>.pub (SPKI PEM). */
+export declare function writeKeyPair(kp: KeyPair, dir: string, name: string): {
+    keyFile: string;
+    pubFile: string;
+};
+export declare function loadPrivateKey(path: string): KeyPair;
+export declare function loadPublicKey(path: string): PublicKeyRef;
+export interface Envelope {
+    payloadType: string;
+    payload: string;
+    signatures: {
+        keyid: string;
+        sig: string;
+    }[];
+}
+export declare function dsseSign(payloadType: string, payloadObj: unknown, kp: KeyPair): Envelope;
+export type DsseVerifyResult = {
+    ok: true;
+    payload: unknown;
+    keyid: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** Verifies the envelope against any of the given trusted keys, matched by keyid. */
+export declare function dsseVerify(env: Envelope, trusted: PublicKeyRef[]): DsseVerifyResult;

package/dist/crypto.js

@@ -0,0 +1,92 @@
+// Hashing, Ed25519 keys, and DSSE envelopes. No third-party crypto.
+import { createHash, generateKeyPairSync, sign, verify, createPrivateKey, createPublicKey } from "node:crypto";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+/** Deterministic JSON: sorted keys, no whitespace, undefined dropped. Not full RFC 8785, but stable across runs. */
+export function canonicalize(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(v) {
+    if (Array.isArray(v))
+        return v.map(sortKeys);
+    if (v && typeof v === "object") {
+        const out = {};
+        for (const k of Object.keys(v).sort()) {
+            const x = v[k];
+            if (x !== undefined)
+                out[k] = sortKeys(x);
+        }
+        return out;
+    }
+    return v;
+}
+export function sha256Hex(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+/** sha256 over the canonical JSON of a value. */
+export function digestOf(value) {
+    return sha256Hex(canonicalize(value));
+}
+/** keyid = sha256 of the SPKI DER encoding of the public key. */
+export function keyidOf(publicKey) {
+    return sha256Hex(publicKey.export({ type: "spki", format: "der" }));
+}
+export function generateKeyPair() {
+    const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+    return { privateKey, publicKey, keyid: keyidOf(publicKey) };
+}
+/** Writes <dir>/<name>.key (PKCS8 PEM, mode 0600) and <dir>/<name>.pub (SPKI PEM). */
+export function writeKeyPair(kp, dir, name) {
+    mkdirSync(dir, { recursive: true });
+    const keyFile = join(dir, `${name}.key`);
+    const pubFile = join(dir, `${name}.pub`);
+    writeFileSync(keyFile, kp.privateKey.export({ type: "pkcs8", format: "pem" }), { mode: 0o600 });
+    writeFileSync(pubFile, kp.publicKey.export({ type: "spki", format: "pem" }));
+    return { keyFile, pubFile };
+}
+export function loadPrivateKey(path) {
+    const privateKey = createPrivateKey(readFileSync(path));
+    const publicKey = createPublicKey(privateKey);
+    return { privateKey, publicKey, keyid: keyidOf(publicKey) };
+}
+export function loadPublicKey(path) {
+    const publicKey = createPublicKey(readFileSync(path));
+    return { publicKey, keyid: keyidOf(publicKey) };
+}
+function pae(payloadType, payload) {
+    const header = `DSSEv1 ${Buffer.byteLength(payloadType)} ${payloadType} ${payload.length} `;
+    return Buffer.concat([Buffer.from(header), payload]);
+}
+export function dsseSign(payloadType, payloadObj, kp) {
+    const payload = Buffer.from(canonicalize(payloadObj));
+    const sig = sign(null, pae(payloadType, payload), kp.privateKey);
+    return {
+        payloadType,
+        payload: payload.toString("base64"),
+        signatures: [{ keyid: kp.keyid, sig: sig.toString("base64") }],
+    };
+}
+/** Verifies the envelope against any of the given trusted keys, matched by keyid. */
+export function dsseVerify(env, trusted) {
+    if (!env || typeof env.payload !== "string" || !Array.isArray(env.signatures) || env.signatures.length === 0) {
+        return { ok: false, error: "malformed envelope" };
+    }
+    const payload = Buffer.from(env.payload, "base64");
+    const data = pae(env.payloadType, payload);
+    for (const s of env.signatures) {
+        const key = trusted.find((t) => t.keyid === s.keyid);
+        if (!key)
+            continue;
+        const good = verify(null, data, key.publicKey, Buffer.from(s.sig, "base64"));
+        if (good) {
+            try {
+                return { ok: true, payload: JSON.parse(payload.toString()), keyid: s.keyid };
+            }
+            catch {
+                return { ok: false, error: "payload is not JSON" };
+            }
+        }
+        return { ok: false, error: `signature by ${s.keyid.slice(0, 12)} did not verify` };
+    }
+    return { ok: false, error: `no trusted key matches keyids [${env.signatures.map((s) => s.keyid.slice(0, 12)).join(", ")}]` };
+}

package/dist/delegation.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { type Envelope, type KeyPair, type PublicKeyRef } from "./crypto.ts";
+export declare const DELEGATION_TYPE = "application/vnd.agent-custody.delegation+json";
+export declare const DelegationSchema: z.ZodObject<{
+    version: z.ZodLiteral<"0.1">;
+    principal: z.ZodString;
+    agent: z.ZodString;
+    scopes: z.ZodArray<z.ZodString>;
+    issuedAt: z.ZodISODateTime;
+    expiresAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type Delegation = z.infer<typeof DelegationSchema>;
+export declare function createDelegation(principalKey: KeyPair, d: Delegation): Envelope;
+export type DelegationVerifyResult = {
+    ok: true;
+    delegation: Delegation;
+    keyid: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function verifyDelegation(env: Envelope, trustedPrincipals: PublicKeyRef[]): DelegationVerifyResult;
+/** True when `at` (ISO) lies inside the grant's validity window. */
+export declare function delegationValidAt(d: Delegation, at: string): boolean;

package/dist/delegation.js

@@ -0,0 +1,31 @@
+// A delegation grant: a principal signs a statement that an agent may use certain tools for a window of time.
+import { z } from "zod";
+import { dsseSign, dsseVerify } from "./crypto.js";
+export const DELEGATION_TYPE = "application/vnd.agent-custody.delegation+json";
+export const DelegationSchema = z.object({
+    version: z.literal("0.1"),
+    principal: z.string().min(1),
+    agent: z.string().min(1),
+    scopes: z.array(z.string().min(1)).min(1),
+    issuedAt: z.iso.datetime(),
+    expiresAt: z.iso.datetime(),
+});
+export function createDelegation(principalKey, d) {
+    return dsseSign(DELEGATION_TYPE, DelegationSchema.parse(d), principalKey);
+}
+export function verifyDelegation(env, trustedPrincipals) {
+    if (env.payloadType !== DELEGATION_TYPE)
+        return { ok: false, error: `unexpected payloadType ${env.payloadType}` };
+    const r = dsseVerify(env, trustedPrincipals);
+    if (!r.ok)
+        return r;
+    const parsed = DelegationSchema.safeParse(r.payload);
+    if (!parsed.success)
+        return { ok: false, error: `invalid delegation: ${parsed.error.message}` };
+    return { ok: true, delegation: parsed.data, keyid: r.keyid };
+}
+/** True when `at` (ISO) lies inside the grant's validity window. */
+export function delegationValidAt(d, at) {
+    const t = Date.parse(at);
+    return t >= Date.parse(d.issuedAt) && t <= Date.parse(d.expiresAt);
+}

package/dist/gateway.d.ts

@@ -0,0 +1,21 @@
+import { type CallToolResult, type Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { GatewayConfig } from "./config.ts";
+import { type Delegation } from "./delegation.ts";
+export declare const GATEWAY_VERSION = "0.1.0";
+export declare const RECEIPT_META_KEY = "agent-custody/receipt";
+export declare const MODEL_META_KEY = "agent-custody/model";
+export interface CallParams {
+    name: string;
+    arguments?: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+}
+export interface Gateway {
+    agentId: string;
+    delegation: Delegation;
+    listTools(): Promise<Tool[]>;
+    handleCall(params: CallParams): Promise<CallToolResult>;
+    close(): Promise<void>;
+}
+export declare function createGateway(cfg: GatewayConfig): Promise<Gateway>;
+/** Exposes the gateway as an MCP server over stdio. Everything diagnostic must go to stderr. */
+export declare function serveStdio(gw: Gateway): Promise<void>;

package/dist/gateway.js

@@ -0,0 +1,158 @@
+// The MCP gateway: sits between an agent and one upstream MCP server, enforces scope + Cedar policy,
+// and emits a signed, logged receipt for every tool call, allowed or denied.
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { digestOf, loadPrivateKey, loadPublicKey } from "./crypto.js";
+import { delegationValidAt, verifyDelegation } from "./delegation.js";
+import { createIssuer } from "./issue.js";
+import { evaluate, policyDigest } from "./policy.js";
+export const GATEWAY_VERSION = "0.1.0";
+export const RECEIPT_META_KEY = "agent-custody/receipt";
+export const MODEL_META_KEY = "agent-custody/model";
+function resolveFactArgs(template, args) {
+    const out = {};
+    for (const [k, v] of Object.entries(template)) {
+        if (v.startsWith("$args.")) {
+            const key = v.slice("$args.".length);
+            if (!(key in args))
+                throw new Error(`fact argument "${k}" needs call argument "${key}", which is missing`);
+            out[k] = args[key];
+        }
+        else {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+/** First text content item, JSON-parsed when possible. Tool results carry no signature, so this is "observed", never "attested". */
+function extractValue(result) {
+    const text = result.content.find((c) => c.type === "text");
+    if (!text || text.type !== "text")
+        return null;
+    try {
+        return JSON.parse(text.text);
+    }
+    catch {
+        return text.text;
+    }
+}
+export async function createGateway(cfg) {
+    const gatewayKey = loadPrivateKey(cfg.identity.keyFile);
+    const trusted = cfg.trustedPrincipalKeys.map(loadPublicKey);
+    const grantEnvelope = JSON.parse(readFileSync(cfg.grantFile, "utf8"));
+    const grant = verifyDelegation(grantEnvelope, trusted);
+    if (!grant.ok)
+        throw new Error(`delegation grant rejected: ${grant.error}`);
+    if (!delegationValidAt(grant.delegation, new Date().toISOString()))
+        throw new Error("delegation grant is outside its validity window");
+    const delegation = grant.delegation;
+    const principalKeyid = grant.keyid;
+    const policyText = readFileSync(cfg.policyFile, "utf8");
+    const pDigest = policyDigest(policyText);
+    const issuer = createIssuer(gatewayKey, cfg.receiptsDir, cfg.logFile);
+    const upstream = new Client({ name: "agent-custody-gateway", version: GATEWAY_VERSION });
+    await upstream.connect(new StdioClientTransport({ command: cfg.upstream.command, args: cfg.upstream.args, env: cfg.upstream.env, stderr: "inherit" }));
+    const callUpstream = async (name, args) => (await upstream.callTool({ name, arguments: args }));
+    async function gatherFacts(tool, args) {
+        const facts = {};
+        for (const f of cfg.facts.filter((f) => f.forTools.includes(tool))) {
+            const fargs = resolveFactArgs(f.args, args);
+            const result = await callUpstream(f.tool, fargs);
+            if (result.isError)
+                throw new Error(`fact "${f.name}" lookup via ${f.tool} failed: ${JSON.stringify(extractValue(result))}`);
+            facts[f.name] = { tool: f.tool, args: fargs, value: extractValue(result), resultDigest: digestOf(result), provenance: "observed" };
+        }
+        return facts;
+    }
+    async function handleCall(params) {
+        const tool = params.name;
+        const args = params.arguments ?? {};
+        const receiptId = randomUUID();
+        const timestamp = new Date().toISOString();
+        const modelClaim = params._meta?.[MODEL_META_KEY];
+        let facts = {};
+        let policy;
+        let execution;
+        if (!delegation.scopes.includes(tool)) {
+            policy = { decision: "deny", reasons: [], errors: [`tool "${tool}" is not in the delegation scopes`], policyDigest: pDigest };
+        }
+        else {
+            try {
+                facts = await gatherFacts(tool, args);
+                const factValues = Object.fromEntries(Object.entries(facts).map(([k, f]) => [k, f.value]));
+                policy = evaluate(policyText, {
+                    agentId: delegation.agent,
+                    tool,
+                    context: { args, facts: factValues, grant: { principal: delegation.principal, scopes: delegation.scopes } },
+                });
+            }
+            catch (e) {
+                policy = { decision: "deny", reasons: [], errors: [String(e instanceof Error ? e.message : e)], policyDigest: pDigest };
+            }
+        }
+        if (policy.decision === "allow") {
+            try {
+                const result = await callUpstream(tool, args);
+                execution = { status: result.isError ? "failed" : "executed", result, resultDigest: digestOf(result), provenance: "observed" };
+            }
+            catch (e) {
+                execution = { status: "error", error: String(e instanceof Error ? e.message : e), provenance: "observed" };
+            }
+        }
+        else {
+            execution = { status: "denied", reason: [...policy.reasons, ...policy.errors].join("; ") || "no permit policy matched", provenance: "observed" };
+        }
+        issuer.issue({
+            receiptId,
+            timestamp,
+            issuer: { kind: "gateway", keyid: issuer.keyid, version: GATEWAY_VERSION },
+            principal: { id: delegation.principal, keyid: principalKeyid, provenance: "attested" },
+            agent: { id: delegation.agent, provenance: "attested" },
+            delegation: { envelope: grantEnvelope, provenance: "attested" },
+            session: { id: null, toolUseId: null, provenance: "claimed" },
+            model: { id: typeof modelClaim === "string" ? modelClaim : null, provenance: "claimed" },
+            tool: { name: tool, provenance: "observed" },
+            request: { args, argsDigest: digestOf(args), provenance: "claimed" },
+            facts,
+            policy: { ...policy, provenance: "observed" },
+            execution,
+        });
+        const meta = { [RECEIPT_META_KEY]: receiptId };
+        const refuse = (text) => ({ isError: true, content: [{ type: "text", text: `${text} (receipt ${receiptId})` }], _meta: meta });
+        switch (execution.status) {
+            case "denied":
+                return refuse(`Denied by policy: ${execution.reason}`);
+            case "error":
+                return refuse(`Upstream error: ${execution.error}`);
+            default: {
+                const result = execution.result;
+                return { ...result, _meta: { ...result._meta, ...meta } };
+            }
+        }
+    }
+    return {
+        agentId: delegation.agent,
+        delegation,
+        async listTools() {
+            const { tools } = await upstream.listTools();
+            return tools.filter((t) => delegation.scopes.includes(t.name));
+        },
+        handleCall,
+        close: () => upstream.close(),
+    };
+}
+/** Exposes the gateway as an MCP server over stdio. Everything diagnostic must go to stderr. */
+export async function serveStdio(gw) {
+    const server = new Server({ name: "agent-custody-gateway", version: GATEWAY_VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: await gw.listTools() }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => gw.handleCall(req.params));
+    await server.connect(new StdioServerTransport());
+    await new Promise((resolve) => {
+        server.onclose = resolve;
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./config.ts";
+export * from "./crypto.ts";
+export * from "./delegation.ts";
+export * from "./gateway.ts";
+export * from "./issue.ts";
+export * from "./log.ts";
+export * from "./policy.ts";
+export * from "./receipt.ts";
+export * from "./verify.ts";
+export * from "./sdk/index.ts";

package/dist/index.js

@@ -0,0 +1,11 @@
+// Public surface of @agent-custody/receipts. Framework adapters live on subpaths, ./sdk/<framework>, because they import optional peers.
+export * from "./config.js";
+export * from "./crypto.js";
+export * from "./delegation.js";
+export * from "./gateway.js";
+export * from "./issue.js";
+export * from "./log.js";
+export * from "./policy.js";
+export * from "./receipt.js";
+export * from "./verify.js";
+export * from "./sdk/index.js";

package/dist/issue.d.ts

@@ -0,0 +1,7 @@
+import { type KeyPair } from "./crypto.ts";
+import { type ReceiptBundle, type ReceiptPredicate } from "./receipt.ts";
+export interface Issuer {
+    keyid: string;
+    issue(predicate: ReceiptPredicate): ReceiptBundle;
+}
+export declare function createIssuer(key: KeyPair, receiptsDir: string, logFile: string): Issuer;

package/dist/issue.js

@@ -0,0 +1,21 @@
+// Signing, logging and writing a receipt. Shared by every producer: the gateway and the SDK.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { canonicalize, dsseSign } from "./crypto.js";
+import { MerkleLog } from "./log.js";
+import { buildStatement, RECEIPT_TYPE, TREEHEAD_TYPE } from "./receipt.js";
+export function createIssuer(key, receiptsDir, logFile) {
+    const log = new MerkleLog(logFile);
+    mkdirSync(receiptsDir, { recursive: true });
+    return {
+        keyid: key.keyid,
+        issue(predicate) {
+            const envelope = dsseSign(RECEIPT_TYPE, buildStatement(predicate), key);
+            const entry = log.append(canonicalize(envelope));
+            const treeHead = dsseSign(TREEHEAD_TYPE, { treeSize: entry.treeSize, rootHash: entry.rootHash, timestamp: new Date().toISOString() }, key);
+            const bundle = { envelope, treeHead, inclusion: { leafIndex: entry.leafIndex, treeSize: entry.treeSize, hashes: entry.hashes } };
+            writeFileSync(join(receiptsDir, `${predicate.receiptId}.json`), JSON.stringify(bundle, null, 2));
+            return bundle;
+        },
+    };
+}

package/dist/log.d.ts

@@ -0,0 +1,23 @@
+export interface InclusionProof {
+    leafIndex: number;
+    treeSize: number;
+    hashes: string[];
+}
+export declare function leafHash(data: string): Buffer;
+export declare function rootOf(leafHashes: Buffer[], size?: number): string;
+export declare function inclusionProof(leafHashes: Buffer[], leafIndex: number, treeSize?: number): InclusionProof;
+/** RFC 9162 section 2.1.3.2 verification. Pure function: needs only the leaf hash, proof and claimed root. */
+export declare function verifyInclusion(leaf: Buffer, proof: InclusionProof, rootHex: string): boolean;
+export declare class MerkleLog {
+    private hashes;
+    private readonly file;
+    constructor(file: string);
+    get size(): number;
+    /** Appends a leaf (an opaque string, typically a canonical JSON envelope). Returns its proof against the new root. */
+    append(leaf: string): InclusionProof & {
+        rootHash: string;
+    };
+    root(size?: number): string;
+    /** Reads a log file and returns the root at the given size, for auditors holding a copy of the log. */
+    static rootFromFile(file: string, size: number): string;
+}

package/dist/log.js

@@ -0,0 +1,109 @@
+// Append-only Merkle log with RFC 6962 / RFC 9162 hashing and inclusion proofs.
+// Leaves are stored as JSONL so anyone holding the file can recompute the root.
+import { createHash } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+const h = (...parts) => {
+    const c = createHash("sha256");
+    for (const p of parts)
+        c.update(p);
+    return c.digest();
+};
+export function leafHash(data) {
+    return h(Buffer.from([0x00]), Buffer.from(data));
+}
+const nodeHash = (l, r) => h(Buffer.from([0x01]), l, r);
+/** largest power of two strictly less than n (n >= 2) */
+function split(n) {
+    let k = 1;
+    while (k * 2 < n)
+        k *= 2;
+    return k;
+}
+function mth(leaves, lo, hi) {
+    const n = hi - lo;
+    if (n === 0)
+        return createHash("sha256").digest();
+    if (n === 1)
+        return leaves[lo];
+    const k = split(n);
+    return nodeHash(mth(leaves, lo, lo + k), mth(leaves, lo + k, hi));
+}
+function path(m, leaves, lo, hi) {
+    const n = hi - lo;
+    if (n <= 1)
+        return [];
+    const k = split(n);
+    return m < k
+        ? [...path(m, leaves, lo, lo + k), mth(leaves, lo + k, hi)]
+        : [...path(m - k, leaves, lo + k, hi), mth(leaves, lo, lo + k)];
+}
+export function rootOf(leafHashes, size = leafHashes.length) {
+    return mth(leafHashes, 0, size).toString("hex");
+}
+export function inclusionProof(leafHashes, leafIndex, treeSize = leafHashes.length) {
+    if (leafIndex < 0 || leafIndex >= treeSize || treeSize > leafHashes.length)
+        throw new Error("index out of range");
+    return { leafIndex, treeSize, hashes: path(leafIndex, leafHashes, 0, treeSize).map((b) => b.toString("hex")) };
+}
+/** RFC 9162 section 2.1.3.2 verification. Pure function: needs only the leaf hash, proof and claimed root. */
+export function verifyInclusion(leaf, proof, rootHex) {
+    let fn = proof.leafIndex;
+    let sn = proof.treeSize - 1;
+    if (fn < 0 || sn < 0 || fn > sn)
+        return false;
+    let r = leaf;
+    for (const hex of proof.hashes) {
+        if (sn === 0)
+            return false;
+        const p = Buffer.from(hex, "hex");
+        if (fn % 2 === 1 || fn === sn) {
+            r = nodeHash(p, r);
+            if (fn % 2 === 0) {
+                while (fn % 2 === 0 && fn !== 0) {
+                    fn = Math.floor(fn / 2);
+                    sn = Math.floor(sn / 2);
+                }
+            }
+        }
+        else {
+            r = nodeHash(r, p);
+        }
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+    }
+    return sn === 0 && r.toString("hex") === rootHex;
+}
+export class MerkleLog {
+    hashes = [];
+    file;
+    constructor(file) {
+        this.file = file;
+        if (existsSync(file)) {
+            for (const line of readFileSync(file, "utf8").split("\n")) {
+                if (line.trim())
+                    this.hashes.push(leafHash(JSON.parse(line)));
+            }
+        }
+        else {
+            mkdirSync(dirname(file), { recursive: true });
+        }
+    }
+    get size() {
+        return this.hashes.length;
+    }
+    /** Appends a leaf (an opaque string, typically a canonical JSON envelope). Returns its proof against the new root. */
+    append(leaf) {
+        appendFileSync(this.file, JSON.stringify(leaf) + "\n");
+        this.hashes.push(leafHash(leaf));
+        const treeSize = this.hashes.length;
+        return { ...inclusionProof(this.hashes, treeSize - 1, treeSize), rootHash: rootOf(this.hashes, treeSize) };
+    }
+    root(size = this.size) {
+        return rootOf(this.hashes, size);
+    }
+    /** Reads a log file and returns the root at the given size, for auditors holding a copy of the log. */
+    static rootFromFile(file, size) {
+        return new MerkleLog(file).root(size);
+    }
+}

package/dist/policy.d.ts

@@ -0,0 +1,16 @@
+export interface PolicyDecision {
+    decision: "allow" | "deny";
+    /** ids of policies that determined the decision */
+    reasons: string[];
+    /** evaluation errors; non-empty always yields deny */
+    errors: string[];
+    policyDigest: string;
+}
+export interface PolicyRequest {
+    agentId: string;
+    tool: string;
+    /** Cedar context. Numbers must be integers; Cedar has no floats. */
+    context: Record<string, unknown>;
+}
+export declare function policyDigest(policyText: string): string;
+export declare function evaluate(policyText: string, req: PolicyRequest): PolicyDecision;