archipelagoandClaude Opus 5
ba052736be
Narrative pass. The Security Requirements section described a blocklist where
the code enforces an allow-list, and attributed enforcement to the wrong layer:
- **"Forbidden: mounting system paths /, /etc, /var, /usr, /proc, /sys"** — the
real rule (`manifest.rs:1290-1313`) is the inverse: `volumes[].source` must be
absolute and under `/var/lib/archipelago/`, or a plain named volume, or one of
two reviewed exceptions (`/run/user/1000/podman/podman.sock`, `/var/run/dbus`).
Anything else is a parse error. The old wording also listed `/var` as
forbidden while every app in the repo binds `/var/lib/archipelago/<id>` — a
developer reading it would not know where their own data goes.
- **"enforced by the marketplace/catalog pipeline and the node"** — split by
layer instead. The capability allow-list is parser-enforced (verified against
the 9 entries at `manifest.rs:1089-1099`); `:latest` is NOT — only
`validate-app-manifest.sh` checks it, and a `:latest` manifest still installs.
readonly_root / no_new_privileges / network_policy=isolated are parser
defaults, so omitting them is safe rather than dangerous.
Also:
- `derived_env` documented `HOST_IP`/`HOST_MDNS`/`DISK_GB` "such as"; the set is
closed and includes a fourth, `{{BITCOIN_HOST}}`. Noted that unknown
placeholders pass through verbatim rather than erroring, so a typo silently
ships `{{FOO}}` into the container.
- The networking example hardcoded `bitcoin-knots`; `{{BITCOIN_HOST}}` resolves
to knots or core depending on what's installed.
- Documented the `files[].content` placeholder set, which is a different set
from derived_env and wasn't mentioned at all — notably `{{NETWORK_GATEWAY}}`
(the nginx `resolver` fix for post-restart 502s) and `{{secret:NAME}}`.
- The "check the UI" URL `/app/my-app/` is not a route; it's
`/dashboard/apps/:id` (detail) or `/dashboard/app-session/:appId` (embed).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Archipelago documentation
Start here. This index groups the docs by what you're trying to do. The
authoritative behaviour is always the code in core/; where a doc and the code
disagree, the code wins and the doc is a bug.
Getting started
- User Walkthrough — setting up and using a node, from hardware to daily use
- Talking to your node — the conversational command surface
- Seed Verification — independently verify your 24-word backup
- Troubleshooting — common problems and how to resolve them
- Gamepad / Controller Navigation — driving the UI from a controller
Architecture
- Architecture — the system at a glance
- Multi-Node Architecture — how nodes relate across a fleet
- API Reference — the JSON-RPC surface
App development
- App Developer Guide — build and package a containerized app
- App Manifest Specification — the manifest schema, field by field
- Manifest → Quadlet unit — how a manifest compiles to a systemd-owned container unit
- Container lifecycle — the reconciler state machine: install/adopt/start/stop/self-heal
- App secrets — declaring, generating and injecting per-install credentials
- Registry-Distributed Manifests — how manifests reach nodes via the signed catalog
- Decentralized Marketplace Protocol — publishing apps via an external registry
- Bitcoin RPC Relay — letting an external wallet reach the node's Bitcoin RPC
- Companion Pairing QR — the pairing handoff contract
- TV input inside iframe apps — keyboard/gamepad routing into embedded apps
Design docs
These record why a thing is built the way it is. They are design records, not step-by-step guides, and some predate the current implementation.
- Registry-Distributed Manifests
- DHT Distribution
- Bitcoin Multi-Version
- Dual Ecash
- Hardware Signer
- Manifest Hooks
- Meshroller Integration
- Nostr Git Source Hosting
- Nostr Identity Import · Nostr Signer Login (research)
- Streaming Ecash (phase 4)
- App Packaging Migration
Decisions (ADRs)
- ADR-001: Podman over Docker
- ADR-002: DID Key Method for Node Identity
- ADR-003: Nostr Relays for Discovery
- ADR-004: Tor Hidden Services for Peer Communication
- ADR-005: ChaCha20-Poly1305 for Backup Encryption
- ADR-006: Nostr Relays for Marketplace Discovery
- ADR-007: DID-Based Federation Trust
- ADR-008: Dual Key Strategy (Ed25519 + Secp256k1)
- ADR-009: Manifest-Level Container Security
- ADR-011: DWN Deprioritization
Security
- Security Policy — how to report a vulnerability
- PSBT Signing Architecture
- Bitcoin RPC Proxy Exposure
- Entropy Enforcement (KEY-05)