Mobile Authenticator & Recovery

Scope

Strong authentication only works when enrollment, recovery, and support workflows are clear to the people who administer them. This guide keeps the operator-facing identity assurance model and removes the low-level implementation detail used by the internal product manual.

Current Scope

Portal now ships two first-party native app projects:

1. ios/PortalAuthenticator
2. android/PortalAuthenticator

Both apps now truthfully ship the same narrow mobile slice:

1. local manual TOTP entry, edit, delete, and QR import
2. local rolling-code display and on-device vault persistence
3. optional local biometric or device-auth gate over already-stored app state
4. fixed Cadres development Portal web and API endpoints
5. generate and keep a device-bound Ed25519 key on the device
6. complete the browser-issued linked-device challenge
7. inventory linked devices
8. revoke linked devices
9. load a narrow governance approvals inbox and detail
10. approve or deny governance access requests through the linked-device action-challenge flow
11. report public-vault readiness and blocker state as groundwork only

Portal’s backend now also ships the next mobile-safe workflow contract:

1. governance requester catalog, submit, history, and detail facades
2. governance approval and access-review read facades
3. support-access read facades
4. device-authenticated action challenges for governance, access-review, and support-access decisions

The current native apps consume only the governance approval subset of those workflow routes. Governance requester UI, access-review UI, and support-access UI remain non-shipped mobile scope.

What this wave still does not ship:

1. push approvals
2. public-vault account bootstrap or sync
3. backup or recovery
4. governance requester UI, access-review UI, or support-access UI
5. mobile session review or revoke

Pair A Device

The current branch still does not ship a browser pairing issuer UI. Challenge issuance still happens through the authenticated contract from a normal Portal browser session.

Workflow:

1. Open either native app:
2. iOS: run ios/PortalAuthenticator from Xcode on an iPhone or simulator
3. Android: open android/PortalAuthenticator in Android Studio and run it on an Android 13+ device or emulator, or use the checked-in Gradle wrapper from the repo root
4. Use the app’s fixed Cadres development environment configuration.
5. From an authenticated Portal browser session in a normal membership context, issue a link challenge.
6. Paste the returned challenge_token into the native app.
7. Review or edit the device label and complete Link Device.

Expected result:

1. the native app signs the canonical pairing payload with its local Ed25519 key
2. Portal records the linked device and writes audit action auth.mobile_device_linked

Sign In To Manage Linked Devices

The app now uses Portal’s real first-party native auth path:

1. open the Devices tab
2. review the fixed Cadres development Portal web and API endpoints shown in the app
3. tap Sign In With Portal
4. complete the browser-based Portal login, MFA, tenant selection, or consent flow inside the native browser handoff:
5. iOS uses ASWebAuthenticationSession
6. Android uses Custom Tabs plus the app’s deep-link callback
7. Portal redirects back to the app’s registered callback URL

After sign-in, the Devices tab can:

1. list the authenticated user’s linked devices for the selected tenant context

Operational Notes

1. The iOS app stores the Ed25519 private key in Keychain with device-only accessibility. It does not claim Secure Enclave backing in this tranche.
2. The Android app stores a software-generated Ed25519 private key encrypted at rest with an Android Keystore wrapping key. It does not claim hardware-backed or StrongBox-backed Ed25519 in this tranche.
3. The native apps use Portal’s real browser-based sign-in, not embedded fake login forms.
4. The backend accepts the native token path only on the explicit linked-device-management and mobile-workflow facade routes. Other browser-session-sensitive self-service routes still rely on the existing portal_session contract.
5. High-value mobile workflow decisions now require both the canonical Portal identity checks and a one-time linked-device action challenge signed by the exact active device key.
6. Both apps now ship local biometric or device-auth gating only over already-stored app state. That local unlock is not a second auth model and not a permission bypass.
7. Neither app ships push, camera, notification, public-vault account bootstrap, backup, recovery, requester workflow UI, access-review UI, support-access UI, or native session review in this wave.