PII in een PDF redigeren via Connect

In een oogopslag

Deze recipe beschrijft hoe gedetecteerde persoonsgegevens (PII) uit de tekstlaag van een document worden verwijderd met de redactiehulpmiddelen die NextPDF Connect beschikbaar stelt. Deze hulpmiddelen vallen binnen Enterprise-niveau. ToolRegistry bouwt redact_pdf, zone_redact_pdf en deidentify_pdf door met class_exists() te controleren of de Enterprise-privacyklassen (RedactionEngine + PiiDetector) beschikbaar zijn. Het registreert elk hulpmiddel uitsluitend op het enterprise-niveau wanneer die klassen via autoloading beschikbaar zijn. Bij een installatie met alleen open source ontbreken de hulpmiddelen: de aanroep mislukt met een fout over een onbekend hulpmiddel in plaats van stilzwijgend terug te vallen. Alle drie de hulpmiddelen declareren destructiveHint: true. De bewerking herschrijft de pagina-inhoud en kan niet vanuit het bewerkte document ongedaan worden gemaakt.

Deze pagina documenteert het gedrag van de hulpmiddelen via de Connect-interface. Een redactieworkflow certificeert niet dat een document na de aanroep vrij is van persoonsgegevens. Detectie vindt uitsluitend plaats in de extraheerbare tekstlaag en de implementatie blijft verantwoordelijk voor de verificatie van het resultaat.

Installeren

composer require nextpdf/server

De redactiehulpmiddelen registreren zich alleen wanneer u de Enterprise-privacymodule naast de server installeert. Deze wordt geleverd in nextpdf/premium. Controleer of het hulpmiddel beschikbaar is in de actieve implementatie voordat u erop vertrouwt:

./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

Als redact_pdf ontbreekt in het resultaat van tools/list, zijn de Enterprise-privacyklassen op deze installatie niet via autoloading beschikbaar. Zie /connect/tool-catalog/ voor uitleg over hoe het register tijdens het opstarten de hulpmiddelenset per niveau berekent.

Conceptueel overzicht

Drie hulpmiddelen ondersteunen drie redactiestrategieën. Ze vallen allemaal binnen Enterprise-niveau en hebben allemaal de destructieve hint:

redact_pdf — detecteert en verwijdert persoonsgegevens uit de tekstinhoud van het document met een ingebouwde detector en retourneert daarna de bewerkte inhoud en een gestructureerd rapport.
zone_redact_pdf — past op coördinaten gebaseerde zoneredacties toe op de tekstinhoud. Gebruik het wanneer u de regio kent op basis van positie en niet op basis van een patroon.
deidentify_pdf — past een systematische de-identificatiestrategie (redigeren of onderdrukken) toe op gedetecteerde entiteiten.

Het verwijderen van inhoud uit een contentstream van een pagina bewerkt die stream destructief: de betrokken bytes worden herschreven en zijn niet herstelbaar uit het bewerkte document (ISO 32000-2 §14.11). Het rapport legt bewust het aantal tekens en de positie van elke verwijdering vast, nooit de verwijderde tekst zelf.

API-oppervlak

Het Enterprise-pakket dat elk hulpmiddel definieert, levert ook het exacte request- en responseschema. Deze pagina documenteert het Connect-aanroepcontract, geen vaste parameterlijst. De hulpmiddelnamen die op basis van het actieve register zijn geverifieerd, zijn redact_pdf, zone_redact_pdf en deidentify_pdf, allemaal in de categorie document met destructiveHint: true. De gezaghebbende catalogus is /connect/tool-catalog/. Deze recipe vermeldt geen totaal aantal hulpmiddelen, omdat die waarde een eigenschap van de implementatie tijdens runtime is.

Codevoorbeeld — snelstart

Detecteer en verwijder inhoud via Model Context Protocol (MCP) (tools/call). De onderstaande argumenten tonen de vorm van de aanroep. Het gezaghebbende argumentschema is het schema dat tools/list in uw implementatie retourneert:

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

Een geslaagde aanroep retourneert een rapport. Voor elke verwijdering legt een vermelding de pagina, een categorielabel, het oorspronkelijke aantal tekens en een omsluitend kader vast, maar niet de verwijderde tekst.

Codevoorbeeld — productie

Behandel de redactieaanroep als een destructieve bewerking en inspecteer het rapport voordat u het document vrijgeeft. Maak bij netwerktransport onderscheid tussen een transportfout en een fout op hulpmiddelniveau:

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

Geef het bewerkte document pas vrij nadat een mens of een downstreamcontrole het rapport heeft beoordeeld. Door vrijgave pas na die beoordeling toe te staan, plaatst u de controle op de plek waar de geautomatiseerde bewerking het risico van restgegevens introduceert (IEC 31010:2019).

Randgevallen en valkuilen

Gescande PDF zonder tekstlaag. Detectie vindt plaats in de extraheerbare tekstlaag. Een pagina die alleen uit een afbeelding bestaat, levert nul verwijderingen op en is geen fout. Als de inhoud gerasterd is, voer dan optische tekenherkenning (OCR) uit op het document vóór de redactie.
Versleutelde bron. Geef het documentwachtwoord op via het argumentschema van het hulpmiddel. Zonder dit wachtwoord mislukt de aanroep in plaats van slechts een deel van het document te verwerken.
Hulpmiddel afwezig. Bij een installatie met alleen open source worden de Enterprise-privacyklassen niet beschikbaar via autoloading en is redact_pdf niet geregistreerd, zodat de aanroep mislukt met een fout over een onbekend hulpmiddel. Dit is de bedoelde grens, geen degradatie.
Overlappende detecties. Wanneer meer dan één detector dezelfde regio matcht, verwijdert het hulpmiddel de regio eenmaal en ontdubbelt het de rapportage.

Prestaties

Het prestatiebudget in de front-matter is een documentatielimiet, geen servicegarantie. Grote documenten worden pagina voor pagina verwerkt. Ga ervan uit dat u de aanroep opnieuw uitvoert voor een subset van het paginabereik, in plaats van een globale time-out te verhogen.

Beveiligingsnotities

Dataresidentie en PII-mitigaties

De Connect-host verwerkt documenttekst binnen hetzelfde proces. Het rapport laat verwijderde tekst bewust weg en rapporteert alleen aantallen en posities, zodat het rapport de persoonsgegevens die het beschrijft niet opnieuw introduceert. Dataresidentie op implementatieniveau voor invoer en bewerkte uitvoer valt onder de verantwoordelijkheid van de integrator; het is geen eigenschap van het hulpmiddel.

Veilige telemetrie en logscrubbing

Log het pad van het bronbestand of de inhoud van het rapport niet op een logniveau dat extern wordt verzonden. Log alleen de naam van het hulpmiddel, de request-id en de pass/fail-uitkomst.

Dreigingsmodel

Een redactie die tekst visueel bedekt maar niet verwijdert, houdt de gegevens extraheerbaar. Deze hulpmiddelen herschrijven de betrokken contentstream in plaats van er een rechthoek overheen te leggen; het herstellen van verwijderde bytes uit het bewerkte document is niet mogelijk (ISO 32000-2 §14.11). Er blijft een restrisico bestaan wanneer de detector inhoud mist: een patroon dat buiten zijn regels valt, of tekst die alleen als gerasterde afbeelding aanwezig is. De workflow beperkt dat risico met de verplichte rapportbeoordeling, niet met een claim van volledigheid.

Gedrag in FIPS-modus

Redactie voert geen cryptografische bewerking uit en wordt niet beïnvloed door een beleid voor Federal Information Processing Standards (FIPS)-modus op de host.

Conformiteit

Bewering	Clausule	reference_id
Het verwijderen van inhoud herschrijft de betrokken contentstream	ISO 32000-2 §14.11
Redactie markeert en verwijdert vervolgens; de verwijdering is een inhoudsbewerking	ISO 32000-2 §14.11
Controle op het punt waar de geautomatiseerde bewerking risico introduceert	IEC 31010:2019

Ondersteuning voor de redactiehulpmiddelen certificeert niet dat een verwerkt document vrij is van persoonsgegevens. Voor die vaststelling is een onafhankelijke beoordeling nodig.

Commerciële context

De redactiehulpmiddelen vallen binnen Enterprise-niveau. Ze registreren zich alleen wanneer nextpdf/premium naast de server is geïnstalleerd. Zie de conversielink in de front-matter.

Connect-specifieke details

Transportbeschikbaarheid (MCP / REST / gRPC)

U roept de hulpmiddelen op dezelfde manier aan via elk transport dat de gedeelde hulpmiddelexecutor gebruikt: MCP tools/call, het REST-hulpmiddelendpoint en de gRPC-service. Het argumentschema is transportonafhankelijk. Dat is het schema dat wordt geretourneerd door tools/list (MCP) of de servicedescriptor (gRPC).

HITL-risiconiveau

Alle drie de hulpmiddelen declareren destructiveHint: true. Wanneer een operator een hulpmiddel via een configuratie-override verhoogt naar het risiconiveau approval_required, wordt de aanroep achter de ConfirmationGate geplaatst. De override mag het risico alleen verhogen, nooit verlagen. Zie /connect/hitl-risk-niveaus/.

JSON-envelop van de bevestigingsgate

Wanneer het hulpmiddel is gegrendeld en zonder geldig token wordt aangeroepen, retourneert de gate een challenge-envelop met deze vorm:

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

De aanroeper roept hetzelfde hulpmiddel opnieuw aan met arguments._confirmation_token ingesteld op het uitgegeven token. Het token bindt de naam van het hulpmiddel, een nonce en een TTL van 300 seconden — niet de argumenten — en is voor eenmalig gebruik.

Zie ook

/connect/tool-catalog/ — hoe het register de hulpmiddelenset per niveau berekent.
/connect/hitl-risk-niveaus/ — het risicomodel met vier niveaus en de gate.
/cookbook/connect/extract-text-content/ — bekijk een voorbeeld van de extraheerbare tekst vóór de redactie.
/cookbook/connect/digital-signature/ — onderteken het bewerkte document voor de chain-of-custody.