Security model¶
Mirrors SECURITY.md
in the repo. Read it before you rely on approvo for anything that matters.
What approvo makes tamper-evident¶
Given an intact key directory and, ideally, an externally pinned
checkpoint, verify() detects all of the following no matter what
happens to the ledger storage:
- Forged approvals — a decision counts only if its DSSE envelope
verifies against either a key registered to the claimed approver or an
authorized
decision_issuerkey for thislog_id, valid at the decision's timestamp. - Content swaps — decisions bind to
context_digest; change a byte of the request and every approval stops counting. - History rewrites — hash-chained entries; edits, deletions, insertions, reordering all break the chain, and wholesale rebuilds diverge from signed checkpoints.
- Policy swaps — requests pin
policy_digest; evaluation refuses a policy that no longer hashes to the pin. - Status fabrication — status is re-derived on every read; a tampered
status.changedevent changes nothing.
What approvo does NOT protect against¶
- Destruction of the store. Tamper-evidence is not backup. An attacker who drops the ledger destroys the evidence. Mirror it.
- A compromised key directory. If an attacker can register their key
as
user:casey, they can sign as Casey. Protect the directory at least as well as the ledger; distribute it out of band; review changes to it. - A compromised approver key. Signatures prove key possession, not
human intent. Use short validity windows,
revoked_at, and — for detached signing — client-side keys in an HSM or platform keystore. - Trusted time. Timestamps come from the injected
Clock. A malicious operator colluding with a key holder could backdate a decision. An RFC 3161 timestamp source is a planned extension; until then, frequent externally-pinned checkpoints bound the backdating window. - Confidentiality. The ledger is plaintext by design. Keep secrets out of subjects and comments.
- A dishonest verifier. Run
verify()on infrastructure the ledger operator does not control, with an out-of-band key directory and a pinned checkpoint. - Server-side / custodial signing key custody.
submit_decisionhas your backend hold the signing key — either a per-person key or, with aSigningService, one orgdecision_issuerkey that signs for everyone. Either way a compromised backend can forge approvals for known identities. Useprepare_decision+submit_signed_decisionfor anything that gates production.
Operational checklist¶
- Publish a checkpoint after every batch of activity and on a schedule; pin the latest one where the operator cannot write it.
- Keep the log signing key on separate infrastructure from approver keys.
- Deny
UPDATE/DELETEon the ledger table to the application credential. - Gate deploys on
status == "approved"and a subject match andverify().raise_for_failures()— all three. - Partition logs by
log_idso no single chain is a global write bottleneck.
Reporting a vulnerability¶
Open a GitHub security advisory on the repository, or email the address in
pyproject.toml. Please don't file public issues for suspected
vulnerabilities.