Skip to content

Latest commit

 

History

History
97 lines (71 loc) · 4.13 KB

key-rotation.md

File metadata and controls

97 lines (71 loc) · 4.13 KB

Key Rotation

Procedures for rotating encryption keys and secrets in this repository.

Age Key Rotation

Rotate the age encryption key when: a team member leaves, key compromise is suspected, or on schedule.

Add a new key (expand recipients)

# 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 an old key (revoke access)

  1. Remove the public key from .sops.yaml
  2. Re-encrypt all files:
    sops updatekeys secrets/production.env
    sops updatekeys clusters/production/hosts.enc.yaml
  3. The removed key can no longer decrypt future versions of these files
  4. Important: if the removed key was compromised, also rotate all secret values (see below)

Secret Rotation

Rotate a CARTO basemap browser key

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_KEY

Then 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.

Edit a single secret

# Opens your $EDITOR with decrypted values; re-encrypts on save
sops secrets/production.env

Rotate all secrets after a compromise

If the age private key was compromised, all encrypted values are potentially exposed. Rotate everything:

  1. Rotate the age key (see above)
  2. Rotate all credential values:
    • Database passwords: Change in production.env, then run frameworks cluster provision --only infrastructure to 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 in production.env
    • x402 gas wallet (X402_GAS_WALLET_PRIVKEY): Reconcile pending settlements, replace the key and X402_GAS_WALLET_ADDRESS together, 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 through frameworks crypto wallet rotate --xpub-file <file> --network mainnet; retain every retired xprv offline because previously issued addresses can receive late transfers
  3. 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.

Rotate host IPs

sops clusters/production/hosts.enc.yaml
# Edit the IPs, save — file is re-encrypted automatically

Recovery

If the primary age key is lost but a recovery key exists:

  1. Decrypt using the recovery key: SOPS_AGE_KEY_FILE=/path/to/recovery-key.txt sops -d secrets/production.env
  2. Generate a new primary key: age-keygen -o new-primary.txt
  3. Update .sops.yaml with the new primary public key (replacing the lost one)
  4. Re-encrypt all files: sops updatekeys secrets/production.env && sops updatekeys clusters/production/hosts.enc.yaml

Adding a Team Member

  1. Have them generate an age keypair: age-keygen
  2. Add their public key to .sops.yaml (comma-separated)
  3. Re-encrypt: sops updatekeys on all encrypted files
  4. They can now decrypt with their private key