@agent-custody/receipts 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # agent-custody
 
-Chain of custody for AI agents: signed, independently verifiable receipts for every tool call.
+Chain of custody for AI agents: a signed receipt for every tool call, checkable with public keys alone. What each check proves, and against whom, is [a table below](#what-a-receipt-proves-and-what-it-does-not).
 
 Two producers, one receipt format, one verifier.
 
@@ -9,7 +9,7 @@ Two producers, one receipt format, one verifier.
 
 Anyone holding the public keys can verify a receipt offline. The agent is not trusted. The layer around it is, and the receipt says exactly how far that trust extends, starting with who issued it.
 
-- [Tutorials](docs/tutorials.md): fifteen runnable examples, one per aspect of the code, all executed by the test suite
+- [Tutorials](docs/tutorials.md): eighteen runnable examples, one per aspect of the code, all executed by the test suite
 - [Usage guide](docs/usage.md): gateway setup, wiring into Claude Desktop, Claude Code, or your own agent loop
 - [The interceptor SDK](docs/sdk.md): Claude Code hooks, the Claude Agent SDK, adapters for the OpenAI Agents SDK, Vercel AI SDK and LangChain, and wrapping tool functions in anything else
 - [Writing policies](docs/policies.md): how a tool call becomes a Cedar request, with tested examples
@@ -75,6 +75,8 @@ flowchart LR
     P -. "public key" .-> V
     G -. "public key" .-> V
     A -. "traces (unchanged)" .-> O
+    G -. "one span per receipt, OTLP" .-> O
+    S -. "one span per receipt, OTLP" .-> O
 ```
 
 Three parties hold keys. The **principal** signs a grant saying which agent may use which tools until when. The **issuer**, gateway or SDK, signs every receipt and every tree head. The **verifier** holds only public keys and needs no access to the issuer, the agent, or the upstream system.
@@ -106,6 +108,7 @@ Every receipt names its issuer, and the verifier prints what that issuer kind is
 | Python: LangChain, OpenAI Agents SDK, Claude Agent SDK | sidecar + [Python package](../python/README.md) | `wrap_tools`, `claude_hook` PreToolUse deny, `client.wrap` | `ReceiptCallbackHandler` | the real Python packages, receipts checked by this verifier |
 | Go, Java, Rust, any language with HTTP | sidecar | decide then record | record | [examples/languages](examples/languages), each run against a live sidecar |
 | any MCP host in any language: Claude Agent SDK Python, OpenAI Agents Python | gateway | yes | | the gateway is an MCP server; [usage.md](docs/usage.md#python-hosts) |
+| any REST API, as tools the agent reaches through the gateway | gateway, `rest` upstream | yes | | a stand-in HTTP API; [usage.md](docs/usage.md#setup-step-by-step) |
 
 The framework packages are optional peer dependencies. Each adapter imports only from its own package.
 
@@ -170,7 +173,7 @@ Every field carries a provenance label. This is the design decision that matters
 bun install                              # from the repository root, once for the workspace
 cd packages/receipts
 node scripts/demo.ts                     # gateway: keys, grant, policy, four tool calls, verification, a tampering attempt; then the SDK wrapping the same tool
-node examples/01-keys-and-signing.ts     # first of fifteen step-by-step examples, see docs/tutorials.md
+node examples/01-keys-and-signing.ts     # first of eighteen step-by-step examples, see docs/tutorials.md
 bun run test                             # this package; `bun run test` at the root runs every package
 ```
 
@@ -208,7 +211,8 @@ const refund = issuer.wrap("stripe.refund", async (args: { amount: number }) =>
 | the principal really delegated this scope to this agent | anyone with the principal's key | operator, agent | grant signed by principal key, checked for scope and validity window | done |
 | the policy decision was made against this exact policy | anyone | operator swapping policies | sha256 of policy text in the receipt | done |
 | facts the policy relied on were not asserted by the agent | anyone reading the receipt | agent | facts fetched by the gateway, recorded with their own digests, labelled `observed` | done |
-| the upstream system actually executed the action | third party | operator | needs the upstream's own signed response embedded verbatim | **not done**, depends on the tool provider |
+| the side effect was committed to the log before it happened | anyone with a log copy | operator, log outage | for tools in `precommit`, a signed authorization logged first, embedded in the receipt with its leaf position, checked to precede the receipt | done |
+| the upstream system actually executed the action | anyone with the upstream's key or the provider's secret | operator | the upstream signs its result for the receipt, or the provider's own delivery signature (Stripe, GitHub) is embedded and checked | done, for upstreams that sign |
 | the operator itself cannot mint a false receipt | regulator, counterparty | operator | needs a TEE-hosted signer or a federated log | **not done** |
 | which model produced the call | anyone | operator | no hosted provider signs model identity | **not possible today**, labelled `claimed` |
 | an SDK receipt reflects what the tool really did | anyone | agent's own process | none; the SDK shares a process with the agent | **by design not claimed**; issuer kind `sdk` says so |
@@ -224,13 +228,15 @@ src/log.ts         Merkle log: append, root, inclusion and consistency proofs, v
 src/log-sink.ts    where leaves go: the local file, or a remote log over HTTP; plus the reference log server
 src/policy.ts      Cedar evaluation wrapper, fail-closed
 src/delegation.ts  signed delegation grants
-src/receipt.ts     receipt statement types and provenance labels
-src/issue.ts       sign, log, and write a receipt; shared by both producers
+src/receipt.ts     receipt and authorization statement types and provenance labels
+src/issue.ts       sign, log, and write a receipt, or commit an authorization first; shared by both producers
 src/gateway.ts     the MCP proxy: scope check, facts, policy, forward, receipt
 src/sdk/index.ts   the interceptor: policy decision, record, wrap(tool fn)
 src/sdk/claude.ts  Claude Code command hook and Claude Agent SDK in-process hooks
 src/sdk/openai-agents.ts, vercel-ai.ts, langchain.ts   framework adapters, tested against the real packages
 src/sidecar.ts     the SDK issuer behind a local HTTP API, for agents in other languages
+src/otel.ts        OpenTelemetry export: one OTLP/HTTP span per receipt, after the receipt, no SDK dependency
+src/rest.ts        the REST connector: an HTTP API described as tools, standing where an MCP upstream stands
 src/upstream.ts    attested execution: an upstream signs its result for the receipt; the verifier checks it with the upstream key
 vectors/           conformance vectors: receipts, keys, logs, proofs, and expected verdicts; `bun run vectors` regenerates them
 src/verify.ts      offline verification, the human-readable report, and the audit that a later log extends an earlier one
@@ -239,7 +245,7 @@ src/retention.ts   pruning the log: leaves become their hashes, bundles are remo
 src/index.ts       the package's public surface; adapters are exported on ./sdk/<framework> subpaths
 tsconfig.build.json  emits dist/ (JavaScript plus declarations) for consumers; the repo itself runs the .ts directly
 scripts/           fake Stripe upstream (signs its results with --key), a second fake upstream, fixture builders for gateway and SDK, demo
-examples/          fifteen runnable tutorials, plus examples/languages/: Python, Go, Java, and Rust clients of the sidecar, run by the test suite, one per aspect; each is run by the test suite
+examples/          eighteen runnable tutorials, plus examples/languages/: Python, Go, Java, and Rust clients of the sidecar, run by the test suite, one per aspect; each is run by the test suite
 test/              unit tests per module, end-to-end gateway test, SDK and hook tests,
                    adapter tests against the real packages, and a test that runs every policy in docs/policies.md
 docs/              tutorials, usage (gateway), sdk, policies, verification
@@ -271,12 +277,18 @@ The design is two producers feeding one verifier. The SDK is the top of the funn
 - Remote log: the issuer can append to a log run by someone else over HTTP, whose key then signs the tree heads, so a verifier learns the receipt was in a log the operator could not rewrite. Includes the reference log server, bearer-token auth, and a root endpoint for auditors.
 - Framework adapters, each tested against the real package with a scripted model and no network: OpenAI Agents SDK (`wrapTools` enforces, `observeRunner` records from lifecycle events), Vercel AI SDK (`wrapTools` over a real `generateText` loop), LangChain (`ReceiptCallbackHandler` records, `issuer.wrap` enforces).
 
+- A log for someone else: `hashOnly` sends leaf hashes so the log never holds a receipt; the reference server runs several tenant logs at `/t/<tenant>/` with their own tokens and ids; tree heads name their log and the verifier checks it with `--log-id`. Phase 1 of the hosted log, [issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6).
+- OpenTelemetry export: with `otel` in either config, every receipt is also one span at the collector the team already runs, trace id equal to the receipt id, attributes for tool, agent, principal, status, decision, and log position; after the receipt, best effort, never on the evidence path.
+- The REST connector: a plain HTTP API described as tools in the gateway config, credentials from the environment, so an agent's direct API calls become receipted, policy-checked tool calls through the gateway.
+- Pre-commit authorization for consequential tools: named in `precommit`, a call is signed and logged before it is forwarded, withheld if the log will not take it, and its receipt carries the committed authorization with proof that it precedes the execution.
+
 **Next, in the order it pays off**
 
-1. OpenTelemetry export: emit each receipt as a span with the receipt id and issuer kind as attributes, so existing collectors and dashboards carry them without a new pipeline.
-2. An HTTP transport for the gateway, with the grant presented per connection, for a shared deployment rather than one process per agent session.
-3. Delegation chains for sub-agents.
-4. Receiver-attested receipts for agent-to-agent calls.
-5. A TEE-hosted signer, then SD-JWT redaction, then ZK proofs of policy compliance. Not before.
+1. The hosted log, [issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6), phases 2 and 3: the Postgres store with one writer per tenant, tokens and rate limits, the signer as its own process, published checkpoints, and well-known keys fetched with `--log-url`. Phase 1 is done; it comes before everything below.
+2. Post-quantum signatures: ML-DSA beside Ed25519 in the same DSSE envelope, hybrid by default when a PQ key is present, in every signed artefact and in the browser verifier. [Issue #11](https://github.com/ch4r10t33r/agent-custody/issues/11).
+3. An HTTP transport for the gateway, with the grant presented per connection, for a shared deployment rather than one process per agent session.
+4. Delegation chains for sub-agents.
+5. Receiver-attested receipts for agent-to-agent calls.
+6. A TEE-hosted signer, then SD-JWT redaction, then ZK proofs of policy compliance. Not before.
 
 A Python SDK follows the same shape once the TypeScript adapters have settled.

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { parseArgs } from "node:util";
 import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import { loadConfig, loadSdkConfig } from "./config.js";
 import { generateKeyPair, loadPrivateKey, loadPublicKey, writeKeyPair } from "./crypto.js";
 import { createDelegation } from "./delegation.js";
@@ -29,10 +30,24 @@ const USAGE = `agent-custody <command>
   prune   --log <log.jsonl> --before <ISO instant> [--receipts <dir>]
           retention on the receipt log: replaces older leaves with their hashes, so proofs still verify and the content is gone
   log     --file <log.jsonl> --key <log.key> [--port 8787] [--host 127.0.0.1] [--token-env <NAME>]   reference log server
-  verify  <bundle.json> --issuer-key <pub> [--principal-key <pub>] [--log-key <pub>] [--upstream-key <pub>] [--stripe-secret-env NAME] [--github-secret-env NAME] [--log <log.jsonl>] [--json]
-  audit   --older <bundle.json> --newer <bundle.json> (--log <log.jsonl> | --log-url <url>) --issuer-key <pub> [--log-key <pub>] [--json]
+  verify  <bundle.json> --issuer-key <pub> [--principal-key <pub>] [--log-key <pub>] [--log-id <id>] [--upstream-key <pub>] [--stripe-secret-env NAME] [--github-secret-env NAME] [--log <log.jsonl>] [--json]
+  audit   --older <bundle.json> --newer <bundle.json> (--log <log.jsonl> | --log-url <url>) --issuer-key <pub> [--log-key <pub>] [--log-id <id>] [--json]
           checks that the newer receipt's log extends the older one's: nothing between them was rewritten
 `;
+/** The tenants file for `log --tenants`: paths relative to the file, tokens from the environment, ids default to the tenant name. */
+function loadTenants(path) {
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    const out = {};
+    for (const [name, t] of Object.entries(raw)) {
+        if (!/^[A-Za-z0-9_.-]+$/.test(name) || typeof t?.file !== "string")
+            throw new Error(`tenants: "${name}" needs a file, and its name must be a plain identifier`);
+        const token = t.tokenEnv ? process.env[t.tokenEnv] : undefined;
+        if (t.tokenEnv && !token)
+            throw new Error(`tenants: environment variable ${t.tokenEnv} for "${name}" is not set`);
+        out[name] = { file: resolve(dirname(resolve(path)), t.file), ...(token ? { tokens: [token] } : {}), ...(t.logId ? { logId: t.logId } : {}) };
+    }
+    return out;
+}
 async function main(argv) {
     const [cmd, ...rest] = argv;
     switch (cmd) {
@@ -116,7 +131,7 @@ async function main(argv) {
         case "log": {
             const { values } = parseArgs({
                 args: rest,
-                options: { file: { type: "string" }, key: { type: "string" }, port: { type: "string", default: "8787" }, host: { type: "string", default: "127.0.0.1" }, "token-env": { type: "string" } },
+                options: { file: { type: "string" }, key: { type: "string" }, port: { type: "string", default: "8787" }, host: { type: "string", default: "127.0.0.1" }, "token-env": { type: "string" }, "log-id": { type: "string" }, tenants: { type: "string" } },
             });
             if (!values.file || !values.key)
                 throw new Error("log needs --file and --key");
@@ -124,8 +139,10 @@ async function main(argv) {
             if (values["token-env"] && !token)
                 throw new Error(`log: environment variable ${values["token-env"]} is not set`);
             const key = loadPrivateKey(values.key);
-            const running = await serveLog(values.file, key, { port: Number(values.port), host: values.host, ...(token ? { tokens: [token] } : {}) });
-            console.error(`agent-custody log: ${running.url} keyid=${key.keyid} file=${values.file} ${token ? "bearer token required" : "open, anyone may append"}`);
+            // --tenants names a JSON file { "<tenant>": { "file": "...", "tokenEnv": "NAME", "logId": "..." } }; each is reached at /t/<tenant>/.
+            const tenants = values.tenants ? loadTenants(values.tenants) : undefined;
+            const running = await serveLog(values.file, key, { port: Number(values.port), host: values.host, ...(token ? { tokens: [token] } : {}), ...(values["log-id"] ? { logId: values["log-id"] } : {}), ...(tenants ? { tenants } : {}) });
+            console.error(`agent-custody log: ${running.url} keyid=${key.keyid} file=${values.file}${values["log-id"] ? ` log=${values["log-id"]}` : ""} ${token ? "bearer token required" : "open, anyone may append"}${tenants ? ` tenants=${Object.keys(tenants).join(",")}` : ""}`);
             await new Promise((resolve) => process.once("SIGINT", resolve));
             await running.close();
             return 0;
@@ -139,6 +156,7 @@ async function main(argv) {
                     "gateway-key": { type: "string", multiple: true },
                     "principal-key": { type: "string", multiple: true },
                     "log-key": { type: "string", multiple: true },
+                    "log-id": { type: "string" },
                     "upstream-key": { type: "string", multiple: true },
                     "stripe-secret-env": { type: "string" },
                     "github-secret-env": { type: "string" },
@@ -155,6 +173,7 @@ async function main(argv) {
                 issuerKeys: issuerKeyFiles.map(loadPublicKey),
                 principalKeys: (values["principal-key"] ?? []).map(loadPublicKey),
                 ...(values["log-key"] ? { logKeys: values["log-key"].map(loadPublicKey) } : {}),
+                ...(values["log-id"] ? { logId: values["log-id"] } : {}),
                 ...(values["upstream-key"] ? { upstreamKeys: values["upstream-key"].map(loadPublicKey) } : {}),
                 ...(values["stripe-secret-env"] || values["github-secret-env"] ? { providerSecrets: { ...(values["stripe-secret-env"] ? { stripe: secretFrom(values["stripe-secret-env"]) } : {}), ...(values["github-secret-env"] ? { github: secretFrom(values["github-secret-env"]) } : {}) } } : {}),
                 ...(values.log ? { logFile: values.log } : {}),
@@ -172,6 +191,7 @@ async function main(argv) {
                     "log-url": { type: "string" },
                     "issuer-key": { type: "string", multiple: true },
                     "log-key": { type: "string", multiple: true },
+                    "log-id": { type: "string" },
                     json: { type: "boolean", default: false },
                 },
             });
@@ -193,7 +213,7 @@ async function main(argv) {
                     throw new Error(`log refused the consistency query: ${res.status}`);
                 proof = (await res.json()).hashes;
             }
-            const result = auditExtends(older, newer, proof, keyFiles.map(loadPublicKey));
+            const result = auditExtends(older, newer, proof, keyFiles.map(loadPublicKey), values["log-id"]);
             if (values.json)
                 console.log(JSON.stringify(result, null, 2));
             else {

package/dist/config.d.ts

@@ -1,4 +1,50 @@
 import { z } from "zod";
+/** One REST endpoint offered to the agent as a tool. `{name}` segments in the path come from the call's arguments; the rest go to the query on GET and DELETE, or to a JSON body otherwise. */
+declare const RestToolSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    method: z.ZodDefault<z.ZodEnum<{
+        DELETE: "DELETE";
+        GET: "GET";
+        PATCH: "PATCH";
+        POST: "POST";
+        PUT: "PUT";
+    }>>;
+    path: z.ZodString;
+    query: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    body: z.ZodDefault<z.ZodEnum<{
+        json: "json";
+        none: "none";
+    }>>;
+    inputSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type RestToolConfig = z.infer<typeof RestToolSchema>;
+/** A plain HTTP API as an upstream: no MCP server needed. Secrets come from the environment through headerEnv, never from the file or the agent. */
+declare const RestUpstreamSchema: z.ZodObject<{
+    baseUrl: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    headerEnv: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        method: z.ZodDefault<z.ZodEnum<{
+            DELETE: "DELETE";
+            GET: "GET";
+            PATCH: "PATCH";
+            POST: "POST";
+            PUT: "PUT";
+        }>>;
+        path: z.ZodString;
+        query: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        body: z.ZodDefault<z.ZodEnum<{
+            json: "json";
+            none: "none";
+        }>>;
+        inputSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RestUpstreamConfig = z.infer<typeof RestUpstreamSchema>;
 declare const UpstreamSchema: z.ZodUnion<readonly [z.ZodObject<{
     command: z.ZodString;
     args: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -6,6 +52,31 @@ declare const UpstreamSchema: z.ZodUnion<readonly [z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     url: z.ZodString;
     tokenEnv: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    rest: z.ZodObject<{
+        baseUrl: z.ZodString;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        headerEnv: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        tools: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            method: z.ZodDefault<z.ZodEnum<{
+                DELETE: "DELETE";
+                GET: "GET";
+                PATCH: "PATCH";
+                POST: "POST";
+                PUT: "PUT";
+            }>>;
+            path: z.ZodString;
+            query: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            body: z.ZodDefault<z.ZodEnum<{
+                json: "json";
+                none: "none";
+            }>>;
+            inputSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
 }, z.core.$strip>]>;
 export type UpstreamConfig = z.infer<typeof UpstreamSchema>;
 declare const FactSchema: z.ZodObject<{
@@ -26,6 +97,31 @@ export declare const GatewayConfigSchema: z.ZodObject<{
     }, z.core.$strip>, z.ZodObject<{
         url: z.ZodString;
         tokenEnv: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        rest: z.ZodObject<{
+            baseUrl: z.ZodString;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            headerEnv: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            timeoutMs: z.ZodDefault<z.ZodNumber>;
+            tools: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+                method: z.ZodDefault<z.ZodEnum<{
+                    DELETE: "DELETE";
+                    GET: "GET";
+                    PATCH: "PATCH";
+                    POST: "POST";
+                    PUT: "PUT";
+                }>>;
+                path: z.ZodString;
+                query: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                body: z.ZodDefault<z.ZodEnum<{
+                    json: "json";
+                    none: "none";
+                }>>;
+                inputSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
     }, z.core.$strip>]>>;
     upstreams: z.ZodOptional<z.ZodArray<z.ZodIntersection<z.ZodUnion<readonly [z.ZodObject<{
         command: z.ZodString;
@@ -34,6 +130,31 @@ export declare const GatewayConfigSchema: z.ZodObject<{
     }, z.core.$strip>, z.ZodObject<{
         url: z.ZodString;
         tokenEnv: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        rest: z.ZodObject<{
+            baseUrl: z.ZodString;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            headerEnv: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            timeoutMs: z.ZodDefault<z.ZodNumber>;
+            tools: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                description: z.ZodOptional<z.ZodString>;
+                method: z.ZodDefault<z.ZodEnum<{
+                    DELETE: "DELETE";
+                    GET: "GET";
+                    PATCH: "PATCH";
+                    POST: "POST";
+                    PUT: "PUT";
+                }>>;
+                path: z.ZodString;
+                query: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                body: z.ZodDefault<z.ZodEnum<{
+                    json: "json";
+                    none: "none";
+                }>>;
+                inputSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
     }, z.core.$strip>]>, z.ZodObject<{
         name: z.ZodString;
     }, z.core.$strip>>>>;
@@ -47,11 +168,18 @@ export declare const GatewayConfigSchema: z.ZodObject<{
         forTools: z.ZodArray<z.ZodString>;
         optional: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>>;
+    precommit: z.ZodDefault<z.ZodArray<z.ZodString>>;
     receiptsDir: z.ZodString;
     logFile: z.ZodOptional<z.ZodString>;
     log: z.ZodOptional<z.ZodObject<{
         url: z.ZodString;
         tokenEnv: z.ZodOptional<z.ZodString>;
+        hashOnly: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    otel: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        headersEnv: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        serviceName: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type GatewayConfig = z.infer<typeof GatewayConfigSchema>;
@@ -70,6 +198,12 @@ export declare const SdkConfigSchema: z.ZodObject<{
     log: z.ZodOptional<z.ZodObject<{
         url: z.ZodString;
         tokenEnv: z.ZodOptional<z.ZodString>;
+        hashOnly: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    otel: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        headersEnv: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        serviceName: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     framework: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;

package/dist/config.js

@@ -2,12 +2,37 @@ import { z } from "zod";
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 /** Where receipts are logged: a local file, or a log reached over HTTP whose bearer token comes from an environment variable. */
-const LogSchema = z.object({ url: z.string().url(), tokenEnv: z.string().min(1).optional() });
+const LogSchema = z.object({ url: z.string().url(), tokenEnv: z.string().min(1).optional(), /** send leaf hashes only; the log never holds the receipt. Use it for any log run by someone else */ hashOnly: z.boolean().optional() });
 const oneLog = { message: "exactly one of logFile or log is required" };
+/** Optional OpenTelemetry export: every receipt also becomes a span at this OTLP/HTTP collector, after it is issued. Never on the evidence path. */
+const OtelSchema = z.object({ url: z.string().url(), headersEnv: z.record(z.string(), z.string().min(1)).optional(), serviceName: z.string().min(1).optional() });
 const hasOneLog = (c) => (c.logFile ? 1 : 0) + (c.log ? 1 : 0) === 1;
+/** One REST endpoint offered to the agent as a tool. `{name}` segments in the path come from the call's arguments; the rest go to the query on GET and DELETE, or to a JSON body otherwise. */
+const RestToolSchema = z.object({
+    name: z.string().min(1),
+    description: z.string().optional(),
+    method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).default("GET"),
+    path: z.string().min(1),
+    /** argument names sent as query parameters, when the default placement is not wanted */
+    query: z.array(z.string().min(1)).optional(),
+    /** "none" sends no body even on POST */
+    body: z.enum(["json", "none"]).default("json"),
+    /** the JSON Schema the agent sees; default accepts any object */
+    inputSchema: z.record(z.string(), z.unknown()).default({ type: "object" }),
+});
+/** A plain HTTP API as an upstream: no MCP server needed. Secrets come from the environment through headerEnv, never from the file or the agent. */
+const RestUpstreamSchema = z.object({
+    baseUrl: z.string().url(),
+    headers: z.record(z.string(), z.string()).optional(),
+    /** header name to environment variable, e.g. { "authorization": "STRIPE_BEARER" }; a missing variable fails at startup */
+    headerEnv: z.record(z.string(), z.string().min(1)).optional(),
+    timeoutMs: z.number().int().positive().default(30_000),
+    tools: z.array(RestToolSchema).min(1),
+});
 const UpstreamSchema = z.union([
     z.object({ command: z.string(), args: z.array(z.string()).default([]), env: z.record(z.string(), z.string()).optional() }),
     z.object({ url: z.string().url(), tokenEnv: z.string().min(1).optional() }),
+    z.object({ rest: RestUpstreamSchema }),
 ]);
 const FactSchema = z.object({
     /** key under context.facts */
@@ -23,7 +48,7 @@ const FactSchema = z.object({
 });
 export const GatewayConfigSchema = z.object({
     identity: z.object({ keyFile: z.string() }),
-    /** the upstream MCP server: a process to spawn over stdio, or a URL to reach over Streamable HTTP with an optional bearer token from the environment */
+    /** the upstream: an MCP server to spawn over stdio, an MCP URL to reach over Streamable HTTP with an optional bearer token from the environment, or a REST API described as tools */
     upstream: UpstreamSchema.optional(),
     /** several upstreams behind one gateway and one grant; each tool name must belong to exactly one of them */
     upstreams: z.array(UpstreamSchema.and(z.object({ name: z.string().min(1) }))).min(1).optional(),
@@ -31,9 +56,15 @@ export const GatewayConfigSchema = z.object({
     trustedPrincipalKeys: z.array(z.string()).min(1),
     policyFile: z.string(),
     facts: z.array(FactSchema).default([]),
+    /**
+     * Consequential tools, by name or "*" for all: before forwarding one of these, the gateway commits a signed
+     * authorization to the log and refuses the call if the log will not take it. Evidence then precedes the side effect.
+     */
+    precommit: z.array(z.string().min(1)).default([]),
     receiptsDir: z.string(),
     logFile: z.string().optional(),
     log: LogSchema.optional(),
+    otel: OtelSchema.optional(),
 }).refine(hasOneLog, oneLog).refine((c) => (c.upstream ? 1 : 0) + (c.upstreams ? 1 : 0) === 1, { message: "exactly one of upstream or upstreams is required" });
 /** Loads a config file and resolves every path relative to the file's directory. */
 export function loadConfig(path) {
@@ -60,6 +91,7 @@ export const SdkConfigSchema = z.object({
     receiptsDir: z.string(),
     logFile: z.string().optional(),
     log: LogSchema.optional(),
+    otel: OtelSchema.optional(),
     /** free-text label of the host framework, e.g. "claude-code", "openai-agents" */
     framework: z.string().optional(),
 }).refine(hasOneLog, oneLog);

package/dist/gateway.d.ts

@@ -1,6 +1,8 @@
 import { type CallToolResult, type Tool } from "@modelcontextprotocol/sdk/types.js";
 import type { GatewayConfig } from "./config.ts";
 import { type Delegation } from "./delegation.ts";
+import { type LogSink } from "./log-sink.ts";
+import { type ReceiptExporter } from "./otel.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";
@@ -23,6 +25,12 @@ export interface Gateway {
     handleCall(params: CallParams): Promise<CallToolResult>;
     close(): Promise<void>;
 }
-export declare function createGateway(cfg: GatewayConfig): Promise<Gateway>;
+export interface GatewayOptions {
+    /** the log to append to, in place of the one the config names; for embedding and tests */
+    log?: LogSink;
+    /** told about every receipt after it is written, in place of the exporter the config names */
+    exporter?: ReceiptExporter;
+}
+export declare function createGateway(cfg: GatewayConfig, options?: GatewayOptions): 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

@@ -1,4 +1,4 @@
-// The MCP gateway: sits between an agent and one upstream MCP server, enforces scope + Cedar policy,
+// The MCP gateway: sits between an agent and its upstreams, MCP servers or REST APIs, 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";
@@ -12,7 +12,9 @@ import { digestOf, loadPrivateKey, loadPublicKey } from "./crypto.js";
 import { delegationValidAt, verifyDelegation } from "./delegation.js";
 import { createIssuer } from "./issue.js";
 import { openLog } from "./log-sink.js";
+import { openExporter } from "./otel.js";
 import { upstreamEvidenceOf } from "./upstream.js";
+import { restUpstream } from "./rest.js";
 import { evaluate, policyDigest } from "./policy.js";
 export const GATEWAY_VERSION = "0.1.0";
 export const RECEIPT_META_KEY = "agent-custody/receipt";
@@ -55,7 +57,7 @@ function extractValue(result) {
         return text.text;
     }
 }
-export async function createGateway(cfg) {
+export async function createGateway(cfg, options = {}) {
     const gatewayKey = loadPrivateKey(cfg.identity.keyFile);
     const trusted = cfg.trustedPrincipalKeys.map(loadPublicKey);
     const grantEnvelope = JSON.parse(readFileSync(cfg.grantFile, "utf8"));
@@ -68,7 +70,9 @@ export async function createGateway(cfg) {
     const principalKeyid = grant.keyid;
     const policyText = readFileSync(cfg.policyFile, "utf8");
     const pDigest = policyDigest(policyText);
-    const issuer = createIssuer(gatewayKey, cfg.receiptsDir, openLog(cfg, gatewayKey));
+    const issuer = createIssuer(gatewayKey, cfg.receiptsDir, options.log ?? openLog(cfg, gatewayKey), { exporter: options.exporter ?? openExporter(cfg) });
+    const precommit = new Set(cfg.precommit);
+    const consequential = (tool) => precommit.has("*") || precommit.has(tool);
     // One gateway, one grant, one session, and as many upstreams as the agent's job needs. Each tool name belongs to
     // exactly one upstream, decided at startup, so a receipt's tool is unambiguous and consumed facts flow across them.
     const upstreamConfigs = cfg.upstreams ? cfg.upstreams.map((u) => ({ name: u.name, cfg: u })) : [{ name: "upstream", cfg: cfg.upstream }];
@@ -76,14 +80,19 @@ export async function createGateway(cfg) {
     const owner = new Map();
     const advertised = [];
     for (const { name, cfg: u } of upstreamConfigs) {
-        const client = new Client({ name: "agent-custody-gateway", version: GATEWAY_VERSION });
-        if ("url" in u) {
+        let client;
+        if ("rest" in u) {
+            client = restUpstream(name, u.rest);
+        }
+        else if ("url" in u) {
+            client = new Client({ name: "agent-custody-gateway", version: GATEWAY_VERSION });
             const token = u.tokenEnv ? process.env[u.tokenEnv] : undefined;
             if (u.tokenEnv && !token)
                 throw new Error(`upstream ${name}: environment variable ${u.tokenEnv} is not set`);
             await client.connect(new StreamableHTTPClientTransport(new URL(u.url), token ? { requestInit: { headers: { authorization: `Bearer ${token}` } } } : {}));
         }
         else {
+            client = new Client({ name: "agent-custody-gateway", version: GATEWAY_VERSION });
             await client.connect(new StdioClientTransport({ command: u.command, args: u.args, env: u.env, stderr: "inherit" }));
         }
         upstreams.set(name, client);
@@ -141,6 +150,7 @@ export async function createGateway(cfg) {
         let facts = {};
         let policy;
         let execution;
+        let authorization;
         if (!delegation.scopes.includes(tool)) {
             policy = { decision: "deny", reasons: [], errors: [`tool "${tool}" is not in the delegation scopes`], policyDigest: pDigest };
         }
@@ -158,7 +168,32 @@ export async function createGateway(cfg) {
                 policy = { decision: "deny", reasons: [], errors: [String(e instanceof Error ? e.message : e)], policyDigest: pDigest };
             }
         }
-        if (policy.decision === "allow") {
+        const head = {
+            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" },
+            tool: { name: tool, provenance: "observed", ...(owner.has(tool) && upstreamConfigs.length > 1 ? { upstream: owner.get(tool) } : {}) },
+            request: { args, argsDigest: digestOf(args), provenance: "claimed" },
+            facts,
+            consumed: { factIds: consumedNow, provenance: "observed" },
+        };
+        if (policy.decision === "allow" && consequential(tool)) {
+            // A consequential call is committed to the log before it goes out, so that evidence of the side effect exists
+            // before the side effect does. If the log will not take the authorization, the call is not forwarded.
+            try {
+                authorization = await issuer.authorize({ ...head, policy: { ...policy, provenance: "observed" } });
+            }
+            catch (e) {
+                execution = { status: "withheld", reason: `the log did not commit the authorization, so the call was not forwarded: ${String(e instanceof Error ? e.message : e)}`, provenance: "observed" };
+            }
+        }
+        if (execution) {
+            // withheld: nothing was forwarded
+        }
+        else if (policy.decision === "allow") {
             try {
                 // The upstream learns which receipt this call is, and who the grant says is calling. An upstream that keeps
                 // state, such as the memory server, cites the receipt as the source of what it stores.
@@ -176,19 +211,11 @@ export async function createGateway(cfg) {
             execution = { status: "denied", reason: [...policy.reasons, ...policy.errors].join("; ") || "no permit policy matched", provenance: "observed" };
         }
         await 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" },
+            ...head,
             session: { id: null, toolUseId: null, provenance: "claimed" },
             model: { id: typeof modelClaim === "string" ? modelClaim : null, provenance: "claimed" },
-            tool: { name: tool, provenance: "observed", ...(owner.has(tool) && upstreamConfigs.length > 1 ? { upstream: owner.get(tool) } : {}) },
-            request: { args, argsDigest: digestOf(args), provenance: "claimed" },
-            facts,
-            consumed: { factIds: consumedNow, provenance: "observed" },
             policy: { ...policy, provenance: "observed" },
+            ...(authorization ? { authorization } : {}),
             execution,
         });
         const meta = { [RECEIPT_META_KEY]: receiptId };
@@ -198,6 +225,8 @@ export async function createGateway(cfg) {
                 return refuse(`Denied by policy: ${execution.reason}`);
             case "error":
                 return refuse(`Upstream error: ${execution.error}`);
+            case "withheld":
+                return refuse(`Not executed: ${execution.reason}`);
             default: {
                 const result = execution.result;
                 return { ...result, _meta: { ...result._meta, ...meta } };

package/dist/index.d.ts

@@ -1,3 +1,11 @@
+export { AUTHORIZATION_PREDICATE_TYPE, buildAuthorizationStatement } from "./receipt.ts";
+export type { AuthorizationBundle, AuthorizationPredicate, AuthorizationStatement } from "./receipt.ts";
+export type { GatewayOptions } from "./gateway.ts";
+export { buildRequest, restUpstream } from "./rest.ts";
+export { openExporter, otlpExporter, spanFor } from "./otel.ts";
+export type { OtelConfig, OtlpOptions, ReceiptExporter } from "./otel.ts";
+export type { IssuerOptions } from "./issue.ts";
+export type { RestOptions, UpstreamClient } from "./rest.ts";
 export * from "./config.ts";
 export * from "./crypto.ts";
 export * from "./delegation.ts";

package/dist/index.js

@@ -1,4 +1,7 @@
 // Public surface of @agent-custody/receipts. Framework adapters live on subpaths, ./sdk/<framework>, because they import optional peers.
+export { AUTHORIZATION_PREDICATE_TYPE, buildAuthorizationStatement } from "./receipt.js";
+export { buildRequest, restUpstream } from "./rest.js";
+export { openExporter, otlpExporter, spanFor } from "./otel.js";
 export * from "./config.js";
 export * from "./crypto.js";
 export * from "./delegation.js";