Eliminar PII de un PDF mediante Connect

De un vistazo

Esta receta elimina los datos personales detectados de la capa de texto de un documento mediante las herramientas de redacción que expone NextPDF Connect. Estas herramientas son de nivel Enterprise. ToolRegistry construye redact_pdf, zone_redact_pdf y deidentify_pdf comprobando las clases de privacidad de Enterprise (RedactionEngine + PiiDetector) con class_exists(), y registra cada una en el nivel enterprise solo si esas clases pueden cargarse automáticamente. En una instalación exclusivamente de código abierto, las herramientas están ausentes: la llamada falla con un error de herramienta desconocida en lugar de degradarse de forma silenciosa. Las tres herramientas declaran destructiveHint: true. La edición reescribe el contenido de la página y no se puede revertir a partir del documento editado.

Esta página documenta el comportamiento de las herramientas en la superficie de Connect. Un flujo de redacción no certifica que un documento concreto quede libre de datos personales tras la llamada. La detección opera únicamente sobre la capa de texto extraíble, y el despliegue sigue siendo responsable de verificar el resultado.

Instalación

composer require nextpdf/server

Las herramientas de redacción se registran únicamente cuando el módulo de privacidad de Enterprise está instalado junto al servidor. El módulo se distribuye en nextpdf/premium. Debe confirmarse que la herramienta esté presente en el despliegue en ejecución antes de depender de ella:

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

Si redact_pdf no aparece en el resultado de tools/list, las clases de privacidad de Enterprise no se resolvieron en esta instalación. Para saber cómo el registro calcula el conjunto de herramientas por nivel en el arranque, consultar /connect/tool-catalog/.

Visión conceptual

Tres herramientas cubren tres estrategias de redacción. Todas son de nivel Enterprise y todas están marcadas como operaciones destructivas:

redact_pdf: detecta y elimina los datos personales del contenido de texto sin formato del documento mediante un detector integrado, y devuelve el contenido editado junto con un informe estructurado.
zone_redact_pdf: aplica redacciones por zonas basadas en coordenadas al contenido de texto sin formato. Debe usarse cuando se conozca la región que se debe eliminar por posición, en lugar de por patrón.
deidentify_pdf: aplica una estrategia sistemática de desidentificación (redactar o suprimir) a las entidades detectadas.

Eliminar contenido de un flujo de contenido de página es una edición destructiva de ese flujo: los bytes afectados se reescriben y no se pueden recuperar a partir del documento editado (ISO 32000-2 §14.11). Por diseño, el informe registra el número de caracteres y la posición de cada eliminación, nunca el texto eliminado en sí.

Superficie de la API

El esquema exacto de solicitud y respuesta de cada herramienta lo proporciona el paquete de Enterprise que la define. Esta página documenta el contrato de invocación de Connect, no una lista fija de parámetros. Los nombres de las herramientas verificados contra el registro en ejecución son redact_pdf, zone_redact_pdf y deidentify_pdf, todas en la categoría document con destructiveHint: true. El catálogo de referencia es /connect/tool-catalog/. Esta receta no fija una cantidad total de herramientas, porque eso es una propiedad en tiempo de ejecución del despliegue.

Ejemplo de código: inicio rápido

Detectar y eliminar mediante MCP (tools/call). Los argumentos siguientes ilustran la forma de la llamada. El esquema de argumentos de referencia es el que devuelve tools/list en el despliegue:

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

Una llamada correcta devuelve un informe. Para cada eliminación, la entrada registra la página, una etiqueta de categoría, el número de caracteres original y un recuadro delimitador, no el texto eliminado.

Ejemplo de código: producción

La llamada de redacción debe tratarse como una operación destructiva, y el informe debe inspeccionarse antes de publicar el documento. En un transporte de red, un fallo de transporte y un error a nivel de herramienta son dos 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

El documento editado solo debe publicarse después de que una persona o un control posterior haya revisado el informe. Mantener la publicación sujeta a esa revisión sitúa el control en el punto donde la edición automatizada introduce el riesgo de datos residuales (IEC 31010:2019).

Casos límite y trampas

PDF escaneado sin capa de texto. La detección se ejecuta sobre la capa de texto extraíble. Una página compuesta solo por una imagen produce cero eliminaciones y no constituye un error. Si el contenido está rasterizado, debe aplicarse OCR al documento antes de la redacción.
Origen cifrado. Debe proporcionarse la contraseña del documento a través del esquema de argumentos de la herramienta. Sin ella, la llamada falla en lugar de procesarse parcialmente.
Herramienta ausente. En una instalación exclusivamente de código abierto, las clases de privacidad de Enterprise no se resuelven y redact_pdf no se registra, por lo que la llamada falla con un error de herramienta desconocida. Este es el límite previsto, no una degradación.
Detecciones superpuestas. Cuando más de un detector coincide con la misma región, la región se elimina una sola vez y el informe la registra sin duplicados.

Rendimiento

El presupuesto de rendimiento del frontmatter es un límite de documentación, no una garantía de nivel de servicio. Los documentos grandes se procesan página por página. Debe preverse volver a ejecutar la llamada sobre un intervalo reducido de páginas en lugar de aumentar un tiempo de espera global.

Notas de seguridad

Residencia de datos y mitigaciones de PII

El texto del documento se procesa dentro del proceso en el host de Connect. El informe omite deliberadamente el texto eliminado e informa únicamente de los recuentos y las posiciones, de modo que el propio informe no reintroduce los datos personales que describe. La residencia de datos del despliegue para la entrada y la salida editada es responsabilidad del integrador, no una propiedad de la herramienta.

Telemetría segura y depuración de registros

No se debe registrar la ruta del documento de origen ni el cuerpo del informe en un nivel de registro que se envíe externamente. Solo se deben registrar el nombre de la herramienta, el identificador de la solicitud y el resultado pass/fail.

Modelo de amenazas

Una redacción que cubre visualmente el texto pero no lo elimina deja los datos extraíbles. Estas herramientas reescriben el flujo de contenido afectado en lugar de superponer un rectángulo; no es posible recuperar los bytes eliminados a partir del documento editado (ISO 32000-2 §14.11). El riesgo residual corresponde al contenido con el que el detector no coincidió: un patrón fuera de sus reglas o texto presente únicamente como una imagen rasterizada. El flujo de trabajo mitiga esto con la revisión obligatoria del informe, no con una afirmación de exhaustividad.

Comportamiento en modo FIPS

La redacción no realiza ninguna operación criptográfica y no se ve afectada por una política de modo FIPS en el host.

Conformidad

Afirmación	Cláusula	reference_id
Eliminar contenido reescribe el flujo de contenido afectado	ISO 32000-2 §14.11
La redacción marca y luego elimina; la eliminación es una edición de contenido	ISO 32000-2 §14.11
Control situado en el punto donde la edición automatizada introduce el riesgo	IEC 31010:2019

La compatibilidad con las herramientas de redacción no certifica que un documento procesado esté libre de datos personales. Eso debe determinarlo una revisión independiente.

Contexto comercial

Las herramientas de redacción son de nivel Enterprise. Se registran únicamente cuando nextpdf/premium está instalado junto al servidor. Consultar el enlace de conversión en el frontmatter.

Particularidades de Connect

Disponibilidad de transportes (MCP / REST / gRPC)

Las herramientas se invocan de la misma forma en cada transporte que utiliza el ejecutor de herramientas compartido: MCP tools/call, el extremo de herramientas REST y el servicio gRPC. El esquema de argumentos es independiente del transporte. Es el que devuelve tools/list (MCP) o el descriptor del servicio (gRPC).

Nivel de riesgo HITL

Las tres herramientas declaran destructiveHint: true. Un operador que eleve una herramienta al nivel de riesgo approval_required mediante una anulación de configuración hace que la llamada pase por la ConfirmationGate. La anulación solo puede elevar el riesgo, nunca reducirlo. Consultar /connect/hitl-risk-tiers/.

Sobre JSON de la puerta de confirmación

Cuando la herramienta está condicionada y se invoca sin un token válido, la puerta devuelve un sobre de desafío con esta forma:

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

El llamante vuelve a invocar la misma herramienta con arguments._confirmation_token establecido en el token emitido. El token vincula el nombre de la herramienta, un nonce y un TTL de 300 segundos —no los argumentos— y solo puede usarse una vez.

Véase también

/connect/tool-catalog/: cómo el registro calcula el conjunto de herramientas por nivel.
/connect/hitl-risk-tiers/: el modelo de riesgo de cuatro niveles y la puerta.
/cookbook/connect/extract-text-content/: previsualizar el texto extraíble antes de redactar.
/cookbook/connect/digital-signature/: firmar el documento editado para la cadena de custodia.