SELF-2540: Fix account recovery flow after phone restore

[transphorm]

Summary

• Add startup routing logic that detects missing keychain secrets after an iCloud restore and routes the user to account recovery instead of a broken Home screen
• Fix both recovery flows (cloud restore and manual phrase entry) so a successful mnemonic restore without local document data navigates to CountryPicker for re-import instead of dead-ending at Home
• Remove all failure-path navigations to Home from recovery screens — failed restores now keep the user on the recovery screen to retry

Changes

React Native App

• SplashScreen.tsx — Replace hardcoded Home route with getStartupNavigationTarget() that checks hasSecretStored() and hasAnyValidRegisteredDocument() to determine the correct startup screen. Suppress deep link processing during recovery.
• startupRouting.ts (new) — Pure routing function: no secret + documents/recovery signals → AccountRecoveryChoice; no secret + fresh user → Disclaimer; otherwise → Home.
• AccountRecoveryChoiceScreen.tsx — Remove dead !secret check; navigate to CountryPicker when secret recovered but no local document; remove Home navigations on failure paths.
• RecoverWithPhraseScreen.tsx — Same: remove dead !secret check, navigate to CountryPicker on missing document, remove Home navigations on all failure paths.
• deeplinks.ts — Add peekQueuedUrl() to read the queued URL without consuming it during recovery.

Tests

• startupRouting.test.ts (new) — Unit tests covering all startup routing branches and recovery signal detection.

Docs/Specs

• Whitespace-only table formatting changes in kmp-revival/SPEC.md and sdk-distribution/SPEC.md (unrelated).

Linear Issues

• Closes SELF-2540 — No account recovery flow after iCloud phone restore

Test Plan

• yarn workspace @selfxyz/mobile-app jest:run tests/src/screens/app/startupRouting.test.ts --runInBand passes
• yarn workspace @selfxyz/mobile-app types passes
• Manual: Dev build → register document → Dev Settings → Danger Zone → "Delete your private key" → force quit → relaunch → verify AccountRecoveryChoice screen appears
• Manual: Complete mnemonic recovery without local document → verify navigation to CountryPicker
• Manual: Enter invalid mnemonic → verify user stays on recovery screen (no Home redirect)

Native Consolidation Checklist

• CONTRACTS.md reviewed - no unintended contract changes
• Layer 1 bridge contract tests pass (cd app && yarn jest:run / yarn workspace @selfxyz/rn-sdk-test-app test)
• Layer 3 builds pass (app iOS, RN test app iOS, RN test app Android)
• Layer 4 manual smoke test signed off (if consolidation PR)
• No new native business logic added (logic belongs in TypeScript)

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Startup routing now selects the initial screen and whether queued deep links are allowed.
  • Added helper to wait for persisted settings hydration.
  • Centralized recovery copy for account recovery UI text.

• Improvements

  • Recovery flows now guide users toward document import and avoid unnecessary Home fallbacks.
  • Deep link handling preserves queued URLs until allowed; splash startup respects that.
  • Disclaimer screen includes test IDs for automated flows.

• Tests

  • Unit tests for startup routing and updated E2E launch flows.

• Documentation

  • Markdown table formatting tweaks in project specs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
self-webview-app	Ignored	Preview	Apr 9, 2026 7:14pm

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Startup navigation now computes an initial target with controllable queued-deeplink semantics. Deeplink API changed from get-and-clear semantics to a peek-only accessor. Account recovery flows and copy were updated (new recoveryCopy added). A setting-store hydration helper, startup routing tests, e2e disclaimer handling, and minor spec/table formatting edits were added.

Changes

Cohort / File(s)	Summary
Deeplink API & navigation helper app/src/navigation/deeplinks.ts	Replaced get-and-clear queued-URL accessor with a peek-only API (peekQueuedUrl()); relocated safeNavigate definition without changing its navigation logic.
Startup routing, splash & tests app/src/screens/app/startupRouting.ts, app/src/screens/app/SplashScreen.tsx, app/tests/src/screens/app/startupRouting.test.ts	Added startup routing types and logic (StartupNavigationTarget, getStartupNavigationTarget, hasStartupRecoverySignal); Splash computes startup target and conditionally processes queued deep links according to that target; added tests covering permutations.
Account recovery flow & copy app/src/screens/account/recovery/AccountRecoveryChoiceScreen.tsx, app/src/screens/account/recovery/RecoverWithPhraseScreen.tsx, app/src/screens/account/recovery/recoveryCopy.ts, app/src/screens/account/recovery/DocumentDataNotFoundScreen.tsx, app/src/screens/account/recovery/AccountRecoveryScreen.tsx	Deferred private-key derivation until passport data confirmed; removed several failure-path navigations to Home, treat missing passport data as document-import-required and route to CountryPicker; adjusted cloud-restore control flow and conditional cloud-toggle; replaced many hardcoded UI strings with recoveryCopy.
Setting store hydration helper app/src/stores/settingStore.ts	Added waitForSettingStoreHydration() to await Zustand persist rehydration with a one-time listener and immediate post-subscription check.
Onboarding UI & e2e flows app/src/screens/onboarding/DisclaimerScreen.tsx, app/tests/e2e/launch.android.flow.yaml, app/tests/e2e/launch.ios.flow.yaml	Added testIDs (disclaimer-screen-root, disclaimer-dismiss-button) and conditional e2e steps to dismiss the disclaimer when present before waiting for home screen.
iOS E2E workflow .github/workflows/mobile-e2e.yml	Simulator setup now performs an erase/boot sequence (simctl erase + bootstatus -b) to ensure a clean simulator state before reinstall.
Specs formatting specs/projects/sdk/workstreams/kmp-revival/SPEC.md, specs/projects/sdk/workstreams/sdk-distribution/SPEC.md	Adjusted Markdown table separators/column widths/alignment for consistent rendering; no semantic changes.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: fixing the account recovery flow after phone restore, which is the core objective of this PR.
Description check	✅ Passed	The description comprehensively covers all major changes, provides clear rationale, includes a detailed test plan with manual steps, and follows the repository template structure.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch bugfix/self-2540-icloud-account-recovery

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 59817da0f8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 3131c041-9095-44d1-b999-bd9039c9c38c

📥 Commits

Reviewing files that changed from the base of the PR and between 59817da and edbf0be.

📒 Files selected for processing (2)

• app/src/screens/app/SplashScreen.tsx
• app/src/stores/settingStore.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• app/src/screens/app/SplashScreen.tsx

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 396402dd-3cdb-4b61-84f1-41b7c5806bce

📥 Commits

Reviewing files that changed from the base of the PR and between f8083b4 and a114180.

📒 Files selected for processing (6)

• .github/workflows/mobile-e2e.yml
• app/src/screens/account/recovery/AccountRecoveryChoiceScreen.tsx
• app/src/screens/account/recovery/AccountRecoveryScreen.tsx
• app/src/screens/account/recovery/DocumentDataNotFoundScreen.tsx
• app/src/screens/account/recovery/RecoverWithPhraseScreen.tsx
• app/src/screens/account/recovery/recoveryCopy.ts

✅ Files skipped from review due to trivial changes (1)

• app/src/screens/account/recovery/DocumentDataNotFoundScreen.tsx

🚧 Files skipped from review as they are similar to previous changes (1)

• app/src/screens/account/recovery/AccountRecoveryChoiceScreen.tsx