Skip to main content
← Back to list
01Issue
FeatureClosedSwamp ClubPublic
AssigneesNone

Relationships

#2539 Docs: serve token-secrets external key opt-in (swamp-club#2324)

Opened by stack72 · 9/25/2026

swamp-club#2324 adds an opt-in serve.yaml block that keeps the _token-secrets encryption key outside the datastore:

token-secrets:
  vault: prod-secrets        # any user vault except _token-secrets
  key: swamp-token-secrets-key

Pages to update:

  • content/manual/reference/swamp-serve (serve config reference): the new token-secrets block, fields, key format (32 bytes, hex or base64, generated by the operator with a CSPRNG such as openssl rand -base64 32), read once at startup.
  • content/manual/reference/swamp-serve/access-commands.md: it describes _token-secrets; add that by default the key sits beside the secrets in the datastore (datastore read access decrypts every token), how to opt in, and that local access token mint/rotate/reveal read the block from .swamp/serve.yaml and refuse without it once the control plane is migrated.
  • content/manual/reference/remote-execution/worker-commands.md: worker token create stores secrets in _token-secrets; same note.
  • A how-to (swamp-serve how-to or vaults): enabling the external key on an existing deployment. Steps: generate the key, store it in a vault whose storage is outside the datastore (identical on every instance and every host running local token commands), add the block, run swamp serve check-config, restart all instances together, then rotate tokens minted before the change and delete old copies (datastore backups, noncurrent object versions on versioned buckets, and root-level _control/token-secrets/ left by a namespace migration). There is no way back to a co-located key.

The design reference is design/primitives/serve.md, section Identity and access, paragraph Token secrets key.

02Bog Flow
✓OPEN○TRIAGED○IN PROGRESS◉CLOSED

Closed

9/28/2026, 11:32:29 PM

No activity in this phase yet.

03Sludge Pulse
Editable. Press Enter to edit.

stack72 commented 9/28/2026, 11:32:29 PM

Documented in https://github.com/swamp-club/swamp-club/pull/1259. Added a token-secrets: block section to reference/swamp-serve/serve-flags.md and a 'Token secrets encryption key' section to access-commands.md, plus a note in worker-commands.md. New how-to: how-to/swamp-serve/keep-token-secrets-key-outside-datastore.md (generate and store the key, add the block, run serve check-config, restart all instances together, rotate old tokens and delete old copies). The check-config output shown was captured from a sandbox run.

Sign in to post a ripple.