# MEK Rotation Runbook

**Status:** Stub — populate as part of Phase 1.F.11
**Owner:** Platform team
**Source pattern:** [`learning_ai_notes/docs/runbooks/MEK_ROTATION.md`](../../../../../learning_ai_notes/docs/runbooks/MEK_ROTATION.md) (commit `bcad7d3`)

---

## Purpose

This runbook describes how to **rotate the Master Encryption Key (MEK)** used for
field-level encryption of sensitive tracker data (PII fields on items, comments, attachment
URLs, agent API key seeds).

Tracker MEK rotation follows the same envelope-encryption pattern as NoteLett:

1. Tracker holds a **per-product MEK reference** in env (`TRACKER_MEK_ID_<PRODUCTID>`).
2. The MEK itself is stored in **Azure KeyVault**, never in process memory beyond
   a single request lifecycle.
3. Each encrypted field has a `keyId` envelope marking which MEK version encrypted it.
4. Rotation creates a new MEK version; new writes use the new version; reads support
   both old and new until reencryption sweep completes.

---

## Pre-rotation Checklist

- [ ] Confirm Azure KeyVault access from tracker-service host
- [ ] Confirm latest backup of Cosmos `tracker` container exists (RPO < 1 h)
- [ ] Notify on-call: rotation window expected ~30 min for active read-path verification
- [ ] Capture baseline metrics — read/write latency on encrypted fields

---

## Rotation Procedure

> **TODO** — adapt full procedure from `learning_ai_notes/docs/runbooks/MEK_ROTATION.md`
> once tracker-service field encryption ships in Phase 1.F. Sketch only below.

1. **Create new MEK version in KeyVault**
   - `az keyvault key create --vault-name <vault> --name tracker-mek-<productId> --kty RSA`
   - Record new `keyId`
2. **Update tracker-service env** with new `TRACKER_MEK_ID_<PRODUCTID>`
3. **Rolling restart tracker-service** — new writes encrypt with new key
4. **Reencryption sweep** — background job re-reads + re-writes all encrypted fields with new key
5. **Verify** — zero encrypted fields still on old key version
6. **Revoke old key** — disable old KeyVault version

---

## Rollback

If decryption fails after rotation:

1. Revert env to previous `TRACKER_MEK_ID_<PRODUCTID>`
2. Restart tracker-service
3. Re-enable old KeyVault version
4. Investigate which fields failed before retrying

---

## Verification

- [ ] `pnpm run smoke:local` passes end-to-end after rotation
- [ ] All encrypted fields on items / comments / attachments decrypt correctly via API
- [ ] Audit log entry recorded for the rotation event

---

_See [`SECRET_MANAGEMENT.md`](./SECRET_MANAGEMENT.md) for the broader env / KeyVault secret workflow._