ApprovalService¶
approvo.service.ApprovalService ¶
create_request
async
¶
create_request(*, kind: str, subject: dict, requested_by: str, policy_id: str, not_valid_after: str, nonce: str | None = None) -> ApprovalRequest
Create a request, or return the identical existing one.
The request id is the canonical hash of the identity-bearing
fields, so calling this twice with the same arguments returns the
same request without a second ledger entry — retries are safe with
no idempotency key needed. Pass a fresh nonce (see
:func:new_nonce) to intentionally open a second request for the
same subject.
submit_decision
async
¶
submit_decision(*, request_id: str, approver_id: str, verdict: Verdict, signer: Signer | None = None, comment: str = '', idempotency_key: str = '', authn: dict | None = None) -> Record
Sign and record a decision in one call (server-side signing).
The signature comes from, in order: an explicit signer argument;
otherwise the injected :class:~approvo.crypto.signing.SigningService
(org/custodial key resolved for this log). Convenient for internal
tools — but the backend holds signing authority, so for production
gates prefer :meth:prepare_decision + :meth:submit_signed_decision.
When a custodial decision_issuer key signs, pass authn —
evidence you authenticated approver_id (see ADR-0012). It is
bound into the signature and recorded for audit.
prepare_decision
async
¶
prepare_decision(*, request_id: str, approver_id: str, verdict: Verdict, comment: str = '', idempotency_key: str = '') -> DecisionChallenge
Produce the exact bytes an approver's client must sign.
Hand the challenge to the client. It signs pae_b64 (base64 of
the DSSE pre-authentication encoding) with the approver's key and
returns the signature, which you pass to
:meth:submit_signed_decision. No private key ever reaches your
backend, so a compromised backend cannot forge an approval.
envelope_from_challenge
staticmethod
¶
Assemble a DSSE envelope from a challenge and client signatures.
signatures is [{"keyid": ..., "sig": <base64>}, ...].
submit_signed_decision
async
¶
Record a decision the approver's client signed.
Everything is re-derived from the envelope — the challenge is advisory and is never trusted. The envelope must carry a valid signature for the approver it names, bind to the current request body, and fall inside the approval window.
get_status
async
¶
Authoritative status, re-derived from the ledger. Gate on this.
get_view
async
¶
Projected view. Fast, cached, not authoritative.
query
async
¶
List/filter requests for a UI. Reads projections, not the ledger.
rebuild_projections
async
¶
Recompute every view from the ledger. Safe to run any time.
Use after a schema change, a projection-store loss, or whenever you want to prove the read model still agrees with the ledger.
checkpoint
async
¶
Publish a signed tree head over the current log.
Signed by the injected :class:~approvo.crypto.signing.SigningService
(checkpoint key resolved for this log) or, failing that, by
log_signer.
verify
async
¶
verify(*, trusted_checkpoint: Checkpoint | None = None, from_seq: int = 0, limit: int | None = None) -> VerificationReport
Re-derive everything and report every integrity check.
Walks the ledger streaming, so it is safe on a large log. For
routine checks against a huge ledger, pass from_seq (and the
expected_prev_hash implied by a pinned checkpoint) to verify
only the segment written since you last looked.
Module-level helpers¶
approvo.service.new_nonce ¶
128 bits of randomness, for intentionally duplicate requests.