{"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 `AUTH_SECRET` and `AUTH_GITHUB_SECRET`.\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- Roll the app deployment so all instances consume the new secrets.\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\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  - `/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":"<h1 id=\"auth-credential-rotation-runbook\">Auth credential rotation runbook</h1>\n<p>This runbook is the authoritative process for rotating `AUTH_SECRET` and `AUTH_GITHUB_SECRET`.</p>\n<h2 id=\"why-this-exists\">Why this exists</h2>\n<ul><li>Prevent long-lived session-signing keys.</li><li>Keep GitHub OAuth secrets out of stale environments.</li><li>Preserve a stable evidence trail for operational sign-off and incident recovery.</li></ul>\n<h2 id=\"rotation-steps\">Rotation steps</h2>\n<ul><li>Generate a fresh local auth secret:</li></ul>\n<pre><code>\nopenssl rand -base64 32\n</code></pre>\n<ul><li>Update `AUTH_SECRET` in platform secret store and the target deployment environment.</li><li>Generate/rotate `AUTH_GITHUB_SECRET` in the linked GitHub OAuth app dashboard.</li><li>Roll the app deployment so all instances consume the new secrets.</li><li>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).</li><li>Confirm old secret values are removed from:</li><li>`.env*` files checked into source control,</li><li>CI cache/snapshot artifacts,</li><li>local shell histories and docs.</li></ul>\n<h2 id=\"evidence-required-for-closeout\">Evidence required for closeout</h2>\n<ul><li>Date of change:</li><li>Owner:</li><li>Deployment target:</li><li>Verification command(s):</li><li>`pnpm session:closeout --summary &quot;AUTH credential rotation completed&quot;`</li><li>`/api/health` (manual smoke to confirm auth-gated paths are healthy)</li><li>Evidence artifact:</li><li>Roadmap operational sign-off section entry (`docs/roadmap.md` → `Pre-Era-C Operational Sign-Off`)</li><li>Runbook completion record in release notes/runbook (this file + execution log in your normal runbook location)</li></ul>\n<h2 id=\"recurring-check\">Recurring check</h2>\n<ul><li>Re-run this runbook at or before each major operational checkpoint and record date/owner in the operational sign-off section.</li></ul>","updatedAt":"2018-10-20T01:46:40.000Z","checksum":"449b8b8eecb6d460e49a97781ddd9b3b3a7178930c5259e410a00052728c2d10","checksumPrefix":"449b8b8eecb6","anchorCount":4,"lineCount":43,"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"}