# Runtime Authority Mandate Check

Runtime human-authority enforcement for consequential agent actions.
An agent asks, before any consequential act, whether a live human mandate
authorizes this exact action right now. Four answers: approve, confirm,
escalate, block.

## What this does

Credential services answer who an agent is. Mandate Check answers a
different question: is THIS action, right now, inside a live human
mandate? It applies to any consequential act: purchasing, posting,
writing, changing state, or invoking a downstream tool.

What makes it different:

- Live action authorization, checked at execution time. Identity and
  static policy are checked once; mandates are checked every time.
- Four decisions instead of a binary yes/no: approve executes, confirm
  and escalate route to the human, block refuses with reasons.
- Delegation-tree aware: sub-agent mandates only shrink, the daily
  total is shared across the whole tree, and one revocation halts
  every branch, including work already in motion.
- Everything lands in a hash-linked audit trail the human can verify.

## Base URL

https://mandate-check.onrender.com

## Endpoints

POST /v1/bootstrap
  One call, working mandate. Send {} or customize.
  Example:
    curl -X POST https://mandate-check.onrender.com/v1/bootstrap \
      -H "Content-Type: application/json" \
      -d '{"principal_name":"demo","agent_name":"agent-1"}'
  Response includes your mandate_id, your limits, and literal example
  bodies for every next call (in the "next" field).

POST /v1/check
  Ask before any consequential action. Gate on "execute".
  Example (a payment):
    curl -X POST https://mandate-check.onrender.com/v1/check \
      -H "Content-Type: application/json" \
      -d '{"mandate_id":"mnd_abc","action":"pay","amount":30,"presenter":"agent-1"}'
  Example (any non-monetary act, same call):
    -d '{"mandate_id":"mnd_abc","action":"write","presenter":"agent-1"}'
  Response:
    {"decision":"approve","execute":true,"reasons":[],"latency_ms":0.2}
  decision is approve | confirm | escalate | block.
  execute is true only for approve.

POST /v1/delegate
  Mint a narrower mandate for a sub-agent. Scopes and limits only shrink.
  Body: {"mandate_id":"mnd_abc","audience":"sub-1","scopes":["pay"]}

POST /v1/revoke              Body: {"mandate_id":"mnd_abc"}
POST /v1/revoke_principal    Body: {"principal":"human:demo-xxxxxx"}
GET  /v1/audit/{principal}   Hash-linked event chain + chain_verified flag.
GET  /healthz                Liveness.

## How the agent should use this

1. POST /v1/bootstrap once. Save mandate_id and principal from the response.
2. Before every consequential action (a payment, a post, a write, a
   state change, a tool call), POST it to /v1/check. If execute is
   true, act.
3. If decision is "confirm" or "escalate", STOP and route to your human
   with the reasons. Do not retry with a smaller amount to sneak under.
4. If "block", do not act. The reasons say why.
5. Spawning sub-agents? Give each one a delegated mandate via /v1/delegate,
   never your own. The daily total is shared across all of you.
6. Never cache an approve. Mandates expire and humans revoke. Ask each time.
7. When your run ends, GET /v1/audit/{principal} and hand your human the
   verified chain. That is your proof you stayed inside your authority.

Demo service: in-memory, rate-limited (120/min), your principal is your own
sandbox. Reference implementation of the same semantics: the auth: mandate
plugin + guarded_purchase scenario in the Nanda Town repo (NandaHack PR).
Concepts: AIHAPI working draft, OTIS Labs. Patents pending. otislabs.ai