secrets #
in a small setup, secrets leak by being displayed during ordinary work: a run page that renders configuration, a command that prints an env file, an agent transcript. so one encrypted store holds each value, every runtime copy is derived from it, and values move between them without being shown.
the store and its consumers #
a sops file encrypted with age, in a local git repository with no remote, is
the store. each machine that decrypts it has its own age key, and key files
never leave their machines. on macOS, sops reads
~/Library/Application Support/sops/age/keys.txt, not
~/.config/sops/age/keys.txt; keep both identical.
anything holding a value at runtime (a worker's env file, a CI secret table, a
platform secret store, an orchestrator's secret block) is a consumer derived
from the store. a hand edit to a consumer lands in the store the same day, or
drift detection stops meaning anything. a status check compares each consumer
to the store by sha256 and exits non-zero on a difference; a sync step writes
values out and is a no-op on a second run. a new consumer is proven by changing it by
hand and watching status catch it and sync repair it.
byte equality proves synchronization, not the intended recipient. a consumer and its canonical reference can agree perfectly while both still point at the old API. read the intended entry back, assert the endpoint/account and role, then perform one allowed and one refused operation with the actual consumer.
platforms that already store secrets well keep their own surfaces until one causes trouble or blocks a rotation; every absorbed surface is maintenance. a password manager that asks for a biometric approval on each read cannot sit behind automation, but can hold a recovery copy.
moving a value without displaying it #
hand values to the next program on stdin, never as an argument, which shows up
in process listings and shell history: sops set --value-stdin (the value
must be JSON, so encode a string with jq -Rs),
kubectl create secret generic --from-file=key=/dev/stdin,
gh secret set NAME, fly secrets import. a value shown once in a web UI goes
clipboard → pbpaste | jq -Rs 'rtrimstr("\n")' | sops set --value-stdin ...,
then the clipboard is cleared.
SOPS nested index paths use successive segments, such as
["service"]["token"]. the comma-array form ["service", "token"] is not an
equivalent path: SOPS 3.13.3 accepts it as a literal key rather than updating
the nested entry. check the decrypted object's intended keys in memory after
an edit, including that no unexpected sibling keys appeared; a successful
command exit is not proof that the intended reference changed.
check a value by length and prefix, two copies by a sha256 prefix, and a token
by the provider's verify endpoint or one refused and one allowed call.
temporary files get umask 077 and are deleted by the command that made them.
an orchestrator shows whatever its run configuration contains, so a token in a deployment's job variables appears on every run page. a reference to a secret block, resolved when the run starts, keeps it out.
rotation #
for each credential, the store's README answers: could it be replaced now, with one command on each side, and the consumer confirmed working? a yes is written as those commands, a no as exactly what is missing. narrow scope at creation makes the answer easier: a token limited to DNS edits in one zone can be rolled without first finding out what else used it.
sources #
- secrets store README and rotation answers,
~/tangled.org/zzstoatzz.io/secrets, 2026-08 to 2026-10; job-variables display in prefect run configuration, 2026-08-23. - cert-manager DNS-01 token stored with
sops set --value-stdinand applied withkubectlfrom stdin, my-prefect-serverdocs/tailnet-only.md, 2026-10-21; Tailscale trust credential secrets moved from the admin console by clipboard, 2026-10-22. - SOPS 3.13.3 nested-index behavior and canonical/consumer agreement checked
during the MPS CI migration, my-prefect-server
docs/migrations/2026-10-27-remaining-cutover.md, 2026-10-27.