Connect를 통해 PDF에서 PII를 삭제합니다

Connect를 통해 PDF에서 PII를 삭제합니다

한눈에 보기

이 레시피에서는 NextPDF Connect가 노출하는 삭제 도구를 사용하여 문서의 텍스트 레이어에서 탐지된 개인 데이터를 제거합니다. 이들 도구는 Enterprise 등급입니다. ToolRegistry는 class_exists()로 Enterprise 프라이버시 클래스(RedactionEngine + PiiDetector)를 탐지하여 redact_pdf, zone_redact_pdf, deidentify_pdf를 구성하며, 해당 클래스가 오토로드 가능할 때만 각 도구를 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/에 있습니다. 이 레시피는 도구 개수를 다시 명시하지 않습니다. 이는 배포의 런타임 속성이기 때문입니다.

코드 샘플 — 빠른 시작

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가 등록되지 않으므로, 호출은 알 수 없는 도구 오류로 실패합니다. 이는 의도된 경계이며, 기능이 조용히 저하되는 동작이 아닙니다.
• 중첩된 탐지. 둘 이상의 탐지기가 동일한 영역을 일치 항목으로 찾으면, 해당 영역은 한 번만 제거되고 보고서에서는 중복이 제거됩니다.

성능

프런트매터의 성능 예산은 문서화된 상한이며 서비스 수준 보장이 아닙니다. 대용량 문서는 페이지 단위로 처리됩니다. 전역 시간 초과를 높이기보다 페이지 범위의 하위 집합에 대해 호출을 다시 실행하는 방식을 예산에 반영합니다.

보안 참고 사항

데이터 레지던시 및 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 위험 등급

세 도구 모두 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/tool-catalog/ — 레지스트리가 등급별 도구 집합을 계산하는 방식.
• /connect/hitl-risk-tiers/ — 4단계 위험 모델과 게이트.
• /cookbook/connect/extract-text-content/ — 삭제하기 전에 추출 가능한 텍스트를 미리 봅니다.
• /cookbook/connect/digital-signature/ — 보관 연속성을 위해 편집된 문서에 서명합니다.