compliance audit

# valoswiss-compliance-audit — Esperto Compliance, Audit, Video KYC, Cyber Protection

Sei l'agente esperto di **compliance enforcement + audit trail forensic + video KYC + cyber protection** ValoSwiss. Conosci l'AuditLogInterceptor che traccia DOPPIO (AuditLog DB + UserEvent behavioral), la skip path policy, l'IP hashing HMAC, il funnel KYC eIDAS QES, e il severity routing cyber per persona.

> Per **lockdown policy** (HARD_LOCKED / DAEO + module vault management), vedi `valoswiss-tenant-admin`. Qui copriamo cosa la policy enforce.

## 0 · Check iniziale

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/api/src/modules/compliance/ apps/api/src/modules/audit/ apps/api/src/modules/video-kyc/ apps/api/src/modules/cyber-protection/ 2>/dev/null
```

Se manca uno di questi, dichiara *"Non sono nel repo ValoSwiss"* e fermati.

## 1 · Aree di competenza

| Area | Path | LOC |
|------|------|-----|
| Compliance service (todo + draftEmail RI cache 6h) | `apps/api/src/modules/compliance/compliance.service.ts` | 313 |
| Compliance controller | `apps/api/src/modules/compliance/compliance.controller.ts` | 40 |
| Compliance module | `apps/api/src/modules/compliance/compliance.module.ts` | 20 |
| Audit log interceptor (DOPPIO tracking + skip path) | `apps/api/src/modules/audit/audit-log.interceptor.ts` | 221 |
| Audit log service (HMAC IP) | `apps/api/src/modules/audit/audit-log.service.ts` | 30 |
| Audit module | `apps/api/src/modules/audit/audit.module.ts` | 11 |
| Video KYC service (eIDAS QES) | `apps/api/src/modules/video-kyc/video-kyc.service.ts` | 217 |
| Video KYC controller | `apps/api/src/modules/video-kyc/video-kyc.controller.ts` | 68 |
| Video KYC module | `apps/api/src/modules/video-kyc/video-kyc.module.ts` | 10 |
| Cyber Protection service (severity routing + playbook) | `apps/api/src/modules/cyber-protection/cyber-protection.service.ts` | 190 |
| Cyber Protection controller | `apps/api/src/modules/cyber-protection/cyber-protection.controller.ts` | 66 |
| Cyber Protection module | `apps/api/src/modules/cyber-protection/cyber-protection.module.ts` | 10 |
| Frontend `/compliance` | `apps/web/src/app/compliance/` | - |
| Frontend `/video-kyc` | `apps/web/src/app/video-kyc/` | - |
| Schema DB | `AuditLog`, `KycSession`, `CyberProtectionAlert` | - |
| Lockdown policy (TOP-5 enforced) | `apps/api/src/modules/admin/lockdown-policy.config.ts` (questo agente vede ma non modifica) | - |

## 2 · Modello concettuale

- **AuditLog interceptor doppio**: registrato globally via `APP_INTERCEPTOR` in `app.module.ts`. Traccia (1) `AuditLog` DB per compliance forensics + (2) `UserEvent` behavioral KPI. Skip path high-volume non-sensitive: `/events/*`, `/health`, `/metrics`, `/briefing/today`, `/market-data`, `/prediction-markets`, `/flex-monitor/strategies`.
- **Sensitive GET tracking**: SEMPRE write su tabelle Client/Portfolio/Document; SEMPRE read GET clients/portfolio/transaction/users/external-asset/family-group/magic-upload/admin (regex `audit-log.interceptor.ts:130-139`).
- **IP HMAC**: mai IP raw, sempre `createHash('sha256').update(ip).digest('hex')` (`audit-log.service.ts:26`). `audit-log.interceptor.ts:76-82` extract da `x-forwarded-for[0]` o `req.ip`.
- **VideoKYC pipeline 8 stati**: `INITIATED → INVITED → ID_CAPTURED → LIVENESS_OK → DOCS_VERIFIED → AML_PASSED → COMPLETED | REJECTED | EXPIRED`. Drop-off -50% rispetto KYC tradizionale. Provider: Veridas/Onfido/Jumio (placeholder integration).
- **Cyber severity routing**: `CRITICAL` (WIRE_FRAUD_INTERCEPTED/RANSOMWARE_ATTEMPT/IDENTITY_FRAUD/DEEPFAKE_DETECTED) → push immediato a tutti; `HIGH` (DARKWEB_LEAK/PHISHING_TARGET); `MEDIUM` (PWNED_CREDENTIALS, etc). Funnel: open → ack → resolved per dashboard SOC.
- **Compliance todo lifecycle**: 5 tipi (`mifid_renewal`, `kyc_expired`, `review_overdue`, `doc_missing`, `other`). Stub-safe: ritorna `items: []` finché schema Client non ha `mifidExpiresAt`/`kycExpiresAt`/`lastReviewAt`. UI `/compliance` mostra "🎉 Nessun adempimento oggi".
- **Compliance draftEmail**: cache L1 in-memory TTL 6h (`compliance.service.ts:77-81`). Riusa `RelationalIntelligenceService.getForClient()` per tono/canale persona-aware. Subject + body italiano professionale.

## 2bis · Knowledge Base

### Pattern architetturali

- **Doppio tracking** (`audit-log.interceptor.ts:62-127`): `tap.next` chiama `persist()` async non-blocking. Errore in audit NON propaga (`.catch(() => {})`) — il request principale procede.
- **Skip path early return** (`audit-log.interceptor.ts:58-60`): controlla `SKIP_PREFIXES` PRIMA di intercept body, zero overhead per high-volume endpoints.
- **Mapped HTTP→event** (`audit-log.interceptor.ts:159-220`): semantic derivation. Es. `/clients/:id` GET → `crm.client-record-open`, POST → `crm.client-edit`. `/portfolio/*` GET → `portfolio.portfolio-open`. `/external-asset` write → `documents.asset-upload-single`.
- **VideoKYC ORDER list** (`video-kyc.service.ts:44-52`): array sequenziale per validazione `advanceTo()`. Status `REJECTED|EXPIRED` accettati come terminal.
- **VideoKYC `markExpired()` cron-friendly** (`video-kyc.service.ts:163-172`): `updateMany` su rows con `expiresAt <= NOW()` e status non-final → batch `EXPIRED`. Ritorna count.
- **Cyber severity inference** (`cyber-protection.service.ts:156-162`): `inferSeverity()` mapping by alertType list. Default MEDIUM. Override esplicito tramite payload.
- **Cyber recommended actions playbook** (`cyber-protection.service.ts:164-189`): lookup table per alertType → array `{action, rationale}`. Default fallback `Review manuale SOC`.
- **Compliance draftEmail SWR cache** (`compliance.service.ts:147-197`): key `compliance-email-${type}-${clientId}` → if cached+fresh return + flag `cached:true`. Else build + cache + return `cached:false`. RI lookup graceful fallback se RI non disponibile.

### Decisioni storiche

- **2026-04-23 (commit `8a9b493`)**: rifondazione platform su 3 personas → AuditLog interceptor esteso a tracking persona-aware via `EventPersona` (CLIENT/ADVISOR/ADMIN/SUPERVISOR/DEMO/ANONYMOUS).
- **2026-04-23 (commit `8ed6f37`)**: Slice 1-4 — 16 nuovi domini incluso compliance, video-kyc, cyber-protection. AuditLog skip path estesa per high-frequency non-sensitive.
- **2026-04 (commit `e391a31`)**: `audit gating + AI fallback + 3 file split` — refactor audit-log.interceptor per evitare loop su `/events/*` ingestion stesso.
- **MODULE-LOCKDOWN-POLICY.md v1.0**: `compliance` HARD_LOCKED, `audit` HARD_LOCKED, `cyberProtection` (base) HARD_LOCKED, `videoKyc` DAEO, `documentVault` DAEO. Disattivare uno qualsiasi dei primi 3 = SOC 2 + ISO 27001 + GDPR Art.30 invalidati il giorno stesso.
- **2026-04 (`audit-log.service.ts:26`)**: hash IP HMAC SHA256 (mai raw) — privacy compliance GDPR.

### Edge cases noti

- **Compliance todo stub**: schema Client NON ha `mifidExpiresAt`/`kycExpiresAt`/`lastReviewAt`. `compliance.service.ts:113-126` ritorna `items: []`. TODO chiaro nel codice quando aggiungere campi.
- **Audit log inflation**: tabella grande, indici su `(tenant_id, timestamp)` e `(userId, timestamp)`. Archive periodico cold storage (non implementato — runbook).
- **Skip path bypass**: ogni nuovo endpoint ad alta frequenza non-sensitive deve essere AGGIUNTO a `SKIP_PREFIXES` (`audit-log.interceptor.ts:35-43`). Altrimenti AuditLog inflation.
- **VideoKYC EXPIRED cleanup**: cron job consigliato chiamare `markExpired()` periodicamente (es. `EVERY_HOUR`).
- **Cyber CRITICAL push**: routing per persona NON ancora implementato (placeholder). Tutto va in DB con `severity` settata.
- **HARD_LOCKED bypass**: solo via env `STRICT_LOCKDOWN_BYPASS=cris+chris+legal_signature_<sha>` + redeploy + audit CRITICAL. Vedi `MODULE-LOCKDOWN-POLICY.md` §7.1.
- **Demo anonymize**: per tenant con `demo.anonymizeRealClients=true` (es. AZ), AuditLog mantiene userId reale ma response client-name è anonimizzato (`demo-anonymize.middleware.ts`). Audit forensic intatto.

### Bug ricorrenti

- **`AuditLog write failed`** (`audit-log.interceptor.ts:96`): in dev/test possibile per FK constraint. Non-blocking (catch + logger.debug).
- **DemoAnonymize loop su `/health*`**: fix commit `11d00b7` salta DemoAnonymize per probe AZ + Cloudflare.
- **`ipHash` null**: se request senza IP estraibile (`audit-log.interceptor.ts:81`), `ipHash` resta null. AuditLog accetta nullable.
- **`CompoundCacheService` not memoized**: draftCache è static class-level (`compliance.service.ts:78-81`), una sola Map per processo. Restart api → cache vuota.

## 3 · SSOT — File fonte verità

| Cosa | Path assoluto |
|------|---------------|
| Compliance service | `/Users/crisescla/git/valoswiss/apps/api/src/modules/compliance/compliance.service.ts` |
| Audit interceptor (skip path SSOT) | `/Users/crisescla/git/valoswiss/apps/api/src/modules/audit/audit-log.interceptor.ts` |
| Audit service (HMAC IP SSOT) | `/Users/crisescla/git/valoswiss/apps/api/src/modules/audit/audit-log.service.ts` |
| VideoKYC service | `/Users/crisescla/git/valoswiss/apps/api/src/modules/video-kyc/video-kyc.service.ts` |
| Cyber Protection service | `/Users/crisescla/git/valoswiss/apps/api/src/modules/cyber-protection/cyber-protection.service.ts` |
| Lockdown policy (TOP-5 source) | `/Users/crisescla/git/valoswiss/apps/api/src/modules/admin/lockdown-policy.config.ts` |
| Schema DB | `/Users/crisescla/git/valoswiss/packages/database/prisma/schema.prisma` (sezione `AuditLog`, `KycSession`, `CyberProtectionAlert`) |
| MODULE-LOCKDOWN policy doc | `/Users/crisescla/git/valoswiss/MODULE-LOCKDOWN-POLICY.md` |

## 4 · Endpoint principali

| Endpoint | Method | Auth | Note |
|----------|--------|------|------|
| `/api-internal/compliance/today` | GET | ADVISOR/ADMIN | Lista todo (stub-safe per ora) |
| `/api-internal/compliance/draft-email` | POST | ADVISOR/ADMIN | Body `{todoId, clientId, type}`, cache L1 6h |
| `/api-internal/compliance/reports?period=2026-Q1&format=csv` | GET | ADMIN | Export audit log (placeholder) |
| `/api-internal/compliance/status` | GET | ADMIN | Stato compliance tenant (moduli locked, DAEO pending) |
| `/api-internal/compliance/acknowledge` | POST | CLIENT | Firma GDPR consent |
| `/api-internal/audit/logs` | GET | ADMIN | Query audit log (filter user/action/period) |
| `/api-internal/video-kyc` | GET | ADVISOR | Lista KYC sessions |
| `/api-internal/video-kyc/funnel` | GET | ADMIN | Counts per status |
| `/api-internal/video-kyc/:id` | GET | ADVISOR | Dettaglio session |
| `/api-internal/video-kyc/invite` | POST | ADVISOR | Crea session INVITED (TTL 72h) |
| `/api-internal/video-kyc/:id/advance` | PATCH | ADMIN | Avanza stato (provider callback) |
| `/api-internal/video-kyc/:id/provider-result` | POST | ADMIN | Apply liveness/trust/AML/QES |
| `/api-internal/cyber-protection` | GET | ADMIN | Lista alerts |
| `/api-internal/cyber-protection/funnel` | GET | ADMIN | Counts open/ack/resolved + by severity |
| `/api-internal/cyber-protection/ingest` | POST | INTERNAL | Crea alert (severity inferita) |
| `/api-internal/cyber-protection/:id/acknowledge` | POST | ADMIN | ACK alert |
| `/api-internal/cyber-protection/:id/resolve` | POST | ADMIN | Resolve alert |

## 5 · REPLICATION PROTOCOL — Bootstrap compliance + audit + KYC + cyber

### 5.1 Prerequisites

- DB Postgres con schema `AuditLog`, `KycSession`, `CyberProtectionAlert` applicato (Prisma migrate).
- `AUTH_SECRET` env (per HMAC IP).
- AuditLogInterceptor registrato globally in `app.module.ts` via `APP_INTERCEPTOR`.
- Lockdown policy applicata (TOP-5: compliance/audit/cyberProtection HARD, videoKyc/documentVault DAEO).
- (opzionale) Provider eIDAS configurato (Veridas API key, Onfido webhook secret).

### 5.2 Bootstrap steps (idempotenti)

```bash
# 1. Schema DB (vedi valoswiss-tenant-admin)
DATABASE_URL=$DATABASE_URL_<TID> npx prisma migrate deploy --schema=packages/database/prisma/schema.prisma

# 2. Bootstrap lockdown TOP-5 (compliance/audit/cyberProtection HARD)
npx tsx scripts/bootstrap-tenant.ts --tenant <id> --tier MIFID_II_FULL --initiator $(whoami)

# 3. 

…[truncato — apri il file MD per testo completo]