Remova PII de um PDF via Connect

Visão geral

Esta receita remove informações de identificação pessoal (PII) detectadas da camada de texto de um documento usando as ferramentas de redaction expostas pelo NextPDF Connect. Essas ferramentas são de nível Enterprise. O ToolRegistry monta redact_pdf, zone_redact_pdf e deidentify_pdf ao verificar a presença das classes de privacidade do Enterprise (RedactionEngine + PiiDetector) com class_exists(). Ele registra cada ferramenta no nível enterprise somente quando essas classes podem ser carregadas via autoload. Em uma instalação somente open source, as ferramentas ficam ausentes: a chamada falha com um erro de ferramenta desconhecida, em vez de degradar silenciosamente. As três ferramentas declaram destructiveHint: true. A edição reescreve o conteúdo da página e não é reversível a partir do documento editado.

Esta página documenta o comportamento das ferramentas na superfície do Connect. Um fluxo de trabalho de redaction não certifica que um documento esteja livre de dados pessoais após a chamada. A detecção é executada apenas na camada de texto extraível, e a implantação continua sendo responsável por verificar o resultado.

Instalação

composer require nextpdf/server

As ferramentas de redaction só são registradas quando você instala o módulo de privacidade do Enterprise junto com o servidor. Esse módulo é fornecido em nextpdf/premium. Confirme que a ferramenta está presente na implantação em execução antes de depender dela:

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

Se redact_pdf estiver ausente do resultado de tools/list, as classes de privacidade do Enterprise não foram resolvidas nesta instalação. Consulte /connect/tool-catalog/ para saber como o registro calcula, na inicialização, o conjunto de ferramentas por nível.

Visão geral conceitual

Três ferramentas cobrem três estratégias de redaction. Todas são de nível Enterprise e todas carregam o hint destrutivo:

redact_pdf — detecta e remove dados pessoais do conteúdo em texto puro do documento com um detector integrado e, em seguida, retorna o conteúdo editado e um relatório estruturado.
zone_redact_pdf — aplica redactions por zona baseadas em coordenadas ao conteúdo em texto puro. Use-a quando você conhece a região pela posição, não por um padrão.
deidentify_pdf — aplica uma estratégia sistemática de desidentificação (redact ou suppress) em todas as entidades detectadas.

Remover conteúdo de um content stream de página edita esse stream de modo destrutivo: os bytes afetados são reescritos e não são recuperáveis a partir do documento editado (ISO 32000-2 §14.11). Por design, o relatório registra a contagem de caracteres e a posição de cada remoção, nunca o texto removido em si.

Superfície da API

O pacote Enterprise que define cada ferramenta também fornece o esquema exato de requisição e resposta correspondente. Esta página documenta o contrato de invocação do Connect, não uma lista fixa de parâmetros. Os nomes das ferramentas conferidos no registro em execução são redact_pdf, zone_redact_pdf e deidentify_pdf, todos na categoria document com destructiveHint: true. O catálogo de referência é /connect/tool-catalog/. Esta receita não repete uma contagem de ferramentas, porque esse valor é uma propriedade de tempo de execução da implantação.

Exemplo de código — Início rápido

Detecte e remova conteúdo pelo Model Context Protocol (MCP) (tools/call). Os argumentos abaixo mostram o formato da chamada. O esquema de argumentos oficial é o que tools/list retorna na sua implantação:

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

Uma chamada bem-sucedida retorna um relatório. Para cada remoção, uma entrada registra a página, um rótulo de categoria, a contagem original de caracteres e uma bounding box, não o texto removido.

Exemplo de código — Produção

Trate a chamada de redaction como uma operação destrutiva e inspecione o relatório antes de liberar o documento. Em um transporte de rede, trate uma falha de transporte e um erro no nível da ferramenta como casos distintos:

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

Libere o documento editado somente depois da revisão do relatório por um humano ou por um controle posterior. Condicionar a liberação a essa revisão coloca o controle no ponto em que a edição automatizada introduz o risco de dados residuais (IEC 31010:2019).

Casos extremos e pegadinhas

PDF digitalizado sem camada de texto. A detecção é executada na camada de texto extraível. Uma página composta apenas por imagem resulta em zero remoções e não é um erro. Se o conteúdo estiver rasterizado, execute o reconhecimento óptico de caracteres (OCR) no documento antes da redaction.
Origem criptografada. Forneça a senha do documento por meio do esquema de argumentos da ferramenta. Sem ela, a chamada falha em vez de processar apenas parte do documento.
Ferramenta ausente. Em uma instalação somente open source, as classes de privacidade do Enterprise não são resolvidas e redact_pdf não é registrada; portanto, a chamada falha com um erro de ferramenta desconhecida. Esse é o limite pretendido, não uma degradação.
Detecções sobrepostas. Quando mais de um detector corresponde à mesma região, a ferramenta remove a região uma vez e desduplica o relatório.

Desempenho

O orçamento de desempenho no front-matter é um limite de documentação, não uma garantia de nível de serviço. Documentos grandes são processados página por página. Planeje reexecutar a chamada em um subconjunto do intervalo de páginas, em vez de aumentar um timeout global.

Notas de segurança

Residência de dados e mitigações de PII

O host do Connect processa o texto do documento no próprio processo. O relatório omite deliberadamente o texto removido e informa apenas contagens e posições, de modo que o relatório não reintroduza os dados pessoais que descreve. A residência de dados no nível da implantação, para a entrada e a saída editada, é responsabilidade do integrador, não uma propriedade da ferramenta.

Telemetria segura e limpeza de logs

Não registre o caminho do documento de origem nem o corpo do relatório em um nível de log enviado externamente. Registre apenas o nome da ferramenta, o id da requisição e o resultado pass/fail.

Modelo de ameaças

Uma redaction que cobre o texto visualmente, mas não o remove, deixa os dados extraíveis. Essas ferramentas reescrevem o content stream afetado em vez de sobrepor um retângulo; recuperar os bytes removidos a partir do documento editado não é possível (ISO 32000-2 §14.11). Permanece um risco residual quando o detector deixa passar conteúdo: um padrão fora das regras dele ou texto presente apenas como imagem rasterizada. O fluxo de trabalho mitiga esse risco com a revisão obrigatória do relatório, não com uma alegação de completude.

Comportamento no modo FIPS

A redaction não realiza nenhuma operação criptográfica e não é afetada por uma política de modo Federal Information Processing Standards (FIPS) no host.

Conformidade

Alegação	Cláusula	reference_id
Remover conteúdo reescreve o content stream afetado	ISO 32000-2 §14.11
A redaction marca e então remove; a remoção é uma edição de conteúdo	ISO 32000-2 §14.11
Controle posicionado no ponto em que a edição automatizada introduz risco	IEC 31010:2019

O suporte às ferramentas de redaction não certifica que um documento processado esteja livre de dados pessoais. Uma revisão independente faz essa determinação.

Contexto comercial

As ferramentas de redaction são de nível Enterprise. Elas só são registradas quando nextpdf/premium está instalado junto com o servidor. Consulte o link de conversão no front-matter.

Especificidades do Connect

Disponibilidade por transporte (MCP / REST / gRPC)

Você invoca as ferramentas da mesma maneira em todos os transportes que acionam o executor de ferramentas compartilhado: MCP tools/call, o endpoint de ferramenta REST e o serviço gRPC. O esquema de argumentos é independente do transporte. Ele é o que tools/list (MCP) retorna ou o descritor de serviço (gRPC) informa.

Nível de risco HITL

As três ferramentas declaram destructiveHint: true. Quando um operador eleva uma ferramenta ao nível de risco approval_required por meio de uma substituição de configuração, a chamada passa a ser controlada pelo ConfirmationGate. A substituição só pode elevar o risco, nunca reduzi-lo. Consulte /connect/hitl-risk-tiers/.

Envelope JSON do gate de confirmação

Quando a ferramenta está controlada por gate e é invocada sem um token válido, o gate retorna um envelope de desafio com este formato:

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

O chamador reinvoca a mesma ferramenta com arguments._confirmation_token definido como o token emitido. O token vincula o nome da ferramenta, um nonce e um TTL de 300 segundos — não os argumentos — e é de uso único.

Veja também

/connect/tool-catalog/ — como o registro calcula o conjunto de ferramentas por nível.
/connect/hitl-risk-tiers/ — o modelo de risco de quatro níveis e o gate.
/cookbook/connect/extract-text-content/ — visualize o texto extraível antes de fazer a redaction.
/cookbook/connect/digital-signature/ — assine o documento editado para a cadeia de custódia.