Pipeline DLP per i documenti — guida operatore

Quando la scansione DLP è abilitata per un workspace, ogni documento caricato attraversa una scansione asincrona pg-boss dopo l'ingest:

Funzione Enterprise opzionale attivabile per workspace (workspaces.dlpDocumentScanEnabled, default off; l'abilitazione richiede il superamento della eval gate). Fonte: docs/DLP_DOCUMENT_PIPELINE.md (Phase 192, DLP-01..06 — v0.28.1). Righe di provenienza: FACT-CENSUS.md F-DLP-1, F-DLP-2, F-AUDIT-1.

1. Detect — pipeline a 3 livelli: pattern regex configurabili dall'admin (dlpPatternService), validazione checksum per gli identificatori italiani a formato fisso (Codice Fiscale incl. omocodia, P.IVA, IBAN — dlpChecksum), e NER contestuale via LLM per nomi/indirizzi (il client Ollama esistente).
2. Mask — le entità rilevate diventano segnaposto numerati a livello documento ([PERSON_1], [GOV_ID_2], …). Il masking è idempotente (mask∘mask = mask) — la sintassi dei segnaposto non può mai ri-agganciarsi.
3. Re-embed mascherato — document_chunks.chunkText viene riscritto con il testo mascherato, searchVector/searchVectorMulti (FTS) ricalcolati, e i vettori ri-embedd via l'endpoint collector /api/ingest/reembed`. Nessun vettore non redatto resta ricercabile.
4. Encrypt originals — il testo originale e ogni valore di entità sono conservati cifrati AES-256-GCM (encryptionService, contratto ENCRYPTION_KEY). Il masking è one-way: gli originali cifrati sono l'unica copia pulita.

Controlli admin

Toggle per workspace (DLP-01)

Settings → Workspaces → interruttore DLP document scan (colonna workspaces.dlpDocumentScanEnabled, default off).

• L'interruttore resta disabilitato finché la eval gate (sotto) non è passata — la DISABILITAZIONE non è mai bloccata.
• Lo stato flippa ottimisticamente e torna indietro in caso di errore di salvataggio.

Eval gate (DLP-05)

La valutazione della qualità del rilevamento deve passare prima dell'abilitazione:

• POST /api/system/dlp/eval/run (admin) — esegue il runner ripetibile sul corpus di fixture PII italiane committed (packages/server/src/__tests__/fixtures/dlp-eval/). Persiste il risultato in SystemConfig DLP_EVAL_LAST_RUN (non editabile da admin).
• GET /api/system/dlp/eval/result (admin) — legge l'ultimo run; mai eseguito restituisce { passed: false, noRun: true } — mai un pass silenzioso.
• Metrica di gate: zero falsi positivi da checksum soppressi sulle classi GOV_ID/FINANCIAL. La recall PERSON/ADDRESS è documentata sola (nerMode marca stub vs live).

Backfill del corpus legacy (DLP-06)

POST /api/system/dlp/backfill (admin, con conferma AlertDialog nella UI):

• Eval-gated: rifiuta con 409 { error, gate: "eval-not-passed" } quando l'ultimo eval è assente o fallito.
• Idempotente + riprendibile: marker dlpScannedAt — un ri-run in-coda solo i documenti privi del marker.
• Rate-limited: concorrenza di coda 1 (sotto la coda di scansione live).
• La convergenza è pinned dal twin di integrazione (Postgres reale): chunk mascherati persistiti, tsvector ricalcolati, payload reembed byte-equal al testo mascherato, query di audit zero-PII rimanenti.

Le quattro classi di pattern (identificatori europei/italiani)

Le classi checksum (GOV_ID/FINANCIAL) sono deterministiche; quelle contestuali (PERSON/ADDRESS) passano dal NER LLM — la loro recall è documentata nel risultato dell'eval.

Chat re-composition (DLP-03)

I segnaposto mascherati raggiungono la LLM; a fine stream, esattamente una volta, il server ri-composa i segnaposto nel messaggio terminale per gli utenti che possiedono dlp:unmask sul workspace del documento citato. Il campo additivo content nel payload done SSE porta il testo ri-composto; i visitatori widget non ricevano mai testo ri-composto (enforce server-side; per la UI è solo un nascondere il controllo).

Preview unmask (DLP-04)

GET /api/documents/:documentId/text serve il testo mascherato di default. ?unmask=true ri-composa solo attraverso la scala di gate: param valido → toggle del workspace on → resolveWorkspaceRole + permesso dlp:unmask. Ogni arm di mancanza restituisce testo mascherato (200) — l'endpoint non è mai un oracolo di entitlement. Il toggle della UI si disegna solo per gli utenti autorizzati su documenti con entità (assenza dal DOM), è per-vista e non persistito.

Matrice di audit (SC-4)

Ogni percorso di lettura è pinned da un test comportamentale (18 righe: vista testo, preview OCR, synthesis, citations, widget RAG, MCP tools, FTS, export, copia KB, reembed admin). Widget/citations/MCP portano pin negativi hard (mascherati, mai ri-composti).

Questa guida copre la superficie operativa della pipeline DLP dei documenti; l'approfondimento tecnico vive nel post gemello:

• L'approfondimento tecnico

Provenance

---

Riferimento operativo — Simmetric Chat v0.28.1 (docs aggiornate 2026-10-02, census SHA `aca5b8ff`).