vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(swarm): state the secrets rule precisely instead of carving an exception

Browse source 
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.
This commit is contained in:
atlas 2026-08-16 16:21:46 +02:00
commit 4114d6898b
1 changed files with 11 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

23
docs/swarm/secrets.md
View file

@ -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