qu3-app

QU3 - 量子耐性 MCP クライアント

このプロジェクトは、量子耐性マルチコンピュートプロバイダー（MCP）環境との安全なインタラクションのためのクライアントアプリケーション（qu3-app）を提供します。耐量子暗号（PQC）標準を活用して、安全な通信チャネルの確立、クライアント認証、およびサーバーの実証検証を実現します。

このクライアントは、QU3 インタラクションプロトコルをサポートする MCP サーバーと連携するように設計されています。開発およびテスト用に、互換性のあるモックサーバー実装が scripts/mock_mcp_server.py に含まれています。

アーキテクチャとフロー

セキュアな通信フロー

以下の図は、QU3 クライアントと MCP サーバー間に実装されたエンドツーエンドのセキュアな通信パターンを示しています：

sequenceDiagram
    participant Client as QU3 Client (CLI)
    participant Server as MCP Server

    Note over Client,Server: Initial Setup (First Run / Keys Missing)
    Client->>+Server: GET /keys (Fetch Server Public Keys)
    Server-->>-Client: Server KEM PK, Server Sign PK (Base64)
    Client->>Client: Store Server Public Keys Locally

    Note over Client,Server: Establish Secure Session
    Client->>+Server: POST /kem-handshake/initiate { Client KEM PK, Client Sign PK }
    Server->>Server: Encapsulate Shared Secret (using Client KEM PK)
    Server->>Server: Derive AES-256 Session Key & Store Session Details
    Server-->>-Client: { KEM Ciphertext }
    Client->>Client: Decapsulate Shared Secret & Derive AES-256 Session Key
    Client->>Client: Store AES Session Key

    Note over Client,Server: Secured Inference Request
    Client->>Client: Prepare Secure Request (Sign Payload, Encrypt with AES Key)
    Client->>+Server: POST /inference { Client KEM PK, nonce, ciphertext }
    Server->>Server: Process Secure Request (Lookup Session, Validate Timestamp, Decrypt, Verify Signature)
    Server->>Server: Execute Model(input_data) -> output_data
    Server->>Server: Prepare Secure Response (Prepare Attestation, Sign, Encrypt with AES Key)
    Server-->>-Client: { resp_nonce, resp_ciphertext }
    Client->>Client: Process Secure Response (Decrypt, Verify Attestation)
    Client->>Client: Process Result

    Note over Client,Server: Secured Policy Update
    Client->>Client: Prepare Secure Policy (Read, Sign, Encrypt with AES Key)
    Client->>+Server: POST /policy-update { Client KEM PK, policy_nonce, policy_ciphertext, policy_sig }
    Server->>Server: Process Secure Policy (Lookup Session, Validate Timestamp, Decrypt, Verify Signature)
    Server->>Server: Process Policy (Mock)
    Server->>Server: Prepare Secure Status (Sign Status, Encrypt with AES Key)
    Server-->>-Client: { status_nonce, status_ciphertext, status_sig }
    Client->>Client: Process Secure Status (Decrypt, Verify Signature)
    Client->>Client: Display Status

クライアントコンポーネント相互作用

この図は、クライアントアプリケーション内のメイン Python モジュール間の相互作用を示しています：

graph TD
    A("User CLI (Typer)") --> B("src_main");
    B -- Initiates --> C("src_mcp_client (MCPClient)");
    B -- Uses --> D("src_config_utils");
    C -- Uses --> E("src_pqc_utils");
    C -- Uses --> G("requests Session");
    D -- Uses --> H("PyYAML");
    D -- Manages --> I("Key Files");
    D -- Uses --> G;
    E -- Uses --> J("liboqs_python");
    E -- Uses --> K("cryptography");

    subgraph Cryptography
        J
        K
    end

    subgraph Networking
        G
    end

    subgraph "Configuration & Keys"
        H
        I
    end

キー管理概要

鍵はセキュリティプロトコルに重要です。以下はそれらの管理方法です：

graph LR
    subgraph Client Side
        A["CLI: generate-keys"] --> B{"src_main.py"};
        B --> C["src_pqc_utils.py"]:::pqc --> D{"Generate KEM/Sign Pairs"};
        D --> E["src_config_utils.py"]:::config --> F["Save Client Keys (.pub, .sec)"];

        G["CLI: run-inference/etc."] --> B;
        B --> H{"Initialize Client"};
        H --> E --> I{"Load Client Keys?"};
        I -- Found --> J["Use Keys"];
        I -- Not Found --> D;

        H --> E --> K{"Load Server Keys?"};
        K -- Found --> J;
        K -- Not Found --> L{"Fetch Server Keys?"};
        L -- Calls --> E --> M["GET /keys"]:::net;
        M -- Response --> E --> N["Save Server Keys (.pub)"];
        N --> J;
        L -- Fetch Fail --> O["(Error - Cannot Proceed)"];
    end

    subgraph "Server Side (Mock)" 
        P["Server Startup"] --> Q["scripts_mock_mcp_server.py"];
        Q --> R["src_config_utils.py"]:::config --> S{"Load/Generate Server Keys"};
        S --> T["Save Server Keys (.pub, .sec)"];
        Q --> U["Register /keys Endpoint"];
        U -- Request for /keys --> V{"Return Server Public Keys"};
    end

    subgraph "Filesystem (Key Dir)"
        F
        T
        N
    end

    classDef pqc fill:#f9d,stroke:#333,stroke-width:2px;
    classDef config fill:#cfc,stroke:#333,stroke-width:2px;
    classDef net fill:#cdf,stroke:#333,stroke-width:2px;

コアコンポーネント

• src/main.py: Typer で構築されたコマンドライン（CLI）インターフェース。ユーザーコマンドを処理し、クライアント操作をオーケストレーションし、結果を表示します。鍵生成、推論、エージェントワークフロー、ポリシー更新のコマンドを含みます。
• src/mcp_client.py: 以下を担当するメインクライアントクラス（MCPClient）：
  • PQC 鍵の管理。
  • リクエスト（MCPRequest）およびレスポンス（MCPResponse）データ構造の定義。
  • KEM ハンドシェイク（connect）によるセキュアセッションの確立。
  • 署名および暗号化されたリクエストの送信（send_request）。
  • 暗号化/署名されたレスポンスの処理と検証。
  • 切断の処理（disconnect）。
• src/pqc_utils.py: liboqs-python を使用した PQC 操作（Kyber KEM、SPHINCS+ 署名）、cryptography を使用した AES-GCM 暗号化/復号化、および HKDF 鍵導出のユーティリティ関数。
• src/config_utils.py: config.yaml からの設定読み込み、ファイルからの鍵読み込み/保存、および /keys エンドポイントからのサーバー公開鍵取得を処理します。
• scripts/mock_mcp_server.py: MCP 環境をシミュレートする FastAPI 開発/テストサーバー。KEM ハンドシェイク、リクエスト復号化/検証、基本モデル実行、実証署名、レスポンス暗号化、ポリシー更新、鍵配布のサーバー側ロジックを実装します。
• config.yaml: デフォルト鍵ディレクトリ（key_directory）やサーバー URL（server_url）などの設定を保存するための設定ファイル。
• tests/: コアコンポーネント（pqc_utils、config_utils、mcp_client）の単体テスト（unittest）を含むディレクトリ。

機能

• PQC アルゴリズム: NIST PQC ファイナリストを使用:
  • KEM: Kyber-768
  • 署名: SPHINCS+-SHA2-128f-simple
• PQC 鍵管理: Kyber および SPHINCS+ 鍵ペアを生成およびロードします。
• セキュアセッション確立: ネットワークハンドシェイク (/kem-handshake/initiate) 上で Kyber KEM を使用して共有シークレットを確立します。
• 鍵導出: HKDF-SHA256 を使用して KEM 共有シークレットから 32 バイトの AES-256 鍵を導出します。
• 暗号化通信: KEM ハンドシェイク後、導出されたセッション鍵を使用して AES-256-GCM でリクエスト/レスポンスペイロードを暗号化します。
• クライアント認証: クライアントが SPHINCS+ を使用してリクエストに署名し、サーバーが検証します。
• サーバーアテステーション: サーバーが SPHINCS+ を使用してレスポンス (アテステーションデータ) に署名し、クライアントが検証します。
• 設定: config.yaml から鍵ディレクトリとサーバー URL をロードします。
• 自動化されたサーバー鍵取得: クライアントがローカルで見つからない場合、/keys エンドポイントからサーバー公開鍵を自動的に取得します。
• CLI コマンド:
  • generate-keys: クライアント鍵ペアを作成します。
  • run-inference: 単一の保護されたインファレンスリクエストを送信します。
  • run-agent: 順序付きワークフロー (modelA->modelB) を実行し、出力を入力として渡します (非辞書出力をラップ)、ステップバイステップのレポートと堅牢な失敗処理を含みます。
  • update-policy: 暗号化および署名されたポリシーファイルをサーバーに送信します。
• モックサーバー: 対応するサーバー側の PQC および通信ロジックを実装するエンドポイント (/, /keys, /kem-handshake/initiate, /inference, /policy-update) を含みます。テスト用にサンプルモデル model_caps および model_reverse を提供します。
• ユニットテスト: コア暗号化ユーティリティ、設定管理、およびクライアント通信ロジック (ネットワークモック付き) をカバーするユニットテストを含みます。

セットアップ

1. リポジトリをクローン:

   git clone <repository_url>
   cd qu3-app
   

2. 仮想環境を作成:

   python3 -m venv venv
   source venv/bin/activate
   

3. 依存関係をインストール:

   pip install -r requirements.txt
   

   (注: liboqs-python には C コンパイラおよび liboqs C ライブラリなどのシステム依存関係が必要な場合があります。インストールが失敗した場合は、そのドキュメントを参照してください。)
4. (オプション) config.yaml を設定: 必要に応じて key_directory または server_url を変更します。デフォルトの鍵ディレクトリは ~/.qu3/keys/ です。

クイックスタート

# Easy installation
./scripts/install.sh
# Validate setup
python -m src.main validate-config
# Test connection
python -m src.main test-connection
# Run benchmarks
python -m src.main benchmark

モックサーバーを実行

1 つのターミナルで実行:

# Ensure virtual environment is active
source venv/bin/activate

python -m scripts.mock_mcp_server

サーバーが起動します (通常は http://127.0.0.1:8000) し、設定されたキーディレクトリに独自の鍵ペアが存在しない場合は自動的に生成します。

クライアント CLI を実行

別のターミナル (仮想環境がアクティベートされた状態) で:

1. クライアント鍵を生成: (一度実行すれば十分です。--force を使用しない限り)

   python -m src.main generate-keys
   

2. サーバー鍵を取得 (自動): クライアントは初期化中 (run-inference, run-agent, update-policy) にサーバーの /keys エンドポイントから鍵の取得を試みます。server_kem.pub と server_sign.pub が config.yaml で指定されたキーディレクトリに見つからない場合です。接続が必要なクライアントコマンドを実行する前に、モックサーバーが実行されていることを確認してください。

3. 単一インファレンスを実行:

   # モックサーバーの model_caps を使用した例
   python -m src.main run-inference model_caps '{"text": "process this data"}'
   
   # サーバー URL を指定した例
   python -m src.main run-inference model_reverse '{"text": "backward"}' --server-url http://127.0.0.1:8000
   

4. エージェントワークフローを実行:

   # 2 つのモックモデルをチェーンした例
   python -m src.main run-agent "model_caps -> model_reverse" '{"text": "flow start"}'
   

5. ポリシーを更新: ポリシーファイル (例: my_policy.txt) をいくつかのコンテンツで作成します。

   echo "Allow model_caps access." > my_policy.txt
   python -m src.main update-policy --policy-file my_policy.txt
   

テストの実行

ユニットテストを実行するには:

# Ensure virtual environment is active
source venv/bin/activate

python -m unittest discover tests

または特定のテストファイルを実行します:

python -m unittest tests.test_pqc_utils
python -m unittest tests.test_config_utils
python -m unittest tests.test_mcp_client

🆕 最新のアップデート

最新リリースには、開発者体験の大幅な改善が含まれています:

新しい CLI コマンド

• validate-config: 環境と設定の包括的な検証
• inspect-keys: 詳細なキー検査とステータスレポート
• test-connection: オペレーションなしでのサーバー接続テスト
• benchmark: 量子耐性オペレーションのパフォーマンス測定

強化されたインストール

• 自動インストールスクリプト (scripts/install.sh) が複雑な依存関係を処理
• Docker 開発環境の改善
• エラーハンドリングと診断の向上

ドキュメント & サンプル

• 包括的なトラブルシューティングガイド (TROUBLESHOOTING.md)