@agent-custody/receipts 0.5.5 → 0.5.6

package/README.md

@@ -14,6 +14,7 @@ Anyone holding the public keys can verify a receipt offline. The agent is not tr
 - [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
 - [Verifying a receipt](docs/verification.md): what each check means and what a verified receipt does and does not prove
+- [What the evidence satisfies](docs/compliance.md): the receipts, packs, and certificates mapped to SOC 2, ISO 27001, the EU AI Act, and UK GDPR, with what none of them claims
 
 ## Getting started
 
@@ -58,7 +59,7 @@ flowchart LR
     R[("receipt bundles<br/>receipts/*.json")]
     L[("Merkle log<br/>local file, or a remote log<br/>run by someone else")]
     V["Verifier<br/>auditor, counterparty, CI job"]
-    O["Observability<br/>OTel, LangSmith, Arize"]
+    O["Observability<br/>OTel, Splunk, LangSmith, Arize"]
 
     P -- "signed delegation grant" --> G
     A -- "MCP tools/call" --> G
@@ -105,7 +106,7 @@ Every receipt names its issuer, and the verifier prints what that issuer kind is
 | Vercel AI SDK | SDK | `wrapTools` | | a real `generateText` loop over the SDK's mock model |
 | LangChain / LangGraph (JS) | SDK | `tool(issuer.wrap(fn))` | `ReceiptCallbackHandler` | real `StructuredTool` invocations |
 | anything else | SDK | `issuer.wrap(name, fn)` | `issuer.record` | plain functions |
-| 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 |
+| Python: LangChain, OpenAI Agents SDK, CrewAI, Claude Agent SDK | sidecar + [Python package](../python/README.md) | `wrap_tools` (OpenAI Agents, CrewAI), `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) |
@@ -241,6 +242,7 @@ src/sdk/claude.ts  Claude Code command hook and Claude Agent SDK in-process hook
 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/splunk.ts      Splunk export: one HTTP Event Collector event per receipt, token from the environment, beside or instead of otel
 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
@@ -268,7 +270,7 @@ The design is two producers feeding one verifier. The SDK is the top of the funn
 - Claude Code command hook for PreToolUse, PostToolUse, and PostToolUseFailure, with blocking on deny.
 - Claude Agent SDK in-process hooks over the same handler.
 - Provider-native deliveries: an upstream wrapping Stripe or GitHub attaches the signed webhook or delivery for the call; a verifier with the shared secret checks the HMAC, the timestamp, and the binding to the result, and reports the execution as attested by shared secret.
-- Logarithmic appends: the Merkle log caches complete subtrees, so issuing a receipt costs the same at the millionth leaf as at the first; measured at 0.15 ms per receipt and about half a millisecond per gateway call including policy, a fact lookup, and the upstream signature.
+- Logarithmic appends: the Merkle log caches complete subtrees, so issuing a receipt costs the same at the millionth leaf as at the first; measured at 0.15 ms per receipt and about half a millisecond per gateway call including policy, a fact lookup, and the upstream signature. A remote log adds one network round trip plus about five milliseconds of server work per call, two for a pre-committed call; the [deployment guide](https://agent-custody.dev/guide/deployment) has the measurements against the live log.
 - Retention on the log: `prune` replaces leaves older than a cutoff with their hashes and removes their bundles, so proofs still verify and the content is gone.
 - Several upstreams under one gateway and one grant, each tool owned by exactly one, with the receipt naming which served the call; consumed facts flow across them.
 - Attested execution: an upstream that holds a key signs its result for the receipt, the gateway embeds it, and a verifier given the upstream key reports the execution as attested rather than observed. The memory server and the demo upstream sign.
@@ -288,6 +290,7 @@ The design is two producers feeding one verifier. The SDK is the top of the funn
 - The log over Postgres: `log --db-env`, leaves as hashes in one table keyed by tenant, one writer per tenant by advisory lock, tenants and hashed tokens in tables managed by `log-admin`, rate limits and a body cap, retries in the sink, and `import` for an existing file log. Phase 2 of [issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6).
 - 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.
+- Splunk export: with `splunk` in either config, every receipt is also one event at the HTTP Event Collector, with the receipt id, tool, agent, principal, status, decision, and log position as searchable fields and the token from the environment; the same best-effort rule.
 - 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.
 

package/dist/config.d.ts

@@ -181,6 +181,14 @@ export declare const GatewayConfigSchema: z.ZodObject<{
         headersEnv: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         serviceName: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    splunk: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        tokenEnv: z.ZodString;
+        index: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodString>;
+        sourcetype: z.ZodOptional<z.ZodString>;
+        host: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type GatewayConfig = z.infer<typeof GatewayConfigSchema>;
 export type FactConfig = z.infer<typeof FactSchema>;
@@ -205,6 +213,14 @@ export declare const SdkConfigSchema: z.ZodObject<{
         headersEnv: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         serviceName: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    splunk: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        tokenEnv: z.ZodString;
+        index: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodString>;
+        sourcetype: z.ZodOptional<z.ZodString>;
+        host: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     framework: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type SdkConfig = z.infer<typeof SdkConfigSchema>;

package/dist/config.js

@@ -6,6 +6,7 @@ const LogSchema = z.object({ url: z.string().url(), tokenEnv: z.string().min(1).
 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 SplunkSchema = z.object({ url: z.string().url(), tokenEnv: z.string().min(1), index: z.string().min(1).optional(), source: z.string().min(1).optional(), sourcetype: z.string().min(1).optional(), host: 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({
@@ -65,6 +66,7 @@ export const GatewayConfigSchema = z.object({
     logFile: z.string().optional(),
     log: LogSchema.optional(),
     otel: OtelSchema.optional(),
+    splunk: SplunkSchema.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) {
@@ -92,6 +94,7 @@ export const SdkConfigSchema = z.object({
     logFile: z.string().optional(),
     log: LogSchema.optional(),
     otel: OtelSchema.optional(),
+    splunk: SplunkSchema.optional(),
     /** free-text label of the host framework, e.g. "claude-code", "openai-agents" */
     framework: z.string().optional(),
 }).refine(hasOneLog, oneLog);

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export type { AuthorizationBundle, AuthorizationPredicate, AuthorizationStatemen
 export type { GatewayOptions } from "./gateway.ts";
 export { buildRequest, restUpstream } from "./rest.ts";
 export { openExporter, otlpExporter, spanFor } from "./otel.ts";
+export { hecEvent, splunkExporter } from "./splunk.ts";
 export { fileBackend, importLogFile, PostgresLog, PostgresTenancy, RateLimiter } from "./log-store.ts";
 export { connectSigner, fetchLogKeys, localSigner, serveSigner, signerHandler } from "./signer.ts";
 export type { KeyDocument, RemoteSignerOptions, RetiredKey, RunningSigner, Signer, SignerServerOptions } from "./signer.ts";
@@ -17,6 +18,7 @@ export type { AdminOptions } from "./log-admin.ts";
 export type { Checkpoint, CheckpointStore } from "./checkpoints.ts";
 export type { AppendResult, LogBackend, PostgresLike, PostgresLogOptions, RateLimitOptions, Tenant, TokenRecord } from "./log-store.ts";
 export type { OtelConfig, OtlpOptions, ReceiptExporter } from "./otel.ts";
+export type { SplunkConfig, SplunkOptions } from "./splunk.ts";
 export type { IssuerOptions } from "./issue.ts";
 export type { RestOptions, UpstreamClient } from "./rest.ts";
 export * from "./config.ts";

package/dist/index.js

@@ -2,6 +2,7 @@
 export { AUTHORIZATION_PREDICATE_TYPE, buildAuthorizationStatement } from "./receipt.js";
 export { buildRequest, restUpstream } from "./rest.js";
 export { openExporter, otlpExporter, spanFor } from "./otel.js";
+export { hecEvent, splunkExporter } from "./splunk.js";
 export { fileBackend, importLogFile, PostgresLog, PostgresTenancy, RateLimiter } from "./log-store.js";
 export { connectSigner, fetchLogKeys, localSigner, serveSigner, signerHandler } from "./signer.js";
 export { bothCheckpoints, dirCheckpoints, postgresCheckpoints } from "./checkpoints.js";

package/dist/otel.d.ts

@@ -1,4 +1,5 @@
 import type { ReceiptBundle, ReceiptPredicate } from "./receipt.ts";
+import { type SplunkConfig } from "./splunk.ts";
 export interface OtelConfig {
     /** the collector's OTLP/HTTP base, e.g. http://localhost:4318; spans go to <url>/v1/traces */
     url: string;
@@ -22,7 +23,8 @@ export interface OtlpOptions {
 }
 /** 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. */
+/** The exporters a config asks for, as one; undefined when it asks for none. Each is told independently, so one failing never silences another. */
 export declare function openExporter(cfg: {
     otel?: OtelConfig | undefined;
+    splunk?: SplunkConfig | undefined;
 }): ReceiptExporter | undefined;

package/dist/otel.js

@@ -1,3 +1,4 @@
+import { splunkExporter } from "./splunk.js";
 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. */
@@ -81,7 +82,21 @@ export function otlpExporter(cfg, opts = {}) {
         },
     };
 }
-/** The exporter a config asks for, or undefined. */
+/** The exporters a config asks for, as one; undefined when it asks for none. Each is told independently, so one failing never silences another. */
 export function openExporter(cfg) {
-    return cfg.otel ? otlpExporter(cfg.otel) : undefined;
+    const all = [];
+    if (cfg.otel)
+        all.push(otlpExporter(cfg.otel));
+    if (cfg.splunk)
+        all.push(splunkExporter(cfg.splunk));
+    if (all.length === 0)
+        return undefined;
+    if (all.length === 1)
+        return all[0];
+    return {
+        where: all.map((e) => e.where).join(", "),
+        async exported(p, bundle) {
+            await Promise.all(all.map((e) => e.exported(p, bundle)));
+        },
+    };
 }

package/dist/splunk.d.ts

@@ -0,0 +1,26 @@
+import type { ReceiptBundle, ReceiptPredicate } from "./receipt.ts";
+import type { ReceiptExporter } from "./otel.ts";
+export interface SplunkConfig {
+    /** the collector's base, e.g. https://splunk.example.com:8088; events go to <url>/services/collector/event */
+    url: string;
+    /** environment variable holding the HEC token; a missing variable fails at startup */
+    tokenEnv: string;
+    /** index to write to; omitted, the token's default index */
+    index?: string | undefined;
+    /** the event's source field; default agent-custody */
+    source?: string | undefined;
+    /** the event's sourcetype; default agent-custody:receipt */
+    sourcetype?: string | undefined;
+    /** the event's host field; omitted, the collector fills it in */
+    host?: string | undefined;
+}
+/** The HEC event for one receipt: flat fields Splunk can search without a props stanza. Exported for tests and other transports. */
+export declare function hecEvent(p: ReceiptPredicate, bundle: ReceiptBundle, cfg: SplunkConfig): Record<string, unknown>;
+export interface SplunkOptions {
+    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 as one event to a Splunk HTTP Event Collector. Failures are reported, never thrown. */
+export declare function splunkExporter(cfg: SplunkConfig, opts?: SplunkOptions): ReceiptExporter;

package/dist/splunk.js

@@ -0,0 +1,59 @@
+/** The HEC event for one receipt: flat fields Splunk can search without a props stanza. Exported for tests and other transports. */
+export function hecEvent(p, bundle, cfg) {
+    const auth = p.authorization;
+    const exec = p.execution;
+    return {
+        time: Date.parse(p.timestamp) / 1000,
+        source: cfg.source ?? "agent-custody",
+        sourcetype: cfg.sourcetype ?? "agent-custody:receipt",
+        ...(cfg.index ? { index: cfg.index } : {}),
+        ...(cfg.host ? { host: cfg.host } : {}),
+        event: {
+            receipt_id: p.receiptId,
+            issuer_kind: p.issuer.kind,
+            issuer_keyid: p.issuer.keyid,
+            tool: p.tool.name,
+            upstream: p.tool.upstream ?? null,
+            agent: p.agent.id,
+            agent_provenance: p.agent.provenance,
+            principal: p.principal.id,
+            status: exec.status,
+            reason: exec.reason ?? exec.error ?? null,
+            policy_decision: p.policy?.decision ?? null,
+            policy_digest: p.policy?.policyDigest ?? null,
+            policy_reasons: p.policy?.reasons ?? [],
+            args_digest: p.request.argsDigest,
+            log_leaf_index: bundle.inclusion.leafIndex,
+            log_tree_size: bundle.inclusion.treeSize,
+            authorization_leaf_index: auth ? auth.inclusion.leafIndex : null,
+            consumed_count: p.consumed?.factIds.length ?? 0,
+            model: p.model.id,
+            session: p.session.id,
+        },
+    };
+}
+/** An exporter that posts each receipt as one event to a Splunk HTTP Event Collector. Failures are reported, never thrown. */
+export function splunkExporter(cfg, opts = {}) {
+    const f = opts.fetch ?? fetch;
+    const env = opts.env ?? process.env;
+    const warn = opts.warn ?? ((m) => console.error(m));
+    const token = env[cfg.tokenEnv];
+    if (!token)
+        throw new Error(`splunk: environment variable ${cfg.tokenEnv} is not set`);
+    const headers = { "content-type": "application/json", authorization: `Splunk ${token}` };
+    const base = cfg.url.endsWith("/") ? cfg.url : `${cfg.url}/`;
+    const url = new URL("services/collector/event", base);
+    return {
+        where: cfg.url,
+        async exported(p, bundle) {
+            try {
+                const res = await f(url, { method: "POST", headers, body: JSON.stringify(hecEvent(p, bundle, cfg)), signal: AbortSignal.timeout(5000) });
+                if (!res.ok)
+                    warn(`agent-custody: splunk export of receipt ${p.receiptId} refused by ${cfg.url}: ${res.status}`);
+            }
+            catch (e) {
+                warn(`agent-custody: splunk export of receipt ${p.receiptId} failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        },
+    };
+}

package/docs/compliance.md

@@ -0,0 +1,64 @@
+# What the evidence satisfies
+
+Auditors ask for controls by their names. This page maps the requirements they cite most to the artefacts agent-custody produces, so a security questionnaire can be answered with a file rather than a paragraph. It is a map, not a certificate: the artefacts are evidence that a control operated, and the control itself, the policy, the grant, the retention window, the person who reviews an alarm, is yours.
+
+Two rules keep the answers honest. First, say which producer made the receipt: a gateway receipt was enforced outside the agent's process, an SDK receipt is the agent's own report, and the receipt's `issuer.kind` says which. Second, say where the log runs: with the default local log the operator can rewrite history, with a log run by someone else they cannot, and with a witness neither operator can. The [proof table](../README.md#what-a-receipt-proves-and-what-it-does-not) has the full list of claims and against whom each holds.
+
+## The artefacts
+
+| artefact | what it is | how to produce it |
+| --- | --- | --- |
+| receipt | one signed record per tool call: who authorized it, what the agent saw, what it did, the policy decision, its position in the log | issued by the gateway or the SDK; `receipts/<id>.json` |
+| authorization | the same, committed to the log before a consequential call was forwarded | `precommit` in the gateway config |
+| verification report | the check list a third party gets from the receipt and public keys alone | `agent-custody verify` |
+| audit | proof that the log at a later size extends its earlier state | `agent-custody audit` between any two tree heads or checkpoints |
+| checkpoint | a signed tree head published on a schedule, countersigned by a witness where one runs | the log's checkpoints host, the witness's host |
+| action pack | one receipt explained and packed with every downstream receipt, signed | `agent-custody-memory explain --out --sign` |
+| custody pack | one fact's history, receipts, blast radius, holds, and forget certificate, signed | `agent-custody-memory pack` |
+| forget certificate | the receipt of the call that erased a value from the ledger and the stores, with each store's answer | `memory.forget` through the gateway |
+| eval report | scores for stale reads, contradictions, and blast radius after retraction, signed | `agent-custody-memory eval --sign` |
+| usage | appends per tenant per month on the hosted log | `/admin/usage.csv` |
+
+## SOC 2, Trust Services Criteria
+
+| criterion | what it asks | what answers it |
+| --- | --- | --- |
+| CC6.1, logical access | access to systems is restricted to authorized users | the delegation grant: a human-signed statement of which agent may call which tools, for how long, embedded in every gateway receipt and re-checked by the verifier |
+| CC6.3, authorization changes | access is granted, modified, and removed by authorized parties | grants have validity windows and are signed by a principal key the gateway is configured to trust; a new grant is a new signed file, a revoked one expires |
+| CC7.2, monitoring for anomalies | the entity monitors system components for anomalies | every call has a receipt, allowed or denied, and `explain` answers who, why, and what depended on it; the OpenTelemetry and Splunk exports carry each receipt into the existing SIEM |
+| CC7.3, evaluation of security events | events are evaluated to determine whether they are incidents | the action pack: one receipt with every downstream receipt, verifiable by the evaluator without access to the system |
+| CC7.4, incident response | incidents are contained and remediated | blast radius names every action and belief that depended on a wrong fact; retract and forget are receipted calls, so the remediation has its own evidence |
+| CC8.1, change management | changes are authorized and tracked | the policy digest in every receipt identifies the exact policy that decided the call, so a policy change is visible in the receipts on either side of it |
+
+## ISO/IEC 27001:2022, Annex A
+
+| control | what it asks | what answers it |
+| --- | --- | --- |
+| A.5.15, access control | rules for access based on business requirements | the grant and the Cedar policy, with the policy decision on facts the gateway fetched itself |
+| A.5.28, collection of evidence | evidence is collected in a form that stands up | receipts are signed, hashed into a Merkle log, and verifiable offline; the audit proves nothing was rewritten between two points; the packs are single signed artefacts for a case file |
+| A.8.10, information deletion | information is deleted when no longer required | forget erases a value from the ledger and the adapted stores and the receipt is the certificate, with each store's own answer; retention sweeps run as receipted calls; a legal hold refuses both |
+| A.8.15, logging | logs are produced, stored, protected, and analysed | the transparency log, append-only and hashed, with a log run by someone else where the operator must not be trusted |
+| A.8.16, monitoring activities | networks, systems, and applications are monitored | `log-check` from a machine that is not the log's, and the per-receipt spans in the SIEM |
+| A.8.32, change management | changes are subject to change management | the policy digest, the grant's window, and the receipts either side of a change |
+
+## EU AI Act, obligations on high-risk systems and their deployers
+
+| article | what it asks | what answers it |
+| --- | --- | --- |
+| Article 12, record-keeping | automatic recording of events over the system's lifetime, enabling traceability | one receipt per tool call, in a tamper-evident log, with the facts the agent was shown and the beliefs it wrote; `explain` traces any action to its causes and consequences |
+| Article 14, human oversight | humans can understand, oversee, and intervene | the grant is a human's signature over what the agent may do; the policy decides on facts the agent did not supply; retract and forget are the intervention, receipted |
+| Article 19, retention of logs | logs are kept for a period appropriate to the purpose | retention windows per space in the memory server; `prune` on the receipt log keeps every proof valid while the content is gone; a legal hold overrides both |
+| Article 26, deployer obligations | deployers keep logs and monitor operation | the same receipts and the same monitor; a tenant on the hosted log has its own log id and checkpoints an auditor can fetch |
+
+## UK GDPR
+
+| provision | what it asks | what answers it |
+| --- | --- | --- |
+| Article 5(2), accountability | the controller demonstrates compliance | signed receipts and packs demonstrate what was done and why, to a party who has no access to the controller's systems |
+| Article 17, right to erasure | personal data is erased on request | the forget certificate, including `stillIndexed` when a store has not caught up, which is what an honest response to a data subject says |
+| Article 30, records of processing | records of processing activities are kept | the receipts, and the memory ledger's history of every fact with its source receipt |
+| Article 32, security of processing | appropriate technical measures | the hosted log holds hashes only, and receipts stay with the controller |
+
+## What no artefact here claims
+
+That the agent's arguments were correct, that the model named in a receipt produced the call, that the upstream executed the action unless it signed the result or a provider delivery is embedded, or that an SDK receipt was enforced outside the agent. The [proof table](../README.md#what-a-receipt-proves-and-what-it-does-not) says so, and a questionnaire answer that repeats it will survive the reviewer who checks.

package/docs/sdk.md

@@ -30,7 +30,7 @@ Use the SDK for reach. Use the gateway for anything that moves money, touches pr
 
 `policyFile` and `principalId` are optional. Without a policy the SDK records and never denies. Paths resolve relative to the config file. Instead of `logFile`, `"log": { "url": "https://log.example.com/", "tokenEnv": "AGENT_CUSTODY_LOG_TOKEN" }` sends every leaf to a log run by someone else, whose key then signs the tree heads; see [usage.md](usage.md) for what that changes and [verification.md](verification.md) for what it proves. Generate the key with `node src/cli.ts keygen --dir keys --name app`.
 
-`"otel": { "url": "http://localhost:4318" }` additionally exports every receipt as one span to that OTLP/HTTP collector, after the receipt is written, with the receipt id as the trace id; see the [usage guide](usage.md#setup-step-by-step) for the fields. Export never blocks or fails a receipt.
+`"otel": { "url": "http://localhost:4318" }` additionally exports every receipt as one span to that OTLP/HTTP collector, after the receipt is written, with the receipt id as the trace id; see the [usage guide](usage.md#setup-step-by-step) for the fields. Export never blocks or fails a receipt. `"splunk": { "url": ..., "tokenEnv": "HEC_TOKEN" }` does the same to a Splunk HTTP Event Collector, one event per receipt with the receipt id and log position as fields; both blocks may be set together.
 
 Policies see `context.args` and an empty `context.facts`. A policy that reads `context.facts` or `context.grant` errors, which is a deny. That is intended: an SDK policy cannot pretend it checked something outside the agent's process.
 

package/docs/tutorials.md

@@ -28,6 +28,7 @@ Suggested reading order is the numbering. Output lands in `examples-out/`, which
 | 16 | consequential tools, committed first | [16-precommit.ts](../examples/16-precommit.ts) | a refund named in `precommit`: the authorization leaf before the receipt leaf, the five authorization checks in the report, and the same call withheld when the log refuses | `src/gateway.ts`, `src/issue.ts`, `src/verify.ts` |
 | 17 | a REST API as an upstream | [17-rest-upstream.ts](../examples/17-rest-upstream.ts) | a stand-in payments API described as two tools, the token from the environment, a refund allowed on the gateway's own lookup and one denied before reaching the API, the receipt verified | `src/rest.ts`, `src/gateway.ts` |
 | 18 | OpenTelemetry export | [18-opentelemetry.ts](../examples/18-opentelemetry.ts) | a stand-in OTLP collector, `otel` in the config, one span per receipt with the receipt id as trace id, the collector going away and the next receipt still issued | `src/otel.ts`, `src/issue.ts` |
+| 19 | Splunk export | [19-splunk.ts](../examples/19-splunk.ts) | a stand-in HTTP Event Collector, `splunk` in the config with the token from the environment, one event per receipt with the receipt id and log position as fields, the collector going away and the next receipt still issued | `src/splunk.ts`, `src/otel.ts` |
 
 ## How policies are defined, in one paragraph
 

package/docs/usage.md

@@ -109,6 +109,8 @@ Exactly one of the two. The bearer token comes from the named environment variab
 
 `otel`, optional in both the gateway and SDK configs, sends every receipt to the collector you already run as one span over OTLP/HTTP, after the receipt is issued: `"otel": { "url": "http://localhost:4318", "headersEnv": { "x-api-key": "OTEL_KEY" }, "serviceName": "support-agents" }`. The span's trace id is the receipt id, its attributes carry the tool, agent, principal, execution status, policy decision, and log position, and its status is an error only when the upstream failed or errored, since a denial is the policy working. Export is best effort: a collector that is down or refuses costs a line on stderr, never a receipt. Tutorial 18 shows it against a stand-in collector.
 
+`splunk`, optional in both configs and usable beside `otel`, sends every receipt to a Splunk HTTP Event Collector as one event: `"splunk": { "url": "https://splunk.example.com:8088", "tokenEnv": "HEC_TOKEN", "index": "agents" }`, with optional `source` (default `agent-custody`), `sourcetype` (default `agent-custody:receipt`), and `host`. The token is read from the named environment variable at startup and never appears in the config. Each event carries `receipt_id`, `tool`, `agent`, `principal`, `status`, `reason`, `policy_decision`, `policy_digest`, `args_digest`, `log_leaf_index`, `log_tree_size`, and `authorization_leaf_index` as plain fields, so a search like `sourcetype="agent-custody:receipt" status=denied` needs no field extraction and every alert leads to the receipt by id. The same rule holds: the event is a copy, the receipt is the evidence, and a collector outage costs a warning. Tutorial 19 shows it.
+
 `facts` tells the gateway which upstream tool to call before evaluating policy for a given tool. `$args.<key>` copies a value from the intercepted call. The result appears in Cedar as `context.facts.<name>` and in the receipt with its own digest, labelled `observed`. If a fact lookup fails, the call is denied and the receipt says why. A lookup with `"optional": true` is skipped when a `$args.<key>` it needs is absent from the call, and the fact is then simply not present, which a policy tests with `context.facts has <name>`; this is how a policy sees the fact a `memory.write` is about to supersede without denying every write that supersedes nothing.
 
 `precommit` names the consequential tools, or `["*"]` for all of them. For every other tool the gateway forwards the call and then records it, so if the log is unreachable at that moment the side effect exists before its evidence does. For a tool in `precommit` the gateway first signs an authorization statement, everything the receipt will say except the outcome, and appends it to the log. Only if the log took it does the call go upstream. The receipt then embeds that authorization with its own inclusion proof, and a verifier checks that it names this call and sits in the log before the receipt does. If the log will not take it, the call is not forwarded, the agent is told `Not executed`, and the receipt records `execution.status: "withheld"` with the policy's `allow` beside it. The authorization is also written on its own as `receipts/<receiptId>.authorization.json`, which is the evidence that survives if the gateway dies between forwarding and the receipt. Use it for money, for anything irreversible, and for anything a counterparty could later dispute; the cost is one extra log append per call.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-custody/receipts",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "description": "Chain of custody for AI agents: signed, independently verifiable receipts for tool calls. MCP gateway + Cedar policy + Merkle transparency log",
   "license": "Apache-2.0",
   "repository": {