lfg2025/archy
1
0
Fork 0
Code Issues 27 Pull Requests 5 Actions Packages Projects Releases 3 Wiki Activity

Archipelago — open-source initial import

Browse Source
This commit is contained in:
Archipelago
2026-08-12 10:55:50 +00:00
commit b67e1527a2
2068 changed files with 472303 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/1.8.0-RELEASE-HARDENING-PLAN.md
+421
View File
@@ -0,0 +1,421 @@
# Archipelago 1.8.0 — Release Hardening Plan & Tracker
> **The one living checklist for shipping 1.8.0.** Derived from a full-system deep
> audit (2026-07-02): backend security, backend code-quality, frontend, mesh,
> tests/release pipeline, and the ISO build. Supersedes nothing — it *sits above*
> **Keep it updated: tick a box the moment an item lands, with the commit sha.**
**Definition of done for 1.8.0:** the supply chain is authenticated end-to-end
(§A), OTA self-update is safe and rollback-proven on real hardware (§B), no
secrets ship in the image (§F), and the single-node gate stays 5/5 green through
all of it. Everything else is polish that should not block the tag.
**Legend:** `[ ]` open · `[~]` in progress · `[x]` done · 🔴 critical · 🟠 high ·
🟡 medium · 🟢 low/polish · ⛔ blocked on you.
---
## 🎯 The single most important insight
The **release signing ceremony (Workstream B) is the linchpin.** ✅ The ceremony
KEY was generated (user confirmed 2026-07-02) — the hard offline part is done. But
the outputs are **not yet wired into the repo**: `anchor.rs:21` is still `None` and
`releases/app-catalog.json` carries no `signature`/`signed_by` (its `image_signature`
fields are literal `"cosign://..."` placeholders). Three mechanical steps remain,
split by who can run them: **(1)** pin the pubkey — needs only the *public* hex, can
be done in-repo now; **(2)** sign the catalog with the `RELEASE_MASTER_MNEMONIC` —
only the publisher, secret never touches a host; **(3)** implement + flip cosign
enforcement on the pull path. Until (1)+(2) land, every "verify the signature" task
below is written but not enforced. **This is still the critical path; §A converges on it.**
---
## §A — Supply-chain authentication (🔴 THE release blocker)
Today an attacker who controls the mirror IP (or any MITM on the plaintext HTTP
path) can ship an arbitrary root binary, arbitrary container images, and an
arbitrary app catalog to the entire fleet — fully unattended under
`auto_apply`. These four items are one story and must land together.
- [x] 🔴 **Pin `RELEASE_ROOT_PUBKEY_HEX` + sign the catalog** — DONE 2026-07-02.
`anchor.rs` pinned to `5d15cbee…d469951` (signer
`did:key:z6MkkidEnEpo6qHMCNSZoNKWtvQvxq3whnaME9wGgEFhq7ur`); trust tests updated (16/16
green). `releases/app-catalog.json` signed in place (`signed_by` matches, 64-byte sig);
two blocking floats fixed en route (`archy-btcpay-db` version→string, `cpu_limit` 0.25→1).
Ship order (backward-compatible): signed catalog goes out first (old binaries still accept
it), pinned-anchor binary follows in the next build/OTA. **Still ahead:** (a) the
pinned-anchor binary must actually be built + shipped for enforcement to be live on nodes;
(b) flip "accept unsigned" → "reject unsigned" only after the whole fleet is on the pinned
binary (`container/app_catalog.rs:397`, the `Unsigned` arm) — see the next item.
- [~] 🔴 **Enforce a signature on the OTA manifest before trusting it.** Signature
verification LANDED 2026-07-02: `check_for_updates` now fetches raw JSON and runs
`trust::verify_detached` — a present-but-invalid/wrong-signer signature hard-rejects
the mirror; unsigned manifests are offered for MANUAL apply only (`manifest_signed`
surfaced in `UpdateState`) and **auto-apply refuses them**. Publisher side:
`create-release.sh` signs the manifest inline (ceremony), `publish-release-assets.sh`
hard-refuses to ship unsigned (grep + `ceremony verify` crypto gate), and
`scripts/sign-manifest.sh` exists for re-signs. **Still open:** move the mirror
to HTTPS + pinned cert (tracked with the next item); flip unsigned-manual-apply →
hard-reject once the fleet is on a pinned-anchor binary.
- [x] 🔴 **Implement container image signature verification (cosign).** DONE 2026-07-04
(code path; enforcement dormant until the ceremony): new `container::image_verify`
gates BOTH pull sites (`PodmanClient::pull_image` + the dev-only `DockerRuntime`).
Claims classify as None / the literal `cosign://...` placeholder (every fleet
manifest today → pull proceeds, logged) / Declared → `cosign verify --key
/etc/archipelago/cosign.pub --insecure-ignore-tlog=true` (+ both insecure-registry
flags for the HTTP mirror; flags verified against cosign docs), hard-fail on missing
key, missing cosign binary, timeout, or bad signature — a declared signature can
never be skipped, on either runtime. Key path overridable via
`ARCHIPELAGO_COSIGN_PUBKEY`. Deleted the caller-less, blocking, wrong-CLI
`security::ImageVerifier`. **Activation = ceremony work**: pin cosign.pub on nodes +
install cosign + publish real `image_signature` values (in that order); tracked with
the Workstream B signing ceremony item.
- [ ] 🟠 **Move the image mirror to HTTPS; drop `--tls-verify=false`.**
`podman_client.rs:641` `INSECURE_REGISTRY_HOSTS = ["source.archipelago-foundation.org"]` +
`config.rs:104,124` allowlist pull images over unauthenticated HTTP. Remove the raw-IP
entries; give the mirror a valid/pinned cert. (Same host also baked insecurely into
the ISO — see §F.)
- [x] 🟠 **Validate every image string at the pull site, not just the RPC boundary.**
DONE 2026-07-03: policy extracted to `container::image_policy` (single source of truth;
RPC-boundary check delegates to it) and BOTH orchestrator pull sites (`install_fresh` +
`ensure_resolved_source_available`) hard-bail on refs that fail it. Policy accepts
trusted-registry refs + registry-less Docker Hub shorthand (`grafana/grafana` — used by
8 manifests, can't name an attacker host); rejects any explicit non-allowlisted
registry host, shell metachars, malformed refs. 4 new unit tests; container 159 /
package 46 green.
---
## §B — OTA self-update safety (🔴 1.8.0's headline feature is untested live)
The apply path itself is well-built (resumable download, staged-complete marker,
atomic swap, single-depth backup). The gaps are **authenticity** (§A) and
**verification depth** — plus the fact that the upgrade path has never run
end-to-end on real hardware.
- [x] 🔴 **Deepen the post-OTA health check.** DONE 2026-07-03: `verify_pending_update`
now requires, in the same attempt, (1) frontend 2xx/3xx via nginx, (2) backend RPC
liveness — unauthenticated POST `/rpc/v1`; 401/403 = alive, 5xx/404/refused = dead,
so a 502-behind-static-files release now rolls back, (3) rootless `podman ps`
reachability; plus a pre-loop binary-version==marker assertion that catches a silent
or half swap (new frontend + old binary) deterministically. Per-app container
assertions deliberately EXCLUDED — the pre-Quadlet service restart legitimately kills
containers and the reconciler can need minutes (false-rollback risk); revisit after
the Phase-3 flip. LND-unlock-level checks remain out of scope for the 90s window.
- [ ] 🟠 **Run one real upgrade-from-vN-1 soak on hardware before tagging.**
No test installs the previous version, points it at a staged 1.8.0 manifest, applies,
and asserts health + rollback. This is the top release risk for an OTA release. A
two-VM (or two-node) harness is enough.
- [x] 🟡 **Guard the frontend-build-no-op in the *actual* release path.** DONE 2026-07-08
(`e77ccff0`): the grep guard is folded directly into `create-release.sh` right after its
own `npm run build` (post-version-bump, pre-packaging — calling `run.sh --with-build` at
stage 0 would have checked the pre-bump version). Verified both ways against the real
dist: passes on the current version, trips on a missing one.
- [x] 🟢 **publish-release-assets verifies size, not sha256.** DONE 2026-07-08 (`e77ccff0`):
the verify loop now downloads each published asset and compares sha256 (and size)
against the manifest. Verified live against the v1.7.99-alpha assets on the vps2 mirror.
---
## §C — Backend robustness (🟠 stability, mostly low-effort/high-ROI)
Note: the `.unwrap()`/`panic!` worry is a **non-issue** — nearly all are in test
modules; production request/boot paths are essentially panic-free. The real risks:
- [x] 🟠 **Log swallowed persistence writes.** DONE 2026-07-02 (full-workspace re-inventory
found 19 production sites): 16 converted to `if let Err(e) = … { warn!(…) }` — mesh
config (`server.rs`), relay tor endpoint (`bitcoin_relay.rs`), update mirrors/state +
staging flush/sync (`update.rs`), registry config, radio-contact blocklist, mesh outbox
sweep (`scheduler.rs`), block-header cache (`mesh/mod.rs`), 7× peer-transport badge
(`sync.rs` + `content.rs`). Federation tombstone/untombstone upgraded to hard errors
(see §I). Install-log line write left fire-and-forget with an explanatory comment.
- [x] 🟠 **Remove blocking `std::process::Command` from async handlers.** DONE 2026-07-03:
converted to `tokio::process` — `published_host_port` (install), `detect_disk_gb`
(dependencies), factory-reset restart (system/handlers), `config.rs detect_host_ip`,
the orchestrator host-facts helpers (`detect_host_ip/mdns/disk_gb`, `bitcoin_host`,
`resolve_dynamic_env` now async through all 6 call sites), and `AutoRuntime::new`
probes. `transport/fips.rs is_available()` (sync trait method on the async route path)
now serves the cached value and refreshes via a background thread (stale-while-
revalidate) instead of blocking on systemctl. `image_verifier.rs` cosign sites have no
callers yet — handled with the §A cosign item. Tests: container 155 / transport 29 /
config 29 / package 46 all green.
- [x] 🟡 **Restrict Bitcoin RPC exposure.** DECIDED (user, 2026-07-08: break external
wallets) + DONE `dd61a204`: manifest port mappings grew a validated `bind` field;
bitcoin-knots/-core publish 8332 on `127.0.0.1` + the archy-net gateway `10.89.0.1`
only (in-node consumers dial host.archipelago/host.containers.internal → 10.89.0.1,
unaffected; P2P 8333 stays public); legacy config.rs strings get the same incl.
unauthenticated ZMQ 28332/28333. Unbound ports render byte-identical (no false-drift
wave). **Still to roll out:** catalog regen + re-sign for catalog-covered nodes;
each node's bitcoin container recreates once on deploy → restart lnd after (IP cache).
- [x] 🟡 **Move secret env out of plaintext channels → podman secrets.** DONE 2026-07-05,
**VERIFIED ON .228 2026-07-08**: recreate wave settled (only fedimint-gateway lagged —
restart-sensitive, converged via a controlled quadlet restart, healthy, 0 plaintext
password vars in inspect); btcpay inspect carries no secret values; 17 quadlet unit
files use `Secret=` lines. Original notes:
secret env no longer merges into `environment` — it would land in `podman inspect`
AND as plaintext `Environment=` lines in Quadlet unit files on disk (the worse leak).
New pipeline: `expand_and_partition_env` taints plain entries that interpolate
secrets (btcpay's `Password=${BTCPAY_DB_PASS}` connection strings travel as secrets
too), values register as podman secrets (stdin, `--replace`, content-hash label,
per-app cache so steady-state reconciles are podman-free), containers reference
them via `secret_env` (API) / `Secret=…,type=env` (Quadlet). Verified empirically
on fleet podman 5.4.2: value absent from inspect, runtime injection works. Rotation
drift via `io.archipelago.secret-env-hash` container label; pre-upgrade containers
lack the label → ONE-TIME recreate wave on first reconcile after deploy (by design —
scrubs plaintext secrets from existing container configs). Docker dev fallback keeps
plain env (no secret store). `/proc/<pid>/environ` inside the container is unchanged
(env is the app-compat contract); the closed leaks are inspect output + unit files.
- [x] 🟡 **Harden rate-limit IP extraction.** DONE 2026-07-03: the accept loop injects the
TCP `PeerAddr` into request extensions; `extract_client_ip` honors
`X-Real-IP`/`X-Forwarded-For` ONLY when the connection is from loopback (our nginx,
which sets `X-Real-IP $remote_addr`) — direct connections (e.g. the FIPS peer
listener) bucket under their socket IP, so per-request header rotation no longer
defeats the login limiter. 3 unit tests.
- [x] 🟢 **Include `seq` in the mesh signed preimage.** DONE 2026-07-04 (receiver half):
`verify_signature` accepts a v2 preimage `(t,v,ts,seq)` alongside legacy v1 `(t,v,ts)`;
`signed_with_seq()` is the v2 sender path, deliberately NOT yet wired — receivers
hard-drop bad signatures, so senders stay on v1 until the whole fleet verifies v2.
The seq-tampering window closes only when the v1 arm is removed (track as a
post-fleet-rollout follow-up). Unit tests cover v2 verify, v2 seq-tamper rejection,
and v1 sign-then-set-seq compatibility.
- [x] 🟢 **Guard the short-DID slice panic** (`mesh/listener/decode.rs:566`) and gate the
dev-mode `password123` bypass (`auth.rs:18`) behind `#[cfg]`. DONE 2026-07-04:
advert_name uses `.get()` fallback (malformed radio-supplied DID can't panic the
listener); the pre-setup dev-password login + the constant itself are
`#[cfg(debug_assertions)]` — no release binary carries the bypass regardless of
runtime config.
- [ ] 🟢 **Apply the seccomp/apparmor profile** — `security/src/container_policies.rs:71` is a
TODO; the profile is defined but never applied to podman.
- [ ] 🟡 **Manifests that hardcode secrets in plain `environment:` bypass the whole secret
pipeline** (found during the 2026-07-08 .228 leak check): indeedhub-api/-ffmpeg ship
`AES_MASTER_SECRET=0123456789abcdef…` and photoprism `PHOTOPRISM_ADMIN_PASSWORD=archipelago`
as literal plaintext in quadlet unit files; grafana's `GF_SECURITY_ADMIN_PASSWORD=$${…}`
reference never expands. Fix = declare them as `generated_secrets`/`secret_env` in the
manifests — which means catalog regen + re-sign + republish (catalog overlay supremacy).
- [x] 🟠 **Legacy `mempool` umbrella id destroys the split stack on stop→start (quadlet).**
FOUND by the first quadlet-mode gate run on .228 (2026-07-08), FIXED `161a6e4d`:
orchestrator start/stop/restart now alias `mempool` → the split members whenever the
umbrella manifest was dropped (same alias install already used); podman-5
`no such object` phrasing added to all 3 `is_missing_container_error` classifiers.
Follow-up (open): reconciler-side cleanup of an orphan umbrella `mempool` container
when the split stack owns the frontend, so the stale-tile state can't arise at all.
- [x] 🟠 **Transitional package state sticks past the gate window on legacy apps**
(vaultwarden:stop run C, jellyfin:stop run D, uptime-kuma:start run E — .228
2026-07-09), FIXED `dd3afbba`: the scanner already saw the settled container every
60s but `merge_preserving_transitional` refused to report it until the RPC worker
wrote back — and workers legitimately trail the container by minutes (stop workers
queue behind the orchestrator app_lock that reconcile's host-port repair holds
through multi-minute stability waits; start workers hold `Starting` through
readiness budgets up to 420s for uptime-kuma against a 240s gate window, with the
20-minute Installing stuck-timeout as the only escape). New merge rules:
(Stopping, Stopped)+user-stop-marker → Stopped; (Starting, Running) → Running;
Restarting deliberately unresolved. Follow-up (open, same family as the op-lock
known-limit): repair/readiness waits should abort early when a user-stop marker
appears mid-wait, so an explicit stop is never queued behind a multi-minute repair.
- [x] 🟢 **`install_log()` has been a no-op since April** — `/var/log/archipelago/
container-installs.log` is 0 bytes: the service sandbox leaves /var/log read-only,
the open() fails, fire-and-forget drops every line. FIXED `c3f0a306`: every line
now mirrors to tracing/journald; file append stays best-effort.
- [x] 🟢 **Gate tests 123/124 false-fail on user-stopped apps with lingering quadlet
units** (run E: the inactive bitcoin-core of the multi-version pair), FIXED
`2683ad4f0`: `use-quadlet-backends-install.bats` active-state asserts now honour
`user-stopped.json`.
- [ ] 🟠 **Backend recreate must cascade to dependent apps** (found on .228 2026-07-08):
when bitcoin-knots was recreated mid-gate (one-time secret-env recreate) it got a new
archy-net IP; **lnd caches the resolved backend IP** and kept dialing the dead one
("no route to host") for 30+ min — chain-blind with open channels, silently (container
"running", health green). Repair was a manual lnd restart. Fix = reconciler/health
monitor restarts (or at least alerts on) apps whose declared backend container was
recreated; same class applies to electrumx/btcpay/nbxplorer → bitcoin links.
---
## §D — Frontend security & performance (🟠)
The untrusted mesh/LoRa chat path is **safe** (interpolation, no `v-html` — good).
The real issues are the app-bridge origin model and a bloated bundle.
- [x] 🟠 **Validate `event.origin` + add consent gates in the NIP-07 nostr bridge.**
DONE 2026-07-02: `handleNostrRequest` rejects senders whose `event.origin` doesn't match
the open app's URL origin, and ALL identity-sensitive methods (`getPublicKey`, `signEvent`,
`nip04`/`nip44` encrypt+decrypt) now go through the consent/approved-origins gate, not just
`signEvent`. Verified present in the built bundle.
- [x] 🟠 **Origin-check the `share-to-mesh` handler.** DONE 2026-07-02: `App.vue`
`onShareToMeshMessage` now requires `ev.origin === window.location.origin` (matching
`Chat.vue`).
- [ ] 🟡 **Decide the app-iframe isolation model.** `AppSessionFrame.vue:54` /
`AppLauncherOverlay.vue:79` embed apps same-origin with no meaningful `sandbox`; a
same-origin app can read the CSRF cookie + `localStorage`. Ideal fix (serve apps from a
per-app subdomain origin) is architectural — at minimum decide + document for 1.8.0.
- [ ] 🟡 **Shrink the 93 MB dist.** `assets/video/video-intro.mp4` is **14.7 MB**
(precached by the service worker → blocks PWA install), plus ~18 MB of ~1 MB full-screen
JPEGs. Convert backgrounds to WebP/AVIF at responsive sizes, lazy/stream the intro video,
and exclude video/audio from the Workbox precache. Biggest, easiest perf win.
- [x] 🟢 **DOMPurify the `Server.vue` QR SVG / guard `Mesh.vue` pollInterval / surface
`curatedApps.ts` fetch failures.** DONE 2026-07-03: WireGuard peer QR now sanitized with
the same `USE_PROFILES: {svg}` call as TwoFactorSection; Mesh poll interval guarded +
nulled on unmount; catalog fetch failures log per-URL console.warn incl. the
all-sources-failed fallback. Bundle-verified.
---
## §E — Mesh transports (🟢 mostly done — verify & polish)
Confirmed **fixed in HEAD:** B8 (1970 timestamps), B6 (inbound RX surfacing), the
per-message transport pill, and the archy↔archy plain-TEXT-DM E2E fix. Remaining:
- [ ] 🟠 **Active Reticulum daemon-death detection.** `reticulum.rs:589` only `warn!`s on
socket EOF and `try_recv_frame` then returns `Ok(None)` forever; nothing calls
`child.try_wait()`. On an idle link a crashed daemon is invisible for up to 30 min (the
RX-stall timeout). Treat socket EOF as `Err` → immediate respawn. (Pairs with the current
`fix/reticulum-daemon-pdeathsig` branch work.)
- [ ] 🟡 **Persist chat history across restarts.** `state.messages` boots empty
(`listener/mod.rs:283`) while outbox/scheduler/peers survive — inconsistent; bubbles
vanish on restart. Add `mesh-messages.json` mirroring the `scheduler.rs`/`outbox.rs`
pattern (or explicitly accept the loss).
- [ ] 🟡 **Tighten the 30 s legacy dedup** (`listener/mod.rs:383-389`) — it silently drops a
peer legitimately sending identical text twice within 30 s.
- [ ] 🟢 **Wire the PyInstaller daemon binary into the release tarball / deploy script**
(Rust expects `/usr/local/bin/archy-reticulum-daemon`, `reticulum.rs:80`); add the RNode
udev rule; finish `ARCHY:2:` announce→`arch_pubkey_hex` binding (`reticulum.rs:119`).
- [ ] 🟢 **Duty-cycle guard for LoRa TX** — none exists; EU 868 is legally 1%. At minimum an
airtime budget/warning.
---
## §F — ISO / image build (🔴 one secret leak; otherwise 🟠 hardening)
`image-recipe/_archived/build-auto-installer-iso.sh` (3604 lines) is the real
builder; OTA is the normal update path but the ISO is what produces installable
media (latest artifact only one minor behind).
- [ ] ⛔🔴 **Anthropic API key — INTENTIONAL for alpha/beta, hard GO-LIVE gate.**
`build-auto-installer-iso.sh:2645` bakes a live `sk-ant-…` key into `claude-api-proxy.service`
so alpha/beta testers get frictionless AI (deliberate — per user 2026-07-02). **Do NOT
remove for alpha/beta.** Before public GA it MUST be removed + rotated + injected at runtime
(a second copy also exists in a worktree). Track it here so it can't be forgotten at launch.
- [x] 🔴 **Per-device secrets on first boot.** DONE 2026-07-13 (`caf9e6d3`):
`archipelago-first-boot-secrets.service` (enabled on the installed target, ordered
Before=ssh/nginx/archipelago, marker-guarded) regenerates the self-signed TLS keypair
with the device hostname in the SAN and all SSH host keys via staging-first swap —
a failed regeneration keeps the baked keys instead of leaving the device keyless.
**Unverified on hardware**: needs one RC-ISO install to confirm the service fires
and sshd/nginx pick up the new keys.
- [~] 🟠 **Kill default credentials.** The **web** default is GONE: no default account is
ever created (`main.rs:356-362` deliberately does not call `AuthManager::ensure_default_user`),
the login screen shows a password-creation form while `auth.isSetup` is false, and the
`password123` pre-setup bypass is `#[cfg(debug_assertions)]` + `dev_mode` (`api/rpc/auth.rs:36-46`),
so no release binary carries it. STILL SHIPPING: the SSH login
`archipelago`/`archipelago` (`image-recipe/archipelago-scripts/install-to-disk.sh:205`)
and SSH `PasswordAuthentication yes`. Lock root, disable SSH password auth (or
force-change on first login).
- [~] 🟠 **Sign + checksum the ISO.** Checksums DONE 2026-07-13 (`caf9e6d3`): the builder
emits `<iso>.sha256` after xorriso, and `scripts/sign-iso-checksums.sh` signs
`{artifact, sha256, size}` as a JSON doc with the release-root ceremony (verify with
`archipelago ceremony verify` against the pinned anchor; build host never holds the
key). **Still open:** Secure Boot — `BOOTX64.EFI` is unsigned though
`grub-efi-amd64-signed` is installed.
- [ ] 🟠 **Registries over HTTPS in the image too** — `source.archipelago-foundation.org`
are baked `insecure=true`/`tls_verify:false` (`:216`, `:2308`). (Ties to §A.)
- [ ] 🟡 **Add `unattended-upgrades` + a default-deny nftables firewall** (allow 22/80/443 +
mesh/WG). Neither exists today; OS packages drift until reflash and there is no host
firewall.
- [ ] 🟡 **Pin the build for reproducibility.** FIPS daemon is built from unpinned upstream
`main`, Tailscale from its live apt repo, and `scripts/image-versions.sh` uses many
`:latest`/`stable` tags (+ `bitcoin-ui:1.7.84-alpha`, 15 behind). Pin to commits/versions;
snapshot apt. Wire ISO version to `Cargo.toml` so it can't drift.
- [ ] 🟢 **Harden LUKS + roadmap A/B partitioning.** The LUKS data key sits in plaintext on the
unencrypted root (`:2137`); add TPM2/passphrase binding. Longer-term: A/B (or
factory-reset) partitions for safe OTA rollback, and a real install-time TUI
(`docs/archive/INSTALL-SCREENS-DESIGN.md` exists but the installer is headless "press Enter").
---
## §G — Refactor & code health (🟢 not release-blocking; do after the tag or opportunistically)
- [ ] 🟢 **Manifest-drive per-app special-casing.** App names are branched on across 5-7 Rust
files (`config.rs` 36 match arms, `runtime.rs` 17, `install.rs:275-287` dispatch,
`prod_orchestrator.rs:54-83` baseline/restart-sensitive lists). Move `baseline`,
`restart_sensitive`, `stack_members`, `multi_container` into the manifest schema; collapse
the five near-identical `install_*_stack()` wrappers into one generic call. **Biggest
maintainability win.** (Grew again 2026-07-09: `stack_member_app_ids` in
`package/dependencies.rs` — the quadlet stack-resurrection fallback — is a fifth
per-app map that must fold into the same manifest field.)
- [ ] 🟢 **Route all podman/systemctl through `podman_client`.** 113 raw `Command::new("podman")`
+ 32 `systemctl` calls bypass the existing 952-LOC wrapper → untestable + the blocking-call
risk (§C). Consolidating also unlocks unit tests for the thinly-tested `package/` handlers
(`stacks.rs` 1 test, `config.rs` 2, `runtime.rs` 3, `install.rs` 7).
- [ ] 🟢 **Split the god-modules.** `prod_orchestrator.rs` (5,263 LOC) → `orchestrator/{reconcile,
host_ports,ownership,hooks}.rs`; `Mesh.vue` (2,485 LOC / 241 KB chunk) → sub-components.
Both are well-tested, so safe.
- [ ] 🟢 **Delete dead code.** ~4,100 LOC of orphan StartOS crates (`js-engine`, `models`,
`helpers`, `container-init`) not in the workspace or linked; the committed AppleDouble
`._*.rs` files; the committed `.venv/`/`build/`/`__pycache__` under the duplicate
`reticulum-daemon/` tree; promote `MeshRadioDevice` enum → trait.
- [ ] 🟢 **Resolve the Quadlet flag & dep hygiene.** Decide `use_quadlet_backends`' fate
(flip default + delete the legacy `create_container` branch, or freeze as experimental —
don't ship both half-maintained). Consolidate the mixed hyper 0.14/1.x ecosystem; bump
stale majors (reqwest, base64, thiserror, tokio-tungstenite).
---
## §H — Testing gaps that gate confidence (🟠)
- [ ] 🟠 **Add the OTA upgrade soak** (same as §B item 2) — the highest-value missing test.
- [ ] 🟡 **Add a host-reboot survival tier** — every app is `○` (untested) for reboot in
`TESTING.md:138`; the gate can't reboot the node it runs on. Run SSH-`reboot`-then-reprobe
out-of-band per node.
- [ ] 🟡 **Make the release gate run the full Rust suite** (or hard-require a green CI sha).
`tests/release/run.sh:101` runs only a 6-module slice because the full 1000-test suite
hangs PTYs on the dev box → 994 tests unverified at release time if CI is stale.
- [x] 🟡 **Add `--max-time` to `node_rpc()`.** DONE 2026-07-08 (`380f4f19`): login + rpc get
`--connect-timeout 10 --max-time 120` (override `MULTINODE_RPC_TIMEOUT`). Verified live:
.116 login/rpc OK; an unroutable node fails in 10s instead of hanging.
- [x] 🟢 **De-hardcode creds in tests.** DONE 2026-07-08 (`380f4f19`): multinode suites no
longer commit node passwords — `*_PW` env required, auto-loaded from git-ignored
`tests/multinode/.env` (`.env.example` documents the shape). Still open from this
bullet: snapshot/restore node baseline between destructive iterations
(teardown currently only clears `/tmp` session files).
---
## §I — Carried-over open items (still valid)
- [~] 🟠 **Multinode gate pass** — 5× destructive gate was launched on node `.5`; bring the
rest of the fleet to precondition, then run the existing (undocumented-but-present)
`tests/multinode/{smoke,meshtastic}.sh` cross-node suites.
- [~] 🟠 **Federation `remove-node` tombstone regression.** Code fix DONE 2026-07-02:
`remove_node` now tombstones BEFORE trimming the node list and propagates the write
error (idempotent, so retries are clean); `add_node`'s untombstone likewise propagates
before mutating. **Still open: `tests/multinode/smoke.sh` re-verify on real nodes.**
- [ ] 🟠 **Phase-3 Quadlet default-flip** — validated + opt-in on .228/.198; flip
`config.rs:256` once the .5 gate reports clean.
- [ ] 🟠 **Developer CLI suite** (`archy app validate/render/install/test`) — gates external
app publishing (`APP-PACKAGING-MIGRATION-PLAN.md` step 5).
- [ ] 🟡 **Version bump + tag** — DECIDED (user, 2026-07-08): the release ships as
**`1.8.0-alpha`**. Remaining work is the mechanical bump + `create-release.sh` run
when the gate criteria are met.
- [ ] 🟢 **Bitcoin multi-version fleet OTA** — DECIDED (user, 2026-07-08): timing doesn't
matter; fold the branch into the next fleet OTA.
- [x] ~~⛔🟢 **3ccc stock-Meshtastic RF validation**~~ — DROPPED per user 2026-07-08; the
code fix stays in, no live-radio validation will be scheduled.
---
## Suggested order of attack
1. **The critical path:** §A signing ceremony → then turn on manifest/catalog/image
signature enforcement (§A) + OTA HTTPS/signature + deeper health check (§B).
2. **Cheap high-ROI stability:** §C swallowed-writes + blocking-calls; §D nostr-bridge
+ share-to-mesh origin checks; §H OTA soak + reboot tier.
3. **Image hardening:** rest of §F (per-device secrets, default creds, ISO signing,
firewall/unattended-upgrades, pinning).
4. **Polish, post-tag:** §G refactors, §E mesh persistence/dedup, §D bundle shrink.
5. **Decisions you own (⛔):** version name, signing mnemonic, bitcoin OTA timing, 3ccc test.
6. **Before public GA only (NOT alpha/beta):** remove + rotate the Anthropic key (§F) —
intentionally left in for frictionless AI during alpha/beta.
*Last updated: 2026-07-13 (hardening session 4: §F per-device first-boot
secrets + ISO checksum emission/ceremony signing `caf9e6d3` — both need one
RC-ISO install to verify on hardware; Secure Boot remains the open half of
ISO signing). Update this line + tick boxes with commit shas as items land.*
docs/APP-PACKAGING-MIGRATION-PLAN.md
+451
View File
@@ -0,0 +1,451 @@
# App Packaging Migration Plan
## Goal
Turn Archipelago into a serious app platform while preserving the fundamentals that drove the original architecture:
- Rootless Podman and security-first execution.
- Managed node-OS behavior: health, repair, backups, updates, secrets, and routing.
- Bitcoin/LND/Tor/Web5/mesh integration where the platform genuinely needs deep awareness.
- A developer-friendly app packaging model that avoids app-specific Rust installers as the normal path.
## Current Contract
The runtime contract is manifest-first. App packages live at `apps/<app-id>/manifest.yml` and are validated by the shared container manifest parser.
The current canonical manifest fields are:
- `app`: identity and app-level metadata.
- `container`: image or build source, pull policy, network, entrypoint, custom args, derived env, secret env, and data UID.
- `dependencies`: storage and app dependencies.
- `resources`: CPU, memory, disk.
- `security`: capabilities, read-only root, no-new-privileges, network policy, optional AppArmor profile.
- `ports`, `volumes`, `files`, `environment`, `health_check`, and `devices`.
- `metadata`: current catalog-facing presentation data such as category, tier, icon, repo/source, author, and features.
- extension keys may exist temporarily, but they are transitional and should not become a second contract.
The historical `archy-app.yml` name should be treated as superseded. The active local package filename is `manifest.yml`.
## Current Progress
As of the current `1.8-alpha` workstream:
- `apps/*/manifest.yml` is the source of truth for runtime app definitions.
- The Rust manifest parser validates app identity, image-vs-build source selection, safe environment/secrets, safe ports, safe bind/named/tmpfs volumes, generated files under declared bind mounts, devices, and security/network policy values.
- Manifest-owned generated files exist through `app.files` and have been used for app config material (e.g. strfry, netbird config regeneration).
- Local image builds are represented with `container.build`; pulled images are represented with `container.image`.
- Data ownership repair is represented with `container.data_uid`.
- Derived host facts and secret-file-backed environment variables are represented with `container.derived_env` and `container.secret_env`.
- Catalog metadata generation is implemented by `scripts/generate-app-catalog.py`.
- App-session launch ports/titles and new-tab launch behavior now have a generated TypeScript metadata path from manifests, with manual overrides preserved for companion UIs and aliases that do not have manifest-owned metadata yet.
- Runtime package listings now derive LAN launch URLs from manifest-owned `interfaces.main` declarations or HTTP app ports before falling back to legacy compatibility aliases.
- Release drift checking is implemented by `scripts/check-app-catalog-drift.py --release --strict`.
- The canonical catalog and the UI public catalog are expected to remain byte-for-byte synced after generation.
- Runtime validation has already moved many simple and moderate apps into the manifest/orchestrator path, including Filebrowser, Vaultwarden, Portainer, Uptime Kuma, Grafana, Gitea, Nextcloud, SearXNG, Nostr Relay, PhotoPrism, Jellyfin, and several Bitcoin-adjacent apps.
The remaining migration work is mostly orchestration quality: post-reboot adoption, progress reporting, stale scanner-state handling, update policy, multi-container stack ownership, proxy route generation, and cleanup of obsolete legacy installers/fallbacks.
## Target Architecture
Use a StartOS-inspired package model with Umbrel-like app folders.
```text
apps/example-commerce/
manifest.yml
Dockerfile
icon.svg
screenshots/
instructions.md
hooks/
post-install.sh
pre-start.sh
repair.sh
health.sh
backup.sh
restore.sh
proxy/
routes.yml
```
Archipelago becomes the secure compiler/runtime for these packages. The manifest declares what it needs; Archipelago validates it, injects secrets, creates rootless Podman containers, generates nginx/Tor/public routes, registers health checks, displays credentials, and manages lifecycle.
## Core Principles
- App packages are declarative by default.
- Hooks are allowed only as controlled, reviewed escape hatches.
- Rootless Podman stays.
- Arbitrary privileged Compose execution is not allowed.
- Each app has one source of truth.
- Catalog, launch URLs, mobile behavior, credentials, backup paths, and public routes come from the app package or its generated catalog entry.
- Rust backend owns orchestration, not app-specific business logic.
- Core infrastructure can remain special-case where justified.
## What Stays
- Rootless Podman.
- Archipelago orchestrator.
- Health/reconcile/repair loops.
- Host nginx.
- Nginx Proxy Manager integration.
- Tor/public routing goals.
- Bitcoin/LND/mesh/Web5/FIPS/security direction.
- OTA update system.
- App-session/mobile shell.
- Managed secrets and credentials display.
## What Changes
- Complex app stacks stop living in Rust.
- `app-catalog/catalog.json` becomes generated.
- Frontend fallback marketplace data is removed or generated.
- App-session port maps and new-tab launch behavior become generated.
- Public proxy routes become app-declared.
- Install/start/restart/backup/restore become package-driven.
- App updates become app package changes where possible, not full backend code changes.
## Package Schema Direction
Example `manifest.yml`:
```yaml
app:
id: example-commerce
name: Example Commerce
version: 3.23.0
description: Composable commerce platform
container:
image: docker.io/myorg/example-commerce:1.0.0
pull_policy: if-not-present
network: archy-net
entrypoint: ["sh", "-lc"]
custom_args:
- /app/start.sh
derived_env:
- key: PUBLIC_URL
template: https://{{HOST_MDNS}}:9010
secret_env:
- key: SALEOR_SECRET_KEY
secret_file: example-commerce-secret-key
dependencies:
- storage: 20Gi
resources:
cpu_limit: 4
memory_limit: 2Gi
security:
capabilities: []
readonly_root: true
no_new_privileges: true
network_policy: isolated
ports:
- host: 9010
container: 9000
protocol: tcp
volumes:
- type: bind
source: /var/lib/archipelago/example-commerce
target: /data
options: [rw]
environment:
- NODE_ENV=production
health_check:
type: http
endpoint: http://localhost:9000
path: /health
interval: 30s
timeout: 5s
retries: 3
```
Optional generated files, hooks, icons, and screenshots can sit beside the manifest, but the manifest stays the source of truth. Compose-style definitions are not executed directly.
## Security Model
Do not run arbitrary Compose directly. Archipelago validates:
- No privileged containers unless explicitly approved.
- No host filesystem mounts outside approved paths.
- No Docker socket mounts.
- No host network unless explicitly approved.
- No dangerous capabilities by default.
- No arbitrary device access without declaration.
- No rootful execution.
- Pinned images preferred.
- Resource limits required.
- Backup paths declared where the app stores durable data.
- Public routes explicit.
- Secrets referenced by name, not hardcoded.
When the runtime needs app-specific facts that do not belong in the manifest, prefer adding a reusable platform primitive rather than introducing another ad hoc installer path.
This preserves the reason for avoiding raw Umbrel-style Compose while still giving developers a sane package format.
## Lifecycle Model
Every app package should support:
- install
- configure
- start
- stop
- restart
- update
- repair
- health
- backup
- restore
- uninstall
- migrate
Archipelago owns the state machine.
Optional hooks:
- `post-install.sh` for migrations/admin creation.
- `pre-start.sh` for ownership repair.
- `repair.sh` for app-specific remediation.
- `health.sh` for custom health checks.
- `backup.sh` and `restore.sh` only when simple path backups are insufficient.
Hooks run with a controlled environment and restricted permissions.
## Hard Work
The hard work is not writing YAML. The hard work is safely translating app packages into reliable rootless runtime behavior:
- Build a robust package validator.
- Map a safe Compose subset to rootless Podman.
- Handle multi-container networks without hardcoded IPs.
- Handle rootless volume ownership correctly.
- Generate host nginx routes from app metadata.
- Handle public-domain apps without leaking private `192.168.x.x` or `100.x.x.x` URLs.
- Inject secrets without exposing values in logs or frontend bundles.
- Make backup/restore consistent across databases and files.
- Migrate existing hand-built containers to package-owned containers.
- Keep old alpha nodes working while introducing the new system.
- Avoid keeping two permanent systems that drift forever.
## Alpha Node Impact
Existing alpha nodes must not be broken.
Phase 1 behavior:
- Current Rust installers keep working.
- Current app manifests keep working.
- New app package loader exists beside the old system.
- No existing app is automatically migrated.
- Alpha nodes receive compatibility code only.
Phase 2 behavior:
- New installs of selected apps use package mode.
- Existing installs can be detected and adopted.
- App state is preserved.
- Migration is opt-in or happens only for low-risk apps.
Phase 3 behavior:
- Stable migrated apps switch to package mode by default.
- Existing containers are adopted if names/volumes match.
- Data directories are preserved.
- Old Rust installers remain as fallback for at least one release cycle.
Phase 4 behavior:
- Remove old installers only after live alpha validation.
- Keep migration repair code for already-deployed nodes.
## Migration Rules
For every migrated app:
- Preserve `/var/lib/archipelago/<app>` data.
- Preserve generated secrets.
- Preserve credentials shown to users.
- Preserve public ports where possible.
- Preserve container names where needed for adoption.
- Never delete volumes during migration.
- Stop/recreate containers only when necessary.
- Record migration version in app state.
- Provide rollback path to old installer for alpha builds.
## Notes For The Release
- Catalog entries should be generated from manifests so the UI and runtime agree on launch metadata.
- The developer docs should describe the manifest/runtime contract that exists today, not the older publish-model draft.
- If a new capability is needed, add one reusable manifest field or orchestrator primitive and document it here before wiring a one-off app branch.
## First Apps To Migrate
Start with low-risk apps:
- Filebrowser
- Vaultwarden
- Uptime Kuma
- Grafana
Then moderate apps:
- Gitea
- Nextcloud
- SearXNG
- Nginx Proxy Manager metadata integration
Then complex apps:
- Mempool
- BTCPay Server
- NetBird only if safe
Leave for later:
- Bitcoin
- LND
- Electrs/ElectrumX
- Tor
- System update
- Mesh/Web5/FIPS core services
## Complex Stack Reference Goal
Saleor has been removed from the supported release catalog until it has a real
manifest-owned package. A future complex stack should become the showcase
package and prove:
- Multi-container stack support.
- Generated secrets.
- Post-install migration/admin user hooks.
- Dashboard/API/storefront routes.
- Same-origin public GraphQL routing.
- Credentials display.
- Backup paths.
- Health checks.
- Public domain support.
- Alpha-node adoption.
Once a complex stack is clean, the app system is credible.
## Implementation Phases
**Status (2026-07-08):** Phases 1–3 ✅ DONE (per-member manifests won over a
compose subset; all five real multi-container stacks — btcpay, mempool,
immich, netbird, indeedhub — install via `install_stack_via_orchestrator`).
Phase 5 mostly done (orchestrator-first with legacy fallback + per-app
adoption/repair). Phase 4 (routing via `proxy/routes.yml`) NOT started —
routing is still host-nginx driven. Phase 6 (cleanup + developer CLI) NOT
started; the CLI gates external app publishing.
### Phase 1: Package Contract
- Use `apps/<app-id>/manifest.yml` as the package contract.
- Keep the Rust parser/validator as the canonical schema implementation.
- Keep generated catalog output from manifest-owned metadata.
- Finish generated app-session launch metadata so launch behavior cannot drift from manifests.
- Add/keep tests for unsafe package rejection.
### Phase 2: Single-Container Runtime
- Continue hardening package install for one-container apps.
- Compile manifests to rootless Podman/Quadlet runtime behavior.
- Support ports, env, generated files, devices, volumes, resources, health checks, data UID repair, image pull/build availability checks, and launch metadata.
- Keep Filebrowser, Vaultwarden, Portainer, Uptime Kuma, Grafana, SearXNG, Jellyfin, PhotoPrism, and similar apps as regression proofs.
### Phase 3: Multi-Container Runtime
- Decide whether multi-container stacks use a safe `compose.yml` subset or a manifest-native `services` section.
- Support app-local networks.
- Support service dependencies and readiness gates.
- Support internal service names.
- Support generated env/secrets across services.
- Support controlled hooks only where declarative primitives are insufficient.
- Adopt existing multi-container apps without deleting data.
### Phase 4: Routing
- Add `proxy/routes.yml`.
- Generate host nginx routes.
- Generate Tor/public routes.
- Fix same-origin API routing class of bugs permanently.
- Integrate with Nginx Proxy Manager sync.
### Phase 5: Migration
- Add adoption logic for existing containers.
- Add migration metadata.
- Migrate simple apps.
- Migrate a serious multi-container app once the stack model is stable.
- Keep rollback.
- Prove reboot recovery with repeated clean post-reboot lifecycle passes.
- Preserve Nostr signer bridges, Bitcoin dependency wait states, and public launch ports during adoption.
### Phase 6: Cleanup
- Remove duplicated catalog/frontend data.
- Remove migrated Rust stack installers.
- Document package format.
- Add developer tooling: validate, test, package, install locally.
- Remove stale fallback metadata, app-specific lifecycle branches, and compatibility shims only after live validation.
## Developer Tooling
Add commands like:
```bash
archy app validate apps/example-commerce
archy app render apps/example-commerce
archy app install apps/example-commerce
archy app test apps/example-commerce
```
Developers should be able to package an app without understanding Archipelago internals.
## Open Source Story
Public explanation:
> Archipelago uses rootless Podman and a validated app package format. App authors define services declaratively, while the OS enforces security, secrets, routing, backups, health, and lifecycle repair. This gives us Umbrel-like app packaging with StartOS-like managed service discipline.
## Rework Estimate
- Package schema and validator: 1-2 weeks.
- Single-container package runtime: 1-2 weeks.
- Generated catalog/frontend metadata: 1 week.
- Multi-container support: 2-4 weeks.
- Routing/public proxy integration: 1-2 weeks.
- Hooks/secrets/backups: 2-3 weeks.
- First migrations: 2-4 weeks.
- Complex stack reference migration: 1-2 weeks.
- Cleanup/docs/tooling: 2-3 weeks.
Total estimate: 8-14 weeks of serious work for an excellent system.
Minimum viable version: 3-5 weeks.
## Biggest Risks
- Rootless Podman edge cases continue to bite.
- Compose compatibility scope creeps too wide.
- Hooks become an unsafe escape hatch.
- Migration accidentally disrupts alpha nodes.
- Generated metadata drifts from old manual data during transition.
- Old and new systems remain permanently duplicated.
## Risk Controls
- Support a strict Compose subset, not all Compose.
- Validate everything.
- Keep hooks minimal and logged.
- Migrate one app at a time.
- Add live alpha-node checks before each release.
- Generate catalog/app-session data early.
- Set a deadline for deleting migrated legacy installers.
## Immediate Next Steps
1. Expand generated app-session metadata beyond ports/titles/new-tab behavior to cover proxy paths and companion UI aliases where those can be declared safely in manifests.
2. Define the app update policy and wire it into manifest/catalog metadata.
3. Finish post-reboot adoption and stale scanner-state handling for migrated apps.
4. Convert remaining multi-container legacy stacks to a manifest-owned model without deleting data.
5. Add developer tooling around the current `manifest.yml` contract: validate, render, local install, lifecycle test.
6. Migrate a serious multi-container app as the proof package once the stack model is stable.
7. Leave Bitcoin/LND/core services as managed infrastructure until the package system is proven for normal apps.
docs/COMMANDS.md
+145
View File
@@ -0,0 +1,145 @@
# Talking to your node
Every way to ask an Archipelago node a question: over the LoRa mesh, by voice, and over HTTP.
Two rules worth internalising before the tables:
- **`!ai` asks a language model. `!archy` never does.** `!archy` reads the same status caches the HTTP endpoints serve, so its answers are deterministic, cost nothing, and keep working with the assistant switched off.
- **Mesh command prefixes are exact strings** (case-insensitive). **Voice phrases are not** — they are matched by Home Assistant's intent parser, so the examples below are representative, not literal.
---
## 1. Mesh commands
Sent as ordinary text over the mesh — either as plain channel/DM text from a stock meshcore or Meshtastic client, or typed into a 1:1 chat in the Archipelago UI.
### `!archy` — node status, no AI
| Command | Aliases | Answers with |
|---|---|---|
| `!archy` | `!archy status` | OS version, chain tip, peer count, electrum progress |
| `!archy btc` | `bitcoin`, `node`, `sync` | Sync state, block height, peer count |
| `!archy electrs` | `electrum` | Electrum index progress |
| `!archy version` | `ver` | Archipelago OS version |
| anything else | — | A one-line usage hint |
Examples of what comes back:
```
!archy → Archipelago OS v1.7.99-alpha: BTC synced 957295 (12p), electrum 86%.
!archy btc → BTC: synced, block 957295, 12 peers.
!archy electrs → Electrum: syncing 86.2% (824785/957295).
!archy version → Archipelago OS v1.7.99-alpha
!archy wat → archy: !archy [status|btc|electrs|version]. Node status, no AI.
```
`!archyfoo` is not a command — the prefix must be followed by whitespace or end-of-message.
### `!ai` / `!ask` — language model
```
!ai what is the halving schedule
!ask how do I open a lightning channel
```
Requires the assistant to be **enabled** (`assistant_enabled` in `mesh-config.json`). Backend is `ollama` (default, `qwen2.5-coder`) or `claude` (`claude-haiku-4-5-20251001`), set by `assistant_backend`. The model is told to reply in at most two short sentences, because airtime is scarce.
### Who is allowed to ask
Both commands share one gate — `is_sender_allowed()` in `mesh/listener/assist.rs`. Evaluated in order:
1. **Blocked contact** → always denied.
2. **On `assistant_allowed_contacts`** → allowed, even without a signature. This is the deliberate opt-in for keyless phone clients.
3. **`assistant_trusted_only == false`** → anyone on the mesh may ask.
4. **`assistant_trusted_only == true`** → the asker must be *authenticated* **and** carry federation `Trusted` status.
"Authenticated" means the message carried an Ed25519 signature that verified against the sender's known identity key, **or** it arrived over the federation (Tor) transport, which verifies upstream. **Bare plain-text radio messages are never authenticated** — so on a `trusted_only` node, a stock meshcore client can only get an answer by being on the allowlist.
Denials are silent on the wire (no airtime is spent saying "no"); the asker is recorded so an operator can allow them from the UI.
The one asymmetry: **`!ai` additionally requires `assistant_enabled`; `!archy` does not**, because it never calls a model. Turning the LLM off should not take node status with it.
### Where the answer goes
| You asked from | Reply arrives as |
|---|---|
| Plain radio text, your pubkey is known | A private unicast DM (not the public channel) |
| Plain radio text, pubkey unresolvable | A broadcast on channel 0 |
| 1:1 chat in the Archipelago UI | A chat bubble in the same thread |
| The `AssistQuery` widget | Ordered, reassembled `AssistResponse` chunks |
Size caps: 480 characters per answer overall, 200 for plain-text channel/DM replies, and a hard 160-byte LoRa frame limit underneath both.
---
## 2. Voice
A [PineVoice](https://pine64.org) satellite speaker, wake word **"Hey Jarvis"** (or press the centre button). Speech-to-text is Whisper, text-to-speech is Piper — both run locally on the node. Nothing leaves the box.
Phrases are matched by intent, so wording is flexible. These are examples, not exact strings:
| Ask something like | You hear |
|---|---|
| "What is Archipelago OS?" · "What is this node running?" | A one-sentence description plus the running version |
| "What version am I running?" | Version and uptime |
| "Is my node synced?" · "How is my Bitcoin node doing?" · "Bitcoin node status" | Sync state, block height, peer count |
| "What's the current block height?" · "How many blocks do we have?" | The chain tip |
| "Is the electrum server synced?" · "Electrum status" | Index progress |
Optional and alternative words are part of the templates, so "how is *the* node doing" and "how is *my* Bitcoin node" both land on the same intent.
### How voice is wired
The speaker is a Wyoming satellite. Home Assistant runs it through an Assist pipeline: wake word on-device → audio streamed to Whisper → intent matched → Piper speaks the answer.
| Piece | Location (on the node) |
|---|---|
| Whisper + Piper services | `~/.config/containers/systemd/wyoming-{whisper,piper}.container` |
| Wyoming entries, Assist pipeline | `home-assistant/.storage/{core.config_entries,assist_pipeline.pipelines}` |
| Sensors + spoken answers | `home-assistant/configuration.yaml` (`rest:` and `intent_script:`) |
| Phrasings | `home-assistant/custom_sentences/en/archipelago.yaml` |
Home Assistant reaches the node's own HTTP API at `host.containers.internal` — **not** the node's LAN IP, which under rootless podman's pasta networking resolves back to the container itself.
Adding a phrase means editing `custom_sentences/en/archipelago.yaml`; adding an *answer* means adding an `intent_script` entry (and a `rest:` sensor if it needs new data).
---
## 3. HTTP
Served by nginx on port 80, proxying the backend on `127.0.0.1:5678`.
**No authentication required** (5-second cache):
| Endpoint | Returns |
|---|---|
| `GET /health` | Status, uptime, version, services |
| `GET /bitcoin-status` | `getblockchaininfo` + `getnetworkinfo` + `getindexinfo` |
| `GET /electrs-status` | Index height, progress, onion address |
```bash
curl -s http://<node>/bitcoin-status | jq '.blockchain_info.blocks'
```
**Session required** — everything else goes through JSON-RPC at `POST /rpc/v1`:
```bash
curl -s http://<node>/rpc/v1 -H 'Content-Type: application/json' \
-d '{"method":"auth.login","params":{"password":"…"}}' -c jar.txt
curl -s http://<node>/rpc/v1 -b jar.txt -H 'Content-Type: application/json' \
-d '{"method":"system.stats","params":{}}'
```
Login returns a `session` cookie. State-changing calls also need the `X-CSRF-Token` header. Exactly twelve read-only methods are CSRF-exempt, so for those the cookie alone is enough:
`node-messages-received` · `server.echo` · `server.get-state` · `system.stats` · `system.get-settings` · `system.get-node-key` · `system.get-metrics` · `system.get-version` · `tor.status` · `tor.onion-addresses` · `bitcoin.relay-status` · `federation.list-nodes`
Anything not on that list — including `bitcoin.getinfo` and `monitoring.current` — needs the CSRF header. If TOTP is enabled, follow the login with `auth.login.totp`.
---
## Adding a command
- **New `!archy` sub-command** — add a variant to `NodeCmd` and a match arm in `run_node_cmd`, both in `mesh/listener/node_cmd.rs`. Keep answers under 200 characters so a stock client sees the whole thing in one frame.
- **New mesh prefix** — add a `strip_*_trigger` alongside `strip_archy_trigger`, then hook it in `decode.rs` (plain radio text) and `dispatch.rs` (typed 1:1 chat). Both paths must be wired or the command only works from one of them.
- **New voice phrase or answer** — see the voice table above.
docs/GAMEPAD-NAV.md
+159
View File
@@ -0,0 +1,159 @@
# Gamepad / Controller Navigation Map
## Global Controls
| Button | Action |
|--------|--------|
| D-pad Up/Down | Navigate between items |
| D-pad Left | Go to sidebar (from any page) |
| D-pad Right | Enter main content from sidebar |
| Enter (A) | Activate / click focused element |
| Escape (B) | Go back one level (inner → container → sidebar → detail page back) |
## Navigation Layers
```
SIDEBAR ──Right──► CONTAINERS (or NAV BAR) ──Enter──► INNER CONTROLS
▲ ▲ │
└──Escape──────────────┘◄─────────Escape──────────────────┘
```
### Sidebar
- **Up/Down**: Move between sidebar items (wraps), auto-navigates links
- **Right**: Jump to main content (first container, or first button on container-free pages)
- **Left**: Nothing
### Nav Bar (mode-switcher tabs, category buttons)
- **Left/Right**: Move between tabs
- **Down**: Jump to first container below (remembers which tab for Up return)
- **Up**: Nothing (Escape to go to sidebar)
- **Left from leftmost**: Go to sidebar
### Container Grid (card tiles on most pages)
- **Arrows**: Spatial nav between containers
- **Enter**: Activate primary action (Install/Launch/navigate) or enter inner controls
- **Escape**: Go to sidebar
- **Left from leftmost**: Go to sidebar
- **Up from top row**: Return to remembered nav bar tab, or spatial to nearest nav item
### Inside Container (inner buttons after Enter)
- **Arrows**: Move between inner controls
- **Escape**: Exit back to the container tile
### Text Inputs
- **Up/Down**: Exit field, navigate spatially
- **Enter**: Submit (click adjacent button)
- **Left/Right**: Cursor movement (exit at edges)
### Container-Free Pages (Settings)
- **Right from sidebar**: Focus first button immediately (no 1s poll delay)
- **Up/Down**: Linear navigation through all buttons/toggles
- **Left**: Go to sidebar
- **Escape**: Go to sidebar
---
## Per-Page Mappings
### Home (`/dashboard`)
Container grid. Dashboard info cards.
### My Apps (`/dashboard/apps`)
| # | Element | Type |
|---|---------|------|
| Nav | My Apps / App Store / Services tabs | Nav bar (Left/Right) |
| 1–N | App cards (grid) | Containers — Enter to view details, inner Launch/Stop/Restart buttons |
### App Store / Discover (`/dashboard/discover`)
| # | Element | Type |
|---|---------|------|
| Nav | My Apps / App Store / Services tabs | Nav bar (Left/Right) |
| 1–2 | Sovereignty Stack featured cards | Containers (`glass-card transition-all hover:-translate-y-1`) |
| 3–N | All Applications grid cards | Containers — Enter for details, inner Install/Launch buttons |
### Network (`/dashboard/server`)
| # | Element | Type |
|---|---------|------|
| 1 | Quick Actions card | Single container — Enter to access Restart/Check Tor/View Logs buttons |
| 2 | Local Network card | Container |
| 3 | Web3 card | Container |
| 4 | Network Interfaces card | Container |
| 5 | Tor Services card | Container |
### Mesh (`/dashboard/mesh`)
| # | Element | Type |
|---|---------|------|
| 1 | Device status card | Container (left column) |
| 2 | Actions row (Enable/Broadcast/Off-Grid/Refresh) | Container |
| 3 | Peers list card | Container — Enter peer to open chat, inner peer items navigable |
| 4 | Chat panel | Container (right column) — message input + send |
| 5+ | Tool panels (Bitcoin/Dead Man/Map) | Containers |
**Chat flow**: Select peer (Enter) → focus auto-jumps to message input → type → Enter sends.
### Cloud (`/dashboard/cloud`)
Container grid. Folder/file cards.
### Settings (`/dashboard/settings`)
**Container-free page** — linear button navigation, no containers.
| # | Element | Section |
|---|---------|---------|
| 1 | Server Name input + save | Account Info |
| 2 | What's New button | Account Info |
| 3 | Copy DID button | Account Info |
| 4 | Copy Onion Address button | Account Info |
| 5 | Change Password button | Account → opens modal |
| 6 | Enable 2FA / Disable 2FA button | Account |
| 7 | Logout button | Account |
| 8 | Language selector buttons | Interface Mode |
| 9 | Login with Claude button | Claude Auth |
| 10 | Enable All / toggle per-category | AI Data Access |
| 11 | Manage Updates button | System Updates |
| 12 | Webhook URL input | Webhooks |
| 13 | Secret input | Webhooks |
| 14 | Container Crash / Update Available toggles | Webhooks |
| 15 | Disk Space Warning / Backup Complete toggles | Webhooks |
| 16 | Save Configuration / Send Test buttons | Webhooks |
| 17 | Enable Beta Telemetry button | Telemetry |
| 18 | Create Backup button | Backup |
| 19 | Export Channel Backup button | Backup |
| 20 | Network Diagnostics button | Danger Zone |
| 21 | Reboot button | Danger Zone → confirms with modal |
| 22 | Factory Reset button | Danger Zone → confirms with modal |
### Monitoring (`/dashboard/monitoring`)
Container grid. Stats/chart cards.
---
## Focus Memory
| Key | Remembers | Used When |
|-----|-----------|-----------|
| `sidebar` | Last sidebar item | Returning to sidebar via Escape/Left |
| `main` | Last focused container | Re-entering main zone |
| `navBar` | Last focused tab/button | Up from container returns to same tab |
All focus memory is cleared on route change.
## Data Attributes
| Attribute | Purpose |
|-----------|---------|
| `data-controller-zone="main"` | Main content area (on `<main>`) |
| `data-controller-zone="sidebar"` | Sidebar navigation |
| `data-controller-container` | Focusable card/tile (with `tabindex="0"`) |
| `data-controller-install` | Container has an Install button (Enter prioritizes it) |
| `data-controller-launch` | Container has a Launch button (Enter prioritizes it) |
| `data-controller-install-btn` | The actual Install button inside a container |
| `data-controller-launch-btn` | The actual Launch button inside a container |
| `data-controller-ignore` | Skip this element and descendants from navigation |
| `data-controller-focus` | Make non-standard element focusable |
## Implementation
- **File**: `neode-ui/src/composables/useControllerNav.ts`
- **Store**: `neode-ui/src/stores/controller.ts` (tracks active state + gamepad count)
- **Sounds**: `neode-ui/src/composables/useNavSounds.ts` (move/action/back)
- **Spatial nav**: `findNearestInDirection()` — filters by direction, scores by overlap + distance
docs/LICENSE-COMPLIANCE-AUDIT.md
+155
View File
@@ -0,0 +1,155 @@
# License Compliance Audit — Open-Source Release
Audit date: 2026-07-22. Scope: entire repo (core Rust workspace, neode-ui, apps/*, Android companion, image-recipe ISO, docker/, app-catalog, reticulum-daemon, demo/) plus the external FIPS source and registry-mirrored images.
**Verdict (as of the 2026-07-22 audit):** the dependency graph is almost entirely permissive (MIT/Apache/BSD) and compatible with a free open-source release. But the repo was not releasable as-is: it had **no license of its own**, one **LGPL Rust dependency**, several **non-redistributable committed assets** (proprietary fonts, unknown-rights media), and **missing attribution machinery**. Everything below is ordered by severity.
> **Updated 2026-08-08.** §1 (no license) and §3 (non-redistributable committed
> files) are now **closed** — root `LICENSE` (MIT) + `NOTICE` are in the tree, and
> the proprietary fonts and unused packages have actually been deleted. **§2
> (`zbase32`, LGPL-3.0+) is now closed too** — replaced by an in-tree
> implementation. No copyleft dependency remains in the Rust graph.
---
## STATUS UPDATE — 2026-07-23
**DONE:**
- MIT adopted. Root `LICENSE` + `NOTICE` added; `license = "MIT"` in all 5 workspace crates (archy-fips-core already had it); `"license": "MIT"` (+ `"private": true`) in all 4 package.json files.
- Deleted: `Courier_New/`, `Benton_Sans/`, `Redacted/` fonts; `wireguard.apk`;
`atob.s9pk`.
**History note (2026-08-08):** this line originally claimed all of these plus
`test-install.sh` were "git-rm'd" on 2026-07-23. They were not — only the
`web/dist` copies had been removed, and all seven sources were still tracked at
HEAD nearly three weeks later. The six listed above were actually deleted on
2026-08-08 (`neode-ui/test-install.sh` was left; it is not a licensing
concern). Kept as a reminder that a DONE entry here is a claim, not evidence —
re-verify with:
```
git ls-tree -r HEAD --name-only | grep -iE 'Courier_New|Benton_Sans|Redacted/|wireguard.apk|atob.s9pk'
```
Deletion was safe: no `@font-face` rule ever referenced them (all four in the
tree load Montserrat), the `Courier New` hits in `tailwind.config.js` and two
public HTML files are `font-family` fallbacks naming the *system* font, and
`wireguard.apk` / `atob.s9pk` had zero references anywhere. Montserrat (OFL.txt)
and Open Sans (LICENSE.txt) remain, as does the actively-used
`archipelago-companion.apk`. Removing the two packages also took ~40 MB off
the frontend OTA tarball.
- Media provenance resolved: all demo music/photos/posters, UI sfx, backgrounds, and intro video are the author's original work — recorded in `demo/content/README.md` and `NOTICE`.
- Meshtastic device artwork attributed (`mesh-devices/ATTRIBUTION.md` + NOTICE); icon attribution added (`assets/icon/ATTRIBUTION.md`: game-icons.net CC BY 3.0, pixelarticons MIT).
- Reticulum decision: include + disclose (NOTICE states the Reticulum License restrictions and that it applies only to the optional daemon).
- indeedhub: deferred — partnership in place; license the submodule before/at public release.
- License inventories generated: `core/THIRD-PARTY-LICENSES.md` (649 crates) and `neode-ui/THIRD-PARTY-LICENSES.md` (runtime deps + fonts + vendored).
**REMAINING (code changes, awaiting review — see sections below for detail):**
1. ~~Replace `zbase32` (LGPL-3.0+) with `z32` or original impl~~ — **DONE 2026-08-08**, original impl (§2).
2. Swap `redis:7.4.8` → Valkey in `scripts/image-versions.sh` and deploys — §3.
3. Delete dead StartOS-derived crates `core/{js-engine,container-init,models,helpers}` — §4.
4. Attribution build integration: cargo-about in CI → ship full license texts in ISO; vite/rollup license plugin (or UI licenses page) for the web bundle; Android OSS-licenses screen — §5.
5. Release-checklist items: per-release Debian source pointer (snapshot.debian.org), catalog `license`/`sourceUrl` fields, restrict ISO image bundling to the audited list — §6.
6. ~~Before repo goes public: purge deleted fonts/APKs from git history (`git filter-repo`)~~ — **superseded**: the launch plan is a fresh-history publish, so there is no history to rewrite. What still applies is verifying the game-icons author credit, and actually deleting the files (see the correction above — they were never removed).
**Re-verified 2026-08-08:**
- ~~`zbase32 0.1.2` (LGPL-3.0+) is still a direct dependency.~~ **Removed 2026-08-08** — see §2.
- `LICENSE` (MIT) and `NOTICE` are present ✅. `core/THIRD-PARTY-LICENSES.md` and `neode-ui/THIRD-PARTY-LICENSES.md` are present ✅.
- The four StartOS-derived crates in item 3 (`core/{js-engine,container-init,models,helpers}`) **still exist** — note KEY-05 legitimately cites `core/models`, so that one needs a look before deletion rather than a blind `rm`.
---
## 1. BLOCKER — the project has no license ✅ CLOSED
_Resolved: MIT adopted, root `LICENSE` + `NOTICE` present. Original finding below._
There is no `LICENSE`/`COPYING` file anywhere in the repo. No crate in `core/` declares a `license` field; none of the four `package.json` files do either (and the three `apps/*` packages aren't even `private: true`). Until fixed, the code is "all rights reserved" — publicly visible, but legally not open source and not usable by anyone.
**Do:**
- [ ] Choose a license. **Recommendation: MIT** — the Bitcoin-ecosystem norm (Bitcoin Core, LND are MIT), maximally compatible with everything found in the graph. (Alternatives: Apache-2.0 adds a patent grant; GPLv3 if copyleft is desired — nothing in the deps prevents any of these.)
- [ ] Add `LICENSE` at repo root with the year and copyright holder.
- [ ] Add `license = "MIT"` to all five workspace member `Cargo.toml`s (archipelago, container, openwrt, performance, security) and `Android/rust/archy-fips-core` (declares MIT but ships no license file — add one).
- [ ] Add `"license": "MIT"` to `neode-ui/package.json` and `apps/{morphos-server,router,did-wallet}/package.json`.
## 2. BLOCKER — copyleft dependency that must be replaced ✅ CLOSED 2026-08-08
- [x] **`zbase32 0.1.2` — LGPL-3.0+** — was the only hard copyleft blocker in all 649 resolved Rust crates. Direct dep of `archipelago`, used in `core/archipelago/src/network/did_dht.rs` for did:dht z-base-32 encoding. LGPL statically linked into a Rust binary requires shipping relinkable objects/source — impractical.
**DONE 2026-08-08.** Replaced with an original in-tree implementation at
`core/archipelago/src/network/zbase32.rs` (~60 lines incl. docs) rather than
the `z32` crate — the encoding is an alphabet substitution over a bit stream,
so this removes the blocker without adding any dependency or new supply-chain
surface. Dropped from `Cargo.toml` and `Cargo.lock`.
Byte-compatibility was the hard requirement: a `did:dht` identifier *is* this
encoding of an Ed25519 public key, so any drift would silently rotate every
node's DID and orphan its published DHT records. The replacement is pinned
against the removed crate's own three doc-test vectors, the canonical vectors
from Zimmermann's z-base-32 spec, and four known 32-byte keys — plus a
`did_for_a_known_key_is_stable` test at the `did_dht.rs` call site.
No GPL, AGPL, SSPL, or unlicensed crates exist anywhere else in the Rust graph. (`r-efi` and `self_cell` list LGPL/GPL only as options in OR-expressions — elect MIT/Apache, no action.)
## 3. BLOCKER — committed files we may not redistribute ◐ fonts/packages CLOSED 2026-08-08; media + redis items still open
Remove from git (history purge is **moot** — the launch plan is a fresh-history publish, so past commits are not carried over):
- [x] `neode-ui/public/assets/fonts/Courier_New/` — Monotype proprietary font, no license, **unused in CSS**. ~~Delete.~~ **DELETED 2026-08-08.**
- [x] `neode-ui/public/assets/fonts/Benton_Sans/BentonSans-Regular.otf` — commercial Font Bureau typeface, no license, unused. ~~Delete.~~ **DELETED 2026-08-08.**
- [x] `neode-ui/public/packages/wireguard.apk` (17 MB) — **DELETED 2026-08-08.** — official WireGuard Android APK containing GPL-2.0 `libwg` components; redistribution triggers GPL source-offer. **Unreferenced since the FIPS migration** — delete.
- [x] `neode-ui/public/packages/atob.s9pk` (24 MB) — **DELETED 2026-08-08.** — Start9 service package, unknown license, referenced only by a test script. Delete.
- [ ] `demo/content/music/` (18 full tracks, ~150 MB) and `demo/peer-media/` (17 photos/book covers/film posters) — no recorded rights. If they're your own/AI-generated work, document that in a `demo/content/README`; otherwise remove.
- [ ] `neode-ui/public/assets/video/video-intro.mp4`, `Kratter.MP3`, photographic `bg-*.jpg` backgrounds, UI/arcade sound effects in `assets/audio/` — same: document provenance (user-made per project convention) or replace. `welcome-noderunner.mp3` is ElevenLabs TTS — their commercial-use terms allow this on paid plans; note it.
- [ ] **Registry: `redis:7.4.8`** (`scripts/image-versions.sh` `REDIS_IMAGE`) — Redis ≥ 7.4 is RSALv2/SSPLv1, **not open source**; re-hosting it on your registry is redistribution under a restricted license. **Switch to Valkey** (BSD-3, already mirrored) everywhere.
## 4. VERIFY — unknown/third-party provenance
- [ ] **`neode-ui/public/assets/img/mesh-devices/` (36 SVGs)** — almost certainly Meshtastic project device artwork (meshtastic/web is GPL-3.0). Confirm source; either replace with original art or comply with the upstream license + attribution.
- [ ] **`neode-ui/public/assets/icon/`** — `barbarian.svg`, `batteries.svg` match game-icons.net (**CC BY 3.0 — visible attribution required**); pixel-style icons match pixelarticons (MIT). Confirm and add attribution, or replace.
- [x] `Redacted/redacted.regular.ttf` — upstream is SIL OFL 1.1 but no license file is shipped. ~~Add `OFL.txt` or delete (unused).~~ **DELETED 2026-08-08** (unused; deleting was cheaper than sourcing the OFL text).
- [ ] **indeedhub** — submodule (private gitea) not checked out; no known license, yet `indeedhub{,-api,-ffmpeg}:1.0.0` images are distributed via registry/ISO. `indeedhub-ffmpeg` implies a bundled FFmpeg (LGPL/GPL → source-offer obligations). Must license the project and audit the ffmpeg build before public release.
- [ ] `minmoto/fmcd` v0.8.0 and `ark-bitcoin/bark` (barkd) — binaries redistributed in your images; verify upstream licenses (bark claims Apache-2.0/MIT dual) and include their notices.
- [ ] **Start9/StartOS heritage** — `core/{js-engine,container-init,models,helpers}` are StartOS-derived (embassy paths, s9pk handling). start-os is MIT → attribution required if kept. **Better: delete these four crates** — they are not workspace members, cannot compile (broken `../../patch-db` path dep), and carry an unpinned `yajrc = "*"` git dep on a moving branch. Deleting removes both the attribution question and dead code.
- [ ] **Reticulum (RNS 1.3.5 + LXMF)** — verified: custom "Reticulum License" — MIT-style **plus field-of-use restrictions** (no systems designed to harm humans; no AI/ML training-dataset use). Redistribution is permitted, so shipping the PyInstaller `archy-reticulum-daemon` binary is fine **if** the license text is included with it — but the OS cannot claim to be 100 % OSI-open-source while bundling it. Options: include + disclose (recommended, matches "plan for decentralization" honesty), or make the daemon an optional download.
## 5. REQUIRED — attribution / notice machinery (currently absent)
Nearly every permissive license (MIT/BSD/ISC/Apache) requires reproducing copyright + license text **in distributed binaries** — and right now every distribution channel strips them:
- [ ] **Rust binaries** (649 crates, ~85 % MIT/Apache dual): generate `THIRD-PARTY-LICENSES` with `cargo-about` (or `cargo-license`) in CI; ship it in the ISO at e.g. `/usr/share/doc/archipelago/`. Include **ring's three license files** (LICENSE, LICENSE-BoringSSL, LICENSE-other-bits) and note the system OpenSSL (Apache-2.0) linked via `ssh2`.
- [ ] **Web bundle**: Vite/esbuild strips all `@license` comments from `web/dist`. Add `rollup-plugin-license`/`vite-plugin-license` to emit a third-party attribution file, or add an "Open-source licenses" page in the UI. Runtime deps needing notices: vue/vue-router/pinia/vue-i18n (MIT), d3 (ISC), leaflet (BSD-2), dompurify (elect Apache-2.0 of its MPL/Apache dual), fuse.js (Apache-2.0), qrcode/qr-scanner/qrloop/buffer/fast-json-patch (MIT).
- [ ] **Android APK**: `packaging.excludes` strips `META-INF` license texts and there is no licenses screen. Add an OSS-licenses screen or bundled `licenses.txt` covering AndroidX/Compose/OkHttp/ZXing (Apache-2.0), **fips © 2026 Johnathan Corgan (MIT — the core of the VPN feature)**, tokio/tracing (MIT), subtle (BSD-3), tun (WTFPL — permissive, just list it), secp256k1 family (CC0). Generate the Rust side from the committed `Cargo.lock` with cargo-about.
- [ ] **AIUI demo bundle** (`demo/aiui/` — committed minified build): bundles Mermaid, Cytoscape, KaTeX, D3, Lodash, Workbox (all MIT/BSD). Add a `THIRD-PARTY-LICENSES` file next to it (or rebuild with a license plugin).
- [ ] Keep the intact MIT headers in the two vendored `qrcode.js` copies (docker/lnd-ui, docker/electrs-ui) — already compliant, don't minify them.
- [ ] Fonts kept: Montserrat (OFL.txt present ✓), Open Sans (Apache LICENSE.txt present ✓) — keep license files adjacent to the font files in dist.
## 6. REQUIRED — distribution-level obligations (ISO & registry)
The ISO redistributes a full Debian (trixie) system plus ~29 container image tarballs; the private registry re-hosts upstream images. Re-hosting = redistribution, same obligations as bundling.
- [ ] **GPL source offer for the ISO** — kernel, GRUB, busybox/live-boot, coreutils, nftables, cryptsetup, wireguard-tools, SYSLINUX `isohdpfx.bin`, etc. Easiest compliance: keep `/usr/share/doc/*/copyright` (the build already does ✓) **and** publish, per release, either a mirror of the exact Debian source packages (`apt-get source` snapshot / snapshot.debian.org pointer) or a written offer in the docs. Add this to the release checklist.
- [ ] **AGPLv3 images redistributed** (mempool, Grafana, Vaultwarden, SearXNG, PhotoPrism, Nextcloud, Immich, CryptPad, MinIO): AGPL compliance = make corresponding source available. You ship a **modified** mempool-frontend (`docker/mempool-frontend` entrypoint patch) — the patch is in-repo, so compliance is met once the repo is public; state this in docs. For unmodified images, link upstream sources in the app catalog.
- [ ] **GPLv2/GPLv3 images** (MariaDB, Jellyfin, AdGuard Home, strfry): unmodified redistribution → provide license text + upstream source links (a `license` + `sourceUrl` field per `app-catalog/catalog.json` entry solves this catalog-wide).
- [ ] **Non-free firmware** (firmware-realtek/iwlwifi/misc/linux-nonfree, intel/amd microcode): redistributable but proprietary — disclose in docs ("includes non-free firmware for hardware support"), like Debian's own non-free-firmware ISOs do.
- [ ] The ISO build's live-server image capture (`podman save` of whatever matches on the dev server) is a compliance hazard — bundle only from the audited image list.
- [ ] FIPS daemon (jmcorgan/fips v0.4.1, MIT ✓) and nostr-rs-relay binary (MIT ✓): include their license texts in the notices bundle.
## 7. Housekeeping (supports compliance)
- [ ] Add lockfiles + pinned versions in `apps/*` (currently floating `^` ranges, violating the project's own pinning rule) — reproducibility is also what makes license audits stay true.
- [ ] `Android` fips dep is pinned to a personal fork rev (`9qeklajc/fips-native@46494a74`) — mirror or vendor it so outside contributors can build.
- [ ] Move `@types/dompurify` to devDeps; refresh stale `neode-ui/node_modules`.
- [ ] Add a `NOTICE` file at root naming: fips (Johnathan Corgan, MIT), Start9 start-os (if any derived code remains), Kazuhiko Arase qrcode.js, font licenses, icon attributions.
- [ ] Consider CI license gating: `cargo-deny` (Rust) + `license-checker` (npm) with an allowlist, so new copyleft deps are caught at PR time.
---
## Quick reference: what's already clean
- All Rust crates: permissive or dual-licensed (`zbase32` was the sole exception and is gone as of 2026-08-08).
- All 833 npm packages in neode-ui: no GPL/AGPL anywhere; only dev-tool LGPL (sharp's libvips, never distributed).
- Android Gradle deps: 100 % Apache-2.0, all pinned, no Play Services/telemetry.
- FIPS mesh: MIT (© 2026 Johnathan Corgan) — keep notice.
- js-engine binds deno_core (MIT) as a crate, nothing vendored — moot if dead crates are deleted.
- reticulum-daemon Python is original code; obligations attach only to the PyInstaller binary (see §4).
- Bitcoin Core/Knots, LND, BTCPay, Electrs, Fedimint, core-lightning, Gitea, Home Assistant, Tailscale, Portainer, Uptime-Kuma, filebrowser, ollama, penpot: MIT/Apache/BSD/Zlib/MPL — link + notice is enough.
docs/README.md
+89
View File
@@ -0,0 +1,89 @@
# 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](user-walkthrough.md) — setting up and using a node, from hardware to daily use
- [Talking to your node](COMMANDS.md) — the conversational command surface
- [Seed Verification](SEED-VERIFICATION.md) — independently verify your 24-word backup
- [Troubleshooting](troubleshooting.md) — common problems and how to resolve them
- [Gamepad / Controller Navigation](GAMEPAD-NAV.md) — driving the UI from a controller
- [Pine voice commands](pine-voice-commands.md) — the voice-satellite phrase surface
## Architecture
- [Architecture](architecture.md) — the system at a glance
- [Multi-Node Architecture](multi-node-architecture.md) — how nodes relate across a fleet
- [API Reference](api-reference.md) — the JSON-RPC surface
## Contributing to Archipelago itself
- [Developer Guide](developer-guide.md) — building the workspace, the frontend, and an ISO
- [Contributor guide (`CLAUDE.md`)](../CLAUDE.md) — invariants, build/verify, the production test gate
- [Bulletproof containers](bulletproof-containers.md) — why the reconciler is level-triggered
- [Release signing runbook](workstream-b-signing-runbook.md) — the ceremony and key handling
- [1.8.0 Release Hardening Plan](1.8.0-RELEASE-HARDENING-PLAN.md) — the release-blocking checklist
- [Third-party license audit](LICENSE-COMPLIANCE-AUDIT.md) — dependency licensing posture
- [Demo build info](demo-build-info.md) — operating the public demo sandbox
## App development
- [App Developer Guide](app-developer-guide.md) — build and package a containerized app
- [App Manifest Specification](app-manifest-spec.md) — the manifest schema, field by field
- [Manifest → Quadlet unit](quadlet-compilation.md) — how a manifest compiles to a systemd-owned container unit
- [Container lifecycle](container-lifecycle.md) — the reconciler state machine: install/adopt/start/stop/self-heal
- [App secrets](secrets.md) — declaring, generating and injecting per-install credentials
- [Registry-Distributed Manifests](registry-manifest-design.md) — how manifests reach nodes via the signed catalog
- [Decentralized Marketplace Protocol](marketplace-protocol.md) — publishing apps via an external registry
- [Bitcoin RPC Relay](bitcoin-rpc-relay.md) — letting an external wallet reach the node's Bitcoin RPC
- [Companion Pairing QR](companion-pairing-qr.md) — the pairing handoff contract
- [TV input inside iframe apps](tv-input-iframe-apps.md) — 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](registry-manifest-design.md)
- [DHT Distribution](dht-distribution-design.md)
- [Bitcoin Multi-Version](bitcoin-multi-version-design.md)
- [Dual Ecash](dual-ecash-design.md)
- [Hardware Signer](hardware-signer-design.md)
- [Manifest Hooks](manifest-hooks-design.md)
- [Meshroller Integration](meshroller-integration-design.md)
- [Nostr Git Source Hosting](nostr-git-source-hosting.md)
- [Nostr Identity Import](nostr-identity-import-plan.md) · [Nostr Signer Login (research)](nostr-signer-login-research.md)
- [Streaming Ecash (phase 4)](phase4-streaming-ecash-plan.md)
- [App Packaging Migration](APP-PACKAGING-MIGRATION-PLAN.md)
## Decisions (ADRs)
- [ADR-001: Podman over Docker](adr/001-podman-over-docker.md)
- [ADR-002: DID Key Method for Node Identity](adr/002-did-key-method.md)
- [ADR-003: Nostr Relays for Discovery](adr/003-nostr-for-discovery.md)
- [ADR-004: Tor Hidden Services for Peer Communication](adr/004-tor-for-peer-communication.md)
- [ADR-005: ChaCha20-Poly1305 for Backup Encryption](adr/005-chacha20-backup-encryption.md)
- [ADR-006: Nostr Relays for Marketplace Discovery](adr/006-nostr-marketplace-discovery.md)
- [ADR-007: DID-Based Federation Trust](adr/007-did-federation-trust.md)
- [ADR-008: Dual Key Strategy (Ed25519 + Secp256k1)](adr/008-dual-key-strategy.md)
- [ADR-009: Manifest-Level Container Security](adr/009-manifest-container-security.md)
- [ADR-011: DWN Deprioritization](adr/011-dwn-deprioritization.md)
There is no ADR-010 — the number was never issued, so the gap is not a missing
file.
## Security
- [Security Policy](../SECURITY.md) — how to report a vulnerability
- [PSBT Signing Architecture](security/PSBT-SIGNING-ARCHITECTURE.md)
- [Bitcoin RPC Proxy Exposure](security/BITCOIN-RPC-PROXY-EXPOSURE.md)
- [Entropy Enforcement (KEY-05)](security/KEY-05-ENTROPY-ENFORCEMENT.md)
## Roadmap & history
- [Roadmap](ROADMAP.md) — where the project is going
- [archive/](archive/README.md) — superseded design and status documents, kept for provenance
docs/RELEASE_NOTES_BACKLOG.md
+15
View File
@@ -0,0 +1,15 @@
# Release Notes Backlog
## Next Release Required Work
- Backfill missing or thin historical release notes before cutting the next release.
- Audit every `CHANGELOG.md` section from `v1.7.44-alpha` through the current release.
- Replace raw commit-hash entries with user/operator-facing bullets that explain behavior changes, operational impact, validation, and known limitations.
- Ensure `releases/manifest.json` changelog entries come from curated `CHANGELOG.md` notes only.
## Release Note Policy
- Every release must have at least three curated bullets.
- Raw `git log --oneline` output is not acceptable release documentation.
- Notes should answer what changed, why it matters, what operators should expect, and any known limitations.
- `scripts/check-release-manifest.sh` is the enforcement gate before publishing artifacts.
docs/ROADMAP.md
+95
View File
@@ -0,0 +1,95 @@
# Archipelago Roadmap
_Last updated: 2026-07-08. This is the public-facing summary. The live,
open engineering work is tracked in the public issue tracker._
## North star
A world-class, **developer-ready app platform**: every app manifest-driven,
manifests distributed via a **signed registry**, and third-party developers
publishing through an **external/decentralized marketplace** — all rootless,
secure, robust, and 100%-uptime-capable.
Five pillars every app must satisfy: Quadlet-everywhere · level-triggered
reconciler · lifecycle-bulletproof (full test matrix, repeatedly green) ·
data-driven (no host changes, no per-app binary code) · rootless +
security-first.
## ✅ Shipped
- **Single-node production gate GREEN** (2026-06-23) — the full destructive
lifecycle matrix (install / UI / stop / start / restart / reinstall /
reboot-survive / backend-restart-survive / uninstall) passed 5 consecutive
times with zero failures on real hardware. This was the first exit criterion.
- **Manifest-driven app platform** — 50+ apps as declarative manifests; all
multi-container stacks (BTCPay, Mempool, Immich, NetBird, IndeeHub) install
through the orchestrator; generated-secrets system replaces per-app secret code.
- **Rust orchestrator + level-triggered reconciler** — the bash-script era is
retired; drift self-heals on a 30-second loop.
- **Registry-distributed manifests** — the signed catalog embeds full manifests
per app; nodes verify against the pinned release-root key and overlay
catalog manifests over disk files (catalog wins).
- **Release signing ceremony** (2026-07-02) — release-root Ed25519 key pinned
in the binary; OTA release manifests and the app catalog are signed;
auto-apply refuses unsigned manifests.
- **1.8.0 hardening batches** — supply-chain signature verification, deepened
post-OTA health checks, async-executor and secret-handling fixes, browser
origin checks, dist shrink.
- **Reticulum third mesh transport** — RNS/LXMF over real LoRa hardware
(RNode), interop verified against Sideband; joins Meshtastic and MeshCore
behind one chat UI with X3DH + double-ratchet E2E, attachments, and mesh AI.
- **Bitcoin multi-version** — Core and Knots with per-app version pinning and
safe switching (fleet rollout pending below).
- **Decentralized marketplace backend** — Nostr NIP-78 discovery, DID-signed
manifests, federation-weighted trust scoring, Lightning purchase invoices.
- **Quadlet migration validated** — all backends run as `user.slice` Quadlet
services on the canary node (default flip pending below).
- **Public demo** — multi-visitor sandbox deployed.
## 🔄 In progress
- **Multinode pass** — run the same production gate across the whole test
fleet, plus cross-node federation/mesh suites. This is the current exit
criterion.
- **Quadlet default flip** — flip the validated Quadlet path from opt-in to
default fleet-wide; eliminates the last container-flapping root cause.
- **Container-flapping elimination** — reconciler churn and failed-unit
self-healing gaps observed on live nodes.
- **Reticulum tail** — ship the daemon binary inside the release tarball;
final fleet redeploys.
## ⏳ Release-blocking for 1.8.0
Tracked in detail in [`1.8.0-RELEASE-HARDENING-PLAN.md`](1.8.0-RELEASE-HARDENING-PLAN.md):
- **OTA upgrade-from-previous-version soak** on real hardware — the top
untested release risk.
- **ISO/image hardening** — per-device TLS/SSH keys on first boot, remove
default credentials and SSH password auth, signed + checksummed ISO,
registries over HTTPS, unattended-upgrades and firewall defaults.
- **Bitcoin multi-version fleet OTA** — code done; rollout timing is a
deliberate hold.
- Version bump to `1.8.0-alpha` + tag once the pre-tag items close.
## 🔭 Planned (post-1.8.0)
- **Developer CLI** — `archy app validate / render / install / test`; the gate
for opening third-party app publishing.
- **External marketplace maturation** — publishing tooling, trust UX, and
reputation surfaces on top of the shipped backend
([`marketplace-protocol.md`](marketplace-protocol.md)).
- **DHT/P2P distribution** — releases and app images over iroh-based swarm
([`dht-distribution-design.md`](dht-distribution-design.md); feature-gated
skeleton exists).
- **P2P encrypted voice/video** over Tor between federated nodes.
- **Dual ecash** — Fedimint + Cashu phases 2–6, networking-sats
([`dual-ecash-design.md`](dual-ecash-design.md)).
- **Paid streaming** — streaming ecash for content
([`phase4-streaming-ecash-plan.md`](phase4-streaming-ecash-plan.md)).
- **Hardware signer** support ([`hardware-signer-design.md`](hardware-signer-design.md)).
- **Code health** — split god-modules, remove dead crates, route all
podman/systemctl calls through the wrapper.
## Release pipeline
Feature Testing (internal) → User Testing (controlled hardware) → Beta Live (public).
docs/SEED-VERIFICATION.md
+462
View File
@@ -0,0 +1,462 @@
# Archipelago Seed Verification
Independently verify that your 24-word BIP-39 mnemonic produces the correct
Nostr keys and DID identifiers — using only standard cryptographic primitives,
no Archipelago code.
```
24-word mnemonic
|
v
PBKDF2-HMAC-SHA512 (2048 rounds, salt = "mnemonic")
|
v
64-byte master seed
|
+-- HKDF-SHA256 (info="archipelago/node/ed25519/v1")
| --> Node Ed25519 keypair --> did:key:z...
|
+-- HKDF-SHA256 (info="archipelago/nostr-node/secp256k1/v1")
| --> Node Nostr key --> npub1...
|
+-- HKDF-SHA256 (info="archipelago/fips/secp256k1/v1")
| --> FIPS mesh transport key --> npub1...
|
+-- HKDF-SHA256 (info="archipelago/identity/{i}/ed25519/v1")
| --> Identity[i] Ed25519 --> did:key:z...
|
+-- BIP-32 m/44'/1237'/0'/0/{i} (NIP-06)
| --> Identity[i] Nostr key --> npub1...
|
+-- BIP-32 m/84'/0'/0'
| --> Bitcoin HD wallet
|
+-- HKDF-SHA256 (info="archipelago/lnd/entropy/v1")
--> 16 bytes LND aezeed entropy
```
Source: [`core/archipelago/src/seed.rs`](../core/archipelago/src/seed.rs) and
[`core/archipelago/src/identity.rs`](../core/archipelago/src/identity.rs)
---
## Setup
```bash
pip3 install cryptography ecdsa
```
Two packages, both pure crypto, no network calls. Python 3.9+.
---
## The Verification Script
Save as `verify-seed.py` and run with your mnemonic:
```bash
MNEMONIC="word1 word2 ... word24" python3 verify-seed.py
```
```python
#!/usr/bin/env python3
"""
Archipelago seed derivation verifier.
Re-derives every key from a BIP-39 mnemonic using the exact same algorithms
as the Rust backend (seed.rs), so you can compare outputs independently.
Dependencies: cryptography, ecdsa (pip3 install cryptography ecdsa)
No network calls. No file writes. Safe to run air-gapped.
"""
import hashlib, hmac, os, sys
# ── BIP-39: mnemonic --> 64-byte master seed ─────────────────────────────
def mnemonic_to_seed(mnemonic: str) -> bytes:
"""PBKDF2-HMAC-SHA512, 2048 rounds, salt = 'mnemonic', no passphrase."""
return hashlib.pbkdf2_hmac(
"sha512",
mnemonic.encode("utf-8"),
b"mnemonic", # BIP-39 salt prefix + empty passphrase
2048,
)
# ── HKDF-SHA256 (RFC 5869) ──────────────────────────────────────────────
def hkdf_sha256(ikm: bytes, info: bytes, length: int = 32) -> bytes:
"""
HKDF-Extract(salt=None, ikm) then HKDF-Expand(PRK, info, L).
Salt=None means 32 zero bytes per RFC 5869 section 2.2.
Matches: hkdf::Hkdf::<Sha256>::new(None, ikm).expand(info, &mut okm)
"""
# Extract
prk = hmac.new(b"\x00" * 32, ikm, hashlib.sha256).digest()
# Expand (32 bytes = 1 block, only T(1) needed)
t1 = hmac.new(prk, info + b"\x01", hashlib.sha256).digest()
return t1[:length]
# ── Ed25519 ──────────────────────────────────────────────────────────────
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
def ed25519_keypair(secret_32: bytes) -> tuple[bytes, bytes]:
"""Returns (private_32, public_32) from a 32-byte seed."""
sk = Ed25519PrivateKey.from_private_bytes(secret_32)
pk = sk.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw)
return secret_32, pk
# ── secp256k1 ────────────────────────────────────────────────────────────
from ecdsa import SECP256k1, SigningKey as ECDSASigningKey
def secp256k1_xonly(secret_32: bytes) -> bytes:
"""32-byte x-only pubkey (Schnorr/Nostr format) from private key bytes."""
sk = ECDSASigningKey.from_string(secret_32, curve=SECP256k1)
point = sk.get_verifying_key().pubkey.point
return point.x().to_bytes(32, "big")
# ── BIP-32 HD derivation (secp256k1) ────────────────────────────────────
import struct
SECP256K1_N = SECP256k1.order
def _bip32_master(seed: bytes) -> tuple[bytes, bytes]:
"""BIP-32 master key: HMAC-SHA512(key='Bitcoin seed', data=seed)."""
I = hmac.new(b"Bitcoin seed", seed, hashlib.sha512).digest()
return I[:32], I[32:] # (secret, chain_code)
def _bip32_ckd(key: bytes, chain: bytes, index: int) -> tuple[bytes, bytes]:
"""Child key derivation (private -> private)."""
if index >= 0x80000000:
data = b"\x00" + key + struct.pack(">I", index)
else:
# Compressed pubkey for non-hardened
sk = ECDSASigningKey.from_string(key, curve=SECP256k1)
pt = sk.get_verifying_key().pubkey.point
prefix = b"\x02" if pt.y() % 2 == 0 else b"\x03"
data = prefix + pt.x().to_bytes(32, "big") + struct.pack(">I", index)
I = hmac.new(chain, data, hashlib.sha512).digest()
child = (int.from_bytes(I[:32], "big") + int.from_bytes(key, "big")) % SECP256K1_N
return child.to_bytes(32, "big"), I[32:]
def bip32_derive(seed: bytes, path: str) -> bytes:
"""
Derive private key for a BIP-32 path like 'm/44h/1237h/0h/0/0'.
Matches: bitcoin::bip32::Xpriv::new_master + derive_priv
"""
key, chain = _bip32_master(seed)
for part in path.lstrip("m/").split("/"):
hardened = part.endswith("'") or part.endswith("h")
idx = int(part.rstrip("'h"))
if hardened:
idx += 0x80000000
key, chain = _bip32_ckd(key, chain, idx)
return key
# ── Bech32 encoding (NIP-19: npub / nsec) ───────────────────────────────
_BECH32 = "qpzry9x8gf2tvdw0s3jn54khce6mua7l"
def _bech32_polymod(values):
GEN = [0x3B6A57B2, 0x26508E6D, 0x1EA119FA, 0x3D4233DD, 0x2A1462B3]
chk = 1
for v in values:
b = chk >> 25
chk = ((chk & 0x1FFFFFF) << 5) ^ v
for i in range(5):
chk ^= GEN[i] if ((b >> i) & 1) else 0
return chk
def bech32_encode(hrp: str, data: bytes) -> str:
"""Bech32 encode (NIP-19 for npub1.../nsec1...)."""
# Convert 8-bit to 5-bit
acc, bits, vals = 0, 0, []
for byte in data:
acc = (acc << 8) | byte
bits += 8
while bits >= 5:
bits -= 5
vals.append((acc >> bits) & 31)
if bits:
vals.append((acc << (5 - bits)) & 31)
# Checksum
hrp_exp = [ord(c) >> 5 for c in hrp] + [0] + [ord(c) & 31 for c in hrp]
polymod = _bech32_polymod(hrp_exp + vals + [0]*6) ^ 1
checksum = [(polymod >> 5*(5-i)) & 31 for i in range(6)]
return hrp + "1" + "".join(_BECH32[d] for d in vals + checksum)
# ── did:key encoding ────────────────────────────────────────────────────
_B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
def base58_encode(data: bytes) -> str:
n = int.from_bytes(data, "big")
result = ""
while n > 0:
n, r = divmod(n, 58)
result = _B58[r] + result
for b in data:
if b == 0:
result = "1" + result
else:
break
return result
def to_did_key(ed25519_pub_32: bytes) -> str:
"""did:key:z<base58btc(0xed01 + pubkey)> — W3C did:key method, Ed25519."""
return "did:key:z" + base58_encode(b"\xed\x01" + ed25519_pub_32)
# ── Main ─────────────────────────────────────────────────────────────────
def main():
mnemonic = os.environ.get("MNEMONIC", "").strip()
if not mnemonic:
print("Enter your 24-word mnemonic (space-separated):")
mnemonic = input("> ").strip()
words = mnemonic.split()
if len(words) != 24:
print(f"Error: expected 24 words, got {len(words)}", file=sys.stderr)
sys.exit(1)
seed = mnemonic_to_seed(mnemonic)
W = 72
print()
print("=" * W)
print(" ARCHIPELAGO SEED DERIVATION VERIFICATION")
print("=" * W)
print()
print(f" Seed fingerprint (SHA-256): {hashlib.sha256(seed).hexdigest()[:16]}...")
print(f" Seed length: {len(seed)} bytes")
# ── 1. Node Ed25519 + DID ────────────────────────────────────────────
print()
print("-" * W)
print(" 1. NODE ED25519 KEY")
print(f" HKDF-SHA256(seed, info='archipelago/node/ed25519/v1')")
print("-" * W)
node_ed_priv, node_ed_pub = ed25519_keypair(
hkdf_sha256(seed, b"archipelago/node/ed25519/v1")
)
node_did = to_did_key(node_ed_pub)
print(f" Private: {node_ed_priv.hex()}")
print(f" Public: {node_ed_pub.hex()}")
print(f" did:key: {node_did}")
# ── 2. Node Nostr key ────────────────────────────────────────────────
print()
print("-" * W)
print(" 2. NODE NOSTR KEY")
print(f" HKDF-SHA256(seed, info='archipelago/nostr-node/secp256k1/v1')")
print("-" * W)
node_nostr_priv = hkdf_sha256(seed, b"archipelago/nostr-node/secp256k1/v1")
node_nostr_pub = secp256k1_xonly(node_nostr_priv)
print(f" Private: {node_nostr_priv.hex()}")
print(f" X-only: {node_nostr_pub.hex()}")
print(f" nsec: {bech32_encode('nsec', node_nostr_priv)}")
print(f" npub: {bech32_encode('npub', node_nostr_pub)}")
# ── 2b. FIPS mesh transport key ─────────────────────────────────────
print()
print("-" * W)
print(" 2b. FIPS MESH TRANSPORT KEY")
print(f" HKDF-SHA256(seed, info='archipelago/fips/secp256k1/v1')")
print("-" * W)
fips_priv = hkdf_sha256(seed, b"archipelago/fips/secp256k1/v1")
fips_pub = secp256k1_xonly(fips_priv)
print(f" X-only: {fips_pub.hex()}")
print(f" npub: {bech32_encode('npub', fips_pub)}")
# ── 3. Identity[0..2] Ed25519 + DID ─────────────────────────────────
print()
print("-" * W)
print(" 3. IDENTITY ED25519 KEYS + DID")
print(f" HKDF-SHA256(seed, info='archipelago/identity/{{i}}/ed25519/v1')")
print("-" * W)
for i in range(3):
info = f"archipelago/identity/{i}/ed25519/v1".encode()
priv, pub = ed25519_keypair(hkdf_sha256(seed, info))
did = to_did_key(pub)
print(f" [{i}] Public: {pub.hex()}")
print(f" did:key: {did}")
# ── 4. Identity[0..2] Nostr (NIP-06 BIP-32) ────────────────────────
print()
print("-" * W)
print(" 4. IDENTITY NOSTR KEYS (NIP-06)")
print(f" BIP-32 m/44'/1237'/0'/0/{{i}}")
print("-" * W)
for i in range(3):
priv = bip32_derive(seed, f"m/44'/1237'/0'/0/{i}")
pub = secp256k1_xonly(priv)
print(f" [{i}] X-only: {pub.hex()}")
print(f" nsec: {bech32_encode('nsec', priv)}")
print(f" npub: {bech32_encode('npub', pub)}")
# ── 5. Bitcoin BIP-84 ───────────────────────────────────────────────
print()
print("-" * W)
print(" 5. BITCOIN WALLET (BIP-84)")
print(f" BIP-32 m/84'/0'/0'")
print("-" * W)
btc_acct = bip32_derive(seed, "m/84'/0'/0'")
btc_pub = secp256k1_xonly(btc_acct)
print(f" Account key: {btc_acct.hex()}")
print(f" Account pub: {btc_pub.hex()}")
# ── 6. LND Entropy ──────────────────────────────────────────────────
print()
print("-" * W)
print(" 6. LND AEZEED ENTROPY")
print(f" HKDF-SHA256(seed, info='archipelago/lnd/entropy/v1') [16 bytes]")
print("-" * W)
lnd = hkdf_sha256(seed, b"archipelago/lnd/entropy/v1", 16)
print(f" Entropy: {lnd.hex()}")
# ── Done ─────────────────────────────────────────────────────────────
print()
print("=" * W)
print(" Compare these values with your Archipelago node:")
print(" SSH: xxd -p /var/lib/archipelago/identity/node_key.pub (section 1)")
print(" cat /var/lib/archipelago/identity/nostr_pubkey (section 2)")
print(" RPC: curl -s -b jar.txt http://<ip>/rpc/v1 \\")
print(" -H 'Content-Type: application/json' \\")
print(" -d '{\"method\":\"node.did\"}' | jq .")
print(" ...and {\"method\":\"node.nostr-pubkey\"} for the npub")
print("=" * W)
print()
if __name__ == "__main__":
main()
```
---
## How to Run
```bash
# Install (two packages, pure crypto, no telemetry)
pip3 install cryptography ecdsa
# Option A: environment variable (doesn't persist in shell history)
read -rs MNEMONIC && export MNEMONIC
# (type or paste your 24 words, press Enter)
python3 verify-seed.py
unset MNEMONIC
# Option B: interactive prompt
python3 verify-seed.py
# Enter your 24-word mnemonic (space-separated):
# > abandon abandon ... art
```
---
## What to Compare
| Output field | Where to find on your node |
|---|---|
| Node Ed25519 public | `xxd -p /var/lib/archipelago/identity/node_key.pub` |
| Node did:key | Settings > Identity > Node DID |
| Node npub | Settings > Identity > Nostr Public Key |
| Identity[0] did:key | Settings > Identity > first identity DID |
| Identity[0] npub | Settings > Identity > first identity Nostr key |
RPC alternative (from any machine on the LAN):
```bash
# Node identity
curl -s http://archipelago.local/api/rpc \
-H 'Content-Type: application/json' \
-d '{"method":"identity.get-node"}' | jq .
# All identities
curl -s http://archipelago.local/api/rpc \
-H 'Content-Type: application/json' \
-d '{"method":"identity.list"}' | jq .
```
---
## Cryptographic Reference
### HKDF-SHA256 (RFC 5869)
Used for Ed25519 and node-level Nostr keys. Domain separation via unique `info` strings
prevents key reuse across contexts.
```
Extract: PRK = HMAC-SHA256(salt=0x00*32, ikm=64_byte_seed)
Expand: OKM = HMAC-SHA256(PRK, info || 0x01) [first 32 bytes]
```
The Rust backend uses `hkdf::Hkdf::<Sha256>::new(None, ikm)` where `None` salt = 32 zero bytes.
### BIP-32 (secp256k1 HD derivation)
Used for per-identity Nostr keys (NIP-06) and Bitcoin wallet.
```
Master: HMAC-SHA512(key="Bitcoin seed", data=64_byte_seed)
Child: HMAC-SHA512(key=chain_code, data=0x00||key||index) [hardened]
HMAC-SHA512(key=chain_code, data=pubkey||index) [normal]
```
The Rust backend uses the `bitcoin` crate: `Xpriv::new_master()` + `derive_priv()`.
### did:key (W3C)
```
did:key:z + base58btc( 0xED 0x01 || 32_byte_ed25519_pubkey )
```
Multicodec prefix `0xED 0x01` identifies Ed25519 public keys.
The Rust backend uses `bs58::encode()` over a 34-byte buffer.
### NIP-19 Bech32 (npub/nsec)
```
npub1... = bech32(hrp="npub", data=32_byte_x_only_pubkey)
nsec1... = bech32(hrp="nsec", data=32_byte_private_key)
```
X-only pubkey = just the x-coordinate of the secp256k1 point (Schnorr format).
---
## Security
- Run on an air-gapped machine or at minimum a private terminal session
- The script makes zero network calls and writes zero files
- After verification, clean up:
```bash
rm verify-seed.py
unset MNEMONIC
history -c # bash
# or: fc -W /dev/null # zsh
```
- Never paste your mnemonic into a web tool, online REPL, or shared terminal
docs/adr/001-podman-over-docker.md
+32
View File
@@ -0,0 +1,32 @@
# ADR-001: Podman Over Docker
**Status**: Accepted
**Date**: 2026-03
## Context
Archipelago needs a container runtime for running applications. Docker and Podman are the two main options.
## Decision
Use Podman as the container runtime instead of Docker.
## Consequences
### Positive
- **Rootless by default**: Containers run without root privileges, reducing attack surface
- **Daemonless**: No persistent daemon process; containers are managed as individual processes under systemd
- **Docker-compatible**: Supports Docker images and most Docker CLI commands
- **Systemd integration**: Podman containers can be managed as systemd services natively
- **No vendor lock-in**: OCI-compliant, works with any container registry
### Negative
- **Smaller ecosystem**: Some Docker-specific tools and compose features require adaptation
- **Docker Compose differences**: Podman Compose exists but has occasional compatibility gaps
- **Documentation**: Most container documentation assumes Docker; developers need to translate
- **Networking**: Podman networking (CNI/netavark) differs from Docker's bridge networking
### Mitigation
- Use `podman` CLI wrapper that provides Docker-compatible interface
- Document Podman-specific commands in developer guide
- Use `archy-net` custom network for inter-container DNS
docs/adr/002-did-key-method.md
+31
View File
@@ -0,0 +1,31 @@
# ADR-002: DID Key Method for Node Identity
**Status**: Accepted
**Date**: 2026-03
## Context
Each Archipelago node needs a cryptographic identity for peer authentication, federation, and verifiable credentials. Multiple DID methods exist (did:web, did:ion, did:key, did:peer).
## Decision
Use `did:key` as the primary DID method.
## Consequences
### Positive
- **Self-contained**: The DID document is derived entirely from the public key — no external resolution needed
- **Offline-capable**: Works without internet, aligning with sovereignty principles
- **Simple**: No registration, no blockchain, no web server required
- **Fast**: DID resolution is a local computation, not a network request
- **Ed25519**: Uses Ed25519 keys which are fast, compact, and well-supported
### Negative
- **No key rotation**: The DID is bound to a single key; rotating requires a new DID
- **No service endpoints in DID**: Cannot embed service URLs in the DID document itself
- **No revocation**: Cannot revoke a did:key without out-of-band mechanisms
### Mitigation
- Use federation trust lists for key management and revocation
- Store service endpoints (onion address, pubkey) separately in federation state
- Support migration to did:peer or did:web in future versions if key rotation is needed
docs/adr/003-nostr-for-discovery.md
+35
View File
@@ -0,0 +1,35 @@
# ADR-003: Nostr Relays for Node and App Discovery
**Status**: Accepted
**Date**: 2026-03
## Context
Archipelago nodes need to discover peers and community apps without a central registry. Options: custom P2P protocol, DHT, BitTorrent tracker, Nostr relays, IPFS.
## Decision
Use Nostr relays (NIP-78, kind 30078) for both node discovery and marketplace app manifests.
## Consequences
### Positive
- **Decentralized**: Multiple independent relays; no single point of failure
- **Existing infrastructure**: Thousands of Nostr relays already running globally
- **Censorship-resistant**: If one relay censors, others still serve events
- **Simple protocol**: WebSocket + JSON — easy to implement without heavy dependencies
- **Key management**: Nostr uses secp256k1, same curve as Bitcoin — natural fit
- **NIP-33 replaceable events**: Latest event replaces previous — clean update model
- **Tor-compatible**: WebSocket over Tor SOCKS proxy works natively
### Negative
- **Relay availability varies**: Some relays may be down or rate-limited
- **No guaranteed persistence**: Relays may prune old events
- **Spam potential**: Open publishing means anyone can publish junk manifests
- **Latency**: Querying multiple relays adds latency to discovery
### Mitigation
- Query multiple relays in parallel; deduplicate results
- Cache results locally with 15-minute TTL
- Use trust scoring to rank manifests (DID verification, relay consensus, federation trust)
- Use hashtag filtering (`archipelago-marketplace`) to narrow queries
docs/adr/004-tor-for-peer-communication.md
+60
View File
@@ -0,0 +1,60 @@
# ADR-004: Tor Hidden Services for Peer Communication
**Status**: Accepted (2026-03) — **partially superseded in practice, see
Amendment below**
**Date**: 2026-03
## Context
Federated nodes need to communicate directly for state sync, app deployment, and peer verification. Options: direct IP, VPN tunnel, Tor hidden services, I2P.
## Decision
Use Tor hidden services (.onion addresses) for all inter-node communication.
## Consequences
### Positive
- **NAT traversal**: Works behind any firewall or NAT without port forwarding
- **IP privacy**: Nodes never expose their real IP addresses to each other
- **End-to-end encryption**: Tor provides encryption without additional TLS setup
- **Censorship resistance**: Onion routing makes traffic analysis difficult
- **Stable addressing**: .onion addresses persist across IP changes and network migrations
- **No central infrastructure**: No VPN server, STUN/TURN server, or relay needed
### Negative
- **Latency**: Tor adds 200-500ms per hop; 3 hops per direction = noticeable delay
- **Bandwidth**: Tor network has limited bandwidth; not suitable for bulk data transfer
- **Reliability**: Tor circuits can break; connections may need retry logic
- **Setup complexity**: Requires running a Tor daemon (`archy-tor` container)
- **Blocked networks**: Some networks block Tor; bridges can help but add complexity
### Mitigation
- Use Tor only for RPC/control plane; bulk data (container images) pulled from registries
- Implement retry with backoff for Tor connections
- Container `archy-tor` runs automatically with host networking for hidden service access
- Federation sync interval (5 min) tolerates occasional connection failures
## Amendment (recorded 2026-08)
Two things in this ADR no longer describe the system. Both changes happened
without their own ADR, which is itself worth noting.
**1. Tor is no longer used for *all* inter-node communication — it is the last
fallback.** The transport layer now tries, in order, mesh radio → LAN → FIPS
overlay → Tor (`transport::TransportKind`, priority 1–4). The latency and
bandwidth costs listed above are exactly why: FIPS was introduced to carry WAN
peering that Tor made too slow, and direct LAN peering skips the overlay
entirely for co-located nodes. Tor's NAT-traversal and IP-privacy properties are
still what make it the dependable floor when the others are unavailable.
**2. Tor does not run as the `archy-tor` container.** It is the host's Debian
`tor` package, running as `debian-tor` and driven by the
`archipelago-tor-helper` path unit (`scripts/tor-helper.sh`), which installs a
staged `/etc/tor/torrc` and restarts the service. The migration was deliberate
and is still enforced: `scripts/container-doctor.sh` removes an `archy-tor`
container if it finds one and switches the node to system Tor. There is no
`apps/tor` manifest.
The decision to use onion services for peer reachability stands; only its
exclusivity and its packaging changed.
docs/adr/005-chacha20-backup-encryption.md
+32
View File
@@ -0,0 +1,32 @@
# ADR-005: ChaCha20-Poly1305 for Backup Encryption
**Status**: Accepted
**Date**: 2026-03
## Context
Backups contain sensitive data (keys, credentials, app state) and must be encrypted at rest. Options: AES-256-GCM, ChaCha20-Poly1305, XChaCha20-Poly1305.
## Decision
Use ChaCha20-Poly1305 (AEAD) with Argon2id key derivation for backup encryption.
## Consequences
### Positive
- **Software performance**: ChaCha20 is faster than AES on hardware without AES-NI (common on ARM/SBCs)
- **Constant-time**: No timing side channels, unlike some AES implementations
- **AEAD**: Authenticated encryption ensures both confidentiality and integrity
- **Widely audited**: Used in TLS 1.3, WireGuard, and Signal Protocol
- **Simple implementation**: No padding, no CBC/CTR mode complexity
- **Argon2id KDF**: Memory-hard key derivation resists GPU/ASIC brute force attacks
### Negative
- **96-bit nonce**: Must ensure nonce uniqueness per encryption (random generation with collision check)
- **Not FIPS-certified**: Some enterprise environments require AES (not relevant for personal nodes)
- **Less hardware acceleration**: AES-NI on x86 can make AES faster on desktop CPUs
### Mitigation
- Generate random nonce per backup; store nonce alongside ciphertext
- Argon2id with high memory cost (64MB) and iterations (3) for password-to-key derivation
- Target hardware is mixed x86/ARM; ChaCha20's consistent performance is an advantage
docs/adr/006-nostr-marketplace-discovery.md
+57
View File
@@ -0,0 +1,57 @@
# ADR-006: Nostr Relays for Marketplace Discovery
## Status
Accepted
## Context
Archipelago needs a mechanism for users to discover and install third-party applications. The traditional approach is a centralized app store (like Apple App Store, Google Play, or Umbrel's marketplace). However, a centralized store introduces:
- A single point of failure and censorship
- A trust dependency on the store operator
- Barriers to entry for app developers (gatekeeping)
- Privacy concerns (the store operator knows what every user installs)
As a sovereign computing platform, Archipelago should align with decentralized principles.
## Decision
Use **Nostr relays** (NIP-78 application-specific data, kind 30078 events) for decentralized app manifest discovery instead of a centralized marketplace server.
### How It Works
1. **App developers** publish signed manifests as Nostr events to public relays
2. **Archipelago nodes** query multiple relays for available app manifests
3. **Trust scoring** uses verification count across relays, developer reputation (DID-linked), and optional community endorsements
4. **Users** see a merged, deduplicated list of available apps with trust indicators
### Trust Tiers
- **Verified**: Published by known developers, seen on 3+ relays, DID-verified
- **Community**: Seen on 2+ relays, valid manifest, unsigned or new developer
- **Unverified**: Single relay, new developer, use at own risk
## Consequences
### Positive
- No single point of failure — apps remain discoverable even if relays go offline
- No gatekeeping — any developer can publish apps
- Privacy-preserving — no central server tracking installs
- Censorship-resistant — apps can't be removed by a single entity
- Aligns with Nostr ecosystem already used for node identity
### Negative
- Discovery can be slower (querying multiple relays)
- Quality control relies on trust scoring rather than human curation
- Spam/malicious manifests require robust filtering
- Users need to understand trust tiers (not a simple "everything is safe" model)
### Mitigations
- Cache relay responses locally for fast subsequent loads
- Built-in curated app list for essential apps (Bitcoin, LND, etc.)
- Container security model (readonly_root, capability dropping) limits damage from malicious apps
- Manifest signature verification before installation
docs/adr/007-did-federation-trust.md
+54
View File
@@ -0,0 +1,54 @@
# ADR-007: DID-Based Federation Trust
## Status
Accepted
## Context
Archipelago supports federation — multiple nodes forming a trusted group for remote monitoring, app deployment, and state synchronization. Federation requires a trust establishment mechanism:
- **Centralized PKI** (Certificate Authorities): requires internet access, introduces third-party trust
- **Pre-shared keys**: simple but doesn't scale, no identity verification
- **DID-based bilateral verification**: each node verifies the other's cryptographic identity directly
## Decision
Use **bilateral DID-based verification** with single-use invite codes for federation trust establishment.
### How It Works
1. **Node A** generates a single-use invite code containing its DID, .onion address, and a shared secret
2. **Node B** receives the code (out-of-band: QR code, message, etc.) and submits it
3. **Both nodes** verify each other's DIDs by exchanging signed challenges over Tor
4. **Trust is established** — each node stores the other's DID and public key
5. **Ongoing communication** uses DID-authenticated messages over Tor hidden services
### Trust Levels
- **Trusted**: Full access — can view status, deploy apps, sync state
- **Observer**: Read-only access — can view status but not modify
- **Untrusted**: Blocked from federation operations
## Consequences
### Positive
- No third-party trust dependency (no CA, no central server)
- Works fully offline/air-gapped for the verification step
- Strong cryptographic identity (Ed25519 keys)
- Granular trust levels for different access patterns
- Invite codes are single-use (no replay attacks)
### Negative
- Requires out-of-band code exchange (can't auto-discover peers for federation)
- No revocation mechanism beyond removing the peer from the local trust store
- Key rotation requires re-establishing trust with all peers
- Trust is bilateral — each node maintains its own trust decisions
### Mitigations
- Nostr-based node discovery (ADR-003) handles finding nodes; federation handles trusting them
- Tor hidden services provide transport encryption and anonymity
- State sync includes heartbeat/health checks to detect unreachable peers
docs/adr/008-dual-key-strategy.md
+62
View File
@@ -0,0 +1,62 @@
# ADR-008: Dual Key Strategy (Ed25519 + Secp256k1)
## Status
Accepted
## Context
Archipelago operates at the intersection of two cryptographic ecosystems:
- **Web5 / DIDs**: The W3C DID specification and Verifiable Credentials ecosystem predominantly uses **Ed25519** (EdDSA) for digital signatures
- **Nostr / Bitcoin**: The Nostr protocol and Bitcoin ecosystem use **secp256k1** (ECDSA/Schnorr) for signatures
A single key type cannot serve both ecosystems without conversion layers or compatibility issues.
## Decision
Maintain **two key pairs per node identity**:
1. **Ed25519** — Primary identity key for DID documents, verifiable credentials, federation authentication, and backup encryption
2. **Secp256k1** — Nostr-compatible key for relay publishing, node discovery, and Lightning Network interactions
### Key Derivation
- Both keys are derived from the same master seed during node initialization
- The Ed25519 key is the canonical identity (stored in the DID document)
- The secp256k1 key is linked to the DID via the Nostr profile (NIP-05 verification)
### Usage Matrix
| Operation | Key Used |
|-----------|----------|
| DID document signing | Ed25519 |
| Verifiable credentials | Ed25519 |
| Federation auth | Ed25519 |
| Backup encryption | Ed25519 (via X25519 DH) |
| Nostr event publishing | secp256k1 |
| Node discovery | secp256k1 (Nostr) |
| Lightning channel auth | secp256k1 |
## Consequences
### Positive
- Full compatibility with both Web5 and Nostr ecosystems
- No conversion layers or compatibility hacks needed
- Each key type is used in its native context (maximum security)
- Both keys from same seed — single backup protects both
- Future-proof: can add new key types without breaking existing ones
### Negative
- Two keys to manage instead of one
- Users need to understand which pubkey is which (mitigated by UI)
- Key rotation must update both key types
- Slightly larger DID documents (two verification methods)
### Mitigations
- UI presents a unified identity view — users see "My Identity" not "My Ed25519 Key"
- Backup system captures the master seed, from which both keys derive
- DID document includes both verification methods with clear purpose labels
docs/adr/009-manifest-container-security.md
+99
View File
@@ -0,0 +1,99 @@
# ADR-009: Manifest-Level Container Security Enforcement
## Status
Accepted
## Context
Archipelago runs third-party applications as containers. Without enforcement, containers could:
- Run as root and escalate privileges
- Access the host filesystem
- Modify their own binaries (persistence of malicious code)
- Acquire unnecessary Linux capabilities
- Use unverified or tampered container images
Other node OS projects (Umbrel, Start9) vary in their security enforcement. Archipelago targets a higher security bar suitable for handling Bitcoin private keys and personal data.
## Decision
Enforce security constraints at the **manifest level**, applied automatically during container creation. Every container MUST comply with these non-negotiable defaults:
### Mandatory Security Defaults
| Constraint | Value | Rationale |
|-----------|-------|-----------|
| `readonly_root` | `true` | Prevents runtime filesystem modification (anti-persistence) |
| `no_new_privileges` | `true` | Prevents privilege escalation via setuid/setgid |
| `user` | UID > 1000 | Never run as root |
| `capabilities` | Drop ALL, add only required | Principle of least privilege |
| `image_tag` | Pinned version | No `latest` tags — reproducible deploys |
| `seccomp_profile` | Default | Blocks dangerous syscalls |
### Manifest Enforcement
The `core/container/` module validates manifests before container creation:
1. **Parse** the YAML manifest
2. **Validate** all required security fields are present
3. **Reject** manifests that violate mandatory defaults (e.g., `readonly_root: false` without explicit override)
4. **Apply** security context during `podman create`
### Optional Overrides
Some apps legitimately need elevated privileges:
- `readonly_root: false` — Only for apps that must write to their root filesystem (documented reason required)
- Additional capabilities (e.g., `NET_ADMIN` for VPN apps) — must be explicitly listed and justified
## Consequences
### Positive
- Defense in depth — even if a container image is compromised, damage is limited
- Consistent security posture across all apps
- Transparent — users can inspect any app's security manifest
- Aligns with industry best practices (CIS Benchmarks, NIST)
### Negative
- Some apps may not work without modifications (e.g., apps expecting root)
- Read-only root requires explicit volume mounts for writable directories
- Developers must understand and comply with the security model
- Slightly more complex manifest format than competitors
### Mitigations
- Clear documentation in `docs/app-manifest-spec.md`
- Example manifests for common app patterns
- Build-time validation catches issues before deployment
- Override mechanism for legitimate exceptions (with audit trail)
## Implementation status
The decision above stands; this section records how much of it is actually
enforced today, because the "non-negotiable" table overstates it. Verified
against `core/container/src/manifest.rs` and `core/security/src/`:
| Constraint | Reality |
|---|---|
| `capabilities` drop-all + allow-list | ✅ **Enforced.** A capability outside the nine-entry allow-list is a parse error, so the app cannot install |
| Bind-mount confinement | ✅ **Enforced** (stronger than this ADR describes): sources must be under `/var/lib/archipelago/`, a named volume, or one of two reviewed exceptions |
| `readonly_root` / `no_new_privileges` | ◐ **Defaults, not gates.** Both default to `true` when omitted, but `validate_security()` does not reject an explicit `false` — the "reject manifests that violate mandatory defaults" step does not exist |
| `image_tag` pinned | ◐ **Preflight only.** `scripts/validate-app-manifest.sh` grades it; the parser accepts `:latest` and the app installs |
| `user` UID > 1000 | ❌ **Not validated.** The runtime manifest parser has no UID check at all (the marketplace schema has an advisory one, which is a different type) |
| `seccomp_profile` | ❌ **Does not exist.** The string `seccomp` appears nowhere in `core/` — not as code, not as a TODO |
| AppArmor | ❌ **Inert.** `container_policies.rs` can generate and `apparmor_parser -r` a profile, but its own comment says `TODO: Configure Podman to use the profile`. `security.apparmor_profile` is parsed into a manifest field that nothing ever reads |
So the accurate summary is: capability and mount confinement are hard gates,
the process-hardening flags are safe-by-default rather than enforced, and the
kernel-level sandboxing (seccomp/AppArmor) named in the decision was never
wired up. Closing the last two rows is tracked in
[`1.8.0-RELEASE-HARDENING-PLAN.md`](../1.8.0-RELEASE-HARDENING-PLAN.md).
## References
- `docs/app-manifest-spec.md` — Full manifest specification
- `core/container/src/` — Container security implementation
- `core/security/src/` — AppArmor profiles and secrets management
docs/adr/011-dwn-deprioritization.md
+31
View File
@@ -0,0 +1,31 @@
# ADR-011: DWN Deprioritization
## Status
Accepted
## Context
TBD/Block shut down in November 2024, donating Web5 code to the Decentralized Identity Foundation (DIF). The DWN (Decentralized Web Node) specification was heavily backed by TBD — without their engineering team, the spec has lost momentum:
- No maintained Rust DWN SDK exists (the `dwn` crate by unavi-xyz is v0.4.0 with 323 downloads)
- TBD's reference implementation was TypeScript-only
- DIF has not allocated resources to continue DWN development
- The spec itself is complex (personal data stores with protocol-based access control)
Meanwhile, Archipelago's federation over Tor + Nostr relays already serves the core peer data sync use case that DWN was intended for.
## Decision
1. **Keep existing DWN store code** in `core/archipelago/src/network/dwn_store.rs` — it works for peer file catalogs and federation state
2. **Stop calling it "Web5 DWN"** in user-facing text — it's our custom implementation, not a full DWN spec implementation
3. **Do not invest in DWN spec compliance** — the spec is stalled and may not stabilize
4. **Prioritize Nostr + federation** for peer discovery and data exchange
5. **Re-evaluate if DIF produces a viable Rust SDK** or the spec gains new maintainers
## Consequences
- DWN functionality remains available but is not actively developed
- Peer sync uses federation + Nostr instead of DWN protocols
- Reduces maintenance burden — no need to track a stalled spec
- If DWN resurfaces with strong tooling, we can adopt it later
docs/api-reference.md
+399
View File
@@ -0,0 +1,399 @@
# Archipelago API Reference
All endpoints use JSON-RPC over HTTP POST to `/rpc/v1`.
**Request format:**
```json
{
"method": "namespace.action",
"params": { ... }
}
```
**Response format:**
```json
{
"result": { ... }
}
```
**Error format:**
```json
{
"error": { "message": "Error description" }
}
```
**Authentication:** All endpoints require a valid session cookie (`archipelago_session`) except those marked "No Auth".
---
## Authentication
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `auth.login` | `{ password: string }` | `{ ok: bool, totp_required?: bool }` | No Auth |
| `auth.logout` | — | `{ ok: bool }` | Yes |
| `auth.changePassword` | `{ current: string, new: string }` | `{ ok: bool }` | Yes |
| `auth.isOnboardingComplete` | — | `{ complete: bool }` | No Auth |
| `auth.onboardingComplete` | — | `{ ok: bool }` | Yes |
| `auth.resetOnboarding` | — | `{ ok: bool }` | Yes |
### TOTP 2FA
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `auth.totp.setup.begin` | `{ password: string }` | `{ secret: string, qr_uri: string, backup_codes: string[] }` | Yes |
| `auth.totp.setup.confirm` | `{ code: string }` | `{ ok: bool }` | Yes |
| `auth.totp.disable` | `{ password: string }` | `{ ok: bool }` | Yes |
| `auth.totp.status` | — | `{ enabled: bool }` | Yes |
| `auth.login.totp` | `{ code: string }` | `{ ok: bool }` | No Auth |
| `auth.login.backup` | `{ code: string }` | `{ ok: bool }` | No Auth |
---
## Container Orchestration
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `container-install` | `{ image: string, name?: string }` | `{ ok: bool, container_id: string }` | Yes |
| `container-start` | `{ id: string }` | `{ ok: bool }` | Yes |
| `container-stop` | `{ id: string }` | `{ ok: bool }` | Yes |
| `container-remove` | `{ id: string }` | `{ ok: bool }` | Yes |
| `container-list` | — | `{ containers: Container[] }` | Yes |
| `container-status` | `{ id: string }` | `{ status: string, ... }` | Yes |
| `container-logs` | `{ id: string, lines?: number }` | `{ logs: string }` | Yes |
| `container-health` | `{ id: string }` | `{ healthy: bool }` | Yes |
## Package Management
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `package.install` | `{ id: string, dockerImage?: string, url?: string, version?: string }` | `{ ok: bool }` | Yes |
| `package.start` | `{ id: string }` | `{ ok: bool }` | Yes |
| `package.stop` | `{ id: string }` | `{ ok: bool }` | Yes |
| `package.restart` | `{ id: string }` | `{ ok: bool }` | Yes |
| `package.uninstall` | `{ id: string }` | `{ ok: bool }` | Yes |
## Bundled Apps
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `bundled-app-start` | `{ id: string }` | `{ ok: bool }` | Yes |
| `bundled-app-stop` | `{ id: string }` | `{ ok: bool }` | Yes |
---
## Node Identity & P2P
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `node.did` | — | `{ did: string }` | Yes |
| `node.signChallenge` | `{ challenge: string }` | `{ signature: string }` | Yes |
| `node.tor-address` | — | `{ address: string }` | Yes |
| `node.nostr-publish` | — | `{ ok: bool, event_id: string }` | Yes |
| `node.nostr-pubkey` | — | `{ pubkey: string }` | Yes |
| `node-nostr-verify-revoked` | — | `{ revoked: bool, nostr_pubkey: string }` | Yes |
| `node-nostr-discover` | — | `{ nodes: DiscoveredNode[] }` | Yes |
| `node-add-peer` | `{ did: string, address: string }` | `{ ok: bool }` | Yes |
| `node-list-peers` | — | `{ peers: Peer[] }` | Yes |
| `node-remove-peer` | `{ did: string }` | `{ ok: bool }` | Yes |
| `node-send-message` | `{ to: string, message: string }` | `{ ok: bool }` | Yes |
| `node-check-peer` | `{ did: string }` | `{ online: bool }` | Yes |
| `node-messages-received` | — | `{ messages: Message[] }` | Yes |
| `node.createBackup` | `{ password: string }` | `{ path: string }` | Yes |
---
## Identity Management
### Multi-Identity
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `identity.list` | `{}` | `{ identities: Identity[] }` | Yes |
| `identity.create` | `{ label: string }` | `{ identity: Identity }` | Yes |
| `identity.get` | `{ id: string }` | `{ identity: Identity }` | Yes |
| `identity.delete` | `{ id: string }` | `{ ok: bool }` | Yes |
| `identity.set-default` | `{ id: string }` | `{ ok: bool }` | Yes |
| `identity.sign` | `{ id: string, data: string }` | `{ signature: string }` | Yes |
| `identity.verify` | `{ id: string, data: string, signature: string }` | `{ valid: bool }` | Yes |
| `identity.resolve-did` | `{ did: string }` | `{ document: DIDDocument }` | Yes |
| `identity.resolve-remote-did` | `{ did: string }` | `{ document: DIDDocument }` | Yes |
| `identity.verify-did-document` | `{ document: object }` | `{ valid: bool }` | Yes |
### Nostr Keys
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `identity.create-nostr-key` | `{ id: string }` | `{ pubkey: string, npub: string }` | Yes |
| `identity.nostr-sign` | `{ id: string, event: object }` | `{ signed_event: object }` | Yes |
### Bitcoin Names (NIP-05)
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `identity.register-name` | `{ name: string, pubkey: string }` | `{ ok: bool }` | Yes |
| `identity.remove-name` | `{ name: string }` | `{ ok: bool }` | Yes |
| `identity.resolve-name` | `{ name: string }` | `{ pubkey: string }` | Yes |
| `identity.list-names` | `{}` | `{ names: NameEntry[] }` | Yes |
| `identity.link-name` | `{ name: string, identity_id: string }` | `{ ok: bool }` | Yes |
### Verifiable Credentials
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `identity.issue-credential` | `{ subject: string, claims: object }` | `{ credential: VC }` | Yes |
| `identity.verify-credential` | `{ credential: object }` | `{ valid: bool }` | Yes |
| `identity.list-credentials` | `{ id?: string }` | `{ credentials: VC[] }` | Yes |
| `identity.revoke-credential` | `{ credential_id: string }` | `{ ok: bool }` | Yes |
| `identity.create-presentation` | `{ credentials: string[] }` | `{ presentation: VP }` | Yes |
| `identity.verify-presentation` | `{ presentation: object }` | `{ valid: bool }` | Yes |
---
## Bitcoin & Lightning
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `bitcoin.getinfo` | — | `{ blocks: number, connections: number, ... }` | Yes |
| `lnd.getinfo` | — | `{ identity_pubkey: string, num_active_channels: number, ... }` | Yes |
| `lnd.listchannels` | — | `{ channels: Channel[] }` | Yes |
| `lnd.openchannel` | `{ pubkey: string, amount: number }` | `{ funding_txid: string }` | Yes |
| `lnd.closechannel` | `{ channel_point: string }` | `{ closing_txid: string }` | Yes |
| `lnd.newaddress` | — | `{ address: string }` | Yes |
| `lnd.sendcoins` | `{ addr: string, amount?: number, send_all?: bool, target_conf?: number, sat_per_vbyte?: number }` | `{ txid: string }` | Yes |
| `lnd.estimatefee` | `{ addr: string, amount: number, target_conf?: number }` | `{ fee_sat: number, sat_per_vbyte: number }` | Yes |
| `lnd.createinvoice` | `{ amount: number, memo?: string }` | `{ payment_request: string }` | Yes |
| `lnd.payinvoice` | `{ payment_request: string }` | `{ preimage: string }` | Yes |
| `lnd.create-psbt` | `{ outputs: object, ... }` | `{ psbt: string }` | Yes |
| `lnd.finalize-psbt` | `{ psbt: string }` | `{ signed_psbt: string }` | Yes |
---
## Ecash Wallet
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `wallet.ecash-balance` | — | `{ balance: number, mint_url: string }` | Yes |
| `wallet.ecash-mint` | `{ amount: number }` | `{ ok: bool }` | Yes |
| `wallet.ecash-melt` | `{ amount: number, invoice: string }` | `{ ok: bool }` | Yes |
| `wallet.ecash-send` | `{ amount: number }` | `{ token: string }` | Yes |
| `wallet.ecash-receive` | `{ token: string }` | `{ amount: number }` | Yes |
| `wallet.ecash-history` | — | `{ transactions: EcashTx[] }` | Yes |
| `wallet.networking-profits` | — | `{ total_sats: number, ... }` | Yes |
---
## Network
### Interfaces & WiFi
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `network.list-interfaces` | — | `{ interfaces: Interface[] }` | Yes |
| `network.scan-wifi` | — | `{ networks: WifiNetwork[] }` | Yes |
| `network.configure-wifi` | `{ ssid: string, password: string }` | `{ ok: bool }` | Yes |
| `network.configure-ethernet` | `{ interface: string, mode: "dhcp"\|"static", ip?: string, gateway?: string, dns?: string }` | `{ ok: bool }` | Yes |
| `network.diagnostics` | — | `{ wan_ip: string, nat_type: string, upnp_available: bool, tor_connected: bool, wifi_count: number }` | Yes |
### DNS
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `network.dns-status` | — | `{ provider: string, servers: string[], doh_enabled: bool, doh_url: string?, resolv_conf_servers: string[] }` | Yes |
| `network.configure-dns` | `{ provider: "system"\|"cloudflare"\|"google"\|"quad9"\|"mullvad"\|"custom", servers?: string[] }` | `{ ok: bool, provider: string, servers: string[], doh_enabled: bool }` | Yes |
### Network Overlay
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `network.get-visibility` | — | `{ visibility: string }` | Yes |
| `network.set-visibility` | `{ visibility: string }` | `{ ok: bool }` | Yes |
| `network.request-connection` | `{ target_did: string }` | `{ request_id: string }` | Yes |
| `network.list-requests` | — | `{ requests: ConnectionRequest[] }` | Yes |
| `network.accept-request` | `{ request_id: string }` | `{ ok: bool }` | Yes |
| `network.reject-request` | `{ request_id: string }` | `{ ok: bool }` | Yes |
### Router / UPnP
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `router.discover` | — | `{ router: RouterInfo }` | Yes |
| `router.list-forwards` | — | `{ forwards: PortForward[] }` | Yes |
| `router.add-forward` | `{ port: number, protocol: string, description: string }` | `{ ok: bool }` | Yes |
| `router.remove-forward` | `{ port: number, protocol: string }` | `{ ok: bool }` | Yes |
| `router.detect` | `{ ... }` | `{ detected: bool, ... }` | Yes |
| `router.info` | — | `{ ... }` | Yes |
| `router.configure` | `{ ... }` | `{ ok: bool }` | Yes |
---
## Tor
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `tor.list-services` | — | `{ services: TorService[] }` | Yes |
| `tor.create-service` | `{ name: string, port: number }` | `{ onion_address: string }` | Yes |
| `tor.delete-service` | `{ name: string }` | `{ ok: bool }` | Yes |
| `tor.get-onion-address` | `{ name: string }` | `{ address: string }` | Yes |
## Nostr Relays
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `nostr.list-relays` | — | `{ relays: RelayConfig[] }` | Yes |
| `nostr.add-relay` | `{ url: string }` | `{ ok: bool }` | Yes |
| `nostr.remove-relay` | `{ url: string }` | `{ ok: bool }` | Yes |
| `nostr.toggle-relay` | `{ url: string }` | `{ ok: bool }` | Yes |
| `nostr.get-stats` | — | `{ total_relays: number, connected: number, enabled: number }` | Yes |
---
## VPN
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `vpn.status` | — | `{ connected: bool, provider?: string, ip_address?: string, hostname?: string, peers_connected: number }` | Yes |
| `vpn.configure` | `{ provider: "tailscale"\|"wireguard", auth_key?: string, address?: string, dns?: string, peer?: object }` | `{ ok: bool }` | Yes |
| `vpn.disconnect` | — | `{ disconnected: bool }` | Yes |
## Mesh Networking
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `mesh.status` | — | `{ enabled: bool, device: string?, nodes: MeshNode[] }` | Yes |
| `mesh.peers` | — | `{ peers: MeshPeer[], count: number }` | Yes |
| `mesh.broadcast` | — | `{ ok: bool }` | Yes |
| `mesh.configure` | `{ enabled: bool, device?: string }` | `{ ok: bool }` | Yes |
---
## Federation
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `federation.invite` | — | `{ code: string }` | Yes |
| `federation.join` | `{ code: string }` | `{ ok: bool, node: FederatedNode }` | Yes |
| `federation.list-nodes` | — | `{ nodes: FederatedNode[] }` | Yes |
| `federation.remove-node` | `{ did: string }` | `{ ok: bool }` | Yes |
| `federation.set-trust` | `{ did: string, trust: "trusted"\|"observer"\|"untrusted" }` | `{ ok: bool }` | Yes |
| `federation.sync-state` | — | `{ results: SyncResult[] }` | Yes |
| `federation.get-state` | — | `{ state: NodeStateSnapshot }` | Federation peer |
| `federation.peer-joined` | `{ did: string, onion: string, pubkey: string }` | `{ accepted: bool }` | Federation peer |
| `federation.deploy-app` | `{ target_did: string, app_id: string, version?: string }` | `{ ok: bool }` | Yes |
---
## Marketplace
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `marketplace.discover` | — | `{ apps: DiscoveredApp[], relay_count: number }` | Yes |
| `marketplace.publish` | `{ app_id, name, version, description, author, container, category, ... }` | `{ ok: bool, event_id: string }` | Yes |
| `marketplace.get-manifest` | `{ app_id: string }` | `DiscoveredApp \| { error: string }` | Yes |
| `marketplace.list-published` | — | `{ manifests: AppManifest[] }` | Yes |
| `marketplace.verify` | `{ ... manifest fields ... }` | `{ valid: bool, issues: string[], trust_score: number }` | Yes |
---
## DWN (Decentralized Web Node)
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `dwn.status` | — | `{ running: bool, message_count: number, protocol_count: number }` | Yes |
| `dwn.sync` | — | `{ synced: number }` | Yes |
| `dwn.register-protocol` | `{ uri: string, definition: object }` | `{ ok: bool }` | Yes |
| `dwn.list-protocols` | — | `{ protocols: Protocol[] }` | Yes |
| `dwn.remove-protocol` | `{ uri: string }` | `{ ok: bool }` | Yes |
| `dwn.query-messages` | `{ protocol?: string, limit?: number }` | `{ messages: DwnMessage[] }` | Yes |
| `dwn.write-message` | `{ protocol: string, data: object }` | `{ ok: bool, message_id: string }` | Yes |
---
## Content Catalog
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `content.list-mine` | — | `{ items: ContentItem[] }` | Yes |
| `content.add` | `{ title: string, type: string, data: object }` | `{ ok: bool, id: string }` | Yes |
| `content.remove` | `{ id: string }` | `{ ok: bool }` | Yes |
| `content.set-pricing` | `{ id: string, price_sats: number }` | `{ ok: bool }` | Yes |
| `content.set-availability` | `{ id: string, available: bool }` | `{ ok: bool }` | Yes |
| `content.browse-peer` | `{ peer_did: string }` | `{ items: ContentItem[] }` | Yes |
---
## System
### Monitoring
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `system.stats` | — | `{ cpu_percent: number, ram_used: number, ram_total: number, disk_used: number, disk_total: number, uptime_secs: number, load_avg: number[] }` | Yes |
| `system.processes` | — | `{ processes: Process[] }` | Yes |
| `system.temperature` | — | `{ celsius: number? }` | Yes |
| `system.detect-usb-devices` | — | `{ devices: UsbDevice[] }` | Yes |
### Updates
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `update.check` | — | `{ available: bool, version?: string, changelog?: string }` | Yes |
| `update.status` | — | `{ state: string, progress?: number }` | Yes |
| `update.dismiss` | — | `{ ok: bool }` | Yes |
| `update.download` | — | `{ ok: bool }` | Yes |
| `update.apply` | — | `{ ok: bool }` | Yes |
| `update.rollback` | — | `{ ok: bool }` | Yes |
| `update.get-schedule` | — | `{ auto_check: bool, auto_install: bool, schedule: string }` | Yes |
| `update.set-schedule` | `{ auto_check?: bool, auto_install?: bool, schedule?: string }` | `{ ok: bool }` | Yes |
### Backup & Restore
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `backup.create` | `{ password: string, include?: string[] }` | `{ path: string, size: number }` | Yes |
| `backup.list` | — | `{ backups: BackupEntry[] }` | Yes |
| `backup.verify` | `{ path: string, password: string }` | `{ valid: bool }` | Yes |
| `backup.restore` | `{ path: string, password: string }` | `{ ok: bool }` | Yes |
| `backup.delete` | `{ path: string }` | `{ ok: bool }` | Yes |
| `backup.list-drives` | — | `{ drives: UsbDrive[] }` | Yes |
| `backup.to-usb` | `{ drive: string, password: string }` | `{ ok: bool }` | Yes |
### Security
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `security.rotate-secrets` | `{ app_id?: string }` | `{ rotated: string[] }` | Yes |
| `security.list-expiring` | `{ days?: number }` | `{ secrets: ExpiringSecret[] }` | Yes |
---
## Utility
| Method | Params | Returns | Auth |
|--------|--------|---------|------|
| `echo` | `{ message: string }` | `{ message: string }` | No Auth |
| `server.echo` | `{ message: string }` | `{ message: string }` | No Auth |
---
## Example: cURL
```bash
# Login (the password you created on the node's first-boot setup screen —
# there is no default password)
curl -c cookies.txt -X POST http://archipelago.local/rpc/v1 \
-H "Content-Type: application/json" \
-d '{"method":"auth.login","params":{"password":"YOUR_NODE_PASSWORD"}}'
# Get system stats (authenticated)
curl -b cookies.txt -X POST http://archipelago.local/rpc/v1 \
-H "Content-Type: application/json" \
-d '{"method":"system.stats"}'
# Get DID
curl -b cookies.txt -X POST http://archipelago.local/rpc/v1 \
-H "Content-Type: application/json" \
-d '{"method":"node.did"}'
```
docs/app-developer-guide.md
+463
View File
@@ -0,0 +1,463 @@
# Archipelago App Developer Guide
Build and package containerized apps for Archipelago.
## Overview
Apps run as rootless Podman containers on user nodes. You describe an app in `apps/<app-id>/manifest.yml`; the backend validates that manifest, compiles it into rootless container/runtime behavior, and the release pipeline generates catalog surfaces from the same manifest-owned metadata.
Archipelago's app contract is deliberately manifest-first. A developer should be able to describe images or local builds, ports, volumes, generated files, dependencies, health/readiness, data ownership, networking, secrets, and supported bridge integrations in the app manifest without asking for a custom OS image or app-specific backend patch. When a real app needs a capability that is not represented yet, the preferred path is to add a reusable manifest/orchestrator primitive that other apps can use too.
The historical marketplace-publish design is not the active local developer contract for `1.8-alpha`. For this release, local manifests are the source of truth and catalog JSON is generated from them.
## App Manifest
Every app needs a manifest at `apps/<app-id>/manifest.yml`. The root key is `app`; runtime, catalog, and integration fields live below that key.
### Template Manifest
```yaml
# apps/my-app/manifest.yml
app:
id: my-app # Unique, lowercase kebab-case
name: My App
version: 1.0.0 # Semantic versioning
description: My App does one thing well.
container:
image: docker.io/myorg/my-app:1.0.0
pull_policy: if-not-present
network: archy-net
entrypoint: ["sh", "-lc"]
custom_args:
- /app/start.sh
derived_env:
- key: PUBLIC_URL
template: https://{{HOST_MDNS}}:8180
secret_env:
- key: APP_PASSWORD
secret_file: my-app-password
dependencies:
- storage: 1Gi
resources:
cpu_limit: 2
memory_limit: 512Mi
security:
capabilities: []
readonly_root: true
no_new_privileges: true
network_policy: isolated
ports:
- host: 8180
container: 8080
protocol: tcp
volumes:
- type: bind
source: /var/lib/archipelago/my-app
target: /data
options: [rw]
environment:
- APP_MODE=production
health_check:
type: http
endpoint: http://localhost:8080
path: /health
interval: 30s
timeout: 5s
retries: 3
files:
- path: /var/lib/archipelago/my-app/config.yml
content: |
bind: 0.0.0.0:8080
overwrite: false
metadata:
icon: /assets/img/app-icons/my-app.svg
category: tools
tier: optional
repo: https://github.com/myorg/my-app
launch:
open_in_new_tab: false
```
### Required Fields
| Field | Description |
|-------|-------------|
| `app.id` | Unique identifier, lowercase, kebab-case only |
| `app.name` | Human-readable name |
| `app.version` | Version string containing at least one digit; semantic versions are preferred |
| `container.image` or `container.build` | Exactly one image source must be present |
| `security.readonly_root` | Should remain `true` for normal apps |
| `security.no_new_privileges` | Should remain `true` for normal apps |
### Current Manifest Fields
| Field | Purpose |
|-------|---------|
| `app.id`, `app.name`, `app.version`, `app.description` | App identity and release metadata |
| `app.container.image` | Registry image to pull |
| `app.container.build` | Local build definition with `context`, `dockerfile`, `tag`, and optional `build_args` |
| `app.container.pull_policy` | Pull behavior, usually `if-not-present` |
| `app.container.network` | Podman network setting such as `archy-net` or `pasta`; dangerous namespace-sharing modes are rejected |
| `app.container.entrypoint` / `custom_args` | Entrypoint and command override |
| `app.container.derived_env` | Environment values rendered from host facts. The complete placeholder set is `{{HOST_IP}}`, `{{HOST_MDNS}}`, `{{DISK_GB}}`, `{{BITCOIN_HOST}}`; an unknown name or an unbalanced `{{` is a parse error, so typos fail loudly |
| `app.container.secret_env` | Environment values read from `/var/lib/archipelago/secrets/<secret_file>`, injected as podman secrets (never visible in `podman inspect` or unit files) |
| `app.container.generated_secrets` | Secrets the orchestrator creates on first use (`hex16`/`hex32`/`base64`/`bcrypt`) — self-healing, 0600, no host provisioning |
| `app.container.generated_certs` | Self-signed TLS certs materialised before create; CN/SANs rendered from host facts |
| `app.container.network_aliases` | Extra DNS names on the app network so stack members answer to short baked-in hostnames (`api`, `minio`, `relay`) |
| `app.container.data_uid` | UID:GID ownership repair for app data directories |
| `app.hooks` | Allow-listed lifecycle hooks (`post_install`: `exec` inside the app's own container, `copy_from_host` from allow-listed roots) — see `manifest-hooks-design.md` |
| `app.dependencies` | Storage requirements and app dependencies |
| `app.resources` | CPU, memory, and disk limits |
| `app.security` | Capabilities, read-only root, no-new-privileges, network policy, optional AppArmor profile |
| `app.ports` | Host-to-container port mappings |
| `app.volumes` | `bind`, `volume`, or `tmpfs` mounts |
| `app.files` | Generated files under declared bind-mounted host paths |
| `app.environment` | Static `KEY=value` environment entries |
| `app.health_check` | HTTP or TCP health check settings |
| `app.devices` | Explicit device paths |
| `app.metadata` | Catalog-facing presentation metadata such as icon, category, tier, repo/source, author, feature bullets, and launch hints |
| `app.interfaces.main` | Optional primary UI launch surface with `port`, `protocol`, and `path` |
Additional extension keys may exist for current integrations, for example Bitcoin, Lightning, or app-specific launch/interface metadata. Treat extension keys as transitional unless they are documented as reusable platform primitives.
Use `metadata.launch.open_in_new_tab: true` when the app UI is known to reject iframe embedding with headers such as `X-Frame-Options` or restrictive CSP. The frontend app-session metadata is generated from this flag during release work.
### Launch Interfaces
If an app exposes a user-facing web UI, declare its primary launch surface in
`interfaces.main`. Runtime package listings prefer this interface over inferred
port mappings, which matters for apps that expose non-UI service ports or use a
companion wait/proxy UI.
```yaml
interfaces:
main:
name: Web UI
description: Primary app interface
type: ui
port: 8180
protocol: http
path: /
```
For simple HTTP apps without `interfaces.main`, Archipelago can still infer the
launch URL from the first declared TCP host port when the app has an HTTP health
check. TCP-only service ports, such as Bitcoin RPC/P2P, are not treated as UI
launch URLs.
Interface keys must use lowercase ASCII letters, digits, hyphens, or
underscores. Supported interface types are `ui`, `api`, and `metrics`; only
`type: ui` is treated as a launchable app surface. Supported protocols are
`http` and `https`, and `path` must start with `/`.
### Nostr Signer Bridge (NIP-07)
Apps embedded in the Archipelago iframe can use the node's Nostr identity to sign
events without managing their own keys. Archipelago injects a **NIP-07 provider**
(`window.nostr` with `getPublicKey()` / `signEvent()` / `nip04` / `nip44`) that bridges
to the host. Your app code uses standard NIP-07 — no Archipelago-specific API.
**How injection works.** After install, the host copies `nostr-provider.js` into the
app container and patches the app's web server so every page loads it and the app is
iframe-embeddable. This is **best-effort** and depends on your server config exposing
the right hooks. For an **nginx-served SPA** (the supported reference shape, e.g.
IndeeHub) your `nginx.conf` must satisfy this contract:
1. **Be iframe-embeddable.** Do not send a hard `X-Frame-Options: DENY`. The host
strips a `SAMEORIGIN`/`DENY` `X-Frame-Options` header line if present; restrictive
CSP `frame-ancestors` will still block embedding.
2. **Keep an exact-match `location = /sw.js {` block.** The provider's no-cache
`location = /nostr-provider.js` block is inserted immediately before it.
3. **Keep an SPA fallback line `try_files $uri $uri/ /index.html;`.** A
`sub_filter` that injects `<script src="/nostr-provider.js"></script>` before
`</head>` is inserted right after it. (nginx must have `ngx_http_sub_module` —
stock `nginx:alpine` does.)
4. **If you proxy an API that does NIP-98 URL verification**, expose
`proxy_set_header X-Forwarded-Prefix /api;`; the host rewrites it to honor the
outer reverse proxy's prefix.
The patch is **idempotent** (it checks for an existing `nostr-provider` reference
before editing) and re-runs on reinstall. If you rename or remove any of the anchor
strings above, injection silently no-ops and `window.nostr` will be undefined in your
app — so guard those lines in your config (see the contract comment block at the top of
IndeeHub's `nginx.conf` for a template).
> Non-nginx servers (Next.js `node server.js`, etc.) are not auto-patched today. Either
> serve via nginx, or ship `nostr-provider.js` yourself and reference it in your HTML;
> the canonical script lives at `/opt/archipelago/web-ui/nostr-provider.js` on the node.
Declare iframe intent in the manifest so the launcher embeds (vs. opens a new tab):
```yaml
metadata:
launch:
open_in_new_tab: false # default; set true only if the app cannot be iframed
```
## Security Requirements
Two different things enforce these, and it's worth knowing which is which:
- **The Rust parser (`core/container/src/manifest.rs`)** is the hard gate. A
manifest that violates one of its rules fails to parse, so the app cannot be
installed at all.
- **`scripts/validate-app-manifest.sh`** is the submission preflight. It applies
the *policy* rules the parser doesn't encode, and grades them `fail`/`warn`.
### Mandatory
1. **No `:latest` tag** — Pin a specific version: `myapp:1.0.0`. Checked by the
preflight script (a `fail` for new apps, a `warn` for existing manifests being
migrated), **not** by the parser — a `:latest` manifest still installs, so
pinning is on you.
2. **Read-only root filesystem** — `security.readonly_root: true` (use volumes
for writable data). This is the parser's default when you omit it.
3. **No privilege escalation** — `security.no_new_privileges: true`. Also the
parser's default when omitted.
4. **Minimal capabilities** — Drop all caps, only add required ones. The
allow-list below *is* parser-enforced: anything outside it is a parse error.
5. **No host network unless explicitly approved** — keep
`security.network_policy` isolated or bridge (`isolated` is the default).
### Allowed Capabilities
The parser currently accepts this allow-list. Keep capability requests minimal; some accepted capabilities still require release review before a public package should depend on them.
| Capability | When Needed |
|-----------|-------------|
| `CHOWN` | App needs to change file ownership |
| `DAC_OVERRIDE` | App needs to bypass file permissions |
| `FOWNER` | App needs ownership-related file operations |
| `NET_ADMIN` | Network administration; requires extra scrutiny |
| `NET_BIND_SERVICE` | App binds to ports below 1024 |
| `NET_RAW` | Raw network sockets; requires extra scrutiny |
| `SETUID`, `SETGID` | App manages user switching |
| `SYS_ADMIN` | Broad administrative capability; avoid for normal apps |
### Forbidden
- Namespace-sharing network modes such as `container:<name>` or `ns:<path>`
- **Host bind mounts outside `/var/lib/archipelago/`.** This is an allow-list,
not a blocklist of "system paths": `volumes[].source` must be absolute and
start with `/var/lib/archipelago/`, or be a plain named volume (no slashes),
or be one of two reviewed exceptions (`/run/user/1000/podman/podman.sock`,
`/var/run/dbus`). `..` anywhere in the path is rejected. Everything else fails
to parse, so your app's data belongs under `/var/lib/archipelago/<app-id>`
- Capabilities outside the allow-list above — including `SYS_PTRACE`
- Privileged containers or rootful execution
- Hardcoded secrets in environment variables or images — use `secret_env` or
`generated_secrets`
## Container Best Practices
### Volumes
```yaml
volumes:
- type: bind
source: /var/lib/archipelago/my-app
target: /data
options: [rw]
```
Data is stored at `/var/lib/archipelago/{app-id}/` on the host.
Generated files must live under a declared bind-mounted host path:
```yaml
files:
- path: /var/lib/archipelago/my-app/config.yml
content: |
bind: 0.0.0.0:8080
overwrite: false
```
Use `overwrite: false` for first-run defaults that users or the app may later modify. Use `overwrite: true` only for generated files the platform must own.
`files[].content` supports its own placeholder set — a different one from
`derived_env`:
| Placeholder | Renders to |
|---|---|
| `{{HOST_IP}}` / `{{HOST_MDNS}}` | Host facts (`hostname -I` / the node's `.local` name) |
| `{{NETWORK_GATEWAY}}` | The gateway of the app's Podman network, i.e. aardvark's DNS address. Use it as an nginx `resolver` so container names re-resolve per request instead of pinning a stale IP and 502-ing after a restart |
| `{{secret:NAME}}` | The trimmed contents of the `0600` secret `NAME` from the service-owned secrets dir. `NAME` must be a bare filename. Never logged |
### Health Checks
Define a health check endpoint in your container:
```dockerfile
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
CMD curl -f http://localhost:8080/health || exit 1
```
### Logging
- Log to stdout/stderr (Podman captures container logs)
- Never log secrets, passwords, or keys
- Use structured logging (JSON) for machine parsing
### Networking
Apps get their own network namespace. To connect to other Archipelago apps:
```yaml
# If your app needs to talk to Bitcoin
dependencies:
- bitcoin-knots
container:
network: archy-net
derived_env:
- key: BITCOIN_RPC_HOST
template: "{{BITCOIN_HOST}}" # resolves to whichever Bitcoin app is installed
- key: BITCOIN_RPC_PORT
template: "8332"
```
Prefer `{{BITCOIN_HOST}}` over hardcoding `bitcoin-knots` — a node may be running
Bitcoin Core instead, and the placeholder resolves to whichever is present.
The `archy-net` Podman network provides DNS resolution between containers. Use `derived_env` for host facts like `HOST_MDNS` instead of hardcoding node-specific URLs.
## Catalog Generation
Catalog JSON is generated from manifests during release work. Do not manually edit generated fields in `app-catalog/catalog.json` or `neode-ui/public/catalog.json` when the same value belongs in the manifest.
Manifest-owned catalog fields currently include:
- app title from `app.name`;
- version from `app.version`;
- description from `app.description`;
- Docker image from `app.container.image`;
- category from `app.category` or `app.metadata.category`;
- tier from `app.metadata.tier`;
- icon from `app.metadata.icon`;
- repo URL from `app.metadata.repo`, `repoUrl`, or `source`.
### 1. Build and Push Your Image
```bash
podman build -t docker.io/myorg/my-app:1.0.0 .
podman push docker.io/myorg/my-app:1.0.0
```
### 2. Generate Catalogs
```bash
python3 scripts/generate-app-catalog.py
```
### 3. Verify Drift
```bash
python3 scripts/check-app-catalog-drift.py --release --strict
```
Before release, the canonical catalog and UI public catalog should match:
```bash
cmp -s app-catalog/catalog.json neode-ui/public/catalog.json
```
## Testing Your App
### Validate Your Manifest
Before anything else, check your manifest against the schema and the app-submission
rules:
```bash
./scripts/validate-app-manifest.sh apps/my-app/manifest.yml
```
It reports `STATUS: APPROVED` or `STATUS: REJECTED` with the specific failures —
including the ones that block submission, such as an unpinned `:latest` image
tag (new apps must pin a concrete version). It needs `python3` and PyYAML; it
tells you if either is missing. The Rust parser in `core/container/src/manifest.rs`
remains the canonical validator — this script is the fast local preflight.
### Local Testing
```bash
# Run your container locally
podman run -d --name my-app \
-p 8180:8080 \
--read-only \
--security-opt no-new-privileges \
--user 1000:1000 \
docker.io/myorg/my-app:1.0.0
# Verify it works
curl http://localhost:8180/health
# Check logs
podman logs my-app
```
### On an Archipelago Node
1. Install via the marketplace UI or RPC:
```bash
curl -b cookies.txt -X POST http://archipelago.local/rpc/v1 \
-d '{"method":"package.install","params":{"id":"my-app","dockerImage":"docker.io/myorg/my-app:1.0.0"}}'
```
2. Verify the container is running:
```bash
curl -b cookies.txt -X POST http://archipelago.local/rpc/v1 \
-d '{"method":"container-list"}'
```
3. Check the UI. The app's detail page is `http://archipelago.local/dashboard/apps/my-app`; the embedded launch surface is `http://archipelago.local/dashboard/app-session/my-app`
### Validate Manifest
```bash
cargo test --manifest-path core/Cargo.toml -p archipelago-container
python3 scripts/check-app-catalog-drift.py --release --strict
```
## Updating Your App
1. Build and push the new version: `docker.io/myorg/my-app:1.1.0`.
2. Update `app.version` and `app.container.image` or `app.container.build.tag`.
3. Run catalog generation and drift checks.
4. Validate install/start/stop/restart/uninstall/reinstall behavior before shipping.
The broader app update policy for `1.8-alpha` is still being finalized. Until that policy is locked, app manifests should be explicit and pinned so update detection compares concrete image/tag metadata rather than mutable tags.
## App Icon
- Provide a URL to your app icon (PNG, WebP, or SVG)
- Recommended size: 256x256 pixels
- Square aspect ratio
- If no icon URL, a generic placeholder is shown in the marketplace
## Release Validation Expectations
Every supported app must satisfy the lifecycle contract:
- install
- launch
- stop
- start
- restart
- uninstall while preserving data
- reinstall with preserved data
- report truthful health/status
- survive backend restart
- survive host reboot
For apps with special dependencies, launch must explain dependency wait states instead of showing a dead iframe. Examples include Bitcoin sync/IBD, Lightning wallet readiness, Nostr signer bridge injection, Tailscale login/auth, and app-specific setup screens.
Runtime changes should be validated with focused tests first, then the release lifecycle harness on the validation host when host access is intentionally resumed.
docs/app-manifest-spec.md
+170
View File
@@ -0,0 +1,170 @@
# App Manifest Specification
_Accurate as of 2026-07-08. The canonical schema is the Rust parser in
`core/container/src/manifest.rs` (`AppManifest` → `AppDefinition`); if this
document and the code disagree, the code wins. See
[`app-developer-guide.md`](app-developer-guide.md) for the authoring workflow._
Every app is a directory `apps/<id>/` containing a `manifest.yml` with a single
top-level `app:` block. Apps are declarative — the orchestrator owns the entire
lifecycle; there is no per-app installer code.
One honest caveat: seven first-party apps still get Rust-side pre-start work
through a hardcoded `match app_id` in `ProdOrchestrator::run_pre_start_hooks` —
`bitcoin-ui`, `filebrowser`, `lnd`, `archy-nbxplorer`, `btcpay-server`,
`fedimint-clientd` and `grafana` render or repair a config before start. That is
orchestrator code rather than a per-app installer, but it is not
manifest-declared, and the direction of travel is to replace each case with a
reusable manifest primitive.
## Top-level fields (`app:`)
| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `id` | string | ✅ | Lowercase ASCII letters, digits and single hyphens only — **no underscores**, no leading/trailing `-`, no `--` (`is_valid_app_id`). Should match the directory name, though nothing enforces that: the loader keys off `app.id`, so a mismatch silently registers the app under the id in the file rather than the folder. |
| `name` | string | ✅ | Display name. |
| `version` | string | ✅ | App version shown in the UI. |
| `description` | string | — | One-line description. |
| `container` | ContainerConfig | — | Image/build source + runtime shape (below). |
| `dependencies` | list | — | `- storage: "10GB"`, `- { app_id: bitcoin, version: … }`, or a bare string. |
| `resources` | ResourceLimits | — | `cpu_limit` (int), `memory_limit` (e.g. `"512m"`), `disk_limit`. |
| `security` | SecurityPolicy | — | See [Security](#security). |
| `ports` | list of PortMapping | — | `- { host: 8080, container: 80, protocol: tcp }`. |
| `volumes` | list of Volume | — | See [Volumes](#volumes). |
| `files` | list of GeneratedFile | — | Config files written before create: `{ path, content, overwrite }`. `path` must sit under a declared bind mount. |
| `environment` | list of string | — | `- KEY=value` pairs (static). |
| `health_check` | HealthCheck | — | `{ type, endpoint/path, interval, timeout, retries }`. `type` is free-form today; `http` is what the monitor exercises. |
| `devices` | list of string | — | Host device paths; must start with `/dev/`. |
| `interfaces` | map | — | Launch surfaces, keyed by name (`main`): `{ name, description, type, port, protocol, path }`. |
| `hooks` | LifecycleHooks | — | Allow-listed lifecycle hooks. See [Hooks](#hooks). |
| _anything else_ | — | — | Unknown keys are absorbed into an `extensions` map (serde flatten) and treated as transitional metadata — e.g. `container_name`, `metadata`, `category`, `bitcoin_integration`, `lightning_integration`. These are **not** typed schema; do not rely on them being validated. |
## `container:` (ContainerConfig)
Exactly **one** of `image` or `build` must be present (image XOR build).
| Field | Type | Notes |
|-------|------|-------|
| `image` | string | Registry reference. Pull source. |
| `image_signature` | string | Optional signature reference for image verification. |
| `pull_policy` | string | Default `if-not-present`. |
| `build` | BuildConfig | Local build: `{ context, dockerfile (default "Dockerfile"), tag, build_args }`. |
| `network` | string | Literal podman `--network` value (`archy-net`, `host`, a stack network, …). Omitted = rootless default isolated network. |
| `network_aliases` | list of string | Extra DNS names on `network` (podman `--network-alias`) — lets stack members answer to short baked-in hostnames (`api`, `minio`, `relay`). |
| `entrypoint` | list of string | Entrypoint override. |
| `custom_args` | list of string | Extra positional args appended after the image. |
| `derived_env` | list | `- { key, template }` — template rendered against host facts at apply time. The allow-list is exactly `{{HOST_IP}}`, `{{HOST_MDNS}}`, `{{DISK_GB}}`, `{{BITCOIN_HOST}}` (`DERIVED_PLACEHOLDERS`); an unknown name or unbalanced `{{` fails validation. `{{BITCOIN_HOST}}` resolves to whichever Bitcoin app is running (`bitcoin-knots` or `bitcoin-core`, defaulting to knots). Never hard-code host specifics. |
| `secret_env` | list | `- { key, secret_file }` — value read from `/var/lib/archipelago/secrets/<secret_file>` and injected as a **podman secret**, so it never appears in `podman inspect` or unit files. `secret_file` must be a bare filename (no `/`, no `..`). |
| `generated_secrets` | list | `- { name, kind }` — orchestrator materialises the secret on first use (0600, rootless service user, idempotent + self-healing). `kind ∈ hex16 | hex32 | base64 | bcrypt` (bcrypt writes `<name>` = hash and `<name>.pw` = plaintext). |
| `generated_certs` | list | `- { crt, key, common_name?, sans? }` — self-signed TLS materialised before create; CN/SANs rendered against host facts. |
| `data_uid` | string | `"UID:GID"` applied to the app's bind-mounted data dir before create (rootless subuid mapping, e.g. Postgres). |
## Security
```yaml
security:
readonly_root: true # default true
no_new_privileges: true # default true
capabilities: [CHOWN] # default [] (cap-drop ALL, add back only these)
network_policy: isolated # isolated | bridge | host (default isolated)
apparmor_profile: null # optional profile name
```
Validation (enforced at `AppManifest::validate()`):
- Capabilities must come from the reviewed allow-list (CHOWN, DAC_OVERRIDE,
FOWNER, NET_ADMIN, NET_BIND_SERVICE, NET_RAW, SETGID, SETUID, SYS_ADMIN).
- `network_policy` must be exactly `isolated`, `bridge`, or `host`.
- No `container:`/`ns:` network modes; devices must be `/dev/*`.
- Bind-mount sources are confined to `/var/lib/archipelago` (reviewed
exceptions: the rootless podman socket and dbus).
- `derived_env` templates may only use the placeholder allow-list;
`secret_env`/`generated_secrets` names must be bare filenames.
- Hook steps are validated against the hook allow-list (below).
## Volumes
```yaml
volumes:
- type: bind # bind | volume | tmpfs
source: /var/lib/archipelago/myapp/data
target: /data
options: [rw] # allow-list: rw, ro, z, Z, shared, …
- type: tmpfs
target: /tmp
tmpfs_options: "rw,noexec,nosuid,size=256m"
```
## Hooks
Declarative, allow-listed operations that run against the app's **own
container** — never the host (design: `manifest-hooks-design.md`).
```yaml
hooks:
post_install: # runs once after install, container running
- copy_from_host: # src relative to an allow-listed root (data dir / web-ui);
src: web-ui/nostr-provider.js # no absolute paths, no '..'
dest: /usr/share/nginx/html/nostr-provider.js
- exec: ["sh", "-c", "nginx -s reload"] # podman exec inside the container
pre_start: [] # reserved in the schema; executor not yet wired
```
## Installation semantics
The orchestrator compiles the manifest into a rootless Podman container that
survives backend restarts and reboots, and a level-triggered reconciler
converges drift every 30 seconds (`BootReconciler::DEFAULT_INTERVAL`).
Multi-container apps are sets of per-member manifests installed together via
the stack orchestrator (`api/rpc/package/stacks.rs`) on an app-local network.
**Quadlet is not the default path.** `config.use_quadlet_backends` defaults to
`false`, so ordinary apps still take the legacy `podman create + start` path;
the Quadlet-unit-under-`user.slice` backend is opt-in per node (config key or
`ARCHIPELAGO_USE_QUADLET_BACKENDS`) and stays behind the flag until the
lifecycle harness has gone green against it. Companion UI containers are the
exception that do use Quadlet today.
## Distribution
Manifests ship two ways:
1. **Signed catalog** (primary): `releases/app-catalog.json` embeds the full
manifest per app and carries an Ed25519 detached signature verified against
the pinned release-root anchor. Nodes overlay catalog manifests over disk
files — **catalog wins** for image-only apps; `apps/<id>/manifest.yml` on
disk remains the fallback and is still required for build-source apps.
2. **Decentralized marketplace**: Nostr NIP-78 discovery with DID-signed
manifests ([`marketplace-protocol.md`](marketplace-protocol.md)). Note the
marketplace uses its own flatter manifest schema, not this one.
## Minimal example
```yaml
app:
id: myapp
name: My App
version: 1.0.0
description: Does something useful
container:
image: docker.io/vendor/myapp:1.0.0
generated_secrets:
- { name: myapp-admin-password, kind: hex16 }
secret_env:
- { key: ADMIN_PASSWORD, secret_file: myapp-admin-password }
ports:
- { host: 8090, container: 8080 }
volumes:
- { type: bind, source: /var/lib/archipelago/myapp, target: /data, options: [rw] }
health_check:
type: http
path: /health
interfaces:
main:
type: ui
port: 8090
```
Validate with `scripts/validate-app-manifest.sh` and regenerate the catalog
with `scripts/generate-app-catalog.py` (drift-checked in CI by
`scripts/check-app-catalog-drift.py`).
docs/architecture.md
+232
View File
@@ -0,0 +1,232 @@
# Archipelago — Architecture
> **Bitcoin Node OS** — Flash to USB, install on hardware, manage via web UI.
**Stack**: Rust backend + Vue 3 + TypeScript (strict) + Vite + Tailwind CSS + Pinia + rootless Podman (Quadlet)
**Target OS**: Debian 13 (Trixie) — x86_64 and ARM64
**Status**: 1.8.0-alpha — single-node production gate green; multinode pass + release hardening in progress (see [`ROADMAP.md`](ROADMAP.md))
---
## System Layers
```
┌──────────────────────────────────────────────────────┐
│ YOUR BROWSER │
│ Vue 3 SPA (Composition API + Pinia) │
└──────────────────────┬───────────────────────────────┘
│ HTTP / WebSocket
┌──────────────────────┴───────────────────────────────┐
│ NGINX │
│ /rpc/v1 → backend /app/{id}/ → container │
└──────────────────────┬───────────────────────────────┘
│ port 5678 (127.0.0.1)
┌──────────────────────┴───────────────────────────────┐
│ RUST BACKEND (core/) │
│ Auth, ~380 RPC methods, orchestrator + reconciler, │
│ federation, mesh, identity, wallet, updates │
└──────────────────────┬───────────────────────────────┘
│ Podman REST API socket + systemd Quadlet units
┌──────────────────────┴───────────────────────────────┐
│ ROOTLESS PODMAN CONTAINERS │
│ 50+ manifest-driven apps the orchestrator owns and │
│ self-heals; companion UIs run as systemd Quadlet │
└──────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────┐
│ DEBIAN 13 (Trixie) │
│ systemd, UFW, Tor, AppArmor, Reticulum daemon │
└──────────────────────────────────────────────────────┘
```
## Codebase Stats
| Component | Lines | Files |
|-----------|-------|-------|
| Rust backend (`core/`) | ~117,000 | ~334 |
| TypeScript/Vue (`neode-ui/src/`) | ~69,000 | ~325 |
| Shell scripts (`scripts/`) | — | ~51 |
| Packaged apps (`apps/*/manifest.yml`) | — | 51 |
## Backend Crates (`core/`)
Workspace members (root `core/Cargo.toml`):
| Crate | Purpose |
|-------|---------|
| `archipelago` | Main binary — API (~380 RPC methods), container orchestrator + boot reconciler, mesh, identity/federation, wallet, updates, marketplace |
| `container` (`archipelago-container`) | Podman REST client, canonical manifest schema, Quadlet compiler, health monitor, signed app catalog, image verification |
| `security` (`archipelago-security`) | AppArmor/seccomp container policy generation, secrets manager |
| `openwrt` (`archipelago-openwrt`) | TollGate gateway provisioning over SSH/UCI |
| `performance` (`archipelago-performance`) | Resource limits |
Also on disk but **not** workspace members (standalone/legacy, cleanup tracked in the hardening plan §G): `models`, `helpers`, `js-engine`, `container-init`.
### Key Backend Modules
```
core/archipelago/src/
├── api/handler/ — HTTP routing (/rpc, /health, /dwn, /ws)
├── api/rpc/dispatcher.rs — RPC dispatch (~380 method arms)
├── api/rpc/package/ — App install/lifecycle/stacks (multi-container)
├── container/ — prod_orchestrator, boot_reconciler, quadlet,
│ app_catalog (signed, embedded manifests),
│ version_config, crash_recovery, secrets
├── trust/ — release-root anchor (pinned Ed25519 pubkey),
│ detached-signature verify, did:key
├── mesh/ — Meshtastic + MeshCore + Reticulum transports,
│ X3DH/double-ratchet crypto, outbox/scheduler,
│ mesh AI assistant, bitcoin relay
├── federation/ — multi-node federation over Tor, state sync
├── identity.rs / identity_manager.rs — Ed25519 did:key, multi-identity
├── credentials/ — W3C Verifiable Credentials
├── nostr_discovery.rs — Nostr presence (NIP-33 kind 30078)
├── nostr_handshake.rs — NIP-44 encrypted peer comms
├── marketplace.rs — decentralized app marketplace (Nostr NIP-78,
│ DID-signed manifests, trust scoring)
├── wallet/ — LND integration, ecash (Fedimint/Cashu)
├── update.rs — signed OTA: resumable download, rollback,
│ post-update self-verify window
├── session.rs / auth.rs — sessions (persisted), Argon2id, TOTP
├── transport/ / network/ — Tor transport, DWN store/sync
└── fips/ / swarm/ / streaming/ — federation IPS anchor, P2P swarm (gated), streaming (WIP)
```
## App Platform (as built)
An app is a directory `apps/<id>/manifest.yml` parsed by the canonical schema
in `core/container/src/manifest.rs`. A manifest declares identity, a container
source (**image XOR build**), and runtime shape: ports, volumes (confined to
`/var/lib/archipelago`), generated config files, environment, devices,
resources, health checks, and the launch interface. Ergonomics are declarative
too: `derived_env` (host-fact templating), `secret_env` (podman secrets — values
never appear in `podman inspect` or unit files), `generated_secrets` /
`generated_certs` (self-healing), `network_aliases`, `data_uid`, and
allow-listed `post_install` hooks that run inside the app's own sandbox.
**Install** creates a rootless container the orchestrator owns; the companion
UI containers run as systemd **Quadlet units under `user.slice`** (the
validated path being flipped to default for all apps), so those survive backend
restarts and reboots outright, and the reconciler rebuilds any container that
vanishes. Multi-container apps (BTCPay, Mempool, Immich, NetBird, IndeeHub) are sets of
per-member manifests installed via the stack orchestrator on an app-local
network with readiness gates and generated cross-service secrets. A
level-triggered **boot reconciler** converges actual state to desired state
every 30 seconds.
**Distribution**: the signed catalog (`releases/app-catalog.json`, Ed25519
detached signature over canonical JSON, verified against the pinned
release-root anchor in `trust/anchor.rs`) embeds the full manifest per app;
nodes overlay catalog manifests over disk files (catalog wins), so apps can
ship without OTA disk files. A curated subset (27 apps) powers the store UI
(`app-catalog/catalog.json`). A parallel **decentralized marketplace**
(Nostr NIP-78 discovery, DID-signed manifests, federation-weighted trust
scoring, Lightning purchase invoices) is implemented as a second,
community-distribution channel.
**Security invariants** enforced at manifest validation: read-only root and
no-new-privileges by default, capability allow-list, `network_policy ∈
{isolated, bridge, host}`, bind mounts confined to `/var/lib/archipelago`, no
privileged containers, rootless only.
## Frontend (`neode-ui/src/`)
```
├── api/ — RPC client, WebSocket, container client
├── views/ — Dashboard, Apps, Marketplace, Cloud, Server,
│ Mesh, Web5, Settings, Monitoring, Fleet, Chat,
│ onboarding flow (11 screens), kiosk, recovery
├── components/ — EasyHome, ModeSwitcher, BootScreen, SpotlightSearch, …
├── stores/ — Pinia: app, install, mesh, cloud, goals, uiMode,
│ controller (gamepad), aiPermissions, …
├── composables/ — useControllerNav, useToast, useNavSounds, …
├── router/ — ~51 routes
└── style.css — global glassmorphism theme
```
Three UI modes (Pro/Easy/Chat), gamepad navigation, i18n, PWA. Tested with
Vitest + Playwright. AIUI is a separate external app surfaced via nginx.
## Mesh Networking
Three LoRa transports behind one chat UI and a common `MeshRadioDevice`
surface:
- **Meshtastic** — in-process async serial driver (protobuf over SLIP)
- **MeshCore** — framed-serial protocol; phone companion apps speak this
- **Reticulum (RNS/LXMF)** — host-supervised Python daemon
(`reticulum-daemon/`, PyInstaller-packaged, one per RNode radio) speaking
Unix-socket JSON-RPC to the backend; `archy-rnodeconf` ships as an OS-level
radio config tool
End-to-end encryption uses X3DH key agreement + double-ratchet. Extras: image
and voice attachments, mesh AI assistant (`!ai`), Bitcoin balance relay over
mesh, steganography, store-and-forward outbox.
## Networking
- **Container DNS**: app-local Podman networks with `network_aliases`; aardvark-dns resolution
- **Tor**: system daemon, SOCKS5 on 9050, hidden services per node; all inter-node federation traffic
- **Federation**: invite-based joining, DID-based trust levels, state sync, cross-node app deploy
- **UFW**: `DEFAULT_FORWARD_POLICY="ACCEPT"` required for LAN container access
- **OpenWrt/TollGate**: gateway provisioning via the `openwrt` crate
## Security Model
| Layer | Measures |
|-------|----------|
| OS | Debian hardening, AppArmor, minimal packages |
| Nginx | CSP headers, rate limiting, auth_request, session validation |
| Backend | Input validation, CSRF, session auth, bind 127.0.0.1 only |
| Containers | Rootless Podman, cap-drop ALL + reviewed allow-list, readonly root, no-new-privileges, memory limits |
| Supply chain | Ed25519-signed release manifests + app catalog against a pinned release-root anchor; auto-apply refuses unsigned |
| Crypto | Ed25519 signatures, ChaCha20-Poly1305 encryption, Argon2id password hashing (transparent bcrypt upgrade), constant-time comparisons |
| Network | Tor hidden services, UFW firewall, SSRF prevention |
## Data Paths
| Data | Path |
|------|------|
| App data | `/var/lib/archipelago/{app-id}/` |
| Identity | `/var/lib/archipelago/identity/` |
| Multi-identity | `/var/lib/archipelago/identities/` |
| Federation | `/var/lib/archipelago/federation/` |
| DWN messages | `/var/lib/archipelago/dwn/messages/` |
| Credentials | `/var/lib/archipelago/credentials/` |
| Backups | `/var/lib/archipelago/backups/` (ChaCha20-Poly1305) |
| Secrets | `/var/lib/archipelago/secrets/{app-id}/` (0600, service-user-owned) |
| Sessions | `/var/lib/archipelago/sessions.json` |
| Marketplace cache | `/var/lib/archipelago/marketplace/` |
| Frontend | `/opt/archipelago/web-ui/` |
| Backend binary | `/usr/local/bin/archipelago` |
## Key Features (Working)
- 50+ containerized apps with one-click install/manage; full lifecycle matrix repeatedly green on real hardware
- Bitcoin Core **and** Knots with per-app version pinning and safe switching; LND + Core Lightning
- Multi-node federation with invite-based joining and trust levels
- W3C DID identity (did:key, DID Documents, Verifiable Credentials)
- Nostr: NIP-33 node discovery, NIP-44/NIP-04 encryption, NIP-07 signer bridge for iframe apps, relay hosting
- Decentralized marketplace (NIP-78 discovery, trust scoring, Lightning purchases)
- File sharing with access controls (free/peers-only/paid via LN, on-chain, ecash)
- Encrypted backups (Argon2 + ChaCha20-Poly1305)
- Health monitoring + level-triggered reconciler with tiered auto-restart
- Tri-protocol LoRa mesh (Meshtastic / MeshCore / Reticulum) with E2E crypto
- Signed OTA updates with rollback and post-update self-verification
- Three-mode UI (Pro/Easy/Chat), gamepad navigation, real-time WebSocket updates
- Bootable ISO installer (`image-recipe/`), Android companion app
## Further Documentation
| Doc | Purpose |
|-----|---------|
| [`ROADMAP.md`](ROADMAP.md) | Shipped / in-progress / planned |
| [`developer-guide.md`](developer-guide.md) | Dev setup, workflow, code conventions |
| [`api-reference.md`](api-reference.md) | RPC endpoint reference |
| [`app-developer-guide.md`](app-developer-guide.md) | Building and publishing apps |
| [`app-manifest-spec.md`](app-manifest-spec.md) | The `manifest.yml` schema |
| [`user-walkthrough.md`](user-walkthrough.md) | End-user installation and usage guide |
| [`troubleshooting.md`](troubleshooting.md) | Diagnostic scenarios and solutions |
| [`multi-node-architecture.md`](multi-node-architecture.md) | Federation protocol design |
| [`marketplace-protocol.md`](marketplace-protocol.md) | Decentralized app discovery via Nostr |
| [`archive/`](archive/) | Historical audits, session logs, shipped designs |
docs/archive/INSTALL-SCREENS-DESIGN.md
+117
View File
@@ -0,0 +1,117 @@
# Archipelago Installer — Screen Designs
Edit these screens to match your vision. I'll implement exactly what you specify.
Each screen is what the user sees at that moment on the console (80 columns wide).
Constraints: bash TUI only (no ncurses). ANSI colors available:
- `\033[1;37m` = bold white, `\033[1;33m` = bold yellow/orange
- `\033[32m` = green, `\033[31m` = red, `\033[37m` = dim gray
- `\033[0m` = reset. Box-drawing chars: ━ ─ │ ╭ ╮ ╰ ╯ ╔ ╗ ╚ ╝ █ ▓ ░ ▌▐
- Spinners possible: ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ or ◐◓◑◒ or |/-\
---
## Screen 1: Welcome / Press Enter
```
(clear screen, centered)
a r c h i p e l a g o
━━━━━━━━━━━━━━━━━━━━━
automatic installer
Press Enter to install | Ctrl+C for shell
```
---
## Screen 2: Detecting Disk
```
a r c h i p e l a g o
━━━━━━━━━━━━━━━━━━━━━
[1/7] Checking tools .............. ✓
[2/7] Detecting disks
Found: /dev/sda (465.8G) — TOSHIBA MQ01ACF0
──────────────────────────────────────────
⚠ All data on /dev/sda will be erased.
Press Enter to install | Ctrl+C to cancel
```
---
## Screen 3: Installing (progress)
```
a r c h i p e l a g o
━━━━━━━━━━━━━━━━━━━━━
[1/7] Checking tools .............. ✓
[2/7] Detecting disks ............. ✓
[3/7] Creating partitions ......... ✓
[4/7] Formatting .................. ✓
[5/7] Installing system ........... ✓
[6/7] Encrypting data partition ◐
AES-256-XTS (AES-NI detected)
──────────────────────────────────────────
```
---
## Screen 4: Bootloader
```
a r c h i p e l a g o
━━━━━━━━━━━━━━━━━━━━━
[1/7] Checking tools .............. ✓
[2/7] Detecting disks ............. ✓
[3/7] Creating partitions ......... ✓
[4/7] Formatting .................. ✓
[5/7] Installing system ........... ✓
[6/7] Encrypting data ............. ✓
[7/7] Installing bootloader ....... ✓
──────────────────────────────────────────
```
---
## Screen 5: Complete
```
a r c h i p e l a g o
━━━━━━━━━━━━━━━━━━━━━
Installation Complete
After reboot, open the Web UI from any device:
http://archipelago.local
SSH: ssh archipelago@archipelago.local
Password: archipelago
Web Login: password123
──────────────────────────────────────────
>>> REMOVE THE USB DRIVE NOW <<<
Press Enter to reboot
```
---
## Notes for Dorian
- Edit any screen above to match what you want to see
- Add/remove steps, change wording, change layout
- Specify colors per line if you want (e.g. "this line in yellow")
- I can add a spinner animation on the active step
- Box-drawing, progress bars, anything bash can render is fair game
- Once you're happy with the designs I'll implement them exactly
docs/archive/README.md
+22
View File
@@ -0,0 +1,22 @@
# docs/archive — historical records
Documents here are **finished history**: completed session logs, handovers,
point-in-time status snapshots, security audits of past versions, and design
docs whose feature has since shipped. They are kept for provenance and are
**not** maintained — nothing in this directory describes the current system.
For current state, start at:
- `docs/architecture.md` — as-built system architecture
- `docs/ROADMAP.md` — public-facing roadmap
| File | What it was | Why archived |
|------|-------------|--------------|
| `rust-orchestrator-migration.md` | Design for migrating container lifecycle from bash to Rust | Migration complete — `prod_orchestrator.rs` + `boot_reconciler.rs` are the live system |
| `demo-deployment-design.md` | Design for the public demo sandbox | Demo shipped; `docs/demo-build-info.md` is the live ops doc |
| `app-registry-status-2026-06-21.md` | Per-app migration snapshot from node .228 @ v1.7.99-alpha | Point-in-time snapshot; headline findings (immich legacy, meshtastic present) no longer true |
| `security-code-audit-2026-03.md` | March 2026 security audit of v0.1.0 (33 findings) | Historical record; top findings since remediated (Argon2id, persisted sessions, image verification) |
| `INSTALL-SCREENS-DESIGN.md` | Installer screen design solicitation | Installer implemented in `image-recipe/` |
| `three-mode-ui-design.md` | Design for the Pro/Easy/Chat three-mode UI | Fully implemented (`stores/uiMode.ts`, `EasyHome.vue`, `Chat.vue`, goals system) |
| `HANDOVER-2026-07-02-iso-feedback.md` | Session handover from the 2026-07-02 ISO feedback bug-bash | Completed session log |
| `SESSION-1.8.0-OTA-PROGRESS.md` | Working notes from the 1.8.0 OTA push | Completed session log |
docs/archive/app-registry-status-2026-06-21.md
+153
View File
@@ -0,0 +1,153 @@
# Archipelago App Registry — Status Survey
**Generated:** 2026-06-21 · **Survey node:** .228 (archi resilience node, 14-app) · **Binary:** v1.7.99-alpha
This document inventories every app in the registry and reports, per app:
manifest-based or not · installed on .228 · migration status (Quadlet/legacy) ·
automated test coverage / release-gate status.
---
## 1. Architecture context — "manifest-based or not"
**Every registry app is manifest-based.** That is the core architecture
(Pillar 4, *data-driven apps*): install/uninstall needs only the app's
`manifest.yml` + catalog entry — no host OS changes, no archipelago binary code
per app. The live registry on .228 is **40 loaded manifests**
(`Loaded 40 app manifest(s) from disk`).
The **only** non-manifest runtime units are:
- **4 companions** — `archy-bitcoin-ui`, `archy-lnd-ui`, `archy-electrs-ui`,
`archy-fedimint-ui`. Built from `docker/<name>` contexts via
`core/archipelago/src/container/companion.rs`, *not* the manifest registry.
- **Stack sub-containers** — `immich_*`, `indeedhub-*`, `netbird-*`. Spawned by
their parent manifest app.
---
## 2. Migration status (Quadlet-everywhere — Pillar 1)
"Migrated" = runs as a **Quadlet unit under `user.slice`**, so it survives an
`archipelago.service` restart (legacy in-cgroup containers get SIGKILLed on
restart and reconciled back).
On .228 migration is **effectively complete** — every installed app is
`QUADLET:running` **except one**:
| Status | Apps |
|---|---|
| ✅ Migrated (Quadlet / user.slice) | bitcoin-knots, electrumx, lnd, fedimint, fedimint-clientd, fedimint-gateway, btcpay-server (+archy-btcpay-db, archy-nbxplorer), mempool, mempool-api, archy-mempool-db, indeedhub (+7 sub-containers), netbird (+server, +dashboard), vaultwarden, jellyfin, filebrowser, portainer, botfights, nostr-rs-relay, homeassistant, + 4 companions |
| ⚠️ NOT migrated (legacy, service cgroup) | **immich_server** — still in `/system.slice/archipelago.service`. The only legacy holdout. (`immich_postgres`/`immich_redis` are pod members.) |
---
## 3. Exhaustive per-app registry table
| App (registry id) | Manifest | Installed on .228 | Migration | Test coverage |
|---|---|---|---|---|
| bitcoin-knots | yes | ✅ | QUADLET | **L1 RPC ●**, L2 UI ● |
| bitcoin-core | yes | ✗ (shares knots) | — | ◐ regression-gate |
| lnd | yes | ✅ | QUADLET | **L1 RPC ●**, L2 ● |
| electrumx | yes | ✅ | QUADLET | **L1 RPC ●**, L2 ● |
| btcpay-server | yes | ✅ | QUADLET | **L1 RPC ●**, L2 ● |
| mempool | yes | ✅ | QUADLET | **L1 RPC ●**, L2 ● |
| mempool-api | yes | ✅ | QUADLET | via mempool stack |
| archy-mempool-db | yes | ✅ | QUADLET | via mempool stack |
| archy-mempool-web | yes | ✗ | — | via mempool stack |
| archy-btcpay-db | yes | ✅ | QUADLET | via btcpay stack |
| archy-nbxplorer | yes | ✅ | QUADLET | via btcpay stack |
| fedimint (Guardian) | yes | ✅ | QUADLET | L1 ◐ container-only, L2 ● |
| fedimint-clientd | yes | ✅ | QUADLET | none |
| fedimint-gateway | yes | ✅ (this session) | QUADLET | none |
| filebrowser | yes | ✅ | QUADLET | L2 probe-only |
| indeedhub | yes | ✅ | QUADLET | none |
| jellyfin | yes | ✅ | QUADLET | none |
| vaultwarden | yes | ✅ | QUADLET | none |
| portainer | yes | ✅ | QUADLET | none |
| botfights | yes | ✅ | QUADLET | none |
| nostr-rs-relay | yes | ✅ | QUADLET | none |
| home-assistant | yes | ✅ (container `homeassistant`) | QUADLET | none |
| netbird | yes | ✅ (+server, +dashboard) | QUADLET | none |
| immich | yes | ✅ | ⚠️ **LEGACY** | none |
| grafana | yes | ✗ (unit *activating*, no container) | staged | none |
| strfry | yes | ✗ (unit *activating*) | staged | none |
| ~~onlyoffice~~ | — | removed 2026-06-21 | — | — |
| aiui | yes | ✗ | — | none |
| core-lightning | yes | ✗ | — | none |
| did-wallet | yes | ✗ | — | none |
| gitea | yes | ✗ | — | none |
| lightning-stack | yes | ✗ | — | none |
| meshtastic | yes | ✗ | — | none |
| morphos-server | yes | ✗ | — | none |
| nextcloud | yes | ✗ | — | none |
| photoprism | yes | ✗ | — | none |
| router | yes | ✗ | — | none |
| searxng | yes | ✗ | — | none |
| uptime-kuma | yes | ✗ | — | none |
| bitcoin-ui | yes | runs as companion `archy-bitcoin-ui` | QUADLET (companion) | L3 companions ● |
| lnd-ui | yes | runs as companion `archy-lnd-ui` | QUADLET (companion) | L3 companions ● |
| electrs-ui | yes | runs as companion `archy-electrs-ui` | QUADLET (companion) | L3 companions ● |
| fips-ui | yes | ✗ | — | none |
Notes:
- `home-assistant` (registry id) runs as container **`homeassistant`** — the
app-id ≠ container-name. A duplicate `home-assistant.service` quadlet unit
sits in *activating*; the live container is `homeassistant` (Up 6 days, healthy).
- `grafana` / `strfry` have Quadlet `.container` units but the units are stuck
*activating* with **no running container** — staged, not live. Worth a
separate investigation.
- `onlyoffice` was **removed from the registry on 2026-06-21**.
---
## 4. Test-gate reality
**No app has passed the formal release gate.** The gate is `run-gate.sh` green
across the full lifecycle matrix (install / UI reachable / stop / start /
restart / reinstall / reboot-survive / archipelago-restart-survive / uninstall),
**5× on .228 AND .198**. All 8 release-gate checkboxes in
`tests/lifecycle/TESTING.md` are **unchecked (☐)**.
What exists today:
| Layer | Status |
|---|---|
| L0 unit | 631 tests ● green |
| L1 RPC | ● for **6 core apps only**: bitcoin-knots, lnd, electrumx, btcpay, mempool, fedimint |
| L2 UI | ● dashboard + 7 proxy paths + bitcoin-ui:8334 |
| L3 lifecycle survival | companions ● ; backends ◐ (regression-gate only — fails until Phase-3 Quadlet flag flips by default) |
| Per-app L1+L2 matrix | **50 of 110 cells** |
| L4 browser / L5 chaos / L6 perf | ○ 0 — not started |
Regression suites added after v1.7.90-alpha (run read-only, abort releases on
failure): `bitcoin-receive.bats`, `port-drift.bats`, `secret-completeness.bats`.
**The other ~30 registry apps have zero automated coverage.**
---
## 5. Key gaps
1. **immich** is the last legacy (in-cgroup) app — migrate to Quadlet to finish Pillar 1.
2. **grafana / strfry** Quadlet units stuck *activating* with no container — investigate. (onlyoffice removed 2026-06-21.)
3. **fedimint-gateway / fedimint-clientd** (this session) now run but have no lifecycle test coverage.
4. The formal **5× release gate has never been green** — it is the blocker for the v1.7.52 tag.
---
## 6. This session's changes (2026-06-21)
- **Generated-secrets system** deployed to .228 (binary + manifests). Self-healing:
the root-owned `fedimint-gateway-hash` was regenerated archipelago-owned/readable
→ **fedimint-gateway now starts** (gatewayd webserver up on :8176). `fmcd-password`
generated for fedimint-clientd.
- **Guardian-UI CSS fix** applied on .228: rebuilt the stale `localhost/fedimint-ui:latest`
companion image (built 2026-06-12, pre-fix) from the corrected context
(`@guardian_assets` proxy fallback to :8177). Guardian's own CSS
(`/assets/bootstrap.min.css`, `/assets/style.css`) **404 → 200 text/css**.
Root cause: `companion.rs::ensure_image_present` skips rebuild when the
`:latest` image already exists, so the context fix never re-baked.
*Survey method: live `podman` cgroup inspection on .228 + `/opt/archipelago/apps`
manifest enumeration + `tests/lifecycle/TESTING.md`.*
docs/archive/demo-deployment-design.md
+168
View File
@@ -0,0 +1,168 @@
# Public Demo Deployment — Design
**Status:** design (2026-06-22)
**Goal:** a public, click-to-play demo of the Archipelago UI that **auto-tracks
the real code** yet stays **separated** from the private monorepo and its
secrets/backend. Deployed via **Portainer**, mock-data driven, with working file
storage and a testnet-flavored Bitcoin sandbox so visitors can play freely.
See also: `neode-ui/mock-backend.js` (existing mock), `docker-compose.demo.yml`
(existing demo stack).
---
## 1. What already exists (the 70%)
The demo is mostly built. Inventory:
| Asset | Path | State |
|-------|------|-------|
| Mock backend (Node/Express + ws) | `neode-ui/mock-backend.js` (~3,862 lines) | 95+ JSON-RPC methods: auth, package lifecycle, Bitcoin/LND wallet, mesh, federation, identity, monitoring, mock filebrowser |
| Mock data | `mockData` / `walletState` / `MOCK_FILES` in `mock-backend.js` | rich; 10 pre-installed apps, 30+ marketplace apps, wallet balances, seeded files (Music/Documents/Photos/Videos) |
| Demo compose | `docker-compose.demo.yml` | `neode-backend` (mock, `:5959`) + `neode-web` (nginx, `:4848`); header already says "Deploy via Portainer" |
| Backend image | `neode-ui/Dockerfile.backend` | Node 22 Alpine → `node mock-backend.js` |
| Web image | `neode-ui/Dockerfile.web` | multi-stage `vite build` → nginx |
| Demo nginx | `neode-ui/docker/nginx-demo.conf` | proxies `/rpc/v1`, `/ws`, `/app/*` to the mock backend |
| Precedent | `indee-demo` Portainer stack | separate stack referencing a **pre-built image** — the pattern we extend |
**Gaps for a *public* (not dev) demo:** state is global (visitors collide),
uploads are no-ops, Bitcoin block height is hardcoded, no CI image pipeline, no
separated public deploy repo.
---
## 2. Architecture: source in monorepo, demo ships as images, public repo is thin
The tension — "must update as I update the real code" **and** "sort of
separated" — is resolved by separating at the **deploy layer, not the source
layer**.
```
monorepo (private — single source of truth)
neode-ui/ + mock-backend.js
│ push to main
▼
CI: build archy-demo-web + archy-demo-backend
│ push :demo / :latest
▼
registry (source.archipelago-foundation.org / vps2)
│ Portainer webhook / re-pull
▼
archy-demo (public repo — tiny)
docker-compose.yml ──referencing pre-built images──▶ Portainer ▶ demo.<host>
.env.example
```
- **Single source of truth = the monorepo.** `neode-ui/` and `mock-backend.js`
stay where they are, so the demo tracks real code automatically — no fork to
sync, no drift.
- **Separation = the public repo never holds source.** `archy-demo` contains only
a `docker-compose.yml` (image refs) + `.env.example` + README. No Rust backend,
no secrets, no UI source. Safe to make public.
- **Auto-update flow:** edit code → push → CI rebuilds demo images → Portainer
redeploys. The public compose file is touched rarely (only when service shape
changes).
**Why not a true fork / `git subtree split`?** It works but needs a sync job
*and* re-exposes UI source publicly. The image pipeline gives stronger
separation (zero source leak) **and** zero manual sync. (Decided 2026-06-22.)
---
## 3. Work items
### 3.1 CI image pipeline
- On push to `main` (path filter: `neode-ui/**`), build:
- `archy-demo-backend` from `neode-ui/Dockerfile.backend`
- `archy-demo-web` from `neode-ui/Dockerfile.web` (`build:docker`)
- Tag `:demo` + `:<git-sha>`, push to the registry.
- Trigger Portainer redeploy (stack webhook) on success.
### 3.2 Public `archy-demo` repo
- `docker-compose.yml` mirroring `docker-compose.demo.yml` but **`image:`
references instead of `build:`** (pull `:demo`, no build context).
- `.env.example` (`ANTHROPIC_API_KEY`, `VITE_DEV_MODE=existing`, session TTL,
upload quota).
- README: one-paragraph "deploy in Portainer → web editor paste / deploy from
repo," access on `:4848`.
- No source. This is the only public surface.
### 3.3 Multi-user: per-session sandbox (reset on idle) ⟵ *decided*
The biggest code change. Today `mockData` / `walletState` / `MOCK_FILES` are
**global singletons** → visitors corrupt each other's view.
- Issue a `demo-session` cookie on first hit (the mock already sets a session on
login; extend it to anonymous visitors).
- Key state by session id: `sessions[sid] = { mockData, walletState, files }`,
each **deep-cloned from a pristine seed** on creation.
- Reap on idle (e.g. 30 min no activity) + hard cap concurrent sessions; on reap,
free memory + temp dir.
- RPC dispatch + WS patches resolve the per-session state instead of the global.
- Keeps the demo a true playground: install/uninstall/spend freely, reset by
reconnecting.
### 3.4 File storage: persisted per session ⟵ *decided*
Today filebrowser upload/delete/rename are 200-OK no-ops.
- Back each session with a temp dir (e.g. `/tmp/demo/<sid>/`), seeded from
`MOCK_FILES`.
- Make `POST/DELETE/PATCH /app/filebrowser/api/resources/*` and `GET …/raw/*`
read/write that dir. Enforce a per-session quota (e.g. 50 MB) and reject
oversize/odd MIME.
- Cleaned when the session is reaped — no standing public writable volume, no real
filebrowser container to harden.
### 3.5 Bitcoin: testnet-flavored mock ⟵ *decided*
- Relabel wallet/chain as **testnet/signet**: `tb1q…` addresses, "testnet" chain
in `bitcoin.getinfo`, scripted-but-plausible block height + confirmations.
- Keep `dev.faucet` as the in-UI "get test sats" button (instant, free).
- No real `bitcoind` → no sync, no disk, no public RPC attack surface.
- *Future upgrade path:* swap to a real signet node + LND in the stack if we ever
want movable real test sats (out of scope now).
### 3.6 Mock containers / app lifecycle
- The mock already simulates `package.install/uninstall/start/stop/restart`
asynchronously. For the demo, **force simulation mode** (never touch a real
Docker socket — rootless/safe and host-independent). Confirm no path in
`mock-backend.js` reaches for a real runtime when `DEMO=1`.
### 3.7 Mock-data refresh
- Update `mockData` static apps + marketplace to current app set/versions, refresh
wallet figures, seeded mesh messages, and files so the demo feels current. This
is ongoing and rides the same image pipeline.
---
## 4. Invariants / guardrails (public exposure)
- **No real secrets, no real backend, no real Docker socket** in the demo image or
public repo. Mock password stays a known demo credential, clearly labeled.
- **Per-session isolation** is a hard requirement before going public — without it
the demo is unusable for strangers.
- **Resource caps:** session count, per-session memory + upload quota, idle reap;
the box can't be DoS'd into OOM by upload spam or session churn.
- **`ANTHROPIC_API_KEY`** (chat) is injected via Portainer env, never committed;
rate-limit / budget-cap demo chat usage.
- **Read-only registry creds** for the Portainer host to pull `:demo`.
---
## 5. Files / seams
| Concern | Where |
|---------|-------|
| Per-session state, file persistence, testnet labels, sim-mode | `neode-ui/mock-backend.js` |
| Build contexts (reused as-is) | `neode-ui/Dockerfile.backend`, `neode-ui/Dockerfile.web`, `neode-ui/docker/nginx-demo.conf` |
| Demo stack (in-repo, dev) | `docker-compose.demo.yml` (keep `build:`) |
| Public stack (new repo) | `archy-demo/docker-compose.yml` (`image:` refs), `.env.example`, README |
| CI pipeline | new workflow (path filter `neode-ui/**` → build + push `:demo` → Portainer webhook) |
---
## 6. Open questions
1. **Demo host** — which Portainer instance (OVH `.168`? a dedicated VPS)? Public
DNS + TLS for `demo.<domain>`?
2. **Registry for `:demo` images** — `source.archipelago-foundation.org` vs vps2; public-pull or
creds baked into Portainer?
3. **Session TTL + concurrency cap** — concrete numbers (30 min / N sessions / 50 MB)?
4. **Chat in the demo** — enable Claude chat (needs key + budget cap) or stub it?
5. **Sync cadence** — rebuild `:demo` on every `neode-ui/**` push, or nightly?
docs/archive/rust-orchestrator-migration.md
+525
View File
@@ -0,0 +1,525 @@
# Rust Orchestrator Migration — Design Doc
Status: **DRAFT — pending user approval**
Author: OpenCode session, 2026-04-22
Supersedes planning in `docs/bulletproof-containers.md` v1.7.43 slot
## Problem statement
Today, the archipelago backend has **no production container orchestrator**. Production containers (bitcoin-knots, lnd, electrumx, btcpay, filebrowser, and the three custom UIs archy-bitcoin-ui / archy-electrs-ui / archy-lnd-ui) are installed by **bash scripts** at first boot (`scripts/first-boot-containers.sh`) and optionally reconciled by another bash script (`scripts/reconcile-containers.sh`) that is **not enabled by default**. The existing `DevContainerOrchestrator` (`core/archipelago/src/container/dev_orchestrator.rs`) is hardcoded to append `-dev` suffixes and gated behind `config.dev_mode`, so it has never managed a production container.
This design migrates production container management into Rust, under a single orchestrator that owns install, start, stop, restart, upgrade, uninstall, health, and self-healing for every container. The three custom UI containers are the first-class test fixture: they exercise the "build image from local Dockerfile" path (which today doesn't exist in the manifest schema) and their lifecycle was the original failure class the user asked to fix.
## Non-goals
- Backwards compatibility with `first-boot-containers.sh`: we **delete** it and its systemd unit after verifying Rust parity.
- Backwards compatibility with the existing `package-install` RPC’s podman shell-outs: those get rewritten to call the orchestrator.
- Registry signature verification: `image_signature` stays optional. Sigstore/cosign integration is out of scope.
- Network isolation improvements: existing SecurityPolicy fields stay as-is.
- Dev mode removal: `DevContainerOrchestrator` keeps existing behavior for local development; prod code path is separate.
## Scope of this migration
In scope:
1. Extend `ContainerConfig` schema with a `source:` variant supporting `{type: build, context, dockerfile, tag}` alongside `{type: pull, image, pull_policy}`.
2. Extend `ContainerRuntime` trait + `PodmanRuntime` impl with `build_image(...)` and `image_exists(...)`.
3. Introduce `ProdContainerOrchestrator` (new type) with identical public surface to `DevContainerOrchestrator` but **no `-dev` suffix**, **no port offset**, **no data-path rewriting**, **no bitcoin_simulator gate**. It is wired into `RpcHandler::orchestrator` in prod (currently `None`).
4. Add `AdoptionScan` at orchestrator startup: enumerate `podman ps -a`, match by container name against declared manifests, adopt into orchestrator state without recreating.
5. Add `BootReconciler` task spawned from `main.rs` (replacing the commented-out `run_boot_reconciliation` hook). Walks the manifest set on startup and periodically, ensures each is present-and-running, builds/pulls/creates anything missing, logs failures non-silently.
6. Ship three manifests in the repo: `apps/bitcoin-ui/manifest.yml`, `apps/electrs-ui/manifest.yml`, `apps/lnd-ui/manifest.yml`. They use the new `source: build` variant pointing at `/opt/archipelago/docker/<name>/`.
7. Delete `scripts/first-boot-containers.sh`, `scripts/reconcile-containers.sh`, `scripts/container-specs.sh`, `image-recipe/configs/archipelago-first-boot-containers.service`, `image-recipe/configs/archipelago-reconcile.service`. Remove enablement from ISO builder.
Out of scope this migration (tracked separately):
- Migrating btcpay / mempool / fedimint multi-container stacks to manifests (they currently live in `core/archipelago/src/api/rpc/package/stacks.rs`). They keep working via `package-install` RPC. Phase 2.
- Rewriting the 26 existing `apps/*/manifest.yml` files to use the new `source:` schema. They stay on `image:` for now; the schema is **additive and backwards-compatible**.
- Re-enabling signature verification; stays todo.
## Data model changes
### 1. `ContainerConfig` gets a `source` enum
File: `core/container/src/manifest.rs:58`
**Before:**
```rust
pub struct ContainerConfig {
pub image: String,
pub image_signature: Option<String>,
pub pull_policy: String,
}
```
**After:**
```rust
pub struct ContainerConfig {
// Legacy shorthand (backwards compatible with all 26 existing manifests):
// if `source` is absent, `image` + `pull_policy` are interpreted as
// `source: { type: pull, image, pull_policy }`.
#[serde(default)]
pub image: String,
#[serde(default)]
pub image_signature: Option<String>,
#[serde(default = "default_pull_policy")]
pub pull_policy: String,
// New: explicit source. If present, overrides the legacy shorthand.
#[serde(default)]
pub source: Option<ContainerSource>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "lowercase")]
pub enum ContainerSource {
/// Pull an image from a registry.
Pull {
image: String,
#[serde(default)]
image_signature: Option<String>,
#[serde(default = "default_pull_policy")]
pull_policy: String,
},
/// Build an image from a local Dockerfile.
Build {
/// Filesystem path to build context, absolute or relative to manifest dir.
context: String,
/// Dockerfile path relative to context. Defaults to "Dockerfile".
#[serde(default = "default_dockerfile")]
dockerfile: String,
/// Tag to assign to the built image, e.g. "localhost/bitcoin-ui:local".
tag: String,
/// `--build-arg` key=value pairs.
#[serde(default)]
build_args: HashMap<String, String>,
/// If true, rebuild on every reconcile. If false, only build when tag is missing.
#[serde(default)]
always_rebuild: bool,
},
}
```
Validation in `AppManifest::validate`:
- If `source` is absent AND `image` is empty → error (unchanged rule just rephrased).
- If `source` is present, legacy `image` field is ignored with a warning.
- `Build::context` must resolve to an existing directory that contains `dockerfile`.
Tests to add:
- Parse a legacy manifest → works, produces `ContainerSource::Pull` at resolution time.
- Parse a `source: { type: build, ... }` manifest → works.
- Parse a manifest with both legacy `image:` and `source:` → warning logged, `source:` wins.
- Parse a manifest with neither → rejected.
### 2. `ContainerRuntime` trait gets `build_image` + `image_exists`
File: `core/container/src/runtime.rs:10`
```rust
#[async_trait]
pub trait ContainerRuntime: Send + Sync {
// existing methods unchanged...
async fn pull_image(&self, image: &str, signature: Option<&str>) -> Result<()>;
async fn create_container(...) -> Result<()>;
// ...
// NEW:
/// Build an image from a local Dockerfile. Returns Ok(()) if the image now
/// exists under the given tag (whether newly built or already present and
/// `force=false`). Returns Err if the build failed.
async fn build_image(
&self,
context: &Path,
dockerfile: &str,
tag: &str,
build_args: &HashMap<String, String>,
force: bool,
) -> Result<()>;
/// Check if an image exists in the local image store.
async fn image_exists(&self, tag: &str) -> Result<bool>;
}
```
`PodmanRuntime::build_image` shells out:
```
podman build --tag <tag> \
--file <context>/<dockerfile> \
--build-arg KEY=VALUE ... \
<context>
```
Force-rebuild semantics: if `force=false`, skip when `image_exists(tag) == true`. If `force=true`, always build (podman's own layer cache handles the fast path).
Tests:
- `build_image` happy path on a minimal Dockerfile (using a throwaway context in tmpdir).
- `build_image` failure path (nonsense Dockerfile) → Err.
- `image_exists` returns false for nonexistent tag.
- `image_exists` returns true after `build_image`.
### 3. Manifest resolution: `ContainerSource::resolve(manifest_dir) -> ResolvedSource`
New method that turns the raw manifest into something the orchestrator can act on:
```rust
pub enum ResolvedSource {
Pull { image: String, signature: Option<String>, pull_policy: PullPolicy },
Build { context: PathBuf, dockerfile: String, tag: String, build_args: HashMap<String,String>, always_rebuild: bool },
}
impl ContainerConfig {
pub fn resolve(&self, manifest_dir: &Path) -> Result<ResolvedSource> {
match &self.source {
Some(ContainerSource::Pull { image, image_signature, pull_policy }) => Ok(ResolvedSource::Pull { ... }),
Some(ContainerSource::Build { context, dockerfile, tag, build_args, always_rebuild }) => {
let abs_context = if Path::new(context).is_absolute() {
PathBuf::from(context)
} else {
manifest_dir.join(context)
};
Ok(ResolvedSource::Build { context: abs_context, ... })
}
None => {
// Legacy shorthand
if self.image.is_empty() {
return Err(...);
}
Ok(ResolvedSource::Pull { image: self.image.clone(), ... })
}
}
}
}
```
## Runtime architecture
### `ProdContainerOrchestrator`
New file: `core/archipelago/src/container/prod_orchestrator.rs`
```rust
pub struct ProdContainerOrchestrator {
runtime: Arc<dyn ContainerRuntimeTrait>,
manifests_dir: PathBuf, // e.g. /opt/archipelago/apps
data_dir: PathBuf, // e.g. /var/lib/archipelago
state: Arc<RwLock<OrchestratorState>>,
config: Config,
}
struct OrchestratorState {
/// app_id → known manifest (loaded from disk at startup, refreshed on reconcile)
manifests: HashMap<String, AppManifest>,
/// app_id → current known state (from adoption scan or our own ops)
containers: HashMap<String, ContainerState>,
/// app_id → last install/health/build timestamp
last_reconciled: HashMap<String, Instant>,
}
```
Public surface mirrors `DevContainerOrchestrator` but **container name = `archy-<app_id>` for UI apps, `<app_id>` for backends, matching existing .116 naming**:
```rust
impl ProdContainerOrchestrator {
pub async fn new(config: Config) -> Result<Self> { ... }
pub async fn load_manifests(&self) -> Result<()> { /* walks manifests_dir */ }
pub async fn adopt_existing(&self) -> Result<AdoptionReport> { /* scans podman ps -a */ }
pub async fn reconcile_all(&self) -> Result<ReconcileReport> { /* ensures every manifest has a running container */ }
pub async fn install(&self, app_id: &str) -> Result<()> { /* build-or-pull + create + start */ }
pub async fn start(&self, app_id: &str) -> Result<()> { ... }
pub async fn stop(&self, app_id: &str) -> Result<()> { ... }
pub async fn restart(&self, app_id: &str) -> Result<()> { ... }
pub async fn remove(&self, app_id: &str, preserve_data: bool) -> Result<()> { ... }
pub async fn upgrade(&self, app_id: &str) -> Result<()> { /* re-read manifest, rebuild/pull, recreate */ }
pub async fn status(&self, app_id: &str) -> Result<ContainerStatus> { ... }
pub async fn list(&self) -> Result<Vec<ContainerStatus>> { ... }
pub async fn logs(&self, app_id: &str, lines: u32) -> Result<Vec<String>> { ... }
pub async fn health(&self, app_id: &str) -> Result<String> { ... }
}
```
**Container naming rule** (matches `.116` existing fixture so adoption works):
- If the manifest has `extensions["container_name"]` → use that verbatim.
- Else if the app_id starts with `bitcoin-ui` / `electrs-ui` / `lnd-ui` → `archy-<app_id>`.
- Else → `<app_id>`.
This is codified and tested; no ad-hoc naming in the codebase.
### `AdoptionScan`
On orchestrator startup, before any reconcile:
```rust
async fn adopt_existing(&self) -> Result<AdoptionReport> {
let all = self.runtime.list_containers().await?; // podman ps -a
let mut report = AdoptionReport::default();
for c in all {
// For each manifest we have loaded, check if the expected container name matches
for (app_id, manifest) in self.state.read().await.manifests.iter() {
let expected_name = compute_container_name(manifest);
if c.name == expected_name {
// This container is ours. Record its state.
self.state.write().await.containers.insert(app_id.clone(), c.state.clone());
report.adopted.push(app_id.clone());
}
}
}
Ok(report)
}
```
No recreate. No touching data volumes. Just "we now know this container belongs to app X and its current state is Y".
### `BootReconciler`
New file: `core/archipelago/src/container/boot_reconciler.rs`
```rust
pub struct BootReconciler {
orchestrator: Arc<ProdContainerOrchestrator>,
interval: Duration, // e.g. 5 minutes
shutdown: CancellationToken,
}
impl BootReconciler {
pub async fn run_forever(self) {
// Initial reconcile immediately (after adoption).
let _ = self.orchestrator.reconcile_all().await;
loop {
tokio::select! {
_ = tokio::time::sleep(self.interval) => {
let _ = self.orchestrator.reconcile_all().await;
}
_ = self.shutdown.cancelled() => break,
}
}
}
}
```
`reconcile_all`:
```rust
async fn reconcile_all(&self) -> Result<ReconcileReport> {
let manifests: Vec<_> = self.state.read().await.manifests.values().cloned().collect();
let mut report = ReconcileReport::default();
for manifest in manifests {
let app_id = &manifest.app.id;
match self.ensure_running(&manifest).await {
Ok(action) => report.record(app_id, action),
Err(e) => {
tracing::error!(app_id, error = %e, "Reconcile failed for app");
report.failures.push((app_id.clone(), e.to_string()));
}
}
}
if !report.failures.is_empty() {
// Surface via WebSocket so the UI can show a banner.
self.notify_failures(&report).await;
}
Ok(report)
}
async fn ensure_running(&self, manifest: &AppManifest) -> Result<ReconcileAction> {
let name = compute_container_name(manifest);
match self.runtime.get_container_status(&name).await {
Ok(status) if matches!(status.state, ContainerState::Running) => Ok(ReconcileAction::NoOp),
Ok(status) if matches!(status.state, ContainerState::Exited | ContainerState::Stopped) => {
self.runtime.start_container(&name).await?;
Ok(ReconcileAction::Started)
}
Ok(_) => Ok(ReconcileAction::NoOp), // Created / Paused — leave alone
Err(_) => {
// Container doesn't exist. Install it.
self.install_fresh(manifest).await?;
Ok(ReconcileAction::Installed)
}
}
}
async fn install_fresh(&self, manifest: &AppManifest) -> Result<()> {
let manifest_dir = ...; // directory of manifest.yml
let resolved = manifest.app.container.resolve(manifest_dir)?;
match resolved {
ResolvedSource::Pull { image, signature, .. } => {
self.runtime.pull_image(&image, signature.as_deref()).await?;
}
ResolvedSource::Build { context, dockerfile, tag, build_args, always_rebuild } => {
if always_rebuild || !self.runtime.image_exists(&tag).await? {
self.runtime.build_image(&context, &dockerfile, &tag, &build_args, always_rebuild).await?;
}
}
}
self.runtime.create_container(manifest, &compute_container_name(manifest), 0).await?;
self.runtime.start_container(&compute_container_name(manifest)).await?;
Ok(())
}
```
### Wire-up in `main.rs`
File: `core/archipelago/src/main.rs`
Replace the commented-out `run_boot_reconciliation` block (`main.rs:107-111`) with:
```rust
// Load manifests + adopt existing + start reconciler loop.
let orchestrator = Arc::new(ProdContainerOrchestrator::new(config.clone()).await?);
orchestrator.load_manifests().await?;
let adoption = orchestrator.adopt_existing().await?;
tracing::info!(adopted = adoption.adopted.len(), "Container adoption complete");
let reconciler = BootReconciler::new(orchestrator.clone(), Duration::from_secs(300), shutdown_token.clone());
tokio::spawn(reconciler.run_forever());
```
`RpcHandler` gets the orchestrator regardless of `dev_mode`:
```rust
// core/archipelago/src/api/rpc/mod.rs:83
let orchestrator: Option<Arc<dyn ContainerOrchestrator>> = if config.dev_mode {
Some(Arc::new(DevContainerOrchestrator::new(config.clone()).await?))
} else {
Some(Arc::new(prod_orch.clone()))
};
```
Where `ContainerOrchestrator` becomes a trait implemented by both `DevContainerOrchestrator` and `ProdContainerOrchestrator`.
### First-boot replacement
There is no separate first-boot code. The reconciler handles it: when the archipelago service starts on a fresh node, `adopt_existing` finds nothing, `reconcile_all` sees no running container for any manifest, and installs each one in dependency order (bitcoin-core first, then everything else). On subsequent boots, adoption finds existing containers and reconcile mostly no-ops.
**Removes completely**:
- `/var/lib/archipelago/.first-boot-containers-done` marker (no longer needed)
- `/var/lib/archipelago/.unbundled` handling in first-boot script (becomes a config flag in archipelago.conf if we still need it)
- `scripts/first-boot-containers.sh` (1392 lines)
- `scripts/reconcile-containers.sh`
- `scripts/container-specs.sh`
- `image-recipe/configs/archipelago-first-boot-containers.service`
- `image-recipe/configs/archipelago-reconcile.service`
- Related enable/disable in ISO builder
## The three UI manifests
Example: `apps/bitcoin-ui/manifest.yml`
```yaml
app:
id: bitcoin-ui
name: Bitcoin Knots UI
version: 1.0.0
description: Custom Archipelago UI for Bitcoin Knots
container:
source:
type: build
context: /opt/archipelago/docker/bitcoin-ui
dockerfile: Dockerfile
tag: localhost/bitcoin-ui:local
build_args:
BITCOIN_RPC_AUTH: ${BITCOIN_RPC_AUTH} # injected from host-ip.env or secrets
always_rebuild: false
dependencies:
- app_id: bitcoin-core
resources:
memory_limit: 128Mi
security:
network_policy: host
readonly_root: false
ports: [] # host networking
volumes: []
environment: []
health_check:
type: http
endpoint: http://127.0.0.1:8334
path: /
interval: 30s
extensions:
container_name: archy-bitcoin-ui
```
The `extensions.container_name` is how we match the existing running container on .116 for adoption. Same pattern for `electrs-ui` (container_name: `archy-electrs-ui`, port probe 50002) and `lnd-ui` (container_name: `archy-lnd-ui`, port probe 8081).
**BITCOIN_RPC_AUTH injection**: today `first-boot-containers.sh` `sed`s this value into `nginx.conf` (destructively). In the new world, it's a `--build-arg` — the Dockerfile gets `ARG BITCOIN_RPC_AUTH` and templates `nginx.conf` from a template file. Fixes the "sed destroys the source" bug from the mapping.
## Migration path (.116 and .228 specifically)
### .116 (all 3 UIs currently running, adopted from bash install)
1. Ship the new archipelago binary with the prod orchestrator.
2. On archipelago restart, `adopt_existing` scans `podman ps -a`, sees `archy-bitcoin-ui`, `archy-electrs-ui`, `archy-lnd-ui` already running.
3. Matches them against the new manifests by `extensions.container_name`.
4. Records state. Reconciler sees them Running → NoOp.
5. Manual test: `podman stop archy-bitcoin-ui` → within 5 minutes, reconciler starts it again. `podman rm -f archy-bitcoin-ui` → reconciler rebuilds from `/opt/archipelago/docker/bitcoin-ui/Dockerfile` and re-creates.
### .228 (no bitcoin-ui, no lnd-ui, has electrs-ui from bash first-boot)
1. Ship same binary.
2. Adoption finds only `archy-electrs-ui`.
3. Reconciler sees `bitcoin-ui` and `lnd-ui` missing → triggers `install_fresh` for each.
4. For `bitcoin-ui`: `image_exists("localhost/bitcoin-ui:local")` → false. `build_image(/opt/archipelago/docker/bitcoin-ui, Dockerfile, localhost/bitcoin-ui:local, {BITCOIN_RPC_AUTH: ...}, force=false)`. Then create + start.
5. Same for `lnd-ui`.
6. Manual test: HTTP probe ports 8334 and 8081 return 200 within ~5 minutes of service restart.
## Test plan
Unit tests (Rust, in-process):
- `manifest::tests::legacy_image_parses_as_pull_source`
- `manifest::tests::explicit_pull_source_parses`
- `manifest::tests::explicit_build_source_parses`
- `manifest::tests::source_build_requires_tag`
- `runtime::tests::build_image_happy_path` (uses a minimal Dockerfile in `tempfile::TempDir`)
- `runtime::tests::build_image_failure`
- `runtime::tests::image_exists_roundtrip`
- `prod_orchestrator::tests::install_fresh_pull`
- `prod_orchestrator::tests::install_fresh_build`
- `prod_orchestrator::tests::adopt_existing_matches_by_name`
- `prod_orchestrator::tests::reconcile_starts_exited_container` (with a mock runtime)
- `prod_orchestrator::tests::reconcile_installs_missing_container`
- `prod_orchestrator::tests::compute_container_name_ui_apps_prefixed`
- `prod_orchestrator::tests::compute_container_name_backend_apps_bare`
Integration tests (require real podman, run on archy node):
- Fresh-install path: wipe containers + images, start archipelago, verify all 3 UIs up within 60s.
- Adoption path: containers pre-running, start archipelago, verify no recreate (compare container IDs before/after).
- Reconcile-start path: `podman stop archy-bitcoin-ui`, wait, verify restart.
- Reconcile-recreate path: `podman rm -f archy-bitcoin-ui`, wait, verify rebuild+recreate.
- Rebuild-on-Dockerfile-change path: edit Dockerfile, call `upgrade` RPC, verify image rebuilt and container recreated.
Chaos matrix (bash + Playwright, the original goal):
- For each UI (bitcoin-ui, electrs-ui, lnd-ui) × each event (stop, start, restart, remove+reconcile, SIGKILL, archipelago-service-restart, host-reboot) × each node (.116, .228): assert HTTP 200 + page-title marker returns within 60s of event.
## Risks + mitigations
| Risk | Mitigation |
|------|------------|
| Adoption mismatches and re-creates a container we already had, losing its data | Adoption matches by exact name; `install_fresh` only runs when `get_container_status` returns Err (container doesn't exist), not when it returns Stopped/Exited. Unit tested. |
| Build loop: reconciler rebuilds on every tick | `always_rebuild: false` + `image_exists` check. Only rebuilds when image tag is missing OR `upgrade` RPC is called. |
| Reconciler runs while user is mid-install via the UI | Orchestrator state has per-app mutex; reconcile waits. Install path takes the same mutex. |
| Auto-rollback (v1.7.41) fires during testing | `reconcile_all` is spawned AFTER server is healthy and responding; if it fails, archipelago the service still passes verification. Individual container failures are logged, not fatal. |
| Dependency ordering: bitcoin-ui needs BITCOIN_RPC_AUTH which is generated at first boot | Reconciler handles dependency order by reading `manifest.app.dependencies` and installing in topological order. If the dep doesn't exist yet, skip and retry next tick. |
| Moving `/opt/archipelago/docker/<name>` content breaks the build context | That path is stable per the ISO builder at `image-recipe/build-auto-installer-iso.sh:1671-1685`. Manifests reference it absolutely. |
| Dropping bash scripts breaks existing ISOs in the field | Target release cycle is disposable alpha nodes. For existing alpha nodes (.116, .228) we hot-swap the binary and let the reconciler take over, then the next reboot doesn't need the systemd units; we mask them manually. |
| User wants to downgrade to v1.7.42 | Auto-rollback mechanism already handles that; binary swap is reversible. The removed bash scripts are still in git history. |
## Implementation order
1. **Schema first**: extend `ContainerConfig` + `ContainerSource` + `resolve()` + validation + unit tests. ~100 LOC Rust + ~80 LOC tests.
2. **Runtime**: `build_image` + `image_exists` in trait, `PodmanRuntime`, `DockerRuntime` (can stub), `AutoRuntime`. ~150 LOC + tests with throwaway tempdir Dockerfile.
3. **ProdContainerOrchestrator**: new type with `install/start/stop/restart/remove/status/list/logs/health/adopt_existing/reconcile_all/ensure_running/install_fresh`. ~400 LOC + unit tests with mocked runtime.
4. **ContainerOrchestrator trait**: abstract over Dev and Prod so `RpcHandler` is polymorphic. ~50 LOC refactor.
5. **BootReconciler**: task spawner with loop + cancellation. ~80 LOC + unit tests.
6. **main.rs wire-up**: adopt + spawn reconciler. ~20 LOC.
7. **3 UI manifests + Dockerfile BITCOIN_RPC_AUTH refactor** (use ARG + template file, not sed). ~60 lines of YAML + ~20 lines of Dockerfile.
8. **Remove bash scripts + services**: split into sub-steps because `first-boot-containers.sh` creates 25+ containers (only 3 ported in Step 7) AND does non-container setup (secret gen, UID-mapping chowns, Tor hostnames, WireGuard, firewall, nostr-relay dir):
- **8a** (cheap, safe): delete `image-recipe/configs/archipelago-reconcile.{service,timer}` + their ISO-builder touchpoints (the systemd enablement + `cp` into `$WORK_DIR`). `BootReconciler` fully replaces the timer-driven path — no more periodic bash invocation. **Keep** `scripts/reconcile-containers.sh` + `scripts/container-specs.sh` because `core/archipelago/src/api/rpc/package/update.rs` still shells out to reconcile-containers.sh during OTA updates; porting that call site requires manifests for every container it touches (which is Step 8b's scope). Atomic commit, low risk.
- **8b** (large, deferred): port the remaining ~25 container creations from `first-boot-containers.sh` into `apps/<id>/manifest.yml` files. One manifest per commit, validated against current bash behavior (ports, volumes, env, deps, health checks, post-create wallet/db bootstrap). Probably 1-2 days of careful porting. Includes `apps/filebrowser/manifest.yml`. Then port `update.rs`'s two `reconcile-containers.sh` call sites to the `ContainerOrchestrator` trait (`upgrade(app_id)`).
- **8c** (final, one-way door): rename `first-boot-containers.sh` → `first-boot-setup.sh`, strip out all `$DOCKER run/pull/exec` calls, keep only secret generation + dir prep + Tor/WG/firewall/nostr setup. Rename `archipelago-first-boot-containers.service` → `archipelago-first-boot-setup.service`. Delete `scripts/reconcile-containers.sh` + `scripts/container-specs.sh` (update.rs no longer needs them). Add ISO builder lines to copy `apps/*/manifest.yml` → `/opt/archipelago/apps/`. Full ISO build test on .116 required before commit.
9. **Live test on .228**: hot-swap binary, expect 3 UIs to come up within 60s of service restart.
10. **Live test on .116**: hot-swap binary, expect zero container recreation + adoption-confirmed log lines.
11. **Chaos matrix** on both nodes.
Each step is a separate commit. Steps 1–6 are independent-enough that they can each have their own test gate.
## Estimated total
~1000 LOC Rust added, ~1500 lines bash deleted, ~50 LOC Rust deleted. 8–12 hours of focused work across multiple sessions. No release pressure per user decision.
## Open questions for user
1. **Container naming**: I propose `archy-<app_id>` for UIs, `<app_id>` for backends (matches current .116 fixture). Alternative: unify on `archy-<app_id>` for everything and migrate existing backends by renaming at adoption. Which?
2. **BITCOIN_RPC_AUTH injection**: the build-arg approach rebuilds the UI image when the auth value changes. Fine during normal operation (rare). Alternative: mount the nginx.conf at runtime as a volume, never bake auth into the image. Which?
3. **Reconciler interval**: 5 minutes. Too slow for a dropped container (user sees a broken UI for up to 5 min). Alternative: 30 seconds + more expensive `podman ps` calls. Which?
4. **Concurrent reconcile + user install**: per-app mutex is the simple answer. Alternative: a single orchestrator-wide mutex (simpler, slower). Which?
5. **Delete bash scripts in this migration, or keep them around as fallback?** I recommend delete (single source of truth), but deleting `first-boot-containers.sh` is a one-way door in terms of field recovery.
docs/archive/security-code-audit-2026-03.md
+576
View File
@@ -0,0 +1,576 @@
# Archipelago Security & Code Quality Audit Report
**Date**: March 2026
**Version audited**: 0.1.0
**Auditor**: Automated code review (Claude)
**Scope**: Authentication, sessions, cryptography, container security, RPC, frontend, custom code vs libraries
---
## 1. Executive Summary
### Overall Security Posture: 7.5 / 10
Archipelago demonstrates a security-conscious design with several production-grade patterns already in place. The project makes defensible choices in cryptography, follows capability-based container hardening, and implements layered authentication with TOTP 2FA. However, gaps remain in image signature verification, some postMessage origin validation, and the use of bcrypt instead of the already-available Argon2id for password hashing.
For a v0.1.0 self-sovereign personal server, this is a strong foundation. The code reads like it was written by someone who understands the threat model (local network appliance, single admin user, potentially hostile containers).
### Top 5 Risks (by severity)
1. **Cosign image verification is a TODO** (`podman_client.rs:84`). Container images are pulled without cryptographic signature checks. A compromised registry or MITM on image pull could inject malicious containers. This is the single largest attack surface.
2. **`postMessage('*')` wildcard origin in Nostr signer** (`AppSession.vue:490`, `appLauncher.ts:262,306,309`). Responses to NIP-07 signing requests are sent with `'*'` target origin, allowing any window/iframe to intercept signed Nostr events. A malicious app loaded in an adjacent iframe could harvest signatures.
3. **bcrypt for password hashing instead of Argon2id** (`auth.rs:108,245`). bcrypt is battle-tested but vulnerable to GPU/ASIC acceleration. Argon2id is already a dependency (used in TOTP and backup encryption) and provides memory-hard resistance. Using two different password hashing schemes in the same codebase is also a maintenance smell.
4. **Sessions are in-memory only** (`session.rs`). All sessions are lost on service restart, forcing all users to re-authenticate. More critically, there is no persistence layer to support session revocation auditing or multi-instance deployments.
5. **`v-html` used for TOTP QR SVG rendering** (`Settings.vue:286`). The SVG is server-generated, but `v-html` is a known XSS vector. If the QR generation path were ever to include user-controlled input, this would become exploitable.
### Top 5 Strengths
1. **TOTP implementation is production-grade**. Envelope encryption (KEK wraps MEK wraps secret), Argon2id key derivation with strong parameters (64 MiB, t=3, p=4), ChaCha20-Poly1305 AEAD, zeroize on drop, replay protection via used time steps, bcrypt-hashed backup codes. This exceeds what most node-OS projects implement.
2. **Comprehensive rate limiting**. Login rate limiting (5 attempts / 60s per IP) plus per-endpoint rate limiting on 25+ sensitive methods including financial operations, identity creation, backup operations, and federation joins. Configurable windows per method.
3. **CSRF protection is properly implemented**. Double-submit cookie pattern: `csrf_token` cookie (readable by JS) + `X-CSRF-Token` header validated on every authenticated request. SameSite=Strict on session cookies. HttpOnly on session cookie (not accessible to JS).
4. **Container security defaults are correct**. `--cap-drop=ALL` with explicit per-app capability add-back, `--security-opt=no-new-privileges:true` on all non-privileged containers, read-only root filesystem where compatible, per-app capability documentation.
5. **Error sanitization prevents information leakage**. `sanitize_error_message()` strips internal file paths and system details, returning generic errors for anything not in the user-facing prefix allowlist. Path components like `/var/lib/archipelago/` are replaced with `[data]/`.
### Recommended Actions (ordered by impact)
1. Implement cosign image verification before any public release. This is a hard requirement for supply chain security.
2. Replace `postMessage('*')` with explicit target origins derived from the iframe's `src` URL.
3. Migrate password hashing from bcrypt to Argon2id (already a dependency) with a transparent upgrade path on next login.
4. Add `DOMPurify.sanitize()` around all `v-html` usage or replace with a component-based SVG renderer.
5. Add session persistence (SQLite) to survive restarts and enable audit logging.
---
## 2. Session & Auth
### Password Hashing
**Current**: `bcrypt` crate with `DEFAULT_COST` (cost factor 12).
| Property | bcrypt (current) | Argon2id (available) |
|----------|-----------------|---------------------|
| Algorithm | Blowfish-based, 1999 | Memory-hard, won PHC 2015 |
| GPU resistance | Moderate (small state) | Strong (memory-hard) |
| Cost factor | `DEFAULT_COST = 12` (~250ms) | m=64MiB, t=3, p=4 (already configured in `totp.rs`) |
| ASIC resistance | Weak | Strong |
| Ecosystem status | Mature, stable | Modern standard, OWASP recommended |
| Already a dependency | No (separate crate) | Yes (`argon2` crate used by `totp.rs` and `backup/identity.rs`) |
**Finding**: bcrypt at cost 12 is adequate for a local appliance where login attempts are rate-limited. However, Argon2id is already linked into the binary. Using two different password hashing algorithms in the same project increases cognitive overhead and the risk of confusion. The TOTP module already uses Argon2id with well-chosen parameters (64 MiB memory, t=3 iterations, p=4 parallelism).
**Recommendation**: Migrate to Argon2id on next password change. Store a version tag in `user.json` to allow transparent upgrade: on successful bcrypt login, re-hash with Argon2id and save.
### Session Tokens
**Current**: 32 bytes from `rand::random()` (which delegates to `OsRng`/`ChaCha20Rng`), hex-encoded (64 characters). Tokens are hashed with SHA-256 before storage, so the raw token never exists in the session map.
**Analysis**:
- 256 bits of entropy from a CSPRNG: more than sufficient. Brute-forcing 2^256 is infeasible.
- SHA-256 hashing of stored tokens: correct. A database leak would not expose session tokens.
- Hex encoding doubles the string length but is unambiguous and URL-safe.
**Verdict**: This is correct and secure for a single-instance appliance. No change needed.
### Session Storage
**Current**: In-memory `HashMap<[u8; 32], Session>` behind `Arc<RwLock<>>`.
| Feature | Status |
|---------|--------|
| TTL-based expiry | 24 hours inactivity (full), 5 minutes (pending TOTP) |
| Max concurrent sessions | 5 (oldest evicted) |
| Session rotation on password change | Yes (`rotate()` + `invalidate_all_except()`) |
| Cleanup of expired sessions | `cleanup_expired()` available, presumably called periodically |
| Persistence across restarts | **No** |
| Audit trail | **No** |
**Risk**: Medium. Session loss on restart is annoying but not a security issue (it forces re-authentication). The lack of audit trail means there is no way to retroactively determine who was authenticated when.
**Recommendation**: Add SQLite-backed session store when adding multi-user support. For now, the in-memory approach is acceptable.
### CSRF Protection
**Current**: Double-submit cookie pattern.
1. On login, server sets `csrf_token` cookie (SameSite=Strict, readable by JS) and `session` cookie (HttpOnly, SameSite=Strict).
2. Frontend reads `csrf_token` from `document.cookie` and sends it as `X-CSRF-Token` header on every RPC call.
3. Backend validates `csrf_cookie == csrf_header` on every authenticated request.
**Analysis**:
- SameSite=Strict prevents cross-origin cookie submission entirely in modern browsers.
- The double-submit pattern provides defense-in-depth for browsers that do not enforce SameSite.
- CSRF token is 32 bytes (256 bits) of randomness -- sufficient.
- Secure flag is conditionally set (production only, not dev mode) -- correct.
**Finding**: The CSRF implementation is sound. One minor note: the CSRF token is generated independently of the session token. This is fine because both are random and the cookie binding ensures they cannot be used cross-session.
**Verdict**: Correct. No changes needed.
### Rate Limiting
**Login rate limiter**: 5 failures per 60 seconds per IP. Implemented as `Vec<Instant>` per IP with sliding window.
**Endpoint rate limiter**: Per-method limits on 25+ sensitive endpoints. Examples:
| Endpoint | Max Requests | Window |
|----------|-------------|--------|
| `wallet.send` | 5 | 300s |
| `lnd.payinvoice` | 10 | 300s |
| `identity.create` | 10 | 300s |
| `backup.create` | 10 | 600s |
| `system.factory-reset` | (not rate-limited) | -- |
| `container-install` | 5 | 300s |
| `auth.changePassword` | 3 | 300s |
| `federation.join` | 5 | 60s |
| `update.apply` | 2 | 600s |
**Coverage gaps**:
- `system.factory-reset` is not rate-limited. While it requires authentication, a compromised session could rapidly trigger factory resets. Low practical risk since one reset wipes everything.
- `tor.rotate-service` is not rate-limited. Rapid rotation could burn through Tor circuits.
- No global rate limit across all endpoints -- only per-method. A compromised session could flood non-limited endpoints.
**Verdict**: Good coverage for a single-user appliance. The per-method approach is appropriate for the threat model.
### TOTP 2FA
**Implementation quality**: Excellent.
| Feature | Implementation |
|---------|---------------|
| Secret generation | 20 bytes (160 bits) from `OsRng` |
| Secret storage | Encrypted at rest: Argon2id KDF -> ChaCha20-Poly1305 envelope |
| Encryption layers | 3: password -> KEK (Argon2id) -> MEK (random) -> secret |
| Verification window | Current step +/- 1 (3 steps total, ~90s window) |
| Replay protection | Used time steps tracked and rejected |
| Code comparison | Constant-time comparison (`constant_time_eq`) |
| Backup codes | 8 codes, bcrypt-hashed, one-time use |
| Pending session | Max 5 attempts, 5-minute TTL, then forced re-login |
| Re-keying | MEK re-encrypted under new password on password change |
| Zeroize | KEK, MEK, and raw secret zeroized after use |
**Finding**: This is a textbook TOTP implementation. The envelope encryption (KEK/MEK pattern) is the same approach used by hardware security modules. The `zeroize` crate ensures secrets do not linger in memory.
One minor note: `constant_time_eq` is hand-rolled rather than using the `subtle` crate's `ConstantTimeEq`. The implementation is correct (XOR accumulation), but the `subtle` crate is specifically designed to resist compiler optimizations that could break constant-time behavior.
**Recommendation**: Consider switching to `subtle::ConstantTimeEq` for the TOTP comparison. The current implementation is likely fine in practice, but `subtle` provides stronger guarantees against compiler reordering.
---
## 3. Cryptographic Review
| Component | Our Implementation | Library Alternative | Correct? | Secure? | Verdict |
|-----------|-------------------|---------------------|----------|---------|---------|
| **Password hashing** | `bcrypt` crate, `DEFAULT_COST` (12) | `argon2` crate (already a dep) | Yes | Adequate | **Migrate to Argon2id**. Already a dependency, memory-hard, OWASP recommended. bcrypt is not broken but Argon2id is strictly better against modern attacks. |
| **Session tokens** | `rand::random::<[u8; 32]>()` + hex, SHA-256 stored hash | `tower-sessions` or signed JWTs via `jsonwebtoken` | Yes | Yes | **Keep custom**. 256-bit CSPRNG tokens with hashed storage is textbook. JWTs add complexity and stateless verification is not needed for single-instance. |
| **TOTP KDF** | `argon2` crate, Argon2id v0x13, m=64MiB, t=3, p=4 | N/A (already using the right library) | Yes | Yes | **Correct**. Strong parameters that balance security and UX on modest hardware. |
| **TOTP encryption** | `chacha20poly1305` crate, KEK/MEK envelope | `age` crate | Yes | Yes | **Keep custom**. The envelope pattern gives us re-keying without re-encrypting the secret. `age` would not support this use case without wrapping. |
| **DID signing** | `ed25519-dalek` direct usage | SpruceID `ssi` crate | Yes | Yes | **Keep custom**. Our code is 381 lines, handles did:key + DID Documents + dual-key (Ed25519+secp256k1). `ssi` would add 50+ transitive deps. |
| **VC signatures** | Custom Ed25519Signature2020 proof (credentials.rs, 796 lines) | SpruceID `ssi` VC module | Yes | Yes for our proof type | **Keep custom for issuance**. Consider `ssi` only for verifying external VCs with non-Ed25519 proof types. |
| **Backup encryption** | Argon2id KDF + ChaCha20-Poly1305 (backup/identity.rs, 132 lines) | `age` crate | Yes | Yes | **Keep custom**. Clean, minimal, well-tested. `age` is simpler API but our code is already simple. |
| **Key storage** | Raw bytes in files with `0o600` permissions | `keyring` crate or OS keychain | Yes | Adequate | **Keep current**. File-based is correct for headless Linux server. No desktop environment means no keychain daemon. Permissions are set immediately after key generation. |
| **Constant-time comparison** | Hand-rolled XOR accumulation | `subtle` crate `ConstantTimeEq` | Correct logic | Likely | **Consider `subtle`**. Hand-rolled constant-time code can be optimized away by the compiler. `subtle` uses inline assembly barriers. Low risk in practice. |
| **CSRF tokens** | `rand::thread_rng().fill()` 32 bytes | N/A | Yes | Yes | **Correct**. `thread_rng()` delegates to `OsRng`-seeded `ChaCha20Rng`. 256 bits is more than sufficient. |
### Key Observations
1. **Argon2 is used correctly in two places** (TOTP and backup) **but not for password hashing**. This is the most obvious inconsistency. The project already pays the compilation cost for `argon2`; using it for password hashing would unify the crypto stack.
2. **ChaCha20-Poly1305 is used correctly** throughout. Nonces are generated from `OsRng`, key material is zeroized after use, and the AEAD construction prevents both tampering and ciphertext manipulation.
3. **Ed25519-dalek usage is clean**. Key generation uses `OsRng`, signing and verification are straightforward, the Ed25519-to-X25519 conversion for key agreement is done correctly via `curve25519-dalek`.
4. **No custom cryptographic primitives**. All cryptographic operations use well-audited Rust crates. The project does not implement any ciphers, hash functions, or key exchange algorithms from scratch. This is the correct approach.
---
## 4. Container Security
### Capability Dropping
**Default**: `--cap-drop=ALL` applied to all non-privileged containers (`package.rs:265`).
Per-app capabilities are explicitly added back via `get_app_capabilities()`:
| App Category | Capabilities Added | Justification |
|-------------|-------------------|---------------|
| Minimal apps (searxng, filebrowser, etc.) | None | Runs with zero capabilities |
| Standard apps (photoprism, grafana) | CHOWN, SETUID, SETGID | Internal user switching |
| Bitcoin/Lightning | CHOWN, FOWNER, SETUID, SETGID, DAC_OVERRIDE | Data directory ownership |
| Web servers (nginx-proxy-manager, vaultwarden) | CHOWN, SETUID, SETGID, NET_BIND_SERVICE | Binding ports < 1024 |
| Tailscale | `--privileged` + NET_ADMIN, NET_RAW | VPN tunnel creation (unavoidable) |
**Finding**: The capability model is well-designed. Each app gets the minimum capabilities needed. The `--privileged` exception for Tailscale is documented and unavoidable (it needs TUN device access and network namespace manipulation).
**Risk**: DAC_OVERRIDE grants the ability to bypass file permission checks. This is a broad capability. For Bitcoin/Lightning, it is necessary because the containers need to access data directories with varying ownership. Consider whether `FOWNER` alone would suffice for some of these apps.
### Read-Only Root Filesystem
**Current**: `--read-only` is applied to apps listed in `is_readonly_compatible()`:
- searxng, grafana, filebrowser, mempool-electrs, electrs, nostr-rs-relay, ollama, indeedhub
**Not read-only**: Bitcoin, LND, Nextcloud, BTCPay, Jellyfin, HomeAssistant, and others.
With `--read-only`, tmpfs mounts are added for `/tmp` and `/run`:
```
--tmpfs=/tmp:rw,noexec,nosuid,size=256m
--tmpfs=/run:rw,noexec,nosuid,size=64m
```
**Finding**: The `noexec` and `nosuid` flags on tmpfs mounts are a good hardening measure. The list of read-only-compatible apps is conservative, which is the correct approach -- it is better to not break an app than to force read-only on an incompatible container.
**Recommendation**: Gradually test more apps with `--read-only` and expand the list. Each new addition should be validated by running the app and checking for write failures.
### No-New-Privileges
**Current**: `--security-opt=no-new-privileges:true` applied to all non-Tailscale containers (`package.rs:266`).
**Finding**: Correct. This prevents setuid binaries inside containers from escalating privileges. Combined with `--cap-drop=ALL`, this creates a strong privilege boundary.
### User Namespace / Non-Root
**Current**: Podman runs containers with rootless mode when the `archipelago` user is not root (`podman_client.rs:60-66`). However, `podman_async()` uses `sudo podman` (`podman_client.rs:71-73`), which runs containers in the root Podman context.
**Finding**: The `sudo podman` invocation means containers run in a root context, not rootless. While `--cap-drop=ALL` and `no-new-privileges` provide strong isolation, the containers themselves may run as root (UID 0) inside their namespace. Whether the container process runs as non-root depends on the container image's Dockerfile (e.g., `USER 1000`).
**Recommendation**: Add `--user` flags to container creation where the upstream image supports it. Audit each container image to determine which ones run as root internally.
### Image Pinning
**Current**: The `is_valid_docker_image()` function validates registry origin (docker.io, ghcr.io, localhost) and rejects shell metacharacters. However, there is no enforcement of digest pinning (e.g., `image@sha256:...`).
Images can be specified with tags (`:latest`, `:v1.0.0`) but tags are mutable -- a registry compromise could replace the image behind a tag.
**Finding**: No digest pinning is enforced. While registry validation limits the attack surface, a compromised registry account could push malicious images under existing tags.
**Recommendation**: For the curated app list, pin images to specific digests in the marketplace metadata. Allow tag-based pulls for user-specified images but warn about the risk.
### Cosign Verification
**Current**: `podman_client.rs:83-84`:
```rust
// TODO: Implement cosign verification
log::warn!("Signature verification not yet implemented: {}", sig);
```
**Finding**: This is the most significant security gap in the container subsystem. Without signature verification, there is no cryptographic proof that a pulled image was built by the expected author.
**Risk**: HIGH. This should be implemented before any public release.
**Recommendation**: Integrate `sigstore-rs` for cosign verification. At minimum, verify signatures for the curated app list. Third-party apps from the decentralized marketplace should also have verifiable signatures (the publisher's Nostr key can serve as the trust anchor).
### Network Isolation
**Current**: Containers are placed on either:
- `archy-net` (shared network for Bitcoin stack: bitcoin-knots, lnd, electrs, mempool, btcpay, fedimint)
- Host network (Tailscale only)
- Default isolated network (all other apps)
**Finding**: The `archy-net` shared network is necessary for the Bitcoin stack to communicate (LND needs Bitcoin RPC, Mempool needs Electrs, etc.). Other apps are properly isolated.
**Recommendation**: Consider creating separate networks for distinct app clusters (e.g., `btcpay-net` for BTCPay + nbxplorer + postgres) rather than putting everything on `archy-net`. This would limit lateral movement if a single container is compromised.
### Secrets Injection
**Current**: Secrets are passed to containers via environment variables (`-e` flag). For example, Bitcoin RPC credentials:
```rust
"--bitcoind-password".to_string(), "archipelago123".to_string(),
```
**Finding**: Environment variables are visible via `podman inspect` and `/proc/<pid>/environ` on the host. The hardcoded `archipelago123` RPC password is particularly concerning -- it should be randomly generated per installation.
**Recommendation**:
1. Generate random credentials per app installation and store them via the secrets manager.
2. Prefer bind-mounting secret files into containers (`--secret` or `-v /path/to/secret:/run/secrets/password:ro`) over environment variables.
3. Replace the hardcoded `archipelago123` Bitcoin RPC password with a per-install random password.
---
## 5. RPC Security
### Authentication Enforcement
**Unauthenticated endpoints** (from `UNAUTHENTICATED_METHODS`):
- `auth.login`, `auth.login.totp`, `auth.login.backup` -- login flow
- `auth.isOnboardingComplete`, `auth.isSetup` -- setup status checks
- `health` -- health check
- `backup.restore-identity` -- onboarding restore (before user account exists)
- `federation.peer-joined`, `federation.peer-address-changed`, `federation.get-state` -- inter-node RPC
**Finding**: The unauthenticated endpoint list is reasonable. The federation endpoints are called by peer nodes over Tor and cannot use session cookies -- they are rate-limited instead (10 requests/60s for peer-joined and peer-address-changed, 30 requests/60s for get-state).
`backup.restore-identity` is unauthenticated by design -- it is used during onboarding before a user account exists. This is the correct approach.
**Risk**: The federation endpoints accept peer assertions (e.g., "I just joined your federation") without cryptographic authentication beyond the Tor hidden service address. A future improvement would be to require DID-signed payloads for federation RPCs.
### RBAC
**Current**: RBAC is implemented and wired into the RPC dispatcher (`mod.rs:249-269`). Three roles are defined:
| Role | Access |
|------|--------|
| Admin | Everything |
| Viewer | Read-only system/node/container/federation/identity/backup methods + logout |
| AppUser | Basic system stats, container listing, health, logout, password change |
**Finding**: RBAC is operational. The `can_access()` method uses prefix matching (e.g., `method.starts_with("system.")`) which is a reasonable approach for method-based access control.
**Concern**: The Viewer role grants access to `federation.list` and `dwn.query` but not `dwn.write-message`. This is correct. However, the prefix-matching approach means that if a new method like `system.factory-reset` is added, it would be accessible to Viewers because it starts with `system.`. The current code mitigates this because `system.factory-reset` is not listed in the Viewer's allowed prefixes -- it requires an exact `system.` prefix match, and the Viewer role only allows `method.starts_with("system.")`.
**Wait** -- actually, `system.factory-reset` does start with `system.`, so Viewers WOULD have access to it under the current RBAC rules.
**Risk**: MEDIUM. Any new `system.*` method is automatically accessible to Viewers. The Viewer role should use an explicit allowlist rather than prefix matching for the `system.` namespace.
**Recommendation**: Change Viewer's `system.*` access to an explicit list: `system.stats`, `system.temperature`, `system.disk-status`, etc. Do not allow `system.factory-reset`, `system.shutdown`, `system.reboot`, or `system.disk-cleanup` for Viewers.
### Input Validation
Five critical endpoints traced from params to handler:
1. **`auth.login`**: Password extracted as string from params, passed to `bcrypt::verify()`. No injection risk -- bcrypt operates on byte arrays. Rate-limited.
2. **`package.install`**: Package ID validated by `validate_app_id()` (lowercase alphanumeric + hyphens, 1-64 chars, no leading hyphen). Docker image validated by `is_valid_docker_image()` (length check, no shell metacharacters, registry allowlist). Both validations are solid.
3. **`system.factory-reset`**: Requires `confirm: true` parameter. Authenticated and RBAC-checked. No injection risk -- the handler performs fixed system operations.
4. **`backup.restore-identity`**: Accepts a JSON blob with a base64-encoded encrypted backup. The backup is decrypted with a user-supplied passphrase. Input validation: blob must be valid base64, must contain salt + nonce + ciphertext of minimum length, decrypted key must be exactly 32 bytes. The Argon2id KDF prevents timing attacks on the passphrase.
5. **`identity.create`**: Accepts optional `label` and `type` parameters. The label is stored as-is in a JSON file. No length validation on the label. This is a low risk since the label is never used in shell commands or HTML rendering, but a maximum length should be enforced.
### Error Sanitization
**Current**: `sanitize_error_message()` in `mod.rs:72-104`:
- User-facing prefixes (Invalid, Missing, Not found, etc.) are passed through with path sanitization.
- Path components (`/var/lib/archipelago/`, `/usr/local/bin/`, `/etc/`) are replaced with `[data]/`, `[bin]/`, `[config]/`.
- Messages exceeding 200 characters are truncated.
- All other errors return: `"Operation failed. Check server logs for details."`
**Finding**: This is a good approach. The prefix allowlist ensures that validation errors remain actionable for the user while internal errors (stack traces, database errors, file system errors) are hidden.
**Minor concern**: The `contains()` check (`msg.contains(prefix)`) rather than `starts_with()` means that an internal error message containing the word "Password" anywhere would be passed through. For example, an error like "Failed to read /etc/shadow: Password file locked" would match the "Password" prefix. This is unlikely to leak sensitive information but is worth tightening.
### Path Traversal
**Frontend** (`filebrowser-client.ts`): `sanitizePath()` is not present in `rpc-client.ts`, but the filebrowser client strips `..` and `/` from filenames: `name.replace(/\.\./g, '').replace(/\//g, '')`.
**Backend**: File operations use `PathBuf::join()` which does not normalize `..` components. However, all file paths are constructed from validated app IDs (alphanumeric + hyphens) and fixed directory structures. There is no user-controlled path component that could escape the data directory.
**Verdict**: Path traversal risk is low. The app ID validation prevents directory traversal in container data paths.
---
## 6. Frontend Security
### XSS
**`v-html` usage**: Found in one location:
- `Settings.vue:286`: `<div v-html="totpQrSvg" />` -- renders server-generated SVG.
**Analysis**: The SVG is generated by the `qrcode` crate on the backend and contains only geometric shapes (rects, paths). It does not include any user-controlled content. However, `v-html` bypasses Vue's template escaping entirely.
**Risk**: LOW currently (SVG is trusted server output), but HIGH if the generation path ever changes.
**Recommendation**: Replace `v-html` with either:
1. An `<img>` tag with a data URI: `<img :src="'data:image/svg+xml;base64,' + btoa(totpQrSvg)" />`
2. `DOMPurify.sanitize(totpQrSvg)` before rendering with `v-html`.
### CSRF
**Frontend implementation** (`rpc-client.ts:18-21, 42-45`):
```typescript
function getCsrfToken(): string | null {
const match = document.cookie.match(/(?:^|;\s*)csrf_token=([^;]+)/)
return match ? match[1]! : null
}
```
The CSRF token is read from cookies and sent as `X-CSRF-Token` header on every RPC call via `fetch()` with `credentials: 'include'`.
**Finding**: Correctly implemented. The token is scoped to the session (new token issued on login, rotated on password change, expired on logout).
### Credential Storage (localStorage)
Audit of all `localStorage.setItem` calls:
| Key | Content | Risk |
|-----|---------|------|
| `neode_locale` | Language preference ("en") | None |
| `neode-auth` | Boolean flag ("true") | None -- not a credential |
| `neode_onboarding_complete` | Boolean flag | None |
| `neode_intro_seen` | Boolean flag | None |
| `neode_backup_created` | Boolean flag | None |
| `neode_did` | DID string (public identifier) | None -- DIDs are public |
| `neode_did_state` | DID + KID + pubkey (all public) | None |
| `neode_nostr_npub` | Nostr public key (public) | None |
| `archipelago-ui-mode` | "easy" / "advanced" | None |
| `archipelago-goal-progress` | UI progress state | None |
| `archipelago-spotlight-recent` | Recent search items | None |
| `federation-view` | Active federation tab | None |
| `IDENTITY_KEY + appId` | Nostr identity for app context | **LOW** -- contains public key, not private |
| `APPROVED_ORIGINS_KEY` | Set of approved iframe origins | **LOW** -- UI preference |
| `DISPLAY_MODE_KEY` | "overlay" / "tab" | None |
**Finding**: No secrets, passwords, private keys, or session tokens are stored in localStorage. All stored values are either UI preferences or public identifiers. This is correct.
### iframe postMessage Security
**Outbound `postMessage('*')` calls** (wildcard target origin):
1. `AppSession.vue:490,492` -- Nostr signing responses sent to iframe source with `'*'`
2. `AppLauncherOverlay.vue:390` -- Escape key event sent to parent with `'*'`
3. `appLauncher.ts:262,306,309` -- Nostr signing responses sent to iframe source with `'*'`
**Inbound origin validation**:
1. `contextBroker.ts:65` -- Validates `event.origin !== this.allowedOrigin` (properly restrictive)
2. `Chat.vue:110` -- Validates against expected AIUI URL origin (properly restrictive)
3. `AppSession.vue` and `appLauncher.ts` -- No origin validation on incoming `nostr-request` messages
**Finding**: The Nostr signer (NIP-07 bridge) accepts signing requests from any iframe without verifying the origin, and sends signed responses back with `'*'` target origin. This means:
- Any iframe loaded in the app launcher could request Nostr event signatures.
- The signed response could be intercepted by any window.
**Mitigation**: The user is prompted to approve signing requests (a consent dialog exists in `appLauncher.ts`), and the approved origins list is stored in localStorage. However, the initial request acceptance has no origin check.
**Risk**: MEDIUM. A malicious app loaded in an iframe could silently request signatures for crafted Nostr events.
**Recommendation**:
1. Validate `event.origin` on incoming `nostr-request` messages against the app's known URL.
2. Replace `postMessage(msg, '*')` with `postMessage(msg, expectedOrigin)` for Nostr responses.
3. The `AppLauncherOverlay.vue:390` escape event using `'*'` is lower risk since it only sends a UI event to the parent window, but should still use a specific origin.
### Dependency Audit
Note: `npm audit` was not run as part of this review (requires network access and node_modules). This should be run separately:
```bash
cd neode-ui && npm audit
```
The project uses Vue 3, Vite 7, and Pinia -- all actively maintained. The key security-relevant frontend dependencies are:
- `fetch` API (native, no third-party HTTP client)
- No `eval()` or `new Function()` usage detected
- No inline scripts or styles that would conflict with CSP
---
## 7. Custom Code vs Libraries
### Summary Table
| # | Component | Lines | Quality | Alternative | Verdict |
|---|-----------|-------|---------|-------------|---------|
| 1 | HTTP Server (`handler.rs`) | 813 | Functional but hand-rolled | `axum` | **Migrate** |
| 2 | Session Management (`session.rs`) | 595 | Solid, well-tested | `tower-sessions` | **Keep** (for now) |
| 3 | Rate Limiting (`session.rs` + `mod.rs`) | ~120 | Simple, effective | `governor` | **Keep** |
| 4 | DID Implementation (`identity.rs`) | 381 | Clean, W3C compliant | SpruceID `ssi` | **Keep** |
| 5 | Verifiable Credentials (`credentials.rs`) | 796 | W3C VC 2.0 compliant | SpruceID `ssi` VC | **Keep** (consider `ssi` for external VC verification) |
| 6 | did:dht | ~200 | Works via `mainline` | `pkarr` | **Evaluate** |
| 7 | DWN Store | ~300 | Skeletal | None mature | **Keep** (deprioritize) |
| 8 | WebSocket State Broadcasting | ~200 | Works but full-resync | `json-patch` | **Add library** |
| 9 | Form Validation (frontend) | Scattered | Inconsistent | `zod` | **Add library** |
| 10 | Container Runtime (`podman_client.rs`) | 410 | Clean abstraction | `bollard` | **Keep** |
### Detailed Assessments
**1. HTTP Server (custom `handler.rs` -- 813 lines)**
The handler manually implements routing, CORS headers, WebSocket upgrade, request body parsing, and response building using raw `hyper 0.14`. This works but is fragile -- every new route requires manual pattern matching, there is no middleware stack, and hyper 0.14 is end-of-life.
Alternative: `axum` (built by the tokio team on hyper 1.x) provides typed extractors, a middleware stack via `tower`, built-in WebSocket support, and is the de facto standard for Rust web servers.
**Verdict**: Migrate. This is the highest-impact refactoring item. `axum` would reduce `handler.rs` to approximately 200 lines while adding type safety, automatic request parsing, and tower middleware support. Risk is medium -- the RPC logic is unchanged, only the HTTP glue changes.
**2. Session Management (custom `session.rs` -- 595 lines including 300+ lines of tests)**
The session store is ~200 lines of production code with ~370 lines of comprehensive tests. It implements token hashing, TTL expiry, concurrent session limits, session rotation, and pending TOTP sessions with attempt tracking. The code uses `zeroize` for TOTP secrets.
Alternative: `tower-sessions` with `tower-sessions-sqlx-store` for SQLite-backed persistence.
**Verdict**: Keep custom for now. The implementation is correct, well-tested, and purpose-built for the two-phase TOTP flow. A library would not handle the pending/full session distinction without significant customization. Migrate to `tower-sessions` only if SQLite persistence or multi-instance deployment is needed.
**3. Rate Limiting (custom, ~120 lines)**
Simple in-memory sliding window counters per (method, IP). Not configurable at runtime but the static configuration is well-chosen for each endpoint category.
Alternative: `governor` crate or `tower::limit::RateLimitLayer`.
**Verdict**: Keep custom. The implementation is straightforward, correct, and tailored to the per-method needs. `governor` would add a dependency for minimal benefit. Revisit only if distributed rate limiting is needed (multiple backend instances).
**4. DID Implementation (`identity.rs` -- 381 lines)**
Clean implementation of `did:key` method using `ed25519-dalek`. Generates W3C DID Core v1.0 compliant DID Documents with Ed25519 verification keys and X25519 key agreement keys. Includes Ed25519-to-X25519 conversion, Nostr secp256k1 dual-key support, and roundtrip tests.
Alternative: SpruceID `ssi` crate (v0.15.0).
**Verdict**: Keep custom. The code is ~380 lines, handles exactly the features needed (did:key + dual-key DID Documents), and has good test coverage (12 tests). `ssi` would add 50+ transitive dependencies for features like did:web, did:ethr, did:ion resolution that are not needed. The maintenance burden of 380 lines of well-tested code is far lower than managing a large dependency tree.
**5. Verifiable Credentials (`credentials.rs` -- 796 lines)**
W3C VC Data Model 2.0 implementation supporting issuance, verification, revocation, and verifiable presentations. Uses Ed25519Signature2020 proof format.
Alternative: SpruceID `ssi` VC module.
**Verdict**: Keep custom for issuance and node-to-node verification. The code handles the one proof type needed for Archipelago's use case (Ed25519Signature2020). Consider `ssi` only if external VC verification is needed (verifying credentials issued by non-Archipelago systems with different proof types like BbsBlsSignature2020 or JsonWebSignature2020).
**6. did:dht (`did_dht.rs` -- ~200 lines)**
Implements did:dht resolution via the `mainline` crate (BEP-44 signed DHT records). Includes in-memory caching.
Alternative: `pkarr` crate (v5.0.3, 550K downloads) -- higher-level abstraction over mainline DHT.
**Verdict**: Evaluate `pkarr`. If it handles the BEP-44 encoding that is currently done manually, it would reduce code and benefit from upstream maintenance. If it adds unnecessary abstraction, keep custom. The current code is small and works.
**7. DWN Store (`dwn_store.rs` -- ~300 lines)**
Basic CRUD operations, filesystem-backed, protocol registration. Skeletal implementation.
Alternative: No production-ready DWN implementation exists in Rust. The `dwn` crate by unavi-xyz is v0.4.0 with 323 downloads.
**Verdict**: Keep custom. No viable alternative. Per ADR-011, DWN is deprioritized. The current skeleton is sufficient for the protocol registration feature.
**8. WebSocket State Broadcasting (`state.rs` -- ~200 lines)**
Uses tokio broadcast channels to send full state model resyncs on every change. Every WebSocket client receives the entire state JSON on every update.
Alternative: `json-patch` crate for RFC 6902 JSON diffs. The frontend already includes `fast-json-patch`.
**Verdict**: Add `json-patch`. This is one of the highest-impact improvements. On a system with 10+ containers and active monitoring, the full-state broadcast can be 50-100 KB per update. JSON patches would reduce this to a few hundred bytes per change. Both the Rust `json-patch` crate and the frontend `fast-json-patch` library are mature and actively maintained.
**9. Form Validation (manual inline in Vue components)**
Validation logic is scattered across Vue components with inconsistent patterns. Some forms validate on submit, others on blur, and error messages are not standardized.
Alternative: `zod` (TypeScript-first schema validation, 40M+ weekly npm downloads).
**Verdict**: Add `zod`. Centralize validation schemas in `src/types/schemas.ts`. This is critical for the onboarding flow where bad input (weak passphrase, malformed DID) can cause key generation failures. `zod` integrates naturally with TypeScript and can generate types from schemas, reducing duplication.
**10. Container Runtime Abstraction (`podman_client.rs` -- 410 lines)**
Clean Podman client that wraps CLI invocations for container lifecycle operations. Handles both JSON array and NDJSON output formats from Podman.
Alternative: `bollard` crate (Docker/Podman API client, 7M downloads).
**Verdict**: Keep custom. The current abstraction is clean and purpose-built for the manifest-based approach. `bollard` is Docker-first and would require wrapping for the `AppManifest`-driven container creation. The CLI approach also avoids the Podman socket configuration complexity that `bollard` would require.
---
## What To Do Next
The three most impactful changes from this audit, in priority order:
1. **Implement cosign image verification** (`podman_client.rs`). Integrate `sigstore-rs` for container image signature verification. This closes the largest supply chain attack surface. Without it, a compromised Docker registry could push malicious images.
2. **Fix postMessage wildcard origins** (`AppSession.vue`, `appLauncher.ts`). Replace `postMessage(msg, '*')` with targeted origins. Add `event.origin` validation on incoming Nostr signing requests. This prevents malicious iframes from harvesting signed events.
3. **Migrate password hashing to Argon2id** (`auth.rs`). Add a version field to the user JSON. On login, if the hash is bcrypt, verify with bcrypt, then re-hash with Argon2id and save. This unifies the crypto stack and provides better GPU resistance.
These three changes address the top three risks identified in this audit and are achievable without architectural changes.
docs/archive/three-mode-ui-design.md
+377
View File
@@ -0,0 +1,377 @@
# Three-Mode UI System: Easy / Pro / Chat
## Overview
Archipelago's UI will support three switchable modes, each targeting a different user experience level:
| Mode | Label in UI | Target User | What They See |
|------|-------------|-------------|---------------|
| **Pro** | Pro | Power users, developers, node operators | Current full interface — all services, configs, technical details |
| **Easy** | Easy | Complete beginners, non-technical users | Goal-based interface — "Open a Shop", "Store My Photos" |
| **Chat** | Chat | Everyone (future) | Conversational AI interface powered by AIUI |
### Key Principles
1. **Pro mode is preserved** — the current interface stays exactly as-is and continues to be improved
2. **Same URLs** — modes don't change route paths. `/dashboard` shows different content based on mode
3. **Cross-surfacing** — Easy mode goals are searchable from Spotlight (Cmd+K) and suggested in Pro mode
4. **Persistent preference** — mode choice saved to localStorage + backend UIData
---
## How Modes Work
### Architecture: Conditional Rendering
Rather than separate route trees (`/easy/home`, `/pro/home`), the mode controls **what renders within existing routes**:
```
Dashboard.vue (shared shell)
├── Sidebar → nav items change per mode
├── ModeSwitcher → always visible in sidebar
└── <RouterView>
└── Home.vue (dispatcher)
├── <GamerHome /> (Pro mode)
├── <EasyHome /> (Easy mode)
└── <ChatHome /> (Chat mode)
```
This means:
- Auth guards, WebSocket, stores — all shared
- URLs never change — bookmarks work regardless of mode
- Both modes use the same component library (glass-card, glass-button, etc.)
### Navigation Per Mode
**Pro Mode** (current, 7 items):
```
Home → My Apps → App Store → Cloud → Network → Web5 → Settings
```
**Easy Mode** (simplified, 3 items):
```
Home → My Services → Settings
```
**Chat Mode** (4 items):
```
Home → Chat → My Apps → Settings
```
---
## Easy Mode: Goal-Based Interface
### The Problem
Current interface says: "Here are 20+ services you can install. Figure out which ones you need, install them, configure them to talk to each other."
Easy mode says: **"What do you want to do?"**
### Goal Cards (Easy Mode Home)
When in Easy mode, the Home screen shows goal cards instead of the current 4 technical overview cards:
```
┌─────────────────────┐ ┌─────────────────────┐
│ 🏪 Open a Shop │ │ ⚡ Accept Payments │
│ │ │ │
│ Set up your own │ │ Receive Bitcoin & │
│ Bitcoin-powered │ │ Lightning payments │
│ online store │ │ │
│ │ │ ~30 min • Beginner │
│ ~45 min • Beginner │ │ ▸ Start │
│ ▸ Start │ └─────────────────────┘
└─────────────────────┘
┌─────────────────────┐ ┌─────────────────────┐
│ 📸 Store My Photos │ │ 📁 Store My Files │
│ │ │ │
│ Private photo │ │ Personal cloud │
│ backup & gallery │ │ storage & sync │
│ │ │ │
│ ~15 min • Beginner │ │ ~20 min • Beginner │
│ ▸ Start │ │ ▸ Start │
└─────────────────────┘ └─────────────────────┘
┌─────────────────────┐ ┌─────────────────────┐
│ ⚡ Lightning Node │ │ 🔑 Create Identity │
│ │ │ │
│ Run your own │ │ Sovereign DID & │
│ Lightning Network │ │ Nostr identity │
│ routing node │ │ │
│ │ │ ~5 min • Beginner │
│ ~40 min • Beginner │ │ ▸ Start │
│ ▸ Start │ └─────────────────────┘
└─────────────────────┘
┌─────────────────────┐
│ 💾 Back Up │
│ │
│ Encrypted backup │
│ of your entire │
│ node │
│ │
│ ~10 min • Beginner │
│ ▸ Start │
└─────────────────────┘
```
### Goal Workflow Wizard
Clicking a goal opens a **multi-step wizard** at `/dashboard/goals/:goalId`:
```
┌──────────────────────────────────────────────────────┐
│ ← Back to Goals │
│ │
│ Open a Shop │
│ Set up your own Bitcoin-powered online store │
│ │
│ Step 2 of 4 │
│ ═══════════════════════▓▓▓░░░░░░░░░░░░ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ ✅ Step 1: Install Bitcoin Node │ │
│ │ Bitcoin Core is running and syncing │ │
│ └─────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ ⏳ Step 2: Install Lightning Network │ │
│ │ Installing LND... [45%] │ │
│ │ ████████████████████░░░░░░░░░░░░░ │ │
│ └─────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ ○ Step 3: Install BTCPay Server │ │
│ │ Waiting for Lightning to be ready │ │
│ └─────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ ○ Step 4: Set Up Your Store │ │
│ │ Configure your store name and settings │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ ℹ️ Bitcoin needs to sync before Lightning can │
│ start. This takes 2-3 days on first run. │
│ │
└──────────────────────────────────────────────────────┘
```
**Smart features:**
- Steps already satisfied (app running from a previous goal) are auto-completed
- Dependency resolution: Bitcoin must be running before LND can start
- Real-time progress from WebSocket data patches
- `configure` steps open the app in the iframe launcher for the user to complete
### Goal Definitions
| Goal | What It Provisions | Estimated Time |
|------|-------------------|----------------|
| **Open a Shop** | Bitcoin Knots + LND + BTCPay Server | ~45 min |
| **Accept Payments** | Bitcoin Knots + LND | ~30 min |
| **Store My Photos** | Immich (photo management) | ~15 min |
| **Store My Files** | Nextcloud (cloud storage) | ~20 min |
| **Run a Lightning Node** | Bitcoin Knots + LND + channel setup | ~40 min |
| **Create My Identity** | Built-in DID + Nostr keypair | ~5 min |
| **Back Up Everything** | Built-in encrypted backup | ~10 min |
---
## Mode Switcher UI
### Desktop Sidebar
A compact three-segment toggle sits below the logo, above navigation:
```
┌──────────────────────┐
│ 🏝️ Archipelago │
│ v0.1.0 │
│ │
│ ┌──────┬──────┬────┐ │
│ │ Easy │ Pro │Chat│ │ ← Mode switcher
│ └──────┴──────┴────┘ │
│ │
│ ○ Home │
│ ○ My Apps │ ← Nav items change
│ ○ App Store │ per mode
│ ○ ... │
│ │
│ ⚙ Settings │
│ ↪ Logout │
│ ● Online │
└──────────────────────┘
```
### Settings Page
Full-width selection cards in a new "Interface Mode" section:
```
┌──────────────────────────────────────────────────────┐
│ Interface Mode │
│ Choose how you want to interact with your node. │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ │ │ ██████ │ │ │ │
│ │ Easy Mode │ │ Pro Mode │ │ Chat Mode │ │
│ │ │ │ (Active) │ │ (Soon) │ │
│ │ Goal-based │ │ Full │ │ AI chat │ │
│ │ guided │ │ control │ │ interface │ │
│ │ setup │ │ of all │ │ │ │
│ │ │ │ services │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└──────────────────────────────────────────────────────┘
```
Uses the existing `.path-option-card` / `.path-option-card--selected` pattern from OnboardingPath.vue.
### Mobile
Mode switcher is in Settings only (bottom tab bar has limited space).
---
## Cross-Surfacing: Goals Everywhere
### Spotlight Search (Cmd+K)
Goals are added to the help tree and appear in search results regardless of mode:
```
┌──────────────────────────────────────┐
│ 🔍 shop │
│ │
│ Quick Start Goals │
│ 🚀 Open a Shop │
│ 🚀 Accept Payments │
│ │
│ Navigate │
│ → App Store │
│ │
│ Actions │
│ → Install an App │
└──────────────────────────────────────┘
```
### Pro Mode Home
A "Quick Start Goals" section appears at the bottom of Pro mode's Home, giving power users easy access to the guided workflows:
```
┌──────────────────────────────────────────────────────┐
│ Quick Start Goals │
│ Not sure where to start? Try a guided setup. │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Open a Shop │ │ Accept │ │ Store Photos │ │
│ │ │ │ Payments │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└──────────────────────────────────────────────────────┘
```
---
## Chat Mode (Placeholder)
For now, Chat mode shows a placeholder with a disabled input:
```
┌──────────────────────────────────────────────────────┐
│ │
│ 💬 AI Assistant │
│ │
│ Conversational interface coming soon. │
│ Talk to your node, ask questions, and │
│ manage everything through natural language. │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ What would you like to do? │ │
│ └──────────────────────────────────────┘ │
│ │
│ AIUI integration in development │
│ │
└──────────────────────────────────────────────────────┘
```
When AIUI is integrated, this becomes the conversational interface where users can say things like "Set up a Lightning node" and the system guides them through it via chat.
---
## Data Model
### UIMode Type
```typescript
type UIMode = 'gamer' | 'easy' | 'chat'
```
Stored in:
- `localStorage` as `archipelago-ui-mode` (immediate, works offline)
- `UIData.mode` on the backend (synced via WebSocket, persists across devices)
### Goal Types
```typescript
interface GoalDefinition {
id: string // 'open-a-shop'
title: string // 'Open a Shop'
subtitle: string // 'Accept Bitcoin payments with your own store'
icon: string // Icon identifier
category: string // 'commerce', 'payments', 'storage', etc.
requiredApps: string[] // ['bitcoin-core', 'lnd', 'btcpay-server']
steps: GoalStep[] // Sequential steps
estimatedTime: string // '~45 minutes'
difficulty: 'beginner' | 'intermediate'
}
interface GoalStep {
id: string
title: string // 'Install Bitcoin Node'
description: string
appId?: string // Which app this step provisions
action: 'install' | 'configure' | 'verify' | 'info'
isAutomatic: boolean // Can system do this without user input?
}
```
---
## Implementation Order
| Phase | What | Files Changed | Visible Effect |
|-------|------|--------------|----------------|
| 1 | Data layer | types, stores, data files | None (foundation) |
| 2 | Mode switching | Dashboard, Settings, Router | Mode toggle appears, nav changes |
| 3 | Easy mode views | Home refactor, EasyHome, GoalDetail | Easy mode is functional |
| 4 | Chat + polish | Chat placeholder, Spotlight goals, Pro goals section | Complete system |
Each phase deploys independently. Phase 1 is invisible. Phase 2 adds the switcher. Phase 3 makes Easy mode work. Phase 4 polishes everything.
---
## File Inventory
### New Files (10)
```
src/types/goals.ts — Goal type definitions
src/data/goals.ts — Goal catalog (7 goals)
src/stores/uiMode.ts — UI mode Pinia store
src/stores/goals.ts — Goal progress tracking
src/components/ModeSwitcher.vue — Mode toggle widget
src/components/GamerHome.vue — Extracted current Home content
src/components/EasyHome.vue — Easy mode goal cards
src/components/ChatHome.vue — Chat mode home wrapper
src/views/GoalDetail.vue — Goal workflow wizard
src/views/Chat.vue — Chat placeholder
```
### Modified Files (11)
```
src/types/api.ts — Add UIMode type + mode field to UIData
src/router/index.ts — Add goals/:goalId and chat routes
src/views/Dashboard.vue — Computed nav items, ModeSwitcher in sidebar
src/views/Home.vue — Mode dispatcher (GamerHome/EasyHome/ChatHome)
src/views/Settings.vue — Interface Mode selection section
src/data/helpTree.ts — Goals in Spotlight search
src/style.css — Mode switcher, goal card, wizard CSS
src/stores/app.ts — Sync mode from backend
src/api/rpc-client.ts — setUIMode() RPC method
src/components/SpotlightSearch.vue — Visual indicator for goal items
mock-backend.js — ui.set-mode handler
```
docs/bitcoin-multi-version-design.md
+211
View File
@@ -0,0 +1,211 @@
# Bitcoin Multi-Version Support — Design
**Status:** implemented — all four phases shipped (catalog schema, install-time selection, in-app switch + auto-update toggle, and the verified image build pipeline). Downgrades are guarded: the update path never offers a lower version than what is running.
**Goal:** let a user choose *which* version of Bitcoin Core / Bitcoin Knots to
install (latest pre-selected, older versions in a dropdown), and later switch
versions or opt into auto-update — all manifest/catalog-driven, all served from
**our signed registry**, rootless, with **zero data loss** across version
changes.
See also: [`docs/registry-manifest-design.md`](registry-manifest-design.md)
(catalog distribution + signing this builds on),
and the production test gate (which must be green first).
---
## 1. Where we are today
### Image source / build
| Thing | Today |
|-------|-------|
| `apps/bitcoin-core/Dockerfile` | `FROM bitcoin/bitcoin:24.0` — a **community** image, **stale** (manifest says 28.4), no project-official Docker image exists |
| `apps/bitcoin-knots/` | **no Dockerfile** — `:latest` is built/pushed by hand |
| Registry | `scripts/image-versions.sh` → `ARCHY_REGISTRY="source.archipelago-foundation.org/lfg2025"`; only `BITCOIN_KNOTS_IMAGE=…/bitcoin-knots:latest` pinned, no Core pin |
| Tags in registry | **one tag per image**. No historical versions. |
### Version pinning
- `apps/bitcoin-core/manifest.yml` → `…/bitcoin:28.4` (pinned).
- `apps/bitcoin-knots/manifest.yml` → `…/bitcoin-knots:latest` (**floating** — a
liability for reproducibility and for "switch back to the version I had").
- `core/archipelago/src/container/app_catalog.rs` + `app-catalog/catalog.json`:
signed, hourly-fetched, carries `version` (badge text) + `image`.
`catalog_image_override()` overrides the manifest image **only if same-repo**.
`available_update_for_app()` already ignores floating tags for update
detection.
### Install path
- `prod_orchestrator.rs::install_fresh()` resolves the image as
**manifest image → catalog override → pull**. There is **no per-install
version parameter** — `orchestrator.install(app_id)` takes only the id.
- RPC `package.install` (`api/rpc/package/install.rs`) *accepts* `dockerImage` /
`version` params but for orchestrator-managed apps (bitcoin-core / bitcoin-knots
are allowlisted) it **ignores them** and lets the orchestrator resolve.
- **Conflict guard** (`prod_orchestrator.rs` ~1306–1325): core and knots may not
run simultaneously. Must be preserved by everything below.
### UI
- Install is **one-click, no modal** (`MarketplaceAppDetails.vue::installApp()`).
- Update badge + "Update to X" already exist (`appDetails/AppHeroSection.vue`,
RPC `package.update`).
- **No** Bitcoin-specific settings panel; all apps share `AppSidebar.vue`.
- Per-app config persisted **only at install time** as `containerConfig` →
`/var/lib/archipelago/app-configs/<id>.json`. **No post-install set-config RPC.**
---
## 2. Source-of-truth decision: official upstream → our registry
We use the **official releases** as upstream provenance, but nodes only ever pull
from our registry. Nodes do **not** fetch bitcoin.org / GitHub at install time —
that would break rootless/offline installs and the signed-registry trust model,
and neither project publishes an official Docker image anyway.
**Official sources (verified):**
| Impl | Index | Per-version asset pattern |
|------|-------|---------------------------|
| Bitcoin Core | [bitcoincore.org/en/releases](https://bitcoincore.org/en/releases/) · [github bitcoin/bitcoin](https://github.com/bitcoin/bitcoin/releases) | `https://bitcoincore.org/bin/bitcoin-core-<ver>/bitcoin-<ver>-x86_64-linux-gnu.tar.gz` + `SHA256SUMS` + `SHA256SUMS.asc` |
| Bitcoin Knots | [github bitcoinknots/bitcoin](https://github.com/bitcoinknots/bitcoin/releases) · [bitcoinknots.org/files](https://bitcoinknots.org/) | `https://bitcoinknots.org/files/<maj>.x/<ver>/bitcoin-<ver>-x86_64-linux-gnu.tar.gz` (`<ver>` e.g. `29.3.knots20260508`) |
Both ship **signed binary tarballs** with multi-builder Guix attestations
(`SHA256SUMS.asc`). The build pipeline verifies these **once, at build**; our DHT
Phase 0 registry signature then carries provenance to the fleet.
> Knots version strings embed a build date (`29.3.knots20260508`). Treat the full
> string as the tag; surface a friendly `29.3` + date in the UI.
---
## 3. Design
### Phase 0 — Reproducible, verified image pipeline *(prerequisite)*
New `scripts/build-bitcoin-image.sh <impl> <version>` that, per version:
1. Downloads the official tarball + `SHA256SUMS(.asc)` (GitHub release assets are
an identical mirror → fallback).
2. Verifies SHA256 **and** the Guix/builder GPG signatures. **Fail closed.**
3. Builds a minimal **rootless** image: pin a small base, unpack
`bitcoind`/`bitcoin-cli`. Keep the existing entrypoint probe
(`command -v bitcoind || find /opt -path '*/bin/bitcoind'`) so per-version
layout differences don't break startup.
4. Tags + pushes `:<version>` **and** updates the default pin (`:latest` /
`:28.4`-style) to the registry.
**Curate, don't mirror everything.** Publish a bounded set (proposal: current +
last ~3 majors), e.g. Core `31.0, 30.0, 29.3, 28.4, 27.2` and Knots
`29.3.knots…, 28.1.knots…, 27.1.knots…`. **`log` / document dropped versions** —
silent truncation reads as "all versions supported" when it isn't.
Also fixes existing debt: replaces the stale community `FROM bitcoin/bitcoin:24.0`
and gives Knots a real Dockerfile + non-floating tags.
### Phase 1 — Version catalog (signed, registry-distributed)
Extend `AppCatalogEntry` (forward-compatible — no `deny_unknown_fields`, old nodes
ignore it):
```jsonc
"bitcoin-core": {
"version": "31.0", // default / latest (existing field)
"image": "…/bitcoin:31.0", // existing
"versions": [ // NEW
{ "version": "31.0", "image": "…/bitcoin:31.0", "default": true },
{ "version": "30.0", "image": "…/bitcoin:30.0" },
{ "version": "28.4", "image": "…/bitcoin:28.4", "deprecated": true, "eol": "2026-...." }
]
}
```
Published to `releases/app-catalog.json`, signed by the existing release-root
mechanism. This is the **single source of truth** the UI reads for "what can I
install / switch to," and third-party-registry apps inherit the capability for
free. `version`/`image` stay as the default for back-compat.
### Phase 2 — Install-time version selection
- **Orchestrator:** add `install_with_image(app_id, Option<image_tag>)` (or an
optional arg on `install`). When a tag is supplied, **validate same-repo**
against the manifest (reuse `image_without_registry_or_tag()`), then override in
`install_fresh()`. Default path unchanged. Preserve the core/knots conflict
guard.
- **RPC:** thread the selected version/image from `package.install` into the
orchestrator for the allowlisted apps (the param is already received — just not
forwarded).
- **UI:** the first **install modal** in the app — latest pre-selected, dropdown
of `versions[]`, deprecated/EOL badges on old entries. On confirm, pass the
chosen version to `package.install`.
### Phase 3 — In-app version switch + auto-update toggle
- **UI:** a Bitcoin **"Version & Updates"** card (conditional in `AppSidebar.vue`
for `bitcoin-core` / `bitcoin-knots`): current version, a switch dropdown, and
an **auto-update-to-latest** toggle.
- **Switch = controlled re-pull/recreate** reusing the `package.update`
machinery but targeting an arbitrary (incl. older) tag → effectively
`package.set-version`.
- **Persistence:** new `package.set-config` RPC writing the existing
`app-configs/<id>.json` (`{ pinnedVersion, autoUpdate }`).
- **Auto-update:** the existing hourly catalog check, when `autoUpdate:true`,
triggers `package.update` to the catalog default. A pinned version **suppresses
the update badge**.
---
## 4. Invariants & safety rails
- **Rootless only.** Pipeline images and run path stay rootless; no Docker-socket,
no privileged.
- **No data loss across version change.** Preserve `/var/lib/archipelago/bitcoin`,
secrets (`bitcoin-rpc-password`, `…-rpcauth`), ports, and the adoption container
name on every install / switch / update.
- **⚠️ Downgrade vs. chainstate (highest risk).** Bitcoin Core refuses to start on
a chainstate written by a *newer* version unless reindexed (expensive, or data
loss on a pruned node). The UI **must** warn loudly on downgrade; the
orchestrator should gate/confirm it and never silently wipe. Pruned nodes can't
simply `-reindex`.
- **Core ⇄ Knots switch** stays governed by the existing conflict guard; treat an
impl switch as distinct from a version switch.
- **Floating tags** (`latest`) are never advertised as a selectable "version" and
never counted as an available update (already handled by
`available_update_for_app`).
- **Verify on a real node** and pass the lifecycle gate before any
tag.
---
## 5. Files / seams (no code yet)
| Concern | File |
|---------|------|
| Image build/push | new `scripts/build-bitcoin-image.sh`; `apps/bitcoin-core/Dockerfile`; new `apps/bitcoin-knots/Dockerfile`; `scripts/image-versions.sh` |
| Catalog schema | `core/archipelago/src/container/app_catalog.rs`; `releases/app-catalog.json` (+ `app-catalog/catalog.json`) |
| Install override | `core/archipelago/src/container/prod_orchestrator.rs` (`install` / `install_fresh`); `api/rpc/package/install.rs`; `api/rpc/dispatcher.rs` |
| Switch / set-config RPC | `api/rpc/package/update.rs`; new `package.set-config` handler; `app-configs/<id>.json` |
| Install modal | `neode-ui/src/views/MarketplaceAppDetails.vue`; new `…/marketplace/AppInstallModal.vue` |
| Version & Updates card | `neode-ui/src/views/appDetails/AppSidebar.vue`; `neode-ui/src/api/rpc-client.ts`; `neode-ui/src/types/api.ts` |
---
## 6. Open questions
1. **Curated version set** — how many majors back do we host, and storage budget
on the registry?
2. **Multi-arch** — fleet is x86_64 today; do any nodes need arm64 images?
3. **Pruned-node downgrade policy** — block outright, or allow with an explicit
"this will require re-sync / may lose pruned data" confirmation?
4. **Auto-update default** — off (opt-in) for a consensus-critical app like
Bitcoin? (Recommended: **off**, explicit opt-in.)
5. **Knots date-suffix UX** — how to display `29.3.knots20260508` cleanly.
---
## Sources
- [Bitcoin Core releases](https://bitcoincore.org/en/releases/)
- [bitcoin/bitcoin releases](https://github.com/bitcoin/bitcoin/releases)
- [bitcoinknots/bitcoin releases](https://github.com/bitcoinknots/bitcoin/releases)
- [Bitcoin Knots](https://bitcoinknots.org/)
- [bitcoin.org version history](https://bitcoin.org/en/version-history)
docs/bitcoin-rpc-relay.md
+291
View File
@@ -0,0 +1,291 @@
# Bitcoin RPC Relay for External Wallets
This note captures the pattern used to let an external wallet, such as Wasabi,
use an Archipelago Bitcoin node for transaction relay without exposing the
node's admin RPC credentials.
## Goal
Expose a public HTTPS JSON-RPC endpoint that can broadcast transactions and read
basic chain/mempool state, while preventing wallet and admin RPC access.
The endpoint should be fronted by nginx or another TLS reverse proxy:
```text
wallet client -> https://<subdomain>/ -> reverse proxy -> Archipelago node nginx -> bitcoind RPC
```
Do not expose Bitcoin RPC credentials with wallet/admin access to external
users.
## Restricted RPC User
Create a separate RPC user, currently named `txrelay`, with an `rpcauth` secret
and a Bitcoin RPC whitelist.
Allowed RPC methods:
```text
sendrawtransaction
submitpackage
testmempoolaccept
getmempoolinfo
getrawmempool
getmempoolentry
getnetworkinfo
getblockchaininfo
getblockcount
getblockhash
getblockheader
getrawtransaction
gettxout
decoderawtransaction
decodescript
estimatesmartfee
```
Wallet/admin access is denied by setting `-rpcwhitelistdefault=0` and giving the
`txrelay` user only the method whitelist above.
Secrets live under:
```text
/var/lib/archipelago/secrets/bitcoin-rpc-txrelay-password
/var/lib/archipelago/secrets/bitcoin-rpc-txrelay-rpcauth
/var/lib/archipelago/secrets/bitcoin-rpc-txrelay-client.env
```
Do not commit these files or paste them into docs.
## Archipelago UI/API Flow
The productized flow is managed from the Bitcoin Core/Knots custom UI in the
`Transaction Relay Sharing` panel.
Implemented RPC methods:
```text
bitcoin.relay-status
bitcoin.relay-update-settings
bitcoin.relay-request-peer
bitcoin.relay-approve-request
bitcoin.relay-reject-request
bitcoin.relay-create-tor-service
```
When peer sharing is enabled, `bitcoin.relay-update-settings` automatically
provisions the restricted `txrelay` password, `rpcauth`, and client env file if
they do not already exist. If those files were just generated, restart Bitcoin
Core/Knots so `bitcoind` reloads the `txrelay` `rpcauth` and whitelist flags.
The UI shows:
```text
HTTP / HTTPS / Tor relay endpoint settings
local sync status
restricted credential readiness, without printing the password
trusted peer dropdown, disabled until the local node is synchronized
incoming relay requests with approve/reject actions
outbound relay requests and approval status
```
Approving an incoming peer request sends the selected endpoint plus restricted
`txrelay` credentials through the existing encrypted peer-message path. On the
requesting node, approved peer credentials are stored in a per-peer secret env
file:
```text
/var/lib/archipelago/secrets/bitcoin-relay-peer-<peer-pubkey-prefix>.env
```
The UI returns the credential secret path and approved endpoint metadata, but it
does not display the raw password.
For dev review, the mock server exposes the Bitcoin UI at:
```text
http://localhost:8102/app/bitcoin-ui/
```
## Bitcoin Startup Flags
The Bitcoin Knots app should add the restricted user only when the secret exists:
```sh
RPC_TXRELAY_AUTH="$(printenv BITCOIN_RPC_TXRELAY_RPCAUTH || true)"
RPC_TXRELAY_FLAGS="-rpcwhitelistdefault=0"
if [ -n "$RPC_TXRELAY_AUTH" ]; then
RPC_TXRELAY_FLAGS="$RPC_TXRELAY_FLAGS -rpcauth=$RPC_TXRELAY_AUTH -rpcwhitelist=txrelay:sendrawtransaction,submitpackage,testmempoolaccept,getmempoolinfo,getrawmempool,getmempoolentry,getnetworkinfo,getblockchaininfo,getblockcount,getblockhash,getblock,getblockheader,getrawtransaction,gettxout,gettxspendingprevout,decoderawtransaction,decodescript,estimatesmartfee,uptime,ping,getconnectioncount,getpeerinfo,getindexinfo,getdeploymentinfo,getchaintips"
fi
```
Then include `$RPC_TXRELAY_FLAGS` in the `bitcoind` command. Keep the local
`archipelago` RPC user unrestricted for internal services by using
`-rpcwhitelistdefault=0` and only setting a whitelist for `txrelay`.
The current implementation touches:
```text
apps/bitcoin-knots/manifest.yml
scripts/container-specs.sh
```
## Node nginx
The Archipelago node can expose a host-based nginx vhost that proxies to local
Bitcoin RPC:
```nginx
limit_req_zone $binary_remote_addr zone=bitcoin_rpc_ext:10m rate=5r/s;
server {
listen 80;
server_name rpc.example.com;
client_max_body_size 2m;
location / {
limit_req zone=bitcoin_rpc_ext burst=20 nodelay;
limit_req_status 429;
proxy_pass http://127.0.0.1:8332;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_connect_timeout 5s;
proxy_send_timeout 120s;
proxy_read_timeout 120s;
proxy_buffering off;
}
}
```
If another public reverse proxy terminates TLS, point it at:
```text
http://<archipelago-lan-ip>:80
```
For the tested node the LAN upstream was:
```text
http://archipelago.local:80
```
The public proxy should serve a valid TLS certificate for the chosen subdomain.
## DNS and Routing
Use a subdomain that resolves to the public reverse proxy:
```text
Type: A
Host/Name: <subdomain-only>
Value: <public-ip>
```
For example, if the desired hostname is `rpc.example.com`, the DNS host/name
field is usually only `rpc`, not the full `rpc.example.com`. Entering the full
hostname in some DNS panels can accidentally create:
```text
rpc.example.com.example.com
```
The public proxy should forward:
```text
TCP 443 -> TLS reverse proxy for the subdomain
TCP 80 -> optional, needed for HTTP-01 certificate issuance or redirects
```
If the public proxy is separate from the Archipelago node, configure it with:
```text
server_name: <subdomain>
scheme: http
upstream host: <archipelago-lan-ip>
upstream port: 80
```
## Verification
Check authoritative DNS:
```sh
dig @<authoritative-dns-ip> <subdomain> A +noall +answer +authority
dig @1.1.1.1 +short <subdomain> A
```
Check TLS:
```sh
openssl s_client -connect <subdomain>:443 -servername <subdomain> </dev/null
```
Check the public RPC path:
```sh
. /var/lib/archipelago/secrets/bitcoin-rpc-txrelay-client.env
curl -sS --user "$BITCOIN_RPC_TXRELAY_USER:$BITCOIN_RPC_TXRELAY_PASSWORD" \
--data-binary '{"jsonrpc":"1.0","id":"check","method":"getblockchaininfo","params":[]}' \
"<relay-endpoint-url>"
```
Check that transaction broadcast reaches Bitcoin RPC, without needing a real
transaction:
```sh
curl -sS --user "$BITCOIN_RPC_TXRELAY_USER:$BITCOIN_RPC_TXRELAY_PASSWORD" \
--data-binary '{"jsonrpc":"1.0","id":"badtx","method":"sendrawtransaction","params":["00"]}' \
"<relay-endpoint-url>"
```
Expected result is a Bitcoin RPC validation error such as `TX decode failed`,
which confirms the request reached `sendrawtransaction`.
If a wallet verifies the connection but reports `RPC Forbidden` during
broadcast, the credentials authenticated but the broadcast method was outside
the loaded `txrelay` whitelist. Restart the active Bitcoin backend after
updating the whitelist, then test both `sendrawtransaction` and, for newer
package-relay clients, `submitpackage`. Also confirm the public reverse proxy
passes the wallet's `Authorization` header through to `127.0.0.1:8332`; do not
point public wallet traffic at the Bitcoin UI `/bitcoin-rpc/` helper, because
that helper injects the local dashboard credential.
Check that wallet/admin RPC is blocked:
```sh
curl -sS -o /tmp/txrelay-deny.json -w '%{http_code}\n' \
--user "$BITCOIN_RPC_TXRELAY_USER:$BITCOIN_RPC_TXRELAY_PASSWORD" \
--data-binary '{"jsonrpc":"1.0","id":"deny","method":"listwallets","params":[]}' \
"<relay-endpoint-url>"
```
Expected result:
```text
403
```
## Tested Outcome
The working endpoint used in this setup was:
```text
https://<your-mempool-instance>/
```
It was verified with:
```text
DNS resolves
TLS certificate is valid
txrelay credentials authenticate
getblockchaininfo returns chain=main
sendrawtransaction reaches Bitcoin RPC
listwallets is blocked for txrelay
```
docs/bulletproof-containers.md
+319
View File
@@ -0,0 +1,319 @@
# Bulletproof Containers
**Status**: historical design record (agreed 2026-04-22). The *architecture* —
level-triggered, desired-state reconciliation — was adopted and is live. Several
specifics below were not built as written, so read this for the incident history
and the reasoning, not as a description of the code. For how the lifecycle
actually works today, read [Container lifecycle](container-lifecycle.md).
What became of the plan, verified against the tree:
| Item | Outcome |
|---|---|
| Level-triggered reconciler | ✅ Shipped, but as `container/boot_reconciler.rs` + `container/prod_orchestrator.rs`. The `core/archipelago/src/reconcile/` module laid out below (`desired.rs`/`current.rs`/`diff.rs`/`apply.rs`/…) **was never created** — no file in it exists |
| FM5 post-OTA probe + auto-rollback | ✅ Shipped — `update-pending-verify.json` (`update.rs:100`) |
| FM4 `host.archipelago` alias | ✅ Shipped — `AddHost=host.archipelago:10.89.0.1` in generated units |
| FM1/FM3 Quadlet ownership | ◐ Partial. Companion UIs run as Quadlet units; **main app containers do not** — `use_quadlet_backends` still defaults false, so the "v1.7.48+ full migration" below has not happened |
| FM2 bitcoin.conf drift | ◐ Solved differently. There is no `reconcile::derived::render_bitcoin_conf`; instead bitcoind is run with an explicit `-conf` derived from secrets at each start and stale datadir configs are removed (`remove_stale_bitcoin_conf`) |
| FM6 podman corrupt-state self-heal | ❌ **Not implemented.** No `podman system renumber` recovery, no startup probe for "invalid internal status". The failure that made a node unreachable in 2026-04 would still need manual SSH |
Note also that the unit paths below say `/etc/containers/systemd/`; units are
actually written per-user to `~/.config/containers/systemd/`
(`quadlet.rs:DEFAULT_REL_UNIT_DIR`), since the whole path is rootless.
**Target**: zero-manual-intervention container lifecycle. A user installs,
uninstalls, reboots, updates, or loses power — every combination must leave the
node in a known-good state without SSH.
---
## Why we're doing this
The v1.7.38 and v1.7.39 rollouts on 2026-04-22 exposed a cluster of container-lifecycle failures that required manual SSH recovery on every affected node. If a user had been on those nodes, they'd have been stuck with "can't reach" or 500 errors and no path forward. We can't ship beta with this class of failure on the table.
The pattern under every failure: **the canonical source of truth had the right answer, but derived state drifted away from it and nothing noticed or fixed it.**
### The six failure modes
| # | Symptom | Root cause |
|---|---|---|
| FM1 | `archy-bitcoin-ui` + `archy-lnd-ui` disappeared from `podman ps -a` after a daemon restart | Archipelago owns container creation imperatively; no owner recreates companions after a crash mid-transition |
| FM2 | ElectrumX "Daemon connection problem" | `bitcoin.conf`'s `rpcauth` drifted from `/var/lib/archipelago/secrets/bitcoin-rpc-password` — config written once at install, never re-derived |
| FM3 | archipelago.service `status=226/NAMESPACE` crash-loop SIGKILL'd every child container | Containers were children of archipelago's cgroup; systemd teardown killed them. `KillMode=control-group` default |
| FM4 | `host.containers.internal` inside containers resolved to LAN gateway (192.168.1.254) | Known podman bug on bridge networks pre-5.3 ([#22644](https://github.com/containers/podman/issues/22644)) |
| FM5 | Nginx 500 fleet-wide after OTA | Tarball root dir was `drwx------` (700), extracted identically on every node. Fixed in v1.7.40 at build time; still need post-OTA auto-rollback |
| FM6 | Rootless podman's `libpod/bolt_state.db` vanished → whole registry node unreachable | No detection of corrupt state; required manual `rm -rf /run/user/$UID/libpod` + `podman system renumber` |
---
## Architecture decision
**Adopt balena-style, level-triggered, desired-state reconciler built on Quadlet + sdnotify.**
This is the one architecture that would have prevented all six failures, because each one is "reality drifted from the intended config and nothing noticed" — the exact problem reconcilers are designed for.
### Why not the alternatives
- **Keep imperative + patch per-failure** — we've been doing this. Five releases in a day. Doesn't scale.
- **Migrate to LXC (StartOS's path)** — 6-month project. Our investment in podman (`install.rs`, `docker_packages.rs`, `image_versions.rs`) is substantial. Quadlet gives us StartOS's isolation property without the migration.
- **Ship k3s / MicroShift** — 400-800 MB RAM baseline on top of bitcoind/electrs. Overkill for a home node OS.
- **Edge-triggered like Umbrel** — their `app.ts` has an explicit TODO admitting they don't handle failure events. We'd inherit the same bug class.
### The four patterns (from mature players)
1. **Desired-state-first, level-triggered reconcile.** balena-supervisor, Kubernetes operators, NixOS. A supervisor owns a manifest of *what should run*; on every tick it diffs against *what is running* and issues steps.
2. **Every container is its own systemd unit, not a child of the daemon.** Red Hat's Quadlet pattern: a `.container` file is parsed by a systemd *generator* into a normal `.service`. The daemon can crash without taking any containers with it.
3. **sdnotify readiness + HealthCmd + rollback.** Podman v3.4+ has real rollback: bad image fails health check, systemd considers service failed, Podman re-tags the previous image digest.
4. **Credentials and config derived from canonical secrets on every apply.** Not trusted across upgrades; re-rendered idempotently from single source of truth.
### Fix-per-failure
| Failure | Fix |
|---|---|
| FM1 | Move companions to Quadlet `.container` files in `/etc/containers/systemd/`. systemd (not archipelago) owns them |
| FM2 | `reconcile::derived::render_bitcoin_conf(secrets)` — pure function, runs every tick, atomic rewrite + HUP on drift |
| FM3 | `KillMode=mixed` in archipelago.service + containers in their own `archipelago-apps.slice`. Quadlet units already live outside archipelago's cgroup |
| FM4 | Ship `/etc/containers/containers.conf` with `host_containers_internal_ip = "10.89.0.1"` + `default_rootless_network_cmd = "pasta"`; also `--add-host=host.archipelago:10.89.0.1` in every unit |
| FM5 | Post-OTA `curl -k https://127.0.0.1/` health probe in new binary startup. If non-200 within 90s, rollback to `web-ui.bak` + binary-backup |
| FM6 | Startup probe: `podman info` with timeout. On "invalid internal status", clear `/run/user/$UID/{containers,libpod,podman}` + `podman system renumber` + reconcile tick rebuilds from Quadlet units |
---
## New code layout (lands in v1.7.48)
```
core/archipelago/src/reconcile/
mod.rs run_reconcile_loop, reconcile_once — called from main.rs
desired.rs DesiredState built from packages.json + catalog + secrets
current.rs snapshot via `systemctl list-units archy-*.service` + `podman ps -a --format json`
diff.rs pure: reconcile(desired, current) -> Vec<Step> (unit-testable without podman)
apply.rs step executor with timeouts, structured logs, backoff
quadlet.rs write `.container` / `.volume` / `.network` units atomically
derived.rs render_bitcoin_conf, render_containers_conf, render_nginx_app_routes
backoff.rs restart-history tracking (moved from health_monitor.rs)
```
### Step types (idempotent)
```rust
enum Step {
WriteQuadletUnit(path, content),
WriteDerivedFile(path, content),
WriteSecret(path, content),
DaemonReload,
EnsureStarted(unit),
StopUnit(unit),
RestartUnit(unit),
PullImage(ref),
}
```
### Triggers
- 30s interval tick
- install/uninstall RPC
- update-applied event
- explicit `/rpc/v1/reconcile.tick`
- podman event stream (if available)
Level-triggered + idempotent — every call considers full desired vs current diff. Missed ticks/events are irrelevant.
### Edits to existing code
- **`src/main.rs`**: replace `tokio::spawn(crash_recovery::start_stopped_containers)` with `tokio::spawn(reconcile::run_reconcile_loop(state))`. Keep self-heal perms + PID-marker crash detection.
- **`src/api/rpc/package/install.rs`**: stop calling `podman run` directly. Writes desired state + Quadlet unit + signals reconciler. Reconciler does pull + `systemctl start`.
- **`src/api/rpc/package/runtime.rs`** + `lifecycle.rs` + `stacks.rs`: same pattern — mutate desired state, reconciler applies.
- **`src/crash_recovery.rs`**: keep PID-marker + snapshot. Delete `start_stopped_containers` (reconciler handles cold boot). Keep `user-stopped.json` as `AppSpec.desired_state: Started | UserStopped | Uninstalled`.
- **`src/health_monitor.rs`**: strip restart logic. Keep memory-leak detection; push unhealthy events as `Trigger::ContainerUnhealthy(name)`.
- **`src/bitcoin_rpc.rs`**: add `pub fn derive_rpcauth_line(user, pass) -> String` (HMAC-SHA256 per Bitcoin Core's `rpcauth.py`).
- **`src/update.rs`**: post-swap health probe + auto-rollback (v1.7.41).
---
## Shipping order
Each release is independently deployable. Not a big-bang rewrite.
### v1.7.41 — Post-OTA health probe + auto-rollback (closes FM5)
- In `update.rs`: write `/var/lib/archipelago/update-pending-verify.json` just before service restart, with `applied_at`, `new_version`, `previous_version`, deadline.
- In `main.rs` startup: read marker, spawn verification task. Wait 15s for full startup, then `curl -k https://127.0.0.1/` with retries up to 90s.
- On 200: delete marker.
- On non-200 after window: call `rollback_update(data_dir)` (already exists), restart service to boot the old binary.
- Smallest diff, highest ROI.
### v1.7.42 — containers.conf + host.archipelago alias (closes FM4)
- Idempotent write of `/etc/containers/containers.conf` on startup (archipelago compares hash, rewrites only on drift).
- Add `--add-host=host.archipelago:10.89.0.1` to every generated container in `install.rs` / `docker_packages.rs`.
- ElectrumX `DAEMON_URL` migrates from `host.containers.internal` → `host.archipelago`.
### v1.7.43 — `reconcile::derived` for bitcoin.conf / lnd.conf (closes FM2)
- Pure function `render_bitcoin_conf(secrets) -> String`.
- Tick every 30s: read secret, derive `rpcauth`, compare to on-disk, atomic rewrite (via `tempfile::NamedTempFile::persist`) + `podman exec ... kill -HUP 1` on drift.
- Same pattern for `lnd.conf`.
- First user of the eventual `reconcile::` module — ships the `derived.rs` piece early.
### v1.7.44 — Podman state self-heal on startup (closes FM6)
- Startup probe: `podman info --format '{{.Host.OS}}'` with 10s timeout.
- On "invalid internal status" or similar:
- `systemctl --user stop podman.socket podman.service`
- `rm -rf /run/user/$UID/{containers,libpod,podman}`
- `podman system renumber`
- Trigger reconcile tick (will rebuild containers from their source of truth)
- Surface clear error on `/health` if recovery fails — don't silently serve 502.
### v1.7.45–47 — Quadlet migration per companion (closes FM1 + FM3)
One companion per release so regressions have a narrow blame window:
- **v1.7.45**: `archy-bitcoin-ui` → Quadlet `.container` unit
- **v1.7.46**: `archy-lnd-ui` → Quadlet
- **v1.7.47**: `archy-electrs-ui` → Quadlet
Each:
1. Write `.container` file to `/etc/containers/systemd/<name>.container`
2. `systemctl daemon-reload`
3. `systemctl enable --now <name>.service`
4. Remove the `podman run` path from `install.rs` for that name
5. Add Goss probe for the lifecycle test matrix
### v1.7.48+ — Full reconcile module
- `core/archipelago/src/reconcile/` replaces imperative `install.rs` container management.
- Main app containers (bitcoin-knots, bitcoin-core, lnd, electrumx, btcpay-server, mempool, fedimint) become Quadlet units.
- `install.rs` shrinks to ~300 lines of "write desired state, poke reconciler."
- Biggest diff, lands last.
---
## Test harness (parallel track)
### Stack
- **Outer runner**: `bats-core` — TAP-style bash testing, readable by anyone
- **Verifier**: `goss` — YAML assertions on ports, processes, HTTP endpoints, files. Reused by CI + live probe
- **Chaos layer**: Chaos Toolkit JSON experiments (steady-state-hypothesis → method → rollback → verify)
- **VM layer**: `vmtest` (Go) for reboot-survival + ISO-boot tests, or raw QEMU+SSH
- **Tor probe**: curl through archipelago's own tor SOCKS5 (`--socks5-hostname 127.0.0.1:9050`), 60-180s retry window
- **Live probe**: small Rust agent on every fleet node, ships same Goss YAMLs to Prometheus. Neither Umbrel nor StartOS has this — real differentiator.
- **Reproducibility**: btrfs subvolume snapshots primary (fast), QEMU qcow2 for ISO/kernel-level repro
### Directory layout
```
tests/lifecycle/
bats/
_helpers.bash # install_app, wait_healthy, assert_no_orphans
00_bootstrap.bats
10_install.bats # per-app install
20_ui_reachable.bats # direct port + HTTPS proxy + iframe
30_tor_reachable.bats # .onion probe
40_stop_start.bats
50_restart.bats
60_reboot.bats # vmtest-driven
70_reinstall.bats # idempotence + data preservation
80_uninstall.bats # leak check
90_soak.bats # 2-6h hold, periodic probe
goss/
bitcoin-knots.yaml
bitcoin-core.yaml
lnd.yaml
electrumx.yaml
btcpay-server.yaml
mempool.yaml
fedimint.yaml
chaos/
kill9_archipelago_mid_install.json
wipe_bolt_db.json
kill9_bitcoind.json
reboot_during_ota.json
corrupt_bitcoin_conf.json
systemctl_restart_mid_install.json
fill_disk_99_percent.json
kill_tor.json
delete_nginx_snippet.json
clock_jump_30min.json
vm/
iso_boot_smoke.go
reboot_survival.go
ci/
vm_runner.sh
collect_artifacts.sh
probe/archy-probe/ # Rust bin, reuses goss YAMLs, ships to fleet
Makefile # `make beta-matrix`, `make chaos`, `make soak`
```
### Minimum beta matrix
7 apps × 9 lifecycle events × 10 chaos scenarios. Pass = every MUST-ship cell green on fresh rootless-podman single-node CI.
| Case \ App | knots | core | lnd | electrumx | btcpay | mempool | fedimint |
|---|---|---|---|---|---|---|---|
| Fresh install | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| UI direct port | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| UI HTTPS proxy | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| UI iframe | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Tor .onion reachable | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ |
| Stop → ports released | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Restart → integrations | — | — | ✓↔btc | ✓↔btc | ✓↔btc,lnd | ✓↔electrs | — |
| Reboot survival | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Reinstall idempotent | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Uninstall no orphans | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 6h soak | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
**Harness scaffold lands in v1.7.41.** First lifecycle tests blocking v1.7.45. Full matrix + chaos suite blocking beta tag.
### Chaos scenarios (10)
Ordered by likelihood × severity:
1. `kill -9 archipelagod` mid-install → systemd restart, in-flight install resumes or cleanly rolls back
2. `rm bolt_state.db` while service stopped → restart regenerates, no data loss in named volumes
3. `systemctl restart archipelago` mid-install → no orphans, no half-state
4. Reboot mid-OTA → old version intact OR new version active, never half
5. Corrupt `bitcoin.conf` → container restart-loops; UI surfaces banner; reconcile re-derives; other apps unaffected
6. Fill `/var` to 99% → graceful degradation, disk-pressure report
7. Revoke rootless-netns → self-heal within Tor descriptor window
8. `pkill -9 tor` → supervisor restarts; onions reachable within 3–5 min
9. Delete nginx conf snippet → reconciler rewrites or `archipelago doctor` flags drift
10. Clock jump +30min → daemons survive; Tor recovers
---
## Decision log
| Decision | Answer | Rationale |
|---|---|---|
| Scope | 6+ incremental releases, not big-bang rewrite | Each closes one failure class, narrow blame window |
| Quadlet migration | Yes | Isolation from daemon crashes, systemd-native recovery, free from Red Hat's production patterns. Minimum podman version becomes 4.4+ (fine for modern Debian) |
| Live probe to Prometheus | Yes, part of beta | Genuine differentiator — neither Umbrel nor StartOS has this. Adds Grafana dep |
| Test gating | Scaffold in v1.7.41, first tests blocking v1.7.45, full matrix blocking beta tag | Gradual rather than all-or-nothing |
---
## Key sources
### Architecture
- Umbrel [app.ts](https://raw.githubusercontent.com/getumbrel/umbrel/master/packages/umbreld/source/modules/apps/app.ts) — edge-triggered, TODO on failure handling
- StartOS [repo](https://github.com/Start9Labs/start-os), [v0.4 podman→LXC announce](https://community.start9.com/t/startos-v0-4-0-alpha-10-has-replaced-podman-new-commands-for-terminal/4062)
- balena-supervisor [repo](https://github.com/balena-os/balena-supervisor), [Supervisor API](https://docs.balena.io/reference/supervisor/supervisor-api)
- Quadlet: [Dan Walsh 2023 blog](https://www.redhat.com/en/blog/quadlet-podman), [podman-systemd.unit(5)](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html)
- Podman rollback: [auto-update blog](https://www.redhat.com/en/blog/podman-auto-updates-rollbacks), [podman-auto-update(1)](https://docs.podman.io/en/latest/markdown/podman-auto-update.1.html)
- Kubernetes operator pattern: [Kubebuilder reconcile](https://deepwiki.com/kubernetes-sigs/kubebuilder/5.2-reconciliation-loop), [good practices](https://book.kubebuilder.io/reference/good-practices)
- NixOS containers: [wiki](https://wiki.nixos.org/wiki/NixOS_Containers)
### Known bugs & references
- `host.containers.internal` → LAN: [podman #22644](https://github.com/containers/podman/issues/22644), [#23782](https://github.com/containers/podman/issues/23782)
- `bolt_state.db` recovery: [podman #17730](https://github.com/containers/podman/issues/17730), [staticdir mismatch #20872](https://github.com/containers/podman/issues/20872)
- aardvark-dns flakiness: [#20396](https://github.com/containers/podman/issues/20396), [#22407](https://github.com/containers/podman/issues/22407)
- systemd 226/NAMESPACE: [Arch forum](https://bbs.archlinux.org/viewtopic.php?id=156963), [systemd #29526](https://github.com/systemd/systemd/issues/29526)
- [systemd CGROUP_DELEGATION](https://systemd.io/CGROUP_DELEGATION/), [systemd.kill(5)](https://www.freedesktop.org/software/systemd/man/latest/systemd.kill.html)
### Test harness prior art
- Umbrel [ci.yml](https://github.com/getumbrel/umbrel/blob/master/.github/workflows/ci.yml) — Vitest + qemu matrix fan-out
- [YunoHost package_check](https://github.com/YunoHost/package_check) — closest analog, scored per-app lifecycle harness on LXC
- [bats-core](https://github.com/bats-core/bats-core)
- [Goss](https://github.com/goss-org/goss), [dgoss](https://github.com/aelsabbahy/goss-docker)
- [Chaos Toolkit](https://chaostoolkit.org/)
- [vmtest (Go)](https://github.com/anatol/vmtest)
### Tor
- [rend-spec-v3](https://github.com/torproject/torspec/blob/main/rend-spec-v3.txt) — descriptor lifetime + republish cadence
- [stem](https://stem.torproject.org/) — Python Tor controller for `HS_DESC UPLOADED` waits
docs/companion-keyboard-viewport.md
+99
View File
@@ -0,0 +1,99 @@
# Companion app — soft-keyboard viewport handover
**Audience:** the companion (Android WebView wrapper) developer.
**Reported:** 2026-08-04 by the operator — in chat, when the soft keyboard opens,
padding is added to the bottom tab bar and the page scrolls; the chat window
should instead scale to the height that remains above the keyboard.
## Why this is (most likely) companion-side
The symptom described — content keeps its full height, the browser *pans/scrolls*
the focused input into view, and the fixed bottom bar picks up a visual gap — is
the classic Android `adjustPan` (or edge-to-edge-without-IME-insets) signature.
The web side already implements the correct contract, verified in-repo:
1. **`neode-ui/index.html`** carries
`interactive-widget=resizes-content` in its viewport meta. In Chrome 108+
this makes the keyboard resize the **layout** viewport, so
`window.innerHeight` shrinks.
2. **`neode-ui/src/main.ts` → `syncViewportHeightVar()`** mirrors
`window.innerHeight` into the CSS var `--visual-viewport-height` on
`resize`, `orientationchange`, and `visualViewport.resize`. It deliberately
uses `innerHeight` (not `visualViewport.height`) so the value shares a
reference frame with `position: fixed` elements like the mobile tab bar.
3. **`neode-ui/src/style.css`** sizes the mobile layout (including the chat
iframe container) from
`var(--visual-viewport-height, 100dvh)` minus the tab-bar/safe-area vars.
So on mobile web Chrome, the keyboard shrinks `innerHeight`, the var updates,
and the chat scales. **An Android WebView ignores the `interactive-widget`
meta entirely** — keyboard resize there is governed by the host app. If the
host pans instead of resizing, no amount of web CSS can fix it: the WebView's
`innerHeight` never changes and the system scrolls the page instead.
## What the companion app should do
Pick the branch that matches how the Activity is configured:
### A. Not edge-to-edge (no `WindowCompat.setDecorFitsSystemWindows(window, false)`)
Set the soft-input mode so the WebView is *resized*, not panned:
```xml
<!-- AndroidManifest.xml, on the Activity hosting the WebView -->
<activity
android:name=".MainActivity"
android:windowSoftInputMode="adjustResize" />
```
`adjustPan` (and on some OEM builds the historical default `adjustUnspecified`)
produces exactly the reported behaviour.
### B. Edge-to-edge (decorFitsSystemWindows = false)
`adjustResize` alone stops working in edge-to-edge; you must consume the IME
inset yourself and resize the WebView:
```kotlin
ViewCompat.setOnApplyWindowInsetsListener(webViewContainer) { view, insets ->
val ime = insets.getInsets(WindowInsetsCompat.Type.ime())
val bars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
// Resize the container to end above the keyboard (or the nav bar when closed)
view.updatePadding(bottom = maxOf(ime.bottom, bars.bottom))
WindowInsetsCompat.CONSUMED
}
```
(If targeting SDK 35+, edge-to-edge is enforced, so branch B is the one that
applies.)
### Do NOT compensate on the web side
Please don't inject extra bottom padding, margins, or scroll offsets into the
page from the wrapper — the web layout already subtracts the tab bar and safe
areas from `--visual-viewport-height`, and wrapper-side compensation double
counts (that is the "padding added to the tabs" half of the symptom).
## How to verify the fix
In the WebView's remote-debug console (`chrome://inspect`), focus the chat
input and check:
- `window.innerHeight` **shrinks** by roughly the keyboard height → correct
(branch A/B working). The chat window will scale; no page scroll.
- `window.innerHeight` **unchanged** while `window.visualViewport.height`
shrinks → the WebView is still panning; the manifest/insets change hasn't
taken effect.
## Web-side status (for completeness)
- neode-ui (the page the companion actually loads): already correct, no change
needed.
- AIUI standalone (`aiui/packages/app/index.html`): was missing the
`interactive-widget` token; added 2026-08-04 for parity. Only affects AIUI
used outside a node, not the embedded/companion path.
- iOS Safari / iOS WKWebView: `interactive-widget` is not supported there. If
an iOS wrapper appears later, the equivalent is
`KeyboardLayoutGuide`/`keyboardWillChangeFrame` driving the WKWebView frame —
same principle: resize the web content, never pan it.
docs/companion-pairing-qr.md
+128
View File
@@ -0,0 +1,128 @@
# Companion app pairing QR — integration handoff
**Status:** web-UI side SHIPPED (CompanionIntroOverlay.vue, 2026-07-16). This doc is
the contract + requirements for the companion-app side (worked on separately, on
the Mac).
## What the web UI now does
The "Remote Companion" intro modal (shown once after first dashboard login, and in
the public demo) gained a second screen:
1. **Screen 1 (existing):** APK download QR (desktop) / download button, plus a new
**"I've installed it"** button to the right of the download button.
2. **Screen 2 (new, slide transition):** a **pairing QR** the companion app scans to
auto-fill the server entry, with a **Back** button returning to screen 1. On
small screens (where you can't scan your own display) an
**"Open in companion app"** deep-link button is shown above Back, using the same
URI as the QR.
## The QR payload / deep link (the contract)
A single URI, also usable as an OS deep link:
```
archipelago://pair?v=1&url=<origin>&name=<display name>[&tok=<device token>][&pw=<password>][&fnpub=…&fip=…&fhost=…&fudp=…&ftcp=…]
```
Query parameters:
| param | required | meaning |
|-------|----------|---------|
| `v` | yes | Payload version, currently `1`. Reject/ignore unknown majors gracefully — show "please update the app". |
| `url` | yes | Full origin the app should connect to, scheme included: `https://demo.archipelago-foundation.org`, `http://archipelago.local`, `http://192.0.2.10`, etc. No trailing slash guaranteed either way — normalize. |
| `name`| no | Display name for the server entry. Real nodes send the configured server name, or `My Archipelago` when it's still the factory default. |
| `tok` | no | **Device token** minted via `auth.createDeviceToken` when the QR is rendered. The app logs in with `{"method":"auth.login","params":{"token":"…"}}` — same endpoint, same rate limiter, skips TOTP (the token was minted from an authenticated session). Long-lived until re-minted (re-showing the pair screen replaces the `companion` token) or revoked (`auth.revokeDeviceToken`). Scan → instantly connected, no typing. |
| `pw` | no | Login password. **Only present in the public demo** (shared demo password `entertoexit`). Real nodes never embed a password — the frontend doesn't have it. |
| `fnpub` | no | Node's FIPS mesh identity (bech32 npub of the daemon's seed-derived key). Presence of this param means "this node speaks FIPS — mesh with it". |
| `fip` | no | Node's `fips0` ULA (IPv6). Once the phone is meshed, the node's UI stays reachable at `http://[<fip>]` from anywhere — this is the remote-access address (replaces the old WireGuard 10.44.0.1 flow). |
| `fhost` | no | Host the phone's embedded FIPS dials (same host `url` resolved to). |
| `fudp` / `ftcp` | no | Mesh transport ports on `fhost` (currently 2121/udp and 8443/tcp). |
| `fanchors` | no | Comma-joined `npub@host:port/transport` rendezvous anchors, capped at 4. **The FIRST entry is the paired node itself** (`fnpub` at its current LAN host — the addr is a dial *hint*, the npub is the identity). The remaining entries are the node's seed anchors, and the node guarantees the Archipelago public anchor (vps2, `146.59.87.168:8444/tcp`) is present even if the operator trimmed their own list — so the phone can always rendezvous through the public mesh when the LAN endpoint is unreachable (away from home / NAT). |
Examples the web UI actually emits:
- Demo: `archipelago://pair?v=1&url=https%3A%2F%2Fdemo.archipelago-foundation.org&pw=entertoexit`
- Real node, browsed via LAN IP: `archipelago://pair?v=1&url=http%3A%2F%2F192.0.2.10`
- Real node kiosk (UI runs on localhost, so it advertises the mDNS name from
`system.get-hostname`): `archipelago://pair?v=1&url=http%3A%2F%2Farchipelago.local`
## Companion app requirements
1. **Scan entry point:** the app's action is labeled **"Scan Node's QR"**
(implemented 2026-07-17; the modal copy in CompanionIntroOverlay.vue was
updated to match).
2. **Parse the URI** (from camera scan AND from an OS deep-link intent —
register the `archipelago://` scheme so the "Open in companion app" button on
phones works).
3. On success, **create/update a saved server entry**:
- Server address = `url` exactly as given (respect the scheme — the demo is
https, LAN nodes are typically http, `.local` mDNS names must work).
- If `pw` present, prefill the password and attempt auto-login; otherwise land
on the password prompt for that server.
- If an entry with the same origin already exists, update it rather than
duplicating.
4. **Demo flow (the showcase):** scanning the demo QR should take a fresh install
to a logged-in demo session in one step — url `https://demo.archipelago-foundation.org`,
password `entertoexit`, no manual typing.
5. **Robustness:**
- Tolerate unknown extra query params (forward compat — we may add `name`,
`cert` fingerprint, etc. under `v=1`).
- Self-signed HTTPS on `.local`/LAN addresses may appear later; don't hard-fail
the parse on scheme.
- Bad/foreign QR → clear error, stay on the scan screen.
## Landed extensions (2026-07-22)
- **Device token** (`tok`) — real nodes now pair instantly; see the param table.
Minting replaces the previous `companion` token, so merely re-opening the pair
screen invalidates a previously issued token (the phone's session/remember
cookies keep working; a re-scan re-pairs).
- **`name`** — the app labels the entry with the node's server name
("My Archipelago" when unset).
- **FIPS mesh params** (`fnpub`/`fip`/`fhost`/`fudp`/`ftcp`/`fanchors`) — the
companion app embeds a leaf-only FIPS node (Android/rust/archy-fips-core)
behind a split-tunnel VpnService and dials the node + rendezvous anchors on
scan. This replaces the WireGuard install/tunnel onboarding screens entirely;
remote access = the node's fips0 ULA (`fip`), which the WebView falls back to
automatically when the LAN address stops answering.
## npub-first connectivity (2026-07-23 — REQUIRED app-side changes)
The QR used to be effectively IP-first: the app connected to `url`/`fhost` and
broke as soon as the LAN renumbered or the phone left home. FIPS peers on
**npubs**; IPs are only dial hints. The app must treat them that way:
1. **Identity = `fnpub`.** The saved server entry is keyed by the node's npub
(fall back to origin only when the QR has no FIPS params). Re-scanning the
same npub updates the entry even if every address changed.
2. **Peer with the node itself as the first anchor** (`fanchors[0]`): on LAN
this is direct p2p over FIPS (mDNS/known-endpoint dial via archy-fips-core
v0.4+, which discovers LAN peers without any IP pinning), so it keeps
working after DHCP renumbering.
3. **Peer with the public anchors too** (remaining `fanchors` entries — the
Archipelago vps2 anchor is always included by the node): away from LAN the
phone routes to the node's npub via the public mesh and reaches the UI at
`http://[<fip>]` (the fips0 ULA).
4. **Address selection order** for the WebView: LAN `url` when it answers →
ULA `fip` over the mesh otherwise. Never hard-fail because the scanned LAN
IP stopped existing.
(Node-side counterpart shipped 2026-07-23: `fips.pair-info` always includes
the vps2 public anchor, and the web UI prepends the node's self-anchor to
`fanchors`.)
App-side status: items 2/3 were already covered by `FipsPreferences.
upsertNodePeer` (npub-matched peers, self-anchor dedup) and item 4 by the
WebView's `meshFallbackUrl` retry. Item 1 shipped 2026-07-23: `ServerEntry`
carries `npub` (trailing serialization field, legacy entries still parse) and
`ServerPreferences` matches saved/active entries via `sameNode` — npub first,
address/port/scheme only as the LAN-only fallback.
## Testing checklist (app side)
- [ ] Scan demo QR from https://demo.archipelago-foundation.org → auto-connected demo session.
- [ ] Scan a real node's QR (LAN IP origin) → entry created, password prompt shown.
- [ ] Scan a kiosk node's QR (`http://<name>.local`) → mDNS resolution works on the phone.
- [ ] Tap "Open in companion app" on a phone browser → deep link opens the app with the same behavior.
- [ ] Re-scan same node → no duplicate entry.
docs/companion-qr-decoder-zxing-cpp.md
+134
View File
@@ -0,0 +1,134 @@
# Companion QR decoder — the zxing-cpp option (deferred)
*2026-08-11. Status: **NOT actioned.** Held as the next lever if the tuned
ZXing-Java pipeline proves insufficient in field testing. Companion-only —
touches `Android/` and nothing else.*
Related: [`qr-scanner-snappiness-handover.md`](qr-scanner-snappiness-handover.md)
(web + native survey, 2026-07-29), [`companion-pairing-qr.md`](companion-pairing-qr.md)
(the payload being scanned).
## Where we actually landed first
Before reaching for a new decoder, the native scanner
(`Android/app/src/main/java/com/archipelago/app/ui/components/QrScannerOverlay.kt`)
was rebuilt around one rule:
> **Every frame costs the same, and every frame sees the whole scene.**
Per frame: centre ROI at full resolution (dense invoices keep their
pixels-per-module) + the whole frame at half resolution (coverage) + one
alternating `GlobalHistogramBinarizer` pass. Bounded extras only: an inverted
ROI every 8th frame, one `TRY_HARDER` pass over the *half*-frame at most once
a second.
Two bugs were fixed on the way, both worth remembering because they are easy
to reintroduce:
1. **Escalation-on-failure is backwards.** An earlier version unlocked
progressively more expensive searches on each frame that missed, ending in
a `TRY_HARDER` pass over the full 2 MP frame (150–300 ms). The result was a
scanner that locked on instantly when the code was already in view at open,
and crawled when the user opened the camera and then moved to the code —
because hunting collapsed the rate from ~30 attempts/sec to ~4, each on a
motion-blurred frame. Failure means the user is still aiming, which is when
the scanner must be *fastest*, not most thorough.
2. **A one-shot `startFocusAndMetering` locks the lens.** It puts AF in AUTO
until auto-cancel; the 5 s default spans exactly the window where the user
is swinging the phone toward the code, and a locked lens cannot follow.
Auto-cancel is now 1 s so `CONTROL_AF_MODE_CONTINUOUS_PICTURE` does the
tracking.
Plus `CONTROL_AE_TARGET_FPS_RANGE` pinned to the highest floor the back camera
offers at ≤30 fps, which caps exposure (~33 ms) and kills the motion blur that
indoor auto-exposure otherwise bakes into every hand-held frame.
That combination tested better on device (2026-08-11). This document covers
what to do **if it is still not good enough.**
## The remaining structural limit
The decoder engine itself. ZXing's Java implementation is both the slow part
and the picky part — most relevantly, it rejects perspective-skewed codes
outright, which is much of what the sensor sees while the user is moving. No
amount of frame budgeting fixes a decoder that will not accept the frame.
## The candidate: zxing-cpp
`io.github.zxing-cpp:android` — the maintained C++ rewrite of ZXing with an
official Android/Kotlin wrapper.
**Why it clears the project's dependency bar** (`~/.claude/CLAUDE.md`):
Apache-2.0, established OSS, fully on-device, no telemetry, no Play Services,
no account or network dependency. This is the distinguishing point against
**ML Kit**, which is the other fast option and is disqualified: it is
proprietary and Play-Services-backed.
**What it buys:**
- Roughly 5–10× faster than ZXing-Java on the same frames.
- Materially better on the cases that actually fail here: perspective/rotation
(`tryRotate`, and its detector handles warp rather than rejecting it),
blur, low contrast, damaged codes.
- Built-in inversion handling (`tryInvert`), removing our alternating
inverted-ROI pass.
- Accepts an `ImageProxy` directly, so the manual Y-plane crop/copy machinery
in `QrCodeAnalyzer` can largely be deleted — including the reused
`roiBuffer`/`halfBuffer` and the `pixelStride` handling.
**Costs / risks:**
- New native dependency. APK grows ~1–2 MB — limited because the app is
already arm64-only (`abiFilters += "arm64-v8a"`), so only one ABI ships.
- Adds a native attack/maintenance surface next to the existing Rust FIPS
core. Pin the version exactly, per project rules.
- The tuned camera work above (AE FPS floor, AF auto-cancel, flat per-frame
budget) stays relevant regardless — a faster decoder does not fix a blurred
or out-of-focus frame. Do **not** rip that out as part of this change.
## Integration sketch
> ⚠️ Coordinates and API surface below are from memory and were **not**
> verified against Maven Central — the machine this was written on had no
> network. Confirm the current artifact version and wrapper API on the first
> online Gradle sync before trusting the snippet.
`Android/app/build.gradle.kts`:
```kotlin
// Replaces com.google.zxing:core for the live-camera path.
implementation("io.github.zxing-cpp:android:<pin-exact-version>")
```
`QrCodeAnalyzer` collapses to roughly:
```kotlin
private val reader = BarcodeReader().apply {
options = BarcodeReader.Options(
formats = setOf(BarcodeFormat.QR_CODE),
tryHarder = true,
tryRotate = true,
tryInvert = true,
)
}
override fun analyze(image: ImageProxy) {
try {
reader.read(image).firstOrNull()?.text?.let(onDecoded)
} finally {
image.close()
}
}
```
Keep `com.google.zxing:core` for now regardless: the still-image path
(`decodeQrFromUri` in `WalletQrScannerModal.kt`, used by "Upload image") and
`prewarmQrScanner` both use it, and neither is on the hot path.
## Decision trigger
Action this only if field testing shows the current pipeline still failing the
**move-to-the-code** case — open the scanner pointing at nothing, then bring it
to a QR at a normal hand-held distance. If that reads within about a second in
ordinary room light, the Java decoder is doing its job and this stays on the
shelf.
docs/container-lifecycle.md
+108
View File
@@ -0,0 +1,108 @@
# Container lifecycle
How Archipelago keeps apps in the state you asked for — install, start, stop,
restart, uninstall — and how it self-heals without ever resurrecting something
you deliberately stopped. Source of truth:
`core/archipelago/src/container/prod_orchestrator.rs` and
`core/archipelago/src/container/boot_reconciler.rs`.
## The model: level-triggered, not fire-and-forget
Archipelago does not start a container and hope. A long-running **reconciler**
compares *desired state* (what the manifests and your explicit choices say
should be running) against *actual state* (what podman reports) and repairs the
difference. It is **level-triggered**: it acts on the current gap every tick, not
on a one-time event, so a container that dies, a unit that vanishes, or a reboot
that clears everything are all just "the gap is non-zero, close it".
The reconciler is spawned once at boot (`BootReconciler`) after an initial
`adopt_existing()` pass, and runs every **30 seconds**. It finishes an in-flight
pull or build before honouring a shutdown signal — it is never interrupted
mid-operation.
Concurrency: each app has its own async mutex guarding all mutating operations
against the reconciler, so a manual `stop` and a reconcile tick can't race, but
reconciles across different apps still run without serialising against each
other.
## Desired state has three inputs
For each app the reconciler asks: *should this be running right now?* The answer
comes from three durable signals, checked in this order:
1. **Explicitly user-stopped** (`user-stopped.json`). If you stopped an app, its
id is recorded and the reconciler leaves it down — it is **not** a gap to
repair. Cleared when you start it again. This is what makes a stop *stick*
across restarts and reboots.
2. **Explicitly uninstalled** (`user-uninstalled.json`). Same idea for uninstall:
a baseline app you removed stays removed, so self-heal can't reinstall it.
3. **Otherwise, the manifest set** — every catalog/disk app that isn't stopped or
uninstalled should be running.
Dependencies are pulled in: an app that is up requires its declared
dependencies, so they are kept up too — but a dependency you explicitly stopped
still stays stopped.
## The operations
All go through the orchestrator, all take the per-app lock, all are idempotent:
| Operation | What it does |
|-------------|--------------|
| **adopt** | At boot, take ownership of a pre-existing container **by name** rather than recreating it — preserves data, ports and identity across a daemon restart. |
| **install** | Materialise secrets → ensure image (build from a local Dockerfile or use a pre-pulled image) → create and start the container (via Quadlet where enabled). |
| **start / stop** | Bring the container up/down and record the desired-state change. A stop writes the app to `user-stopped.json`. |
| **restart** | Stop then start, preserving the container's data and identity. |
| **remove** | Stop and remove the container, **preserving `/var/lib/archipelago/<app>`, secrets, credentials and ports** — a reinstall or upgrade lands on the same data. |
| **upgrade** | Recreate at a new image while preserving data (see the version rules below). |
| **health** | Report the container's health from its declared `health_check`. |
## Self-heal vs. respecting your choice
The one rule that ties it together: **self-heal must never override a deliberate
stop or uninstall.**
- A container that disappeared while its siblings run — a wedged teardown, a
reboot that cleared it — is a hole to repair, and the reconciler rebuilds it
from the durable "was running" snapshot.
- A container that is down because you stopped or uninstalled it is a *choice*,
and the reconciler leaves it alone.
A small set of **baseline apps** are expected to exist from first boot and
self-heal when their container is missing — but the `user_stopped` /
`user_uninstalled` gates are checked first, so even a baseline app you turned off
stays off. Getting this wrong in either direction is a real bug: resurrecting a
stopped app ignores the operator, and failing to rebuild a crashed one is the
fire-and-forget failure the whole design exists to remove.
## Migrations never destroy data
Any recreate path — upgrade, reinstall, repair — preserves the app's data
directory, its generated secrets, its credentials, its ports, and the container
name used for adoption. An update that would roll a version *backwards* is
refused (see the version guard in `container::image_versions`): the update button
never offers a lower version than what is running, so a stale record cannot turn
into a downgrade. Version pins are honoured — a pinned app is not "updated" out
from under the operator by the catalog.
## Inspecting lifecycle state
```bash
# what podman actually has — run as the archipelago service user (rootless)
podman ps -a --format '{{.Names}}\t{{.Status}}'
# the durable desired-state signals
cat /var/lib/archipelago/user-stopped.json
cat /var/lib/archipelago/user-uninstalled.json
# the reconciler's decisions. archipelago.service is a SYSTEM unit that runs
# as User=archipelago (WantedBy=multi-user.target), so this is not --user —
# unlike the companion Quadlet units, which are per-user.
sudo journalctl -u archipelago | grep -iE 'reconcile|adopt|install|user.stopped'
```
## Related
- [Manifest → Quadlet unit](quadlet-compilation.md) — how the unit the reconciler manages is generated
- [App secrets](secrets.md) — the `ensure_generated_secrets` tick that runs before start
- [App Manifest Specification](app-manifest-spec.md) — `health_check`, `dependencies`, `restart` fields
docs/demo-build-info.md
+109
View File
@@ -0,0 +1,109 @@
# Archipelago Public Demo — build info & status
**Status:** implemented & deployable (2026-07-14)
**Branch:** `main` — the demo machinery was merged from the old `demo-build`
branch and now lives on main, pushed to
`gitea-vps2` = `https://source.archipelago-foundation.org/lfg2025/archy.git`.
A public, click-to-play demo of the Archipelago UI, 100% mock-data driven,
multi-visitor, deployed via Portainer. See also `docs/archive/demo-deployment-design.md`
(original design) and `demo-deploy/` (thin prebuilt-image stack).
---
## Deploy (Portainer)
Build-from-repo (works today, no registry needed):
| Field | Value |
|-------|-------|
| Repository URL | `https://source.archipelago-foundation.org/lfg2025/archy.git` |
| Reference | `refs/heads/main` |
| Compose path | `docker-compose.demo.yml` |
| Auth | user `lfg2025`, password = Gitea token |
| UI port | **2100** · Login password: **`entertoexit`** |
Redeploy after each push. `docker-compose.demo.yml` builds two images
(`neode-ui/Dockerfile.backend` = mock server, `neode-ui/Dockerfile.web` = nginx+UI).
The thin `demo-deploy/docker-compose.yml` pulls prebuilt `:demo` images instead
(needs the CI image pipeline / registry wired — `.github/workflows/demo-images.yml`).
### Flags / env
- Backend: `DEMO=1` (compose sets it) → multi-session sandbox, no real runtime.
- Web build: `VITE_DEMO=1` (Dockerfile.web ARG, default 1) → inlined demo UI behaviour.
- Optional: `ANTHROPIC_API_KEY` (NOT needed — AIUI chat is canned in demo),
`DEMO_SESSION_TTL_MS` (45m), `DEMO_MAX_SESSIONS` (500), `DEMO_FILE_QUOTA_BYTES` (50MB).
---
## Architecture
Everything is gated behind `DEMO` (off = classic single-user dev mock, unchanged).
- **`neode-ui/mock-backend.js`** — the entire fake backend (Node/Express, ~95+ RPCs).
- **Per-session isolation:** `AsyncLocalStorage` + Proxy. Globals (`mockData`,
`walletState`, `userState`, `mockState`, `bitcoinRelayMockState`) are Proxies
that resolve to the current request's store, keyed by a `demo_sid` cookie.
Deep-cloned from `SEED_*` on first hit; idle-reaped; per-session WS fan-out.
- **Files:** per-session in-memory store + curated disk files (see below).
- Forces simulation mode in DEMO (`docker=null`).
- **`neode-ui/src/composables/useDemoIntro.ts`** — the frontend demo switch
(`IS_DEMO`), per-day intro gate, `DEMO_PASSWORD`, app demoability + launch URLs.
- **`neode-ui/docker/nginx-demo.conf`** — routes `/rpc`, `/ws`, `/app/*`,
`/electrs-status`, `/proxy/`, `/lnd-connect-info`, the IndeeHub/Mempool
reverse-proxies, and the SPA.
- **`docker/{bitcoin-ui,electrs-ui,lnd-ui,fedimint-ui}/`** — the REAL registry app
UIs, served statically under `/app/<id>/` with mocked data endpoints.
- **`demo/aiui/`** — prebuilt AIUI dist (chat is canned; `?mockArchy&seed`).
- **`demo/files/`** — curated cloud files drop-in (see below).
## Demo features (all implemented)
Per-session sandbox · per-session file upload (Range streaming) · testnet/signet
flavor · per-day intro replay · `entertoexit` login (prefilled + hint) · version
`<real>-demo` · onboarding wizard skipped (intro kept) · "No demo" install gating ·
real app UIs (Bitcoin Core vs Knots by subversion, ElectrumX, LND, Fedimint;
Mempool/IndeeHub iframed) · 12 federation nodes / 5 peers · FIPS active · interactive
buy flow (testnet addresses, bolt11, 2s QR) · real testnet tx links (mempool.space) ·
networking profits 5,231,978 sats + labelled wallet txs · VPN · Nostr relays ·
node-visibility toggle · dummy Cashu mints + Fedimint federations · AIUI canned
reply + `?mockArchy` mock data + `?seed` pre-loaded "Content Showcase" chat.
---
## Curated cloud files (`demo/files/`)
Drop real files into `demo/files/<Folder>/<file>` and commit — they become the
cloud content for every visitor (read-only; git access = the "private login").
Loader **merges per top-level folder**: adding `Music/` swaps only Music and keeps
the sample Documents/Photos/Videos. Empty → built-in seeds. Text inlined; binaries
streamed from disk with HTTP Range (seek). Backend reads `/demo/files` —
**Dockerfile.backend COPYs it; `.dockerignore` must allow it.**
---
## Gotchas (READ before editing)
- **Sibling dirs need both the Dockerfile COPY and a `.dockerignore` allow.**
`docker/bitcoin-ui`, `docker/electrs-ui`, `docker/lnd-ui`, `docker/fedimint-ui`,
`demo/files` are outside `neode-ui/`; they're copied into the backend image and
un-ignored in `.dockerignore` (`* ` + `!docker/` + `docker/*` + `!docker/<ui>/`).
Forgetting either → Portainer build "not found" or runtime 500/404.
- **Real app UIs assume root-serving** — served via `express.static('/app/<id>')`
+ `/app/<id>/assets/*` → `/assets/*` redirect + per-path data endpoints
(`bitcoin-status`, `rpc/v1`, `bitcoin-rpc/`, `/proxy/lnd/*`, `/electrs-status`).
- **Uploaded-via-UI files are ephemeral** (per-session, lost on redeploy/reap).
Only `demo/files/` persists.
- **Mempool iframe is best-effort** (third-party CSP/websockets). **IndeeHub** is
reverse-proxied with header-strip + `sub_filter` asset rewrite; if still black,
it's indee's own `X-Frame-Options` (fix on that server).
- **AIUI `?seed` bootstrap hardcodes the current AIUI bundle hash**
(`/aiui/assets/seedPrompts-CLWaUv28.js`) — re-paste if AIUI is rebuilt. Tiny
first-load IndexedDB race (one refresh shows the chat).
- **Running mock-backend.js locally in the sandbox is flaky:** start backgrounded,
`sleep 5+`, then curl; NEVER `pkill -f mock-backend` (it matches & kills the
shell) — use `pkill -x node`.
- **Delete-405** seen pre-redeploy was nginx/stale; backend DELETE returns 200.
---
## Commit trail (demo-build, newest last)
`2715f2d8` sandbox → … → `7efebb4a` media merge + AIUI seed. ~14 commits, all
`feat(demo)/fix(demo)`.
docs/developer-guide.md
+311
View File
@@ -0,0 +1,311 @@
# Archipelago Developer Guide
## Project Structure
```
archy/
├── core/ # Rust backend
│ └── archipelago/
│ ├── src/
│ │ ├── main.rs # Entry point, module declarations
│ │ ├── api/rpc/ # RPC endpoint handlers
│ │ │ ├── dispatcher.rs # Route dispatcher (~380 method arms)
│ │ │ ├── auth.rs # Login, session, TOTP
│ │ │ ├── container.rs # Container lifecycle
│ │ │ ├── package/ # Package install/lifecycle/stacks
│ │ │ ├── interfaces.rs # Network interfaces, WiFi, DNS
│ │ │ ├── federation/ # Federation management
│ │ │ ├── marketplace.rs # Community marketplace
│ │ │ └── ... # Other endpoint groups (mesh/, identity/, lnd/, tor/, system/)
│ │ ├── auth.rs # Password hashing, sessions
│ │ ├── config.rs # Configuration loading
│ │ ├── server.rs # HTTP/WS server (axum)
│ │ ├── container/ # Podman integration
│ │ ├── network/ # Network management
│ │ │ ├── dns.rs # DNS configuration
│ │ │ ├── router.rs # UPnP, diagnostics
│ │ │ └── dwn_*.rs # DWN protocol
│ │ ├── federation/ # Federation protocol
│ │ ├── marketplace.rs # Marketplace discovery
│ │ ├── identity.rs # DID key management
│ │ ├── vpn.rs # VPN (Tailscale/WireGuard)
│ │ ├── mesh/ # Tri-protocol mesh (Meshtastic/MeshCore/Reticulum)
│ │ └── ...
│ ├── Cargo.toml
│ └── tests/ # Integration tests
├── neode-ui/ # Vue 3 frontend
│ ├── src/
│ │ ├── api/ # RPC client, WebSocket, container client
│ │ │ └── rpc-client.ts # Central RPC client (all backend calls)
│ │ ├── views/ # Page components
│ │ │ ├── Home.vue # Dashboard with system stats
│ │ │ ├── Marketplace.vue # App store (curated + community)
│ │ │ ├── Server.vue # Network, VPN, DNS management
│ │ │ ├── Federation.vue # Federation dashboard
│ │ │ ├── Settings.vue # User settings
│ │ │ ├── Web5.vue # DID, DWN, Nostr
│ │ │ └── ...
│ │ ├── stores/ # Pinia state management
│ │ ├── components/ # Reusable UI components
│ │ ├── composables/ # Vue composables
│ │ ├── router/ # Vue Router with guards
│ │ ├── types/ # TypeScript type definitions
│ │ └── style.css # Global styles + Tailwind utilities
│ ├── vite.config.ts
│ └── package.json
├── scripts/ # Deployment and utility scripts
│ ├── first-boot-containers.sh # ISO first-boot setup
│ └── run-tests.sh # CI test runner
├── image-recipe/ # ISO build configuration
│ ├── build-debian-iso.sh
│ └── configs/ # Nginx, systemd configs
├── docs/ # Documentation
│ ├── architecture.md
│ ├── app-manifest-spec.md
│ ├── marketplace-protocol.md
│ └── multi-node-architecture.md
├── apps/ # App manifests (YAML)
├── CLAUDE.md # Contributor guide (invariants, build/verify)
└── docs/ROADMAP.md # Project roadmap
```
## Development Setup
### Prerequisites
- Node.js 20+ and npm for frontend development.
- Rust stable for backend development.
- Linux with Podman, systemd, and Nginx for host integration work.
- Debian 13 is the target runtime for release validation.
### Local Frontend Development
```bash
cd neode-ui
npm install
npm start # Vite dev server on :8100, mock backend on :5959
```
The dev server at `http://localhost:8100` uses a mock backend.
### Deploying Changes
Release and host-integration builds should run on Linux. Build the backend and
frontend on the target, or cross-build and copy the artifacts across:
```bash
cd core && cargo build --release
cd neode-ui && npm ci && npm run build
```
A deploy then:
1. Copies the build output to the node
2. Builds Rust backend on the server (`cargo build --release`)
3. Builds Vue frontend (`npm run build`)
4. Copies artifacts to production paths
5. Restarts the `archipelago` systemd service
6. Runs a health check
### Running Tests
```bash
# Frontend tests
cd neode-ui && npm test
# Backend tests
cd core && cargo test --all-features
# Both
./scripts/run-tests.sh
```
`scripts/run-tests.sh` can run backend tests on a Linux target when
`ARCHIPELAGO_SSH_HOST` and `ARCHIPELAGO_SSH_KEY` are set.
## Adding a New RPC Endpoint
### 1. Create the Handler
Add a handler method in the appropriate file under `core/archipelago/src/api/rpc/`. If no existing file fits, create a new one.
```rust
// core/archipelago/src/api/rpc/mymodule.rs
use super::RpcHandler;
use anyhow::Result;
impl RpcHandler {
/// mymodule.action — description of what it does.
pub(super) async fn handle_mymodule_action(
&self,
params: Option<serde_json::Value>,
) -> Result<serde_json::Value> {
let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
let name = params
.get("name")
.and_then(|v| v.as_str())
.ok_or_else(|| anyhow::anyhow!("Missing required parameter: name"))?;
// Your logic here
let result = do_something(name).await?;
Ok(serde_json::json!({ "ok": true, "result": result }))
}
}
```
**Key patterns:**
- Handlers are `pub(super)` — visible only to the RPC router
- Accept `Option<serde_json::Value>` for params (omit for parameterless endpoints)
- Return `Result<serde_json::Value>`
- Use `self.config.data_dir` for data persistence
- Use `anyhow::bail!()` for error responses
### 2. Register the Route
Add the module declaration in `core/archipelago/src/api/rpc/mod.rs`, then add
the route arm to the `dispatch()` match in
`core/archipelago/src/api/rpc/dispatcher.rs`:
```rust
// api/rpc/mod.rs, at the top:
mod mymodule;
// api/rpc/dispatcher.rs, in the dispatch() match statement:
"mymodule.action" => self.handle_mymodule_action(params).await,
```
### 3. Add Module (if new)
If your logic warrants a separate module:
```rust
// core/archipelago/src/main.rs
mod mymodule; // Add to module declarations
```
### 4. Frontend Client
Add a convenience method to `neode-ui/src/api/rpc-client.ts`:
```typescript
async myAction(params: { name: string }): Promise<{ ok: boolean; result: string }> {
return this.call({
method: 'mymodule.action',
params,
})
}
```
### 5. Deploy and Test
```bash
curl -X POST http://<node-host>/rpc/v1 \
-H "Content-Type: application/json" \
-b "archipelago_session=YOUR_SESSION" \
-d '{"method":"mymodule.action","params":{"name":"test"}}'
```
## Adding a New Vue Page
### 1. Create the Component
```vue
<!-- neode-ui/src/views/MyPage.vue -->
<template>
<div>
<h1 class="text-4xl font-bold text-white mb-2">My Page</h1>
<div class="glass-card p-6">
<!-- Content here -->
</div>
</div>
</template>
<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { rpcClient } from '@/api/rpc-client'
// State and logic
</script>
```
### 2. Add the Route
In `neode-ui/src/router/index.ts`, add inside the dashboard children:
```typescript
{
path: 'my-page',
name: 'my-page',
component: () => import('@/views/MyPage.vue'),
},
```
### 3. Standards
- Always use `<script setup lang="ts">` — never Options API
- Use `glass-card` for containers, `bg-white/5 rounded-lg` for sub-rows
- Create global CSS classes in `src/style.css` instead of inline Tailwind
- Use `rpcClient` from `@/api/rpc-client.ts` for all backend calls
- Handle loading states and errors for all async operations
## Writing Tests
### Frontend (Vitest)
```typescript
// neode-ui/src/api/__tests__/my-test.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest'
describe('MyFeature', () => {
beforeEach(() => {
vi.restoreAllMocks()
})
it('should do something', async () => {
vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
ok: true,
json: () => Promise.resolve({ result: 'ok' }),
}))
// Test your logic
expect(true).toBe(true)
})
})
```
### Backend (Rust)
```rust
#[cfg(test)]
mod tests {
use super::*;
use tempfile::tempdir;
#[tokio::test]
async fn test_my_function() {
let dir = tempdir().unwrap();
let result = my_function(dir.path()).await.unwrap();
assert_eq!(result, expected);
}
}
```
## Code Quality Checklist
- [ ] TypeScript strict mode: no `any`, use `unknown` or proper types
- [ ] No `unwrap()` or `expect()` in production Rust code — use `?`
- [ ] No `console.log` — wrap in `if (import.meta.env.DEV)`
- [ ] No empty catch blocks — log or handle errors
- [ ] Functions under 50 lines
- [ ] `cargo clippy` and `cargo fmt` pass
- [ ] `npx vue-tsc --noEmit` passes
- [ ] Security: validate all inputs, no command injection
- [ ] Container security: readonly_root, no_new_privileges, non-root user
## Contributing
1. Create a feature branch: `git checkout -b feature/my-feature`
2. Make changes following the standards above
3. Test locally: `cd neode-ui && npm test`
4. Verify on an Archipelago node
5. Commit with conventional format: `feat: add my feature`
docs/dht-distribution-design.md
+192
View File
@@ -0,0 +1,192 @@
# DHT / Peer-Distributed Content Design
**Status:** partially implemented — **not** "no code yet" as this line previously
read. `core/archipelago/src/swarm/` exists (`mod.rs`, `iroh_provider.rs`,
`paid.rs`, `paid_alpn.rs`, `payment.rs`) along with `content_hash.rs`, behind the
**default-off** `iroh-swarm` cargo feature (`Cargo.toml:21` — the iroh/iroh-blobs
deps are optional and only pulled in by that feature). `config.swarm_enabled`
gates it at runtime and also defaults off, so a stock build ships this inert.
Treat the phases below as design; check the feature flag before assuming a phase
is live. · **Date:** 2026-06-16 · **Author:** archipelago + Claude
## 1. Purpose
Make Archipelago's large-file movement **peer-distributed**: a node should be able to
fetch content (OTA updates, app/OCI images, IndeeHub films) from *any other node that
already has it*, falling back to the central origin only when no peer can serve it.
This document covers three use-cases that are **the same problem** —
"fetch content-addressed bytes from whatever node already has them, verify, fall back to
origin":
1. **OTA releases** — node binaries + frontend tarballs.
2. **App installs** — container/OCI images.
3. **IndeeHub streaming** — films created in "backstage" on one node, streamable from any
node that has them stored or cached.
### Guiding principle (decided 2026-06-16)
> **Swarm-assist, origin always wins.** The peer swarm is an *optimization*. The central
> origin (OVH HTTP release assets / MinIO) remains the **guaranteed fallback** and the
> source of truth for reliability. We never bet correctness or availability on the P2P
> layer. This is what keeps the system bulletproof while the P2P stack matures.
## 2. Current state (verified 2026-06-16)
### OTA (`core/archipelago/src/update.rs`)
- Manifest at `DEFAULT_UPDATE_MANIFEST_URL` (`update.rs:67`) = vps2 OVH
(`source.archipelago-foundation.org/lfg2025/archy/raw/branch/main/releases/manifest.json`).
- `check_for_updates()` (`:565`) walks an operator mirror list (`default_mirrors()` `:105`,
`load_mirrors()` `:123`), origin-rewrites component URLs to the chosen mirror
(`rewrite_manifest_origins()` `:227`).
- `download_component_resumable()` (`:821`) — resumable HTTP Range download, 6 retries,
exponential backoff.
- **Integrity: SHA-256 only** (`:984`), compared against `ComponentUpdate.sha256`.
- **No authenticity:** manifests are *unsigned*. A compromised mirror can serve a malicious
but hash-consistent binary. Post-apply health probe + auto-rollback exist
(`verify_pending_update()` `:389`, `rollback_update()` `:1423`) but that is not a
substitute for signature verification.
- Manifest schema: `{version, release_date, changelog[], components[{name, current_version,
new_version, download_url, sha256, size_bytes}]}`.
### App installs (`core/archipelago/src/api/rpc/package/install.rs`)
- `handle_package_install()` (`:195`) → `do_pull_image()` (`:1062`) tries each registry from
`container/registry.rs` in priority order (OVH primary), `rewrite_image()` rewrites the
origin, `podman pull`. Same centralized-mirror shape as OTA.
### Transport & identity (already P2P-capable)
- `transport/mod.rs` — `NodeTransport` trait (`:74`), `TransportRouter` (`:336`), priority
stack Mesh→LAN→FIPS→Tor. `PeerRegistry` (`:199`) tracks per-peer addresses
(mesh id, LAN ip:port, `fips_npub`, onion).
- Seed-derived identity (`seed.rs`): node Ed25519 (`archipelago/node/ed25519/v1`), node
Nostr secp256k1 (`archipelago/nostr-node/secp256k1/v1`), FIPS secp256k1
(`archipelago/fips/secp256k1/v1`). DID + npub per node.
- **Already content-addressed:** `blobs.rs` stores `blobs/<cid>` keyed by **SHA-256** hex,
with HMAC-SHA256 capability tokens (`BlobMeta`, 64 MiB cap). `transport/chunking.rs` does
Reed-Solomon chunking for LoRa.
### Trust scaffolding — **NOT built yet**
- No `core/src/trust/`, no `ROOT_PUBKEY`, no `derive_release_root_*`, no
`archipelago/release/root/*` HKDF strings, no JCS/canonical JSON, no signing ceremony
scripts, no `manifest-v2.json`. The "Phase 0 signed manifest" design exists only as notes.
### IndeeHub (the streaming target)
- Original platform (not a fork). Working source: `~/Projects/Indeedhub Prototype/`
(Vue 3 + NestJS). Submodule `source.archipelago-foundation.org/lfg2025/indeehub.git` (repointed off the retired host —
needs a live remote). In `archy`: image-only, `apps/indeedhub/manifest.yml` pulls
`source.archipelago-foundation.org/lfg2025/indeedhub:1.0.0` (+ `-api`, `-ffmpeg`, postgres, redis,
minio, nostr-rs-relay).
- Streaming today: FFmpeg → **HLS (.m3u8 + AES-128 .ts segments)** in **MinIO**
(`indeedhub-private`/`-public`), metadata in Postgres, transcode queue in Redis,
auth via Nostr (NIP-98). Glue: `install.rs:68` `patch_indeedhub_nostr_provider()`
injects the NIP-07 provider into the nginx-wrapped frontend.
- **No "backstage" code yet** — it's the creator/upload side we're introducing.
## 3. Protocol evaluation (verified maintenance status, 2026-06-16)
| Option | Verdict | Why |
| --- | --- | --- |
| **Web5 / TBD / DWN** | ❌ Reject | Block **wound TBD down**, handed components to DIF (`TBD54566975`→`decentralized-identity`). `web5-js` latest release **0.12.0, Oct 2024** (~20 mo stale). DWN spec still **Draft**. DWNs are DID-scoped *record stores*, not a blob-streaming swarm. Fails the "well-maintained + bulletproof" bar. |
| **iroh / iroh-blobs** | ✅ Swarm engine | **v1.0.0 shipped 2026-06-15.** Rust (matches core), **BLAKE3 verified streaming** over **QUIC + hole-punching + relays**, content-addressed, KB→TB, **native byte-range** support (ideal for HLS). n0 team, production relays. |
| **Nostr Blossom** | ✅ Index/catalog layer | SHA-256-addressed blobs over HTTP, modular BUD specs (BUD-01/02/04/05/06/08), actively developed, **already aligned** (Nostr identity everywhere; `blobs.rs` already SHA-256). Server-centric (not a peer swarm) → use as discovery + IndeeHub catalog + HTTP fallback, not the distribution engine. |
| **libp2p-kad (hand-rolled DHT)** | ⚠️ De-prioritize | Was the old "Phase 4 build a Kademlia" plan. iroh 1.0 supersedes the need to hand-roll discovery + swarm. Revisit only if iroh proves unworkable. |
**Note vs. prior plan:** the saved DHT design said "no iroh as a Phase 0–5 dep (revisit
post-Phase 3)." iroh hitting 1.0 removes the main reason for that deferral — **this design
reverses that non-choice** and adopts iroh as the swarm layer, collapsing the from-scratch
Kademlia work.
## 4. Recommended architecture — three layers, one engine
Build **one** peer-distribution layer; use it for all three use-cases.
```
┌─────────────────────────────────────────────┐
Authenticity │ Signed Nostr events (per-node npub) + │ "who published this,
& Discovery │ seed-derived RELEASE ROOT key for OTA + │ who has it"
│ Blossom BUD catalog for IndeeHub │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
Integrity & │ BLAKE3 content addressing (iroh-native, │ "name bytes by hash,
Addressing │ range-verifiable). SHA-256 kept in manifest │ verify on arrival"
│ during migration window. │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
Transport & │ iroh-blobs swarm (peers that already have │ "move the bytes"
Swarm │ it) ─── fallback ───▶ OVH HTTP / MinIO │
│ origin (ALWAYS wins) │
└─────────────────────────────────────────────┘
```
- **Integrity/addressing — BLAKE3.** iroh-native, supports verified *range* streaming
(essential for HLS + resumable). Keep SHA-256 in the manifest for back-compat through the
migration window; add a `blake3` field alongside.
- **Discovery/authenticity — signed Nostr events + release root key.**
- OTA: the **Phase 0 seed-derived release root key** signs the manifest (BLAKE3 root hash
+ version). Integrity ≠ authenticity — content addressing proves *bytes are intact*, the
signature proves *we authorized them*. Both are required.
- "Who has blob X" advertised via signed Nostr events `{content-hash, provider-npub, ts}`,
so nodes find seeds without a central tracker.
- IndeeHub: Blossom BUDs for the film catalog + provider/mirror lists.
- **Transport/swarm — iroh-blobs, origin fallback.** Node asks the swarm for a hash; peers
that have it serve range-verified BLAKE3 streams; if the swarm yields nothing, fall back to
the existing resumable HTTP path (`update.rs:821`) against OVH/MinIO. **A node that
finishes a download automatically becomes a seed.**
### Bulletproof posture
The swarm sits *above* a proven HTTP path, never in place of it. Worst case (every peer
offline, iroh bug, NAT failure) the node downloads exactly as it does today. iroh 1.0 is new;
this containment is deliberate.
## 5. Use-case flows
### OTA / app installs
1. Node reads the **signed** manifest (via signed Nostr event or HTTP), gets BLAKE3 root hash
+ release-root signature; verify signature → reject on failure.
2. Query swarm (signed provider events) for peers holding that hash.
3. Download range-verified BLAKE3 stream from peers; verify full BLAKE3 (+ SHA-256 during
migration).
4. No peers / failure → resumable HTTP from OVH (current path).
5. Apply + health-probe + auto-rollback (unchanged). Updated node **becomes a seed**.
6. OCI images: content-address image layers the same way; OVH registry stays the origin.
### IndeeHub streaming ("backstage → any node")
1. Creator publishes a film in **backstage** → FFmpeg → HLS; **each .ts segment is a
content-addressed (BLAKE3) blob**, immutable and small → ideal swarm objects.
2. Publish a **signed Nostr event** advertising title + segment hashes (Blossom catalog).
3. Any node running IndeeHub resolves the content address and **streams from the nearest
node(s) that have it stored/cached** via iroh range streaming; MinIO/OVH is origin.
4. AES-128 key delivery + NIP-98 auth unchanged (keys gate decryption; swarm only moves
encrypted segments — so untrusted seeds can cache without seeing plaintext).
## 6. Phasing (folds into the existing Phase 0–6 plan)
0. **Signed manifests (required first, unbuilt).** `derive_release_root_ed25519` /
`derive_release_root_nostr` in `seed.rs` (HKDF `archipelago/release/root/ed25519/v1`,
`.../secp256k1/v1`); `core/src/trust/` (anchor/bundle/manifest/timestamp/nostr); JCS
canonical JSON; ceremony scripts; `manifest-v2.json` with signature. Gives *authenticity*,
which content-addressing does not.
1. **BLAKE3 alongside SHA-256** in the manifest + `blobs.rs`.
2. **iroh-blobs PoC** behind a feature flag: serve OTA blobs from the swarm with HTTP
fallback; measure on a scratch/test node, then the fleet.
3. **Signed Nostr advertisement events** for releases (publisher identity + provider lists).
4. **IndeeHub on the same blob layer** (Blossom catalog + iroh swarm; MinIO origin).
This collapses the old "Phase 4: build S/Kademlia from scratch" into "adopt iroh," a large
de-risking.
## 7. Open decisions
- **BLAKE3 migration scope:** dual-hash window length; whether to re-hash historical
releases or only BLAKE3 going forward.
- **iroh ↔ existing transports:** iroh brings its own QUIC + hole-punching + relays; decide
how it coexists with FIPS/Tor (run iroh standalone first; integrate with `TransportRouter`
later if useful).
- **Seed retention policy:** how long nodes keep blobs to seed others (disk pressure on small
nodes); pinning rules for IndeeHub films vs. transient OTA blobs.
- **Privacy:** iroh dial-by-key vs. Tor's anonymity; default transport per content type.
## References
- iroh: https://github.com/n0-computer/iroh · iroh-blobs: https://github.com/n0-computer/iroh-blobs · docs: https://docs.iroh.computer/protocols/blobs
- Blossom: https://github.com/hzrd149/blossom · NIP-B7: https://nips.nostr.com/B7 · nostr-blossom (Rust): https://docs.rs/nostr-blossom
- Web5/DWN (rejected): https://github.com/decentralized-identity/web5-js · https://identity.foundation/decentralized-web-node/spec/ · https://block.xyz/inside/block-contributes-digital-identity-components-to-the-decentralized-identity-foundation
docs/dual-ecash-design.md
+135
View File
@@ -0,0 +1,135 @@
# Dual-ecash: Cashu + Fedimint, seamlessly
Status: **in progress** (2026-06-17). FE scaffolding + Fedimint HTTP bridge landed and
compile-checked; live federation round-trip and networking-sats routing are not yet validated.
## Why
Today the node's wallet (`core/archipelago/src/wallet/ecash.rs`, `mint_client.rs`, `cashu.rs`)
speaks **only** the Cashu NUT HTTP protocol (BDHKE, `cashuA…` tokens). There is **no** Fedimint
*client* — `apps/fedimint` is only the guardian server, and the "local Fedimint" default mint at
`127.0.0.1:8175` is just the guardian UI nginx, which does not expose the Cashu NUT API. So:
- The node can hold/spend generic Cashu tokens, but cannot hold Fedimint ecash or join federations.
- "Networking sats" (streaming/seeding revenue) is hardcoded to the Cashu wallet.
Goal: support **both** ecash protocols seamlessly — hold balances in either, join arbitrary
federations, and let networking-sats be paid/received over whichever protocol the peer accepts.
## Architecture decision
**Containerized `fedimint-clientd` + thin HTTP bridge** (chosen over linking the native
`fedimint-client` Rust SDK into the binary, and over a Lightning-only bridge).
```
archipelago binary
├─ CashuMintClient ──HTTP (NUT /v1/*)──▶ cashu mint
└─ FedimintClient ──REST (/v2/*)─────▶ fedimint-clientd container ──▶ federation guardians
```
Rationale: keeps the heavy, fast-moving Fedimint SDK **out** of the main binary (no compile-time
coupling, no rebuild bloat, OTA-friendly), and fits the existing app/container architecture
(`apps/fedimint`, `apps/fedimint-gateway`). The Rust side is just a `reqwest` client, mirroring
`MintClient`.
### fedimint-clientd REST surface (v0.3.x)
- Auth: `Authorization: Bearer <password>`. Default port 8080 (we map it to host **8178** because
8080 is LND REST). Base path `/v2/...`.
- `GET /v2/admin/info` — per-federation balances (`totalAmountMsat`, denominations, meta).
- `POST /v2/admin/join` — `{ "inviteCode": "fed1…", "useManualSecret": false }` → joins / returns `federationId`.
- `POST /v2/mint/spend` — `{ federationId, amountMsat }` → serialized notes (ecash to send).
- `POST /v2/mint/reissue` — `{ federationId, notes }` → redeem received notes; returns reissued amount.
- `POST /v2/ln/invoice` / `POST /v2/ln/pay` — Lightning in/out (used for cross-protocol swaps).
- `GET /health`.
Multi-federation: requests carry a `federationId`; clientd's `multimint` manages many clients.
**Exact JSON field names must be pinned to the clientd image tag we vendor** — code defensively.
## Components
### 1. Container app — `apps/fedimint-clientd/manifest.yml`
Sidecar running `fedimint-clientd`, mirroring `apps/fedimint-gateway`. Host port 8178 → container
8080. Password from node secret `fedimint-clientd-password`. State volume at
`/var/lib/archipelago/fedimint-clientd`. Added to `RESERVED_PORTS` (port_allocator.rs) and
`fallback_package_port()` (server.rs).
### 2. Rust bridge — `core/archipelago/src/wallet/fedimint_client.rs`
Thin `reqwest` client: `info()`, `join()`, `spend()`, `reissue()`, `ln_invoice()`, `ln_pay()`.
`from_node(data_dir)` resolves base URL + password (env `FEDIMINT_CLIENTD_URL` /
`FEDIMINT_CLIENTD_PASSWORD`, else defaults + secret file). Tor-proxy support via `with_client`,
mirroring `MintClient`.
### 3. RPCs — `core/archipelago/src/api/rpc/fedimint.rs`
- `wallet.fedimint-list` → joined federations + balances (`{federation_id, name, balance_sats}[]`).
- `wallet.fedimint-join` `{invite_code}` → joins via clientd, persists to
`wallet/fedimint_federations.json`, returns `{federation_id}`.
- `wallet.fedimint-leave` `{federation_id}` → untracks locally.
- `wallet.fedimint-balance` → total sats across federations (from clientd `info`).
Local registry `wallet/fedimint_federations.json` = `{ federations: [{federation_id, name}] }` so
the list survives clientd being temporarily down; balances are live from clientd.
### 4. Frontend — `WalletSettingsModal.vue`
Tabbed: **Cashu Mints** (live: `streaming.list-mints` / `streaming.configure-mints`) and
**Fedimint Federations** (`wallet.fedimint-list` / `-join` / `-leave`). Gear icon on
`HomeWalletCard`. `fedimintBackendReady` flips to `true` once the RPCs ship; join degrades
gracefully with a clear error if the clientd app isn't installed.
### 4b. Default federation (zero-touch)
clientd auto-joins a default federation at boot via `FEDIMINT_CLIENTD_INVITE_CODE` (manifest), and
the Rust bridge `ensure_default_federation()` idempotently joins + tracks it (called from
`wallet.fedimint-list`) so already-running nodes pick it up too. Constant
`DEFAULT_FEDERATION_INVITE` in `fedimint_client.rs` is the single source on the Rust side; keep it
in sync with the manifest env. clientd is a **client, not the guardian** — it needs no local
`fedimintd`, so it bundles standalone.
### 4c. Bundling on every node
- **Bundled ISO:** add image to `scripts/image-versions.sh`, the ISO bundle `.tar` list, and a
core-create block in `scripts/first-boot-containers.sh`; mark `tier: "core"` in
`app-catalog/catalog.json`.
- **Unbundled ISO:** `first-boot-containers.sh` exits after FileBrowser only — add clientd to that
early-exit block so unbundled nodes also get it out of the box.
- **CAVEAT:** confirm the *current* ISO assembler before editing the bundle list — the one found is
under `image-recipe/_archived/` (likely stale); `first-boot-containers.sh`/`image-versions.sh`
are current.
- Image: build from source (no official image; `flake.nix` only) → push to vps2
`source.archipelago-foundation.org/lfg2025/fedimint-clientd:v0.4.0`.
### 5. Unified balance
`HomeWalletCard` ecash row = Cashu `wallet.ecash-balance` + Fedimint `wallet.fedimint-balance`.
(Home already calls `wallet.ecash-balance`; add fedimint and sum.)
## Networking sats — dual protocol (phase 6, NOT yet wired)
The economic layer (`streaming.rs`, `streaming/gate.rs`, sessions, pricing, metering) is already
protocol-agnostic — it just calls into the wallet. The injection points are:
1. **Protocol-tag accepted mints.** `accepted_mints: Vec<String>` → carry protocol, e.g.
`cashu:https://mint…` / `fedimint:<federation_id>`. Migrate `wallet/accepted_mints.json` with a
back-compat reader (bare URL ⇒ `cashu:`).
2. **`MintClient::new()` is the bottleneck** (~10 call sites). Introduce a `MintBackend` trait with
`CashuBackend` (wraps current code) and `FedimintBackend` (calls `FedimintClient`).
3. **`Token` enum** `Cashu(CashuToken) | Fedimint(notes)`; serialize/verify by variant.
4. `build_payment_token()` picks a `(backend, id)` the peer accepts; `verify_and_receive_payment()`
auto-detects the token variant and reissues/swaps on the right backend.
5. Cross-protocol settlement (Cashu↔Fedimint) bridges over Lightning (BOLT11) — both sides already
have mint/melt (Cashu) and `ln/invoice`+`ln/pay` (Fedimint).
6. `Web5NetworkingProfitsSettings.vue`: per-service payout protocol/mint selector.
## Phases
- [x] **P0** FE tabbed Wallet Settings modal + gear (Cashu live, Fedimint tab structured).
- [x] **P1** `fedimint-clientd` container manifest + ports.
- [x] **P2** `FedimintClient` HTTP bridge + `wallet.fedimint-*` RPCs (compiles).
- [ ] **P3** Validate join / balance / spend / reissue against a live clientd + real federation on a scratch node.
- [ ] **P4** Unified ecash balance in the wallet card (Cashu + Fedimint).
- [ ] **P5** Flip FE fully live; surface "install Fedimint client app" when clientd unreachable.
- [ ] **P6** Networking-sats dual-protocol routing (the `MintBackend`/`Token` refactor above).
## Validation (per project testing discipline)
clientd image + a real federation are required; cannot be validated from the dev tree. Validate on
a scratch node: install Fedimint app + clientd, join a known test federation, confirm
`wallet.fedimint-balance`, then a spend→reissue round-trip between two nodes, then networking-sats
payment over Fedimint. Heavy/iterative work belongs in a worktree (see CLAUDE.md memory).
docs/hardware-signer-design.md
+171
View File
@@ -0,0 +1,171 @@
# Archipelago Hardware Signer — Design Notes (PSBT + Nostr)
> Status: **exploratory / spec stub** (2026-06-24). No code yet. This captures the
> hardware-selection reasoning and architecture for a small, air-gapped, super-secure
> signing device built around the Tropic Square **TROPIC01** secure element, intended
> to integrate with Archipelago as an external signer.
## 1. Goal
A small, super-secure, air-gapped handheld device that:
- Signs **Bitcoin PSBTs** for the Archipelago wallet.
- (Stretch / dual-function) Signs **Nostr events** for the node's sovereign identity.
- Communicates **only via QR** (camera in, screen out) — no USB data path, no radio in
use. Pure air-gap, same threat model as SeedSigner but with a real audited secure element.
- Anchors key-at-rest security and RNG in the **TROPIC01** open-source secure element.
## 2. The critical curve caveat
**TROPIC01's signing engine supports P-256 (ECDSA) and Ed25519 (EdDSA) — NOT secp256k1.**
Bitcoin and Nostr both require secp256k1. Therefore:
- The secure element is the **vault + RNG + attestation**, not the signer.
- The seed lives encrypted inside TROPIC01 (tamper mesh, pairing, secure channel).
- The host MCU does the actual **secp256k1 ECDSA (Bitcoin)** and **Schnorr / BIP-340
(Taproot + Nostr)** signing in software.
- TODO before committing: re-check whether a firmware revision adds secp256k1 — it's
open RISC-V silicon and has been a community ask. If/when it lands, this design gets
materially stronger (signing in-silicon).
## 3. Architecture (two chips)
```
[ QR in ] --> Camera (OV2640)
|
Host MCU (ESP32-S3) <--SPI--> TROPIC01 (Mini Board)
| (seed vault, RNG,
Touch screen secure channel, attest)
|
[ QR out ] <-- Display (signed PSBT / signed event)
```
- **Host MCU** drives camera, touch screen, QR parse/render, PSBT + Nostr logic, and
the secp256k1/Schnorr signing.
- **TROPIC01** protects the seed at rest and supplies the TRNG + secure boot/attestation
over an authenticated+encrypted SPI channel.
## 4. Hardware selection
### 4.1 MCU — the camera-ease vs radio-purity fork
| | **ESP32-S3** (recommended) | **RP2350** |
|---|---|---|
| Camera | Native DVP interface; huge QR-scan code ecosystem | No camera peripheral — bit-bang over PIO (harder) |
| Radios on die | WiFi + BLE present (con for air-gap purists) | **None** |
| Security | Secure boot, flash encryption | Cortex-M33 + TrustZone, signed boot, OTP |
| secp256k1 in SW | Fine (240 MHz dual-core) | Fine (150 MHz dual-core M33) |
| Price (chip / board) | ~$3 / ~$6 | ~$1.20 / ~$5 |
**Pick: ESP32-S3 (N16R8 — 16MB flash / 8MB PSRAM).** The camera is the hard part of the
build and the S3 is the only cheap MCU with a native camera interface. PSRAM matters for
holding camera frames during QR decode. The on-die radio is the one downside — acceptable
because trust is anchored in the TROPIC01, not the MCU. If radio-on-die is a hard no,
switch to RP2350 and accept harder camera bring-up. (SeedSigner deliberately chose a
no-WiFi Pi Zero 1.3 for exactly this reason — the concern is legitimate.)
### 4.2 Camera
- **OV2640** 2MP module — standard ESP32-cam sensor, code everywhere. ~$2–4.
### 4.3 Thin touch screen
Pick by review legibility (the whole security value is the human verifying address +
amount before tap-to-approve):
- **2.0" IPS ST7789 capacitive, 240×320 — recommended.** Easiest to read a full Bitcoin
address/amount. ~$8–12.
- 1.69" rounded-rect IPS ST7789 + CST816 cap touch — best size/compactness balance.
~$7–10.
- 1.28" round (GC9A01 + CST816) — smallest/thinnest but **too cramped** for address
verification; skip for a signer.
**Do not go below ~1.69".** Use capacitive (not resistive) touch for a thin glass-front
tap-to-confirm feel.
### 4.4 TROPIC01 board (from the Tropic Square order form)
All options speak SPI (wires to the S3 the same way). Two-board plan:
- **Development: TROPIC01 USB DevKit (€50)** — STM32 + USB-to-SPI stick. Bring up the
secure-element stack (pairing, key gen, secure channel) on a PC first, independent of
the camera/screen work.
- **Final device: TROPIC01 Mini Board (€9.50)** — small easy-to-solder module exposing
SPI; solder straight to the S3's SPI bus inside the enclosure.
- Skip: Standalone Sample (€5, bare QFN — needs hot-air), Raspberry Pi / Arduino Shields
(wrong host form factor), MIKROE Click (€20, only if you have a mikroBUS rig).
### 4.5 Rough BOM
| Item | ~Cost |
|---|---|
| ESP32-S3 N16R8 board | $6–8 |
| OV2640 camera | $2–4 |
| 2.0" cap-touch IPS | $8–12 |
| TROPIC01 Mini Board | €9.50 |
| (Dev only) TROPIC01 USB DevKit | €50 |
**Core device BOM ≈ $20–30** + TROPIC01 Mini Board, before enclosure/battery.
## 5. Dual-function: Nostr signer
Genuinely viable and a natural fit — **Nostr signs with Schnorr/BIP-340 over secp256k1,
the same scheme as Bitcoin Taproot.** So Nostr signing reuses the secp256k1+Schnorr code
already needed for Bitcoin — near-zero marginal firmware cost.
### 5.1 One seed → two separated keys
From the single seed in the TROPIC01:
- **Bitcoin:** BIP-32/39/84 HD derivation.
- **Nostr:** **NIP-06** deterministic derivation (`m/44'/1237'/…`) → `nsec`/`npub`.
One backup, two independent identities, no cross-contamination.
### 5.2 Cold vs hot tension
| | Bitcoin | Nostr |
|---|---|---|
| Frequency | Rare, high-value | Frequent, often interactive |
| Natural transport | QR / PSBT — air-gap perfect | Apps want real-time signing |
| Air-gap comfort | Excellent | Fine for occasional events, painful for chat |
Two possible modes:
1. **Air-gapped QR Nostr signer (recommended):** app shows unsigned-event QR → camera
scan → touch approve → signed-event QR back. Great for high-value/infrequent events
(root identity, profile/metadata, key rotation, announcements). Keeps 100% air-gap.
2. **Connected NIP-46 "bunker" over USB/serial:** enables interactive real-time signing
but **breaks the air-gap** and reintroduces the USB/radio attack surface. Not
recommended for this device.
### 5.3 Recommendation
Keep it **cold for both roles.** The device guards the Bitcoin spending key *and* the
high-value Nostr **identity** key — neither ever touches a network. Day-to-day Nostr
chatter uses a separate hot software key; the hardware device protects only the
identity-defining key you can't afford to leak. Avoids putting a hot key next to cold
Bitcoin funds.
## 6. Archipelago integration
- Slots in as an **external signer** path alongside the existing wallet flow — does not
touch the orchestrator. Archipelago builds PSBT → renders QR (animated QR for large
txs) → device scans → touch review → returns signed-PSBT QR → Archipelago broadcasts.
- Especially apt given Archipelago's Nostr/Blossom catalog + node-identity direction
(see `dht-distribution-design.md`): the device becomes the **hardware root of trust**
for both halves of a node's identity — its `npub`/DID and its Bitcoin keys — aligning
with the sovereign/secure/rootless north star.
## 7. Open items / next steps
- [ ] **Pin budget:** confirm the S3 GPIO/SPI budget fits camera DVP + display SPI +
TROPIC01 SPI simultaneously. (Biggest unknown before buying.)
- [ ] Confirm current TROPIC01 firmware secp256k1 status (could remove the §2 caveat).
- [ ] Define QR payload formats for both roles (PSBT vs unsigned Nostr-event JSON) so a
single scan→approve→return firmware loop handles either transparently.
- [ ] Animated/multi-part QR strategy for large PSBTs.
- [ ] Seed provisioning ceremony into the TROPIC01 (gen on-device via its TRNG; never
import in clear).
- [ ] Enclosure + power (battery vs USB-power-only-while-airgapped).
- [ ] Decide: ESP32-S3 (radio present) vs RP2350 (no radio, harder camera) — final call.
docs/manifest-hooks-design.md
+114
View File
@@ -0,0 +1,114 @@
# Manifest Lifecycle Hooks — Design
**Status:** implemented through Phase 4 (see §6; updated 2026-07-08) — only declarative `pre_start` remains · originally Task #20
(indeedhub, netbird) off legacy Rust installers.
See `docs/APP-PACKAGING-MIGRATION-PLAN.md`
("controlled hooks").
---
## 1. Problem
Some apps need a step the static manifest can't express: a **post-start container
mutation**. The motivating case is indeedhub's `patch_indeedhub_nostr_provider()`:
1. `podman exec indeedhub sed -i '/X-Frame-Options/d' /etc/nginx/conf.d/default.conf`
(strip the header so the app loads in our iframe)
2. `podman cp /opt/archipelago/web-ui/nostr-provider.js indeedhub:/usr/share/nginx/html/`
3. patch nginx conf to inject `<script src="/nostr-provider.js">` and reload
A manifest `files:` entry writes files on the **host** before create; it cannot
patch a **running** container or copy a host file into it. Without a hook,
migrating indeedhub to the orchestrator ships a broken UI.
## 2. Non-goals / security posture
Per the packaging plan: **NOT arbitrary host scripts.** Hooks are declarative,
allowlisted operations, run against the app's **own** (already manifest-sandboxed)
container. This preserves "no arbitrary privileged execution" while giving a
reviewed escape hatch.
- **No host execution.** `exec` runs *inside the container* (`podman exec`), never
on the host.
- **No arbitrary host reads.** `copy_from_host.src` is **relative to an allowlist
root** (`<data_dir>` and `/opt/archipelago/web-ui`), resolved + canonicalised;
any `..` escape or absolute path outside the allowlist is rejected at validate().
- **Same privileges as the container.** `exec` inherits the container's caps
(already dropped per `security:`), so a hook can't exceed the app's own sandbox.
- **Best-effort + idempotent.** Hooks must be safe to re-run (guard with
`grep -q … || …`). A hook failure is logged, not fatal — matching the legacy
best-effort patch, so a transient hook error never bricks an install.
## 3. Schema (`AppDefinition.hooks`)
```yaml
app:
id: indeedhub
hooks:
post_install: # after the container is created + running, on install
- exec: ["sed", "-i", "/X-Frame-Options/d", "/etc/nginx/conf.d/default.conf"]
- copy_from_host:
src: "web-ui/nostr-provider.js" # relative to allowlist root
dest: "/usr/share/nginx/html/nostr-provider.js"
- exec: ["sh", "-c", "grep -q nostr-provider /etc/nginx/conf.d/default.conf || sed -i 's#</head>#<script src=\"/nostr-provider.js\"></script></head>#' /etc/nginx/conf.d/default.conf"]
- exec: ["nginx", "-s", "reload"]
pre_start: [] # (future) run before each start — repair/ownership
```
Types (in `archipelago-container`):
```rust
pub enum HookStep {
Exec { exec: Vec<String> },
CopyFromHost { copy_from_host: HostCopy },
}
pub struct HostCopy { pub src: String, pub dest: String }
pub struct LifecycleHooks {
#[serde(default)] pub post_install: Vec<HookStep>,
#[serde(default)] pub pre_start: Vec<HookStep>,
}
```
`hooks` is `#[serde(default)]` + forward-compatible (absent = no hooks).
## 4. Execution
`container::hooks::run_post_install(manifest, container_name, data_dir)`:
- Resolve container name via `compute_container_name`.
- For each step in order:
- `Exec` → `podman exec <container> <args…>` (timeout-bounded).
- `CopyFromHost` → canonicalise `src` against the allowlist roots; reject on
escape; `podman cp <abs-src> <container>:<dest>`.
- Log each step; on error, `warn!` and continue (best-effort).
Called from the orchestrator's install path **after** the container is up
(post-create/health), and gated so it runs on install (not every reconcile).
Validation (`AppManifest::validate`): every `copy_from_host.src` must resolve
inside an allowlist root and contain no `..`; `exec` must be non-empty.
## 5. indeedhub migration (the payoff)
With hooks, indeedhub becomes fully manifest-driven: 7 member manifests
(postgres/redis/minio/relay/api/ffmpeg/frontend) + the frontend manifest carries
the `post_install` hook above. `install_indeedhub_stack` becomes orchestrator-first
(like btcpay), legacy as fallback. Same pattern unblocks netbird's setup steps.
## 6. Phases
1. ✅ **Schema + validation + unit tests** — `LifecycleHooks`/`HookStep`/`HostCopy`
in `archipelago-container::manifest`, allowlist-enforced at `validate()`.
(commit `4c1a4e59`)
2. ✅ **Executor + wire into orchestrator install** — `container::hooks::run_post_install`
(`exec` + `copy_from_host`, canonicalise + symlink-escape prefix check, best-effort);
called from `install_fresh` after the container is up, fresh-container-only.
(commit `955c54b7`)
3. ✅ **indeedhub**: member manifests + frontend `post_install` hooks shipped
(`apps/indeedhub/manifest.yml` declares the nostr-provider copy + nginx
reload; `install_indeedhub_stack` is orchestrator-first via
`install_stack_via_orchestrator`).
4. ✅ **netbird** (resolved differently): installs via the stack orchestrator,
but its setup is handled by `generated_secrets`/`generated_certs` + the
per-app Rust `run_pre_start_hooks` path rather than manifest hooks — no
`hooks:` block in its manifest.
5. ⏳ `pre_start` hooks (repair/ownership) — type exists; executor not yet
wired. Note: `prod_orchestrator.rs::run_pre_start_hooks` is a hardcoded
per-app Rust match today, NOT this declarative path.
docs/marketplace-protocol.md
+463
View File
@@ -0,0 +1,463 @@
# Decentralized App Marketplace Protocol
**Status:** implemented (updated 2026-07-08). This started as a protocol
proposal; the described subsystem is now shipped end-to-end —
`core/archipelago/src/marketplace.rs` (discover/publish/trust scoring),
the `marketplace.*` RPC namespace, and `Marketplace.vue`. Beyond this doc,
the code also adds `marketplace.create-invoice` (Lightning BOLT11 app
purchases). What remains is maturation: publishing tooling and trust UX
(see `ROADMAP.md`). Note: the manifest schema below is the marketplace's
own flatter format, **not** the runtime `apps/*/manifest.yml` schema
(`app-manifest-spec.md`).
> **The DID signature layer is implemented** as of 2026-08-08. `publish` signs
> with the node's Ed25519 identity key, `discover` verifies every manifest
> before caching it, and a manifest whose signature is *present but wrong* is
> dropped rather than listed at a lower score. See
> [Signing Protocol](#signing-protocol) for the exact preimage rules — they are
> normative, and an implementation that canonicalises differently will produce
> signatures this node rejects.
## Overview
Archipelago's community marketplace enables developers to publish app manifests to Nostr relays, where nodes discover and install them without a central app store. Trust is established through DID-signed manifests and community reputation.
## Architecture
```
Developer Node Nostr Relays User Node
│ │ │
│── Publish signed manifest ──► │ │
│ (NIP-78, kind 30078) │ │
│ │ ◄── Query app manifests ── │
│ │ (filter by d-tag) │
│ │ │
│ │── Return signed manifests ──► │
│ │ │
│ │ [Verify DID signature] │
│ │ [Check trust score] │
│ │ [Display in marketplace] │
│ │ │
│ │ [User clicks Install] │
│ │ [Pull container image] │
│ │ [Start container] │
```
## Manifest Schema
App manifests published to Nostr relays use the marketplace's own flatter JSON
schema — the `AppManifest` type in `marketplace.rs`, shown below — serialized
into the Nostr event's `content`. It is **not** the runtime
`apps/{app-id}/manifest.yml` schema in
[`app-manifest-spec.md`](app-manifest-spec.md); the two are separate types that
happen to share a name.
### Marketplace Manifest Fields
```json
{
"app_id": "my-bitcoin-tool",
"name": "My Bitcoin Tool",
"version": "1.2.0",
"description": {
"short": "A useful Bitcoin utility",
"long": "Detailed description of what this app does..."
},
"author": {
"name": "Developer Name",
"did": "did:key:z6Mkh...",
"nostr_pubkey": "npub1..."
},
"container": {
"image": "docker.io/developer/my-bitcoin-tool:1.2.0",
"ports": [{ "container": 8080, "host": 8180, "protocol": "tcp" }],
"volumes": [{ "name": "data", "path": "/data" }],
"env": {
"NETWORK": "mainnet"
},
"capabilities": [],
"readonly_root": true,
"no_new_privileges": true,
"run_as_user": 1000
},
"category": "money",
"icon_url": "https://example.com/icon.png",
"repo_url": "https://github.com/developer/my-bitcoin-tool",
"license": "MIT",
"min_archipelago_version": "0.1.0",
"dependencies": [],
"signatures": {
"manifest_hash": "sha256:abc123...",
"did_signature": "base64-encoded-signature"
}
}
```
### Required Fields
| Field | Type | Description |
|-------|------|-------------|
| `app_id` | string | Unique identifier, lowercase kebab-case |
| `name` | string | Human-readable display name |
| `version` | string | Semantic version (major.minor.patch) |
| `description.short` | string | One-line description (max 120 chars) |
| `author.did` | string | Developer's DID (did:key method) |
| `container.image` | string | Full container image reference with tag (never `latest`) |
| `category` | string | One of: money, commerce, data, networking, home, community, other |
### Security-Required Fields
| Field | Default | Description |
|-------|---------|-------------|
| `container.readonly_root` | true | Container root filesystem is read-only |
| `container.no_new_privileges` | true | Prevent privilege escalation |
| `container.run_as_user` | 1000 | UID to run as (must be ≥ 1000) |
| `container.capabilities` | [] | Required Linux capabilities (drop all, add only needed) |
## Nostr Event Format
### Event Kind
App manifests use **NIP-78 application-specific data** with event kind **30078** (replaceable parameterized). This matches the existing node discovery pattern in `nostr_discovery.rs`.
### Event Structure
```json
{
"kind": 30078,
"tags": [
["d", "archipelago-app:<app_id>"],
["t", "archipelago-marketplace"],
["t", "category:<category>"],
["version", "<semver>"],
["image", "<container_image>"],
["L", "archipelago"],
["l", "app-manifest", "archipelago"]
],
"content": "<JSON-serialized manifest>",
"created_at": 1710000000,
"pubkey": "<developer's secp256k1 pubkey hex>",
"sig": "<schnorr signature>"
}
```
### Tag Semantics
| Tag | Purpose |
|-----|---------|
| `d` | Unique identifier for NIP-33 replaceable events. Format: `archipelago-app:<app_id>` |
| `t` | Searchable topic tags for relay filtering |
| `version` | Allows version-specific queries |
| `image` | Container image for quick display without parsing content |
| `L`/`l` | NIP-32 labeling namespace for structured queries |
### Publishing a Manifest
1. Developer creates/updates their app manifest
2. `author.did` is filled in with the node's own `did:key` if empty. If it is
set to a **different** DID, publishing is refused — the node can only sign as
itself, and broadcasting a manifest every verifier will reject helps nobody
3. Canonicalise the manifest without `signatures` and SHA-256 it (see
[Signing Protocol](#signing-protocol))
4. Sign the digest with the node's Ed25519 identity key and attach `signatures`
5. Embed the signed manifest as the Nostr event content
6. Sign the Nostr event with the node's secp256k1 Nostr key
7. Publish to all configured Nostr relays
Note the two distinct keys: the **Ed25519 identity key** proves *authorship of
the manifest* and is what `author.did` names; the **secp256k1 Nostr key** proves
*who sent this event*. They are separate on purpose — relaying is not
authorship, and only the first survives being copied between relays.
### Discovering Manifests
1. Node queries configured relays with filter:
```json
{
"kinds": [30078],
"limit": 100,
"#t": ["archipelago-marketplace"]
}
```
2. For each returned event:
a. Verify Nostr event signature (standard NIP-01)
b. Parse manifest JSON from content
c. Verify DID signature on manifest hash
d. Check manifest against security requirements
e. Calculate trust score
3. Return manifests sorted by trust score
## Trust Model
### Trust Score Calculation
Each discovered app receives a trust score (0-100) based on:
This table is `calculate_trust_score()` in `marketplace.rs`. What each factor
actually checks:
| Factor | Max | What is checked |
|--------|-----|-----------------|
| **Identity proven** | 30 | The manifest carries a `valid` DID signature — the author demonstrated control of the key `author.did` encodes. Requires key material; cannot be faked by choosing a string |
| **Relay consensus** | 20 | Graduated, and never zero: 1 relay → 5, 2–3 → 12, 4+ → 20 |
| **Federation trust** | 20 | `author.did` is in the user's federated DID list **and** identity is proven. Both halves are required — see below |
| **Provenance** | 15 | 10 for a 3-part semver `version`, 5 for a non-empty `repo_url`. Nothing counts published versions |
| **Security compliance** | 15 | 15 when `validate_manifest()` returns no issues, 5 when it returns 1–2, 0 otherwise |
Both identity-derived factors hang off the signature, which is the point:
- Before, "DID present" was `did.starts_with("did:")`, so an unsigned manifest
with a plausible-looking DID string and a pinned image scored 65 — *Community*
tier — on no cryptography whatsoever. It now scores 35, *Unverified*.
- Federation trust is gated too. An unverified `author.did` is just a string the
publisher chose, so an attacker could otherwise copy the DID of a peer the
user federates with and collect 20 points for impersonating precisely the
party the user trusts most.
An unsigned publisher is not punished beyond losing those points: `missing` is a
normal state, and such apps still appear.
### Trust Tiers
| Score | Tier | UI Treatment |
|-------|------|--------------|
| 80-100 | Verified | Green badge, install with one click |
| 50-79 | Community | Yellow badge, install with confirmation |
| 20-49 | Unverified | Orange badge, install with warning dialog |
| 0-19 | Untrusted | Red badge, requires explicit security override |
### Federation-Based Trust
When a developer's DID appears in the user's federation network (trusted peer), the app automatically receives +20 trust points. This creates organic trust propagation: if you trust a node operator, you're more likely to trust their published apps.
### ADR: Nostr Relays over Centralized Registry
**Decision**: Use Nostr relays as the app discovery layer instead of a centralized registry.
**Context**: A centralized app store contradicts Archipelago's sovereignty principles. Nostr relays provide censorship-resistant, decentralized event distribution.
**Consequences**:
- (+) No single point of failure for app discovery
- (+) Developers publish without permission or review gates
- (+) Multiple relay sources increase availability
- (+) Leverages existing Nostr infrastructure and key management
- (-) No global content moderation (each node decides trust locally)
- (-) Spam is possible (mitigated by DID verification and trust scoring)
- (-) Relay availability varies (mitigated by querying multiple relays)
## Signing Protocol
### Manifest Signing (DID Layer)
**Normative.** These rules define the signed preimage byte-for-byte. An
implementation that canonicalises differently will produce signatures this node
rejects, so they are worth following exactly.
```
1. Take the manifest with `signatures` REMOVED (a signature cannot cover the
field that holds it; omit the key entirely rather than setting it null).
2. Canonicalise to JSON:
- every object's keys sorted lexicographically, recursively;
- no insignificant whitespace;
- arrays keep their order.
3. manifest_hash = SHA-256(canonical_json_bytes)
4. did_signature = Ed25519_Sign(author_private_key, manifest_hash)
^ the signature covers the 32 RAW DIGEST BYTES, not the "sha256:..."
string and not the JSON itself.
5. Attach:
{
"signatures": {
"manifest_hash": "sha256:<64 lowercase hex chars>",
"did_signature": "<standard base64, RFC 4648 §4, with padding>"
}
}
```
The signing key MUST be the Ed25519 key that `author.did` encodes — `author.did`
is a `did:key` whose multibase body is `0xed01 || <32-byte public key>`. A
publisher signing with any other key produces a manifest that verifies as
`invalid` and is dropped.
**Why canonicalisation is required and not cosmetic.** `container.env` is a map,
and map iteration order is not stable across processes or implementations. Sign
the serialiser's natural output and the same manifest hashes differently between
runs, so signatures fail at random rather than never — much harder to diagnose
than a clean rejection. Sorting keys removes the ambiguity.
`archipelago` implements this in `marketplace::canonical_signing_bytes` /
`sign_manifest` / `verify_manifest_signature`.
### Event Signing (Nostr Layer)
Standard NIP-01 Schnorr signature over the event ID (hash of serialized event fields). This is handled by the Nostr client library.
### Verification Flow
```
Receiving Node:
1. Verify Nostr event signature (NIP-01) → event authenticity [IMPLEMENTED]
2. Extract manifest JSON from event content [IMPLEMENTED]
3. Canonicalise the manifest without `signatures`, SHA-256 it [IMPLEMENTED]
4. Compare with manifest.signatures.manifest_hash → content integrity [IMPLEMENTED]
5. Resolve author.did (did:key) to its Ed25519 public key [IMPLEMENTED]
6. Verify did_signature over the digest → author identity [IMPLEMENTED]
7. Check container.image tag is pinned (not :latest) [ADVISORY]
8. Validate security fields meet minimums [ADVISORY]
```
Steps 3–6 are `verify_manifest_signature()`, which returns one of three verdicts
rather than a boolean:
| Verdict | Meaning | What discovery does |
|---|---|---|
| `valid` | Hash matches the content **and** the key named by `author.did` signed it | Listed; earns the identity-derived trust points |
| `missing` | No `signatures` block | Listed, but scores **zero** on identity and federation. An unsigned publisher is unproven, not hostile |
| `invalid` | A `signatures` block is present and wrong — tampered, corrupt, or signed by another key | **Dropped entirely**, with the reason logged. Never cached, never installable |
That `invalid` handling is deliberate: a broken signature is not a low-quality
manifest, it is a forged or corrupted one, so it fails closed rather than
appearing with a scary badge someone can click past.
Steps 7–8 still run, but `validate_manifest()` returns a list of *issues* that
feed the trust score — they do not block discovery or installation.
## RPC Endpoints
### Marketplace Discovery
| Method | Description | Auth |
|--------|-------------|------|
| `marketplace.discover` | Query relays for app manifests, verify, score, return sorted | Local |
| `marketplace.publish` | Sign the manifest with this node's identity key, then publish to configured relays | Local |
| `marketplace.get-manifest` | Get full manifest for a specific app by ID | Local |
| `marketplace.verify` | Check a manifest's DID signature and security compliance without publishing it | Local |
`marketplace.verify` returns the signature verdict separately from the advisory
policy issues, because they mean different things:
```json
{
"signature": { "status": "invalid", "reason": "did_signature does not verify against author.did" },
"signature_valid": false,
"valid": true, // ← policy compliance only; NOT authenticity
"issues": [],
"trust_score": 35,
"trust_tier": "unverified"
}
```
`valid` has always meant "passes the advisory security checks". Read
`signature_valid` for authenticity. Discovered apps carry the same verdict in
their `signature` field.
### Manifest Management
| Method | Description | Auth |
|--------|-------------|------|
| `marketplace.list-published` | List manifests published by this node | Local |
### Purchases
| Method | Description | Auth |
|--------|-------------|------|
| `marketplace.create-invoice` | Create a Lightning BOLT11 invoice for a paid app | Local |
| `marketplace.check-payment` | Poll whether an invoice has settled | Local |
`marketplace.unpublish` was specified here but **never implemented** — the
string appears nowhere in the codebase, and there is no dispatcher entry. NIP-33
replaceable events mean an unpublish would have to be a tombstone/replacement
rather than a delete, which is presumably why it stalled.
## Security Requirements
### Container Security Enforcement
`validate_manifest()` checks the following and returns them as a list of issues.
**These are score inputs, not gates** — a manifest that fails all of them is
still discoverable and installable, it just scores 0 on the security factor:
1. **No `latest` tag**: Image must use a specific version tag
2. **Read-only root**: `readonly_root` should be true
3. **No root**: `run_as_user` must be **≥ 1000** (the code's bound; the example
manifest above uses exactly `1000`)
4. **No new privileges**: `no_new_privileges` should be true
Items previously listed here — a capability allow-list, a host-networking ban,
and system-path mount restrictions — are **not** part of marketplace validation.
Those rules exist, but they live in the runtime manifest parser
(`core/container/src/manifest.rs`, see [`app-manifest-spec.md`](app-manifest-spec.md))
and apply to `apps/*/manifest.yml`, which is a different schema from the
marketplace manifest. Closing that gap is part of the pre-third-party-publishing
work.
### Image Verification
- Container images are pulled from registries, never transferred between nodes
- Future: Cosign signature verification for container images (leverages `core/security/`)
- Image digest pinning recommended for production apps
## UI: Community Marketplace Tab
### Route
Extends existing `/dashboard/marketplace` page.
### Layout
Two tabs at the top of Marketplace.vue:
1. **Curated** (existing): Built-in apps maintained by Archipelago team
2. **Community** (new): Apps discovered from Nostr relays
### Community Tab Components
1. **App Grid**: Same card layout as curated tab, with trust score badge
2. **Search & Filter**: Category filter + text search across community apps
3. **Trust Indicators**: Color-coded badges (Verified/Community/Unverified/Untrusted)
4. **App Detail**: Shows full manifest, developer DID, relay sources, version history
5. **Install Flow**: Trust-level-dependent confirmation (one-click for Verified, warning for Untrusted)
### Publishing UI
Accessible from Settings or a "Developer" section:
1. Select a local app container to publish
2. Fill in manifest metadata (description, category, icon)
3. Review security compliance
4. Sign and publish to relays
5. View published manifests and their discovery status
## Data Storage
```
/var/lib/archipelago/marketplace/
├── cache/
│ └── manifests.json # Cached discovered manifests, trust scores included
└── published/
└── <app-id>.json # Manifests published by this node
```
The earlier version of this tree also listed `cache/trust-scores.json` and
`config.json`. Neither is written: scores live on the cached entries themselves
(`MarketplaceCache`), and there is no marketplace preferences file.
## Implementation Notes
### Relay Query Strategy
1. Query all enabled relays in parallel (from `nostr_relays.rs` config), with a
10s connect timeout and a 20s fetch timeout per relay
2. Deduplicate manifests by `app_id` + `version`
3. If the same manifest is found on multiple relays, boost trust score
4. Write results to `cache/manifests.json`
Items 4–5 of the original design — a 15-minute cache TTL and a 30-minute
background refresh — are **not implemented**. The cache has no expiry and
nothing refreshes it on a timer; it is rewritten whenever
`marketplace.discover` runs.
### Version Comparison
- Use semantic versioning for all version comparisons
- When multiple versions exist for the same `app_id`, show the latest
- Keep version history available in app detail view
- Flag apps with versions older than 6 months as potentially unmaintained
docs/meshroller-integration-design.md
+176
View File
@@ -0,0 +1,176 @@
# Meshroller → Rust-native mesh assistant (issue #50)
**Decision (2026-06-17): seam (a) — lift Meshroller's *behaviors* into our Rust
mesh stack as typed message kinds.** We do NOT package the Python/Meshtastic
daemon. Meshroller rides Meshtastic-serial + a local Ollama; our radio is
**meshcore** (Heltec V3) and the `meshtastic` Python module cannot drive it. So
we reimplement its four behaviors natively against `core/archipelago/src/mesh/`,
drop the Python + Meshtastic dependency, and reuse our existing event/transport
seams.
Meshroller's behaviors (from the Phase-0 review of `meshroller.py`):
1. **LLM bridge** — relay an inbound mesh message to a local LLM, send the reply
back on the mesh.
2. **Trusted-node auth** — only trusted senders may invoke commands.
3. **Scheduled / queued messaging** — send messages at a future time; queue for
peers that are currently offline.
4. **On-channel command parser** — recognise commands in channel traffic.
---
## Where this plugs in (verified seam map)
| Concern | File / type | Anchor |
|---|---|---|
| Wire message kinds | `mesh/message_types.rs` `MeshMessageType` (`#[repr(u8)]`) | 28–73 |
| Envelope (CBOR, `0x02` marker, `seq`, `sig`) | `mesh/message_types.rs` `TypedEnvelope` | 183–197 |
| Inbound dispatch match | `mesh/listener/dispatch.rs` `handle_typed_envelope_direct()` | 80–691 |
| Outbound send | `mesh/mod.rs` `send_typed_wire()` / `send_channel_typed_wire()` | 848 / 1152 |
| Radio I/O command channel | `mesh/listener/mod.rs` `MeshCommand` (`SendText`/`BroadcastChannel`) | 55–73 |
| Frame chunking (≤160 B/frame, transparent) | `mesh/listener/session.rs` `send_dm_via_channel()` | — |
| UI push | `mesh/types.rs` `MeshEvent` (broadcast on `state.event_tx`, cap 64) | 125–164 |
| Trust gate | `federation/types.rs` `TrustLevel::Trusted` on `FederatedNode`; `federation::load_nodes()` | 5–52 |
| Block on user-blocklist | `mesh/listener/mod.rs` `ContactEntry.blocked` (`state.contacts`) | 110 |
| Local model | Ollama container, port **11434** (`port_allocator.rs:11`); call via `reqwest` (already a dep) | — |
No in-Rust LLM exists yet; we call the **local Ollama HTTP API** (the same model
Meshroller used) so nothing new is baked into the binary.
---
## Phase 1 — the assistant on the wire
### 1.1 New typed message kinds (`message_types.rs`)
Add two variants (next free tag = 24):
```rust
AssistQuery = 24, // "ask the node's AI" — prompt + optional model
AssistResponse = 25, // reply — request_id + text + done flag
```
Wire the four spots the enum requires (`from_u8` 76–104, `from_label` 109–137,
`label()` 139–166, plus the variant) — mirror the `Invoice` variant exactly.
Payloads (CBOR via `encode_payload`/`decode_payload`):
```rust
pub struct AssistQueryPayload { pub req_id: u64, pub prompt: String, pub model: Option<String> }
pub struct AssistResponsePayload { pub req_id: u64, pub text: String, pub seq: u16, pub done: bool }
```
`seq`/`done` let a long reply span multiple `AssistResponse` messages without
relying solely on frame reassembly (radio airtime is scarce — see §1.4 cap).
### 1.2 Inbound handler (`listener/dispatch.rs`)
Add a match arm for `AssistQuery`, mirroring the **`TxRelay`** arm (169–207):
validate → **gate** → spawn background work (never block the radio loop).
```rust
Some(MeshMessageType::AssistQuery) => {
let payload = decode_payload::<AssistQueryPayload>(&envelope.v)?;
if !assistant_enabled(state) { return; } // kill switch (config)
if !sender_is_allowed(state, sender_contact_id).await { warn!(..); return; }
if !rate_limit_ok(state, sender_contact_id).await { return; } // 1 in-flight / sender
let _ = state.event_tx.send(MeshEvent::AssistQueryReceived { from_contact_id, prompt });
let st = Arc::clone(state);
tokio::spawn(async move { run_assist(&st, sender_contact_id, payload).await; });
}
```
`run_assist`: POST `http://localhost:11434/api/generate`
(`{model, prompt, stream:false}`), cap + chunk the response (§1.4), and emit each
chunk back to the sender via `send_typed_wire(contact_id, …, "assist_response", …)`.
Also store via the existing `store_typed_message` path so it lands in history,
and emit `MeshEvent::AssistResponseReady`.
### 1.3 Trust gate (`sender_is_allowed`)
Reuse the federation trust list — no new store:
```rust
let nodes = federation::load_nodes(&data_dir).await.unwrap_or_default();
let peer = state.peers.read().await.get(&sender_contact_id).cloned();
let trusted = peer.and_then(|p| nodes.iter().find(|n|
Some(&n.pubkey) == p.pubkey_hex.as_ref() || Some(&n.did) == p.did.as_ref())
.map(|n| n.trust_level == TrustLevel::Trusted)).unwrap_or(false);
```
Plus honour `ContactEntry.blocked`. Config picks the policy:
**trusted-only** (default) | **specific contacts** | **anyone on channel** (opt-in).
### 1.4 Airtime discipline (meshcore reality)
Frames are ≤160 B and reassembly is automatic, but bandwidth is tiny. So:
- **Cap** the reply (default ~480 chars / ≤3 `AssistResponse` chunks); append
`…(truncated — reply '!more')` and keep the tail server-side for a `!more`.
- **Rate-limit**: one in-flight query per sender; drop/deny extras.
- **Timeout** the Ollama call (e.g. 60 s) and reply with a short error on failure
(`MeshEvent::AssistResponseReady { error }`).
### 1.5 Channel command parser
The killer entry point is a plain channel message, not a typed one. In the
inbound **`Text`** path, when a channel-0/1 message starts with the trigger
(default `!ai ` / `!ask `), synthesise an `AssistQuery` from the remainder and
run the same gated `run_assist`. This means **any meshcore client** (even a bare
Meshtastic-style sender) can ask, while typed `AssistQuery` is the rich path our
own UI uses. Trigger + enable are config.
A sibling command, **`!archy`**, answers node-status questions from the local
status caches with no model in the loop (`mesh/listener/node_cmd.rs`). It reuses
this design's trust gate (`is_sender_allowed`) and reply routing verbatim, but
deliberately does *not* require `assistant_enabled` — turning the LLM off should
not take node status with it. See [COMMANDS.md](COMMANDS.md) for the full
user-facing command surface.
### 1.6 UI events (`types.rs`)
```rust
AssistQueryReceived { from_contact_id: u32, prompt: String },
AssistResponseReady { req_id: u64, to_contact_id: u32, error: Option<String> },
ScheduledMessageFired { message_id: u64 }, // for Phase 1.7
```
Subscribers already flow through the single `event_tx` broadcast — no extra
wiring.
### 1.7 Scheduled / queued messaging
A small `AssistScheduler` owned by `MeshService` (sits beside `relay_tracker` /
`dead_man_switch` in `mod.rs`):
- Persisted queue `{ id, contact_id|channel, wire, fire_at, attempts }` under
`data_dir/mesh/scheduled.json`.
- A tokio task wakes at the earliest `fire_at`, sends via the normal
`send_typed_wire` / `MeshCommand::SendText` path, emits `ScheduledMessageFired`.
- **Offline queue**: on send failure (peer unreachable) keep the item and retry
when a `PeerDiscovered` / `PeerUpdated` event names that peer.
- RPC: `mesh.schedule-message { contact_id|channel, body, fire_at }`,
`mesh.list-scheduled`, `mesh.cancel-scheduled`.
---
## Phase 2 — killer Mesh-tab UX (ties into `project_mesh_telegram_plan`)
**Onboarding (one screen, three steps):**
1. *Model* — detect Ollama on :11434. If absent, a single "Install AI (Ollama)"
button deep-links to the App Store entry; if present, pick the model
(default the one already pulled).
2. *Who can ask* — Trusted nodes only (default) · Pick contacts · Anyone on the
mesh channel (with a clear "uses your node's compute / airtime" warning).
3. *Trigger word* — default `!ai`; toggle the whole feature on.
**Usage (Mesh tab):**
- An **Assistant** card: on/off, model, policy, trigger; live feed driven by
`AssistQueryReceived` / `AssistResponseReady`.
- Composer gains two actions: **Ask the mesh AI** (sends a typed `AssistQuery`)
and **Send later** (date/time → `mesh.schedule-message`), with a "Scheduled"
list (`mesh.list-scheduled`, cancel).
The 1–2 killer actions: *ask the island's AI from any radio*, and *queue a
message that sends itself when a peer comes back in range.*
---
## Verification
Needs **2 radios** (the .116 meshcore + a second) + Ollama running on the
answering node:
1. From radio B send `!ai what's the block height?` → node A (trusted) answers on
the channel; untrusted B is silently denied.
2. Typed `AssistQuery` from our UI → chunked `AssistResponse` renders in the feed.
3. Long reply → truncation + `!more` continues.
4. Schedule a message to an out-of-range peer → it fires when the peer reappears.
## Effort & order
Multi-day. Land in this order so each step is testable alone:
1.1 enum + payloads → 1.2/1.3/1.4 gated bridge → 1.5 channel trigger →
1.6 events → 1.7 scheduler → Phase 2 UI. Phases 1.1–1.4 are the minimum
demoable slice (ask over the mesh, get an answer).
docs/multi-node-architecture.md
+188
View File
@@ -0,0 +1,188 @@
# Multi-Node Architecture
## Overview
Archipelago supports federation — multiple nodes can form a trusted cluster to share status, deploy apps remotely, and coordinate services. This document describes the architecture for multi-node orchestration.
## Discovery & Trust Model
### Node Discovery
Nodes discover each other through two complementary channels:
1. **Nostr Relay Discovery**: Each node publishes its identity (DID, onion address, pubkey) to configured Nostr relays as a NIP-78 application-specific event. Other nodes query relays to find peers.
2. **Direct Invite**: A node generates an invite code containing its DID, onion address, and a one-time authentication token. The recipient node uses this code to establish a direct connection.
3. **Tor Hidden Services**: All inter-node communication uses Tor hidden services (.onion addresses) for privacy and NAT traversal.
### Trust Establishment
Federation uses a mutual DID verification model:
```
Node A Node B
│ │
│── federation.invite (generates invite code) ──► │
│ │
│ ◄── federation.join (presents invite + DID) ── │
│ │
│── Verify Node B's DID Document over Tor ──────► │
│ ◄── Verify Node A's DID Document over Tor ── │
│ │
│── Exchange signed challenge/response ─────────► │
│ ◄── Exchange signed challenge/response ────── │
│ │
│ [Mutual trust established] │
│ [Both nodes add each other to federation] │
```
**Trust Levels**:
- `trusted`: Full federation — can deploy apps, sync state, see all container statuses
- `observer`: Read-only — can see status but cannot deploy or modify
- `untrusted`: Discovered but not yet verified — pending invite acceptance
### ADR: Decentralized Trust over Centralized Authority
**Decision**: Use DID-based mutual verification instead of a central authority or PKI.
**Context**: Archipelago nodes are sovereign — no central server should control trust. Each node maintains its own trust list.
**Consequences**:
- (+) No single point of failure for trust
- (+) Nodes can federate without internet (direct Tor connection)
- (+) Consistent with the DID identity model already in use
- (-) No global revocation mechanism (each node manages its own trust)
- (-) Trust is bilateral — A trusting B doesn't imply C trusts B
## Shared State Protocol
### State Sync
Federated nodes periodically sync their state. Each node exposes a state summary via its RPC endpoint, accessible only to trusted federation peers.
**Synced data**:
- Container/app statuses (installed, running, stopped, version)
- Node health (CPU, memory, disk, uptime)
- Available storage capacity
- Tor hidden service status
- Lightning Network status (channels, capacity)
**Not synced** (privacy):
- Credentials and secrets
- Private keys
- Session data
- User passwords
### Sync Protocol
```
Every 5 minutes (configurable):
For each federated node:
1. POST to peer's /rpc/ endpoint: federation.get-state
2. Authenticate with signed challenge (DID key)
3. Receive state snapshot
4. Store in local federation cache
5. Broadcast changes via WebSocket to local UI
```
### State Storage
```
/var/lib/archipelago/federation/
├── nodes.json # List of federated nodes with trust levels
├── state-cache/
│ ├── <node-did>.json # Latest state snapshot from each peer
│ └── ...
└── invites/
├── pending.json # Outgoing invites awaiting acceptance
└── received.json # Incoming invites awaiting approval
```
## RPC Endpoints
### Federation Management
| Method | Description | Auth |
|--------|-------------|------|
| `federation.invite` | Generate invite code for a new peer | Local |
| `federation.join` | Accept an invite and establish federation | Local |
| `federation.list-nodes` | List all federated nodes with status | Local |
| `federation.remove-node` | Remove a node from federation | Local |
| `federation.set-trust` | Change trust level for a federated node | Local |
### Federation Data Exchange
| Method | Description | Auth |
|--------|-------------|------|
| `federation.get-state` | Return node's state snapshot | Federation peer |
| `federation.deploy-app` | Request remote app installation | Trusted peer |
| `federation.sync-state` | Trigger manual state sync | Local |
### Authentication for Inter-Node RPC
Federation RPC calls between nodes use DID-based authentication:
1. Caller includes `X-Federation-DID` header with their DID
2. Caller includes `X-Federation-Sig` header with a signed timestamp
3. Receiver verifies the DID is in their trusted federation list
4. Receiver verifies the signature using the DID's public key
5. Timestamp must be within 5 minutes to prevent replay attacks
## Federated App Deployment
### Flow
```
Local Node Remote Node
│ │
│── federation.deploy-app ──────► │
│ {app_id, version, config} │
│ │
│ [Remote verifies trust level] │
│ [Remote checks if app exists] │
│ [Remote pulls container image] │
│ [Remote starts container] │
│ │
│ ◄── Status update via sync ── │
│ {app_id: "running"} │
```
### Constraints
- Only `trusted` peers can deploy apps to each other
- Remote node can reject deployment (insufficient resources, policy)
- Container images are pulled from registry, not transferred between nodes
- App configuration is sent with the deploy command
- Remote node applies its own security policies (AppArmor, capabilities)
## UI: Federation Dashboard
**Route**: `/dashboard/server/federation`
**Components**:
1. **Node List**: Table of federated nodes showing:
- Node name (DID-derived or custom alias)
- Status: online/offline (based on last successful sync)
- Trust level badge (trusted/observer)
- App count, resource usage summary
- Last seen timestamp
2. **Add Node**: Form with invite code input or QR code scanner
3. **Node Detail Modal**: Clicking a node shows:
- Full DID and onion address
- Container/app list with statuses
- Resource usage (CPU, memory, disk)
- Deploy app button (if trusted)
- Change trust level / remove node
## Security Considerations
1. **All federation traffic over Tor**: Prevents IP address leakage between nodes
2. **DID-based auth**: No shared secrets; each node proves identity with its key
3. **Replay protection**: Signed timestamps prevent replay attacks
4. **Trust is bilateral**: Both nodes must agree to federate
5. **App deployment is opt-in**: Remote node can refuse deployment requests
6. **State snapshots are read-only**: A compromised peer cannot modify another node's state
7. **Invite codes are single-use**: Once accepted, the invite token is invalidated
docs/nostr-git-source-hosting.md
+252
View File
@@ -0,0 +1,252 @@
# Nostr Git Source Hosting Plan
This plan describes how Archipelago can publish and accept contributions to its
source code through `ngit`, NIP-34, and GRASP while keeping the developer
experience inside Archipelago.
## Goals
- Publish Archipelago source from a sanitized, fresh-history repository.
- Make the in-app registry the primary onboarding path for contributors.
- Let contributors clone, branch, push PR branches, open PRs, and discuss issues
with a Nostr identity from their Archipelago node.
- Follow the Bitcoin Core development model: broad public review and easy forks,
with canonical merge authority held by a small maintainer set.
- Give contributors full read, fork, and proposal rights, but no direct merge
rights on the canonical repository.
- Keep the official maintainer identity and merge authority separate from user
node identities.
## Current Building Blocks
Archipelago already has most of the primitives needed for this:
- App manifests and the app registry already install developer tooling as
rootless Podman apps.
- The `gitea` app provides a conventional fallback Git UI and package registry.
- The app launcher already exposes a consent-gated NIP-07 bridge for launched
apps using `getPublicKey`, `signEvent`, NIP-04, and NIP-44 requests.
- The backend exposes node and identity Nostr signing RPC methods.
- FIPS gives nodes a stable mesh identity and private transport path, but repo
announcements and PRs should remain NIP-34 compatible on normal Nostr relays.
- DWN protocol registration exists and can be used later for local contribution
metadata/cache, but should not be required for the first public workflow.
## Protocol Basis
Use existing Nostr Git conventions rather than inventing an Archipelago-only
protocol:
- NIP-34 repository announcement events identify repositories with kind `30617`.
- NIP-34 repository state events publish branch/tag refs with kind `30618`.
- NIP-34 patches, pull requests, PR updates, issues, and status events use kinds
`1617`, `1618`, `1619`, `1621`, and `1630`-`1633`.
- `ngit` provides the `git-remote-nostr` helper for `nostr://` clone URLs and PR
branches.
- GRASP servers provide Git Smart HTTP storage while Nostr events remain the
authority for repository identity, refs, PRs, issues, and maintainer state.
Primary references:
- https://nips.nostr.com/34
- https://docs.rs/crate/ngit/latest/source/README.md
- https://ngit.dev/grasp/
## Recommended Architecture
### Apps
Create two first-party apps:
- `ngit`: CLI/runtime package containing `ngit` and `git-remote-nostr`.
- `archipelago-source`: web UI for cloning Archipelago source, viewing NIP-34
issues/PRs, opening branches, and submitting PR events.
The `archipelago-source` app should depend on `ngit`. It can also recommend
Gitea for users who want a conventional local web Git UI, but Gitea should not
be the source of truth for public contribution permissions.
### Contributor Onboarding
When the user installs `archipelago-source` from the registry:
1. Show a modal before first launch: "Contribute to Archipelago".
2. Explain that the app will use their Archipelago Nostr identity to clone and
sign contribution events.
3. Display the maintainer repository announcement, clone URL, maintainer npub,
and relay/GRASP endpoints.
4. Ask for consent to:
- fetch repository metadata from configured relays,
- clone source through `nostr://`,
- create local branches,
- sign NIP-34 issue/PR/comment events,
- push PR branches to approved GRASP servers.
5. Store approval per app origin, identity id, repository id, and relay set.
This should build on the existing NIP-07 app-launcher bridge, but use a more
specific permission scope than the generic sign-event approval.
### Identity And Permissions
Use four identity classes:
- `archipelago-maintainer`: an offline or tightly controlled Nostr key that
signs the canonical kind `30617` repo announcement and status/merge events.
- `archipelago-merge-maintainer`: one of the small set of maintainer npubs
allowed to advance canonical refs and publish valid merged/applied status.
- `archipelago-build`: release automation key for signed release artifacts and
CI status events. It must not have merge authority.
- `contributor`: user node or app-specific identity used for PRs, issues, and
comments.
Contributor rights:
- Clone the repository.
- Open issues.
- Push proposal branches using `pr/<npub>/<short-topic>` or `pr/<event-id>`.
- Publish NIP-34 PR/update/comment events.
- Rebase and update their own PR branch.
- Run local validation and attach status evidence.
Contributor restrictions:
- Cannot update `refs/heads/main` or release branches in canonical state.
- Cannot publish maintainer-valid merge/applied status.
- Cannot alter the canonical repository announcement.
- Cannot publish release catalog signatures.
Maintainer rights:
- Publish/update the canonical repo announcement.
- Publish canonical `refs/heads/main` state.
- Mark PRs merged/closed/draft via NIP-34 status events.
- Sign release tags and catalog updates.
Fork rights:
- Any contributor can create their own NIP-34 kind `30617` repository
announcement for a fork.
- Fork announcements should use the NIP-34 `u` tag to point back to the
canonical `archy` repository.
- The source app should make forking a first-class path: "Fork on Nostr", clone
the fork locally, push branches to the contributor's GRASP list, and open PRs
back to canonical Archipelago when they want review.
- Forks can have their own maintainer npubs, relays, policies, and release
cadence, but the app should clearly label them as forks unless signed by the
canonical maintainer set.
The GRASP server policy should enforce this by accepting pushes to maintainer
refs only when backed by signed maintainer state, while allowing contributor PR
refs from their own npubs.
## Repository Layout
Canonical repo announcement:
- repo id: `archy`
- display name: `Archipelago`
- clone URLs:
- `nostr://<maintainer-npub>/<relay-hint>/archy`
- `https://<grasp-host>/<maintainer-npub>/archy.git`
- relays:
- Archipelago-operated relay
- at least two public Nostr relays that support the event load
- GRASP servers:
- Archipelago-operated GRASP instance
- one public GRASP-compatible mirror
Keep the existing HTTP Git remote as a mirror during launch. The docs can
present `nostr://` as the preferred contribution path once the workflow is
proven.
## UI Requirements
The source app should provide:
- A first-run contribution modal with a real Archipelago source graphic, not a
generic text-only dialog.
- Current clone status and local path.
- Branch list, changed files, commit form, and push/open-PR flow.
- PR inbox, issue list, maintainer status, and relay health.
- Explicit identity indicator showing which npub will sign events.
- A merge rights indicator that clearly says contributors can propose changes
but cannot merge them.
- A fork flow that creates a user-owned NIP-34 repo announcement and remote,
then offers "Open PR to Archipelago" from any fork branch.
- Maintainer badges based only on pinned canonical maintainer npubs, not relay
metadata or server-side account names.
- Links to container docs, deployment docs, manifest spec, and open-source
readiness tasks.
## Backend Work
Add an RPC module for source contribution workflow:
- `source.repo-info`: returns canonical announcement, clone URL, relay set,
maintainer npubs, and local clone state.
- `source.ensure-ngit`: verifies the `ngit` app/runtime is installed.
- `source.clone`: clones or updates the local source checkout.
- `source.status`: returns branch, dirty files, ahead/behind, and PR state.
- `source.commit`: creates a local commit from selected files.
- `source.fork`: creates a contributor-owned NIP-34 fork announcement and local
remote.
- `source.open-pr`: pushes a PR branch and publishes a kind `1618` event.
- `source.update-pr`: updates the branch and publishes kind `1619`.
- `source.issue`: publishes a kind `1621` event.
Backend must shell out through a narrow command wrapper, never arbitrary user
commands. The wrapper should set an isolated working tree under
`/var/lib/archipelago/source/archy`, run as the Archipelago service user, and
deny operations outside that path.
## Security Model
- Never expose maintainer private keys to an Archipelago node.
- Prefer app-specific contributor identities over the node's default identity.
- Require per-action consent for first PR push, issue creation, and signing any
event that tags the canonical repository.
- Pin the canonical maintainer npub in the app manifest and backend config.
- Keep the canonical merge-maintainer allow list signed by the
`archipelago-maintainer` key; never infer merge rights from GRASP server
accounts.
- Verify the canonical kind `30617` event signature before displaying clone
instructions.
- Treat GRASP servers as untrusted storage; verify Git refs against signed
Nostr state.
- Do not use destructive git operations from the UI without an explicit modal.
- Store local clones and generated patches outside app container writable roots
unless the user exports them.
## MVP
1. Package `ngit` as a first-party app.
2. Stand up one Archipelago-operated GRASP server and one Nostr relay.
3. Publish sanitized fresh-history `archy` through `ngit init`.
4. Add a simple `archipelago-source` app that clones source and links out to the
preferred Nostr Git browser.
5. Add app-launcher consent scopes for repository-specific NIP-34 signing.
6. Allow issues and PR branch submission from contributor npubs.
7. Add a one-click fork flow that publishes a contributor-owned fork
announcement referencing canonical Archipelago.
8. Keep maintainer merge/status publication manual.
## Later
- Native PR review UI with file diffs and inline comments.
- CI status events signed by the build identity.
- FIPS-first source sync between trusted Archipelago nodes.
- Private prerelease repositories using NIP-42 allow lists and/or protected
events if the ecosystem support is mature enough.
- Multi-maintainer policy with threshold signatures or explicit maintainer-list
rotation events.
## Open Questions
- Which maintainer npub should become canonical for `archy`?
- Should contributor identities be node-default or app-specific by default?
- Which GRASP implementation should be deployed first: `ngit-grasp` or another
NIP-34/GRASP-compatible relay?
- Should the source app include a full web Git UI in v1, or launch Gitea/ngit
browser links for review while keeping signing/submission native?
- What exact license and contribution certificate should contributors accept
before submitting PR events?
docs/nostr-identity-import-plan.md
+82
View File
@@ -0,0 +1,82 @@
# Add an existing Nostr identity to the node — UX & implementation plan
**Status:** plan only (2026-07-16), no code. Companion research: `docs/nostr-signer-login-research.md`.
## Where it lives
The **Nostr Identities** screen (`Web5Identities.vue`, backed by `identity.list` /
`identity.create`). Today every identity is **seed-derived** (`identity_manager.rs`
derives ed25519 + nostr keys from the BIP-39 master seed at an index). "Add existing"
introduces a second class of identity: one whose key material comes from *outside* the
seed.
## Two import kinds (both needed, different guarantees)
1. **Full import (nsec)** — the node holds the secret key. The identity behaves exactly
like a seed-derived one (can sign in embedded apps, publish, encrypt). NOT covered by
seed backup — flag it visibly and include it in the encrypted node backup.
2. **Linked signer (npub only)** — the node stores just the public key; signing is
delegated to the user's own signer (browser extension NIP-07, or a NIP-46 remote
signer later). Zero key custody; some features (background publishing) unavailable —
the UI should badge what works.
## The UX (matching the house style)
**Entry point:** next to "Create identity" on Nostr Identities, an **"Add existing"**
glass-button. Opens a modal with three tabs (same tab pattern as the send/receive
modals):
1. **Browser extension** (default when `window.nostr` exists)
- One button: "Connect with extension". Flow: `getPublicKey()` → show the npub +
resolved profile (kind-0 fetched via the node's relays: avatar, name — instant
recognition) → "Add this identity".
- Creates a **linked signer** identity. A challenge signature
(`signEvent` on a throwaway event) proves key possession before adding — never add
an unverified npub as "yours".
2. **Secret key (nsec)**
- Paste field (masked, `nsec1…` or hex), inline validation + derived npub preview
with the same kind-0 profile card before confirming.
- Scary-clear copy: "Your key will be stored on this node, encrypted at rest. It is
NOT part of your seed backup — back it up separately." Confirm step requires the
profile card to load or an explicit "add anyway".
- Creates a **full** identity.
3. **Public key (npub)** — watch-only
- Paste an npub for a linked identity without any signer attached yet (useful to
reserve the profile, upgrade to extension/NIP-46 signing later).
**After adding:** the identity appears in the same grid with a small origin badge —
`seed` / `imported` / `linked` — and the imported profile picture/name pulled from
relays. Everything else (picker in apps, rename, avatar) behaves uniformly.
**Removal:** existing delete flow; for `imported` identities the confirm dialog warns
the key is destroyed unless exported first (offer "Export nsec" in the identity's detail
sheet, gated behind password re-entry).
## Backend work
- `identity_manager.rs`: identity records gain `origin: Seed { index } | Imported |
Linked`, optional `nostr_secret_hex` absent for Linked. Storage: reuse the existing
encrypted identity file; imported secrets included in node backup.
- New RPCs:
- `identity.import-nostr` `{ nsec | npub, name?, verify_sig? }` → validates, derives
npub, rejects duplicates (same pubkey as any existing identity), returns the new
identity.
- `identity.fetch-profile` `{ pubkey }` → kind-0 lookup via `nostr_relays.rs` for the
preview card (frontend could also do this, but the node already has relay plumbing
and avoids CORS).
- `identity.nostr-sign` (used by the iframe NIP-07 bridge): for `Linked` identities
return a typed error the bridge translates into "ask the user's extension instead" —
phase 2; phase 1 simply hides linked identities from the in-app signer picker.
## Demo mode
Mock `identity.import-nostr` + `identity.fetch-profile` in mock-backend.js (canned
profile: picture + name for any pasted npub) so the whole add-existing flow is
demoable without real relays.
## Phasing
1. **Phase 1 (small):** nsec + npub tabs, origin badges, backup inclusion, mock.
2. **Phase 2:** extension tab with possession-proof + kind-0 preview cards everywhere.
3. **Phase 3:** NIP-46 remote-signer identities + login integration (shares the QR
plumbing from the signer-login work).
docs/nostr-signer-login-research.md
+95
View File
@@ -0,0 +1,95 @@
# Sign in to the node with a Nostr signer — research & recommendation
**Status:** research only (2026-07-16), no code. Companion plan: `docs/nostr-identity-import-plan.md`.
## What's already in the tree (and what it isn't)
The IndeeHub "sign in with signer" work is the *inverse* of this feature: the node acts
as a NIP-07 **provider** for embedded iframe apps, signing with node-held keys
(`useNostrBridge.ts` postMessage bridge → `identity.nostr-sign` etc., picker UI in
`NostrIdentityPicker.vue`). It never verifies an external signer — but the UI patterns
(picker modal, QR rendering) and the backend crypto are reusable:
- **`nostr-sdk 0.44` is already a core dependency** (`nostr_handshake.rs` runs a real
relay client) — schnorr event verification and NIP-46 client support are essentially
free on the Rust side.
- Auth today is single-password + optional TOTP, and TOTP already uses a **two-step
login** (`auth.login` → `auth.login.totp`) — the exact slot where a parallel
`auth.login.nostr.*` path fits.
- The node can host its own relay (strfry app), and the frontend already bundles `qrcode`.
## Candidate flows, ranked by friction
### A. Browser extension (NIP-07) — lowest friction on desktop (2 clicks)
Login page shows "Sign in with extension" when `window.nostr` exists. Server issues a
random challenge → extension signs a **kind 22242** auth event carrying the challenge →
server verifies signature + challenge + `created_at` freshness + that the pubkey is
enrolled → normal session cookie. ~50 lines of frontend, ~80 lines of Rust. No relay
involved at all.
### B. QR scan with a mobile signer (NIP-46 `nostrconnect://`) — the headline UX (scan + 1 tap)
1. Backend generates an ephemeral client keypair and renders a
`nostrconnect://<pubkey>?relay=<url>&secret=<rand>&perms=sign_event:22242&name=Archipelago` QR.
2. User scans with **Amber** (Android reference signer; Aegis/Nowser also scan;
nsec.app is paste-based; Alby is *not* a NIP-46 signer).
3. Phone connects to the relay, acks the secret; backend requests one
`sign_event:22242` over the encrypted NIP-46 channel, verifies, issues the session.
**Key architectural choice:** make the **Rust backend the NIP-46 client** (rust-nostr's
`nostr-connect` crate), talking to the relay over localhost — the browser only polls our
own RPC for "signer connected". No websocket/mixed-content issues in the Vue app.
**Relay topology:** no public relay is required by the spec — and public relays often
rate-limit ephemeral NIP-46 traffic. The node's own strfry is the ideal relay (private,
LAN-fast); the QR should carry a relay URL derived from the Host the browser used
(LAN IP / Tailscale IP — not `.local`, which Android often can't resolve).
**One empirical blocker to test first: does Amber accept plain `ws://` LAN relays?**
(Self-signed `wss://` will likely fail cert validation.) If not, route `wss://` through
the existing nginx/HTTPS cert story.
### C. Remembered NIP-46 session (persisted bunker pointer) — zero-tap repeat logins
Same as B but persists the pairing so future logins auto-approve. Adds state,
revocation surface, and "bunker offline = silent hang" failure modes. **Defer** — B
re-scans in ~5 seconds anyway.
## Recommendation
Ship **A + B behind one "Sign in with Nostr" button**; skip C for now. Password (+TOTP)
stays the permanent fallback — exactly as the user proposed, the signer is enrolled in a
step *after* password creation, never instead of it. The verification core is one shared
Rust function (sig + challenge + freshness + enrolled-pubkey → session).
- **Onboarding:** after the password (and seed) steps, an optional "Connect a signer"
card: QR (nostrconnect) + "Use browser extension" + Skip. Success enrolls the npub as
a login key.
- **Settings (next to TOTP):** list enrolled npubs (added date + method), "Add npub"
(paste, becomes usable after a challenge-verify), "Connect another signer" (same
QR/extension modal), "Remove" (requires password confirm; removing the last npub never
locks the account — password always works).
- **Libraries:** hand-roll the 22242 event for NIP-07 (window.nostr is a browser global);
rust-nostr `nostr-connect` for NIP-46. Avoid the 2.4 MB `nostr-login` JS bundle —
wrong fit for a self-hosted box (defaults to public bunkers); it's UX prior art only.
## Security notes
- Only pubkeys enrolled **while authenticated** (or during onboarding) may log in —
a simple `login_npubs` list next to the TOTP data in `auth.rs`.
- Challenge: 32-byte random, single-use, 2–5 min TTL, `created_at` ±60 s, deleted on
first verify attempt; pin an origin/host tag. Rate-limit like password attempts.
- The `secret` in the nostrconnect URI is a bearer token — one QR per attempt, expires
with the challenge.
- Policy call: signer approval should count as the second factor for TOTP accounts
(possession of phone/extension key), so nostr login doesn't silently bypass TOTP.
## Open questions
1. Amber + `ws://` LAN relay — needs a 10-minute on-device test before committing.
2. Which relay URL to embed (LAN vs Tailscale vs onion) — derive from browser Host.
3. NIP-46 encryption: spec says NIP-44, some signers still NIP-04 — rust-nostr handles
both; verify against current Amber.
4. Track draft **NIP-97 "Login with Nostr"** (matches this UX exactly, unmerged) —
align, don't depend.
**Prior art:** no mainstream self-hosted node OS (Umbrel, Start9, Alby Hub) ships Nostr
QR login for its own UI — this would be genuinely differentiating, and every building
block is already in the tree.
docs/phase4-streaming-ecash-plan.md
+389
View File
@@ -0,0 +1,389 @@
# Phase 4+ — Paid swarm streaming & the IndeeHub "Archipelago" source
**Status:** PLAN / design (2026-06-17) · **Branch:** `agent-trust-wip` ·
**partly implemented — "not implemented" was stale.** The paid-serving half
landed on main: `core/archipelago/src/swarm/paid.rs` says in its own header that
it is "DHT distribution plan, Phase 4 step F", with `paid_alpn.rs` and
`payment.rs` alongside it, a `streaming::` module, and the
`streaming.list-services` / `configure-service` / `toggle-service` / `pay` /
`prepare-payment` RPCs. It is doubly default-off: the swarm needs the
`iroh-swarm` cargo feature plus `config.swarm_enabled`, and serving stays free
for everyone until the operator enables the `content-download` service. Check
those gates before assuming any step below is live or dead.
**Builds on:** `docs/dht-distribution-design.md` (Phases 0–3, swarm + Blossom), the
Phase 3 swarm work just landed (`swarm/`, `content_hash.rs`, `trust/`).
This plans three things the user asked for, in one coherent architecture:
1. **Pay sats (ecash) for transport** of streaming film data between nodes.
2. **Networking *through* nodes** — relaying/routing a stream via intermediate peers.
3. An **"Archipelago" content source in IndeeHub** that shows every film uploaded
to *backstage*, on every node running the IndeeHub app.
> ## Headline finding
> **Most of the primitives already exist.** This is ~80% integration glue, not
> greenfield. A full Cashu/ecash wallet, a metered streaming payment gate, a
> 4-tier transport layer, the iroh-blobs swarm (just added), signed Nostr
> advertisements, and the Ed25519 trust module are all already in the tree. The
> genuinely new code is: (a) a paid-serving hook on the iroh side, (b) a relay
> protocol, and (c) the IndeeHub film catalog + Archipelago-local API.
---
## 0. Inventory — what we can build on (all already in `core/archipelago/src`)
| Capability | Where | State |
| --- | --- | --- |
| **Cashu ecash wallet** (mint/melt/send/receive, BDHKE) | `wallet/ecash.rs`, `wallet/cashu.rs`, `wallet/mint_client.rs`, `wallet/bdhke.rs` | ✅ implemented |
| **Local mint** (Fedimint) backing the wallet | `apps/fedimint` (`http://127.0.0.1:8175`) | ✅ deployed |
| **Lightning** (invoices, pay, channels) for mint/melt | `api/rpc/lnd/*`, `container/lnd.rs`, `apps/lnd` | ✅ implemented |
| **Streaming payment gate** (accepts `cashuA` tokens, opens metered session) | `streaming/gate.rs` | ✅ implemented |
| **Metering & pricing** (sats per byte / ms / request; e.g. content-download = 1 sat/MB) | `streaming/meter.rs`, `streaming/pricing.rs`, `streaming/session.rs` | ✅ implemented |
| **Revenue/profit accounting** (incl. `StreamingRevenue` tx type) | `wallet/profits.rs` | ✅ implemented |
| **Paid-service discovery** on Nostr (kind 10021, TollGate TIP-01 shape) | `streaming/advertisement.rs` | ✅ implemented |
| **Content server** that verifies+receives payment before serving | `content_server.rs` (`verify_and_receive_payment()`) | ✅ implemented |
| **iroh-blobs swarm** (fetch content-addressed blobs from peers, verify, seed) | `swarm/` (`iroh-swarm` feature) | ✅ just added |
| **Signed seed adverts** (NIP-33 kind 30081, blake3→endpoint) | `swarm/seed_advert.rs` | ✅ just added |
| **BLAKE3 content addressing** | `content_hash.rs` | ✅ implemented |
| **Ed25519 trust / `did:key` / detached signatures** | `trust/` | ✅ implemented (anchor ceremony pending) |
| **4-tier transport** (Mesh > LAN > FIPS > Tor) + `last_transport` | `transport/*`, `fips/dial.rs` | ✅ implemented |
| **Node discovery + federation trust** (Trusted/Observer) | `nostr_handshake.rs`, `federation/*` | ✅ implemented |
What is **NOT** present and must be built:
- **A paid-serving hook on the iroh-blobs provider.** Today the swarm seeds to
anyone (`BlobsProtocol::new(&store, None)` — no authorization). To charge for
swarm bandwidth we need a per-request gate that consults `streaming/gate.rs`.
- **A relay protocol.** No "peer A asks peer B to forward traffic to peer C".
Transport is point-to-point; there is no multi-hop routing, TTL, or relay
accounting.
- **IndeeHub Archipelago catalog.** The shipped IndeeHub points at the external
`staging-api.indeehub.studio` + AWS S3/CloudFront. Nothing makes a film
uploaded on node A visible on node B. No *backstage* code exists yet.
---
## 1. Pay sats (ecash) for transport of streaming films
### Goal
When node B streams a film blob (an HLS `.ts` segment) *from* node A's swarm,
A earns sats for the bytes it serves — using the ecash gate that already meters
`content-download`.
### What exists vs. what's new
- ✅ The economic machinery is done: `streaming/pricing.rs` already ships a
`content-download` service priced per MB; `streaming/gate.rs` turns a `cashuA`
token into a metered session; `meter.rs` deducts bytes; `profits.rs` records
`StreamingRevenue`.
- ❌ The swarm serving path doesn't consult any of it. `IrohProvider::new`
spins up `BlobsProtocol` that answers every blob request unconditionally.
### Design — "paid swarm" as a gated blob protocol
The clean seam is the iroh-blobs **accept** side. Two viable shapes:
**(A) In-band gate via a custom ALPN (preferred).** Keep iroh-blobs for the raw
byte transfer but front it with a tiny request/grant exchange on a second ALPN
(`archy/paid-blobs/1`):
1. B wants `blake3:H`. It dials A's endpoint and sends `{want: H, token?: cashuA}`.
2. A calls `streaming::gate::check_gate("content-download", peer=B, bytes≈len(H), token)`.
- `PaymentRequired` → A replies with price + its accepted mints
(`streaming.list-mints`) and the sat amount; B mints/sends a `cashuA` and retries.
- `PaidAndAllowed` / `Allowed` (within existing session allotment) → A authorizes
the blob hash for this connection and hands off to iroh-blobs to stream it.
3. A meters served bytes via `meter::record_and_check` and records revenue.
**(B) Pre-paid session, then open serving.** B opens a metered session up front
(buys N MB of `content-download` allotment with one token), and A's blob protocol
checks "does this peer have remaining allotment?" before each blob. Simpler, fewer
round-trips, slightly looser accounting. Good first cut.
Recommend **(B) for v1** (least new protocol surface — reuses sessions verbatim),
graduating to **(A)** when we want per-blob price discovery.
### Free vs. paid policy (important)
- **OTA + app-catalog blobs stay FREE.** Charging for security updates is hostile
and breaks the "origin always wins" guarantee. Gating applies **only** to the
IndeeHub film scope (a per-blob or per-advert "monetized" flag).
- Trusted federation peers (`TrustLevel::Trusted`) can be configured to serve each
other free; payment is for untrusted/public swarm peers.
### Integration points
- **DONE (2026-06-17):** `swarm/paid.rs` — the accept-side gate. Builds the
iroh-blobs `EventSender` (intercept connect + GET, hard-disable `push`) and
authorizes each request through `streaming::gate::check_gate("content-download",
peer_endpoint, blob_size, None)`. Free when the service is disabled (default);
denies unpaid peers when enabled; fails OPEN on internal error. Wired into
`IrohProvider::new`; unit-tested. The Settings toggle the user just got drives it.
- Reuse: `streaming/gate.rs`, `meter.rs`, `session.rs`, `wallet/ecash.rs`,
`streaming/advertisement.rs` (advertise the node as a paid blob seeder).
- TODO (fetch side): `swarm::fetch_content_addressed` gains an optional
"willing-to-pay budget + token source" so a downloading node can auto-pay from
its ecash wallet up to a cap (opening a session via `streaming.pay`), then fall
back to origin if too expensive. This is where **cross-mint settlement (§2a)**
plugs in — the payer may need to swap into the seeder's accepted mint first.
---
## 2. Networking *through* nodes (relayed / routed streaming)
This is the largest genuinely-new piece. Two distinct meanings — both useful:
### 2a. iroh-native relays (cheap, already mostly free)
iroh 1.0 already hole-punches and falls back to **relay servers** for connectivity
when a direct QUIC path can't be established. So "streaming through a node that
can reach the seed when I can't" partly exists at the iroh layer. Action: run/seed
our **own** iroh relay(s) on the OVH/hub infrastructure and pin them in config, so
the swarm doesn't depend on n0's public relays. Low effort, high resilience.
### 2b. Application-level paid relay (the real gap)
"Node B pays node A to fetch a film from origin/swarm on B's behalf and forward it"
— useful when B is behind a censored/expensive link and A has good connectivity
(the beta-cellular-node scenario from memory). This needs a real protocol:
- **`relay.offer` advert** (Nostr kind 10021 with a `relay` tag + price/MB) — reuse
`streaming/advertisement.rs`; add a `relay-bandwidth` service to `pricing.rs`.
- **`relay.fetch` request** over the existing transport (`PeerRequest` in
`fips/dial.rs`): `{content: blake3:H | url, pay: cashuA}`. The relay runs the
normal `swarm::fetch_content_addressed` (swarm-assist, origin fallback), meters
the bytes through `streaming/gate`, and streams them back to the requester.
- **Accounting:** add a `RelayBytes` metric to `streaming/meter.rs` distinct from
origin `content-download`, so "relay provided" is tracked separately in
`profits.rs` (the doc already separates `routing_fees` from `streaming_revenue`).
- **Safety rails:** single-hop only for v1 (no A→B→C→D); TTL + loop guard before
any multi-hop; cap per-session bytes; only relay the **public film scope**, never
private user blobs or arbitrary URLs (prevent open-proxy abuse).
### Phasing for §2
1. Pin our own iroh relays (config only). — *days*
2. Single-hop paid `relay.fetch` for film blobs, gated by ecash. — *the core build*
3. Multi-hop routing + path discovery. — *deferred; only if single-hop proves out*
---
## 2a. Cross-mint ecash settlement — paying across *different* mints
**Problem (user, 2026-06-17):** payment must work when the payer and the seeder
use **different** mints — not only two nodes on the same Fedimint. A node holding
tokens on mint **A** must be able to pay a seeder that only accepts mint **B**,
automatically.
### Why this is mostly a generalization, not new crypto
The wallet already tracks proofs **per-mint**: `WalletData::balance_for_mint(url)`,
`select_proofs(url, amount)`, `add_proofs(url, proofs)` are all mint-scoped, and
`MintClient::new(url)` targets any mint. What's hardcoded is convenience: `mint_quote`
/ `melt_quote` / `mint_tokens` / `melt_tokens` always use the single home
`wallet.mint_url`. So the data model is multi-mint already; we add the *swap* and
parameterize the helpers by target mint.
### The swap primitive (Cashu/Fedimint settle over Lightning)
To move value **A → B**, both mints expose BOLT11 mint+melt quotes (already in
`mint_client.rs`), and Lightning bridges them:
1. `MintClient::new(B).mint_quote(amount)` → a BOLT11 invoice `inv_B` (pay it to get B tokens).
2. `MintClient::new(A).melt_quote(inv_B)` → cost in A tokens (`amount + fee_reserve`).
3. Select A proofs and `melt` them on A to pay `inv_B` over Lightning.
4. When `inv_B` settles, `MintClient::new(B).mint_tokens(quote_B)` → claim B tokens;
`wallet.add_proofs(B, …)`.
Net: value lands on B minus (A melt fee + LN routing + B mint fee). The node's LND
isn't strictly required — the mints' own LN gateways settle — but a healthy local
node/route improves success. Implementation = three thin `*_at(mint_url, …)`
variants of the existing helpers + one composer:
`swap_between_mints(data_dir, from, to, amount, max_fee_sats) -> Result<u64>`.
### Where the swap happens — two models
- **Payer-side swap (recommended default).** Before paying seeder S (whose
`accepted_mints` are advertised via `streaming.advertise` / the gate's
`PaymentRequired.pricing.accepted_mints`), the payer picks the cheapest path:
pay directly if it already holds a token on one of S's mints; otherwise
`swap_between_mints(A → S_mint)` then send a token denominated in S's mint. **S
never has to trust mint A** — it only ever receives its own mint's tokens. Clean.
- **Payee-side auto-consolidation (optional, more liberal).** S widens
`accepted_mints` to any mint it's willing to melt-swap from, accepts an A token,
then swaps A → home-mint in the background. Broader acceptance, but S briefly
carries mint-A counterparty risk.
A node can do both: advertise a broad accept list *and* have payers prefer
direct/cheap mints.
### Guardrails (these are the real design decisions)
- **Mint trust list.** Mints can be insolvent or rug. Only swap *into* / accept
mints on a configured allow-list (default: home mint + a small curated set, with
the local Fedimint always trusted). Surface this in the Settings UI alongside the
per-service pricing.
- **Fee/slippage cap.** Every swap costs sats. `max_fee_sats` (or a max %) refuses a
swap that would cost more than the content is worth; the payer then declines and
uses origin. Show the all-in cost (price + swap fee) before auto-paying.
- **Origin always wins.** If the LN swap fails (no route, mint offline, over
budget), fall back to the HTTP origin with no payment. A mint problem must never
block content.
- **Idempotency / crash-safety.** Persist in-flight swaps (`melt` quote id + `mint`
quote id) so a crash between "paid `inv_B`" and "claimed B tokens" resumes the
claim instead of double-paying. Reuse the wallet's tx log.
- **Liquidity.** Swaps need the mints to have inbound/outbound LN liquidity; cache
recent swap success per mint-pair and prefer routes that have worked.
### Phasing for §2a
1. `*_at(mint_url, …)` helpers + `swap_between_mints` + mint trust list + fee cap. — *the core*
2. Payer-side auto-swap in the payment builder (pick cheapest accepted mint). — *wires §1/§2 to it*
3. Idempotent resume + per-pair liquidity cache. — *hardening*
4. (Optional) payee-side auto-consolidation.
This keeps the headline promise intact: **pay anyone, on any trusted mint,
automatically — or fall back to free origin.**
---
## 3. IndeeHub "Archipelago" content source
### Goal
A new source tab inside the IndeeHub app, **"Archipelago"**, listing every film
uploaded to *backstage*, streamable on any node — independent of the external
`indeehub.studio` API.
### Today (from the research)
- IndeeHub frontend (Next.js) is built against `NEXT_PUBLIC_API_URL =
staging-api.indeehub.studio` and pulls media from AWS S3/CloudFront. It is
**not Archipelago-aware**. nginx proxies it at `/app/indeedhub/` and injects a
NIP-07 Nostr provider.
- A MinIO stack exists (`indeedhub-public` / `indeedhub-private` buckets); FFmpeg
produces HLS there. **No backstage upload UI/code exists yet.**
- The design doc's Phase 4 already describes the target: backstage → FFmpeg → HLS
→ each `.ts` is a BLAKE3 blob → signed Nostr "Blossom" catalog event → any node
resolves the content address and streams from the nearest holder; MinIO origin.
### Architecture — four pieces
**(i) Backstage upload + transcode (origin side).**
Minimal creator flow on a publisher node: upload master → FFmpeg → HLS
(`.m3u8` + `.ts`) into MinIO (reuse the existing `indeedhub-ffmpeg`/MinIO stack).
For each segment compute `blake3_hex` (`content_hash::blake3_hex`) and import it
into the iroh seed store (`IrohProvider::seed_and_advertise`, generalized beyond
releases). The playlist references segments by content hash.
**(ii) Signed film catalog on Nostr (the "Archipelago" source).**
Define a new addressable event — **kind 30082, `archy-film`** (sibling of the
30081 seed advert) — published by the publisher node, **signed via `trust/`**:
```jsonc
{
"title": "...", "creator_did": "did:key:z...", "duration_s": 5400,
"poster": "blake3:...", // poster image blob
"playlist": "blake3:...", // the .m3u8 (itself a blob)
"segments": ["blake3:...", ...], // ordered .ts segment hashes
"enc": { "scheme": "aes-128", "key_ref": "nip98" }, // see (iv)
"monetized": { "service": "content-download", "sats_per_mb": 1 } // optional
}
```
The signature uses `trust::sign_detached`; consumers verify with
`trust::verify_detached`. **Publisher trust:** films show in the Archipelago tab
only from publishers on the node's trusted/federation set (or a pinned
"Archipelago film-root" key, mirroring the release-root anchor concept). This is
the key that stops the shared catalog from being a spam vector.
**(iii) Archipelago-local film API (makes it appear on every node).**
New RPC + HTTP endpoints in `api/`:
- `film.catalog` / `GET /api/film-catalog` — query Nostr relays for kind-30082
events from trusted publishers, verify signatures, dedupe, return merged JSON.
Cache like `app_catalog.rs` does (mtime/TTL, atomic write).
- `GET /api/film/:blake3` — serve a segment: `swarm::fetch_content_addressed`
(swarm-assist → MinIO/OVH origin), BLAKE3-verified, with HTTP range support so
the player can seek. This is where §1 (paid serving) and §2 (relay) plug in.
- The IndeeHub frontend gets an **"Archipelago" source** that points at
`/api/film-catalog` instead of `indeehub.studio`. Cleanest: a small build/runtime
flag or an injected config (same nginx `sub_filter` mechanism already used to
inject the NIP-07 provider) that registers the Archipelago source alongside the
existing studio source — additive, not a replacement.
**(iv) Encryption / access (private films).**
Public films: plaintext segments, freely cacheable, swarm-distributable. Private
films: keep AES-128 HLS; **untrusted seeds cache only ciphertext** (they never see
plaintext), and the decryption key is delivered per-viewer via NIP-98 auth (the
mechanism IndeeHub already uses) or NIP-44 DM. Payment (§1) gates *bytes*; the
*key* gates *plaintext* — two independent locks. This lets us pay strangers to
seed encrypted blobs without leaking content.
### "On every node" — propagation
Propagation is **pull**, not push: every node's `film.catalog` periodically queries
the same Nostr relays (already configured for discovery) for trusted-publisher film
events. A film uploaded on node A is therefore visible on node B as soon as B
refreshes its catalog — exactly how `app_catalog.rs` already distributes app
updates fleet-wide. No central server; the relays carry only signed metadata, the
blobs flow peer-to-peer with MinIO/OVH as origin.
---
## 4. Suggested end-to-end phasing
| Step | Deliverable | Risk | Reuses |
| --- | --- | --- | --- |
| **A** | Generalize `seed_and_advertise` beyond releases → arbitrary public blob scope (films) | low | swarm/ |
| **B** | `film.catalog` RPC + signed kind-30082 events + trusted-publisher gating | low–med | trust/, app_catalog.rs pattern |
| **C** | `GET /api/film/:blake3` range-streaming via swarm-assist + MinIO origin | med | swarm/, content_server.rs |
| **D** | IndeeHub "Archipelago" source wired to the local API (additive) | med (frontend, external repo) | nginx sub_filter |
| **E** | Backstage: upload → FFmpeg → HLS → blob import + catalog publish | med | MinIO/ffmpeg stack |
| **F** | **DONE** — paid swarm serving (`swarm/paid.rs` gates the blob protocol via `streaming/gate`); free by default | med | streaming/* |
| **F2** | Cross-mint settlement (§2a): `swap_between_mints` + payer-side auto-swap + mint trust list + fee cap | med–high | wallet/ecash, mint_client, lnd |
| **G** | Pin our own iroh relays (config) | low | iroh |
| **H** | Single-hop paid `relay.fetch` for film blobs | high | transport/, streaming/* |
| **I** | Multi-hop routing | high / deferred | — |
A→E delivers "films on every node" with free volunteer seeding (the design-doc
vision). F→H layer the sats economy on top. I is genuinely future work.
> **Shipping directive (user, 2026-06-17):** the IndeeHub "Archipelago" change
> ships — after testing — as a **decoupled app-catalog update**, NOT a binary
> OTA. Publish the new IndeeHub image + bump `releases/app-catalog.json` so every
> node gets the per-app "Update" badge (the mechanism in
> `container/app_catalog.rs` / `package.check-updates`). Node-side API changes
> (steps B/C) that need the binary go through the normal OTA; the *app* (step D,
> the IndeeHub frontend image) goes through the app catalog. See memories
> `project_decoupled_app_updates` + `reference_indeehub_canonical_source`.
---
## 5. Open questions / decisions needed
1. **iroh-blobs authorization granularity.** ✅ **RESOLVED (2026-06-17 spike).**
iroh-blobs 0.103 exposes exactly the hook we need: `BlobsProtocol::new(&store,
Some(EventSender))`. With an `EventMask` set to intercept, the provider asks our
handler to authorize each request and we return `EventResult = Result<(),
AbortReason>`:
- `RequestMode::Intercept` / `InterceptLog` — per-blob-request allow/deny
(`Err(AbortReason::Permission)` denies, `Err(AbortReason::RateLimited)` defers).
- `ConnectMode::Intercept` — reject at the connection handshake (cheap pre-filter).
- `ThrottleMode::Intercept` — per-request throttle/meter hook for byte accounting.
- `RequestMode::Disabled` — hard-reject a whole request kind (e.g. disable `Push`
so peers can never write into our store).
→ **§1 shape (A) is the recommended path** (native, no fork): the accept-side
handler calls `streaming::gate::check_gate("content-download", peer_endpoint,
bytes, token)` and maps `PaymentRequired`/`InsufficientPayment` →
`Err(Permission)`, `Allowed`/`PaidAndAllowed` → `Ok(())`. Peer identity comes
from the `Connection`'s remote endpoint id. (See `iroh_blobs::provider::events`.)
2. **Film-publisher trust anchor.** One global "Archipelago film-root" key (curated
store, like release-root) vs. per-node trusted-publisher sets vs. both. Affects
spam resistance and who can publish to *everyone's* Archipelago tab.
3. **MinIO as origin across the fleet** — single canonical MinIO on the hub vs.
per-node MinIO with cross-seeding. The swarm makes per-node origin viable but
the *first* upload needs a home.
4. **IndeeHub frontend is an external repo** (`~/Projects/indeehub-frontend`,
built into `apps/indeedhub`). Adding an "Archipelago" source needs changes
there; scope whether it's a build-time source registration or a runtime-injected
config (preferred — keeps the node OS in control).
5. **Pricing defaults & free tier.** What's free (OTA, trusted peers, first N MB?)
vs. paid, and the default sats/MB. `pricing.json` already supports this; needs a
policy.
6. **Payment UX / auto-pay caps.** A downloading node auto-paying from its ecash
wallet needs a user-set ceiling and a "prefer free origin if peer wants > X"
rule, so streaming never silently drains the wallet.
---
## 6. Why this is tractable
The hard, slow-to-build substrate — an ecash wallet, a metered payment gate,
content addressing, a verifying swarm, signed discovery, a trust module, a
multi-transport stack — is **already in the tree and (for the swarm) just tested**.
The remaining work is wiring those together along the three axes above, with the
two new protocols (paid blob serving, single-hop relay) being the only substantial
net-new surface. Everything stays behind feature flags / opt-in config and obeys
the project's north star: **swarm-assist, origin always wins** — and now,
**free updates, optional paid films.**
docs/pine-voice-commands.md
+170
View File
@@ -0,0 +1,170 @@
# Pine voice commands — the "what can I say" book
Everything here is spoken to the speaker after the wake word: **"Hey Jarvis, …"**
How it decides who answers you:
- **Exact-ish phrases** (sections 1–4) are matched **locally on your node** — instant,
free, works with no internet and no API key.
- **Anything else** goes to **Claude ("Archy")**, which either calls the same node
tools behind the scenes (so loose phrasings still get real numbers) or just
answers the question. Needs the Anthropic API key that Pine seeds.
- **Mesh announcements** need nobody to say anything — the speaker pipes up on its
own when a mesh message arrives.
---
## 1. Bitcoin — block height (local, instant)
- "what's the block height"
- "what's the current block height"
- "what is the block height"
- "block height"
- "current block height"
- "how many blocks"
- "how many blocks are there"
## 2. Peers — bitcoin **and** mesh in one answer (local, instant)
The answer includes both your bitcoin peer count and your mesh peer count.
- "how many peers"
- "how many peers do I have"
- "how many peers is the node connected to"
- "peer count"
- "node peer count"
## 3. Sync status (local, instant)
Fully synced → it tells you the block it's synced to. Still syncing → the percent.
- "is the node synced"
- "is bitcoin synced"
- "is the node fully synced"
- "is bitcoin fully synced"
- "how synced is the node"
- "how synced is bitcoin"
- "sync status"
- "bitcoin sync status"
- "sync progress"
- "sync percentage"
## 4. Lightning balance (local, instant)
- "what's my lightning balance"
- "what is my lightning balance"
- "lightning balance"
- "how many sats do I have"
- "how many sats are in my wallet"
---
## 5. Same questions, said like a human (Claude routes to the node)
The point of the AI brain: you don't have to remember the magic words. All of
these end in the same real numbers as sections 1–4:
- "how tall is the chain right now"
- "what block are we on"
- "is my bitcoin thing done downloading yet"
- "how far along is the sync"
- "are we caught up with the blockchain"
- "how's my node doing"
- "is everything okay with the node"
- "how many people is my node talking to"
- "is anyone connected to my node"
- "am I rich in lightning"
- "how much money is in my lightning wallet"
- "do I have any sats"
- "what's my node's status"
## 6. Mesh
**Hands-free announcements** — when a mesh text arrives, the speaker announces it
by itself: *"New mesh message from ⟨sender⟩: ⟨text⟩"*. Nothing to say; just have
someone send you one.
**Asking about the mesh:**
- "how many peers" — the local answer already includes mesh peers
- "how many mesh peers do I have"
- "am I connected to the mesh"
- "what was the last mesh message"
- "who sent the last mesh message"
- "read me the latest mesh message"
- "did I get any mesh messages"
(The last-message questions go through Claude reading the mesh sensor — phrasing
is free-form.)
## 7. Ask the AI anything
Short spoken answers, one or two sentences, no robot-reading-markdown. A sampler
by mood:
**Bitcoin & lightning, explained**
- "what actually happens when a block is mined"
- "explain the halving like I'm five"
- "what's the difference between on-chain and lightning"
- "why do confirmations matter"
- "what's a mempool"
- "is it normal for sync to take days"
**Everyday brain**
- "why is the sky blue"
- "how long do I boil an egg"
- "what can I cook with eggs and spinach"
- "what's 15 percent of 84"
- "how many ounces in a kilo"
- "what's 21 million divided by 8 billion"
- "how do you say good morning in Portuguese"
- "give me a word that rhymes with orange"
**Fun**
- "tell me a joke"
- "tell me a bitcoin joke"
- "give me a fun fact"
- "tell me a two-sentence scary story"
- "settle an argument: is a hotdog a sandwich"
**Advice-ish**
- "what should I name my node"
- "give me one tip for keeping my seed phrase safe"
- "what's a good way to explain my node to my mum"
Follow-ups work conversationally — ask something, then "and why is that?" without
re-explaining yourself.
## 8. Built-in assistant basics (Home Assistant, local)
- "what time is it"
- "what's the date today"
- "set a timer for 5 minutes" / "cancel the timer" / "how long is left on the
timer" — *timer support depends on the PineVoice satellite build; try it once
and you'll know.*
- "nevermind" / "cancel" — bail out of a listening session.
## 9. Smart home (only if you've got devices in Home Assistant)
Pine rides on Home Assistant Assist, so if you ever add exposed devices
(lights, plugs, sensors), the standard grammar lights up automatically:
- "turn on the living room light" / "turn off everything"
- "is the front door locked"
- "what's the temperature inside"
No devices → these politely fail; nothing to test today.
## 10. Known not-to-work (yet) — don't burn time on these
- **Sending** a mesh message by voice ("tell Bob I'm on my way") — receive/announce
only, for now.
- Controlling the node by voice ("restart bitcoin", "install an app") — read-only
on purpose.
- Long memory across sessions — each conversation is fresh.
---
## If something misbehaves
Say exactly what you said, what it answered (or didn't), and roughly when — the
node keeps logs of every pipeline run and it's usually a one-look diagnosis.
docs/quadlet-compilation.md
+126
View File
@@ -0,0 +1,126 @@
# Manifest → Quadlet unit
How an app manifest becomes a Podman [Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html)
`.container` unit that systemd owns, where the unit lands, and how to inspect one.
Source of truth: `core/archipelago/src/container/quadlet.rs`.
## Why Quadlet
Containers used to be fire-and-forget `tokio::spawn` blocks. If the daemon
crashed mid-spawn or the kernel reaped a parent cgroup, the container vanished
from `podman ps` and only a manual `podman run` brought it back. Quadlet removes
that whole class of failure: the unit lives on disk, **systemd owns
start/restart, and archipelago is just the provisioner**. This is the path that
runs the companion UI containers today (`archy-bitcoin-ui`, `archy-lnd-ui`,
`archy-electrs-ui`), and the validated path being flipped to default for apps.
## What gets generated
`Quadlet::from_manifest(manifest, name)` translates a manifest into a unit, and
`render()` produces the file. Every unit carries a header making clear it is not
hand-edited:
```ini
# Generated by archipelago. DO NOT EDIT.
# Edits are overwritten on the next reconcile.
[Unit]
Description=<app description>
After=network-online.target
Wants=network-online.target
Requires=<dependency>.service # one per declared dependency
After=<dependency>.service
[Container]
ContainerName=<name>
Image=<image ref>
Pull=never # image must be present locally already
Network=<host | pasta | slirp4netns | bridge name>
User=<uid> # when the manifest pins one
DropCapability=ALL # security default
AddCapability=<cap> # only capabilities the manifest opts into
PublishPort=<bind>:<host>:<container>/<proto>
Environment=<KEY>=<value> # non-secret env only
Secret=<secret_name>,type=env,target=<KEY> # secrets by REFERENCE, never value
Volume=<source>:<target><opts>
ReadOnly=true # when security.readonly_root
NoNewPrivileges=true # when security.no_new_privileges
HealthCmd=<cmd> # from the health_check block
[Service]
TimeoutStartSec=0
Restart=<always | on-failure> # from the restart policy
RestartSec=10 # 10s backoff caps a crash loop
[Install]
WantedBy=default.target
```
Two things to note in that mapping:
- **Secrets go in by reference, never by value.** A `secret_env` entry renders as
`Secret=<name>,type=env,target=<KEY>`, so podman injects the value at run time
from the node's secret store. The plaintext never appears in the unit file. See
[App secrets](secrets.md).
- **`Pull=never` is deliberate.** The provisioner does not pull images from here;
the image must already be local (pre-pulled or built). A missing image surfaces
immediately instead of retrying silently behind systemd's restart loop.
- **`PublishPort` is dropped entirely under `Network=host`.** Podman rejects the
combination and the container crash-loops on exit 125, so declared ports are
omitted rather than rendered. With host networking the container is already on
the host's ports; a manifest that declares both is not an error, the mapping is
just silently unnecessary.
## Where units land
Rootless, per-user, under the archipelago service user (uid 1000, with linger
enabled so the units run without an active login):
```
~/.config/containers/systemd/<name>.container
```
Quadlet's systemd generator translates `<name>.container` into a
`<name>.service` unit at **daemon-reload** time. Everything is `systemctl --user`
— the system bus is never touched from this path.
## Lifecycle: render → write → enable → disable
The module does four things and nothing else:
1. **render** — manifest → unit text (above).
2. **write** — `tempfile + rename` so a partially-written unit is never visible to
systemd, and `write_if_changed` compares bytes first: if the rendered unit
matches what is on disk, nothing is touched — no daemon-reload, no restart
cascade. This is what makes a reconcile tick cheap and non-disruptive.
3. **enable** — `daemon-reload` then start the `.service`.
4. **disable** — stop and remove.
## Inspecting a unit
Run these **as the archipelago service user** (the units are in its user bus):
```bash
# the generated unit
cat ~/.config/containers/systemd/archy-bitcoin-ui.container
# what systemd made of it
systemctl --user cat archy-bitcoin-ui.service
systemctl --user status archy-bitcoin-ui.service
journalctl --user -u archy-bitcoin-ui.service
# after editing a unit by hand for debugging (it will be overwritten on reconcile)
systemctl --user daemon-reload
```
Because the unit is regenerated on every reconcile, the way to change a
container's shape is to change its **manifest** (and, for a catalog-covered app,
regenerate and re-sign the catalog), never to edit the `.container` file — the
`DO NOT EDIT` header is literal.
## Related
- [Container lifecycle](container-lifecycle.md) — the reconciler that drives this
- [App Manifest Specification](app-manifest-spec.md) — the manifest fields mapped above
- [App secrets](secrets.md) — how `Secret=` references resolve
- [ADR-001: Podman over Docker](adr/001-podman-over-docker.md)
docs/registry-manifest-design.md
+163
View File
@@ -0,0 +1,163 @@
# Registry-Distributed App Manifests — Design
**Status:** implemented — Phases 1–3 shipped (schema + catalog-wins overlay,
signed publisher generator with embedded manifests for all apps, immich
end-to-end via `install_stack_via_orchestrator`); Phases 4–5 (build-context
apps content-addressed, drop `apps/` from OTA) remain open. Updated 2026-07-08.
**Goal (north-star):** every app installs from a manifest distributed via the
signed app-catalog on the registry — **no OS-level code reliance, no
OTA-shipped disk manifest required**. Rootless, signed, robust, reboot-survivable.
See also: [`docs/dht-distribution-design.md`](dht-distribution-design.md) (this is
its "discovery/authenticity" layer).
---
## 1. Where we started (the pre-Phase-1 baseline)
This section is the problem statement the design was written against, kept for
context. **It no longer describes the running system** — Phases 1–3 shipped, so
see "Where we are now" below.
Two distinct mechanisms, only one of which was registry-distributed:
| Thing | Source | Reaches node via | Carried |
|-------|--------|------------------|---------|
| `apps/*/manifest.yml` | repo working tree | **OTA**: `self-update.sh` rsyncs `apps/ → /opt/archipelago/apps/` | full manifest (the orchestrator's real source of truth) |
| `app-catalog.json` | `releases/app-catalog.json` | **registry HTTP fetch**, hourly, **signed** (`app_catalog::refresh_catalog`) | version + image override only |
### Where we are now
`releases/app-catalog.json` carries 66 entries, and 56 of them embed a full
`manifest` block — one for every `apps/*/manifest.yml` in the tree. So the
"catalog carries an image override only" gap below is closed for image-only
apps; what remains is build-context apps (Phase 4) and dropping `apps/` from the
OTA rsync (Phase 5).
- Orchestrator registry = in-memory `state.manifests: HashMap<app_id, LoadedManifest>`,
populated by `ProdContainerOrchestrator::load_manifests()` walking the disk dir.
`install(app_id)` → `loaded(app_id)` → "unknown app_id" if absent.
- `app_catalog.rs` is already: signed (release-root, `trust::verify_detached` over
the raw JSON), mirror-derived URLs, atomic cache at `<data_dir>/app-catalog.json`,
**forward-compatible** (no `deny_unknown_fields` — adding fields never breaks old nodes).
**Gap:** the manifest itself is never registry-distributed. Every app — btcpay,
grafana, immich — depends on an OTA-shipped disk file. That is the OS-level
reliance to eliminate.
## 2. Target
The signed catalog entry carries the **full manifest**. The orchestrator loads
manifests from the catalog cache (origin), falling back to disk only during the
migration window. Publishing an app = editing the catalog + signing + push — no
binary OTA, no disk manifest.
```
publisher: apps/*/manifest.yml ──generate──▶ releases/app-catalog.json (embeds + signs)
node: refresh_catalog() ──fetch+verify──▶ <data_dir>/app-catalog.json
load_manifests() ──merge──▶ state.manifests (catalog wins; disk = fallback)
install(app_id) ──▶ create the rootless container (Quadlet unit when
use_quadlet_backends is on; podman create+start otherwise)
```
## 3. Schema change (`app_catalog::AppCatalogEntry`)
Add one optional, forward-compatible field:
```rust
/// Full app manifest, embedded so the app installs from the registry alone
/// (no OTA-shipped disk file). Carried as the raw value the publisher signed;
/// deserialized into `AppManifest` at load time. Absent during migration =>
/// the node uses the disk manifest fallback.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub manifest: Option<serde_json::Value>,
```
Why `serde_json::Value`, not `AppManifest`:
- keeps the **signed preimage** intact (we verify over the raw JSON bytes; a typed
round-trip could drop/reorder unknown fields and break the signature),
- decouples catalog schema from manifest schema churn,
- deserialize + `validate()` happens at orchestrator load, exactly like `from_file`.
Authenticity is **free**: `fetch_one` already verifies the release-root signature
over the whole document, so an embedded manifest is covered by the same signature.
A present-but-bad signature is already a hard reject.
## 4. Orchestrator load path (`load_manifests`)
Extend (not replace) the disk walk:
1. Load disk manifests as today → `disk: HashMap<app_id, LoadedManifest>`.
2. Load catalog manifests from the cache: for each entry with `manifest: Some(v)`,
`serde_json::from_value::<AppManifest>(v)` then `validate()`; on success build a
`LoadedManifest { manifest, manifest_dir }`.
3. **Merge, catalog-wins**: a catalog manifest overrides the disk one for the same
`app_id`. Disk remains the fallback for apps the catalog doesn't cover (migration).
- Rationale: the registry is the authoritative origin; disk is the legacy
transport we're retiring. This matches `app_catalog`'s "catalog verdict is
authoritative when it covers the app" posture.
4. A catalog manifest that fails parse/validate is logged and skipped → disk
fallback used (one bad entry never blocks the fleet, same as the disk walk).
### `manifest_dir` for registry manifests — IMPLEMENTED
`LoadedManifest.manifest_dir` is used **only** in the `ResolvedSource::Build` branch
(relative `container.build.context` resolution — two call sites). Image-only apps
(`ResolvedSource::Pull`) never read it.
**Decision (phase 1, shipped):** keep `manifest_dir: PathBuf` (no `Option` ripple
through the codebase). A catalog manifest with a **build source is skipped** so its
disk manifest stays in effect — build contexts aren't registry-distributed until a
later phase (content-addressed, per the DHT plan). For an accepted (image-only)
catalog manifest, `manifest_dir` = the disk app dir if the app also exists on disk,
else a sentinel `<manifests_dir>/<app_id>` (never read for image-only apps).
This is enforced by `catalog_manifest_to_overlay(app_id, value) -> Option<AppManifest>`
in `prod_orchestrator.rs`, which returns `None` (→ disk fallback) for: unparseable
value, embedded-id ≠ catalog-key, failed `validate()`, or a build source.
## 5. Publishing (publish-side generator)
Add a generator (extend `create-release.sh` / a small `scripts/gen-app-catalog`):
- walk `apps/*/manifest.yml`, parse, embed each as the entry's `manifest` (JSON),
- keep `version`/`image`/`images` derived from the manifest for the badge path,
- write `releases/app-catalog.json`, then **sign** with the existing release-root
ceremony (`archipelago ceremony` / Phase 0 seed). Unsigned still accepted in the
migration window.
## 6. Migration & rollback
- **Backward compatible**: old nodes ignore the new `manifest` field (no
`deny_unknown_fields`) and keep using disk manifests.
- **Forward**: new nodes prefer catalog manifests, disk as fallback. Once the
catalog covers every app and is verified live, drop `apps/` from the OTA rsync.
- **Rollback**: delete `<data_dir>/app-catalog.json` (or revert the published
catalog) → nodes fall back to disk manifests. No data touched.
## 7. Phases
1. ✅ **Schema + load merge** (this design): `manifest` field, `load_manifests`
catalog-wins merge, unit tests (catalog overrides disk; bad catalog
manifest → disk fallback; absent → disk); `manifest_dir` stayed a plain
`PathBuf` (see §4). Image-only apps.
2. ✅ **Publisher generator + signing**: `releases/app-catalog.json` embeds a
full `manifest` block per app (all disk manifests covered) and is verified
via the release-root detached signature.
3. ✅ **First real app end-to-end**: immich installs via
`install_stack_via_orchestrator` with `generated_secrets`; the
`install_immich_stack` name survives only as an orchestrator-first wrapper.
4. ⏳ **Build-context apps**: content-addressed build contexts in the catalog (DHT
swarm fetch) so companions stop needing disk too.
5. ⏳ **Drop `apps/` from OTA** once coverage + live verification complete.
## 8. Open questions
- Do we embed manifests inline or reference them by content hash (BLAKE3) with a
separate signed blob? Inline is simplest for Phase 1; hashing aligns with the
DHT image-by-digest plan and keeps the catalog small. Lean inline now, revisit
at Phase 4 when build contexts (large) need addressing anyway.
- ~~`generated_files` with inline content (vs. source-dir) — already supported in
the manifest schema?~~ **Answered: yes.** `app.files[]` takes inline `content`
(with `{{HOST_IP}}` / `{{NETWORK_GATEWAY}}` / `{{secret:NAME}}` rendering), so
registry manifests already carry small rendered files inline and that disk
dependency is gone. See [`app-manifest-spec.md`](app-manifest-spec.md).
docs/secrets.md
+117
View File
@@ -0,0 +1,117 @@
# App secrets
How an app declares a secret, how Archipelago materialises it, and how it
reaches the container — with the rules a developer must not break.
The whole point: **an app never ships a credential.** It declares the *shape* of
the secrets it needs, and the node generates a fresh, per-install value that
never leaves the node and is never logged. Source of truth:
`core/archipelago/src/container/secrets.rs` and the manifest schema in
`core/container/src/manifest.rs`.
## The two halves
A secret has a producer and a consumer, and they are separate manifest fields:
- **`generated_secrets`** — *produce* a random value into a file.
- **`secret_env`** — *inject* a file's contents into the container as an env var.
An app can use either alone. A generated secret with no consumer is just a file
on the node; a `secret_env` with no matching `generated_secrets` reads a file
that some other component (or the daemon) is expected to have written.
## Declaring a generated secret
```yaml
container:
generated_secrets:
- name: btcpay-db-password
kind: hex16
- name: fedimint-gateway-hash
kind: bcrypt
```
`name` is a **bare filename** under the node's secrets directory
(`/var/lib/archipelago/secrets/`). It is validated at manifest-load time — no
`/`, no `..` — so a manifest cannot write outside that directory.
`kind` chooses how the value is produced. Each kind is deterministic in *shape*
(the orchestrator knows exactly which files it will create) but random in value:
| `kind` | Value | Files written | Use for |
|---------|-----------------------------------------|-----------------------------------|---------|
| `hex16` | 16 random bytes, lowercase hex (32 ch) | `<name>` | service passwords, API tokens |
| `hex32` | 32 random bytes, lowercase hex (64 ch) | `<name>` | longer keys/cookies |
| `base64`| 32 random bytes, standard base64 (44 ch)| `<name>` | services that base64-decode their key (e.g. netbird relay `authSecret`) |
| `bcrypt`| a random password **and** its bcrypt hash| `<name>` (hash) + `<name>.pw` (plaintext) | server configured with a hash, client needs the plaintext |
`bcrypt` is the only kind that writes two files: `<name>` holds the bcrypt hash a
server is configured with, and `<name>.pw` holds the plaintext for any client
that must authenticate against it. A `secret_env` injects whichever of the two it
references.
## Injecting a secret into the container
```yaml
container:
secret_env:
- key: BTCPAY_DB_PASS
secret_file: btcpay-db-password
```
At apply time the orchestrator reads `/var/lib/archipelago/secrets/<secret_file>`
and makes it available in the container as `<key>`. It does **not** do this by
adding `KEY=value` to the environment — that value would show up in
`podman inspect` output and, on the Quadlet path, as a plaintext `Environment=`
line in a unit file on disk. Instead the resolved pairs are registered as podman
secrets named `archy-env-<app-id>-<key>` and referenced by name, so the value
never lands in the manifest, a unit file, `podman inspect`, or a log line.
**Interpolation taints.** A plain `environment` entry that interpolates a secret
— e.g. BTCPay's `ConnectionString=...Password=${BTCPAY_DB_PASS}` — is treated as
secret-bearing itself and travels the same protected path, rather than being
left in the clear because it was declared under `environment`. So you can build
connection strings from secrets without leaking them.
## How materialisation works
`ensure_generated_secrets()` runs on **every install and reconcile tick**, before
`secret_env` is resolved. It is idempotent and self-healing:
1. **Fast path.** If every target file for a secret already exists, is readable
by the service user, and is non-empty, it is left untouched. A secret is
generated **once** and then persists across restarts, updates and reinstalls —
this is what makes credentials stable (migrations never regenerate a working
secret out from under a database).
2. **Self-heal.** A target file that exists but is unreadable or empty — e.g.
left root-owned by a botched earlier write — is removed and recreated, owned
by the service user. The unlink uses the secrets directory's own write bit, so
recovery needs no privilege escalation.
3. **Write.** New values are written through an atomic `0600` writer: a temp file
in the same directory, fsynced, then renamed over the target, so a reader never
sees a half-written secret and the file is only ever readable by its owner.
Because it runs every tick and no-ops when the secret is healthy, calling it is
always safe; there is no separate "provision secrets" step to forget.
## Rules a developer must not break
- **Never hardcode a credential**, in the manifest or in code, even as a
fallback. A shared fallback password means everyone holding a copy of the repo
holds that credential. Declare `generated_secrets` instead.
- **Never log a secret.** `secret_env` values and the files under the secrets
directory stay out of logs, error messages and status output.
- **One canonical name.** The orchestrator, first-boot script, reconcile path and
any deploy tooling must all reference a secret by the *same* filename. A
producer writing `<app>-password` while the consumer reads `<app>-hash` yields a
service that authenticates against a credential nothing generated.
- **Pick the encoding the service expects.** `hex*` and `base64` decode to
different bytes; a service that base64-decodes its configured key must be given
a `base64` secret, or it will run with the wrong key material.
## Related
- [App Manifest Specification](app-manifest-spec.md) — the full manifest schema
- [ADR-009: Manifest-Level Container Security](adr/009-manifest-container-security.md)
- [Entropy Enforcement (KEY-05)](security/KEY-05-ENTROPY-ENFORCEMENT.md) — why secret
generation draws from an explicitly-named CSPRNG
docs/security/BITCOIN-RPC-PROXY-EXPOSURE.md
+162
View File
@@ -0,0 +1,162 @@
# The Bitcoin RPC proxy that stayed open after it was fixed
**Status:** code fix committed (`f6b5245b`); on-node verification recorded below.
**Found:** 2026-08-02, a test node, while verifying `a05956c4` instead of assuming it.
**Severity:** critical on any affected node — unauthenticated control of Bitcoin Core RPC
through a proxy that injects the node's own credentials.
## Why this document exists
`a05956c4` closed two unauthenticated endpoints on the wallet UI ports. Its commit message
stated:
> The nginx template is `include_str!`'d and re-rendered on every reconcile pass, so this
> ships atomically with the binary.
That is true for most nodes and false for a specific, silent, and not-rare state. The half
that landed correctly (LND) made the half that did not (Bitcoin RPC) *harder* to notice,
because a spot check of the LND endpoint returns a clean `401` and reads as "patched".
## What was observed
Node running the fixed binary (installed 17:21, contains the new template — `auth_request`
present in the binary at 4 occurrences). All probes from the node's own LAN address, no
cookies, no credentials:
| Probe | Result |
|---|---|
| `GET http://192.0.2.240:18083/lnd-connect-info` | `401`, 24 bytes, `{"error":"Unauthorized"}` — **closed** |
| `POST http://192.0.2.240:8334/bitcoin-rpc/` (`getblockcount`) | `200` — `{"result":960774,"error":null}` — **OPEN** |
| `OPTIONS http://192.0.2.240:8334/bitcoin-rpc/` | `204` with `Access-Control-Allow-Origin: *` — **OPEN** |
The rendered config on disk, `/var/lib/archipelago/bitcoin-ui/nginx.conf`, was dated
**2026-06-30** — the pre-fix version, with no `auth_request` and with the wildcard CORS
header the fix removes.
## Root cause
Three facts have to be true at once, and on this node they were:
1. `bitcoin-ui` is listed in the node's durable `user-uninstalled` marker
(`/var/lib/archipelago/user-uninstalled.json`).
2. `reconcile_app` returns on that marker (`prod_orchestrator.rs:1956`) **before** reaching
`run_pre_start_hooks`, which is the only thing that renders the nginx config.
3. The container keeps running anyway, because it is owned by **systemd via a Quadlet
unit** — `archy-bitcoin-ui.service`, `active`, restarted 17:25 after the daemon restart —
not by the reconciler that is refusing to touch it.
So: *a container systemd keeps alive, that the orchestrator has stopped reconciling, never
receives a config fix shipped inside the binary.* The marker means "must stay removed", but
nothing enforces removal against systemd, and the orchestrator treats the marker as
permission to stop looking.
This is not a one-app accident. On the same node `archy-electrs-ui` is in the identical
state (uninstalled marker + active Quadlet unit + `Up 10 days`). It serves only a static
page with no credential-injecting proxy, so its exposure is low — but it would miss any
future config fix the same way.
## Why it matters beyond this node
An OTA carrying `a05956c4` would have closed the LND leak everywhere and silently failed to
close the Bitcoin RPC proxy on every node in this state — while making those nodes *look*
patched to exactly the check an operator would run first. That is the most misleading
possible outcome of shipping a security fix.
## The fix
`f6b5245b`: a container that is actually running is a live attack surface whatever a marker
says about it, so its security-relevant config is reconciled even behind the marker, and the
container is restarted so nginx loads it.
Deliberately narrow:
- Nothing is created, pulled, built, started or resurrected. The "must stay removed"
contract can only weaken for a container that is **already running**, which by definition
means it was never removed.
- A hook error is swallowed, not propagated — an app the user uninstalled must not be able
to fail the reconcile pass for every app after it.
- The pre-existing marker test passes unchanged; that is what proves the removal contract
survived. A new regression test pins the whole chain: stale conf in, gate present out,
container restarted, nothing created.
## What actually closed it on a test node — and what that does NOT prove
Sequence, from file mtimes, container start times and the daemon journal:
| Time (EDT) | Event |
|---|---|
| 18:33 | Probe: `POST /bitcoin-rpc/` → `200` with a real block height. Exposure confirmed live. |
| 18:36 | A **separate rebuild of bitcoin-ui**, done outside this work, rendered the fixed conf and recreated `archy-bitcoin-ui`. `:8334` closes here. |
| 19:06 | The binary carrying `f6b5245b` is installed and the daemon restarted. |
| 19:12 | Probe: `POST /bitcoin-rpc/` → `401`. `OPTIONS` now returns `Access-Control-Allow-Origin: http://192.0.2.240:8334`, not `*`. |
So the node is closed, and the fixed template is proven to work end to end on real
hardware — but **the reconcile fix itself was never exercised.** By the time it was
deployed, the state it repairs had already been cleared by the unrelated rebuild. The
`401` proves `a05956c4`'s template; it does not prove the delivery path `f6b5245b` adds.
That distinction is the whole point of this document, so it is recorded rather than
rounded off: `bitcoin-ui` is *still* in the node's `user-uninstalled` marker, meaning the
next time its config needs to change, this node depends on `f6b5245b` — untested — or on
someone happening to rebuild the app again.
Tracked as broken window 15 — **since closed by the controlled test below.**
## Proving the delivery path on real hardware
Run on a test node, 2026-08-02 20:00–20:03 EDT, with operator approval. The point was to
prove the thing the incidental rebuild had made unprovable: that **reconcile itself**
repairs this state, unaided.
The daemon was stopped first, so the reconciler could not repair the state before the
re-exposure had been confirmed — otherwise a passing probe would prove nothing about
which mechanism produced it.
| Step | Action | Observed |
|---|---|---|
| 1 | Install a faithfully stale conf (no `auth_request`, credential-injecting `proxy_pass`, `Allow-Origin: *`) and restart the container | — |
| 2 | Probe with no cookies | `POST /bitcoin-rpc/` → **`200`**, `{"result":960790}`; `Allow-Origin: *`. **Genuinely re-exposed** |
| 3 | Start the daemon (20:00:36) and touch nothing further | — |
| 4 | Reconcile pass at **20:02:19** | `bitcoin_ui: nginx.conf rendered auth_hash=51f2b5af`, then `WARN prod_orchestrator: rewrote config for a user-uninstalled app whose container is still RUNNING (systemd/Quadlet keeps it alive independently of reconcile) — restarting so it picks the new config up app_id=bitcoin-ui container=archy-bitcoin-ui` |
| 5 | Probe again | `POST /bitcoin-rpc/` → **`401`**; `Allow-Origin: http://192.0.2.240:8334` |
| 6 | Compare state | Conf **byte-identical** to the pre-test known-good; container healthy |
Step 2 is what makes steps 4–6 mean anything: without a confirmed `200`, the later `401`
would be consistent with the state never having been broken at all.
Both halves are now proven on hardware: `a05956c4`'s template (the gate works) and
`f6b5245b`'s delivery path (the gate arrives at a container the reconciler had been
skipping).
## Credential rotation — decided against, 2026-08-02
The operator's call, recorded here so it is not silently re-litigated: **no LND macaroon
rotation, and no Bitcoin RPC password rotation.** The reasoning was that there is no
evidence of exploitation and the vulnerability is being closed rather than lived with.
`scripts/security/rotate-lnd-macaroon.sh` stays in the tree as a tool. Its ordering
guard (refuses to rotate on a binary lacking the fix) remains the right shape for whenever
rotation is wanted — including for the Bitcoin RPC password, which has no equivalent tool
yet.
**Amended 2026-08-08.** This section said the script "has never rotated anything on any
node"; that is no longer true. A rotation was performed on a development node while
responding to the BTCPay Server advisory (that node had been running an affected
`btcpayserver:2.3.9`), and it exposed a gap the script did not cover: BTCPay's inline copy
of the macaroon was left stranded, so its Lightning payments failed silently while both
apps reported healthy. Rotation is now a first-class, password-confirmed dashboard action
that repairs that copy as part of the run — see
[`LND-MACAROON-ROTATION.md`](LND-MACAROON-ROTATION.md). The fleet decision recorded above
is unchanged: no fleet-wide rotation for this leak.
What this decision accepts: any macaroon or RPC password read through either hole before
it was closed stays valid. That is a deliberate, informed trade, not an oversight.
## Operator note
Deploying the fix rewrites the config and restarts `archy-bitcoin-ui` (a brief Bitcoin UI
interruption, nothing else). Any node that ever had `bitcoin-ui` uninstalled while its
Quadlet unit stayed active should be re-probed with the `POST /bitcoin-rpc/` check above —
a `401` is the pass condition. Treat the Bitcoin RPC password on any node that answered
`200` as known to anyone who could reach that port, and rotate it **after** the fix is
deployed, never before.
docs/security/KEY-05-ENTROPY-ENFORCEMENT.md
+685
View File
@@ -0,0 +1,685 @@
# KEY-05 — Entropy enforcement: per-site classification and mechanism record
**Requirement:** ROADMAP `KEY-05`.
**Supersedes:** backlog `R-13`. **Absorbs:** `R-05` (duplicate-`rand` visibility) and `R-09`
(CSPRNG-readiness record). **Resolves:** `F-10a` from the internal entropy and
seed-generation audit, which recorded raw match counts and **deliberately declined
to classify them**.
**Tree state this document was derived against:** `HEAD = c5a82cba` (2026-08-02).
**Update:** every `migrate` disposition in the table below has since been applied.
No `rand::random()` / `rand::thread_rng()` call remains in production `archipelago`
code — each draws through `entropy::draw_key_bytes` from a named `OsRng`, and
`core/clippy.toml` now bans both APIs, so a regression fails the build.
---
## Nothing here is broken today
`rand::random()` and `rand::thread_rng()` on the pinned `rand 0.8.5` resolve to
`ReseedingRng<ChaCha12Core, OsRng>` — seeded from `getrandom(2)`, reseeded every 64 KiB,
fork-protected. **Every value in the table below was drawn from a genuine CSPRNG.** This
document is not an incident record.
What KEY-05 removes is the *structural* shape: 41 call sites whose entropy backend is
selected by `Cargo.lock` resolution and crate feature flags rather than stated in
Archipelago's own source, with no compile error if that selection changes. That is the shape
("T1") that produced the 2026-07-30 COLDCARD entropy defect, here with key material, an AEAD
nonce and session credentials in the blast radius.
---
## Layer coverage
ROADMAP KEY-05 names five layers. None was dropped.
| Layer | What it is | Task that closes it | Status |
|---|---|---|---|
| (a) | Sealed key-generation RNG allowlist at the mnemonic seam; the false `impl rand::CryptoRng` promise retired | Task 2 | **Closed** — `entropy::KeyGenRng` sealed via a private `sealed::Sealed`; `seed.rs::generate_mnemonic_with` retyped to it; zero `impl rand::CryptoRng` blocks remain in the crate |
| (b) | Crate-wide compile-time ban on the defaulted entry points, enforced by the CI clippy step that already exists | Task 2 (dry run, uncommitted) → Task 6 (enable) | **NOT CLOSED** — see `## Clippy dry-run evidence` and `## What this does not close`. Blocked behind the Task 5 human checkpoint. |
| (c) | `cargo-deny` `bans` rule making the duplicate-`rand` split visible and change-detecting | Task 5 (decision) → Task 6 (implement) | **NOT CLOSED** — blocked on the Task 5 human decision |
| (d) | Degenerate-entropy runtime predicate | Task 2 (built) → Tasks 3/4 (applied) | **Closed** — `entropy::is_degenerate` / `entropy::draw_key_bytes`, applied at every `guarded: yes` row below |
| (e) | Durable CSPRNG-readiness record | Task 2 | **Closed** — `entropy::record_csprng_readiness`, called from `MasterSeed::generate` |
Layers (b) and (c) are the two that turn CI red for every agent on this shared repository if
they are enabled wrongly. Both are gated behind Task 5, a `gate="blocking-human"` checkpoint.
---
## Source precedence
The Phase 10 hardening work lists **F-07 / R-05**
and **F-10 / R-13** under `## Deferred Ideas`. KEY-05 was added to the ROADMAP on
**2026-08-02**, after that context was gathered, and explicitly absorbs R-05 and supersedes
R-13. The ROADMAP requirement is the later and governing artifact.
Two deferrals from that context **stand and were not executed**:
- **F-09 / R-12** — TOTP modulo bias. `totp.rs:305` is migrated for its *entropy source*
only. The `% charset.len()` selection is byte-for-byte unchanged. (The bias is presently
**zero**: the charset is 32 characters and 32 divides 256 exactly. R-12 is about the latent
bias if the charset ever changes length.)
- **F-11 / R-14** — `Math.random()` in `neode-ui`. No frontend file is touched by this plan.
---
## Enforcement blast radius — pinned mechanically
CI runs clippy with `working-directory: core` (`.github/workflows/ci.yml:19`) and
`cargo clippy --all-targets --all-features -- -D warnings` (`:35`). A `clippy.toml` at
`core/` therefore governs exactly the workspace members and no more.
`cargo metadata --no-deps --format-version 1` run from `core/`, package names only:
```
['archipelago', 'archipelago-container', 'archipelago-openwrt', 'archipelago-performance', 'archipelago-security']
```
`models`, `helpers` and `js-engine` **do not appear**. They are directories under `core/` but
are not workspace members (`core/Cargo.toml:4-10`), and are referenced only by each other.
**Stated limitation, not an omission.** `core/models/src/data_url.rs:163`
(`let random: [u8; 10] = rand::random();`) and `core/models/src/procedure_name.rs:32`
(`Some(format!("Properties-{}", rand::random::<u64>()))`) are real matches of the same shape
and are **outside KEY-05's reach**: they are outside the clippy build graph, so no
`disallowed-methods` entry can reach them, and they are outside this plan's `files_modified`.
Neither draws key material (a data-URL filename component and a procedure-name suffix), and
neither is compiled into the `archipelago` binary. They are recorded here so a future reader
does not mistake "43 classified" for "43 of 45 in the repository".
The other four workspace members (`container`, `openwrt`, `performance`, `security`) contain
**zero** matches — verified by
`grep -rn "rand::random\|thread_rng()" core/container core/openwrt core/performance core/security --include=*.rs`,
which returns nothing. So the ban, once enabled, is free for them.
---
## Per-site classification — all 43 matches
Source of the inventory, re-run against the working tree at `HEAD = c5a82cba` rather than
inherited from the plan or from F-10a:
```
grep -rn "rand::random\|thread_rng()" core/archipelago/src --include=*.rs
```
→ **43 lines across 16 files** (15 code files + `seed.rs`, whose two matches are comments).
`prod/test` is decided by whether the line falls inside that file's `#[cfg(test)] mod tests`
block; the block's start line is cited in the `## cfg(test) boundaries` section below and is
the evidence for every `test` verdict.
`guarded` is `yes` only where the drawn value is **key material or an AEAD nonce** *and* the
draw is **at least `MIN_GUARDED_LEN` = 12 bytes**. Every `no` carries its reason.
| Site | Expression | Kind | Becomes | Guarded | Disposition |
|---|---|---|---|---|---|
| `core/archipelago/src/storage_crypto.rs:39` | `let nonce_bytes: [u8; 12] = rand::random();` | production | ChaCha20-Poly1305 nonce for the message / mesh-contact at-rest stores; the 12-byte prefix of the `nonce ‖ ciphertext` envelope | **yes** (12 B, AEAD nonce — reuse is a keystream break) | migrate |
| `core/archipelago/src/credentials/store.rs:120` | `let nonce_bytes: [u8; 12] = rand::random();` | production | ChaCha20-Poly1305 nonce for the credential store, inside `encrypt_credentials` | **yes** (12 B, AEAD nonce) | migrate |
| `core/archipelago/src/session.rs:156` | `let token_bytes: [u8; 32] = rand::random();` | production | full authenticated session token (`SessionStore::create`) | **yes** (32 B, bearer credential) | migrate |
| `core/archipelago/src/session.rs:178` | `let token_bytes: [u8; 32] = rand::random();` | production | pending-TOTP session token (`create_pending`) | **yes** (32 B) | migrate |
| `core/archipelago/src/session.rs:254` | `let new_token_bytes: [u8; 32] = rand::random();` | production | rotated token on pending→full upgrade (`upgrade_to_full`) | **yes** (32 B) | migrate |
| `core/archipelago/src/session.rs:294` | `let new_token_bytes: [u8; 32] = rand::random();` | production | rotated session token (`rotate`) | **yes** (32 B) | migrate |
| `core/archipelago/src/session.rs:478` | `rand::random::<u64>()` | test (mod at `:471`) | uniquifying suffix in a temp-file path for `new_for_tests` | no — 8 B, a filename component, not key material | migrate |
| `core/archipelago/src/session.rs:489` | `rand::random::<u64>()` | test | temp-file path suffix | no — as above | migrate |
| `core/archipelago/src/session.rs:498` | `rand::random::<u64>()` | test | temp-file path suffix | no — as above | migrate |
| `core/archipelago/src/session.rs:511` | `rand::random::<u64>()` | test | temp-file path suffix | no — as above | migrate |
| `core/archipelago/src/session.rs:538` | `rand::random::<u64>()` | test | temp-file path suffix | no — as above | migrate |
| `core/archipelago/src/session.rs:569` | `rand::random::<u64>()` | test | temp-file path suffix | no — as above | migrate |
| `core/archipelago/src/session.rs:584` | `rand::random::<u64>()` | test | temp-file path suffix | no — as above | migrate |
| `core/archipelago/src/session.rs:602` | `rand::random::<u64>()` | test | temp-file path suffix | no — as above | migrate |
| `core/archipelago/src/session.rs:620` | `rand::random::<u64>()` | test | temp-file path suffix | no — as above | migrate |
| `core/archipelago/src/session.rs:651` | `rand::random::<u64>()` | test | temp-file path suffix | no — as above | migrate |
| `core/archipelago/src/session.rs:669` | `rand::random::<u64>()` | test | temp-file path suffix | no — as above | migrate |
| `core/archipelago/src/session.rs:685` | `rand::random::<u64>()` | test | temp-file path suffix | no — as above | migrate |
| `core/archipelago/src/device_tokens.rs:64` | `let token_bytes: [u8; 32] = rand::random();` | production | companion-device bearer token (`device_tokens::create`) | **yes** (32 B, bearer credential) | migrate |
| `core/archipelago/src/federation/invites.rs:42` | `rand::thread_rng().fill(&mut token_bytes);` | production | 16-byte federation invite token, hex-encoded into the invite payload | **yes** (16 B, unguessable-by-design token) | migrate |
| `core/archipelago/src/wallet/bdhke.rs:133` | `let random_bytes: [u8; 32] = rand::random();` | production | Cashu (NUT-00/NUT-10) proof secret — **genuine ecash key material** | **yes** (32 B) | migrate |
| `core/archipelago/src/wallet/bdhke.rs:139` | `let mut rng = rand::thread_rng();` → `SecretKey::new(&mut rng)` | production | Cashu blinding factor — a secp256k1 scalar; **genuine ecash key material** | no — **deliberate non-application**, see `## Deliberate non-applications of the guard` | migrate |
| `core/archipelago/src/wallet/bdhke.rs:169` | `let k = SecretKey::new(&mut rand::thread_rng());` | test (mod at `:144`) | throwaway scalar in `test_bdhke_flow` | no — test scalar, same rejection-sampling argument as `:139` | migrate |
| `core/archipelago/src/wallet/bdhke.rs:206` | `let k = SecretKey::new(&mut rand::thread_rng());` | test | throwaway scalar | no — as above | migrate |
| `core/archipelago/src/mesh/x3dh.rs:100` | `let spk_id: u32 = rand::random();` | production | `SignedPrekey.id` — a 4-byte **identifier**, not key material (the X25519 secret comes from `crypto::generate_x25519_ephemeral()` at `:99`) | no — 4 B, below `MIN_GUARDED_LEN`; an "all bytes identical" predicate false-positives on a 4-byte draw once in 2^24 | migrate |
| `core/archipelago/src/mesh/x3dh.rs:114` | `let otk_id: u32 = rand::random();` | production | `OneTimePrekey.id` — 4-byte identifier; the secret comes from `crypto::generate_x25519_ephemeral()` at `:113` | no — as above | migrate |
| `core/archipelago/src/container/secrets.rs:103` | `rand::thread_rng().fill_bytes(&mut buf);` | production | `random_hex(bytes)` — the manifest-declared `generated_secrets` (app passwords, API keys); the original F-10 | **yes when `bytes >= 12`** (the only production callers request 16/32); unguarded below the floor | migrate |
| `core/archipelago/src/container/secrets.rs:112` | `rand::thread_rng().fill_bytes(&mut buf);` | production | `random_base64(bytes)` — same, for services that base64-decode to raw bytes (e.g. netbird `encryptionKey`) | **yes when `bytes >= 12`** | migrate |
| `core/archipelago/src/api/rpc/package/install.rs:732` | `let secret: [u8; 32] = rand::random();` | production | SearXNG `server.secret_key` in `settings.yml` — signs SearXNG's own tokens | **yes** (32 B, app secret) | migrate |
| `core/archipelago/src/api/rpc/package/install.rs:1456` | `let salt_bytes: [u8; 16] = rand::random();` | production | `rpcauth=` salt for the Bitcoin Core RPC HMAC credential line | **yes** (16 B; the salt is half the credential — a degenerate salt weakens the stored `rpcauth` line) | migrate |
| `core/archipelago/src/bitcoin_rpc.rs:62` | `let bytes: [u8; 16] = rand::random();` | production (file has no `#[cfg(test)]` module) | the Bitcoin RPC **password** itself, hex-encoded to 32 chars | **yes** (16 B, credential) | migrate |
| `core/archipelago/src/api/rpc/package/pine_ha.rs:102` | `let raw: [u8; 32] = rand::random();` | production | Pine/Home-Assistant status bearer token, written 0600 under `NODE_SECRETS_DIR` | **yes** (32 B, bearer credential) | migrate |
| `core/archipelago/src/api/rpc/package/pine_ha.rs:490` | `"entry_id": id(rand::random()),` | production | Home Assistant config-entry **id** (16 B hex) — HA needs uniqueness only; not a credential and never authenticates anything | no — an identifier, not key material; fails the "key material or AEAD nonce" test | migrate |
| `core/archipelago/src/api/rpc/package/pine_ha.rs:507` | `"subentry_id": id(rand::random()),` | production | HA conversation subentry id | no — identifier, as above | migrate |
| `core/archipelago/src/api/rpc/package/pine_ha.rs:521` | `"subentry_id": id(rand::random()),` | production | HA `ai_task_data` subentry id | no — identifier, as above | migrate |
| `core/archipelago/src/api/rpc/package/pine_ha.rs:588` | `let entry_id: [u8; 16] = rand::random();` | production | HA `wyoming` config-entry id | no — identifier, as above | migrate |
| `core/archipelago/src/api/rpc/package/pine_ha.rs:665` | `let raw: [u8; 26] = rand::random();` | production | ULID-shaped HA id (26 Crockford-base32 chars) | no — identifier, as above | migrate |
| `core/archipelago/src/api/rpc/auth.rs:125` | `hex::encode(rand::random::<[u8; 2]>())` | production (file has no `#[cfg(test)]` module) | 4-hex-char suffix disambiguating default-named `companion-*` device entries in the UI | no — 2 B; an "all bytes identical" predicate false-positives once in 256, which would be worse than the defect it guards | migrate |
| `core/archipelago/src/fips/dial.rs:75` | `let id: u16 = rand::random();` | production | DNS query transaction id for the FIPS `_fips` lookup | no — 2 B, protocol identifier; same 1-in-256 false-positive argument | migrate |
| `core/archipelago/src/transport/chunking.rs:149` | `let message_id: u32 = rand::random();` | production | chunk-frame `message_id` correlating Reed-Solomon shards | no — 4 B, protocol identifier | migrate |
| `core/archipelago/src/totp.rs:305` | `let idx = (rand::random::<u8>() as usize) % charset.len();` | production | one character of a TOTP backup code (bcrypt-hashed before storage) | no — a single byte, far below the floor; **the `%` selection is R-12 and is deliberately untouched** | migrate |
| `core/archipelago/src/seed.rs:87` | `/// to \`&mut rand::thread_rng()\` *inside* the \`bip39\` crate, so the RNG backing every` | doc comment | nothing — prose in the F-02 remediation rationale | n/a | comment |
| `core/archipelago/src/seed.rs:681` | `// bip39's transitive \`rand::thread_rng()\` default, is the one consumed.` | line comment | nothing — prose inside `mnemonic_generation_uses_injected_rng` | n/a | comment |
**Disposition tally:** `migrate` = 41, `comment` = 2, `allow` = **0**.
**There are no `allow` rows.** Every test fixture migrates to `OsRng` as readily as production
code does, so no site needed an exemption, and consequently **no
`#[allow(clippy::disallowed_methods)]` attribute is introduced anywhere in the crate**. That
is the strongest available outcome for layer (b): the ban has no holes to audit.
### cfg(test) boundaries — the evidence for every prod/test verdict
| File | `#[cfg(test)] mod tests` begins | Consequence |
|---|---|---|
| `core/archipelago/src/session.rs` | `:471` | 4 of 16 matches are production; 12 are test fixtures |
| `core/archipelago/src/wallet/bdhke.rs` | `:144` | 2 production, 2 test |
| `core/archipelago/src/api/rpc/package/pine_ha.rs` | `:979` | all 6 matches are production |
| `core/archipelago/src/mesh/x3dh.rs` | `:292` | both matches production |
| `core/archipelago/src/container/secrets.rs` | `:275` | both matches production |
| `core/archipelago/src/api/rpc/package/install.rs` | `:2872` | both matches production |
| `core/archipelago/src/storage_crypto.rs` | `:79` | production |
| `core/archipelago/src/credentials/store.rs` | `:168` | production |
| `core/archipelago/src/device_tokens.rs` | `:112` | production |
| `core/archipelago/src/federation/invites.rs` | `:350` | production |
| `core/archipelago/src/totp.rs` | `:340` | production |
| `core/archipelago/src/transport/chunking.rs` | `:294` | production |
| `core/archipelago/src/fips/dial.rs` | `:683` | production |
| `core/archipelago/src/seed.rs` | `:513` | `:87` is above it (doc comment on a production fn); `:681` is inside it |
| `core/archipelago/src/bitcoin_rpc.rs` | **none** — the file has no `#[cfg(test)]` module at all (72 lines) | its single match is production by construction |
| `core/archipelago/src/api/rpc/auth.rs` | **none** — the file has no `#[cfg(test)]` module at all (332 lines) | its single match is production by construction |
---
## Two corrections to F-10a
F-10a recorded **raw match counts** and said so explicitly ("the full table in §F-10a"); it
declined to classify. These are resolutions of that refusal, not contradictions of it.
**1. `session.rs` is 4 production sites, not 16.** F-10a's headline table reports
`session.rs | 16` under a "Generates: session tokens" column. The evidence line is
`core/archipelago/src/session.rs:471` — `mod tests {` — above which lie exactly four matches
(`:156`, `:178`, `:254`, `:294`) and below which lie twelve. The twelve below are
`rand::random::<u64>()` used to uniquify a temp-file name in
`SessionStore::new_for_tests(std::env::temp_dir().join(format!("archipelago-sessions-test-{}.json", …)))`
— not tokens at all. (F-10a's own body text does carry the `4 prod + 12 test` split; the
correction is that the headline number is a raw grep count and must not be read as a
production-site count.)
**2. `mesh/x3dh.rs`'s two matches are prekey identifiers, not key material.** The evidence
lines are `core/archipelago/src/mesh/x3dh.rs:99` and `:113` —
`let (spk_secret, spk_public) = crypto::generate_x25519_ephemeral();` and
`let (otk_secret, otk_public) = crypto::generate_x25519_ephemeral();`. The X25519 secrets are
produced there; `:100` and `:114` draw only the `u32` `id` fields of `SignedPrekey` and
`OneTimePrekey`. They remain in scope — they are values that go on the wire — but the
characterisation "X3DH key agreement — key material" overstates these two specific lines.
(The internal audit has since been corrected; this section records the derivation
independently.)
---
## Sealing: what it prevents and what it does not
`core/archipelago/src/entropy.rs` declares a **private** module `sealed` containing a trait
`Sealed`, and
```rust
pub(crate) trait KeyGenRng: rand::RngCore + sealed::Sealed { … }
```
`sealed::Sealed` is nameable only from inside `entropy`, so `impl KeyGenRng for MyType`
written anywhere else cannot compile — the required supertrait bound is unsatisfiable and
unimplementable there.
**What it prevents.**
- No other module of this crate can add a member to the key-generation allowlist.
- No downstream crate can, either.
- `seed.rs::generate_mnemonic_with` is typed `R: KeyGenRng`, so the entropy source for the
entire master key hierarchy — node Ed25519 `did:key`, node Nostr key, FIPS mesh key,
per-identity keys, the BIP-84 wallet, LND aezeed entropy, and the fleet release-root
**signing** key — is constrained at the type level rather than by a doc comment.
**What it does not prevent, stated plainly.**
- **It does not prevent someone editing `entropy.rs` itself and adding a member.** Sealing
makes the allowlist a closed set that is *reviewable in one file*; it does not make it
immutable. That is the honest limit of the mechanism.
- **It does not prevent code calling an RNG directly, bypassing the seam entirely.** A new
`let k: [u8; 32] = rand::random();` in some unrelated module never mentions `KeyGenRng` and
sealing has nothing to say about it. **That gap is exactly what layer (b) covers.** The two
mechanisms are complementary, not redundant: (a) constrains what can drive a seam, (b)
constrains what can be written at all.
- **The "no downstream crate" clause is vacuous today.** `core/archipelago` is a
**binary-only** crate — `core/archipelago/Cargo.toml:8` declares `[[bin]]` with
`path = "src/main.rs"` and there is no `src/lib.rs`, so nothing depends on it and there are
no downstream crates to exclude. The clause is stated because it becomes load-bearing the
day this is split into a library, not because it is doing work now.
### The false `CryptoRng` promise is retired, not relocated
`seed.rs` previously carried `impl rand::CryptoRng for CountingRng` — a marker asserting that
an ascending counter is suitable for cryptographic use. `CryptoRng` has no compiler-checked
content: it is a promise any caller can make about any type, which is why the old bound
`R: rand::CryptoRng + rand::RngCore` was satisfiable by a counter in the first place.
KEY-05 **deletes** that impl rather than moving it. After this plan the crate contains **zero**
`impl rand::CryptoRng` blocks — verified comment-filtered, so prose describing the deletion can
neither satisfy nor invalidate the check:
```
$ grep -rn "impl rand::CryptoRng" core/archipelago/src --include=*.rs \
| grep -vE ':[0-9]+: *(//|///|\*)' | wc -l
0
```
There is now exactly one mechanism for the claim "this RNG may generate keys", and it is the
one the compiler verifies.
### Deviation from the plan: `KeyGenRng::GUARD_DRAWS`
The plan specified `draw_key_bytes` as unconditionally guarded *and* required
`generate_mnemonic_with` to route through it *and* required the pre-existing
`mnemonic_generation_uses_injected_rng` known-answer assertions to stay byte-identical. **Those
three requirements are mutually unsatisfiable**, and the contradiction is not incidental: that
test's RNG emits `0x00, 0x01, … 0x1f`, which *is* the ascending-counter pattern layer (d)
exists to reject. Guarding it makes the known-answer pin unrepresentable.
Resolution: `KeyGenRng` carries an associated constant
```rust
const GUARD_DRAWS: bool = true;
```
which `draw_key_bytes` consults. Three properties make this an acceptable seam rather than a
hole:
1. **It is inside the seal.** Only a type blessed in `entropy.rs` can set it, because only such
a type can implement `KeyGenRng` at all.
2. **The only member that sets it `false` is `#[cfg(test)]`-gated.** `testing::CountingRng` is
not compiled into the `archipelago` binary, so in a production build *every* allowlist
member is guarded. `sealed_allowlist_has_one_production_member` asserts
`<OsRng as KeyGenRng>::GUARD_DRAWS` is `true`.
3. **The guard is still observed tripping through `draw_key_bytes`**, not merely through the
pure predicate: `testing::ConstantRng` keeps the default `GUARD_DRAWS = true`, and
`draw_key_bytes_rejects_and_zeroizes_a_degenerate_draw` proves the full path — refusal,
variant, and buffer zeroization.
The alternative — dropping the known-answer pin to satisfy the guard — would have deleted the
crate's only proof that the RNG named at the call site is the one `bip39` consumes. That proof
is the entire point of the F-02 remediation this plan generalises.
---
## Degenerate-entropy predicate
`entropy::is_degenerate(&[u8]) -> Option<DegenerateEntropy>` recognises **exactly three**
patterns and nothing else:
| Variant | Predicate | Why this shape |
|---|---|---|
| `AllZero` | every byte is `0x00` | what a buffer looks like when the fill never happened |
| `AllIdentical` | every byte equals `bytes[0]` | an uninitialised constant fill; checked *after* `AllZero` so the reported variant is the more specific one |
| `Counter` | every adjacent pair satisfies `b[i+1] == b[i].wrapping_add(1)`, **or** every adjacent pair satisfies `b[i+1] == b[i].wrapping_sub(1)` | a counter PRNG standing in for a CSPRNG — the 2026-07-30 COLDCARD shape |
**Nothing heuristic.** No entropy estimator, no chi-squared, no "looks non-random" scoring. A
predicate whose false-positive rate cannot be computed in closed form cannot be argued safe,
and refusing genuine CSPRNG output on a key-generation path is strictly worse than the defect
being guarded against.
### False-positive bound, computed
For a uniform random `n`-byte buffer (`n ≥ 2`):
- `P(AllIdentical)` — the first byte is free, the remaining `n−1` must match:
`256^−(n−1) = 2^−8(n−1)`. This already includes `AllZero` as a subset.
- `P(Counter)` — the first byte is free, the remaining `n−1` are then determined; ascending
and descending are disjoint for `n ≥ 2` (they would require `+1 ≡ −1 (mod 256)`):
`2 · 2^−8(n−1)`.
- Union bound: `P(degenerate) ≤ 3 · 2^−8(n−1)`.
| `n` | Bound | As a probability |
|---|---|---|
| 2 | `3 · 2^−8` | **1.17 × 10⁻²** — about 1 in 85 |
| 4 | `3 · 2^−24` | 1.79 × 10⁻⁷ — about 1 in 5.6 million |
| **12** (`MIN_GUARDED_LEN`, the ChaCha20-Poly1305 nonce width) | `3 · 2^−88` | **9.7 × 10⁻²⁷** |
| **32** (session tokens, Cashu secrets, master-seed entropy) | `3 · 2^−248` | **6.6 × 10⁻⁷⁵** |
Over a deliberately generous lifetime budget of **10¹² guarded draws across the whole fleet,
forever**, the expected number of false rejections is **9.7 × 10⁻¹⁵ at n = 12** and
**6.6 × 10⁻⁶³ at n = 32**. A false stop is not a risk this predicate meaningfully carries at or
above the floor.
### Why twelve is the floor, and why it is a panic
The `n = 2` and `n = 4` rows are the argument. On a 2-byte draw the predicate fires on genuine
CSPRNG output about **once in 85** — vastly worse than the defect it guards against. That is why
`draw_key_bytes` **panics** rather than erroring on a buffer shorter than `MIN_GUARDED_LEN`:
calling the guard where its own bound does not hold is a programmer error, not an input
condition. A caller that legitimately needs fewer bytes draws from `OsRng` directly and
unguarded, and the classification table above records every such site with its reason.
Twelve is also exactly the ChaCha20-Poly1305 nonce width, so every AEAD nonce in the crate is
guardable *at* the floor rather than below it.
### On a trip: refuse, zeroize, do not retry
`draw_key_bytes` zeroizes the buffer, logs the variant and the buffer **length**, and returns
the error. **There is no retry.** A retry would paper over a genuinely broken RNG, which is
precisely the failure this layer exists to surface. The bytes themselves are never logged.
### Empirical companion
`degenerate_accepts_100k_osrng_draws` runs 100,000 consecutive 32-byte `OsRng` draws through
`is_degenerate` and asserts every one is accepted. Given the 6.6 × 10⁻⁷⁵ bound above, a single
rejection there means the predicate is wrong, not that the run was unlucky.
---
## CSPRNG-readiness ledger
**Path.** `<ARCHIPELAGO_DATA_DIR>/security/csprng-readiness.jsonl`, with
`ARCHIPELAGO_DATA_DIR` falling back to `/var/lib/archipelago` — the same resolution
`container/version_config.rs:36-39` uses. Resolving its own path is what lets layer (e) live
entirely inside `entropy.rs` **without** touching `bootstrap.rs` or `api/rpc/system/handlers.rs`,
both of which belong to plan `10-04`.
Deliberately **outside `identity/`**: the KEY-02 rootfs identity sweep and
`backup.restore-identity` operate on that directory wholesale, and neither should ever have to
reason about a file that is not key material.
**Schema.** One JSON object per line, append-only:
```json
{"v":1,"ts":"2026-08-02T18:04:11Z","ready":true,"event":"master-seed-generate"}
```
| Field | Meaning |
|---|---|
| `v` | schema version — exists so a future change does not orphan lines already on fleet nodes |
| `ts` | RFC 3339 UTC, second precision |
| `ready` | `true` / `false` / `null` — the verdict `seed.rs::kernel_csprng_ready()` computes via `getrandom(GRND_NONBLOCK)`; `null` on a non-Linux build or an unexpected errno |
| `event` | which generation event this verdict belongs to; `master-seed-generate` from `MasterSeed::generate` |
**No entropy, no key bytes, no seed material, no mnemonic word, and no hash of any of them is
ever written.** A readiness ledger that carried any of those would be a new place to steal a
key from, sitting one directory away from `identity/`. The record is a
`#[derive(serde::Serialize)]` struct with exactly four fields rather than a `json!` literal, so
the schema is a compile-time object that cannot drift.
`readiness_record_contains_no_mnemonic_words` proves this the strong way: it generates a real
mnemonic through `MasterSeed::generate()` against a temporary data dir and asserts the ledger's
alphabetic token set is a **subset of the fixed schema vocabulary** — from which "no mnemonic
word leaked" follows, since any leaked word would be a token outside that set. The test does
**not** do a naive substring search, and the reason is recorded in the test itself: `master`,
`seed` and `ready` are themselves BIP-39 English words, and `generate` contains the BIP-39 word
`era` as a substring (`gen-era-te`), so a naive check would be flaky *and* wrong in both
directions.
**Permissions.** Created `0o600` via `OpenOptions::mode`, matching the identity-blob pattern at
`seed.rs` and the generated-secret pattern at `container/secrets.rs:207`.
**Best-effort, by design.** Every failure path — cannot create the directory, cannot open the
file, cannot write, cannot serialise — logs at `warn` and returns. `ceremony.rs` generates a
master seed **offline**, on a machine that need not have `/var/lib/archipelago` at all. An
audit record that could fail key generation would be an availability defect introduced by a
security feature, which is not a trade worth making.
`readiness_record_survives_unwritable_data_dir` proves this with a real unwritable path (a
*file* where the data directory should be), not by inspection.
**What it closes.** `MasterSeed::generate` computed the readiness verdict, logged it into three
branches, and then discarded it. That discard is the whole of backlog **R-09**: a node could
never answer, after the fact, whether the kernel pool was seeded when its keys were born. It
can now.
## Deliberate non-applications of the guard
Layer (d) is applied at every `guarded: yes` row in the classification table. It is **not**
applied at the sites below. Each is recorded with its reason rather than silently omitted,
because a guard that is quietly skipped somewhere is worse than one that is openly bounded.
### 1. `wallet/bdhke.rs` — the Cashu blinding factor
`random_blinding_factor` migrates to an explicit `OsRng` but does **not** route through
`draw_key_bytes`. The draw is consumed by `secp256k1::SecretKey::new(&mut rng)`, which performs
**rejection sampling** into the curve group order — it draws, tests the candidate against the
order, and redraws on rejection. Intercepting the bytes to inspect them would mean
reimplementing that sampling in Archipelago, and getting rejection sampling subtly wrong on an
ecash key is a materially larger correctness risk than the guard buys against a hypothetical
future RNG rebinding.
The migration is still worth doing on its own: the *source* is now named, which is the whole of
layer (a)'s claim, and `blinding_factor_is_valid_and_varies` pins that successive factors are
valid, in-range secp256k1 scalars and differ — so a rebinding to a constant source fails there
rather than silently producing correlated ecash.
### 2. Short protocol identifiers — below `MIN_GUARDED_LEN`
| Site | Width | Why unguarded |
|---|---|---|
| `mesh/x3dh.rs:100`, `:114` | 4 B (`u32` prekey ids) | Below the floor. Not key material — the X25519 secrets come from `crypto::generate_x25519_ephemeral()`. |
| `transport/chunking.rs:149` | 4 B (`u32` message id) | Below the floor; a frame correlator. |
| `fips/dial.rs:75` | 2 B (`u16` DNS transaction id) | Below the floor; `AllIdentical` would false-positive **once in 256**. |
| `api/rpc/auth.rs:125` | 2 B (display-name suffix) | Below the floor; same 1-in-256 argument. The actual credential is minted by `device_tokens::create`, which **is** guarded. |
| `totp.rs:305` | 1 B | A single byte cannot be meaningfully inspected at all. |
The bound table in `## Degenerate-entropy predicate` is the argument: at two bytes the predicate
fires on genuine CSPRNG output about once in 85, which is a far worse defect than the one it
guards against. `draw_key_bytes` **panics** below the floor precisely so that this reasoning
cannot be bypassed by accident.
### 3. Non-credential identifiers at or above the floor
`api/rpc/package/pine_ha.rs:490`, `:507`, `:521`, `:588` (16-byte Home Assistant config-entry
and subentry ids) and `:665` (a 26-byte ULID-shaped id) are long enough to guard but are **not
key material or AEAD nonces**: Home Assistant requires only uniqueness from them and they
authenticate nothing. Guarding them would widen the guard's contract from "key material" to
"anything random", which makes the `guarded` column meaningless and puts a panic path on an app
config-seeding routine for no security gain. `pine_ha.rs:102` — the actual status **bearer
token** in the same file — *is* guarded, which is the distinction the column exists to record.
### 4. Where a degenerate draw aborts rather than propagating
`draw_key_bytes` returns a `Result`, and every site whose function already returns `Result`
propagates it: `storage_crypto::seal`, `credentials::encrypt_credentials`,
`device_tokens::create`, `federation::invites::create_invite`, the two `install.rs` sites, and
`seed::generate_mnemonic_with`. `pine_ha.rs:102` returns `Option` and degrades to `None` with a
`warn!`.
Four sites **abort** instead, and this is a deviation from the plan's "propagate rather than
unwrap" instruction that needs stating:
| Site | Why it cannot propagate |
|---|---|
| `session.rs::fresh_session_token` | `create`, `create_pending` and `rotate` return a bare `String`; their callers are in `api/rpc/mod.rs` and `api/rpc/totp.rs`, files plan 10-06 does not own. Widening them to `Result` is an API change this plan is not permitted to make. |
| `wallet/bdhke.rs::generate_secret` | returns `Vec<u8>` |
| `bitcoin_rpc.rs::generate_random_password` | returns `String`, and its caller is a `OnceCell` initialiser that also returns `String` |
| `container/secrets.rs::fill_secret_bytes` | `random_hex` / `random_base64` return `String` |
In every one of the four, the only two available behaviours are *emit a predictable credential*
or *refuse loudly*, and only the second is defensible. Reaching the branch means the kernel
CSPRNG returned 12–32 bytes that are all-zero, all-identical or a ±1 counter — the machine has
no usable entropy and must not be issuing credentials at all. None of the four can be driven by
attacker-supplied input: the predicate reads only `OsRng` output. The false-trip bound is
`3 · 2^−88` at 12 bytes and `3 · 2^−248` at 32.
Making these propagate properly is a worthwhile follow-up, but it is an API change across files
this plan does not own, so it is recorded here rather than performed.
## Clippy dry-run evidence
A lint config that is never observed to fail is indistinguishable from one that is
misconfigured, so the ban was **observed firing** rather than assumed. Run from `core/`,
2026-08-02, clippy 1.95.0.
### The ban fires
A single banned call was reintroduced into `entropy.rs` and clippy re-run:
```
warning: use of a disallowed method `rand::random`
--> archipelago/src/entropy.rs:675:5
|
675 | rand::random::<u64>()
| ^^^^^^^^^^^^^^^^^^^
|
= note: KEY-05: inherits its entropy backend from a dependency default instead of
stating it. Use rand::rngs::OsRng at the call site; for key material or AEAD
nonces >= 12 bytes use crate::entropy::draw_key_bytes. See
docs/security/KEY-05-ENTROPY-ENFORCEMENT.md
= note: `#[warn(clippy::disallowed_methods)]` on by default
```
The `reason` string reaches the developer at the point of failure, which is the whole
value of the `reason` field. Under the CI invocation's `-D warnings` this is an error.
### The reintroduction was reverted
After `git checkout core/archipelago/src/entropy.rs`, the residual count is **0**:
```
grep -rn "rand::random\|thread_rng()" core/archipelago/src --include=*.rs \
| grep -vE ':[0-9]+: *(//|///|\*)' | wc -l
0
```
### ⚠️ The enforcement channel is currently NOT green — a finding, not a side note
Layer (b) was designed to need no CI change because the Rust job already runs
`cargo clippy --all-targets --all-features -- -D warnings`. That reasoning is sound, but
the measured state of the tree is not:
**`cargo clippy --all-targets --all-features` emits 42 pre-existing warnings** on this
tree, unrelated to KEY-05 — `unused import: DeviceProbe`, `constant ELECTRUM is never
used`, `value assigned to last_err is never read`, plus ~39 style lints
(`redundant_guards`, `manual_map`, `needless_return`, `nonminimal_bool`,
`items_after_test_module`, and others). Under `-D warnings` **every one of them is
already an error**, so that CI step cannot currently pass for reasons that have nothing
to do with this plan.
Consequences, stated plainly:
1. KEY-05 layer (b) is **correctly configured and proven to fire**, but the gate it rides
on is red for other reasons. Until those 42 are cleared, a new banned RNG call would be
one error among many rather than the distinctive build-stopper the design intends.
2. This is **pre-existing and out of scope here** — clearing 42 lints across the crate is
its own change, and doing it immediately before an OTA would be poor sequencing.
3. It is recorded rather than quietly absorbed, because a reader would otherwise
reasonably conclude from "no CI change was needed" that the gate is live and effective.
It is live; it is not yet effective.
Recommended follow-up: a dedicated lint-clearing pass, after which layer (b) becomes a
real gate. Tracked in `## What this does not close`.
## cargo-deny evidence
Verified by the same standard — the rule was observed both passing and failing.
**A. The tree as it stands passes.** `cargo deny check bans` → `bans ok`, exit 0.
**B. The rule bites.** The plan offered two demonstrations; the second was used
(introducing a synthetic third `rand` was impractical without perturbing the lockfile).
The grandfather `[[bans.skip]]` entry was temporarily removed and the rule fired on the
existing pair, printing the full dependency trees for both versions and exiting **2**:
```
├ rand v0.8.5 (direct, + archipelago-security, bip39, mainline,
│ secp256k1, tungstenite 0.20.1)
├ rand v0.9.2 (totp-rs 5.7.0; tungstenite 0.26.2 via nostr-sdk)
bans FAILED
```
This also independently confirms F-07's account of where each version comes from.
**C. Restored.** The grandfather entry was put back and `cargo deny check bans` returns
`bans ok`, exit 0.
## cargo-deny policy
**Decision (checkpoint 10-06 Task 5, human-approved 2026-08-02): `bans` only. `advisories` NOT
enabled.** Pinned version: **cargo-deny 0.20.2**.
### Tool legitimacy (the required pre-step)
`cargo-deny` was verified on crates.io before being wired into CI:
| Check | Result |
|---|---|
| Publisher / repository | EmbarkStudios — `github.com/EmbarkStudios/cargo-deny`, resolves |
| Homepage | same as repository |
| Latest published version | `0.20.2`, published 2026-07-09 |
| Downloads | ~4,786,401 all-time; ~1,285,082 recent |
| Version pinned in CI | `0.20.2` |
Disposition: legitimate, actively maintained, plausible download history for a tool of its age.
### Why bans-only
R-05 / F-07 / KEY-05(c) asked for exactly one thing: fail the build when the duplicate `rand`
majors change, "so the split is visible rather than silent". That is what shipped.
The `advisories` section is a materially larger, separate commitment and was declined **for now**,
with the cost stated rather than glossed: an advisories gate fails builds when a **new CVE is
published against an existing dependency, with no change to this repository**. On a tree where
several agents commit and push continuously, an unrelated upstream disclosure would block
everyone at an arbitrary hour, and the remediation is frequently a dependency bump that is itself
a phase-sized change — this repo pins `bip39` and `bitcoin` exactly, and F-07 already documents
why a `rand` bump is not casual. No break-glass procedure exists today. That is a policy call
about how the team wants to be interrupted, so it was taken by a human, not defaulted by a planner.
### Mechanism
`core/deny.toml` uses a global `multiple-versions = "allow"` with a per-crate
`[[bans.deny]] name = "rand", deny-multiple-versions = true`, plus a dated `[[bans.skip]]`
grandfather entry pinning `=0.9.2` exactly. The contract, independent of config keys:
- the tree **as it stands** passes;
- a **third** `rand` version, or a change to either member of the current pair, **fails**.
### CI wiring, and one deliberate deviation from the plan's suggestion
The plan anticipated the `EmbarkStudios/cargo-deny-action`. That action was inspected and
**not** used: it exposes **no input to pin the cargo-deny version**, and an unpinned
supply-chain checker is a contradiction in terms — it would reintroduce, at the CI layer, exactly
the "backend fixed by configuration rather than stated" failure shape this whole plan exists to
remove. Instead the CI step installs the tool from crates.io at an exact version
(`cargo install --locked cargo-deny --version 0.20.2`), which is also the source that was
legitimacy-checked above, and avoids adding a second, unvetted third-party action to the workflow.
Cost of this choice, stated honestly: `cargo install` is slower than a prebuilt-binary action on
a cold cache. The existing `actions-rust-lang/setup-rust-toolchain@v1` caching mitigates it.
## What this does not close
Recorded so that nothing here is mistaken for a stronger guarantee than it is.
- **F-07's advisory half remains OPEN.** Bans-only was selected; there is still no
dependency-advisory (CVE) gate in CI. This stays in the backlog as R-05's unfinished remainder,
and adopting it needs an agreed break-glass procedure first.
- **The two `rand` majors are still both in the graph.** This layer makes the split *visible and
change-detecting*; it does not unify it. Unifying means bumping exactly-pinned crypto
dependencies and is not in scope here.
- **F-09 / R-12 remains deferred.** `totp.rs` still selects its charset with `% charset.len()`.
The bias is presently **zero** (32 divides 256 exactly), and only the *entropy source* was
migrated. The selection algorithm was deliberately left untouched.
- **F-11 / R-14 remains deferred.**
- **`core/models` is outside the enforcement graph.** `cargo metadata --no-deps` confirms the
workspace members are `archipelago`, `archipelago-container`, `archipelago-openwrt`,
`archipelago-performance` and `archipelago-security`. `core/models/src/data_url.rs:163` and
`core/models/src/procedure_name.rs:32` are real matches of the same shape that **no
`disallowed-methods` entry can reach**. This is a stated limitation, not an omission.
- **Sealing does not prevent an edit to `entropy.rs` itself.** The allowlist is sealed against
*other modules* adding a member; anyone editing `entropy.rs` can still add one. The mechanism
raises the act from an invisible default to a deliberate, reviewable change to a file whose
entire purpose is this guarantee — that is the honest claim, and it is not "impossible".
- **Mnemonics generated before this change came from the previous source.** That source was, and
remains, `getrandom(2)`-backed on the pinned `rand 0.8.5` — so nothing already generated is
suspect. This plan removes a *future* failure mode; it is not a remediation of past key material,
and no re-generation is implied or required.
- **Layer (b)'s gate is live but not yet effective.** The tree carries 42 pre-existing clippy
warnings that are already errors under the CI step's `-D warnings`, so that step cannot pass
today for reasons unrelated to KEY-05. The ban is correctly configured and proven to fire (see
`## Clippy dry-run evidence`), but it needs a dedicated lint-clearing pass before a new banned
RNG call stands out as the distinctive build-stopper the design intends. Out of scope here.
- **The degenerate-entropy predicate is not a health check for the kernel CSPRNG.** It rejects
three specific catastrophic shapes at the moment of a draw. It cannot detect a subtly-biased or
backdoored generator, and it is not evidence that one is absent.
docs/security/LND-MACAROON-ROTATION.md
+191
View File
@@ -0,0 +1,191 @@
# Rotating this node's Lightning credentials
A Lightning macaroon is a **bearer token**: whoever holds one can spend from the
node's wallet. There is no revocation list and no expiry. If a macaroon is ever
read by something you do not control — a leaked endpoint, a screenshot, a phone
that has since been lost, an app that ran a version with a published
vulnerability — that ability persists until the macaroons are rotated.
Rotation is therefore a **routine operator action**, not an emergency procedure.
Two paths do the same work:
| Path | Use when |
|---|---|
| **Dashboard** — Settings → *Lightning credentials* | Normal case. Password-confirmed, shows progress, repairs BTCPay for you. |
| **`scripts/security/rotate-lnd-macaroon.sh`** | No dashboard reachable, or you want a detect-only report. |
## What rotation actually does
LND derives every macaroon it issues from a root key in `macaroons.db`. Remove
that root key plus the issued `*.macaroon` files, restart, and LND mints a fresh
root key and a fresh set of macaroons when the wallet unlocks. Every macaroon
issued before that moment — including any an attacker holds — stops verifying.
## Why your funds and channels survive
Macaroons are bearer tokens, not keys. Coins live in `wallet.db` and channel
state in `channel.db`; channels are secured by the node's identity and channel
keys, none of which are derived from the macaroon root key. Neither database is
opened, moved or deleted.
Both paths **prove** this rather than asserting it: they record the node's
identity pubkey and its channel census before rotating, and refuse to report
success if either differs afterwards.
Two details in that check are deliberate and should not be "tightened":
- **Channels are compared as a total, not as `num_active_channels`.** The active
count only counts channels whose peer is currently online, so it legitimately
dips for minutes after *any* restart while peers reconnect. Asserting on it
alone would abort a perfectly healthy rotation.
- **`wallet.db` is not compared byte-for-byte.** btcwallet records chain-sync
progress inside it, so the file changes on every start. Asserting byte-identity
would fire a frightening false alarm on a completely healthy rotation.
## What it never does
- No macaroon **content** reaches a response, an error, a log line, or the
progress feed the dashboard polls. Everything reported is a SHA-256 digest or a
byte count — enough to prove the material changed without disclosing it to
whoever is reading the screen.
- No path from "rotate my credentials" to "delete my wallet". LND's boot path
self-heals a wallet no candidate password can open by wiping and recreating it;
correct for an unattended boot, catastrophic here. Rotation unlocks through
`container::lnd::unlock_existing_wallet_no_wipe`, so a wallet whose password
this node does not hold surfaces as a **failed rotation** with the wallet
intact.
## Nothing else may touch LND mid-rotation
Between "stop LND" and "start LND" the rotation owns a stopped container whose
credential material is being deleted. Two background actors would step in there
unasked: the **health monitor** restarts any container it finds stopped, and the
**reconciler** starts one whose unit is enabled. Either brings LND back up
mid-deletion — and LND re-mints `macaroons.db` on unlock, so the deletion loop
would race a live process writing that file, or "succeed" against material that
had already been regenerated. The operator would be told they had rotated while
the old root key was still in service.
The rotation therefore holds `app_ops::op_lock("lnd")` for its whole duration.
That is the lock both actors already consult (`lifecycle_op_in_flight`, reached
in the health monitor via `lifecycle_op_covers_container`), and it also
serialises against the `package.start`/`stop`/`restart` workers, so an operator
hitting "Restart" on Lightning mid-rotation queues rather than interleaving. A
rotation requested while one of those is running fails fast with a short
explanation instead of waiting silently.
Deliberately **not** the `user-stopped` marker that `recreate_wallet_destructively`
uses for its own window: that marker is a file on disk, so a rotation that died
between marking and clearing would leave Lightning suppressed *permanently* —
fixable only by finding and editing JSON on the node. The lock guard releases
when it drops, on every path including a panic.
## The BTCPay coupling — the part that bites
**BTCPay Server keeps its own inline copy of the admin macaroon**, and it cannot
self-heal. LND's data directory is owned by its container's mapped uid, so BTCPay
cannot bind-mount the macaroon file (EACCES across the userns boundary). The
connection string therefore carries the macaroon as hex:
```
type=lnd-rest;server=https://lnd:8080/;macaroon=<hex>;certthumbprint=<hex>
```
delivered as the `btcpay-lnd-connection` secret file. Rotate the macaroons and
that copy becomes a dead credential. Nothing notices on its own, because the
daemon only regenerates this secret when LND's **TLS cert thumbprint** changes —
and macaroon rotation does not touch the cert.
The resulting state is the dangerous one: **BTCPay is up, LND is up, both report
healthy, and every Lightning invoice BTCPay tries to create fails.**
Repair needs two things, and one without the other is cosmetic:
1. **Rewrite the secret** (`container::lnd::rewrite_btcpay_lnd_connection_secret`).
This is what makes the change visible: `secret_env_hash` is derived from the
resolved secret contents, so a changed file reads as label drift on the
running container.
2. **Recreate the container.** `btcpay-server` is on the restart-sensitive list,
and the reconcile loop runs in `ExistingOnly` mode *always* — boot and
periodic alike — where env drift on a restart-sensitive app is detected and
then deliberately skipped. Rewriting the secret alone therefore changes
nothing that is running. Observed directly on a development node, once per
tick, for half an hour:
```
container drift detected during boot reconcile; leaving running
restart-sensitive app untouched app_id=btcpay-server
```
The dashboard path calls
`ContainerOrchestrator::mark_credential_rotated("btcpay-server")`, which is
the flag the drift check consults to override restart-sensitivity. It is the
same carve-out FED-07 added for the Fedimint gateway, and the reasoning is
identical: restart sensitivity protects apps that are *working*, and this one
is working only in appearance.
**The shell script cannot set that in-process flag**, so it does the equivalent
from outside: it deletes the secret (the daemon regenerates it within a tick),
then removes the `btcpay-server` container so the orchestrator's own
desired-state recovery rebuilds it around unchanged data. That recovery is what
makes this safe rather than a hand-rolled remove-and-run — it fires because the
app is still installed and was in the last running-containers snapshot. The
script then prints the commands to confirm it actually happened, because a
failure here is invisible.
## Slow nodes: the unlock budget
LND opens `channel.db`, `graph.db` and `wallet.db` before it serves the unlocker
at all, and on a busy node that is genuinely slow — **2m38s measured on a box
running 30 containers**. The unlock helper used to give up after ~60s, which on
such a node could never succeed.
That timeout was not a harmless retry. Reconcile records the post-start hook as
failed, restarts LND, and the slow database open starts over: a restart loop that
leaves the wallet permanently locked and every LND-dependent app (BTCPay's
internal node included) broken, on exactly the nodes least able to afford it.
The not-ready budget is now ~10 minutes (`UNLOCK_NOT_READY_ATTEMPTS`). Waiting
longer costs nothing, because a genuinely wrong password still exits on the first
pass through the candidate list — the `all_rejected` fast path is untouched.
## Verifying a rotation
The dashboard shows all of this. From a shell:
```bash
# 1. Fingerprint changed (digest only — never print the macaroon)
sudo sha256sum /var/lib/archipelago/lnd/data/chain/bitcoin/mainnet/admin.macaroon
# 2. Same node, same channels
podman exec lnd lncli --network=mainnet getinfo \
| python3 -c 'import json,sys; d=json.load(sys.stdin); print(d["identity_pubkey"], \
d["num_active_channels"] + d["num_inactive_channels"], d["num_pending_channels"])'
# 3. BTCPay is carrying the CURRENT macaroon, not the rotated-out one
CUR=$(sudo od -An -v -tx1 /var/lib/archipelago/lnd/data/chain/bitcoin/mainnet/admin.macaroon | tr -d ' \n')
SEC=$(sudo sed -n 's/.*macaroon=\([0-9a-f]*\).*/\1/p' /var/lib/archipelago/secrets/btcpay-lnd-connection)
[ "$CUR" = "$SEC" ] && echo "current" || echo "STALE — BTCPay's Lightning is broken"
# 4. BTCPay was actually recreated (a silent failure looks like success)
podman inspect btcpay-server --format '{{.Created}}'
```
Check 3 is the one people skip, and it is the one that fails.
## Afterwards
- **Re-pair every wallet app**, Zeus most importantly. Open the Lightning app in
the dashboard and scan the pairing QR again; it serves the new macaroon.
- **Delete the backup once re-pairing is done.** Both paths back the old material
up to `/var/lib/archipelago/lnd/macaroon-rotation-<stamp>` (0700) so a mistake
is recoverable. That directory holds the **old root key** and is still
sensitive: `sudo rm -rf <path>`.
## Related
- `docs/security/BITCOIN-RPC-PROXY-EXPOSURE.md` — the leak that first made
rotation necessary, and the operator decision not to rotate the fleet for it.
- `scripts/security/rotate-lnd-macaroon.sh` — the shell path, including its
ordering guard (it refuses to rotate on a binary that still leaks
`/lnd-connect-info`, since the new macaroon would leak within seconds).
docs/security/PSBT-SIGNING-ARCHITECTURE.md
+618
View File
@@ -0,0 +1,618 @@
# PSBT-First Signing Architecture
> ## ⚠️ Status update (2026-08-02): **§8 Phase 1 was superseded by deletion, not delivered**
>
> Phase 1 ("Descriptor watch-only read path", §8) planned to **rewrite**
> `handle_bitcoin_init_wallet_from_seed` so Bitcoin Core's wallet held only the xpub. That is not
> what happened. Under Phase 10 decision **D-07b**, the entire Bitcoin Core wallet path was
> **deleted**: `handle_bitcoin_init_wallet_from_seed` and its `bitcoin.init-wallet-from-seed`
> dispatch arm are gone. It had no caller, LND is the wallet the product drives, and the endpoint
> was authenticated *and* password-gated, so F-13 was key-at-rest duplication rather than an
> exposed endpoint.
>
> **Consequences for reading the rest of this document:**
>
> - **§0's "single highest-value change"** and **§2.1's invariant** now read against a code path
> that no longer exists. Their goal — the BIP-84 private key existing in exactly one place —
> is **achieved**, by removal rather than by conversion to watch-only.
> - **§1.1, §2.2, §3.1 and §7.3** describe a Core watch-only wallet and a wallet migration.
> **There is no such wallet and no migration was performed or is planned.**
> - **§3.1's key-origin requirement** still holds, but it now applies to the **PSBT** rather than
> to Archipelago-emitted descriptors, of which there are none left. `lnd.create-psbt` inspects
> and reports it (`psbt_key_origin_report`, `core/archipelago/src/api/rpc/lnd/wallet.rs`).
> - **§5 (LND) is unaffected and remains accurate**, including **§5.4's honesty table**, which is
> correct as written and unchanged.
>
> **Note:** the current signing-posture record is maintained internally. It records the
> deletion with its evidence, an honest per-step coverage map of the LND PSBT round trip, and the
> verdict on whether an external signer can sign a default node's PSBT today (it cannot: no fleet
> node is provisioned watch-only). Phases 2-7 below are unaffected as design targets.
> **Status: specification.** No implementation. This document defines a target architecture and
> a phased rollout that a future `/gsd-plan-phase` can consume directly. It deliberately
> contains no code, adds no dependencies, and changes no wallet or signing behaviour.
>
> **Companion document:** the internal entropy and seed-generation audit that
> motivated this spec. **Cross-linked design:**
> `docs/hardware-signer-design.md` — the exploratory TROPIC01 air-gapped signer, which this
> architecture treats as the future *first-party* signer, not as a competing design.
**Provenance rules used throughout.** Every architectural claim is grounded in either (a) a
`file:line` from this tree, or (b) RESEARCH.md Part C
(which cites Bitcoin Core `doc/psbt.md`, `doc/descriptors.md`, `doc/multisig-tutorial.md`, the
Core 30.0 release notes, LND `docs/remote-signing.md` and `docs/psbt.md`). Anything from
neither is marked `[UNVERIFIED]`.
---
## 0. Why this document exists
The 2026-07-30 Coinkite COLDCARD entropy incident swept ~1,082 BTC from ~1,195 addresses. The
Archipelago-specific reading is in the audit; the design-relevant lesson is narrower and is the
organising principle of this spec:
> **T1's survivors were the users who took the *optional* extra step.** Users who rolled dice
> contributed ≥128 bits independently of the broken RNG and were not at risk. The safe path
> existed the whole time; it just was not the default.
Everything below follows from that. The safe path (watch-only + external signer + PSBT) must be
the **default** and must feel like the normal way to use Archipelago, not an expert mode buried
behind a warning. The hot wallet is retained, deliberately, as an explicitly-secondary tier —
because a safe path users route around is not a safe path.
**Where the tree stands today (important, and not what the target says).**
`core/archipelago/src/api/rpc/bitcoin.rs:161-294` already creates a **descriptor** wallet
(`createwallet ... descriptors=true`, `:207`) — which is the right foundation — but it passes
`disable_private_keys = false` (`:203`) and imports `wpkh(xprv/0/*)` and `wpkh(xprv/1/*)`
(`:229-231`), i.e. **the BIP-84 account extended *private* key is imported into Bitcoin Core's
`wallet.dat`.** The node's spending key therefore lives in two places: the daemon's Argon2 +
ChaCha20-Poly1305 envelope (`core/archipelago/src/seed.rs:238-269`) *and* Core's wallet
database. The code is careful with the string in memory (`bitcoin.rs:189`, zeroized at `:222`
and `:284`), but the key itself is persisted by Core. Closing that gap is Phase 1 of the
rollout in §8, and it is the single highest-value change in this document.
---
## 1. Target architecture
### 1.1 Watch-only descriptor wallet on the node
The node runs a Bitcoin Core wallet that is **structurally incapable of signing**:
- Created with `createwallet` passing **`disable_private_keys = true`** and
`descriptors = true`. Note the ordering already used at
`core/archipelago/src/api/rpc/bitcoin.rs:200-208` — the second positional argument is
`disable_private_keys`, currently `false`.
- Populated with `importdescriptors`, using **public** descriptors only
(`wpkh([fingerprint/84h/0h/0h]xpub.../0/*)` and `.../1/*`).
Unsignability comes from the *absence of private key material*, not from a flag that could be
flipped. That is the correct construction and is why "watch-only" here means "descriptor wallet
with no private keys", not "a wallet we promise not to sign with".
**Descriptor-only from day one.** Bitcoin Core 30.0 removed the ability to create *or load* BDB
legacy wallets (RESEARCH §C.1). Nothing in this design may depend on a legacy wallet, on
`importmulti`, or on any of the 11 removed legacy RPCs. Archipelago is already descriptor-based
(`bitcoin.rs:207`), so this costs nothing to preserve and would be expensive to lose.
### 1.2 The loop, with the actual RPCs
| Step | RPC | Scope | Notes |
|---|---|---|---|
| 1. Construct + fund | `walletcreatefundedpsbt` | **wallet** | Runs on the watch-only wallet. Selects inputs, adds change, attaches the metadata the signer needs. |
| 2. Fill UTXO data (optional) | `utxoupdatepsbt` | node | Useful when the PSBT was built elsewhere or is missing witness UTXO data. |
| 3. Inspect | `analyzepsbt` | node | **Drive all UI state from this** — see §1.3. |
| 4. Export | — | — | Serialise to base64 / file / QR (§4). |
| 5. Sign (offline) | external signer | — | Hardware device, or `descriptorprocesspsbt` on an offline machine holding the descriptors. |
| 6. Import | — | — | Scan / upload the signed PSBT back. |
| 7. Merge signatures | `combinepsbt` | node | Multisig only: merges signatures for the **same** transaction from multiple signers. |
| 8. Merge transactions | `joinpsbts` | node | Different transactions into one. **Not** the multisig merge — a common and expensive confusion. |
| 9. Finalize | `finalizepsbt` | node | Produces the network-serialized transaction. |
| 10. Broadcast | `sendrawtransaction` | node | Except for LND channel funding — see §5. |
`walletprocesspsbt` (wallet-scoped) and `descriptorprocesspsbt` (node-scoped, takes a descriptor
list, **needs no wallet**) are the two signing entry points. `descriptorprocesspsbt` is the
right primitive for an offline signing machine that has descriptors but no wallet.
**Wallet-scoped vs node-scoped matters operationally**: wallet-scoped RPCs must be addressed to
the specific wallet endpoint (`/wallet/<name>`), node-scoped ones must not. Archipelago's
existing `bitcoin_rpc_call` helper (`core/archipelago/src/api/rpc/bitcoin.rs:191-210` usage)
will need an explicit wallet-scoping parameter rather than one global endpoint.
### 1.3 `analyzepsbt` drives the UI — do not infer state
`analyzepsbt` reports, per input, what is still missing and **which role must act next**
(updater / signer / finalizer). The UI must render from that, not from Archipelago's own guess
about how many signatures a 2-of-3 needs. Rationale: role inference is where coordinators get
multisig wrong, and the node already has an authoritative answer one RPC away. It also makes
the "what do I do now" screen correct for free in partial-signature states.
### 1.4 Versions this runs against
From the manifests, so the spec is not written against an imaginary node:
| App | Manifest version | Image |
|---|---|---|
| Bitcoin Core | `28.4.0` (`apps/bitcoin-core/manifest.yml:4`) | `bitcoin:28.4` (`:10`) |
| Bitcoin Knots | `28.1.0` (`apps/bitcoin-knots/manifest.yml:4`) | **`bitcoin-knots:latest`** (`:10`) |
| LND | `0.18.4` (`apps/lnd/manifest.yml:4`) | `lnd:v0.18.4-beta` (`:8`), requires Bitcoin `>=26.0` (`:25`) |
**Flagged, in scope to name and out of scope to fix:** `bitcoin-knots:latest`
(`apps/bitcoin-knots/manifest.yml:10`) is an **unpinned tag**, at odds with ADR-009's
pinned-tag mandate and with every other image in these three manifests. For a wallet-bearing
component, an unpinned tag means the descriptor/PSBT RPC surface underneath a user's funds can
change on a `podman pull`. Fixing it belongs to whoever owns ADR-009 enforcement.
**PSBTv2 / BIP-370** is merged into Bitcoin Core (RESEARCH §C.1). **`[UNVERIFIED]`** — which
released version first exposes it at the RPC surface, and how broadly hardware signers accept
it, was not confirmed. **Build against PSBTv1 as the interop baseline**; treat v2 as
opportunistic and never as a requirement for a user to spend their money.
---
## 2. Where each step lives
Three surfaces, one non-negotiable invariant.
### 2.1 The invariant
> **The BIP-84 private key stays in the daemon's encrypted store. Only the xpub goes into the
> Core descriptor wallet. The private key is never imported into Core.**
Today this is violated (`core/archipelago/src/api/rpc/bitcoin.rs:229-231`, §0). The at-rest
envelope that should hold it exclusively already exists and is sound: Argon2 + ChaCha20-Poly1305
with per-blob salt and nonce from `OsRng`, written `0600`
(`core/archipelago/src/seed.rs:238-269`, `:243-246`, `:318-324`).
### 2.2 Rust orchestrator — `core/archipelago`
Owns everything that touches keys or Core:
- Derives the BIP-84 account key (`core/archipelago/src/seed.rs:207-224`, path `m/84'/0'/0'`)
and exports **only** the account-level xpub plus its key-origin fingerprint into descriptors.
- Creates and maintains the watch-only wallet (rewrite of
`handle_bitcoin_init_wallet_from_seed`, `core/archipelago/src/api/rpc/bitcoin.rs:161-294`).
- Owns the PSBT lifecycle RPCs: construct, analyze, combine, finalize, broadcast.
- Owns the *internal* software-signer path used by the hot tier (§6), which decrypts the seed
under the user's password exactly as `bitcoin.rs:182-185` does today, signs, and zeroizes.
- Enforces spend limits server-side (§6). **Limits enforced in the UI are not limits.**
### 2.3 `neode-ui`
Owns presentation and transport only. It must never see a private key, an xprv, or a mnemonic
outside the onboarding flow the audit already scopes (F-04, F-08).
- Renders the PSBT review screen: inputs, outputs, fee, change, and the `analyzepsbt` "next
role" state.
- Renders the export payload as animated QR (§4) and offers file download.
- Accepts the signed PSBT by camera scan or file upload.
- Renders the cold / warm / hot tier badges (§6) and the honest Lightning copy (§5.4).
### 2.4 Companion app
Owns the air-gap camera path. It already has the two pieces this needs:
- A working QR scanner (project memory: native scan shipped in companion 0.5.22; dense-QR fix
`07772b56`).
- SeedQR encode/decode (`neode-ui/src/utils/seedqr.ts:11`), with a correct, honest note at
`:9` that the LND aezeed is **not** BIP-39 and must never be SeedQR-encoded.
The companion is the natural home for scan-heavy multi-frame PSBT transport, because the node's
own browser may be a TV kiosk with no camera.
---
## 3. Tiers
### 3.1 Tier 1 — single-sig with an external hardware signer
- Descriptor: `wpkh([<fingerprint>/84h/0h/0h]xpub.../0/*)` and `.../1/*`.
- **Key-origin annotation `[fingerprint/derivation]` is mandatory, not cosmetic.** Without it a
hardware signer cannot locate its own key in the PSBT and will refuse to sign (RESEARCH §C.2).
Every descriptor Archipelago emits must carry it. The current code emits descriptors with **no
key-origin prefix** (`core/archipelago/src/api/rpc/bitcoin.rs:230-231`) — a second concrete
reason Phase 1 must rewrite that function.
- Descriptor checksums: obtain via `getdescriptorinfo` before `importdescriptors`, as the
existing code correctly already does (`bitcoin.rs:234-259`). Core rejects a wrong checksum.
### 3.2 Tier 2 — `wsh(sortedmulti(k, ...))` multisig
- Script: `wsh(sortedmulti(k, xpub1/…, xpub2/…, xpub3/…))`.
- **Why `sortedmulti` over ordered `multi`:** `sortedmulti` (BIP-67) lexicographically sorts the
keys in the resulting script, so the wallet can be **recreated without preserving xpub order**.
With ordered `multi`, losing the order loses the wallet even though every key survives — a
recovery failure mode that is entirely avoidable. Use `sortedmulti` unless a specific
cosigner demands ordered `multi`.
- **BIP-48 derivation** for multisig accounts: `m/48'/<coin>'/<account>'/<script_type>'`, with
`2'` = P2WSH. Every coordinator (Sparrow, Nunchuk, Caravan, Specter) expects this path; using
anything else means users cannot import their Archipelago multisig anywhere else.
- Descriptor exchange: each cosigner contributes an xpub **with key origin**; the coordinator
assembles the descriptor and every participant imports the identical descriptor string. All
participants must be able to export the descriptor for backup — a multisig backup is the
descriptor plus each seed, and users who back up only seeds lose funds.
- Reference to copy rather than re-derive: Bitcoin Core's `doc/multisig-tutorial.md` and the
functional test `test/functional/wallet_multisig_descriptor_psbt.py`, which is the exact RPC
sequence in executable form (RESEARCH §C.3).
### 3.3 Taproot / MuSig2 multisig — future work, deliberately
`tr(...)` descriptors exist, but **`[UNVERIFIED]`** — the 2026 state of MuSig2 key-aggregation
support in Core's descriptor wallets and across hardware signers was not confirmed (RESEARCH
§C.3, Open Question 4). Shipping a multisig scheme whose recovery depends on unconfirmed
signer support is how users lose money years later. **Ship `wsh(sortedmulti(...))`.** Revisit
taproot multisig when Core's support and at least two independent hardware signers can be
verified against a real device.
---
## 4. Air-gapped transport
### 4.1 The format decision
| Format | Mechanism | Verdict |
|---|---|---|
| **BC-UR v2** (Blockchain Commons) | **Fountain-coded** (rateless erasure). Any sufficient subset of frames reconstructs the payload; order-independent. | **Recommended primary.** |
| **BBQr** (Coinkite) | Payload split across sequential frames; receiver accumulates and must obtain each missing frame. | Support for Coldcard interop; not the primary. |
| microSD / file (`.psbt`) | Plain file exchange. | **Mandatory fallback, always offered.** |
| SeedQR | Static QR of mnemonic word indices. | **Seed transport only, not PSBT.** Already shipped (`neode-ui/src/utils/seedqr.ts:11`). |
**Recommendation: BC-UR v2 as primary, BBQr for Coldcard interop, file always available.**
The justification is specific to Archipelago's hardware reality rather than generic. The
companion app scans QR from a phone camera, frequently at a TV or in a rack cupboard, in poor
light. BBQr's sequential model means a single missed frame stalls the user until that exact
frame comes round again — the failure mode is "keep pointing the camera and hope". BC-UR's
fountain coding means *any* sufficient number of frames reconstructs the payload, so a bad
scanning environment degrades into "takes longer" instead of "gets stuck". That difference is
what makes an air-gap workflow tolerable enough that users keep using it — which, per §0, is
the whole point.
**`[UNVERIFIED]`** — device support matrix. Confirmed from RESEARCH §C.4: Coldcard → BBQr
(native) + microSD + NFC; Foundation Passport and Keystone → UR; SeedSigner → BC-UR v2. Jade,
Krux, BitBox, Ledger and Trezor support was **not** confirmed and must be verified against real
hardware before any of them is listed as supported in the UI.
### 4.2 QR density — animated is mandatory, not a nice-to-have
A QR code maxes out around ~2,953 bytes at the largest version with the lowest error correction,
and far less at densities a phone camera can actually read across a room. **A real multi-input
multisig PSBT routinely exceeds that.** Therefore:
- **Multi-frame animated QR is mandatory.** Single-QR PSBT export must not be the only path.
- **A file fallback must always be offered**, on every export screen, with equal visual weight.
microSD/file has no density limit and is the most reliable route for large PSBTs.
- The UI must show frame progress (e.g. "142 of 210 frames received") so a stalled scan is
visibly stalled rather than mysteriously slow.
### 4.3 Consistency with the first-party signer
`docs/hardware-signer-design.md` specifies a QR-only, camera-in/screen-out air-gapped signer
(TROPIC01 + ESP32-S3), and lists "Animated/multi-part QR strategy for large PSBTs" as an open
item (`docs/hardware-signer-design.md:167`) and "Define QR payload formats for both roles" at
`:165`. **This document answers both for Bitcoin: BC-UR v2 primary, BBQr for Coldcard interop.**
That signer, when built, should implement the same format so the same node-side transport code
serves third-party signers and the first-party device identically. Its dual Nostr-signing role
(`docs/hardware-signer-design.md:110-148`) is out of scope here but shares the transport layer,
which is an argument for implementing transport as a payload-agnostic module.
---
## 5. LND — what is and is not achievable
### 5.1 Decision table
| Capability | Achievable? | Detail |
|---|---|---|
| Watch-only `lnd` + separate signer instance | **Yes** | `remotesigner.*` on the watch-only node; the signer needs no chain backend (`bitcoin.node=nochainbackend`). |
| Signer fully offline | **No** | The signer must accept a **live inbound gRPC connection**. "Offline except for one connection" is not an air-gap. |
| Air-gap channel / revocation / HTLC keys | **No** | These live in the signer and must sign **on demand, at protocol speed**. A routing node cannot tolerate human-in-the-loop signing. **This is the hard limit of the entire design.** |
| PSBT funding of channels | **Yes** | `lncli openchannel --psbt`; `PsbtShim` via `FundingStateStep`; batch by passing the returned PSBT as `base_psbt`. |
| Open a channel with zero LND wallet balance | **Yes** | The `--psbt` flow explicitly supports funding from an external wallet. |
| **Self-broadcast the funding transaction** | **NEVER** | LND must publish it "in the proper funding flow order **or the funds can be lost**". Encode as a hard UI rule — see §5.3. |
| Sign arbitrary messages / on-chain txs externally | **Yes** | `signrpc` / `walletrpc` (`signer:generate`, `onchain:write`). |
| Move private keys between instances after init | **No** | Not supported. |
| Add accounts dynamically without wallet reconstruction | **No** | Not supported. |
Source: RESEARCH §C.5, from LND `docs/remote-signing.md` and `docs/psbt.md`.
### 5.2 Required accounts and the taproot gotcha
Remote signing requires xpubs for level-3 derivation accounts: purpose **49** (NP2WKH), **84**
(P2WKH), **86** (P2TR), and **1017** accounts 0-255 (node identity, channels, watchtower,
HTLCs). Setup is `lncli wallet accounts list > accounts-signer.json` on the signer, then
`lncli createwatchonly accounts-signer.json` on the watch-only node. A minimal signer macaroon
is `lncli bakemacaroon --save_to signer.custom.macaroon message:write signer:generate
address:read onchain:write`.
**Taproot gotcha:** requires LND v0.15.3-beta+ and a manual
`lncli wallet accounts import --address_type p2tr <xpub> default` on upgrade, or the node fails
with `"account 0 not found"`. Archipelago pins LND `0.18.4` (`apps/lnd/manifest.yml:4`), so the
version floor is satisfied; the manual import step is not automatic and must be part of any
migration runbook.
Migrating an existing node is `remotesigner.migrate-wallet-to-watch-only=true`, which **purges
private key material in place** — one-way, and therefore gated behind a verified backup.
### 5.3 The self-broadcast rule is a hard UI constraint
Archipelago already exposes `lnd.create-psbt` and `lnd.finalize-psbt`
(`core/archipelago/src/api/rpc/dispatcher.rs:136-137`,
implemented in `core/archipelago/src/api/rpc/lnd/wallet.rs:605` and `:711`), and the finalize
handler already broadcasts (`core/archipelago/src/api/rpc/lnd/wallet.rs:757`). That is correct
for an **on-chain** send and **catastrophic** for a channel-funding PSBT.
**Rule:** any PSBT produced by the channel-funding flow must be tagged as such end-to-end, and
every broadcast path must refuse to broadcast a channel-funding PSBT. The refusal belongs in the
Rust orchestrator, not in the UI, and it should be a type-level distinction (a distinct
`ChannelFundingPsbt` wrapper) rather than a boolean anyone can forget to check. This is the one
place in this document where a mistake destroys funds rather than exposing them.
### 5.4 On-chain vs Lightning — two genuinely different tiers
The design splits cleanly, and the split must be visible to users:
| | **On-chain balance** | **Lightning balance** |
|---|---|---|
| Key exposure | Can be fully cold — key never on the node | **Necessarily hot** — channel/revocation/HTLC keys must sign at protocol speed |
| Protection mechanism | Watch-only descriptors + PSBT + external signer | Remote signing *relocates* keys to a hardened host; it does not remove hot exposure |
| Honest claim | "Cold storage" is accurate | "Cold storage" is **false** |
**The exact sentence the UI should use:**
> *A Lightning routing node's channel keys are necessarily hot. Remote signing moves them to a
> hardened machine; it does not make them cold. Only your on-chain balance can be genuinely
> protected by an offline signer.*
**Any copy implying a routing node's channel keys are cold is misleading and must not ship.**
This is not pedantry: a user who believes their Lightning balance is cold will keep more in it
than they would otherwise, which is precisely the miscalibration that turns an incident into a
loss. The Coldcard incident is a good reason to be conservative in this copy rather than
optimistic.
---
## 6. The hot wallet as the explicitly-secondary option
The hot wallet stays. Removing it would push users to worse tools. It is framed, limited, and
labelled as secondary.
1. **Hard separation of on-chain and Lightning balances** in the data model and in the UI.
**Never one blended number.** They have different key exposure (§5.4), different recovery
stories, and different risk. A single "balance" figure silently averages a cold number with a
hot one, which is a lie of composition.
2. **Server-enforced spend limits.** Per-transaction and rolling-daily, enforced in the Rust
orchestrator. Anything above the limit is **forced onto the PSBT path** — not blocked, not
warned-and-allowed: routed. Archipelago already rate-limits financial RPCs
(`core/archipelago/src/rate_limit.rs:62-69`: `wallet.send` 5/300s, `lnd.sendcoins` 5/300s,
`lnd.openchannel` 3/300s), so the enforcement point exists; value limits are the addition.
3. **Reuse the existing at-rest envelope.** Argon2 + ChaCha20-Poly1305, per-blob salt and nonce
from `OsRng`, `0600` (`core/archipelago/src/seed.rs:238-269`, `:318-324`). Do not invent a
second envelope. See audit finding **F-05** on aligning the Argon2 parameters with ADR-005
before this tier carries meaningful value.
4. **Zeroization on every path.** The existing code is the standard to match:
`core/archipelago/src/seed.rs:262`, `:292`, `:384`, `:401`;
`core/archipelago/src/api/rpc/bitcoin.rs:222`, `:284`.
5. **Explicit tiering in the UI**, named rather than hidden:
- **Cold** — watch-only + external signer. On-chain only. The default for new wallets.
- **Warm** — hot on-chain key in the daemon's envelope, under spend limits.
- **Hot** — Lightning. Unavoidably hot; labelled as such.
### 6.1 Nudging toward PSBT without punishing the hot path
The failure mode to avoid is a safe path so tedious that users disable it, and a hot path so
nagged-at that users stop reading warnings. Concretely:
- **Default new wallets to cold.** Do not make the user opt in to safety. This is the direct
lesson of §0.
- **One-time framing, not per-transaction nagging.** Explain the tiers once, at setup, and then
show a small persistent tier badge. Repeated modal warnings train users to dismiss modals.
- **Make the limit the teacher.** When a spend exceeds the warm limit, route it to the PSBT
flow with a neutral explanation ("this amount uses your signing device") rather than an error.
The user learns the tier boundary by using it.
- **Never make the hot path feel broken.** A small Lightning payment should be one tap. If
everyday use is painful, users move their funds to software that does not have any of this.
- **Let the user raise limits, deliberately.** A limit the user cannot adjust gets worked around
entirely; a limit they must consciously raise is a decision they remember making.
---
## 7. Migration for existing users
### 7.1 What the incident does and does not imply here
**Be precise, because both errors are costly.**
- **A software fix does not repair an already-generated seed.** If a seed was produced by a
defective RNG, updating the software leaves it exactly as guessable. This is why Coinkite told
users to migrate rather than merely update.
- **The audit found no such defect in Archipelago.** The internal entropy audit's
§2 and §4 record that every first-party key-generation call site draws from a genuine CSPRNG,
that the mnemonic is a real 256-bit value, and that `[ARCHY-1]` is a *structural* risk with no
present exploitability.
**Therefore: no Archipelago user needs to rotate their seed because of the COLDCARD incident.**
Do not ship a banner implying otherwise. Over-alarming has a real cost — it triggers unnecessary
fund movements, which have their own fee, privacy, and fat-finger risks, and it burns the
credibility needed for a real advisory later.
**Who this section *does* apply to:**
1. **Users whose seed was generated on a Coldcard and imported into Archipelago**, on affected
firmware. Their seed is at risk from T1, independent of Archipelago's own code quality. They
should follow Coinkite's guidance and the sequence in §7.2.
2. **Every user, at the point Phase 1 lands** — because the account xprv is currently imported
into Bitcoin Core (`core/archipelago/src/api/rpc/bitcoin.rs:229-231`, §0). Moving to
watch-only does not require a new seed; it requires re-creating the Core wallet without
private keys. That is a *wallet* migration, not a *key* migration, and it must be presented
as such — see §7.3.
### 7.2 Seed-rotation sequence (only when a seed is actually suspect)
Order matters; each step de-risks the next.
1. **Generate a new key** on trusted, fixed hardware or software.
2. **Verify the backup** — restore it into a second wallet and confirm it reproduces the same
first receive address before sending anything.
3. **Verify a receive address** on the signing device's own screen, not only on the host.
4. **Send a small test transaction** to the new wallet and confirm it arrives and is spendable.
5. **Migrate the funds** from the old wallet to the new one.
6. **Retain the old backup** until every output is confirmed spent and the new wallet's balance
is verified. Destroying the old backup early is the most common way this sequence loses money.
If Lightning is in use, closing channels is part of step 5 and is slow (force-closes carry
timelocks). Budget for it; do not present channel migration as instantaneous.
### 7.3 Wallet migration to watch-only (Phase 1) — *not* a seed rotation
For every existing user, when Phase 1 lands:
1. Confirm the encrypted seed backup exists and is decryptable
(`core/archipelago/src/seed.rs:341-357`, `seed_exists` at `:360-362`).
2. Derive the account xpub and build the key-origin-annotated descriptors.
3. Create a **new** wallet with `disable_private_keys = true` and import the public descriptors.
4. Rescan, and confirm the new watch-only wallet reports the **same balance and the same UTXO
set** as the old one. Do not proceed on any mismatch.
5. Only then unload and remove the private-key-bearing wallet from Core.
**The user's seed does not change and their funds do not move.** Say that plainly in the UI —
the natural user fear on seeing any wallet-migration prompt is that their money is being touched.
---
## 8. Phased rollout
Each phase names a goal, its dependencies, candidate requirements, and whether it needs real
hardware. This section is the input a future `/gsd-plan-phase` consumes.
### Phase 1 — Descriptor watch-only read path
**Goal:** the node's Bitcoin Core wallet holds no private keys; the daemon's encrypted store is
the only place the BIP-84 key exists.
**Dependencies:** none. **This is the highest-value change in the document and it unblocks
everything else** — no external-signer flow is meaningful while Core holds the xprv.
**Candidate requirements:**
- `createwallet` is called with `disable_private_keys = true` (currently `false`,
`core/archipelago/src/api/rpc/bitcoin.rs:203`).
- Imported descriptors carry the **xpub** and a key-origin annotation
`[fingerprint/84h/0h/0h]` (currently a bare xprv with no origin, `bitcoin.rs:229-231`).
- A migration path re-creates the wallet watch-only and verifies balance/UTXO parity before
removing the old wallet (§7.3).
- The account xprv is never written to Core and never leaves the Argon2 envelope except in
memory, zeroized.
- Regression test: the wallet cannot sign — a signing attempt against it fails structurally.
**Real hardware:** yes, for the migration — verify on a node with real UTXO history (`.228`).
### Phase 2 — PSBT construct and export
**Goal:** the node can build a funded PSBT from the watch-only wallet and hand it out.
**Dependencies:** Phase 1.
**Candidate requirements:**
- `walletcreatefundedpsbt` wired with explicit fee control, reusing the existing fee-preset UI.
- `analyzepsbt` exposed and used as the single source of UI state (§1.3).
- Export as base64 and as a `.psbt` file download.
- A PSBT review screen showing inputs, outputs, fee, change, and destination — the human check
the whole air-gap model depends on.
**Real hardware:** no (regtest/testnet sufficient).
### Phase 3 — External-signer import and finalize
**Goal:** a signed PSBT from a third-party signer completes the loop and broadcasts.
**Dependencies:** Phase 2.
**Candidate requirements:**
- Import a signed PSBT by file upload; `combinepsbt` where multiple parts arrive.
- `finalizepsbt` + `sendrawtransaction`, with the channel-funding refusal of §5.3 in place from
day one — not retrofitted.
- Clear error surfacing when `analyzepsbt` says signatures are still missing.
**Real hardware:** **yes** — must be verified end-to-end against at least one real signer
(Coldcard or Passport) before it is offered to users.
### Phase 4 — Air-gap transport (BC-UR v2 + BBQr)
**Goal:** the loop closes over QR, with a file fallback, in the companion app.
**Dependencies:** Phase 3.
**Candidate requirements:**
- BC-UR v2 encode (node) and decode (companion), fountain-coded, with visible frame progress.
- BBQr decode for Coldcard interop.
- File fallback offered with equal weight on every export and import screen (§4.2).
- Payload-agnostic transport module, so `docs/hardware-signer-design.md`'s Nostr role can reuse
it later without a rewrite.
**Real hardware:** **yes** — QR density and scan reliability cannot be evaluated in an emulator.
Verify at realistic distance and lighting, including the TV-kiosk case.
### Phase 5 — Multisig
**Goal:** `wsh(sortedmulti(k, ...))` wallets with BIP-48 paths and descriptor exchange.
**Dependencies:** Phase 4 (large multisig PSBTs are exactly the case that needs robust transport).
**Candidate requirements:**
- Create/import a `wsh(sortedmulti(...))` descriptor with per-key origin annotations.
- BIP-48 `m/48'/0'/<account>'/2'` derivation for Archipelago's own key.
- Descriptor export/backup UX that states plainly that the descriptor is part of the backup.
- `combinepsbt` across N signers with `analyzepsbt`-driven progress.
- Interop test against at least one external coordinator (Sparrow or Nunchuk).
**Real hardware:** **yes** — two independent signers minimum.
### Phase 6 — LND remote signing
**Goal:** LND runs watch-only with a separate signer instance, with honest UI copy.
**Dependencies:** Phase 1 (the on-chain story must be settled first; doing Lightning first would
teach users the wrong mental model).
**Candidate requirements:**
- Signer instance provisioning (`bitcoin.node=nochainbackend`, minimal macaroon) and watch-only
setup via `createwatchonly`.
- Explicit p2tr account import step (§5.2), or a documented failure with a fix-it action.
- `remotesigner.migrate-wallet-to-watch-only=true` migration, gated behind a verified backup —
it purges key material in place and is one-way.
- UI copy carrying the §5.4 sentence verbatim, and no copy anywhere claiming Lightning funds are
cold.
**Real hardware:** **yes** — two hosts, and a real channel.
### Phase 7 — Hot-wallet limits and tiering
**Goal:** the hot path is bounded, labelled, and routes large spends to PSBT.
**Dependencies:** Phase 3 (there must be a PSBT path to route *to*).
**Candidate requirements:**
- Server-enforced per-transaction and rolling-daily limits, with over-limit spends routed to the
PSBT flow rather than rejected (§6.1).
- On-chain and Lightning balances separated in the data model and never summed in the UI.
- Cold / warm / hot tier badges.
- New wallets default to cold.
**Real hardware:** no, beyond normal on-node verification.
### Sequencing note
Phases 1-4 are the spine and should run in order. Phase 6 (LND) and Phase 7 (limits) can run in
parallel with Phase 5 (multisig) once Phase 3 lands. Phase 1 alone materially improves the
current security posture and should not wait for the rest.
---
## 9. Related documents
- The internal entropy and seed-generation audit — motivating this spec; see F-05
(Argon2 parameters) and the F-13 addendum on the xprv-in-Core issue.
- `docs/hardware-signer-design.md` — the first-party TROPIC01 air-gapped signer; §4.3 above
answers two of its open items.
- `docs/adr/005-chacha20-backup-encryption.md` — the at-rest envelope §6 reuses.
— Part C is the source for the Core RPC table, the LND capability matrix, and the air-gap
format comparison.
docs/troubleshooting.md
+630
View File
@@ -0,0 +1,630 @@
# Archipelago Troubleshooting Guide
This guide covers the most common issues you may encounter with Archipelago, along with diagnostic commands and solutions.
## Connection & Access
### 1. Can't connect to the web UI
**Symptoms**: Browser shows "connection refused" or spins forever when accessing `http://<your-server-ip>`
**Diagnosis**:
```bash
# Check if the server is reachable on the network
ping <server-ip>
# SSH in and check Nginx
ssh archipelago@<server-ip>
sudo systemctl status nginx
sudo nginx -t
# Check if the backend is running
sudo systemctl status archipelago
curl -s http://localhost:5678/health
```
**Solutions**:
- Ensure you're on the same network (LAN) as the server
- If Nginx is down: `sudo systemctl restart nginx`
- If backend is down: `sudo systemctl restart archipelago`
- Check firewall: `sudo ufw status` — port 80 (HTTP) and 443 (HTTPS) must be allowed
- If the server IP changed, check your router's DHCP lease table or run `ip addr show` on the server
### 2. Login page loads but login fails
**Symptoms**: You see the login screen but entering the correct password shows an error
**Diagnosis**:
```bash
# Check backend logs
sudo journalctl -u archipelago --since "5 minutes ago" --no-pager
# Test the RPC endpoint directly
curl -s -X POST http://localhost:5678/rpc/v1 \
-H 'Content-Type: application/json' \
-d '{"method":"server.echo","params":{"message":"test"}}' | head -100
```
**Solutions**:
- There is no default password — the password is the one you created on this
node's first-boot "Set Up Your Node" screen. Password recovery requires SSH
access to the node; note that simply deleting `/var/lib/archipelago/user.json`
does **not** work, because the onboarding gate refuses `auth.setup` once the
node is provisioned
- Clear browser cookies and try again (stale session cookie)
- Restart the backend: `sudo systemctl restart archipelago`
- Check if the database is accessible: `ls -la /var/lib/archipelago/`
### 3. Web UI loads but shows blank white page
**Symptoms**: Browser loads but nothing renders, or you see a white screen
**Diagnosis**:
```bash
# Check if frontend files exist
ls -la /opt/archipelago/web-ui/index.html
ls -la /opt/archipelago/web-ui/assets/
# Check browser console (F12 > Console) for JavaScript errors
# Check Nginx error log
sudo tail -20 /var/log/nginx/error.log
```
**Solutions**:
- Redeploy the frontend: run the deploy script from the development machine
- Check if files exist in `/opt/archipelago/web-ui/` — if missing, the deploy didn't complete
- Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R)
- Try a different browser or incognito mode
### 4. HTTPS certificate warning
**Symptoms**: Browser shows "Your connection is not private" or certificate error
**Solutions**:
- Archipelago uses a self-signed certificate by default — this is expected on first visit
- Click "Advanced" > "Proceed to site" (Chrome) or "Accept the Risk" (Firefox)
- For permanent fix, configure a domain name and use Let's Encrypt
- On kiosk mode, the certificate is auto-accepted
---
## App Issues
### 5. App won't start (container fails to launch)
**Symptoms**: Clicking "Start" on an app shows an error, or the app stays in "stopped" state
**Diagnosis**:
```bash
# Check container status
podman ps -a --filter "name=<app-id>"
# Check container logs
podman logs <app-id> --tail 50
# Check if the image exists
podman images | grep <app-id>
# Check available disk space
df -h /var/lib/archipelago
```
**Solutions**:
- If the image is missing: reinstall the app from the Marketplace
- If disk is full: run disk cleanup from the **Server** page (`/server`), or manually `podman system prune`
- If the container exits immediately: check logs for the root cause (usually missing config or permissions)
- Restart the Podman socket. Archipelago runs **rootless** Podman as the
`archipelago` user, so this is a `--user` unit — `sudo systemctl restart podman`
would restart the unrelated root socket:
`systemctl --user restart podman.socket`
### 6. App shows "unhealthy" status
**Symptoms**: App is running but shows a yellow or red health indicator
**Diagnosis**:
```bash
# Check container health
podman healthcheck run <app-id>
# Check container resource usage
podman stats <app-id> --no-stream
# Check container logs for errors
podman logs <app-id> --tail 100 | grep -i error
```
**Solutions**:
- Some apps take time to become healthy after starting (especially Bitcoin which needs to sync)
- Check if the app has enough resources (RAM, CPU)
- Restart the specific app from the UI or: `podman restart <app-id>`
- Check if dependent services are running (e.g., LND requires Bitcoin)
### 7. Bitcoin not syncing / stuck at a block height
**Symptoms**: Bitcoin node shows the same block height for an extended period
**Diagnosis**:
```bash
# Check Bitcoin logs
podman logs bitcoin-knots --tail 50
# Check if Bitcoin is connected to peers.
# The datadir inside the container is /home/bitcoin/.bitcoin, and the RPC
# credentials live in the generated /tmp/rpc.conf (the manifest's entrypoint
# writes it from the BITCOIN_RPC_USER/BITCOIN_RPC_PASS secrets) — bitcoin-cli
# needs both flags or it can't authenticate.
podman exec bitcoin-knots bitcoin-cli \
-datadir=/home/bitcoin/.bitcoin -conf=/tmp/rpc.conf \
getpeerinfo | grep -c '"addr"'
# Check sync progress
podman exec bitcoin-knots bitcoin-cli \
-datadir=/home/bitcoin/.bitcoin -conf=/tmp/rpc.conf \
getblockchaininfo | grep -E "blocks|headers|verificationprogress"
```
**Solutions**:
- Initial sync takes 1-7 days depending on hardware — be patient
- Ensure the server has a stable internet connection
- Check disk space. The manifest picks the mode from the disk it's given: under
1000 GB it runs **pruned** (`-prune=550`, a few GB); at 1000 GB or more it runs
a full `-txindex=1` archival node, which needs 600 GB+ and growing
- If stuck: restart the container `podman restart bitcoin-knots`
- If peers = 0: check firewall allows port 8333 outbound
- Editing `bitcoin.conf` in the data directory has **no effect** — the
entrypoint runs bitcoind with an explicit `-conf=/tmp/rpc.conf` and logs
"ignoring legacy datadir bitcoin.conf". Flags come from the app manifest, so
persistent changes belong there (and, for catalog-covered apps, in the signed
catalog entry that overrides the on-disk manifest)
### 8. LND won't connect to Bitcoin
**Symptoms**: LND shows errors about Bitcoin connection, or channels aren't working
**Diagnosis**:
```bash
# Check LND logs
podman logs lnd --tail 50
# Check if Bitcoin RPC is accessible from LND
podman exec lnd wget -qO- http://bitcoin-knots:8332/ 2>&1 | head -5
# Check LND status
podman exec lnd lncli getinfo 2>&1 | head -20
```
**Solutions**:
- Ensure Bitcoin is fully synced before starting LND
- Both containers must be on the same Podman network (`archy-net`)
- Check Bitcoin RPC credentials match what LND expects
- Restart both containers in order: Bitcoin first, then LND
---
## Backup & Recovery
### 9. Backup fails to create
**Symptoms**: Backup button shows an error, or backup file is empty
**Diagnosis**:
```bash
# Check disk space
df -h /var/lib/archipelago
# Check backup directory permissions
ls -la /var/lib/archipelago/backups/
# Check backend logs for backup errors
sudo journalctl -u archipelago --since "10 minutes ago" | grep -i backup
```
**Solutions**:
- Ensure sufficient disk space (backups can be large)
- Check permissions: backup directory should be owned by `archipelago` user
- Try creating a smaller backup (exclude app data)
- Restart the backend service and try again
### 10. Can't restore from backup
**Symptoms**: Restore process fails or data doesn't appear after restore
**Diagnosis**:
```bash
# Verify backup file integrity
file /path/to/backup.archipelago
ls -la /path/to/backup.archipelago
# Check backend logs during restore
sudo journalctl -u archipelago -f
```
**Solutions**:
- Ensure the backup file is not corrupted (check file size is reasonable)
- Passphrase must match what was used during backup creation
- Stop all running apps before restoring
- After restore, restart the backend: `sudo systemctl restart archipelago`
---
## System Updates
### 11. System update fails
**Symptoms**: Update button shows an error, or update process hangs
**Diagnosis**:
```bash
# Check internet connectivity
curl -s https://debian.org > /dev/null && echo "Internet OK" || echo "No internet"
# Check backend logs
sudo journalctl -u archipelago --since "15 minutes ago" | grep -i update
# Check disk space (updates need temporary space)
df -h /
```
**Solutions**:
- Ensure stable internet connection during updates
- Ensure at least 2GB free disk space
- If update hangs: wait 10 minutes, then restart the backend
- Do NOT power off during an update — this can corrupt the system
- If the system is in a bad state after a failed update, recover over SSH — the
USB installer has no repair mode (its boot menu offers only "Install
Archipelago", "Install Archipelago (verbose)" and "Boot from local disk")
### 12. Server won't boot after update
**Symptoms**: Server doesn't respond after a system update
**Solutions**:
- Wait 5 minutes — the first boot after update may take longer
- If still unresponsive: connect a monitor/keyboard to check boot messages
- If it's a bootloader problem rather than a disk problem, boot the USB and pick
"Boot from local disk" to chainload the installed system
- As a last resort: reinstall from USB and restore from backup. The installer is
interactive — it asks for the target disk and requires typing `yes` — so
booting it does not by itself destroy the existing install
---
## Kiosk Mode
### 13. Kiosk display shows black screen
**Symptoms**: Connected monitor shows black screen instead of the Archipelago UI
**Diagnosis**:
```bash
# SSH in and check kiosk service
sudo systemctl status archipelago-kiosk
# Check if X11/Wayland is running
ps aux | grep -E "(Xorg|weston|chromium|firefox)"
# Check display output
ls /dev/dri/
xrandr --query 2>/dev/null || echo "No display server"
```
**Solutions**:
- Restart the kiosk service: `sudo systemctl restart archipelago-kiosk`
- Check HDMI cable is securely connected
- Try a different HDMI port or cable
- Check if the display is set to the correct input source
- Review kiosk logs: `sudo journalctl -u archipelago-kiosk --since "5 minutes ago"`
### 14. Kiosk display is stuck or frozen
**Symptoms**: Kiosk shows the UI but it's unresponsive to touch/mouse
**Solutions**:
- The watchdog service should auto-restart frozen kiosk — wait 30 seconds
- SSH in and restart: `sudo systemctl restart archipelago-kiosk`
- Check if the backend is responsive: `curl -s http://localhost:5678/health`
- If backend is down too, restart everything: `sudo systemctl restart archipelago archipelago-kiosk`
---
## Network & Connectivity
### 15. Tor address not available
**Symptoms**: Settings shows "Tor: Not configured" or the .onion address is missing
Tor is **not** a container — it's the host's Debian `tor` package, running as
`debian-tor`. Archipelago never touches it directly: it stages a torrc and asks
`archipelago-tor-helper` (a `.path` unit watching
`/var/lib/archipelago/tor-config/tor-action`) to install it and restart Tor.
**Diagnosis**:
```bash
# Check the host Tor service and the helper that drives it
sudo systemctl status tor
sudo journalctl -u archipelago-tor-helper --since "10 minutes ago"
# Is the SOCKS port up? (this is the liveness check the backend itself uses)
nc -z 127.0.0.1 9050 && echo "Tor SOCKS OK"
# The readable hostname copy the backend actually reads
cat /var/lib/archipelago/tor-hostnames/archipelago
# The hidden-service dir itself (root-owned 0700 — needs sudo)
sudo cat /var/lib/tor/hidden_service_archipelago/hostname 2>/dev/null \
|| sudo cat /var/lib/archipelago/tor/hidden_service_archipelago/hostname
```
**Solutions**:
- Tor takes 30-60 seconds to bootstrap — wait and refresh
- If `/var/lib/archipelago/tor-hostnames/archipelago` is missing but the
hidden-service dir has a `hostname`, the readable copy didn't sync — the
helper's `sync-hostnames` action rewrites it
- Check that the Tor data directory exists and is owned by `debian-tor`
- Restart Tor: `sudo systemctl restart tor`
### 16. Peers can't reach my node
**Symptoms**: Federation peers show "unreachable" status
**Diagnosis**:
```bash
# Check if Tor is running (the fallback transport for peer connectivity)
sudo systemctl status tor
# Check your Tor address
cat /var/lib/archipelago/tor-hostnames/archipelago
# Test connectivity from the server side
curl -s http://localhost:5678/rpc/v1 \
-H 'Content-Type: application/json' \
-d '{"method":"node.tor-address","params":{}}' | head -50
```
**Solutions**:
- Tor is the last-resort transport, not the only one: peering prefers mesh
radio, then LAN, then FIPS, and only falls back to Tor. A peer stuck on
"unreachable" with Tor healthy usually means the higher transports are all
down too — check the FIPS anchor first
- Tor circuits can be slow — connections may take 30+ seconds
- Share your correct .onion address with peers
- Both nodes must be on the same federation
### 17. DNS resolution issues
**Symptoms**: Apps can't reach external services, container downloads fail
**Diagnosis**:
```bash
# Test DNS from the server
nslookup google.com
dig google.com
# Check DNS configuration
cat /etc/resolv.conf
# Test from within a container
podman exec bitcoin-knots nslookup seed.bitcoin.sipa.be
```
**Solutions**:
- Configure DNS from the **Server** page (`/server`): try Cloudflare (1.1.1.1) or Google (8.8.8.8)
- If using custom DNS, verify the server addresses are correct
- Restart networking: `sudo systemctl restart systemd-resolved`
---
## Performance & Resources
### 18. Server is very slow / high CPU usage
**Symptoms**: Web UI is slow to respond, apps are laggy
**Diagnosis**:
```bash
# Check CPU and memory usage
top -bn1 | head -15
# Check per-container resource usage
podman stats --no-stream
# Check disk I/O
iostat -x 1 3
```
**Solutions**:
- Bitcoin initial sync uses heavy CPU — this is normal and temporary
- Check which container is using the most resources with `podman stats`
- Stop apps you don't need
- If RAM is full: add swap space or upgrade hardware
- Consider using an SSD if running on HDD (massive I/O improvement)
### 19. Disk full
**Symptoms**: Apps fail, UI shows disk warning, new installs fail
**Diagnosis**:
```bash
# Check disk usage
df -h /var/lib/archipelago
# Find largest directories
du -sh /var/lib/archipelago/*/ | sort -rh | head -10
# Check Podman image/container sizes
podman system df
```
**Solutions**:
- Run disk cleanup from the **Server** page (`/server`)
- Remove unused app data: `podman system prune -a` (WARNING: removes all stopped containers and unused images)
- Move Bitcoin data to external drive if chain data is too large
- Check for large log files: `du -sh /var/log/*/ | sort -rh`
- Consider upgrading to a larger disk
### 20. WebSocket disconnections / "Reconnecting..." banner
**Symptoms**: UI shows a reconnecting indicator, real-time updates stop
**Diagnosis**:
```bash
# Check backend health
curl -s http://localhost:5678/health
# Check backend logs for WebSocket errors
sudo journalctl -u archipelago --since "5 minutes ago" | grep -i websocket
# Check system resources (WebSocket can drop under load)
free -h
```
**Solutions**:
- Brief disconnections are normal during backend restarts — the UI auto-reconnects
- If persistent: check if the backend is overloaded (high CPU/RAM)
- Restart the backend: `sudo systemctl restart archipelago`
- Check Nginx WebSocket proxy config: `/etc/nginx/sites-available/archipelago` must include `proxy_set_header Upgrade $http_upgrade`
- If on WiFi, try wired Ethernet for more stable connectivity
### 21. LoRa radio firmware flash failed / board unresponsive
**Symptoms**: The "Erase & Flash Now" flow in the mesh hot-swap modal reports
an error, or the radio no longer enumerates as a serial device after a flash
attempt.
**Diagnosis**:
```bash
# Poll the flash job's last-known stage/error directly
curl -s http://localhost:5678/rpc/v1 \
-H 'Content-Type: application/json' \
-d '{"method":"mesh.flash-status","params":{}}'
# Confirm the board is still enumerating at all
ls -la /dev/ttyUSB* /dev/ttyACM* /dev/mesh-radio 2>&1
# esptool/rnodeconf binaries present?
which esptool; ls -la /usr/local/bin/archy-rnodeconf
```
**Solutions**:
- A failure during `erasing`/`writing` (MeshCore/Meshtastic) or
`autoinstalling` (Reticulum) can leave the chip erased or half-written —
this is expected risk of the "always erase first" default, not a bug.
- Heltec V3/V4 boards can be forced back into bootloader mode manually: hold
**BOOT**, tap **RST**, then release **BOOT** — this puts the chip in a
state esptool can always talk to, regardless of what firmware (if any) is
currently on it.
- With the board in bootloader mode, a manual recovery flash can be run
directly over SSH without the UI:
```bash
esptool --chip esp32s3 --port /dev/ttyACM0 erase_flash
esptool --chip esp32s3 --port /dev/ttyACM0 write_flash 0x0 <known-good-image.bin>
```
- For Reticulum/RNode boards, the equivalent manual recovery is
`archy-rnodeconf /dev/ttyACM0 --autoinstall` (or `/usr/local/bin/archy-rnodeconf`
if it's not on `PATH`) — it re-runs the same fetch+erase+flash+bootstrap
sequence the UI triggers.
- If `esptool`/`archy-rnodeconf` are missing entirely, they should have been
installed by the last `self-update.sh` run — check
`sudo journalctl -u archipelago-update` for install failures, or install
`esptool` via `sudo apt-get install esptool` directly.
- Once a fresh image is confirmed written, unplug/replug the radio (or wait
for the next detection poll) — the hot-swap modal re-probes automatically
and shows whatever firmware is actually on the board now.
**Known incident (2026-07-23) — reconnect storm / device boot-loop after a
failed flash**: a real Heltec V3 got stuck cycling "connect → partial
handshake → drop" every 5-15s for 5+ minutes after a `mesh.flash-device`
attempt failed with `Reading firmware download stream`. Root cause was two
compounding issues, both now fixed:
1. `spawn_mesh_listener`'s reconnect backoff (`core/archipelago/src/mesh/listener/mod.rs`)
reset to its 5s minimum any time the prior session had been `device_connected`
at all, even for under a second — so a device that connects-then-drops
repeatedly never actually backed off. Every retry's `open()` toggles
DTR/RTS, which resets many ESP32 boards' MCU (native-USB *and*
CP2102/CH340 auto-reset-circuit boards), so the aggressive retries were
themselves *causing* the boot loop, not just observing one. Fixed by only
resetting backoff when a session ran for at least `STABLE_SESSION_THRESHOLD`
(20s) — see that constant's doc comment.
2. `mesh::flash::start_flash_job`'s post-completion handler auto-resumed the
listener unconditionally, even after a *failed* flash, immediately
re-entering the reconnect loop above with no cooldown. Fixed: on failure
the listener is now deliberately left stopped (reconnect manually via the
UI once the board is confirmed alive); on success there's a 5s settle
delay before resuming, so the board finishes booting from the flash
tool's own reset before Archipelago starts probing it again.
3. Separately, the download itself was failing because `mesh::flash`'s HTTP
client had a blanket 30s request timeout that covered the *entire*
download (including streaming a 170MB Meshtastic zip), not just
connection setup — fixed with a per-chunk stall timeout instead of a
fixed total-transfer cap.
If this symptom recurs (rapid repeating `mesh::serial: Opened serial
port... Starting Meshcore handshake` lines in `journalctl -u archipelago`
without a `LoRa firmware flash` job in progress), it's a NEW instance of the
same class of bug, not the one above — check whether backoff is actually
escalating (`Mesh session error: ... (retry in Xs)` — X should grow past 5s
within a few cycles) before assuming it's flashing-related.
---
## General Maintenance
### Quick Health Check Commands
```bash
# Overall system status
sudo systemctl status archipelago nginx
# All containers
podman ps -a
# Disk usage
df -h /var/lib/archipelago
# Memory usage
free -h
# Recent errors
sudo journalctl -u archipelago --since "1 hour ago" -p err
# Backend health endpoint
curl -s http://localhost:5678/health
```
### Emergency Recovery
If the system is completely unresponsive:
1. **Power cycle**: Hold power button for 10 seconds, then turn back on
2. **Wait 5 minutes**: Services take time to start, especially if containers need to recover
3. **SSH in**: If web UI is down but SSH works, restart services manually
4. **Chainload the installed system**: Boot the Archipelago USB and pick "Boot
from local disk" — this rules out a broken bootloader
5. **Clean install + restore**: As last resort, do a fresh install and restore from backup
### Collecting Diagnostic Information
If you need to report an issue, collect this information:
```bash
# System info
uname -a
cat /etc/os-release
# Service status
sudo systemctl status archipelago nginx
# Recent logs (last 100 lines)
sudo journalctl -u archipelago --no-pager -n 100
# Container status
podman ps -a
# Disk and memory
df -h
free -h
# Network
ip addr show
```
docs/tv-input-iframe-apps.md
+84
View File
@@ -0,0 +1,84 @@
# TV input: keyboard/gamepad inside iframe apps — design
**Goal (2026-07-23, user requirement):** on a TV/kiosk node, keyboard and
gamepad control must work *inside iframe apps* (IndeeHub, Jellyfin, fedimint
UI, AIUI…), easily and globally — no per-app hacks.
## What already exists
- `neode-ui/src/composables/useControllerNav.ts` — a complete spatial-nav
system for the shell: reads gamepads (`navigator.getGamepads`), moves focus
between `data-controller-container` regions, plays nav sounds. It stops at
iframe boundaries: nothing is forwarded into frames.
- Keyboard focus DOES enter iframes natively (click/Tab into the frame), and a
focused iframe receives all keys — same- or cross-origin. The gap is
gamepad→app and deliberate focus handoff shell↔frame.
- Kiosk Chromium is our process (archipelago-kiosk-launcher), X11, and the ISO
already ships `xdotool`. Most app iframes are **cross-origin**
(`http://host:port`), so shell-side script injection is impossible for them;
only the nginx-proxied `/app/...` ones are same-origin.
## Recommended architecture — two layers, both global
### Layer 1 (OS, kiosk nodes): gamepad → virtual keyboard, kernel-level
A small host daemon (`archipelago-gamepad-keys`) on kiosk nodes:
- reads game controllers via evdev (`/dev/input/event*`, capability
BTN_GAMEPAD), hotplug-aware (udev monitor or 5s rescan — same pattern as the
audio router);
- emits a **uinput virtual keyboard**: D-pad/left-stick → arrow keys, A →
Enter, B → Escape, X → Space (play/pause), Y → `f` (fullscreen in most
players), shoulders → Tab / Shift+Tab, Start → Enter, Select → Escape;
- ships exactly like the audio router: `image-recipe/configs/` script + unit,
spliced into the ISO, `include_str!` self-heal in `bootstrap.rs`, gated on
the kiosk being installed. The `archipelago` user is in `input` group OR the
unit runs as root (uinput needs it anyway — run as root, it's ~100 lines of
evdev→uinput with no network).
Why this layer wins: the browser sees a real keyboard, so **every iframe —
any origin, any app — just works** the way it does for a physical keyboard
today. Video players, web games, AIUI: all of them already have keyboard
bindings. Zero app cooperation, zero web-platform security fights.
### Layer 2 (shell): deliberate focus handoff into/out of frames
Small extension to `useControllerNav`:
- When spatial nav selects an app-session container and the user presses
A/Enter: call `iframe.focus()` (works cross-origin) — keys (real or
virtual) now flow into the app.
- A dedicated **exit chord** the daemon maps from the gamepad (e.g. Home
button → F12 or a rarely-used key): the shell listens with a *capturing*
window listener; on seeing it, `iframe.blur()` + return focus to the shell
nav. Keyboard users get the same via a documented chord (e.g. long
Escape / Ctrl+Escape — plain Escape stays with the app, players use it).
- Same-origin frames (the `/app/...` proxied set) can additionally get the
full spatial-nav treatment by running the existing nav over
`iframe.contentDocument` — nice-to-have after the layers above land.
### Optional layer 3 (per-app polish): postMessage contract
For OUR app UIs only (AIUI, fedimint, launcher pages): a tiny
`archipelago:input` postMessage contract for semantic actions (back, home,
context-menu) where raw keys aren't expressive enough. Documented in the app
packaging docs; never required for an app to be usable.
## What NOT to do
- ❌ CDP (`--remote-debugging-port` + Input.dispatchKeyEvent): works but adds
a privileged debug port to the kiosk and a daemon↔browser coupling; the
uinput route gets the same result at kernel level with no attack surface.
- ❌ Per-app nav scripts injected into iframes: cross-origin makes this
impossible for most apps, and it's exactly the per-app hack the requirement
rules out.
## Implementation order
1. `archipelago-gamepad-keys` daemon (evdev→uinput, ~python3 stdlib or small
Rust bin) + unit + ISO splice + bootstrap self-heal. Test on Framework PT
with any USB/BT controller.
2. `useControllerNav`: A-button → `iframe.focus()` on the focused app session;
exit-chord capture listener to reclaim focus.
3. (Later) same-origin spatial nav inside `/app/...` frames; postMessage
contract for our own app UIs.
docs/user-walkthrough.md
+410
View File
@@ -0,0 +1,410 @@
# Archipelago User Walkthrough
A complete guide to setting up and using Archipelago, from hardware to daily use. Each section describes what the user sees and does, serving as the basis for video tutorials.
---
## Part 1: Hardware & Preparation
### What You Need
- **Hardware**: Any x86_64 PC (Intel NUC, mini PC, old desktop) or Raspberry Pi 5
- Minimum: 4GB RAM, 32GB SSD
- Recommended: 8GB+ RAM, 1TB+ NVMe SSD (for Bitcoin full node)
- **USB drive**: 8GB+ for the installer
- **Network**: Ethernet cable (recommended) or WiFi
- **Monitor + keyboard**: For initial setup (optional if using headless mode)
- **Another computer**: To flash the USB and access the web UI
### Step 1: Download the ISO
> **Screenshot**: Browser showing the Archipelago releases page with download buttons for x86_64 and ARM64 ISOs.
1. Go to the Archipelago releases page
2. Download the latest `archipelago-auto-installer-*.iso` for your architecture
3. Verify the checksum matches the published hash
### Step 2: Flash the USB Drive
> **Screenshot**: Balena Etcher with the ISO selected and a USB drive ready to flash.
1. Download [Balena Etcher](https://etcher.io) (free, cross-platform)
2. Insert your USB drive
3. Open Etcher, select the downloaded ISO
4. Select your USB drive
5. Click "Flash!" — wait for completion (2-5 minutes)
### Step 3: Boot from USB
> **Screenshot**: BIOS boot menu showing USB drive as an option.
1. Insert the flashed USB into your target hardware
2. Power on and enter BIOS/boot menu (usually F2, F12, or Del during boot)
3. Select the USB drive as the boot device
4. The installer will start automatically
---
## Part 2: Installation
### Step 4: Auto-Installer Runs
> **Screenshot**: Terminal showing the auto-installer progress — partitioning, copying files, setting up the system.
The auto-installer handles everything:
- Partitions the target disk (erases existing data)
- Copies the Archipelago system
- Installs the bootloader
- Pre-loads container images for offline app installation
**Duration**: 5-15 minutes depending on hardware speed.
### Step 5: First Boot
> **Screenshot**: Console showing systemd services starting — archipelago.service, nginx, podman.
1. Remove the USB drive when prompted
2. The system reboots into Archipelago
3. Services start automatically (takes 30-60 seconds)
4. If a monitor is connected, the kiosk mode launches showing the web UI
---
## Part 3: First-Time Setup (Onboarding)
### Step 6: Connect to the Web UI
> **Screenshot**: Browser address bar showing `http://192.168.1.x` with the Archipelago splash screen loading.
1. Find your server's IP address:
- Check your router's DHCP client list
- Or connect a monitor — the IP is shown on the kiosk display
2. Open a browser on any device on the same network
3. Navigate to `http://<server-ip>`
4. The splash screen plays the Archipelago intro animation
### Step 7: Tap to Start
> **Screenshot**: The splash screen with "Tap anywhere to begin" text and cosmic background animation.
1. The intro screen shows the Archipelago logo with atmospheric music
2. Tap or click anywhere to proceed
3. A typing animation welcomes you: "Welcome, Noderunner"
### Step 8: Create Your Password
> **Screenshot**: The "Set Up Your Node" screen with password and confirm-password fields, glass-morphism design.
**There is no default web password.** A freshly installed node has no user
account at all, so this screen shows a password-creation form rather than a
login form:
1. Enter a password (minimum 8 characters)
2. Confirm it in the second field
3. Click "Set Up Node"
Every boot after this one shows the normal login form and asks for the password
you chose here. Store it somewhere you can get back to — recovering it requires
SSH access to the node.
### Step 9: Choose Your Path (Onboarding)
> **Screenshot**: The onboarding path selection screen showing three options: Bitcoin Node, Home Server, Full Sovereignty.
The onboarding wizard guides you through setup:
1. **Choose your path**:
- **Bitcoin Node**: Bitcoin Knots + LND + Mempool (focused)
- **Home Server**: Bitcoin + Home Assistant + File Manager (balanced)
- **Full Sovereignty**: Everything — Bitcoin, Lightning, Nostr, VPN, Cloud (maximum)
2. **Create your identity**:
> **Screenshot**: DID creation screen showing the generated decentralized identifier.
- A DID (Decentralized Identifier) is generated for your node
- This is your sovereign digital identity — no third party needed
3. **Backup your seed**:
> **Screenshot**: Seed phrase display with 12 words and a "I've saved this" checkbox.
- Write down or save your backup passphrase
- This is the only way to recover your node if hardware fails
- Store it securely offline
4. **Verify your backup**:
> **Screenshot**: Verification screen asking to confirm specific words from the backup.
- Confirm you've saved your backup by entering requested words
5. **Setup complete**:
> **Screenshot**: Completion screen with confetti animation and "Enter your node" button.
- Click to enter the dashboard
---
## Part 4: The Dashboard (Daily Use)
### Step 10: Home Screen
> **Screenshot**: The Archipelago dashboard with glass-card layout — system status, Bitcoin sync progress, quick actions.
The home screen shows:
- **System status**: CPU, RAM, disk usage, uptime
- **Bitcoin sync progress**: Block height, peer count, sync percentage
- **Quick actions**: Start/stop apps, check notifications
- **Node identity**: Your DID and Nostr public key
### Step 11: My Apps
> **Screenshot**: The Apps page showing installed containers as glass cards — Bitcoin Knots (running), LND (running), Mempool (stopped).
- View all installed applications
- **Green dot**: Running
- **Red dot**: Stopped
- Click an app to see details, logs, and actions
- Start/stop apps with one click
### Step 12: App Details
> **Screenshot**: Bitcoin Knots detail page showing sync status, peer count, block height, and action buttons.
Each app detail page shows:
- Container status and health
- Live logs (scrollable)
- Start / Stop / Restart buttons
- Launch button (opens the app's own UI in a new tab)
- Resource usage
### Step 13: Marketplace
> **Screenshot**: The Marketplace page with curated app cards — each showing name, description, and install button.
- Browse available applications
- Install with one click
- Apps are verified containers with security hardening
- Categories: Bitcoin, Lightning, Home, Nostr, Other
### Step 14: Cloud (File Manager)
> **Screenshot**: The Cloud page showing folders (Documents, Photos, Music) with breadcrumb navigation.
- Browse files stored on your node
- Upload and download files
- Organized with breadcrumb navigation
- Files are stored locally — not in the cloud
### Step 15: Server Status
> **Screenshot**: The Server page showing CPU/RAM/Disk gauges, Tor status, and network information.
- Real-time system metrics
- Tor connectivity status and .onion address
- DNS configuration
- VPN status
- Federation peers (if configured)
### Step 16: Web5 Identity
> **Screenshot**: The Web5 page showing DID document, Nostr public key, and credential management.
- View your decentralized identity (DID)
- Manage verifiable credentials
- Publish your identity to Nostr relays
- Create and verify presentations
### Step 17: Settings
> **Screenshot**: The Settings page with sections for password, appearance, system update, and shutdown.
- Change password
- Configure TOTP two-factor authentication
- Check for system updates
- Restart or shutdown the server
- Reset onboarding (for testing)
---
## Part 5: Advanced Operations
### Accessing via Tor
> **Screenshot**: Browser showing the .onion address in the Tor Browser URL bar.
1. Install [Tor Browser](https://torproject.org)
2. Find your .onion address in Settings > Server
3. Access your node from anywhere in the world via Tor
### Federation (Multi-Node)
> **Screenshot**: Federation page showing connected peer nodes with status indicators.
1. Generate an invite code from Server > Federation
2. Share the code with a trusted peer
3. They join using the code on their node
4. Monitor peer status and deploy apps remotely
### Hardware Wallet Integration
> **Screenshot**: PSBT signing flow — creating a transaction, scanning QR with hardware wallet.
1. Create a PSBT (Partially Signed Bitcoin Transaction) from Web5
2. Transfer to your hardware wallet (QR code or file)
3. Sign on the hardware wallet
4. Import the signed PSBT back to finalize and broadcast
### Controller / Gamepad Navigation
Archipelago supports Xbox-style controller navigation throughout the UI.
#### Global Controls
| Button | Action |
|--------|--------|
| D-pad Up/Down | Navigate between elements |
| D-pad Left/Right | Move between zones (sidebar ↔ content) |
| A / Enter | Select / activate / enter container |
| B / Escape | Go back / exit container / return to sidebar |
#### Navigation Zones
**Sidebar** (left column — always visible on desktop):
- Up/Down = move between items (wraps), auto-navigates page links
- Right = enter main content (first container, or first button on container-free pages)
- Left = nothing
**Nav Bar** (mode-switcher tabs at top of content — e.g. My Apps / App Store / Services):
- Left/Right = move between tabs
- Down = jump to first card/container below (remembers tab for Up return)
- Up = nothing (Escape to sidebar)
- Left from leftmost = sidebar
**Container Grid** (card tiles — Apps, Discover, Network, Home):
- Arrows = spatial navigation between cards
- Enter = primary action (Install, Launch, or enter inner controls)
- Escape = sidebar
- Left from leftmost card = sidebar
- Up from top row = return to remembered nav bar tab
**Inside Container** (after Enter on a card — inner buttons/controls):
- Arrows = move between inner controls
- Escape = exit back to the card
- Cannot leave via arrows — must Escape first
**Text Inputs** (search bars, form fields):
- Up/Down = exit field, navigate to nearest element
- Enter = submit (clicks the next button)
- Left/Right = cursor movement (exits field at edges)
#### Per-Page Mapping
**Home** (`/dashboard`)
- Right from sidebar → first status card
- D-pad navigates between status cards spatially
- Enter on card → navigates to that section
**My Apps** (`/dashboard/apps`)
- Right from sidebar → first app card
- D-pad navigates app card grid spatially
- Enter on card → app details page
- Enter on focused card with Launch button → launches app
**App Store / Discover** (`/dashboard/discover`)
- Right from sidebar → first featured card
- D-pad navigates card grid (Sovereignty Stack + All Applications)
- Down from nav tabs → first card below
- Up from top card → returns to last-focused tab
- Enter on card → app detail / install
- Cards lift on hover/focus (same as My Apps)
**Network** (`/dashboard/server`)
- Right from sidebar → Quick Actions card
- D-pad navigates between cards: Quick Actions → Local Network / Web3 → Network Interfaces / Tor Services
- Enter on Quick Actions → enters inner buttons (Restart, Check Tor, View Logs)
- Escape from inner buttons → back to card
- All cards lift on hover/focus
**Settings** (`/dashboard/settings`) — **Linear navigation, no containers**
- Right from sidebar → first button (server name row)
- D-pad Up/Down steps through ALL buttons/controls top-to-bottom:
1. Server Name / What's New
2. Copy DID
3. Copy Onion Address
4. Change Password
5. Enable/Disable 2FA
6. Logout
7. Choose Language
8. Login with Claude
9. AI Data Access toggles (each enable/disable row)
10. Manage Updates
11. Webhook URL input
12. Webhook Secret input
13. Container Crash / Update Available toggles
14. Disk Space Warning / Backup Complete toggles
15. Save Configuration / Send Test Webhook
16. Enable Beta Telemetry
17. Create Backup
18. Export Channel Backup
19. Network Diagnostics
20. Reboot
21. Factory Reset
- Enter = activates the focused button/toggle
- Escape / Left = sidebar
**Mesh** (`/dashboard/mesh`)
- Right from sidebar → Device status card (left column)
- D-pad navigates between left-column containers (Device, Actions, Peers)
- Enter on peer → opens chat, auto-focuses message input
- Type message + Enter = send
- Escape = close chat / back to sidebar
**Cloud** (`/dashboard/cloud`)
- Right from sidebar → first folder/file card
- D-pad navigates file grid spatially
- Enter = open folder / file details
**Detail Pages** (app details, marketplace app details):
- Escape / B = go back to previous page
---
## Part 6: Maintenance
### Regular Tasks
| Task | Frequency | How |
|------|-----------|-----|
| Check for updates | Weekly | Settings > System Update |
| Review app health | Daily (glance) | Home screen status cards |
| Backup | Monthly | Settings > Backup |
| Check disk space | Monthly | Server status page |
### Updating Archipelago
1. Go to Settings > System Update
2. Click "Check for Updates"
3. If available, click "Install Update"
4. The system restarts automatically — do not power off during update
### Creating a Backup
1. Go to Settings > Backup
2. Enter a passphrase (remember this!)
3. Click "Create Backup"
4. Download the backup file and store it safely offline
---
## Quick Reference
| Action | Where |
|--------|-------|
| Start/stop an app | My Apps > App Card > Start/Stop |
| Install new app | Marketplace > Find App > Install |
| Check system health | Home or Server page |
| Change password | Settings > Security |
| Enable 2FA | Settings > Security > TOTP |
| View logs | My Apps > App > Logs |
| Access via Tor | Settings > Server > Tor Address |
| Restart server | Settings > System > Restart |
| Create backup | Settings > Backup |
docs/workstream-b-signing-runbook.md
+90
View File
@@ -0,0 +1,90 @@
# Workstream B — Signed app-catalog: completion runbook
**Status: ✅ COMPLETE** (runbook retained for re-running the ceremony — key
rotation, a new publisher, or a fresh release root).
The ceremony described below has been performed. Verified 2026-08-08:
- The anchor is **pinned** — `trust::anchor::RELEASE_ROOT_PUBKEY_HEX` is a
`Some(...)`, not `None`.
- `releases/app-catalog.json` carries a `signature` and a `signed_by` did:key.
Everything below therefore describes how to *do* the ceremony, not work that is
outstanding. The one-way-door warning in "Why this is gated on you" still
applies in full to any re-run: once a binary pins an anchor, a catalog signed by
a different key is hard-rejected fleet-wide.
---
**Original status (2026-06-28):** The registry-distributed manifest pipeline is live — nodes fetch
`releases/app-catalog.json` from the OTA mirror and embed manifests (origin-wins, disk
fallback). What remains for Workstream B is **authenticity**: pin the release-root anchor and
ship a *signed* catalog so nodes can cryptographically verify the publisher.
Today the catalog is **accepted unsigned** ("migration window") and the anchor is **unpinned**
(`core/archipelago/src/trust/anchor.rs` → `RELEASE_ROOT_PUBKEY_HEX = None`). Completing B is
a coordinated ceremony that **only the publisher can run** — it needs the offline
`RELEASE_MASTER_MNEMONIC`, which is not (and must not be) stored on any node or build host.
## Why this is gated on you (not automatable)
- The signing key is an **offline mnemonic** you hold (`archipelago ceremony gen` output, backed
up offline / via `seed.reveal`). It is intentionally absent from the repo and all hosts.
- Order matters: once a binary **pins** the anchor, a catalog carrying a signature from the
*wrong* key is **hard-rejected fleet-wide** (`trust/signed_doc.rs:79`). Unsigned and
correctly-signed catalogs are both accepted; only a *mismatched* signature breaks nodes.
- So the pinned pubkey and the signature MUST come from the same key, shipped consistently.
## The ceremony (run from `core/`, with your mnemonic)
```bash
# 0. (only if you don't already have a release-root key) generate one and back the
# mnemonic up OFFLINE. Prints the pubkey hex + signer did:key.
cargo run --release -p archipelago -- ceremony gen
# 1. Print the release-root pubkey hex for the anchor (idempotent; same mnemonic → same key)
RELEASE_MASTER_MNEMONIC="word1 word2 …" cargo run --release -p archipelago -- ceremony pubkey
# → copy the 64-char hex.
# 2. Pin it in code:
# core/archipelago/src/trust/anchor.rs:21
# - pub const RELEASE_ROOT_PUBKEY_HEX: Option<&str> = None;
# + pub const RELEASE_ROOT_PUBKEY_HEX: Option<&str> = Some("<64-char-hex-from-step-1>");
# 3. Sign the published catalog in place (inserts `signature` + `signed_by` over the
# canonical JSON — re-run after ANY catalog regen, since signing covers the exact bytes):
RELEASE_MASTER_MNEMONIC="word1 word2 …" \
cargo run --release -p archipelago -- ceremony sign releases/app-catalog.json
# 4. Verify locally before shipping (optional sanity): a node build with the pinned anchor
# should log "app-catalog: release-root signature verified (<did>)" rather than
# "self-consistent but anchor not pinned".
```
## Ship order (backward-compatible)
1. Commit the **signed** `releases/app-catalog.json` + the `anchor.rs` change together.
2. Push the signed catalog to the OTA mirror (gitea-vps2 `main`) — old binaries (no pinned
anchor) still accept it (verified-but-unconfirmed); nothing breaks.
3. Build + OTA the binary with the pinned anchor. New nodes now **verify** the catalog against
the anchor. (This is the normal release path — gate the tag per the ship-ritual.)
4. **Later / optional hardening:** once the whole fleet is on the pinned-anchor binary, flip
the policy from "accept unsigned (migration window)" to "reject unsigned" in
`container/app_catalog.rs` (the `SignatureStatus::Unsigned` arm). Do this LAST — while any
node still runs an unsigned catalog it must keep being accepted.
## Env-override escape hatch (no rebuild)
For staging/canary you can pin the anchor without editing code via
`ARCHY_RELEASE_ROOT_PUBKEY=<hex>` (`trust/anchor.rs:23`) on a single node, then sign the catalog
and confirm that node verifies it before baking the constant in.
## What's already done (so this is the only remaining step)
- Catalog distribution + manifest embedding: live (this session's `169ff2e2` published the
corrected catalog to the mirror).
- `ceremony gen|pubkey|sign` tooling: shipped (`core/archipelago/src/ceremony.rs`).
- Verify path: `trust::verify_detached` accepts unsigned, verifies signed against the anchor,
hard-rejects mismatches (`trust/signed_doc.rs`).
- Detached-signature schema fields (`signature`/`signed_by`) already part of the signed
preimage (`container/app_catalog.rs`).