epic: Phone-based pre-install account auth & cloud backup recovery

[castrojo]

Epic: Phone-Assisted Setup & Cloud Recovery

Vision

Allow users to prepare their installation before they boot the installer by using their phone (via the Bluefin website or a companion PWA) to:

1. Authenticate with cloud accounts (Google, Microsoft, iCloud, Nextcloud)
2. Back up existing OS data to their preferred cloud service
3. Generate a recovery token/QR code that the installer can consume on first boot
4. Restore their data seamlessly after installation completes

User Journey

[Phone/Web]                    [Installer]                  [First Boot]
     │                              │                            │
     ├─ Visit setup.projectbluefin.io                            │
     ├─ Sign in with Google/MS/etc  │                            │
     ├─ Select data to back up      │                            │
     ├─ Upload to chosen cloud      │                            │
     ├─ Get QR code / token         │                            │
     │                              │                            │
     │                              ├─ Scan QR during install    │
     │                              ├─ Store token in target     │
     │                              │                            │
     │                              │                            ├─ First boot detects token
     │                              │                            ├─ Downloads backup from cloud
     │                              │                            ├─ Restores: wallpaper, docs,
     │                              │                            │  bookmarks, SSH keys, dotfiles
     │                              │                            └─ Done — feels like home

Components Needed

1. Web app / PWA (setup.projectbluefin.io)

   • OAuth2 flows for Google Drive, OneDrive, iCloud, Nextcloud
   • Data category picker (Documents, Photos, Music, Bookmarks, Fonts, SSH keys, dotfiles)
   • Upload orchestration to user's cloud of choice
   • Token/QR generation with encrypted manifest

2. Installer integration

   • QR scanner step (optional, camera access from Flatpak?)
   • Or: manual token entry field
   • Store recovery manifest in target filesystem

3. First-boot recovery agent (systemd service)

   • Reads manifest from /etc/tuna-recovery/
   • Downloads data from cloud using stored OAuth tokens
   • Places files in correct XDG directories
   • Cleans up tokens after successful restore

4. Security considerations

   • OAuth tokens encrypted at rest with machine-specific key
   • Short-lived tokens with refresh capability
   • User can revoke access from cloud provider at any time
   • Manifest includes checksums for integrity verification

Prior Art

• Apple: iCloud backup → restore on new device
• Google: Android backup → restore on new phone
• Samsung Smart Switch
• Windows: OneDrive backup → restore on new PC
• System76: has discussed similar flows

Phases

Phase	Scope	Effort
1	Web app with Google Drive backup + QR token	Large
2	Installer QR scan + token storage	Medium
3	First-boot restore agent	Medium
4	Additional cloud providers (MS, Nextcloud)	Medium
5	Incremental sync / scheduled backups	Large

Relationship to Existing Work

• Builds on the Windows data slurp engine (fisherman/internal/slurp/) which already handles data categorization and extraction
• The slurp Scan() / ExtractData() / InjectData() pattern could be reused for cloud restore
• The recipe JSON could include a recoveryToken field

Open Questions

• Should the web app be a full PWA or a simple static site with OAuth redirects?
• Token lifetime — how long between pre-install backup and actual install?
• Should we support backing up the current Linux install too (not just Windows)?
• Camera access from Flatpak for QR scanning — feasible via portal?
• Alternative to QR: Bluetooth/WiFi Direct pairing with phone?

[castrojo]

Status update: there is no implementation PR attached to this epic yet.

Current phone companion work in PR #70 is limited to local, in-installer phone-assisted setup; it does not yet cover the larger scope here: pre-install cloud authentication, backing up data to a provider, generating a recovery token/manifest, or a first-boot restore agent.

Next steps for this epic are mostly definition work: lock down the external web/PWA scope, recovery token/manifest format and security model, installer handoff UX (QR scan vs token entry), and the first provider/restore path to implement before expanding provider support.