Usuwanie danych PII z pliku PDF przez Connect

W skrócie

Ten przepis pokazuje, jak usuwać wykryte dane osobowe (PII) z warstwy tekstowej dokumentu za pomocą narzędzi do usuwania danych udostępnianych przez NextPDF Connect. Narzędzia te należą do poziomu Enterprise. ToolRegistry tworzy redact_pdf, zone_redact_pdf oraz deidentify_pdf, sprawdzając obecność klas ochrony prywatności z poziomu Enterprise (RedactionEngine + PiiDetector) za pomocą class_exists(). Rejestruje każde narzędzie na poziomie enterprise tylko wtedy, gdy te klasy są dostępne przez autoloader. W instalacji obejmującej wyłącznie wersję open source narzędzia te są niedostępne: wywołanie kończy się błędem nieznanego narzędzia, zamiast po cichu obniżać funkcjonalność. Wszystkie trzy narzędzia deklarują destructiveHint: true. Edycja przepisuje zawartość strony i nie jest odwracalna na podstawie edytowanego dokumentu.

Ta strona opisuje zachowanie narzędzi w interfejsie Connect. Proces usuwania danych nie poświadcza, że po wywołaniu dokument jest wolny od danych osobowych. Wykrywanie działa wyłącznie na możliwej do wyodrębnienia warstwie tekstowej, a za weryfikację wyniku nadal odpowiada wdrożenie.

Instalacja

composer require nextpdf/server

Narzędzia do usuwania danych rejestrują się tylko wtedy, gdy zainstalujesz moduł ochrony prywatności z poziomu Enterprise obok serwera. Jest on dostarczany w nextpdf/premium. Zanim oprzesz na nim proces, potwierdź, że narzędzie jest obecne w działającym wdrożeniu:

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

Jeśli wynik tools/list nie zawiera redact_pdf, to klasy ochrony prywatności z poziomu Enterprise nie zostały rozpoznane w tej instalacji. Zobacz /connect/tool-catalog/, aby dowiedzieć się, jak rejestr oblicza zestaw narzędzi dla danego poziomu podczas uruchamiania.

Przegląd koncepcyjny

Trzy narzędzia obejmują trzy strategie usuwania danych. Wszystkie należą do poziomu Enterprise i wszystkie sygnalizują destrukcyjny charakter działania:

redact_pdf — wykrywa i usuwa dane osobowe z zawartości tekstowej dokumentu za pomocą wbudowanego detektora, a następnie zwraca edytowaną zawartość oraz ustrukturyzowany raport.
zone_redact_pdf — usuwa dane z zawartości tekstowej w strefach wyznaczonych na podstawie współrzędnych. Użyj go, gdy znasz obszar według położenia, a nie według wzorca.
deidentify_pdf — stosuje systematyczną strategię deidentyfikacji (usunięcie lub ukrycie) do wykrytych encji.

Usunięcie zawartości ze strumienia treści strony powoduje destrukcyjną edycję tego strumienia: objęte nią bajty są przepisywane i nie da się ich odzyskać na podstawie edytowanego dokumentu (ISO 32000-2 §14.11). Zgodnie z założeniem raport rejestruje liczbę znaków i położenie każdego usunięcia, lecz nigdy samego usuniętego tekstu.

Powierzchnia API

Pakiet Enterprise, który definiuje każde narzędzie, dostarcza także jego dokładny schemat żądania i odpowiedzi. Ta strona opisuje kontrakt wywołania Connect, a nie stałą listę parametrów. Nazwy narzędzi zweryfikowane w działającym rejestrze to redact_pdf, zone_redact_pdf oraz deidentify_pdf, wszystkie w kategorii document z destructiveHint: true. Wiążącym katalogiem jest /connect/tool-catalog/. Ten przepis nie podaje ponownie liczby narzędzi, ponieważ ta wartość jest właściwością wdrożenia ustalaną w czasie wykonywania.

Przykład kodu — Szybki start

Wykryj i usuń zawartość za pośrednictwem Model Context Protocol (MCP) (tools/call). Poniższe argumenty pokazują kształt wywołania. Wiążącym schematem argumentów jest ten, który tools/list zwraca w Twoim wdrożeniu:

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

Pomyślne wywołanie zwraca raport. Każdy wpis dotyczący usunięcia rejestruje stronę, etykietę kategorii, pierwotną liczbę znaków oraz prostokąt ograniczający, lecz nie usunięty tekst.

Przykład kodu — Produkcja

Traktuj wywołanie usuwania danych jako operację destrukcyjną i sprawdź raport, zanim udostępnisz dokument. W przypadku transportu sieciowego traktuj awarię transportu i błąd na poziomie narzędzia jako odrębne przypadki:

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

Udostępnij edytowany dokument dopiero po sprawdzeniu raportu przez człowieka lub mechanizm kontrolny w dalszej części procesu. Wstrzymanie udostępnienia do czasu tego przeglądu umieszcza kontrolę w miejscu, w którym automatyczna edycja wprowadza ryzyko danych szczątkowych (IEC 31010:2019).

Przypadki brzegowe i pułapki

Zeskanowany plik PDF bez warstwy tekstowej. Wykrywanie działa na możliwej do wyodrębnienia warstwie tekstowej. Strona zawierająca wyłącznie obraz skutkuje wynikiem zero usunięć i nie jest błędem. Jeśli zawartość jest zrasteryzowana, przed usuwaniem danych wykonaj optyczne rozpoznawanie znaków (OCR) dla dokumentu.
Zaszyfrowane źródło. Podaj hasło dokumentu zgodnie ze schematem argumentów narzędzia. Bez niego wywołanie kończy się błędem, zamiast przetwarzać tylko część dokumentu.
Brak narzędzia. W instalacji obejmującej wyłącznie wersję open source klasy ochrony prywatności z poziomu Enterprise nie są rozpoznawane, a redact_pdf nie jest zarejestrowany, więc wywołanie kończy się błędem nieznanego narzędzia. To zamierzona granica, a nie obniżenie funkcjonalności.
Nakładające się wykrycia. Gdy więcej niż jeden detektor dopasuje ten sam obszar, narzędzie usuwa ten obszar jednokrotnie i deduplikuje raport.

Wydajność

Budżet wydajności w nagłówku front-matter jest limitem dokumentacyjnym, a nie gwarancją poziomu usług. Duże dokumenty są przetwarzane strona po stronie. Zaplanuj ponowne wywołanie dla podzbioru stron, zamiast podnosić globalny limit czasu.

Uwagi dotyczące bezpieczeństwa

Rezydencja danych i środki ograniczające ryzyko PII

Host Connect przetwarza tekst dokumentu w obrębie procesu. Raport celowo pomija usunięty tekst i podaje wyłącznie liczby oraz położenia, dzięki czemu nie wprowadza ponownie opisywanych danych osobowych. Za rezydencję danych wejściowych i edytowanego wyniku na poziomie wdrożenia odpowiada integrator; nie jest to właściwość narzędzia.

Bezpieczna telemetria i czyszczenie logów

Nie zapisuj ścieżki dokumentu źródłowego ani treści raportu w logach na poziomie wysyłanym na zewnątrz. W logach zapisuj wyłącznie nazwę narzędzia, identyfikator żądania oraz wynik pass/fail.

Model zagrożeń

Operacja, która jedynie wizualnie zakrywa tekst, lecz go nie usuwa, pozostawia dane możliwe do wyodrębnienia. Te narzędzia przepisują objęty strumień treści zamiast nakładać prostokąt; odzyskanie usuniętych bajtów na podstawie edytowanego dokumentu nie jest możliwe (ISO 32000-2 §14.11). Ryzyko szczątkowe pozostaje, gdy detektor pomija zawartość: wzorzec spoza reguł detektora lub tekst obecny wyłącznie jako zrasteryzowany obraz. Proces ogranicza to ryzyko przez obowiązkowy przegląd raportu, a nie przez deklarację kompletności.

Zachowanie w trybie FIPS

Usuwanie danych nie wykonuje żadnej operacji kryptograficznej i nie zależy od polityki trybu Federal Information Processing Standards (FIPS) na hoście.

Zgodność

Twierdzenie	Klauzula	reference_id
Usunięcie zawartości przepisuje dotknięty strumień treści	ISO 32000-2 §14.11
Usuwanie danych najpierw oznacza, a następnie usuwa; samo usunięcie jest edycją zawartości	ISO 32000-2 §14.11
Kontrola umieszczona w punkcie, w którym automatyczna edycja wprowadza ryzyko	IEC 31010:2019

Sama obsługa narzędzi do usuwania danych nie poświadcza, że przetworzony dokument jest wolny od danych osobowych. Tego rozstrzygnięcia dokonuje niezależny przegląd.

Kontekst komercyjny

Narzędzia do usuwania danych należą do poziomu Enterprise. Rejestrują się tylko wtedy, gdy nextpdf/premium jest zainstalowany obok serwera. Link konwersji znajduje się w nagłówku front-matter.

Specyfika Connect

Dostępność transportów (MCP / REST / gRPC)

Narzędzia wywołujesz w ten sam sposób za pośrednictwem każdego transportu obsługiwanego przez wspólnego wykonawcę narzędzi: MCP tools/call, punkt końcowy narzędzi REST oraz usługa gRPC. Schemat argumentów jest niezależny od transportu. To ten sam schemat, który zwraca tools/list (MCP) lub deskryptor usługi (gRPC).

Poziom ryzyka HITL

Wszystkie trzy narzędzia deklarują destructiveHint: true. Gdy operator podniesie narzędzie do poziomu ryzyka approval_required przez nadpisanie konfiguracji, wywołanie jest blokowane przez ConfirmationGate. Nadpisanie może jedynie podnieść ryzyko, nigdy go nie obniżyć. Zobacz /connect/hitl-risk-tiers/.

Koperta JSON bramki potwierdzenia

Gdy narzędzie jest objęte bramką i zostanie wywołane bez prawidłowego tokenu, bramka zwraca kopertę z wyzwaniem o takiej postaci:

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

Wywołujący ponownie uruchamia to samo narzędzie z arguments._confirmation_token ustawionym na wydany token. Token wiąże nazwę narzędzia, jednorazową wartość (nonce) oraz 300-sekundowy TTL — lecz nie argumenty — i jest jednorazowy.

Zobacz także

/connect/tool-catalog/ — jak rejestr oblicza zestaw narzędzi dla danego poziomu.
/connect/hitl-risk-tiers/ — czteropoziomowy model ryzyka i bramka.
/cookbook/connect/extract-text-content/ — sprawdź możliwy do wyodrębnienia tekst przed usuwaniem danych.
/cookbook/connect/digital-signature/ — podpisz edytowany dokument, aby zachować łańcuch nadzoru.