Menyunting PII dari PDF melalui Connect

Sekilas pandang

Resep ini menghapus informasi pengenal pribadi (PII) yang terdeteksi dari lapisan teks pada dokumen menggunakan alat penyuntingan yang disediakan oleh NextPDF Connect. Semua alat ini berada pada tingkat Enterprise. ToolRegistry membangun redact_pdf, zone_redact_pdf, dan deidentify_pdf dengan memeriksa keberadaan kelas privasi Enterprise (RedactionEngine + PiiDetector) menggunakan class_exists(). Setiap alat didaftarkan pada tingkat enterprise hanya jika kelas-kelas tersebut dapat di-autoload. Pada instalasi yang hanya open-source, alat-alat ini tidak tersedia: panggilan gagal dengan galat unknown-tool, bukan melakukan penurunan kemampuan secara diam-diam. Ketiga alat tersebut mendeklarasikan destructiveHint: true. Penyuntingan menulis ulang konten halaman, dan konten yang dihapus tidak dapat dipulihkan dari dokumen yang telah disunting.

Halaman ini mendokumentasikan perilaku alat pada antarmuka Connect. Alur kerja penyuntingan tidak menjamin bahwa dokumen bebas dari data pribadi setelah panggilan. Deteksi hanya berjalan pada lapisan teks yang dapat diekstraksi, dan deployment tetap bertanggung jawab memverifikasi hasilnya.

Pemasangan

composer require nextpdf/server

Alat penyuntingan terdaftar hanya ketika Anda memasang modul privasi Enterprise bersama server. Modul ini disertakan dalam nextpdf/premium. Pastikan alat tersedia pada deployment yang sedang berjalan sebelum Anda mengandalkannya:

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

Jika redact_pdf tidak ada dalam hasil tools/list, kelas privasi Enterprise tidak berhasil di-resolve pada instalasi ini. Lihat /connect/tool-catalog/ untuk mempelajari cara registry menghitung kumpulan alat per tingkat saat boot.

Tinjauan konseptual

Ketiga alat mencakup tiga strategi penyuntingan. Semuanya berada pada tingkat Enterprise dan membawa petunjuk destruktif:

redact_pdf — mendeteksi dan menghapus data pribadi dari konten teks biasa dokumen dengan detektor bawaan, lalu mengembalikan konten yang telah disunting beserta laporan terstruktur.
zone_redact_pdf — menerapkan penyuntingan zona berbasis koordinat pada konten teks biasa. Gunakan ini ketika Anda mengenali area berdasarkan posisi, bukan berdasarkan pola.
deidentify_pdf — menerapkan strategi de-identifikasi sistematis (menyunting atau menyembunyikan) di seluruh entitas yang terdeteksi.

Menghapus konten dari stream konten halaman berarti menyunting stream tersebut secara destruktif: byte yang terpengaruh ditulis ulang dan tidak dapat dipulihkan dari dokumen yang telah disunting (ISO 32000-2 §14.11). Secara desain, laporan mencatat jumlah karakter dan posisi setiap penghapusan, bukan teks yang dihapus itu sendiri.

Permukaan API

Paket Enterprise yang mendefinisikan setiap alat juga menyertakan skema permintaan dan respons yang tepat. Halaman ini mendokumentasikan kontrak pemanggilan Connect, bukan daftar parameter tetap. Nama alat yang diverifikasi terhadap registry aktif adalah redact_pdf, zone_redact_pdf, dan deidentify_pdf, semuanya dalam kategori document dengan destructiveHint: true. Katalog resminya adalah /connect/tool-catalog/. Resep ini tidak mengulang jumlah alat, karena nilai tersebut merupakan properti runtime dari deployment.

Contoh kode — Mulai cepat

Deteksi dan hapus konten melalui Model Context Protocol (MCP) (tools/call). Argumen di bawah ini menunjukkan bentuk panggilannya. Skema argumen otoritatif adalah skema yang dikembalikan oleh tools/list pada deployment Anda:

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

Panggilan yang berhasil mengembalikan laporan. Untuk setiap penghapusan, entri mencatat halaman, label kategori, jumlah karakter asli, dan kotak pembatas, bukan teks yang dihapus.

Contoh kode — Produksi

Perlakukan panggilan penyuntingan sebagai operasi destruktif dan periksa laporan sebelum Anda merilis dokumen. Pada transport berbasis jaringan, tangani kegagalan transport dan galat tingkat alat sebagai kasus terpisah:

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

Rilis dokumen yang telah disunting hanya setelah manusia atau kontrol hilir meninjau laporan. Menahan rilis sampai tinjauan tersebut selesai menempatkan kontrol pada titik tempat penyuntingan otomatis menimbulkan risiko data residual (IEC 31010:2019).

Kasus tepi & jebakan

PDF hasil pindai tanpa lapisan teks. Deteksi berjalan pada lapisan teks yang dapat diekstraksi. Halaman yang hanya berisi gambar menghasilkan nol penghapusan; itu bukan galat. Jika kontennya berbentuk raster, jalankan optical character recognition (OCR) pada dokumen sebelum penyuntingan.
Sumber terenkripsi. Berikan kata sandi dokumen melalui skema argumen alat. Tanpa kata sandi itu, panggilan gagal, bukan sekadar memproses sebagian dokumen.
Alat tidak tersedia. Pada instalasi yang hanya open-source, kelas privasi Enterprise tidak ter-resolve dan redact_pdf tidak terdaftar, sehingga panggilan gagal dengan galat unknown-tool. Ini adalah batasan yang disengaja, bukan penurunan kualitas.
Deteksi yang tumpang tindih. Ketika lebih dari satu detektor cocok dengan area yang sama, alat menghapus area tersebut sekali dan menghapus duplikasi dari laporan.

Performa

Anggaran performa di front-matter adalah batas dokumentasi, bukan jaminan tingkat layanan. Dokumen besar diproses halaman demi halaman. Rencanakan untuk menjalankan ulang panggilan pada subset rentang halaman, bukan menaikkan batas waktu global.

Catatan keamanan

Residensi data & mitigasi PII

Host Connect memproses teks dokumen secara in-process. Laporan dengan sengaja menghilangkan teks yang dihapus dan hanya melaporkan jumlah serta posisi, sehingga laporan tidak memperkenalkan kembali data pribadi yang dijelaskannya. Residensi data pada tingkat deployment untuk masukan dan keluaran yang telah disunting merupakan tanggung jawab integrator, bukan properti alat.

Telemetri aman & pembersihan log

Jangan mencatat jalur dokumen sumber atau isi laporan pada tingkat log yang dikirim ke luar. Catat hanya nama alat, request id, dan hasil pass/fail.

Model ancaman

Penyuntingan yang secara visual menutupi teks tetapi tidak menghapusnya membuat data tetap dapat diekstraksi. Alat-alat ini menulis ulang stream konten yang terpengaruh alih-alih menumpangkan persegi panjang; memulihkan byte yang dihapus dari dokumen yang telah disunting tidak mungkin dilakukan (ISO 32000-2 §14.11). Risiko residual tetap ada ketika detektor melewatkan konten: pola di luar aturan detektor, atau teks yang hanya hadir sebagai gambar raster. Alur kerja memitigasi risiko tersebut dengan tinjauan laporan yang wajib, bukan dengan klaim kelengkapan.

Perilaku mode FIPS

Penyuntingan tidak melakukan operasi kriptografis apa pun dan tidak terpengaruh oleh kebijakan mode Federal Information Processing Standards (FIPS) pada host.

Kesesuaian

Klaim	Klausul	reference_id
Menghapus konten menulis ulang stream konten yang terpengaruh	ISO 32000-2 §14.11
Penyuntingan menandai lalu menghapus; penghapusan adalah penyuntingan konten	ISO 32000-2 §14.11
Kontrol ditempatkan pada titik tempat penyuntingan otomatis menimbulkan risiko	IEC 31010:2019

Dukungan untuk alat penyuntingan tidak menjamin bahwa dokumen yang telah diproses bebas dari data pribadi. Penentuan tersebut dibuat melalui tinjauan independen.

Konteks komersial

Alat penyuntingan berada pada tingkat Enterprise. Alat-alat ini hanya terdaftar ketika nextpdf/premium dipasang bersama server. Lihat tautan konversi di front-matter.

Spesifik Connect

Ketersediaan transport (MCP / REST / gRPC)

Anda memanggil alat dengan cara yang sama melalui setiap transport yang menggunakan eksekutor alat bersama: MCP tools/call, endpoint alat REST, dan layanan gRPC. Skema argumen tidak bergantung pada transport. Skema tersebut adalah skema yang dikembalikan oleh tools/list (MCP) atau deskriptor layanan (gRPC).

Tingkat risiko HITL

Ketiga alat tersebut mendeklarasikan destructiveHint: true. Ketika operator menaikkan alat ke tingkat risiko approval_required melalui penggantian konfigurasi, panggilan tersebut dibatasi di balik ConfirmationGate. Penggantian itu hanya boleh menaikkan risiko, tidak pernah menurunkannya. Lihat /connect/hitl-risk-tiers/.

Envelope JSON gerbang konfirmasi

Ketika alat berada di balik gerbang dan dipanggil tanpa token yang valid, gerbang mengembalikan envelope tantangan dalam bentuk berikut:

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

Pemanggil memanggil ulang alat yang sama dengan arguments._confirmation_token disetel ke token yang diterbitkan. Token mengikat nama alat, nonce, dan TTL 300 detik — bukan argumennya — dan bersifat sekali pakai.

Lihat juga

/connect/tool-catalog/ — cara registry menghitung kumpulan alat per tingkat.
/connect/hitl-risk-tiers/ — model risiko empat tingkat dan gerbangnya.
/cookbook/connect/extract-text-content/ — pratinjau teks yang dapat diekstraksi sebelum menyunting.
/cookbook/connect/digital-signature/ — tanda tangani dokumen yang telah disunting untuk rantai pengawasan.