Skip to content

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

envelope_from_challenge(challenge: DecisionChallenge, signatures: list[dict]) -> dict

Assemble a DSSE envelope from a challenge and client signatures.

signatures is [{"keyid": ..., "sig": <base64>}, ...].

submit_signed_decision async

submit_signed_decision(envelope: dict) -> Record

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

get_status(request_id: str) -> Record

Authoritative status, re-derived from the ledger. Gate on this.

get_view async

get_view(request_id: str) -> RequestView | None

Projected view. Fast, cached, not authoritative.

query async

query(query: RequestQuery | None = None) -> Page[RequestView]

List/filter requests for a UI. Reads projections, not the ledger.

rebuild_projections async

rebuild_projections(*, batch_size: int = 500) -> int

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

checkpoint() -> Checkpoint

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

new_nonce() -> str

128 bits of randomness, for intentionally duplicate requests.