Metadata-Version: 2.4
Name: algovoi-keystone-compose
Version: 0.3.1
Summary: Verify agentic-action keystone CHAINS offline (RFC 8785 JCS + SHA-256): @name-bound composition with scope-subset, not-revoked and journey assertions, plus the agent-passport client. Cython-compiled submodules of the algovoi_keystone namespace.
Author-email: AlgoVoi <chopmob@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/chopmob-cloud/algovoi-keystone
Project-URL: Substrate, https://docs.algovoi.co.uk/keystone
Keywords: keystone,jcs,rfc8785,agent,passport,falcon,pqc,governance,conformance,composition,audit
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: algovoi-keystone>=0.2.0
Requires-Dist: algovoi-substrate>=0.5.0
Requires-Dist: rfc8785>=0.1.2
Provides-Extra: passport
Requires-Dist: pqcrypto>=0.3.0,<1; extra == "passport"
Dynamic: license-file

# 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.

```json
{
  "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`](examples/keystone-golden.json)
for the canonical chain (its values match the published `keystone_v1` composition
in [algovoi-jcs-conformance-vectors](https://github.com/chopmob-cloud/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):

```python
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):

```python
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:

```bash
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

```bash
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.
