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
BUG-1	Random logout / CSRF mismatch	P0	PLANNED	-
TASK-8	Security hardening (9/12 fixed, H2/H3/H4 remain)	P0	IN PROGRESS	-
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 — node reporting + monitoring panel	P1	PLANNED	-
BUG-20	ElectrumX always shows "Building..." not height	P2	PLANNED	-
TASK-31	Sticky nav header (My Apps/App Store/Services + categories + search)	P2	PLANNED	-
BUG-37	Apps flicker Start/Launch during container scan	P2	PLANNED	-
TASK-38	Add blockchain sync info to homepage System card	P2	PLANNED	-
BUG-3	IndeedHub WebSocket spam in console	P2	PLANNED	-
TASK-17	Alpha version tags + rollback strategy	P2	PLANNED	-
TASK-39	Finish .198 rootless container migration	P1	PLANNED	TASK-11
BUG-40	Uninstall dialog not full-screen modal	P2	PLANNED	-
BUG-41	Uninstall loader ends but app card persists	P2	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

Active Work

BUG-1: Random logout / CSRF mismatch (PLANNED)

Priority: P0 — Critical Status: PLANNED (2026-03-15)

Sessions expire unexpectedly during normal use. Backend sessions now persist to disk (/var/lib/archipelago/sessions.json) but CSRF token mismatch (403) still causes logouts. Need to investigate CSRF token lifecycle and fix the mismatch between cookie and header values.

Root cause analysis so far:

• Sessions were purely in-memory — fixed with disk persistence
• CSRF validation compares cookie value vs X-CSRF-Token header — both present but don't match
• Log: 403 CSRF mismatch — rejecting RPC call ... has_cookie=true has_header=true
• Possible cause: cookie value rotated (e.g., new login in another tab) but frontend cached old value

Key files:

• core/archipelago/src/session.rs — session store (now persisted)
• core/archipelago/src/api/rpc/mod.rs:273-307 — CSRF validation
• neode-ui/src/api/rpc-client.ts:18-45 — frontend CSRF extraction from cookie

Tasks:

• Investigate CSRF token rotation — when/why cookie and header diverge
• Add logging to CSRF validation to capture actual cookie vs header values
• Consider returning CSRF token in response body (not just cookie) for explicit client storage
• Test multi-tab scenario where one tab's login rotates the CSRF token
• Verify session persistence survives deploys (second deploy test)

TASK-2: Roll incoming-tx into deploy & ISO (PLANNED)

Priority: P2 — Medium Status: PLANNED (2026-03-16)

The incoming transactions feature (lnd.gettransactions RPC + wallet badge UI + auto-refresh) is working on .228. Roll changes into deploy-to-target.sh and build-auto-installer-iso.sh so fresh installs and deploys get it automatically. Do not break existing changes.

Key files changed:

• core/archipelago/src/api/rpc/lnd.rs — new handle_lnd_gettransactions method
• core/archipelago/src/api/rpc/mod.rs — registered lnd.gettransactions route
• neode-ui/src/views/Web5.vue — incoming tx badge, panel, auto-refresh polling
• neode-ui/src/style.css — incoming-tx-badge, incoming-tx-row, incoming-tx-slide classes

Tasks:

• Verify changes are already captured by existing deploy (backend build + frontend build)
• Ensure ISO build captures the updated Rust binary and frontend dist
• Test that no existing deploy/build logic is broken

BUG-3: IndeedHub WebSocket spam in console (PLANNED)

Priority: P2 — Medium Status: PLANNED (2026-03-16)

ws://localhost:7777/ connection refused fills browser console endlessly when IndeedHub is loaded in iframe. IndeedHub's compiled frontend bundle hardcodes localhost for WebSocket connections. When loaded from a remote host, localhost resolves to the user's machine, not the server.

Root cause: IndeedHub's Next.js build bakes localhost:7777 into the WebSocket URL. The nginx WebSocket proxy at /app/indeedhub/ws/ exists but is unused because IndeedHub loads via direct port 7777, not through the proxy path.

Tasks:

• Rebuild IndeedHub with NEXT_PUBLIC_WS_URL env var pointing to relative URL or actual server address
• Alternatively, configure IndeedHub to use relative WebSocket URLs (/ws/ instead of ws://localhost:7777/)
• Test that WebSocket reconnection works after the fix

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-8: Security hardening — 9/12 findings fixed (IN PROGRESS)

Priority: P0 — Critical Status: IN PROGRESS (2026-03-18) — 9 of 12 pentest findings fixed

Reference: docs/security-audit-2026-03-11.md

Fixed (commits 27f205f, c1db74e):

• C1: /lnd-connect-info requires session auth
• C3: DEV_MODE removed from production service
• H1: node-message verifies ed25519 signatures
• M1: content.add rejects .. path traversal
• M2: NIP-07 postMessage uses specific origin
• M3: AIUI nginx checks session_id cookie
• L2: Strict v3 onion validation
• MED-03: Shell injection in bitcoin.conf generation
• MED-07: No body size limit on /rpc/

Remaining:

• H2: Federation peer-joined signature verification
• H3: Federation address-changed signature verification
• H4: Bind service ports to 127.0.0.1 (Bitcoin RPC, LND, etc.)

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

---

BUG-40: Uninstall dialog not full-screen modal (PLANNED)

Priority: P2 — Medium Status: PLANNED (2026-03-18)

The uninstall confirmation dialog renders as a small centered card instead of a full-screen modal overlay like all other modals. The sidebar and background content are fully visible behind it — should use the same full-screen backdrop pattern.

Tasks:

• Find the uninstall confirmation component and add full-screen backdrop
• Match the modal pattern used by other dialogs (e.g., send/receive modals)

BUG-41: Uninstall loader ends but app card persists (PLANNED)

Priority: P2 — Medium Status: PLANNED (2026-03-18)

After clicking Uninstall, the loading spinner finishes but the app card remains visible. Need an "Uninstalling..." state on the card that persists until the card is actually removed from the list.

Tasks:

• Add uninstalling state to app cards
• Show "Uninstalling..." overlay on the card after confirm
• Keep state until container is fully removed and card disappears from the list

---

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

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-33	CPU load alert threshold too low (8 = 2x cores)	2026-03-18