@agent-custody/receipts 0.2.0 → 0.4.0

package/dist/issue.d.ts

@@ -1,11 +1,18 @@
 import { type KeyPair } from "./crypto.ts";
 import { type LogSink } from "./log-sink.ts";
-import { type ReceiptBundle, type ReceiptPredicate } from "./receipt.ts";
+import type { ReceiptExporter } from "./otel.ts";
+import { type AuthorizationBundle, type AuthorizationPredicate, type ReceiptBundle, type ReceiptPredicate } from "./receipt.ts";
 export interface Issuer {
     keyid: string;
     log: LogSink;
     /** Signs the statement, appends it to the log, writes the bundle. Rejects if the log refuses the leaf; no bundle is written then. */
     issue(predicate: ReceiptPredicate): Promise<ReceiptBundle>;
+    /** Signs and commits an authorization before a consequential call is forwarded. Rejects if the log refuses; the caller must then not forward. */
+    authorize(predicate: AuthorizationPredicate): Promise<AuthorizationBundle>;
+}
+export interface IssuerOptions {
+    /** told about every receipt after it is written; an exporter's failure never reaches the caller */
+    exporter?: ReceiptExporter | undefined;
 }
 /** `log` is a sink, or a file path for the local log with tree heads signed by the issuer's key. */
-export declare function createIssuer(key: KeyPair, receiptsDir: string, log: string | LogSink): Issuer;
+export declare function createIssuer(key: KeyPair, receiptsDir: string, log: string | LogSink, opts?: IssuerOptions): Issuer;

package/dist/issue.js

@@ -3,9 +3,9 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { canonicalize, dsseSign } from "./crypto.js";
 import { fileLog } from "./log-sink.js";
-import { buildStatement, RECEIPT_TYPE } from "./receipt.js";
+import { buildAuthorizationStatement, buildStatement, RECEIPT_TYPE } from "./receipt.js";
 /** `log` is a sink, or a file path for the local log with tree heads signed by the issuer's key. */
-export function createIssuer(key, receiptsDir, log) {
+export function createIssuer(key, receiptsDir, log, opts = {}) {
     const sink = typeof log === "string" ? fileLog(log, key) : log;
     mkdirSync(receiptsDir, { recursive: true });
     return {
@@ -16,6 +16,17 @@ export function createIssuer(key, receiptsDir, log) {
             const entry = await sink.append(canonicalize(envelope));
             const bundle = { envelope, treeHead: entry.treeHead, inclusion: entry.inclusion };
             writeFileSync(join(receiptsDir, `${predicate.receiptId}.json`), JSON.stringify(bundle, null, 2));
+            // After the evidence, not before, and awaited so a process that exits right after issuing still exports.
+            if (opts.exporter)
+                await opts.exporter.exported(predicate, bundle).catch(() => { });
+            return bundle;
+        },
+        async authorize(predicate) {
+            const envelope = dsseSign(RECEIPT_TYPE, buildAuthorizationStatement(predicate), key);
+            const entry = await sink.append(canonicalize(envelope));
+            const bundle = { envelope, treeHead: entry.treeHead, inclusion: entry.inclusion };
+            // On disk in its own right: if the process dies between forwarding and the receipt, this is the evidence that the call was authorized and sent.
+            writeFileSync(join(receiptsDir, `${predicate.receiptId}.authorization.json`), JSON.stringify(bundle, null, 2));
             return bundle;
         },
     };

package/dist/log-sink.d.ts

@@ -17,6 +17,8 @@ export declare function fileLog(file: string, key: KeyPair): LogSink;
 export interface HttpLogOptions {
     /** sent as a bearer token; the log decides what it is worth */
     token?: string;
+    /** send only the leaf hash; the log then commits to the receipt without ever holding it. Use it for any log run by someone else. */
+    hashOnly?: boolean;
     fetch?: typeof fetch;
 }
 /** A log reached over HTTP: POST <url>/append with {leaf}, expecting a LogAppend back. */
@@ -26,6 +28,7 @@ export interface LogConfig {
     log?: {
         url: string;
         tokenEnv?: string | undefined;
+        hashOnly?: boolean | undefined;
     } | undefined;
 }
 /** The sink a config asks for: a remote log when `log` is set, otherwise the local file. */
@@ -33,6 +36,18 @@ export declare function openLog(cfg: LogConfig, key: KeyPair): LogSink;
 export interface LogServerOptions {
     /** bearer tokens accepted on append; when empty, anyone may append */
     tokens?: string[];
+    /** the id written into every tree head this log signs, so a head cannot be presented as another log's */
+    logId?: string;
+    /**
+     * More logs behind the same server, one per tenant, reached at /t/<tenant>/...: each with its own file, tokens,
+     * and id. The default log stays at the root paths. This is the shape a hosted log takes; the reference server
+     * runs it from a small JSON file.
+     */
+    tenants?: Record<string, {
+        file: string;
+        tokens?: string[];
+        logId?: string;
+    }>;
 }
 /**
  * The reference log server as a node:http request handler.

package/dist/log-sink.js

@@ -6,11 +6,11 @@
 import { timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
 import { dsseSign } from "./crypto.js";
-import { MerkleLog } from "./log.js";
+import { leafHash, MerkleLog } from "./log.js";
 import { TREEHEAD_TYPE } from "./receipt.js";
-function appendSigned(log, key, leaf) {
-    const e = log.append(leaf);
-    const head = { treeSize: e.treeSize, rootHash: e.rootHash, timestamp: new Date().toISOString() };
+function appendSigned(log, key, leaf, logId) {
+    const e = "leaf" in leaf ? log.append(leaf.leaf) : log.appendHash(leaf.leafHash);
+    const head = { treeSize: e.treeSize, rootHash: e.rootHash, timestamp: new Date().toISOString(), ...(logId ? { log: logId } : {}) };
     return { inclusion: { leafIndex: e.leafIndex, treeSize: e.treeSize, hashes: e.hashes }, treeHead: dsseSign(TREEHEAD_TYPE, head, key) };
 }
 /** A local JSONL Merkle log. Tree heads are signed with the given key, normally the issuer's own. */
@@ -20,7 +20,7 @@ export function fileLog(file, key) {
         kind: "file",
         where: file,
         async append(leaf) {
-            return appendSigned(log, key, leaf);
+            return appendSigned(log, key, { leaf });
         },
     };
 }
@@ -35,7 +35,7 @@ export function httpLog(url, opts = {}) {
             const res = await f(new URL("append", base), {
                 method: "POST",
                 headers: { "content-type": "application/json", ...(opts.token ? { authorization: `Bearer ${opts.token}` } : {}) },
-                body: JSON.stringify({ leaf }),
+                body: JSON.stringify(opts.hashOnly ? { leafHash: leafHash(leaf).toString("hex") } : { leaf }),
             });
             if (!res.ok)
                 throw new Error(`log ${url} refused the append: ${res.status} ${(await res.text()).slice(0, 200)}`);
@@ -52,7 +52,7 @@ export function openLog(cfg, key) {
         const token = cfg.log.tokenEnv ? process.env[cfg.log.tokenEnv] : undefined;
         if (cfg.log.tokenEnv && !token)
             throw new Error(`log token: environment variable ${cfg.log.tokenEnv} is not set`);
-        return httpLog(cfg.log.url, token === undefined ? {} : { token });
+        return httpLog(cfg.log.url, { ...(token === undefined ? {} : { token }), ...(cfg.log.hashOnly ? { hashOnly: true } : {}) });
     }
     if (!cfg.logFile)
         throw new Error("config needs logFile or log.url");
@@ -66,9 +66,11 @@ export function openLog(cfg, key) {
  *   GET  /head             -> {treeHead}, the current tree head signed with the log's key
  */
 export function logHandler(file, key, opts = {}) {
-    const log = new MerkleLog(file);
-    const tokens = opts.tokens ?? [];
-    const authorized = (req) => {
+    const root = { log: new MerkleLog(file), tokens: opts.tokens ?? [], logId: opts.logId };
+    const tenants = new Map();
+    for (const [name, t] of Object.entries(opts.tenants ?? {}))
+        tenants.set(name, { log: new MerkleLog(t.file), tokens: t.tokens ?? [], logId: t.logId ?? name });
+    const authorized = (req, tokens) => {
         if (tokens.length === 0)
             return true;
         const h = req.headers.authorization ?? "";
@@ -84,22 +86,33 @@ export function logHandler(file, key, opts = {}) {
             res.end(JSON.stringify(body));
         };
         const url = new URL(req.url ?? "/", "http://localhost");
+        // /t/<tenant>/<op> reaches that tenant's log; anything else is the default log.
+        const m = /^\/t\/([A-Za-z0-9_.-]+)\/(append|root|consistency|head)$/.exec(url.pathname);
+        const which = m ? tenants.get(m[1]) : root;
+        if (!which)
+            return json(404, { error: "unknown log" });
+        const { log, tokens, logId } = which;
         if (req.method === "POST" && url.pathname.endsWith("/append")) {
-            if (!authorized(req))
+            if (!authorized(req, tokens))
                 return json(401, { error: "unauthorized" });
             let body = "";
             for await (const chunk of req)
                 body += chunk;
-            let leaf;
+            let parsed;
             try {
-                leaf = JSON.parse(body).leaf;
+                parsed = JSON.parse(body);
             }
             catch {
-                return json(400, { error: "body must be JSON {leaf}" });
+                return json(400, { error: "body must be JSON {leaf} or {leafHash}" });
+            }
+            if (typeof parsed.leafHash === "string") {
+                if (!/^[0-9a-f]{64}$/.test(parsed.leafHash))
+                    return json(400, { error: "leafHash must be 64 lowercase hex characters" });
+                return json(200, appendSigned(log, key, { leafHash: parsed.leafHash }, logId));
             }
-            if (typeof leaf !== "string" || leaf.length === 0)
-                return json(400, { error: "leaf must be a non-empty string" });
-            return json(200, appendSigned(log, key, leaf));
+            if (typeof parsed.leaf !== "string" || parsed.leaf.length === 0)
+                return json(400, { error: "leaf must be a non-empty string, or send leafHash" });
+            return json(200, appendSigned(log, key, { leaf: parsed.leaf }, logId));
         }
         if (req.method === "GET" && url.pathname.endsWith("/root")) {
             const size = url.searchParams.has("size") ? Number(url.searchParams.get("size")) : log.size;
@@ -115,7 +128,7 @@ export function logHandler(file, key, opts = {}) {
             return json(200, { oldSize, newSize, hashes: log.consistencyProof(oldSize, newSize) });
         }
         if (req.method === "GET" && url.pathname.endsWith("/head")) {
-            const head = { treeSize: log.size, rootHash: log.root(), timestamp: new Date().toISOString() };
+            const head = { treeSize: log.size, rootHash: log.root(), timestamp: new Date().toISOString(), ...(logId ? { log: logId } : {}) };
             return json(200, { treeHead: dsseSign(TREEHEAD_TYPE, head, key) });
         }
         return json(404, { error: "not found" });

package/dist/log.d.ts

@@ -22,6 +22,14 @@ export declare class MerkleLog {
     append(leaf: string): InclusionProof & {
         rootHash: string;
     };
+    /**
+     * Appends a leaf by its RFC 6962 leaf hash, sha256(0x00 || leaf), as hex. The log commits to the leaf without ever
+     * holding it, which is what a log run for someone else should do: the receipt stays with its issuer.
+     */
+    appendHash(leafHashHex: string): InclusionProof & {
+        rootHash: string;
+    };
+    private pushHash;
     root(size?: number): string;
     /** Proof that this log at newSize extends its own earlier state at oldSize. */
     consistencyProof(oldSize: number, newSize?: number): string[];

package/dist/log.js

@@ -165,8 +165,9 @@ export class MerkleLog {
                 if (!line.trim())
                     continue;
                 const parsed = JSON.parse(line);
-                // A pruned leaf keeps only its hash: the tree, its roots, and every proof are unchanged; the content is gone.
-                this.hashes.push(typeof parsed === "string" ? leafHash(parsed) : Buffer.from(parsed.pruned, "hex"));
+                // A pruned leaf keeps only its hash, and a leaf appended by hash never had content here: the tree, its
+                // roots, and every proof are the same either way.
+                this.hashes.push(typeof parsed === "string" ? leafHash(parsed) : Buffer.from((parsed.pruned ?? parsed.hash), "hex"));
             }
         }
         else {
@@ -179,7 +180,20 @@ export class MerkleLog {
     /** 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));
+        return this.pushHash(leafHash(leaf));
+    }
+    /**
+     * Appends a leaf by its RFC 6962 leaf hash, sha256(0x00 || leaf), as hex. The log commits to the leaf without ever
+     * holding it, which is what a log run for someone else should do: the receipt stays with its issuer.
+     */
+    appendHash(leafHashHex) {
+        if (!/^[0-9a-f]{64}$/.test(leafHashHex))
+            throw new Error("leafHash must be 64 lowercase hex characters");
+        appendFileSync(this.file, JSON.stringify({ hash: leafHashHex }) + "\n");
+        return this.pushHash(Buffer.from(leafHashHex, "hex"));
+    }
+    pushHash(hash) {
+        this.hashes.push(hash);
         const treeSize = this.hashes.length;
         return { leafIndex: treeSize - 1, treeSize, hashes: this.tree.path(treeSize - 1, 0, treeSize).map((b) => b.toString("hex")), rootHash: this.tree.mth(0, treeSize).toString("hex") };
     }

package/dist/otel.d.ts

@@ -0,0 +1,28 @@
+import type { ReceiptBundle, ReceiptPredicate } from "./receipt.ts";
+export interface OtelConfig {
+    /** the collector's OTLP/HTTP base, e.g. http://localhost:4318; spans go to <url>/v1/traces */
+    url: string;
+    /** header name to environment variable, for collectors that need a key; a missing variable fails at startup */
+    headersEnv?: Record<string, string> | undefined;
+    /** the service.name resource attribute; default agent-custody */
+    serviceName?: string | undefined;
+}
+export interface ReceiptExporter {
+    readonly where: string;
+    /** called after a bundle is written; must not throw into the issuer */
+    exported(predicate: ReceiptPredicate, bundle: ReceiptBundle): Promise<void>;
+}
+/** The span for one receipt, as the OTLP JSON a collector accepts on /v1/traces. Exported so a test or another transport can reuse it. */
+export declare function spanFor(p: ReceiptPredicate, bundle: ReceiptBundle, serviceName: string): unknown;
+export interface OtlpOptions {
+    fetch?: typeof fetch;
+    env?: Record<string, string | undefined>;
+    /** where export failures are reported; default stderr */
+    warn?: (message: string) => void;
+}
+/** An exporter that posts each receipt's span to an OTLP/HTTP collector. Failures are reported, never thrown. */
+export declare function otlpExporter(cfg: OtelConfig, opts?: OtlpOptions): ReceiptExporter;
+/** The exporter a config asks for, or undefined. */
+export declare function openExporter(cfg: {
+    otel?: OtelConfig | undefined;
+}): ReceiptExporter | undefined;

package/dist/otel.js

@@ -0,0 +1,87 @@
+const str = (key, v) => (v === null || v === undefined ? [] : [{ key, value: { stringValue: v } }]);
+const int = (key, v) => [{ key, value: { intValue: String(v) } }];
+/** The span for one receipt, as the OTLP JSON a collector accepts on /v1/traces. Exported so a test or another transport can reuse it. */
+export function spanFor(p, bundle, serviceName) {
+    const hex = p.receiptId.replace(/-/g, "");
+    const traceId = hex.length === 32 ? hex : hex.padEnd(32, "0").slice(0, 32);
+    const start = BigInt(Date.parse(p.timestamp)) * 1000000n;
+    const end = BigInt(Date.now()) * 1000000n;
+    const status = p.execution.status;
+    const auth = p.authorization;
+    const attributes = [
+        ...str("agent_custody.receipt_id", p.receiptId),
+        ...str("agent_custody.issuer.kind", p.issuer.kind),
+        ...str("agent_custody.issuer.keyid", p.issuer.keyid),
+        ...str("agent_custody.tool", p.tool.name),
+        ...str("agent_custody.upstream", p.tool.upstream),
+        ...str("agent_custody.agent", p.agent.id),
+        ...str("agent_custody.agent.provenance", p.agent.provenance),
+        ...str("agent_custody.principal", p.principal.id),
+        ...str("agent_custody.execution.status", status),
+        ...str("agent_custody.policy.decision", p.policy?.decision),
+        ...str("agent_custody.policy.digest", p.policy?.policyDigest),
+        ...int("agent_custody.log.leaf_index", bundle.inclusion.leafIndex),
+        ...int("agent_custody.log.tree_size", bundle.inclusion.treeSize),
+        ...(auth ? int("agent_custody.authorization.leaf_index", auth.inclusion.leafIndex) : []),
+        ...int("agent_custody.consumed.count", p.consumed?.factIds.length ?? 0),
+        ...str("agent_custody.model", p.model.id),
+        ...str("agent_custody.session", p.session.id),
+    ];
+    return {
+        resourceSpans: [
+            {
+                resource: { attributes: str("service.name", serviceName) },
+                scopeSpans: [
+                    {
+                        scope: { name: "agent-custody", version: p.issuer.version },
+                        spans: [
+                            {
+                                traceId,
+                                spanId: traceId.slice(0, 16),
+                                name: `${p.tool.name}`,
+                                kind: 3, // CLIENT: the agent calling out
+                                startTimeUnixNano: start.toString(),
+                                endTimeUnixNano: (end > start ? end : start).toString(),
+                                attributes,
+                                status: status === "executed" || status === "denied" || status === "withheld" ? { code: 1 } : { code: 2, message: status === "failed" ? "the upstream reported failure" : p.execution.error ?? status },
+                            },
+                        ],
+                    },
+                ],
+            },
+        ],
+    };
+}
+/** An exporter that posts each receipt's span to an OTLP/HTTP collector. Failures are reported, never thrown. */
+export function otlpExporter(cfg, opts = {}) {
+    const f = opts.fetch ?? fetch;
+    const env = opts.env ?? process.env;
+    const warn = opts.warn ?? ((m) => console.error(m));
+    const headers = { "content-type": "application/json" };
+    for (const [header, variable] of Object.entries(cfg.headersEnv ?? {})) {
+        const v = env[variable];
+        if (!v)
+            throw new Error(`otel: environment variable ${variable} is not set`);
+        headers[header] = v;
+    }
+    const base = cfg.url.endsWith("/") ? cfg.url : `${cfg.url}/`;
+    const url = new URL("v1/traces", base);
+    const serviceName = cfg.serviceName ?? "agent-custody";
+    return {
+        where: cfg.url,
+        async exported(p, bundle) {
+            try {
+                const res = await f(url, { method: "POST", headers, body: JSON.stringify(spanFor(p, bundle, serviceName)), signal: AbortSignal.timeout(5000) });
+                if (!res.ok)
+                    warn(`agent-custody: otel export of receipt ${p.receiptId} refused by ${cfg.url}: ${res.status}`);
+            }
+            catch (e) {
+                warn(`agent-custody: otel export of receipt ${p.receiptId} failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        },
+    };
+}
+/** The exporter a config asks for, or undefined. */
+export function openExporter(cfg) {
+    return cfg.otel ? otlpExporter(cfg.otel) : undefined;
+}

package/dist/receipt.d.ts

@@ -4,6 +4,8 @@ import type { PolicyDecision } from "./policy.ts";
 import type { UpstreamEvidence } from "./upstream.ts";
 export declare const RECEIPT_TYPE = "application/vnd.in-toto+json";
 export declare const RECEIPT_PREDICATE_TYPE = "https://agent-custody.dev/receipt/v0.2";
+/** The statement a gateway commits to the log before forwarding a consequential call; the receipt for that call embeds it. */
+export declare const AUTHORIZATION_PREDICATE_TYPE = "https://agent-custody.dev/authorization/v0.1";
 export declare const TREEHEAD_TYPE = "application/vnd.agent-custody.treehead+json";
 /**
  * Provenance of a receipt field. This is the honest part of the design.
@@ -86,6 +88,13 @@ export interface ReceiptPredicate {
     policy: (PolicyDecision & {
         provenance: Provenance;
     }) | null;
+    /**
+     * Present when the tool is one the gateway treats as consequential: the authorization statement it committed to the
+     * log before forwarding the call, with that leaf's inclusion proof and tree head. A verifier checks that it names
+     * this receipt, this tool, and these arguments, and that its leaf precedes the receipt's. Without it, evidence of a
+     * side effect exists only after the side effect.
+     */
+    authorization?: AuthorizationBundle;
     execution: {
         status: "executed" | "failed";
         result: unknown;
@@ -101,8 +110,34 @@ export interface ReceiptPredicate {
         status: "error";
         error: string;
         provenance: Provenance;
+    }
+    /** the policy allowed the call but the gateway did not forward it, because the log would not commit the authorization first */
+     | {
+        status: "withheld";
+        reason: string;
+        provenance: Provenance;
     };
 }
+/** What the gateway commits before a consequential call goes out: everything the receipt will say, except the outcome. */
+export type AuthorizationPredicate = Pick<ReceiptPredicate, "receiptId" | "timestamp" | "issuer" | "principal" | "agent" | "delegation" | "tool" | "request" | "facts" | "consumed" | "policy">;
+export interface AuthorizationStatement {
+    _type: "https://in-toto.io/Statement/v1";
+    subject: {
+        name: string;
+        digest: {
+            sha256: string;
+        };
+    }[];
+    predicateType: typeof AUTHORIZATION_PREDICATE_TYPE;
+    predicate: AuthorizationPredicate;
+}
+/** The committed authorization: the same three parts as a receipt bundle. Written to `receipts/<receiptId>.authorization.json` and embedded in the receipt. */
+export interface AuthorizationBundle {
+    envelope: Envelope;
+    treeHead: Envelope;
+    inclusion: InclusionProof;
+}
+export declare function buildAuthorizationStatement(p: AuthorizationPredicate): AuthorizationStatement;
 export interface ReceiptStatement {
     _type: "https://in-toto.io/Statement/v1";
     subject: {
@@ -118,6 +153,8 @@ export interface TreeHead {
     treeSize: number;
     rootHash: string;
     timestamp: string;
+    /** which log this head belongs to, when the log serves more than one; a verifier told which log to expect checks it */
+    log?: string;
 }
 /** What gets written to disk and handed to a verifier. Self-contained apart from public keys. */
 export interface ReceiptBundle {

package/dist/receipt.js

@@ -1,6 +1,16 @@
 export const RECEIPT_TYPE = "application/vnd.in-toto+json";
 export const RECEIPT_PREDICATE_TYPE = "https://agent-custody.dev/receipt/v0.2";
+/** The statement a gateway commits to the log before forwarding a consequential call; the receipt for that call embeds it. */
+export const AUTHORIZATION_PREDICATE_TYPE = "https://agent-custody.dev/authorization/v0.1";
 export const TREEHEAD_TYPE = "application/vnd.agent-custody.treehead+json";
+export function buildAuthorizationStatement(p) {
+    return {
+        _type: "https://in-toto.io/Statement/v1",
+        subject: [{ name: `tool-call:${p.tool.name}:${p.receiptId}`, digest: { sha256: p.request.argsDigest } }],
+        predicateType: AUTHORIZATION_PREDICATE_TYPE,
+        predicate: p,
+    };
+}
 export function buildStatement(p) {
     return {
         _type: "https://in-toto.io/Statement/v1",

package/dist/rest.d.ts

@@ -0,0 +1,27 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { RestToolConfig, RestUpstreamConfig } from "./config.ts";
+/** The part of an MCP client the gateway uses, so a REST connector can stand where an MCP upstream stands. */
+export interface UpstreamClient {
+    listTools(): Promise<{
+        tools: Tool[];
+    }>;
+    callTool(params: {
+        name: string;
+        arguments?: Record<string, unknown>;
+        _meta?: Record<string, unknown>;
+    }): Promise<unknown>;
+    close(): Promise<void>;
+}
+export interface RestOptions {
+    fetch?: typeof fetch;
+    /** the environment the header secrets are read from; default process.env */
+    env?: Record<string, string | undefined>;
+}
+/** Builds the request for one tool call: path parameters substituted, the rest of the arguments as query or body. */
+export declare function buildRequest(base: string, tool: RestToolConfig, args: Record<string, unknown>): {
+    url: URL;
+    method: string;
+    body: string | null;
+};
+/** A REST API as an upstream. Tools are what the config declares; credentials come from the environment at startup, never from the agent. */
+export declare function restUpstream(name: string, cfg: RestUpstreamConfig, opts?: RestOptions): UpstreamClient;

package/dist/rest.js

@@ -0,0 +1,52 @@
+const encode = (v) => encodeURIComponent(typeof v === "string" ? v : JSON.stringify(v));
+/** Builds the request for one tool call: path parameters substituted, the rest of the arguments as query or body. */
+export function buildRequest(base, tool, args) {
+    const rest = { ...args };
+    const path = tool.path.replace(/\{([A-Za-z0-9_]+)\}/g, (_, name) => {
+        if (!(name in rest) || rest[name] === undefined)
+            throw new Error(`tool ${tool.name}: path needs argument "${name}", which is missing`);
+        const v = rest[name];
+        delete rest[name];
+        return encode(v);
+    });
+    const url = new URL(path.replace(/^\//, ""), base.endsWith("/") ? base : `${base}/`);
+    const method = tool.method;
+    const queryNames = tool.query ?? (method === "GET" || method === "DELETE" ? Object.keys(rest) : []);
+    for (const name of queryNames) {
+        if (rest[name] === undefined)
+            continue;
+        url.searchParams.set(name, typeof rest[name] === "string" ? rest[name] : JSON.stringify(rest[name]));
+        delete rest[name];
+    }
+    const body = method === "GET" || method === "DELETE" || tool.body === "none" ? null : JSON.stringify(rest);
+    return { url, method, body };
+}
+/** A REST API as an upstream. Tools are what the config declares; credentials come from the environment at startup, never from the agent. */
+export function restUpstream(name, cfg, opts = {}) {
+    const f = opts.fetch ?? fetch;
+    const env = opts.env ?? process.env;
+    const headers = { ...(cfg.headers ?? {}) };
+    for (const [header, variable] of Object.entries(cfg.headerEnv ?? {})) {
+        const v = env[variable];
+        if (!v)
+            throw new Error(`upstream ${name}: environment variable ${variable} is not set`);
+        headers[header] = v;
+    }
+    const tools = new Map(cfg.tools.map((t) => [t.name, t]));
+    return {
+        async listTools() {
+            return { tools: cfg.tools.map((t) => ({ name: t.name, description: t.description ?? `${t.method} ${t.path}`, inputSchema: t.inputSchema })) };
+        },
+        async callTool(params) {
+            const tool = tools.get(params.name);
+            if (!tool)
+                throw new Error(`upstream ${name} has no tool "${params.name}"`);
+            const { url, method, body } = buildRequest(cfg.baseUrl, tool, params.arguments ?? {});
+            const res = await f(url, { method, headers: { accept: "application/json", ...(body !== null ? { "content-type": "application/json" } : {}), ...headers }, ...(body !== null ? { body } : {}), signal: AbortSignal.timeout(cfg.timeoutMs) });
+            const text = await res.text();
+            // The result is what the API returned, as text. JSON stays JSON so policy facts and consumers can read it.
+            return { content: [{ type: "text", text: text.length ? text : JSON.stringify({ status: res.status }) }], ...(res.ok ? {} : { isError: true }) };
+        },
+        async close() { },
+    };
+}

package/dist/sdk/index.js

@@ -4,6 +4,7 @@ import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { digestOf, loadPrivateKey } from "../crypto.js";
 import { createIssuer } from "../issue.js";
+import { openExporter } from "../otel.js";
 import { openLog } from "../log-sink.js";
 import { evaluate } from "../policy.js";
 export const SDK_VERSION = "0.1.0";
@@ -21,7 +22,7 @@ export class PolicyDeniedError extends Error {
 }
 export function createSdkIssuer(cfg) {
     const key = loadPrivateKey(cfg.identity.keyFile);
-    const issuer = createIssuer(key, cfg.receiptsDir, openLog(cfg, key));
+    const issuer = createIssuer(key, cfg.receiptsDir, openLog(cfg, key), { exporter: openExporter(cfg) });
     const policyText = cfg.policyFile ? readFileSync(cfg.policyFile, "utf8") : null;
     const decide = (ev) => policyText === null ? null : evaluate(policyText, { agentId: cfg.agentId, tool: ev.tool, context: { args: ev.args, facts: {} } });
     function record(ev, outcome, policy = null) {

package/dist/verify.d.ts

@@ -18,6 +18,8 @@ export interface VerifyOptions {
     providerSecrets?: ProviderSecrets;
     /** If given, the root is recomputed from this log file at the receipt's tree size and compared. */
     logFile?: string;
+    /** If given, every tree head in the bundle must name this log, so a head from another tenant's log cannot be presented as this one's. */
+    logId?: string;
 }
 export interface VerifyResult {
     ok: boolean;
@@ -35,6 +37,6 @@ export interface AuditResult {
  * Does the newer tree head extend the older one? Both must be signed by a trusted log or issuer key, and the proof
  * must be the log's consistency proof between the two sizes. A pass means nothing in the older log was rewritten.
  */
-export declare function auditExtends(older: Envelope, newer: Envelope, proof: string[], keys: PublicKeyRef[]): AuditResult;
+export declare function auditExtends(older: Envelope, newer: Envelope, proof: string[], keys: PublicKeyRef[], logId?: string): AuditResult;
 /** Human-readable report: checks, then every field with its provenance so the reader knows what was proven vs. claimed. */
 export declare function formatReport(r: VerifyResult): string;

package/dist/verify.js

@@ -3,7 +3,7 @@ import { canonicalize, digestOf, dsseVerify } from "./crypto.js";
 import { delegationValidAt, verifyDelegation } from "./delegation.js";
 import { leafHash, MerkleLog, verifyConsistency, verifyInclusion } from "./log.js";
 import { checkProvider, checkUpstream, contentDigest, isProviderAttestation } from "./upstream.js";
-import { RECEIPT_PREDICATE_TYPE, RECEIPT_TYPE, TREEHEAD_TYPE } from "./receipt.js";
+import { AUTHORIZATION_PREDICATE_TYPE, RECEIPT_PREDICATE_TYPE, RECEIPT_TYPE, TREEHEAD_TYPE } from "./receipt.js";
 const short = (s) => s.slice(0, 12);
 export function verifyBundle(bundle, opts) {
     const checks = [];
@@ -64,11 +64,36 @@ export function verifyBundle(bundle, opts) {
         add("no policy errors on an allow", !(p.policy.decision === "allow" && p.policy.errors.length > 0));
     }
     const logKeys = opts.logKeys ?? [];
+    if (p.authorization) {
+        // The gateway says it committed this call to the log before forwarding it. Check that the committed statement is
+        // the issuer's, describes this very call, sits in the log, and sits there before the receipt does.
+        const a = p.authorization;
+        const asig = dsseVerify(a.envelope, opts.issuerKeys);
+        const ast = asig.ok ? asig.payload : null;
+        const typed = !!ast && a.envelope.payloadType === RECEIPT_TYPE && ast.predicateType === AUTHORIZATION_PREDICATE_TYPE;
+        add("authorization signature (issuer key)", asig.ok && typed && asig.keyid === sig.keyid, asig.ok ? (typed ? `keyid ${short(asig.keyid)}` : "not an authorization statement") : asig.error);
+        if (ast && typed) {
+            const ap = ast.predicate;
+            const same = ap.receiptId === p.receiptId && ap.tool.name === p.tool.name && ap.request.argsDigest === p.request.argsDigest && ap.agent.id === p.agent.id && ap.principal.id === p.principal.id && ap.policy?.decision === "allow";
+            add("authorization names this call", same, same ? `${ap.tool.name} for receipt ${short(ap.receiptId)}` : "committed for a different receipt, tool, arguments, agent, or decision");
+            const ath = dsseVerify(a.treeHead, [...logKeys, ...opts.issuerKeys]);
+            add("authorization tree head signature", ath.ok && a.treeHead.payloadType === TREEHEAD_TYPE, ath.ok ? `keyid ${short(ath.keyid)}` : ath.error);
+            if (ath.ok) {
+                const ahead = ath.payload;
+                const included = ahead.treeSize === a.inclusion.treeSize && verifyInclusion(leafHash(canonicalize(a.envelope)), a.inclusion, ahead.rootHash);
+                add("authorization log inclusion proof", included, `leaf ${a.inclusion.leafIndex} of ${a.inclusion.treeSize}`);
+                const before = a.inclusion.leafIndex < bundle.inclusion.leafIndex && a.inclusion.treeSize <= bundle.inclusion.treeSize;
+                add("authorization logged before execution", before, `authorization leaf ${a.inclusion.leafIndex}, receipt leaf ${bundle.inclusion.leafIndex}`);
+            }
+        }
+    }
     const th = dsseVerify(bundle.treeHead, [...logKeys, ...opts.issuerKeys]);
     const byLog = th.ok && logKeys.some((k) => k.keyid === th.keyid);
     add("tree head signature", th.ok && bundle.treeHead.payloadType === TREEHEAD_TYPE, th.ok ? `${byLog ? "log key" : "issuer key"} ${short(th.keyid)}` : th.error);
     if (th.ok) {
         const head = th.payload;
+        if (opts.logId !== undefined)
+            add("tree head names the expected log", head.log === opts.logId, head.log ? `log ${head.log}` : "tree head names no log");
         add("tree head matches inclusion proof size", head.treeSize === bundle.inclusion.treeSize);
         const included = verifyInclusion(leafHash(canonicalize(bundle.envelope)), bundle.inclusion, head.rootHash);
         add("log inclusion proof", included, `leaf ${bundle.inclusion.leafIndex} of ${bundle.inclusion.treeSize}, root ${short(head.rootHash)}`);
@@ -90,7 +115,7 @@ export function verifyBundle(bundle, opts) {
  * Does the newer tree head extend the older one? Both must be signed by a trusted log or issuer key, and the proof
  * must be the log's consistency proof between the two sizes. A pass means nothing in the older log was rewritten.
  */
-export function auditExtends(older, newer, proof, keys) {
+export function auditExtends(older, newer, proof, keys, logId) {
     const checks = [];
     const add = (name, ok, detail) => {
         checks.push(detail === undefined ? { name, ok } : { name, ok, detail });
@@ -105,6 +130,10 @@ export function auditExtends(older, newer, proof, keys) {
     const b = decode("newer", newer);
     if (!a || !b)
         return { ok: false, checks, older: a, newer: b };
+    if (logId !== undefined)
+        add("both tree heads name the expected log", a.log === logId && b.log === logId, `expected ${logId}, got ${a.log ?? "none"} and ${b.log ?? "none"}`);
+    else if (a.log !== b.log)
+        add("both tree heads name the same log", false, `${a.log ?? "none"} and ${b.log ?? "none"}`);
     if (!add("older is not larger than newer", a.treeSize <= b.treeSize, `${a.treeSize} -> ${b.treeSize}`))
         return { ok: false, checks, older: a, newer: b };
     const consistent = verifyConsistency(a.treeSize, a.rootHash, b.treeSize, b.rootHash, proof);
@@ -145,6 +174,12 @@ export function formatReport(r) {
         row("policy", "-", "(none evaluated)");
     if (p.consumed)
         row("consumed", p.consumed.provenance, p.consumed.factIds.length === 0 ? "(no facts shown before this call)" : p.consumed.factIds);
+    if (p.authorization) {
+        const committed = r.checks.filter((c) => c.name.startsWith("authorization ")).every((c) => c.ok);
+        row("authorization", "observed", committed ? `committed to the log as leaf ${p.authorization.inclusion.leafIndex}, before the call was forwarded` : "carried, but its checks FAILED");
+    }
+    else if (p.execution.status === "withheld")
+        row("authorization", "observed", "the log would not commit it; the call was not forwarded");
     const upstreamCheck = r.checks.find((c) => c.name === "upstream signature (upstream key)" || c.name === "upstream signature (provider secret)");
     const hasUpstream = (p.execution.status === "executed" || p.execution.status === "failed") && !!p.execution.upstream;
     const byProvider = hasUpstream && isProviderAttestation(p.execution.upstream);