NextPDF Connect のセキュリティと運用

概要

NextPDF Connect は、ネットワーク経由のトランスポートでは API キーのベアラートークンで認証します。ローカルの MCP トランスポートは、信頼されたサブプロセスとして分離されます。高リスクのツールはすべて、明示的な人間の確認を必須とするゲートの背後に置かれます。このページでは、認証モデル、トランスポートセキュリティ、および脅威モデルについて説明します。

インストール

composer require nextpdf/server

概念の概要

サーバーには 3 つの信頼境界があり、各トランスポートに 1 つずつ対応します。

この 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）。脆弱または予測可能なトークンは、認証破壊（broken-auth）のアンチパターンとして明示的に指摘されています（同じ出典、脆弱性リスト）。以下の設計は、これらの両方を踏まえて構築されています。

API サーフェス

API キーの形式と検証

キーは npk_live_{kid}_{secret} です。kid は O(1) でレコードを検索するために使用される 8 文字の識別子で、エントロピーはシークレットが担います。ストアは生のキーを保持しません。ストアが保持するのは、キー全体の SHA-256 ダイジェストです。リクエストごとに、サーバーは提示されたトークンをハッシュ化し、定数時間比較（hash_equals）で保存済みのダイジェストと比較します。これにより、誤ったキーがタイミングを通じて情報を漏らすことはありません。無効化されたキーや有効期限切れのキーは、ハッシュチェックの前ではなく後に拒否されます。

REST と gRPC のバリデーターは、このロジックを共有します。REST ミドルウェアは Authorization: Bearer npk_live_… を読み取ります。gRPC の認証機構は、HTTP/2 ヘッダーとして転送される gRPC の authorization 呼び出しメタデータから、同じベアラートークンを読み取ります。そのうえで、gRPC の UNAUTHENTICATED ステータスで呼び出しを失敗させます。

両トランスポートとも、認証前のトラフィックにアンチオートメーションのスロットルを適用します。単一のクライアント識別子からの過剰な試行はレート制限され、拒否されます。REST では 429 Too Many Requests、gRPC では gRPC の RESOURCE_EXHAUSTED ステータスとなります。この制御はデフォルトで有効であるため、レート制限ストアを個別に構成していないデプロイメントも保護します。クライアントは直ちに再試行するのではなく、バックオフすべきです。

認証エラーのレスポンス

REST リクエストでキーが欠落している、形式が不正である、無効化されている、または有効期限切れである場合、401 Unauthorized を problem-details 本文と WWW-Authenticate: Bearer レスポンスヘッダーとともに受け取ります。これは、401 レスポンスが、少なくとも 1 つのチャレンジを含む WWW-Authenticate ヘッダーフィールドを必ず（MUST）含めなければならないという 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 は認証をバイパスするため、オーケストレーターは認証情報なしで稼働状態と準備状態を確認できます。これらはステータスのみを返します。ツールやドキュメントのデータを公開することはありません。
確認トークンは 1 回限りの使用で、有効期間が短く設定されています。 ヒューマンインザループのゲートは、ツール名に紐付けられた、有効期間 300 秒のトークンを発行します。トークンは最初の使用時に消費されます。これは認証情報ではなく、API キーの代わりにはなりません。

パフォーマンス

認証は、リクエストごとに 1 回のハッシュ計算と定数時間比較で構成されます。このコストは、レンダリングのコストと比べると無視できる程度です。ホットリロード対応のキーストアは、キーファイルが変更されると再読み込みします。そのため、ローテーションに再起動は不要であり、リクエストごとのコストも増えません。

セキュリティに関する注意事項

ヒューマンインザループのゲート

すべてのツールはリスクレベルを宣言します。最高レベルである ApprovalRequired のツールは、最初の呼び出しでは実行されません。確認ゲートは、1 回限り使用のトークンを含むチャレンジを返します。エージェントは、このチャレンジを人間に提示し、トークンを付けてツールを再度呼び出す必要があります。これは、自動化された操作によってリスクが生じる箇所に意図的に設けられたコントロールです。これはまさに、人間（ここではエージェント）の操作によって持ち込まれるリスクを、その発生箇所またはその近くで制御する場所として IEC 31010 が示している地点です（IEC 31010:2019）。このゲートを設定によって弱めることはできません。設定によるオーバーライドはツールのリスクを引き上げることだけが可能で、ApprovalRequired のツールを引き下げることはできません。/connect/hitl-risk-tiers/. を参照してください。

トランスポートセキュリティの設定

ネットワーク経由のトランスポートは、TLS 自体を終端しません。TLS はデプロイ側で扱う事項です。リファレンスの統合デプロイでは、gRPC トランスポートを相互 TLS で実行し、鍵、証明書、およびクライアント CA をデプロイ時のシークレットとして提供します。相互 TLS では、サーバーは証明書を提示するとともに、クライアント証明書を要求して検証します。REST トランスポートは TLS ターミネーター（リバースプロキシまたはサービスメッシュ）の背後で実行し、信頼できないネットワーク上に平文のリスナーを公開しないでください。設定の詳細は /connect/deployment/ にあります。これは方針の表明であり、ターンキーの保証ではありません。トランスポートを安全にするには適切なデプロイ設定が必要です。

出力パスの封じ込め

ファイル書き込みツールは、要求されたパスを設定済みのベースディレクトリを基準に resolve（解決）して正規化し、NULL バイト、プロトコルラッパー、および .. によるトラバーサルを拒否します。ベースの外側に解決されるパスはすべて拒否します。ベースディレクトリは、最小権限のファイルシステム権限を設定した専用ボリュームに配置してください。

データレジデンシーと PII 対策

サーバーは、設定された TTL（デフォルト 1800 秒）と上限件数（デフォルト 50）の範囲内で、ドキュメントをインメモリのドキュメントストアにのみ保持します。ファイル出力ツールが明示的に呼び出され、かつパスが封じ込めを通過した場合を除き、ドキュメントの内容をディスクに永続化することはありません。サーバーは、ドキュメントをレンダリングまたは検査するために外部へのネットワーク呼び出しを行わないため、リモートリソースを取得するようツールが明示的に設定されていない限り、ドキュメントのバイト列がデプロイ環境の外に出ることはありません。ステートレスでレジデンシーに配慮が必要なデプロイでは、ファイル出力を無効化し（allow_file_output: false）、enabled_tools を最小限のセットに制限してください。

安全なテレメトリとログのスクラビング

監査ログは、Caution 以上のリスクレベルでのツール実行と、発行されたすべての確認チャレンジを記録します。監査レコードには、ツール名、リスクレベル、および成功フラグが含まれます。ツールの引数は機密情報になり得るものとして扱ってください。ログはアクセス制御を備えたシンクに送り、共有環境では、引数のペイロードを出力してしまうほどの詳細度にグローバルなログレベルを引き上げないでください。MCP トランスポートは、ログの内容が標準出力上のプロトコルストリームに混入しないよう、あえてログを標準エラー出力に書き込みます。

準拠

主張	出典	`reference_id`
認証の破壊は API のセキュリティを損なう	OWASP API Security Top 10 の API2:2023
脆弱/予測可能なトークンは認証破壊のアンチパターンである	OWASP API Security Top 10 の API2:2023
`401` は `WWW-Authenticate` チャレンジを必ず（MUST）含めなければならない	RFC 9110 §11.6.1
認証情報の欠落/無効 → `401` ＋チャレンジ	RFC 9110 §11.6
（人間による）リスクの発生箇所でリスクを制御する	IEC 31010:2019

Model Context Protocol の stdio 信頼モデルは、公式の MCP 仕様のリビジョン 2025-06-18 に従います。MCP 仕様はゲート対象の標準コーパスに含まれていないため、その URL とともに /transports/mcp/ に記録されています。

商用に関する補足

署名、墨消し、コンプライアンス、およびフォレンジックのツールは、nextpdf/premium がサーバーとともにインストールされている場合にのみ存在します。これらが存在しても、認証モデルが変わることはありません。それでも、これらのリスクティアにより、破壊的なツールはヒューマンインザループのゲートの後ろに配置されます。