diff --git a/.cursor/rules/Architecture.mdc b/.cursor/rules/Architecture.mdc new file mode 100644 index 00000000..6c9026bb --- /dev/null +++ b/.cursor/rules/Architecture.mdc @@ -0,0 +1,169 @@ +--- +alwaysApply: true +--- + +# Archipelago Bitcoin Node OS - Architecture Documentation + +## Overview + +Archipelago is a next-generation Bitcoin Node OS built on Alpine Linux with Podman containerization, combining the modularity of Parmanode with the security and efficiency of a minimal server OS. + +## System Architecture + +``` +┌─────────────────────────────────────────────────────────┐ +│ Alpine Linux Base (130MB) │ +│ - Minimal kernel │ +│ - Hardened security │ +│ - Read-only root filesystem │ +└─────────────────────────────────────────────────────────┘ + │ + ┌───────────────┼───────────────┐ + │ │ │ +┌───────▼──────┐ ┌──────▼──────┐ ┌─────▼──────┐ +│ Podman │ │ Rust Backend│ │ Vue.js UI │ +│ (rootless) │ │ (core/) │ │ (neode-ui/) │ +└───────┬──────┘ └──────┬──────┘ └─────────────┘ + │ │ + └───────┬───────┘ + │ + ┌───────────▼───────────┐ + │ Container Orchestration│ + │ Layer (new) │ + │ - Manifest parser │ + │ - Podman client │ + │ - Dependency resolver │ + │ - Health monitor │ + └───────────┬───────────┘ + │ + ┌───────────▼───────────┐ + │ Containerized Apps │ + │ - Bitcoin Core │ + │ - LND / CLN │ + │ - BTCPay Server │ + │ - Nostr Relays │ + │ - Meshtastic │ + │ - Web5 DWN │ + └───────────────────────┘ +``` + +## Key Components + +### 1. Alpine Linux Base + +- **Size**: ~130MB (vs 1.5GB+ for Umbrel/StartOS) +- **Security**: Hardened kernel, minimal attack surface +- **Multi-arch**: ARM64 (Raspberry Pi) and x86_64 support + +### 2. Container Orchestration Layer + +Located in `core/container/`: +- **manifest.rs**: Parses YAML app manifests +- **podman_client.rs**: Wraps Podman API for container management +- **dependency_resolver.rs**: Resolves app dependencies and conflicts +- **health_monitor.rs**: Monitors container health and auto-restarts + +### 3. Backend API Extensions + +New RPC endpoints in `core/startos/src/container/`: +- `container-install`: Install app from manifest +- `container-start/stop/remove`: Container lifecycle +- `container-status/logs`: Status and debugging +- `container-list`: List all containers +- `container-health`: Health status aggregation + +### 4. Vue.js UI Integration + +New components in `neode-ui/`: +- **ContainerApps.vue**: List of containerized apps +- **ContainerAppDetails.vue**: Detailed app view with logs +- **ContainerStatus.vue**: Status indicator component +- **container-client.ts**: API client for container operations +- **container.ts**: Pinia store for container state + +### 5. App Manifest System + +Standardized YAML format in `apps/`: +- Defines container image, resources, dependencies +- Security policies and health checks +- Bitcoin/Lightning/Web5 integration metadata + +### 6. Parmanode Compatibility + +Located in `core/parmanode/`: +- **script_runner.rs**: Executes Parmanode scripts in containers +- **converter.rs**: Converts Parmanode modules to app manifests +- **parmanode-wrapper.sh**: Shell wrapper for direct script execution + +### 7. Security Modules + +Located in `core/security/`: +- **container_policies.rs**: Generates AppArmor/SELinux profiles +- **secrets_manager.rs**: Encrypted secrets storage +- **image_verifier.rs**: Cosign signature verification + +### 8. Performance Optimization + +Located in `core/performance/`: +- **resource_manager.rs**: CPU/memory/disk allocation +- **optimize-alpine.sh**: OS-level optimizations + +## App Categories + +### Bitcoin & Lightning +- Bitcoin Core (full node) +- LND (Lightning Network Daemon) +- Core Lightning (CLN) +- BTCPay Server +- Mempool (blockchain explorer) + +### Web5 & Decentralized Protocols +- Nostr relays (nostr-rs-relay, strfry) +- Web5 DWN (Decentralized Web Node) +- DID Wallet +- Bitcoin Domain Names + +### Mesh Networking & Routing +- Meshtastic (LoRa mesh networking) +- Router (mesh routing, device discovery) +- Local network management + +### Self-Hosted Services +- Home Assistant +- Grafana +- SearXNG +- OnlyOffice +- Ollama (local AI) +- Penpot + +## Security Model + +1. **OS Level**: Hardened Alpine, read-only root, minimal kernel +2. **Container Level**: Rootless Podman, capability dropping, network isolation +3. **Secrets**: Encrypted storage, runtime injection only +4. **Supply Chain**: Signed images (Cosign), SBOM generation +5. **Network**: Firewall, rate limiting, Tor integration +6. **Audit**: Immutable logs, configuration tracking + +## Networking + +- **Isolated Networks**: Each app on separate bridge network by default +- **Bitcoin Core**: Isolated network, explicit RPC access +- **Lightning Nodes**: Separate network, gRPC/REST exposed +- **Tor Integration**: Optional, default for privacy-sensitive apps +- **Mesh Networking**: Meshtastic and router support for decentralized communication + +## Data Persistence + +- **App Data**: `/var/lib/archipelago/{app-id}/` +- **Secrets**: `/var/lib/archipelago/secrets/{app-id}/` (encrypted) +- **Logs**: `/var/lib/archipelago/logs/{app-id}/` +- **Backups**: `/var/lib/archipelago/backups/` + +## Future Enhancements + +- Time-travel snapshots (ZFS/BTRFS) +- Decentralized app marketplace (IPFS + Nostr) +- Multi-node clustering +- Hardware attestation (TPM 2.0) +- Protocol-agnostic design (multi-chain support) diff --git a/.cursor/rules/coding-rules.mdc b/.cursor/rules/coding-rules.mdc index e1dae72f..1d9649d2 100644 --- a/.cursor/rules/coding-rules.mdc +++ b/.cursor/rules/coding-rules.mdc @@ -1,17 +1,110 @@ # Archipelago Development Rules -## CRITICAL: Project Structure & Location +**Mission**: Build a production-ready, open-source Bitcoin Node OS that's secure, minimal, and user-friendly from day one. -### NEVER Reference External Directories -- ❌ **NEVER** reference `/Users/tx1138/Code/Archipelago/` in code, scripts, or documentation -- ✅ **ALWAYS** use workspace-relative paths: `./`, `../`, or `$PROJECT_ROOT` -- ✅ The workspace at `/Users/tx1138/Archipelago` is the ONLY project location +**Philosophy**: Code in development should mirror production quality. Write it right the first time. + +--- + +## Table of Contents +1. [Project Structure & Location](#project-structure--location) +2. [Open Source & Licensing](#open-source--licensing) +3. [Production-Ready Development](#production-ready-development) +4. [Architecture & System Design](#architecture--system-design) +5. [Backend Development (Rust)](#backend-development-rust) +6. [Frontend Development (Vue.js)](#frontend-development-vuejs) +7. [Container & Security](#container--security) +8. [Code Quality & Testing](#code-quality--testing) +9. [Documentation](#documentation) +10. [Common Mistakes](#common-mistakes) + +--- + +## Project Structure & Location + +### CRITICAL: Workspace-Relative Paths Only +- ❌ **NEVER** reference absolute user paths (`/Users/username/...`) in code, scripts, or documentation +- ✅ **ALWAYS** use workspace-relative paths: `./`, `../`, or environment variables - ✅ All files must be created in the workspace, never in external directories +- ✅ When copying from external sources, copy TO workspace, then update all references ### File Creation Rules - ✅ Create files directly in the workspace using relative paths - ❌ Never assume files exist elsewhere - check first, create if missing -- ✅ When copying from external sources, copy TO workspace, then update references +- ✅ Use environment variables for paths that change between environments +- ✅ Document all path dependencies in README or setup guides + +--- + +## Open Source & Licensing + +### License Compliance +- ✅ Project is **open source** under [specify license: MIT/Apache 2.0/GPL] +- ✅ All dependencies must be compatible with our license +- ✅ Check license compatibility before adding dependencies +- ✅ Document all third-party licenses in `LICENSES.md` or `THIRD_PARTY_NOTICES.md` + +### Third-Party Code +- ✅ Use permissive licenses (MIT, Apache 2.0, BSD) when possible +- ⚠️ Be cautious with GPL/AGPL dependencies (viral licensing) +- ✅ Always include license headers in source files +- ✅ Document attribution for copied/adapted code + +### Community Standards +- ✅ Follow [Contributor Covenant](https://www.contributor-covenant.org/) code of conduct +- ✅ Provide clear CONTRIBUTING.md with guidelines +- ✅ Use semantic versioning (SemVer) for releases +- ✅ Maintain comprehensive changelog (CHANGELOG.md) +- ✅ Accept community contributions via pull requests +- ✅ Respond to issues and PRs within reasonable timeframes + +### Open Source Best Practices +- ✅ Never commit secrets, API keys, or credentials +- ✅ Use `.gitignore` to exclude sensitive/generated files +- ✅ Keep commit messages clear and descriptive +- ✅ Write documentation as if explaining to new contributors +- ✅ Include setup/installation scripts for easy onboarding + +--- + +## Production-Ready Development + +### Development = Production Mindset +- 🎯 **CRITICAL**: Write production-quality code from the start +- ✅ No "TODO: Fix before production" comments - fix it now +- ✅ No hardcoded values - use configuration from day one +- ✅ No "works on my machine" - test in clean environments +- ✅ Security is NOT optional - implement it in development + +### Configuration Management +- ✅ Use `.env` files for environment-specific configuration +- ✅ Provide `.env.example` with all required variables +- ✅ Never commit `.env` files to git +- ✅ Validate configuration at startup with clear error messages +- ✅ Support multiple environments: dev, staging, production + +### Infrastructure as Code +- ✅ All infrastructure should be reproducible from code +- ✅ Container definitions = production-ready from first commit +- ✅ Scripts should work on fresh systems (document prerequisites) +- ✅ Use Alpine Linux base for containers (production-ready minimal OS) +- ✅ Test multi-arch builds early (ARM64, x86_64) + +### Development Environments +- ✅ Provide dev containers or Docker Compose setups +- ✅ Mock external services for local development +- ✅ Minimize differences between dev and production +- ✅ Document all system prerequisites clearly +- ✅ Use version managers for language runtimes (rustup, nvm) + +### Continuous Integration Preparation +- ✅ Write code that can be automatically tested +- ✅ Keep builds fast (parallelize, cache dependencies) +- ✅ Lint and format code automatically +- ✅ Run security checks on dependencies +- ✅ Test on multiple platforms (Linux, macOS, ARM64) + +--- ## Design System & Styling @@ -54,9 +147,11 @@ } ``` -## StartOS Independence +--- -### Zero StartOS Dependencies +## Architecture & System Design + +### StartOS Independence - ❌ **NEVER** import or reference StartOS-specific code - ❌ **NEVER** copy StartOS patterns without refactoring - ✅ **ALWAYS** create Archipelago-native implementations @@ -66,128 +161,369 @@ ### Backend Architecture - ✅ Use `archipelago-container` crate, not StartOS container code -- ✅ Use our RPC endpoints in `core/startos/src/container/` -- ⚠️ **TEMPORARY**: Using StartOS backend (`startbox`) as base - this is temporary -- ✅ **GOAL**: Build our own Archipelago backend binary that uses ONLY our modules +- ✅ Use our RPC endpoints in `core/archipelago/src/` +- ⚠️ **TEMPORARY**: Using StartOS backend as base during Phase 1 +- 🎯 **GOAL**: Build our own Archipelago backend binary that uses ONLY our modules - ✅ Mark all StartOS-derived code with `// TODO: Refactor to Archipelago-native` -- ✅ For development: Use mock backend for UI work, avoid StartOS backend when possible -- ✅ All new features must use our modules (`archipelago-container`, `archipelago-security`, etc.) +- ✅ For development: Use mock backend for UI work when possible +- ✅ All new features must use our modules (`archipelago-*` crates) -## Container & App Development +### System Architecture Principles +- ✅ **Alpine Linux Base**: 130MB minimal, secure, multi-arch +- ✅ **Podman Only**: Rootless containers, no Docker dependencies +- ✅ **Manifest-Driven**: All apps defined by YAML manifests +- ✅ **Security First**: Read-only filesystems, capability dropping, network isolation +- ✅ **Dependency Resolution**: Automatic dependency management between apps +- ✅ **Health Monitoring**: Built-in health checks and auto-restart -### App Manifest Rules +### Multi-Architecture Support +- ✅ Support both ARM64 (Raspberry Pi) and x86_64 from day one +- ✅ Test builds on both architectures regularly +- ✅ Use multi-arch container images +- ✅ Document architecture-specific differences + +### Modular Design +- ✅ Each crate in `core/` should be independent and reusable +- ✅ Minimize coupling between modules +- ✅ Define clear interfaces between components +- ✅ Use traits for abstraction and testability + +--- + +## Container & Security + +### App Manifest Rules (Production Standards) - ✅ **ALWAYS** create manifests in `apps/{app-id}/manifest.yml` - ✅ Follow the manifest specification in `docs/app-manifest-spec.md` - ✅ Use semantic versioning: `MAJOR.MINOR.PATCH` - ✅ Include security policies, resource limits, health checks +- ✅ Define explicit dependencies with version constraints +- ✅ Include license information and attribution +- ✅ Document configuration options clearly +- ✅ Provide default values that are secure ### Container Orchestration - ✅ Use `archipelago_container::PodmanClient` for all container operations - ✅ Use `archipelago_container::AppManifest` for manifest parsing - ✅ Use `archipelago_container::DependencyResolver` for dependency management - ❌ Never use Docker directly - always use Podman via our client +- ✅ Implement graceful shutdown (handle SIGTERM) +- ✅ Set resource limits (CPU, memory, disk) +- ✅ Monitor container health continuously -### Security First +### Security First (CRITICAL - Production Requirement) +- 🔒 **Security is NOT optional** - every container must be hardened + +#### Container Security - ✅ **ALWAYS** set `readonly_root: true` unless explicitly needed - ✅ **ALWAYS** drop all capabilities, add only required ones -- ✅ **ALWAYS** use isolated networks unless host network is required -- ✅ **ALWAYS** verify container images with Cosign signatures -- ✅ Use AppArmor profiles from `core/security/` +- ✅ **ALWAYS** use isolated networks (never `host` network unless required) +- ✅ **ALWAYS** run as non-root user (UID > 1000) +- ✅ **ALWAYS** set `no-new-privileges: true` +- ✅ Use AppArmor/SELinux profiles from `core/security/` +- ✅ Implement seccomp profiles to restrict syscalls -## Frontend Development +#### Image Security +- ✅ **ALWAYS** verify container images with Cosign signatures +- ✅ Use official base images from trusted registries +- ✅ Pin image versions (never use `latest` tag) +- ✅ Scan images for vulnerabilities (Trivy, Grype) +- ✅ Rebuild images regularly for security updates +- ✅ Generate and publish SBOM (Software Bill of Materials) + +#### Secrets Management +- ✅ **NEVER** hardcode secrets in code or config files +- ✅ Use encrypted secrets storage (`core/security/secrets_manager.rs`) +- ✅ Inject secrets at runtime only (environment variables or mounted files) +- ✅ Rotate secrets regularly +- ✅ Use minimal secret scopes (principle of least privilege) +- ✅ Clear secrets from memory after use +- ✅ Log secret access for audit trails (without logging values) + +#### Network Security +- ✅ Use isolated bridge networks per app +- ✅ Implement firewall rules (iptables/nftables) +- ✅ Rate limit API endpoints +- ✅ Use TLS for all external communication +- ✅ Support Tor for privacy-sensitive apps +- ✅ Implement intrusion detection (fail2ban) + +#### Data Security +- ✅ Encrypt sensitive data at rest +- ✅ Use encrypted volumes for secrets +- ✅ Implement secure backup/restore +- ✅ Sanitize logs (no secrets in logs) +- ✅ Implement data retention policies +- ✅ Support secure data deletion + +--- + +## Frontend Development (Vue.js) ### Vue.js Component Rules -- ✅ Use Composition API (`