Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
90 lines (65 loc) · 5.77 KB

ARCHITECTURE.md

File metadata and controls

90 lines (65 loc) · 5.77 KB
Raw

WebCrypt Architecture & Security Overview

WebCrypt is engineered as a zero-dependency cryptography library for modern web applications, browser extensions, Node.js servers, and WebRTC edge services.

Cryptographic Design & Primitives

WebCrypt exclusively uses standard algorithms implemented directly in browser engine C++ / Rust layers via the native W3C Web Crypto API (globalThis.crypto.subtle):

Primitive Implementation Details Security Standard
Symmetric Encryption AES-256-GCM (256-bit key, 96-bit IV, 128-bit Tag) NIST SP 800-38D
Asymmetric Encryption RSA-OAEP 4096-bit with SHA-256 RFC 3447 / PKCS #1 v2.2
Key Agreement ECDH (P-256 / P-384) NIST FIPS 186-4
Digital Signatures ECDSA (P-256/P-384) & RSA-PSS 4096-bit FIPS 186-4 / RFC 8017
Key Derivation PBKDF2 (SHA-256, 600,000 rounds) & HKDF-SHA256 OWASP 2025+ / RFC 5869
Token Format JWE Compact Serialization RFC 7516

Security Guarantees & Mitigations

1. Timing-Safe Constant-Time Operations

Timing oracle attacks allow eavesdroppers to infer secrets by measuring microsecond differences in comparison functions. TimingSafeHelper provides constant-time comparison methods:

  • constantTimeCompareStrings(strA, strB)
  • constantTimeCompareBuffers(bufA, bufB)
  • timingSafeVerify(...)

2. Post-Quantum & Quantum Resistance Status

  • Symmetric Encryption (AES-256): Resists Grover's quantum search algorithm (effective quantum security: 128 bits).
  • Key Derivation (PBKDF2-SHA256, 600k rounds): Resists Grover quantum speedup for passphrase brute forcing.
  • NIST Post-Quantum Cryptography (PQC): WebCrypt includes experimental Kyber-768/1024 and Dilithium2/3/5 key exchange and signature stubs. See docs/PQC.md for liboqs migration details.

3. Memory & Stream Protection

  • Large file streaming (encryptFile / decryptFile) processes data in 8MB chunks, preventing V8 heap exhaustion on multi-gigabyte files.
  • Base64 encoding/decoding is chunked in 32KB windows to eliminate RangeError: Maximum call stack size exceeded errors.

Model Context Protocol (MCP) AI Agent Architecture

WebCrypt v1.0.1 introduces a zero-dependency Model Context Protocol (MCP) stdio server conforming to JSON-RPC 2.0 and specification "2024-11-05".

┌──────────────────────────────────────────────────────────┐
│                   AI Coding Agent                        │
│     (Antigravity / Cursor / Claude / Copilot / Cline)     │
└────────┬───────────────────┬───────────────────┬─────────┘
         │                   │                   │
         ▼                   ▼                   ▼
┌──────────────────┐┌──────────────────┐┌──────────────────┐
│ state-memory-mcp ││ vision-memory-mcp││   webcrypt-mcp   │
│ (Workflow State) ││  (Visual Cache)  ││ (Cryptographic)  │
│  • Task DAG      ││  • Screenshots   ││  • AES-256-GCM   │
│  • Decisions     ││  • UI Grounding  ││  • RSA-4096      │
│  • Blockers      ││  • Transitions   ││  • Signatures    │
└──────────────────┘└──────────────────┘└──────────────────┘

1. Zero-Dependency Transport & Dispatch

  • Stdio Line Framing: Transport processes newline-delimited JSON-RPC 2.0 messages over standard I/O with non-blocking stream buffering.
  • Lazy Module Initialization: WebCrypt, WebCryptAsym, and WebCryptPQC instances are created on-demand when tools are invoked, avoiding initial process lag and console noise.
  • Error Formatting: Implements standard JSON-RPC 2.0 error codes (-32700 parse error, -32601 method not found, -32602 invalid params).

2. Registered Agent MCP Tools

  1. encrypt_payload: Symmetric (AES-256-GCM) or asymmetric (RSA-4096) string, JSON data, and file encryption.
  2. decrypt_payload: Symmetric or asymmetric decryption returning original plaintext or structured data.
  3. manage_keys: Generates JWK-formatted RSA-4096, ECDH (P-256/P-384), HMAC keys, or high-entropy passwords.
  4. crypto_hash: Cryptographic digest generation (SHA-256, SHA-512, SHA-3) in hex or base64.
  5. sign_verify: ECDSA, RSA-PSS, or HMAC digital signature creation and validation.
  6. pqc_kem_sign: Post-quantum Kyber key encapsulation and Dilithium lattice signatures.

3. Global Project Registry & Tooling Parity

  • Registry Path: ~/.webcrypt/projects.json (overridable via process.env.WEBCRYPT_REGISTRY_PATH).
  • CLI Commands:
    • webcrypt init [dir]: Scaffolds agent skills, MCP configurations, and instruction rules.
    • webcrypt init-global [--scan <dir>] [--clean-stale]: Re-synchronizes all registered projects.
    • webcrypt doctor [dir] [--json]: Diagnoses Web Crypto capabilities, skills, and MCP config validity.
    • webcrypt doctor-global [--json] [--clean-stale]: Performs multi-project system health audit.
    • webcrypt projects [--clean-stale]: Lists registered projects and status.

For setup details across editors, see docs/MCP_IDE_SETUP.md.