Удаление PII из PDF с помощью Connect

Краткий обзор

Этот рецепт помогает удалить обнаруженную персонально идентифицируемую информацию (PII) из текстового слоя документа с помощью инструментов редактирования, предоставляемых NextPDF Connect. Эти инструменты относятся к уровню Enterprise. ToolRegistry создаёт redact_pdf, zone_redact_pdf и deidentify_pdf, проверяя наличие классов конфиденциальности Enterprise (RedactionEngine + PiiDetector) с помощью class_exists(). Каждый инструмент регистрируется на уровне enterprise только тогда, когда эти классы доступны для автозагрузки. При установке только с открытым исходным кодом эти инструменты отсутствуют: вызов завершается ошибкой о неизвестном инструменте, а не молча переходит в деградированный режим. Все три инструмента объявляют 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/, чтобы узнать, как реестр вычисляет набор инструментов для каждого уровня при запуске.

Концептуальный обзор

Три инструмента покрывают три стратегии редактирования. Все они относятся к уровню 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/. Этот рецепт не дублирует количество инструментов, потому что это свойство развёртывания во время выполнения.

Пример кода — быстрый старт

Обнаружение и удаление содержимого через Model Context Protocol (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"
    }
  }
}

Успешный вызов возвращает отчёт. Для каждого удаления запись фиксирует страницу, метку категории, исходное количество символов и ограничивающую рамку, но не удалённый текст.

Пример кода — продакшен

Считайте вызов редактирования деструктивной операцией и изучайте отчёт перед публикацией документа. При работе через сетевой транспорт обрабатывайте сбой транспорта и ошибку на уровне инструмента как отдельные случаи:

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 не регистрируется, поэтому вызов завершается ошибкой о неизвестном инструменте. Это предусмотренная граница, а не деградация.
Перекрывающиеся обнаружения. Когда несколько детекторов совпадают на одной и той же области, инструмент удаляет эту область один раз и устраняет дубликаты в отчёте.

Производительность

Бюджет производительности во front-matter — это документационный предел, а не гарантия уровня обслуживания. Большие документы обрабатываются постранично. Вместо повышения глобального тайм-аута планируйте повторный вызов для подмножества диапазона страниц.

Примечания по безопасности

Резидентность данных и меры по снижению рисков для PII

Хост Connect обрабатывает текст документа внутри процесса. Отчёт намеренно опускает удалённый текст и сообщает только количество и позиции, поэтому не возвращает персональные данные, которые описывает. Резидентность данных на уровне развёртывания для входных данных и отредактированного результата — ответственность интегратора, а не свойство инструмента.

Безопасная телеметрия и очистка журналов

Не записывайте путь к исходному документу или тело отчёта на уровне журналирования, который передаётся вовне. В журнал пишите только имя инструмента, идентификатор запроса и результат pass/fail.

Модель угроз

Редактирование, которое визуально закрывает текст, но не удаляет его, оставляет данные извлекаемыми. Эти инструменты перезаписывают затронутый поток содержимого вместо наложения прямоугольника; восстановить удалённые байты из отредактированного документа невозможно (ISO 32000-2 §14.11). Остаточный риск сохраняется, когда детектор пропускает содержимое: шаблон вне его правил или текст присутствует только как растеризованное изображение. Этот процесс снижает такой риск за счёт обязательной проверки отчёта, а не за счёт утверждения о полноте.

Поведение в режиме FIPS

Редактирование не выполняет криптографических операций, и на него не влияет политика режима Federal Information Processing Standards (FIPS) на хосте.

Соответствие

Утверждение	Раздел	reference_id (идентификатор ссылки)
Удаление содержимого перезаписывает затронутый поток содержимого	ISO 32000-2 §14.11
Редактирование сначала помечает, затем удаляет; удаление является изменением содержимого	ISO 32000-2 §14.11
Контроль размещён там, где автоматическое редактирование вносит риск	IEC 31010:2019

Поддержка инструментов редактирования не подтверждает, что обработанный документ свободен от персональных данных. Такое заключение даёт независимая проверка.

Коммерческий контекст

Инструменты редактирования относятся к уровню Enterprise. Они регистрируются только тогда, когда вместе с сервером установлен nextpdf/premium. См. ссылку для перехода во front-matter.

Особенности Connect

Доступность транспортов (MCP / REST / gRPC)

Вы вызываете инструменты одинаково через любой транспорт, который использует общий исполнитель инструментов: MCP tools/call, конечную точку инструментов REST и службу gRPC. Схема аргументов не зависит от транспорта. Это та же схема, которую возвращает tools/list (MCP) или дескриптор службы (gRPC).

Уровень риска HITL

Все три инструмента объявляют destructiveHint: true. Когда оператор повышает инструмент до уровня риска approval_required через переопределение конфигурации, вызов проходит через ConfirmationGate. Переопределение может только повышать риск и никогда не понижает его. См. /connect/hitl-risk-tiers/.

JSON-конверт шлюза подтверждения

Когда инструмент защищён шлюзом и вызывается без действительного токена, шлюз возвращает конверт запроса вызова такого вида:

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

Вызывающая сторона повторно вызывает тот же инструмент, установив arguments._confirmation_token в выданный токен. Токен связывает имя инструмента, nonce и 300-секундный TTL — но не аргументы — и используется один раз.

См. также

/connect/tool-catalog/ — как реестр вычисляет набор инструментов для каждого уровня.
/connect/hitl-risk-tiers/ — четырёхуровневая модель риска и шлюз.
/cookbook/connect/extract-text-content/ — предварительный просмотр извлекаемого текста перед редактированием.
/cookbook/connect/digital-signature/ — подпишите отредактированный документ, чтобы обеспечить цепочку ответственности.