Connect 経由で PDF から PII を墨消しする

概要

このレシピでは、NextPDF Connect が公開する墨消しツールを使って、ドキュメントのテキストレイヤーから検出された個人データを削除します。これらのツールは Enterprise ティア です。ToolRegistry は、class_exists() で Enterprise のプライバシークラス（RedactionEngine + PiiDetector）を探索して redact_pdf、zone_redact_pdf、deidentify_pdf を構築し、それらのクラスがオートロード可能な場合にのみ、各ツールを enterprise ティアに登録します。オープンソースのみのインストールでは、これらのツールは存在しません。呼び出しは静かにフォールバックせず、未知のツールエラーで失敗します。3 つのツールはいずれも destructiveHint: true を宣言します。この編集ではページコンテンツを書き換えるため、編集後のドキュメントから元に戻すことはできません。

このページでは、Connect サーフェス経由でのツールの動作を説明します。墨消しワークフローは、呼び出し後の当該ドキュメントに個人データが含まれないことを証明するものではありません。検出対象は抽出可能なテキストレイヤーのみであり、結果の検証は引き続きデプロイメント側の責任です。

インストール

composer require nextpdf/server

墨消しツールは、Enterprise のプライバシーモジュールがサーバーと併せてインストールされている場合にのみ登録されます。これは nextpdf/premium に同梱されています。この機能に依存する前に、実行中のデプロイメントでツールが存在することを確認してください。

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

redact_pdf が tools/list の結果に含まれていない場合、このインストールでは Enterprise のプライバシークラスが解決されていません。レジストリが起動時にティアごとのツールセットをどのように算出するかについては、/connect/tool-catalog/ を参照してください。

概念の概要

3 つのツールが 3 つの墨消し戦略をカバーします。いずれも Enterprise ティアであり、破壊的ヒントを備えています。

redact_pdf — 組み込みの検出器を使って、ドキュメントのプレーンテキストコンテンツ内にある個人データを検出して削除し、編集後のコンテンツと構造化レポートを返します。
zone_redact_pdf — プレーンテキストコンテンツに座標ベースのゾーン墨消しを適用します。削除対象の領域を、パターンではなく位置で把握している場合に使用します。
deidentify_pdf — 検出されたエンティティ全体に対して、体系的な非識別化戦略（墨消しまたは抑制）を適用します。

ページコンテンツストリームからコンテンツを削除することは、そのストリームに対する破壊的な編集です。影響を受けるバイトは書き換えられ、編集後のドキュメントから復元できません（ISO 32000-2 §14.11）。設計上、レポートは各削除の文字数と位置を記録しますが、削除されたテキストそのものは決して記録しません。

API サーフェス

各ツールの正確なリクエストスキーマとレスポンススキーマは、それを定義する Enterprise パッケージに同梱されています。このページが記載するのは Connect の呼び出しコントラクトであり、固定のパラメーターリストではありません。実行中のレジストリに照らして検証されたツール名は redact_pdf、zone_redact_pdf、deidentify_pdf で、いずれも document カテゴリに属し、destructiveHint: true を備えています。正式なカタログは /connect/tool-catalog/ です。このレシピではツール数を再掲しません。それはデプロイメントのランタイムプロパティだからです。

コードサンプル — クイックスタート

MCP（tools/call）経由で検出と削除を行います。以下の引数は呼び出しの形を示すものです。正式な引数スキーマは、お使いのデプロイメントで tools/list が返すものです。

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

呼び出しが成功すると、レポートが返されます。各削除について、エントリにはページ、カテゴリラベル、元の文字数、境界ボックスが記録されます。削除されたテキストは記録されません。

コードサンプル — 本番環境

墨消し呼び出しは破壊的操作として扱い、ドキュメントをリリースする前にレポートを確認してください。ネットワーク経由のトランスポートでは、トランスポート障害とツールレベルのエラーは 2 つの別個のケースです。

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

人またはダウンストリームの制御がレポートをレビューした後にのみ、編集後のドキュメントをリリースしてください。そのレビューが完了するまでリリースを保留することで、自動編集が残留データのリスクを生じさせる地点に制御を配置します（IEC 31010:2019）。

エッジケースと注意点

テキストレイヤーのないスキャン済み PDF。 検出は抽出可能なテキストレイヤー上で実行されます。画像のみのページでは削除件数はゼロになり、エラーにはなりません。コンテンツがラスター化されている場合は、墨消しの前にドキュメントを OCR してください。
暗号化されたソース。 ツールの引数スキーマに従ってドキュメントのパスワードを指定してください。パスワードがない場合、呼び出しは部分的に処理されるのではなく失敗します。
ツール不在。 オープンソースのみのインストールでは Enterprise のプライバシークラスが解決されず、redact_pdf は登録されないため、呼び出しは未知のツールエラーで失敗します。これは意図された境界であり、機能低下ではありません。
重複した検出。 複数の検出器が同じ領域に一致した場合、その領域は一度だけ削除され、レポートでは重複が排除されます。

パフォーマンス

フロントマターのパフォーマンスバジェットはドキュメント上の上限であり、サービスレベルの保証ではありません。大きなドキュメントはページごとに処理されます。グローバルなタイムアウトを引き上げるのではなく、ページ範囲のサブセットに対して呼び出しを再実行できる余裕を確保してください。

セキュリティ上の注意

データレジデンシーと PII の緩和策

ドキュメントテキストは Connect ホスト上でインプロセス処理されます。レポートは削除されたテキストを意図的に省略し、件数と位置のみを報告するため、レポート自体が、記述対象である個人データを再導入することはありません。入力および編集後の出力に対するデプロイメントレベルのデータレジデンシーは、ツールのプロパティではなくインテグレーター側の責任です。

安全なテレメトリとログのスクラビング

外部に送出されるログでは、ソースドキュメントのパスやレポート本文を出力しないでください。ログにはツール名、リクエスト ID、pass/fail の結果のみを出力してください。

脅威モデル

テキストを視覚的に覆うだけで削除しない墨消しは、データを抽出可能なまま残します。これらのツールは矩形を重ねるのではなく、影響を受けるコンテンツストリームを書き換えます。編集後のドキュメントから削除されたバイトを復元することはできません（ISO 32000-2 §14.11）。残留リスクは、検出器が一致しなかったコンテンツです。つまり、そのルールの範囲外のパターンや、ラスター画像としてのみ存在するテキストです。ワークフローでは、完全性を主張するのではなく、必須のレポートレビューによってこれを緩和します。

FIPS モードの動作

墨消しは暗号化操作を一切行わないため、ホスト上の FIPS モードポリシーの影響を受けません。

適合性

主張	箇条	reference_id
コンテンツの削除は影響を受けるコンテンツストリームを書き換える	ISO 32000-2 §14.11
墨消しはマークしてから削除する。削除はコンテンツの編集である	ISO 32000-2 §14.11
自動編集がリスクを生じさせる地点に制御を配置する	IEC 31010:2019

墨消しツールのサポートは、処理されたドキュメントが個人データを含まないことを証明するものではありません。その判断は独立したレビューによって行われます。

商用上のコンテキスト

墨消しツールは Enterprise ティアです。これらは nextpdf/premium がサーバーと併せてインストールされている場合にのみ登録されます。フロントマターのコンバージョンリンクを参照してください。

Connect 固有の事項

トランスポートの可用性（MCP / REST / gRPC）

共有ツールエグゼキューターを駆動するすべてのトランスポート、すなわち MCP の tools/call、REST のツールエンドポイント、gRPC サービスでは、ツールの呼び出し方は同一です。引数スキーマはトランスポートに依存しません。これは tools/list（MCP）またはサービスディスクリプター（gRPC）が返すものです。

HITL リスクティア

3 つのツールはいずれも destructiveHint: true を宣言します。設定オーバーライドを通じてツールを approval_required リスクレベルに引き上げたオペレーターは、その呼び出しを ConfirmationGate 配下でゲートします。オーバーライドはリスクを引き上げることしかできず、引き下げることはできません。/connect/hitl-risk-tiers/ を参照してください。

確認ゲートの JSON エンベロープ

ツールがゲートされており、有効なトークンなしで呼び出された場合、ゲートは次の形式のチャレンジエンベロープを返します。

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

呼び出し側は、発行されたトークンを arguments._confirmation_token に設定して、同じツールを再度呼び出します。トークンはツール名、ノンス、300 秒の TTL にバインドされ（引数にはバインドされません）、単一使用です。

Connect 経由で PDF から PII を墨消しする

Connect 経由で PDF から PII を墨消しする

概要

インストール

概念の概要

API サーフェス

コードサンプル — クイックスタート

コードサンプル — 本番環境

エッジケースと注意点

パフォーマンス

セキュリティ上の注意

データレジデンシーと PII の緩和策

安全なテレメトリとログのスクラビング

脅威モデル

FIPS モードの動作

適合性

商用上のコンテキスト

Connect 固有の事項

トランスポートの可用性（MCP / REST / gRPC）

HITL リスクティア

確認ゲートの JSON エンベロープ

関連項目