> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fau.run/developer/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile clients (iOS / Android)

> Approval apps — pairing, device auth, prompts, push, and how to replace the reference client.

## 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](https://docs.fau.run/developer/apps/overview.md).\
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](https://docs.fau.run/developer/reference/device-signing.md)).
* 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

```mermaid theme={null}
sequenceDiagram
  participant A as Agent
  participant N as Node
  participant E as Expo
  participant P as Phone app
  A->>N: tools/call
  N->>N: create approval
  N->>E: push domain+code
  E->>P: banner
  P->>N: GET /papi/pending signed
  P->>N: POST /papi/decide signed
  A->>N: retry tools/call
```

Reachability: phone uses HTTPS to the **node hostname** (usually via relay SNI). Pairing
QR `host` must be reachable off the LAN.

## Responsibilities

| Must | Must not |
| - | - |
| Generate Ed25519 on device | Exfiltrate the secret to your servers |
| Implement `/papi` signing bit-for-bit vs vectors | Trust push JSON for decisions |
| Poll pending | Skip polling because “push exists” |
| Clear token on logout (best effort) | Expect node to hold your APNs `.p8` |

## State machine (session)

```mermaid theme={null}
stateDiagram-v2
  [*] --> Unpaired
  Unpaired --> Paired: POST /papi/pair OK
  Paired --> PushReady: push-token registered
  Paired --> Paired: pending/decide/pause
  PushReady --> Paired: token clear / rotate
  Paired --> Unpaired: user removes / Mac removes device
```

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

| Field | Allowed |
| - | - |
| `approval_id` | yes |
| `agent_domain` | yes |
| `match_code` | yes (`^\d{2}$`) |
| `kind` | yes (`access` / `send` / `test`) |
| mail subject/body/question | **no** |

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

| Concern | Notes |
| - | - |
| Notification permission | iOS prompt; Android 13+ runtime permission |
| Channels | Android channel `approvals`, high importance |
| Background | iOS `remote-notification` background mode |
| Biometrics | Best-effort; Settings must say when unavailable |
| Store distribution | Separate EAS Submit tracks; same protocol code |

## Compliance

Your signer **must** reproduce the published vectors:

→ [Device signing vectors](https://docs.fau.run/developer/reference/device-signing.md)

Also see [Wire specification](https://docs.fau.run/developer/protocol/spec.md) § Phone API. Reference app tests
(`apps/phone`) exercise the same vectors when you have the source.

## Failure modes

| Failure | Behavior | Recovery |
| - | - | - |
| Node unreachable | Show plain “keep Mac awake” | Retry with backoff; queue decides |
| Approval expired | Decide fails | User/agent starts a new request |
| Push denied | Status = denied | Polling still works |
| Token dead | Node clears on Expo error | Re-register on next launch |
| Signature skew | 4xx | Fix device clock |

## Ship the reference app

```bash theme={null}
cd apps/phone
npm test && npx tsc --noEmit
eas credentials -p ios    # APNs key on the EAS project
eas build -p ios --profile preview
# pair → Send test alert → real approval
```

## Replace the reference app

You may ship a completely different UX if you keep the contracts. Checklist:
[App checklist](https://docs.fau.run/developer/apps/checklist.md).

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.

## Related

* [Apps overview](https://docs.fau.run/developer/apps/overview.md)
* [Phone API](https://docs.fau.run/developer/apps/phone-api.md)
* [Push](https://docs.fau.run/developer/apps/push.md)
* [Node](https://docs.fau.run/developer/protocol/node.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.