algovoi-keystone

One command to prove an agentic-action keystone chain composes end to end.

Everyone has receipts. The keystone is the composition: the proof that identity binds to authority binds to policy binds to the decision binds to the execution binds to one trust verdict, every link a content address, recomputable offline, with no issuer contact. A plain receipt checker recomputes individual digests. This recomputes the whole chain and proves it binds.

keystone verify chain.json

keystone chain: passport_ref  ->  mandate_ref  ->  policy_ref  ->  policy_bound_ref  ->  decision_ref  ->  execution_ref  ->  trust_query_ref
------------------------------------------------------------
  OK  passport_ref
      sha256:b3594e33...
  ...
  OK  trust_query_ref
      sha256:18fb601a...  binds passport_ref, mandate_ref, policy_bound_ref, decision_ref, execution_ref
------------------------------------------------------------
KEYSTONE VALID: 7/7 links compose, recompute byte-for-byte, no issuer contact.
  capped: trust_query_ref is one verdict over [...] in order.

Tamper any link and that link, and every link that binds it, diverge:

  BAD execution_ref
      ^ recomputed sha256:8a71a2a3... != declared sha256:f6e2bfc1...
KEYSTONE BROKEN at execution_ref: ... every link that binds it is therefore not provable from these bytes.

(keystone verify exits 0 if the chain composes, 1 if any link is broken, 2 on a malformed chain.)

Why this exists

As agent governance matures from "here is a signed receipt" to "prove the whole chain composed, that the decision that authorized is the one that executed is the one the verdict covers", a receipt is no longer enough. The keystone is that proof, and it is the one piece of the agentic-governance stack that cannot be reproduced by cloning a single digest construction, because it requires the whole composition. This is the turnkey verifier for it.

The chain format

A keystone chain is an ordered list of links. Each link's reference is "sha256:" + SHA-256(RFC 8785 (JCS)(preimage)). Composition is structural: a preimage refers to an earlier link by @name, so a downstream reference cannot be computed without the exact upstream reference.

{
  "schema": "algovoi-keystone-chain/v1",
  "canon": "jcs-rfc8785-v1",
  "chain": [
    { "name": "passport_ref",  "preimage": { "agent_id": "agent-001", "...": "..." } },
    { "name": "decision_ref",  "preimage": { "agent_ref": "@passport_ref", "mandate_ref": "@mandate_ref", "policy_bound_ref": "@policy_bound_ref", "verdict": "ALLOW" } },
    { "name": "execution_ref", "preimage": { "decision_ref": "@decision_ref", "outcome": "COMMITTED", "...": "..." } },
    { "name": "trust_query_ref", "preimage": { "subject_refs": ["@passport_ref", "@mandate_ref", "@policy_bound_ref", "@decision_ref", "@execution_ref"], "trust_outcome": "TRUSTED" } }
  ]
}

An optional "ref" on a link is the declared output; the verifier recomputes and checks it. See examples/keystone-golden.json for the canonical chain (its values match the published keystone_v1 composition in algovoi-jcs-conformance-vectors).

Agent passports (client half)

An Agent Passport is a Falcon-1024 (FIPS 206) signed credential that binds an agent DID to scopes, a spend bound, and an expiry. The issuer runs inside the AlgoVoi payment rails; this package is the client an agent developer needs, both sides of the wire:

Present your passport on an outbound call (needs nothing beyond the base install):

from algovoi_keystone import load_credential, x402_headers, a2a_message_metadata

cred = load_credential()                 # from $ALGOVOI_AGENT_PASSPORT, or pass a path
headers  = x402_headers(cred)            # {"X-Agent-Passport": "<cred>"} on an x402 request
metadata = a2a_message_metadata(cred)    # A2A message metadata carrying the passport

Verify a received passport fully offline, against the issuer's published key, with a stock trust base (rfc8785 + pqcrypto, no AlgoVoi service in the trust path):

from algovoi_keystone import verify_passport, resolve_keys_from_wellknown, fetch_crl

# resolve the issuer key + revocation list once (or pin them from a local trust store)
keys = resolve_keys_from_wellknown("https://pay.issuer.com")   # {kid: pk_bytes}
crl  = fetch_crl("https://pay.issuer.com", next(iter(keys)))

v = verify_passport(cred, issuer_keys=keys, crl=crl, required_scope="pay:invoice")
if v:                                     # True only when status == "active"
    print("ok:", v.agent_did, v.scopes, v.spend_limit_microusd)
else:
    print("refused:", v.status, v.error_code)   # revoked | expired | invalid | unverifiable

Verification is fail-closed: with no key resolved or no revocation confirmation, the verdict is unverifiable, never a default-trust active. The credential's kid is checked against sha256(pk)[:16] of the resolved key, so a swapped key cannot validate. Install the verifier extra with pip install 'algovoi-keystone[passport]'.

From the CLI:

keystone passport inspect  <credential>                       # decode (does NOT trust)
keystone passport verify   <credential> --issuer-url https://pay.issuer.com --scope pay:invoice
keystone passport verify   <credential> --keys keys.json --crl crl.json    # strictly offline
keystone passport present  <credential> --x402                # emit the header to attach

Install

pip install algovoi-keystone            # Python:  keystone verify chain.json
pip install 'algovoi-keystone[passport]'  # + Falcon-1024 passport verify
npm  install -g @algovoi/keystone       # Node:    keystone verify chain.json

Python and Node produce byte-identical references on every link. RFC 8785 JCS + SHA-256 is the whole dependency; the verifier makes no network call.

License

Apache-2.0. (c) AlgoVoi. Keep the NOTICE attribution when you redistribute.