Auth credential rotation runbook

This runbook is the authoritative process for rotating exposed launch secrets,

including `AUTH_SECRET`, `AUTH_GITHUB_SECRET`, `DATABASE_URL`, AI/provider API

keys, and staging smoke override tokens.

Why this exists

• Prevent long-lived session-signing keys.
• Keep GitHub OAuth secrets out of stale environments.
• Preserve a stable evidence trail for operational sign-off and incident recovery.

Rotation steps

• Generate a fresh local auth secret:

openssl rand -base64 32

`METAMUSEUM_TEST_ROLE_OVERRIDE_TOKEN` in every local, CI, and deployment

secret store where they were present.

`security.secretRotation` and `security.secretHistory` rows before public

launch.

• Update `AUTH_SECRET` in platform secret store and the target deployment environment.
• Generate/rotate `AUTH_GITHUB_SECRET` in the linked GitHub OAuth app dashboard.
• Rotate any exposed database URL/password, AI/provider API keys, and
• Record the non-secret preflight evidence:
• `METAMUSEUM_SECRET_ROTATION_CONFIRMED_AT=<ISO timestamp or date>`
• `METAMUSEUM_SECRET_ROTATION_KEYS=AUTH_SECRET,AUTH_GITHUB_SECRET,DATABASE_URL,ANTHROPIC_API_KEY,SMITHSONIAN_API_KEY,METAMUSEUM_TEST_ROLE_OVERRIDE_TOKEN`
• Roll the app deployment so all instances consume the new secrets.
• Verify the repo does not track or retain sensitive env files:
• `git ls-files -- .env .env.local .env.production .env.production.local`
• `git log --full-history --format=%h --all -- .env .env.local .env.production .env.production.local`
• Validate a non-admin protected write path and a public read path (e.g., sign in, then call a write route with the correct role).
• Confirm old secret values are removed from:
• `.env*` files checked into source control,
• CI cache/snapshot artifacts,
• local shell histories and docs.
• Run `pnpm launch:preflight:production`; the artifact must include passing

Evidence required for closeout

• Date of change:
• Owner:
• Deployment target:
• Verification command(s):
• `pnpm session:closeout --summary "AUTH credential rotation completed"`
• `pnpm launch:preflight:production`
• `/api/health` (manual smoke to confirm auth-gated paths are healthy)
• Evidence artifact:
• Roadmap operational sign-off section entry (`docs/roadmap.md` → `Pre-Era-C Operational Sign-Off`)
• Runbook completion record in release notes/runbook (this file + execution log in your normal runbook location)

Recurring check

• Re-run this runbook at or before each major operational checkpoint and record date/owner in the operational sign-off section.