Metadata-Version: 2.4
Name: algovoi-keystone-verifier
Version: 0.1.0
Summary: Independent, offline, one-call verifier for AlgoVoi keystone evidence: re-derives a keystone record, a Payment Evidence Frame, an audit chain of frames, or a full bundle from raw fields and confirms every content-addressed reference matches. Depends only on JCS RFC 8785 canonicalisation; verifies without trusting the builder packages. Runs on any algovoi-substrate version (v0/v1).
Author-email: AlgoVoi <chopmob@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://api.algovoi.co.uk
Project-URL: Documentation, https://docs.algovoi.co.uk/keystone
Keywords: x402,ap2,a2a,mpp,jcs,rfc8785,canonicalisation,agentic-payments,keystone,verifier,audit,execution_ref
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: algovoi-substrate>=0.3.0
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: pytest-cov>=4; extra == "test"
Dynamic: license-file

# algovoi-keystone-verifier

Independent, offline, one-call verification of AlgoVoi keystone evidence.

Given a keystone record, a Payment Evidence Frame, an audit chain of frames, or a full bundle of
all three, this re-derives every content-addressed reference from the raw fields and confirms it
matches the carried value. It depends **only** on the substrate JCS canonicalisation (`sha256_jcs`),
**not** on the packages that produced the evidence, so an auditor verifies without trusting the
builder. RFC 8785 JCS + SHA-256 are the whole dependency; it runs on any substrate version (v0/v1).

## Install

```
pip install algovoi-keystone-verifier
```

## Use

```python
from algovoi_keystone_verifier import verify_bundle, verify_keystone, verify_frame, verify_audit_chain

res = verify_bundle({
    "keystone": keystone_record,     # passport/mandate/policy/decision/execution/trust_query
    "frames": [pef_frame, ...],       # optional Payment Evidence Frames
    "audit_chain": audit_chain,       # optional chain of frames, capped
})
res.ok            # True iff every re-derivation matched
res.to_dict()     # {"ok": ..., "checks": [{"name","ok","detail"}, ...]}
```

It re-derives `decision_ref`, `execution_ref`, `trust_query_ref` and the chain; the PEF
`receipt_hash` and `frame_id`; the audit-chain rows (`prev_hash` linkage, genesis 64 zeros) and the
`trust_query_ref` cap; and cross-checks that frames carry the keystone's `execution_ref`. Tamper any
field and the relevant check fails.

CLI:
```
cat bundle.json | python -m algovoi_keystone_verifier      # exit 0 if every check passes
```

TypeScript twin: [`@algovoi/keystone-verifier`](https://www.npmjs.com/package/@algovoi/keystone-verifier),
byte-identical re-derivation.

## Licensing

Apache-2.0. This open verifier checks the content-addressed references (the unsigned substrate). A
commercial tier verifies the cryptographic signatures (hybrid Falcon-1024 + ML-DSA-65) and ingests
into the Compliance Command Center.

**Pinned edition for adopters, with a free key.** Pin `algovoi-keystone-verifier==0.1.0`, anchor a
`keystone_v1` (or `pef_keystone_v1`) vector hash, and keep the `NOTICE`; that four check gate earns a
free v0 licence key for `algovoi-mandate-auditor` (email chopmob@gmail.com with your import-by-hash
evidence and the `NOTICE`).

Python and TypeScript produce identical re-derivations. Redistribution must retain the `NOTICE` and
the Apache-2.0 `LICENSE`.
