{"id":"ops/auth-credential-rotation","relativePath":"ops/auth-credential-rotation.md","title":"Auth credential rotation runbook","markdown":"# Auth credential rotation runbook\n\nThis runbook is the authoritative process for rotating exposed launch secrets,\nincluding `AUTH_SECRET`, `AUTH_GITHUB_SECRET`, `DATABASE_URL`, AI/provider API\nkeys, and staging smoke override tokens.\n\n## Why this exists\n\n- Prevent long-lived session-signing keys.\n- Keep GitHub OAuth secrets out of stale environments.\n- Preserve a stable evidence trail for operational sign-off and incident recovery.\n\n## Rotation steps\n\n- Generate a fresh local auth secret:\n\n```bash\nopenssl rand -base64 32\n```\n\n- Update `AUTH_SECRET` in platform secret store and the target deployment environment.\n- Generate/rotate `AUTH_GITHUB_SECRET` in the linked GitHub OAuth app dashboard.\n- Rotate any exposed database URL/password, AI/provider API keys, and\n `METAMUSEUM_TEST_ROLE_OVERRIDE_TOKEN` in every local, CI, and deployment\n secret store where they were present.\n- Record the non-secret preflight evidence:\n - `METAMUSEUM_SECRET_ROTATION_CONFIRMED_AT=`\n - `METAMUSEUM_SECRET_ROTATION_KEYS=AUTH_SECRET,AUTH_GITHUB_SECRET,DATABASE_URL,ANTHROPIC_API_KEY,SMITHSONIAN_API_KEY,METAMUSEUM_TEST_ROLE_OVERRIDE_TOKEN`\n- Roll the app deployment so all instances consume the new secrets.\n- Verify the repo does not track or retain sensitive env files:\n - `git ls-files -- .env .env.local .env.production .env.production.local`\n - `git log --full-history --format=%h --all -- .env .env.local .env.production .env.production.local`\n- 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).\n- Confirm old secret values are removed from:\n - `.env*` files checked into source control,\n - CI cache/snapshot artifacts,\n - local shell histories and docs.\n- Run `pnpm launch:preflight:production`; the artifact must include passing\n `security.secretRotation` and `security.secretHistory` rows before public\n launch.\n\n## Evidence required for closeout\n\n- Date of change:\n- Owner:\n- Deployment target:\n- Verification command(s):\n - `pnpm session:closeout --summary \"AUTH credential rotation completed\"`\n - `pnpm launch:preflight:production`\n - `/api/health` (manual smoke to confirm auth-gated paths are healthy)\n- Evidence artifact:\n - Roadmap operational sign-off section entry (`docs/roadmap.md` → `Pre-Era-C Operational Sign-Off`)\n - Runbook completion record in release notes/runbook (this file + execution log in your normal runbook location)\n\n## Recurring check\n\n- Re-run this runbook at or before each major operational checkpoint and record date/owner in the operational sign-off section.\n","sections":[{"level":2,"heading":"Why this exists","anchor":"why-this-exists"},{"level":2,"heading":"Rotation steps","anchor":"rotation-steps"},{"level":2,"heading":"Evidence required for closeout","anchor":"evidence-required-for-closeout"},{"level":2,"heading":"Recurring check","anchor":"recurring-check"}],"html":"

Auth credential rotation runbook

\n

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

\n

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

\n

keys, and staging smoke override tokens.

\n

Why this exists

\n\n

Rotation steps

\n\n
\nopenssl rand -base64 32\n
\n

`METAMUSEUM_TEST_ROLE_OVERRIDE_TOKEN` in every local, CI, and deployment

\n

secret store where they were present.

\n

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

\n

launch.

\n\n

Evidence required for closeout

\n\n

Recurring check

\n","updatedAt":"2018-10-20T01:46:40.000Z","checksum":"76e3fc6daefa6a80717760a035e3e88b28398e5e5120ca8789bb95b9d533d27a","checksumPrefix":"76e3fc6daefa","anchorCount":4,"lineCount":58,"rawUrl":"/api/docs/content?path=ops%2Fauth-credential-rotation.md","htmlUrl":"/docs?doc=ops%2Fauth-credential-rotation.md","apiUrl":"/api/docs/content?path=ops%2Fauth-credential-rotation.md"}