archy/CHANGELOG.md

Changelog

All notable changes to Archipelago will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[1.3.0] - 2026-03-19

Security

Pentest Remediation (33 findings, all addressed)

• Critical: Backend now binds to 127.0.0.1 only — no more direct LAN access to port 5678
• Critical: Fixed path traversal in Tor service management that could allow sudo rm -rf on arbitrary directories
• Critical: Fixed unauthenticated file read/delete via DWN recordId path traversal
• High: Federation peers now require cryptographic signature — unsigned peers rejected
• High: Login redirect XSS vulnerability fixed with proper URL validation
• High: Viewer role restricted to read-only node methods (was granting sign/export access)
• High: Backup restore/verify now validates IDs against path traversal
• High: Tar archive extraction validates every entry path (prevents tar slip attacks)
• High: S3 backup endpoints require HTTPS and reject private IP ranges
• Medium: Remember-me token secret now uses cryptographic random (not machine-id)
• Medium: Destructive operations (factory reset, onboarding reset) now require password re-verification
• Medium: Session token rotated after TOTP verification (prevents interception reuse)
• Medium: Webhook URL validation hardened against IPv6 bypass, DNS rebinding, redirect chains
• Low: CORS localhost:8100 only included in dev mode
• Low: CSP unsafe-inline removed from script-src
• Low: Content filenames validated against path separators and hidden file prefixes
• Low: Nostr relay URLs restricted to wss:// with private IP rejection
• Low: Onion address validation enforces v3 format (56 base32 chars)
• Low: Router detection restricted to private IP ranges only

Nginx Authentication

• Fixed session cookie name mismatch (session_id → session) across all nginx auth checks
• LND Connect info endpoint now properly authenticated

Container Reliability

Memory Limits (prevents OOM crashes)

• All 37 containers in first-boot-containers.sh now have --memory= limits
• Automatic RAM tier detection — reduced limits on 8GB machines
• Prevents a single runaway container from crashing the entire system

Smart Container States

• New exited state distinguishes crashed containers from intentionally stopped ones
• Crashed containers show red "crashed" badge with restart button
• Health-aware status: "healthy" (green), "starting up" (yellow spinner), "unhealthy" (orange pulse)
• Restart button added next to Stop on running containers

Crash Recovery Improvements

• Boot recovery and health monitor now coordinate via shared flag (no more restart cascade)
• User-stopped containers tracked in user-stopped.json — survive reboots without auto-restart
• Boot recovery uses tiered ordering: databases → core → services → apps → UIs
• Health monitor waits for boot recovery to complete before starting checks

UI Improvements

Home Dashboard

• Wallet card now matches Web5 wallet display
• New Transactions modal with full history (incoming/outgoing, amounts, confirmations)
• Transactions button in header — switches to "Incoming" badge when pending transactions exist
• Dev faucet button (dev mode only) with mutable wallet state
• Fixed system stats crash (cpu_usage_percent field name mismatch)

Apps & App Details

• Container restart button (icon) next to Stop on all running apps
• Exited/crashed containers show "Restart" instead of "Start" with red styling
• Removed broken sticky header from Apps page
• Health-aware status badges throughout

Mesh, Cloud, Settings & More

• Mesh view overhaul with improved layout
• Glass button styling updates across components
• New BaseModal and ToggleSwitch components
• Updated translations (English + Spanish)
• Spotlight search improvements

Infrastructure

LND Connect

• Tor hidden service now exposes LND REST port (8080) for remote wallet connections
• Fixed in ISO build script, deploy script, and live servers

Dev Environment

• Mock backend has mutable wallet state (faucet/send/receive actually change balances)
• Testnet stack option auto-starts Podman machine on macOS
• Boot mode simulation for testing startup screens

[1.2.0] - 2026-03-14

Fixed

Crash Loop Resolution

• Identified and fixed UFW blocking Podman subnet DNS resolution on .228
• Fixed archy-nbxplorer, btcpay-server, mempool-web, immich crash loops (3500+ restarts)
• All 32 containers stable with zero crash loops after fix

DWN Sync Performance

• Made dwn.sync endpoint non-blocking (background task with polling)
• Added 90-second overall sync timeout to prevent indefinite blocking
• Deduplicated peer onion addresses before syncing
• Batched message pushes (50/batch) instead of one-at-a-time over Tor
• Fixed HTTP handler to process all messages in batch (was only first)

Backup Reliability

• Increased backup.create rate limit from 3/600 to 10/600 for testing
• Increased backup.restore rate limit from 2/600 to 5/600

Deploy Script

• Added set -eo pipefail for pipe error detection
• Fixed duplicate variable initialization
• Fail on missing binary in --both path (was silently ignored)
• Added post-deploy health check on .198

Added

Cross-Node Test Suite

• US-08: DWN sync tests — 50/50 pass (register, write, sync, query bidirectional)
• US-10: Backup/restore tests — 80/80 pass (create, list, verify, delete × 10 × 2 nodes)
• US-15: Boot recovery tests — .228 9/9 pass (32/32 containers survive 3 reboots)
• trigger_sync_and_wait() helper for polling async DWN sync

did:dht Integration Planning

• Architecture document: docs/did-dht-integration.md
• BEP-44 mutable DHT items, DNS packet encoding, z-base-32 identifiers
• Publication/resolution flows, mainline crate selection, security notes

DWN Protocol Definitions

• 4 Archipelago DWN protocols documented in docs/dwn-protocols.md
• Node Identity Announcements (public)
• File Sharing Catalog (public)
• Federation State (private)
• App Deployment Requests (private)
• Auto-registration of all 4 protocols on backend startup

Deploy Script Improvements

• --dry-run flag shows what would be deployed without executing
• Works with all other flags (--live, --both, --frontend-only)

ISO/First-Boot Improvements

• Auto-create swap file on first boot (50% RAM, min 2GB, max 8GB)
• Tiered container startup ordering in first-boot script
• Tier 1: Databases, Tier 2: Core Services (5s delay), Tier 3: Applications (5s delay)

Security

Backend Hardening

• Rate limiting on federation endpoints (join 5/60s, invite 10/300s)
• DWN message data size limit (10MB max)
• Container security: cap-drop ALL, no-new-privileges, per-app memory limits
• Input validation: path traversal protection on identity/DID endpoints
• Error sanitization: internal paths stripped from error messages

[1.1.0] - 2026-03-13

Added

Nostr Identity in Onboarding

• Auto-generate secp256k1 Nostr keypair during identity creation
• Onboarding shows both DID (did:key:z...) and Nostr ID (npub1...) with copy buttons
• Real Ed25519 signature verification in onboarding verify step
• Real encrypted backup creation in onboarding backup step

NIP-07 Iframe Signing

• nostr-provider.js injected into all proxied iframe apps via nginx sub_filter
• window.nostr interface: getPublicKey(), signEvent(), getRelays()
• Signing consent modal with "Remember for this app" option
• node.nostr-sign RPC endpoint — signs events with node-level Nostr key
• NIP-04 and NIP-44 encrypt/decrypt RPC endpoints for iframe apps
• noStrudel Nostr client added to marketplace as iframe app

File Sharing Across Nodes

• Content catalog with add/remove/browse over Tor
• Three access modes: free, peers_only (DID-authenticated), paid (cashu tokens)
• Availability controls: AllPeers, Nobody, Specific (DID allowlist)
• Peer Files view in Cloud page for browsing federated peers' shared content
• Content download from peers via Tor SOCKS proxy

DWN Multi-Node Sync

• Bidirectional DWN message replication over Tor between federated nodes
• Protocol and message sync via /dwn HTTP endpoint
• DWN sync status in Federation dashboard with "Sync Now" button
• DWN management section in Web5 page (protocols, messages, sync targets)

Node Visualization Map

• D3.js force-directed network topology graph
• Nodes colored by trust level (green/amber/red), opacity by online status
• Self node centered, draggable peer nodes with tooltips
• List/Map tab switcher in Federation page with localStorage persistence

Tor Address Rotation

• tor.rotate-service RPC: generates new .onion address with 24h transition
• Automatic propagation to Nostr relays and federation peers
• tor.cleanup-rotated for expired transition directories
• Per-app Tor toggle (tor.toggle-app) to enable/disable Tor per service
• Tor management UI in Settings with rotate button and per-app toggles

Boot Container Recovery

• All stopped containers automatically started on backend boot
• Fixes clean reboot scenario where PID marker was removed by systemd

Monitoring & Testing

• Federation health check script (cron every 5min, CSV + JSON output)
• Uptime monitor with authenticated RPC access
• test-first-install.sh — 8-check post-install verification
• test-nip07.sh — 11-check NIP-07 signing validation
• test-tor-rotation.sh — 10-check Tor rotation lifecycle
• test-integration-full.sh — 23-check full integration test
• test-failure-recovery.sh — 5-scenario failure injection + recovery

Fixed

• Health monitor webhook gate no longer blocks auto-restart and notifications
• Monitoring alerts now trigger webhook delivery (DiskWarning, ContainerCrash)
• Tor hostname reading with tor-hostnames readable cache (0700 system Tor dirs)
• Tor rotation clears hostname cache before reading new address
• Rotation restarts system Tor (not just archy-tor container)
• NIP-07 signing uses node-level key (matches getPublicKey())
• DWN sync URL uses port 80 (nginx/Tor) instead of 5678
• DWN /dwn POST endpoint allows unauthenticated peer sync
• DWN message handler supports both single and batch message formats

[0.8.0-rc1] - 2026-03-11

Added

W3C Identity & Credentials

• W3C DID Core v1.0 compliant DID Document generation (did:key method)
• DID Document verification and cross-node resolution over Tor
• JSON-LD Verifiable Credentials (VC Data Model 2.0, Ed25519Signature2020 proofs)
• Verifiable Presentation creation with selective disclosure
• Credentials management UI at /dashboard/web5/credentials

Decentralized Web Node (DWN)

• DWN message store with CRUD, protocol registration, and query interface
• DWN HTTP API (POST /dwn, GET /dwn/health)
• Bidirectional peer sync over Tor via SOCKS proxy
• DWN management UI in Web5 page with protocol browser

Multi-Node Federation

• Node federation protocol with invite codes (fed1: prefix), trust levels, state sync
• Federation dashboard at /dashboard/server/federation
• Federated app deployment to trusted peers over Tor
• Architecture documented in docs/multi-node-architecture.md

Decentralized Marketplace

• NIP-78 Nostr-based app manifest discovery across relays
• Trust scoring (0-100) based on DID verification, relay consensus, federation trust
• App manifest publishing with Nostr secp256k1 signing
• Community marketplace tab in App Store with trust score badges

Networking

• VPN integration (Tailscale + WireGuard) with keypair generation and status display
• Mesh networking via Meshtastic LoRa devices with node discovery
• DNS-over-HTTPS configuration (Cloudflare, Google, Quad9, Mullvad, Custom)
• WiFi/Ethernet configuration via nmcli with scan-and-connect modal
• Network interfaces display in Server page

Hardware Wallet Support

• PSBT signing flow (create, QR display, finalize, broadcast)
• USB hardware wallet detection (ColdCard, Trezor, Ledger)
• Hardware wallet signing UI in LND views

System Management

• System monitoring (CPU, RAM, disk gauges on Dashboard)
• Automatic update system with download, apply, rollback, and scheduling
• Disk space management with auto-cleanup at 90% usage
• Container health monitoring with auto-recovery (max 3 restart attempts)
• Crash recovery via PID-file detection and container snapshot restoration
• Graceful shutdown with in-flight request draining (5s timeout)

Backup & Restore

• Full backup with tar.gz + ChaCha20-Poly1305 encryption
• Backup create, list, verify, restore, delete via RPC
• USB drive detection and backup-to-USB
• Backup UI in Settings page

Kiosk Mode

• Chromium kiosk with auto-restart and watchdog service
• Recovery page at /recovery (no auth required)
• Kiosk keyboard shortcuts (Ctrl+Shift+R/H/Q)
• Systemd services for kiosk and watchdog

ARM64 Support

• Cross-compilation for aarch64 with rustls-tls
• All 6 core apps verified with multi-arch images
• Parameterized ISO build script (ARCH=arm64)
• RPi 5 testing guide

Testing

• 236 frontend tests across 17 test files (Vitest)
• 124+ backend tests (cargo test)
• Playwright visual regression suite (12 pages)
• Chaos testing (SIGKILL recovery, concurrent RPC, rapid restarts)
• App lifecycle testing and dependency chain verification
• 1-week continuous uptime monitoring

Documentation

• Developer guide, API reference (100+ endpoints), app developer SDK guide
• 5 Architecture Decision Records (Podman, DID:key, Nostr, Tor, ChaCha20)
• Release process, canary deploy, quality baseline documentation

Changed

• Settings sections use glass-card instead of path-option-card
• Web3 card shows "Coming Soon" badges instead of fake data
• Network diagnostics moved from Settings to Server page
• Removed core/startos/ (2MB of dead code, zero dependencies)

Fixed

• CSRF protection on all state-changing RPC calls
• CORS restricted to same-origin (removed Access-Control-Allow-Origin: *)
• Nginx security headers (X-Frame-Options, CSP, X-Content-Type-Options)
• All 24 silent catch blocks now log in dev mode
• Zero console.log outside dev gate, zero any types

Security

• CSRF token validation on all state-changing endpoints
• Same-origin CORS policy
• Nginx security headers (SAMEORIGIN, nosniff, CSP, Referrer-Policy)
• Container security hardened (readonly root, dropped caps, non-root, no-new-privileges)
• Secrets rotation with AES-256-GCM and automatic scheduling

[0.5.0-beta] - 2026-03-11

Added

Security Hardening

• Session inactivity expiry (24h), max 5 concurrent sessions with oldest eviction
• Session rotation on password change (invalidates all other sessions)
• Container security: --cap-drop=ALL, --security-opt=no-new-privileges:true, read-only root
• Secrets rotation with AES-256-GCM encryption and metadata tracking
• Path traversal prevention (nginx regex blocks + client-side sanitizePath)
• Cookie-based auth for File Browser (removed token from URLs)
• Login rate limiting (5 failures per 60s per IP)
• TOTP two-factor authentication with backup codes

Performance

• Backend startup: ~100ms
• Frontend bundle: ~105 KB gzipped initial load
• WebSocket heartbeat (30s ping/pong) with exponential backoff reconnection
• Server-side 5-minute inactivity timeout for stale WebSocket connections
• Real-time install progress reporting via WebSocket during container pulls
• Connection state machine (connecting/connected/disconnecting/disconnected)

Apps & Integrations

• Pinned all container images to specific versions (no :latest tags)
• Fedimint and Fedimint Gateway with auto-LND detection
• IndeedHub virtual app integration
• Expanded read-only root filesystem support (electrs, nostr-relay, ollama)
• Dependency chain validation (Bitcoin → Electrs → Mempool, Bitcoin → LND)

Documentation

• Comprehensive user guide (docs/user-guide.md)
• Beta release checklist (docs/BETA-RELEASE-CHECKLIST.md)
• 72-hour stability test script

Fixed

• Penpot hardcoded secret key replaced with SHA256-derived key
• WebSocket reconnection reliability after network interruption

[0.1.0] - 2026-01-28

🎉 Initial Release

The first production release of Archipelago - a next-generation Bitcoin Node OS for macOS.

Added

Core Features

• Native Rust Backend - High-performance async server using Tokio and Hyper
• Modern Vue.js Frontend - Beautiful glassmorphism UI with Tailwind CSS
• Docker Integration - Seamless container orchestration via Docker Desktop
• Real-time WebSocket - Live updates for container status and system events
• Authentication System - Secure user login and session management

Bitcoin & Lightning

• Bitcoin Core - Full node in regtest mode with custom UI
• LND - Lightning Network Daemon with dedicated interface
• BTCPay Server - Bitcoin payment processing
• Mempool Explorer - Blockchain visualization and analytics

Applications

• Penpot - Open-source design and prototyping platform
• Endurain - Self-hosted fitness tracking
• Morphos - File conversion utility
• Nextcloud - Cloud storage and file management
• Home Assistant - Home automation hub
• Grafana - Metrics and monitoring dashboards
• OnlyOffice - Document editing suite
• SearXNG - Privacy-respecting search engine
• Fedimint - Federated e-cash system

User Interface

• Onboarding Flow - Guided setup for new users
• Dashboard - Real-time system overview
• My Apps - Alphabetically sorted app management
• Cloud Interface - File management by type (Documents, Photos, Videos, Music)
• Web5 Explorer - Decentralized identity and data management
• Settings - System configuration and preferences
• Custom Launch Pages - Dedicated UIs for Bitcoin Core and LND

Technical Features

• Container Runtime Abstraction - Support for Docker and Podman
• Dynamic Package Discovery - Automatic detection of running containers
• Health Monitoring - Container status and health checks
• Data Persistence - Docker volumes for app data
• Network Isolation - Secure container networking
• Resource Management - CPU and memory allocation

Architecture

• Backend: Rust + Tokio + Hyper + WebSocket
• Frontend: Vue 3 + TypeScript + Vite + Pinia
• Styling: Tailwind CSS + Custom Glassmorphism
• Containers: Docker Compose + Dockerode API
• Build System: Cargo + npm + macOS App Bundle

Known Limitations

• Requires Docker Desktop (23.0+)
• macOS only (Intel and Apple Silicon)
• Single-user mode
• No auto-updates (manual download required)
• Ollama excluded due to image size
• Manual Docker container management

System Requirements

• macOS 10.15 (Catalina) or later
• 8GB RAM minimum (16GB recommended)
• 20GB free disk space (50GB+ for blockchain data)
• Docker Desktop 23.0 or later
• Internet connection for initial container downloads

Installation

1. Download Archipelago-0.1.0-macOS.dmg
2. Open the DMG and drag Archipelago to Applications
3. Install Docker Desktop if not already installed
4. Launch Archipelago from Applications
5. Access the UI at http://localhost:8100

Security

• Code Signed: Yes (Developer ID)
• Notarized: Yes (Apple notarization)
• Sandboxed: No (requires full disk access for Docker)
• Hardened Runtime: Yes
• Gatekeeper: Compatible

Documentation

• README.md - Project overview
• BUILD_MACOS.md - Build instructions
• DEPLOYMENT_CHECKLIST.md - Release process
• docs/ - Detailed documentation

Credits

Built with:

• Rust (backend)
• Vue.js (frontend)
• Docker (containers)
• Alpine Linux (inspiration)
• Parmanode (Bitcoin scripts)
• And many open-source dependencies

License

[Specify your license here]

---

Version History

0.1.0 - 2026-01-28

Initial public release

---

Future Roadmap

See GitHub Issues for planned features:

• Auto-update system
• Multi-user support
• Native container runtime (no Docker Desktop)
• iOS companion app
• Hardware wallet integration
• Tor integration
• VPN/Tailscale support
• Backup/restore functionality
• Mac App Store distribution
• Windows and Linux builds

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Support

• GitHub Issues: Report bugs and request features
• Documentation: See /docs directory
• Community: [Discord/Telegram/Forum link]