Chirindo

A fail-closed cryptographic gate for the MCP tool-call boundary — the watchtower for your AI agents. By Headless Oracle.

Chirindo — Shona for "watchtower."

A stdio MCP proxy that intercepts tools/call requests from a real MCP client (Claude Desktop, Cursor), evaluates a policy, and either forwards the call to the real downstream server (ALLOW) or returns a tool-failure response WITHOUT forwarding (DENY) — emitting a signed receipt in either case.

Chirindo emits calibrated evidence: a verifying party can prove that the gate fired for a given call and that the chain is recomputable from the signed records. The receipts do not prove an action was "safe" — only that the gate's decision is captured, signed, and tamper-evident (not tamper-proof: an edit, a reorder, or a deletion other than cutting off the tail breaks the hash chain and is caught by recorder verify; cutting off the tail, and a rewrite by the key holder, are caught only against witnessed checkpoints, see Witness). The receipt format and signing reuse the existing recorder engine — no reimplementation of JCS, hashing, or Ed25519.

Chirindo is an operator-run gate that signs its receipts operator-side. Anyone holding a receipt can recompute it against the gate's published key, so a receipt is a recomputable, tamper-evident record of what this operator's gate decided — not a neutral third party's attestation, and not proof that the underlying action was "safe."

Posture: fail-closed (the opposite of the recorder)

The recorder is observe-only: it never blocks the agent, even when its own signer crashes. The gate is the inverse: when it cannot evaluate policy, it denies. When it cannot write a receipt for an action that already ran, it withholds the result from the client (the action's side effect already happened; we cannot un-do it, but we can prevent the agent from acting on an un-receipted result).

Related MCP server: Proofpane

Architecture

MCP client (Claude Desktop)
        │
        ▼ stdio (JSON-RPC 2.0, newline-delimited)
   chirindo proxy   ◀── policy.json (deny rules)
        │
        ▼ stdio
  downstream MCP server (the real one)

The client launches chirindo proxy as its MCP server. The proxy spawns the real downstream MCP server as a child process. Every JSON-RPC frame in either direction passes through the proxy. tools/call requests are evaluated against the loaded policy:

• ALLOW → forward to downstream; on the response, write an ALLOW receipt and pass the response back to the client.

• DENY → synthesize a tool-execution-error response ({result: {content:[...], isError: true}}) per MCP spec § Error Handling, send it to the client, write a DENY receipt. The downstream NEVER sees the call.

• FAIL-CLOSED → if the policy can't be loaded or the evaluator throws, DENY the call.

All other frames (initialize, tools/list, responses, notifications) pass through unmodified, with these exceptions. A tools/call is recognised by its method alone, whatever its id or jsonrpc members say, and these client lines are refused, never forwarded:

• a tools/call with no id: a DENY receipt and no reply (a message without an id is a notification);

• a tools/call whose id is null, or is not a string or an integer: a DENY receipt and a JSON-RPC error -32600 with id: null;

• a JSON-RPC batch (a JSON array): a DENY receipt for each tools/call in it and one -32600 error (MCP removed batching in its 2025-06-18 revision);

• a line that is not JSON (-32700), or that has a carriage return inside it (-32600);

• a message that names a member twice in one object, or whose top-level members include jsonrpc, id, method or params in another case ("Method", or "paramſ" with U+017F), or that has two members differing only in case at the top level or in params; and a tools/call whose params holds name, arguments or _meta in another case: -32600 with the request's id. A decoder that matches member names without regard to case, as Go's encoding/json does for a struct, could read these differently from the gate;

• a message with a member named __proto__ at the top level or in params: -32600 with the request's id, and a DENY receipt when the method of the message or of that member can be read as a tools/call. JSON.parse keeps __proto__ as an inert data member, so the gate reads no method or name from it; but a downstream that copies the message into a fresh object (Object.assign({}, msg), a for...in loop) sets that object's prototype from the member, so a method and params carried inside it read as the message's own;

• a message whose method is not a string (an array such as ["tools/call"], an object, a number, true, false or null), or is tools/call only after trimming white space or folding case ("TOOLS/CALL", "tools/call "), or holds a control or format character: -32600 with the request's id, and a DENY receipt when it can be read as a tools/call. A downstream that trims or folds the method, or that turns a method that is not a string into text (String(method), or a lookup in a table of handlers keyed by method), could otherwise run a call the gate never checked;

• a tools/call with an integer outside JavaScript's safe range (beyond 2^53 - 1), or a number too large for a double (such as 1e400), anywhere in it: -32600 with the request's id. The gate forwards an allowed call re-encoded from its parsed value, which would change such a number (1e400 would become null);

• a tools/call nested more than 128 levels deep, too deep to canonicalize for a receipt: -32600 with the request's id, and a DENY receipt whose args_hash is over the empty object. The gate computes a call's args_hash and request_commitment before forwarding it, so a call it could not record never reaches the downstream; a call at or within the limit runs as before;

• a tools/call with the id of a tools/call still waiting for its result: -32600 with the request's id;

• a tools/call whose params is not an object, or whose params.name is not a non-empty string: -32602 with the request's id; its DENY receipt names the tool "";

• a tools/call whose params.name begins or ends with white space, or holds a control or format character (Unicode categories Cc and Cf, such as NUL or a zero-width space) anywhere: -32602 with the request's id. A downstream that trims names, or drops such characters, could read the name of a tool that a deny rule names;

• unless the proxy runs with --allow-nonstandard-tool-names, a tools/call whose params.name is outside MCP's rule for tool names: -32602 with the request's id. MCP's tools page (revision 2026-07-28, "Tool Names") says tool names SHOULD be 1 to 128 characters long, and "The following SHOULD be the only allowed characters": ASCII letters, digits, underscore (_), hyphen (-) and dot (.). A downstream may normalize a name outside that rule into the name of a tool a deny rule names (NFKC turns the fullwidth ｍｏｃｋ＿ｓｗａｐ into mock_swap; invisible and combining characters can be dropped). With the flag such names are forwarded, deny rules compare them without regard to case only, and the proxy prints a warning to stderr at start.

"The request's id" is the message's id when the message is a request (it has a method member, in any case), has one member named exactly id, and that id is a string or an integer within JavaScript's safe range; otherwise the error has id: null. A client's response to a request from the server is answered with id: null, since its id is the server's.

Each refusal writes one line to stderr. Every refused line that is a tools/call, or that a downstream could read as one (matching member names without regard to case, trimming, folding the case of or dropping control and format characters from the method, reading a method that is not a string as text, or reading a __proto__ member as the message's own members), gets one DENY receipt (a batch, one per such element); lines that are not JSON or have a carriage return inside get none, nor does a tools/call whose arguments hold a number too large for a double, which no receipt can hash (its stderr line says so). A tools/call refused for nesting too deep gets a DENY receipt over the empty object. A refusal's DENY receipt reads like a policy denial (decision: "deny", decision_source: "config"): the reason is in the stderr line only. Member names inside params.arguments and params._meta are not checked for case or for a __proto__ member; the receipt's args_hash covers the arguments as the gate parsed them, which is what it forwards.

The signed receipt

Each intercepted tools/call produces a single line appended to a per-session JSONL chain file. The receipt is an evidence.action/1 record from the recorder schema, with the gate block populated. The example below is real signer output from a throwaway key, verbatim — it verifies with chirindo verify:

{
  "v": "evidence.action/1",
  "seq": 0,
  "session_id": "11111111-2222-4333-8444-555555555555",
  "ts": "2026-07-08T09:00:00.000Z",
  "agent": {
    "vendor": "chirindo",
    "version": "0.0.1"
  },
  "event": {
    "type": "mcp_call",
    "outcome": "executed",
    "server": "everything",
    "tool_name": "echo",
    "args_hash": "sha256:cbbbdcd27692344de5dbab3abcaba413fb0f45307267de7081401576df1cb176",
    "decision": "allow",
    "decision_source": "config",
    "result_hash": "sha256:493466351f6341d054cec14e973f001dc7d66e5bb4a4177d42014725b2f7cb6b"
  },
  "request_commitment": "sha256:55e4964e7b22557513889732c7998697d40eaeb3cf4996686a638ce9d64c8ccf",
  "gate": {
    "request_commitment": "sha256:55e4964e7b22557513889732c7998697d40eaeb3cf4996686a638ce9d64c8ccf",
    "gate_receipt": "sha256:6cbf1406bf3a0c6a2d6a123697ea72c990f2f8e0f50fdbfc5c568109d1e654dc",
    "gate_family": "permit",
    "result": "act"
  },
  "jwks_uri": "https://gate.example.com/.well-known/jwks.json",
  "key_thumbprint": "DEHVOBA-vd8KledaxgxgPHkpGS4TES9CTQcMTVHcwYo",
  "iss": "https://gate.example.com",
  "prev_hash": "sha256:5a8534e71ecae904f1a9b2945b77bcc9bc3035b08c3968d0fe1ce199189cc345",
  "kid": "DEHVOBA-vd8KledaxgxgPHkpGS4TES9CTQcMTVHcwYo",
  "sig": "E_BIbjouxmMZClFqU2sVw8xkhZDhI8o4ZKjYmTJzHby0nBxJTvSs1-Gu7EZyrQS0E1etqpe9wekeHxzOVjgvCw"
}

Field notes:

• v is evidence.action/1. A v1 receipt binds the signer inside the signed bytes with two fields: key_thumbprint — the RFC 7638 JWK thumbprint of the gate's signing key, which the verifier recomputes from the resolved key and checks before the signature, so a key substituted at the jwks_uri can't pass by verifying under itself — and iss, the issuer identity, defaulting to the origin of jwks_uri (the operator's own domain, never Headless Oracle). For a v1 receipt kid == key_thumbprint: one key identity, reconcilable from the receipt alone.

• agent names the gate software that wrote the receipt: vendor is chirindo and, from 0.5.3, version is the version of the package that wrote it. Receipts written by 0.5.2 and earlier, like the example above, carry "version": "0.0.1" whatever the package version was.

• event: this is an ALLOW receipt (outcome: "executed", decision: "allow", gate.result: "act"). A DENY receipt instead reads denied / deny / halt and omits result_hash — there was no downstream response to hash. args_hash and result_hash are RFC 8785 JCS + SHA-256 over the argument and result values (recomputable by any verifier, not JSON.stringify).

• gate.request_commitment MUST equal the top-level request_commitment (the continuity invariant); gate.gate_receipt is the hash of the receipt computed while gate_receipt still held the placeholder "self"; it is not the receipt's entry hash. The entry hash is computed from the signed record without sig, "sha256:" + hex(SHA-256(JCS(record without "sig"))) (the value the next record's prev_hash carries), and that computed value is what ordering evidence should carry. An outside time for the receipt comes from a witnessed checkpoint whose count covers that entry (see Showing a gate ran before an action).

• jwks_uri (optional) names where this receipt's signing key is published; it is inside the signed bytes, so the operator commits to it.

The chain verifies via the recorder's verify engine — same hash chain, same signature scheme, same canonical bytes — which is exactly what chirindo verify runs. Cross-tool interop is the point: the gate's output is evidence the recorder's verifier already understands.

Commands

chirindo init   [--dir <path>]
chirindo proxy  --policy <file> --server-label <name>
                [--dir <path>] [--chain <file>] [--session-id <id>]
                [--checkpoint-every <N>] [--witness <base-url>]
                [--witness-key <hex|jwk-file>] [--witness-name <name>]
                [--witness-account-key-file <path>]
                [--allow-nonstandard-tool-names]
                -- <downstream-command> [<args>...]
chirindo checkpoint <chain-file> [--dir <path>] [--witness <base-url>]
                [--witness-key <hex|jwk-file>] [--witness-name <name>]
                [--witness-account-key-file <path>]
chirindo verify <chain-file> [--key <identity.json> | --jwks <url>]
                [--expect-thumbprint <tp>]... [--trust-file <file>]
                [--max-skew-ms <ms>]
                [--witness <base-url> | --witness-file <sidecar>]
                [--witness-key <hex|jwk-file>] [--witness-key-id <id>]
                [--witness-name <name>]

Defaults: --dir = ./.gate/, identity at <dir>/identity.json, chain at <dir>/sessions/<session-id>.jsonl.

verify key resolution (precedence, highest first): --key <file> > --jwks <url> > the receipt's own jwks_uri > $RECORDER_JWKS_URL > the published default. Fallback happens only when the higher source is absent — a receipt whose jwks_uri is present but unreachable is UNVERIFIABLE, never silently re-resolved to a default key. There is no implicit local-identity default; pass --key for the offline path.

Hardened fetch. Every jwks_uri fetch is https:// + port 443 only, rejects IP-literal hosts and any hostname that resolves to a private/loopback/link-local address (checked after DNS, so a rebind can't slip through), follows at most one same-origin redirect, caps the body at 64 KiB, times out at 5 s, and requires a JSON content-type. A receipt that names an http:// jwks_uri is malformed → INVALID.

Policy file format

{
  "deny": [
    { "tool": "delete", "reason": "destructive: blocked by policy" },
    { "tool": "shell_exec", "server": "everything" }
  ]
}

A rule matches if tool is the call's name without regard to case, AND server (if present) is the proxy's --server-label exactly. Without regard to case means under Unicode case folding and under the full case mappings of upper and lower case: a rule for delete_file also matches DELETE_FILE, Delete_File and delete_file (with the ligature U+FB01), which a downstream that looks tools up without regard to case could run as delete_file. Up to 0.5.2 the match was exact. By default a name outside MCP's rule for tool names is refused before any rule is applied (see the refusals above). Anything not matched by a deny rule is allowed. The shipped policy.json is {"deny": []} — records everything, blocks nothing, observe-only by default. Enforcement is opt-in (see step 6 below). Fail-closed: an unreadable or malformed policy file still denies all calls.

Witness

A hash chain signed by the operator lets anyone detect edits, reordering, and deletions other than cutting off the tail, made by someone who does not hold the signing key. It cannot detect the tail being cut off (a verifier given only the file has no expected length), nor the key holder rewriting history and re-signing it. A witness narrows both: the gate sends signed checkpoints {count, last_entry_hash, ...} to an independent party, which records each one and signs a receipt saying when it saw it. The wire contract is WITNESS_SPEC v0.5, a public edition of the spec the witness serves at https://api.headlessoracle.com/v1/witness/spec (the served spec is authoritative; v0.5 adds optional accounts to v0.4 and changes nothing a verifier checks). Both https://api.headlessoracle.com and https://headlessoracle.com serve the witness paths (checked 9 Oct 2026, below); the spec names https://api.headlessoracle.com as the base URL.

What has been exercised, and what has not. This client is tested against a local stub of the spec (test/witness-stub.ts), and was run by hand on 7 Oct 2026 against the witness's own source served locally (wrangler dev): anonymous and account-key checkpoints, verify --witness with a pinned key, 402 payment_required, 403 witness_plan_required, the anonymous-cap 503 and the account 429 quota_exceeded.

On 9 Oct 2026 the 0.5.0 client code (packed from this repository and installed in a clean directory) was run against production, anonymously, with no account key:

• Two one-receipt chains were made with chirindo proxy around the mock MCP server in examples/observe-only-agent/. chirindo checkpoint sent one to https://api.headlessoracle.com and the other to https://headlessoracle.com; each POST was accepted and returned a signed receipt (witness.checkpoint/1, public_key_id key_2026_v1), written to the sidecar.

• The witness key was taken from GET /v5/keys (both hosts returned the same key) and pinned. chirindo verify --key ... --witness <host> --witness-key <pinned> read VALID and WITNESSED through count 1 for both chains against both hosts, each host returning the receipt the other host stored, so the two hosts read one store.

• One byte of a chain changed (one hex digit of event.args_hash): verify read TAMPERED — entry 0: request_commitment mismatch, exit 1. That edit is caught by the chain itself; the run did not exercise a witness-only detection (a cut-off tail or a re-signed rewrite) against production. With a wrong pinned witness key, verify read TAMPERED — witness receipt at count 1 invalid, exit 1.

• GET /v1/witness/checkpoints?kid=...&session_id=... returned the stored receipt on both hosts.

Not exercised against production: account keys, the 402 paid path, the 403 and 401 key refusals, the anonymous daily cap (503) and the account quota (429), rate limits, fork receipts, multi-page next_after reads, checkpoints from a long-running proxy (--checkpoint-every, the shutdown checkpoint), and a key rotation.

# checkpoint the head of a chain, optionally witnessed
chirindo checkpoint <chain> --witness https://api.headlessoracle.com

# or let the proxy do it: every N receipts, and once more on clean shutdown
chirindo proxy ... --checkpoint-every 50 --witness https://api.headlessoracle.com -- <cmd>

# verify the chain against the witness (pin the witness key: hex or JWK file)
chirindo verify <chain> --key <identity.json> \
  --witness https://api.headlessoracle.com --witness-key <hex>

• Checkpoints are written to the sidecar <chain>.witness.ndjson, one line {checkpoint, witness_receipt, witness_error} each, never into the chain file (a checkpoint inside the live chain would make every later receipt write fail). chirindo checkpoint refuses (exit 1, nothing written) unless the chain verifies VALID under the identity's key, that key signed the chain, and its kid is an RFC 7638 thumbprint (not a legacy ed25519/... kid).

• A witness failure on the proxy is one sidecar line with witness_error and one stderr line; the tool call is never delayed, altered or denied (see the fail-closed table). On clean shutdown the proxy checkpoints the head and waits at most 5 s for the witness before exiting. A killed process writes no final checkpoint: everything after its last witnessed checkpoint is protected by the chain alone.

• What is sent to the witness: the checkpoint's kid, session_id, count, last_entry_hash, ts, sig, the constant v and type fields, and the gate's public key; plus, as with any HTTPS request, the sender's IP address. Never arguments, results or records.

• A --session-id longer than 128 characters cannot be witnessed.

• verify --witness <url> queries the witness (following next_after pages); verify --witness-file <sidecar> --witness-key <key> reads the receipts from the sidecar, offline. --witness-file trusts the sidecar the operator supplied; only querying the witness is independent of the operator. Output on success is the usual VALID lines, then WITNESSED through count N, received_at T, witness key <hex> and M records after the last witnessed checkpoint are not witness-protected. A cut-off tail, a rewrite, or a fork reads TAMPERED naming the lowest failing count; no receipts reads NO WITNESS: ... (exit 1); a witness key fetched from /v5/keys instead of pinned is named and exits 1. --witness-name sets the expected receipt witness member (default headlessoracle.com).

Receipt signature verification needs no Headless Oracle service when you verify with --key, with --jwks <your URL>, or through the receipt's own jwks_uri. Without --key or a --jwks URL, a receipt with no jwks_uri, and with $RECORDER_JWKS_URL unset, is checked against keys fetched from https://headlessoracle.com/.well-known/jwks.json; pinning a thumbprint (--expect-thumbprint) removes the need to trust that fetch. Evidence from Headless Oracle's witness relies on Headless Oracle, and only for truncation and rewrite detection.

A runnable demonstration against a local stub witness (not Headless Oracle's) is in examples/e015-4-kit/.

Witness accounts (v0.5, optional)

Without an account, checkpoints go to a pool shared by everyone. An Evidence plan key gives the operator its own daily quota:

# from a file (preferred; whitespace around the key is trimmed)
chirindo proxy ... --witness https://api.headlessoracle.com \
  --witness-account-key-file ~/.config/chirindo/witness.key -- <cmd>

# or from the environment
CHIRINDO_WITNESS_ACCOUNT_KEY=ho_live_... chirindo checkpoint <chain> \
  --witness https://api.headlessoracle.com

• Precedence: --witness-account-key-file wins; CHIRINDO_WITNESS_ACCOUNT_KEY is read only when the flag is absent, and only when --witness is given. The key is never accepted as a command-line value (--witness-account-key is refused), so it does not land in shell history or process listings. --witness-key is unrelated: it is the witness's public key.

• The key must be ho_live_ followed by 64 lowercase hex characters; anything else exits 2 before any request is made, with a message that never echoes it.

• It is sent as Authorization: Bearer <key> on the checkpoint POST only. Reading receipts (GET /v1/witness/checkpoints, GET /v5/keys) is public and never carries it. Redirects are refused, so it is never re-sent to another host. It is never written to the sidecar or printed.

• A refused key (401 invalid_key, 402 payment_required, 403 witness_plan_required) or a used-up quota (429 quota_exceeded) is a witness failure like any other: one sidecar line with witness_error, and on the proxy the tool call is permitted unchanged. A 401 is never answered from the anonymous pool instead. When the reply carries the spec's upgrade object (429 quota_exceeded, or the anonymous-cap 503), chirindo prints at most one stderr line naming its pricing URL; it does not retry.

Limits, as the spec states them (all best effort):

Only a POST that stores a new checkpoint counts; repeating an already-stored checkpoint is free. Account checkpoints do not count against the anonymous cap, and that cap being reached does not block an account, so an account key closes the "anyone can use up the daily cap" gap below for that operator (not the rate limit per address). Receipts are identical for both pools; nothing in a receipt says which pool stored it. Prices are not in this README: the witness returns them in its upgrade object and at https://headlessoracle.com/v5/pricing.

Honest limits

A witness receipt is Headless Oracle's signed statement that at received_at it was shown a checkpoint signed by the key with that thumbprint; it is only as reliable as Headless Oracle and its signing key. It does not prove who controls the key, that the records are true, or that they were written at the times they carry.

What it adds to the chain alone: a cut-off tail, or a rewrite by the key holder (edit, delete or reorder, then re-sign and re-link), of any history up to the last witnessed checkpoint, made after that checkpoint was witnessed, is detected when the chain is compared with the witness's receipts. Edits, reordering, and deletions other than cutting off the tail, made by anyone without the signing key, are already detected by the chain and its signatures, with no witness. Cutting off the tail is not detected by the chain alone, whoever does it.

What it does not detect:

• records after the last witnessed checkpoint, which can be cut off or rewritten undetectably;

• a history rewritten before it was first witnessed (compare received_at with the records' ts: that gap is the exposure window);

• a session the operator never presents, because the verifier looks up only the session_id of the chain it was given, and a rewrite under a new session_id or a new key starts with no receipts;

• unwitnessed periods: a failed checkpoint never blocks a tool call, a killed process writes no final checkpoint, and because the witness accepts checkpoints from anyone without an account, anyone can use up the rate limit or the daily cap and leave other operators' checkpoints unwitnessed until it resets;

• a wrong witness: nothing here lets a verifier detect Headless Oracle omitting receipts from a query, signing a false received_at, losing stored rows, or the theft of its signing key; receipts are not kept in a public append-only log with consistency proofs.

Two honest cases verify TAMPERED:

• A chain file exported before its session ended verifies TAMPERED once later checkpoints are witnessed, because it looks truncated; verify the complete session file.

• Two chains written under the same key and session_id (for example a reused --session-id with a new chain file) are a fork to the witness and verify TAMPERED.

Verifying against a sidecar file trusts the operator who supplied it. Only querying the witness is independent of the operator.

Receipts are individually signed but the list is not: a mirror, proxy or modified client can drop receipts, hiding a cut-off tail or rewrite after the last receipt it returns. Pinning the witness key does not detect a dropped receipt; query https://api.headlessoracle.com directly.

After a key rotation /v5/keys lists only the new key; receipts signed under an earlier key verify only against a copy pinned before rotation.

The witness is operated by Headless Oracle, which also publishes the gate software. It is independent of the operator, not of Headless Oracle. Anyone who knows a (kid, session_id) pair can read that session's checkpoint counts and times. No arguments, results or records are ever sent to the witness.

Showing a gate ran before an action

A receipt's gate_receipt (in its gate object) is the hash of the receipt computed while gate_receipt still held the placeholder "self"; it is not the receipt's entry hash. The entry hash is computed from the signed record without sig, "sha256:" + hex(SHA-256(JCS(record without "sig"))), and that computed value is what ordering evidence should carry. Outside evidence about a receipt says these things and no more:

1. A witness receipt. A witnessed checkpoint whose count covers the gate receipt's entry is the witness's signed statement that it received that checkpoint at received_at, on the witness's clock. It says nothing about whether the gate's contents are true or whether the action was authorized.

2. The transaction itself. Where the action is an on-chain transaction, the strongest ordering evidence is to carry the gate receipt's entry hash, computed as above, in the transaction itself, so the blockchain orders them without trusting any clock.

3. Refusals. A witness also records refusals (DENY receipts, once a checkpoint covers them), which leave nothing on-chain.

The served spec's honest_limits member (https://api.headlessoracle.com/v1/witness/spec) states what a witness receipt does and does not attest.

A worked example of all three, run against production with an offline checker, is in examples/ordering-evidence/.

Chirindo trial recorder

The trial recorder lets a merchant's checkout service record each agent cart as a signed, hash-chained entry and have the witness countersign checkpoints of that chain. It is the recording and witnessing half of the gate, with nothing blocked: record() is synchronous, never throws and returns a plain object; every call that makes no entry is recorded in gaps.ndjson, or, if that file cannot be written, in one stderr line; the recorder never fails your checkout.

What it does not show

These are limits of the evidence an entry can support, copied verbatim from the evidence verifier (examples/evidence-bundle/lib/limits.mjs):

• L1. A gate entry is the operator's own signed statement of what its gate saw and decided. The bundle does not show that a decision was wise, that the agent read the instruction correctly, or that any member's contents are true.

• L3. The witness receipt is Headless Oracle's signed statement that at received_at it was shown a checkpoint signed by the key with that thumbprint; it is only as reliable as Headless Oracle and its signing key. The witness is operated by Headless Oracle, which also publishes the gate software: it is independent of an operator other than Headless Oracle, not of Headless Oracle.

• L5. This version checks instructions only in the minimal profile of Annex A. Verifiable Intent and AP2 members are carried with their digests and marked PRESENT, not verified.

• L7. Times on the principal's, the issuer's, the operator's and Headless Oracle's clocks are those parties' statements, and the block timestamp is set by the block producer within the chain's rules. Only the orderings that need no clock rest on signatures and hashes alone.

• L24. v0.10. For a card payment, the payment proof is the card network's authorization record, which the issuer holds; this bundle neither carries nor verifies it. What this verdict shows is whether the decision and the order the gate recorded were witnessed before the charge's authorization time as stated, and whether that order matches the stated charge: the stated charge and its time are the statements of the person running the verifier, taken from the processor's records.

• L25. v0.10. The committed order is the agent's statement at decision time, as the gate recorded it: its merchant, items, prices, refundability, dates and places are what the agent's call named. The bundle does not show that the merchant fulfilled that order, that the charge was for it beyond the fields compared, or that an item's attributes are true.

What it records, and where

Each record() that passes its checks writes one entry. Its tool name is record_agent_cart, its decision allow, and its arguments are exactly { "order": <order> }, plus "agent_context": <agent_context> when given: the place where spec v0.10 section 4.3, "The committed order", reads the order. Entries are the format the proxy writes, so chirindo verify <chain> --key <dir>/identity.json reads them unchanged. The chain holds only hashes; the arguments are kept beside it, one file per entry, because the evidence format needs them.

Under the data directory (chirindo init --dir <dir> creates its identity; the recorder never creates keys):

The 32 hex characters are the start of args_hash after sha256:; no file name holds a colon. Directories are created 0700 and files 0600 where the OS honours modes. Each recorder process writes its own chain under <dir>/chains/, so finding an order means looking across all of them.

record({ order_ref, order, agent_context?, call_seq? }) returns { ok: true, entry_hash, args_hash, count, session_id }, or { ok: false, reason, paths, session_id }, where paths holds RFC 6901 pointers of the members that decided it. Member names that are plain identifiers ([A-Za-z0-9_-], at most 64) are written into paths as they are, any other name as ~invalid-key; values never are. The input is checked, then copied once into a snapshot that every later check and the write use. The checks run in this order, and the first failure decides:

If a part-written line cannot be cut from the chain, the chain is broken: one gap line with reason chain-broken says so, and every later record() in that process is refused with write-failed. That chain's file then ends in the part-written line, so chirindo verify rejects it.

Allowed members: order_ref, order, agent_context, call_seq. In agent_context: channel (acp, ucp, ap2, mcp, stripe-approval-hook or other); platform_signature (header_name, value, optional key_id and alg, each at most 4,096 characters); payment_token_limits (currency, three upper-case letters; max_amount_minor, a decimal string with no sign and no leading zero; optional expires_at, an RFC 3339 UTC time naming a real instant, so 2026-02-30T00:00:00Z and 24:00:00 are refused); agent_name (at most 256 characters); mandate (format ap2, vi or other; value at most 65,536 characters). In the order, the members of spec section 4.3, with an item name of at most 256 characters.

Screening reads only the free-text fields: an item's name, location and category, and agent_context.agent_name. A card-number-like token is 13 to 19 contiguous digits, or digit groups of 3 to 6 digits joined by one kind of separator throughout (single spaces or single hyphens), 13 to 19 digits in all, whose first digit is 2 to 6 and which passes the Luhn check, standing alone (not touching a letter or digit). In an item's name, location and category an e-mail-like token (local@domain.tld) is refused too. Identifiers, references, SKUs, amounts, dates and the other agent_context fields are your own values and are never screened. Screening is a guard against a mistake, not a data-protection control: do not put personal data in an order.

When to call it

Each time your code creates or changes the agent's cart, and once more just before your code calls your payment processor. Inside a payment platform's approval hook, pass the cart only, and keep any witness wait inside that hook's own time limit.

Pass call_seq, a counter your code increments for every call, so that the numbers that never arrived can be found: call_seq is kept with each entry (in its retained file) and with each failure (in its gap line). Your counter restarts when your process restarts, so the numbers repeat across restarts.

awaitWitness(entry_hash, maxMs) resolves, never rejects, with { ok: true, received_at, covering_count } once a verified witness receipt covers the entry, or { ok: false, reason } with timeout (at maxMs, capped at 3,500), no-witness, unknown-entry (not one of this process's last 10,000 entries), stopped, closed or internal. At most one witness POST is in flight; a new head waits while one is, and the later checkpoint covers the heads in between. So the record made just before the charge can wait up to one witness round trip more than its own POST: allow for that in your wait limit. On quota_exceeded, payment_required, invalid_key or witness_plan_required the recorder stops sending until 00:00 UTC or a restart, and says so once in the log.

close(timeoutMs) (default 5,000) sends a final checkpoint of the head unless it is already witnessed or in flight, and waits at most that long; a POST still unanswered is recorded as witness_timeout, and a head never sent because sending was stopped as witness_stopped.

After a restart, the recorder looks at up to 10 earlier chains in the data directory, signed by this identity, that no running recorder holds and that have not changed for 10 minutes, and sends one checkpoint for each head that no receipt covers; after each of its own POSTs, one such head goes before its next own head. It reads only a chain's first line and last complete line (a torn last line is ignored): it does not verify the lines between. Such a checkpoint's receipt carries a late received_at, and shows that the head existed by then; it does not show that the chain verifies. A stale lock left by a crashed process can make that session look live if its process id has been reused; such a chain is then skipped.

What reaches the witness

Each checkpoint POST carries the checkpoint members v, type, session_id, count, last_entry_hash, ts, kid and sig, and the gate's public key; the account key, when one is configured, as Authorization: Bearer on that POST only; and, as with any HTTPS request, your server's IP address. Never an order, an argument or an entry. The timing file holds counts, hashes, times and outcomes only, never a key, a signature or an error body.

Gaps

Every record() that makes no entry appends a line to gaps.ndjson: { ts, session_id, order_ref_sha256, call_seq, reason, paths }. Some failures the recorder never sees: your own timeout, the recorder unreachable, your process restarting. Count your own failed calls and report each with reportGap({ order_ref, call_seq?, reason }) (or POST /gap), where reason is caller-timeout, unreachable or other. If a gap line cannot be written, the call still returns, and one stderr line says so.

Erasure

chirindo trial-erase --dir <dir> --args-hash <sha256:hex>
chirindo trial-erase --dir <dir> --order-ref <order_ref>

Removes every retained file for that args_hash, or for that order reference (matched by its SHA-256), and prints one JSON line per file, then {"removed_count": N}. It never touches a chain, a sidecar, gaps.ndjson or witness-timing.ndjson, and empty retained-file directories may remain. After erasure:

• the chain still shows that an entry existed, and its hashes;

• a hash of short or guessable content can itself identify that content;

• a gap line still holds the SHA-256 of an order reference and its call_seq;

• the witness's receipts (count, session id, head hash, times) are kept by Headless Oracle;

• the evidence format can no longer be completed for that record.

A retained file whose entry was never appended (the process stopped between the two writes) is an orphan: no entry names its hash, so it is evidence of nothing.

The loopback endpoint

chirindo trial-recorder --dir <dir> --server-label <name> [--port 7419] \
  [--host 127.0.0.1|::1] [--token-file <file>] [--jwks-uri <https-url>] \
  [--witness <base-url> --witness-key <hex|jwk-file> --witness-name <name>] \
  [--witness-account-key-file <path>]

It prints {"listening":"http://127.0.0.1:<port>"} once bound and serves POST /record, POST /await ({ "entry_hash", "max_ms" }), POST /gap and GET /health. Call http://127.0.0.1:<port>, not localhost: the Host header must name the bound address and port. Each POST needs Content-Type: application/json; bodies are capped at 256 KB and a duplicate member is refused. A reply is 200 only when its ok is true; a refused input is 422, an awaitWitness timeout 504, and a failure on the recorder's side 503, each with the result object. Without --token-file, any process on this host can call it; with one, each POST needs Authorization: Bearer <token>. GET /health needs no token and shows the session id.

In your service

The trial recorder ships from 0.6.0: npm install @headlessoracle/chirindo@0.6.0.

Create one recorder per process. The package is ESM only:

import { createTrialRecorder } from "@headlessoracle/chirindo/trial-recorder";

const recorder = createTrialRecorder({
  dir: "/var/lib/chirindo",
  serverLabel: "checkout",
  witness: { baseUrl: "https://api.headlessoracle.com", name: "headlessoracle.com", pinnedKey: "<hex>" },
});
const r = recorder.record({ order_ref: "R-1001", order, call_seq: n++ });
// ... on shutdown
await recorder.close();

From CommonJS, load it with const { createTrialRecorder } = await import("@headlessoracle/chirindo/trial-recorder"). createTrialRecorder throws on invalid options or a missing identity; nothing after it throws. The package now has an exports map, so deep imports such as @headlessoracle/chirindo/dist/... no longer resolve; only @headlessoracle/chirindo/trial-recorder, @headlessoracle/chirindo/purchase-check and @headlessoracle/chirindo/package.json do. The chirindo command is unchanged.

Purchase check (before you charge)

The purchase check is for a payment provider whose agents buy for its customers. Before minting a credential or charging, the provider's code sends the instruction it signed for its customer and the order to Chirindo. Chirindo answers allow or deny with the reasons, and writes each decision it makes on a well-formed request as a signed, hash-chained receipt before it answers.

The purchase check ships from 0.6.0: npm install @headlessoracle/chirindo@0.6.0.

What it claims, and its limits

Before you charge, Chirindo checks each purchase against the instruction you signed for your customer, refuses one outside it, and keeps a signed, chained record of each decision it makes and its reason.

That claim holds only with these five limits:

• Limit 1. It checks only purchases the provider sends through it. A purchase made around it is not checked, and a deny binds only if the provider obeys it. A repeat allow is not a second purchase.

• Limit 2. The instruction is signed by the provider, stating what its customer approved. Chirindo does not see or verify the customer's approval. The provider also holds the gate key. The record is the provider's own signed, chained record, with checkpoints sent to Headless Oracle's witness.

• Limit 4. Spend is not summed across purchases. Each purchase is checked against the cap and uses are counted, so an instruction allows up to max_uses purchases, each up to the cap. Counts are shared only within one directory and one process.

• Limit 5. The order is what the caller states. The cap is judged on its stated total, and Chirindo does not see the charge. Only an after-the-fact comparison with the charge shows a mismatch (L24).

• Limit 6. These leave no receipt: input refused at step 1, record-failed, and a repeat (it returns the earlier receipt). evaluatePurchase is a dry run, not a record.

The full list:

1. It checks only purchases the provider sends through it. A purchase made around it is not checked, and a deny binds only if the provider obeys it. A repeat allow is not a second purchase.

2. The instruction is signed by the provider, stating what its customer approved. Chirindo does not see or verify the customer's approval. The provider also holds the gate key. The record is the provider's own signed, chained record, with checkpoints sent to Headless Oracle's witness.

3. The description is carried and signed over, not checked. The v0.1 mappers set no item or category limits.

4. Spend is not summed across purchases. Each purchase is checked against the cap and uses are counted, so an instruction allows up to max_uses purchases, each up to the cap. Counts are shared only within one directory and one process.

   • Start-up re-reads every chain in purchase-chains/ to rebuild the counts, so start-up time grows with history.

5. The order is what the caller states. The cap is judged on its stated total, and Chirindo does not see the charge. Only an after-the-fact comparison with the charge shows a mismatch (L24).

6. These leave no receipt: input refused at step 1, record-failed, and a repeat (it returns the earlier receipt). evaluatePurchase is a dry run, not a record.

7. Today's evidence-bundle verifier does not read check. In a bundle a deny shows only as a record that cites no instruction; its reason is read from the receipt itself. A verifier that reads it is planned.

8. The witness is Headless Oracle's own, not independent (L3).

9. The MCP gate does not check purchases (v0.2).

10. A later evidence bundle judges the instruction's time window at the charge's authorization time, as the processor states it, not at the time of the check. A charge authorized after valid_until shows as outside the instruction, even when the check allowed it in time.

The API

The package is ESM only. Create one check per data directory and process:

import { createPurchaseCheck } from "@headlessoracle/chirindo/purchase-check";

const pc = createPurchaseCheck({ dir: "/var/lib/chirindo" }); // after `chirindo init --dir /var/lib/chirindo`
const r = pc.check({ instruction: instructionJsonText, order });
if (r.decision === "allow") {
  // charge: r.receipt is the signed receipt of this decision, already written
}
// ... on shutdown
await pc.close();

createPurchaseCheck({ dir, serverLabel?, jwksUri?, witness?, now? })

• It loads the identity chirindo init made, and refuses a kid that is not the RFC 7638 thumbprint of its key.

• It takes an exclusive lock on the directory.

• It verifies every chain in <dir>/purchase-chains/.

• It throws on invalid options, a held or stale lock, or a chain that does not verify. Nothing after it throws.

check({ instruction, order }) is synchronous and never throws.

• instruction is the instruction's JSON text, so that a duplicate member can be detected. It is an Annex A.3 signed-instruction-ed25519/0.3 instruction with card limits only.

• order is the committed order of spec 4.3.

• It returns { decision, reasons, exceeded, card_limits, instruction_sha256, at, receipt, repeat }.

• An allow is returned only after its receipt is written. Any failure to write gives deny record-failed: alone on what would have been an allow, after the deny's own reasons on a deny.

• An identical order checked again under the same instruction, merchant and order reference returns the earlier allow, with repeat: true. It writes nothing and uses nothing.

The receipt. It is an ordinary chirindo receipt, so chirindo verify reads it. It has tool_name "check" and a top-level check member holding the decision, its reasons and the order's digest. On an allow, event.outcome is "executed", which on a purchase-check receipt means "the check allowed". The arguments of each receipt are kept in <dir>/purchase-args/.

evaluatePurchase(instruction, order, { kid, at, usesSoFar }) is the same judge as a dry run. It writes nothing and consumes no use. Its answer is neither a decision nor a record, and a provider must not charge on it.

signInstruction(body, privateKey) signs an instruction body with the provider's Ed25519 key, as principal.

The HTTP form

chirindo purchase-check --dir <dir> --token-file <file> [--port 7420] \
  [--host 127.0.0.1|::1] [--server-label <name>] [--jwks-uri <https-url>] \
  [--witness <base-url> --witness-key <hex|jwk-file> --witness-name <name>]

It prints {"listening":"http://127.0.0.1:<port>"} once bound, and serves POST /v1/check with the body { "instruction": "<JSON text>", "order": { ... } }.

Requests:

• The token is required: each request needs Authorization: Bearer <token>.

• Call http://127.0.0.1:<port>, not localhost: the Host header must name the bound address and port.

• The body needs Content-Type: application/json. It is capped at 256 KB, read as UTF-8 that must be valid, and parsed strictly.

• No CORS header is sent.

Status codes:

The CLI and the library cannot run on one directory at once, because of the lock.

A stale lock

If a process holding the directory ends without closing (a crash, a kill), <dir>/purchase-chains/.lock remains. The next start refuses and names the lock's pid and path. Check that no process holds the directory, then remove that file. The lock is never removed automatically.

Reasons

Every reason matches exactly one pattern of the frozen vocabulary of purchase-check/0.1, published in docs/purchase-check-reasons.md and exported as PURCHASE_REASON_PATTERNS. A change to the vocabulary is a new check.v.

Mappers

The mappers follow each provider's public documentation as read on 30 Oct 2026; no provider has reviewed or endorsed them.

They build an instruction body from a provider's own approval object. The provider then signs it as principal, with signInstruction. The functions:

• mapCrossmintOrderIntent takes an order intent.

• mapBasisTheoryAllowance takes an allowance.

• mapPravaMandate takes a mandate together with the session that set it up.

Each takes { principalKey, agentKids, maxUses, approvedAt, iat? }.

What a mapper sets:

• An amount becomes minor units by a fixed currency table (CURRENCY_EXPONENTS). An unknown currency refuses. Precision finer than the minor unit is floored, so the cap is never above what was approved.

• A merchant becomes the origin of its URL (merchantIdOf), and the provider must build order.merchant_id with the same function.

• Times become Z instants.

What a mapper refuses: each refusal is a MapperError with a stable code. Among them: an unknown currency, a URL with userinfo or a scheme other than http or https, a time that does not parse, and a Prava session with more than one merchant entry.

For Prava: valid_until is the earlier of the mandate's validUntil and the approval time plus the session's effective_until_minutes (default 15). For a recurring mandate, that can make an instruction valid for minutes, narrower than the mandate itself. A caller may sign a fresh instruction for each charge.

Getting started

The goal of this section: take you from "I use Cursor or Claude Code with my own MCP server" to "Chirindo is observing it, and I can independently verify a receipt." Six steps, all done locally except the verify hop which contacts a public JWKS endpoint.

1. Install

For now: git clone Chirindo, npm install && npm run build. Note the absolute path to the repo — the next step uses it.

Generate the gate's signing identity:

node <ABSOLUTE-PATH-TO-CHIRINDO>/dist/cli.js init --dir <ABSOLUTE-PATH-TO-CHIRINDO>/.gate
# -> initialized chirindo at <abs path>
#    kid:          <rfc7638-thumbprint>

2. Configure your client

Copy the template that matches your MCP client into the right place:

• Cursor: config-examples/cursor-mcp.json → <your-project>/.cursor/mcp.json (or ~/.cursor/mcp.json)

• Claude Desktop: config-examples/claude_desktop_config.json → ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

Then edit two things — see config-examples/README.md:

1. Replace every <ABSOLUTE-PATH-TO-CHIRINDO> with the absolute path to your Chirindo checkout.

2. Replace the line after "--" with your real downstream MCP server's command (the template ships with npx -y @your-org/your-mcp-server as a deliberately-invalid placeholder so a forgotten edit fails loudly). The documented default is npx-form on every platform; a node + absolute-path fallback is documented for clients whose PATH does not include npx.

Restart your client. You should see my-server-gated in its MCP indicator. Chirindo is now wrapping your server.

3. Run

Use your agent as you normally would — anything that calls a tool on your downstream server is being observed.

4. Observe

Each MCP session writes a chain file:

ls <ABSOLUTE-PATH-TO-CHIRINDO>/.gate/sessions/

One JSONL line per tools/call. Each line is a signed receipt covering the request and its outcome. Inspect one:

head -n 1 <ABSOLUTE-PATH-TO-CHIRINDO>/.gate/sessions/<session-id>.jsonl

You'll see event.type:"mcp_call", event.decision:"allow", gate.result:"act", and an Ed25519 signature in sig.

5. Verify (the payoff)

node <ABSOLUTE-PATH-TO-CHIRINDO>/dist/cli.js verify \
  <ABSOLUTE-PATH-TO-CHIRINDO>/.gate/sessions/<session-id>.jsonl \
  --jwks

The bare --jwks form resolves the gate's public key from the recorder's published JWKS document over HTTPS, then verifies every record's signature and the hash-chain linkage. Expected output:

VALID — N entries, chain intact, all signatures verified, session <id>
verified under key <thumbprint> resolved from <source> (<origin>)

The second line is not decoration. It names which key verified the chain and where that key came from (flag, receipt-jwks, env, or default). Read it carefully, because:

Without a pin, VALID means the chain is internally consistent under the key that was presented — NOT that it was signed by Headless Oracle or anyone in particular. A self-describing receipt tells the verifier where to fetch a key; on its own that only proves the chain agrees with that key.

To assert who signed, pin the key's RFC 7638 thumbprint:

chirindo verify <chain> --jwks --expect-thumbprint <tp>
# or a JSON trust file: --trust-file trusted-keys.json
#   ["<tp1>", "<tp2>"]   |   { "thumbprints": ["<tp1>"] }

--expect-thumbprint is repeatable. If the resolved key's thumbprint is not in your pinned set, verification is INVALID — untrusted_key (exit

1. even when every signature checks out — the chain is consistent, but not with a key you trust. The key binding is enforced before the signature: every v1 receipt carries the signer's thumbprint in its signed bytes, and the verifier compares the thumbprint of the key it resolved to that committed value first, so a substituted key at the jwks_uri cannot pass by verifying under itself.

You just verified, against a public key over the internet, what your gate recorded — no trust in this repo, no trust in the binary you ran, no trust in the client you used. The receipts prove the gate fired for each call and that the chain is recomputable from the signed records. They do not prove the action was "safe," only that the decision is captured, signed, and tamper-evident (not tamper-proof: an edit, a reorder, or a deletion other than cutting off the tail breaks the hash chain and is caught by chirindo verify; cutting off the tail, and a rewrite by the key holder, are caught only against witnessed checkpoints, see Witness).

Offline alternative (no network): --key <ABSOLUTE-PATH-TO-CHIRINDO>/.gate/identity.json.

6. Enforce (opt-in)

Enforcement is one line in policy.json. Add a deny rule for a tool on your downstream server that you'd rather never have happen:

{
  "deny": [
    { "tool": "shell_exec", "reason": "blocked by policy" }
  ]
}

Restart your client. Ask the agent to call shell_exec. The downstream never receives the call; the agent sees isError: true; a DENY receipt with event.decision:"deny" and gate.result:"halt" is appended to the chain. Run chirindo verify again — still VALID.

That's the observe→enforce transition: same gate, same receipts, one extra line in policy.json.

Honesty about what isError: true does and doesn't do

MCP's spec describes tool execution errors this way:

Tool Execution Errors contain actionable feedback that language models can use to self-correct and retry with adjusted parameters.

So isError: true blocks the action (we never forward to the downstream) but does NOT block the agent — the LLM may retry. Each retry is independently evaluated by the gate and will be denied again if it matches policy. The destructive side-effect is prevented; the agent's attempt count is not capped. Productization may want a stronger "this conversation cannot perform this action" mechanism than per-call denial (e.g. a session-scoped lockout, or a protocol-error escalation after N denials).

What the harness proves and what it does NOT

Proves (from the test suite)

• The proxy correctly parses and mediates newline-delimited JSON-RPC per MCP stdio transport spec.

• On DENY, the downstream server never receives the call — proven by the in-memory test asserting a flag set on the fake downstream's data handler stays false, AND by the spawn test asserting the fake server's "DESTRUCTIVE delete tool ran" stderr line never appears.

• ALLOW + DENY + FAIL-CLOSED each emit a receipt with gate populated per the schema, including the continuity invariant gate.request_commitment == record.request_commitment.

• The recorder's verify accepts every produced chain unchanged, and catches a tampered receipt with the legible request_commitment mismatch reason.

• The OS-pipe path works (spawn integration test).

• chirindo verify (CLI e2e test) reports VALID on a fresh chain, TAMPERED on a mutated chain, and exit 2 on conflicting --key + --jwks — same vocabulary the recorder uses, because it is the recorder's verify engine wired into the chirindo binary.

• The strict-ingest gate fails closed at the JSON parse boundary: an integer token outside the IEEE-754 safe range (unsafe_number) or a repeated object member at any depth (duplicate_member) is rejected before it is hashed, so a non-recomputable input can never enter a receipt or pass verification. The gate sits on both the receipt-writing hash path and chirindo verify's chain parse (strict-json.test.ts, conformance-strict-parse.test.ts).

Also verified (beyond the unit suite)

• Conformance corpus, three-way and enforced. The canonicalization (RFC 8785 / JCS) and RFC 7638 key-binding vectors are verified byte-for-byte across three implementations — Chirindo's own, an independent RFC 8785 library (@truestamp/canonify), and the external vector author — and the strict-ingest reject vectors fail closed with the expected reason. The binary enforces the same canonicalization and strict-ingest the vectors check; it is not a separate reference implementation. (Harness: conformance/verify-harness/.) This is deliberately not the claim that a published package "passes a conformance suite". That claim requires a re-verification run against the published artifact, and no such run has been made. Published versions and their dates are listed on npm (https://www.npmjs.com/package/@headlessoracle/chirindo?activeTab=versions). From 0.5.1 on, each release is published from its tag, and the release notes record a file-by-file comparison of the published tarball with that tag. Everything above was verified against the source tree, not against the tarball the registry serves.

• Live fetch/verify, end-to-end. The verify path was exercised by hand against the live published JWKS over HTTPS, and all three verdicts behaved as specified: a well-formed chain resolved its key and returned VALID; a receipt whose committed key_thumbprint was altered returned INVALID (key_binding_mismatch), rejected before the signature check; and a chain signed by a key the JWKS does not publish returned UNVERIFIABLE (issuer_key_unresolvable) with no silent fallback to a default key.

Does NOT prove

• The real client honors isError: true as a block in the agent loop — for clients other than the ones already tested. Cursor's agent halts cleanly on a deny-shaped result (proven live, see SPIKE_RESULT.md); whether Claude Desktop and other MCP clients surface it the same way to the LLM must be confirmed per client.

• COSE output mode. Receipts are currently JSON/Ed25519/base64url. A COSE_Sign1 variant is the productization step for ecosystem interop.

• Argument-level policy. The current policy matches on tool name (+ optional server label) only. Production needs argument matchers (e.g. "deny shell_exec whose command starts with rm").

• Per-action UI — the proxy emits stderr logs and writes JSONL; Claude Desktop / Cursor will not surface "this action was gated" in any operator-visible way without further integration.

License

Apache-2.0. See LICENSE.