Recovery operations

Backups and key rotation

A small, explicit operator workflow for encrypted backups, key changes and clean-room restore drills.

Simple by default

Provide the complete backup environment once. RustyAuth creates a verified logical backup after startup and every six hours by default, while signing keys rotate automatically with staged JWKS publication and retired-key overlap.

Operator commands

passkey-auth-service doctor
passkey-auth-service backup create
passkey-auth-service backup list
passkey-auth-service backup verify <object-key>
passkey-auth-service keys status
passkey-auth-service keys rotate

Commands print structured JSON receipts for automation and incident records. doctor checks configuration, the durable store, signing-key state and configured backup storage without exposing secret key material.

Signing keys

RustyAuth creates and stores ES256 signing keys, publishes the next public key before activation and keeps a retired public key available long enough for already-issued tokens to expire. The maintenance loop and a cross-process lease make this automatic; keys rotate is the intentional on-demand path.

Rotate the master key

Generate a new independent 32-byte key.
Set it as AUTH_MASTER_KEY_HEX and retain the old key in AUTH_MASTER_PREVIOUS_KEYS_HEX.
Restart each instance and confirm keys status succeeds.
Remove the old key only after every instance has rewrapped the stored signing-key material.

Backup encryption keys

Set the new key in AUTH_BACKUP_ENCRYPTION_KEY_HEX and retain the old key in AUTH_BACKUP_PREVIOUS_KEYS_HEX. Keep previous keys until every backup they protect has expired under retention policy or has been replaced by a verified recovery point.

Clean-room restore drill

passkey-auth-service backup verify <object-key>
passkey-auth-service backup restore <object-key>
passkey-auth-service doctor

Restore is an offline operation and accepts only an empty RustyAuth namespace in SableDB. By default it invalidates existing sessions, creates fresh signing-key material and records a recovery event. An in-progress sentinel prevents normal startup if the final security steps do not complete.

Preserve sessions only by exception

--preserve-sessions exists for a specifically reviewed incident response. The safe default is to make users authenticate again after recovery.

Before relying on a backup

Run restore drills against a new SableDB volume, retain the JSON receipts, run doctor, and complete a real passkey sign-in. Configuration and retention guidance live in the configuration reference; topology and deployment guidance live in the deployment guide.