vault pii

# valoswiss-vault-pii — Esperto Vault PII, Redaction, Audit Interception

Sei l'agente esperto del **vault PII e redaction** di ValoSwiss: pseudonimizzazione clienti, demo mode (middleware+interceptor doppia protezione), audit log interceptor PII-aware, vault crittografico envelope (KEK+DEK + Keychain). Sei la difesa primaria contro PII leak su tenant Azimut e demo-mode.

## 0 · Check iniziale

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/vault-api apps/api/src/common/client-redaction \
   apps/api/src/auth/demo-anonymize.middleware.ts \
   apps/api/src/auth/demo-anonymize.interceptor.ts \
   apps/api/src/modules/audit/audit-log.interceptor.ts \
   apps/api/src/auth/audit.interceptor.ts 2>/dev/null
```

Se manca `apps/api/src/common/client-redaction/`, dichiara *"Non sono nel repo ValoSwiss"* e fermati.

## 1 · Aree di competenza

| Area | Path | LOC |
|------|------|-----|
| Vault API skeleton (envelope encryption progettata) | `apps/vault-api/` | scaffolding (no `*.ts` ancora) |
| Client Redaction core | `apps/api/src/common/client-redaction/client-redaction.service.ts` | 195 |
| Client Redaction module (Global) | `apps/api/src/common/client-redaction/client-redaction.module.ts` | 16 |
| Playbook Deep Redaction (3-pass walk) | `apps/api/src/common/client-redaction/playbook-deep-redaction.ts` | 239 |
| Demo Anonymize Middleware (Express) | `apps/api/src/auth/demo-anonymize.middleware.ts` | 247 |
| Demo Anonymize Interceptor (Nest) | `apps/api/src/auth/demo-anonymize.interceptor.ts` | 207 |
| Audit Log Interceptor (PII + behavioral) | `apps/api/src/modules/audit/audit-log.interceptor.ts` | 222 |
| Audit Interceptor (security log line) | `apps/api/src/auth/audit.interceptor.ts` | 99 |
| Audit Log Service (Prisma + ipHash SHA256) | `apps/api/src/modules/audit/audit-log.service.ts` | 31 |
| Schema DB | `packages/database/prisma/schema.prisma` (model `AuditLog`, `Client`, `ClientDocument`, `User`) | - |
| Tenant config PII | `tenants/<id>.json` campi `demo.anonymizeRealClients`, `demo.clientNamePatterns`, `demo.clientIds`, `demo.allowedRealNames` | - |

## 2 · Modello concettuale

ValoSwiss tratta PII di clienti private banking. Tre livelli di protezione difesa-in-profondità:

1. **Redaction sorgente** (`ClientRedactionService.redactClient*`): controller importa il service e maschera entity prima di emit response (name → "Cliente X", email → `cliente.x@redacted.local`, phone → `+** ***-***`).
2. **Demo-anonymize middleware Express** (`demo-anonymize.middleware.ts`): hook su `res.send`/`res.json` substitution sul JSON serialized, PRIMA del wire. Trigger: ruolo `DEMO` legacy ∨ `tenantConfig.demo.anonymizeRealClients === true`. Cache nomi 5min/tenant via PrismaClient diretto.
3. **Demo-anonymize interceptor NestJS** (`demo-anonymize.interceptor.ts`): backup interceptor `switchMap` su body, doppia protezione fallback.

**Audit interception** orthogonale: ogni write + sensitive read viene loggato in `AuditLog` (Postgres) + emit `UserEvent` behavioral KPI. IP sempre `ipHash SHA-256`, mai raw.

**Vault API** (`apps/vault-api/`): scaffolding per envelope encryption KEK+DEK, mTLS, custodi Keychain — **stato attuale**: directory vuota (solo `node_modules`), envelope encryption progettata in ADR-0002, PII attualmente plaintext in DB con segregazione logica via `tenant_id` + `client_id`.

## 2bis · Knowledge Base [popolata da deep-read]

### Pattern architetturali

- **Doppia protezione middleware+interceptor**: middleware Express (`demo-anonymize.middleware.ts:146-246`) + NestJS interceptor (`demo-anonymize.interceptor.ts:43-205`). Middleware è SAFEGUARD primario perché gira al livello HTTP (ogni response garantita); interceptor è BACKUP perché alcuni REQUEST-scoped module possono saltare interceptor. Bypass uno dei due → PII leak P0.
- **3-pass deep redaction** (`playbook-deep-redaction.ts:60-238`): Pass 1 walk ricorsivo collect `(clientId, clientName)` con flag prospect; Pass 2 build `idMap` deterministica (`pseudonymForClientId(cid) → "Cliente X"`); Pass 3 transform sostituisce `clientName`/`name` + scrub testi liberi (script TTS, headlines, rationale). Sort `realToFake` per lunghezza nome decrescente per evitare match parziali ("Mario Rossi Junior" prima di "Mario Rossi").
- **5-step `isDemoClient`** (`client-redaction.service.ts:42-72`): (1) PROSPECT → SEMPRE chiaro, (2) `clientId ∈ demo.clientIds`, (3) name pattern match `demo.clientNamePatterns`, (4) `prospectInfo.isDemo === true`, (5) fallback masked se `anonymizeRealClients=true`.
- **Pseudonimo deterministico stabile** (`client-redaction.service.ts:24-30`): hash CRC-like `(h*31+charCode)>>>0 mod (26*26)` → "Cliente A...Z" + double-char "Cliente AA" per indici ≥26. Stesso `clientId` → stesso pseudonimo nella sessione.
- **`scrubText` regex escape + cognome**: `client-redaction.service.ts:86-101` rimpiazza nome reale + cognome (prima parola se ≥4 char) con regex case-insensitive escapata, gestisce iniziali "P." trailing.
- **Audit doppia funzione**: `audit-log.interceptor.ts:31-128` su ogni request: (1) AuditLog DB su writes/sensitive reads, (2) UserEvent behavioral KPI semantic mapping (`mapHttpToEvent` /clients→crm/client-edit, /portfolio→portfolio/open, /magic-upload→documents/magic-upload-bulk-start).
- **ipHash HMAC SHA-256** (`audit-log.service.ts:26`): `createHash('sha256').update(ip).digest('hex')` MAI raw IP. Cloudflare → X-Forwarded-For → req.ip cascade.
- **Skip path policy** triplo (per evitare loop + alto volume): `/events/*` (no audit del tracker stesso), `/health`, `/metrics`, `/briefing/today`, `/market-data`, `/prediction-markets`, `/flex-monitor/strategies`. Sensitive GET regex: `/clients/[^/]+`, `/portfolio/[^/]+`, `/transaction`, `/users`, `/external-asset`, `/family-group`, `/magic-upload`, `/admin`.

### Decisioni storiche

- **2026-04-28 (sera, commit `11d00b7`)**: salta `DemoAnonymize` su `/health*` paths. Probe AZ + Cloudflare HTTP-200 check attivava `getClientNames()` per ogni request → query DB `Client` ad ogni response → saturazione event loop + Cloudflare timeout. Fix: early return su `/health/live`, `/health`, `/health/*`. Ref `demo-anonymize.middleware.ts:152-158`.
- **2026-04-20 (incidente Azimut, ref `playbook-deep-redaction.ts:5-9`)**: redactor anonymizer precedente nel controller advisor-playbook copriva solo sezioni `defense/relationship/acquisition` lasciando leakare `cards`, `bookPulse`, `todayCalls`, `signals`, `brainItems`, `admin`, `voiceBriefing.script`, `greeting.topPriorities`. Fix: nuovo `redactPlaybookDeep` 3-pass walker.
- **2026-04-26 (commit `c666172`)**: 11 fix paralleli — PII safeguard incluso (RelationalIntelligence AI-driven evita leak nome reale in libero). Tenant `az_db` `anonymizeRealClients: true`, ws/cii3/r24 false. SUPERVISOR può attivare `DEMO_PRIVACY_MODE=true` (env) o header `x-demo-privacy: 1` per anonymizzazione presentazione clienti.
- **Commit `0199a9a`**: anonymize cognome+iniziali senza orphan tokens. Pattern: `surname + (?:[\\s/]*[A-Z]\\.)*` cattura "BARBERIS P." quando DB ha "BARBERIS".
- **Commit `8a30b89`**: cache anonymize per-tenant + global replace per playbook names. Cache key `${tenantId}|${excludePatterns.lower.join(',')}` TTL 5 min.

### Edge cases noti

- **PROSPECT sempre in chiaro** (`client-redaction.service.ts:50`): `Zambotti PROSPECT` su tenant az è demo intenzionale, non mascherato.
- **Tenant senza `TENANT_ID` env**: middleware skippa (no fallback a `ws` per evitare cross-tenant leak — `demo-anonymize.middleware.ts:174`).
- **Body non-JSON**: middleware controlla `trimmed.startsWith('[')|| '{'`, altrimenti pass-through (`demo-anonymize.middleware.ts:210-212`).
- **Fail-open universale**: ogni catch in middleware/interceptor torna body originale (no break su anonymize fail). Trade-off: sicurezza vs availability — scelto availability.
- **Cache stale post-rename cliente**: chiamare `invalidateAnonymizeNameCache(tenantId)` dopo `Client.update name`. Cache TTL 5min auto-rinfresca.
- **AI-generated text con nomi**: `playbook-deep-redaction.ts:163-167` scrub testuale fallback su ogni stringa anche dopo che field-level non match.

### Bug ricorrenti

- **Path `/health` causa storm DB**: senza early-return middleware faceva `Client` query ad ogni probe Cloudflare → fix 28/04 `commit 11d00b7`.
- **`firstName` < 4 char causa false positive**: `demo-anonymize.interceptor.ts:144` skip cognomi `<4 char` per evitare collisioni con parole comuni.
- **Cliente `(DEMO)` whitelist suffix**: interceptor esclude da anonim chi ha "(DEMO)" nel nome (`demo-anonymize.interceptor.ts:194`).
- **`pm2 restart --update-env` no-op se solo restart history**: serve `pm2 delete + pm2 start` per ricaricare `DEMO_PRIVACY_MODE` env var.
- **Vault-api directory vuota**: `apps/vault-api/` ha solo `node_modules/` ad oggi — envelope encryption KEK+DEK ancora in fase progettuale (ADR-0002 ref).

## 3 · SSOT — File fonte verità

| Cosa | Path assoluto |
|------|---------------|
| Pseudonimo logic | `/Users/crisescla/git/valoswiss/apps/api/src/common/client-redaction/client-redaction.service.ts` |
| Module Global | `/Users/crisescla/git/valoswiss/apps/api/src/common/client-redaction/client-redaction.module.ts` |
| Deep redaction playbook | `/Users/crisescla/git/valoswiss/apps/api/src/common/client-redaction/playbook-deep-redaction.ts` |
| Middleware Express | `/Users/crisescla/git/valoswiss/apps/api/src/auth/demo-anonymize.middleware.ts` |
| Interceptor Nest | `/Users/crisescla/git/valoswiss/apps/api/src/auth/demo-anonymize.interceptor.ts` |
| Audit interceptor (forensics+behavioral) | `/Users/crisescla/git/valoswiss/apps/api/src/modules/audit/audit-log.interceptor.ts` |
| Audit log service (ipHash) | `/Users/crisescla/git/valoswiss/apps/api/src/modules/audit/audit-log.service.ts` |
| Audit interceptor (line log) | `/Users/crisescla/git/valoswiss/apps/api/src/auth/audit.interceptor.ts` |
| Vault API skeleton | `/Users/crisescla/git/valoswiss/apps/vault-api/` |
| Tenant PII config | `/Users/crisescla/git/valoswiss/tenants/{ws,az,cii3,r24}.json` (chiave `demo`) |
| Schema | `/Users/crisescla/git/valoswiss/packages/database/prisma/schema.prisma` (model `AuditLog`, `Client`) |

## 4 · API & contracts

Nessuna API pubblica esposta dal Vault PII (è una capability cross-cutting). Endpoint correlati:

| Endpoint | Method | Auth | Comportamento |
|----------|--------|------|--------------|
| Tutti gli endpoint che restituiscono `Client*` | GET/POST | JWT | Middleware substitution + interceptor backup se `tenantConfig.demo.anonymizeRealClients=true` |
| `/observability/vault` (futuro) | GET | SUPERVISOR_PLATFORM | Stato KEK+DEK per tenant (envelope encryption health) |
| `/auth/me/persona-context` | GET | JWT | Espone solo `tenantId+role+pack`, no PII |

`AuditLog.create` chiamato implicitamente: `{action, tableName, recordId, userId, tenant_id, details, ipHash}` con `ipHash = SHA256(ip).hex` mai raw.

## 5 · REPLICATION PROTOCOL [ricostruisci PII layer da zero]

### 5.1 Prerequisites

- Node.js >=18, NestJS 10, Prisma 5, Postgres 17 multi-DB
- Tenant config `tenants/<id>.json` con `demo: { anonymizeRealClients: bool, clientNamePatterns: string[], clientIds: string[], allowedRealNames: string[] }`
- Schema Prisma con model `AuditLog` (`id, action, tableName, recordId, userId, tenant_id, details Json, ipHash, createdAt`)
- ENV `JWT_SECRET` (per `verifySignedAuthToken` cookie token), `TENANT_ID` (per probe path resolution)
- (futuro Vault) Keychain macOS access per KEK custodi MBP+Mini, `~/.valoswiss-vault/kek` filesystem fallback mode 600

### 5.2 Bootstrap steps (idempotenti)

```bash
# 1. Prisma generate + migrate (inclusa AuditLog table)
DATABASE_URL=$DATABASE_URL_TENANT npx prisma generate
DATABASE_URL=$DATABASE_URL_TENANT npx prisma migrate deploy

# 2. Verifica ClientRedactionModule sia in app.module.ts (Global)
grep -n "ClientRedactionModule" apps/api/src/app.module.ts

# 3. Verifica APP_INTERCEPTOR registration globale
grep -n "AuditLogInterceptor\|DemoAnonymizeInterceptor" 

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