Skip to main content

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 QR host 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

  1. Parse fau://pair?host&code&fp (code = six digits).
  2. POST /papi/pair with pubkey + device name (kind: device_key).
  3. Store credentials in secure storage (biometric lock when available).
  4. Request notification permission → Expo token → POST /papi/push-token.

Decide

  1. GET /papi/pending (signed).
  2. Render from Approval only — do not invent mail.
  3. POST /papi/decide with decision, ts, nonce.
  4. If offline: queue the decide locally; never drop a deny.

Test push

Dashboard may send kind: "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.