box/docs/PHONE-OTP.md

# Phone-OTP Login Flow

> **Box is the main surface.** All operator work goes through Box (box.muse-dev.online). The web UI, `box` CLI, and agents share the same API endpoints. No UI-only powers.

**Status:** proven on bl (2026-10-03)
Alternative to the email-OTP path for muse.ai login; same form, same OTP
mechanics, different delivery channel (SMS instead of email).

## When

Fresh chrome-box profile + NetVM node, no session yet. Used when the
account's primary identifier is a mobile number rather than an email.

## Prerequisites

- chrome-box profile + NetVM node provisioned on bl (1:1: profile == node
  == Warp identity). See `README.md` "Provisioning a node".
- A real mobile number that can receive SMS — **human-provided per login
  attempt, never stored, never written to any registry, log, or memory.**
  The registry records only `phone_otp: yes` as the route.

## Flow

1. Launch headless Chromium in the node's netns:
   `netvm-chrome.sh --headless <profile> https://muse.ai`
   (CDP on by default for automation.)
2. Via CDP: open muse.ai → "Log in" → inline form "Mobile number or email".
3. Enter the human-provided mobile number (E.164) and Continue.
4. If the number maps to **multiple Meta accounts**, an account-selection
   UI appears (observed 2026-10-03: "Meta Account" vs "piparada" with
   Instagram avatar — see `docs/meta-account-selection.png`). Select the
   intended account.
5. muse.ai sends a 6-digit SMS OTP.
6. Human reads the SMS and relays the OTP (board/chat handoff, or direct).
7. Enter the OTP via CDP and submit. Session established, cached in the
   profile.
8. Verify: revisit muse.ai via CDP, confirm logged-in markers, no login
   wall. Flip the `ACCOUNTS.md` row to `active`.

## Operator/human split

- **Agent:** browser launch, CDP automation, form entry, OTP submission,
  verification. Never sees the phone number beyond the single form entry.
- **Human:** provides the number per attempt, receives the SMS, relays the
  OTP. The only party that ever holds the number.
- **Operator:** provisions the node, coordinates, maintains the registry.

## PII rules

- The phone number is PII. It goes into the login form and nowhere else —
  not the registry, not logs, not chat history, not memory.
- OTP codes are relayed, used once, never stored.
- If the number is linked to other accounts (e.g. Facebook), that linkage
  is managed via the separate Meta Accounts Center API
  (`docs/META-ACCOUNTS-API.md`) — never conflated with the OTP flow.

## Failure modes

- **OTP expired:** re-request from the form (note rate limits if hit).
- **SMS delayed:** wait 60s, retry once, then escalate (possible carrier
  filtering).
- **Session lost on browser restart:** observed 2026-10-03 (`pip` node) —
  re-auth from step 1. If recurrent, investigate session persistence.
- **Wrong number entered:** restart from step 1.
- **Account-selection ambiguity:** confirm with the human which account
  before proceeding; never guess.

## Provenance

- 2026-10-03: `646` — phone OTP login completed (first Meta Account
  option), bl.
- 2026-10-03: `pip` (piparada) — phone OTP login completed; session lost
  on browser restart, needs re-auth.
- 3 OTP codes used 2026-10-03 without rate-limit issues.
- Egress: bl Warp (104.28.195.181) accepted without bot-detection friction.