What this is
A mobile client is a paired device that lets a human approve or deny agent requests. It is not an email client and not an agent SDK. Mental model: a hardware security key with a UI — the secret never leaves the phone; the node only learns decisions that verify under the registered public key. Reference app:apps/phone/ (Expo / React Native).Protocol guide for builders: Build an approval app.
This page explains protocol expectations so forks stay compatible.
Goals
- Show each approval with agent domain + match code.
- Make deny/reject the easiest action.
- Prove decisions with device signatures (Device signing).
- Optionally wake via push without putting mail in the notification.
Non-goals
- Syncing or searching the mailbox on the phone.
- Using the Mac dashboard token from a mobile binary.
- Requiring an account on your cloud to approve FAU prompts.
Place in the system
Reachability: phone uses HTTPS to the node hostname (usually via relay SNI). Pairing QRhost must be reachable off the LAN.
Responsibilities
State machine (session)
Persist:host, device_id, secret key, fingerprint, optional mail address for chrome.
Critical flows
Pair
- Parse
fau://pair?host&code&fp(code = six digits). POST /papi/pairwith pubkey + device name (kind: device_key).- Store credentials in secure storage (biometric lock when available).
- Request notification permission → Expo token →
POST /papi/push-token.
Decide
GET /papi/pending(signed).- Render from
Approvalonly — do not invent mail. POST /papi/decidewithdecision,ts,nonce.- If offline: queue the decide locally; never drop a deny.
Test push
Dashboard may sendkind: "test" / approval_id: "ap_test_push". Show success; do not
open a synthetic approval.
Push contract
On tap: refresh pending over signed HTTP, then navigate to that id.
Multi-app: one node fans out to every registered token. Your app and another vendor’s
app can both pair; there is no per-app filter today.
Your Expo/EAS project owns APNs/FCM. The node only stores
ExponentPushToken[…] and
POSTs to Expo’s HTTP API.
iOS vs Android
Compliance
Your signer must reproduce the published vectors: → Device signing vectors Also see Wire specification § Phone API. Reference app tests (apps/phone) exercise the same vectors when you have the source.
Failure modes
Ship the reference app
Replace the reference app
You may ship a completely different UX if you keep the contracts. Checklist: App checklist. Anti-patterns: mail inbox UI theater; auto-allow on notification; device secret on your backend; dashboard token in the mobile app.Design decisions
Decision: device signatures simpler than RFC 9421.Why: both ends controlled by FAU ecosystem; smaller mobile code.
Tradeoff: second auth scheme to document and vector-test. Decision: Expo as push hop.
Why: app vendors keep APNs keys; node stays dumb.
Tradeoff: Expo availability; content must stay non-sensitive.