Concepts¶
approvo has a small number of moving parts. This page explains each one by the attack it defends against.
The request¶
An ApprovalRequest describes what is being approved: a kind
("software-release", "db-migration", anything), a subject (a
kind-specific JSON object), who asked, which policy governs it, and a
window (not_valid_after).
Its request_id is the canonical hash of its identity-bearing fields —
not including created_at. Two create_request calls with the same
arguments therefore produce the same id.
- Attack: duplicate requests from retries. A network blip makes your
BFF call
create_requesttwice. Without content-addressing you get two approval workflows for one release. With it, the second call returns the first request. (ADR-0001) - Attack: "that's not the request I approved". See
context_digestbelow.
The decision¶
A Decision is an approver's approve or reject. It carries:
request_id— which request,context_digest— the canonical hash of the full request body (includingcreated_at) as the approver saw it,verdict,approver_id,decided_at, an optionalcomment,idempotency_key.
It travels as a DSSE envelope: the canonical decision bytes plus one or more detached signatures over the PAE of the payload type and body.
- Attack: forge an approval. Without a signature, anyone with write
access to your database inserts a
decision.recordedrow and the release ships. With one, the forged decision fails signature verification, never counts toward status, andverify()flags it. - Attack: bait-and-switch. Casey approves version 1.4.0. An attacker
edits the request's subject to 6.6.6 and ships that. The decision's
context_digestno longer matches the request body, so the approval stops counting andverify()reports it. - Attack: replay a decision onto another request. The envelope's
context_digestis bound to one specific request body; it will not satisfy any other. - Attack: a compromised BFF signs for everyone. Use detached
signing:
prepare_decisionhands the client the bytes to sign, and the private key never reaches your server. (ADR-0002)
The key directory¶
KeyDirectory maps a keyid to a KeyRef: a public key, its owner, and a
validity window (not_before / not_after / revoked_at). It is the
trust root at verification time.
A signature counts only if its keyid resolves to a key that was valid at
the decision's timestamp — not at verification time. An approval signed
with a then-valid key that was later rotated or revoked stays valid;
revoked_at only invalidates signatures dated after the revocation.
- Attack: use a stolen, since-revoked key. Revoke it in the directory
with a
revoked_attimestamp; every decision dated after that stops counting. - Attack: tamper with the directory itself. approvo cannot help here —
see Security model. Protect
keys.jsonlike the ledger.
The policy¶
A Policy is data, not code: allowed_approvers (ids and/or
role:<name>), threshold, optional require_distinct_roles,
separation_of_duties, reject_is_terminal, max_age_seconds,
required_subject_fields. It is content-addressed too.
A request pins policy_digest at creation. Evaluation refuses to run
against a policy whose current hash does not match the pin
(PolicyMismatch).
- Attack: weaken the policy after the fact. Drop the threshold from 2
to 1, or add yourself to
allowed_approvers, then point to an already-approved request. The pinned digest no longer matches, soget_statusandverifyboth refuse. (ADR-0005) - Attack: approve outside the mandate.
evaluateis a pure function that only counts decisions from eligible approvers, inside the window, bound to the right request body. See Policies.
The ledger¶
Every state change is a LedgerEntry appended to an append-only,
hash-chained log: request.created, decision.recorded,
status.changed, checkpoint.published. Each entry's entry_hash covers
all its content; each entry's prev_hash is the previous entry's
entry_hash.
- Attack: edit a past entry. Its
entry_hashno longer reproduces. - Attack: edit it and recompute its hash. The next entry's
prev_hashnow points at the old hash — chain broken. - Attack: delete, insert, or reorder. Sequence numbers are contiguous from zero and the chain links break.
- Attack: two BFF instances append at once. The store's uniqueness
constraint on
(log_id, seq)lets exactly one win; the loser retries against the new head. (ADR-0008)
The ledger is the only source of truth. get_status replays a
request's events and re-runs the policy on every call.
Checkpoints¶
A Checkpoint is a signed tree head: "as of tree_size entries the
Merkle root was root_hash",
signed by the log key. Publish them regularly and pin the latest one
somewhere the ledger operator cannot write.
- Attack: rebuild the entire ledger consistently. The hash chain
alone only proves internal consistency — a
TRUNCATE+ re-insert produces a perfectly self-consistent lie. A pinned checkpoint doesn't reproduce against the rebuilt log, soverify(trusted_checkpoint=…)proves the fork. (ADR-0003)
Records vs. views¶
Two read models, deliberately separate:
Record (get_status) |
RequestView (get_view / query) |
|
|---|---|---|
| Source | replayed from the ledger | projection store |
| Cost | O(decisions) |
one indexed row read |
| Freshness | always exact | eventually consistent |
| Use for | gating decisions | list / filter / search UIs |
| If lost | n/a | rebuild_projections() |
Gating on a RequestView is a security bug. (ADR-0009)
Idempotency¶
- Requests: content-addressed, so retries are inherently safe.
- Decisions:
reservean idempotency key, do the append,completeit with the result. Concurrent retries seewon=Falseand replay the stored response. A key reused with a different fingerprint raisesIdempotencyConflict. (ADR-0007)
Time¶
Timestamps are RFC 3339 UTC strings, produced by an injectable Clock.
Policy evaluation (window expiry, key validity) uses these. approvo trusts
the clock you give it; a trusted external time source (RFC 3161) is a
future extension. Until then, frequent externally-pinned checkpoints bound
how far a colluding operator could backdate. See Security
model.