elevenlabs-webhook-nodejs 1.0.0

package/docs/architecture/02-AUTHENTICATION.md

@@ -0,0 +1,1040 @@
+# 02 — Authentication & Authorization
+
+> Covers opaque token + Redis-backed JWT system, RBAC with 6 roles and 40+ permissions,
+> clinic-scoped access, NestJS guards/decorators, password reset, and rate limiting.
+> Last updated: 2026-04-02
+
+---
+
+## Table of Contents
+
+1. [Authentication Overview](#1-authentication-overview)
+2. [Opaque Token + Redis JWT System](#2-opaque-token--redis-jwt-system)
+3. [JWT Payload Structure (Server-Side)](#3-jwt-payload-structure-server-side)
+4. [Login Flow](#4-login-flow)
+5. [Register Flow](#5-register-flow)
+6. [Token Refresh Flow](#6-token-refresh-flow)
+7. [Logout Flow](#7-logout-flow)
+8. [Password Reset Flow](#8-password-reset-flow)
+9. [Rate Limiting](#9-rate-limiting)
+10. [Authorization — RBAC](#10-authorization--rbac)
+11. [Permissions Catalog](#11-permissions-catalog)
+12. [Role-to-Permission Mapping](#12-role-to-permission-mapping)
+13. [Clinic-Scoped Access](#13-clinic-scoped-access)
+14. [NestJS Guards and Decorators](#14-nestjs-guards-and-decorators)
+15. [Sequence Diagrams](#15-sequence-diagrams)
+
+---
+
+## 1. Authentication Overview
+
+| Aspect | Implementation |
+|--------|---------------|
+| Framework | Passport.js with custom strategy (`@nestjs/passport` + `@nestjs/jwt`) |
+| Password hashing | bcrypt (12 rounds) |
+| Token system | **Opaque tokens** sent to client. Real JWTs stored server-side in Redis. Client never sees the JWT |
+| Access session | Opaque token → Redis lookup → JWT payload. TTL 15 minutes |
+| Refresh session | Opaque token → Redis + PostgreSQL. TTL 30 days |
+| Token revocation | Instant — delete the Redis key. No blacklist needed |
+| Rate limiting | `@nestjs/throttler` with Redis storage |
+| Security headers | `@fastify/helmet` (CSP, HSTS, X-Frame-Options) |
+| CORS | Strict origin whitelist — only `FRONTEND_URL` allowed |
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `JWT_SECRET` | JWT signing secret (server-side only — JWTs never leave the server) |
+| `JWT_REFRESH_SECRET` | Refresh token signing secret |
+| `JWT_ACCESS_EXPIRY` | `15m` |
+| `JWT_REFRESH_EXPIRY` | `30d` |
+
+---
+
+## 2. Opaque Token + Redis JWT System
+
+The client **never receives a JWT**. Instead, it receives an opaque session token (crypto-random string). The real JWT lives in Redis, server-side only.
+
+### Why This Design
+
+| Concern | Traditional JWT | Our Approach |
+|---------|----------------|-------------|
+| Token theft | JWT in localStorage/cookie can be decoded, replayed | Opaque string is meaningless without Redis access |
+| Revocation | Requires a blacklist (check every request) | Delete the Redis key — instant, no blacklist |
+| Payload exposure | Client can decode JWT and see permissions, features, etc. | Client sees nothing — opaque token is a random string |
+| Session control | Wait for JWT expiry or maintain blacklist | Full control — delete key = session dead |
+
+### Access Session
+- **Client receives:** Opaque token (32-byte crypto-random hex string)
+- **Redis stores:** `session:{opaqueToken}` → JWT string, TTL = 15 minutes
+- **On each request:** Client sends opaque token in `Authorization: Bearer {opaqueToken}` → Server does `Redis GET session:{opaqueToken}` → gets JWT → verifies signature → extracts payload → proceeds
+- **On revocation:** `Redis DEL session:{opaqueToken}` → next request returns 401
+
+### Refresh Session
+- **Client receives:** Opaque refresh token (32-byte crypto-random hex string)
+- **Redis stores:** `refresh:{opaqueRefreshToken}` → user ID, TTL = 30 days
+- **PostgreSQL stores:** `refresh_tokens` table for persistence (Redis may restart)
+- **On refresh:** Client sends opaque refresh token → Server looks up user ID → re-resolves permissions, features, clinics from DB → generates new JWT → stores in Redis with new opaque token → returns new opaque token pair
+- **Rotation:** Old opaque tokens are deleted on refresh. One refresh token = one use.
+
+### Redis Keys
+
+| Key Pattern | TTL | Purpose |
+|-------------|-----|---------|
+| `session:{opaqueToken}` | 15m | Maps opaque access token to JWT string |
+| `refresh:{opaqueRefreshToken}` | 30d | Maps opaque refresh token to user ID |
+
+### Token Generation
+
+```typescript
+import { randomBytes } from 'crypto';
+
+function generateOpaqueToken(): string {
+  return randomBytes(32).toString('hex'); // 64-char hex string
+}
+```
+
+### Request Authentication Flow
+
+```
+Client request
+  → Authorization: Bearer {opaqueToken}
+  → Server: Redis GET session:{opaqueToken}
+  → If not found: 401 Unauthorized
+  → If found: JWT string
+  → Verify JWT signature (jwt.verify with JWT_SECRET)
+  → Extract payload (userId, tenantId, role, permissions, features, clinicIds)
+  → Proceed to guards (PermissionsGuard, FeaturesGuard, ClinicAccessGuard)
+```
+
+### Prisma Model (unchanged)
+
+```prisma
+model RefreshToken {
+  token_id         String   @id @default(uuid())
+  token_user_id    String
+  token_value      String   @unique  -- stores the opaque refresh token (not JWT)
+  token_expires_at DateTime
+  token_created_at DateTime @default(now())
+
+  user User @relation(fields: [token_user_id], references: [user_id], onDelete: Cascade)
+
+  @@index([token_user_id])
+  @@index([token_expires_at])
+  @@map("refresh_tokens")
+}
+```
+
+---
+
+## 3. JWT Payload Structure (Server-Side)
+
+The JWT is stored in Redis, never sent to the client. It carries everything needed for authorization:
+
+```typescript
+interface JwtPayload {
+  sub: string;           // User ID (UUID)
+  tenantId: string;      // Tenant ID (UUID) — null for platform roles
+  role: UserRole;        // 'superadmin' | 'sales' | 'owner' | 'admin' | 'doctor' | 'receptionist'
+  permissions: string[]; // Resolved permission list from role (e.g., ['patients:read', 'chats:send'])
+  features: string[];    // Tenant's enabled feature flags (e.g., ['whatsapp_agent', 'google_calendar'])
+  clinicIds: string[];   // Assigned clinic IDs — empty for owner (all clinics)
+  allClinics: boolean;   // true if user sees all clinics (owner/superadmin)
+  iat: number;           // Issued at
+  exp: number;           // Expires at
+}
+```
+
+**Design rationale:** The JWT provides a structured, signed payload with all authorization data. Permissions, features, and clinic assignments are embedded so that guards can check access without DB lookups on every request. The only I/O per request is a single Redis GET to resolve the opaque token to the JWT.
+
+If a user's role or clinic assignment changes mid-session, the change takes effect after the current access token expires (max 15 minutes) or the user re-authenticates. On refresh, the payload is rebuilt from the database.
+
+---
+
+## 4. Login Flow
+
+### Endpoint
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/auth/login` | None | Login with email + password |
+
+### Flow
+
+1. Client sends `{ email, password }` to `POST /auth/login`.
+2. Server looks up user by email, verifies bcrypt hash.
+3. Server checks `user.is_active` and `tenant.is_active`.
+4. Server resolves permissions from role, fetches tenant features and clinic assignments.
+5. Server generates JWT (signed, 15m expiry) — **never sent to client**.
+6. Server generates opaque access token (`randomBytes(32).toString('hex')`).
+7. Server stores in Redis: `session:{opaqueAccessToken}` = JWT, TTL = 15m.
+8. Server generates opaque refresh token, stores in Redis (`refresh:{token}`, TTL 30d) + PostgreSQL (`refresh_tokens` table).
+9. Server returns `{ user, tenant, access_token: opaqueAccessToken, refresh_token: opaqueRefreshToken }`.
+
+The client stores the opaque tokens. It never sees or decodes the JWT.
+
+---
+
+## 5. Register Flow
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/auth/register` | None | Register a new tenant + owner user |
+
+1. Client sends `{ firstName, lastName, email, password, tenantName }`.
+2. Server creates a new Tenant record (thin — just name, features, kvkk).
+3. Server creates a default Clinic for the tenant (name = tenantName, `is_default = true`, all config defaults: language "tr", AI provider "openai", grace period 180s, etc.).
+4. Server creates a User with `role = owner`, linked to the new tenant.
+5. Server generates JWT → stores in Redis with opaque token → stores refresh in Redis + PostgreSQL.
+6. Server returns `{ user, tenant, access_token: opaqueAccessToken, refresh_token: opaqueRefreshToken }`.
+
+**Rate limited:** 3 requests per hour per IP (abuse prevention).
+
+**Note:** The clinic gets all operational config with sensible defaults on creation. The tenant holds no config — see [01-DATABASE-SCHEMA clinics](#2-clinics).
+
+---
+
+## 6. Token Refresh Flow
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/auth/refresh` | None (opaque refresh_token in body) | Rotate tokens |
+
+1. Client sends `{ refresh_token: opaqueRefreshToken }`.
+2. Server does `Redis GET refresh:{opaqueRefreshToken}`. If not found, check PostgreSQL.
+3. Server checks expiry.
+4. Server deletes old opaque tokens: `Redis DEL refresh:{old}`, `Redis DEL session:{oldAccess}`, delete from PostgreSQL.
+5. Server re-resolves the user's current role, permissions, features, and clinic assignments from DB.
+6. Server generates new JWT → new opaque access token → stores in Redis (`session:{new}`, 15m TTL).
+7. Server generates new opaque refresh token → stores in Redis (`refresh:{new}`, 30d TTL) + PostgreSQL.
+8. Server returns `{ access_token: newOpaqueAccessToken, refresh_token: newOpaqueRefreshToken }`.
+
+**Key point:** The refresh flow is the moment when role/clinic changes propagate into the JWT payload.
+If an admin changes a user's role at T=0 and the user refreshes at T=5m, the new JWT (stored in Redis) will
+carry the updated permissions.
+
+---
+
+## 7. Logout Flow
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/auth/logout` | Opaque token | Revoke session |
+
+1. Client sends logout request with `Authorization: Bearer {opaqueAccessToken}`.
+2. Server resolves user from the opaque token (Redis GET).
+3. Server deletes `session:{opaqueAccessToken}` from Redis.
+4. Server deletes the user's refresh token from PostgreSQL + Redis.
+5. Any subsequent request with the old opaque token returns 401 (Redis key gone).
+
+**No blacklist needed.** Deleting the Redis key = instant revocation.
+
+**On password change:** All Redis session keys for the user are deleted + all refresh tokens deleted from Redis + PostgreSQL. Forces re-authentication on all devices.
+
+---
+
+## 8. Password Reset Flow
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/auth/forgot-password` | None | Request password reset link |
+| POST | `/auth/reset-password` | None (token in body) | Set new password |
+
+### Flow
+
+1. User submits email to `POST /auth/forgot-password`.
+2. Server generates a random token (32 bytes hex).
+3. Server stores a **bcrypt hash** of the token in `password_reset_tokens` with a 1-hour TTL.
+4. Server sends the raw token to the user via email (or SMS via NetGSM as fallback).
+5. User clicks the link, which opens the frontend with the token in the URL.
+6. Frontend sends `{ token, new_password }` to `POST /auth/reset-password`.
+7. Server finds the matching record by hashing the submitted token and comparing.
+8. Server verifies the token has not expired (1h TTL) and has not been used.
+9. Server updates the user's password (bcrypt hash).
+10. Server **revokes all refresh tokens** for the user (forces re-login on all devices).
+11. Server marks the reset token as used and deletes it.
+
+### Prisma Model
+
+```prisma
+model PasswordResetToken {
+  id        String    @id @default(uuid())
+  userId    String
+  tokenHash String    @unique  // bcrypt hash of token
+  expiresAt DateTime           // 1 hour from creation
+  usedAt    DateTime?
+  createdAt DateTime  @default(now())
+
+  user User @relation(fields: [userId], references: [user_id], onDelete: Cascade)
+
+  @@index([expiresAt])
+  @@map("password_reset_tokens")
+}
+```
+
+**Cleanup:** BullMQ repeatable job `auth:cleanup-reset-tokens` deletes expired tokens periodically.
+
+**Rate limited:** 3 requests per 15 minutes per email.
+
+---
+
+---
+
+## 10. Rate Limiting
+
+Implemented with `@nestjs/throttler` backed by Redis storage.
+
+### Global Configuration
+
+```typescript
+@Module({
+  imports: [
+    ThrottlerModule.forRoot({
+      throttlers: [{ ttl: 60_000, limit: 200 }], // Global: 200 req/min per user
+      storage: new ThrottlerStorageRedisService(redis),
+    }),
+  ],
+})
+```
+
+### Per-Route Limits
+
+| Route | Limit | Window | Keyed By | Purpose |
+|-------|-------|--------|----------|---------|
+| `POST /auth/login` | 5 requests | 1 min | IP | Brute force prevention |
+| `POST /auth/forgot-password` | 3 requests | 15 min | Email | Spam prevention |
+| `POST /auth/register` | 3 requests | 1 hour | IP | Abuse prevention |
+| `/webhooks/*` | 100 requests | 1 min | IP | Webhook flooding |
+| Global API | 200 requests | 1 min | User (JWT sub) | General abuse |
+
+### Redis Key Pattern
+
+```
+throttle:{scope}:{identifier}
+```
+
+TTL equals the window duration. Example: `throttle:auth-login:192.168.1.1` expires after 60s.
+
+### Per-Route Override
+
+```typescript
+@Post('login')
+@Throttle({ default: { ttl: 60_000, limit: 5 } })
+async login(@Body() dto: LoginDto) { ... }
+```
+
+---
+
+## 11. Authorization -- RBAC
+
+Roles are **permission bundles**. Each role maps to a fixed set of atomic permissions. Users have exactly one role. Clinic assignments then scope *where* those permissions apply.
+
+### 11.1 Roles
+
+**Platform Roles** (no tenantId -- system-wide access):
+
+| Role | Scope | Who | Access |
+|------|-------|-----|--------|
+| `superadmin` | System-wide | Platform operator | All endpoints, all tenants, bypasses all guards |
+| `sales` | System-wide | Platform sales team | Create tenants, assign plans, view tenant list -- no access to tenant internal data |
+
+**Tenant Roles** (scoped to a tenant + assigned clinics):
+
+| Role | Scope | Who | Access |
+|------|-------|-----|--------|
+| `owner` | All clinics | Clinic chain owner | Full tenant management + all clinics, user management, billing, settings |
+| `admin` | Assigned clinics | Branch administrator | Full access to assigned clinics, invite users for their clinics |
+| `doctor` | Assigned clinics | Doctor/specialist | Patient history, operator requests, appointments, call transcripts |
+| `receptionist` | Assigned clinics | Front desk staff | Live chat, appointments, calls, leads -- the daily operator role |
+
+### 11.2 Platform vs Tenant Roles
+
+- `superadmin` and `sales` have `tenantId = null` on the User record. They operate at the platform level.
+- `sales` can only access `/platform/*` endpoints. Attempting to access tenant data (e.g., `/chats`) throws `403 Forbidden`.
+- `owner`, `admin`, `doctor`, `receptionist` always have a `tenantId`. Every query they make is automatically tenant-scoped via Prisma middleware.
+- `owner` automatically has access to **all clinics** within their tenant. No explicit clinic assignments needed.
+- `admin`, `doctor`, `receptionist` must be explicitly assigned to clinics via `UserClinicAssignment`.
+
+---
+
+## 12. Permissions Catalog
+
+Format: `resource:action`. There are 37 atomic permissions across 16 resource categories.
+
+### Platform Permissions (superadmin + sales)
+
+| Permission | Description |
+|------------|-------------|
+| `platform:tenants.list` | List all tenants across the platform |
+| `platform:tenants.create` | Create new tenant + owner user |
+| `platform:tenants.read` | View any tenant detail (name, plan, status) |
+| `platform:tenants.update` | Update tenant plan, features, active status |
+| `platform:plans.read` | View available plans |
+| `platform:plans.manage` | Create/update plans |
+
+### Tenant Management
+
+| Permission | Description |
+|------------|-------------|
+| `tenant:read` | View tenant info and settings |
+| `tenant:update` | Update tenant settings |
+| `tenant:features` | Toggle feature flags |
+
+### Clinics
+
+| Permission | Description |
+|------------|-------------|
+| `clinics:read` | View clinic list and settings |
+| `clinics:create` | Create new clinic |
+| `clinics:update` | Update clinic settings |
+| `clinics:delete` | Delete clinic |
+
+### Users
+
+| Permission | Description |
+|------------|-------------|
+| `users:read` | View user list |
+| `users:invite` | Invite new users |
+| `users:update` | Update user roles/clinics |
+| `users:delete` | Remove users |
+
+### Phone Numbers
+
+| Permission | Description |
+|------------|-------------|
+| `phone_numbers:read` | View phone numbers |
+| `phone_numbers:manage` | Add/edit/remove phone numbers |
+
+### Agents
+
+| Permission | Description |
+|------------|-------------|
+| `agents:read` | View agents |
+| `agents:manage` | Configure agents |
+
+### WhatsApp / Live Chat
+
+| Permission | Description |
+|------------|-------------|
+| `chats:read` | View chat list and messages |
+| `chats:takeover` | Take over session from AI |
+| `chats:send` | Send messages in live chat |
+| `chats:resolve` | Manually resolve sessions |
+| `chats:config` | Configure WhatsApp settings (connect, disconnect, blacklist) |
+
+### Calls
+
+| Permission | Description |
+|------------|-------------|
+| `calls:read` | View call records and transcripts |
+
+### Leads
+
+| Permission | Description |
+|------------|-------------|
+| `leads:read` | View leads |
+| `leads:update` | Update lead status |
+| `leads:export` | Export leads as CSV |
+
+### Appointments
+
+| Permission | Description |
+|------------|-------------|
+| `appointments:read` | View appointments |
+| `appointments:manage` | Create/cancel/reschedule appointments manually |
+
+### Outbound Campaigns
+
+| Permission | Description |
+|------------|-------------|
+| `campaigns:read` | View campaigns and results |
+| `campaigns:manage` | Create/start/stop campaigns |
+| `campaigns:export` | Export campaign results |
+
+### Appointment Validation
+
+| Permission | Description |
+|------------|-------------|
+| `validation:read` | View validation batches |
+| `validation:manage` | Create/submit/cancel batches |
+| `validation:export` | Export validation results |
+
+### Billing
+
+| Permission | Description |
+|------------|-------------|
+| `billing:read` | View usage, invoices, billing history |
+| `billing:manage` | Record payments, manage plans |
+
+### Analytics
+
+| Permission | Description |
+|------------|-------------|
+| `analytics:read` | View dashboards and reports |
+
+### Patients
+
+| Permission | Description |
+|------------|-------------|
+| `patients:read` | View patient list, detail, medical history |
+| `patients:create` | Create new patients manually |
+| `patients:update` | Edit patient info, medical history, documents, notes |
+| `patients:delete` | Soft-delete patients |
+| `patients:export` | Export patient data (CSV, KVKK) |
+
+### Treatments
+
+| Permission | Description |
+|------------|-------------|
+| `treatments:read` | View treatment catalog |
+| `treatments:manage` | Create/edit/delete treatments |
+| `treatment_plans:manage` | Create/edit treatment plans and items |
+
+### Calendar
+
+| Permission | Description |
+|------------|-------------|
+| `calendar:read` | View calendar settings |
+| `calendar:manage` | Connect/disconnect Google Calendar, configure |
+
+### KVKK / Compliance
+
+| Permission | Description |
+|------------|-------------|
+| `kvkk:read` | View deletion requests, retention policy |
+| `kvkk:manage` | Request data export/deletion |
+
+### Audit
+
+| Permission | Description |
+|------------|-------------|
+| `audit:read` | View audit trail |
+
+### Payments (Patient)
+
+| Permission | Description |
+|------------|-------------|
+| `payments:read` | View patient payments |
+| `payments:manage` | Create payment links, refund |
+
+---
+
+## 13. Role-to-Permission Mapping
+
+The complete mapping from each role to its granted permissions.
+
+### superadmin
+
+Bypasses all permission checks entirely. Has implicit access to everything.
+
+### sales
+
+```
+platform:tenants.list
+platform:tenants.create
+platform:tenants.read
+platform:tenants.update
+platform:plans.read
+```
+
+Sales can only onboard tenants and manage plans. Zero access to tenant internal data (chats, calls, leads, etc.).
+
+### owner
+
+Full access within their tenant. All permissions below:
+
+```
+tenant:read, tenant:update, tenant:features
+clinics:read, clinics:create, clinics:update, clinics:delete
+users:read, users:invite, users:update, users:delete
+phone_numbers:read, phone_numbers:manage
+agents:read, agents:manage
+chats:read, chats:takeover, chats:send, chats:resolve, chats:config
+calls:read
+leads:read, leads:update, leads:export
+appointments:read, appointments:manage
+campaigns:read, campaigns:manage, campaigns:export
+validation:read, validation:manage, validation:export
+billing:read, billing:manage
+analytics:read
+contacts:read, contacts:update, contacts:export
+calendar:read, calendar:manage
+kvkk:read, kvkk:manage
+audit:read
+payments:read, payments:manage
+```
+
+### admin
+
+Same as owner minus: `clinics:create`, `clinics:delete`, `tenant:update`, `tenant:features`, `users:update`, `users:delete`, `billing:manage`, `kvkk:manage`. Only sees assigned clinics.
+
+```
+tenant:read
+clinics:read, clinics:update
+users:read, users:invite
+phone_numbers:read, phone_numbers:manage
+agents:read, agents:manage
+chats:read, chats:takeover, chats:send, chats:resolve, chats:config
+calls:read
+leads:read, leads:update, leads:export
+appointments:read, appointments:manage
+campaigns:read, campaigns:manage, campaigns:export
+validation:read, validation:manage, validation:export
+billing:read
+analytics:read
+contacts:read, contacts:update, contacts:export
+calendar:read, calendar:manage
+kvkk:read
+audit:read
+payments:read, payments:manage
+```
+
+### doctor
+
+Read-heavy role focused on clinical data:
+
+```
+tenant:read
+clinics:read
+chats:read
+calls:read
+leads:read
+appointments:read, appointments:manage
+contacts:read, contacts:update
+analytics:read
+```
+
+### receptionist
+
+Day-to-day operations role:
+
+```
+tenant:read
+clinics:read
+chats:read, chats:takeover, chats:send, chats:resolve
+calls:read
+leads:read, leads:update
+appointments:read, appointments:manage
+contacts:read, contacts:update
+payments:read, payments:manage
+```
+
+### Complete Matrix
+
+| Permission | superadmin | sales | owner | admin | doctor | receptionist |
+|------------|:---:|:---:|:---:|:---:|:---:|:---:|
+| `platform:tenants.list` | * | Y | - | - | - | - |
+| `platform:tenants.create` | * | Y | - | - | - | - |
+| `platform:tenants.read` | * | Y | - | - | - | - |
+| `platform:tenants.update` | * | Y | - | - | - | - |
+| `platform:plans.read` | * | Y | - | - | - | - |
+| `platform:plans.manage` | * | - | - | - | - | - |
+| `tenant:read` | * | - | Y | Y | Y | Y |
+| `tenant:update` | * | - | Y | - | - | - |
+| `tenant:features` | * | - | Y | - | - | - |
+| `clinics:read` | * | - | Y | Y | Y | Y |
+| `clinics:create` | * | - | Y | - | - | - |
+| `clinics:update` | * | - | Y | Y | - | - |
+| `clinics:delete` | * | - | Y | - | - | - |
+| `users:read` | * | - | Y | Y | - | - |
+| `users:invite` | * | - | Y | Y | - | - |
+| `users:update` | * | - | Y | - | - | - |
+| `users:delete` | * | - | Y | - | - | - |
+| `phone_numbers:read` | * | - | Y | Y | - | - |
+| `phone_numbers:manage` | * | - | Y | Y | - | - |
+| `agents:read` | * | - | Y | Y | - | - |
+| `agents:manage` | * | - | Y | Y | - | - |
+| `chats:read` | * | - | Y | Y | Y | Y |
+| `chats:takeover` | * | - | Y | Y | - | Y |
+| `chats:send` | * | - | Y | Y | - | Y |
+| `chats:resolve` | * | - | Y | Y | - | Y |
+| `chats:config` | * | - | Y | Y | - | - |
+| `calls:read` | * | - | Y | Y | Y | Y |
+| `leads:read` | * | - | Y | Y | Y | Y |
+| `leads:update` | * | - | Y | Y | - | Y |
+| `leads:export` | * | - | Y | Y | - | - |
+| `appointments:read` | * | - | Y | Y | Y | Y |
+| `appointments:manage` | * | - | Y | Y | Y | Y |
+| `campaigns:read` | * | - | Y | Y | - | - |
+| `campaigns:manage` | * | - | Y | Y | - | - |
+| `campaigns:export` | * | - | Y | Y | - | - |
+| `validation:read` | * | - | Y | Y | - | - |
+| `validation:manage` | * | - | Y | Y | - | - |
+| `validation:export` | * | - | Y | Y | - | - |
+| `billing:read` | * | - | Y | Y | - | - |
+| `billing:manage` | * | - | Y | - | - | - |
+| `analytics:read` | * | - | Y | Y | Y | - |
+| `patients:read` | * | - | Y | Y | Y | Y |
+| `patients:create` | * | - | Y | Y | - | Y |
+| `patients:update` | * | - | Y | Y | Y | Y |
+| `patients:delete` | * | - | Y | - | - | - |
+| `patients:export` | * | - | Y | Y | - | - |
+| `treatments:read` | * | - | Y | Y | Y | Y |
+| `treatments:manage` | * | - | Y | Y | - | - |
+| `treatment_plans:manage` | * | - | Y | Y | Y | - |
+| `calendar:read` | * | - | Y | Y | - | - |
+| `calendar:manage` | * | - | Y | Y | - | - |
+| `kvkk:read` | * | - | Y | Y | - | - |
+| `kvkk:manage` | * | - | Y | - | - | - |
+| `audit:read` | * | - | Y | Y | - | - |
+| `payments:read` | * | - | Y | Y | - | Y |
+| `payments:manage` | * | - | Y | Y | - | Y |
+
+`*` = superadmin bypasses all checks. `Y` = explicitly granted. `-` = not granted.
+
+---
+
+## 14. Clinic-Scoped Access
+
+Beyond permissions, data visibility is further scoped by **clinic assignment**. A user might have `chats:read` permission but can only see chats belonging to their assigned clinics.
+
+### Rules
+
+| Role | Clinic Access |
+|------|---------------|
+| `superadmin` | All tenants, all clinics (bypasses everything) |
+| `owner` | All clinics within their tenant (automatic, no assignments needed) |
+| `admin` | Only explicitly assigned clinics |
+| `doctor` | Only explicitly assigned clinics |
+| `receptionist` | Only explicitly assigned clinics |
+| `sales` | No clinic access (platform role -- only `/platform/*` endpoints) |
+
+### UserClinicAssignment Table
+
+```prisma
+model UserClinicAssignment {
+  assign_id         String   @id @default(uuid())
+  assign_user_id    String
+  assign_clinic_id  String
+  assign_created_at DateTime @default(now())
+
+  user   User   @relation(fields: [assign_user_id], references: [user_id], onDelete: Cascade)
+  clinic Clinic @relation(fields: [assign_clinic_id], references: [clinic_id], onDelete: Cascade)
+
+  @@unique([assign_user_id, assign_clinic_id])
+  @@index([assign_user_id])
+  @@index([assign_clinic_id])
+  @@map("user_clinic_assignments")
+}
+```
+
+### ClinicAccessGuard Logic
+
+```typescript
+async function clinicAccessGuard(request) {
+  const user = request.user; // From JWT payload
+
+  // Superadmin and owner bypass clinic scoping
+  if (['superadmin', 'owner'].includes(user.role)) {
+    return; // Full access to all clinics
+  }
+
+  // Sales role has no tenant/clinic access
+  if (user.role === 'sales') {
+    throw new ForbiddenException('Sales role cannot access tenant data');
+  }
+
+  // For admin, doctor, receptionist: resolve assigned clinics
+  const assignedClinicIds = await getAssignedClinicIds(user.id);
+
+  // If route targets a specific clinic, verify access
+  if (request.params.clinicId) {
+    if (!assignedClinicIds.includes(request.params.clinicId)) {
+      throw new ForbiddenException('No access to this clinic');
+    }
+  }
+
+  // Inject for downstream use (services filter queries by these IDs)
+  request.accessibleClinicIds = assignedClinicIds;
+}
+```
+
+### How Services Use Clinic Scoping
+
+Services receive `clinicIds` from the guard and add it to every database query:
+
+```typescript
+async findAll(tenantId: string, clinicIds: string[]) {
+  return this.prisma.whatsappChat.findMany({
+    where: {
+      chat_tenant_id: tenantId,
+      chat_clinic_id: { in: clinicIds },  // Scoped by accessible clinics
+    },
+  });
+}
+```
+
+For `owner` and `superadmin`, `clinicIds` is empty/undefined, and the clinic filter is omitted (all clinics returned).
+
+---
+
+## 15. NestJS Guards and Decorators
+
+### Guards (applied via `@UseGuards`)
+
+| Guard | Purpose | Order |
+|-------|---------|-------|
+| `JwtAuthGuard` | Validates JWT signature, checks Redis blacklist, extracts user payload | 1st (always) |
+| `PermissionsGuard` | Checks that the user's role grants the required permission(s) | 2nd |
+| `FeaturesGuard` | Checks that the tenant has the required feature flag(s) enabled | 3rd |
+| `ClinicAccessGuard` | Verifies clinic assignment, injects `accessibleClinicIds` | 4th |
+
+### Decorators
+
+| Decorator | Type | Usage |
+|-----------|------|-------|
+| `@Permissions('chats:read', 'chats:send')` | Method | Requires **any** of the listed permissions |
+| `@RequireAllPermissions('users:invite', 'clinics:read')` | Method | Requires **all** of the listed permissions |
+| `@Features('whatsapp_agent')` | Method/Controller | Requires the tenant feature flag to be enabled |
+| `@CurrentUser()` | Parameter | Extracts `JwtPayload` from the request |
+| `@AccessibleClinics()` | Parameter | Extracts `clinicIds` injected by `ClinicAccessGuard` |
+
+### Guard Composition Examples
+
+```typescript
+// Basic: just authentication
+@UseGuards(JwtAuthGuard)
+
+// Authentication + permission check
+@UseGuards(JwtAuthGuard, PermissionsGuard)
+
+// Authentication + permission + feature flag
+@UseGuards(JwtAuthGuard, PermissionsGuard, FeaturesGuard)
+
+// Authentication + clinic scoping
+@UseGuards(JwtAuthGuard, ClinicAccessGuard)
+
+// Full stack: auth + permission + feature + clinic
+@UseGuards(JwtAuthGuard, PermissionsGuard, FeaturesGuard, ClinicAccessGuard)
+```
+
+### Complete Controller Example
+
+```typescript
+@Controller('chats')
+@UseGuards(JwtAuthGuard, PermissionsGuard, ClinicAccessGuard)
+export class ChatsController {
+
+  @Get()
+  @Permissions('chats:read')
+  async listChats(
+    @CurrentUser() user: JwtPayload,
+    @AccessibleClinics() clinicIds: string[],
+  ) {
+    // clinicIds is auto-populated:
+    //   owner/superadmin -> all clinics (empty array = no filter)
+    //   receptionist -> only assigned clinics
+    return this.chatsService.findAll(user.tenantId, clinicIds);
+  }
+
+  @Post(':chatId/messages')
+  @Permissions('chats:send')
+  async sendMessage(
+    @CurrentUser() user: JwtPayload,
+    @Param('chatId') chatId: string,
+    @Body() body: SendMessageDto,
+  ) {
+    // ClinicAccessGuard already verified user has access to this chat's clinic
+    return this.chatsService.sendHumanMessage(chatId, user.id, body.text);
+  }
+}
+```
+
+### Feature-Gated Example
+
+```typescript
+@Controller('whatsapp')
+@UseGuards(JwtAuthGuard, PermissionsGuard, FeaturesGuard)
+@Features('whatsapp_agent')  // Entire controller requires whatsapp_agent feature
+export class WhatsAppController {
+  // All routes here are gated by the feature flag
+}
+```
+
+---
+
+## 15. Sequence Diagrams
+
+### Login (Standard -- No 2FA)
+
+```
+Client                          Server                         Redis         PostgreSQL
+  |                               |                              |               |
+  |  POST /auth/login             |                              |               |
+  |  {email, password}            |                              |               |
+  |------------------------------>|                              |               |
+  |                               |  Find user by email          |               |
+  |                               |-------------------------------------------->|
+  |                               |<--------------------------------------------|
+  |                               |                              |               |
+  |                               |  Verify bcrypt(password)     |               |
+  |                               |  Check user.is_active        |               |
+  |                               |  Check tenant.is_active      |               |
+  |                               |                              |               |
+  |                               |  Resolve permissions, features, clinics     |
+  |                               |-------------------------------------------->|
+  |                               |<--------------------------------------------|
+  |                               |                              |               |
+  |                               |  Sign access JWT (15m)       |               |
+  |                               |  Generate refresh token      |               |
+  |                               |                              |               |
+  |                               |  Store refresh token         |               |
+  |                               |----->SET auth:refresh:{tok}  |               |
+  |                               |<-----------------------------|               |
+  |                               |  Store refresh token in DB   |               |
+  |                               |-------------------------------------------->|
+  |                               |<--------------------------------------------|
+  |                               |                              |               |
+  |  {user, tenant,               |                              |               |
+  |   access_token,               |                              |               |
+  |   refresh_token}              |                              |               |
+  |<------------------------------|                              |               |
+```
+
+### Login with 2FA
+
+```
+Client                          Server                         Redis         PostgreSQL
+  |                               |                              |               |
+  |  POST /auth/login             |                              |               |
+  |  {email, password}            |                              |               |
+  |------------------------------>|                              |               |
+  |                               |  Find user, verify password  |               |
+  |                               |-------------------------------------------->|
+  |                               |<--------------------------------------------|
+  |                               |                              |               |
+  |                               |  user.twoFactorEnabled = true|               |
+  |                               |  Sign temp JWT (5m, sub only)|               |
+  |                               |                              |               |
+  |  {requires_2fa: true,         |                              |               |
+  |   temp_token: "..."}          |                              |               |
+  |<------------------------------|                              |               |
+  |                               |                              |               |
+  |  POST /auth/2fa/authenticate  |                              |               |
+  |  {temp_token, totp_code}      |                              |               |
+  |------------------------------>|                              |               |
+  |                               |  Verify temp_token (5m TTL)  |               |
+  |                               |  Decrypt TOTP secret         |               |
+  |                               |  Verify TOTP code (otplib)   |               |
+  |                               |                              |               |
+  |                               |  (same as standard login     |               |
+  |                               |   from here: resolve perms,  |               |
+  |                               |   sign tokens, store refresh)|               |
+  |                               |----->SET auth:refresh:{tok}  |               |
+  |                               |-------------------------------------------->|
+  |                               |                              |               |
+  |  {user, tenant,               |                              |               |
+  |   access_token,               |                              |               |
+  |   refresh_token}              |                              |               |
+  |<------------------------------|                              |               |
+```
+
+### Token Refresh
+
+```
+Client                          Server                         Redis         PostgreSQL
+  |                               |                              |               |
+  |  POST /auth/refresh           |                              |               |
+  |  {refresh_token}              |                              |               |
+  |------------------------------>|                              |               |
+  |                               |  Check Redis set             |               |
+  |                               |----->GET auth:refresh:{tok}  |               |
+  |                               |<-----------------------------|               |
+  |                               |                              |               |
+  |                               |  Verify in PostgreSQL        |               |
+  |                               |-------------------------------------------->|
+  |                               |<--------------------------------------------|
+  |                               |                              |               |
+  |                               |  Check expiry                |               |
+  |                               |                              |               |
+  |                               |  Delete old refresh token    |               |
+  |                               |----->DEL auth:refresh:{tok}  |               |
+  |                               |-------------------------------------------->|
+  |                               |                              |               |
+  |                               |  Re-resolve user role,       |               |
+  |                               |  permissions, features,      |               |
+  |                               |  clinic assignments from DB  |               |
+  |                               |-------------------------------------------->|
+  |                               |<--------------------------------------------|
+  |                               |                              |               |
+  |                               |  Sign new access JWT (15m)   |               |
+  |                               |  Generate new refresh token  |               |
+  |                               |                              |               |
+  |                               |  Store new refresh token     |               |
+  |                               |----->SET auth:refresh:{new}  |               |
+  |                               |-------------------------------------------->|
+  |                               |                              |               |
+  |  {access_token,               |                              |               |
+  |   refresh_token}              |                              |               |
+  |<------------------------------|                              |               |
+```
+
+### Password Reset
+
+```
+Client                          Server                   Email/SMS        PostgreSQL
+  |                               |                          |               |
+  |  POST /auth/forgot-password   |                          |               |
+  |  {email}                      |                          |               |
+  |------------------------------>|                          |               |
+  |                               |  Find user by email      |               |
+  |                               |-------------------------------------------->|
+  |                               |<--------------------------------------------|
+  |                               |                          |               |
+  |                               |  Generate 32-byte token  |               |
+  |                               |  bcrypt(token) -> hash   |               |
+  |                               |  Store hash, 1h TTL      |               |
+  |                               |-------------------------------------------->|
+  |                               |                          |               |
+  |                               |  Send raw token          |               |
+  |                               |------------------------->|               |
+  |                               |                          |               |
+  |  {message: "Reset link sent"} |                          |               |
+  |<------------------------------|                          |               |
+  |                               |                          |               |
+  |  ... user clicks link ...     |                          |               |
+  |                               |                          |               |
+  |  POST /auth/reset-password    |                          |               |
+  |  {token, new_password}        |                          |               |
+  |------------------------------>|                          |               |
+  |                               |  bcrypt(token), find match               |
+  |                               |-------------------------------------------->|
+  |                               |<--------------------------------------------|
+  |                               |                          |               |
+  |                               |  Check expiry (1h)       |               |
+  |                               |  Check not used          |               |
+  |                               |                          |               |
+  |                               |  Update password hash    |               |
+  |                               |  Revoke ALL refresh tokens               |
+  |                               |  Mark reset token used   |               |
+  |                               |-------------------------------------------->|
+  |                               |                          |               |
+  |  {message: "Password reset"}  |                          |               |
+  |<------------------------------|                          |               |
+```
+
+---
+
+## Appendix: File Locations (NestJS Target)
+
+```
+src/
+  auth/
+    auth.module.ts
+    auth.controller.ts          # /auth/* endpoints
+    auth.service.ts             # JWT + bcrypt + Redis blacklist + 2FA
+    strategies/
+      jwt.strategy.ts           # Passport JWT strategy
+
+  common/
+    guards/
+      jwt-auth.guard.ts         # @UseGuards(JwtAuthGuard)
+      permissions.guard.ts      # @UseGuards(PermissionsGuard)
+      features.guard.ts         # @UseGuards(FeaturesGuard)
+      clinic-access.guard.ts    # @UseGuards(ClinicAccessGuard)
+    decorators/
+      permissions.decorator.ts  # @Permissions()
+      features.decorator.ts     # @Features()
+      current-user.decorator.ts # @CurrentUser()
+      accessible-clinics.decorator.ts # @AccessibleClinics()
+```