Caviarder les données personnelles d'un PDF avec Connect

Caviarder les données personnelles d’un PDF via Connect

En bref

Cette recette montre comment retirer les données personnelles détectées dans la couche de texte d’un document à l’aide des outils de caviardage exposés par NextPDF Connect. Ces outils relèvent de l’édition Enterprise. ToolRegistry construit redact_pdf, zone_redact_pdf et deidentify_pdf en vérifiant la présence des classes de confidentialité Enterprise (RedactionEngine + PiiDetector) avec class_exists(), et ne les enregistre sous l’édition enterprise que lorsque ces classes sont chargeables par l’autoloader. Sur une installation purement open source, ces outils sont absents : l’appel échoue avec une erreur d’outil inconnu plutôt que de se dégrader silencieusement. Les trois outils déclarent destructiveHint: true. L’opération réécrit le contenu de la page et n’est pas réversible à partir du document modifié.

Cette page documente le comportement des outils sur la surface Connect. Un flux de caviardage ne certifie pas qu’un document donné est exempt de données personnelles après l’appel. La détection ne porte que sur la couche de texte extractible, et la vérification du résultat reste de la responsabilité du déploiement.

Installation

composer require nextpdf/server

Les outils de caviardage ne sont enregistrés que lorsque le module de confidentialité Enterprise est installé aux côtés du serveur. Il est livré dans nextpdf/premium. Vérifie que l’outil est bien présent dans le déploiement en cours d’exécution avant de t’y fier :

./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 est absent du résultat de tools/list, c’est que les classes de confidentialité Enterprise n’ont pas pu être résolues sur cette installation. Consulte /connect/tool-catalog/ pour savoir comment le registre calcule l’ensemble d’outils par édition au démarrage.

Vue d’ensemble conceptuelle

Trois outils couvrent trois stratégies de caviardage. Tous relèvent de l’édition Enterprise, et tous portent l’indicateur destructif :

• redact_pdf — détecte et retire les données personnelles du contenu en texte brut du document à l’aide d’un détecteur intégré, puis renvoie le contenu modifié ainsi qu’un rapport structuré.
• zone_redact_pdf — applique au contenu en texte brut des caviardages par zone fondés sur des coordonnées. Utilise-le lorsque tu connais la région à retirer par sa position plutôt que par un motif.
• deidentify_pdf — applique une stratégie de désidentification systématique (caviarder ou supprimer) à l’ensemble des entités détectées.

Retirer du contenu d’un flux de contenu de page constitue une modification destructive de ce flux — les octets concernés sont réécrits et ne sont pas récupérables à partir du document modifié (ISO 32000-2 §14.11). Par conception, le rapport consigne le nombre de caractères et la position de chaque retrait, jamais le texte retiré lui-même.

Surface de l’API

Le schéma exact de requête et de réponse de chaque outil est livré avec le paquet Enterprise qui le définit. Cette page documente le contrat d’appel Connect, et non une liste de paramètres figée. Les noms d’outils vérifiés auprès du registre en cours d’exécution sont redact_pdf, zone_redact_pdf et deidentify_pdf, tous dans la catégorie document avec destructiveHint: true. Le catalogue de référence est /connect/tool-catalog/. Cette recette ne fige pas de nombre d’outils, car il s’agit d’une propriété d’exécution du déploiement.

Exemple de code — Démarrage rapide

Détecte et retire les données via MCP (tools/call). Les arguments ci-dessous illustrent la forme de l’appel. Le schéma d’arguments qui fait foi est celui que tools/list renvoie sur ton déploiement :

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

Un appel réussi renvoie un rapport. Pour chaque retrait, une entrée consigne la page, une étiquette de catégorie, le nombre initial de caractères et un rectangle englobant — mais pas le texte retiré.

Exemple de code — Production

Traite l’appel de caviardage comme une opération destructive, et inspecte le rapport avant de diffuser le document. Sur un transport réseau, une défaillance de transport et une erreur au niveau de l’outil sont deux cas distincts :

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

Ne diffuse le document modifié qu’après revue du rapport par un humain ou par un contrôle en aval. Conditionner la diffusion à cette revue place le contrôle à l’endroit où la modification automatisée introduit le risque de données résiduelles (IEC 31010:2019).

Cas limites & pièges

• PDF numérisé sans couche de texte. La détection s’exécute sur la couche de texte extractible. Une page composée uniquement d’images donne zéro retrait et ne constitue pas une erreur. Si le contenu est rastérisé, applique l’OCR au document avant le caviardage.
• Source chiffrée. Fournis le mot de passe du document via le schéma d’arguments de l’outil. Sans lui, l’appel échoue plutôt que de traiter le document partiellement.
• Outil absent. Sur une installation purement open source, les classes de confidentialité Enterprise ne peuvent pas être résolues et redact_pdf n’est pas enregistré, si bien que l’appel échoue avec une erreur d’outil inconnu. Il s’agit de la limite voulue, et non d’une dégradation.
• Détections qui se chevauchent. Lorsque plusieurs détecteurs correspondent à la même région, la région est retirée une seule fois et le rapport déduplique les entrées.

Performance

Le budget de performance défini dans le front-matter est un plafond documentaire, et non une garantie de niveau de service. Les documents volumineux sont traités page par page. Prévois de relancer l’appel sur un sous-ensemble de plages de pages plutôt que d’augmenter le délai d’expiration global.

Notes de sécurité

Résidence des données & mesures d’atténuation des données personnelles

Le texte du document est traité au sein du processus, sur l’hôte Connect. Le rapport omet délibérément le texte retiré et ne signale que des décomptes et des positions, de sorte que le rapport lui-même ne réintroduit pas les données personnelles qu’il décrit. La résidence des données, au niveau du déploiement, pour l’entrée comme pour la sortie modifiée, relève de la responsabilité de l’intégrateur, et non d’une propriété de l’outil.

Télémétrie sûre & nettoyage des journaux

Ne journalise pas le chemin du document source ni le corps du rapport dans un niveau de journalisation exporté vers l’extérieur. Ne journalise que le nom de l’outil, l’identifiant de la requête et le résultat pass/fail.

Modèle de menace

Un caviardage qui masque visuellement le texte sans le retirer laisse les données extractibles. Ces outils réécrivent le flux de contenu concerné plutôt que d’y superposer un rectangle ; récupérer les octets retirés à partir du document modifié n’est pas possible (ISO 32000-2 §14.11). Le risque résiduel tient au contenu que le détecteur n’a pas reconnu : un motif qui échappe à ses règles, ou du texte présent uniquement sous forme d’image rastérisée. Le flux atténue ce risque par la revue obligatoire du rapport, et non en prétendant à l’exhaustivité.

Comportement en mode FIPS

Le caviardage n’effectue aucune opération cryptographique et n’est pas affecté par une politique de mode FIPS sur l’hôte.

Conformité

Assertion	Clause	reference_id
Le retrait de contenu réécrit le flux de contenu concerné	ISO 32000-2 §14.11
Le caviardage marque puis retire ; le retrait est une modification de contenu	ISO 32000-2 §14.11
Contrôle placé à l’endroit où la modification automatisée introduit le risque	IEC 31010:2019

La prise en charge des outils de caviardage ne constitue pas une certification qu’un document traité est exempt de données personnelles. Cette détermination relève d’une revue indépendante.

Contexte commercial

Les outils de caviardage relèvent de l’édition Enterprise. Ils ne sont enregistrés que lorsque nextpdf/premium est installé aux côtés du serveur. Consulte le lien de conversion dans le front-matter.

Spécificités de Connect

Disponibilité des transports (MCP / REST / gRPC)

Tu invoques les outils de façon identique sur chaque transport qui passe par l’exécuteur d’outils partagé : MCP tools/call, le point de terminaison d’outils REST et le service gRPC. Le schéma d’arguments est indépendant du transport. C’est celui que renvoie tools/list (MCP) ou le descripteur de service (gRPC).

Niveau de risque HITL

Les trois outils déclarent destructiveHint: true. Un opérateur qui élève un outil au niveau de risque approval_required via une surcharge de configuration place l’appel derrière le ConfirmationGate. La surcharge ne peut qu’élever le risque, jamais l’abaisser. Consulte /connect/hitl-risk-tiers/.

Enveloppe JSON de la barrière de confirmation

Lorsque l’outil est protégé par la barrière et invoqué sans jeton valide, la barrière renvoie une enveloppe de défi de cette forme :

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

L’appelant réinvoque le même outil avec arguments._confirmation_token renseigné avec le jeton émis. Le jeton lie le nom de l’outil, un nonce et une durée de vie (TTL) de 300 secondes — mais pas les arguments — et il est à usage unique.

Voir aussi

• /connect/tool-catalog/ — comment le registre calcule l’ensemble d’outils par édition.
• /connect/hitl-risk-tiers/ — le modèle de risque à quatre niveaux et la barrière.
• /cookbook/connect/extract-text-content/ — prévisualise le texte extractible avant de caviarder.
• /cookbook/connect/digital-signature/ — signe le document modifié pour assurer la chaîne de traçabilité.