Rimuovere i dati personali (PII) da un PDF tramite Connect

In breve

Questa ricetta mostra come rimuovere i dati personali rilevati dal livello di testo di un documento usando gli strumenti di redazione esposti da NextPDF Connect. Tali strumenti sono di livello Enterprise. ToolRegistry costruisce redact_pdf, zone_redact_pdf e deidentify_pdf verificando la presenza delle classi privacy Enterprise (RedactionEngine + PiiDetector) tramite class_exists() e li registra nel livello enterprise solo quando tali classi sono caricabili automaticamente. In un’installazione esclusivamente open source gli strumenti sono assenti: la chiamata fallisce con un errore di strumento sconosciuto, senza degradare in modo silenzioso. Tutti e tre gli strumenti dichiarano destructiveHint: true. La modifica riscrive il contenuto della pagina e non è reversibile a partire dal documento modificato.

Questa pagina documenta il comportamento degli strumenti sulla superficie Connect. Un flusso di redazione non certifica che un determinato documento sia privo di dati personali dopo la chiamata. Il rilevamento opera unicamente sul livello di testo estraibile e la verifica del risultato resta responsabilità del deployment.

Installazione

composer require nextpdf/server

Gli strumenti di redazione si registrano solo quando il modulo privacy Enterprise è installato insieme al server. È fornito in nextpdf/premium. Verificare che lo strumento sia presente nel deployment in esecuzione prima di farvi affidamento:

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
EOF

Se redact_pdf è assente dal risultato di tools/list, le classi privacy Enterprise non sono state risolte in questa installazione. Consultare /connect/tool-catalog/ per capire come il registry calcola all’avvio l’insieme di strumenti per livello.

Panoramica concettuale

Tre strumenti coprono tre strategie di redazione. Sono tutti di livello Enterprise e riportano tutti l’avviso di operazione distruttiva:

redact_pdf — rileva e rimuove i dati personali nel contenuto testuale semplice del documento usando un rilevatore integrato e restituisce il contenuto modificato insieme a un report strutturato.
zone_redact_pdf — applica al contenuto testuale semplice redazioni per zona basate sulle coordinate. Da usare quando la regione da rimuovere è nota per posizione anziché in base a un pattern.
deidentify_pdf — applica una strategia sistematica di de-identificazione (redazione o soppressione) alle entità rilevate.

La rimozione di contenuto da un flusso di contenuto di pagina è una modifica distruttiva di tale flusso: i byte interessati vengono riscritti e non sono recuperabili a partire dal documento modificato (ISO 32000-2 §14.11). Per scelta progettuale, il report registra il numero di caratteri e la posizione di ciascuna rimozione, mai il testo rimosso.

Superficie API

Lo schema esatto di richiesta e risposta per ciascuno strumento è fornito con il pacchetto Enterprise che lo definisce. Questa pagina documenta il contratto di invocazione di Connect, non un elenco fisso di parametri. I nomi degli strumenti verificati rispetto al registry in esecuzione sono redact_pdf, zone_redact_pdf e deidentify_pdf, tutti nella categoria document con destructiveHint: true. Il catalogo di riferimento è /connect/tool-catalog/. Questa ricetta non ribadisce un conteggio degli strumenti, perché si tratta di una proprietà di runtime del deployment.

Esempio di codice — Avvio rapido

Rilevare e rimuovere tramite MCP (tools/call). Gli argomenti seguenti illustrano la forma della chiamata. Lo schema autorevole degli argomenti è quello restituito da tools/list nel proprio deployment:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "redact_pdf",
    "arguments": {
      "source": "/var/lib/nextpdf/in/employee-directory.pdf"
    }
  }
}

Una chiamata riuscita restituisce un report. Per ogni rimozione, una voce registra la pagina, un’etichetta di categoria, il numero di caratteri originale e un riquadro di delimitazione, ma non il testo rimosso.

Esempio di codice — Produzione

Trattare la chiamata di redazione come un’operazione distruttiva ed esaminare il report prima di rilasciare il documento. Con un trasporto di rete, un guasto del trasporto e un errore a livello di strumento sono due casi distinti:

curl -sS -X POST https://connect.example.com/v1/tools/redact_pdf \
  -H 'Authorization: Bearer '"$NEXTPDF_CONNECT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"source":"/var/lib/nextpdf/in/legal-discovery-batch.pdf"}' \
  -o /tmp/redaction-report.json -w '%{http_code}' > /tmp/redaction-status

status="$(cat /tmp/redaction-status)"
if [ "$status" != "200" ]; then
  # 4xx/5xx is a normal HTTP outcome the caller inspects, not a transport
  # failure. A connection error (curl non-zero exit) is the separate case.
  echo "redact_pdf returned HTTP $status; inspect the body, do not release the document" >&2
  exit 1
fi

Rilasciare il documento modificato solo dopo che una persona o un controllo a valle ha esaminato il report. Subordinare il rilascio a questa revisione colloca il controllo nel punto in cui la modifica automatica introduce il rischio di dati residui (IEC 31010:2019).

Casi limite e insidie

PDF scansionato senza livello di testo. Il rilevamento opera sul livello di testo estraibile. Una pagina composta solo da immagini produce zero rimozioni e non costituisce un errore. Se il contenuto è rasterizzato, eseguire l’OCR del documento prima della redazione.
Origine cifrata. Fornire la password del documento tramite lo schema degli argomenti dello strumento. In mancanza della password, la chiamata fallisce anziché elaborare parzialmente.
Strumento assente. In un’installazione esclusivamente open source le classi privacy Enterprise non vengono risolte e redact_pdf non è registrato, perciò la chiamata fallisce con un errore di strumento sconosciuto. Questo è il limite previsto, non un degrado.
Rilevamenti sovrapposti. Quando più di un rilevatore individua la stessa regione, la regione viene rimossa una sola volta e il report elimina i duplicati.

Prestazioni

Il budget prestazionale nel front-matter è un limite documentale, non una garanzia di livello di servizio. I documenti di grandi dimensioni vengono elaborati pagina per pagina. Prevedere la riesecuzione della chiamata su un sottointervallo di pagine anziché aumentare un timeout globale.

Note di sicurezza

Residenza dei dati e mitigazioni dei dati personali (PII)

Il testo del documento viene elaborato in-process sull’host Connect. Il report omette deliberatamente il testo rimosso e riporta solo conteggi e posizioni, così che il report stesso non reintroduca i dati personali che descrive. La residenza dei dati a livello di deployment per l’input e l’output modificato è responsabilità dell’integratore, non una proprietà dello strumento.

Telemetria sicura e ripulitura dei log

Non registrare il percorso del documento di origine né il corpo del report in un livello di log inviato all’esterno. Registrare solo il nome dello strumento, l’id della richiesta e l’esito pass/fail.

Modello di minaccia

Una redazione che copre visivamente il testo ma non lo rimuove lascia i dati estraibili. Questi strumenti riscrivono il flusso di contenuto interessato anziché sovrapporre un rettangolo; il recupero dei byte rimossi a partire dal documento modificato non è possibile (ISO 32000-2 §14.11). Il rischio residuo è costituito dal contenuto non individuato dal rilevatore: un pattern al di fuori delle sue regole oppure testo presente solo come immagine rasterizzata. Il flusso mitiga questo rischio con la revisione obbligatoria del report, non con un’affermazione di completezza.

Comportamento in modalità FIPS

La redazione non esegue alcuna operazione crittografica e non è influenzata da una policy in modalità FIPS sull’host.

Conformità

Affermazione	Clausola	reference_id
La rimozione di contenuto riscrive il flusso di contenuto interessato	ISO 32000-2 §14.11
La redazione prima contrassegna e poi rimuove; la rimozione è una modifica del contenuto	ISO 32000-2 §14.11
Controllo collocato nel punto in cui la modifica automatica introduce il rischio	IEC 31010:2019

Il supporto per gli strumenti di redazione non certifica che un documento elaborato sia privo di dati personali. Tale determinazione spetta a una revisione indipendente.

Contesto commerciale

Gli strumenti di redazione sono di livello Enterprise. Si registrano solo quando nextpdf/premium è installato insieme al server. Consultare il link di conversione nel front-matter.

Specifiche di Connect

Disponibilità dei trasporti (MCP / REST / gRPC)

Gli strumenti si invocano allo stesso modo su ogni trasporto che pilota l’esecutore di strumenti condiviso: MCP tools/call, l’endpoint dello strumento REST e il servizio gRPC. Lo schema degli argomenti è indipendente dal trasporto. È quello restituito da tools/list (MCP) o dal descrittore del servizio (gRPC).

Livello di rischio HITL

Tutti e tre gli strumenti dichiarano destructiveHint: true. Un operatore che eleva uno strumento al livello di rischio approval_required tramite un override di configurazione sottopone la chiamata al ConfirmationGate. L’override può solo aumentare il rischio, mai ridurlo. Consultare /connect/hitl-risk-tiers/.

Envelope JSON del gate di conferma

Quando lo strumento è sottoposto al gate e viene invocato senza un token valido, il gate restituisce un envelope di challenge in questa forma:

{ "allowed": false, "challenge": "<human-readable text>", "token": "confirm_<nonce>" }

Il chiamante reinvoca lo stesso strumento con arguments._confirmation_token impostato sul token emesso. Il token vincola il nome dello strumento, un nonce e un TTL di 300 secondi — non gli argomenti — ed è monouso.

Vedere anche

/connect/tool-catalog/ — come il registry calcola l’insieme di strumenti per livello.
/connect/hitl-risk-tiers/ — il modello di rischio a quattro livelli e il gate.
/cookbook/connect/extract-text-content/ — visualizzare in anteprima il testo estraibile prima della redazione.
/cookbook/connect/digital-signature/ — firmare il documento modificato per la catena di custodia.