Approvals
What you see is what you sign
Section titled “What you see is what you sign”An approval binds a display to a signature, the way banks bind a payment confirmation to its amount and payee.
| Part | Content | Bound by |
|---|---|---|
| payload | action, parameters, target, proposer (user or agent run, level, on whose behalf), catalog and policy versions, expiry | its canonical digest (RFC 8785) |
| display | rendered on your device from the payload by the action’s template, which ships inside the signed catalog | the template’s digest |
| plan | before → after per field; for a playbook every step, target and check | the plan’s digest |
| evidence | test results, a commit range, a cost estimate, each with a digest | each digest |
| confirmation | for destructive actions, the target you picked or typed | in the signed statement |
You sign one digest over all of it. The core cannot change any part without voiding your signature, and the node runs exactly this plan: if the state has drifted since, the approval is void and a new one is needed.
The display is split by trust:
- Facts: verified by the core: parameters, target, proposer and level, risk class, the deciding policy, expiry.
- Changes: before → after.
- Evidence: a verdict plus a digest, labelled as not verified by the core.
- Claims: text written by a module or an agent (a rationale, an impact estimate). Shown last, as plain truncated text, clearly labelled as unverified, never as Markdown or links. It is never the basis of the decision.
Who may approve
Section titled “Who may approve”- Quorums count distinct users, never devices. Two devices of one person are one approval.
- Nobody approves their own proposal. An agent run acts on behalf of a user, and that user cannot be the human approver of the run’s proposal. Exceptions are visible and audited: solo mode (one person alone approves their own agent, while the roster has exactly one approver) and the emergency change (self-confirmed with an incident reference, reviewed by two owners within 24 hours).
- Risky actions always need a human at level
presence. Agent reviewers may settlesafeandroutineactions understarterandstandard; understrictthey are advisory only. - Reviewer agents get the payload, facts, changes and evidence as structured data, not the proposer’s free text, so a proposer cannot talk the reviewer into anything. A profile can demand a different model than the proposer’s.
- Roles can be scoped to environments, for example an operator on staging only.
Channels
Section titled “Channels”| Channel | Key | Notes |
|---|---|---|
| iPhone app | Secure Enclave, after Face ID, Touch ID or the device code | App Attest as the key attestor under standard |
| Android app | Android Keystore (StrongBox where present), after biometrics or PIN | key attestation chain to Google’s roots |
| Mac menu bar app | Secure Enclave or keychain, after Touch ID or password | |
vcx | PKCS#11 (a YubiKey over PIV, a SoftHSM token in labs) or the Mac’s Secure Enclave | PIN per signature under strict |
The apps pair by QR code with a comparison code, list pending approvals, render the display locally and sign after a slide gesture and user verification. They do not propose, open tunnels or sign rosters by themselves; roster changes reach them as their own approvals. Notifications are only a wake-up: “an approval is waiting”, without content. The app fetches the details over mTLS.
The audit records the channel of every approval. A policy can demand a local channel for risky actions.
Losing a device
Section titled “Losing a device”Any other device of the same member, or an owner, can suspend a lost device at once (vcx device suspend, or “My
devices” in the app). Its pending decisions are dropped and the ops it approved but that have not run are voided. A
whole member can be suspended too (vcx member suspend); the nodes enforce it.