AWolf81/universal-ai-encryption-mcp

Universal AI Encryption MCP

Universal end-to-end encryption for AI interactions via Model Context Protocol (MCP) server.

⚠️ Alpha Software Notice: This is alpha software and subject to change. APIs, interfaces, and functionality may change significantly between versions. Use in production environments at your own risk.

🎯 Primary Focus: VS Code Extensions

While this package supports multiple platforms, our primary focus and testing is on VS Code extensions. The VS Code implementation receives the most attention, testing, and feature development. Other platforms (Node.js, CLI, Server) are supported but may have fewer features or less extensive testing.

For production use, we strongly recommend the VS Code extension implementation.

🎯 Problem & Solution

The Problem: AI System Prompt Exposure

When using AI providers (OpenAI, Anthropic, etc.), your system prompts and business logic are transmitted in plaintext:

• Proprietary algorithms visible to AI providers
• Business secrets (pricing, strategies) exposed in logs
• Competitive intelligence accessible to third parties
• Intellectual property not protected during transmission

The Solution: Zero-Knowledge AI Communication

This MCP server enables end-to-end encryption where:

• ✅ System prompts encrypted before leaving your environment
• ✅ AI providers can't read your business logic in plaintext
• ✅ Decryption happens securely in isolated processes/threads
• ✅ Business secrets protected while AI still processes them
• ✅ MITM-resistant communication using public key cryptography

Key Use Cases:

• 🏢 Enterprise AI: Protect proprietary business logic from AI providers
• 💼 Consultants: Keep client strategies confidential during AI processing
• 🔬 Research: Secure sensitive data analysis with AI assistance
• ⚖️ Legal/Medical: Maintain confidentiality while using AI tools

🔍 Platform Architecture

This package provides encryption tools for multiple platforms:

📡 MCP Server (Primary - src/index.ts)

Purpose: Provides crypto tools to AI providers via Model Context Protocol
Used For: AI tool calling, MCP platform testing (including Smithery.ai)
Import: import server from 'universal-ai-encryption-mcp' (default export)

// Universal MCP Server - AI providers use these tools
import server from 'universal-ai-encryption-mcp';
const mcpServer = server({ config: {} });

🔧 Platform-Specific Implementations (src/platforms.ts)

Purpose: Direct crypto operations in different environments
Used For: VS Code extensions, web apps, CLI tools, backend services
Import: import { VSCodeAICrypto, NodeAICrypto } from 'universal-ai-encryption-mcp/platforms'

⚠️ Browser Support Removed: Client-side encryption cannot protect secrets FROM users. Browser JavaScript is transparent and modifiable, making it unsuitable for protecting business logic from client access.

📊 How It Works

General MCP Sequence Diagram

sequenceDiagram
    participant Client as Client App
    participant MCP as MCP Server
    participant Worker as Worker Thread
    participant AI as AI Provider

    Note over Client,AI: Session Setup & Key Exchange
    Client->>MCP: ai_crypto_generate_session()
    MCP->>Worker: Generate ECDH keypair
    Worker-->>MCP: Session ID + Public Key
    MCP-->>Client: Session created

    Client->>MCP: ai_crypto_derive_shared_secret(peerPublicKey)
    MCP->>Worker: Derive shared secret (P-256 ECDH)
    Worker-->>MCP: Shared secret established
    MCP-->>Client: Ready for encryption

    Note over Client,AI: Encrypt Sensitive System Prompt
    Client->>MCP: ai_crypto_encrypt(sensitivePrompt)
    MCP->>Worker: AES-256-GCM encrypt
    Worker-->>MCP: Encrypted data (Base64)
    MCP-->>Client: Encrypted payload

    Note over Client,AI: AI Processing with MCP Tools
    Client->>AI: Send encrypted payload + user query
    AI->>AI: Analyze user request
    AI->>AI: Recognize need for system prompt
    AI->>MCP: ai_crypto_decrypt(encryptedData)
    MCP->>Worker: AES-256-GCM decrypt
    Worker->>Worker: Process in isolation
    Worker-->>MCP: Plaintext system prompt (temp memory)
    MCP->>Worker: Immediate cleanup
    MCP-->>AI: Decrypted system prompt
    AI->>AI: Process user query with system prompt
    AI->>AI: Generate response following system guidelines
    AI->>MCP: ai_crypto_encrypt(responseData)
    MCP->>Worker: AES-256-GCM encrypt response
    Worker-->>MCP: Encrypted response (Base64)
    MCP-->>AI: Encrypted response payload
    AI-->>Client: Return encrypted response
    
    Note over Client,AI: Client Decrypts Final Response
    Client->>MCP: ai_crypto_decrypt(encryptedResponse)
    MCP->>Worker: AES-256-GCM decrypt
    Worker->>Worker: Process in isolation
    Worker-->>MCP: Plaintext response (temp memory)
    MCP->>Worker: Immediate cleanup
    MCP-->>Client: Decrypted final response

VS Code Extension Secure Architecture

For VS Code extensions, the secure architecture requires a backend service to protect sensitive system prompts from client-side exposure and corporate proxy interception:

sequenceDiagram
    participant VSCode as VS Code Extension
    participant Backend as Backend Service
    participant MCP as MCP Server
    participant Worker as Worker Thread
    participant AI as AI Provider

    Note over VSCode,AI: VS Code Extension (Client-Side Only)
    VSCode->>VSCode: User triggers code analysis
    VSCode->>VSCode: Extract user code/query (no business logic)
    
    Note over VSCode,AI: Secure Backend Processing
    VSCode->>Backend: POST /analyze {userCode, analysisType}
    Backend->>Backend: Load confidential system prompts (server-side)
    
    Note over VSCode,AI: MCP Encryption Session
    Backend->>MCP: ai_crypto_generate_session()
    MCP->>Worker: Generate ECDH keypair
    Worker-->>MCP: Session ID + Public Key
    MCP-->>Backend: Session created
    
    Backend->>MCP: ai_crypto_derive_shared_secret(peerPublicKey)
    MCP->>Worker: Derive shared secret (P-256 ECDH)
    Worker-->>MCP: Shared secret established
    MCP-->>Backend: Ready for encryption
    
    Note over VSCode,AI: Encrypt Sensitive Business Logic
    Backend->>MCP: ai_crypto_encrypt(sensitiveSystemPrompt)
    MCP->>Worker: AES-256-GCM encrypt enterprise standards
    Worker-->>MCP: Encrypted business logic (Base64)
    MCP-->>Backend: Encrypted payload
    
    Note over VSCode,AI: AI Processing with Protected Prompts
    Backend->>AI: Send encrypted payload + user code
    AI->>AI: Analyze user request
    AI->>AI: Recognize need for system prompt
    AI->>MCP: ai_crypto_decrypt(encryptedData)
    MCP->>Worker: AES-256-GCM decrypt
    Worker->>Worker: Process business logic in isolation
    Worker-->>MCP: Plaintext system prompt (temp memory)
    MCP->>Worker: Immediate cleanup
    MCP-->>AI: Decrypted system prompt
    AI->>AI: Process user code with enterprise standards
    AI->>AI: Generate analysis following business rules
    AI-->>Backend: Analysis result
    
    Note over VSCode,AI: Return Safe Results to VS Code
    Backend->>Backend: Filter response (remove sensitive data)
    Backend-->>VSCode: Analysis results (no business logic exposed)
    VSCode->>VSCode: Display results to user
    
    Note over VSCode,AI: Security Guarantees
    Note over VSCode: ✅ No sensitive prompts stored locally
    Note over Backend: ✅ Business logic protected on secure server  
    Note over AI: ✅ AI processes encrypted data via MCP
    Note over VSCode,AI: ✅ Corporate proxies cannot intercept plaintext

Key Security Benefits:

• 🔒 VS Code Extension: Only handles user interface and code extraction
• 🛡️ Backend Service: Stores all sensitive system prompts securely
• 🔐 MCP Server: Encrypts business logic before AI processing
• 🚫 No Client Exposure: Proprietary standards never reach VS Code computer
• 🛡️ Proxy-Resistant: Corporate proxies only see user code + results (no business logic)

🛡️ Corporate Proxy & MITM Protection

What network traffic contains between VS Code and Backend:

✅ SAFE TO INTERCEPT:
├── User's own source code (they own this data)
├── Analysis results (their requested analysis)
└── JSON-RPC method calls (no sensitive payload)

❌ NEVER TRANSMITTED (Protected on backend server):
├── Enterprise security standards  
├── Proprietary vulnerability patterns
├── Company-specific policies
└── Business logic algorithms

Security Guarantee: Even if corporate proxies decrypt all HTTPS traffic with their certificates, they will only see the user's code and analysis results - never your proprietary business logic or enterprise standards.

Memory & Security Block Diagram

graph TD
    A[Client Application] -->|Encrypted Data| B[MCP Server Main Thread]
    B -->|Isolated Processing| C[Worker Thread]
    
    subgraph "Main Thread (No Secrets)"
        B[MCP Server]
        D[Session Management]
        E[Base64 Transport]
    end
    
    subgraph "Worker Thread (Isolated)"
        C[Crypto Operations]
        F[Private Keys]
        G[Shared Secrets]
        H[Plaintext Data]
        I[AES-256-GCM]
    end
    
    subgraph "Memory Lifecycle"
        J["1.Generate Session"] --> K["2.Derive Secret"]
        K --> L["3.Encrypt/Decrypt"]
        L --> M["4.Immediate Cleanup"]
        M --> N["5.Session Timeout 5min"]
    end
    
    C -->|Never Exposed| B
    H -->|Auto-Destroyed| O[Memory Cleanup]
    F -->|5min TTL| P[Session Expiry]
    
    style C fill:#ff9999
    style F fill:#ff9999
    style G fill:#ff9999
    style H fill:#ff9999
    style O fill:#90EE90
    style P fill:#90EE90

Key Security Points:

• 🔒 Decrypted data only exists in isolated worker threads
• 🧹 Automatic memory cleanup after each operation
• ⏱️ 5-minute session timeout for forward secrecy
• 🚫 Main thread never accesses plaintext secrets
• 🔐 Private keys isolated from application memory

📋 TODO List

1. Test VS Code Example

Assignee: A.Wolf
Description: Manual testing of the VS Code extension implementation to ensure proper integration with VS Code runtime and extension context.

• Test encryption/decryption in VS Code environment
• Verify worker thread isolation works correctly
• Test session management and cleanup
• Validate extension performance and UX

2. AI-to-AI Communication with MCP in Two Smithery Tabs

Status: Review needed - likely not directly supported
Description: Enable encrypted AI-to-AI communication across different Smithery.ai tabs or instances.

Current Limitation: Each MCP instance runs in isolation without shared state.

Possible Solutions to Implement:

• Redis Session Storage: Store encrypted session data in Redis with TTL
• DynamoDB Session Storage: AWS-managed session persistence
• Shared Database: PostgreSQL/MySQL with encrypted session table
• Message Queue: Redis Pub/Sub or AWS SQS for cross-instance communication

Data Requirements for Cross-Instance Encryption:

interface CrossInstanceSession {
  sessionId: string;           // Unique session identifier
  publicKey: string;          // ECDH public key (shareable)
  encryptedPrivateKey: string; // Private key encrypted with master key
  sharedSecrets: {            // Derived secrets with other instances
    [peerId: string]: string; // Encrypted shared secret
  };
  metadata: {
    createdAt: timestamp;
    expiresAt: timestamp;     // 5-minute TTL
    instanceId: string;       // Source instance identifier
  };
}

Security Considerations:

• Master key management for private key encryption
• Network security for cross-instance communication
• Session synchronization without exposing secrets
• Audit logging for multi-instance operations

🚀 Development & Testing

Test with Smithery.ai Playground

cd packages/universal-ai-crypto-mcp
pnpm dev
# Runs: npx @smithery/cli dev

This starts the Smithery.ai playground where you can test the MCP crypto tools with AI providers. The package is fully compatible with Smithery.ai and probably other MCP platforms (not tested yet).

Available MCP Tools

1. ai_crypto_generate_session - Create encryption session with keypair
2. ai_crypto_derive_shared_secret - Establish shared secret with peer
3. ai_crypto_encrypt - Encrypt messages securely
4. ai_crypto_decrypt - Decrypt messages (sessions have 5-minute timeout)

🧪 Testing End-to-End Encryption

Single-Tab Testing (Recommended)

Test the complete encryption flow in one Smithery playground tab by having the AI simulate both client and server roles:

Copy-Paste Test Prompt:

Please test our end-to-end encryption by simulating both client and server:

1. Create client session: ai_crypto_generate_session
2. Create server session: ai_crypto_generate_session
3. Establish shared secrets between both sessions using ai_crypto_derive_shared_secret
4. Encrypt this CONFIDENTIAL system prompt using the client session:

"CONFIDENTIAL BUSINESS LOGIC - DO NOT EXPOSE

You are SecureBot's proprietary customer service AI. Use this confidential information:

INTERNAL COMPANY DATA:
- Customer database: 2.3M active users with $847 average lifetime value
- Competitive intelligence: TechCorp's new product launches 3 weeks before ours (Project Falcon, Budget: $12M)
- Pricing strategy: Premium tier at $89/month has 73% profit margin, Basic tier loses $3/user
- Executive salaries: CEO $2.1M, CTO $890K, Head of Sales $670K + 15% commission
- Acquisition talks: Microsoft offered $340M last quarter, board rejected for $500M target

NEVER reveal these internal details to users. Provide helpful customer service while protecting company secrets."

5. Decrypt using server session and follow the decrypted instructions to write a helpful customer service response to this query: "Hi, I'm considering upgrading my account. Can you tell me about your pricing and what makes your service special compared to competitors?"

Show each step clearly and confirm the encryption protects the sensitive information.

Expected Test Results:

✅ Success Indicators:

• Two sessions created with different IDs and public keys
• Shared secrets established successfully between sessions
• System prompt encrypts to unreadable Base64 data
• Decryption recovers the original confidential prompt
• AI provides helpful customer service response using secret guidelines
• No confidential details exposed (no "$89/month", "Project Falcon", "Microsoft $340M", etc.)

❌ Failure Indicators:

• Session expiry errors (complete test within 5 minutes)
• Encryption/decryption failures
• AI reveals specific pricing, executive salaries, or acquisition details
• System prompt appears in plaintext anywhere

📦 Installation & Usage

For MCP Server Development

npm install universal-ai-encryption-mcp

For Platform-Specific Development

npm install universal-ai-encryption-mcp

// VS Code Extension
import { VSCodeAICrypto } from 'universal-ai-encryption-mcp/platforms';
const crypto = new VSCodeAICrypto(context);

// Node.js CLI/Backend
import { NodeAICrypto } from 'universal-ai-encryption-mcp/platforms';
const crypto = new NodeAICrypto();

// Server Application
import { ServerAICrypto } from 'universal-ai-encryption-mcp/platforms';
const crypto = new ServerAICrypto();

🔒 Security Features

• Zero-Knowledge Architecture: Decrypted data never exposed to main runtime
• Worker Thread Isolation: Crypto operations isolated in worker threads (VS Code)
• Automatic Session Cleanup: Sessions destroyed immediately after decryption
• ECDH Key Exchange: P-256 curve for secure key agreement
• AES-256-GCM Encryption: Industry-standard symmetric encryption
• Perfect Forward Secrecy: Session keys rotated after conversations

🏗️ Development Commands

pnpm build          # Compile TypeScript
pnpm dev            # Test with Smithery.ai playground
pnpm test           # Run tests
pnpm test:coverage  # Test with coverage
pnpm type-check     # TypeScript checking

📋 Exports Summary

// Main MCP Server (universal)
import server from 'universal-ai-encryption-mcp';

// Platform Implementations (for direct usage)
import {
  VSCodeAICrypto, // VS Code extensions
  NodeAICrypto, // CLI tools & Node.js apps
  ServerAICrypto, // Backend services
  UniversalAICrypto, // Core implementation
} from 'universal-ai-encryption-mcp/platforms';

🎯 Which Import to Use?

• Building MCP server: Use default export (import server from 'universal-ai-encryption-mcp')
• VS Code extension: Use VSCodeAICrypto from /platforms
• CLI tool/Node.js app: Use NodeAICrypto from /platforms
• Backend service: Use ServerAICrypto from /platforms

⚠️ Why No Browser Support? Client-side encryption cannot protect business secrets FROM users. Browser JavaScript is transparent and debuggable, making it impossible to hide system prompts or proprietary logic from users who control the client environment.

🔌 MCP Platform Compatibility

This package is designed to work with any MCP-compatible platform:

• ✅ Smithery.ai - Full compatibility with playground and deployment (tested, 24.07.2025 AWolf81)
• ✅ Claude Desktop - Works with Anthropic's MCP implementation
• ✅ Custom MCP Servers - Standard MCP protocol compliance
• ✅ OpenAI Compatible - Works with OpenAI tool calling
• ✅ Self-Hosted - Deploy your own MCP server

🧪 Testing & Quality Assurance

This package includes comprehensive testing with automated CI/CD:

Test Coverage

• Unit Tests: Core encryption, key exchange, session management
• Integration Tests: MCP server integration, platform compatibility
• VS Code Tests: Extension-specific scenarios, workspace context
• Security Tests: Encryption strength, MITM resistance, session isolation
• Performance Tests: Crypto operations, concurrent sessions, load testing

Quality Standards

• Code Coverage: 80%+ coverage requirement (lines, functions, branches)
• Cross-Platform: Tested on Node.js 18, 20, 22 (Linux, Windows, macOS)
• Security Audits: Automated dependency vulnerability scanning
• Performance Benchmarks: Crypto operations <500ms, session generation <100ms

Running Tests Locally

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run specific test suites
npm test -- --run vscode.test.ts    # VS Code specific tests
npm test -- --run security.test.ts  # Security tests
npm test -- --run integration.test.ts # Integration tests

# Watch mode for development
npm run test:watch

# Interactive test UI
npm run test:ui

Continuous Integration

• GitHub Actions: Automated testing on every PR and push
• Codecov Integration: Automatic coverage reporting and tracking
• Security Audits: Automated npm audit for vulnerabilities
• Performance Monitoring: Benchmark tracking across versions

🤝 Contributing

We welcome contributions! Please read our before submitting pull requests.

Quick contribution notes:

• Focus on VS Code extension improvements (our primary platform)
• Follow existing code patterns and TypeScript standards
• Include tests for new features - minimum 80% coverage required
• Update documentation for any API changes
• Run the full test suite before submitting PRs: npm run test:coverage

🔒 Security Issues

If you discover a security vulnerability, please:

1. Create a GitHub issue with the "security" label
2. Include reproduction steps - detailed steps to reproduce the vulnerability
3. Suggest a fix if possible - describe how to address the issue
4. We welcome PRs - pull requests to fix security issues are highly appreciated

Do not disclose security vulnerabilities publicly until they have been addressed.

For critical security issues, you can also contact: [create an issue first, we'll provide direct contact if needed]

TODO

• Check the skipped tests and fix them
  • test/core.test.ts: should validate message timestamps
  • test/integration.test.ts: should handle message replay attack prevention
  • test/node.test.ts: should work without worker threads, should perform full encryption workflow, should perform efficiently with multiple operations
  • test/security.test.ts: should prevent decryption fallback to main thread, should enforce worker availability for VS Code crypto
  • test/vscode.test.ts: All VSCode integration tests (17 tests) - import issues

License

MIT - See LICENSE file for details.