# Security & Privacy Posture (`SECURITY.md`)

This document outlines the security controls, multi-tenant isolation boundaries, and GDPR/AI Act privacy capabilities implemented across the platform.

---

## 1. Authentication & Session Security
- **Password Storage**: Passwords are salted with 16 cryptographic random bytes and hashed using `scrypt` (`64-byte` key length) and verified in constant time via `crypto.timingSafeEqual` ([`src/utils/auth.ts`](file:///c:/wamp64/www/Ai-voice-agent-call-center-project/services/call-engine/src/utils/auth.ts)).
- **Brute-Force Account Lockout**: After **5 consecutive failed login attempts**, the user account is automatically locked for **15 minutes** (`lockedUntil` on `User.model.ts`) and an immutable `auth.login_locked` event is written to `AuditLog`.
- **Token Rotation**: Stateless HMAC-SHA256 JWT tokens with dedicated `/api/auth/refresh` rotation and strict expiration verification.

---

## 2. Multi-Tenant Isolation & RBAC
- **4-Tier Role Hierarchy**: `super_admin` | `owner` | `admin` | `member` enforced via `requireAuth` and `requireRole` middleware ([`src/middleware/auth.middleware.ts`](file:///c:/wamp64/www/Ai-voice-agent-call-center-project/services/call-engine/src/middleware/auth.middleware.ts)).
- **Row-Level Tenant Scoping**: Every MongoDB query across `Company`, `CallSession`, `ConversationTurn`, `Appointment`, `KnowledgeChunk`, `CrmConfig`, and `AuditLog` is scoped to `req.user.tenantName`. Cross-tenant `PUT`/`DELETE` attempts return `403 Forbidden` (verified by automated tests in [`src/tests/phase6SecurityAndLoad.test.ts`](file:///c:/wamp64/www/Ai-voice-agent-call-center-project/services/call-engine/src/tests/phase6SecurityAndLoad.test.ts)).

---

## 3. OWASP Top 10 Mitigations
- **SSRF Protection (`A10:2021`)**: The Website-to-Agent URL crawler (`POST /api/company/generate-from-url`) validates all URLs through [`src/utils/ssrfGuard.ts`](file:///c:/wamp64/www/Ai-voice-agent-call-center-project/services/call-engine/src/utils/ssrfGuard.ts):
  - Rejects non-`http:`/`https:` schemes (`file:`, `ftp:`, `gopher:`, `javascript:`).
  - Performs DNS resolution (`dns.lookup(..., { all: true })`) before connecting and blocks IPv4 loopback (`127.0.0.0/8`), RFC1918 private ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), link-local/cloud metadata (`169.254.169.254`), CGNAT (`100.64.0.0/10`), and IPv6 loopback/unique-local (`::1`, `fc00::/7`, `fe80::/10`).
- **Schema Validation (`A03:2021`)**: Request payloads are validated using **Zod** schemas via `validateBody()`.
- **HTTP Security Headers (`A05:2021`)**: `securityHeaders` middleware sets `Content-Security-Policy`, `Strict-Transport-Security` (HSTS), `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, and `Referrer-Policy: strict-origin-when-cross-origin`.
- **Webhook Authenticity (`A08:2021`)**: Twilio webhooks (`/twilio/*`) verify `X-Twilio-Signature` using HMAC-SHA1 (`twilio.validateRequest`) when `ENFORCE_TWILIO_SIGNATURE=true`.

---

## 4. GDPR & EU AI Act Compliance
- **AI Transparency & Recording Consent**: Every agent profile supports a configurable welcome greeting disclosing that the caller is speaking with an AI assistant and optional recording consent toggle.
- **PII Redaction**: `redactPii()` masks emails, payment card numbers, and SSNs in application logs.
- **GDPR Art. 15 & Art. 20 (Right to Data Portability)**: Tenant owners/admins can export their entire workspace data bundle as structured JSON via `GET /api/privacy/export`.
- **GDPR Art. 17 (Right to Erasure)**: Tenant owners/admins can permanently purge all call logs, transcripts, and PII via `DELETE /api/privacy/erase-calls`.
- **Immutable Security Audit Trail**: Sensitive actions (logins, lockouts, plan changes, team invites, URL crawls, GDPR exports/erasures) are logged to `AuditLog` (`GET /api/privacy/audit-logs`).