From 2c53a7d77f99b63e6dc3ba4c79177971fb9f6111 Mon Sep 17 00:00:00 2001 From: archipelago Date: Fri, 7 Aug 2026 20:51:53 -0400 Subject: [PATCH] docs: fix the CSRF-exempt list and describe how secret_env actually reaches a container MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **COMMANDS.md** named six CSRF-exempt read-only methods, two of which (`bitcoin.getinfo`, `monitoring.current`) are not exempt — a client trusting the doc would send them with the cookie alone and get rejected. The real set is twelve (`api/rpc/mod.rs:326-340`); listed all of them and said plainly that everything else needs the header. The rest of the doc verified clean: the 480 / 200 / 160-char caps, the four `assistant_*` config keys, both default model ids, `is_sender_allowed`, `strip_archy_trigger` / `run_node_cmd`, the three unauthenticated HTTP endpoints, and `auth.login.totp` all match the code. **secrets.md** said `secret_env` "sets `` in the container's environment", which reads as a plain `-e KEY=value` and undersells the design. It isn't: resolved pairs are registered as podman secrets named `archy-env--` and referenced by name, precisely so the value stays out of `podman inspect` and out of plaintext `Environment=` lines in Quadlet units. Also documented the interpolation-taint rule — a plain `environment` entry that expands `${SECRET}` (BTCPay's connection strings) is itself treated as secret-bearing rather than left in the clear, which is what makes it safe to build connection strings from secrets. Everything else in secrets.md verified against `container/secrets.rs`: the four kinds and their file shapes, the bare-filename rule, the every-tick idempotent `ensure_generated_secrets`, and the atomic 0600 temp-fsync-rename writer. Co-Authored-By: Claude Opus 5 (1M context) --- docs/COMMANDS.md | 6 +++++- docs/secrets.md | 14 ++++++++++++-- 2 files changed, 17 insertions(+), 3 deletions(-) diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index 87a9a224..7f7e2179 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -130,7 +130,11 @@ curl -s http:///rpc/v1 -b jar.txt -H 'Content-Type: application/json' \ -d '{"method":"system.stats","params":{}}' ``` -Login returns a `session` cookie. Read-only methods (`system.stats`, `system.get-metrics`, `bitcoin.getinfo`, `monitoring.current`, `bitcoin.relay-status`, `tor.status`) are CSRF-exempt, so the cookie alone is enough; state-changing calls also need the `X-CSRF-Token` header. If TOTP is enabled, follow the login with `auth.login.totp`. +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`. --- diff --git a/docs/secrets.md b/docs/secrets.md index 5a761bf3..5009fce5 100644 --- a/docs/secrets.md +++ b/docs/secrets.md @@ -60,8 +60,18 @@ container: ``` At apply time the orchestrator reads `/var/lib/archipelago/secrets/` -and sets `` in the container's environment to its contents. The value is -never written into the manifest, the Quadlet unit, or any log line. +and makes it available in the container as ``. 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--` 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