Runbook: Veri anahtarı (DEK) rotasyonu
Sağlayıcı kimlik bilgileri (APNs p8, FCM private_key, VAPID private key) envelope encryption ile saklanır (ADR-0008): MASTER_KEY yalnızca veri anahtarlarını (DEK) sarar; her kayıt aktif DEK ile v2.<kid>.<iv>.<tag>.<ct>…
Sağlayıcı kimlik bilgileri (APNs p8, FCM private_key, VAPID private key) envelope encryption ile saklanır (ADR-0008):
MASTER_KEY yalnızca veri anahtarlarını (DEK) sarar; her kayıt aktif DEK ile v2.<kid>.<iv>.<tag>.<ct> biçiminde şifrelenir.
Ne zaman?
- Düzenli: 90 günde bir.
- Olay: DEK'in sızdığından şüphelenildiğinde, yetkili bir çalışan ayrıldığında, veritabanı yedeği dışarı çıktığında.
Komut
npm run keys:rotate
```text
Yapılanlar (tek transaction):
1. Yeni DEK üretilir ve `MASTER_KEY` ile sarılarak `data_keys` tablosuna aktif olarak yazılır.
2. Önceki aktif anahtar `retired` olur.
3. `channel_configs.secret_enc` ve webhook gizlileri/özel başlıkları eski DEK ile çözülüp yeni DEK ile yeniden şifrelenir; `secret_kid` güncellenir.
Çıktı örneği:
```text
Veri anahtarı döndürüldü: dek_01… → dek_02…; yeniden şifrelenen kayıt: 3
```text
Kullanılmayan eski anahtarları silmek için (rotasyondan en az 2 dakika sonra; API/worker süreçleri aktif anahtarı 60 sn önbelleğe alır ve bu sürede eski anahtarla yazabilir):
```bash
npm run keys:rotate -- --purge-only
```text
Temizlik kanal kimlik bilgileri ile webhook gizli/önceki gizli ve özel başlıklarında kullanılan anahtarları atlar. `--purge` rotasyonla birlikte çalışır ama yeni emekliye ayrılan anahtarı bekleme süresi nedeniyle silmez.
## MASTER_KEY değişimi
`MASTER_KEY` yalnızca sarmalanmış DEK'leri ve doğrudan şifrelenmiş birkaç alanı (MFA gizli anahtarları, SDK identity secret'ları) korur.
1. Yeni 32 baytlık anahtar üretin: `node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"`.
2. `.env` içinde `MASTER_KEY` değerini yeni anahtarla değiştirin; eski değeri komuta verin:
```bash
npm run keys:rewrap -- --old=<eski-base64>
```text
(veya eski anahtarı `MASTER_KEY_PREVIOUS` ortam değişkeninde verin). Komut tek transaction içinde `data_keys.wrapped_dek`, `mfa_factors.secret_enc` (yalnızca TOTP; kurtarma kodları tek yönlü özet olduğundan dokunulmaz) ve `apps.sdk_secret_enc` alanlarını yeni anahtarla yeniden şifreler.
3. API ve worker süreçlerini yeniden başlatın; `POST /internal/v1/apps/{appId}/channels/{channel}/validate` ile bir kanalın çözülebildiğini ve bir MFA girişinin çalıştığını doğrulayın.
## Doğrulama
- `npm run test:integration` içinde "anahtar rotasyonu" ve "MASTER_KEY yeniden sarmalama" testleri: rotasyon/yeniden sarmalama sonrası kimlik bilgisi çözülür ve doğrulama başarılıdır.
- Rotasyon sırasında API çalışmaya devam edebilir; çözümde `kid`'e göre DEK yüklendiğinden eski ve yeni kayıtlar birlikte okunabilir.Runbook: Kuyruk birikmesi (queue backlog) ve DLQ
Alarmlar: QueueDepthHigh (waiting + prioritized > 50k, 10 dk; öncelikli işler BullMQ'da prioritized kümesindedir), DeadLetterQueueHigh (failed > 100), WorkerJobsStalled (iş var, tamamlanan yok), WorkerDown. Pano:…
Runbook: İşlemsel sentetik izleme
Faz 14 kabulü "staging'de 7 gün hatasız sentetik izleme" bu kontrolle ölçülür. .github/workflows/synthetic.yml 15 dakikada bir scripts/synthetic.ts çalıştırır: