archy/docs/MASTER_PLAN.md

# MASTER PLAN

> Archipelago project task tracking and roadmap.
>
> **BETA FREEZE ACTIVE (2026-03-18)** — No new features. Fix bugs, harden security, test everything.
> Pipeline: **Feature Testing** → **User Testing** → **Beta Live**
> Progress: `docs/BETA-PROGRESS.md` | Acceptance: `docs/BETA-RELEASE-CHECKLIST.md`

## Roadmap

### Phase 1: Feature Testing (internal) — CURRENT

| ID | Title | Priority | Status | Dependencies |
|----|-------|----------|--------|--------------|
| **FEATURE-4** | **Onboarding loading screen with progress** | **P1** | IN PROGRESS | - |
| **TASK-9** | **Full feature testing sweep** | **P1** | PLANNED | - |
| **TASK-10** | **ISO build verification + multi-hardware test** | **P1** | PLANNED | - |
| **TASK-12** | **Beta telemetry — reporter + toggle + collector POST** | **P1** | IN PROGRESS | - |
| **TASK-39** | **Finish .198 rootless container migration** | **P1** | PLANNED | TASK-11 |
| **TASK-42** | **LUKS2 full-partition encryption for /var/lib/archipelago/** | **P1** | IN PROGRESS | - |
| **BUG-44** | **App iframe shows blank/broken when container is starting or crashed** | **P2** | PLANNED | - |
| **TASK-45** | **Deploy script: auto-chown data dirs after rootful→rootless migration** | **P2** | PLANNED | - |
| **BUG-46** | **FileBrowser missing in unbundled ISO + Cloud auto-login broken** | **P1** | IN PROGRESS | - |
| **BUG-47** | **Onboarding: DID sign 403 + blob HTTPS + no password setup** | **P1** | IN PROGRESS | - |
| **FEATURE-48** | **Meshtastic support for mesh (plug and play)** | **P1** | PLANNED | - |

### Phase 2: User Testing (controlled, real hardware)

| ID | Title | Priority | Status | Dependencies |
|----|-------|----------|--------|--------------|
| **TASK-13** | **Recruit 3-5 test users, distribute ISOs** | **P1** | NOT STARTED | Phase 1 complete |
| **TASK-14** | **Monitor telemetry, triage + fix user-reported issues** | **P1** | NOT STARTED | TASK-12, TASK-13 |
| **TASK-15** | **Rebuild ISO with fixes, re-verify** | **P1** | NOT STARTED | TASK-14 |

### Phase 3: Beta Live (public)

| ID | Title | Priority | Status | Dependencies |
|----|-------|----------|--------|--------------|
| **TASK-16** | **Final ISO build + release notes + distribution** | **P1** | NOT STARTED | Phase 2 complete |

### Post-Beta (FROZEN — do not start)

| ID | Title | Priority | Status | Dependencies |
|----|-------|----------|--------|--------------|
| **TASK-2** | **Roll incoming-tx into deploy & ISO** | **P2** | DEFERRED | - |
| **INQUIRY-5** | **Offline balance check via mesh relay** | **P2** | DEFERRED | - |
| **FEATURE-6** | **Watch-only wallet architecture** | **P1** | DEFERRED | - |
| **TASK-7** | **Mesh Bitcoin security hardening** | **P1** | DEFERRED | FEATURE-6 |
| **FEATURE-43** | **P2P encrypted voice/video calling (WebRTC over federation)** | **P1** | DEFERRED | - |
| **FEATURE-48** | **Meshtastic support for mesh (plug and play)** | **P1** | PLANNED | - |

## Active Work

### FEATURE-4: Onboarding loading screen with progress (IN PROGRESS)
**Priority**: P1 — High
**Status**: IN PROGRESS (2026-03-17)

Users hit the onboarding screen before the backend is ready, resulting in "Server is still starting up" errors that block identity creation. The onboarding flow should not begin until the server is fully operational.

**Solution**: Show the existing screensaver as a loading/boot screen with server startup progress. Swap the inner logo for animated pixel art icons (smiley face, Bitcoin logo, etc.) that cycle while services come online. Show progress indicators for each backend service (identity store, container runtime, LND, etc.). Only transition to onboarding once `/health` returns ready.

**Key considerations**:
- Reuse the existing screensaver component as the boot screen
- Animated pixel art icons rotate in the center (smiley, BTC, lightning bolt, etc.)
- Progress bar or status checklist showing which services are ready
- Poll `/health` endpoint for service readiness
- Smooth transition from boot screen → onboarding once all critical services are up
- First-boot vs normal boot: first boot shows onboarding after, normal boot goes to dashboard

**Key files**:
- `neode-ui/src/views/Onboarding.vue` — current onboarding flow
- `neode-ui/src/components/Screensaver.vue` — existing screensaver to repurpose
- `core/archipelago/src/api/rpc/mod.rs` — health endpoint
- `core/archipelago/src/server.rs` — startup sequence and service initialization

**Tasks**:
- [ ] Investigate current health endpoint — what services does it check, what's missing
- [ ] Design boot screen component: screensaver background + animated pixel icons + progress
- [ ] Create pixel art icon set (smiley, BTC, lightning, shield, etc.) as SVG/CSS animations
- [ ] Implement service readiness polling (health check with granular service status)
- [ ] Add backend support for granular startup progress (which services are ready)
- [ ] Build boot screen component with smooth transition to onboarding/dashboard
- [ ] Handle edge cases: very slow starts, partial service failures, timeout fallback
- [ ] Test on fresh ISO install (first-boot scenario)

### TASK-9: Full app testing matrix on fresh install (PLANNED)
**Priority**: P1 — High
**Status**: PLANNED (2026-03-18)

Run through the complete `docs/BETA-RELEASE-CHECKLIST.md` app matrix on a fresh ISO install. Every app: install, launch, UI loads, uninstall. Every dependency chain: correct errors when deps missing.

### TASK-10: ISO build verification + multi-hardware test (PLANNED)
**Priority**: P1 — High
**Status**: PLANNED (2026-03-18)

Build a fresh ISO, install on at least 2 different hardware configurations, verify full onboarding flow, app installs, and multi-day uptime.

---

### TASK-17: Alpha version tags + rollback strategy (PLANNED)
**Priority**: P2 — Medium
**Status**: PLANNED (2026-03-18)

Tag every significant alpha version with git tags for easy rollback. Each tag should correspond to a deployable state. Maintain a version log so any alpha can be rebuilt and deployed.

**Tasks**:
- [ ] Tag current state as `v1.2.0-alpha.1` (pre-rootless-podman)
- [ ] Establish naming convention: `v{major}.{minor}.{patch}-alpha.{build}`
- [ ] Tag after rootless podman migration: `v1.2.0-alpha.2`
- [ ] Document rollback procedure (git checkout tag + deploy)
- [ ] Add version tag step to deploy script (auto-tag on successful deploy)
- [ ] Update CHANGELOG.md with each alpha milestone

---

### TASK-42: LUKS2 full-partition encryption for /var/lib/archipelago/ (IN PROGRESS)
**Priority**: P1 — High
**Status**: IN PROGRESS (2026-03-26)

Encrypt all Archipelago app data at rest using LUKS2 full-partition encryption. Protects Bitcoin wallet data, LND macaroons, FileBrowser files, Vaultwarden vault, secrets, and everything else from physical disk seizure. Seamless UX — user never interacts with encryption directly.

**Design**:
- LUKS2 partition for `/var/lib/archipelago/` created during ISO install
- Cipher: AES-256-XTS (hardware AES-NI on x86_64, ChaCha20 fallback on ARM without AES-NI)
- Key derived from setup password via Argon2id + hardware salt (`/sys/class/dmi/id/product_uuid`)
- Key file stored at `/root/.luks-archipelago.key` (root:600, on boot partition)
- Auto-unlock via `/etc/crypttab` on every boot — no passphrase prompt
- Password change in Settings re-derives key and rotates LUKS keyslot

**Threat model**:
- Disk removed from machine = fully encrypted, unreadable
- Running machine with login = transparent (same as today)
- Forgot password = cannot decrypt (correct sovereign behavior)

**Tasks**:
- [x] ISO installer: create LUKS2 partition, format + mount at `/var/lib/archipelago/`
- [ ] First-boot: derive LUKS key from setup password via Argon2id + hardware salt
- [x] Store key file at `/root/.luks-archipelago.key` with 600 perms
- [x] Configure `/etc/crypttab` for auto-unlock at boot
- [ ] Settings password change: re-derive LUKS key, add new keyslot, remove old
- [x] Detect AES-NI availability, fall back to ChaCha20 on ARM without it
- [ ] Test: fresh install, reboot survives, power-cycle survives, password change works
- [ ] Test: disk removed from machine is unreadable
- [x] Update `image-recipe/build-auto-installer-iso.sh`

**Key files**:
- `image-recipe/build-auto-installer-iso.sh` — partition creation
- `scripts/first-boot-containers.sh` — runs after LUKS mount
- `core/archipelago/src/api/rpc/system.rs` — password change handler
- `core/archipelago/src/server.rs` — startup checks

### BUG-44: App iframe shows blank/broken when container is starting or crashed (PLANNED)
**Priority**: P2 — Medium
**Status**: PLANNED (2026-03-21)

When an app container is still starting up or has crashed, the iframe overlay shows a blank/broken page with no feedback. Should show contextual loading states:
- **Starting**: skeleton loader or "App is starting up..." with spinner
- **Crashed**: "App has stopped" with restart button and link to logs
- **Port not ready**: "Waiting for app to become available..." with timeout warning
- **X-Frame-Options blocked**: Detect and open in new tab automatically

**Key files**:
- `neode-ui/src/views/AppSession.vue` — iframe container
- `neode-ui/src/stores/appLauncher.ts` — app launch state
- `neode-ui/src/api/container-client.ts` — container status checks

### TASK-45: Deploy script: auto-chown data dirs after rootful→rootless migration (PLANNED)
**Priority**: P2 — Medium
**Status**: PLANNED (2026-03-21)

When `deploy-tailscale.sh` migrates from rootful to rootless Podman, all files in `/var/lib/archipelago/` created by the old root-running backend are owned by `root:root`. The new backend runs as `archipelago` user and can't read them (node-key.pem, credentials, sessions, identity, etc.). Deploy script must auto-detect and fix ownership after migration.

Also fix:
- `/run/user/1000/crun` ownership (left as root from rootful container creation)
- Container recreation needs `--cap-add NET_BIND_SERVICE` for apps binding port 80 (nextcloud)
- Container recreation needs config volume mounts for apps writing to `/etc/` (searxng)
- Frontend should be copied from .228, not built locally (prevents build mismatches)

**Key files**:
- `scripts/deploy-tailscale.sh` — Step 14 (UID mapping) and Step 22 (container creation)
- `scripts/first-boot-containers.sh` — container creation reference

### BUG-46: FileBrowser missing in unbundled ISO + Cloud auto-login broken (IN PROGRESS)
**Priority**: P1 — High
**Status**: IN PROGRESS (2026-03-26)

Two issues with the Cloud feature on fresh installs:

1. **FileBrowser not prepackaged in unbundled ISO** — The unbundled ISO variant doesn't include the FileBrowser container image, so Cloud doesn't work out of the box. FileBrowser is a core dependency (not an optional app) since it powers the Cloud file manager. Must be bundled even in the unbundled variant.

2. **FileBrowser auto-login not working** — The auto-login flow (so users don't need to enter separate FileBrowser credentials) appears broken. Need to investigate whether the auth proxy/token injection is functioning correctly on fresh installs.

**Tasks**:
- [x] Add FileBrowser image to unbundled ISO build (core dependency, always bundled)
- [x] Create minimal first-boot script for unbundled mode (FileBrowser only)
- [x] Fix auto-login: `Secure` cookie flag silently fails on HTTP — made conditional
- [x] Changed `SameSite=Strict` to `SameSite=Lax` for better navigation compatibility
- [ ] Test Cloud feature end-to-end on a fresh install (both bundled and unbundled)

**Key files**:
- `image-recipe/build-auto-installer-iso.sh` — UNBUNDLED container image list
- `scripts/first-boot-containers.sh` — FileBrowser container creation
- `image-recipe/configs/nginx-archipelago.conf` — FileBrowser proxy config
- `neode-ui/src/views/Cloud.vue` — Cloud UI / auto-login logic

### BUG-47: Onboarding: DID sign 403 + blob HTTPS + no password setup (IN PROGRESS)
**Priority**: P1 — High
**Status**: IN PROGRESS (2026-03-26)

Three onboarding issues on clean install:

1. **Sign DID returns 403 Forbidden** — The DID verification/signing step during onboarding fails with a 403 response from the backend.
2. **Blob URL HTTPS warning** — Browser complains about blob URL loaded over insecure connection (`blob:http://...` should be served over HTTPS). Likely related to the backup download on HTTP connections.
3. **No password setup on clean install** — Users cannot set a password during onboarding. The setup password flow is missing or broken.

**Root causes found**:
- `node.did`, `node.signChallenge`, `node.nostr-pubkey`, `node.createBackup`, `identity.verify` were NOT in `UNAUTHENTICATED_METHODS` — onboarding has no session, so they all returned 403
- `auth.setup` and `auth.isSetup` RPC methods were missing from the dispatcher — the frontend called them but no handler existed
- Blob HTTPS warning is a browser security feature on HTTP connections (not a code bug)

**Tasks**:
- [x] Add onboarding methods to UNAUTHENTICATED_METHODS in middleware.rs
- [x] Add `auth.setup` RPC handler (creates user with password, prevents re-setup)
- [x] Add `auth.isSetup` RPC handler (checks if user.json exists)
- [x] Rust compiles clean
- [ ] Blob URL HTTPS warning — known browser limitation on HTTP, no code fix needed
- [ ] Test full onboarding flow end-to-end on fresh ISO

**Key files**:
- `neode-ui/src/views/OnboardingVerify.vue` — DID signing step
- `neode-ui/src/views/OnboardingBackup.vue` — Backup download (blob URL)
- `neode-ui/src/views/OnboardingIntro.vue` — Password setup entry point
- `core/archipelago/src/api/rpc/auth.rs` — Auth RPC endpoints
- `core/archipelago/src/api/rpc/middleware.rs` — Request auth middleware

---

## Post-Beta (FROZEN)

*These tasks are deferred until after beta ships. Do not start.*

- **INQUIRY-5**: Offline balance check via mesh relay
- **FEATURE-6**: Watch-only wallet architecture
- **TASK-7**: Mesh Bitcoin security hardening
- **TASK-2**: Roll incoming-tx into deploy & ISO
- **FEATURE-43**: P2P encrypted voice/video calling (WebRTC over federation)

---

### FEATURE-43: P2P encrypted voice/video calling — WebRTC over federation (DEFERRED)
**Priority**: P1 — High
**Status**: DEFERRED (post-beta)

Self-sovereign encrypted voice and video calling between Archipelago peers. Zero new containers or dependencies — uses browser-native WebRTC with signaling over the existing federation WebSocket. Integrates directly into peer tabs/chat.

**Security & Privacy**:
- All media encrypted via DTLS/SRTP (WebRTC mandatory encryption — no opt-out)
- Signaling (SDP offers, ICE candidates) transmitted over existing federation WebSocket through Tor
- ICE candidate filtering: strip local/public IP candidates in Tor-relay mode
- No central server, no metadata leakage — true P2P between browsers
- Two privacy modes:
  - **LAN Direct**: <50ms latency, IPs visible to peer (trusted same-network peers)
  - **Tor Relay**: 300-800ms latency, full anonymity via coturn TURN server on .onion

**Architecture**:
- Signaling reuses existing federation WebSocket — new message types: `call-offer`, `call-answer`, `call-ice`, `call-hangup`, `call-reject`, `call-busy`
- Browser `getUserMedia()` + `RTCPeerConnection` — no backend media processing
- Opus codec for voice (~30kbps, handles Tor latency well)
- VP8/VP9 adaptive bitrate for video (720p on LAN, degrades gracefully)
- Optional `coturn` container (~10MB RAM) for Tor-relay media mode only

**UX**:
- Voice and video call buttons in peer chat (federation contacts)
- Incoming call: glass modal slides up with peer name + avatar, accept/decline
- In-call: floating glass PIP overlay — navigate while talking
- One-tap mute, camera toggle, speaker toggle, hangup
- Call quality indicator (green/yellow/red based on RTT)
- Ring timeout (30s) → missed call notification
- Call history in peer chat thread

**Tasks**:
- [ ] `CallService.ts` — WebRTC wrapper (offer/answer, ICE management, stream handling, codec negotiation)
- [ ] Federation signaling protocol — new message types over existing WS (`call-offer`, `call-answer`, `call-ice`, `call-hangup`)
- [ ] Rust backend — relay call signaling messages between federation peers (pass-through, no media processing)
- [ ] ICE candidate filtering — strip public IPs in privacy mode, force relay-only
- [ ] `CallOverlay.vue` — incoming call modal (glass aesthetic, ring animation, accept/decline)
- [ ] `CallPIP.vue` — floating picture-in-picture during active call (draggable, minimize/expand)
- [ ] `CallControls.vue` — mute, camera toggle, speaker, hangup, privacy mode switch
- [ ] Voice-only mode — Opus codec, bandwidth-optimized, Tor-friendly
- [ ] Video mode — VP8/VP9 adaptive bitrate, resolution scaling based on connection quality
- [ ] Optional `coturn` container manifest — TURN relay for Tor-routed media
- [ ] Call quality monitoring — RTT measurement, packet loss detection, quality indicator
- [ ] Call history — persist in peer chat thread, missed call notifications
- [ ] Multi-peer consideration — design for 1:1 first, extensible to group calls later
- [ ] Test: LAN direct call (voice + video)
- [ ] Test: Tor relay call (voice — verify latency is acceptable)
- [ ] Test: call during active chat, call while navigating other views
- [ ] Test: network interruption recovery (ICE restart)

**Key files** (new):
- `neode-ui/src/services/CallService.ts` — WebRTC engine
- `neode-ui/src/components/call/CallOverlay.vue` — incoming call UI
- `neode-ui/src/components/call/CallPIP.vue` — in-call floating overlay
- `neode-ui/src/components/call/CallControls.vue` — call action buttons
- `apps/coturn/manifest.yml` — optional TURN relay container

**Key files** (modified):
- `neode-ui/src/views/Federation.vue` — call buttons in peer chat
- `core/archipelago/src/api/rpc/federation.rs` — call signaling relay
- `neode-ui/src/stores/federation.ts` — call state management

## Completed

| ID | Title | Completed |
|----|-------|-----------|
| **TASK-11** | Rootless podman migration (.228 — 30 containers) | 2026-03-18 |
| **TASK-32** | Integrate boot loader into deploy + build + production | 2026-03-17 |
| **TASK-34** | Pentest findings remediation plan | 2026-03-18 |
| **TASK-26** | Rename fedimintd to "Fedimint Guardian" + icon | 2026-03-18 |
| **TASK-27** | Add tab-launch icon to apps that open in tabs | 2026-03-18 |
| **TASK-28** | Sort installed apps to end of marketplace | 2026-03-18 |
| **TASK-29** | Fix mesh mobile: remove title/flash/peers header, fix gutters | 2026-03-18 |
| **TASK-30** | On-Chain as first tab in receive Bitcoin modals | 2026-03-18 |
| **TASK-35** | Federation node names (show name not DID, hover for key) | 2026-03-18 |
| **TASK-36** | Cleaner iframe error screen with remediation | 2026-03-18 |
| **BUG-1** | Random logout / CSRF mismatch — HMAC-derived tokens | 2026-03-18 |
| **TASK-8** | Security hardening — 12/12 pentest findings fixed | 2026-03-18 |
| **BUG-20** | ElectrumX index estimate string ~55→~130 GB | 2026-03-18 |
| **BUG-37** | App card Start/Launch flicker during container scan | 2026-03-18 |
| **BUG-40** | Uninstall dialog not full-screen modal | 2026-03-18 |
| **BUG-41** | Uninstall loader ends but app card persists | 2026-03-18 |
| **BUG-33** | CPU load alert threshold too low (8 = 2x cores) | 2026-03-18 |
| **TASK-31** | Sticky nav header (Apps page) | 2026-03-18 |
| **TASK-38** | Blockchain sync info on homepage System card | 2026-03-18 |
| **TASK-17** | Alpha version tags + deploy auto-tag | 2026-03-18 |
| **BUG-3** | IndeedHub WebSocket spam — removed dead nostrConfig | 2026-03-18 |