@fhestate/mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FHESTATE Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,432 @@
+<div align="center">
+
+# 🧠 FHESTATE: Model Context Protocol (MCP) Server
+
+### *AUTONOMOUS AI AGENTS POWERED BY FULLY HOMOMORPHIC ENCRYPTION (FHE)*
+
+> **"Granting AI the power to execute FHE on-chain, without ever seeing the plaintext."**
+
+[![FHESTATE](https://img.shields.io/badge/FHESTATE-MCP_v1.0.0-8A2BE2?style=for-the-badge&logo=rocket&logoColor=white)](https://github.com/fhestate/fhestate-mcp)
+[![Solana](https://img.shields.io/badge/Solana-Devnet-14F195?style=for-the-badge&logo=solana&logoColor=black)](https://solana.com)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+<br>
+[![Model Context Protocol](https://img.shields.io/badge/Protocol-MCP-orange?style=for-the-badge)](https://modelcontextprotocol.io)
+[![TFHE-rs](https://img.shields.io/badge/TFHE--rs-v0.7.3-red?style=for-the-badge&logo=rust&logoColor=white)](https://github.com/zama-ai/tfhe-rs)
+
+</div>
+
+## 📑 Table of Contents
+
+- [1. Overview](#-1-overview)
+- [2. The Coprocessor Architecture & IPC](#%EF%B8%8F-2-the-coprocessor-architecture--ipc)
+- [3. The Security & Redaction Engine](#-3-the-security--redaction-engine)
+- [4. The Confidential Execution Flow (Memo Anchoring)](#-4-the-confidential-execution-flow-memo-anchoring)
+- [5. Use Case: Autonomous Agent Workflows](#-5-use-case-autonomous-agent-workflows)
+- [6. The Comprehensive Tool Matrix](#%EF%B8%8F-6-the-comprehensive-tool-matrix)
+- [7. Quick Start & IDE Integration](#-7-quick-start--ide-integration)
+- [8. LLM Execution Example (JSON-RPC Lifecycle)](#-8-llm-execution-example-json-rpc-lifecycle)
+- [9. Troubleshooting & IPC Error Codes](#-9-troubleshooting--ipc-error-codes)
+- [10. Contact & Support](#-10-contact--support)
+
+---
+
+## 🌟 1. Overview
+
+The **FHESTATE MCP Server** is a production-grade execution bridge that connects non-deterministic Large Language Models (LLMs) like Claude 3.5 Sonnet to deterministic Fully Homomorphic Encryption (FHE) on the Solana blockchain.
+
+In the current landscape of Artificial Intelligence, LLMs act as "brains in vats." They can reason and write code, but they are fundamentally isolated from secure, cryptographic hardware. The FHESTATE Model Context Protocol (MCP) solves this by providing a standardized, zero-trust `stdio` pipeline directly into a local Rust cryptographic coprocessor. 
+
+By utilizing this MCP Server, you transform a passive AI chatbot into an active, confidential FHE operator. The AI can autonomously encrypt local memory, perform off-chain homomorphic math, and anchor the resulting `SHA-256` hash commitments to the Solana blockchain—all without ever possessing the decryption keys.
+
+### 1.1 The Institutional Paradigm Shift
+- 🤖 **Zero-Trust AI Autonomy**: The LLM can direct FHE operations without ever seeing the plaintext data or the `client_key.bin`.
+- 🛡️ **Subprocess Isolation**: Heavy TFHE mathematics are routed safely through local Rust subprocesses to prevent AI memory exhaustion and Denial of Service (DoS).
+- 🔗 **Solana Devnet Anchoring**: Agents can autonomously construct, sign, and broadcast transactions to the Solana Devnet, spending local wallet funds to post immutable cryptographic proofs.
+- 🔒 **Aggressive Redaction**: Absolute system paths are scrubbed from LLM context windows to prevent local host topology leaks to cloud providers (OpenAI/Anthropic).
+- ✅ **Strict Zod Boundaries**: Cryptographic `Uint32` constraints are strictly enforced via Zod schemas, instantly rejecting AI hallucinations before they crash the Rust binary.
+
+---
+
+## 🏗️ 2. The Coprocessor Architecture & IPC
+
+The fundamental challenge of implementing FHE on Solana is the strict 1.4 million Compute Unit (CU) transaction limit. Evaluating a single TFHE-rs boolean gate requires thousands of CPU cycles; evaluating a full homomorphic addition or multiplication requires billions.
+
+To solve this, the FHESTATE MCP Server implements a **Coprocessor Architecture**. The Node.js server does not perform the cryptography itself. Instead, it securely spawns the `fhe-cli` Rust binary, acts as a sanitization layer, and manages the blockchain network calls.
+
+### 2.1 Component Interaction Flow
+
+```mermaid
+graph TD
+    subgraph "Cloud / AI Layer"
+        LLM[Claude 3.5 / Cursor LLM]
+        MCP_CLIENT[MCP Client Interface]
+    end
+
+    subgraph "Host Machine (Node.js MCP Server)"
+        ZOD[Zod Validation Layer]
+        REDACT[Path Redaction Engine]
+        RPC_SERVER[JSON-RPC 2.0 Server]
+        WEB3[Solana Web3.js]
+    end
+
+    subgraph "Host Machine (Rust / Cryptography)"
+        FHE_CLI[fhe-cli Binary]
+        TFHE[TFHE-rs Library]
+        KEYS[.fhe_keys Directory]
+    end
+
+    subgraph "Solana Network"
+        DEVNET[Solana Devnet RPC]
+    end
+
+    LLM <-->|JSON-RPC via stdio| MCP_CLIENT
+    MCP_CLIENT <--> RPC_SERVER
+    
+    RPC_SERVER -->|Validate Params| ZOD
+    ZOD -->|fhe_encrypt / blind_step| FHE_CLI
+    FHE_CLI -->|Reads| KEYS
+    FHE_CLI -->|Computes| TFHE
+    FHE_CLI -->|stdout Hash| REDACT
+    REDACT --> RPC_SERVER
+    
+    ZOD -->|devnet_submit_memo| WEB3
+    WEB3 -->|Sign Tx| DEVNET
+```
+
+### 2.2 Deep Dive: Inter-Process Communication (IPC)
+The MCP server uses asynchronous `stdio` to communicate with the IDE/Claude Desktop, but it uses `child_process.spawn` to communicate with the Rust Coprocessor. This is managed by the `cli-bridge.ts` module.
+
+When the AI Agent calls `fhe_encrypt(42)`:
+1. **Payload Interception**: The Node MCP Server receives the JSON-RPC request.
+2. **Argument Construction**: Node constructs an argument array: `['encrypt', '--value', '42']`. It strictly avoids using shell interpolation.
+3. **Subprocess Spawning**: Node spawns the Rust process with `shell: false` and a `cwd` restricted to the workspace.
+4. **Lattice Computation**: The Rust Coprocessor spins up the TFHE-rs lattice mathematics. This consumes ~500MB of RAM and heavily utilizes the CPU for roughly 2-3 seconds to generate a massive 15MB ciphertext file.
+5. **Buffer Management**: The Rust binary writes the resulting SHA-256 hash of that file to its `stdout` pipe. Node's `cli-bridge.ts` reads the stream.
+6. **Graceful Exit**: The Node server closes the process, parses the output through the Redaction Engine, and returns the formatted hash to the AI.
+
+---
+
+## 🔒 3. The Security & Redaction Engine
+
+Because the AI Agent is fundamentally untrusted and operates in a non-deterministic manner, the MCP Server implements extreme isolation and data scrubbing mechanisms. It assumes the LLM is actively hostile or prone to severe hallucinations.
+
+### 3.1 The Redaction Engine (`redact.ts`)
+
+LLMs are cloud-hosted. If the local Rust binary outputs a success message like `Saved to C:\Users\Admin\Documents\Crypto\.fhe_keys\client_key.bin`, passing this raw string back to the LLM exposes your local folder structure, username, and topology to Anthropic/OpenAI servers.
+
+The MCP Server utilizes a specialized **Redaction Engine** that intercepts all `stdout` arrays before they are formatted into the JSON-RPC response.
+
+```mermaid
+flowchart LR
+    Rust[Rust Coprocessor] -->|Raw stdout| Buffer[Node.js Buffer]
+    Buffer --> Regex1[Regex: Match Absolute Paths]
+    Regex1 --> Regex2[Regex: Match Base58/Seeds]
+    Regex2 --> Mask[Overwrite with REDACTED]
+    Mask --> LLM[Return to AI Context]
+```
+
+- **Path Scrubbing**: It uses heuristic regex to locate Windows (`C:\...`) and POSIX (`/...`) absolute paths and overwrites them with `[REDACTED_PATH]`.
+- **Key Scrubbing**: It scans for 12-word seed phrases or 88-character Base58 strings that resemble private keys and masks them, ensuring the AI never accidentally reads the developer's wallet secret into its context window.
+
+### 3.2 Zod Strictness & Cryptographic Bounds
+LLMs frequently hallucinate string parameters where integers are required. Because `TFHE-rs` operates on strict byte widths, it will panic and abort the process if fed a non-standard byte width (e.g., a float or a negative number). 
+
+The MCP Server uses strict `zod` schemas to enforce `Uint32` boundaries. If Claude attempts to call `fhe_encrypt(1.5)` or injects a path traversal payload like `fhe_encrypt("../../")`, the Zod layer intercepts the call *before* it hits the Rust binary. It immediately returns a JSON-RPC `-32602` Invalid Params error, forcing the AI to self-correct its logic.
+
+### 3.3 Buffer Capping & DoS Prevention
+The `stdout` buffer from the FHE binary is capped at exactly 512KB. If an AI hallucinates an infinite loop or triggers a command that dumps massive amounts of data, the subprocess is forcefully terminated via `SIGKILL` after 60 seconds to prevent host memory exhaustion.
+
+### 3.4 Read-Only Sandbox Override
+If you are running a public hackathon or do not want the AI to spend Devnet SOL, you can hard-lock the network layer. Set `FHESTATE_MCP_READ_ONLY=1` in the `env` block of your MCP configuration. The AI will still be able to execute heavy FHE math locally, but the `devnet_submit_memo` tool will immediately throw an `Unauthorized` error.
+
+---
+
+## 🌊 4. The Confidential Execution Flow (Memo Anchoring)
+
+The core functional purpose of the MCP Server is to allow AI agents to securely execute FHE commitments and anchor them to the Solana blockchain. 
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant AI Agent
+    participant Node Coprocessor
+    participant Solana Devnet
+
+    note over User, Solana Devnet: Phase 1: Local FHE Encryption
+    User->>AI Agent: "Encrypt the value 150"
+    AI Agent->>Node Coprocessor: fhe_encrypt(150)
+    Node Coprocessor->>Node Coprocessor: Load client_key.bin
+    Node Coprocessor->>Node Coprocessor: Generate 15MB Ciphertext
+    Node Coprocessor-->>AI Agent: Return SHA-256 Hash
+    
+    note over User, Solana Devnet: Phase 2: On-Chain Anchoring
+    AI Agent->>Solana Devnet: devnet_submit_memo(Hash)
+    Solana Devnet-->>AI Agent: Return Signature & Solscan Link
+    AI Agent-->>User: "Success. Your data is encrypted and anchored."
+```
+
+### 4.1 Local Encryption Phase
+The AI Agent utilizes the `fhe_encrypt` tool to encrypt the data locally. The plaintext value never leaves the host machine. Because the generated ciphertext is massive, the Rust node stores it securely in the `.fhe_keys/` directory and returns only the 32-byte cryptographic hash to the AI.
+
+### 4.2 On-Chain Anchoring Phase
+The AI Agent automatically calls the `devnet_submit_memo` tool with the resulting hash. The MCP server utilizes `@solana/web3.js` to construct an SPL Memo transaction (formatted exactly as `local://<hash>`). The server signs the transaction using the developer's keypair specified in `FHESTATE_WALLET_PATH`, and broadcasts it to the Solana Devnet, returning the finalized signature to the AI.
+
+---
+
+## 🤖 5. Use Case: Autonomous Agent Workflows
+
+How does an AI actually use this MCP server in a real-world scenario? 
+
+To ensure that the LLM cannot hallucinate steps or skip cryptographic verifications, the MCP server enforces an internal `blind-step` hash chain. The server's registry defines **3 distinct AI agents** (Sentinel, Auditor, Coordinator) that can be combined into different confidential workflows (missions).
+
+The MCP Server is pre-configured with **3 execution workflows** (demo scripts) that show how these agents interact:
+
+### Workflow 1: The Fast Path (Sentinel Only)
+**"Sentinel Secret Vote"**
+This is the fastest workflow. A single Sentinel agent takes a user's binary vote (1 or 0), encrypts it locally via `fhe_encrypt`, and advances the hash chain. No other agents are required.
+
+### Workflow 2: The Compliance Path (Sentinel → Auditor)
+**"Sentinel → Auditor Compliance Scan → Auditor Seal Record"**
+1. **Sentinel**: Encrypts the user's intent and establishes the `stepHash`.
+2. **Auditor**: Receives the `stepHash` from the Sentinel, runs a zero-knowledge compliance scan against the encrypted data, and permanently seals the record if the policy passes.
+
+### Workflow 3: The Routing Path (Sentinel → Coordinator)
+**"Sentinel Market Signal → Coordinator Route Intent"**
+1. **Sentinel**: Encrypts a quantitative market signal (e.g., a blind trade intent) and passes the hash forward.
+2. **Coordinator**: Takes the verified signal hash and routes the intent to a specific execution channel on-chain using `devnet_submit_memo`.
+
+---
+
+## 🛠️ 6. The Comprehensive Tool Matrix
+
+The MCP Server exposes exactly **13 highly restricted JSON-RPC tools**. If a tool is not on this list, the AI cannot execute it. Every tool is strictly typed using Zod.
+
+### 6.1 FHE Cryptography Tools (Compute-Heavy)
+
+#### 1. `fhe_encrypt`
+- **Description**: The core cryptographic engine. Takes a plaintext `Uint32` integer from the LLM, pipes it to the local Rust `fhe-cli`, and generates a massive (15MB+) `TFHE-rs` ciphertext. To protect the LLM context window, it only returns the `SHA-256` commitment hash.
+- **Risk Profile**: Moderate (High CPU Usage).
+- **Zod Schema**: 
+  ```typescript
+  z.object({
+    value: z.number().int().min(0).max(4294967295)
+  }).strict()
+  ```
+
+#### 2. `agent_run_blind_step`
+- **Description**: Advances the agent memory chain. Takes an `agentId` (Sentinel/Auditor) and a `missionId`, and computes the next link in the local `stepHash` chain. 
+- **Risk Profile**: Low.
+- **Zod Schema**: 
+  ```typescript
+  z.object({
+    agentId: z.string(),
+    missionId: z.string(),
+    value: z.number().int().min(0).max(4294967295)
+  }).strict()
+  ```
+
+#### 3. `fhe_cli_run`
+- **Description**: A highly restricted sandbox allowing the AI to execute specific diagnostic commands on the `fhe-cli` binary.
+- **Risk Profile**: Moderate.
+- **Zod Schema**: 
+  ```typescript
+  z.object({
+    subcommand: z.string(),
+    args: z.array(z.string()).max(10)
+  }).strict()
+  ```
+  *(Note: Only subcommands `['doctor', 'history', 'balance']` are allowlisted. Path traversal `../` is explicitly blocked).*
+
+#### 4. `simulate_homomorphic_eval`
+- **Description**: Simulates the Auditor homomorphic logic over an encrypted payload, returning a deterministic boolean pseudo-hash. Bridges the gap between the theoretical Auditor functionality and the current CLI capabilities.
+- **Risk Profile**: Low.
+- **Zod Schema**: 
+  ```typescript
+  z.object({
+    logicGate: z.string(),
+    inputHash: z.string().min(64)
+  }).strict()
+  ```
+
+### 6.2 Solana Network Tools (State Modifying)
+
+#### 5. `devnet_wallet_status`
+- **Description**: Pings the `FHESTATE_RPC` and checks the exact SOL lamport balance of the keypair specified in `FHESTATE_WALLET_PATH`.
+- **Risk Profile**: Low (Read-Only RPC call).
+- **Zod Schema**: `z.object({}).strict()`
+
+#### 6. `devnet_history`
+- **Description**: Fetches the 5 most recent transaction signatures associated with the local developer wallet, allowing the AI to verify if its previous transactions successfully landed on-chain.
+- **Risk Profile**: Low (Read-Only RPC call).
+- **Zod Schema**: `z.object({}).strict()`
+
+#### 7. `devnet_submit_memo`
+- **Description**: **[CRITICAL]** This tool modifies blockchain state and spends funds. It constructs, signs, and broadcasts a live transaction to the Solana Devnet. It wraps the `SHA-256` ciphertext hash generated by `fhe_encrypt` in an SPL Memo (`local://<hash>`), anchoring the FHE commitment on-chain.
+- **Risk Profile**: Extreme. Spends Devnet SOL. Automatically disabled if `FHESTATE_MCP_READ_ONLY=1` is set.
+- **Zod Schema**:
+  ```typescript
+  z.object({
+    value: z.number().int().min(0).max(4294967295)
+  }).strict()
+  ```
+
+#### 8. `solscan_link`
+- **Description**: A static formatting tool. Takes a raw Solana Base58 signature and constructs a valid `https://solscan.io` URL bound strictly to the Devnet cluster.
+- **Risk Profile**: None (Static String Generation).
+- **Zod Schema**:
+  ```typescript
+  z.object({
+    signature: z.string().min(80).max(90)
+  }).strict()
+  ```
+
+### 6.3 Knowledge & Verification Tools (Zero Risk)
+
+#### 9. `list_agents_and_missions`
+- **Description**: Returns the full JSON registry of all available confidential AI agents (Sentinel, Auditor, Coordinator) and their specific allowed mission IDs. Used to ground the AI before it executes a workflow.
+- **Zod Schema**: `z.object({}).strict()`
+
+#### 10. `execution_protocol_script`
+- **Description**: Returns the exact step-by-step presentation script used for walking a developer through the Sentinel Secret Vote workflow. Ensures the AI uses canonical phrasing during live integrations.
+- **Zod Schema**: `z.object({}).strict()`
+
+#### 11. `architectural_proof_checklist`
+- **Description**: Returns the pre-flight checklist required to successfully deploy the FHESTATE system in a live environment, ensuring all devnet wallets, rust binaries, and environment variables are positioned correctly.
+- **Zod Schema**: `z.object({}).strict()`
+
+#### 12. `get_mcp_config_state`
+- **Description**: Safely reads the server's local environment configuration. Returns redacted visibility into the operational state.
+- **Zod Schema**: `z.object({}).strict()`
+
+#### 13. `verify_ciphertext_hash`
+- **Description**: Zero-Trust format verification of an intent hash before anchoring to Devnet. Mathematically validates the SHA-256 entropy.
+- **Zod Schema**: 
+  ```typescript
+  z.object({
+    hash: z.string().min(64)
+  }).strict()
+  ```
+
+---
+
+## 🚀 7. Quick Start & IDE Integration
+
+Because this MCP server interfaces with a local Rust binary, setup requires compiling the Coprocessor first.
+
+### Step 1: Compile the Rust Coprocessor
+You must have Rust `1.70+` installed. 
+```bash
+git clone https://github.com/fhestate/fhestate-rs.git
+cd fhestate-rs
+cargo build --release -p fhe-cli
+```
+*Note the absolute path to the generated binary: `.../fhestate-rs/target/release/fhe-cli`.*
+
+### Step 2: Build the MCP Server
+```bash
+cd mcp/fhestate-mcp
+npm install
+npm run build
+```
+
+### Step 3: Configure the Solana Wallet
+Generate a new Devnet keypair. **DO NOT USE A MAINNET WALLET.**
+```bash
+solana-keygen new --outfile devnet-wallet.json --no-bip39-passphrase
+solana airdrop 2 -k devnet-wallet.json --url devnet
+```
+*Note the absolute path to this JSON file.*
+
+### Step 3: Configure Cursor IDE or Claude Desktop
+
+Open your MCP configuration file:
+- **Cursor IDE**: `Settings > Features > MCP > Add New`
+- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
+
+Add the following configuration, replacing the absolute paths with your actual system paths:
+
+```json
+{
+  "mcpServers": {
+    "fhestate-coprocessor": {
+      "command": "node",
+      "args": ["/ABSOLUTE/PATH/TO/fhestate/mcp/fhestate-mcp/dist/index.js"],
+      "env": {
+        "FHESTATE_CLI_PATH": "/ABSOLUTE/PATH/TO/fhestate-rs/target/release/fhe-cli",
+        "FHESTATE_WALLET_PATH": "/ABSOLUTE/PATH/TO/devnet-wallet.json",
+        "FHESTATE_RPC": "https://api.devnet.solana.com",
+        "FHESTATE_MCP_READ_ONLY": "0"
+      }
+    }
+  }
+}
+```
+
+Restart your IDE or Claude Desktop. You should now see the 13 tools available in the agent's context window. Type `"Check my devnet wallet balance"` to initiate the handshake.
+
+---
+
+## 💻 8. LLM Execution Example (JSON-RPC Lifecycle)
+
+This is how an AI Agent (like Claude) actually communicates with the MCP Server under the hood to execute a confidential operation. The AI constructs a JSON-RPC payload:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req_1a2b3c",
+  "method": "tools/call",
+  "params": {
+    "name": "fhe_encrypt",
+    "arguments": {
+      "value": 50
+    }
+  }
+}
+```
+
+The MCP Server intercepts this, enforces the Zod `Uint32` boundary, pipes the `50` to the Rust Coprocessor, and returns the redacted hash commitment back to the AI's context window:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "req_1a2b3c",
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "Ciphertext generated. Local Hash: 8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 🛑 9. Troubleshooting & IPC Error Codes
+
+When interacting with the MCP server over standard input/output (stdio), you may encounter specific JSON-RPC error codes resulting from the IPC Bridge.
+
+| JSON-RPC Code | HTTP Equivalent | Trigger Scenario | Resolution |
+|---------------|-----------------|------------------|------------|
+| `-32602` | `400 Bad Request` | Zod Validation Failure. AI hallucinated a string instead of a `Uint32` or tried to use path traversal `../`. | Inform the AI of the Zod constraints. It will automatically correct its payload. |
+| `-32603` | `500 Internal Error` | CLI Binary `ENOENT`. The Node server cannot find the `fhe-cli` binary. | Verify `FHESTATE_CLI_PATH` in your MCP Config is absolute and the binary was compiled. |
+| `-32000` | `504 Gateway Timeout`| Coprocessor Timeout. The FHE math took longer than 60s. | You likely ran `cargo build` instead of `cargo build --release`. FHE math requires release optimizations. |
+| `-32001` | `401 Unauthorized` | Read-Only Sandbox active. AI tried to call `devnet_submit_memo`. | Set `FHESTATE_MCP_READ_ONLY=0` if you intend to spend Devnet SOL. |
+| `-32002` | `502 Bad Gateway` | Solana Web3 Connection Error. Devnet RPC dropped the packet. | Switch `FHESTATE_RPC` to a premium provider like Helius or Alchemy. |
+
+---
+
+## 📞 10. Contact & Support
+
+- **Documentation**: [Comprehensive Technical Specs](https://docs.fhestate.org)
+- **GitHub Issues**: [Report bugs or request features](https://github.com/fhestate/fhestate-mcp/issues)
+- **Discussions**: [Join community discussions](https://github.com/fhestate/fhestate-mcp/discussions)
+- **Twitter**: [@fhe_state](https://twitter.com/fhe_state)
+
+---
+
+<div align="center">
+Copyright © 2026 FHESTATE Protocol. All rights reserved. <br>
+<i>Private Intelligence. Public Settlement.</i>
+</div>

package/SECURITY.md

@@ -0,0 +1,158 @@
+# 🛡️ SECURITY MODELING: @fhestate/mcp-server
+
+**Document Version:** 1.0.0
+**Target Infrastructure:** Solana Devnet & TFHE-rs Coprocessor
+**Compliance Standard:** FHESTATE Enterprise Security Guidelines
+
+---
+
+## 1. Executive Security Posture
+
+The `@fhestate/mcp-server` is explicitly designed as a zero-trust execution bridge between non-deterministic Large Language Models (LLMs) and deterministic cryptographic processors (FHE/TFHE). Because this Node.js process sits directly on a host machine with access to a filesystem, shell binaries, and Solana private keys, the security posture must assume that the connected AI Agent is **actively hostile or deeply hallucinating**.
+
+This document outlines the strict cryptographic, systemic, and network-level security guarantees enforced by the server, as well as the known vulnerabilities, risk boundaries, and incident response protocols required for enterprise deployment.
+
+---
+
+## 2. The AI Threat Model
+
+Advanced LLMs (such as Claude 3.5 Sonnet or OpenAI models) are highly capable but mathematically unpredictable. When granting an AI access to a local Model Context Protocol (MCP) server, operators face three primary threat vectors:
+
+### 2.1 Prompt Injection to Shell Execution (RCE)
+If an attacker feeds a malicious prompt to the LLM (e.g., via an untrusted file loaded in the IDE), the AI may attempt to execute arbitrary shell commands. 
+*   **Mitigation**: The MCP Server completely disables raw shell access. The `fhe_cli_run` and `fhe_encrypt` tools spawn the Rust `fhe-cli` binary using `child_process.spawn` with `shell: false`. Furthermore, command arguments are strictly allowlisted. The AI cannot pipe (`|`), chain (`&&`), or inject bash commands.
+
+### 2.2 Host System Path Traversal
+An AI might attempt to read sensitive files outside the FHESTATE workspace (e.g., `~/.ssh/id_rsa` or `~/.config/solana/id.json`).
+*   **Mitigation**: Any argument passed to the CLI bridge that contains `../` or relative traversal operators is aggressively intercepted by the MCP Node server and blocked with a `-32602` JSON-RPC error.
+
+### 2.3 Cryptographic Memory Exhaustion (DoS)
+FHE operations (specifically Zama's TFHE-rs) are computationally massive. Generating a single ciphertext can consume hundreds of megabytes of RAM and heavy CPU cycles. If an AI hallucinates a loop, it could trigger a Denial of Service (DoS) on the host machine.
+*   **Mitigation**: The MCP Server enforces a strict `timeout` of 60 seconds on all subprocesses. Additionally, the `stdout` and `stderr` buffers are capped at exactly 512KB. If the FHE coprocessor exceeds these limits, the Node process sends a `SIGKILL` to forcefully terminate the Rust worker, returning a `-32603` timeout error to the AI.
+
+---
+
+## 3. Strict Zod Boundary Enforcement
+
+Every single JSON-RPC request originating from the LLM must pass through a strict `zod` schema validation layer before interacting with the Node runtime or the Rust coprocessor.
+
+### 3.1 The Uint32 Cryptographic Boundary
+TFHE-rs operates on highly specific integer types. Passing a floating-point number or a negative integer into the CLI will cause a Rust panic.
+*   **Zod Enforcement**: 
+    ```typescript
+    value: z.number().int().min(0).max(4294967295)
+    ```
+    This schema guarantees that the AI can only pass valid `u32` integers into the `fhe_encrypt` and `agent_run_blind_step` tools. If the AI attempts to pass a string or a float, the MCP server rejects it immediately and feeds the Zod type error back to the AI for self-correction.
+
+### 3.2 Enum Sandboxing for Agent Workflows
+The confidential agents are bounded by specific logical states. The AI cannot invent new agents or mission types.
+*   **Zod Enforcement**:
+    ```typescript
+    agentId: z.enum(["sentinel", "auditor", "coordinator"])
+    ```
+    This prevents the AI from hallucinating unauthorized operators or injecting SQL-like syntax into the local hash-chain memory.
+
+---
+
+## 4. The Redaction Engine (`redact.ts`)
+
+LLMs are highly context-sensitive. If an internal tool returns an absolute file path (e.g., `C:\Users\Admin\Documents\wallet.json`), the LLM will store that path in its active context window. This creates a high risk of leaking host-system topology to cloud-based LLM providers.
+
+To solve this, the FHESTATE MCP Server employs an aggressive redaction layer on all outgoing JSON-RPC packets.
+
+### 4.1 Automated Path Scrubbing
+The `redact.ts` module intercepts all strings returning to the AI. It uses regular expressions to identify absolute system paths (both Unix `/` and Windows `C:\` styles) and aggressively overwrites them with safe placeholder tokens.
+*   *Raw CLI Output*: `"Saved ciphertext to /Users/dev/.fhe_keys/client_key.bin"`
+*   *Redacted AI Output*: `"Saved ciphertext to [REDACTED_PATH]/client_key.bin"`
+
+### 4.2 Seed Phrase and Private Key Isolation
+While the MCP server does not expose tools to read raw private keys, the redaction engine acts as a fail-safe. Any output matching the structure of a BIP39 12-word mnemonic or a Base58 Solana private key array is forcefully scrubbed.
+
+---
+
+## 5. Wallet Management & On-Chain Risk
+
+The MCP Server interacts with the Solana blockchain via the `@solana/web3.js` library, specifically through the `devnet_submit_memo` tool. This tool requires access to a local Keypair to sign and pay for transactions.
+
+### 5.1 Devnet Scope ONLY
+**WARNING**: This repository and its accompanying tools are explicitly audited for the **Solana Devnet** only. 
+*   You must never place a Mainnet wallet containing real financial value (SOL, USDC) into the path resolved by `FHESTATE_WALLET_PATH`.
+*   The transaction construction logic does not currently utilize Mainnet priority fees or advanced MEV-protection logic.
+
+### 5.2 The Read-Only Sandbox (`FHESTATE_MCP_READ_ONLY`)
+For environments where the host machine is shared or the operator does not wish to allow the AI to mutate blockchain state, operators must configure the environment variable:
+`FHESTATE_MCP_READ_ONLY=1`
+
+When this flag is active:
+1. The `devnet_submit_memo` tool is artificially disabled.
+2. If the AI attempts to call it, the server intercepts the request before touching the Solana RPC and returns an error: `Network mutations are disabled. FHESTATE_MCP_READ_ONLY is active.`
+3. The AI can still perform local FHE mathematics (`fhe_encrypt`), but it cannot spend Devnet SOL.
+
+---
+
+## 6. The Coprocessor Handshake (`fhe-cli`)
+
+The security of the MCP Server relies entirely on the integrity of the `fhe-cli` binary. 
+
+### 6.1 Binary Sourcing
+The MCP Server assumes that the `fhe-cli` binary was compiled locally by the operator from the official `fhestate-rs` repository. 
+*   **Do not download pre-compiled `fhe-cli` binaries from untrusted sources.** A malicious binary could intercept the FHE payload and exfiltrate it before encryption.
+*   **Path Resolution**: The server attempts to find the binary via the `FHESTATE_CLI_PATH` environment variable. If omitted, it attempts to resolve the binary relative to the repository root. Ensure your file permissions prevent unauthorized modification of the target release folder.
+
+### 6.2 Key Material Isolation
+The `fhe-cli` generates its evaluation and client keys inside the `.fhe_keys/` hidden directory. 
+*   The MCP Server does **not** expose any JSON-RPC tools capable of reading these files. 
+*   The AI Agent never possesses the `client_key.bin` and therefore cannot mathematically decrypt the ciphertexts it requests. It operates strictly in a "blind" capacity.
+
+---
+
+## 7. Incident Response Matrix
+
+If an operator suspects that the MCP server or the connected AI Agent has behaved maliciously, follow this response matrix:
+
+| Severity Level | Indicator of Compromise (IoC) | Immediate Action | Secondary Action |
+|---|---|---|---|
+| **CRITICAL** | Devnet SOL is draining rapidly from the configured wallet without user prompt. | 1. Terminate the Node.js MCP Process immediately.<br>2. Disconnect the IDE/Claude Desktop. | Revoke the Devnet wallet. Audit the `server.ts` file for unauthorized modifications. |
+| **HIGH** | The `fhe-cli` process is consuming 100% CPU for more than 5 minutes. | 1. Run `killall fhe-cli` (Unix) or End Process in Task Manager (Windows). | Check the LLM context window to see if it hallucinated an infinite loop of `fhe_encrypt` calls. |
+| **MEDIUM** | Redaction failure: Absolute system paths are visible in the AI chat window. | 1. Clear the chat context window immediately to prevent the LLM from caching the paths. | Submit a bug report to the repository detailing the regex failure in `redact.ts`. |
+| **LOW** | The AI repeatedly fails to execute `fhe_cli_run` due to Zod validation errors. | 1. No action required. The system is operating as designed. | Guide the AI with better prompting regarding Uint32 limits. |
+
+---
+
+## 8. Vulnerability Disclosure Policy
+
+FHESTATE takes the security of our cryptography and integration pipelines seriously. If you discover a vulnerability in the `@fhestate/mcp-server` that allows for Remote Code Execution (RCE), Mainnet financial loss, or cryptographic bypass, please follow our responsible disclosure protocol.
+
+### 8.1 Reporting Guidelines
+1. **Do not open a public GitHub issue.**
+2. Send an encrypted email to `security@fhestate.org` detailing the exact exploit path, the MCP version, and a minimal reproducible example (MRE).
+3. Wait for acknowledgment from the core engineering team within 48 hours.
+
+### 8.2 Out of Scope Vulnerabilities
+The following scenarios are considered out of scope for security bounties:
+*   Social engineering of the AI Agent (e.g., convincing the AI to write a bad tweet).
+*   Denial of Service (DoS) caused by intentionally setting the `timeout` parameter in `cli-bridge.ts` to `0`.
+*   Loss of Devnet SOL due to intentional abuse of the `devnet_submit_memo` tool.
+
+---
+
+## 9. Architectural Integrity & Continuous Integration
+
+To maintain the security posture described in this document, the `fhestate-mcp` repository enforces strict CI/CD pipelines.
+
+### 9.1 The Smoke Test Suite
+Before any code is merged into the `main` branch, it must pass the `smoke-list-tools.mjs` test. This test programmatically spawns the MCP server and executes a mock JSON-RPC handshake, verifying that exactly 10 zero-trust tools are registered and that the `zod` schemas are intact.
+
+### 9.2 Dependency Auditing
+The server relies on highly vetted dependencies:
+*   `@modelcontextprotocol/sdk`: The official standard for AI tool execution.
+*   `zod`: The industry standard for runtime type validation.
+*   `@solana/web3.js`: The official Solana foundation library.
+
+The `package.json` explicitly pins these dependencies. Operators should run `npm audit` frequently to ensure no transitive dependencies have introduced supply-chain vulnerabilities.
+
+---
+
+## 10. Disclaimer
+
+This software is provided "as is", without warranty of any kind, express or implied. By operating the `@fhestate/mcp-server`, you acknowledge that bridging non-deterministic LLMs to local filesystems and cryptographic binaries inherently involves risk. You agree to run this server in a sandboxed, Devnet-only capacity.