From 4114d6898b61e8614662b1f9b51aa14f5a9187ca Mon Sep 17 00:00:00 2001 From: atlas Date: Sun, 16 Aug 2026 16:21:46 +0200 Subject: [PATCH] docs(swarm): state the secrets rule precisely instead of carving an exception Review: the public keys are not an exception, the paragraph was incomplete. It is private key material and access tokens that are file-based so they stay out of the nix store; public material in a public store is fine. Fixes the rule itself, which removes the need for the special case the previous commit added. --- docs/swarm/secrets.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/swarm/secrets.md b/docs/swarm/secrets.md index f43683e2..8c670efc 100644 --- a/docs/swarm/secrets.md +++ b/docs/swarm/secrets.md @@ -6,11 +6,16 @@ This page is that answer, one row per secret. Two rules run through all of it. -**A secret is a path, never a value.** Every option that carries a credential -takes a file path (`*File`), because a literal written into a nix expression is -rendered into the nix store — which is world-readable and permanent. There is no -option anywhere in this tree that accepts a secret inline, and adding one would -be a leak rather than a convenience. +**Private key material and access tokens are paths, never values.** Every option +carrying one takes a file path (`*File`), because a literal written into a nix +expression is rendered into the nix store — world-readable and permanent. No +option in this tree accepts one inline, and adding one would be a leak rather +than a convenience. + +The rule is about what must stay secret, not about credentials generally. +**Public material is a value**: a certificate, or a public nkey like +`swarm.nats.calloutUserPublicKey`, is published to every client that connects, +so the store is a perfectly good place for it. **The generator and the reader are usually in different containers.** They share the host's network namespace, which makes them feel co-located, but their @@ -51,13 +56,7 @@ because nothing outside that container ever reads them. **That is the test worth applying to any secret added here** — and the client secret's plaintext half is the one row that fails it, which is the entire reason a delivery step exists. -### The queue's public keys are values, not paths - -`nats.calloutUserPublicKey` and `nats.calloutIssuerPublicKey` take a value -rather than a file path, and that is not an exception to the rule at the top of -this page. A public nkey is published to every client that connects; being -widely known is its job. The matching **seeds** are the secrets, are named only -as paths, and reach the callout responder and nothing else. +### Minting the queue's callout nkeys `nats.autoGenerateCallout` mints both keypairs on the host before the queue starts. It is on by default only under `enableAllLocalDefaults` — the one