NextPDF Connect의 보안 및 운영

한눈에 보기

NextPDF Connect는 API 키 베어러 토큰으로 네트워크 전송을 인증합니다. 로컬 MCP 전송은 신뢰할 수 있는 하위 프로세스로 격리됩니다. 모든 고위험 도구는 명시적인 사람 확인을 거치도록 게이트로 보호됩니다. 이 페이지에서는 인증 모델, 전송 보안, 위협 모델을 설명합니다.

설치

composer require nextpdf/server

개념적 개요

서버에는 각 전송마다 하나씩, 세 개의 신뢰 경계가 있습니다.

세 전송 중 MCP stdio 전송은 로컬 클라이언트가 시작하는 하위 프로세스입니다. 표준 입력에서 JSON-RPC를 읽고 표준 출력에 응답을 씁니다. 이 전송에는 네트워크 리스너와 API 키가 없습니다. 신뢰는 운영 체제의 프로세스 경계에서 상속되며, 이는 MCP 사양이 stdio에 대해 정의하는 신뢰 모델입니다. 로그는 표준 오류로 전달되므로 프로토콜 스트림을 손상시키지 않습니다.

나머지 두 전송인 REST 전송과 gRPC 전송은 네트워크 전송입니다. 두 전송 모두 인증이 필요 없는 상태 점검 프로브를 제외한 모든 요청에 API 키 베어러 토큰을 요구합니다. 동일한 키 저장소, 키 형식, 상수 시간 검증이 두 전송에 모두 사용됩니다. gRPC 전송은 호출 메타데이터에서 토큰을 읽고, REST는 Authorization 헤더에서 읽습니다.

잘못 구현된 인증은 OWASP API Security Top 10이 API2:2023 Broken Authentication으로 지목하는 실패 유형입니다. 여기에 구현 결함이 있으면 호출자를 식별하는 API의 능력이 손상되고, 따라서 API 보안 전반이 손상됩니다(OWASP API Security Top 10, API2:2023). 약하거나 예측 가능한 토큰은 깨진 인증 안티패턴으로 명시적으로 지적됩니다(동일 출처, 취약점 목록). 아래 설계는 이 두 위험을 모두 방어하도록 구성되었습니다.

API 표면

API 키 형식 및 검증

키는 npk_live_{kid}_{secret} 형식입니다. kid는 O(1) 레코드 조회에 사용되는 8 자 식별자이며, 시크릿이 엔트로피를 담습니다. 저장소는 원시 키를 절대 보관하지 않고, 전체 키 자료의 SHA-256 다이제스트만 보관합니다. 서버는 각 요청에서 제시된 토큰을 해시하여 저장된 다이제스트와 상수 시간 비교(hash_equals)로 대조하므로, 잘못된 키는 타이밍을 통해 아무 정보도 드러내지 않습니다. 비활성화되거나 만료된 키는 해시 검사 이전이 아니라 이후에 거부됩니다.

REST 및 gRPC 검증기는 이 로직을 공유합니다. REST 미들웨어는 Authorization: Bearer npk_live_…를 읽습니다. gRPC 인증기는 동일한 베어러 토큰을 gRPC authorization 호출 메타데이터에서 읽으며, 이는 HTTP/2 헤더로 전송됩니다. 인증에 실패하면 gRPC UNAUTHENTICATED 상태로 호출을 실패 처리합니다.

두 전송 모두 사전 인증 트래픽에 자동화 방지 스로틀을 적용합니다. 하나의 클라이언트 ID에서 과도한 시도가 발생하면 속도 제한으로 거부됩니다. REST에서는 429 Too Many Requests, gRPC에서는 gRPC RESOURCE_EXHAUSTED 상태로 응답합니다. 이 제어는 기본적으로 활성화되어 있으므로, 속도 제한 저장소를 별도로 구성하지 않은 배포 환경도 보호합니다. 클라이언트는 즉시 재시도하기보다 백오프해야 합니다.

권한 없음 응답

키가 없거나 형식이 잘못되었거나 비활성화되었거나 만료된 REST 요청은 401 Unauthorized와 problem-details 본문, 그리고 WWW-Authenticate: Bearer 응답 헤더를 받습니다. 이는 401 응답이 하나 이상의 챌린지를 포함하는 WWW-Authenticate 헤더 필드를 반드시 포함해야 한다는 HTTP 요구 사항과 일치합니다(RFC 9110 §11.6.1). 이 요구 사항은 자격 증명이 누락되었거나 잘못된 자격 증명을 담은 요청에는 401과 WWW-Authenticate 챌린지로 응답해야 한다는 규칙에서 비롯됩니다(RFC 9110 §11.6).

키 엔타이틀먼트

각 키 레코드는 허용되는 최대 제품 등급을 담고 있습니다. REST 파이프라인은 인증된 클라이언트의 ID와 등급을 요청에 첨부하므로, 다운스트림 권한 부여가 등급별 기능 및 페이로드 상한을 적용할 수 있습니다. core 등급 키는 해당 패키지가 설치되어 있더라도 Pro 또는 Enterprise 작업을 실행할 수 없습니다.

엣지 케이스 및 주의 사항

• MCP 전송에는 API 키가 없습니다. 이는 의도적이며 로컬 하위 프로세스에 적합합니다. MCP 서버를 네트워크 심을 통해 노출하지 마십시오. 네트워크를 통해 접근하는 에이전트가 도구를 필요로 하는 경우, 인증을 수행하는 REST 또는 gRPC 전송 앞에 배치하십시오.

• 상태 점검 프로브는 의도적으로 익명입니다. /healthz와 /readyz는 인증을 우회하므로, 오케스트레이터가 자격 증명 없이 활성 상태와 준비 상태를 점검할 수 있습니다. 이 엔드포인트는 상태만 반환하며, 어떤 도구 또는 문서 데이터도 노출하지 않습니다.

• 확인 토큰은 일회용이며 수명이 짧습니다. 휴먼인더루프 게이트는 도구 이름에 바인딩되고 수명이 300 초인 토큰을 발급합니다. 토큰은 처음 사용될 때 소비됩니다. 이는 인증용 자격 증명이 아니며 API 키를 대체하지 않습니다.

성능

인증은 요청당 단일 해시와 상수 시간 비교 하나로 이루어집니다. 그 비용은 렌더링 비용에 비하면 무시할 수 있는 수준입니다. 핫 리로딩 키 저장소는 키 파일이 변경되면 다시 읽히므로, 키 교체에 재시작이 필요하지 않고 요청당 비용도 추가하지 않습니다.

보안 참고 사항

휴먼인더루프 게이트

모든 도구는 위험 수준을 선언합니다. 최고 수준인 ApprovalRequired 도구는 첫 호출에서 실행되지 않습니다. 확인 게이트는 일회용 토큰이 포함된 챌린지를 반환합니다. 에이전트는 챌린지를 사람에게 제시하고 토큰과 함께 도구를 다시 호출해야 합니다. 이는 자동화된 작업이 위험을 유발하는 지점에 배치된 의도적인 통제입니다. 이는 IEC 31010이 사람(여기서는 에이전트)의 행위로 발생한 위험을 발생 지점 또는 그 부근에서 통제하기 위해 지목하는 지점과 일치합니다(IEC 31010:2019). 게이트는 구성으로 약화될 수 없습니다. 구성 재정의는 도구의 위험을 높일 수만 있으며, ApprovalRequired 도구를 낮출 수는 없습니다. /connect/hitl-risk-tiers/를 참조하십시오.

전송 보안 구성

네트워크 전송은 TLS를 자체적으로 종료하지 않습니다. TLS는 배포 환경의 책임 범위입니다. 참조용 통합 배포는 gRPC 전송을 상호 TLS로 실행하며, 키, 인증서 및 클라이언트 CA를 배포 시크릿으로 제공합니다. 상호 TLS에서는 서버가 인증서를 제시하고 클라이언트 인증서를 요구하고 검증합니다. REST 전송은 TLS 종료자(역방향 프록시 또는 서비스 메시) 뒤에서 실행하고, 신뢰할 수 없는 네트워크에 평문 리스너를 절대 노출하지 마십시오. 구성 세부 사항은 /connect/deployment/에 있습니다. 이는 보안 태세에 대한 설명이지 턴키 보장이 아니며, 보안 전송에는 올바른 배포 구성이 필요합니다.

출력 경로 격리

파일 쓰기 도구는 구성된 기본 디렉터리를 기준으로 요청된 경로를 해석하고 정규화하며, 널 바이트, 프로토콜 래퍼 및 .. 순회를 거부합니다. 기본 디렉터리 밖으로 해석되는 경로는 모두 거부합니다. 기본 디렉터리는 최소 권한 파일 시스템 권한을 갖는 전용 볼륨에 두십시오.

데이터 거주성 및 PII 완화 조치

서버는 구성된 TTL(기본값 1800 초)과 제한된 개수(기본값 50) 범위 안에서만 인메모리 문서 저장소에 문서를 보관합니다. 파일 출력 도구가 명시적으로 호출되고 경로가 격리를 통과하는 경우를 제외하고는 문서 내용을 디스크에 저장하지 않습니다. 서버는 문서를 렌더링하거나 검사하기 위한 아웃바운드 네트워크 호출을 수행하지 않으므로, 도구가 원격 리소스를 가져오도록 명시적으로 구성되지 않는 한 문서 바이트는 배포 환경을 벗어나지 않습니다. 상태 비저장성이 필요하고 거주성에 민감한 배포의 경우, 파일 출력을 비활성화하고(allow_file_output: false) enabled_tools를 최소 집합으로 제한하십시오.

안전한 원격 측정 및 로그 스크러빙

감사 로깅은 Caution 위험 수준 이상의 도구 실행과 발급된 모든 확인 챌린지를 기록합니다. 감사 레코드는 도구 이름, 위험 수준 및 성공 플래그를 담습니다. 도구 인수는 잠재적으로 민감한 것으로 취급하십시오. 로그를 액세스 제어가 적용된 싱크로 전달하고, 공유 환경에서 인수 페이로드를 반영하는 상세 수준으로 전역 로그 수준을 높이지 마십시오. MCP 전송은 로그 내용이 표준 출력의 프로토콜 스트림에 절대 들어가지 않도록 의도적으로 로그를 표준 오류에 씁니다.

적합성

주장	출처	reference_id
깨진 인증은 API 보안을 손상시킵니다	OWASP API 보안 Top 10, API2:2023
약하거나 예측 가능한 토큰은 깨진 인증 안티패턴입니다	OWASP API 보안 Top 10, API2:2023
401은 WWW-Authenticate 챌린지를 반드시 포함해야 합니다	RFC 9110 §11.6.1
누락/잘못된 자격 증명 → 401 + 챌린지	RFC 9110 §11.6
(사람) 유발 지점에서 위험을 통제	IEC 31010:2019

Model Context Protocol stdio 신뢰 모델은 공식 MCP 사양 개정판 2025-06-18을 따릅니다. MCP 사양은 게이트된 표준 코퍼스의 일부가 아니므로, /transports/mcp/에 해당 URL과 함께 기록됩니다.

상업적 맥락

서명, 편집(redaction), 규정 준수 및 포렌식 도구는 nextpdf/premium이 서버와 함께 설치된 경우에만 존재합니다. 이러한 도구가 존재하더라도 인증 모델은 변경되지 않습니다. 이들의 위험 등급은 여전히 파괴적인 도구를 휴먼인더루프 게이트 뒤에 둡니다.

함께 보기

• /connect/hitl-risk-tiers/ — 위험 모델 및 확인 엔벨로프 세부 정보
• /connect/deployment/ — TLS, 상호 TLS, 시크릿 및 워커 튜닝
• /transports/rest/ — REST 미들웨어 파이프라인 및 OpenAPI 보안 스키마
• /transports/grpc/ — gRPC 메타데이터 인증 및 상태 코드
• /connect/configuration/ — enabled_tools, 키 저장소 선택, 위험 재정의