Pipeline DLP para documentos — referência operativa

Quando a varredura DLP está habilitada para um workspace, cada documento carregado atravessa uma varredura assíncrona pg-boss após a ingestão:

Funcionalidade Enterprise opcional ativável por workspace (workspaces.dlpDocumentScanEnabled, por defeito off; a ativação exige passar a eval gate). Fonte: docs/DLP_DOCUMENT_PIPELINE.md (Phase 192, DLP-01..06 — v0.28.1). Linhas de proveniência: FACT-CENSUS.md F-DLP-1, F-DLP-2, F-AUDIT-1.

1. Detect — uma pipeline de 3 níveis: patterns regex configuráveis pela administração (dlpPatternService), validação por checksum para os identificadores italianos de formato fixo (Codice Fiscale incl. a omocodia, P.IVA, IBAN — dlpChecksum) e NER contextual via LLM para nomes/endereços (o cliente Ollama existente).
2. Mask — as entidades detetadas tornam-se marcadores numerados ao nível do documento ([PERSON_1], [GOV_ID_2], …). A máscara é idempotente (mask∘mask = mask) — a sintaxe dos marcadores nunca volta a prender-se.
3. Re-embed mascarado — document_chunks.chunkText é reescrito com o texto mascarado, searchVector/searchVectorMulti (FTS) recalculados, e os vetores re-embedados via o endpoint do collector /api/ingest/reembed. Nenhum vetor não redigido continua pesquisável.
4. Cifra dos originais — o texto original e cada valor de entidade ficam guardados cifrados AES-256-GCM (encryptionService, o contrato ENCRYPTION_KEY). A máscara é one-way: os originais cifrados são a única cópia limpa.

Controlos de administração

O interruptor por workspace (DLP-01)

Settings → Workspaces → o interruptor DLP document scan (a coluna workspaces.dlpDocumentScanEnabled, por defeito off).

• O interruptor fica desabilitado até a eval gate (abaixo) passar — a DESHABILITAÇÃO nunca é bloqueada.
• O estado altera-se de forma otimista e retrocede quando a gravação falha.

A eval gate (DLP-05)

A avaliação da qualidade da deteção tem de passar antes da ativação:

• POST /api/system/dlp/eval/run (admin) — executa o runner repetível sobre o corpus de fixtures PII italianas comprometido (packages/server/src/__tests__/fixtures/dlp-eval/). Persiste o resultado em SystemConfig DLP_EVAL_LAST_RUN (não editável pela administração).
• GET /api/system/dlp/eval/result (admin) — lê a última corrida; nunca executada devolve { passed: false, noRun: true } — nunca uma passagem silenciosa.
• A métrica da barreira: zero falsos positivos de checksums suprimidos nas classes GOV_ID/FINANCIAL. A recall de PERSON/ADDRESS fica documentada somente (nerMode marca stub vs live).

O backfill do corpus legado (DLP-06)

POST /api/system/dlp/backfill (admin, com confirmação AlertDialog na UI):

• Eval-gated: recusa com 409 { error, gate: "eval-not-passed" } quando o último eval falta ou caiu.
• Idempotente + retomável: o marcador dlpScannedAt — um re-run põe em fila só os documentos sem o marcador.
• Rate-limited: concorrência de fila 1 (por baixo da fila de varredura em execução).
• A convergência fica afixada pelo gémeo de integração (Postgres real): chunks mascarados persistidos, tsvector recalculado, o payload reembed byte-igual ao texto mascarado, e as consultas de auditoria = zero PII restante.

As quatro classes de patterns (identificadores europeus/italianos)

As classes de checksum (GOV_ID/FINANCIAL) são determinísticas; as contextuais (PERSON/ADDRESS) passam pela NER LLM — a sua recall fica documentada no resultado do eval.

Chat re-composition (DLP-03)

Os marcadores mascarados alcançam a LLM; ao fim do stream, exatamente uma vez, o servidor recompõe os marcadores na mensagem terminal para os utilizadores que tenham dlp:unmask no workspace do documento citado. O campo aditivo content no payload done do SSE leva o texto recomposto; os visitantes widget NUNCA recebem texto recomposto (aplicado server-side; para a UI é só esconder o controlo).

A pré-visualização unmask (DLP-04)

GET /api/documents/:documentId/text serve o texto mascarado por defeito. ?unmask=true só recompõe através da escada de barreiras: o param válido → o interruptor do workspace on → resolveWorkspaceRole + a permissão dlp:unmask. Cada braço de falta devolve texto mascarado (200) — o endpoint nunca é um oráculo de habilitação. O interruptor da UI desenha-se só para os utilizadores autorizados sobre documentos com entidades (ausência do DOM), é por-vista e nunca persiste.

A matriz de auditoria (SC-4)

Cada via de leitura fica afixada por um teste comportamental (18 linhas: vista de texto, pré-visualização OCR, synthesis, citations, widget RAG, MCP tools, FTS, export, cópia KB, reembed admin). Widget/citations/MCP levam aficações negativas duras (mascarados, nunca recompensados).

Este guia cobre a superfície operacional do pipeline DLP para os documentos; a profundidade técnica vive no post gémeo:

• A profundidade técnica

Provenance

---

Referência operativa — Simmetric Chat v0.28.1 (documentos atualizados a 2026-10-02, SHA do census `aca5b8ff`).