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.