presidio-evidence

The signed-evidence substrate of the presidio-hardened-* family. Every component that gates an action on evidence, or produces evidence for someone else to check, uses one contract: canonical JSON and SHA-256 content addressing, detached Ed25519 or HMAC-SHA256 signatures, fail-closed verification against a trust store, and provenance parents that chain payloads into a verifiable graph. Independent of Microsoft Presidio.

The library was extracted from four production implementations before they could drift apart. Seven family repositories now conform to it. Provenance parents (ADR-0002) chain classification → gate decision → training run → runtime posture → payment into one DAG, so regulatory traceability is a data structure rather than process documentation.

The contract is schemas/ + vectors/, not the code. The Python package and the Rust crate both prove conformance against the same golden vectors, and both trees ship inside the Python package. A consumer migrates by pointing its existing tests at the vectors first and swapping imports second.

Install

pip install presidio-evidence             # Layer 0 + HMAC, stdlib only
pip install 'presidio-evidence[crypto]'   # adds Ed25519 (cryptography)

Python 3.11+. The runtime has no dependencies; Ed25519 needs the crypto extra.

Use

from presidio_evidence import (
    EVIDENCE_REF_SCHEMA_ID_V3,
    build_envelope,
    content_hash,
    load_trust_store,
    sign_evidence_v3,
    verify_envelope,
)

ch = content_hash({"item_id": "D1", "status": "evidence-present"})  # Layer 0
sig = sign_evidence_v3(ch, "my-signer", "iki-gov", "D1", key=priv_hex)  # Layer 1, @3
ref = {
    "item_id": "D1",
    "framework": "iki-gov",
    "source": "my-tool",
    "source_version": "1.0",
    "ledger_ref": "run-42",
    "content_hash": ch,
    "signer": "my-signer",
    "signature": sig,
    "claimed_at": "2026-10-25T00:00:00Z",
}
envelope = build_envelope([ref], schema=EVIDENCE_REF_SCHEMA_ID_V3)

trust = load_trust_store({"my-signer": {"alg": "ed25519", "public_key": pub_hex}})
results = verify_envelope(envelope, trust, expected_framework="iki-gov")
assert all(r.verified for r in results)

Verification never raises on bad evidence: a wrong key, tampered content, a relabelled subject or an unknown signer verifies as False, with a reason per ref. A malformed envelope raises EvidenceError.

Keys (ADR-0001 D3): generate_ed25519_keypair() and public_key_hex(priv) produce trust-store entries; load_private_key(path) requires mode 0600 (or reads an environment variable with env="VAR") and never echoes key material. Key custody stays with the operator; the library stores nothing.

The contract trees are package data: schemas_dir(), vectors_dir(), schema_ids() and load_schema("presidio-hardened/evidence-ref@3").

CLI

presidio-evidence verify envelope.json --trust trust-store.json
presidio-evidence verify envelope.json --trust trust-store.json --require-subject-binding iki-gov
presidio-evidence keygen --out signer.key --signer my-signer   # 0600 file; prints the trust-store entry

verify exits 0 only if every ref verifies. It fails closed on malformed input, on refs that declare an optimistic or zk tier (this verifier checks signature attestations only, ADR-0003 D6), and on an @1/@2 ref claimed for more than one item.

The contract

Layers (ADR-0001 D1): 0 canonical JSON (strict: floats rejected) and SHA-256 content addressing · 1 detached signatures and trust-store verification · 2 approval semantics, out of scope (treasury keeps its dual control).

Every schema change is append-only (ADR-0001 D5): a published vector is never edited, and a new wire format is a new major. Verifiers accept @1, @2 and @3; a gate that needs subject binding demands @3 for its framework.

Consumers

Each consumer has a golden vector here, so a regression in any of them fails this repository's CI as well as its own.

Verify a checkout

pip install -e ".[dev]"
python scripts/generate_vectors.py --check   # vectors byte-stable
pytest tests/ -q                             # Python conformance, 100% coverage gate
cargo test --manifest-path rust/Cargo.toml   # Rust conformance

Layout

schemas/    JSON Schemas (normative)
vectors/    golden test vectors, append-only, generated by scripts/generate_vectors.py
src/        Python package: Layer 0/1, refs and envelopes, keys, CLI
rust/       Rust crate: Layer 0 and the signing messages, plus conformance tests
tests/      Python conformance suite
docs/adr/   architecture decision records
docs/       MIGRATION.md (per-consumer plan)

Roadmap

Design rationale: ADR-0001. Requirements ledger: PRESIDIO-REQ.md. Migration order: docs/MIGRATION.md. Changes: CHANGELOG.md.

Security

See SECURITY.md for supported versions, how to report a vulnerability, and the threat model.

License

MIT