WebCrypt v1.0.0

Zero-dependency cryptographic suite & native AI Agent Tooling (MCP) for modern JavaScript.

AES-256-GCM symmetric encryption, RSA-4096 hybrid asymmetric encryption, ECDH key agreement, digital signatures, JWE compact serialization (RFC 7516), post-quantum cryptography (Kyber/Dilithium), and native Model Context Protocol (MCP) tooling — built natively for browser, Node.js, edge runtimes, and autonomous AI coding agents.

Interactive Live Demo & Documentation

• 🚀 Try WebCrypt Live Playground: Test AES-256, RSA-4096, ECDH, digital signatures, and file encryption directly in your browser.
• 📖 Multi-IDE MCP Setup Guide: Step-by-step installation for Google Antigravity, Cursor, Claude Desktop, VS Code, Windsurf, Cline, and Zed.
• 📚 Documentation Index

What's New in v1.0.0

• 🤖 Native Model Context Protocol (MCP) Server: Zero-dependency stdio server (npx webcrypt mcp) empowering AI agents to encrypt sensitive artifacts, generate cryptographic proofs, and protect vault data.
• ⚡ Automated Project Scaffolding (webcrypt init): One-command initialization of agent skills, IDE MCP configs, and workspace instruction rules.
• 🌐 Global Multi-Project Management (webcrypt init-global / webcrypt doctor-global): Batch re-scaffolding and health diagnostics across all projects registered in ~/.webcrypt/projects.json.
• 📐 Deterministic Multi-Chunk Framing: Fixed 8MB plaintext chunking with 8MB + 16B ciphertext streaming framing for constant-memory multi-gigabyte file encryption.
• ⚛️ Self-Consistent Post-Quantum KEM: Kyber512/768/1024 and hybrid classical+PQC KEM round-trips.
• 🛡️ Centralized Web Crypto Resolution: Automatic seamless environment detection across browsers, Web Workers, Node.js 18+, Bun, and edge runtimes.
• 🌐 PuterVision Triple Memory Synergy: Seamless zero-friction encryption layer for state-memory-mcp (workflow state memory) and vision-memory-mcp (visual caching & grounding).

Installation & Quick Setup

1. Install as Library

npm install webcrypt

2. Auto-Initialize Project for AI Agents & IDEs

# Global installation (recommended for CLI)
npm install -g webcrypt

# Inside any project directory
webcrypt init

webcrypt init automatically creates .agents/skills/webcrypt-mcp/SKILL.md, .cursor/mcp.json, .vscode/mcp.json, and injects agent rules into AGENTS.md, .cursorrules, .windsurfrules, .gemini/instructions.md, and CLAUDE.md.

Why Use WebCrypt MCP? (Key Benefits for AI Agents)

AI coding agents (Antigravity, Cursor, Claude, Copilot, Windsurf, Cline) routinely handle confidential materials: API keys, database connection strings, architecture plans, and private conversation logs.

WebCrypt MCP equips your AI agents with an autonomous, zero-dependency cryptographic vault directly in their toolbelt:

• 🔐 Confidential Local Vaulting: Agents encrypt API keys, credentials, and sensitive state nodes (encrypt_payload) before saving them to disk, preventing plaintext leaks in prompt histories and git repositories.
• 🛡️ Cryptographic Provenance & Tamper-Proof Signing: Agents compute SHA-256/SHA-3 hashes (crypto_hash) and digital signatures (sign_verify) on code diffs, release binaries, and test evidence packs.
• 🤝 Secure Inter-Agent Communication: Subagents and peer agents generate ephemeral JWK keypairs (manage_keys) to establish encrypted channels over shared message buses.
• 🧠 Completes the PuterVision Triad:
  • state-memory-mcp: Workflow tracking, task DAGs, decisions, and blockers.
  • vision-memory-mcp: Visual UI state caching, screenshot layout trees, and element grounding.
  • webcrypt-mcp: Vault encryption, evidence signatures, and cryptographic integrity.
• ⚡ Zero Dependencies: 100% native Web Crypto API execution (globalThis.crypto.subtle) across Node.js 18+, Bun, browsers, and edge environments—no node-gyp or native compilation issues.
• ⚛️ Post-Quantum Ready: Built-in Kyber KEM and Dilithium signatures (pqc_kem_sign) future-proof long-term agent artifacts against quantum attacks.

Comparison: With vs. Without WebCrypt MCP

IDE & AI Agent Platform Integration

WebCrypt provides native Model Context Protocol (MCP) tooling exposing 6 core cryptographic tools to AI agents:

MCP Configuration Snippets by IDE

🔵 Google Antigravity (~/.gemini/config/config.json)

{
  "mcpServers": {
    "webcrypt": {
      "command": "npx",
      "args": ["-y", "webcrypt", "mcp"]
    }
  }
}

🟣 Cursor IDE (.cursor/mcp.json)

{
  "mcpServers": {
    "webcrypt": {
      "command": "npx",
      "args": ["-y", "webcrypt", "mcp"]
    }
  }
}

🟠 Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "webcrypt": {
      "command": "npx",
      "args": ["-y", "webcrypt", "mcp"]
    }
  }
}

🟢 VS Code / GitHub Copilot Agent (.vscode/mcp.json)

{
  "mcpServers": {
    "webcrypt": {
      "command": "npx",
      "args": ["-y", "webcrypt", "mcp"]
    }
  }
}

🌊 Windsurf (~/.codeium/windsurf/mcp_config.json) & 🤖 Cline (cline_mcp_settings.json)

{
  "mcpServers": {
    "webcrypt": {
      "command": "npx",
      "args": ["-y", "webcrypt", "mcp"]
    }
  }
}

📖 For full setup details, see the Multi-IDE MCP Setup Guide.

CLI & Global Project Management

# Verify environment and configuration health
webcrypt doctor

# Audit all registered projects across your machine
webcrypt doctor-global

# Re-initialize all projects in ~/.webcrypt/projects.json
webcrypt init-global

# Scan an entire workspace directory and auto-register all projects
webcrypt init-global --scan ~/workspaces

# List all registered projects
webcrypt projects --clean-stale

# Direct CLI text encryption / decryption
webcrypt encrypt "secret message" -p "my-password"
webcrypt decrypt "<base64>" -p "my-password"

# Direct CLI key generation
webcrypt keygen rsa
webcrypt keygen ecdh
webcrypt keygen password

PuterVision Triple Memory Triad

WebCrypt serves as the cryptographic security pillar of the PuterVision autonomous agent ecosystem:

                  ┌──────────────────────────────────────────────────────────┐
                  │                 Autonomous AI Coding Agent               │
                  └─────────────┬──────────────────────────────┬─────────────┘
                                │                              │
                                ▼                              ▼
                 ┌─────────────────────────────┐ ┌───────────────────────────┐
                 │  State Memory MCP (Graph)   │ │  Vision Memory MCP (AX)   │
                 └──────────────┬──────────────┘ └─────────────┬─────────────┘
                                │                              │
                                └──────────────┬───────────────┘
                                               │ (Zero-friction Vault Protection)
                                               ▼
                                 ┌───────────────────────────┐
                                 │     WebCrypt MCP Server   │
                                 │   (Stdio JSON-RPC 2.0)    │
                                 └───────────────────────────┘

JavaScript / TypeScript API Quick Start

1. Symmetric Text & JSON Encryption (AES-256-GCM)

import { WebCrypt } from "webcrypt";
const wc = new WebCrypt();

// Text encryption
const encrypted = await wc.encryptText("Secret message", "my-password");
const decrypted = await wc.decryptText(encrypted, "my-password");

// Automatic JSON object serialization
const vaultData = { apiKey: "secret_123", tokens: 5000 };
const cipherData = await wc.encryptData(vaultData, "vault-password");
const restoredData = await wc.decryptData(cipherData, "vault-password");

2. Streaming File Encryption (Constant Memory)

const { blob, filename } = await wc.encryptFile(file, "my-password", { parallelChunks: 4 });
const decrypted = await wc.decryptFile(blob, "my-password");

3. Public-Key Hybrid Encryption (RSA-4096)

import { WebCryptAsym } from "webcrypt";
const wca = new WebCryptAsym();

const keys = await wca.generateKeyPair(4096);
const encrypted = await wca.encryptText("Secret payload", keys.publicKey);
const decrypted = await wca.decryptText(encrypted, keys.privateKey);

4. ECDH Key Agreement & Fast Encryption

const aliceKeys = await wca.generateECDHKeyPair("P-256");
const bobKeys = await wca.generateECDHKeyPair("P-256");

const encrypted = await wca.encryptWithECDH(
  "Confidential channel data",
  aliceKeys.privateKey,
  bobKeys.publicKey
);
const decrypted = await wca.decryptWithECDH(encrypted, bobKeys.privateKey, aliceKeys.publicKey);

5. Digital Signatures & HMAC

// ECDSA signatures
const signingKeys = await wca.generateSigningKeyPair("P-256");
const signature = await wca.signText("Tamper-proof statement", signingKeys.privateKey);
const isValid = await wca.verifyText("Tamper-proof statement", signature, signingKeys.publicKey);

// Post-Quantum HMAC (SHA-3)
const hmacKey = await wc.generateHmacKeySHA3("shared-secret");
const tag = await wc.computeHmacSHA3("Message data", hmacKey);
const validMac = await wc.verifyHmacSHA3("Message data", tag, hmacKey);

📚 Technical Documentation Directory

Explore dedicated technical guides and deep dives in the docs/ directory:

🌐 PuterVision Triple Memory Triad

WebCrypt forms the core cryptographic and security layer of the PuterVision Autonomous AI Agent Ecosystem:

┌───────────────────────────────────────────────────────────┐
│              Autonomous AI Coding Agent                   │
│     (Antigravity / Cursor / Claude / Copilot / Cline)     │
└─────────┬───────────────────┬───────────────────┬─────────┘
          │                   │                   │
          ▼                   ▼                   ▼
┌───────────────────┐┌───────────────────┐┌───────────────────┐
│ state-memory-mcp  ││ vision-memory-mcp ││     webcrypt      │
│  (Workflow State) ││  (Visual Cache)   ││  (Security Vault) │
│  • Task Graph DAG ││  • UI Grounding   ││  • AES-256 Vault  │
│  • Decisions & SDD││  • Layout Trees   ││  • RSA/ECDH Keys  │
│  • Event Ledger   ││  • Visual History ││  • Digital Sigs   │
└───────────────────┘└───────────────────┘└───────────────────┘

• 📊 @putervision/state-memory-mcp: Deterministic persistent SQLite state graph for tracking workflow state, task DAGs, decision records, and Spec-Driven Development.
• 👁️ @putervision/vision-memory-mcp: Multimodal visual layout caching, perceptual hashing, element grounding, and video replay analysis.
• 🔐 webcrypt: Zero-dependency cryptographic vault, payload encryption, key generation, digital signatures, and post-quantum security.

🧪 Testing & Verification

# Run full unit and integration test matrix (30 test suites, 247 tests)
npm test

# Run test coverage audit
npm run test:coverage

⚖️ License & Disclaimers

Developed and maintained by PuterVision. Released under the MIT License.

• 100% Local Execution Guarantee: All encryption, key generation, and hash calculations occur entirely in your local runtime via standard W3C Web Crypto API (crypto.subtle). Zero external API calls, telemetry, or network transmissions.
• Trademarks & Non-Affiliation: Product names (Cursor, Claude Code, Google Antigravity, VS Code, GitHub Copilot, Windsurf, Cline, Zed) are property of their respective owners and used solely for compatibility identification.