lfg2025/archy
1
0
Fork 0
Code Issues 9 Pull Requests Actions Packages Projects Releases 44 Wiki Activity
archy/loop/plan.md
Dorian 4149337c1d fix: correct IndeedHub port mapping from 8190 to 7777 
Backend metadata and manifest now match the actual running config
and the frontend port mapping.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-15 04:28:18 +00:00

51 KiB
Raw Blame History

Overnight Plan — Archy Refactoring & App Integration Hardening

Make the Archy codebase rock-solid: fix all broken containers/iframes, perfect app installation/management/icons, get IndeedHub + Nostr signer flawless, and begin critical refactoring. No new features, no design changes. Bitcoin only. See docs/refactoring-plan.md for the full 3-year plan. See CLAUDE.md for all project rules and conventions. Deploy after every change: ./scripts/deploy-to-target.sh --live — test at http://192.168.1.228

Phase 1: Fix App Icon Consistency

  • Fix PhotoPrism icon typo in backend metadata: In core/archipelago/src/container/docker_packages.rs, the get_app_metadata() function references photoprims.svg (missing 'h') for the PhotoPrism icon. Search for photoprims and replace with photoprism. Verify the icon file exists at neode-ui/public/assets/img/app-icons/photoprism.svg. Run cargo clippy --all-targets --all-features in core/ on the dev server after the fix.

  • Fix IndeedHub duplicate icon — consolidate to indeedhub.png: Two icon files exist: neode-ui/public/assets/img/app-icons/indeedhub.ico and indeehub.ico (typo). Delete indeehub.ico. Convert indeedhub.ico to indeedhub.png (better format consistency). Update all references: (1) neode-ui/src/utils/dummyApps.ts line ~518 — change indeehub.ico to indeedhub.png, (2) neode-ui/src/views/Marketplace.vue line ~913 — change indeehub.ico to indeedhub.png, (3) core/archipelago/src/container/docker_packages.rs lines ~451-454 — change indeehub.ico to indeedhub.png. Search the entire codebase for indeehub (missing 'd') and fix all occurrences to indeedhub. Run cd neode-ui && npm run type-check to verify.

  • Audit all app icons match their references: Cross-check every icon path referenced in docker_packages.rs get_app_metadata() against actual files in neode-ui/public/assets/img/app-icons/. Verify each app in the Marketplace.vue getCuratedAppList() function has an icon that exists. If any icon is missing, check if a similar-named file exists (e.g., wrong extension). Fix all mismatches. Remove orphaned icons that no app references (e.g., atob.png, community-store.png, k484.png, lorabell.png, morphos.png — verify they're truly unused first). Standardize: prefer .png or .svg over .ico and .webp where possible without changing existing working icons.

Phase 2: Fix Container Crash Loops & Health

  • Diagnose and fix container networking DNS failures: SSH to 192.168.1.228 (sshpass -p 'EwPDR8q45l0Upx@' ssh -o StrictHostKeyChecking=no archipelago@192.168.1.228). Run sudo podman ps -a --format '{{.Names}} {{.Status}}' | grep -i restart to identify containers in crash loops. The known issue is DNS resolution failures — containers can't resolve each other by name (e.g., mempool-web can't find mempool-api). Check if the archy-net Podman network exists: sudo podman network ls. If missing, create it: sudo podman network create archy-net. Reconnect all containers that need inter-container DNS to this network. Verify with sudo podman exec archy-mempool-web ping mempool-api. Restart affected containers and monitor for 2 minutes to confirm no more crash loops.

  • Fix .198 server swap and memory: SSH to 192.168.1.198. Check current swap: free -h. If no swap configured, create a 4GB swap file: sudo fallocate -l 4G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile. Add to /etc/fstab: /swapfile none swap sw 0 0. Verify with free -h. This prevents OOM kills that crash containers.

  • Stop and remove ollama container if not needed: SSH to 192.168.1.228. Check ollama status: sudo podman ps -a | grep ollama. If it's in "Created" state and never started, remove it: sudo podman rm ollama. This frees a container slot and removes clutter from the app list. If the user has ollama in their installed apps, leave it but start it: sudo podman start ollama.

  • Verify all core Bitcoin containers are healthy: SSH to 192.168.1.228. Check these containers are running and healthy: bitcoin-knots, lnd, mempool-api, archy-mempool-web, mempool-electrs, btcpay-server, archy-nbxplorer. Run sudo podman ps --format '{{.Names}}\t{{.Status}}' | grep -E "(bitcoin|lnd|mempool|btcpay|nbxplorer|electrs)". For any that are not "Up", check logs: sudo podman logs --tail 50 {container-name}. Fix the root cause (usually missing network, wrong env var, or dependency not ready). After fixes, run curl -s http://localhost:5678/health to verify the Archy backend sees them all.

Phase 3: Fix Iframe Embedding for All Apps

  • Audit X-Frame-Options headers for all proxied apps: SSH to 192.168.1.228. For each app with a known port, check the actual response headers: for port in 81 3000 3001 4080 7777 8080 8081 8082 8083 8085 8096 8123 8175 8176 8190 8240 8334 8888 9000 9001 9980 11434 2283 2342 23000 50002; do echo "Port $port:"; curl -sI http://localhost:$port/ 2>/dev/null | grep -i "x-frame\|content-security-policy" || echo " (no frame restrictions)"; done. Record the results. Compare against the blocking list in neode-ui/src/stores/appLauncher.ts (lines 23-31, the XFRAME_BLOCKED_PORTS array). Update the blocking list to match reality — if an app no longer sends X-Frame-Options DENY, remove it from the blocked list. If an app sends it but isn't in the list, add it.

  • Ensure nginx strips X-Frame-Options for iframe-compatible apps: In image-recipe/configs/nginx-archipelago.conf, verify every /app/{id}/ location block includes proxy_hide_header X-Frame-Options; for apps that should work in iframes. Apps that genuinely can't work in iframes (BTCPay with DENY, Home Assistant with SAMEORIGIN that rejects proxy origin) should open in new tabs. For apps like Grafana (port 3000) — check if setting the env var GF_SECURITY_ALLOW_EMBEDDING=true on the Grafana container fixes it, then remove it from the blocked list. For Nextcloud (port 8085) — check if the nginx sub_filter approach or Nextcloud's overwriteprotocol setting allows embedding. For Uptime Kuma (port 3001) — it may work with the header stripped. Test each by loading http://192.168.1.228/app/{id}/ in a browser iframe or curl -sI http://192.168.1.228/app/{id}/ | grep -i frame.

  • Fix nginx sub_filter for apps with root-relative asset paths: Apps served under /app/{id}/ may have root-relative paths like /static/main.js that break because they resolve to the Archy root, not the app root. In image-recipe/configs/nginx-archipelago.conf, check IndeedHub's location block (lines 334-367) — it already uses sub_filter to rewrite paths. Verify the same pattern exists for other Next.js/React apps that need it (Penpot on 9001, Immich on 2283, Fedimint UI on 8175). For each, test: load the app at http://192.168.1.228/app/{id}/, open browser dev tools Network tab, check for 404s on static assets. If assets 404, add appropriate sub_filter rules to their nginx location block. After changes, sync the config: scp image-recipe/configs/nginx-archipelago.conf archipelago@192.168.1.228:/tmp/ && ssh archipelago@192.168.1.228 'sudo cp /tmp/nginx-archipelago.conf /etc/nginx/sites-available/archipelago && sudo nginx -t && sudo systemctl reload nginx'.

  • Deploy and verify iframe loading for all apps: Deploy with ./scripts/deploy-to-target.sh --live. After deploy, test each app iframe by hitting the Archy UI at http://192.168.1.228, navigating to Apps, and clicking each installed app. Verify: (1) iframe apps load content (not blank white), (2) blocked apps open in new tab cleanly, (3) no mixed-content warnings in console. Log any remaining issues for the next phase.

Phase 4: IndeedHub + Nostr Signer Integration

  • Verify IndeedHub container is running and accessible: SSH to 192.168.1.228. Check: sudo podman ps | grep indeedhub. If not running, check if the image exists: sudo podman images | grep indeedhub. If no image, pull from manifest: the image is git.tx1138.com/lfg2025/indeedhub:latest (from apps/indeedhub/manifest.yml). Pull and start: sudo podman pull git.tx1138.com/lfg2025/indeedhub:latest && sudo podman run -d --name indeedhub --restart unless-stopped -p 7777:3000 --cap-drop ALL --cap-add CHOWN --cap-add SETUID --cap-add SETGID --security-opt no-new-privileges --user 1001 git.tx1138.com/lfg2025/indeedhub:latest. Verify it responds: curl -sI http://localhost:7777/. Check nginx proxy works: curl -sI http://localhost/app/indeedhub/.

  • Fix IndeedHub port mapping inconsistency: In core/archipelago/src/container/docker_packages.rs, line ~139-141 hardcodes http://localhost:8190 for IndeedHub. But nginx and the frontend use port 7777. Update docker_packages.rs to use port 7777: change Some("http://localhost:8190".to_string()) to Some("http://localhost:7777".to_string()). Also verify apps/indeedhub/manifest.yml — if it says port 8190, update to 7777 to match the actual deployment. In neode-ui/src/stores/appLauncher.ts line 67, confirm '7777': '/app/indeedhub/' is correct. Deploy with ./scripts/deploy-to-target.sh --live and test.

  • Verify nostr-provider.js injection works for IndeedHub iframe: The NIP-07 Nostr signer works by nginx injecting neode-ui/public/nostr-provider.js into the iframe via sub_filter. Check the IndeedHub nginx location block in image-recipe/configs/nginx-archipelago.conf (lines 334-367) includes a sub_filter that injects <script src="/nostr-provider.js"></script> into the HTML response. If missing, add: sub_filter '</head>' '<script src="/nostr-provider.js"></script></head>'; with sub_filter_once on; and sub_filter_types text/html;. Sync nginx config to server and reload. Verify by loading IndeedHub in the Archy iframe and checking browser dev tools console for window.nostr availability — run JSON.stringify(Object.keys(window.nostr)) in the iframe console, should show ["getPublicKey","signEvent","getRelays","nip04","nip44"].

  • Test full NIP-07 signing flow with IndeedHub: Open Archy at http://192.168.1.228, go to Apps, click IndeedHub. Expected flow: (1) NostrIdentityPicker modal appears on first launch asking which identity to use, (2) select an identity with a Nostr key, (3) IndeedHub loads in iframe, (4) when IndeedHub requests window.nostr.getPublicKey(), the Archy parent responds with the selected identity's Nostr pubkey, (5) when IndeedHub requests window.nostr.signEvent(event), NostrSignConsent modal appears, (6) user approves, event is signed via identity.nostr-sign RPC, (7) signed event returned to IndeedHub. Test each step. If NostrIdentityPicker doesn't show, check AppSession.vue line ~302-304 isIdentityAwareApp() includes 'indeedhub'. If signing fails, check RPC logs: ssh archipelago@192.168.1.228 'sudo journalctl -u archipelago --since "5 min ago" | grep -i nostr'.

  • Ensure IndeedHub content loads fully — all pages, media, navigation: After the Nostr flow works, navigate through IndeedHub's content inside the iframe. Check: (1) all pages/routes load (no blank screens), (2) media content (videos, images) loads, (3) navigation within IndeedHub works without breaking the iframe, (4) no console errors related to CORS, mixed content, or CSP. If videos don't load, check if the video hosting domain is blocked by CSP headers — may need to add Content-Security-Policy adjustments in the nginx location block. If internal navigation causes the iframe to navigate to a bare URL (not under /app/indeedhub/), add sub_filter rules to rewrite the app's internal links.

  • Test NIP-04 and NIP-44 encryption/decryption: In IndeedHub (or manually via browser console in the iframe), test the encryption methods: (1) window.nostr.nip04.encrypt(somePubkey, "test message") — should return ciphertext, (2) window.nostr.nip04.decrypt(somePubkey, ciphertext) — should return "test message", (3) same for nip44.encrypt and nip44.decrypt. If any fail, check RPC handlers in core/archipelago/src/api/rpc/identity.rs — the handle_identity_nostr_encrypt_nip04/nip44 and decrypt handlers (lines 428-496). Check that the identity manager has the required keys.

Phase 5: App Installation & Management Polish

  • Verify install flow for every Bitcoin-related marketplace app: In the Archy UI at http://192.168.1.228, go to Marketplace. For each Bitcoin-related app (Bitcoin Knots, LND, Mempool, BTCPay, Electrs, Fedimint), click through to the detail page. Verify: (1) icon loads correctly (not fallback logo), (2) description is accurate, (3) "Install" button appears if not installed, (4) dependency warnings show correctly (Mempool requires Bitcoin Knots + Electrs, BTCPay requires Bitcoin Knots), (5) if already installed, status shows correctly. Fix any issues found in neode-ui/src/views/MarketplaceAppDetails.vue. Note: Archy is Bitcoin only — remove any Monero or Liquid entries from Marketplace.vue getCuratedAppList() if present.

  • Remove non-Bitcoin altcoin entries from marketplace: Search neode-ui/src/views/Marketplace.vue for "monero", "liquid", "litecoin", or any non-Bitcoin cryptocurrency entries in the getCuratedAppList() function. Remove them entirely. Archy is a Bitcoin-only platform. Run cd neode-ui && npm run type-check after changes.

  • Fix dependency checks — frontend must match backend: In neode-ui/src/views/MarketplaceAppDetails.vue, find the hardcoded dependency definitions (around lines 447-456). Cross-reference with core/archipelago/src/api/rpc/package.rs lines 64-96 where backend dependency checks are defined. Ensure they match exactly. If backend checks for has_bitcoin before installing electrs, the frontend dependency list for electrs must show bitcoin-knots as a prerequisite. Update the frontend to match the backend. Ideally, add an RPC method package.get-dependencies that returns the dependency list from the backend, and have the frontend call it instead of hardcoding — but for now, just make the hardcoded lists match.

  • Verify start/stop/restart works for all installed apps: In the Archy UI, go to Apps. For each installed app, test: (1) click Stop — container stops, UI updates to "Stopped" state, (2) click Start — container starts, UI updates to "Running" state with health indicator, (3) click the app — it launches (iframe or new tab as appropriate). Check that the container store (neode-ui/src/stores/container.ts) correctly polls for status changes after start/stop actions. If status doesn't update, check the WebSocket state broadcasting in core/archipelago/src/state.rs.

  • Fix route-to-package-key mapping divergence: In neode-ui/src/views/AppDetails.vue lines 501-529, the route ID to backend container name mapping is hardcoded. Verify every mapping is correct by checking actual container names on the server: ssh archipelago@192.168.1.228 'sudo podman ps --format "{{.Names}}"'. Fix any mismatches. Known issues: mempool maps to mempool-web but backend may use archy-mempool-web. Check electrs maps to mempool-electrs or archy-electrs. Run cd neode-ui && npm run type-check after changes.

Phase 6: Backend Critical Fixes

  • Fix session TTL clock bug — use SystemTime instead of Instant: Read core/archipelago/src/session.rs. Find where Instant::now() is used for session TTL/expiry (around line 97). Instant is monotonic but can drift on sleep/hibernate — common on NUC/Pi hardware. Replace with SystemTime::now() for absolute time comparison. The FULL_SESSION_TTL (24 hours) and PENDING_TOTP_TTL (5 minutes) checks should use SystemTime::elapsed() or store SystemTime timestamps and compare with SystemTime::now(). Run cargo test --all-features in core/ on the dev server.

  • Enforce RBAC in RPC handler: Read core/archipelago/src/auth.rs — find the UserRole enum and can_access() method. Then read core/archipelago/src/api/rpc/mod.rs — find where authenticated requests are dispatched to handlers. Add a role check before dispatching: after validating the session, get the user's role, call role.can_access(method_name), and return an authorization error if denied. For now, all users created via onboarding should default to Admin role (single-user system), but this lays the groundwork for multi-user. Run cargo clippy --all-targets --all-features && cargo test --all-features on the dev server.

  • Remove dead code and #[allow(dead_code)]: Search core/ for all #[allow(dead_code)] and #[allow(unused)] annotations. For each: (1) if the code is genuinely unused and not part of a planned feature, delete it, (2) if it should be used (like RBAC — now wired up in previous task), remove the allow annotation. Key file: core/archipelago/src/auth.rs lines ~70, 83, 88. Run cargo clippy --all-targets --all-features to verify no new warnings.

  • Deploy and verify backend fixes: Run ./scripts/deploy-to-target.sh --live. After deploy: (1) verify login still works at http://192.168.1.228 (password: password123), (2) verify session persists after navigating between pages, (3) check logs for any new errors: ssh archipelago@192.168.1.228 'sudo journalctl -u archipelago --since "2 min ago" | grep -i error'.

Phase 7: Frontend Cleanup

  • Remove dead dockerode dependency: Run cd /Users/dorian/Projects/archy/neode-ui && npm uninstall dockerode and npm uninstall @types/dockerode if it exists. Search the codebase for any remaining imports: grep -r "dockerode" neode-ui/src/. Remove any dead imports found. Run npm run type-check to verify nothing breaks.

  • Fix the 10 failing frontend tests: Run cd /Users/dorian/Projects/archy/neode-ui && npm run test -- --reporter=verbose 2>&1 | head -100 to see which tests fail. Known failures: (1) src/stores/__tests__/appLauncher.test.ts — URL rewriting tests expecting different proxy behavior, (2) src/views/__tests__/settings.test.ts — heading selector h1 not finding the heading element. For each failing test, read the test file and the component/store it tests. Update test expectations to match current implementation. Do NOT change the production code to match tests — fix the tests. Run npm run test until all pass.

  • Add 404 catch-all route: In neode-ui/src/router/index.ts, add a catch-all route at the end of the routes array: { path: '/:pathMatch(.*)*', name: 'not-found', component: () => import('@/views/NotFound.vue') }. Create neode-ui/src/views/NotFound.vue — a simple view using the existing .glass-card class with "Page not found" message and a router-link back to /dashboard. Use <script setup lang="ts">, no props needed. Style with existing global classes only (.glass-card, .glass-button). Run npm run type-check.

Phase 8: Web5 Identity & Credentials Hardening

Context: TBD/Block shut down Nov 2024 — Web5 repos donated to DIF but effectively unmaintained. Archy's custom implementations (did:key, did:dht, VCs, multi-identity) are W3C-compliant and well-tested. SpruceID ssi crate (v0.15.0, Feb 2026) is the only mature Rust DID/VC library. DWN spec is stalled — no Rust implementation exists anywhere. Strategy: keep our custom stack (it's good), fix onboarding gaps, encrypt credential storage, validate against W3C specs, evaluate ssi for external VC verification only, deprioritize DWN in favor of Nostr + federation. Do NOT adopt dead TBD SDKs.

  • Fix DID onboarding — replace mock signature with real proof-of-control: In neode-ui/src/views/OnboardingVerify.vue, the verification step uses generateMockSignature() instead of real cryptographic proof. Replace with a call to node.signChallenge RPC (or identity.sign if it exists). The flow should be: (1) frontend generates a random challenge string, (2) sends to identity.sign RPC with the node's default identity, (3) backend signs with Ed25519 key, (4) frontend displays the signature as proof the node controls the DID. Check core/archipelago/src/api/rpc/identity.rs for existing sign handlers — handle_identity_sign should work. If node.signChallenge RPC doesn't exist, the identity.sign endpoint (which takes { id?, data } and returns { signature }) should be sufficient. Update the Vue component to call it. Run cd neode-ui && npm run type-check.

  • Fix DID onboarding — real encrypted backup: In neode-ui/src/views/OnboardingBackup.vue, the backup step uses mock JSON data instead of real encrypted key material. Replace with a call to identity.export or backup.create-identity RPC (check what exists in core/archipelago/src/api/rpc/identity.rs and core/archipelago/src/api/rpc/backup_rpc.rs). The backup should contain the Ed25519 private key encrypted with the user's password via Argon2 + ChaCha20-Poly1305 (the encryption stack already exists in core/security/). If no export RPC exists, create one that: (1) derives a key from the user's password with Argon2, (2) encrypts the identity's private key with ChaCha20-Poly1305, (3) returns base64-encoded ciphertext. The frontend should offer this as a downloadable .json file. Run cargo test --all-features on the dev server.

  • Fix DID onboarding UX copy: In neode-ui/src/views/OnboardingDid.vue, the copy says "Generate DID" but actually fetches an existing DID from the server (generated at first boot). Update the button text to "View Your DID" or "Retrieve Your DID" and the description to explain that the DID was created when the node was set up. Small change but prevents user confusion. Do NOT change any styling or layout.

  • Validate DID Document structure against W3C spec: In core/archipelago/src/identity.rs, the generate_did_document() function builds a DID Document. Verify it includes all required fields per W3C DID Core v1.0: id, verificationMethod (with correct type: "Ed25519VerificationKey2020"), authentication, assertionMethod, keyAgreement (X25519). Check that @context includes ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/suites/ed25519-2020/v1"]. Add a unit test that validates the document structure against these requirements. Run cargo test --all-features.

  • Validate Verifiable Credentials against W3C VC 2.0 spec: In core/archipelago/src/credentials.rs, verify the VerifiableCredential struct produces output matching W3C VC Data Model 2.0. Check: (1) @context includes https://www.w3.org/ns/credentials/v2, (2) type array starts with "VerifiableCredential", (3) proof uses Ed25519Signature2020 with proper structure (type, created, verificationMethod, proofPurpose, proofValue), (4) issuanceDate is RFC 3339, (5) credentialSubject has id field with holder DID. Add a test that issues a credential, serializes to JSON, and validates all required fields. Run cargo test --all-features.

  • Evaluate SpruceID ssi crate for DID resolution validation: Add ssi = "0.15" to core/Cargo.toml as an optional dependency ([dependencies.ssi] version = "0.15" optional = true). Create a test (behind #[cfg(feature = "ssi-compat")]) that: (1) generates a DID Document with Archy's identity.rs, (2) parses it with ssi::did::Document, (3) verifies the structure is valid per the ssi library's validation. This is a compatibility check — if ssi can parse our documents, we're spec-compliant. If it fails, note what's wrong. Do NOT make ssi a required dependency — this is for validation only. Run cargo test --features ssi-compat on dev server.

  • Evaluate pkarr crate for did:dht enhancement: Research the pkarr crate (v5.0.3, 550K downloads) by reading its documentation. It provides Ed25519-public-key-addressable resource records over the Mainline DHT — essentially did:dht but with better tooling and active maintenance. Compare with Archy's current did_dht.rs implementation that uses mainline directly. If pkarr offers advantages (relay fallback, caching, DNS-packet handling), document them in docs/pkarr-evaluation.md. Do NOT switch yet — just evaluate and document findings. Key question: does pkarr handle the BEP-44 signed DNS packet encoding that Archy currently does manually in did_dht.rs?

  • Clean up DWN — remove dead TBD references and simplify: Search the codebase for any references to TBD URLs, @tbd54566975, tbd.website, or TBD-specific terminology. Remove them. In docs/dwn-protocols.md, update the context to note that TBD is defunct and Archy's DWN is a custom implementation for peer sync, not a full DWN spec implementation. In core/archipelago/src/network/dwn_store.rs, verify the protocol definitions use Archy-specific URLs (https://archipelago.dev/protocols/...) not TBD URLs. Keep the DWN store functionality — it works for peer file catalogs and federation state — but stop calling it "Web5 DWN" in user-facing text. In neode-ui/src/views/Web5.vue, if there are references to "TBD" or "Web5 by TBD", update to just "Decentralized Identity" or "Web5 Standards".

  • Add did:dht auto-refresh background task: In core/archipelago/src/server.rs, add a background task that refreshes the did:dht publication every 2 hours. DHT records expire if not re-published. The task should: (1) check if the node has a published did:dht, (2) if yes, call did_dht::create_and_publish() to re-publish, (3) log success/failure. Use tokio::spawn with tokio::time::interval(Duration::from_secs(7200)). Only run if config.nostr_discovery_enabled is true (the same flag that gates DHT usage). Add the task alongside the existing background tasks (container scanner, peer health, etc.).

  • Encrypt credentials storage at rest: Read core/archipelago/src/credentials.rs — credentials are stored as plaintext JSON in {data_dir}/credentials/credentials.json. These may contain sensitive claims about identity holders. Fix: encrypt the file at rest using AES-256-GCM (the aes-gcm crate is already a dependency). Follow the pattern used in core/security/ for secrets encryption — derive a key from the node's master key. On read: detect if file is plaintext JSON (starts with [ or {) vs encrypted (binary/base64), decrypt if needed. On write: always encrypt. This provides a migration path — existing plaintext files get encrypted on first write. Add a test that writes credentials, reads them back, and verifies the file on disk is not plaintext. Run cargo test --all-features on dev server.

  • Add identity lifecycle integration tests: In core/archipelago/src/identity_manager.rs, add comprehensive tests for the full lifecycle: (1) create identity with default purpose → verify did:key format matches did:key:z6Mk..., (2) create Nostr key → verify npub starts with npub1, (3) sign arbitrary data → verify signature with public key, (4) issue a VC from this identity → verify the VC, (5) create a presentation wrapping the VC → verify the presentation, (6) delete identity → verify it's gone and default shifts. Use tempfile::tempdir() for storage. Target: 8+ new #[tokio::test] cases. Run cargo test --all-features.

  • Write ADR for DWN deprioritization: Create docs/adr/011-dwn-deprioritization.md. Document: (1) TBD/Block shut down Nov 2024, donated code to DIF, (2) no maintained Rust DWN SDK exists, (3) DWN spec losing momentum without TBD's backing, (4) Archy's federation over Tor + Nostr relays already serve the peer data sync use case, (5) DWN store code stays in codebase but is not actively developed, (6) re-evaluate if DIF produces a viable Rust SDK. Follow existing ADR format in docs/adr/. This is documentation only — no code changes.

  • Deploy to both nodes and test Web5 features: Deploy with ./scripts/deploy-to-target.sh --both. Test at http://192.168.1.228: (1) navigate to Web5 page — DID displays correctly, (2) click "Publish to DHT" if available — should publish and show status, (3) go to Credentials page — issue a test credential to self, verify it shows in list. Repeat on http://192.168.1.198. Check logs on both: ssh archipelago@192.168.1.228 'sudo journalctl -u archipelago --since "5 min ago" | grep -iE "(did|credential|dwn|identity)"' and same for .198.

  • Test cross-node DID resolution between .228 and .198: From .228's Web5 page, get its DID (did:key). SSH to .198 and test resolving .228's DID: curl -s http://localhost:5678/rpc/v1 -H 'Content-Type: application/json' -d '{"method":"identity.resolve-remote-did","params":{"did":"<.228-did>","onion_address":"<.228-onion>"}}'. The response should return .228's full DID Document. Test the reverse direction (resolve .198's DID from .228). If resolution fails, check: (1) Tor is running on both nodes (sudo podman ps | grep tor), (2) onion addresses are valid (cat /var/lib/archipelago/tor/*/hostname), (3) RPC is accessible over Tor. Fix any issues found.

  • Test cross-node credential issuance and verification: From .228, issue a Verifiable Credential where .228 is the issuer and .198's DID is the subject. Use the Credentials UI or RPC: curl -s http://localhost:5678/rpc/v1 -H 'Content-Type: application/json' -d '{"method":"identity.issue-credential","params":{"subject_did":"<.198-did>","credential_type":"FederationMember","claims":{"role":"peer","joined":"2026-03-15"}}}'. Copy the credential ID. From .198, verify the credential: curl -s http://localhost:5678/rpc/v1 -H 'Content-Type: application/json' -d '{"method":"identity.verify-credential","params":{"credential_id":"<id>"}}'. If .198 can't verify (it needs .228's public key), test the resolution chain: .198 resolves .228's DID → extracts public key → verifies signature. Fix any issues in the verification flow.

  • Test federation trust via DIDs between .228 and .198: Verify the federation between the two nodes uses DID-based identity. SSH to .228: curl -s http://localhost:5678/rpc/v1 -H 'Content-Type: application/json' -d '{"method":"federation.list-nodes"}'. Check that .198 appears as a peer with its DID. SSH to .198 and verify .228 appears similarly. If federation is not set up between them, establish it: use federation.invite on .228 to generate an invite, then federation.join on .198. After joining, verify: (1) both nodes see each other in their peer lists, (2) both nodes have each other's DIDs, (3) peer health checks pass between them. Check logs for federation errors: sudo journalctl -u archipelago --since "10 min ago" | grep -i federation.

  • Test DWN sync between .228 and .198: Even though DWN is deprioritized, test the existing sync functionality. On .228, write a test DWN message: curl -s http://localhost:5678/rpc/v1 -H 'Content-Type: application/json' -d '{"method":"dwn.write","params":{"protocol":"https://archipelago.dev/protocols/file-catalog/v1","data":{"filename":"test.txt","size":1024}}}'. Check DWN status on both nodes: curl -s http://localhost:5678/rpc/v1 -d '{"method":"dwn.status"}'. If sync is working, the message should appear on .198 after a sync cycle. If sync is not working, document what fails and where — this informs whether to invest more or formally pause DWN development. Don't spend more than 15 minutes debugging — document findings either way.

Phase 9: Factory Reset, Restore, & End-to-End Onboarding Test

Goal: Be able to factory reset the node, go through onboarding (DID + Nostr key created together), keys loaded into identity management, sign into IndeedHub with native Nostr signer, content loads. Also: restore from backup on the very first screen.

  • Implement system.factory-reset RPC endpoint: Create a new RPC handler in core/archipelago/src/api/rpc/system.rs (or add to an existing system module). The system.factory-reset method should: (1) require authentication (admin only), (2) accept { confirm: true } param as a safety check, (3) stop all running containers via PodmanClient (iterate podman ps -q and stop each), (4) delete user data: remove {data_dir}/user.json, {data_dir}/onboarding.json, {data_dir}/identities/ directory, {data_dir}/credentials/ directory, {data_dir}/peers.json, {data_dir}/did-cache/ directory, {data_dir}/dwn/ directory, (5) keep container images (don't re-download), keep the identity/node_key (node identity persists — it's the hardware identity), keep nginx and systemd configs, (6) clear all sessions from the session store, (7) restart the Archipelago service: sd_notify::notify(false, &[sd_notify::NotifyState::Reloading]) then exit the process (systemd will restart it), or alternatively use std::process::Command::new("sudo").args(["systemctl", "restart", "archipelago"]).spawn(). Register the handler in core/archipelago/src/api/rpc/mod.rs. Run cargo clippy --all-targets --all-features && cargo test --all-features on the dev server.

  • Add factory reset button to Settings.vue: In neode-ui/src/views/Settings.vue, add a "Factory Reset" section at the very bottom of the page (after all other settings). Use a .path-option-card container with a red-tinted warning. Include: (1) heading "Factory Reset", (2) description "Wipe all user data, identities, and credentials. Container images are preserved. The node will restart and show the onboarding screen.", (3) a .glass-button styled with red text/border that says "Factory Reset", (4) on click, show a confirmation dialog (use a simple v-if modal with .glass-card styling) asking "Are you sure? This will delete all identities, credentials, and settings. This cannot be undone." with Cancel and "Yes, Reset" buttons, (5) on confirm, call rpcClient.call({ method: 'system.factory-reset', params: { confirm: true } }), (6) on success, clear all localStorage (localStorage.clear()), redirect to /onboarding/intro. Use existing glass styles only — no new CSS classes. Run cd neode-ui && npm run type-check.

  • Add "Restore from Backup" button to OnboardingIntro.vue (first screen): In neode-ui/src/views/OnboardingIntro.vue, this is the very first screen a user sees after a fresh install or factory reset. Currently it just has a "Unlock your sovereignty →" button. Add a "Restore from Backup" link below it. Implementation: (1) add showRestore and restoreFile and passphrase refs, (2) below the main CTA button, add a subtle text link "Restore from backup" (style: text-white/50 hover:text-white/80 underline text-sm cursor-pointer mt-4 block text-center), (3) clicking it toggles a restore panel (use .glass-card) with: a file input (<input type="file" accept=".json">) for the archipelago-did-backup.json file, a password input for the backup passphrase, and a "Restore" .glass-button, (4) on file select, read the JSON with FileReader, (5) on Restore click, call rpcClient.call({ method: 'backup.restore-identity', params: { backup: parsedJson, passphrase: password } }), (6) on success, show "Identity restored successfully" message, then navigate to /onboarding/did — the DID step will now show the restored DID instead of generating a new one. Run cd neode-ui && npm run type-check.

  • Implement backup.restore-identity RPC for DID restore: Check if core/archipelago/src/api/rpc/backup_rpc.rs has an identity-specific restore handler. The existing backup.restore is for full system backups (tar archives from USB). We need a lighter backup.restore-identity that: (1) accepts the JSON blob from node.createBackup (the archipelago-did-backup.json file), (2) extracts: version, encrypted blob, (3) decrypts with Argon2 + ChaCha20-Poly1305 using the provided passphrase (reverse of backup::create_encrypted_backup() in core/archipelago/src/backup/identity.rs), (4) writes the decrypted 32-byte Ed25519 private key to {data_dir}/identity/node_key with 0o600 permissions, (5) returns { did, pubkey } of the restored identity. If the backup/identity.rs module already has a restore_encrypted_backup() function, use it. If not, create one following the inverse of create_encrypted_backup(). Register the handler in rpc/mod.rs. Run cargo clippy --all-targets --all-features && cargo test --all-features.

  • Ensure DID + Nostr keypair exist immediately from boot / factory reset: The node's Ed25519 key is auto-generated at first boot (stored in identity/node_key), and node.did / node.nostr-pubkey RPCs derive from it. But user identities with Nostr keys are only created when the user reaches the Identity step in onboarding. Fix this so keys are available from the very start: (1) In core/archipelago/src/main.rs or server.rs, during startup (after loading node identity but before starting the HTTP server), check if any identities exist via IdentityManager::list(). If the list is empty (fresh boot or factory reset), auto-create a default identity: call identity_manager.create("Default", IdentityPurpose::Personal) — this generates Ed25519 + Nostr keypair automatically. (2) Verify identity_manager.rs create() method calls create_nostr_key() automatically — if not, add it after keypair generation. (3) This means when OnboardingDid.vue loads, both node.did AND identity.list already return data with Nostr npub populated. The identity step in onboarding can then let the user rename or create additional identities, but the default is already there. (4) After factory reset (which deletes {data_dir}/identities/), the next boot auto-creates the default identity again. Run cargo test --all-features on the dev server.

  • Deploy factory reset + restore and test the full cycle: Deploy with ./scripts/deploy-to-target.sh --live. Then run the end-to-end test on .228: (1) Login at http://192.168.1.228, go to Settings, scroll to bottom, click "Factory Reset", confirm, (2) node restarts — wait 10-15 seconds, refresh browser, (3) should see the onboarding intro screen, (4) go through: Intro → Path → DID (should show new or existing DID + Nostr npub) → Identity (create "Personal" identity) → Backup (download backup file) → Verify (signature verified) → Done → Login, (5) set password, login, (6) navigate to Web5/Identity page — DID and Nostr npub should display, (7) go to Apps → click IndeedHub, (8) NostrIdentityPicker should appear — select the identity just created, (9) IndeedHub should load in iframe, (10) IndeedHub should request window.nostr.getPublicKey() — Archy returns the identity's Nostr pubkey, (11) if IndeedHub requires signing, NostrSignConsent appears, approve it, (12) IndeedHub content should load from their API (videos, pages). Check logs: ssh archipelago@192.168.1.228 'sudo journalctl -u archipelago --since "5 min ago" | grep -iE "(factory|reset|onboard|identity|nostr|indeedhub)"'.

  • Test restore from backup on fresh state: After the previous test, do another factory reset on .228. This time: (1) when the first screen appears (Login.vue in setup mode), click "Restore from Backup", (2) select the archipelago-did-backup.json file downloaded in the previous test, (3) enter the backup passphrase, (4) click Restore, (5) should see success message, (6) continue onboarding — the DID step should show the SAME DID as before (restored from backup), (7) create identity, complete onboarding, (8) login and verify: same DID, identity management has the restored keys, (9) go to IndeedHub — Nostr signing should work with the restored identity. If any step fails, check: backend logs for restore errors, frontend console for RPC failures, verify the backup file format matches what backup.restore-identity expects.

Phase 10: Final Verification & Deploy

  • Full type-check and lint pass: Run cd /Users/dorian/Projects/archy/neode-ui && npm run type-check — must pass with zero errors. Run npm run test — all tests must pass. On dev server, run cd ~/archy/core && cargo clippy --all-targets --all-features — zero warnings. Run cargo test --all-features — all tests pass.

  • Final deploy and complete smoke test: Run ./scripts/deploy-to-target.sh --live. After deploy, test the full user flow at http://192.168.1.228: (1) login works, (2) dashboard loads with app list, (3) click each installed app — loads in iframe or new tab correctly, (4) go to Marketplace — all icons load, no broken images, no altcoins, (5) open IndeedHub — identity picker shows, select identity, app loads, Nostr signing works, content from their API loads, (6) start/stop an app — status updates correctly, (7) navigate to a fake URL like /dashboard/nonexistent — shows 404 page with back link, (8) Web5 page shows DID + Nostr npub correctly, credentials can be issued and verified, (9) Settings page has Factory Reset at the bottom, (10) factory reset works — node restarts, onboarding appears, (11) restore from backup works on first screen, (12) check server logs for errors: ssh archipelago@192.168.1.228 'sudo journalctl -u archipelago --since "5 min ago" | grep -i error'.

Phase 11: Security & Code Quality Audit Report

Generate a comprehensive written report at docs/security-code-audit-2026-03.md. This phase is research and documentation only — no code changes. The report should be honest about strengths and weaknesses so we know exactly where we stand.

  • Audit authentication & session security: Review core/archipelago/src/auth.rs and core/archipelago/src/session.rs. Document: (1) password hashing — bcrypt with what cost factor? Is Argon2id a better choice for new installs? Compare bcrypt (current) vs argon2id (already a dependency for backup encryption) — pros/cons, (2) session token generation — is 32-byte random hex sufficient entropy? How does it compare to using a CSPRNG-backed JWT or tower-sessions? (3) session storage — in-memory only, lost on restart (unless SQLite was added in earlier phases). Rate the risk, (4) CSRF — 32-byte hex token per login, validated on every request. Is this sufficient? (5) rate limiting — per-method in-memory counters. Document coverage gaps (which endpoints lack rate limiting), (6) TOTP — using totp-rs with encrypted secret storage. Rate the implementation quality. Write findings to a "Session & Auth" section of the report.

  • Audit cryptographic implementations: Review all crypto code across the codebase. For each, compare our implementation against what a library would provide:

    Component Our Implementation Library Alternative Verdict
    Password hashing bcrypt crate, DEFAULT_COST argon2 crate (already a dep) Document: argon2id is newer, memory-hard, better against GPU attacks. bcrypt is battle-tested. Recommendation?
    Session tokens rand::thread_rng().gen::<[u8; 32]>() + hex tower-sessions or signed JWTs via jsonwebtoken Document: current is fine for single-instance. JWTs add stateless verification but complexity
    DID signing ed25519-dalek direct usage SpruceID ssi crate Document: our usage is correct and minimal. ssi adds 50+ transitive deps for features we don't use
    Backup encryption Argon2 KDF + ChaCha20-Poly1305 age crate (encryption tool) Document: our stack is standard and correct. age is simpler API but less control
    VC signatures Custom Ed25519Signature2020 proof SpruceID ssi VC module Document: our impl handles one proof type. ssi handles many but large dep tree
    Nostr encryption nostr-sdk NIP-04/NIP-44 Direct chacha20poly1305 + secp256k1 Document: nostr-sdk is correct choice, actively maintained
    TLS rustls via reqwest openssl Document: rustls is the right choice — pure Rust, no C deps, privacy-focused
    Key storage Raw bytes in files with 0o600 perms keyring crate or OS keychain Document: file-based is correct for headless server. OS keychain not available

    Write findings to a "Cryptographic Review" section. For each row, state: is our code correct? Is it secure? Would a library be better? Why or why not?

  • Audit container security: Review container security across core/container/src/podman_client.rs, core/archipelago/src/api/rpc/package.rs, and apps/*/manifest.yml. Document: (1) are all containers running with --cap-drop ALL + only required caps added back? Check each app manifest, (2) readonly_root: true — which apps have it, which don't and why, (3) no-new-privileges — is it set for all containers? (4) user namespace — are containers running as non-root (UID > 1000)? Check for any running as root, (5) image pinning — are images pinned to specific digests/versions or using :latest? List offenders, (6) cosign verification — still a TODO? Document the gap, (7) network isolation — which containers share networks? Is archy-net properly scoped? (8) secrets injection — how are secrets passed to containers? Env vars (visible in podman inspect) vs mounted files? Write findings to a "Container Security" section.

  • Audit RPC endpoint security: Review core/archipelago/src/api/rpc/mod.rs — the main RPC dispatcher. Document: (1) which endpoints require authentication and which don't? List any unauthenticated endpoints beyond auth.login, auth.setup, auth.isSetup, auth.isOnboardingComplete, (2) RBAC enforcement — was it wired up in Phase 6? If yes, verify it works. If no, document the gap and risk, (3) input validation — pick 5 critical endpoints (login, install package, factory reset, backup restore, identity create) and trace the input from RPC params to handler. Are inputs validated? Are there injection risks? (4) error message sanitization — does sanitize_error_message() strip file paths and internal details from user-facing errors? Test with a few error cases, (5) path traversal — check filebrowser-client.ts sanitizePath() and any backend file operations. Can a crafted path escape the data directory? Write findings to an "RPC Security" section.

  • Audit frontend security: Review the Vue frontend for common web vulnerabilities. Document: (1) XSS — are any user inputs rendered with v-html? Search for v-html across all .vue files. If found, is the content sanitized? (2) CSRF — frontend sends X-CSRF-Token header on every RPC call. Verify this in rpc-client.ts. Is the token properly scoped to the session? (3) credential storage — what's in localStorage? Search for localStorage.setItem across all files. Are any secrets (passwords, keys, tokens) stored client-side? They shouldn't be — only session flags and UI preferences, (4) iframe security — nostr-provider.js uses postMessage('*') for responses. Is the origin validated on incoming messages? Check AppSession.vue and AppLauncherOverlay.vue message handlers — do they verify event.origin? (5) dependency audit — run cd neode-ui && npm audit and document findings. Write findings to a "Frontend Security" section.

  • Assess custom code quality vs library alternatives — full comparison: This is the core of the report. For each major custom module, write a comparison:

    1. HTTP Server (custom hyper 0.14 handler.rs — 813 lines)

    • Quality: Hand-rolled routing, middleware, CORS, WebSocket upgrade. Works but brittle.
    • Alternative: axum (tokio team, built on hyper 1.x). Typed extractors, middleware stack, tower integration.
    • Verdict: Migrate. hyper 0.14 is EOL. axum reduces handler.rs from 813 lines to ~200.
    • Risk: Medium — RPC logic unchanged, only HTTP glue changes.

    2. Session Management (custom session.rs — 200 lines)

    • Quality: In-memory token store, TTL-based expiry, max 5 concurrent sessions, zeroize on drop.
    • Alternative: tower-sessions + tower-sessions-sqlx-store (SQLite backend).
    • Verdict: If SQLite is added, migrate. If not, keep custom — it's simple and correct for single-instance.

    3. Rate Limiting (custom in rpc/mod.rs)

    • Quality: Per-method in-memory counters. Simple, works, not configurable.
    • Alternative: governor crate or tower::limit::RateLimitLayer.
    • Verdict: Low priority swap. Current works fine for single-instance appliance.

    4. DID Implementation (custom identity.rs — ~300 lines)

    • Quality: Clean did:key generation, proper W3C DID Document, good test coverage.
    • Alternative: SpruceID ssi crate (v0.15.0, 146K downloads).
    • Verdict: Keep custom. Our code is ~300 lines, purpose-built, handles dual-key (Ed25519+secp256k1). ssi would add 50+ transitive deps for features we don't need. Use ssi only for external VC verification if needed.

    5. Verifiable Credentials (custom credentials.rs — ~400 lines)

    • Quality: W3C VC 2.0 compliant, issue/verify/revoke/present all working, good test coverage.
    • Alternative: SpruceID ssi VC module.
    • Verdict: Keep custom for issuance. Consider ssi for verification of external VCs (more proof types). Our code handles Ed25519Signature2020 only — sufficient for node-to-node but not for arbitrary external VCs.

    6. did:dht (custom did_dht.rs — ~200 lines)

    • Quality: Works via mainline crate, BEP-44 signed records, in-memory cache.
    • Alternative: pkarr crate (v5.0.3, 550K downloads) — higher-level abstraction over mainline.
    • Verdict: Evaluate pkarr. If it handles BEP-44 encoding we do manually, switch. Otherwise keep custom — it's small and works.

    7. DWN Store (custom dwn_store.rs — ~300 lines)

    • Quality: Basic CRUD, filesystem-backed, protocol registration. Skeletal.
    • Alternative: None production-ready in Rust. dwn crate (unavi-xyz) is v0.4.0, 323 downloads.
    • Verdict: Keep custom. No alternative exists. Deprioritize per ADR-011.

    8. WebSocket State Broadcasting (custom state.rs — ~200 lines)

    • Quality: tokio broadcast channel, full model resync on every change. Functional but inefficient.
    • Alternative: json-patch crate for RFC 6902 diffs. Frontend already has fast-json-patch.
    • Verdict: Add json-patch crate. One of the highest-impact improvements — reduces bandwidth dramatically.

    9. Form Validation (manual inline in Vue components)

    • Quality: Scattered, inconsistent, error-prone as forms grow.
    • Alternative: zod (TypeScript-first schema validation, 40M weekly npm downloads).
    • Verdict: Add zod. Centralize schemas in src/types/schemas.ts. Critical for onboarding where bad input can break key generation.

    10. Container Runtime Abstraction (custom runtime.rs + podman_client.rs — ~600 lines)

    • Quality: Clean trait abstraction (PodmanRuntime, DockerRuntime, AutoRuntime). Well-designed.
    • Alternative: bollard crate (Docker/Podman API client, 7M downloads).
    • Verdict: Keep custom. Our abstraction is clean and purpose-built. bollard is Docker-first and would need wrapping anyway for our manifest-based approach.

    Write all comparisons to a "Custom Code vs Libraries" section with a summary table.

  • Write executive summary and next steps: At the top of docs/security-code-audit-2026-03.md, write an executive summary covering: (1) overall security posture (1-10 rating with justification), (2) top 5 risks ranked by severity, (3) top 5 strengths, (4) recommended next actions (ordered by impact). Reference the docs/refactoring-plan.md 3-year plan for longer-term items. End with a "What to do next" section listing the 3 most impactful changes from this audit. Commit the report.