Security model

Roles, approvals, scopes and what Reversi assumes.

Roles

Role	Can
agent	open runs, request tool calls, report outcomes, read its own runs
auditor	read everything: runs, plans, ledger, evidence, metrics. Changes nothing
approver	auditor, plus decide approvals
operator	approver, plus roll back, resolve unknown outcomes
admin	operator, plus the kill switch

An agent cannot approve its own call or trigger a rollback. The server enforces this by role, and the agent key’s name becomes the ledger actor: a request body cannot choose another actor. API keys and OIDC tokens map to roles; see authentication. On the gateway, operator tools live on a separate endpoint with separate credentials, so they do not exist from the agent’s point of view.

Approvals

Required by manifest, policy or content check. Bound to the arguments, single use, expiring, persisted. See approvals.

Scopes

A run is opened with a set of permissions, sealed with a SHA-256 digest. Each call checks the tool’s permission against the scope. A key may carry max_permissions, capping what runs it opens can request. If stored run state is edited, the seal no longer matches and calls block.

Kill switch

An admin can block every new call at once (POST /v1/halt, the console, or a file named by REVERSI_KILL_FILE, which reversi kill-switch on <file> creates and any number of processes watch). Rollbacks keep working: halting must never stop you from cleaning up.

Observe mode

mode: observe journals violations as would_block and lets the call run. Use it to learn what an agent does before you enforce anything.

Assumptions you must own

• The data directory or database, the key file and the signing key are protected from the agent.
• Reversi is in the only path from the agent to its tools. An agent that can call a tool directly is not governed.
• Manifests are written by someone who understands the tool. MCP-style self-declared hints are not trusted.
• TLS terminates in front of the server and gateway.

See the full threat model.