elevenlabs-webhook-nodejs 1.0.0

package/docs/architecture/11-BILLING.md

@@ -0,0 +1,458 @@
+# 11. Billing System
+
+> Subscription-based billing with usage tracking, period snapshots, and threshold alerts.
+> Last updated: 2026-04-02
+
+---
+
+## Billing Model Overview
+
+The billing system tracks tenant subscriptions, usage, and charges through five interconnected entities:
+
+```
+Plan (defines quotas)
+  |
+  v
+Payment (subscription period with start/end dates)
+  |
+  +---> BillingEvent (append-only ledger of charges/credits)
+  |
+  +---> BillingPeriodSnapshot (immutable usage record at period end)
+  |
+  +---> BillingAlert (threshold notifications: 75%, 90%, 100%)
+```
+
+### Plans
+
+Plans define what a tenant gets. They are system-wide records managed by superadmin/sales.
+
+```prisma
+model Plan {
+  plan_id                        String          @id @default(uuid())
+  plan_name                      String
+  plan_slug                      String          @unique
+  plan_price                     Decimal
+  plan_overage_rate              Decimal
+  plan_included_inbound_minutes  Int             @default(0)
+  plan_included_inbound_calls    Int             @default(0)
+  plan_included_outbound_minutes Int             @default(0)
+  plan_included_outbound_calls   Int             @default(0)
+  plan_included_wa_chats         Int             @default(0)
+  plan_language_support          LanguageSupport @default(single)
+  plan_is_active                 Boolean         @default(true)
+  plan_sort_order                Int             @default(0)
+  plan_created_at                DateTime        @default(now())
+  plan_updated_at                DateTime        @updatedAt
+
+  tenants   Tenant[]
+  snapshots BillingPeriodSnapshot[]
+
+  @@map("plans")
+}
+```
+
+Quotas defined per plan:
+
+| Quota | Field | Description |
+|-------|-------|-------------|
+| Inbound minutes | `plan_included_inbound_minutes` | Total inbound call minutes per billing period |
+| Inbound calls | `plan_included_inbound_calls` | Total inbound call count per period |
+| Outbound minutes | `plan_included_outbound_minutes` | Outbound call minutes (campaigns, validation) |
+| Outbound calls | `plan_included_outbound_calls` | Outbound call count |
+| WhatsApp chats | `plan_included_wa_chats` | Billable WhatsApp chat sessions per period |
+| Language support | `plan_language_support` | single, dual, or multi |
+
+### Payments
+
+A Payment represents a subscription period. Each payment has explicit start/end dates and is linked to the plan in effect at the time.
+
+```prisma
+model Payment {
+  payment_id             String        @id @default(uuid())
+  payment_tenant_id      String
+  payment_type           PaymentType   @default(subscription)  // subscription | top_up
+  payment_plan_slug      String
+  payment_plan_name      String
+  payment_amount         Decimal
+  payment_extra_minutes  Int           @default(0)
+  payment_period_start   DateTime
+  payment_period_end     DateTime
+  payment_method         PaymentMethod @default(cash)          // cash | bank_transfer | other
+  payment_notes          String        @default("")
+  payment_recorded_by_id String
+  payment_created_at     DateTime      @default(now())
+  payment_updated_at     DateTime      @updatedAt
+
+  tenant     Tenant                  @relation(...)
+  recordedBy User                    @relation("RecordedBy", ...)
+  snapshots  BillingPeriodSnapshot[]
+  alerts     BillingAlert[]
+
+  @@index([payment_tenant_id])
+  @@index([payment_tenant_id, payment_period_end(sort: Desc)])
+  @@map("payments")
+}
+```
+
+### BillingEvents (Append-Only Ledger)
+
+Every financial event is recorded as an immutable billing event. These are never updated or deleted.
+
+```prisma
+model BillingEvent {
+  billing_id          String           @id @default(uuid())
+  billing_tenant_id   String
+  billing_clinic_id   String?          // FK -> clinics. Populated for call_charge (copied from call's clinic_id). Null for tenant-level events (subscription, top_up).
+  billing_type        BillingEventType // call_charge | subscription | top_up | refund
+  billing_amount      Decimal
+  billing_currency    String           @default("TRY")
+  billing_call_id     String?
+  billing_description String           @default("")
+  billing_created_at  DateTime         @default(now())
+
+  tenant Tenant  @relation(...)
+  clinic Clinic? @relation(...)
+  call   Call?   @relation(...)
+
+  @@index([billing_tenant_id, billing_created_at(sort: Desc)])
+  @@index([billing_clinic_id, billing_created_at(sort: Desc)])
+  @@map("billing_events")
+}
+```
+
+Event types:
+
+| Type | When Created | `billing_clinic_id` |
+|------|-------------|---------------------|
+| `call_charge` | After each call completes -- amount = duration * overage_rate | Copied from the call's `call_clinic_id`. Enables per-clinic cost breakdown. |
+| `subscription` | When a new payment/subscription is recorded | `null` (tenant-level event) |
+| `top_up` | When extra minutes are purchased | `null` (tenant-level event) |
+| `refund` | When a charge is refunded | Copied from the original event's clinic, if applicable |
+
+### BillingPeriodSnapshots
+
+An immutable snapshot of usage at the end of a billing period. Once created, it never changes. This provides a historical record even if the tenant's plan or data changes later.
+
+```prisma
+model BillingPeriodSnapshot {
+  snapshot_id                  String   @id @default(uuid())
+  snapshot_tenant_id           String
+  snapshot_payment_id          String
+  snapshot_plan_id             String?  // FK to Plan at time of snapshot (historical reference)
+  snapshot_period_start        DateTime
+  snapshot_period_end          DateTime
+
+  // Actual usage during period
+  snapshot_total_calls         Int      @default(0)
+  snapshot_inbound_calls       Int      @default(0)
+  snapshot_inbound_minutes     Decimal  @default(0)
+  snapshot_outbound_calls      Int      @default(0)
+  snapshot_outbound_minutes    Decimal  @default(0)
+  snapshot_total_charges       Decimal  @default(0)
+  snapshot_wa_billable_chats   Int      @default(0)
+  snapshot_wa_total_sessions   Int      @default(0)
+  snapshot_wa_total_messages   Int      @default(0)
+  snapshot_wa_ai_messages      Int      @default(0)
+  snapshot_wa_el_cost          Decimal  @default(0)
+  snapshot_wa_stt_count        Int      @default(0)
+  snapshot_wa_stt_seconds      Decimal  @default(0)
+  snapshot_created_at          DateTime @default(now())
+
+  tenant  Tenant  @relation(...)
+  payment Payment @relation(...)
+  plan    Plan?   @relation(...)
+
+  @@index([snapshot_tenant_id, snapshot_period_start(sort: Desc)])
+  @@map("billing_period_snapshots")
+}
+```
+
+The `snapshot_plan_id` field is critical: it captures which plan was active at the time of the snapshot. If the tenant upgrades later, historical snapshots still reference the old plan's limits for accurate reporting.
+
+### BillingAlerts
+
+Usage threshold alerts. A unique constraint prevents duplicate alerts for the same threshold within the same billing period.
+
+```prisma
+model BillingAlert {
+  alert_id         String       @id @default(uuid())
+  alert_tenant_id  String
+  alert_type       AlertType    // usage_75 | usage_90 | usage_100 | period_expiring
+  alert_service    AlertService // inbound_minutes | inbound_calls | wa_chats | billing_period
+  alert_payment_id String
+  alert_created_at DateTime     @default(now())
+
+  tenant  Tenant  @relation(...)
+  payment Payment @relation(...)
+
+  @@unique([alert_tenant_id, alert_type, alert_service, alert_payment_id])
+  @@map("billing_alerts")
+}
+```
+
+The `@@unique` constraint on `[tenant_id, type, service, payment_id]` ensures a tenant receives at most one alert of each type per service per billing period. Once the "90% inbound minutes" alert fires, it will not fire again until the next period.
+
+---
+
+## Call Charging
+
+### Rate
+
+Configurable per plan via `plan_overage_rate`. Current default: **1.5 TRY per minute**.
+
+### Process
+
+After each call completes (via ElevenLabs post-call webhook), the billing service creates a `BillingEvent`:
+
+```typescript
+async logCallCharge(tenantId: string, clinicId: string, callId: string, durationSeconds: number): Promise<void> {
+  const tenant = await this.prisma.tenant.findUnique({ where: { tenant_id: tenantId }, include: { plan: true } });
+  const rate = tenant.plan.plan_overage_rate;
+  const minutes = Math.ceil(durationSeconds / 60);
+  const amount = minutes * rate;
+
+  await this.prisma.billingEvent.create({
+    data: {
+      billing_tenant_id: tenantId,
+      billing_clinic_id: clinicId,  // Copied from the call's clinic for per-clinic cost breakdown
+      billing_type: 'call_charge',
+      billing_amount: amount,
+      billing_call_id: callId,
+      billing_description: `Call charge: ${minutes} min @ ${rate} TRY/min`,
+    },
+  });
+}
+```
+
+---
+
+## Usage Calculation
+
+### Active Payment Lookup
+
+The active payment is the one whose period has not yet ended. For a given tenant, find the payment where `payment_period_end > now()`, sorted by `payment_period_end DESC`, take the first result.
+
+```typescript
+async getActivePayment(tenantId: string): Promise<Payment | null> {
+  return this.prisma.payment.findFirst({
+    where: {
+      payment_tenant_id: tenantId,
+      payment_period_end: { gt: new Date() },
+    },
+    orderBy: { payment_period_end: 'desc' },
+  });
+}
+```
+
+**Index used:** `@@index([payment_tenant_id, payment_period_end(sort: Desc)])` -- this is the most critical billing index.
+
+### Usage Aggregation
+
+Within the active payment's period, aggregate:
+
+| Metric | Source |
+|--------|--------|
+| Inbound calls / minutes | `Call` table (where `call_direction = 'inbound'`, `call_start_time` within period) |
+| Outbound calls / minutes | `Call` table (where `call_direction = 'outbound'`, `call_start_time` within period) |
+| WhatsApp sessions | `WhatsAppSession` table (where `created_at` within period, billable = true) |
+| STT usage | `SttUsage` table (where `stt_created_at` within period) |
+| Total charges | `BillingEvent` table (where `billing_created_at` within period, type = `call_charge`) |
+
+### Comparison Against Quotas
+
+The usage summary compares aggregated values against the plan's included quotas:
+
+```typescript
+{
+  inbound_minutes: { used: 450, included: 500, percentage: 90 },
+  inbound_calls: { used: 120, included: 200, percentage: 60 },
+  wa_chats: { used: 80, included: 100, percentage: 80 },
+  total_charges: 675.00,
+  period: { start: '2026-03-01', end: '2026-03-31' },
+}
+```
+
+---
+
+## Period Lifecycle
+
+### New Payment Recorded
+
+When a new payment is recorded:
+
+1. Find the previous active payment (if any).
+2. Snapshot the previous period's usage (see below).
+3. The new payment becomes the active payment.
+
+### Period Snapshot on Expiry
+
+A BullMQ repeatable job runs **daily at 00:05 Istanbul time**. It finds all payments where `payment_period_end < now()` and no snapshot exists yet, then creates an immutable `BillingPeriodSnapshot` for each.
+
+```typescript
+// BullMQ job: billing:snapshot-expired-periods
+// Cron: '5 0 * * *' (00:05 daily, Europe/Istanbul)
+
+async snapshotExpiredPeriods(): Promise<void> {
+  const expiredPayments = await this.prisma.payment.findMany({
+    where: {
+      payment_period_end: { lt: new Date() },
+      snapshots: { none: {} },  // No snapshot yet
+    },
+  });
+
+  for (const payment of expiredPayments) {
+    const usage = await this.aggregateUsage(payment.payment_tenant_id, payment.payment_period_start, payment.payment_period_end);
+    await this.prisma.billingPeriodSnapshot.create({
+      data: {
+        snapshot_tenant_id: payment.payment_tenant_id,
+        snapshot_payment_id: payment.payment_id,
+        snapshot_plan_id: /* tenant's plan at time of snapshot */,
+        snapshot_period_start: payment.payment_period_start,
+        snapshot_period_end: payment.payment_period_end,
+        ...usage,
+      },
+    });
+  }
+}
+```
+
+### Billing Alert Check
+
+A separate BullMQ repeatable job runs **daily at 09:00 Istanbul time**. It checks each tenant's current usage against plan quotas and sends alerts via SMS (NetGSM) when thresholds are crossed.
+
+```typescript
+// BullMQ job: billing:check-alerts
+// Cron: '0 9 * * *' (09:00 daily, Europe/Istanbul)
+
+async checkAndSendBillingAlerts(): Promise<void> {
+  const tenants = await this.getTenantsWithActivePayments();
+
+  for (const { tenant, payment, plan } of tenants) {
+    const usage = await this.getUsageSummary(tenant.tenant_id);
+
+    for (const [service, metric] of [
+      ['inbound_minutes', usage.inbound_minutes],
+      ['inbound_calls', usage.inbound_calls],
+      ['wa_chats', usage.wa_chats],
+    ]) {
+      for (const threshold of [75, 90, 100]) {
+        if (metric.percentage >= threshold) {
+          // Unique constraint prevents duplicates
+          await this.prisma.billingAlert.create({
+            data: {
+              alert_tenant_id: tenant.tenant_id,
+              alert_type: `usage_${threshold}`,
+              alert_service: service,
+              alert_payment_id: payment.payment_id,
+            },
+          }).catch(() => {}); // Ignore unique constraint violation (already sent)
+
+          // Send SMS notification
+          await this.netgsmService.sendSms(tenant.manager_phone, alertMessage);
+        }
+      }
+    }
+  }
+}
+```
+
+**Alert types:**
+
+| Type | Trigger |
+|------|---------|
+| `usage_75` | Usage reaches 75% of included quota |
+| `usage_90` | Usage reaches 90% of included quota |
+| `usage_100` | Usage reaches 100% -- overage charges begin |
+| `period_expiring` | Billing period ends within 3 days |
+
+**Services tracked:**
+
+| Service | Quota Source |
+|---------|-------------|
+| `inbound_minutes` | `plan_included_inbound_minutes` |
+| `inbound_calls` | `plan_included_inbound_calls` |
+| `wa_chats` | `plan_included_wa_chats` |
+| `billing_period` | Payment `period_end` date |
+
+---
+
+## Data Model Summary
+
+### Tables
+
+| Table | Purpose | Mutable |
+|-------|---------|---------|
+| `plans` | Define quotas and pricing | Yes (superadmin) |
+| `payments` | Subscription periods with start/end dates | Yes (notes, method) |
+| `billing_events` | Append-only ledger of all financial events | No (append-only) |
+| `billing_period_snapshots` | Immutable usage record at period end | No (immutable) |
+| `billing_alerts` | Usage threshold alert records | No (append-only) |
+
+### Enums
+
+```prisma
+enum BillingEventType {
+  call_charge
+  subscription
+  top_up
+  refund
+}
+
+enum PaymentType {
+  subscription
+  top_up
+}
+
+enum PaymentMethod {
+  cash
+  bank_transfer
+  other
+}
+
+enum AlertType {
+  usage_75
+  usage_90
+  usage_100
+  period_expiring
+}
+
+enum AlertService {
+  inbound_minutes
+  inbound_calls
+  wa_chats
+  billing_period
+}
+```
+
+### Key Indexes
+
+| Index | Purpose |
+|-------|---------|
+| `payments(tenant_id, period_end DESC)` | Active payment lookup -- the single most important billing query |
+| `billing_events(tenant_id, created_at DESC)` | Usage aggregation within a period |
+| `billing_events(clinic_id, created_at DESC)` | Per-clinic cost breakdown |
+| `billing_period_snapshots(tenant_id, period_start DESC)` | Historical period browsing |
+| `billing_alerts(tenant_id, type, service, payment_id) UNIQUE` | Duplicate alert prevention |
+
+---
+
+## BullMQ Jobs
+
+| Job Name | Schedule | What It Does |
+|----------|----------|-------------|
+| `billing:snapshot-expired-periods` | Daily at 00:05 (Europe/Istanbul) | Snapshot usage for all expired billing periods |
+| `billing:check-alerts` | Daily at 09:00 (Europe/Istanbul) | Check usage thresholds and send SMS alerts |
+
+---
+
+## Service API
+
+The billing service exposes these methods (Mongoose calls migrated to Prisma):
+
+| Method | Prisma Equivalent | Description |
+|--------|-------------------|-------------|
+| `logCallCharge()` | `prisma.billingEvent.create()` | Log a call charge as a billing event |
+| `getUsageSummary()` | Prisma aggregation queries | Current period usage vs. plan quotas |
+| `getActivePayment()` | `prisma.payment.findFirst()` with period_end filter | Find current active payment |
+| `snapshotExpiredPeriods()` | BullMQ repeatable job | Create snapshots for ended periods |
+| `checkAndSendBillingAlerts()` | BullMQ repeatable job | Check thresholds, send SMS via NetGSM |

package/docs/architecture/12-SECURITY.md

@@ -0,0 +1,216 @@
+# 12. Security Architecture
+
+> Security is not a separate phase -- it is built into every migration phase from day one.
+> Last updated: 2026-04-02
+
+---
+
+## Data Encryption
+
+### Six AES-256-GCM Encryption Keys
+
+Each domain has its own encryption key to limit blast radius. Compromise of one key does not expose data encrypted by another.
+
+| Key | Env Variable | What It Protects |
+|-----|-------------|-----------------|
+| Google tokens | `GOOGLE_TOKEN_ENCRYPTION_KEY` | OAuth2 refresh tokens for Google Calendar |
+| Meta tokens | `META_TOKEN_ENCRYPTION_KEY` | Page access tokens, WABA tokens for WhatsApp Business + Instagram |
+| TekTipPay | `TEKTIPPAY_ENCRYPTION_KEY` | Payment API keys and secrets |
+| Message content | `MESSAGE_ENCRYPTION_KEY` | Chat message text (`msg_text`, `msg_quoted_text`), operator request text |
+| Patient PII | `PATIENT_PII_ENCRYPTION_KEY` | TC Kimlik, medical history, exam records, clinical notes, document notes, photo set notes |
+| Patient summaries | `PATIENT_SUMMARY_ENCRYPTION_KEY` | AI-generated patient summaries (`patient_ai_summary`) |
+
+All keys are 32-byte hex strings. Generate with: `openssl rand -hex 32`.
+
+### EncryptionService (Shared)
+
+A single `@Injectable()` service used across the application. Each caller passes the appropriate key for their domain.
+
+```typescript
+@Injectable()
+export class EncryptionService {
+  encrypt(plaintext: string, key: string): string {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', Buffer.from(key, 'hex'), iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    return Buffer.concat([iv, authTag, encrypted]).toString('base64');
+  }
+
+  decrypt(ciphertext: string, key: string): string {
+    const buf = Buffer.from(ciphertext, 'base64');
+    const iv = buf.subarray(0, 12);
+    const authTag = buf.subarray(12, 28);
+    const data = buf.subarray(28);
+    const decipher = createDecipheriv('aes-256-gcm', Buffer.from(key, 'hex'), iv);
+    decipher.setAuthTag(authTag);
+    return Buffer.concat([decipher.update(data), decipher.final()]).toString('utf8');
+  }
+}
+```
+
+**Wire format:** `base64(iv[12] + authTag[16] + ciphertext[...])` -- a single opaque string stored in the database.
+
+### Per-Domain Key Derivation
+
+All encryption domains (Google, Meta, TekTipPay, messages, patient PII, patient summaries) use the master key directly since there is no per-entity isolation requirement. Tenant isolation is enforced at the query layer, not the encryption layer.
+
+### What Is Encrypted at Field Level vs. Disk Level
+
+| Data | Encryption Level | Reasoning |
+|------|-----------------|-----------|
+| Google OAuth refresh tokens | **Field-level** (AES-256-GCM) | Calendar access if exposed. Already encrypted in current system. |
+| Meta Business access tokens | **Field-level** (AES-256-GCM) | WhatsApp Business + Instagram takeover if exposed. |
+| TekTipPay credentials | **Field-level** (AES-256-GCM) | Payment system access if exposed. |
+| Chat message text | **Field-level** (AES-256-GCM) | `msg_text`, `msg_quoted_text` encrypted with `MESSAGE_ENCRYPTION_KEY`. Operator request text also encrypted. |
+| Patient PII (TC Kimlik, medical) | **Field-level** (AES-256-GCM) | TC Kimlik numbers, medical history, exam records, clinical notes, document notes, photo set notes encrypted with `PATIENT_PII_ENCRYPTION_KEY`. |
+| Patient AI summaries | **Field-level** (AES-256-GCM) | `patient_ai_summary` encrypted with `PATIENT_SUMMARY_ENCRYPTION_KEY`. |
+| User passwords | **One-way hash** (bcrypt 12 rounds) | Never decrypted. |
+| Tenant API keys | **One-way hash** (bcrypt) | Prefix stored for identification, full key returned once on creation. |
+| Patient phone numbers | **Disk-level** only | Must remain queryable for lookups. Protected by tenant isolation + disk encryption. |
+| Voice recordings | **MinIO SSE** (server-side encryption) | Signed URLs with 1hr TTL control access. |
+| Patient photos | **MinIO SSE** + signed URLs (1hr TTL) | Medical images. Never publicly accessible. |
+| Call transcripts | **Disk-level** only | Must be searchable. Protected by tenant isolation. |
+| CSV exports | **MinIO SSE** + signed URLs (1hr TTL) + auto-delete after 24h | Bulk PII. Time-limited access. |
+
+**Design decision:** Chat message content, patient PII, and patient AI summaries are encrypted at the field level with dedicated keys. This means search and AI processing require decryption at the application layer. Phone numbers remain unencrypted for query lookups. Additional protection comes from: tenant-scoped queries (Prisma middleware), RBAC + clinic scoping, PostgreSQL disk encryption, network isolation, and audit logging.
+
+---
+
+## Tenant Data Isolation
+
+### Prisma Middleware
+
+Every query passes through Prisma middleware that auto-injects tenant scoping:
+
+```typescript
+prisma.$use(async (params, next) => {
+  // Auto-inject WHERE tenantId = currentTenant for all queries
+  // Throw if tenantId is missing on mutations
+  // superadmin/sales bypass with explicit allTenants: true flag
+});
+```
+
+### Isolation Guarantees
+
+| Layer | Mechanism |
+|-------|-----------|
+| **Database queries** | Prisma middleware auto-injects `WHERE tenantId`. No SQL query can return data from another tenant. |
+| **Cross-tenant access** | Requires `superadmin` role + explicit `allTenants: true` flag. |
+| **Clinic scoping** | Layered on top of tenant scoping. `admin/doctor/receptionist` only see assigned clinics. |
+| **MinIO file storage** | Path prefixed with `{tenantId}/`. Signed URLs scoped to tenant path. |
+| **Redis keys** | Prefixed with `tenant:{tenantId}:` where applicable. |
+| **BullMQ jobs** | Jobs carry `tenantId`. Processors verify tenant ownership before acting. |
+
+---
+
+## API Security (11 Layers)
+
+| # | Layer | Implementation |
+|---|-------|---------------|
+| 1 | **Authentication** | Opaque session tokens. Client never sees JWT. Server maps opaque token to JWT stored in Redis. |
+| 2 | **Token revocation** | Delete Redis key = instant revocation. No blacklist needed. |
+| 3 | **Rate limiting** | `@nestjs/throttler` + Redis -- per-route limits (5/min login, 200/min general API, 100/min webhooks). |
+| 4 | **Input validation** | `class-validator` DTOs on every endpoint -- reject malformed requests before they reach business logic. |
+| 5 | **SQL injection** | Prisma parameterized queries -- no raw SQL unless explicitly needed. |
+| 6 | **CORS** | Strict origin whitelist -- only `FRONTEND_URL` allowed. |
+| 7 | **Helmet** | `@fastify/helmet` -- security headers (CSP, HSTS, X-Frame-Options). |
+| 8 | **Body size limits** | Fastify body limit: 10MB default, 50MB for file upload routes. |
+| 9 | **Webhook HMAC** | Signature verification on all inbound webhooks (ElevenLabs, Meta). |
+| 10 | **OAuth state** | HMAC-signed state parameter prevents CSRF on OAuth flows (Google Calendar, Meta). |
+| 11 | **Request logging** | Every request logged with method, URL, status, duration, userId, tenantId, clinicId, requestId. |
+
+### Rate Limiting Details
+
+| Scope | Limit | Window | Purpose |
+|-------|-------|--------|---------|
+| `/auth/login` | 5 requests | 1 min per IP | Brute force prevention |
+| `/auth/forgot-password` | 3 requests | 15 min per email | Spam prevention |
+| `/auth/register` | 3 requests | 1 hour per IP | Abuse prevention |
+| `/webhooks/*` | 100 requests | 1 min per IP | Webhook flooding |
+| Global API | 200 requests | 1 min per user | General abuse |
+
+---
+
+## Secrets Management
+
+### Encryption Keys
+
+| Secret | Storage | Rotation Strategy |
+|--------|---------|-------------------|
+| `GOOGLE_TOKEN_ENCRYPTION_KEY` | Env var / Docker secret | Re-encryption migration for all stored refresh tokens |
+| `META_TOKEN_ENCRYPTION_KEY` | Env var / Docker secret | Re-encrypt all stored Meta access tokens |
+| `TEKTIPPAY_ENCRYPTION_KEY` | Env var / Docker secret | Re-encrypt stored TekTipPay credentials |
+| `MESSAGE_ENCRYPTION_KEY` | Env var / Docker secret | Re-encrypt all `msg_text`, `msg_quoted_text`, operator request text |
+| `PATIENT_PII_ENCRYPTION_KEY` | Env var / Docker secret | Re-encrypt all TC Kimlik, medical history, exam records, clinical notes, document notes, photo set notes |
+| `PATIENT_SUMMARY_ENCRYPTION_KEY` | Env var / Docker secret | Re-encrypt all `patient_ai_summary` fields |
+
+### Other Secrets
+
+| Secret | Storage | Rotation |
+|--------|---------|----------|
+| JWT secret (`JWT_SECRET`) | Env var | Rotate quarterly. JWTs are server-side only (stored in Redis), so rotation affects only new tokens. Old opaque sessions expire naturally. |
+| Database password | Env var / Docker secret | Rotate periodically. Update `DATABASE_URL`. |
+| Redis password | Env var / Docker secret | Rotate periodically. Update `REDIS_URL`. |
+| MinIO credentials (`MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY`) | Env var / Docker secret | Rotate periodically. Update MinIO config and app env simultaneously. |
+| External API keys (ElevenLabs, NetGSM, etc.) | Env var | Per provider policy. |
+| Tenant API keys | bcrypt hash in DB | Tenant can regenerate anytime via dashboard. |
+
+All encryption keys: 32-byte hex strings generated with `openssl rand -hex 32`.
+
+---
+
+## Network Security
+
+### Docker Internal Network
+
+```
++--------------------------------------------------+
+|  asistan724-net (internal)                        |
+|                                                   |
+|  NestJS <--TLS--> PostgreSQL (port 5432, internal)|
+|  NestJS <--TLS--> Redis (port 6379, internal)     |
+|  NestJS <--TLS--> MinIO (port 9000, internal)     |
+|                                                   |
+|  Only NestJS + React exposed to host network      |
++--------------------------------------------------+
+```
+
+### Exposure Rules
+
+| Service | Host Port Binding | Access |
+|---------|------------------|--------|
+| NestJS | `PORT` (3005) | Behind reverse proxy with TLS termination |
+| React | 3020 | Behind same reverse proxy |
+| PostgreSQL | **None** | Internal network only |
+| Redis | **None** | Internal network only |
+| MinIO | **None** | Internal network only |
+
+### TLS Requirements
+
+- PostgreSQL: TLS for all connections from NestJS.
+- Redis: `requirepass` + TLS.
+- MinIO: SSE-S3 (server-side encryption) + TLS for API calls.
+- External APIs: All outbound HTTPS (ElevenLabs, Google, Meta, NetGSM, TekTipPay).
+
+---
+
+## Security per Migration Phase
+
+| Phase | Security Tasks |
+|-------|---------------|
+| **Phase 1** (Config, DB, Redis, MinIO) | `EncryptionService` shared module. PostgreSQL TLS + strong password. Redis `requirepass` + TLS. MinIO SSE-S3 + access policy. Docker network isolation. `@fastify/helmet`. |
+| **Phase 2** (Auth) | Opaque session tokens + Redis (no JWT exposed to client, delete key = revoke). bcrypt for passwords. `@nestjs/throttler` rate limiting with Redis storage. Hashed password reset tokens. CORS whitelist. |
+| **Phase 3** (Tenants, Users, Clinics) | Prisma tenant-scoping middleware. RBAC guards. Clinic access guard. Audit logging on all mutations. |
+| **Phase 4** (Agents) | Tenant-scoped queries. RBAC enforcement. |
+| **Phase 5** (Integrations) | Google token encryption (exists, verify). Meta token encryption (new). ElevenLabs webhook HMAC verification. API key rotation support. |
+| **Phase 6** (Client Tools) | Feature-flag gating on all tools. Tool execution logging. Tenant/clinic context validation in every tool call. |
+| **Phase 7** (Calls, Leads, Billing) | Tenant-scoped and clinic-scoped queries. RBAC on all billing endpoints. `clinic_id` on `billing_events`, `stt_usages`, `tool_execution_logs`. |
+| **Phase 8** (Outbound Campaigns) | Tenant-scoped. RBAC. Call dispatch respects time windows. |
+| **Phase 9** (WhatsApp) | **Message content encryption (AES-256-GCM with `MESSAGE_ENCRYPTION_KEY`).** All media stored in MinIO (not DB). Signed URLs for all media access. WS auth (opaque token on connect). |
+| **Phase 10** (Google Calendar) | Token encryption (verify). OAuth state HMAC signing. |
+| **Phase 11** (Appointment Validation) | Tenant-scoped. RBAC. |
+| **Phase 12** (Inbound Call Schedule) | Tenant-scoped. |
+| **Phase 13** (Webhooks) | HMAC signature verification on all inbound webhooks. Signed outgoing webhooks with per-tenant secret. |
+| **Phase 14** (Admin, Logs, KVKK) | Encrypted data exports (ZIP + password). Crypto-erasure on deletion for encrypted fields. Retention policy enforcement. **Patient PII encryption** (`PATIENT_PII_ENCRYPTION_KEY`). **Patient summary encryption** (`PATIENT_SUMMARY_ENCRYPTION_KEY`). |
+| **Phase 15** (Meta Business API, TekTipPay) | **Meta token encryption.** Webhook signature verification (Meta). **TekTipPay credential encryption.** Payment link tokenization (TekTipPay is a stub -- deferred). |