Secret Rotation Assistant

# Secret Rotation — `STRIPE_SECRET_KEY`

**Class:** Stripe API key (live secret)
**Trigger:** Scheduled (quarterly)
**Deployment platforms:** Vercel (production + preview), local dev `.env.local`
**CI:** GitHub Actions
**Rollback window:** zero-downtime required

<div data-callout="critical" data-label="Rotation cadence">

`STRIPE_SECRET_KEY` is a **live payments credential** with no scope limits — anyone holding it can charge cards, issue refunds, and read PII. Rotate on the **schedule below**, plus immediately on any of: laptop loss, contractor offboarding, accidental commit to a public repo, or vendor compromise notification.

</div>

| Secret class | Cadence | Blast radius | Pattern |
|---|---|---|---|
| Stripe live key | **quarterly** | <span data-pill="critical">customer payments + PII</span> | dual-key overlap window |
| Webhook signing secret | **quarterly** | <span data-pill="caution">webhook auth only</span> | dual-secret verification window |
| Clerk secret | **semi-annual** | <span data-pill="critical">auth bypass</span> | rotate in Clerk console, redeploy |
| Database URL password | **annually** | <span data-pill="critical">data exfiltration</span> | dual-user, app cuts over, drop old |
| HMAC download signer | **annually** | <span data-pill="caution">stale links revoked</span> | dual-secret verification window |

<div data-stack data-stack-title="Procedure — dual-key overlap (zero-downtime)">
<div data-row data-value="T-0">Create new Stripe restricted key in dashboard; copy once</div>
<div data-row data-value="T+5m">Add `STRIPE_SECRET_KEY_NEXT` to Vercel prod + preview, GitHub Actions secrets, local `.env.example`</div>
<div data-row data-value="T+10m">Deploy app reading both keys (code already checks `_NEXT` first, falls back to `_CURRENT`)</div>
<div data-row data-value="T+30m">Watch Stripe dashboard for traffic on the new key; confirm no errors</div>
<div data-row data-value="T+24h">Promote `_NEXT` → `STRIPE_SECRET_KEY`, remove `_NEXT`</div>
<div data-row data-value="T+24h+5m">Revoke the old key in Stripe dashboard</div>
</div>

---

## Where this secret is referenced

| Surface | File / location | Read path |
|---|---|---|
| Application code | `src/lib/stripe-server.ts` | `process.env.STRIPE_SECRET_KEY` |
| Webhook handler | `src/app/api/webhook/stripe/route.ts` | <span data-pill="info">indirect via `stripe-server`</span> |
| Vercel prod | Environment variable, scope: Production | encrypted at rest |
| Vercel preview | Environment variable, scope: Preview | encrypted at rest |
| GitHub Actions | Repo secrets, used by Stripe seeding job | OIDC not applicable |
| Local dev | `.env.local` (gitignored) | developer-managed |

<div data-callout="caution" data-label="Blast radius">

If the old key is revoked before the deploy cutover completes, **every in-flight charge attempt fails** with `StripeAuthenticationError`. The dual-key overlap window above prevents this — do not collapse the 24-hour wait unless you have validated traffic has fully shifted to the new key. Run `pnpm tsx scripts/check-stripe-traffic-by-key.ts` to confirm.

</div>

<div data-callout="critical" data-label="If this was an emergency rotation">

Skip the 24-hour overlap window only if compromise is confirmed. The cost is **~30 seconds of failed checkouts** during deploy plus webhook-replay risk. Compensating actions: enable Stripe's `Block all charges` switch temporarily, and watch the failed-checkout queue for replay candidates after rotation.

</div>

---

## Verification

```bash
# Confirm new key is the only one in use
pnpm tsx scripts/check-stripe-traffic-by-key.ts --window 1h

# Confirm webhook deliveries are signing/verifying correctly
gh run list --workflow=stripe-webhook-smoke.yml --limit 5

# Confirm no app instance still reading the old env var
vercel env ls production | grep STRIPE_SECRET_KEY
```

*This runbook is regenerated each rotation cycle. Do not copy from a previous quarter — the surface map drifts.*

This sample illustrates the skill's output format. Names, metrics, and operational details are illustrative unless the artifact explicitly analyzes public information.