Procedures for rotating encryption keys and secrets in this repository.
Rotate the age encryption key when: a team member leaves, key compromise is suspected, or on schedule.
# Generate new age keypair
age-keygen -o new-key.txt
# Note the public key: age1...
# Add the new public key to .sops.yaml (comma-separated in the age: field)
# Then re-encrypt all files with the updated recipient list:
sops updatekeys secrets/production.env
sops updatekeys clusters/production/hosts.enc.yaml- Remove the public key from
.sops.yaml - Re-encrypt all files:
sops updatekeys secrets/production.env sops updatekeys clusters/production/hosts.enc.yaml
- The removed key can no longer decrypt future versions of these files
- Important: if the removed key was compromised, also rotate all secret values (see below)
Chartroom uses secrets/chartroom.env; Foredeck uses
secrets/foredeck.env. Update each browser app through a hidden prompt:
scripts/sops-env.sh set secrets/chartroom.env CARTO_BASEMAP_BROWSER_KEY
scripts/sops-env.sh set secrets/foredeck.env CARTO_BASEMAP_BROWSER_KEYThen run frameworks cluster provision --only interfaces. The value is
intentionally visible in the browser, but must not appear in plaintext Git,
build arguments, or logs.
# Opens your $EDITOR with decrypted values; re-encrypts on save
sops secrets/production.envIf the age private key was compromised, all encrypted values are potentially exposed. Rotate everything:
- Rotate the age key (see above)
- Rotate all credential values:
- Database passwords: Change in
production.env, then runframeworks cluster provision --only infrastructureto apply - API keys (Stripe, Cloudflare, etc.): Regenerate in each provider's dashboard, update in
production.env - Auto-generated secrets (JWT_SECRET, SERVICE_TOKEN, etc.): Generate new values with
openssl rand -hex 32, update inproduction.env - x402 gas wallet (
X402_GAS_WALLET_PRIVKEY): Reconcile pending settlements, replace the key andX402_GAS_WALLET_ADDRESStogether, fund the replacement with native gas on Base and Arbitrum, then remove residual funds from the retired wallet - Sweep relayers (
CRYPTO_SWEEP_RELAYER_PRIVATE_KEY_<NETWORK>): Pause sweep broadcasts for that network, reconcile pending transactions, replace the encrypted key, fund the replacement with native gas, then resume; never use a treasury owner or HD deposit key - HD deposit key (
HD_WALLET_XPUB): Rotate throughframeworks crypto wallet rotate --xpub-file <file> --network mainnet; retain every retired xprv offline because previously issued addresses can receive late transfers
- Database passwords: Change in
- Re-provision all services:
frameworks cluster provision
Readiness derives every configured relayer address from its encrypted private
key at runtime and checks live one-transaction gas runway. Treasury rotation is
independent: update CRYPTO_TREASURY_<NETWORK> for future sweep manifests, let
old unbroadcast manifests expire/release, and move assets already held by the
old treasury through the treasury's own approved transaction.
sops clusters/production/hosts.enc.yaml
# Edit the IPs, save — file is re-encrypted automaticallyIf the primary age key is lost but a recovery key exists:
- Decrypt using the recovery key:
SOPS_AGE_KEY_FILE=/path/to/recovery-key.txt sops -d secrets/production.env - Generate a new primary key:
age-keygen -o new-primary.txt - Update
.sops.yamlwith the new primary public key (replacing the lost one) - Re-encrypt all files:
sops updatekeys secrets/production.env && sops updatekeys clusters/production/hosts.enc.yaml
- Have them generate an age keypair:
age-keygen - Add their public key to
.sops.yaml(comma-separated) - Re-encrypt:
sops updatekeyson all encrypted files - They can now decrypt with their private key