> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.adid.dev/llms.txt.
> For full documentation content, see https://docs.adid.dev/llms-full.txt.

# Wallet Onboarding

The wallet onboarding flow blends **social login** (Google or GitHub) with on-device key generation so users get a DID without ever seeing a "private key":

1. Tap **Continue with Google / GitHub** on the `OnboardingScreen` (see `packages/wallet/src/screens/OnboardingScreen.tsx`).
2. The OAuth dance redirects through the IDA API (`GET /api/v1/auth/oauth/google` → IdP → `POST /api/v1/auth/oauth/google/callback`) and returns an `accessToken` + `refreshToken` pair.
3. The wallet calls `GET /api/v1/auth/wallet` to retrieve any platform-side wallet metadata. If the user is brand-new, the API auto-provisions Share 2 and a fresh `did:adi` keyed by Share 1 ⊕ Share 2.
4. The wallet asks the user for a **recovery passphrase** (≥ 12 characters) and builds an **encrypted recovery package** with PBKDF2-SHA-512(passphrase, salt, 200 000) → AES-256-GCM. The package contains the material needed to rebuild Share 1 on a fresh device after re-authentication; Share 3 itself stays with the recovery custodian. The wallet offers a **Save backup** action that emails the encrypted package to the user and renders it as text for the user to print or photograph.
5. Biometric unlock (`expo-local-authentication`) is enabled by default; users without biometrics fall back to a 6-digit PIN.

When onboarding completes the wallet stores: the active access/refresh tokens, the user's primary DID, the encrypted Share 1, and a metadata record listing other DIDs the user owns. Subsequent launches read all of these from `expo-secure-store` and re-hydrate the in-memory `Wallet` instance.

> **Note for testers:** the email sender is configured by the API's `AuthService`. In Docker dev compose, no SMTP is wired — the OTP appears in the API logs (`docker compose logs -f api`).