v2 stage 2 follow-up: mobile companion app (iOS + Android) for K11 + recovery + scope grants

[hanwencheng]

Context

Stage-2 hardening (#90) landed all core deliverables on Heima Mainnet except the mobile companion app. The desktop daemon --master-companion mode is the interim path today, but the architecture documents (arch.md §5a Q7, §10.1) and the v2 design intent both call out native iOS + Android as the canonical operator surface for K11-bound ceremonies.

Why we need this

K11 ceremonies require a platform passkey + biometric (Face ID / Touch ID / Windows Hello). On the laptop the WebAuthn ceremony works fine via the browser, but real-world ops (grant scope from anywhere, approve a recovery while traveling, revoke a stolen device without sitting at the laptop) demand mobile.

The recovery flow specifically benefits: when the operator's laptop is lost or compromised, they shouldn't have to find a second laptop to authorize the revoke + rotate. The phone is the natural second factor.

Scope

Bootstrap pairing

• QR scan from laptop → mobile shows {operator_omni, broker_url, k11_challenge}
• Mobile runs navigator.credentials.create against platform passkey (rp_id = companion.litentry.org per arch.md §5a.3.1)
• Mobile POSTs {cred_id, rp_id_hash, pub_x, pub_y} back to broker
• Broker submits registerAdditionalMasterDevice on SidecarRegistry
• Roles: CAP_MINT | RECOVERY (NOT SCOPE_MGMT by default — mobile-mgmt sprawl prevention)

Scope grant approval

• Mobile receives push notification (FCM/APNS) on a pending scope-grant
• Operator reviews {operator_omni, agent_omni, service, action, scope} on mobile
• Approves → Touch ID/Face ID → K11 assertion → setScopeWithWebauthn on AgentKeysScope

Recovery flow (M-of-N from mobile)

• Operator detects laptop loss/compromise
• Opens app → "Lost device — revoke & rotate"
• App constructs revokeDevice + rotateMaster payload
• M-of-N device sigs (≥ recoveryThreshold) authorize the rotation — mobile is one of N
• Submits to chain via broker relay

Out of scope (separate)

• Mobile-side cap-mint UI (agents are not master devices; agent-device-key lives in process, not on mobile)
• Push-notification infrastructure (FCM + APNS keys, server-side notification routing) — separate ops issue
• App store distribution (TestFlight beta + Play Store internal track first)

Dependencies

• ✅ Stage-2 hardening (v2 stage 2 — Hardening: K11 WebAuthn + multi-device recovery + audit/memory/email workers #90) — DONE
• ✅ agentkeys-daemon --master-companion (interim desktop path) — works today
• ❌ rp_id = companion.litentry.org configured at broker — needs DNS + nginx vhost (mirror of cred/memory/audit/email pattern from PR issue #90: co-locate audit/email/cred/memory workers on broker host (dev) #92)
• ❌ FCM + APNS server keys provisioned

Acceptance

• iOS app passes TestFlight beta
• Android app passes Play Store internal track
• End-to-end demo: laptop K11 enroll → mobile pairs → mobile approves scope grant → mobile authorizes M-of-N recovery → laptop's revoked-master cap-mints rejected within 60s

Related

• v2 stage 2 — Hardening: K11 WebAuthn + multi-device recovery + audit/memory/email workers #90 (stage-2 hardening parent — closed; this is the split-out follow-up)
• arch.md §5a.3.1 (master device pairing), §10.1 (role bitfield)