Policies¶
A policy is a frozen dataclass — plain data you can review, sign, store,
and diff. It is content-addressed: policy.digest is the canonical hash
of its fields, and every request pins that digest at creation.
Fields¶
from approvo import Policy
Policy(
id="release-v1",
kind="software-release", # must equal the request's kind
allowed_approvers=( # ids and/or "role:<name>"
"role:release-manager",
"role:qa",
"user:security-oncall",
),
threshold=2, # distinct counting approvals needed
require_distinct_roles=("qa", "sre"), # approvals must cover each of these
separation_of_duties=True, # requester's own approval never counts
reject_is_terminal=True, # any counting reject => rejected
max_age_seconds=7 * 24 * 3600, # window from request creation
required_subject_fields=("artifact_digest", "version"),
)
How evaluation works¶
approvo.policy.engine.evaluate(request, decisions, policy, identities,
at_time) is a pure function. Given the same inputs it always returns
the same PolicyResult. The service passes it only decisions whose DSSE
envelope already verified for the approver they name.
A decision counts when all of these hold:
decision.context_digest == request.context_digest()— bound to this exact request body.- The approver is eligible: their id is in
allowed_approvers, or they hold a role listed asrole:<name>. separation_of_dutiesis off, or the approver is notrequest.requested_by.decided_atis at or before the window close (min(not_valid_after, created_at + max_age_seconds)).
Then:
- One voice per approver — their latest decision wins, so re-submitting the same verdict is idempotent and changing your mind before the window closes is allowed.
- If
reject_is_terminaland any counting decision isreject→rejected. - Else if counting approvals ≥
thresholdandrequire_distinct_rolesare all covered →approved. - Else if
at_timeis past the window →expired. - Else →
pending, withreasonsexplaining what is outstanding.
Examples¶
Two-person rule¶
One from each of two teams¶
Policy(id="cross-team", kind="schema-migration",
allowed_approvers=("role:dba", "role:app-owner"),
threshold=2, require_distinct_roles=("dba", "app-owner"))
Two DBAs approving is still pending — the app-owner role is uncovered.
Break-glass: single approver, short window¶
Policy(id="break-glass", kind="incident-access",
allowed_approvers=("role:incident-commander",),
threshold=1, max_age_seconds=3600)
Allow self-approval (e.g. personal-data export requests)¶
Policy(id="self-serve", kind="data-export",
allowed_approvers=("role:employee",), threshold=1,
separation_of_duties=False)
The policy store¶
ApprovalService takes a PolicyStore — anything with
get(policy_id) -> Policy. InMemoryPolicyStore ships for tests and
small deployments. Back it with a table, a config repo, a bundle from your
policy pipeline — whatever fits. The only rule: once a request has pinned
a digest, the policy it resolves to must keep hashing to that digest, or
get_status raises PolicyMismatch.
To change a policy for new requests, add a new version
(release-v2) rather than mutating release-v1. In-flight requests keep
evaluating against the rules they were opened under — which is usually
exactly what an auditor wants to see.
Externalizing eligibility¶
If "who may approve" gets more complex than roles and ids (attribute
rules, org-chart lookups, time-of-day), compute the eligible set in your
BFF and express the policy as an explicit allowed_approvers list per
request kind, or wrap evaluate with your own pre-filter. approvo keeps
the counting logic — thresholds, distinct roles, separation of duties,
windows — because that is the part that has to be reproducible years
later. See ADR-0005.