QU3 - Quantum-Safe MCP Client

This project provides a client application (qu3-app) for secure interaction with Quantum-Safe Multi-Compute Provider (MCP) environments. It leverages post-quantum cryptography (PQC) standards for establishing secure communication channels, ensuring client authenticity, and verifying server attestations.

This client is designed to work with MCP servers that support the QU3 interaction protocols. For development and testing, a compatible mock server implementation is included in scripts/mock_mcp_server.py.

Architecture & Flow

Secure Communication Flow

The following diagram illustrates the end-to-end secure communication pattern implemented between the QU3 Client and the MCP Server:

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

Client Component Interaction

This diagram shows how the main Python modules within the client application interact:

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

Key Management Overview

Keys are crucial for the security protocols. Here's how they are managed:

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 Clie

... [View full README on GitHub](https://github.com/qu3ai/qu3-app#readme)