🛡️ @wakz/cyber-shield

Enterprise-Grade End-to-End Encryption Library

A zero-dependency, production-ready cryptographic shield that combines AES-256-GCM, ECDH P-256, Double Ratchet, Group Encryption, Digital Signatures, and 20+ security features — all built on the Web Crypto API.

✨ Features

🔐 Core Encryption

| Feature | Description | |---------|-------------| | AES-256-GCM | Authenticated encryption with 128-bit authentication tags | | ECDH P-256 | Elliptic-curve Diffie-Hellman key agreement | | HKDF-SHA-256 | HMAC-based key derivation for all key material | | Perfect Forward Secrecy | Automatic key rotation with configurable intervals |

📁 Binary & File Encryption

| Feature | Description | |---------|-------------| | ArrayBuffer/Uint8Array | Encrypt raw binary data directly | | Blob/File Support | Handle file uploads and large binary objects | | TypedArray Support | Int8Array, Float32Array, DataView, and more | | MIME Type Preservation | Attach content type and filename metadata |

🔄 Double Ratchet Protocol

| Feature | Description | |---------|-------------| | Signal Protocol | Per-message forward secrecy via KDF chain + DH ratchet | | Out-of-Order Messages | Skipped message key storage with TTL-based pruning | | HMAC Binding | Each message signed with HMAC-SHA-256 | | Fingerprint Binding | Device fingerprint hash bound to every message |

👥 Group / Multi-Party Encryption

| Feature | Description | |---------|-------------| | Sender Keys | Signal-inspired group messaging protocol | | Chain Key Advancement | Per-message forward secrecy within groups | | Member Management | Add/remove members with epoch tracking | | Key Distribution | Encrypted sender key distribution via pairwise sessions |

✍️ Digital Signatures

| Feature | Description | |---------|-------------| | ECDSA P-256 | Non-repudiation via elliptic-curve signatures | | Sign/Verify API | Simple API for signing and verifying data | | Key Export | Export signing public keys for verification by third parties |

🔑 Key Management

| Feature | Description | |---------|-------------| | Key Wrapping | AES-KW and AES-GCM key wrap/unwrap | | Password-Based KDF | PBKDF2 with 600,000 iterations (OWASP recommended) | | Secure Key Backup | Password-encrypted key export/import | | Key Escrow | Enterprise key recovery with sharded secrets | | Multi-Session | Manage multiple concurrent encryption sessions |

🛡️ Security Shield

| Feature | Description | |---------|-------------| | Anti-Tamper (4-Layer) | Integrity hash, crypto API verification, DevTools detection, code modification probes | | Traffic Obfuscation | 9 format markers + XOR cipher + size normalization + timing jitter | | Device Fingerprinting | 8 signals + HMAC binding (canvas, WebGL, UA, hardware) | | Replay Prevention | LRU cache + TTL expiry + IV deduplication | | Rate Limiting | Block or queue strategies for crypto operations | | Concurrency Pool | Parallel crypto with configurable limits |

🏢 Enterprise Features

| Feature | Description | |---------|-------------| | Compliance & Audit | Chain-hash audit log for regulatory compliance | | Plugin System | Middleware hooks (beforeProtect, afterProtect, etc.) | | Transport Adapter | Pluggable transport layer (WebSocket, HTTP, etc.) | | Zero-Knowledge Proofs | Schnorr-like ZKP for authentication without secrets | | Streaming Encryption | Chunk-based encryption for large files | | Safety Numbers | Verification numbers for key authenticity |

📦 Installation

npm install @wakz/cyber-shield

🚀 Quick Start

Basic Text Encryption

import WAKZShield from "@wakz/cyber-shield";

// Alice creates a shield
const alice = new WAKZShield({ enableObfuscation: true });
await alice.init();

// Bob creates a shield
const bob = new WAKZShield({ enableObfuscation: true });
await bob.init();

// Exchange public keys
const alicePub = await alice.exportPublicKey();
const bobPub = await bob.exportPublicKey();

await alice.setPeerPublicKey(bobPub);
await bob.setPeerPublicKey(alicePub);

// Encrypt & decrypt
const encrypted = await alice.protect("Hello, Bob! 🔐");
const decrypted = await bob.unprotect(encrypted);

console.log(decrypted); // "Hello, Bob! 🔐"

Binary / File Encryption

// Encrypt binary data (ArrayBuffer, Uint8Array, Blob)
const fileData = new Uint8Array([0x89, 0x50, 0x4E, 0x47]); // PNG header

const encrypted = await alice.protectBinary(fileData, {
  mimeType: "image/png",
  filename: "photo.png",
});

const decrypted = await bob.unprotectBinary(encrypted);
// decrypted is Uint8Array with original bytes

Double Ratchet (Per-Message Forward Secrecy)

const alice = new WAKZShield({ enableRatchet: true });
await alice.init();

const bob = new WAKZShield({ enableRatchet: true });
await bob.init();

// Exchange keys and initialize ratchet
const alicePub = await alice.exportPublicKey();
const bobPub = await bob.exportPublicKey();

await alice.setPeerPublicKey(bobPub);
await bob.setPeerPublicKey(alicePub);

// Each message uses a unique key — compromise of one key doesn't affect others
const msg1 = await alice.protect("Message 1");
const msg2 = await alice.protect("Message 2");
const msg3 = await alice.protect("Message 3");

// Bob can decrypt in any order
const d3 = await bob.unprotectRatchet(msg3);

Group / Multi-Party Encryption

// Alice creates a group
const group = await alice.createGroup("team-alpha", "Engineering Team");

// Bob joins the group
const distribution = await alice.getGroupSenderKeyDistribution(
  "team-alpha",
  bobSharedKey,
);
await bob.joinGroup("team-alpha", distribution, aliceSharedKey, alicePubKey);

// Encrypt for the group
const groupMsg = await alice.protectGroup("team-alpha", "Hello team! 🎉");

// Any member can decrypt
const decrypted = await bob.unprotectGroup(groupMsg);

Digital Signatures

// Create signing key pair
const signingKey = await alice.createSigningKeyPair();

// Sign data
const signature = await alice.sign("Important document");
console.log(signature.algorithm); // "ECDSA-P256"

// Verify signature
const isValid = await alice.verify("Important document", signature.signature);
console.log(isValid); // true

// Export public key for third-party verification
const verificationKey = await alice.exportSigningPublicKey();

Streaming Encryption (Large Files)

// Create a stream
const stream = await alice.createStream();

// Encrypt chunks
const chunk1 = await alice.encryptStreamChunk(stream.streamId, dataSlice1);
const chunk2 = await alice.encryptStreamChunk(stream.streamId, dataSlice2);
const chunk3 = await alice.encryptStreamChunk(
  stream.streamId,
  dataSlice3,
  true, // isFinal = true
);

// Decrypt chunks on the other side
const dec1 = await bob.decryptStreamChunk(stream.streamId, chunk1, stream.key);

Password-Based Key Derivation

// Derive an encryption key from a password
const salt = "unique-salt-value";
const key = await alice.deriveKeyFromPassword("my-secure-password", {
  iterations: 600000, // OWASP recommended minimum
  salt,
});

// Use the derived key for encryption

Key Wrapping

// Wrap (encrypt) the shared key
const wrapped = await alice.wrapKey({ algorithm: "AES-GCM" });

// Unwrap (decrypt) the key later
const unwrappedKey = await alice.unwrapKey(wrapped);

Secure Key Backup

// Export key as encrypted backup
const backup = await alice.exportKeyBackup("strong-backup-password");

// Import key from backup
const restoredKey = await alice.importKeyBackup(
  backup,
  "strong-backup-password",
);

Plugin System

// Create a custom plugin
const loggerPlugin = {
  name: "audit-logger",
  version: "1.0.0",
  afterProtect: async (payload, ctx) => {
    ctx.log(`Message encrypted: ${ctx.sessionId}`);
  },
  afterUnprotect: async (data, ctx) => {
    ctx.log(`Message decrypted: ${ctx.sessionId}`);
  },
};

alice.usePlugin(loggerPlugin);

🏗️ Architecture

@wakz/cyber-shield
├── 🔐 Core Crypto
│   ├── AES-256-GCM (encrypt/decrypt)
│   ├── HKDF-SHA-256 (key derivation)
│   ├── PBKDF2 (password-based KDF)
│   ├── ECDH P-256 (key agreement)
│   ├── ECDSA P-256 (digital signatures)
│   └── AES-KW / AES-GCM (key wrapping)
│
├── 🔄 Protocols
│   ├── Double Ratchet (per-message FS)
│   └── Sender Keys (group encryption)
│
├── 🛡️ Shield Layer
│   ├── Anti-Tamper (4-layer detection)
│   ├── Traffic Obfuscation (9 markers + XOR)
│   ├── Device Fingerprinting (8 signals)
│   └── Replay Prevention (LRU + TTL)
│
└── 🏢 Enterprise
    ├── Multi-Session Manager
    ├── Rate Limiter
    ├── Concurrency Pool
    ├── Plugin System
    ├── Transport Adapter
    ├── Compliance & Audit Log
    ├── Zero-Knowledge Proofs
    ├── Key Escrow
    └── Streaming Encryption

⚙️ Configuration

interface WAKZShieldConfig {
  // Security features
  enableAntiTamper?: boolean;      // Default: true
  enableObfuscation?: boolean;     // Default: true
  enableFingerprint?: boolean;     // Default: true
  enableRatchet?: boolean;         // Default: false
  enableRateLimiting?: boolean;    // Default: false
  enableCompliance?: boolean;      // Default: false

  // Key management
  keyRotationInterval?: number;    // Default: 300000 (5 min)
  keyDerivationIterations?: number;// Default: 1 (use >1 for strengthening)
  maxPayloadSize?: number;         // Default: 10485760 (10MB)

  // Advanced
  entropySeed?: string;            // Custom entropy for key derivation
  verificationToken?: string;      // Public key verification token
  maxConcurrency?: number;         // Default: 4
  rateLimitConfig?: {
    maxOperations: number;         // Default: 100
    windowMs: number;              // Default: 60000
    strategy: "block" | "queue";   // Default: "block"
  };
  complianceConfig?: {
    fipsMode?: boolean;
    enableAudit?: boolean;
    minKeyLength?: number;
    requireKeyRotation?: boolean;
    maxKeyLifetime?: number;
  };
}

📡 Events

const shield = new WAKZShield(
  { enableRatchet: true },
  {
    onTamperDetected: (report) => console.warn("Tamper!", report),
    onKeyRotated: (keyId) => console.log("Key rotated:", keyId),
    onStatusChange: (status) => console.log("Status:", status),
    onError: (error) => console.error("Shield error:", error),
    onRatchetStep: (keyId) => console.log("Ratchet step:", keyId),
    onGroupMemberJoin: (groupId, memberId) => console.log("Member joined"),
    onGroupMemberLeave: (groupId, memberId) => console.log("Member left"),
    onRateLimitHit: () => console.warn("Rate limit reached"),
  },
);

🔬 API Reference

Core Methods

| Method | Returns | Description | |--------|---------|-------------| | init() | Promise<void> | Initialize the shield with key generation | | protect(message) | Promise<EncryptedPayload> | Encrypt a text message | | unprotect(payload) | Promise<string> | Decrypt a text message | | protectBinary(data, opts?) | Promise<BinaryEncryptedPayload> | Encrypt binary data | | unprotectBinary(payload) | Promise<Uint8Array> | Decrypt binary data | | destroy() | Promise<void> | Securely destroy the shield and zero keys |

Key Exchange

| Method | Returns | Description | |--------|---------|-------------| | exportPublicKey() | Promise<string> | Export public key as JSON JWK | | setPeerPublicKey(jwk) | Promise<void> | Set peer's public key | | updatePeerPublicKey(jwk) | Promise<void> | Update peer's public key | | computeSafetyNumber() | Promise<string> | Compute verification safety number | | getCurrentPublicKey() | Promise<string> | Get current public key |

Double Ratchet

| Method | Returns | Description | |--------|---------|-------------| | unprotectRatchet(payload) | Promise<string \| Uint8Array> | Decrypt ratchet-encrypted message |

Group Encryption

| Method | Returns | Description | |--------|---------|-------------| | createGroup(id, name?) | Promise<GroupSession> | Create a new group | | joinGroup(id, dist, key, jwk) | Promise<GroupSession> | Join an existing group | | leaveGroup(id, jwk) | GroupSession | Leave a group | | protectGroup(id, message) | Promise<GroupEncryptedPayload> | Encrypt for group | | unprotectGroup(payload) | Promise<string \| ArrayBuffer> | Decrypt group message | | getGroupSenderKeyDistribution(id, key) | Promise<SenderKeyDistribution> | Get sender key for distribution |

Digital Signatures

| Method | Returns | Description | |--------|---------|-------------| | createSigningKeyPair() | Promise<SigningKeyPair> | Generate signing key pair | | sign(data) | Promise<SignatureResult> | Sign data | | verify(data, sig, pubKey?) | Promise<boolean> | Verify signature | | exportSigningPublicKey() | Promise<string> | Export verification key |

Key Management

| Method | Returns | Description | |--------|---------|-------------| | rotateKeys() | Promise<string> | Rotate session keys (PFS) | | needsRotation() | boolean | Check if rotation is needed | | wrapKey(config?) | Promise<WrappedKey> | Wrap shared key | | unwrapKey(wrapped, config?) | Promise<CryptoKey> | Unwrap a key | | deriveKeyFromPassword(pwd, config?) | Promise<CryptoKey> | Derive key from password | | exportKeyBackup(password) | Promise<string> | Export encrypted key backup | | importKeyBackup(backup, password) | Promise<CryptoKey> | Import key from backup |

Streaming

| Method | Returns | Description | |--------|---------|-------------| | createStream(key?) | Promise<StreamingState> | Create encryption stream | | encryptStreamChunk(id, data, final?) | Promise<StreamChunk> | Encrypt a chunk | | decryptStreamChunk(id, chunk, key) | Promise<Uint8Array> | Decrypt a chunk | | destroyStream(id) | void | Destroy a stream |

Multi-Session

| Method | Returns | Description | |--------|---------|-------------| | createSession() | Promise<string> | Create new session | | listSessions() | SessionInfo[] | List all sessions | | switchSession(id) | void | Switch active session |

Enterprise

| Method | Returns | Description | |--------|---------|-------------| | usePlugin(plugin) | void | Register a plugin | | removePlugin(name) | void | Remove a plugin | | setTransport(adapter) | void | Set transport adapter | | send(message) | Promise<void> | Send encrypted via transport | | onMessage(callback) | () => void | Receive decrypted messages | | getAuditLog() | ReadonlyArray<AuditEntry> | Get audit trail | | createZKPChallenge() | Promise<ZKPChallenge> | Create ZKP challenge | | createZKPProof(challenge, secret) | Promise<ZKPProof> | Create ZKP proof | | verifyZKPProof(challenge, proof, hash) | Promise<ZKPVerification> | Verify ZKP proof | | createEscrowShards(config, n?, t?) | Promise<EscrowedKey[]> | Create key escrow shards |

Info & Status

| Method | Returns | Description | |--------|---------|-------------| | getStatus() | ShieldStatus | Get current status | | getSessionInfo() | object \| null | Get session details | | getInfo() | object | Get shield info & features | | runSecurityAudit() | TamperReport | Run tamper detection checks |

🔒 Security Model

┌──────────────────────────────────────────────────────┐
│                   WAKZShield Security                │
├──────────────────────────────────────────────────────┤
│                                                      │
│  Layer 1: Key Agreement                             │
│  ┌────────────────────────────────────────────────┐  │
│  │ ECDH P-256 → HKDF-SHA-256 → AES-256 + HMAC   │  │
│  │ Entropy seed binding + Strengthened derivation │  │
│  └────────────────────────────────────────────────┘  │
│                                                      │
│  Layer 2: Message Security                          │
│  ┌────────────────────────────────────────────────┐  │
│  │ AES-256-GCM (128-bit tag) + HMAC-SHA-256      │  │
│  │ Fingerprint binding + Replay prevention        │  │
│  └────────────────────────────────────────────────┘  │
│                                                      │
│  Layer 3: Forward Secrecy                           │
│  ┌────────────────────────────────────────────────┐  │
│  │ Auto key rotation (PFS) + Double Ratchet       │  │
│  │ Per-message keys + Skipped key TTL pruning     │  │
│  └────────────────────────────────────────────────┘  │
│                                                      │
│  Layer 4: Runtime Protection                        │
│  ┌────────────────────────────────────────────────┐  │
│  │ Anti-tamper (4-layer) + Obfuscation (9 types)  │  │
│  │ Device fingerprinting + Rate limiting           │  │
│  └────────────────────────────────────────────────┘  │
│                                                      │
└──────────────────────────────────────────────────────┘

🌐 Browser & Node.js Support

| Environment | Support | |-------------|---------| | Chrome 60+ | ✅ Full | | Firefox 55+ | ✅ Full | | Safari 11+ | ✅ Full | | Edge 79+ | ✅ Full | | Node.js 18+ | ✅ Full | | Deno | ✅ Full (Web Crypto API) | | Cloudflare Workers | ✅ Full | | Vercel Edge | ✅ Full |

📜 License

MIT License — see LICENSE for details.

🙏 Third-Party Attributions

See THIRD_PARTY_ATTRIBUTIONS.md for attribution details.

Built with 🛡️ by WAKZ Security Engineering