Build an approver app

Any app can carry approvals: a phone app, a chat bot, a relay. The app moves messages; the person signs the exact action hash with their own enrolled key, at the assurance the route demands. The contract is docs/APPROVAL_API.md.

• Registration, and who signs it
• Authentication
• Poll, stream, webhook
• The challenge per key type
• Publishing a decision
• Enrolling keys at each assurance level
• examples/approver_bot.py, walked through
• How the receipt records it
• Every approval route the authority serves

Registration, and who signs it

A device registers with a one-time enrollment code that the principal issues (POST /approvers/{approver}/enrollment-codes, principal-signed); one call to POST /approvals/enroll registers its app key and enrolls the person's signing key. A server app (relay, bot) is registered by the principal's signature (POST /approvals/apps) for named approvers.

Authentication

Every later call carries Authorization: Situs-App kid=<app kid>, ts=<unix>, sig=<hex>, the app key's signature over the hex sha256 of METHOD\nPATH_WITH_QUERY\nts\nsha256_hex(body). Stale or replayed requests are refused; keep ts strictly increasing.

Poll, stream, webhook

• Poll GET /approvals/pending?approver=&since= with the cursor it returns.
• Stream GET /approvals/stream (server-sent events; resume with Last-Event-ID).
• Webhook: a server app's URL receives each event with a Situs-Signature header.

Events and webhooks are signed by the authority; pin its key from https://situs-vm.o11r.com/api/authority/.well-known/keys.json.

The challenge per key type

Publishing a decision

POST /approvals/{grant_id} with the approver, approve or reject, the action hash and the signature. Repeating the same decision returns the current state; a different one on a decided grant is refused. Poll the item until resolution.receipt_id fills.

Enrolling keys at each assurance level

A route in a mandate demands a level (software by default). A key below it gets assurance_insufficient and the grant stays pending: no app, channel or console can lower it.

examples/approver_bot.py, walked through

• enroll: generates an app key and the person's ed25519 key, and enrolls both with a code (software assurance).
• call: signs each request as §5 says, with a strictly increasing ts.
• run_once: polls pending items, prints the card exactly, asks y/n, and posts the person's signature over challenge.digest.

uv run python examples/approver_bot.py --authority https://situs-vm.o11r.com/api/authority --code SITUS-XXXX-XXXX --approver approver_jdoe

How the receipt records it

who.approval carries the approver, kid, alg, assurance, assurance_basis (verified or declared), app_id and approved_at; signatures.approver is the signature over the action hash. The proof report grades it 4 for hardware_attested, 3 for hardware, 2 for software.

Every approval route the authority serves