Configure Secret Backends

CARACAL_SECRET_BACKEND selects storage for user-entered credentials. It does not replace runtime secret delivery. Values are envelope-encrypted under SECRET_STORE_KEK before backend storage.

Choose a Backend

Implemented identifiers are builtin, vault, infisical, azurekeyvault, awssecretsmanager, gcpsecretmanager, and custom. builtin stores envelopes in Postgres. External backends require their documented endpoint, identity, project/region, or token variables on API and STS.

Safe Procedure

1. Back up Postgres, runtime secrets, and external backend data.
2. Configure one backend on API and STS with the same KEK.
3. Restart API and STS; wait for readiness.
4. Create a disposable provider credential and perform a token exchange.
5. Verify backend operation/error metrics and delete the disposable object.

STS caches external reads for 60 seconds and may serve stale cached data for up to 10 minutes during errors. It never falls back to another backend.

KEK Rotation

Deploy the replacement as SECRET_STORE_KEK and retiring value as SECRET_STORE_KEK_PREVIOUS. Run node apps/api/scripts/rotate-secret-store-kek.mjs from a checkout with the API service’s environment (the script ships beside the API service), verify zero failures, then remove the previous key and restart API and STS.

Permanent credential loss

Removing the retiring KEK before all envelopes are re-sealed makes remaining envelopes unreadable.

Backend Migration and Recovery

Use node apps/api/scripts/migrate-secret-backend.mjs <target-kind> from the same environment while the source remains configured. Switch services only after copying succeeds. On failure, keep the source selected and rerun; do not create a fallback chain.

Next Step

Plan dependent rotations in Rotate Keys and Secrets.