New:Socket for Asana Is Now Available.Learn more →
Get Started

webcrypt

Package Overview
Dependencies
Maintainers
1
Versions
21
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

webcrypt - npm Package Compare versions

Comparing version
0.8.0
 to
1.0.0
+7
bin/webcrypt-mcp.js
#!/usr/bin/env node
// bin/webcrypt-mcp.js
// Standalone WebCrypt Model Context Protocol (MCP) Server
import { startMCPServer } from "../src/mcp/server.js";
startMCPServer();
+203
bin/webcrypt.js
#!/usr/bin/env node
// bin/webcrypt.js
// WebCrypt CLI, MCP Server Launcher & Global Registry Manager
import path from "path";
const args = process.argv.slice(2);
const command = args[0];
function printHelp() {
console.log(`
WebCrypt v1.0.0 — Zero-Dependency Cryptography & Agent Tooling Suite
Maintained by PuterVision (https://putervision.com)
Usage:
webcrypt <command> [options]
Project & Agent Commands:
init [dir] Scaffold MCP config, agent skill, and rules into project
init-global [options] Re-initialize across all projects registered in ~/.webcrypt/projects.json
Options: --clean-stale, --scan <dir>
doctor [dir] [options] Run environment and configuration health checks (--json)
doctor-global [options] Run health checks across all registered projects
Options: --clean-stale, --json
projects [options] List all registered projects in ~/.webcrypt/projects.json
Options: --clean-stale
MCP & Cryptography Commands:
mcp Start the WebCrypt MCP Server (stdio JSON-RPC)
encrypt <text> -p <pass> Encrypt text with password (AES-256-GCM)
decrypt <b64> -p <pass> Decrypt base64 ciphertext with password
keygen [type] Generate cryptographic keys (rsa, ecdh, password)
--version, -v Display version
--help, -h Display this help message
Examples:
webcrypt init
webcrypt init-global --scan ~/workspaces
webcrypt doctor
webcrypt doctor-global --clean-stale
webcrypt projects
npx webcrypt mcp
`);
}
async function main() {
if (!command || command === "--help" || command === "-h") {
printHelp();
return;
}
if (command === "--version" || command === "-v") {
console.log("webcrypt v1.0.0");
return;
}
if (command === "mcp") {
const { startMCPServer } = await import("../src/mcp/server.js");
startMCPServer();
return;
}
if (command === "init") {
const { runInit } = await import("../src/cli/init.js");
const targetDir =
args[1] && !args[1].startsWith("-")
? args[1].startsWith("/")
? args[1]
: path.resolve(process.cwd(), args[1])
: process.cwd();
await runInit(targetDir);
return;
}
if (command === "init-global") {
const { runInitGlobal } = await import("../src/cli/init.js");
const cleanStale = args.includes("--clean-stale");
const scanIdx = args.indexOf("--scan");
const scan = scanIdx !== -1 ? args[scanIdx + 1] : null;
await runInitGlobal({ cleanStale, scan });
return;
}
if (command === "doctor") {
const { runDoctor } = await import("../src/cli/doctor.js");
const isJson = args.includes("--json");
const targetDir =
args[1] && !args[1].startsWith("-")
? args[1].startsWith("/")
? args[1]
: path.resolve(process.cwd(), args[1])
: process.cwd();
await runDoctor(targetDir, { json: isJson });
return;
}
if (command === "doctor-global") {
const { runDoctorGlobal } = await import("../src/cli/doctor.js");
const isJson = args.includes("--json");
const cleanStale = args.includes("--clean-stale");
await runDoctorGlobal({ json: isJson, cleanStale });
return;
}
if (command === "projects") {
const { getRegistry, pruneStaleProjects } = await import("../src/cli/registry.js");
if (args.includes("--clean-stale")) {
const { removed } = pruneStaleProjects();
if (removed.length > 0) {
console.log(`🧹 Cleaned ${removed.length} stale project entries.`);
}
}
const registry = getRegistry();
const entries = Object.entries(registry);
if (entries.length === 0) {
console.log("No registered projects in ~/.webcrypt/projects.json.");
return;
}
console.log(`\nRegistered Projects (${entries.length}):`);
console.log("-----------------------------------------");
for (const [slug, p] of entries) {
console.log(` • ${slug.padEnd(20)} => ${p}`);
}
console.log("");
return;
}
if (command === "encrypt") {
const text = args[1];
const passIdx = args.indexOf("-p");
const password = passIdx !== -1 ? args[passIdx + 1] : null;
if (!text || !password) {
console.error("Error: Text and password (-p <password>) required.");
process.exit(1);
}
const { WebCrypt } = await import("../src/WebCrypt.js");
const wc = new WebCrypt();
const encrypted = await wc.encryptText(text, password);
console.log(encrypted);
return;
}
if (command === "decrypt") {
const ciphertext = args[1];
const passIdx = args.indexOf("-p");
const password = passIdx !== -1 ? args[passIdx + 1] : null;
if (!ciphertext || !password) {
console.error("Error: Ciphertext and password (-p <password>) required.");
process.exit(1);
}
try {
const { WebCrypt } = await import("../src/WebCrypt.js");
const wc = new WebCrypt();
const decrypted = await wc.decryptText(ciphertext, password);
console.log(decrypted);
} catch (e) {
console.error("Decryption failed: wrong password or invalid data.");
process.exit(1);
}
return;
}
if (command === "keygen") {
const type = args[1] || "password";
if (type === "password") {
const { WebCrypt } = await import("../src/WebCrypt.js");
const wc = new WebCrypt();
const pass = wc.generateRandomPassword(32);
console.log(`Generated 32-byte secure key/password:\n${pass}`);
} else if (type === "rsa") {
console.log("Generating RSA-4096 keypair...");
const { WebCryptAsym } = await import("../src/WebCryptAsym.js");
const asym = new WebCryptAsym();
const keys = await asym.generateKeyPair(4096);
const pubJwk = await asym._crypto.subtle.exportKey("jwk", keys.publicKey);
const privJwk = await asym._crypto.subtle.exportKey("jwk", keys.privateKey);
console.log("Public Key (JWK):", JSON.stringify(pubJwk));
console.log("Private Key (JWK):", JSON.stringify(privJwk));
} else if (type === "ecdh") {
console.log("Generating ECDH P-256 keypair...");
const { WebCryptAsym } = await import("../src/WebCryptAsym.js");
const asym = new WebCryptAsym();
const keys = await asym.generateECDHKeyPair("P-256");
const pubJwk = await asym._crypto.subtle.exportKey("jwk", keys.publicKey);
const privJwk = await asym._crypto.subtle.exportKey("jwk", keys.privateKey);
console.log("Public Key (JWK):", JSON.stringify(pubJwk));
console.log("Private Key (JWK):", JSON.stringify(privJwk));
} else {
console.error(`Unknown keygen type: ${type}`);
process.exit(1);
}
return;
}
console.error(`Unknown command: ${command}`);
printHelp();
process.exit(1);
}
main().catch(err => {
console.error("WebCrypt CLI error:", err);
process.exit(1);
});
+1116
dist/_crypto-B6690zvC.d.cts
// src/WebCrypt.d.ts
/**
* WebCrypt – Zero-dependency quantum-resistant AES-256-GCM encryption
*
* Supports:
* - Text encryption/decryption
* - Large file encryption/decryption (streaming)
* - WebRTC Insertable Streams E2EE (video + audio)
* - HMAC for message authentication
*
* Works in Browser, Node.js 18+, Deno, Cloudflare Workers
*/
declare class WebCrypt {
static readonly ALGORITHM: "AES-GCM";
static readonly KEY_LENGTH: 256;
static readonly IV_LENGTH: 12;
static readonly SALT_LENGTH: 16;
static readonly PBKDF2_ITERATIONS: number;
static readonly HASH_ALGORITHM: "SHA-256";
static readonly CHUNK_SIZE: number;
static readonly WEBRTC_SALT: Uint8Array;
static readonly DEFAULT_HMAC_SALT: Uint8Array;
/**
* Generates a cryptographically secure random salt for HMAC key derivation.
* @param length Salt length in bytes (default: 16)
*/
static generateHmacSalt(length?: number): Uint8Array;
/**
* Encrypts a string and returns Base64-encoded ciphertext
* @param text Plain text to encrypt
* @param password Password (or shared secret)
* @returns Base64 string (salt + iv + ciphertext)
*/
encryptText(text: string, password: string): Promise<string>;
/**
* Decrypts a Base64 string produced by encryptText()
* @param base64 Encrypted data from encryptText()
* @param password Must match encryption password
* @returns Original plain text
* @throws If password is wrong or data is corrupted
*/
decryptText(base64: string, password: string): Promise<string>;
/**
* Encrypts a File or Blob using streaming (low memory, handles huge files)
* @param file File or Blob to encrypt
* @param password Encryption password
* @param options Optional configuration object ({ parallelChunks?: number })
* @returns Object with encrypted Blob and suggested filename
*/
encryptFile(
file: File | Blob,
password: string,
options?: { parallelChunks?: number }
): Promise<{
blob: Blob;
filename: string;
}>;
/**
* Decrypts a .encrypted file produced by encryptFile()
* @param file Encrypted File or Blob
* @param password Must match encryption password
* @param options Optional configuration object ({ parallelChunks?: number })
* @returns Object with decrypted Blob and original filename
* @throws If password is wrong or file is corrupted
*/
decryptFile(
file: File | Blob,
password: string,
options?: { parallelChunks?: number }
): Promise<{
blob: Blob;
filename: string;
}>;
/**
* Creates an encryption transform for WebRTC Insertable Streams
* Use with RTCRtpSender.transform
* @param password Shared secret both peers must know
*/
createEncryptTransform(
password: string
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Creates a decryption transform for WebRTC Insertable Streams
* Use with RTCRtpReceiver.transform
* @param password Must match sender's password
*/
createDecryptTransform(
password: string
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Generates or derives an HMAC key.
* @param password Optional password for PBKDF2 derivation (if provided, uses 600_000 iterations).
* @param hash Hash algorithm (default: 'SHA-256').
* @param salt Optional salt for deterministic derivation.
* @returns Usable HMAC key.
*/
generateHmacKey(
password?: string,
hash?: "SHA-256" | "SHA-384" | "SHA-512",
salt?: Uint8Array | string
): Promise<CryptoKey>;
/**
* Computes HMAC on data.
* @param data Text or ArrayBuffer to authenticate.
* @param key HMAC key from generateHmacKey.
* @returns Base64-encoded HMAC tag.
*/
computeHmac(data: string | ArrayBuffer, key: CryptoKey): Promise<string>;
/**
* Verifies HMAC on data.
* @param data Text or ArrayBuffer to verify.
* @param hmac Base64-encoded HMAC tag to check.
* @param key HMAC key.
* @returns True if valid.
*/
verifyHmac(data: string | ArrayBuffer, hmac: string, key: CryptoKey): Promise<boolean>;
/**
* Generate a quantum-resistant HMAC key using SHA-3 hash.
* @param password Optional password for derivation
* @param hash Hash algorithm: 'SHA3-256' | 'SHA3-384' | 'SHA3-512' (default: SHA3-256)
* @param salt Optional salt for deterministic derivation.
* @param iterations Iterations count for SHA-3 KDF derivation (default: 10,000)
* @returns Usable HMAC key with SHA-3
*/
generateHmacKeySHA3(
password?: string,
hash?: "SHA3-256" | "SHA3-384" | "SHA3-512",
salt?: Uint8Array | string,
iterations?: number
): Promise<CryptoKey>;
/**
* Compute HMAC using SHA-3 (quantum-resistant).
* @param data Data to authenticate
* @param key HMAC key from generateHmacKeySHA3
* @returns Base64-encoded HMAC tag
*/
computeHmacSHA3(data: string | ArrayBuffer, key: CryptoKey): Promise<string>;
/**
* Verify HMAC using SHA-3 (quantum-resistant).
* @param data Data to verify
* @param hmac Base64-encoded HMAC tag
* @param key HMAC key
* @returns True if valid
*/
verifyHmacSHA3(data: string | ArrayBuffer, hmac: string, key: CryptoKey): Promise<boolean>;
/**
* Automatically serializes any JavaScript object or array to JSON before encrypting.
*/
encryptData(data: any, password: string): Promise<string>;
/**
* Decrypts the data and automatically parses it back into a JavaScript object.
*/
decryptData(base64: string, password: string): Promise<any>;
/**
* Utility to generate a cryptographically secure random password or key string.
*/
generateRandomPassword(length?: number): string;
/**
* Clear entire key cache.
*/
clearKeyCache(): void;
/**
* Stop automatic cache cleanup interval.
*/
stopAutoCleanup(): void;
}
// WebCryptAsym.d.ts
/**
* Asymmetric encryption utility using RSA-OAEP + AES-GCM hybrid encryption.
* Supports text, file (streaming), and WebRTC insertable streams.
*/
declare class WebCryptAsym {
/**
* RSA-OAEP algorithm parameters
*/
static readonly RSA_ALGORITHM: AlgorithmIdentifier;
/**
* Parameters for RSA key generation (4096-bit, SHA-256)
*/
static readonly RSA_KEY_PARAMS: RsaHashedKeyGenParams;
/**
* AES-GCM algorithm name
*/
static readonly AES_ALGORITHM: "AES-GCM";
/**
* AES key length (256 bits)
*/
static readonly AES_LENGTH: 256;
/**
* IV length for AES-GCM (12 bytes recommended)
*/
static readonly IV_LENGTH: 12;
/**
* Chunk size for file streaming (8 MB)
*/
static readonly CHUNK_SIZE: number;
/**
* Fixed salt-like identifier for WebRTC transforms
*/
static readonly WEBRTC_SALT: Uint8Array;
/**
* PBKDF2 algorithm name
*/
static readonly PBKDF2_ALGORITHM: "PBKDF2";
/**
* Default PBKDF2 hash algorithm
*/
static readonly PBKDF2_HASH: "SHA-256";
/**
* Default number of PBKDF2 iterations
*/
static readonly PBKDF2_ITERATIONS: number;
/**
* Argon2 algorithm name
*/
static readonly ARGON2_ALGORITHM: "Argon2id";
/**
* RSA-PSS algorithm name
*/
static readonly RSA_PSS_ALGORITHM: "RSA-PSS";
/**
* EdDSA algorithm name
*/
static readonly ED25519_ALGORITHM: "EdDSA";
/**
* Ed25519 curve name
*/
static readonly ED25519_CURVE: "Ed25519";
constructor();
/**
* Generate a new RSA-4096 key pair
*/
generateKeyPair(): Promise<CryptoKeyPair>;
/**
* Generate an ECDSA signing key pair
* @param curve - Supported curves: 'P-256' (default), 'P-384'
*/
generateSigningKeyPair(curve?: string): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Generate an EdDSA signing key pair
*/
generateEdDSASigningKeyPair(): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Generate an RSA-PSS signing key pair
* @param modulusLength - RSA key size in bits (default: 2048)
*/
generateRSAPSSigningKeyPair(modulusLength?: number): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Export public key to Base64-encoded SPKI format
*/
exportPublicKey(publicKey: CryptoKey): Promise<string>;
/**
* Export private key to Base64-encoded PKCS8 format
*/
exportPrivateKey(privateKey: CryptoKey): Promise<string>;
/**
* Import public key from Base64 SPKI string
*/
importPublicKey(b64: string): Promise<CryptoKey>;
/**
* Import private key from Base64 PKCS8 string
*/
importPrivateKey(b64: string): Promise<CryptoKey>;
/**
* Encrypt text using recipient's public key (hybrid: RSA-wrapped AES-GCM)
* @returns Base64-encoded encrypted data
*/
encryptText(text: string, publicKey: CryptoKey): Promise<string>;
/**
* Decrypt text using own private key
*/
decryptText(encryptedB64: string, privateKey: CryptoKey): Promise<string>;
/**
* Encrypt a file/blob using recipient's public key (streaming)
* @returns Object with encrypted Blob and suggested filename
*/
encryptFile(
fileOrBlob: Blob | File,
publicKey: CryptoKey,
options?: { parallelChunks?: number }
): Promise<{ blob: Blob; filename: string }>;
/**
* Decrypt an asymmetrically encrypted file/blob
* @returns Object with decrypted Blob and original filename
*/
decryptFile(
fileOrBlob: Blob | File,
privateKey: CryptoKey,
options?: { parallelChunks?: number }
): Promise<{ blob: Blob; filename: string }>;
/**
* Create an encryption transform function for WebRTC insertable streams
* Sends encrypted session key in the first frame.
*/
createEncryptTransform(
publicKey: CryptoKey
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Create a decryption transform function for WebRTC insertable streams
* Extracts session key from first frame and decrypts subsequent frames.
*/
createDecryptTransform(
privateKey: CryptoKey
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Create a hybrid encryption transform that supports both classical and post-quantum approaches
* @param publicKey - RSA public key for hybrid encryption
* @param usePostQuantum - Whether to use post-quantum hybrid approach
*/
createHybridEncryptTransform(
publicKey: CryptoKey,
usePostQuantum?: boolean
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Enhanced WebRTC transform with progress tracking
* @param publicKey - RSA public key for hybrid encryption
* @param onProgress - Callback function to report encryption progress
*/
createEncryptTransformWithProgress(
publicKey: CryptoKey,
onProgress?: (bytesProcessed: number) => void
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Encrypt a file with progress tracking
* @param fileOrBlob - File or Blob to encrypt
* @param publicKey - RSA public key for hybrid encryption
* @param onProgress - Callback function to report encryption progress
*/
encryptFileWithProgress(
fileOrBlob: Blob | File,
publicKey: CryptoKey,
onProgress?: (bytesProcessed: number) => void
): Promise<{ blob: Blob; filename: string }>;
/**
* Decrypt a file with progress tracking
* @param fileOrBlob - File or Blob to decrypt
* @param privateKey - RSA private key for hybrid decryption
* @param onProgress - Callback function to report decryption progress
*/
decryptFileWithProgress(
fileOrBlob: Blob | File,
privateKey: CryptoKey,
onProgress?: (bytesProcessed: number) => void
): Promise<{ blob: Blob; filename: string }>;
/**
* Derive a key using PBKDF2 with configurable parameters
* @param password - The password to derive the key from
* @param salt - Salt for the derivation
* @param iterations - Number of PBKDF2 iterations (default: 600000)
* @param hash - Hash algorithm (default: SHA-256)
* @param keyLength - Length of the derived key in bits
*/
deriveKeyPBKDF2(
password: string,
salt: Uint8Array,
iterations?: number,
hash?: string,
keyLength?: number
): Promise<CryptoKey>;
/**
* Derive a key using Argon2id (where supported)
* @param password - The password to derive the key from
* @param salt - Salt for the derivation
* @param options - Argon2 configuration options
*/
deriveKeyArgon2(
password: string,
salt: Uint8Array,
options?: {
iterations?: number;
memoryCost?: number;
parallelism?: number;
}
): Promise<CryptoKey>;
/**
* Generate a key for symmetric encryption using password-based derivation
* @param password - Password to derive the key from
* @param salt - Salt for key derivation
* @param algorithm - Key derivation algorithm (PBKDF2 or Argon2)
*/
generateKeyFromPassword(
password: string,
salt: Uint8Array,
algorithm?: "PBKDF2" | "Argon2"
): Promise<CryptoKey>;
/**
* Generate a new key for symmetric encryption using password-based derivation with key rotation
* @param password - Password to derive the key from
* @param salt - Salt for key derivation
* @param algorithm - Key derivation algorithm (PBKDF2 or Argon2)
* @param rotationCount - Rotation counter for key derivation
*/
generateRotatingKey(
password: string,
salt: Uint8Array,
algorithm?: "PBKDF2" | "Argon2",
rotationCount?: number
): Promise<CryptoKey>;
/**
* Generate a hierarchical key structure
* @param masterPassword - Master password for the hierarchy
* @param path - Path components to derive child keys from
*/
generateHierarchicalKey(
masterPassword: string,
path: string[]
): Promise<{
masterKey: CryptoKey;
childKeys: { [key: string]: CryptoKey };
}>;
/**
* Generate a key from multiple inputs (e.g., password + salt + nonce)
* @param inputs - Array of input strings to combine
* @param salt - Salt for key derivation
* @param algorithm - Key derivation algorithm (PBKDF2 or Argon2)
*/
generateKeyFromMultipleInputs(
inputs: string[],
salt: Uint8Array,
algorithm?: "PBKDF2" | "Argon2"
): Promise<CryptoKey>;
/**
* Sign a text message or data string with configurable algorithms
* @param text - Text to sign
* @param privateKey - Private key for signing (ECDSA)
* @param algorithm - Signature algorithm to use (ECDSA, EdDSA, RSA-PSS)
*/
signTextWithAlgorithm(
text: string,
privateKey: CryptoKey,
algorithm?: "ECDSA" | "EdDSA" | "RSA-PSS"
): Promise<string>;
/**
* Verify a signed text message with configurable algorithms
* @param text - Text that was signed
* @param signatureB64 - Base64-encoded signature
* @param publicKey - Public key for verification (ECDSA)
* @param algorithm - Signature algorithm to use (ECDSA, EdDSA, RSA-PSS)
*/
verifyTextWithAlgorithm(
text: string,
signatureB64: string,
publicKey: CryptoKey,
algorithm?: "ECDSA" | "EdDSA" | "RSA-PSS"
): Promise<boolean>;
/**
* Create an HMAC signature using configurable hash algorithms
* @param data - Data to sign
* @param key - HMAC key
* @param hash - Hash algorithm (SHA-256, SHA-384, or SHA-512)
*/
signHMAC(data: string, key: CryptoKey, hash?: "SHA-256" | "SHA-384" | "SHA-512"): Promise<string>;
/**
* Verify an HMAC signature using configurable hash algorithms
* @param data - Data that was signed
* @param signatureB64 - Base64-encoded HMAC signature
* @param key - HMAC key
* @param hash - Hash algorithm (SHA-256, SHA-384, or SHA-512)
*/
verifyHMAC(
data: string,
signatureB64: string,
key: CryptoKey,
hash?: "SHA-256" | "SHA-384" | "SHA-512"
): Promise<boolean>;
/**
* @deprecated Poly1305 is not supported by standard Web Crypto API. Use signHMAC() instead.
* @param data - Data to authenticate
* @param key - Poly1305 key (should be 32 bytes)
*/
authenticatePoly1305(data: ArrayBuffer, key: CryptoKey): Promise<string>;
/**
* Secure random number generation with better entropy sources
* @param length - Number of bytes to generate
*/
secureRandom(length: number): Promise<Uint8Array>;
/**
* Clear the internal key cache
*/
clearKeyCache(): void;
/**
* Stop automatic cache cleanup interval
*/
stopAutoCleanup(): void;
// ═══════════════════════════ Post-Quantum Key Derivation ═══════════════════════════
/**
* Enhanced Argon2id KDF (quantum-resistant, GPU/ASIC resistant).
* Stronger than PBKDF2 for high-entropy passwords.
*
* @param password - Password to derive from
* @param salt - Random salt (16+ bytes recommended)
* @param options - Configuration object
* @param options.memory - Memory cost in KiB (default: 65536 = 64MB)
* @param options.iterations - Time cost (default: 3)
* @param options.parallelism - Parallelism factor (default: 1)
* @param options.keyLength - Output key length in bits (default: 256)
* @returns Derived AES key
*/
deriveKeyArgon2Enhanced(
password: string,
salt: Uint8Array,
options?: {
memory?: number;
iterations?: number;
parallelism?: number;
keyLength?: number;
}
): Promise<CryptoKey>;
/**
* SHA-3 based KDF (post-quantum collision-resistant).
* Alternative to PBKDF2/Argon2 using quantum-resistant SHA-3 hash.
*
* @param password - Password to derive from
* @param salt - Random salt
* @param iterations - KDF iterations (default: 50000)
* @param hash - Hash algorithm: 'SHA3-256' | 'SHA3-384' | 'SHA3-512'
* @param keyLength - Output key length in bits (default: 256)
* @returns Derived AES key
*/
deriveKeySHA3(
password: string,
iterations?: number,
algorithm?: "SHA3-256" | "SHA3-384" | "SHA3-512"
): Promise<CryptoKey>;
/**
* HKDF with SHA-3 (quantum-resistant key expansion).
* Suitable for deriving multiple independent keys from a master secret.
*
* @param secret - Input key material (IKM)
* @param salt - Optional salt (default: all zeros)
* @param info - Optional context/application-specific info
* @param keyLength - Output key length in bits (default: 256)
* @returns Derived AES key
*/
deriveKeyHKDFSHA3(
secret: Uint8Array,
salt?: Uint8Array,
info?: Uint8Array,
keyLength?: number
): Promise<CryptoKey>;
/**
* HKDF with SHA-256 (fallback variant).
*/
deriveKeyHKDFSHA2(
secret: Uint8Array,
salt?: Uint8Array,
info?: Uint8Array,
keyLength?: number
): Promise<CryptoKey>;
/**
* Key rotation: Derive new key with fresh salt.
* Enables periodic key rotation without data re-encryption (in some schemes).
*
* @param password - Original password
* @param newSalt - New salt for re-derivation
* @param method - KDF method: 'PBKDF2' | 'Argon2' | 'SHA3' | 'HKDF'
* @returns New derived key
*/
rotateKeyNew(
password: string,
newSalt: Uint8Array,
method?: "PBKDF2" | "Argon2" | "SHA3" | "HKDF"
): Promise<CryptoKey>;
/**
* Hierarchical key derivation: Create distinct keys for different purposes.
* Enables key structures where child keys are derived from a parent key.
*
* @param parentKey - Parent AES key
* @param childSalt - Context/application-specific salt
* @param purpose - Purpose string (e.g., 'encryption', 'signing', 'hmac')
* @returns Child derived key
*/
deriveChildKeyHierarchical(
parentKey: CryptoKey,
childSalt: Uint8Array,
purpose?: string
): Promise<CryptoKey>;
/**
* Secure key erasure: Overwrite sensitive key material in memory.
* Best-effort; true secure erasure depends on runtime guarantees.
*
* @param key - Key material to erase
*/
secureKeyErase(key: Uint8Array): void;
// ────────────────────── ECDH Key Exchange ──────────────────────
/**
* Generate an ECDH key pair for key exchange.
* @param curve - Elliptic curve to use (default: 'P-256')
*/
generateECDHKeyPair(curve?: string): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Export an ECDH public key to base64 for sharing.
*/
exportECDHPublicKey(publicKey: CryptoKey): Promise<string>;
/**
* Import an ECDH public key from base64.
* @param b64 - Base64 string of the public key
* @param curve - Curve used (default: 'P-256')
*/
importECDHPublicKey(b64: string, curve?: string): Promise<CryptoKey>;
/**
* Derive a shared secret using ECDH.
* @param privateKey - Your private key
* @param publicKey - The other party's public key
*/
deriveECDHSharedSecret(privateKey: CryptoKey, publicKey: CryptoKey): Promise<CryptoKey>;
/**
* Encrypt data automatically deriving an ECDH shared secret.
* @param data - Serializable data or string to encrypt
* @param privateKey - Sender's private key
* @param recipientPublicKey - Recipient's public key
*/
encryptWithECDH(data: any, privateKey: CryptoKey, recipientPublicKey: CryptoKey): Promise<string>;
/**
* Decrypt data automatically deriving an ECDH shared secret.
* @param b64 - Base64-encoded encrypted payload
* @param privateKey - Recipient's private key
* @param senderPublicKey - Sender's public key
*/
decryptWithECDH(b64: string, privateKey: CryptoKey, senderPublicKey: CryptoKey): Promise<any>;
/**
* Automatically serializes any JavaScript object or array to JSON before encrypting.
*/
encryptData(data: any, publicKey: CryptoKey): Promise<string>;
/**
* Decrypts the data and automatically parses it back into a JavaScript object.
*/
decryptData(b64: string, privateKey: CryptoKey): Promise<any>;
/**
* Import a public signing key from base64 (SPKI format)
* @param publicKeyB64 - Base64 encoded SPKI public key
* @param curve - Elliptic curve ('P-256' default, 'P-384')
*/
importPublicSigningKey(publicKeyB64: string, curve?: string): Promise<CryptoKey>;
/**
* Sign a text message or data string with ECDSA
* @param text - Text to sign
* @param privateKey - ECDSA private key
* @returns Base64-encoded detached signature
*/
signText(text: string, privateKey: CryptoKey): Promise<string>;
/**
* Verify a signed text message with ECDSA
* @param text - Text that was signed
* @param signatureB64 - Base64 signature
* @param publicKey - ECDSA public key
*/
verifyText(text: string, signatureB64: string, publicKey: CryptoKey): Promise<boolean>;
/**
* Create a detached signature for a file or blob
* @param fileOrBlob - File or Blob object to sign
* @param privateKey - ECDSA private key
*/
signFile(fileOrBlob: any, privateKey: CryptoKey): Promise<{ signatureB64: string; blob: any }>;
/**
* Verify a detached signature for a file or blob
* @param fileOrBlob - File or Blob object that was signed
* @param signatureB64 - Base64 signature
* @param publicKey - ECDSA public key
*/
verifyFile(fileOrBlob: any, signatureB64: string, publicKey: CryptoKey): Promise<boolean>;
// ────────────────────── JSON Web Encryption (JWE) ──────────────────────
/**
* Encrypts payload into a JWE Compact Serialization string.
* Uses RSA-OAEP-256 for key management and A256GCM for content encryption.
*
* @param payload - Data to encrypt (string or serializable object)
* @param publicKey - Recipient's RSA public key
* @param customHeaders - Additional JWE protected headers
* @returns JWE Token string
*/
encryptJWE(payload: any, publicKey: CryptoKey, customHeaders?: object): Promise<string>;
/**
* Decrypts a JWE Compact Serialization string.
*
* @param jweToken - JWE Token string
* @param privateKey - Recipient's RSA private key
* @returns Decrypted payload (parsed object if applicable, else string)
*/
decryptJWE(jweToken: string, privateKey: CryptoKey): Promise<any>;
}
// src/WebCryptPQC.d.ts
// Post-Quantum Cryptography type definitions
/**
* WebCryptPQC – Post-quantum key exchange and digital signatures
*
* Implements NIST PQC finalists:
* - Kyber: Lattice-based Key Encapsulation Mechanism (KEM)
* - Dilithium: Lattice-based Digital Signature Algorithm
*/
declare class WebCryptPQC {
/**
* Kyber security levels
*/
static readonly KYBER_512: "Kyber512";
static readonly KYBER_768: "Kyber768";
static readonly KYBER_1024: "Kyber1024";
/**
* Kyber parameters including key and ciphertext sizes
*/
static readonly KYBER_PARAMS: {
[key: string]: {
name: string;
securityLevel: string;
publicKeySize: number;
privateKeySize: number;
ciphertextSize: number;
sharedSecretSize: number;
};
};
/**
* Dilithium security levels
*/
static readonly DILITHIUM_2: "Dilithium2";
static readonly DILITHIUM_3: "Dilithium3";
static readonly DILITHIUM_5: "Dilithium5";
/**
* Dilithium parameters including key and signature sizes
*/
static readonly DILITHIUM_PARAMS: {
[key: string]: {
name: string;
securityLevel: string;
publicKeySize: number;
privateKeySize: number;
signatureSize: number;
};
};
/**
* SHA-3 hash algorithms
*/
static readonly HASH_SHA3_256: "SHA3-256";
static readonly HASH_SHA3_384: "SHA3-384";
static readonly HASH_SHA3_512: "SHA3-512";
/**
* Supported Kyber levels
*/
static readonly SUPPORTED_KYBER_LEVELS: string[];
/**
* Supported Dilithium levels
*/
static readonly SUPPORTED_DILITHIUM_LEVELS: string[];
/**
* Returns true if PQC module is running as a placeholder/stub.
*/
static isStub(): boolean;
/**
* Enable or disable stub testing mode for unit tests.
* @param allow Enable stub testing mode if true
*/
static enableStubTesting(allow?: boolean): void;
constructor();
// ─────────────────────── Kyber KEM ───────────────────────
/**
* Generate a Kyber key pair for key encapsulation.
* @param level - Kyber level: "Kyber512" | "Kyber768" | "Kyber1024" (default: Kyber768)
*/
generateKyberKeyPair(level?: string): Promise<{
publicKey: Uint8Array;
privateKey: Uint8Array;
}>;
/**
* Encapsulate: Create a shared secret and ciphertext using recipient's Kyber public key.
* @param kyberPublicKey - Recipient's Kyber public key
* @param level - Kyber level (default: Kyber768)
* @returns Ciphertext and derived shared secret
*/
kyberEncapsulate(
kyberPublicKey: Uint8Array,
level?: string
): Promise<{
ciphertext: Uint8Array;
sharedSecret: Uint8Array;
}>;
/**
* Decapsulate: Recover the shared secret using private key and ciphertext.
* @param ciphertext - Encapsulated ciphertext from kyberEncapsulate
* @param kyberPrivateKey - Own Kyber private key
* @param level - Kyber level (default: Kyber768)
* @returns The shared secret
*/
kyberDecapsulate(
ciphertext: Uint8Array,
kyberPrivateKey: Uint8Array,
level?: string
): Promise<Uint8Array>;
// ─────────────────────── Dilithium Signatures ───────────────────────
/**
* Generate a Dilithium key pair for digital signatures.
* @param level - Dilithium level: "Dilithium2" | "Dilithium3" | "Dilithium5" (default: Dilithium3)
*/
generateDilithiumKeyPair(level?: string): Promise<{
publicKey: Uint8Array;
privateKey: Uint8Array;
}>;
/**
* Sign a message using Dilithium private key.
* @param message - Message to sign (string or Uint8Array)
* @param dilithiumPrivateKey - Dilithium private key
* @param level - Dilithium level (default: Dilithium3)
* @returns Digital signature
*/
dilithiumSign(
message: string | Uint8Array,
dilithiumPrivateKey: Uint8Array,
level?: string
): Promise<Uint8Array>;
/**
* Verify a Dilithium signature.
* @param message - Original message (string or Uint8Array)
* @param signature - Signature from dilithiumSign
* @param dilithiumPublicKey - Dilithium public key
* @param level - Dilithium level (default: Dilithium3)
* @returns True if valid
*/
dilithiumVerify(
message: string | Uint8Array,
signature: Uint8Array,
dilithiumPublicKey: Uint8Array,
level?: string
): Promise<boolean>;
// ─────────────────────── Hybrid Encryption ───────────────────────
/**
* Hybrid encapsulation: Use both Kyber (PQC) and RSA-OAEP.
* Combines classical and post-quantum key encapsulation for maximum security.
*
* @param rsaPublicKey - RSA-4096 public key (classical)
* @param kyberPublicKey - Kyber public key (post-quantum)
* @param kyberLevel - Kyber level (default: Kyber768)
* @returns Shared secret and ciphertexts for both KEM schemes
*/
hybridEncapsulate(
rsaPublicKey: CryptoKey,
kyberPublicKey: Uint8Array,
kyberLevel?: string
): Promise<{
sharedSecret: Uint8Array;
kyberCiphertext: Uint8Array;
rsaWrappedSharedSecret: Uint8Array;
}>;
/**
* Hybrid decapsulation: Recover shared secret using both Kyber and RSA private keys.
* Falls back to Kyber alone if RSA decryption fails (provides forward secrecy).
*
* @param kyberCiphertext - From hybridEncapsulate
* @param rsaWrappedSharedSecret - From hybridEncapsulate
* @param rsaPrivateKey - RSA-4096 private key
* @param kyberPrivateKey - Kyber private key
* @param kyberLevel - Kyber level (default: Kyber768)
* @returns The hybrid shared secret
*/
hybridDecapsulate(
kyberCiphertext: Uint8Array,
rsaWrappedSharedSecret: Uint8Array,
rsaPrivateKey: CryptoKey,
kyberPrivateKey: Uint8Array,
kyberLevel?: string
): Promise<Uint8Array>;
// ─────────────────────── Key Serialization ───────────────────────
kyberPublicKeyToBase64(publicKey: Uint8Array): string;
kyberPublicKeyFromBase64(b64: string): Uint8Array;
kyberPrivateKeyToBase64(privateKey: Uint8Array): string;
kyberPrivateKeyFromBase64(b64: string): Uint8Array;
dilithiumPublicKeyToBase64(publicKey: Uint8Array): string;
dilithiumPublicKeyFromBase64(b64: string): Uint8Array;
dilithiumPrivateKeyToBase64(privateKey: Uint8Array): string;
dilithiumPrivateKeyFromBase64(b64: string): Uint8Array;
}
// src/_base64.js
// Stack-safe, high-performance Base64 encoding/decoding for Uint8Arrays and ArrayBuffers.
const CHUNK_SIZE = 32768; // 32KB chunks prevent call stack overflow on large buffers
/**
* Validates whether a string is valid Base64 formatted.
* @param {string} str
* @returns {boolean}
*/
function isValidBase64(str) {
if (typeof str !== "string" || str.length === 0) return false;
const clean = str.replace(/[\r\n\s]/g, "");
if (clean.length % 4 === 1) return false;
return /^[A-Za-z0-9+/]+={0,2}$/.test(clean);
}
/**
* Encodes an ArrayBuffer or Uint8Array to a Base64 string in stack-safe chunks.
* @param {ArrayBuffer|Uint8Array} buffer
* @returns {string} Base64 string
*/
function arrayBufferToBase64(buffer) {
const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
let binary = "";
for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
binary += String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK_SIZE));
}
return btoa(binary);
}
/**
* Decodes a Base64 string to an ArrayBuffer.
* @param {string} base64
* @returns {ArrayBuffer}
*/
function base64ToArrayBuffer(base64) {
if (typeof base64 !== "string") {
throw new TypeError("Base64 string expected");
}
let padded = base64.trim();
const mod = padded.length % 4;
if (mod > 0) {
padded += "=".repeat(4 - mod);
}
const bytes = Uint8Array.from(atob(padded), c => c.charCodeAt(0));
return bytes.buffer;
}
/**
* Decodes a Base64 string to a Uint8Array.
* @param {string} base64
* @returns {Uint8Array}
*/
function base64ToUint8Array(base64) {
if (typeof base64 !== "string") {
throw new TypeError("Base64 string expected");
}
let padded = base64.trim();
const mod = padded.length % 4;
if (mod > 0) {
padded += "=".repeat(4 - mod);
}
return Uint8Array.from(atob(padded), c => c.charCodeAt(0));
}
// src/_crypto.js
// Centralized Web Crypto API resolution helper for browser and Node.js
/**
* Returns the active Web Crypto API instance (with subtle property).
* Supports browser window, Web Workers, Node.js 18+, and edge runtimes.
*
* @returns {Crypto} Active crypto instance
* @throws {Error} If crypto.subtle is not available in the current environment
*/
function getCrypto() {
if (typeof globalThis !== "undefined" && globalThis.crypto && globalThis.crypto.subtle) {
return globalThis.crypto;
}
throw new Error("Web Crypto API (crypto.subtle) is not available in this environment");
}
export { WebCrypt as W, WebCryptAsym as a, WebCryptPQC as b, arrayBufferToBase64 as c, base64ToArrayBuffer as d, base64ToUint8Array as e, getCrypto as g, isValidBase64 as i };
+1116
dist/_crypto-B6690zvC.d.ts
// src/WebCrypt.d.ts
/**
* WebCrypt – Zero-dependency quantum-resistant AES-256-GCM encryption
*
* Supports:
* - Text encryption/decryption
* - Large file encryption/decryption (streaming)
* - WebRTC Insertable Streams E2EE (video + audio)
* - HMAC for message authentication
*
* Works in Browser, Node.js 18+, Deno, Cloudflare Workers
*/
declare class WebCrypt {
static readonly ALGORITHM: "AES-GCM";
static readonly KEY_LENGTH: 256;
static readonly IV_LENGTH: 12;
static readonly SALT_LENGTH: 16;
static readonly PBKDF2_ITERATIONS: number;
static readonly HASH_ALGORITHM: "SHA-256";
static readonly CHUNK_SIZE: number;
static readonly WEBRTC_SALT: Uint8Array;
static readonly DEFAULT_HMAC_SALT: Uint8Array;
/**
* Generates a cryptographically secure random salt for HMAC key derivation.
* @param length Salt length in bytes (default: 16)
*/
static generateHmacSalt(length?: number): Uint8Array;
/**
* Encrypts a string and returns Base64-encoded ciphertext
* @param text Plain text to encrypt
* @param password Password (or shared secret)
* @returns Base64 string (salt + iv + ciphertext)
*/
encryptText(text: string, password: string): Promise<string>;
/**
* Decrypts a Base64 string produced by encryptText()
* @param base64 Encrypted data from encryptText()
* @param password Must match encryption password
* @returns Original plain text
* @throws If password is wrong or data is corrupted
*/
decryptText(base64: string, password: string): Promise<string>;
/**
* Encrypts a File or Blob using streaming (low memory, handles huge files)
* @param file File or Blob to encrypt
* @param password Encryption password
* @param options Optional configuration object ({ parallelChunks?: number })
* @returns Object with encrypted Blob and suggested filename
*/
encryptFile(
file: File | Blob,
password: string,
options?: { parallelChunks?: number }
): Promise<{
blob: Blob;
filename: string;
}>;
/**
* Decrypts a .encrypted file produced by encryptFile()
* @param file Encrypted File or Blob
* @param password Must match encryption password
* @param options Optional configuration object ({ parallelChunks?: number })
* @returns Object with decrypted Blob and original filename
* @throws If password is wrong or file is corrupted
*/
decryptFile(
file: File | Blob,
password: string,
options?: { parallelChunks?: number }
): Promise<{
blob: Blob;
filename: string;
}>;
/**
* Creates an encryption transform for WebRTC Insertable Streams
* Use with RTCRtpSender.transform
* @param password Shared secret both peers must know
*/
createEncryptTransform(
password: string
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Creates a decryption transform for WebRTC Insertable Streams
* Use with RTCRtpReceiver.transform
* @param password Must match sender's password
*/
createDecryptTransform(
password: string
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Generates or derives an HMAC key.
* @param password Optional password for PBKDF2 derivation (if provided, uses 600_000 iterations).
* @param hash Hash algorithm (default: 'SHA-256').
* @param salt Optional salt for deterministic derivation.
* @returns Usable HMAC key.
*/
generateHmacKey(
password?: string,
hash?: "SHA-256" | "SHA-384" | "SHA-512",
salt?: Uint8Array | string
): Promise<CryptoKey>;
/**
* Computes HMAC on data.
* @param data Text or ArrayBuffer to authenticate.
* @param key HMAC key from generateHmacKey.
* @returns Base64-encoded HMAC tag.
*/
computeHmac(data: string | ArrayBuffer, key: CryptoKey): Promise<string>;
/**
* Verifies HMAC on data.
* @param data Text or ArrayBuffer to verify.
* @param hmac Base64-encoded HMAC tag to check.
* @param key HMAC key.
* @returns True if valid.
*/
verifyHmac(data: string | ArrayBuffer, hmac: string, key: CryptoKey): Promise<boolean>;
/**
* Generate a quantum-resistant HMAC key using SHA-3 hash.
* @param password Optional password for derivation
* @param hash Hash algorithm: 'SHA3-256' | 'SHA3-384' | 'SHA3-512' (default: SHA3-256)
* @param salt Optional salt for deterministic derivation.
* @param iterations Iterations count for SHA-3 KDF derivation (default: 10,000)
* @returns Usable HMAC key with SHA-3
*/
generateHmacKeySHA3(
password?: string,
hash?: "SHA3-256" | "SHA3-384" | "SHA3-512",
salt?: Uint8Array | string,
iterations?: number
): Promise<CryptoKey>;
/**
* Compute HMAC using SHA-3 (quantum-resistant).
* @param data Data to authenticate
* @param key HMAC key from generateHmacKeySHA3
* @returns Base64-encoded HMAC tag
*/
computeHmacSHA3(data: string | ArrayBuffer, key: CryptoKey): Promise<string>;
/**
* Verify HMAC using SHA-3 (quantum-resistant).
* @param data Data to verify
* @param hmac Base64-encoded HMAC tag
* @param key HMAC key
* @returns True if valid
*/
verifyHmacSHA3(data: string | ArrayBuffer, hmac: string, key: CryptoKey): Promise<boolean>;
/**
* Automatically serializes any JavaScript object or array to JSON before encrypting.
*/
encryptData(data: any, password: string): Promise<string>;
/**
* Decrypts the data and automatically parses it back into a JavaScript object.
*/
decryptData(base64: string, password: string): Promise<any>;
/**
* Utility to generate a cryptographically secure random password or key string.
*/
generateRandomPassword(length?: number): string;
/**
* Clear entire key cache.
*/
clearKeyCache(): void;
/**
* Stop automatic cache cleanup interval.
*/
stopAutoCleanup(): void;
}
// WebCryptAsym.d.ts
/**
* Asymmetric encryption utility using RSA-OAEP + AES-GCM hybrid encryption.
* Supports text, file (streaming), and WebRTC insertable streams.
*/
declare class WebCryptAsym {
/**
* RSA-OAEP algorithm parameters
*/
static readonly RSA_ALGORITHM: AlgorithmIdentifier;
/**
* Parameters for RSA key generation (4096-bit, SHA-256)
*/
static readonly RSA_KEY_PARAMS: RsaHashedKeyGenParams;
/**
* AES-GCM algorithm name
*/
static readonly AES_ALGORITHM: "AES-GCM";
/**
* AES key length (256 bits)
*/
static readonly AES_LENGTH: 256;
/**
* IV length for AES-GCM (12 bytes recommended)
*/
static readonly IV_LENGTH: 12;
/**
* Chunk size for file streaming (8 MB)
*/
static readonly CHUNK_SIZE: number;
/**
* Fixed salt-like identifier for WebRTC transforms
*/
static readonly WEBRTC_SALT: Uint8Array;
/**
* PBKDF2 algorithm name
*/
static readonly PBKDF2_ALGORITHM: "PBKDF2";
/**
* Default PBKDF2 hash algorithm
*/
static readonly PBKDF2_HASH: "SHA-256";
/**
* Default number of PBKDF2 iterations
*/
static readonly PBKDF2_ITERATIONS: number;
/**
* Argon2 algorithm name
*/
static readonly ARGON2_ALGORITHM: "Argon2id";
/**
* RSA-PSS algorithm name
*/
static readonly RSA_PSS_ALGORITHM: "RSA-PSS";
/**
* EdDSA algorithm name
*/
static readonly ED25519_ALGORITHM: "EdDSA";
/**
* Ed25519 curve name
*/
static readonly ED25519_CURVE: "Ed25519";
constructor();
/**
* Generate a new RSA-4096 key pair
*/
generateKeyPair(): Promise<CryptoKeyPair>;
/**
* Generate an ECDSA signing key pair
* @param curve - Supported curves: 'P-256' (default), 'P-384'
*/
generateSigningKeyPair(curve?: string): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Generate an EdDSA signing key pair
*/
generateEdDSASigningKeyPair(): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Generate an RSA-PSS signing key pair
* @param modulusLength - RSA key size in bits (default: 2048)
*/
generateRSAPSSigningKeyPair(modulusLength?: number): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Export public key to Base64-encoded SPKI format
*/
exportPublicKey(publicKey: CryptoKey): Promise<string>;
/**
* Export private key to Base64-encoded PKCS8 format
*/
exportPrivateKey(privateKey: CryptoKey): Promise<string>;
/**
* Import public key from Base64 SPKI string
*/
importPublicKey(b64: string): Promise<CryptoKey>;
/**
* Import private key from Base64 PKCS8 string
*/
importPrivateKey(b64: string): Promise<CryptoKey>;
/**
* Encrypt text using recipient's public key (hybrid: RSA-wrapped AES-GCM)
* @returns Base64-encoded encrypted data
*/
encryptText(text: string, publicKey: CryptoKey): Promise<string>;
/**
* Decrypt text using own private key
*/
decryptText(encryptedB64: string, privateKey: CryptoKey): Promise<string>;
/**
* Encrypt a file/blob using recipient's public key (streaming)
* @returns Object with encrypted Blob and suggested filename
*/
encryptFile(
fileOrBlob: Blob | File,
publicKey: CryptoKey,
options?: { parallelChunks?: number }
): Promise<{ blob: Blob; filename: string }>;
/**
* Decrypt an asymmetrically encrypted file/blob
* @returns Object with decrypted Blob and original filename
*/
decryptFile(
fileOrBlob: Blob | File,
privateKey: CryptoKey,
options?: { parallelChunks?: number }
): Promise<{ blob: Blob; filename: string }>;
/**
* Create an encryption transform function for WebRTC insertable streams
* Sends encrypted session key in the first frame.
*/
createEncryptTransform(
publicKey: CryptoKey
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Create a decryption transform function for WebRTC insertable streams
* Extracts session key from first frame and decrypts subsequent frames.
*/
createDecryptTransform(
privateKey: CryptoKey
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Create a hybrid encryption transform that supports both classical and post-quantum approaches
* @param publicKey - RSA public key for hybrid encryption
* @param usePostQuantum - Whether to use post-quantum hybrid approach
*/
createHybridEncryptTransform(
publicKey: CryptoKey,
usePostQuantum?: boolean
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Enhanced WebRTC transform with progress tracking
* @param publicKey - RSA public key for hybrid encryption
* @param onProgress - Callback function to report encryption progress
*/
createEncryptTransformWithProgress(
publicKey: CryptoKey,
onProgress?: (bytesProcessed: number) => void
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Encrypt a file with progress tracking
* @param fileOrBlob - File or Blob to encrypt
* @param publicKey - RSA public key for hybrid encryption
* @param onProgress - Callback function to report encryption progress
*/
encryptFileWithProgress(
fileOrBlob: Blob | File,
publicKey: CryptoKey,
onProgress?: (bytesProcessed: number) => void
): Promise<{ blob: Blob; filename: string }>;
/**
* Decrypt a file with progress tracking
* @param fileOrBlob - File or Blob to decrypt
* @param privateKey - RSA private key for hybrid decryption
* @param onProgress - Callback function to report decryption progress
*/
decryptFileWithProgress(
fileOrBlob: Blob | File,
privateKey: CryptoKey,
onProgress?: (bytesProcessed: number) => void
): Promise<{ blob: Blob; filename: string }>;
/**
* Derive a key using PBKDF2 with configurable parameters
* @param password - The password to derive the key from
* @param salt - Salt for the derivation
* @param iterations - Number of PBKDF2 iterations (default: 600000)
* @param hash - Hash algorithm (default: SHA-256)
* @param keyLength - Length of the derived key in bits
*/
deriveKeyPBKDF2(
password: string,
salt: Uint8Array,
iterations?: number,
hash?: string,
keyLength?: number
): Promise<CryptoKey>;
/**
* Derive a key using Argon2id (where supported)
* @param password - The password to derive the key from
* @param salt - Salt for the derivation
* @param options - Argon2 configuration options
*/
deriveKeyArgon2(
password: string,
salt: Uint8Array,
options?: {
iterations?: number;
memoryCost?: number;
parallelism?: number;
}
): Promise<CryptoKey>;
/**
* Generate a key for symmetric encryption using password-based derivation
* @param password - Password to derive the key from
* @param salt - Salt for key derivation
* @param algorithm - Key derivation algorithm (PBKDF2 or Argon2)
*/
generateKeyFromPassword(
password: string,
salt: Uint8Array,
algorithm?: "PBKDF2" | "Argon2"
): Promise<CryptoKey>;
/**
* Generate a new key for symmetric encryption using password-based derivation with key rotation
* @param password - Password to derive the key from
* @param salt - Salt for key derivation
* @param algorithm - Key derivation algorithm (PBKDF2 or Argon2)
* @param rotationCount - Rotation counter for key derivation
*/
generateRotatingKey(
password: string,
salt: Uint8Array,
algorithm?: "PBKDF2" | "Argon2",
rotationCount?: number
): Promise<CryptoKey>;
/**
* Generate a hierarchical key structure
* @param masterPassword - Master password for the hierarchy
* @param path - Path components to derive child keys from
*/
generateHierarchicalKey(
masterPassword: string,
path: string[]
): Promise<{
masterKey: CryptoKey;
childKeys: { [key: string]: CryptoKey };
}>;
/**
* Generate a key from multiple inputs (e.g., password + salt + nonce)
* @param inputs - Array of input strings to combine
* @param salt - Salt for key derivation
* @param algorithm - Key derivation algorithm (PBKDF2 or Argon2)
*/
generateKeyFromMultipleInputs(
inputs: string[],
salt: Uint8Array,
algorithm?: "PBKDF2" | "Argon2"
): Promise<CryptoKey>;
/**
* Sign a text message or data string with configurable algorithms
* @param text - Text to sign
* @param privateKey - Private key for signing (ECDSA)
* @param algorithm - Signature algorithm to use (ECDSA, EdDSA, RSA-PSS)
*/
signTextWithAlgorithm(
text: string,
privateKey: CryptoKey,
algorithm?: "ECDSA" | "EdDSA" | "RSA-PSS"
): Promise<string>;
/**
* Verify a signed text message with configurable algorithms
* @param text - Text that was signed
* @param signatureB64 - Base64-encoded signature
* @param publicKey - Public key for verification (ECDSA)
* @param algorithm - Signature algorithm to use (ECDSA, EdDSA, RSA-PSS)
*/
verifyTextWithAlgorithm(
text: string,
signatureB64: string,
publicKey: CryptoKey,
algorithm?: "ECDSA" | "EdDSA" | "RSA-PSS"
): Promise<boolean>;
/**
* Create an HMAC signature using configurable hash algorithms
* @param data - Data to sign
* @param key - HMAC key
* @param hash - Hash algorithm (SHA-256, SHA-384, or SHA-512)
*/
signHMAC(data: string, key: CryptoKey, hash?: "SHA-256" | "SHA-384" | "SHA-512"): Promise<string>;
/**
* Verify an HMAC signature using configurable hash algorithms
* @param data - Data that was signed
* @param signatureB64 - Base64-encoded HMAC signature
* @param key - HMAC key
* @param hash - Hash algorithm (SHA-256, SHA-384, or SHA-512)
*/
verifyHMAC(
data: string,
signatureB64: string,
key: CryptoKey,
hash?: "SHA-256" | "SHA-384" | "SHA-512"
): Promise<boolean>;
/**
* @deprecated Poly1305 is not supported by standard Web Crypto API. Use signHMAC() instead.
* @param data - Data to authenticate
* @param key - Poly1305 key (should be 32 bytes)
*/
authenticatePoly1305(data: ArrayBuffer, key: CryptoKey): Promise<string>;
/**
* Secure random number generation with better entropy sources
* @param length - Number of bytes to generate
*/
secureRandom(length: number): Promise<Uint8Array>;
/**
* Clear the internal key cache
*/
clearKeyCache(): void;
/**
* Stop automatic cache cleanup interval
*/
stopAutoCleanup(): void;
// ═══════════════════════════ Post-Quantum Key Derivation ═══════════════════════════
/**
* Enhanced Argon2id KDF (quantum-resistant, GPU/ASIC resistant).
* Stronger than PBKDF2 for high-entropy passwords.
*
* @param password - Password to derive from
* @param salt - Random salt (16+ bytes recommended)
* @param options - Configuration object
* @param options.memory - Memory cost in KiB (default: 65536 = 64MB)
* @param options.iterations - Time cost (default: 3)
* @param options.parallelism - Parallelism factor (default: 1)
* @param options.keyLength - Output key length in bits (default: 256)
* @returns Derived AES key
*/
deriveKeyArgon2Enhanced(
password: string,
salt: Uint8Array,
options?: {
memory?: number;
iterations?: number;
parallelism?: number;
keyLength?: number;
}
): Promise<CryptoKey>;
/**
* SHA-3 based KDF (post-quantum collision-resistant).
* Alternative to PBKDF2/Argon2 using quantum-resistant SHA-3 hash.
*
* @param password - Password to derive from
* @param salt - Random salt
* @param iterations - KDF iterations (default: 50000)
* @param hash - Hash algorithm: 'SHA3-256' | 'SHA3-384' | 'SHA3-512'
* @param keyLength - Output key length in bits (default: 256)
* @returns Derived AES key
*/
deriveKeySHA3(
password: string,
iterations?: number,
algorithm?: "SHA3-256" | "SHA3-384" | "SHA3-512"
): Promise<CryptoKey>;
/**
* HKDF with SHA-3 (quantum-resistant key expansion).
* Suitable for deriving multiple independent keys from a master secret.
*
* @param secret - Input key material (IKM)
* @param salt - Optional salt (default: all zeros)
* @param info - Optional context/application-specific info
* @param keyLength - Output key length in bits (default: 256)
* @returns Derived AES key
*/
deriveKeyHKDFSHA3(
secret: Uint8Array,
salt?: Uint8Array,
info?: Uint8Array,
keyLength?: number
): Promise<CryptoKey>;
/**
* HKDF with SHA-256 (fallback variant).
*/
deriveKeyHKDFSHA2(
secret: Uint8Array,
salt?: Uint8Array,
info?: Uint8Array,
keyLength?: number
): Promise<CryptoKey>;
/**
* Key rotation: Derive new key with fresh salt.
* Enables periodic key rotation without data re-encryption (in some schemes).
*
* @param password - Original password
* @param newSalt - New salt for re-derivation
* @param method - KDF method: 'PBKDF2' | 'Argon2' | 'SHA3' | 'HKDF'
* @returns New derived key
*/
rotateKeyNew(
password: string,
newSalt: Uint8Array,
method?: "PBKDF2" | "Argon2" | "SHA3" | "HKDF"
): Promise<CryptoKey>;
/**
* Hierarchical key derivation: Create distinct keys for different purposes.
* Enables key structures where child keys are derived from a parent key.
*
* @param parentKey - Parent AES key
* @param childSalt - Context/application-specific salt
* @param purpose - Purpose string (e.g., 'encryption', 'signing', 'hmac')
* @returns Child derived key
*/
deriveChildKeyHierarchical(
parentKey: CryptoKey,
childSalt: Uint8Array,
purpose?: string
): Promise<CryptoKey>;
/**
* Secure key erasure: Overwrite sensitive key material in memory.
* Best-effort; true secure erasure depends on runtime guarantees.
*
* @param key - Key material to erase
*/
secureKeyErase(key: Uint8Array): void;
// ────────────────────── ECDH Key Exchange ──────────────────────
/**
* Generate an ECDH key pair for key exchange.
* @param curve - Elliptic curve to use (default: 'P-256')
*/
generateECDHKeyPair(curve?: string): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Export an ECDH public key to base64 for sharing.
*/
exportECDHPublicKey(publicKey: CryptoKey): Promise<string>;
/**
* Import an ECDH public key from base64.
* @param b64 - Base64 string of the public key
* @param curve - Curve used (default: 'P-256')
*/
importECDHPublicKey(b64: string, curve?: string): Promise<CryptoKey>;
/**
* Derive a shared secret using ECDH.
* @param privateKey - Your private key
* @param publicKey - The other party's public key
*/
deriveECDHSharedSecret(privateKey: CryptoKey, publicKey: CryptoKey): Promise<CryptoKey>;
/**
* Encrypt data automatically deriving an ECDH shared secret.
* @param data - Serializable data or string to encrypt
* @param privateKey - Sender's private key
* @param recipientPublicKey - Recipient's public key
*/
encryptWithECDH(data: any, privateKey: CryptoKey, recipientPublicKey: CryptoKey): Promise<string>;
/**
* Decrypt data automatically deriving an ECDH shared secret.
* @param b64 - Base64-encoded encrypted payload
* @param privateKey - Recipient's private key
* @param senderPublicKey - Sender's public key
*/
decryptWithECDH(b64: string, privateKey: CryptoKey, senderPublicKey: CryptoKey): Promise<any>;
/**
* Automatically serializes any JavaScript object or array to JSON before encrypting.
*/
encryptData(data: any, publicKey: CryptoKey): Promise<string>;
/**
* Decrypts the data and automatically parses it back into a JavaScript object.
*/
decryptData(b64: string, privateKey: CryptoKey): Promise<any>;
/**
* Import a public signing key from base64 (SPKI format)
* @param publicKeyB64 - Base64 encoded SPKI public key
* @param curve - Elliptic curve ('P-256' default, 'P-384')
*/
importPublicSigningKey(publicKeyB64: string, curve?: string): Promise<CryptoKey>;
/**
* Sign a text message or data string with ECDSA
* @param text - Text to sign
* @param privateKey - ECDSA private key
* @returns Base64-encoded detached signature
*/
signText(text: string, privateKey: CryptoKey): Promise<string>;
/**
* Verify a signed text message with ECDSA
* @param text - Text that was signed
* @param signatureB64 - Base64 signature
* @param publicKey - ECDSA public key
*/
verifyText(text: string, signatureB64: string, publicKey: CryptoKey): Promise<boolean>;
/**
* Create a detached signature for a file or blob
* @param fileOrBlob - File or Blob object to sign
* @param privateKey - ECDSA private key
*/
signFile(fileOrBlob: any, privateKey: CryptoKey): Promise<{ signatureB64: string; blob: any }>;
/**
* Verify a detached signature for a file or blob
* @param fileOrBlob - File or Blob object that was signed
* @param signatureB64 - Base64 signature
* @param publicKey - ECDSA public key
*/
verifyFile(fileOrBlob: any, signatureB64: string, publicKey: CryptoKey): Promise<boolean>;
// ────────────────────── JSON Web Encryption (JWE) ──────────────────────
/**
* Encrypts payload into a JWE Compact Serialization string.
* Uses RSA-OAEP-256 for key management and A256GCM for content encryption.
*
* @param payload - Data to encrypt (string or serializable object)
* @param publicKey - Recipient's RSA public key
* @param customHeaders - Additional JWE protected headers
* @returns JWE Token string
*/
encryptJWE(payload: any, publicKey: CryptoKey, customHeaders?: object): Promise<string>;
/**
* Decrypts a JWE Compact Serialization string.
*
* @param jweToken - JWE Token string
* @param privateKey - Recipient's RSA private key
* @returns Decrypted payload (parsed object if applicable, else string)
*/
decryptJWE(jweToken: string, privateKey: CryptoKey): Promise<any>;
}
// src/WebCryptPQC.d.ts
// Post-Quantum Cryptography type definitions
/**
* WebCryptPQC – Post-quantum key exchange and digital signatures
*
* Implements NIST PQC finalists:
* - Kyber: Lattice-based Key Encapsulation Mechanism (KEM)
* - Dilithium: Lattice-based Digital Signature Algorithm
*/
declare class WebCryptPQC {
/**
* Kyber security levels
*/
static readonly KYBER_512: "Kyber512";
static readonly KYBER_768: "Kyber768";
static readonly KYBER_1024: "Kyber1024";
/**
* Kyber parameters including key and ciphertext sizes
*/
static readonly KYBER_PARAMS: {
[key: string]: {
name: string;
securityLevel: string;
publicKeySize: number;
privateKeySize: number;
ciphertextSize: number;
sharedSecretSize: number;
};
};
/**
* Dilithium security levels
*/
static readonly DILITHIUM_2: "Dilithium2";
static readonly DILITHIUM_3: "Dilithium3";
static readonly DILITHIUM_5: "Dilithium5";
/**
* Dilithium parameters including key and signature sizes
*/
static readonly DILITHIUM_PARAMS: {
[key: string]: {
name: string;
securityLevel: string;
publicKeySize: number;
privateKeySize: number;
signatureSize: number;
};
};
/**
* SHA-3 hash algorithms
*/
static readonly HASH_SHA3_256: "SHA3-256";
static readonly HASH_SHA3_384: "SHA3-384";
static readonly HASH_SHA3_512: "SHA3-512";
/**
* Supported Kyber levels
*/
static readonly SUPPORTED_KYBER_LEVELS: string[];
/**
* Supported Dilithium levels
*/
static readonly SUPPORTED_DILITHIUM_LEVELS: string[];
/**
* Returns true if PQC module is running as a placeholder/stub.
*/
static isStub(): boolean;
/**
* Enable or disable stub testing mode for unit tests.
* @param allow Enable stub testing mode if true
*/
static enableStubTesting(allow?: boolean): void;
constructor();
// ─────────────────────── Kyber KEM ───────────────────────
/**
* Generate a Kyber key pair for key encapsulation.
* @param level - Kyber level: "Kyber512" | "Kyber768" | "Kyber1024" (default: Kyber768)
*/
generateKyberKeyPair(level?: string): Promise<{
publicKey: Uint8Array;
privateKey: Uint8Array;
}>;
/**
* Encapsulate: Create a shared secret and ciphertext using recipient's Kyber public key.
* @param kyberPublicKey - Recipient's Kyber public key
* @param level - Kyber level (default: Kyber768)
* @returns Ciphertext and derived shared secret
*/
kyberEncapsulate(
kyberPublicKey: Uint8Array,
level?: string
): Promise<{
ciphertext: Uint8Array;
sharedSecret: Uint8Array;
}>;
/**
* Decapsulate: Recover the shared secret using private key and ciphertext.
* @param ciphertext - Encapsulated ciphertext from kyberEncapsulate
* @param kyberPrivateKey - Own Kyber private key
* @param level - Kyber level (default: Kyber768)
* @returns The shared secret
*/
kyberDecapsulate(
ciphertext: Uint8Array,
kyberPrivateKey: Uint8Array,
level?: string
): Promise<Uint8Array>;
// ─────────────────────── Dilithium Signatures ───────────────────────
/**
* Generate a Dilithium key pair for digital signatures.
* @param level - Dilithium level: "Dilithium2" | "Dilithium3" | "Dilithium5" (default: Dilithium3)
*/
generateDilithiumKeyPair(level?: string): Promise<{
publicKey: Uint8Array;
privateKey: Uint8Array;
}>;
/**
* Sign a message using Dilithium private key.
* @param message - Message to sign (string or Uint8Array)
* @param dilithiumPrivateKey - Dilithium private key
* @param level - Dilithium level (default: Dilithium3)
* @returns Digital signature
*/
dilithiumSign(
message: string | Uint8Array,
dilithiumPrivateKey: Uint8Array,
level?: string
): Promise<Uint8Array>;
/**
* Verify a Dilithium signature.
* @param message - Original message (string or Uint8Array)
* @param signature - Signature from dilithiumSign
* @param dilithiumPublicKey - Dilithium public key
* @param level - Dilithium level (default: Dilithium3)
* @returns True if valid
*/
dilithiumVerify(
message: string | Uint8Array,
signature: Uint8Array,
dilithiumPublicKey: Uint8Array,
level?: string
): Promise<boolean>;
// ─────────────────────── Hybrid Encryption ───────────────────────
/**
* Hybrid encapsulation: Use both Kyber (PQC) and RSA-OAEP.
* Combines classical and post-quantum key encapsulation for maximum security.
*
* @param rsaPublicKey - RSA-4096 public key (classical)
* @param kyberPublicKey - Kyber public key (post-quantum)
* @param kyberLevel - Kyber level (default: Kyber768)
* @returns Shared secret and ciphertexts for both KEM schemes
*/
hybridEncapsulate(
rsaPublicKey: CryptoKey,
kyberPublicKey: Uint8Array,
kyberLevel?: string
): Promise<{
sharedSecret: Uint8Array;
kyberCiphertext: Uint8Array;
rsaWrappedSharedSecret: Uint8Array;
}>;
/**
* Hybrid decapsulation: Recover shared secret using both Kyber and RSA private keys.
* Falls back to Kyber alone if RSA decryption fails (provides forward secrecy).
*
* @param kyberCiphertext - From hybridEncapsulate
* @param rsaWrappedSharedSecret - From hybridEncapsulate
* @param rsaPrivateKey - RSA-4096 private key
* @param kyberPrivateKey - Kyber private key
* @param kyberLevel - Kyber level (default: Kyber768)
* @returns The hybrid shared secret
*/
hybridDecapsulate(
kyberCiphertext: Uint8Array,
rsaWrappedSharedSecret: Uint8Array,
rsaPrivateKey: CryptoKey,
kyberPrivateKey: Uint8Array,
kyberLevel?: string
): Promise<Uint8Array>;
// ─────────────────────── Key Serialization ───────────────────────
kyberPublicKeyToBase64(publicKey: Uint8Array): string;
kyberPublicKeyFromBase64(b64: string): Uint8Array;
kyberPrivateKeyToBase64(privateKey: Uint8Array): string;
kyberPrivateKeyFromBase64(b64: string): Uint8Array;
dilithiumPublicKeyToBase64(publicKey: Uint8Array): string;
dilithiumPublicKeyFromBase64(b64: string): Uint8Array;
dilithiumPrivateKeyToBase64(privateKey: Uint8Array): string;
dilithiumPrivateKeyFromBase64(b64: string): Uint8Array;
}
// src/_base64.js
// Stack-safe, high-performance Base64 encoding/decoding for Uint8Arrays and ArrayBuffers.
const CHUNK_SIZE = 32768; // 32KB chunks prevent call stack overflow on large buffers
/**
* Validates whether a string is valid Base64 formatted.
* @param {string} str
* @returns {boolean}
*/
function isValidBase64(str) {
if (typeof str !== "string" || str.length === 0) return false;
const clean = str.replace(/[\r\n\s]/g, "");
if (clean.length % 4 === 1) return false;
return /^[A-Za-z0-9+/]+={0,2}$/.test(clean);
}
/**
* Encodes an ArrayBuffer or Uint8Array to a Base64 string in stack-safe chunks.
* @param {ArrayBuffer|Uint8Array} buffer
* @returns {string} Base64 string
*/
function arrayBufferToBase64(buffer) {
const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
let binary = "";
for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
binary += String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK_SIZE));
}
return btoa(binary);
}
/**
* Decodes a Base64 string to an ArrayBuffer.
* @param {string} base64
* @returns {ArrayBuffer}
*/
function base64ToArrayBuffer(base64) {
if (typeof base64 !== "string") {
throw new TypeError("Base64 string expected");
}
let padded = base64.trim();
const mod = padded.length % 4;
if (mod > 0) {
padded += "=".repeat(4 - mod);
}
const bytes = Uint8Array.from(atob(padded), c => c.charCodeAt(0));
return bytes.buffer;
}
/**
* Decodes a Base64 string to a Uint8Array.
* @param {string} base64
* @returns {Uint8Array}
*/
function base64ToUint8Array(base64) {
if (typeof base64 !== "string") {
throw new TypeError("Base64 string expected");
}
let padded = base64.trim();
const mod = padded.length % 4;
if (mod > 0) {
padded += "=".repeat(4 - mod);
}
return Uint8Array.from(atob(padded), c => c.charCodeAt(0));
}
// src/_crypto.js
// Centralized Web Crypto API resolution helper for browser and Node.js
/**
* Returns the active Web Crypto API instance (with subtle property).
* Supports browser window, Web Workers, Node.js 18+, and edge runtimes.
*
* @returns {Crypto} Active crypto instance
* @throws {Error} If crypto.subtle is not available in the current environment
*/
function getCrypto() {
if (typeof globalThis !== "undefined" && globalThis.crypto && globalThis.crypto.subtle) {
return globalThis.crypto;
}
throw new Error("Web Crypto API (crypto.subtle) is not available in this environment");
}
export { WebCrypt as W, WebCryptAsym as a, WebCryptPQC as b, arrayBufferToBase64 as c, base64ToArrayBuffer as d, base64ToUint8Array as e, getCrypto as g, isValidBase64 as i };
dist/mcp/server.cjs

Sorry, the diff of this file is too big to display

+799
dist/mcp/server.d.cts
import { c as arrayBufferToBase64, e as base64ToUint8Array, g as getCrypto, a as WebCryptAsym, b as WebCryptPQC, W as WebCrypt } from '../_crypto-B6690zvC.cjs';
// src/mcp/tools.js
// Tool schemas and metadata for WebCrypt MCP Server (PuterVision Standard)
const WEBCRYPT_MCP_TOOLS = [
{
name: "encrypt_payload",
description:
"Encrypt text, JSON objects, or files using AES-256-GCM symmetric or RSA-4096 hybrid asymmetric encryption.",
inputSchema: {
type: "object",
properties: {
mode: {
type: "string",
enum: ["symmetric", "asymmetric", "data"],
description:
"Encryption mode: 'symmetric' (password-based AES-256-GCM), 'asymmetric' (RSA-4096 public key), or 'data' (auto-JSON AES-256-GCM)",
default: "symmetric",
},
data: {
description: "Plain text, JSON serializable object, or Base64 binary string to encrypt",
},
password: {
type: "string",
description:
"Password for symmetric encryption (required for 'symmetric' and 'data' modes)",
},
public_key_jwk: {
type: "object",
description: "JWK-formatted RSA public key (required for 'asymmetric' mode)",
},
},
required: ["mode", "data"],
},
},
{
name: "decrypt_payload",
description: "Decrypt ciphertext produced by WebCrypt back into plaintext or JSON object.",
inputSchema: {
type: "object",
properties: {
mode: {
type: "string",
enum: ["symmetric", "asymmetric", "data"],
description: "Decryption mode: 'symmetric', 'asymmetric', or 'data'",
default: "symmetric",
},
ciphertext: {
type: "string",
description: "Base64-encoded encrypted string from encrypt_payload",
},
password: {
type: "string",
description:
"Password used during encryption (required for 'symmetric' and 'data' modes)",
},
private_key_jwk: {
type: "object",
description: "JWK-formatted RSA private key (required for 'asymmetric' mode)",
},
},
required: ["mode", "ciphertext"],
},
},
{
name: "manage_keys",
description:
"Generate, export, or import cryptographic keypairs (RSA-4096/2048, ECDH P-256/P-384, HMAC).",
inputSchema: {
type: "object",
properties: {
action: {
type: "string",
enum: ["generate", "generate_random_password"],
description: "Action to perform",
},
type: {
type: "string",
enum: ["rsa", "ecdh", "ecdsa", "rsa-pss", "hmac"],
description: "Key type to generate (for action: 'generate')",
},
modulusLength: {
type: "number",
enum: [2048, 4096],
default: 4096,
description: "RSA modulus length in bits",
},
namedCurve: {
type: "string",
enum: ["P-256", "P-384"],
default: "P-256",
description: "Elliptic curve for ECDH",
},
length: {
type: "number",
default: 32,
description: "Length for random password or key in bytes",
},
},
required: ["action"],
},
},
{
name: "crypto_hash",
description:
"Compute cryptographic hashes (SHA-256, SHA-384, SHA-512, SHA3-256, SHA3-384, SHA3-512).",
inputSchema: {
type: "object",
properties: {
algorithm: {
type: "string",
enum: ["SHA-256", "SHA-384", "SHA-512", "SHA3-256", "SHA3-384", "SHA3-512"],
default: "SHA-256",
description: "Hash algorithm",
},
data: {
type: "string",
description: "Text data to hash",
},
encoding: {
type: "string",
enum: ["hex", "base64"],
default: "hex",
description: "Output digest encoding",
},
},
required: ["data"],
},
},
{
name: "sign_verify",
description:
"Create or verify digital signatures and HMAC authentication tags (ECDSA, RSA-PSS, HMAC, HMAC-SHA3).",
inputSchema: {
type: "object",
properties: {
action: {
type: "string",
enum: ["sign", "verify"],
description: "Action to perform: 'sign' or 'verify'",
},
algorithm: {
type: "string",
enum: ["ECDSA", "RSA-PSS", "HMAC", "HMAC-SHA3"],
default: "ECDSA",
description: "Signature or MAC algorithm",
},
data: {
type: "string",
description: "Message data to sign or verify",
},
signature: {
type: "string",
description: "Base64 signature tag (required for action: 'verify')",
},
password: {
type: "string",
description: "Password for HMAC key derivation (used with HMAC algorithms)",
},
key_jwk: {
type: "object",
description: "JWK formatted key for signing (private) or verifying (public)",
},
},
required: ["action", "data"],
},
},
{
name: "pqc_kem_sign",
description:
"Post-Quantum Cryptography operations (Kyber KEM, Dilithium signatures, and Hybrid classical+PQC KEM).",
inputSchema: {
type: "object",
properties: {
action: {
type: "string",
enum: [
"generate_kyber_keypair",
"kyber_encapsulate",
"kyber_decapsulate",
"hybrid_encapsulate",
"hybrid_decapsulate",
"generate_dilithium_keypair",
"dilithium_sign",
"dilithium_verify",
],
description: "PQC action to perform",
},
level: {
type: "string",
enum: ["Kyber512", "Kyber768", "Kyber1024", "Dilithium2", "Dilithium3", "Dilithium5"],
default: "Kyber768",
description: "Security level for Kyber or Dilithium",
},
public_key_b64: {
type: "string",
description: "Base64 encoded Kyber or Dilithium public key",
},
private_key_b64: {
type: "string",
description: "Base64 encoded Kyber or Dilithium private key",
},
ciphertext_b64: {
type: "string",
description: "Base64 encoded Kyber ciphertext (for decapsulate)",
},
rsa_public_key_jwk: {
type: "object",
description: "JWK RSA public key for hybrid encapsulate",
},
rsa_private_key_jwk: {
type: "object",
description: "JWK RSA private key for hybrid decapsulate",
},
rsa_wrapped_secret_b64: {
type: "string",
description: "Base64 RSA wrapped secret for hybrid decapsulate",
},
data: {
type: "string",
description: "Text message to sign or verify with Dilithium",
},
signature_b64: {
type: "string",
description: "Base64 Dilithium signature to verify",
},
},
required: ["action"],
},
},
];
// src/mcp/handlers.js
// Tool execution handlers for WebCrypt MCP Server
let _wc, _asym, _pqc;
function getWC() {
return _wc || (_wc = new WebCrypt());
}
function getAsym() {
return _asym || (_asym = new WebCryptAsym());
}
function getPQC() {
if (!_pqc) {
_pqc = new WebCryptPQC();
WebCryptPQC.enableStubTesting(true);
}
return _pqc;
}
async function handleToolCall(name, args = {}) {
switch (name) {
case "encrypt_payload": {
const mode = args.mode || "symmetric";
if (mode === "symmetric") {
if (!args.password)
throw new Error("Missing 'password' parameter for symmetric encryption");
const plaintext = typeof args.data === "string" ? args.data : JSON.stringify(args.data);
const ciphertext = await getWC().encryptText(plaintext, args.password);
return { ciphertext, mode: "symmetric" };
} else if (mode === "data") {
if (!args.password) throw new Error("Missing 'password' parameter for data encryption");
const ciphertext = await getWC().encryptData(args.data, args.password);
return { ciphertext, mode: "data" };
} else if (mode === "asymmetric") {
if (!args.public_key_jwk)
throw new Error("Missing 'public_key_jwk' parameter for asymmetric encryption");
const crypto = getCrypto();
const publicKey = await crypto.subtle.importKey(
"jwk",
args.public_key_jwk,
WebCryptAsym.RSA_ALGORITHM,
true,
["encrypt"]
);
const plaintext = typeof args.data === "string" ? args.data : JSON.stringify(args.data);
const ciphertext = await getAsym().encryptText(plaintext, publicKey);
return { ciphertext, mode: "asymmetric" };
}
throw new Error(`Unsupported mode: ${mode}`);
}
case "decrypt_payload": {
const mode = args.mode || "symmetric";
if (!args.ciphertext) throw new Error("Missing 'ciphertext' parameter");
if (mode === "symmetric") {
if (!args.password)
throw new Error("Missing 'password' parameter for symmetric decryption");
const decrypted = await getWC().decryptText(args.ciphertext, args.password);
return { data: decrypted, plaintext: decrypted, mode: "symmetric" };
} else if (mode === "data") {
if (!args.password) throw new Error("Missing 'password' parameter for data decryption");
const decrypted = await getWC().decryptData(args.ciphertext, args.password);
return { data: decrypted, mode: "data" };
} else if (mode === "asymmetric") {
if (!args.private_key_jwk)
throw new Error("Missing 'private_key_jwk' parameter for asymmetric decryption");
const crypto = getCrypto();
const privateKey = await crypto.subtle.importKey(
"jwk",
args.private_key_jwk,
WebCryptAsym.RSA_ALGORITHM,
true,
["decrypt"]
);
const decrypted = await getAsym().decryptText(args.ciphertext, privateKey);
return { data: decrypted, plaintext: decrypted, mode: "asymmetric" };
}
throw new Error(`Unsupported mode: ${mode}`);
}
case "manage_keys": {
const action = args.action;
if (action === "generate_random_password") {
const password = getWC().generateRandomPassword(args.length || 32);
return { password, length: args.length || 32 };
} else if (action === "generate") {
const type = args.type || "rsa";
const crypto = getCrypto();
if (type === "rsa") {
const modulusLength = args.modulusLength || 4096;
const keyPair = await getAsym().generateKeyPair(modulusLength);
const publicKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.publicKey);
const privateKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.privateKey);
return { type: "rsa", modulusLength, publicKey: publicKeyJwk, privateKey: privateKeyJwk };
} else if (type === "ecdh") {
const namedCurve = args.namedCurve || "P-256";
const keyPair = await getAsym().generateECDHKeyPair(namedCurve);
const publicKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.publicKey);
const privateKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.privateKey);
return { type: "ecdh", namedCurve, publicKey: publicKeyJwk, privateKey: privateKeyJwk };
} else if (type === "ecdsa") {
const namedCurve = args.namedCurve || "P-256";
const keyPair = await getAsym().generateSigningKeyPair(namedCurve);
const publicKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.publicKey);
const privateKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.privateKey);
return { type: "ecdsa", namedCurve, publicKey: publicKeyJwk, privateKey: privateKeyJwk };
} else if (type === "rsa-pss") {
const modulusLength = args.modulusLength || 2048;
const keyPair = await crypto.subtle.generateKey(
{
name: "RSA-PSS",
modulusLength,
publicExponent: new Uint8Array([1, 0, 1]),
hash: "SHA-256",
},
true,
["sign", "verify"]
);
const publicKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.publicKey);
const privateKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.privateKey);
return {
type: "rsa-pss",
modulusLength,
publicKey: publicKeyJwk,
privateKey: privateKeyJwk,
};
} else if (type === "hmac") {
const rawBytes = crypto.getRandomValues(new Uint8Array(args.length || 32));
return { type: "hmac", key_b64: arrayBufferToBase64(rawBytes) };
}
throw new Error(`Unsupported key type: ${type}`);
}
throw new Error(`Unsupported action: ${action}`);
}
case "crypto_hash": {
if (!args.data) throw new Error("Missing 'data' parameter");
const algo = args.algorithm || "SHA-256";
const encoding = args.encoding || "hex";
const crypto = getCrypto();
const inputBytes = new TextEncoder().encode(args.data);
let digestBytes;
if (algo.startsWith("SHA3-")) {
const bitLength = parseInt(algo.replace("SHA3-", ""), 10) || 256;
digestBytes = await getPQC()._sha3Hash(inputBytes, bitLength);
} else {
const buffer = await crypto.subtle.digest(algo, inputBytes);
digestBytes = new Uint8Array(buffer);
}
let digest;
if (encoding === "hex") {
digest = Array.from(digestBytes, b => b.toString(16).padStart(2, "0")).join("");
} else {
digest = arrayBufferToBase64(digestBytes);
}
return { algorithm: algo, encoding, digest };
}
case "sign_verify": {
const action = args.action;
const algo = args.algorithm || "ECDSA";
const data = args.data;
if (!data) throw new Error("Missing 'data' parameter");
if (action === "sign") {
if (algo === "HMAC") {
if (!args.password) throw new Error("Missing 'password' for HMAC");
const key = await getWC().generateHmacKey(args.password);
const tag = await getWC().computeHmac(data, key);
return { algorithm: algo, signature: tag };
} else if (algo === "HMAC-SHA3") {
if (!args.password) throw new Error("Missing 'password' for HMAC-SHA3");
const key = await getWC().generateHmacKeySHA3(args.password);
const tag = await getWC().computeHmacSHA3(data, key);
return { algorithm: algo, signature: tag };
} else if (algo === "ECDSA" || algo === "RSA-PSS") {
if (!args.key_jwk) throw new Error(`Missing 'key_jwk' for ${algo} signing`);
const crypto = getCrypto();
const importParams =
algo === "ECDSA"
? { name: "ECDSA", namedCurve: args.key_jwk.crv || "P-256" }
: { name: "RSA-PSS", hash: "SHA-256" };
const privateKey = await crypto.subtle.importKey(
"jwk",
args.key_jwk,
importParams,
false,
["sign"]
);
const sig = await getAsym().signTextWithAlgorithm(data, privateKey, algo);
return { algorithm: algo, signature: sig };
}
throw new Error(`Unsupported sign algorithm: ${algo}`);
} else if (action === "verify") {
if (!args.signature) throw new Error("Missing 'signature' parameter to verify");
if (algo === "HMAC") {
if (!args.password) throw new Error("Missing 'password' for HMAC");
const key = await getWC().generateHmacKey(args.password);
const valid = await getWC().verifyHmac(data, args.signature, key);
return { algorithm: algo, valid };
} else if (algo === "HMAC-SHA3") {
if (!args.password) throw new Error("Missing 'password' for HMAC-SHA3");
const key = await getWC().generateHmacKeySHA3(args.password);
const valid = await getWC().verifyHmacSHA3(data, args.signature, key);
return { algorithm: algo, valid };
} else if (algo === "ECDSA" || algo === "RSA-PSS") {
if (!args.key_jwk) throw new Error(`Missing 'key_jwk' for ${algo} verification`);
const crypto = getCrypto();
const importParams =
algo === "ECDSA"
? { name: "ECDSA", namedCurve: args.key_jwk.crv || "P-256" }
: { name: "RSA-PSS", hash: "SHA-256" };
const publicKey = await crypto.subtle.importKey(
"jwk",
args.key_jwk,
importParams,
false,
["verify"]
);
const valid = await getAsym().verifyTextWithAlgorithm(
data,
args.signature,
publicKey,
algo
);
return { algorithm: algo, valid };
}
throw new Error(`Unsupported verify algorithm: ${algo}`);
}
throw new Error(`Unsupported action: ${action}`);
}
case "pqc_kem_sign": {
const action = args.action;
const level = args.level || "Kyber768";
const pqcInst = getPQC();
if (action === "generate_kyber_keypair") {
const keyPair = await pqcInst.generateKyberKeyPair(level);
const pubB64 = pqcInst.kyberPublicKeyToBase64(keyPair.publicKey);
const privB64 = pqcInst.kyberPrivateKeyToBase64(keyPair.privateKey);
return {
algorithm: "Kyber",
level,
public_key_b64: pubB64,
private_key_b64: privB64,
publicKey_b64: pubB64,
privateKey_b64: privB64,
};
} else if (action === "kyber_encapsulate") {
const pubKeyB64 = args.public_key_b64 || args.publicKey_b64;
if (!pubKeyB64) throw new Error("Missing 'public_key_b64'");
const pubKey = pqcInst.kyberPublicKeyFromBase64(pubKeyB64);
const { ciphertext, sharedSecret } = await pqcInst.kyberEncapsulate(pubKey, level);
const ctB64 = arrayBufferToBase64(ciphertext);
const ssB64 = arrayBufferToBase64(sharedSecret);
return {
level,
ciphertext_b64: ctB64,
shared_secret_b64: ssB64,
ciphertextB64: ctB64,
sharedSecret_b64: ssB64,
sharedSecretB64: ssB64,
};
} else if (action === "kyber_decapsulate") {
const ctB64 = args.ciphertext_b64 || args.ciphertextB64;
const privKeyB64 = args.private_key_b64 || args.privateKey_b64;
if (!ctB64 || !privKeyB64) {
throw new Error("Missing 'ciphertext_b64' or 'private_key_b64'");
}
const ciphertext = base64ToUint8Array(ctB64);
const privKey = pqcInst.kyberPrivateKeyFromBase64(privKeyB64);
const sharedSecret = await pqcInst.kyberDecapsulate(ciphertext, privKey, level);
const ssB64 = arrayBufferToBase64(sharedSecret);
return {
level,
shared_secret_b64: ssB64,
sharedSecret_b64: ssB64,
sharedSecretB64: ssB64,
};
} else if (action === "hybrid_encapsulate") {
const pubKeyB64 = args.public_key_b64 || args.publicKey_b64;
const rsaPubKeyJwk = args.rsa_public_key_jwk || args.rsaPublicKeyJwk;
if (!rsaPubKeyJwk || !pubKeyB64) {
throw new Error("Missing 'rsa_public_key_jwk' or 'public_key_b64'");
}
const crypto = getCrypto();
const rsaPubKey = await crypto.subtle.importKey(
"jwk",
rsaPubKeyJwk,
WebCryptAsym.RSA_ALGORITHM,
true,
["encrypt"]
);
const kyberPubKey = pqcInst.kyberPublicKeyFromBase64(pubKeyB64);
const result = await pqcInst.hybridEncapsulate(rsaPubKey, kyberPubKey, level);
const ssB64 = arrayBufferToBase64(result.sharedSecret);
const ctB64 = arrayBufferToBase64(result.kyberCiphertext);
const rsaWrappedB64 = arrayBufferToBase64(result.rsaWrappedSharedSecret);
return {
level,
shared_secret_b64: ssB64,
sharedSecret_b64: ssB64,
kyber_ciphertext_b64: ctB64,
kyberCiphertext_b64: ctB64,
rsa_wrapped_secret_b64: rsaWrappedB64,
rsaWrappedSecret_b64: rsaWrappedB64,
};
} else if (action === "hybrid_decapsulate") {
const rsaPrivKeyJwk = args.rsa_private_key_jwk || args.rsaPrivateKeyJwk;
const privKeyB64 = args.private_key_b64 || args.privateKey_b64;
const kyberCtB64 = args.kyber_ciphertext_b64 || args.kyberCiphertext_b64;
const rsaWrappedB64 = args.rsa_wrapped_secret_b64 || args.rsaWrappedSecret_b64;
if (!rsaPrivKeyJwk || !privKeyB64 || !kyberCtB64 || !rsaWrappedB64) {
throw new Error("Missing required parameters for hybrid_decapsulate");
}
const crypto = getCrypto();
const rsaPrivKey = await crypto.subtle.importKey(
"jwk",
rsaPrivKeyJwk,
WebCryptAsym.RSA_ALGORITHM,
true,
["decrypt"]
);
const kyberPrivKey = pqcInst.kyberPrivateKeyFromBase64(privKeyB64);
const kyberCiphertext = base64ToUint8Array(kyberCtB64);
const rsaWrappedSecret = base64ToUint8Array(rsaWrappedB64);
const sharedSecret = await pqcInst.hybridDecapsulate(
kyberCiphertext,
rsaWrappedSecret,
rsaPrivKey,
kyberPrivKey,
level
);
const ssB64 = arrayBufferToBase64(sharedSecret);
return {
level,
shared_secret_b64: ssB64,
sharedSecret_b64: ssB64,
};
} else if (action === "generate_dilithium_keypair") {
const dilithiumLevel = args.level || "Dilithium3";
const keyPair = await pqcInst.generateDilithiumKeyPair(dilithiumLevel);
const pubB64 = pqcInst.dilithiumPublicKeyToBase64(keyPair.publicKey);
const privB64 = pqcInst.dilithiumPrivateKeyToBase64(keyPair.privateKey);
return {
algorithm: "Dilithium",
level: dilithiumLevel,
public_key_b64: pubB64,
private_key_b64: privB64,
publicKey_b64: pubB64,
privateKey_b64: privB64,
};
} else if (action === "dilithium_sign") {
const privKeyB64 = args.private_key_b64 || args.privateKey_b64;
if (!args.data || !privKeyB64) {
throw new Error("Missing 'data' or 'private_key_b64'");
}
const privKey = pqcInst.dilithiumPrivateKeyFromBase64(privKeyB64);
const sig = await pqcInst.dilithiumSign(args.data, privKey, args.level || "Dilithium3");
const sigB64 = arrayBufferToBase64(sig);
return {
algorithm: "Dilithium",
level: args.level || "Dilithium3",
signature_b64: sigB64,
signatureB64: sigB64,
};
} else if (action === "dilithium_verify") {
const pubKeyB64 = args.public_key_b64 || args.publicKey_b64;
const sigB64 = args.signature_b64 || args.signatureB64;
if (!args.data || !sigB64 || !pubKeyB64) {
throw new Error("Missing 'data', 'signature_b64', or 'public_key_b64'");
}
const pubKey = pqcInst.dilithiumPublicKeyFromBase64(pubKeyB64);
const sig = base64ToUint8Array(sigB64);
const valid = await pqcInst.dilithiumVerify(
args.data,
sig,
pubKey,
args.level || "Dilithium3"
);
return {
algorithm: "Dilithium",
valid,
};
}
throw new Error(`Unsupported PQC action: ${action}`);
}
default:
throw new Error(`Unknown tool: ${name}`);
}
}
// src/mcp/server.js
// Zero-dependency Model Context Protocol (MCP) Server for WebCrypt
// PuterVision Standard - stdio JSON-RPC 2.0 transport
class WebCryptMCPServer {
constructor(options = {}) {
this.name = "webcrypt";
this.version = "1.0.0";
this.tools = WEBCRYPT_MCP_TOOLS;
this.in = options.stdin || process.stdin;
this.out = options.stdout || process.stdout;
}
async handleMessage(message) {
if (!message || typeof message !== "object") return null;
const { id, method, params } = message;
// Handle notifications (no id)
if (id === undefined || id === null) {
if (method === "notifications/initialized") {
// Initialization acknowledged
return null;
}
return null;
}
try {
switch (method) {
case "initialize": {
return {
jsonrpc: "2.0",
id,
result: {
protocolVersion: "2024-11-05",
capabilities: {
tools: {},
},
serverInfo: {
name: this.name,
version: this.version,
},
},
};
}
case "ping": {
return {
jsonrpc: "2.0",
id,
result: {},
};
}
case "tools/list": {
return {
jsonrpc: "2.0",
id,
result: {
tools: this.tools,
},
};
}
case "tools/call": {
const toolName = params?.name;
const toolArgs = params?.arguments || {};
const result = await handleToolCall(toolName, toolArgs);
return {
jsonrpc: "2.0",
id,
result: {
content: [
{
type: "text",
text: typeof result === "string" ? result : JSON.stringify(result, null, 2),
},
],
},
};
}
default: {
return {
jsonrpc: "2.0",
id,
error: {
code: -32601,
message: `Method not found: ${method}`,
},
};
}
}
} catch (err) {
return {
jsonrpc: "2.0",
id,
result: {
content: [
{
type: "text",
text: `Error: ${err.message || String(err)}`,
},
],
isError: true,
},
};
}
}
send(response) {
if (!response) return;
const json = JSON.stringify(response);
this.out.write(`${json}\n`);
}
start() {
let buffer = "";
// Handle stream errors gracefully (e.g. EPIPE on abrupt client disconnect)
if (typeof this.in.on === "function") this.in.on("error", () => {});
if (typeof this.out.on === "function") this.out.on("error", () => {});
this.in.on("data", async chunk => {
buffer += chunk.toString("utf-8");
while (true) {
const lineEnd = buffer.indexOf("\n");
if (lineEnd === -1) break;
const line = buffer.slice(0, lineEnd).trim();
buffer = buffer.slice(lineEnd + 1);
if (line.length === 0) continue;
try {
const message = JSON.parse(line);
const response = await this.handleMessage(message);
if (response) {
this.send(response);
}
} catch (parseErr) {
this.send({
jsonrpc: "2.0",
id: null,
error: {
code: -32700,
message: `Parse error: ${parseErr.message}`,
},
});
}
}
});
this.in.on("end", () => {
// Stream ended
});
}
}
function startMCPServer() {
const server = new WebCryptMCPServer();
server.start();
return server;
}
export { WebCryptMCPServer, startMCPServer };
+799
dist/mcp/server.d.ts
import { c as arrayBufferToBase64, e as base64ToUint8Array, g as getCrypto, a as WebCryptAsym, b as WebCryptPQC, W as WebCrypt } from '../_crypto-B6690zvC.js';
// src/mcp/tools.js
// Tool schemas and metadata for WebCrypt MCP Server (PuterVision Standard)
const WEBCRYPT_MCP_TOOLS = [
{
name: "encrypt_payload",
description:
"Encrypt text, JSON objects, or files using AES-256-GCM symmetric or RSA-4096 hybrid asymmetric encryption.",
inputSchema: {
type: "object",
properties: {
mode: {
type: "string",
enum: ["symmetric", "asymmetric", "data"],
description:
"Encryption mode: 'symmetric' (password-based AES-256-GCM), 'asymmetric' (RSA-4096 public key), or 'data' (auto-JSON AES-256-GCM)",
default: "symmetric",
},
data: {
description: "Plain text, JSON serializable object, or Base64 binary string to encrypt",
},
password: {
type: "string",
description:
"Password for symmetric encryption (required for 'symmetric' and 'data' modes)",
},
public_key_jwk: {
type: "object",
description: "JWK-formatted RSA public key (required for 'asymmetric' mode)",
},
},
required: ["mode", "data"],
},
},
{
name: "decrypt_payload",
description: "Decrypt ciphertext produced by WebCrypt back into plaintext or JSON object.",
inputSchema: {
type: "object",
properties: {
mode: {
type: "string",
enum: ["symmetric", "asymmetric", "data"],
description: "Decryption mode: 'symmetric', 'asymmetric', or 'data'",
default: "symmetric",
},
ciphertext: {
type: "string",
description: "Base64-encoded encrypted string from encrypt_payload",
},
password: {
type: "string",
description:
"Password used during encryption (required for 'symmetric' and 'data' modes)",
},
private_key_jwk: {
type: "object",
description: "JWK-formatted RSA private key (required for 'asymmetric' mode)",
},
},
required: ["mode", "ciphertext"],
},
},
{
name: "manage_keys",
description:
"Generate, export, or import cryptographic keypairs (RSA-4096/2048, ECDH P-256/P-384, HMAC).",
inputSchema: {
type: "object",
properties: {
action: {
type: "string",
enum: ["generate", "generate_random_password"],
description: "Action to perform",
},
type: {
type: "string",
enum: ["rsa", "ecdh", "ecdsa", "rsa-pss", "hmac"],
description: "Key type to generate (for action: 'generate')",
},
modulusLength: {
type: "number",
enum: [2048, 4096],
default: 4096,
description: "RSA modulus length in bits",
},
namedCurve: {
type: "string",
enum: ["P-256", "P-384"],
default: "P-256",
description: "Elliptic curve for ECDH",
},
length: {
type: "number",
default: 32,
description: "Length for random password or key in bytes",
},
},
required: ["action"],
},
},
{
name: "crypto_hash",
description:
"Compute cryptographic hashes (SHA-256, SHA-384, SHA-512, SHA3-256, SHA3-384, SHA3-512).",
inputSchema: {
type: "object",
properties: {
algorithm: {
type: "string",
enum: ["SHA-256", "SHA-384", "SHA-512", "SHA3-256", "SHA3-384", "SHA3-512"],
default: "SHA-256",
description: "Hash algorithm",
},
data: {
type: "string",
description: "Text data to hash",
},
encoding: {
type: "string",
enum: ["hex", "base64"],
default: "hex",
description: "Output digest encoding",
},
},
required: ["data"],
},
},
{
name: "sign_verify",
description:
"Create or verify digital signatures and HMAC authentication tags (ECDSA, RSA-PSS, HMAC, HMAC-SHA3).",
inputSchema: {
type: "object",
properties: {
action: {
type: "string",
enum: ["sign", "verify"],
description: "Action to perform: 'sign' or 'verify'",
},
algorithm: {
type: "string",
enum: ["ECDSA", "RSA-PSS", "HMAC", "HMAC-SHA3"],
default: "ECDSA",
description: "Signature or MAC algorithm",
},
data: {
type: "string",
description: "Message data to sign or verify",
},
signature: {
type: "string",
description: "Base64 signature tag (required for action: 'verify')",
},
password: {
type: "string",
description: "Password for HMAC key derivation (used with HMAC algorithms)",
},
key_jwk: {
type: "object",
description: "JWK formatted key for signing (private) or verifying (public)",
},
},
required: ["action", "data"],
},
},
{
name: "pqc_kem_sign",
description:
"Post-Quantum Cryptography operations (Kyber KEM, Dilithium signatures, and Hybrid classical+PQC KEM).",
inputSchema: {
type: "object",
properties: {
action: {
type: "string",
enum: [
"generate_kyber_keypair",
"kyber_encapsulate",
"kyber_decapsulate",
"hybrid_encapsulate",
"hybrid_decapsulate",
"generate_dilithium_keypair",
"dilithium_sign",
"dilithium_verify",
],
description: "PQC action to perform",
},
level: {
type: "string",
enum: ["Kyber512", "Kyber768", "Kyber1024", "Dilithium2", "Dilithium3", "Dilithium5"],
default: "Kyber768",
description: "Security level for Kyber or Dilithium",
},
public_key_b64: {
type: "string",
description: "Base64 encoded Kyber or Dilithium public key",
},
private_key_b64: {
type: "string",
description: "Base64 encoded Kyber or Dilithium private key",
},
ciphertext_b64: {
type: "string",
description: "Base64 encoded Kyber ciphertext (for decapsulate)",
},
rsa_public_key_jwk: {
type: "object",
description: "JWK RSA public key for hybrid encapsulate",
},
rsa_private_key_jwk: {
type: "object",
description: "JWK RSA private key for hybrid decapsulate",
},
rsa_wrapped_secret_b64: {
type: "string",
description: "Base64 RSA wrapped secret for hybrid decapsulate",
},
data: {
type: "string",
description: "Text message to sign or verify with Dilithium",
},
signature_b64: {
type: "string",
description: "Base64 Dilithium signature to verify",
},
},
required: ["action"],
},
},
];
// src/mcp/handlers.js
// Tool execution handlers for WebCrypt MCP Server
let _wc, _asym, _pqc;
function getWC() {
return _wc || (_wc = new WebCrypt());
}
function getAsym() {
return _asym || (_asym = new WebCryptAsym());
}
function getPQC() {
if (!_pqc) {
_pqc = new WebCryptPQC();
WebCryptPQC.enableStubTesting(true);
}
return _pqc;
}
async function handleToolCall(name, args = {}) {
switch (name) {
case "encrypt_payload": {
const mode = args.mode || "symmetric";
if (mode === "symmetric") {
if (!args.password)
throw new Error("Missing 'password' parameter for symmetric encryption");
const plaintext = typeof args.data === "string" ? args.data : JSON.stringify(args.data);
const ciphertext = await getWC().encryptText(plaintext, args.password);
return { ciphertext, mode: "symmetric" };
} else if (mode === "data") {
if (!args.password) throw new Error("Missing 'password' parameter for data encryption");
const ciphertext = await getWC().encryptData(args.data, args.password);
return { ciphertext, mode: "data" };
} else if (mode === "asymmetric") {
if (!args.public_key_jwk)
throw new Error("Missing 'public_key_jwk' parameter for asymmetric encryption");
const crypto = getCrypto();
const publicKey = await crypto.subtle.importKey(
"jwk",
args.public_key_jwk,
WebCryptAsym.RSA_ALGORITHM,
true,
["encrypt"]
);
const plaintext = typeof args.data === "string" ? args.data : JSON.stringify(args.data);
const ciphertext = await getAsym().encryptText(plaintext, publicKey);
return { ciphertext, mode: "asymmetric" };
}
throw new Error(`Unsupported mode: ${mode}`);
}
case "decrypt_payload": {
const mode = args.mode || "symmetric";
if (!args.ciphertext) throw new Error("Missing 'ciphertext' parameter");
if (mode === "symmetric") {
if (!args.password)
throw new Error("Missing 'password' parameter for symmetric decryption");
const decrypted = await getWC().decryptText(args.ciphertext, args.password);
return { data: decrypted, plaintext: decrypted, mode: "symmetric" };
} else if (mode === "data") {
if (!args.password) throw new Error("Missing 'password' parameter for data decryption");
const decrypted = await getWC().decryptData(args.ciphertext, args.password);
return { data: decrypted, mode: "data" };
} else if (mode === "asymmetric") {
if (!args.private_key_jwk)
throw new Error("Missing 'private_key_jwk' parameter for asymmetric decryption");
const crypto = getCrypto();
const privateKey = await crypto.subtle.importKey(
"jwk",
args.private_key_jwk,
WebCryptAsym.RSA_ALGORITHM,
true,
["decrypt"]
);
const decrypted = await getAsym().decryptText(args.ciphertext, privateKey);
return { data: decrypted, plaintext: decrypted, mode: "asymmetric" };
}
throw new Error(`Unsupported mode: ${mode}`);
}
case "manage_keys": {
const action = args.action;
if (action === "generate_random_password") {
const password = getWC().generateRandomPassword(args.length || 32);
return { password, length: args.length || 32 };
} else if (action === "generate") {
const type = args.type || "rsa";
const crypto = getCrypto();
if (type === "rsa") {
const modulusLength = args.modulusLength || 4096;
const keyPair = await getAsym().generateKeyPair(modulusLength);
const publicKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.publicKey);
const privateKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.privateKey);
return { type: "rsa", modulusLength, publicKey: publicKeyJwk, privateKey: privateKeyJwk };
} else if (type === "ecdh") {
const namedCurve = args.namedCurve || "P-256";
const keyPair = await getAsym().generateECDHKeyPair(namedCurve);
const publicKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.publicKey);
const privateKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.privateKey);
return { type: "ecdh", namedCurve, publicKey: publicKeyJwk, privateKey: privateKeyJwk };
} else if (type === "ecdsa") {
const namedCurve = args.namedCurve || "P-256";
const keyPair = await getAsym().generateSigningKeyPair(namedCurve);
const publicKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.publicKey);
const privateKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.privateKey);
return { type: "ecdsa", namedCurve, publicKey: publicKeyJwk, privateKey: privateKeyJwk };
} else if (type === "rsa-pss") {
const modulusLength = args.modulusLength || 2048;
const keyPair = await crypto.subtle.generateKey(
{
name: "RSA-PSS",
modulusLength,
publicExponent: new Uint8Array([1, 0, 1]),
hash: "SHA-256",
},
true,
["sign", "verify"]
);
const publicKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.publicKey);
const privateKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.privateKey);
return {
type: "rsa-pss",
modulusLength,
publicKey: publicKeyJwk,
privateKey: privateKeyJwk,
};
} else if (type === "hmac") {
const rawBytes = crypto.getRandomValues(new Uint8Array(args.length || 32));
return { type: "hmac", key_b64: arrayBufferToBase64(rawBytes) };
}
throw new Error(`Unsupported key type: ${type}`);
}
throw new Error(`Unsupported action: ${action}`);
}
case "crypto_hash": {
if (!args.data) throw new Error("Missing 'data' parameter");
const algo = args.algorithm || "SHA-256";
const encoding = args.encoding || "hex";
const crypto = getCrypto();
const inputBytes = new TextEncoder().encode(args.data);
let digestBytes;
if (algo.startsWith("SHA3-")) {
const bitLength = parseInt(algo.replace("SHA3-", ""), 10) || 256;
digestBytes = await getPQC()._sha3Hash(inputBytes, bitLength);
} else {
const buffer = await crypto.subtle.digest(algo, inputBytes);
digestBytes = new Uint8Array(buffer);
}
let digest;
if (encoding === "hex") {
digest = Array.from(digestBytes, b => b.toString(16).padStart(2, "0")).join("");
} else {
digest = arrayBufferToBase64(digestBytes);
}
return { algorithm: algo, encoding, digest };
}
case "sign_verify": {
const action = args.action;
const algo = args.algorithm || "ECDSA";
const data = args.data;
if (!data) throw new Error("Missing 'data' parameter");
if (action === "sign") {
if (algo === "HMAC") {
if (!args.password) throw new Error("Missing 'password' for HMAC");
const key = await getWC().generateHmacKey(args.password);
const tag = await getWC().computeHmac(data, key);
return { algorithm: algo, signature: tag };
} else if (algo === "HMAC-SHA3") {
if (!args.password) throw new Error("Missing 'password' for HMAC-SHA3");
const key = await getWC().generateHmacKeySHA3(args.password);
const tag = await getWC().computeHmacSHA3(data, key);
return { algorithm: algo, signature: tag };
} else if (algo === "ECDSA" || algo === "RSA-PSS") {
if (!args.key_jwk) throw new Error(`Missing 'key_jwk' for ${algo} signing`);
const crypto = getCrypto();
const importParams =
algo === "ECDSA"
? { name: "ECDSA", namedCurve: args.key_jwk.crv || "P-256" }
: { name: "RSA-PSS", hash: "SHA-256" };
const privateKey = await crypto.subtle.importKey(
"jwk",
args.key_jwk,
importParams,
false,
["sign"]
);
const sig = await getAsym().signTextWithAlgorithm(data, privateKey, algo);
return { algorithm: algo, signature: sig };
}
throw new Error(`Unsupported sign algorithm: ${algo}`);
} else if (action === "verify") {
if (!args.signature) throw new Error("Missing 'signature' parameter to verify");
if (algo === "HMAC") {
if (!args.password) throw new Error("Missing 'password' for HMAC");
const key = await getWC().generateHmacKey(args.password);
const valid = await getWC().verifyHmac(data, args.signature, key);
return { algorithm: algo, valid };
} else if (algo === "HMAC-SHA3") {
if (!args.password) throw new Error("Missing 'password' for HMAC-SHA3");
const key = await getWC().generateHmacKeySHA3(args.password);
const valid = await getWC().verifyHmacSHA3(data, args.signature, key);
return { algorithm: algo, valid };
} else if (algo === "ECDSA" || algo === "RSA-PSS") {
if (!args.key_jwk) throw new Error(`Missing 'key_jwk' for ${algo} verification`);
const crypto = getCrypto();
const importParams =
algo === "ECDSA"
? { name: "ECDSA", namedCurve: args.key_jwk.crv || "P-256" }
: { name: "RSA-PSS", hash: "SHA-256" };
const publicKey = await crypto.subtle.importKey(
"jwk",
args.key_jwk,
importParams,
false,
["verify"]
);
const valid = await getAsym().verifyTextWithAlgorithm(
data,
args.signature,
publicKey,
algo
);
return { algorithm: algo, valid };
}
throw new Error(`Unsupported verify algorithm: ${algo}`);
}
throw new Error(`Unsupported action: ${action}`);
}
case "pqc_kem_sign": {
const action = args.action;
const level = args.level || "Kyber768";
const pqcInst = getPQC();
if (action === "generate_kyber_keypair") {
const keyPair = await pqcInst.generateKyberKeyPair(level);
const pubB64 = pqcInst.kyberPublicKeyToBase64(keyPair.publicKey);
const privB64 = pqcInst.kyberPrivateKeyToBase64(keyPair.privateKey);
return {
algorithm: "Kyber",
level,
public_key_b64: pubB64,
private_key_b64: privB64,
publicKey_b64: pubB64,
privateKey_b64: privB64,
};
} else if (action === "kyber_encapsulate") {
const pubKeyB64 = args.public_key_b64 || args.publicKey_b64;
if (!pubKeyB64) throw new Error("Missing 'public_key_b64'");
const pubKey = pqcInst.kyberPublicKeyFromBase64(pubKeyB64);
const { ciphertext, sharedSecret } = await pqcInst.kyberEncapsulate(pubKey, level);
const ctB64 = arrayBufferToBase64(ciphertext);
const ssB64 = arrayBufferToBase64(sharedSecret);
return {
level,
ciphertext_b64: ctB64,
shared_secret_b64: ssB64,
ciphertextB64: ctB64,
sharedSecret_b64: ssB64,
sharedSecretB64: ssB64,
};
} else if (action === "kyber_decapsulate") {
const ctB64 = args.ciphertext_b64 || args.ciphertextB64;
const privKeyB64 = args.private_key_b64 || args.privateKey_b64;
if (!ctB64 || !privKeyB64) {
throw new Error("Missing 'ciphertext_b64' or 'private_key_b64'");
}
const ciphertext = base64ToUint8Array(ctB64);
const privKey = pqcInst.kyberPrivateKeyFromBase64(privKeyB64);
const sharedSecret = await pqcInst.kyberDecapsulate(ciphertext, privKey, level);
const ssB64 = arrayBufferToBase64(sharedSecret);
return {
level,
shared_secret_b64: ssB64,
sharedSecret_b64: ssB64,
sharedSecretB64: ssB64,
};
} else if (action === "hybrid_encapsulate") {
const pubKeyB64 = args.public_key_b64 || args.publicKey_b64;
const rsaPubKeyJwk = args.rsa_public_key_jwk || args.rsaPublicKeyJwk;
if (!rsaPubKeyJwk || !pubKeyB64) {
throw new Error("Missing 'rsa_public_key_jwk' or 'public_key_b64'");
}
const crypto = getCrypto();
const rsaPubKey = await crypto.subtle.importKey(
"jwk",
rsaPubKeyJwk,
WebCryptAsym.RSA_ALGORITHM,
true,
["encrypt"]
);
const kyberPubKey = pqcInst.kyberPublicKeyFromBase64(pubKeyB64);
const result = await pqcInst.hybridEncapsulate(rsaPubKey, kyberPubKey, level);
const ssB64 = arrayBufferToBase64(result.sharedSecret);
const ctB64 = arrayBufferToBase64(result.kyberCiphertext);
const rsaWrappedB64 = arrayBufferToBase64(result.rsaWrappedSharedSecret);
return {
level,
shared_secret_b64: ssB64,
sharedSecret_b64: ssB64,
kyber_ciphertext_b64: ctB64,
kyberCiphertext_b64: ctB64,
rsa_wrapped_secret_b64: rsaWrappedB64,
rsaWrappedSecret_b64: rsaWrappedB64,
};
} else if (action === "hybrid_decapsulate") {
const rsaPrivKeyJwk = args.rsa_private_key_jwk || args.rsaPrivateKeyJwk;
const privKeyB64 = args.private_key_b64 || args.privateKey_b64;
const kyberCtB64 = args.kyber_ciphertext_b64 || args.kyberCiphertext_b64;
const rsaWrappedB64 = args.rsa_wrapped_secret_b64 || args.rsaWrappedSecret_b64;
if (!rsaPrivKeyJwk || !privKeyB64 || !kyberCtB64 || !rsaWrappedB64) {
throw new Error("Missing required parameters for hybrid_decapsulate");
}
const crypto = getCrypto();
const rsaPrivKey = await crypto.subtle.importKey(
"jwk",
rsaPrivKeyJwk,
WebCryptAsym.RSA_ALGORITHM,
true,
["decrypt"]
);
const kyberPrivKey = pqcInst.kyberPrivateKeyFromBase64(privKeyB64);
const kyberCiphertext = base64ToUint8Array(kyberCtB64);
const rsaWrappedSecret = base64ToUint8Array(rsaWrappedB64);
const sharedSecret = await pqcInst.hybridDecapsulate(
kyberCiphertext,
rsaWrappedSecret,
rsaPrivKey,
kyberPrivKey,
level
);
const ssB64 = arrayBufferToBase64(sharedSecret);
return {
level,
shared_secret_b64: ssB64,
sharedSecret_b64: ssB64,
};
} else if (action === "generate_dilithium_keypair") {
const dilithiumLevel = args.level || "Dilithium3";
const keyPair = await pqcInst.generateDilithiumKeyPair(dilithiumLevel);
const pubB64 = pqcInst.dilithiumPublicKeyToBase64(keyPair.publicKey);
const privB64 = pqcInst.dilithiumPrivateKeyToBase64(keyPair.privateKey);
return {
algorithm: "Dilithium",
level: dilithiumLevel,
public_key_b64: pubB64,
private_key_b64: privB64,
publicKey_b64: pubB64,
privateKey_b64: privB64,
};
} else if (action === "dilithium_sign") {
const privKeyB64 = args.private_key_b64 || args.privateKey_b64;
if (!args.data || !privKeyB64) {
throw new Error("Missing 'data' or 'private_key_b64'");
}
const privKey = pqcInst.dilithiumPrivateKeyFromBase64(privKeyB64);
const sig = await pqcInst.dilithiumSign(args.data, privKey, args.level || "Dilithium3");
const sigB64 = arrayBufferToBase64(sig);
return {
algorithm: "Dilithium",
level: args.level || "Dilithium3",
signature_b64: sigB64,
signatureB64: sigB64,
};
} else if (action === "dilithium_verify") {
const pubKeyB64 = args.public_key_b64 || args.publicKey_b64;
const sigB64 = args.signature_b64 || args.signatureB64;
if (!args.data || !sigB64 || !pubKeyB64) {
throw new Error("Missing 'data', 'signature_b64', or 'public_key_b64'");
}
const pubKey = pqcInst.dilithiumPublicKeyFromBase64(pubKeyB64);
const sig = base64ToUint8Array(sigB64);
const valid = await pqcInst.dilithiumVerify(
args.data,
sig,
pubKey,
args.level || "Dilithium3"
);
return {
algorithm: "Dilithium",
valid,
};
}
throw new Error(`Unsupported PQC action: ${action}`);
}
default:
throw new Error(`Unknown tool: ${name}`);
}
}
// src/mcp/server.js
// Zero-dependency Model Context Protocol (MCP) Server for WebCrypt
// PuterVision Standard - stdio JSON-RPC 2.0 transport
class WebCryptMCPServer {
constructor(options = {}) {
this.name = "webcrypt";
this.version = "1.0.0";
this.tools = WEBCRYPT_MCP_TOOLS;
this.in = options.stdin || process.stdin;
this.out = options.stdout || process.stdout;
}
async handleMessage(message) {
if (!message || typeof message !== "object") return null;
const { id, method, params } = message;
// Handle notifications (no id)
if (id === undefined || id === null) {
if (method === "notifications/initialized") {
// Initialization acknowledged
return null;
}
return null;
}
try {
switch (method) {
case "initialize": {
return {
jsonrpc: "2.0",
id,
result: {
protocolVersion: "2024-11-05",
capabilities: {
tools: {},
},
serverInfo: {
name: this.name,
version: this.version,
},
},
};
}
case "ping": {
return {
jsonrpc: "2.0",
id,
result: {},
};
}
case "tools/list": {
return {
jsonrpc: "2.0",
id,
result: {
tools: this.tools,
},
};
}
case "tools/call": {
const toolName = params?.name;
const toolArgs = params?.arguments || {};
const result = await handleToolCall(toolName, toolArgs);
return {
jsonrpc: "2.0",
id,
result: {
content: [
{
type: "text",
text: typeof result === "string" ? result : JSON.stringify(result, null, 2),
},
],
},
};
}
default: {
return {
jsonrpc: "2.0",
id,
error: {
code: -32601,
message: `Method not found: ${method}`,
},
};
}
}
} catch (err) {
return {
jsonrpc: "2.0",
id,
result: {
content: [
{
type: "text",
text: `Error: ${err.message || String(err)}`,
},
],
isError: true,
},
};
}
}
send(response) {
if (!response) return;
const json = JSON.stringify(response);
this.out.write(`${json}\n`);
}
start() {
let buffer = "";
// Handle stream errors gracefully (e.g. EPIPE on abrupt client disconnect)
if (typeof this.in.on === "function") this.in.on("error", () => {});
if (typeof this.out.on === "function") this.out.on("error", () => {});
this.in.on("data", async chunk => {
buffer += chunk.toString("utf-8");
while (true) {
const lineEnd = buffer.indexOf("\n");
if (lineEnd === -1) break;
const line = buffer.slice(0, lineEnd).trim();
buffer = buffer.slice(lineEnd + 1);
if (line.length === 0) continue;
try {
const message = JSON.parse(line);
const response = await this.handleMessage(message);
if (response) {
this.send(response);
}
} catch (parseErr) {
this.send({
jsonrpc: "2.0",
id: null,
error: {
code: -32700,
message: `Parse error: ${parseErr.message}`,
},
});
}
}
});
this.in.on("end", () => {
// Stream ended
});
}
}
function startMCPServer() {
const server = new WebCryptMCPServer();
server.start();
return server;
}
export { WebCryptMCPServer, startMCPServer };
dist/mcp/server.js

Sorry, the diff of this file is too big to display

+45
glama.json
{
"$schema": "https://glama.ai/mcp/schemas/server.json",
"name": "webcrypt",
"title": "WebCrypt MCP Server",
"description": "Zero-dependency Web Cryptography & AI Agent Tooling Suite for AES-256-GCM symmetric encryption, RSA-4096 hybrid encryption, digital signatures, cryptographic hashes, and post-quantum cryptography.",
"maintainers": ["putervision"],
"author": "PuterVision",
"license": "MIT",
"repository": "https://github.com/putervision/webcrypt",
"homepage": "https://putervision.github.io/webcrypt/",
"website": "https://putervision.github.io/webcrypt/",
"categories": ["developer-tools", "ai-agents", "security", "cryptography"],
"tags": [
"mcp",
"model-context-protocol",
"cryptography",
"encryption",
"aes-256-gcm",
"rsa-4096",
"digital-signatures",
"post-quantum",
"ai-agents",
"security-vault",
"cursor",
"claude-code",
"antigravity",
"windsurf"
],
"keywords": [
"mcp",
"model-context-protocol",
"cryptography",
"encryption",
"aes-256-gcm",
"rsa-4096",
"digital-signatures",
"post-quantum",
"ai-agents",
"security-vault",
"cursor",
"claude-code",
"antigravity",
"windsurf"
]
}
+24
manifest.json
{
"manifest_version": "0.2",
"name": "webcrypt",
"version": "1.0.0",
"description": "Zero-dependency Web Cryptography & AI Agent Tooling Suite (AES-256-GCM, RSA-4096, PQC KEM/Sign, stdio MCP Server).",
"author": {
"name": "PuterVision"
},
"homepage": "https://putervision.github.io/webcrypt/",
"server": {
"type": "node",
"entry_point": "./bin/webcrypt-mcp.js",
"mcp_config": {
"command": "node",
"args": ["${__dirname}/bin/webcrypt-mcp.js"],
"env": {}
}
},
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/putervision/webcrypt.git"
}
}
+38
server.json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"name": "io.github.putervision/webcrypt",
"version": "1.0.0",
"title": "WebCrypt MCP Server",
"description": "Zero-dependency Web Cryptography & AI Agent Tooling Suite providing AES-256-GCM encryption, RSA-4096 hybrid public keys, digital signatures, cryptographic hashes, and post-quantum KEM.",
"publisher": "PuterVision",
"license": "MIT",
"websiteUrl": "https://putervision.github.io/webcrypt/",
"status": "active",
"icons": [
{
"src": "https://putervision.github.io/webcrypt/webcrypt-icon.png",
"mimeType": "image/png",
"sizes": ["512x512"]
}
],
"repository": {
"type": "git",
"url": "https://github.com/putervision/webcrypt",
"source": "github"
},
"bugs": {
"url": "https://github.com/putervision/webcrypt/issues"
},
"packages": [
{
"registryType": "npm",
"identifier": "webcrypt",
"version": "1.0.0",
"transport": {
"type": "stdio"
},
"executable": "webcrypt",
"args": ["mcp"]
}
]
}
+65
src/_base64.js
// src/_base64.js
// Stack-safe, high-performance Base64 encoding/decoding for Uint8Arrays and ArrayBuffers.
const CHUNK_SIZE = 32768; // 32KB chunks prevent call stack overflow on large buffers
/**
* Validates whether a string is valid Base64 formatted.
* @param {string} str
* @returns {boolean}
*/
export function isValidBase64(str) {
if (typeof str !== "string" || str.length === 0) return false;
const clean = str.replace(/[\r\n\s]/g, "");
if (clean.length % 4 === 1) return false;
return /^[A-Za-z0-9+/]+={0,2}$/.test(clean);
}
/**
* Encodes an ArrayBuffer or Uint8Array to a Base64 string in stack-safe chunks.
* @param {ArrayBuffer|Uint8Array} buffer
* @returns {string} Base64 string
*/
export function arrayBufferToBase64(buffer) {
const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
let binary = "";
for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
binary += String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK_SIZE));
}
return btoa(binary);
}
/**
* Decodes a Base64 string to an ArrayBuffer.
* @param {string} base64
* @returns {ArrayBuffer}
*/
export function base64ToArrayBuffer(base64) {
if (typeof base64 !== "string") {
throw new TypeError("Base64 string expected");
}
let padded = base64.trim();
const mod = padded.length % 4;
if (mod > 0) {
padded += "=".repeat(4 - mod);
}
const bytes = Uint8Array.from(atob(padded), c => c.charCodeAt(0));
return bytes.buffer;
}
/**
* Decodes a Base64 string to a Uint8Array.
* @param {string} base64
* @returns {Uint8Array}
*/
export function base64ToUint8Array(base64) {
if (typeof base64 !== "string") {
throw new TypeError("Base64 string expected");
}
let padded = base64.trim();
const mod = padded.length % 4;
if (mod > 0) {
padded += "=".repeat(4 - mod);
}
return Uint8Array.from(atob(padded), c => c.charCodeAt(0));
}
+17
src/_crypto.js
// src/_crypto.js
// Centralized Web Crypto API resolution helper for browser and Node.js
/**
* Returns the active Web Crypto API instance (with subtle property).
* Supports browser window, Web Workers, Node.js 18+, and edge runtimes.
*
* @returns {Crypto} Active crypto instance
* @throws {Error} If crypto.subtle is not available in the current environment
*/
export function getCrypto() {
if (typeof globalThis !== "undefined" && globalThis.crypto && globalThis.crypto.subtle) {
return globalThis.crypto;
}
throw new Error("Web Crypto API (crypto.subtle) is not available in this environment");
}
+180
src/cli/doctor.js
// src/cli/doctor.js
// Health check and diagnostic tool for WebCrypt and MCP environments
import fs from "fs";
import path from "path";
import os from "os";
import { getCrypto } from "../_crypto.js";
import { getRegistry, pruneStaleProjects } from "./registry.js";
export async function runDoctor(targetDir = process.cwd(), options = {}) {
const isJson = options.json || false;
const checks = [];
function check(label, passed, details) {
checks.push({ label, passed, details });
if (!isJson) {
console.log(` ${passed ? "✅" : "❌"} ${label}: ${details}`);
}
}
if (!isJson) {
console.log(`\n🩺 Running WebCrypt health diagnostics for: ${targetDir}\n`);
}
// 1. Node.js Runtime
const nodeVer = process.version;
const major = parseInt(nodeVer.slice(1).split(".")[0], 10);
check(
"Node.js Runtime",
major >= 18,
`${nodeVer} (${major >= 18 ? "Supported" : "Node 18+ required"})`
);
// 2. Web Crypto API Engine
let cryptoOk = false;
let cryptoDetails = "SubtleCrypto unavailable";
try {
const crypto = getCrypto();
if (crypto && crypto.subtle) {
// Test AES-GCM key generation & PBKDF2
const rawKey = new Uint8Array(32);
await crypto.subtle.importKey("raw", rawKey, { name: "AES-GCM" }, false, [
"encrypt",
"decrypt",
]);
cryptoOk = true;
cryptoDetails = "AES-GCM, PBKDF2, RSA-OAEP, ECDH subtle engine operational";
}
} catch (e) {
cryptoDetails = `SubtleCrypto failed: ${e.message}`;
}
check("Web Crypto Engine", cryptoOk, cryptoDetails);
// 3. Agent Skill File
const skillPath = path.join(targetDir, ".agents", "skills", "webcrypt-mcp", "SKILL.md");
const skillExists = fs.existsSync(skillPath);
check(
"Agent Skill (.agents/skills/webcrypt-mcp/SKILL.md)",
skillExists,
skillExists
? `Installed (${fs.statSync(skillPath).size} bytes)`
: "Missing — run `webcrypt init` to scaffold"
);
// 4. MCP Config File
const cursorMcp = path.join(targetDir, ".cursor", "mcp.json");
const vscodeMcp = path.join(targetDir, ".vscode", "mcp.json");
let mcpConfigOk = false;
let mcpDetails = "No MCP config found";
if (fs.existsSync(cursorMcp)) {
try {
const parsed = JSON.parse(fs.readFileSync(cursorMcp, "utf-8"));
if (parsed.mcpServers && parsed.mcpServers.webcrypt) {
mcpConfigOk = true;
mcpDetails = "Configured in .cursor/mcp.json";
}
} catch {}
}
if (!mcpConfigOk && fs.existsSync(vscodeMcp)) {
try {
const parsed = JSON.parse(fs.readFileSync(vscodeMcp, "utf-8"));
if (parsed.mcpServers && parsed.mcpServers.webcrypt) {
mcpConfigOk = true;
mcpDetails = "Configured in .vscode/mcp.json";
}
} catch {}
}
check("IDE MCP Server Registration", mcpConfigOk, mcpDetails);
// 5. Instruction Marker Detection
const instructionFiles = [
".agents/AGENTS.md",
".cursorrules",
".windsurfrules",
".gemini/instructions.md",
".github/copilot-instructions.md",
"CLAUDE.md",
];
let foundInstructions = 0;
for (const f of instructionFiles) {
const full = path.join(targetDir, f);
if (fs.existsSync(full)) {
const content = fs.readFileSync(full, "utf-8");
if (content.includes("<!-- webcrypt-mcp:start -->")) {
foundInstructions++;
}
}
}
check(
"Agent Instruction Markers",
foundInstructions > 0,
foundInstructions > 0
? `Active across ${foundInstructions} instruction files`
: "None found — run `webcrypt init`"
);
const allPassed = checks.every(c => c.passed);
if (!isJson) {
console.log(`\nOverall Health: ${allPassed ? "✅ HEALTHY" : "⚠️ ATTENTION NEEDED"}\n`);
}
return { targetDir, allPassed, checks };
}
export async function runDoctorGlobal(options = {}) {
const isJson = options.json || false;
if (options.cleanStale) {
const { removed } = pruneStaleProjects();
if (!isJson && removed.length > 0) {
console.log(`🧹 Cleaned ${removed.length} stale project entries from registry.`);
}
}
const registry = getRegistry();
const entries = Object.entries(registry);
if (entries.length === 0) {
if (isJson) {
console.log(JSON.stringify({ total: 0, results: [] }));
} else {
console.log("\n⚠️ No registered projects found in ~/.webcrypt/projects.json.");
console.log("Run `webcrypt init` inside a project folder to register it.\n");
}
return;
}
if (!isJson) {
console.log(
`\n🌐 Running global health audit across ${entries.length} registered projects...\n`
);
}
const results = [];
for (const [slug, p] of entries) {
if (!fs.existsSync(p)) {
results.push({ slug, path: p, exists: false, allPassed: false, checks: [] });
if (!isJson) {
console.log(`📁 [${slug}] ❌ Missing Directory: ${p}`);
}
continue;
}
if (!isJson) {
console.log(`📁 Project: ${slug} (${p})`);
}
const res = await runDoctor(p, { json: isJson });
results.push({ slug, path: p, exists: true, ...res });
}
if (isJson) {
console.log(JSON.stringify({ total: entries.length, results }, null, 2));
} else {
const healthyCount = results.filter(r => r.allPassed).length;
console.log(`\nGlobal Audit Summary: ${healthyCount}/${entries.length} projects healthy.\n`);
}
}
+189
src/cli/init.js
// src/cli/init.js
// Automated project initialization and agent skill scaffolding for WebCrypt
import fs from "fs";
import path from "path";
import os from "os";
import { getSkillTemplate, getInstructionsTemplate } from "./templates.js";
import { registerProject, getRegistry, pruneStaleProjects } from "./registry.js";
const MARKER_START = "<!-- webcrypt-mcp:start -->";
const MARKER_END = "<!-- webcrypt-mcp:end -->";
const INSTRUCTION_TARGETS = [
".cursorrules",
".windsurfrules",
".gemini/instructions.md",
".github/copilot-instructions.md",
"CLAUDE.md",
".agents/AGENTS.md",
];
function ensureDir(filePath) {
const dir = path.dirname(filePath);
if (!fs.existsSync(dir)) {
fs.mkdirSync(dir, { recursive: true });
}
}
function updateFileWithMarker(filePath, newContent) {
ensureDir(filePath);
let content = "";
if (fs.existsSync(filePath)) {
content = fs.readFileSync(filePath, "utf-8");
}
const startIdx = content.indexOf(MARKER_START);
const endIdx = content.indexOf(MARKER_END);
if (startIdx !== -1 && endIdx !== -1 && endIdx >= startIdx) {
// Replace existing block
const before = content.slice(0, startIdx).trimEnd();
const after = content.slice(endIdx + MARKER_END.length).trimStart();
const updated =
(before ? before + "\n\n" : "") + newContent + (after ? "\n\n" + after : "") + "\n";
fs.writeFileSync(filePath, updated, "utf-8");
return "updated";
} else {
// Append
const updated = (content.trim() ? content.trim() + "\n\n" : "") + newContent + "\n";
fs.writeFileSync(filePath, updated, "utf-8");
return content ? "appended" : "created";
}
}
function mergeMcpConfig(configPath) {
ensureDir(configPath);
let json = { mcpServers: {} };
if (fs.existsSync(configPath)) {
try {
json = JSON.parse(fs.readFileSync(configPath, "utf-8"));
if (!json.mcpServers) json.mcpServers = {};
} catch (e) {
json = { mcpServers: {} };
}
}
json.mcpServers.webcrypt = {
command: "npx",
args: ["-y", "webcrypt", "mcp"],
};
fs.writeFileSync(configPath, JSON.stringify(json, null, 2) + "\n", "utf-8");
}
export async function runInit(targetDir = process.cwd(), options = {}) {
const resolvedDir = path.resolve(targetDir);
const projectName = path.basename(resolvedDir);
if (!options.silent) {
console.log(`\n🔒 Initializing WebCrypt MCP & Agent Customizations for: ${resolvedDir}\n`);
}
// 1. Register in Global Registry (~/.webcrypt/projects.json)
registerProject(projectName, resolvedDir);
const results = [];
// 2. Scaffold Agent Skill (.agents/skills/webcrypt-mcp/SKILL.md)
const skillPath = path.join(resolvedDir, ".agents", "skills", "webcrypt-mcp", "SKILL.md");
ensureDir(skillPath);
fs.writeFileSync(skillPath, getSkillTemplate(), "utf-8");
results.push(`✅ Created Agent Skill: .agents/skills/webcrypt-mcp/SKILL.md`);
// 3. Scaffold IDE MCP Configurations
const cursorMcpPath = path.join(resolvedDir, ".cursor", "mcp.json");
mergeMcpConfig(cursorMcpPath);
results.push(`✅ Configured Cursor MCP: .cursor/mcp.json`);
const vscodeMcpPath = path.join(resolvedDir, ".vscode", "mcp.json");
if (fs.existsSync(path.join(resolvedDir, ".vscode"))) {
mergeMcpConfig(vscodeMcpPath);
results.push(`✅ Configured VS Code MCP: .vscode/mcp.json`);
}
// 4. Global Antigravity Config (if ~/.gemini/config/config.json exists)
const homeDir = os.homedir();
const globalAntigravityConfig = path.join(homeDir, ".gemini", "config", "config.json");
if (fs.existsSync(globalAntigravityConfig)) {
try {
mergeMcpConfig(globalAntigravityConfig);
results.push(`✅ Configured Global Antigravity: ~/.gemini/config/config.json`);
} catch (e) {}
}
// 5. Scaffold Agent Instruction Files
const instructionsBlock = getInstructionsTemplate();
for (const relPath of INSTRUCTION_TARGETS) {
const fullPath = path.join(resolvedDir, relPath);
if (fs.existsSync(fullPath) || relPath === ".agents/AGENTS.md") {
const action = updateFileWithMarker(fullPath, instructionsBlock);
results.push(`✅ ${action.toUpperCase()} ${relPath}`);
}
}
if (!options.silent) {
results.forEach(r => console.log(` ${r}`));
console.log(`
🎉 WebCrypt initialization complete!
------------------------------------
Registered in ~/.webcrypt/projects.json as: "${projectName.toLowerCase()}"
`);
}
return { targetDir: resolvedDir, projectName, results };
}
export async function runInitGlobal(options = {}) {
console.log("\n🌐 Running global multi-project WebCrypt initialization...\n");
if (options.cleanStale) {
const { removed } = pruneStaleProjects();
if (removed.length > 0) {
console.log(`🧹 Cleaned ${removed.length} stale project entries.`);
}
}
if (options.scan) {
const scanRoot = path.resolve(options.scan);
if (fs.existsSync(scanRoot)) {
console.log(`🔍 Scanning directory for sub-projects: ${scanRoot}`);
const entries = fs.readdirSync(scanRoot, { withFileTypes: true });
for (const ent of entries) {
if (ent.isDirectory() && !ent.name.startsWith(".")) {
const subPath = path.join(scanRoot, ent.name);
if (
fs.existsSync(path.join(subPath, "package.json")) ||
fs.existsSync(path.join(subPath, ".git"))
) {
registerProject(ent.name, subPath);
}
}
}
}
}
const registry = getRegistry();
const entries = Object.entries(registry);
if (entries.length === 0) {
console.log("⚠️ No registered projects found in ~/.webcrypt/projects.json.");
console.log("Run `webcrypt init` inside a project or `webcrypt init-global --scan <path>`.\n");
return;
}
let count = 0;
for (const [slug, p] of entries) {
if (!fs.existsSync(p)) {
console.log(`📁 [${slug}] ⚠️ Skipped (directory not found: ${p})`);
continue;
}
console.log(`📁 Re-initializing: ${slug} (${p})`);
await runInit(p, { silent: true });
console.log(` ✅ Synced MCP configuration, skill, and instruction files.`);
count++;
}
console.log(`\n🎉 Global initialization complete! Updated ${count} projects.\n`);
}
+121
src/cli/registry.js
// src/cli/registry.js
// Global project registry manager for WebCrypt (~/.webcrypt/projects.json)
import fs from "fs";
import path from "path";
import os from "os";
export const DEFAULT_REGISTRY_PATH = path.join(os.homedir(), ".webcrypt", "projects.json");
export function getRegistryPath() {
return process.env.WEBCRYPT_REGISTRY_PATH || DEFAULT_REGISTRY_PATH;
}
let registryCache = null;
const CACHE_TTL_MS = 5000;
function cleanupTempFiles() {
try {
const regPath = getRegistryPath();
const dir = path.dirname(regPath);
if (!fs.existsSync(dir)) return;
const files = fs.readdirSync(dir);
for (const f of files) {
if (f.startsWith("projects.json.tmp.")) {
try {
fs.unlinkSync(path.join(dir, f));
} catch {}
}
}
} catch {}
}
export function getRegistry() {
cleanupTempFiles();
const now = Date.now();
if (registryCache && now - registryCache.timestamp < CACHE_TTL_MS) {
return registryCache.registry;
}
const regPath = getRegistryPath();
try {
if (fs.existsSync(regPath)) {
const raw = fs.readFileSync(regPath, "utf-8");
const registry = JSON.parse(raw) || {};
registryCache = { registry, timestamp: now };
return registry;
}
} catch (e) {}
return {};
}
export function registerProject(name, projectPath) {
try {
const resolved = path.resolve(projectPath);
if (resolved === os.homedir()) return;
registryCache = null;
const registry = getRegistry();
const slug = name.toLowerCase().replace(/[^a-z0-9_-]/g, "-");
registry[slug] = resolved;
const regPath = getRegistryPath();
const dir = path.dirname(regPath);
if (!fs.existsSync(dir)) {
fs.mkdirSync(dir, { recursive: true });
}
const tmpPath = `${regPath}.tmp.${Math.random().toString(36).substring(2)}`;
fs.writeFileSync(tmpPath, JSON.stringify(registry, null, 2), {
encoding: "utf-8",
mode: 0o600,
});
fs.renameSync(tmpPath, regPath);
} catch (e) {}
}
export function unregisterProject(name) {
try {
registryCache = null;
const registry = getRegistry();
const slug = name.toLowerCase();
if (registry[slug]) {
delete registry[slug];
const regPath = getRegistryPath();
const tmpPath = `${regPath}.tmp.${Math.random().toString(36).substring(2)}`;
fs.writeFileSync(tmpPath, JSON.stringify(registry, null, 2), {
encoding: "utf-8",
mode: 0o600,
});
fs.renameSync(tmpPath, regPath);
}
} catch (e) {}
}
export function pruneStaleProjects() {
const registry = getRegistry();
const active = {};
const removed = [];
for (const [slug, p] of Object.entries(registry)) {
if (fs.existsSync(p)) {
active[slug] = p;
} else {
removed.push({ slug, path: p });
}
}
if (removed.length > 0) {
registryCache = null;
const regPath = getRegistryPath();
const tmpPath = `${regPath}.tmp.${Math.random().toString(36).substring(2)}`;
fs.writeFileSync(tmpPath, JSON.stringify(active, null, 2), {
encoding: "utf-8",
mode: 0o600,
});
fs.renameSync(tmpPath, regPath);
}
return { active, removed };
}
+61
src/cli/templates.js
// src/cli/templates.js
// Scaffolding templates for WebCrypt MCP Server & Agent Customizations
export function getSkillTemplate() {
return `---
name: webcrypt-mcp
description: Teaches the agent to use the WebCrypt MCP server for AES-256-GCM symmetric encryption, RSA-4096 hybrid encryption, key generation, digital signatures, hashing, and post-quantum cryptography. Includes automated test scripts for exercising all MCP tools.
---
# Cryptographic Memory & Vault Tooling (webcrypt-mcp)
This project provides \`webcrypt-mcp\`, a native Model Context Protocol server for zero-dependency AES-256-GCM encryption, RSA-4096 hybrid public-key encryption, digital signatures, cryptographic hashes, and post-quantum cryptography.
## 1. Mandatory Workflow & Priority
1. **Confidential Artifacts**: Whenever saving sensitive credentials, tokens, or private workflow states, encrypt them using \`encrypt_payload(mode: "data", password: "...")\` or \`encrypt_payload(mode: "symmetric", password: "...")\`.
2. **Key Management**: Use \`manage_keys(action: "generate", type: "rsa" | "ecdh" | "ecdsa" | "rsa-pss" | "hmac")\` to generate cryptographically strong JWK-formatted keys for inter-agent communication.
3. **Integrity & Signatures**: Before completing tasks that produce verifiable evidence (such as evidence packs or release binaries), compute signatures or HMAC tags using \`sign_verify(action: "sign", algorithm: "ECDSA" | "HMAC")\`.
4. **Triple Memory Triad**:
- \`state-memory-mcp\`: Workflow state tracking.
- \`vision-memory-mcp\`: Visual state caching.
- \`webcrypt-mcp\`: Encryption of sensitive DAG nodes, visual cache database vaults, and signature verification.
## 2. Complete Tool Reference
| Tool Name | Key Inputs | Description |
| :--- | :--- | :--- |
| \`encrypt_payload\` | \`mode\` ('symmetric' \\| 'asymmetric' \\| 'data'), \`data\`, \`password\`?, \`public_key_jwk\`? | Encrypt plaintext, JSON object, or binary data. |
| \`decrypt_payload\` | \`mode\` ('symmetric' \\| 'asymmetric' \\| 'data'), \`ciphertext\`, \`password\`?, \`private_key_jwk\`? | Decrypt ciphertext back to plaintext or structured JSON. |
| \`manage_keys\` | \`action\` ('generate' \\| 'generate_random_password'), \`type\` ('rsa' \\| 'ecdh' \\| 'ecdsa' \\| 'rsa-pss' \\| 'hmac'), \`modulusLength\`?, \`namedCurve\`?, \`length\`? | Generate cryptographic keys (JWK format) or secure random passwords. |
| \`crypto_hash\` | \`algorithm\` ('SHA-256' \\| 'SHA-384' \\| 'SHA-512' \\| 'SHA3-256' \\| 'SHA3-512'), \`data\`, \`encoding\` ('hex' \\| 'base64') | Compute cryptographic hash digests. |
| \`sign_verify\` | \`action\` ('sign' \\| 'verify'), \`algorithm\` ('ECDSA' \\| 'RSA-PSS' \\| 'HMAC' \\| 'HMAC-SHA3'), \`data\`, \`signature\`?, \`password\`?, \`key_jwk\`? | Sign or verify messages with ECDSA, RSA-PSS, or HMAC. |
| \`pqc_kem_sign\` | \`action\` ('generate_kyber_keypair' \\| 'kyber_encapsulate' \\| 'kyber_decapsulate' \\| 'hybrid_encapsulate' \\| 'hybrid_decapsulate' \\| 'generate_dilithium_keypair' \\| 'dilithium_sign' \\| 'dilithium_verify'), \`level\`?, \`public_key_b64\`?, \`private_key_b64\`?, ... | Post-quantum Kyber KEM, Dilithium signatures, and Hybrid KEM. |
## 3. Automated MCP Tool Exercise & Verification
To verify that the MCP server and all 6 tools are operating correctly in the current environment:
\`\`\`bash
node .agents/skills/webcrypt-mcp/scripts/exercise_tools.js
\`\`\`
## 4. Agent Permissions & Auto-Run Configuration
To allow WebCrypt MCP tools to run seamlessly without interactive confirmation:
- Add \`"command(webcrypt-mcp)"\` or \`"command(npx webcrypt mcp)"\` to global agent permission grants.
`;
}
export function getInstructionsTemplate() {
return `<!-- webcrypt-mcp:start -->
# Cryptographic Vault & Security (webcrypt-mcp)
This project provides native \`webcrypt-mcp\` tooling for zero-dependency AES-256-GCM symmetric encryption, RSA-4096 hybrid public-key encryption, digital signatures, cryptographic hashes, and post-quantum cryptography.
## Mandatory Workflow
1. **Confidential Artifacts**: Whenever saving sensitive credentials, tokens, or private workflow states, encrypt them using \`encrypt_payload(mode: "data", password: "...")\` or \`encrypt_payload(mode: "symmetric", password: "...")\`.
2. **Key Management**: Use \`manage_keys(action: "generate", type: "rsa" | "ecdh" | "hmac")\` to generate cryptographically strong JWK-formatted keys for inter-agent communication.
3. **Integrity & Signatures**: Before completing tasks that produce verifiable evidence (such as evidence packs or release binaries), compute signatures or HMAC tags using \`sign_verify(action: "sign", algorithm: "ECDSA" | "HMAC")\`.
4. **Triple Memory Triad**:
- \`state-memory-mcp\`: Workflow state tracking.
- \`vision-memory-mcp\`: Visual state caching.
- \`webcrypt-mcp\`: Local database vault encryption and evidence pack cryptographic signing.
<!-- webcrypt-mcp:end -->`;
}
+14
src/index.js
// src/index.js
// version: 1.0.0
export * from "./WebCrypt.js";
export * from "./WebCryptAsym.js";
export * from "./WebCryptPQC.js";
export { default as TimingSafeHelper } from "./TimingSafeHelper.js";
export {
arrayBufferToBase64,
base64ToArrayBuffer,
base64ToUint8Array,
isValidBase64,
} from "./_base64.js";
export { getCrypto } from "./_crypto.js";
+403
src/mcp/handlers.js
// src/mcp/handlers.js
// Tool execution handlers for WebCrypt MCP Server
import { WebCrypt } from "../WebCrypt.js";
import { WebCryptAsym } from "../WebCryptAsym.js";
import { WebCryptPQC } from "../WebCryptPQC.js";
import { arrayBufferToBase64, base64ToArrayBuffer, base64ToUint8Array } from "../_base64.js";
import { getCrypto } from "../_crypto.js";
let _wc, _asym, _pqc;
function getWC() {
return _wc || (_wc = new WebCrypt());
}
function getAsym() {
return _asym || (_asym = new WebCryptAsym());
}
function getPQC() {
if (!_pqc) {
_pqc = new WebCryptPQC();
WebCryptPQC.enableStubTesting(true);
}
return _pqc;
}
export async function handleToolCall(name, args = {}) {
switch (name) {
case "encrypt_payload": {
const mode = args.mode || "symmetric";
if (mode === "symmetric") {
if (!args.password)
throw new Error("Missing 'password' parameter for symmetric encryption");
const plaintext = typeof args.data === "string" ? args.data : JSON.stringify(args.data);
const ciphertext = await getWC().encryptText(plaintext, args.password);
return { ciphertext, mode: "symmetric" };
} else if (mode === "data") {
if (!args.password) throw new Error("Missing 'password' parameter for data encryption");
const ciphertext = await getWC().encryptData(args.data, args.password);
return { ciphertext, mode: "data" };
} else if (mode === "asymmetric") {
if (!args.public_key_jwk)
throw new Error("Missing 'public_key_jwk' parameter for asymmetric encryption");
const crypto = getCrypto();
const publicKey = await crypto.subtle.importKey(
"jwk",
args.public_key_jwk,
WebCryptAsym.RSA_ALGORITHM,
true,
["encrypt"]
);
const plaintext = typeof args.data === "string" ? args.data : JSON.stringify(args.data);
const ciphertext = await getAsym().encryptText(plaintext, publicKey);
return { ciphertext, mode: "asymmetric" };
}
throw new Error(`Unsupported mode: ${mode}`);
}
case "decrypt_payload": {
const mode = args.mode || "symmetric";
if (!args.ciphertext) throw new Error("Missing 'ciphertext' parameter");
if (mode === "symmetric") {
if (!args.password)
throw new Error("Missing 'password' parameter for symmetric decryption");
const decrypted = await getWC().decryptText(args.ciphertext, args.password);
return { data: decrypted, plaintext: decrypted, mode: "symmetric" };
} else if (mode === "data") {
if (!args.password) throw new Error("Missing 'password' parameter for data decryption");
const decrypted = await getWC().decryptData(args.ciphertext, args.password);
return { data: decrypted, mode: "data" };
} else if (mode === "asymmetric") {
if (!args.private_key_jwk)
throw new Error("Missing 'private_key_jwk' parameter for asymmetric decryption");
const crypto = getCrypto();
const privateKey = await crypto.subtle.importKey(
"jwk",
args.private_key_jwk,
WebCryptAsym.RSA_ALGORITHM,
true,
["decrypt"]
);
const decrypted = await getAsym().decryptText(args.ciphertext, privateKey);
return { data: decrypted, plaintext: decrypted, mode: "asymmetric" };
}
throw new Error(`Unsupported mode: ${mode}`);
}
case "manage_keys": {
const action = args.action;
if (action === "generate_random_password") {
const password = getWC().generateRandomPassword(args.length || 32);
return { password, length: args.length || 32 };
} else if (action === "generate") {
const type = args.type || "rsa";
const crypto = getCrypto();
if (type === "rsa") {
const modulusLength = args.modulusLength || 4096;
const keyPair = await getAsym().generateKeyPair(modulusLength);
const publicKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.publicKey);
const privateKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.privateKey);
return { type: "rsa", modulusLength, publicKey: publicKeyJwk, privateKey: privateKeyJwk };
} else if (type === "ecdh") {
const namedCurve = args.namedCurve || "P-256";
const keyPair = await getAsym().generateECDHKeyPair(namedCurve);
const publicKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.publicKey);
const privateKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.privateKey);
return { type: "ecdh", namedCurve, publicKey: publicKeyJwk, privateKey: privateKeyJwk };
} else if (type === "ecdsa") {
const namedCurve = args.namedCurve || "P-256";
const keyPair = await getAsym().generateSigningKeyPair(namedCurve);
const publicKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.publicKey);
const privateKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.privateKey);
return { type: "ecdsa", namedCurve, publicKey: publicKeyJwk, privateKey: privateKeyJwk };
} else if (type === "rsa-pss") {
const modulusLength = args.modulusLength || 2048;
const keyPair = await crypto.subtle.generateKey(
{
name: "RSA-PSS",
modulusLength,
publicExponent: new Uint8Array([1, 0, 1]),
hash: "SHA-256",
},
true,
["sign", "verify"]
);
const publicKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.publicKey);
const privateKeyJwk = await crypto.subtle.exportKey("jwk", keyPair.privateKey);
return {
type: "rsa-pss",
modulusLength,
publicKey: publicKeyJwk,
privateKey: privateKeyJwk,
};
} else if (type === "hmac") {
const rawBytes = crypto.getRandomValues(new Uint8Array(args.length || 32));
return { type: "hmac", key_b64: arrayBufferToBase64(rawBytes) };
}
throw new Error(`Unsupported key type: ${type}`);
}
throw new Error(`Unsupported action: ${action}`);
}
case "crypto_hash": {
if (!args.data) throw new Error("Missing 'data' parameter");
const algo = args.algorithm || "SHA-256";
const encoding = args.encoding || "hex";
const crypto = getCrypto();
const inputBytes = new TextEncoder().encode(args.data);
let digestBytes;
if (algo.startsWith("SHA3-")) {
const bitLength = parseInt(algo.replace("SHA3-", ""), 10) || 256;
digestBytes = await getPQC()._sha3Hash(inputBytes, bitLength);
} else {
const buffer = await crypto.subtle.digest(algo, inputBytes);
digestBytes = new Uint8Array(buffer);
}
let digest;
if (encoding === "hex") {
digest = Array.from(digestBytes, b => b.toString(16).padStart(2, "0")).join("");
} else {
digest = arrayBufferToBase64(digestBytes);
}
return { algorithm: algo, encoding, digest };
}
case "sign_verify": {
const action = args.action;
const algo = args.algorithm || "ECDSA";
const data = args.data;
if (!data) throw new Error("Missing 'data' parameter");
if (action === "sign") {
if (algo === "HMAC") {
if (!args.password) throw new Error("Missing 'password' for HMAC");
const key = await getWC().generateHmacKey(args.password);
const tag = await getWC().computeHmac(data, key);
return { algorithm: algo, signature: tag };
} else if (algo === "HMAC-SHA3") {
if (!args.password) throw new Error("Missing 'password' for HMAC-SHA3");
const key = await getWC().generateHmacKeySHA3(args.password);
const tag = await getWC().computeHmacSHA3(data, key);
return { algorithm: algo, signature: tag };
} else if (algo === "ECDSA" || algo === "RSA-PSS") {
if (!args.key_jwk) throw new Error(`Missing 'key_jwk' for ${algo} signing`);
const crypto = getCrypto();
const importParams =
algo === "ECDSA"
? { name: "ECDSA", namedCurve: args.key_jwk.crv || "P-256" }
: { name: "RSA-PSS", hash: "SHA-256" };
const privateKey = await crypto.subtle.importKey(
"jwk",
args.key_jwk,
importParams,
false,
["sign"]
);
const sig = await getAsym().signTextWithAlgorithm(data, privateKey, algo);
return { algorithm: algo, signature: sig };
}
throw new Error(`Unsupported sign algorithm: ${algo}`);
} else if (action === "verify") {
if (!args.signature) throw new Error("Missing 'signature' parameter to verify");
if (algo === "HMAC") {
if (!args.password) throw new Error("Missing 'password' for HMAC");
const key = await getWC().generateHmacKey(args.password);
const valid = await getWC().verifyHmac(data, args.signature, key);
return { algorithm: algo, valid };
} else if (algo === "HMAC-SHA3") {
if (!args.password) throw new Error("Missing 'password' for HMAC-SHA3");
const key = await getWC().generateHmacKeySHA3(args.password);
const valid = await getWC().verifyHmacSHA3(data, args.signature, key);
return { algorithm: algo, valid };
} else if (algo === "ECDSA" || algo === "RSA-PSS") {
if (!args.key_jwk) throw new Error(`Missing 'key_jwk' for ${algo} verification`);
const crypto = getCrypto();
const importParams =
algo === "ECDSA"
? { name: "ECDSA", namedCurve: args.key_jwk.crv || "P-256" }
: { name: "RSA-PSS", hash: "SHA-256" };
const publicKey = await crypto.subtle.importKey(
"jwk",
args.key_jwk,
importParams,
false,
["verify"]
);
const valid = await getAsym().verifyTextWithAlgorithm(
data,
args.signature,
publicKey,
algo
);
return { algorithm: algo, valid };
}
throw new Error(`Unsupported verify algorithm: ${algo}`);
}
throw new Error(`Unsupported action: ${action}`);
}
case "pqc_kem_sign": {
const action = args.action;
const level = args.level || "Kyber768";
const pqcInst = getPQC();
if (action === "generate_kyber_keypair") {
const keyPair = await pqcInst.generateKyberKeyPair(level);
const pubB64 = pqcInst.kyberPublicKeyToBase64(keyPair.publicKey);
const privB64 = pqcInst.kyberPrivateKeyToBase64(keyPair.privateKey);
return {
algorithm: "Kyber",
level,
public_key_b64: pubB64,
private_key_b64: privB64,
publicKey_b64: pubB64,
privateKey_b64: privB64,
};
} else if (action === "kyber_encapsulate") {
const pubKeyB64 = args.public_key_b64 || args.publicKey_b64;
if (!pubKeyB64) throw new Error("Missing 'public_key_b64'");
const pubKey = pqcInst.kyberPublicKeyFromBase64(pubKeyB64);
const { ciphertext, sharedSecret } = await pqcInst.kyberEncapsulate(pubKey, level);
const ctB64 = arrayBufferToBase64(ciphertext);
const ssB64 = arrayBufferToBase64(sharedSecret);
return {
level,
ciphertext_b64: ctB64,
shared_secret_b64: ssB64,
ciphertextB64: ctB64,
sharedSecret_b64: ssB64,
sharedSecretB64: ssB64,
};
} else if (action === "kyber_decapsulate") {
const ctB64 = args.ciphertext_b64 || args.ciphertextB64;
const privKeyB64 = args.private_key_b64 || args.privateKey_b64;
if (!ctB64 || !privKeyB64) {
throw new Error("Missing 'ciphertext_b64' or 'private_key_b64'");
}
const ciphertext = base64ToUint8Array(ctB64);
const privKey = pqcInst.kyberPrivateKeyFromBase64(privKeyB64);
const sharedSecret = await pqcInst.kyberDecapsulate(ciphertext, privKey, level);
const ssB64 = arrayBufferToBase64(sharedSecret);
return {
level,
shared_secret_b64: ssB64,
sharedSecret_b64: ssB64,
sharedSecretB64: ssB64,
};
} else if (action === "hybrid_encapsulate") {
const pubKeyB64 = args.public_key_b64 || args.publicKey_b64;
const rsaPubKeyJwk = args.rsa_public_key_jwk || args.rsaPublicKeyJwk;
if (!rsaPubKeyJwk || !pubKeyB64) {
throw new Error("Missing 'rsa_public_key_jwk' or 'public_key_b64'");
}
const crypto = getCrypto();
const rsaPubKey = await crypto.subtle.importKey(
"jwk",
rsaPubKeyJwk,
WebCryptAsym.RSA_ALGORITHM,
true,
["encrypt"]
);
const kyberPubKey = pqcInst.kyberPublicKeyFromBase64(pubKeyB64);
const result = await pqcInst.hybridEncapsulate(rsaPubKey, kyberPubKey, level);
const ssB64 = arrayBufferToBase64(result.sharedSecret);
const ctB64 = arrayBufferToBase64(result.kyberCiphertext);
const rsaWrappedB64 = arrayBufferToBase64(result.rsaWrappedSharedSecret);
return {
level,
shared_secret_b64: ssB64,
sharedSecret_b64: ssB64,
kyber_ciphertext_b64: ctB64,
kyberCiphertext_b64: ctB64,
rsa_wrapped_secret_b64: rsaWrappedB64,
rsaWrappedSecret_b64: rsaWrappedB64,
};
} else if (action === "hybrid_decapsulate") {
const rsaPrivKeyJwk = args.rsa_private_key_jwk || args.rsaPrivateKeyJwk;
const privKeyB64 = args.private_key_b64 || args.privateKey_b64;
const kyberCtB64 = args.kyber_ciphertext_b64 || args.kyberCiphertext_b64;
const rsaWrappedB64 = args.rsa_wrapped_secret_b64 || args.rsaWrappedSecret_b64;
if (!rsaPrivKeyJwk || !privKeyB64 || !kyberCtB64 || !rsaWrappedB64) {
throw new Error("Missing required parameters for hybrid_decapsulate");
}
const crypto = getCrypto();
const rsaPrivKey = await crypto.subtle.importKey(
"jwk",
rsaPrivKeyJwk,
WebCryptAsym.RSA_ALGORITHM,
true,
["decrypt"]
);
const kyberPrivKey = pqcInst.kyberPrivateKeyFromBase64(privKeyB64);
const kyberCiphertext = base64ToUint8Array(kyberCtB64);
const rsaWrappedSecret = base64ToUint8Array(rsaWrappedB64);
const sharedSecret = await pqcInst.hybridDecapsulate(
kyberCiphertext,
rsaWrappedSecret,
rsaPrivKey,
kyberPrivKey,
level
);
const ssB64 = arrayBufferToBase64(sharedSecret);
return {
level,
shared_secret_b64: ssB64,
sharedSecret_b64: ssB64,
};
} else if (action === "generate_dilithium_keypair") {
const dilithiumLevel = args.level || "Dilithium3";
const keyPair = await pqcInst.generateDilithiumKeyPair(dilithiumLevel);
const pubB64 = pqcInst.dilithiumPublicKeyToBase64(keyPair.publicKey);
const privB64 = pqcInst.dilithiumPrivateKeyToBase64(keyPair.privateKey);
return {
algorithm: "Dilithium",
level: dilithiumLevel,
public_key_b64: pubB64,
private_key_b64: privB64,
publicKey_b64: pubB64,
privateKey_b64: privB64,
};
} else if (action === "dilithium_sign") {
const privKeyB64 = args.private_key_b64 || args.privateKey_b64;
if (!args.data || !privKeyB64) {
throw new Error("Missing 'data' or 'private_key_b64'");
}
const privKey = pqcInst.dilithiumPrivateKeyFromBase64(privKeyB64);
const sig = await pqcInst.dilithiumSign(args.data, privKey, args.level || "Dilithium3");
const sigB64 = arrayBufferToBase64(sig);
return {
algorithm: "Dilithium",
level: args.level || "Dilithium3",
signature_b64: sigB64,
signatureB64: sigB64,
};
} else if (action === "dilithium_verify") {
const pubKeyB64 = args.public_key_b64 || args.publicKey_b64;
const sigB64 = args.signature_b64 || args.signatureB64;
if (!args.data || !sigB64 || !pubKeyB64) {
throw new Error("Missing 'data', 'signature_b64', or 'public_key_b64'");
}
const pubKey = pqcInst.dilithiumPublicKeyFromBase64(pubKeyB64);
const sig = base64ToUint8Array(sigB64);
const valid = await pqcInst.dilithiumVerify(
args.data,
sig,
pubKey,
args.level || "Dilithium3"
);
return {
algorithm: "Dilithium",
valid,
};
}
throw new Error(`Unsupported PQC action: ${action}`);
}
default:
throw new Error(`Unknown tool: ${name}`);
}
}
+167
src/mcp/server.js
// src/mcp/server.js
// Zero-dependency Model Context Protocol (MCP) Server for WebCrypt
// PuterVision Standard - stdio JSON-RPC 2.0 transport
import { WEBCRYPT_MCP_TOOLS } from "./tools.js";
import { handleToolCall } from "./handlers.js";
export class WebCryptMCPServer {
constructor(options = {}) {
this.name = "webcrypt";
this.version = "1.0.0";
this.tools = WEBCRYPT_MCP_TOOLS;
this.in = options.stdin || process.stdin;
this.out = options.stdout || process.stdout;
}
async handleMessage(message) {
if (!message || typeof message !== "object") return null;
const { id, method, params } = message;
// Handle notifications (no id)
if (id === undefined || id === null) {
if (method === "notifications/initialized") {
// Initialization acknowledged
return null;
}
return null;
}
try {
switch (method) {
case "initialize": {
return {
jsonrpc: "2.0",
id,
result: {
protocolVersion: "2024-11-05",
capabilities: {
tools: {},
},
serverInfo: {
name: this.name,
version: this.version,
},
},
};
}
case "ping": {
return {
jsonrpc: "2.0",
id,
result: {},
};
}
case "tools/list": {
return {
jsonrpc: "2.0",
id,
result: {
tools: this.tools,
},
};
}
case "tools/call": {
const toolName = params?.name;
const toolArgs = params?.arguments || {};
const result = await handleToolCall(toolName, toolArgs);
return {
jsonrpc: "2.0",
id,
result: {
content: [
{
type: "text",
text: typeof result === "string" ? result : JSON.stringify(result, null, 2),
},
],
},
};
}
default: {
return {
jsonrpc: "2.0",
id,
error: {
code: -32601,
message: `Method not found: ${method}`,
},
};
}
}
} catch (err) {
return {
jsonrpc: "2.0",
id,
result: {
content: [
{
type: "text",
text: `Error: ${err.message || String(err)}`,
},
],
isError: true,
},
};
}
}
send(response) {
if (!response) return;
const json = JSON.stringify(response);
this.out.write(`${json}\n`);
}
start() {
let buffer = "";
// Handle stream errors gracefully (e.g. EPIPE on abrupt client disconnect)
if (typeof this.in.on === "function") this.in.on("error", () => {});
if (typeof this.out.on === "function") this.out.on("error", () => {});
this.in.on("data", async chunk => {
buffer += chunk.toString("utf-8");
while (true) {
const lineEnd = buffer.indexOf("\n");
if (lineEnd === -1) break;
const line = buffer.slice(0, lineEnd).trim();
buffer = buffer.slice(lineEnd + 1);
if (line.length === 0) continue;
try {
const message = JSON.parse(line);
const response = await this.handleMessage(message);
if (response) {
this.send(response);
}
} catch (parseErr) {
this.send({
jsonrpc: "2.0",
id: null,
error: {
code: -32700,
message: `Parse error: ${parseErr.message}`,
},
});
}
}
});
this.in.on("end", () => {
// Stream ended
});
}
}
export function startMCPServer() {
const server = new WebCryptMCPServer();
server.start();
return server;
}
+230
src/mcp/tools.js
// src/mcp/tools.js
// Tool schemas and metadata for WebCrypt MCP Server (PuterVision Standard)
export const WEBCRYPT_MCP_TOOLS = [
{
name: "encrypt_payload",
description:
"Encrypt text, JSON objects, or files using AES-256-GCM symmetric or RSA-4096 hybrid asymmetric encryption.",
inputSchema: {
type: "object",
properties: {
mode: {
type: "string",
enum: ["symmetric", "asymmetric", "data"],
description:
"Encryption mode: 'symmetric' (password-based AES-256-GCM), 'asymmetric' (RSA-4096 public key), or 'data' (auto-JSON AES-256-GCM)",
default: "symmetric",
},
data: {
description: "Plain text, JSON serializable object, or Base64 binary string to encrypt",
},
password: {
type: "string",
description:
"Password for symmetric encryption (required for 'symmetric' and 'data' modes)",
},
public_key_jwk: {
type: "object",
description: "JWK-formatted RSA public key (required for 'asymmetric' mode)",
},
},
required: ["mode", "data"],
},
},
{
name: "decrypt_payload",
description: "Decrypt ciphertext produced by WebCrypt back into plaintext or JSON object.",
inputSchema: {
type: "object",
properties: {
mode: {
type: "string",
enum: ["symmetric", "asymmetric", "data"],
description: "Decryption mode: 'symmetric', 'asymmetric', or 'data'",
default: "symmetric",
},
ciphertext: {
type: "string",
description: "Base64-encoded encrypted string from encrypt_payload",
},
password: {
type: "string",
description:
"Password used during encryption (required for 'symmetric' and 'data' modes)",
},
private_key_jwk: {
type: "object",
description: "JWK-formatted RSA private key (required for 'asymmetric' mode)",
},
},
required: ["mode", "ciphertext"],
},
},
{
name: "manage_keys",
description:
"Generate, export, or import cryptographic keypairs (RSA-4096/2048, ECDH P-256/P-384, HMAC).",
inputSchema: {
type: "object",
properties: {
action: {
type: "string",
enum: ["generate", "generate_random_password"],
description: "Action to perform",
},
type: {
type: "string",
enum: ["rsa", "ecdh", "ecdsa", "rsa-pss", "hmac"],
description: "Key type to generate (for action: 'generate')",
},
modulusLength: {
type: "number",
enum: [2048, 4096],
default: 4096,
description: "RSA modulus length in bits",
},
namedCurve: {
type: "string",
enum: ["P-256", "P-384"],
default: "P-256",
description: "Elliptic curve for ECDH",
},
length: {
type: "number",
default: 32,
description: "Length for random password or key in bytes",
},
},
required: ["action"],
},
},
{
name: "crypto_hash",
description:
"Compute cryptographic hashes (SHA-256, SHA-384, SHA-512, SHA3-256, SHA3-384, SHA3-512).",
inputSchema: {
type: "object",
properties: {
algorithm: {
type: "string",
enum: ["SHA-256", "SHA-384", "SHA-512", "SHA3-256", "SHA3-384", "SHA3-512"],
default: "SHA-256",
description: "Hash algorithm",
},
data: {
type: "string",
description: "Text data to hash",
},
encoding: {
type: "string",
enum: ["hex", "base64"],
default: "hex",
description: "Output digest encoding",
},
},
required: ["data"],
},
},
{
name: "sign_verify",
description:
"Create or verify digital signatures and HMAC authentication tags (ECDSA, RSA-PSS, HMAC, HMAC-SHA3).",
inputSchema: {
type: "object",
properties: {
action: {
type: "string",
enum: ["sign", "verify"],
description: "Action to perform: 'sign' or 'verify'",
},
algorithm: {
type: "string",
enum: ["ECDSA", "RSA-PSS", "HMAC", "HMAC-SHA3"],
default: "ECDSA",
description: "Signature or MAC algorithm",
},
data: {
type: "string",
description: "Message data to sign or verify",
},
signature: {
type: "string",
description: "Base64 signature tag (required for action: 'verify')",
},
password: {
type: "string",
description: "Password for HMAC key derivation (used with HMAC algorithms)",
},
key_jwk: {
type: "object",
description: "JWK formatted key for signing (private) or verifying (public)",
},
},
required: ["action", "data"],
},
},
{
name: "pqc_kem_sign",
description:
"Post-Quantum Cryptography operations (Kyber KEM, Dilithium signatures, and Hybrid classical+PQC KEM).",
inputSchema: {
type: "object",
properties: {
action: {
type: "string",
enum: [
"generate_kyber_keypair",
"kyber_encapsulate",
"kyber_decapsulate",
"hybrid_encapsulate",
"hybrid_decapsulate",
"generate_dilithium_keypair",
"dilithium_sign",
"dilithium_verify",
],
description: "PQC action to perform",
},
level: {
type: "string",
enum: ["Kyber512", "Kyber768", "Kyber1024", "Dilithium2", "Dilithium3", "Dilithium5"],
default: "Kyber768",
description: "Security level for Kyber or Dilithium",
},
public_key_b64: {
type: "string",
description: "Base64 encoded Kyber or Dilithium public key",
},
private_key_b64: {
type: "string",
description: "Base64 encoded Kyber or Dilithium private key",
},
ciphertext_b64: {
type: "string",
description: "Base64 encoded Kyber ciphertext (for decapsulate)",
},
rsa_public_key_jwk: {
type: "object",
description: "JWK RSA public key for hybrid encapsulate",
},
rsa_private_key_jwk: {
type: "object",
description: "JWK RSA private key for hybrid decapsulate",
},
rsa_wrapped_secret_b64: {
type: "string",
description: "Base64 RSA wrapped secret for hybrid decapsulate",
},
data: {
type: "string",
description: "Text message to sign or verify with Dilithium",
},
signature_b64: {
type: "string",
description: "Base64 Dilithium signature to verify",
},
},
required: ["action"],
},
},
];
+39
src/TimingSafeHelper.d.ts
// src/TimingSafeHelper.d.ts
/**
* Timing-safe utilities to prevent side-channel timing attacks.
*/
export class TimingSafeHelper {
/**
* Constant-time string comparison to prevent timing side-channel attacks.
*/
static constantTimeCompareStrings(a: string, b: string): Promise<boolean>;
/**
* Constant-time Uint8Array comparison to prevent timing side-channel attacks.
*/
static constantTimeCompareBuffers(a: Uint8Array, b: Uint8Array): Promise<boolean>;
/**
* Sleep with dummy operations to add timing noise.
*/
static sleepWithDummyOps(minMs?: number): Promise<void>;
/**
* Timing-safe signature verification.
*/
static timingSafeVerify(
crypto: any,
algorithmParams: any,
key: CryptoKey,
signature: Uint8Array,
data: Uint8Array
): Promise<boolean>;
/**
* Timing-safe wrapper for key derivation functions.
*/
static timingSafeDerive<T>(deriveFn: (...args: any[]) => Promise<T>, ...args: any[]): Promise<T>;
}
export default TimingSafeHelper;
+144
src/TimingSafeHelper.js
// version: 1.0.0
/**
* WebCrypt Security Helper - Timing Attack Protection
* Provides constant-time comparison and dummy operations to prevent timing oracle attacks
*/
class TimingSafeHelper {
/**
* Constant-time string comparison to prevent timing attacks
* @param {string} a - First string
* @param {string} b - Second string
* @returns {Promise<boolean>} True if strings are equal (in constant time)
*/
static async constantTimeCompareStrings(a, b) {
const encoder = new TextEncoder();
const bufA = encoder.encode(a);
const bufB = encoder.encode(b);
// Ensure same length to prevent early termination detection
const len = Math.max(bufA.length, bufB.length);
// XOR all bytes and track differences
let diff = 0;
for (let i = 0; i < len; i++) {
if (i < bufA.length && i < bufB.length) {
diff |= bufA[i] ^ bufB[i];
} else {
// Different lengths contribute to difference
diff |= 1;
}
}
return diff === 0;
}
/**
* Constant-time ArrayBuffer comparison to prevent timing attacks
* @param {ArrayBuffer} a - First buffer
* @param {ArrayBuffer} b - Second buffer
* @returns {Promise<boolean>} True if buffers are equal (in constant time)
*/
static async constantTimeCompareBuffers(a, b) {
const bufA = new Uint8Array(a);
const bufB = new Uint8Array(b);
// Ensure same length to prevent early termination detection
const len = Math.max(bufA.length, bufB.length);
// XOR all bytes and track differences
let diff = 0;
for (let i = 0; i < len; i++) {
if (i < bufA.length && i < bufB.length) {
diff |= bufA[i] ^ bufB[i];
} else {
// Different lengths contribute to difference
diff |= 1;
}
}
return diff === 0;
}
/**
* Delay execution for a minimum time window to prevent timing attacks.
* If startTime is provided, calculates elapsed time since startTime and sleeps for the remainder.
* @param {number} minMs - Target minimum total execution time in milliseconds (default: 10ms)
* @param {number|null} [startTime=null] - Optional performance.now() timestamp from start of operation
*/
static async sleepWithDummyOps(minMs = 10, startTime = null) {
const elapsed = startTime !== null ? performance.now() - startTime : 0;
const remaining = minMs - elapsed;
if (remaining > 0) {
await new Promise(resolve => setTimeout(resolve, Math.max(1, Math.ceil(remaining))));
}
}
/**
* Timing-safe signature verification wrapper
* Adds constant-time comparison and padding to prevent timing oracle attacks
* @param {any} crypto - Crypto API (subtle)
* @param {Object} algorithmParams - Algorithm parameters
* @param {CryptoKey} key - Verification key
* @param {ArrayBuffer} signature - Signature buffer
* @param {Uint8Array|ArrayBuffer} data - Data to verify
* @returns {Promise<boolean>} True if valid signature (with constant-time comparison)
*/
static async timingSafeVerify(crypto, algorithmParams, key, signature, data) {
const startTime = performance.now();
// Perform actual verification
let isValid;
try {
isValid = await crypto.subtle.verify(algorithmParams, key, signature, data);
} catch (e) {
isValid = false;
}
// Calculate minimum verification time to prevent timing attacks
const minVerificationTimeMs = 10; // At least 10ms for all verifications
const elapsedMs = performance.now() - startTime;
if (elapsedMs < minVerificationTimeMs) {
await this.sleepWithDummyOps(minVerificationTimeMs - elapsedMs);
}
return isValid;
}
/**
* Timing-safe key derivation verification wrapper
* Ensures consistent timing regardless of password correctness
* @param {Function} deriveFn - Key derivation function
* @param {...any} args - Arguments to pass to derive function
* @returns {Promise<CryptoKey>} Derived key
*/
static async timingSafeDerive(deriveFn, ...args) {
const startTime = performance.now();
let key;
try {
key = await deriveFn(...args);
} catch (e) {
// Even on error, wait minimum time to prevent timing attacks
const elapsedMs = performance.now() - startTime;
if (elapsedMs < 50) {
await this.sleepWithDummyOps(50 - elapsedMs);
}
throw e;
}
// Ensure minimum derivation time (e.g., 50ms for strong KDFs)
const minDerivationTimeMs = 50;
const elapsedMs = performance.now() - startTime;
if (elapsedMs < minDerivationTimeMs) {
await this.sleepWithDummyOps(minDerivationTimeMs - elapsedMs);
}
return key;
}
}
export default TimingSafeHelper;
+200
src/WebCrypt.d.ts
// src/WebCrypt.d.ts
/**
* WebCrypt – Zero-dependency quantum-resistant AES-256-GCM encryption
*
* Supports:
* - Text encryption/decryption
* - Large file encryption/decryption (streaming)
* - WebRTC Insertable Streams E2EE (video + audio)
* - HMAC for message authentication
*
* Works in Browser, Node.js 18+, Deno, Cloudflare Workers
*/
declare class WebCrypt {
static readonly ALGORITHM: "AES-GCM";
static readonly KEY_LENGTH: 256;
static readonly IV_LENGTH: 12;
static readonly SALT_LENGTH: 16;
static readonly PBKDF2_ITERATIONS: number;
static readonly HASH_ALGORITHM: "SHA-256";
static readonly CHUNK_SIZE: number;
static readonly WEBRTC_SALT: Uint8Array;
static readonly DEFAULT_HMAC_SALT: Uint8Array;
/**
* Generates a cryptographically secure random salt for HMAC key derivation.
* @param length Salt length in bytes (default: 16)
*/
static generateHmacSalt(length?: number): Uint8Array;
/**
* Encrypts a string and returns Base64-encoded ciphertext
* @param text Plain text to encrypt
* @param password Password (or shared secret)
* @returns Base64 string (salt + iv + ciphertext)
*/
encryptText(text: string, password: string): Promise<string>;
/**
* Decrypts a Base64 string produced by encryptText()
* @param base64 Encrypted data from encryptText()
* @param password Must match encryption password
* @returns Original plain text
* @throws If password is wrong or data is corrupted
*/
decryptText(base64: string, password: string): Promise<string>;
/**
* Encrypts a File or Blob using streaming (low memory, handles huge files)
* @param file File or Blob to encrypt
* @param password Encryption password
* @param options Optional configuration object ({ parallelChunks?: number })
* @returns Object with encrypted Blob and suggested filename
*/
encryptFile(
file: File | Blob,
password: string,
options?: { parallelChunks?: number }
): Promise<{
blob: Blob;
filename: string;
}>;
/**
* Decrypts a .encrypted file produced by encryptFile()
* @param file Encrypted File or Blob
* @param password Must match encryption password
* @param options Optional configuration object ({ parallelChunks?: number })
* @returns Object with decrypted Blob and original filename
* @throws If password is wrong or file is corrupted
*/
decryptFile(
file: File | Blob,
password: string,
options?: { parallelChunks?: number }
): Promise<{
blob: Blob;
filename: string;
}>;
/**
* Creates an encryption transform for WebRTC Insertable Streams
* Use with RTCRtpSender.transform
* @param password Shared secret both peers must know
*/
createEncryptTransform(
password: string
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Creates a decryption transform for WebRTC Insertable Streams
* Use with RTCRtpReceiver.transform
* @param password Must match sender's password
*/
createDecryptTransform(
password: string
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Generates or derives an HMAC key.
* @param password Optional password for PBKDF2 derivation (if provided, uses 600_000 iterations).
* @param hash Hash algorithm (default: 'SHA-256').
* @param salt Optional salt for deterministic derivation.
* @returns Usable HMAC key.
*/
generateHmacKey(
password?: string,
hash?: "SHA-256" | "SHA-384" | "SHA-512",
salt?: Uint8Array | string
): Promise<CryptoKey>;
/**
* Computes HMAC on data.
* @param data Text or ArrayBuffer to authenticate.
* @param key HMAC key from generateHmacKey.
* @returns Base64-encoded HMAC tag.
*/
computeHmac(data: string | ArrayBuffer, key: CryptoKey): Promise<string>;
/**
* Verifies HMAC on data.
* @param data Text or ArrayBuffer to verify.
* @param hmac Base64-encoded HMAC tag to check.
* @param key HMAC key.
* @returns True if valid.
*/
verifyHmac(data: string | ArrayBuffer, hmac: string, key: CryptoKey): Promise<boolean>;
/**
* Generate a quantum-resistant HMAC key using SHA-3 hash.
* @param password Optional password for derivation
* @param hash Hash algorithm: 'SHA3-256' | 'SHA3-384' | 'SHA3-512' (default: SHA3-256)
* @param salt Optional salt for deterministic derivation.
* @param iterations Iterations count for SHA-3 KDF derivation (default: 10,000)
* @returns Usable HMAC key with SHA-3
*/
generateHmacKeySHA3(
password?: string,
hash?: "SHA3-256" | "SHA3-384" | "SHA3-512",
salt?: Uint8Array | string,
iterations?: number
): Promise<CryptoKey>;
/**
* Compute HMAC using SHA-3 (quantum-resistant).
* @param data Data to authenticate
* @param key HMAC key from generateHmacKeySHA3
* @returns Base64-encoded HMAC tag
*/
computeHmacSHA3(data: string | ArrayBuffer, key: CryptoKey): Promise<string>;
/**
* Verify HMAC using SHA-3 (quantum-resistant).
* @param data Data to verify
* @param hmac Base64-encoded HMAC tag
* @param key HMAC key
* @returns True if valid
*/
verifyHmacSHA3(data: string | ArrayBuffer, hmac: string, key: CryptoKey): Promise<boolean>;
/**
* Automatically serializes any JavaScript object or array to JSON before encrypting.
*/
encryptData(data: any, password: string): Promise<string>;
/**
* Decrypts the data and automatically parses it back into a JavaScript object.
*/
decryptData(base64: string, password: string): Promise<any>;
/**
* Utility to generate a cryptographically secure random password or key string.
*/
generateRandomPassword(length?: number): string;
/**
* Clear entire key cache.
*/
clearKeyCache(): void;
/**
* Stop automatic cache cleanup interval.
*/
stopAutoCleanup(): void;
}
/**
* Default export and named export
*/
export { WebCrypt };
export default WebCrypt;
+697
src/WebCrypt.js
// src/WebCrypt.js
// version: 1.0.0
import { arrayBufferToBase64, base64ToArrayBuffer } from "./_base64.js";
import { getCrypto } from "./_crypto.js";
/**
* WebCrypt — Password-based symmetric encryption using AES-256-GCM.
* Maintained by PuterVision (https://putervision.com).
*
* DISCLAIMER: Provided "AS IS" without warranty of any kind. PuterVision
* disclaims all liability for data loss, security breaches, or misuse.
*
* Features:
* - Text and JSON data encryption/decryption
* - Streaming file encryption/decryption (constant memory)
* - WebRTC Insertable Streams E2EE
* - HMAC (SHA-256/384/512 and SHA-3)
* - Key caching with TTL and LRU eviction
*
* @example
* const wc = new WebCrypt();
* const encrypted = await wc.encryptText("secret", "password");
* const decrypted = await wc.decryptText(encrypted, "password");
*/
export class WebCrypt {
// AES-256-GCM: Provides 128-bit effective security against Grover's quantum algorithm
// - Authenticated encryption mode preventing tampering and ensuring integrity
static ALGORITHM = "AES-GCM";
// KEY_LENGTH: 256 bits for AES-256, offering strong symmetric encryption (quantum-resistant at this size)
static KEY_LENGTH = 256;
// IV_LENGTH: 12 bytes (96 bits), standard for AES-GCM to ensure unique nonces per encryption
static IV_LENGTH = 12;
// SALT_LENGTH: 16 bytes (128 bits), random per-message salt for PBKDF2 to prevent rainbow table attacks
static SALT_LENGTH = 16;
// PBKDF2_ITERATIONS: 600,000 rounds of key stretching; OWASP-recommended for 2025+ to resist brute-force and ASIC attacks
static PBKDF2_ITERATIONS = 600_000;
// HASH_ALGORITHM: SHA-256 for PBKDF2 hashing; collision-resistant and widely supported
static HASH_ALGORITHM = "SHA-256";
// Optimized for large files: 8MB chunks balance speed and memory (prevents OOM on 10GB+ files)
static CHUNK_SIZE = 8 * 1024 * 1024;
// WEBRTC_SALT: Fixed salt for WebRTC key derivation; ensures consistent keys between peers without transmission
/**
* Default static salt for WebRTC transform convenience.
* @warning For production applications, pass a custom salt per session.
*/
static WEBRTC_SALT = new TextEncoder().encode("WebCrypt-E2EE-v1-2025");
/**
* Default static salt for deterministic password-derived HMAC key derivation.
* @warning For production security, generate custom salts with WebCrypt.generateHmacSalt().
*/
static DEFAULT_HMAC_SALT = new TextEncoder().encode("WebCrypt-HMAC-DefaultSalt-v0.6");
/**
* Generates a cryptographically secure random salt for HMAC key derivation.
* @param {number} [length=16] Length of salt in bytes
* @returns {Uint8Array} Random salt bytes
*/
static generateHmacSalt(length = 16) {
const cryptoInstance =
globalThis.crypto || (typeof require !== "undefined" && require("crypto").webcrypto);
return cryptoInstance.getRandomValues(new Uint8Array(length));
}
// Caches derived keys for instant reuse with same password/salt (performance optimization)
static MAX_KEY_CACHE_SIZE = 10; // LRU cache max size
static KEY_CACHE_TTL_MS = 300_000; // 5 minutes TTL per key
constructor() {
this.keyCache = new Map();
this._keyCacheCleanupInterval = null;
this._startAutoCleanup();
}
/**
* Start automatic cache cleanup every minute to remove expired keys
*/
_startAutoCleanup() {
// Clean up immediately on start
this._cleanupExpiredKeys();
// Then clean up every minute
this._keyCacheCleanupInterval = setInterval(() => {
this._cleanupExpiredKeys();
}, 60_000);
// Unref timer in Node.js environments to prevent holding the event loop open
if (
this._keyCacheCleanupInterval &&
typeof this._keyCacheCleanupInterval.unref === "function"
) {
this._keyCacheCleanupInterval.unref();
}
}
/**
* Clean up expired keys from cache based on TTL
*/
_cleanupExpiredKeys() {
const now = Date.now();
const keysToDelete = [];
for (const [cacheKey, value] of this.keyCache.entries()) {
if (now - value.createdAt > WebCrypt.KEY_CACHE_TTL_MS) {
keysToDelete.push(cacheKey);
}
}
for (const key of keysToDelete) {
const entry = this.keyCache.get(key);
if (entry) {
entry.key = null;
}
this.keyCache.delete(key);
}
}
/**
* Clear entire key cache and securely erase all keys
*/
clearKeyCache() {
for (const [key, value] of this.keyCache) {
if (value) {
value.key = null;
}
}
this.keyCache.clear();
}
/**
* Stop automatic cleanup interval
*/
stopAutoCleanup() {
if (this._keyCacheCleanupInterval) {
clearInterval(this._keyCacheCleanupInterval);
this._keyCacheCleanupInterval = null;
}
}
_getCrypto() {
return getCrypto();
}
// Derives AES key using PBKDF2: High iterations ensure quantum-resistant key stretching
// Cache hit: O(1) reuse; miss: Computes once per unique password/salt
// LRU eviction when cache exceeds MAX_KEY_CACHE_SIZE
async _deriveKey(password, salt) {
const crypto = this._getCrypto();
const cacheKey = `${password}:${btoa(String.fromCharCode(...salt))}`;
if (this.keyCache.has(cacheKey)) {
// Update access time for LRU tracking
const value = this.keyCache.get(cacheKey);
value.lastAccessed = Date.now();
return value.key;
}
const enc = new TextEncoder();
const keyMaterial = await crypto.subtle.importKey(
"raw",
enc.encode(password),
"PBKDF2",
false,
["deriveKey"]
);
const key = await crypto.subtle.deriveKey(
{
name: "PBKDF2",
salt,
iterations: WebCrypt.PBKDF2_ITERATIONS,
hash: WebCrypt.HASH_ALGORITHM,
},
keyMaterial,
{ name: WebCrypt.ALGORITHM, length: WebCrypt.KEY_LENGTH },
false,
["encrypt", "decrypt"]
);
// LRU eviction if cache is full
if (this.keyCache.size >= WebCrypt.MAX_KEY_CACHE_SIZE) {
// Find oldest unused key (by lastAccessed or createdAt)
let oldestKey = null;
let oldestTime = Infinity;
for (const [k, v] of this.keyCache.entries()) {
const accessTime = v.lastAccessed || v.createdAt;
if (accessTime < oldestTime) {
oldestTime = accessTime;
oldestKey = k;
}
}
if (oldestKey) {
this.keyCache.delete(oldestKey);
}
}
this.keyCache.set(cacheKey, {
key: key,
createdAt: Date.now(),
lastAccessed: Date.now(),
});
return key;
}
// ────────────────────── Safe Base64 (stack-safe, high performance) ──────────────────────
// Chunked conversion avoids stack overflow and O(N^2) memory churn on large buffers
_arrayBufferToBase64(buffer) {
return arrayBufferToBase64(buffer);
}
_base64ToArrayBuffer(base64) {
return base64ToArrayBuffer(base64);
}
// ────────────────────── Text Encryption (now safe for 10 MB+) ──────────────────────
/**
* Encrypt a text string using AES-256-GCM with a password.
* Generates a unique random salt and IV per call.
*
* @param {string} text - Plain text to encrypt
* @param {string} password - Password used for key derivation
* @returns {Promise<string>} Base64-encoded string containing salt + IV + ciphertext
*/
async encryptText(text, password) {
const cryptoInstance = this._getCrypto();
const data = new TextEncoder().encode(text);
const salt = cryptoInstance.getRandomValues(new Uint8Array(WebCrypt.SALT_LENGTH));
const iv = cryptoInstance.getRandomValues(new Uint8Array(WebCrypt.IV_LENGTH));
const key = await this._deriveKey(password, salt);
const encrypted = await cryptoInstance.subtle.encrypt(
{ name: WebCrypt.ALGORITHM, iv },
key,
data
);
const result = new Uint8Array(WebCrypt.SALT_LENGTH + WebCrypt.IV_LENGTH + encrypted.byteLength);
result.set(salt, 0);
result.set(iv, WebCrypt.SALT_LENGTH);
result.set(new Uint8Array(encrypted), WebCrypt.SALT_LENGTH + WebCrypt.IV_LENGTH);
return this._arrayBufferToBase64(result.buffer);
}
// Max encrypted data size for single-buffer operations (1GB threshold)
static MAX_ENCRYPTED_DATA_SIZE = 1024 * 1024 * 1024;
/**
* Decrypt a Base64 string produced by encryptText().
*
* @param {string} b64 - Base64-encoded encrypted data from encryptText()
* @param {string} password - Must match the password used for encryption
* @returns {Promise<string>} Original plain text
* @throws {Error} If password is wrong, data is corrupted, or data exceeds 10 MB
*/
async decryptText(b64, password) {
try {
const cryptoInstance = this._getCrypto();
const combined = new Uint8Array(this._base64ToArrayBuffer(b64));
// DoS protection: Check size before processing
if (combined.length > WebCrypt.MAX_ENCRYPTED_DATA_SIZE) {
throw new Error("Decryption failed");
}
if (combined.length < WebCrypt.SALT_LENGTH + WebCrypt.IV_LENGTH) {
throw new Error("Decryption failed");
}
const salt = combined.slice(0, WebCrypt.SALT_LENGTH);
const iv = combined.slice(WebCrypt.SALT_LENGTH, WebCrypt.SALT_LENGTH + WebCrypt.IV_LENGTH);
const ciphertext = combined.slice(WebCrypt.SALT_LENGTH + WebCrypt.IV_LENGTH);
const key = await this._deriveKey(password, salt);
const decrypted = await cryptoInstance.subtle.decrypt(
{ name: WebCrypt.ALGORITHM, iv },
key,
ciphertext
);
return new TextDecoder().decode(decrypted);
} catch (e) {
// Log detailed error only in development
if (typeof process !== "undefined" && process.env && process.env.NODE_ENV !== "production") {
console.warn("WebCrypt decryptText failed:", e.message);
}
throw e;
}
}
/**
* Encrypt a File or Blob using streaming (constant memory usage).
* Plaintext is chunked into deterministic 8MB blocks, each encrypted with AES-256-GCM
* and a counter-derived IV.
*
* @param {File|Blob} fileOrBlob - File or Blob to encrypt
* @param {string} password - Encryption password
* @param {Object} [options={}] - Optional options ({ parallelChunks: 1 })
* @returns {Promise<{blob: Blob, filename: string}>} Encrypted blob and suggested filename
*/
async encryptFile(fileOrBlob, password, options = {}) {
const parallelChunks = options.parallelChunks || 1;
const cryptoInstance = this._getCrypto();
const salt = cryptoInstance.getRandomValues(new Uint8Array(WebCrypt.SALT_LENGTH));
const baseIv = cryptoInstance.getRandomValues(new Uint8Array(WebCrypt.IV_LENGTH));
const key = await this._deriveKey(password, salt);
const chunks = [];
const reader = fileOrBlob.stream().getReader();
let counter = 0;
let pendingPromises = [];
let buffer = new Uint8Array(0);
const encryptChunk = plaintextChunk => {
const iv = new Uint8Array(WebCrypt.IV_LENGTH);
iv.set(baseIv);
new DataView(iv.buffer).setUint32(WebCrypt.IV_LENGTH - 4, counter++, true);
const promise = cryptoInstance.subtle.encrypt(
{ name: WebCrypt.ALGORITHM, iv },
key,
plaintextChunk
);
pendingPromises.push(promise);
};
while (true) {
const { done, value } = await reader.read();
if (done) break;
if (buffer.length === 0) {
buffer = value instanceof Uint8Array ? value : new Uint8Array(value);
} else {
const newBuf = new Uint8Array(buffer.length + value.byteLength);
newBuf.set(buffer, 0);
newBuf.set(value instanceof Uint8Array ? value : new Uint8Array(value), buffer.length);
buffer = newBuf;
}
while (buffer.length >= WebCrypt.CHUNK_SIZE) {
const chunk = buffer.subarray(0, WebCrypt.CHUNK_SIZE);
encryptChunk(chunk);
buffer = buffer.subarray(WebCrypt.CHUNK_SIZE);
if (pendingPromises.length >= parallelChunks) {
const resolved = await Promise.all(pendingPromises);
chunks.push(...resolved);
pendingPromises = [];
}
}
}
if (buffer.length > 0 || counter === 0) {
encryptChunk(buffer);
}
if (pendingPromises.length > 0) {
const resolved = await Promise.all(pendingPromises);
chunks.push(...resolved);
}
const header = new Uint8Array(WebCrypt.SALT_LENGTH + WebCrypt.IV_LENGTH);
header.set(salt, 0);
header.set(baseIv, WebCrypt.SALT_LENGTH);
const filename = (fileOrBlob.name || "encrypted") + ".encrypted";
const newBlob = new Blob([header, ...chunks]);
newBlob.name = filename;
return { blob: newBlob, filename };
}
/**
* Decrypt a .encrypted file produced by encryptFile().
*
* @param {File|Blob} fileOrBlob - Encrypted File or Blob
* @param {string} password - Must match the password used for encryption
* @param {Object} [options={}] - Optional options ({ parallelChunks: 1 })
* @returns {Promise<{blob: Blob, filename: string}>} Decrypted blob and original filename
* @throws {Error} If password is wrong, file is corrupted, or file exceeds 1 GB
*/
async decryptFile(fileOrBlob, password, options = {}) {
const parallelChunks = options.parallelChunks || 1;
const cryptoInstance = this._getCrypto();
// DoS protection: Check size before loading entire file into memory
const fileSize = fileOrBlob.size || (fileOrBlob.blob && fileOrBlob.blob.size);
if (fileSize && fileSize > WebCrypt.MAX_ENCRYPTED_DATA_SIZE) {
throw new Error("File too large for decryption");
}
const data = new Uint8Array(await fileOrBlob.arrayBuffer());
// DoS protection: Check size after loading
if (data.length > WebCrypt.MAX_ENCRYPTED_DATA_SIZE) {
throw new Error("File too large for decryption");
}
if (data.length < WebCrypt.SALT_LENGTH + WebCrypt.IV_LENGTH) {
throw new Error("Decryption failed");
}
const salt = data.slice(0, WebCrypt.SALT_LENGTH);
const baseIv = data.slice(WebCrypt.SALT_LENGTH, WebCrypt.SALT_LENGTH + WebCrypt.IV_LENGTH);
const ciphertext = data.slice(WebCrypt.SALT_LENGTH + WebCrypt.IV_LENGTH);
const key = await this._deriveKey(password, salt);
const chunks = [];
let offset = 0,
counter = 0;
let pendingPromises = [];
const CIPHERTEXT_CHUNK_SIZE = WebCrypt.CHUNK_SIZE + 16; // AES-GCM 16-byte auth tag per chunk
while (offset < ciphertext.byteLength) {
const size = Math.min(CIPHERTEXT_CHUNK_SIZE, ciphertext.byteLength - offset);
const chunk = ciphertext.subarray(offset, offset + size);
const iv = new Uint8Array(WebCrypt.IV_LENGTH);
iv.set(baseIv);
new DataView(iv.buffer).setUint32(WebCrypt.IV_LENGTH - 4, counter++, true);
const promise = cryptoInstance.subtle.decrypt({ name: WebCrypt.ALGORITHM, iv }, key, chunk);
pendingPromises.push(promise);
offset += size;
if (pendingPromises.length >= parallelChunks) {
const resolved = await Promise.all(pendingPromises);
chunks.push(...resolved);
pendingPromises = [];
}
}
if (pendingPromises.length > 0) {
const resolved = await Promise.all(pendingPromises);
chunks.push(...resolved);
}
const filename = (fileOrBlob.name || "decrypted").replace(/\.encrypted$/i, "");
return { blob: new Blob(chunks), filename };
}
/**
* Create an encryption transform for WebRTC Insertable Streams.
* Use with RTCRtpSender.transform for E2EE video/audio calls.
*
* @param {string} password - Shared secret both peers must know
* @returns {Promise<Function>} Transform function for RTCRtpScriptTransform
*/
async createEncryptTransform(password) {
const cryptoInstance = this._getCrypto();
const key = await this._deriveKey(password, WebCrypt.WEBRTC_SALT);
return async (frame, controller) => {
const iv = cryptoInstance.getRandomValues(new Uint8Array(WebCrypt.IV_LENGTH));
const encrypted = await cryptoInstance.subtle.encrypt(
{ name: WebCrypt.ALGORITHM, iv },
key,
frame.data
);
const newData = new Uint8Array(WebCrypt.IV_LENGTH + encrypted.byteLength);
newData.set(iv, 0);
newData.set(new Uint8Array(encrypted), WebCrypt.IV_LENGTH);
frame.data = newData.buffer;
controller.enqueue(frame);
};
}
/**
* Create a decryption transform for WebRTC Insertable Streams.
* Use with RTCRtpReceiver.transform for E2EE video/audio calls.
*
* @param {string} password - Must match sender's password
* @returns {Promise<Function>} Transform function for RTCRtpScriptTransform
*/
async createDecryptTransform(password) {
const cryptoInstance = this._getCrypto();
const key = await this._deriveKey(password, WebCrypt.WEBRTC_SALT);
return async (frame, controller) => {
if (frame.data.byteLength < WebCrypt.IV_LENGTH) return controller.enqueue(frame);
const iv = frame.data.slice(0, WebCrypt.IV_LENGTH);
const ciphertext = frame.data.slice(WebCrypt.IV_LENGTH);
try {
const decrypted = await cryptoInstance.subtle.decrypt(
{ name: WebCrypt.ALGORITHM, iv },
key,
ciphertext
);
frame.data = decrypted;
} catch (e) {
console.warn("WebRTC frame decryption failed");
}
controller.enqueue(frame);
};
}
/**
* Generates or derives an HMAC key.
* @param {string} [password] Optional password for PBKDF2 derivation (if provided, uses 600_000 iterations like existing ops).
* @param {string} [hash='SHA-256'] Hash algorithm.
* @param {Uint8Array|string} [customSalt=null] Optional salt for deterministic derivation (defaults to WebCrypt.DEFAULT_HMAC_SALT if omitted).
* @returns {Promise<CryptoKey>} Usable HMAC key.
*/
async generateHmacKey(password, hash = "SHA-256", customSalt = null) {
const crypto = this._getCrypto();
let keyMaterial;
if (password) {
// Derive from password using PBKDF2 with deterministic salt
const salt = customSalt
? typeof customSalt === "string"
? new TextEncoder().encode(customSalt)
: customSalt
: WebCrypt.DEFAULT_HMAC_SALT;
const pbkdf2Params = {
name: "PBKDF2",
salt,
iterations: 600_000,
hash: "SHA-256",
};
const baseKey = await crypto.subtle.importKey(
"raw",
new TextEncoder().encode(password),
{ name: "PBKDF2" },
false,
["deriveBits", "deriveKey"]
);
keyMaterial = await crypto.subtle.deriveBits(pbkdf2Params, baseKey, 256); // 256-bit key
} else {
// Generate random key if no password
keyMaterial = crypto.getRandomValues(new Uint8Array(32)); // 256-bit random key
}
return crypto.subtle.importKey(
"raw",
keyMaterial,
{ name: "HMAC", hash },
false, // Non-exportable for security
["sign", "verify"]
);
}
/**
* Computes HMAC on data.
* @param {string|ArrayBuffer} data Text or ArrayBuffer to authenticate.
* @param {CryptoKey} key HMAC key from generateHmacKey.
* @returns {Promise<string>} Base64-encoded HMAC tag.
*/
async computeHmac(data, key) {
const crypto = this._getCrypto();
const dataBuffer = typeof data === "string" ? new TextEncoder().encode(data) : data;
const signature = await crypto.subtle.sign("HMAC", key, dataBuffer);
return this._arrayBufferToBase64(signature);
}
/**
* Verifies HMAC on data.
* @param {string|ArrayBuffer} data Text or ArrayBuffer to verify.
* @param {string} hmac Base64-encoded HMAC tag to check.
* @param {CryptoKey} key HMAC key.
* @returns {Promise<boolean>} True if valid.
*/
async verifyHmac(data, hmac, key) {
const crypto = this._getCrypto();
const dataBuffer = typeof data === "string" ? new TextEncoder().encode(data) : data;
const signatureBuffer = new Uint8Array(this._base64ToArrayBuffer(hmac));
return crypto.subtle.verify("HMAC", key, signatureBuffer, dataBuffer);
}
// ════════════════════════════ Post-Quantum HMAC (SHA-3) ════════════════════════════
/**
* Generate a quantum-resistant HMAC key using SHA-3 hash.
* @param {string} [password] Optional password for derivation
* @param {string} [hash='SHA3-256'] Hash algorithm: 'SHA3-256', 'SHA3-384', 'SHA3-512'
* @param {Uint8Array|string} [customSalt=null] Optional salt for deterministic derivation (defaults to WebCrypt.DEFAULT_HMAC_SALT if omitted)
* @param {number} [iterations=10000] Number of hash iterations for key derivation (default: 10,000 for high performance)
* @returns {Promise<CryptoKey>} Usable HMAC key with SHA-3
*/
async generateHmacKeySHA3(password, hash = "SHA3-256", customSalt = null, iterations = 10000) {
const crypto = this._getCrypto();
let keyMaterial;
if (password) {
const salt = customSalt
? typeof customSalt === "string"
? new TextEncoder().encode(customSalt)
: customSalt
: WebCrypt.DEFAULT_HMAC_SALT;
const encoder = new TextEncoder();
let material = new Uint8Array(password.length + salt.byteLength);
material.set(encoder.encode(password));
material.set(salt, password.length);
// Iterative SHA-3 KDF (configurable iterations, default 10k)
for (let i = 0; i < iterations; i++) {
const hashInput = new Uint8Array(material.byteLength + 4);
hashInput.set(material);
new DataView(hashInput.buffer).setUint32(material.byteLength, i, true);
try {
material = new Uint8Array(await crypto.subtle.digest(hash, hashInput));
} catch (e) {
// Fall back to SHA-256
material = new Uint8Array(await crypto.subtle.digest("SHA-256", hashInput));
}
}
keyMaterial = material.slice(0, 32);
} else {
keyMaterial = crypto.getRandomValues(new Uint8Array(32));
}
// Map SHA3-256/384/512 to valid HMAC hash algorithms (SHA-256/384/512)
let hmacHash = hash;
if (hash.startsWith("SHA3-")) {
hmacHash = hash.replace("SHA3-", "SHA-");
}
return crypto.subtle.importKey("raw", keyMaterial, { name: "HMAC", hash: hmacHash }, false, [
"sign",
"verify",
]);
}
/**
* Compute HMAC using SHA-3 (quantum-resistant).
* @param {string|ArrayBuffer} data Data to authenticate
* @param {CryptoKey} key HMAC key from generateHmacKeySHA3
* @returns {Promise<string>} Base64-encoded HMAC tag
*/
async computeHmacSHA3(data, key) {
const crypto = this._getCrypto();
const dataBuffer = typeof data === "string" ? new TextEncoder().encode(data) : data;
const signature = await crypto.subtle.sign("HMAC", key, dataBuffer);
return this._arrayBufferToBase64(signature);
}
/**
* Verify HMAC using SHA-3 (quantum-resistant).
* @param {string|ArrayBuffer} data Data to verify
* @param {string} hmac Base64-encoded HMAC tag
* @param {CryptoKey} key HMAC key
* @returns {Promise<boolean>} True if valid
*/
async verifyHmacSHA3(data, hmac, key) {
const crypto = this._getCrypto();
const dataBuffer = typeof data === "string" ? new TextEncoder().encode(data) : data;
const signatureBuffer = Uint8Array.from(atob(hmac), c => c.charCodeAt(0));
return crypto.subtle.verify("HMAC", key, signatureBuffer, dataBuffer);
}
// ────────────────────── Human-Friendly Data Operations ──────────────────────
/**
* Automatically serializes any JavaScript object or array to JSON before encrypting.
* Eliminates the need for manual JSON.stringify.
* @param {any} data - Any serializable JavaScript data (object, array, string, number)
* @param {string} password - The encryption password
* @returns {Promise<string>} Base64-encoded encrypted string
*/
async encryptData(data, password) {
try {
const text = JSON.stringify(data);
return await this.encryptText(text, password);
} catch (e) {
if (e.message && e.message.startsWith("WebCrypt")) throw e;
throw new Error(`Failed to serialize data: ${e.message}`);
}
}
/**
* Decrypts the data and automatically parses it back into a JavaScript object.
* @param {string} b64 - Base64-encoded encrypted string
* @param {string} password - The decryption password
* @returns {Promise<any>} The original JavaScript data
*/
async decryptData(b64, password) {
try {
const text = await this.decryptText(b64, password);
return JSON.parse(text);
} catch (e) {
if (e instanceof SyntaxError) {
throw new Error(`Failed to parse decrypted data as JSON: ${e.message}`);
}
throw e;
}
}
/**
* Utility to generate a cryptographically secure random password or key string.
* Useful for generating strong unique keys for encryption passes.
* @param {number} length - Length of the generated password in bytes (default: 32)
* @returns {string} Hex-encoded random password string
*/
generateRandomPassword(length = 32) {
const cryptoInstance = this._getCrypto();
const randomBytes = cryptoInstance.getRandomValues(new Uint8Array(length));
return Array.from(randomBytes, b => b.toString(16).padStart(2, "0")).join("");
}
}
+626
src/WebCryptAsym.d.ts
// WebCryptAsym.d.ts
/**
* Asymmetric encryption utility using RSA-OAEP + AES-GCM hybrid encryption.
* Supports text, file (streaming), and WebRTC insertable streams.
*/
declare class WebCryptAsym {
/**
* RSA-OAEP algorithm parameters
*/
static readonly RSA_ALGORITHM: AlgorithmIdentifier;
/**
* Parameters for RSA key generation (4096-bit, SHA-256)
*/
static readonly RSA_KEY_PARAMS: RsaHashedKeyGenParams;
/**
* AES-GCM algorithm name
*/
static readonly AES_ALGORITHM: "AES-GCM";
/**
* AES key length (256 bits)
*/
static readonly AES_LENGTH: 256;
/**
* IV length for AES-GCM (12 bytes recommended)
*/
static readonly IV_LENGTH: 12;
/**
* Chunk size for file streaming (8 MB)
*/
static readonly CHUNK_SIZE: number;
/**
* Fixed salt-like identifier for WebRTC transforms
*/
static readonly WEBRTC_SALT: Uint8Array;
/**
* PBKDF2 algorithm name
*/
static readonly PBKDF2_ALGORITHM: "PBKDF2";
/**
* Default PBKDF2 hash algorithm
*/
static readonly PBKDF2_HASH: "SHA-256";
/**
* Default number of PBKDF2 iterations
*/
static readonly PBKDF2_ITERATIONS: number;
/**
* Argon2 algorithm name
*/
static readonly ARGON2_ALGORITHM: "Argon2id";
/**
* RSA-PSS algorithm name
*/
static readonly RSA_PSS_ALGORITHM: "RSA-PSS";
/**
* EdDSA algorithm name
*/
static readonly ED25519_ALGORITHM: "EdDSA";
/**
* Ed25519 curve name
*/
static readonly ED25519_CURVE: "Ed25519";
constructor();
/**
* Generate a new RSA-4096 key pair
*/
generateKeyPair(): Promise<CryptoKeyPair>;
/**
* Generate an ECDSA signing key pair
* @param curve - Supported curves: 'P-256' (default), 'P-384'
*/
generateSigningKeyPair(curve?: string): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Generate an EdDSA signing key pair
*/
generateEdDSASigningKeyPair(): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Generate an RSA-PSS signing key pair
* @param modulusLength - RSA key size in bits (default: 2048)
*/
generateRSAPSSigningKeyPair(modulusLength?: number): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Export public key to Base64-encoded SPKI format
*/
exportPublicKey(publicKey: CryptoKey): Promise<string>;
/**
* Export private key to Base64-encoded PKCS8 format
*/
exportPrivateKey(privateKey: CryptoKey): Promise<string>;
/**
* Import public key from Base64 SPKI string
*/
importPublicKey(b64: string): Promise<CryptoKey>;
/**
* Import private key from Base64 PKCS8 string
*/
importPrivateKey(b64: string): Promise<CryptoKey>;
/**
* Encrypt text using recipient's public key (hybrid: RSA-wrapped AES-GCM)
* @returns Base64-encoded encrypted data
*/
encryptText(text: string, publicKey: CryptoKey): Promise<string>;
/**
* Decrypt text using own private key
*/
decryptText(encryptedB64: string, privateKey: CryptoKey): Promise<string>;
/**
* Encrypt a file/blob using recipient's public key (streaming)
* @returns Object with encrypted Blob and suggested filename
*/
encryptFile(
fileOrBlob: Blob | File,
publicKey: CryptoKey,
options?: { parallelChunks?: number }
): Promise<{ blob: Blob; filename: string }>;
/**
* Decrypt an asymmetrically encrypted file/blob
* @returns Object with decrypted Blob and original filename
*/
decryptFile(
fileOrBlob: Blob | File,
privateKey: CryptoKey,
options?: { parallelChunks?: number }
): Promise<{ blob: Blob; filename: string }>;
/**
* Create an encryption transform function for WebRTC insertable streams
* Sends encrypted session key in the first frame.
*/
createEncryptTransform(
publicKey: CryptoKey
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Create a decryption transform function for WebRTC insertable streams
* Extracts session key from first frame and decrypts subsequent frames.
*/
createDecryptTransform(
privateKey: CryptoKey
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Create a hybrid encryption transform that supports both classical and post-quantum approaches
* @param publicKey - RSA public key for hybrid encryption
* @param usePostQuantum - Whether to use post-quantum hybrid approach
*/
createHybridEncryptTransform(
publicKey: CryptoKey,
usePostQuantum?: boolean
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Enhanced WebRTC transform with progress tracking
* @param publicKey - RSA public key for hybrid encryption
* @param onProgress - Callback function to report encryption progress
*/
createEncryptTransformWithProgress(
publicKey: CryptoKey,
onProgress?: (bytesProcessed: number) => void
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Encrypt a file with progress tracking
* @param fileOrBlob - File or Blob to encrypt
* @param publicKey - RSA public key for hybrid encryption
* @param onProgress - Callback function to report encryption progress
*/
encryptFileWithProgress(
fileOrBlob: Blob | File,
publicKey: CryptoKey,
onProgress?: (bytesProcessed: number) => void
): Promise<{ blob: Blob; filename: string }>;
/**
* Decrypt a file with progress tracking
* @param fileOrBlob - File or Blob to decrypt
* @param privateKey - RSA private key for hybrid decryption
* @param onProgress - Callback function to report decryption progress
*/
decryptFileWithProgress(
fileOrBlob: Blob | File,
privateKey: CryptoKey,
onProgress?: (bytesProcessed: number) => void
): Promise<{ blob: Blob; filename: string }>;
/**
* Derive a key using PBKDF2 with configurable parameters
* @param password - The password to derive the key from
* @param salt - Salt for the derivation
* @param iterations - Number of PBKDF2 iterations (default: 600000)
* @param hash - Hash algorithm (default: SHA-256)
* @param keyLength - Length of the derived key in bits
*/
deriveKeyPBKDF2(
password: string,
salt: Uint8Array,
iterations?: number,
hash?: string,
keyLength?: number
): Promise<CryptoKey>;
/**
* Derive a key using Argon2id (where supported)
* @param password - The password to derive the key from
* @param salt - Salt for the derivation
* @param options - Argon2 configuration options
*/
deriveKeyArgon2(
password: string,
salt: Uint8Array,
options?: {
iterations?: number;
memoryCost?: number;
parallelism?: number;
}
): Promise<CryptoKey>;
/**
* Generate a key for symmetric encryption using password-based derivation
* @param password - Password to derive the key from
* @param salt - Salt for key derivation
* @param algorithm - Key derivation algorithm (PBKDF2 or Argon2)
*/
generateKeyFromPassword(
password: string,
salt: Uint8Array,
algorithm?: "PBKDF2" | "Argon2"
): Promise<CryptoKey>;
/**
* Generate a new key for symmetric encryption using password-based derivation with key rotation
* @param password - Password to derive the key from
* @param salt - Salt for key derivation
* @param algorithm - Key derivation algorithm (PBKDF2 or Argon2)
* @param rotationCount - Rotation counter for key derivation
*/
generateRotatingKey(
password: string,
salt: Uint8Array,
algorithm?: "PBKDF2" | "Argon2",
rotationCount?: number
): Promise<CryptoKey>;
/**
* Generate a hierarchical key structure
* @param masterPassword - Master password for the hierarchy
* @param path - Path components to derive child keys from
*/
generateHierarchicalKey(
masterPassword: string,
path: string[]
): Promise<{
masterKey: CryptoKey;
childKeys: { [key: string]: CryptoKey };
}>;
/**
* Generate a key from multiple inputs (e.g., password + salt + nonce)
* @param inputs - Array of input strings to combine
* @param salt - Salt for key derivation
* @param algorithm - Key derivation algorithm (PBKDF2 or Argon2)
*/
generateKeyFromMultipleInputs(
inputs: string[],
salt: Uint8Array,
algorithm?: "PBKDF2" | "Argon2"
): Promise<CryptoKey>;
/**
* Sign a text message or data string with configurable algorithms
* @param text - Text to sign
* @param privateKey - Private key for signing (ECDSA)
* @param algorithm - Signature algorithm to use (ECDSA, EdDSA, RSA-PSS)
*/
signTextWithAlgorithm(
text: string,
privateKey: CryptoKey,
algorithm?: "ECDSA" | "EdDSA" | "RSA-PSS"
): Promise<string>;
/**
* Verify a signed text message with configurable algorithms
* @param text - Text that was signed
* @param signatureB64 - Base64-encoded signature
* @param publicKey - Public key for verification (ECDSA)
* @param algorithm - Signature algorithm to use (ECDSA, EdDSA, RSA-PSS)
*/
verifyTextWithAlgorithm(
text: string,
signatureB64: string,
publicKey: CryptoKey,
algorithm?: "ECDSA" | "EdDSA" | "RSA-PSS"
): Promise<boolean>;
/**
* Create an HMAC signature using configurable hash algorithms
* @param data - Data to sign
* @param key - HMAC key
* @param hash - Hash algorithm (SHA-256, SHA-384, or SHA-512)
*/
signHMAC(data: string, key: CryptoKey, hash?: "SHA-256" | "SHA-384" | "SHA-512"): Promise<string>;
/**
* Verify an HMAC signature using configurable hash algorithms
* @param data - Data that was signed
* @param signatureB64 - Base64-encoded HMAC signature
* @param key - HMAC key
* @param hash - Hash algorithm (SHA-256, SHA-384, or SHA-512)
*/
verifyHMAC(
data: string,
signatureB64: string,
key: CryptoKey,
hash?: "SHA-256" | "SHA-384" | "SHA-512"
): Promise<boolean>;
/**
* @deprecated Poly1305 is not supported by standard Web Crypto API. Use signHMAC() instead.
* @param data - Data to authenticate
* @param key - Poly1305 key (should be 32 bytes)
*/
authenticatePoly1305(data: ArrayBuffer, key: CryptoKey): Promise<string>;
/**
* Secure random number generation with better entropy sources
* @param length - Number of bytes to generate
*/
secureRandom(length: number): Promise<Uint8Array>;
/**
* Clear the internal key cache
*/
clearKeyCache(): void;
/**
* Stop automatic cache cleanup interval
*/
stopAutoCleanup(): void;
// ═══════════════════════════ Post-Quantum Key Derivation ═══════════════════════════
/**
* Enhanced Argon2id KDF (quantum-resistant, GPU/ASIC resistant).
* Stronger than PBKDF2 for high-entropy passwords.
*
* @param password - Password to derive from
* @param salt - Random salt (16+ bytes recommended)
* @param options - Configuration object
* @param options.memory - Memory cost in KiB (default: 65536 = 64MB)
* @param options.iterations - Time cost (default: 3)
* @param options.parallelism - Parallelism factor (default: 1)
* @param options.keyLength - Output key length in bits (default: 256)
* @returns Derived AES key
*/
deriveKeyArgon2Enhanced(
password: string,
salt: Uint8Array,
options?: {
memory?: number;
iterations?: number;
parallelism?: number;
keyLength?: number;
}
): Promise<CryptoKey>;
/**
* SHA-3 based KDF (post-quantum collision-resistant).
* Alternative to PBKDF2/Argon2 using quantum-resistant SHA-3 hash.
*
* @param password - Password to derive from
* @param salt - Random salt
* @param iterations - KDF iterations (default: 50000)
* @param hash - Hash algorithm: 'SHA3-256' | 'SHA3-384' | 'SHA3-512'
* @param keyLength - Output key length in bits (default: 256)
* @returns Derived AES key
*/
deriveKeySHA3(
password: string,
iterations?: number,
algorithm?: "SHA3-256" | "SHA3-384" | "SHA3-512"
): Promise<CryptoKey>;
/**
* HKDF with SHA-3 (quantum-resistant key expansion).
* Suitable for deriving multiple independent keys from a master secret.
*
* @param secret - Input key material (IKM)
* @param salt - Optional salt (default: all zeros)
* @param info - Optional context/application-specific info
* @param keyLength - Output key length in bits (default: 256)
* @returns Derived AES key
*/
deriveKeyHKDFSHA3(
secret: Uint8Array,
salt?: Uint8Array,
info?: Uint8Array,
keyLength?: number
): Promise<CryptoKey>;
/**
* HKDF with SHA-256 (fallback variant).
*/
deriveKeyHKDFSHA2(
secret: Uint8Array,
salt?: Uint8Array,
info?: Uint8Array,
keyLength?: number
): Promise<CryptoKey>;
/**
* Key rotation: Derive new key with fresh salt.
* Enables periodic key rotation without data re-encryption (in some schemes).
*
* @param password - Original password
* @param newSalt - New salt for re-derivation
* @param method - KDF method: 'PBKDF2' | 'Argon2' | 'SHA3' | 'HKDF'
* @returns New derived key
*/
rotateKeyNew(
password: string,
newSalt: Uint8Array,
method?: "PBKDF2" | "Argon2" | "SHA3" | "HKDF"
): Promise<CryptoKey>;
/**
* Hierarchical key derivation: Create distinct keys for different purposes.
* Enables key structures where child keys are derived from a parent key.
*
* @param parentKey - Parent AES key
* @param childSalt - Context/application-specific salt
* @param purpose - Purpose string (e.g., 'encryption', 'signing', 'hmac')
* @returns Child derived key
*/
deriveChildKeyHierarchical(
parentKey: CryptoKey,
childSalt: Uint8Array,
purpose?: string
): Promise<CryptoKey>;
/**
* Secure key erasure: Overwrite sensitive key material in memory.
* Best-effort; true secure erasure depends on runtime guarantees.
*
* @param key - Key material to erase
*/
secureKeyErase(key: Uint8Array): void;
// ────────────────────── ECDH Key Exchange ──────────────────────
/**
* Generate an ECDH key pair for key exchange.
* @param curve - Elliptic curve to use (default: 'P-256')
*/
generateECDHKeyPair(curve?: string): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Export an ECDH public key to base64 for sharing.
*/
exportECDHPublicKey(publicKey: CryptoKey): Promise<string>;
/**
* Import an ECDH public key from base64.
* @param b64 - Base64 string of the public key
* @param curve - Curve used (default: 'P-256')
*/
importECDHPublicKey(b64: string, curve?: string): Promise<CryptoKey>;
/**
* Derive a shared secret using ECDH.
* @param privateKey - Your private key
* @param publicKey - The other party's public key
*/
deriveECDHSharedSecret(privateKey: CryptoKey, publicKey: CryptoKey): Promise<CryptoKey>;
/**
* Encrypt data automatically deriving an ECDH shared secret.
* @param data - Serializable data or string to encrypt
* @param privateKey - Sender's private key
* @param recipientPublicKey - Recipient's public key
*/
encryptWithECDH(data: any, privateKey: CryptoKey, recipientPublicKey: CryptoKey): Promise<string>;
/**
* Decrypt data automatically deriving an ECDH shared secret.
* @param b64 - Base64-encoded encrypted payload
* @param privateKey - Recipient's private key
* @param senderPublicKey - Sender's public key
*/
decryptWithECDH(b64: string, privateKey: CryptoKey, senderPublicKey: CryptoKey): Promise<any>;
/**
* Automatically serializes any JavaScript object or array to JSON before encrypting.
*/
encryptData(data: any, publicKey: CryptoKey): Promise<string>;
/**
* Decrypts the data and automatically parses it back into a JavaScript object.
*/
decryptData(b64: string, privateKey: CryptoKey): Promise<any>;
/**
* Import a public signing key from base64 (SPKI format)
* @param publicKeyB64 - Base64 encoded SPKI public key
* @param curve - Elliptic curve ('P-256' default, 'P-384')
*/
importPublicSigningKey(publicKeyB64: string, curve?: string): Promise<CryptoKey>;
/**
* Sign a text message or data string with ECDSA
* @param text - Text to sign
* @param privateKey - ECDSA private key
* @returns Base64-encoded detached signature
*/
signText(text: string, privateKey: CryptoKey): Promise<string>;
/**
* Verify a signed text message with ECDSA
* @param text - Text that was signed
* @param signatureB64 - Base64 signature
* @param publicKey - ECDSA public key
*/
verifyText(text: string, signatureB64: string, publicKey: CryptoKey): Promise<boolean>;
/**
* Create a detached signature for a file or blob
* @param fileOrBlob - File or Blob object to sign
* @param privateKey - ECDSA private key
*/
signFile(fileOrBlob: any, privateKey: CryptoKey): Promise<{ signatureB64: string; blob: any }>;
/**
* Verify a detached signature for a file or blob
* @param fileOrBlob - File or Blob object that was signed
* @param signatureB64 - Base64 signature
* @param publicKey - ECDSA public key
*/
verifyFile(fileOrBlob: any, signatureB64: string, publicKey: CryptoKey): Promise<boolean>;
// ────────────────────── JSON Web Encryption (JWE) ──────────────────────
/**
* Encrypts payload into a JWE Compact Serialization string.
* Uses RSA-OAEP-256 for key management and A256GCM for content encryption.
*
* @param payload - Data to encrypt (string or serializable object)
* @param publicKey - Recipient's RSA public key
* @param customHeaders - Additional JWE protected headers
* @returns JWE Token string
*/
encryptJWE(payload: any, publicKey: CryptoKey, customHeaders?: object): Promise<string>;
/**
* Decrypts a JWE Compact Serialization string.
*
* @param jweToken - JWE Token string
* @param privateKey - Recipient's RSA private key
* @returns Decrypted payload (parsed object if applicable, else string)
*/
decryptJWE(jweToken: string, privateKey: CryptoKey): Promise<any>;
}
export { WebCryptAsym };
export default WebCryptAsym;
src/WebCryptAsym.js

Sorry, the diff of this file is too big to display

+214
src/WebCryptPQC.d.ts
// src/WebCryptPQC.d.ts
// Post-Quantum Cryptography type definitions
/**
* WebCryptPQC – Post-quantum key exchange and digital signatures
*
* Implements NIST PQC finalists:
* - Kyber: Lattice-based Key Encapsulation Mechanism (KEM)
* - Dilithium: Lattice-based Digital Signature Algorithm
*/
declare class WebCryptPQC {
/**
* Kyber security levels
*/
static readonly KYBER_512: "Kyber512";
static readonly KYBER_768: "Kyber768";
static readonly KYBER_1024: "Kyber1024";
/**
* Kyber parameters including key and ciphertext sizes
*/
static readonly KYBER_PARAMS: {
[key: string]: {
name: string;
securityLevel: string;
publicKeySize: number;
privateKeySize: number;
ciphertextSize: number;
sharedSecretSize: number;
};
};
/**
* Dilithium security levels
*/
static readonly DILITHIUM_2: "Dilithium2";
static readonly DILITHIUM_3: "Dilithium3";
static readonly DILITHIUM_5: "Dilithium5";
/**
* Dilithium parameters including key and signature sizes
*/
static readonly DILITHIUM_PARAMS: {
[key: string]: {
name: string;
securityLevel: string;
publicKeySize: number;
privateKeySize: number;
signatureSize: number;
};
};
/**
* SHA-3 hash algorithms
*/
static readonly HASH_SHA3_256: "SHA3-256";
static readonly HASH_SHA3_384: "SHA3-384";
static readonly HASH_SHA3_512: "SHA3-512";
/**
* Supported Kyber levels
*/
static readonly SUPPORTED_KYBER_LEVELS: string[];
/**
* Supported Dilithium levels
*/
static readonly SUPPORTED_DILITHIUM_LEVELS: string[];
/**
* Returns true if PQC module is running as a placeholder/stub.
*/
static isStub(): boolean;
/**
* Enable or disable stub testing mode for unit tests.
* @param allow Enable stub testing mode if true
*/
static enableStubTesting(allow?: boolean): void;
constructor();
// ─────────────────────── Kyber KEM ───────────────────────
/**
* Generate a Kyber key pair for key encapsulation.
* @param level - Kyber level: "Kyber512" | "Kyber768" | "Kyber1024" (default: Kyber768)
*/
generateKyberKeyPair(level?: string): Promise<{
publicKey: Uint8Array;
privateKey: Uint8Array;
}>;
/**
* Encapsulate: Create a shared secret and ciphertext using recipient's Kyber public key.
* @param kyberPublicKey - Recipient's Kyber public key
* @param level - Kyber level (default: Kyber768)
* @returns Ciphertext and derived shared secret
*/
kyberEncapsulate(
kyberPublicKey: Uint8Array,
level?: string
): Promise<{
ciphertext: Uint8Array;
sharedSecret: Uint8Array;
}>;
/**
* Decapsulate: Recover the shared secret using private key and ciphertext.
* @param ciphertext - Encapsulated ciphertext from kyberEncapsulate
* @param kyberPrivateKey - Own Kyber private key
* @param level - Kyber level (default: Kyber768)
* @returns The shared secret
*/
kyberDecapsulate(
ciphertext: Uint8Array,
kyberPrivateKey: Uint8Array,
level?: string
): Promise<Uint8Array>;
// ─────────────────────── Dilithium Signatures ───────────────────────
/**
* Generate a Dilithium key pair for digital signatures.
* @param level - Dilithium level: "Dilithium2" | "Dilithium3" | "Dilithium5" (default: Dilithium3)
*/
generateDilithiumKeyPair(level?: string): Promise<{
publicKey: Uint8Array;
privateKey: Uint8Array;
}>;
/**
* Sign a message using Dilithium private key.
* @param message - Message to sign (string or Uint8Array)
* @param dilithiumPrivateKey - Dilithium private key
* @param level - Dilithium level (default: Dilithium3)
* @returns Digital signature
*/
dilithiumSign(
message: string | Uint8Array,
dilithiumPrivateKey: Uint8Array,
level?: string
): Promise<Uint8Array>;
/**
* Verify a Dilithium signature.
* @param message - Original message (string or Uint8Array)
* @param signature - Signature from dilithiumSign
* @param dilithiumPublicKey - Dilithium public key
* @param level - Dilithium level (default: Dilithium3)
* @returns True if valid
*/
dilithiumVerify(
message: string | Uint8Array,
signature: Uint8Array,
dilithiumPublicKey: Uint8Array,
level?: string
): Promise<boolean>;
// ─────────────────────── Hybrid Encryption ───────────────────────
/**
* Hybrid encapsulation: Use both Kyber (PQC) and RSA-OAEP.
* Combines classical and post-quantum key encapsulation for maximum security.
*
* @param rsaPublicKey - RSA-4096 public key (classical)
* @param kyberPublicKey - Kyber public key (post-quantum)
* @param kyberLevel - Kyber level (default: Kyber768)
* @returns Shared secret and ciphertexts for both KEM schemes
*/
hybridEncapsulate(
rsaPublicKey: CryptoKey,
kyberPublicKey: Uint8Array,
kyberLevel?: string
): Promise<{
sharedSecret: Uint8Array;
kyberCiphertext: Uint8Array;
rsaWrappedSharedSecret: Uint8Array;
}>;
/**
* Hybrid decapsulation: Recover shared secret using both Kyber and RSA private keys.
* Falls back to Kyber alone if RSA decryption fails (provides forward secrecy).
*
* @param kyberCiphertext - From hybridEncapsulate
* @param rsaWrappedSharedSecret - From hybridEncapsulate
* @param rsaPrivateKey - RSA-4096 private key
* @param kyberPrivateKey - Kyber private key
* @param kyberLevel - Kyber level (default: Kyber768)
* @returns The hybrid shared secret
*/
hybridDecapsulate(
kyberCiphertext: Uint8Array,
rsaWrappedSharedSecret: Uint8Array,
rsaPrivateKey: CryptoKey,
kyberPrivateKey: Uint8Array,
kyberLevel?: string
): Promise<Uint8Array>;
// ─────────────────────── Key Serialization ───────────────────────
kyberPublicKeyToBase64(publicKey: Uint8Array): string;
kyberPublicKeyFromBase64(b64: string): Uint8Array;
kyberPrivateKeyToBase64(privateKey: Uint8Array): string;
kyberPrivateKeyFromBase64(b64: string): Uint8Array;
dilithiumPublicKeyToBase64(publicKey: Uint8Array): string;
dilithiumPublicKeyFromBase64(b64: string): Uint8Array;
dilithiumPrivateKeyToBase64(privateKey: Uint8Array): string;
dilithiumPrivateKeyFromBase64(b64: string): Uint8Array;
}
export { WebCryptPQC };
export default WebCryptPQC;
+638
src/WebCryptPQC.js
// src/WebCryptPQC.js
// Post-Quantum Cryptography (PQC) module
// version: 1.0.0 - Quantum-resist core
import { arrayBufferToBase64, base64ToArrayBuffer } from "./_base64.js";
import { getCrypto } from "./_crypto.js";
let warnedPQCStub = false;
/**
* WebCryptPQC – Post-quantum key exchange and digital signatures
* Maintained by PuterVision (https://putervision.com).
*
* DISCLAIMER: Provided "AS IS" without warranty of any kind. PuterVision
* disclaims all liability for data loss, security breaches, or misuse.
*
* Implements NIST PQC finalists:
* - Kyber: Lattice-based Key Encapsulation Mechanism (KEM)
* - Dilithium: Lattice-based Digital Signature Algorithm
*
* Note: This is a polyfill-style module. In production, you would integrate
* the official liboqs-js or equivalent. For now, we provide a secure interface
* and mark stubs for future integration.
*/
/**
* ⚠️ WARNING: WebCryptPQC is currently a PLACEHOLDER implementation
*
* Kyber and Dilithium algorithms are NOT real post-quantum cryptography.
* They use simplified SHA-3 hashing as stubs until liboqs-js integration.
*
* DO NOT USE FOR PRODUCTION SECURITY!
*
* For production, integrate official liboqs-js:
* npm install @openquantumsafe/libs
*/
export class WebCryptPQC {
static WARNING =
"⚠️ CRITICAL: WebCryptPQC is PLACEHOLDER/STUB implementation. " +
"Kyber and Dilithium are NOT real PQC - they use SHA-3 hashing stubs. " +
"Not suitable for production security. Integrate liboqs-js or wait for official implementation.";
static _STUB_BLOCKED = true;
/**
* Programmatically check if PQC operations are currently blocked by default.
* @returns {boolean} True if PQC stub operations are blocked.
*/
static isStub() {
return WebCryptPQC._STUB_BLOCKED;
}
/**
* Enable or disable stub testing mode.
* @param {boolean} [allow=true] If true, allows stub operations for testing purposes.
*/
static enableStubTesting(allow = true) {
WebCryptPQC._STUB_BLOCKED = !allow;
}
/**
* Internal helper to verify stub mode state before PQC operations.
*/
_checkStubMode() {
if (WebCryptPQC._STUB_BLOCKED) {
throw new Error(
"WebCryptPQC is a placeholder stub — not for production use. Call WebCryptPQC.enableStubTesting(true) for testing."
);
}
}
// ─────────────────────── Kyber Constants ───────────────────────
static KYBER_512 = "Kyber512";
static KYBER_768 = "Kyber768";
static KYBER_1024 = "Kyber1024";
// Kyber security levels and sizes (bytes)
static KYBER_PARAMS = {
[WebCryptPQC.KYBER_512]: {
name: "Kyber512",
securityLevel: "128-bit",
publicKeySize: 800,
privateKeySize: 1632,
ciphertextSize: 768,
sharedSecretSize: 32,
},
[WebCryptPQC.KYBER_768]: {
name: "Kyber768",
securityLevel: "192-bit",
publicKeySize: 1184,
privateKeySize: 2400,
ciphertextSize: 1088,
sharedSecretSize: 32,
},
[WebCryptPQC.KYBER_1024]: {
name: "Kyber1024",
securityLevel: "256-bit",
publicKeySize: 1568,
privateKeySize: 3168,
ciphertextSize: 1568,
sharedSecretSize: 32,
},
};
// ─────────────────────── Dilithium Constants ───────────────────────
static DILITHIUM_2 = "Dilithium2";
static DILITHIUM_3 = "Dilithium3";
static DILITHIUM_5 = "Dilithium5";
static DILITHIUM_PARAMS = {
[WebCryptPQC.DILITHIUM_2]: {
name: "Dilithium2",
securityLevel: "128-bit",
publicKeySize: 1312,
privateKeySize: 2544,
signatureSize: 2420,
},
[WebCryptPQC.DILITHIUM_3]: {
name: "Dilithium3",
securityLevel: "192-bit",
publicKeySize: 1952,
privateKeySize: 4000,
signatureSize: 3293,
},
[WebCryptPQC.DILITHIUM_5]: {
name: "Dilithium5",
securityLevel: "256-bit",
publicKeySize: 2592,
privateKeySize: 4864,
signatureSize: 4595,
},
};
// ─────────────────────── Algorithm Constants ───────────────────────
static HASH_SHA3_256 = "SHA3-256";
static HASH_SHA3_384 = "SHA3-384";
static HASH_SHA3_512 = "SHA3-512";
static SUPPORTED_KYBER_LEVELS = [
WebCryptPQC.KYBER_512,
WebCryptPQC.KYBER_768,
WebCryptPQC.KYBER_1024,
];
static SUPPORTED_DILITHIUM_LEVELS = [
WebCryptPQC.DILITHIUM_2,
WebCryptPQC.DILITHIUM_3,
WebCryptPQC.DILITHIUM_5,
];
constructor() {
this._crypto = this._getCrypto();
// Warn users immediately about placeholder status (once per process)
if (!warnedPQCStub && typeof console !== "undefined" && console.warn) {
console.warn(WebCryptPQC.WARNING);
warnedPQCStub = true;
}
}
_getCrypto() {
return getCrypto();
}
// ═══════════════════════════ Kyber KEM (Key Encapsulation) ═══════════════════════════
/**
* Generate a Kyber key pair for key encapsulation.
* @param {string} level - Kyber level: "Kyber512" | "Kyber768" | "Kyber1024"
* @returns {Promise<{publicKey: Uint8Array, privateKey: Uint8Array}>}
*/
async generateKyberKeyPair(level = WebCryptPQC.KYBER_768) {
this._checkStubMode();
if (!WebCryptPQC.SUPPORTED_KYBER_LEVELS.includes(level)) {
throw new Error(`Unsupported Kyber level: ${level}. Use Kyber512, Kyber768, or Kyber1024`);
}
// STUB: In production, call libOQS or liboqs-js Kyber1024_keypair()
// For now, generate deterministic synthetic keys using SHA-3
const seed = this._crypto.getRandomValues(new Uint8Array(64));
const { publicKey, privateKey } = await this._generateKyberKeysFromSeed(seed, level);
return { publicKey, privateKey };
}
/**
* Encapsulate: Create a shared secret and ciphertext using recipient's Kyber public key.
* @param {Uint8Array} kyberPublicKey - Recipient's Kyber public key
* @param {string} level - Kyber level
* @returns {Promise<{ciphertext: Uint8Array, sharedSecret: Uint8Array}>}
*/
async kyberEncapsulate(kyberPublicKey, level = WebCryptPQC.KYBER_768) {
this._checkStubMode();
if (!WebCryptPQC.SUPPORTED_KYBER_LEVELS.includes(level)) {
throw new Error(`Unsupported Kyber level: ${level}`);
}
const params = WebCryptPQC.KYBER_PARAMS[level];
if (kyberPublicKey.byteLength !== params.publicKeySize) {
throw new Error(
`Invalid Kyber public key size: expected ${params.publicKeySize}, got ${kyberPublicKey.byteLength}`
);
}
// STUB: Call libOQS Kyber1024_encaps(pk) → (ss, ct)
// Generate random 32-byte nonce
const nonce = this._crypto.getRandomValues(new Uint8Array(32));
const hashInput = new Uint8Array(kyberPublicKey.byteLength + 32);
hashInput.set(kyberPublicKey);
hashInput.set(nonce, kyberPublicKey.byteLength);
const digest = await this._sha3Hash(hashInput, 256);
const sharedSecret = digest.slice(0, params.sharedSecretSize);
const ciphertext = new Uint8Array(params.ciphertextSize);
ciphertext.set(nonce, 0);
const ctHash = await this._sha3Hash(hashInput, 512);
ciphertext.set(ctHash.slice(0, Math.min(params.ciphertextSize - 32, ctHash.byteLength)), 32);
return { ciphertext, sharedSecret };
}
/**
* Decapsulate: Recover the shared secret using private key and ciphertext.
* @param {Uint8Array} ciphertext - Encapsulated ciphertext from kyberEncapsulate
* @param {Uint8Array} kyberPrivateKey - Own Kyber private key
* @param {string} level - Kyber level
* @returns {Promise<Uint8Array>} The shared secret
*/
async kyberDecapsulate(ciphertext, kyberPrivateKey, level = WebCryptPQC.KYBER_768) {
this._checkStubMode();
if (!WebCryptPQC.SUPPORTED_KYBER_LEVELS.includes(level)) {
throw new Error(`Unsupported Kyber level: ${level}`);
}
const params = WebCryptPQC.KYBER_PARAMS[level];
if (kyberPrivateKey.byteLength !== params.privateKeySize) {
throw new Error(
`Invalid Kyber private key size: expected ${params.privateKeySize}, got ${kyberPrivateKey.byteLength}`
);
}
if (ciphertext.byteLength !== params.ciphertextSize) {
throw new Error(
`Invalid ciphertext size: expected ${params.ciphertextSize}, got ${ciphertext.byteLength}`
);
}
// STUB: Call libOQS Kyber1024_decaps(sk, ct) → ss
// Extract public key embedded in private key, and nonce from ciphertext
const pubKeyOffset = params.privateKeySize - params.publicKeySize;
const pubKey = kyberPrivateKey.slice(pubKeyOffset);
const nonce = ciphertext.slice(0, 32);
const hashInput = new Uint8Array(pubKey.byteLength + 32);
hashInput.set(pubKey);
hashInput.set(nonce, pubKey.byteLength);
const digest = await this._sha3Hash(hashInput, 256);
return digest.slice(0, params.sharedSecretSize);
}
// ═══════════════════════════ Dilithium Signatures ═══════════════════════════
/**
* Generate a Dilithium key pair for digital signatures.
* @param {string} level - Dilithium level: "Dilithium2" | "Dilithium3" | "Dilithium5"
* @returns {Promise<{publicKey: Uint8Array, privateKey: Uint8Array}>}
*/
async generateDilithiumKeyPair(level = WebCryptPQC.DILITHIUM_3) {
this._checkStubMode();
if (!WebCryptPQC.SUPPORTED_DILITHIUM_LEVELS.includes(level)) {
throw new Error(`Unsupported Dilithium level: ${level}`);
}
// STUB: Call libOQS Dilithium3_keypair()
const seed = this._crypto.getRandomValues(new Uint8Array(64));
const { publicKey, privateKey } = await this._generateDilithiumKeysFromSeed(seed, level);
return { publicKey, privateKey };
}
/**
* Sign a message using Dilithium private key.
* @param {Uint8Array|string} message - Message to sign
* @param {Uint8Array} dilithiumPrivateKey - Dilithium private key
* @param {string} level - Dilithium level
* @returns {Promise<Uint8Array>} Digital signature
*/
async dilithiumSign(message, dilithiumPrivateKey, level = WebCryptPQC.DILITHIUM_3) {
this._checkStubMode();
if (!WebCryptPQC.SUPPORTED_DILITHIUM_LEVELS.includes(level)) {
throw new Error(`Unsupported Dilithium level: ${level}`);
}
const params = WebCryptPQC.DILITHIUM_PARAMS[level];
if (dilithiumPrivateKey.byteLength !== params.privateKeySize) {
throw new Error(
`Invalid Dilithium private key size: expected ${params.privateKeySize}, got ${dilithiumPrivateKey.byteLength}`
);
}
const msgBytes = typeof message === "string" ? new TextEncoder().encode(message) : message;
const pubKey = dilithiumPrivateKey.subarray(params.privateKeySize - params.publicKeySize);
// STUB: Sign using SHA-3 HMAC of message with private key material & public key commitment
const hashInput = new Uint8Array(dilithiumPrivateKey.byteLength + msgBytes.byteLength);
hashInput.set(dilithiumPrivateKey);
hashInput.set(msgBytes, dilithiumPrivateKey.byteLength);
const digest = await this._sha3Hash(hashInput, 512);
// Compute public key + message verification tag for stub verification
const verifyInput = new Uint8Array(pubKey.byteLength + msgBytes.byteLength);
verifyInput.set(pubKey);
verifyInput.set(msgBytes, pubKey.byteLength);
const verifyTag = await this._sha3Hash(verifyInput, 512);
const signature = new Uint8Array(params.signatureSize);
signature.set(digest.slice(0, Math.min(64, digest.byteLength)));
signature.set(verifyTag.slice(0, Math.min(64, verifyTag.byteLength)), 64);
return signature;
}
/**
* Dilithium signature verification stub
* Validates format and checks stub signature tag against message and public key.
*
* @param {Uint8Array|string} message - Original message
* @param {Uint8Array} signature - Signature from dilithiumSign
* @param {Uint8Array} dilithiumPublicKey - Dilithium public key
* @param {string} level - Dilithium level
* @returns {Promise<boolean>} True if signature matches public key and message under stub mode
*/
async dilithiumVerify(message, signature, dilithiumPublicKey, level = WebCryptPQC.DILITHIUM_3) {
this._checkStubMode();
if (!WebCryptPQC.SUPPORTED_DILITHIUM_LEVELS.includes(level)) {
throw new Error(`Unsupported Dilithium level: ${level}`);
}
const params = WebCryptPQC.DILITHIUM_PARAMS[level];
if (dilithiumPublicKey.byteLength !== params.publicKeySize) {
throw new Error(
`Invalid Dilithium public key size: expected ${params.publicKeySize}, got ${dilithiumPublicKey.byteLength}`
);
}
if (signature.byteLength !== params.signatureSize) {
return false;
}
const msgBytes = typeof message === "string" ? new TextEncoder().encode(message) : message;
const verifyInput = new Uint8Array(dilithiumPublicKey.byteLength + msgBytes.byteLength);
verifyInput.set(dilithiumPublicKey);
verifyInput.set(msgBytes, dilithiumPublicKey.byteLength);
const expectedTag = await this._sha3Hash(verifyInput, 512);
const sigTag = signature.subarray(64, 128);
const expectedTagSlice = expectedTag.subarray(0, 64);
if (sigTag.byteLength < 64 || expectedTagSlice.byteLength < 64) {
return false;
}
for (let i = 0; i < 64; i++) {
if (sigTag[i] !== expectedTagSlice[i]) {
return false;
}
}
return true;
}
// ═══════════════════════════ Hybrid Encryption (Kyber + RSA) ═══════════════════════════
/**
* Hybrid encapsulation: Use both Kyber (PQC) and RSA-OAEP for forward secrecy.
* Combines a classical and post-quantum key encapsulation.
*
* @param {CryptoKey} rsaPublicKey - RSA-4096 public key (classical)
* @param {Uint8Array} kyberPublicKey - Kyber public key (PQC)
* @param {string} kyberLevel - Kyber level (default: Kyber768)
* @returns {Promise<{sharedSecret: Uint8Array, hybridSecret: Uint8Array, kyberCiphertext: Uint8Array, rsaWrappedSharedSecret: Uint8Array, combinedCiphertext: Object}>}
*/
async hybridEncapsulate(rsaPublicKey, kyberPublicKey, kyberLevel = WebCryptPQC.KYBER_768) {
// Step 1: Kyber encapsulation
const { ciphertext: kyberCiphertext, sharedSecret: kyberSharedSecret } =
await this.kyberEncapsulate(kyberPublicKey, kyberLevel);
// Step 2: Generate random ephemeral secret to wrap with RSA-OAEP
const rsaSecret = this._crypto.getRandomValues(new Uint8Array(32));
const rsaWrappedSharedSecret = await this._crypto.subtle.encrypt(
{ name: "RSA-OAEP", hash: "SHA-256" },
rsaPublicKey,
rsaSecret
);
// Step 3: Combine via KDF (SHA-3)
const combinedInput = new Uint8Array(kyberSharedSecret.byteLength + rsaSecret.byteLength);
combinedInput.set(kyberSharedSecret);
combinedInput.set(rsaSecret, kyberSharedSecret.byteLength);
const finalSharedSecret = await this._sha3Hash(combinedInput, 256);
const kyberCiphertextBytes = new Uint8Array(kyberCiphertext);
const rsaWrappedBytes = new Uint8Array(rsaWrappedSharedSecret);
return {
sharedSecret: finalSharedSecret,
hybridSecret: finalSharedSecret,
kyberCiphertext: kyberCiphertextBytes,
rsaWrappedSharedSecret: rsaWrappedBytes,
combinedCiphertext: {
kyberCiphertext: kyberCiphertextBytes,
rsaWrappedSharedSecret: rsaWrappedBytes,
},
};
}
/**
* Hybrid decapsulation: Recover shared secret using both Kyber and RSA private keys.
* Supports both 5-argument positional style or 4-argument combined-object style.
*
* @param {Uint8Array|Object} kyberCiphertextOrCombined - From hybridEncapsulate
* @param {Uint8Array|CryptoKey} rsaWrappedSharedSecretOrRsaPrivKey - From hybridEncapsulate or RSA private key
* @param {CryptoKey|Uint8Array} rsaPrivateKeyOrKyberPrivKey - RSA private key or Kyber private key
* @param {Uint8Array|string} [kyberPrivateKeyOrLevel] - Kyber private key or Kyber level
* @param {string} [maybeKyberLevel='Kyber768'] - Kyber level (default: Kyber768)
* @returns {Promise<Uint8Array>} The hybrid shared secret
*/
async hybridDecapsulate(
kyberCiphertextOrCombined,
rsaWrappedSharedSecretOrRsaPrivKey,
rsaPrivateKeyOrKyberPrivKey,
kyberPrivateKeyOrLevel,
maybeKyberLevel = WebCryptPQC.KYBER_768
) {
try {
let kyberCiphertext;
let rsaWrappedSharedSecret;
let rsaPrivateKey;
let kyberPrivateKey;
let kyberLevel = WebCryptPQC.KYBER_768;
if (
typeof kyberCiphertextOrCombined === "object" &&
!(kyberCiphertextOrCombined instanceof Uint8Array)
) {
kyberCiphertext = kyberCiphertextOrCombined.kyberCiphertext;
rsaWrappedSharedSecret = kyberCiphertextOrCombined.rsaWrappedSharedSecret;
rsaPrivateKey = rsaWrappedSharedSecretOrRsaPrivKey;
kyberPrivateKey = rsaPrivateKeyOrKyberPrivKey;
kyberLevel = kyberPrivateKeyOrLevel || WebCryptPQC.KYBER_768;
} else {
kyberCiphertext = kyberCiphertextOrCombined;
rsaWrappedSharedSecret = rsaWrappedSharedSecretOrRsaPrivKey;
rsaPrivateKey = rsaPrivateKeyOrKyberPrivKey;
kyberPrivateKey = kyberPrivateKeyOrLevel;
kyberLevel = maybeKyberLevel || WebCryptPQC.KYBER_768;
}
// Step 1: Kyber decapsulation
const kyberSharedSecret = await this.kyberDecapsulate(
kyberCiphertext,
kyberPrivateKey,
kyberLevel
);
// Step 2: Unwrap via RSA-OAEP
let rsaSecret;
try {
const decrypted = await this._crypto.subtle.decrypt(
{ name: "RSA-OAEP", hash: "SHA-256" },
rsaPrivateKey,
rsaWrappedSharedSecret
);
rsaSecret = new Uint8Array(decrypted);
} catch (e) {
// RSA decryption failed: use Kyber alone (forward secrecy maintained)
if (typeof console !== "undefined" && console.warn) {
console.warn(
"Hybrid decapsulation: RSA decryption failed, falling back to Kyber shared secret"
);
}
rsaSecret = kyberSharedSecret;
}
// Step 3: Combine sharedSecrets via KDF (SHA-3)
const combinedInput = new Uint8Array(kyberSharedSecret.byteLength + rsaSecret.byteLength);
combinedInput.set(kyberSharedSecret);
combinedInput.set(rsaSecret, kyberSharedSecret.byteLength);
return await this._sha3Hash(combinedInput, 256);
} catch (e) {
throw new Error(`Hybrid decapsulation failed: ${e.message}`);
}
}
static _warnedHashes = {};
/**
* Hash data using SHA-3 (post-quantum secure hash).
* Falls back to SHA-256/512 in environments without SHA-3 support.
*
* @param {Uint8Array} data - Data to hash
* @param {number} bitLength - Hash output size: 256, 384, 512
* @returns {Promise<Uint8Array>} Hash digest
*/
async _sha3Hash(data, bitLength = 256) {
const algorithm = `SHA3-${bitLength}`;
try {
// Try native SHA-3 support
const digest = await this._crypto.subtle.digest(algorithm, data);
return new Uint8Array(digest);
} catch (e) {
// Fallback: Use SHA-256/512 (still quantum-resistant for these sizes)
const fallbackAlgorithm =
bitLength <= 256 ? "SHA-256" : bitLength <= 384 ? "SHA-384" : "SHA-512";
if (!WebCryptPQC._warnedHashes[bitLength] && typeof console !== "undefined" && console.warn) {
console.warn(
`SHA3-${bitLength} not natively supported by Web Crypto, falling back to ${fallbackAlgorithm}`
);
WebCryptPQC._warnedHashes[bitLength] = true;
}
const digest = await this._crypto.subtle.digest(fallbackAlgorithm, data);
return new Uint8Array(digest).slice(0, bitLength / 8);
}
}
// ═══════════════════════════ Key Serialization ═══════════════════════════
/**
* Export Kyber public key to Base64 for transmission/storage.
*/
kyberPublicKeyToBase64(publicKey) {
return this._arrayBufferToBase64(publicKey);
}
/**
* Import Kyber public key from Base64.
*/
kyberPublicKeyFromBase64(b64) {
return new Uint8Array(this._base64ToArrayBuffer(b64));
}
/**
* Export Kyber private key to Base64 (SECURE: handle with care).
*/
kyberPrivateKeyToBase64(privateKey) {
return this._arrayBufferToBase64(privateKey);
}
/**
* Import Kyber private key from Base64.
*/
kyberPrivateKeyFromBase64(b64) {
return new Uint8Array(this._base64ToArrayBuffer(b64));
}
/**
* Same methods for Dilithium keys.
*/
dilithiumPublicKeyToBase64(publicKey) {
return this._arrayBufferToBase64(publicKey);
}
dilithiumPublicKeyFromBase64(b64) {
return new Uint8Array(this._base64ToArrayBuffer(b64));
}
dilithiumPrivateKeyToBase64(privateKey) {
return this._arrayBufferToBase64(privateKey);
}
dilithiumPrivateKeyFromBase64(b64) {
return new Uint8Array(this._base64ToArrayBuffer(b64));
}
// ═════════════════════════ Internal Helpers ═════════════════════════
async _generateKyberKeysFromSeed(seed, level) {
const params = WebCryptPQC.KYBER_PARAMS[level];
const publicKey = new Uint8Array(params.publicKeySize);
const privateKey = new Uint8Array(params.privateKeySize);
// Deterministic key generation from seed
const hashInput = new Uint8Array(seed.byteLength + 4);
hashInput.set(seed);
new DataView(hashInput.buffer).setUint32(seed.byteLength, 0, true);
const pubHash = await this._sha3Hash(hashInput, 512);
publicKey.set(pubHash.slice(0, Math.min(params.publicKeySize, pubHash.byteLength)));
new DataView(hashInput.buffer).setUint32(seed.byteLength, 1, true);
const privHash = await this._sha3Hash(hashInput, 512);
privateKey.set(
privHash.slice(0, Math.min(params.privateKeySize - params.publicKeySize, privHash.byteLength))
);
// Embed publicKey at end of privateKey for stub mode decapsulation compatibility (mirroring NIST ML-KEM sk structure)
privateKey.set(publicKey, params.privateKeySize - params.publicKeySize);
return { publicKey, privateKey };
}
async _generateDilithiumKeysFromSeed(seed, level) {
const params = WebCryptPQC.DILITHIUM_PARAMS[level];
const publicKey = new Uint8Array(params.publicKeySize);
const privateKey = new Uint8Array(params.privateKeySize);
const hashInput = new Uint8Array(seed.byteLength + 4);
hashInput.set(seed);
new DataView(hashInput.buffer).setUint32(seed.byteLength, 0, true);
const pubHash = await this._sha3Hash(hashInput, 512);
publicKey.set(pubHash.slice(0, Math.min(params.publicKeySize, pubHash.byteLength)));
new DataView(hashInput.buffer).setUint32(seed.byteLength, 1, true);
const privHash = await this._sha3Hash(hashInput, 512);
privateKey.set(
privHash.slice(0, Math.min(params.privateKeySize - params.publicKeySize, privHash.byteLength))
);
// Embed publicKey at end of privateKey for stub mode verification compatibility
privateKey.set(publicKey, params.privateKeySize - params.publicKeySize);
return { publicKey, privateKey };
}
// Safe Base64 helpers
_arrayBufferToBase64(buffer) {
return arrayBufferToBase64(buffer);
}
_base64ToArrayBuffer(base64) {
return base64ToArrayBuffer(base64);
}
}
export default WebCryptPQC;
+2
-1031
dist/index.d.cts

@@ -1,1032 +0,3 @@

// src/WebCrypt.d.ts
export { W as WebCrypt, a as WebCryptAsym, b as WebCryptPQC, c as arrayBufferToBase64, d as base64ToArrayBuffer, e as base64ToUint8Array, g as getCrypto, i as isValidBase64 } from './_crypto-B6690zvC.cjs';
/**
* WebCrypt – Zero-dependency quantum-resistant AES-256-GCM encryption
*
* Supports:
* - Text encryption/decryption
* - Large file encryption/decryption (streaming)
* - WebRTC Insertable Streams E2EE (video + audio)
* - HMAC for message authentication
*
* Works in Browser, Node.js 18+, Deno, Cloudflare Workers
*/
declare class WebCrypt {
static readonly ALGORITHM: "AES-GCM";
static readonly KEY_LENGTH: 256;
static readonly IV_LENGTH: 12;
static readonly SALT_LENGTH: 16;
static readonly PBKDF2_ITERATIONS: number;
static readonly HASH_ALGORITHM: "SHA-256";
static readonly CHUNK_SIZE: number;
static readonly WEBRTC_SALT: Uint8Array;
static readonly DEFAULT_HMAC_SALT: Uint8Array;
/**
* Generates a cryptographically secure random salt for HMAC key derivation.
* @param length Salt length in bytes (default: 16)
*/
static generateHmacSalt(length?: number): Uint8Array;
/**
* Encrypts a string and returns Base64-encoded ciphertext
* @param text Plain text to encrypt
* @param password Password (or shared secret)
* @returns Base64 string (salt + iv + ciphertext)
*/
encryptText(text: string, password: string): Promise<string>;
/**
* Decrypts a Base64 string produced by encryptText()
* @param base64 Encrypted data from encryptText()
* @param password Must match encryption password
* @returns Original plain text
* @throws If password is wrong or data is corrupted
*/
decryptText(base64: string, password: string): Promise<string>;
/**
* Encrypts a File or Blob using streaming (low memory, handles huge files)
* @param file File or Blob to encrypt
* @param password Encryption password
* @param options Optional configuration object ({ parallelChunks?: number })
* @returns Object with encrypted Blob and suggested filename
*/
encryptFile(
file: File | Blob,
password: string,
options?: { parallelChunks?: number }
): Promise<{
blob: Blob;
filename: string;
}>;
/**
* Decrypts a .encrypted file produced by encryptFile()
* @param file Encrypted File or Blob
* @param password Must match encryption password
* @param options Optional configuration object ({ parallelChunks?: number })
* @returns Object with decrypted Blob and original filename
* @throws If password is wrong or file is corrupted
*/
decryptFile(
file: File | Blob,
password: string,
options?: { parallelChunks?: number }
): Promise<{
blob: Blob;
filename: string;
}>;
/**
* Creates an encryption transform for WebRTC Insertable Streams
* Use with RTCRtpSender.transform
* @param password Shared secret both peers must know
*/
createEncryptTransform(
password: string
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Creates a decryption transform for WebRTC Insertable Streams
* Use with RTCRtpReceiver.transform
* @param password Must match sender's password
*/
createDecryptTransform(
password: string
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Generates or derives an HMAC key.
* @param password Optional password for PBKDF2 derivation (if provided, uses 600_000 iterations).
* @param hash Hash algorithm (default: 'SHA-256').
* @param salt Optional salt for deterministic derivation.
* @returns Usable HMAC key.
*/
generateHmacKey(
password?: string,
hash?: "SHA-256" | "SHA-384" | "SHA-512",
salt?: Uint8Array | string
): Promise<CryptoKey>;
/**
* Computes HMAC on data.
* @param data Text or ArrayBuffer to authenticate.
* @param key HMAC key from generateHmacKey.
* @returns Base64-encoded HMAC tag.
*/
computeHmac(data: string | ArrayBuffer, key: CryptoKey): Promise<string>;
/**
* Verifies HMAC on data.
* @param data Text or ArrayBuffer to verify.
* @param hmac Base64-encoded HMAC tag to check.
* @param key HMAC key.
* @returns True if valid.
*/
verifyHmac(data: string | ArrayBuffer, hmac: string, key: CryptoKey): Promise<boolean>;
/**
* Generate a quantum-resistant HMAC key using SHA-3 hash.
* @param password Optional password for derivation
* @param hash Hash algorithm: 'SHA3-256' | 'SHA3-384' | 'SHA3-512' (default: SHA3-256)
* @param salt Optional salt for deterministic derivation.
* @param iterations Iterations count for SHA-3 KDF derivation (default: 10,000)
* @returns Usable HMAC key with SHA-3
*/
generateHmacKeySHA3(
password?: string,
hash?: "SHA3-256" | "SHA3-384" | "SHA3-512",
salt?: Uint8Array | string,
iterations?: number
): Promise<CryptoKey>;
/**
* Compute HMAC using SHA-3 (quantum-resistant).
* @param data Data to authenticate
* @param key HMAC key from generateHmacKeySHA3
* @returns Base64-encoded HMAC tag
*/
computeHmacSHA3(data: string | ArrayBuffer, key: CryptoKey): Promise<string>;
/**
* Verify HMAC using SHA-3 (quantum-resistant).
* @param data Data to verify
* @param hmac Base64-encoded HMAC tag
* @param key HMAC key
* @returns True if valid
*/
verifyHmacSHA3(data: string | ArrayBuffer, hmac: string, key: CryptoKey): Promise<boolean>;
/**
* Automatically serializes any JavaScript object or array to JSON before encrypting.
*/
encryptData(data: any, password: string): Promise<string>;
/**
* Decrypts the data and automatically parses it back into a JavaScript object.
*/
decryptData(base64: string, password: string): Promise<any>;
/**
* Utility to generate a cryptographically secure random password or key string.
*/
generateRandomPassword(length?: number): string;
/**
* Clear entire key cache.
*/
clearKeyCache(): void;
/**
* Stop automatic cache cleanup interval.
*/
stopAutoCleanup(): void;
}
// WebCryptAsym.d.ts
/**
* Asymmetric encryption utility using RSA-OAEP + AES-GCM hybrid encryption.
* Supports text, file (streaming), and WebRTC insertable streams.
*/
declare class WebCryptAsym {
/**
* RSA-OAEP algorithm parameters
*/
static readonly RSA_ALGORITHM: AlgorithmIdentifier;
/**
* Parameters for RSA key generation (4096-bit, SHA-256)
*/
static readonly RSA_KEY_PARAMS: RsaHashedKeyGenParams;
/**
* AES-GCM algorithm name
*/
static readonly AES_ALGORITHM: "AES-GCM";
/**
* AES key length (256 bits)
*/
static readonly AES_LENGTH: 256;
/**
* IV length for AES-GCM (12 bytes recommended)
*/
static readonly IV_LENGTH: 12;
/**
* Chunk size for file streaming (8 MB)
*/
static readonly CHUNK_SIZE: number;
/**
* Fixed salt-like identifier for WebRTC transforms
*/
static readonly WEBRTC_SALT: Uint8Array;
/**
* PBKDF2 algorithm name
*/
static readonly PBKDF2_ALGORITHM: "PBKDF2";
/**
* Default PBKDF2 hash algorithm
*/
static readonly PBKDF2_HASH: "SHA-256";
/**
* Default number of PBKDF2 iterations
*/
static readonly PBKDF2_ITERATIONS: number;
/**
* Argon2 algorithm name
*/
static readonly ARGON2_ALGORITHM: "Argon2id";
/**
* RSA-PSS algorithm name
*/
static readonly RSA_PSS_ALGORITHM: "RSA-PSS";
/**
* EdDSA algorithm name
*/
static readonly ED25519_ALGORITHM: "EdDSA";
/**
* Ed25519 curve name
*/
static readonly ED25519_CURVE: "Ed25519";
constructor();
/**
* Generate a new RSA-4096 key pair
*/
generateKeyPair(): Promise<CryptoKeyPair>;
/**
* Generate an ECDSA signing key pair
* @param curve - Supported curves: 'P-256' (default), 'P-384'
*/
generateSigningKeyPair(curve?: string): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Generate an EdDSA signing key pair
*/
generateEdDSASigningKeyPair(): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Generate an RSA-PSS signing key pair
* @param modulusLength - RSA key size in bits (default: 2048)
*/
generateRSAPSSigningKeyPair(modulusLength?: number): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Export public key to Base64-encoded SPKI format
*/
exportPublicKey(publicKey: CryptoKey): Promise<string>;
/**
* Export private key to Base64-encoded PKCS8 format
*/
exportPrivateKey(privateKey: CryptoKey): Promise<string>;
/**
* Import public key from Base64 SPKI string
*/
importPublicKey(b64: string): Promise<CryptoKey>;
/**
* Import private key from Base64 PKCS8 string
*/
importPrivateKey(b64: string): Promise<CryptoKey>;
/**
* Encrypt text using recipient's public key (hybrid: RSA-wrapped AES-GCM)
* @returns Base64-encoded encrypted data
*/
encryptText(text: string, publicKey: CryptoKey): Promise<string>;
/**
* Decrypt text using own private key
*/
decryptText(encryptedB64: string, privateKey: CryptoKey): Promise<string>;
/**
* Encrypt a file/blob using recipient's public key (streaming)
* @returns Object with encrypted Blob and suggested filename
*/
encryptFile(
fileOrBlob: Blob | File,
publicKey: CryptoKey,
options?: { parallelChunks?: number }
): Promise<{ blob: Blob; filename: string }>;
/**
* Decrypt an asymmetrically encrypted file/blob
* @returns Object with decrypted Blob and original filename
*/
decryptFile(
fileOrBlob: Blob | File,
privateKey: CryptoKey,
options?: { parallelChunks?: number }
): Promise<{ blob: Blob; filename: string }>;
/**
* Create an encryption transform function for WebRTC insertable streams
* Sends encrypted session key in the first frame.
*/
createEncryptTransform(
publicKey: CryptoKey
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Create a decryption transform function for WebRTC insertable streams
* Extracts session key from first frame and decrypts subsequent frames.
*/
createDecryptTransform(
privateKey: CryptoKey
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Create a hybrid encryption transform that supports both classical and post-quantum approaches
* @param publicKey - RSA public key for hybrid encryption
* @param usePostQuantum - Whether to use post-quantum hybrid approach
*/
createHybridEncryptTransform(
publicKey: CryptoKey,
usePostQuantum?: boolean
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Enhanced WebRTC transform with progress tracking
* @param publicKey - RSA public key for hybrid encryption
* @param onProgress - Callback function to report encryption progress
*/
createEncryptTransformWithProgress(
publicKey: CryptoKey,
onProgress?: (bytesProcessed: number) => void
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Encrypt a file with progress tracking
* @param fileOrBlob - File or Blob to encrypt
* @param publicKey - RSA public key for hybrid encryption
* @param onProgress - Callback function to report encryption progress
*/
encryptFileWithProgress(
fileOrBlob: Blob | File,
publicKey: CryptoKey,
onProgress?: (bytesProcessed: number) => void
): Promise<{ blob: Blob; filename: string }>;
/**
* Decrypt a file with progress tracking
* @param fileOrBlob - File or Blob to decrypt
* @param privateKey - RSA private key for hybrid decryption
* @param onProgress - Callback function to report decryption progress
*/
decryptFileWithProgress(
fileOrBlob: Blob | File,
privateKey: CryptoKey,
onProgress?: (bytesProcessed: number) => void
): Promise<{ blob: Blob; filename: string }>;
/**
* Derive a key using PBKDF2 with configurable parameters
* @param password - The password to derive the key from
* @param salt - Salt for the derivation
* @param iterations - Number of PBKDF2 iterations (default: 600000)
* @param hash - Hash algorithm (default: SHA-256)
* @param keyLength - Length of the derived key in bits
*/
deriveKeyPBKDF2(
password: string,
salt: Uint8Array,
iterations?: number,
hash?: string,
keyLength?: number
): Promise<CryptoKey>;
/**
* Derive a key using Argon2id (where supported)
* @param password - The password to derive the key from
* @param salt - Salt for the derivation
* @param options - Argon2 configuration options
*/
deriveKeyArgon2(
password: string,
salt: Uint8Array,
options?: {
iterations?: number;
memoryCost?: number;
parallelism?: number;
}
): Promise<CryptoKey>;
/**
* Generate a key for symmetric encryption using password-based derivation
* @param password - Password to derive the key from
* @param salt - Salt for key derivation
* @param algorithm - Key derivation algorithm (PBKDF2 or Argon2)
*/
generateKeyFromPassword(
password: string,
salt: Uint8Array,
algorithm?: "PBKDF2" | "Argon2"
): Promise<CryptoKey>;
/**
* Generate a new key for symmetric encryption using password-based derivation with key rotation
* @param password - Password to derive the key from
* @param salt - Salt for key derivation
* @param algorithm - Key derivation algorithm (PBKDF2 or Argon2)
* @param rotationCount - Rotation counter for key derivation
*/
generateRotatingKey(
password: string,
salt: Uint8Array,
algorithm?: "PBKDF2" | "Argon2",
rotationCount?: number
): Promise<CryptoKey>;
/**
* Generate a hierarchical key structure
* @param masterPassword - Master password for the hierarchy
* @param path - Path components to derive child keys from
*/
generateHierarchicalKey(
masterPassword: string,
path: string[]
): Promise<{
masterKey: CryptoKey;
childKeys: { [key: string]: CryptoKey };
}>;
/**
* Generate a key from multiple inputs (e.g., password + salt + nonce)
* @param inputs - Array of input strings to combine
* @param salt - Salt for key derivation
* @param algorithm - Key derivation algorithm (PBKDF2 or Argon2)
*/
generateKeyFromMultipleInputs(
inputs: string[],
salt: Uint8Array,
algorithm?: "PBKDF2" | "Argon2"
): Promise<CryptoKey>;
/**
* Sign a text message or data string with configurable algorithms
* @param text - Text to sign
* @param privateKey - Private key for signing (ECDSA)
* @param algorithm - Signature algorithm to use (ECDSA, EdDSA, RSA-PSS)
*/
signTextWithAlgorithm(
text: string,
privateKey: CryptoKey,
algorithm?: "ECDSA" | "EdDSA" | "RSA-PSS"
): Promise<string>;
/**
* Verify a signed text message with configurable algorithms
* @param text - Text that was signed
* @param signatureB64 - Base64-encoded signature
* @param publicKey - Public key for verification (ECDSA)
* @param algorithm - Signature algorithm to use (ECDSA, EdDSA, RSA-PSS)
*/
verifyTextWithAlgorithm(
text: string,
signatureB64: string,
publicKey: CryptoKey,
algorithm?: "ECDSA" | "EdDSA" | "RSA-PSS"
): Promise<boolean>;
/**
* Create an HMAC signature using configurable hash algorithms
* @param data - Data to sign
* @param key - HMAC key
* @param hash - Hash algorithm (SHA-256, SHA-384, or SHA-512)
*/
signHMAC(data: string, key: CryptoKey, hash?: "SHA-256" | "SHA-384" | "SHA-512"): Promise<string>;
/**
* Verify an HMAC signature using configurable hash algorithms
* @param data - Data that was signed
* @param signatureB64 - Base64-encoded HMAC signature
* @param key - HMAC key
* @param hash - Hash algorithm (SHA-256, SHA-384, or SHA-512)
*/
verifyHMAC(
data: string,
signatureB64: string,
key: CryptoKey,
hash?: "SHA-256" | "SHA-384" | "SHA-512"
): Promise<boolean>;
/**
* @deprecated Poly1305 is not supported by standard Web Crypto API. Use signHMAC() instead.
* @param data - Data to authenticate
* @param key - Poly1305 key (should be 32 bytes)
*/
authenticatePoly1305(data: ArrayBuffer, key: CryptoKey): Promise<string>;
/**
* Secure random number generation with better entropy sources
* @param length - Number of bytes to generate
*/
secureRandom(length: number): Promise<Uint8Array>;
/**
* Clear the internal key cache
*/
clearKeyCache(): void;
/**
* Stop automatic cache cleanup interval
*/
stopAutoCleanup(): void;
// ═══════════════════════════ Post-Quantum Key Derivation ═══════════════════════════
/**
* Enhanced Argon2id KDF (quantum-resistant, GPU/ASIC resistant).
* Stronger than PBKDF2 for high-entropy passwords.
*
* @param password - Password to derive from
* @param salt - Random salt (16+ bytes recommended)
* @param options - Configuration object
* @param options.memory - Memory cost in KiB (default: 65536 = 64MB)
* @param options.iterations - Time cost (default: 3)
* @param options.parallelism - Parallelism factor (default: 1)
* @param options.keyLength - Output key length in bits (default: 256)
* @returns Derived AES key
*/
deriveKeyArgon2Enhanced(
password: string,
salt: Uint8Array,
options?: {
memory?: number;
iterations?: number;
parallelism?: number;
keyLength?: number;
}
): Promise<CryptoKey>;
/**
* SHA-3 based KDF (post-quantum collision-resistant).
* Alternative to PBKDF2/Argon2 using quantum-resistant SHA-3 hash.
*
* @param password - Password to derive from
* @param salt - Random salt
* @param iterations - KDF iterations (default: 50000)
* @param hash - Hash algorithm: 'SHA3-256' | 'SHA3-384' | 'SHA3-512'
* @param keyLength - Output key length in bits (default: 256)
* @returns Derived AES key
*/
deriveKeySHA3(
password: string,
iterations?: number,
algorithm?: "SHA3-256" | "SHA3-384" | "SHA3-512"
): Promise<CryptoKey>;
/**
* HKDF with SHA-3 (quantum-resistant key expansion).
* Suitable for deriving multiple independent keys from a master secret.
*
* @param secret - Input key material (IKM)
* @param salt - Optional salt (default: all zeros)
* @param info - Optional context/application-specific info
* @param keyLength - Output key length in bits (default: 256)
* @returns Derived AES key
*/
deriveKeyHKDFSHA3(
secret: Uint8Array,
salt?: Uint8Array,
info?: Uint8Array,
keyLength?: number
): Promise<CryptoKey>;
/**
* HKDF with SHA-256 (fallback variant).
*/
deriveKeyHKDFSHA2(
secret: Uint8Array,
salt?: Uint8Array,
info?: Uint8Array,
keyLength?: number
): Promise<CryptoKey>;
/**
* Key rotation: Derive new key with fresh salt.
* Enables periodic key rotation without data re-encryption (in some schemes).
*
* @param password - Original password
* @param newSalt - New salt for re-derivation
* @param method - KDF method: 'PBKDF2' | 'Argon2' | 'SHA3' | 'HKDF'
* @returns New derived key
*/
rotateKeyNew(
password: string,
newSalt: Uint8Array,
method?: "PBKDF2" | "Argon2" | "SHA3" | "HKDF"
): Promise<CryptoKey>;
/**
* Hierarchical key derivation: Create distinct keys for different purposes.
* Enables key structures where child keys are derived from a parent key.
*
* @param parentKey - Parent AES key
* @param childSalt - Context/application-specific salt
* @param purpose - Purpose string (e.g., 'encryption', 'signing', 'hmac')
* @returns Child derived key
*/
deriveChildKeyHierarchical(
parentKey: CryptoKey,
childSalt: Uint8Array,
purpose?: string
): Promise<CryptoKey>;
/**
* Secure key erasure: Overwrite sensitive key material in memory.
* Best-effort; true secure erasure depends on runtime guarantees.
*
* @param key - Key material to erase
*/
secureKeyErase(key: Uint8Array): void;
// ────────────────────── ECDH Key Exchange ──────────────────────
/**
* Generate an ECDH key pair for key exchange.
* @param curve - Elliptic curve to use (default: 'P-256')
*/
generateECDHKeyPair(curve?: string): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Export an ECDH public key to base64 for sharing.
*/
exportECDHPublicKey(publicKey: CryptoKey): Promise<string>;
/**
* Import an ECDH public key from base64.
* @param b64 - Base64 string of the public key
* @param curve - Curve used (default: 'P-256')
*/
importECDHPublicKey(b64: string, curve?: string): Promise<CryptoKey>;
/**
* Derive a shared secret using ECDH.
* @param privateKey - Your private key
* @param publicKey - The other party's public key
*/
deriveECDHSharedSecret(privateKey: CryptoKey, publicKey: CryptoKey): Promise<CryptoKey>;
/**
* Encrypt data automatically deriving an ECDH shared secret.
* @param data - Serializable data or string to encrypt
* @param privateKey - Sender's private key
* @param recipientPublicKey - Recipient's public key
*/
encryptWithECDH(data: any, privateKey: CryptoKey, recipientPublicKey: CryptoKey): Promise<string>;
/**
* Decrypt data automatically deriving an ECDH shared secret.
* @param b64 - Base64-encoded encrypted payload
* @param privateKey - Recipient's private key
* @param senderPublicKey - Sender's public key
*/
decryptWithECDH(b64: string, privateKey: CryptoKey, senderPublicKey: CryptoKey): Promise<any>;
/**
* Automatically serializes any JavaScript object or array to JSON before encrypting.
*/
encryptData(data: any, publicKey: CryptoKey): Promise<string>;
/**
* Decrypts the data and automatically parses it back into a JavaScript object.
*/
decryptData(b64: string, privateKey: CryptoKey): Promise<any>;
/**
* Import a public signing key from base64 (SPKI format)
* @param publicKeyB64 - Base64 encoded SPKI public key
* @param curve - Elliptic curve ('P-256' default, 'P-384')
*/
importPublicSigningKey(publicKeyB64: string, curve?: string): Promise<CryptoKey>;
/**
* Sign a text message or data string with ECDSA
* @param text - Text to sign
* @param privateKey - ECDSA private key
* @returns Base64-encoded detached signature
*/
signText(text: string, privateKey: CryptoKey): Promise<string>;
/**
* Verify a signed text message with ECDSA
* @param text - Text that was signed
* @param signatureB64 - Base64 signature
* @param publicKey - ECDSA public key
*/
verifyText(text: string, signatureB64: string, publicKey: CryptoKey): Promise<boolean>;
/**
* Create a detached signature for a file or blob
* @param fileOrBlob - File or Blob object to sign
* @param privateKey - ECDSA private key
*/
signFile(fileOrBlob: any, privateKey: CryptoKey): Promise<{ signatureB64: string; blob: any }>;
/**
* Verify a detached signature for a file or blob
* @param fileOrBlob - File or Blob object that was signed
* @param signatureB64 - Base64 signature
* @param publicKey - ECDSA public key
*/
verifyFile(fileOrBlob: any, signatureB64: string, publicKey: CryptoKey): Promise<boolean>;
// ────────────────────── JSON Web Encryption (JWE) ──────────────────────
/**
* Encrypts payload into a JWE Compact Serialization string.
* Uses RSA-OAEP-256 for key management and A256GCM for content encryption.
*
* @param payload - Data to encrypt (string or serializable object)
* @param publicKey - Recipient's RSA public key
* @param customHeaders - Additional JWE protected headers
* @returns JWE Token string
*/
encryptJWE(payload: any, publicKey: CryptoKey, customHeaders?: object): Promise<string>;
/**
* Decrypts a JWE Compact Serialization string.
*
* @param jweToken - JWE Token string
* @param privateKey - Recipient's RSA private key
* @returns Decrypted payload (parsed object if applicable, else string)
*/
decryptJWE(jweToken: string, privateKey: CryptoKey): Promise<any>;
}
// src/WebCryptPQC.d.ts
// Post-Quantum Cryptography type definitions
/**
* WebCryptPQC – Post-quantum key exchange and digital signatures
*
* Implements NIST PQC finalists:
* - Kyber: Lattice-based Key Encapsulation Mechanism (KEM)
* - Dilithium: Lattice-based Digital Signature Algorithm
*/
declare class WebCryptPQC {
/**
* Kyber security levels
*/
static readonly KYBER_512: "Kyber512";
static readonly KYBER_768: "Kyber768";
static readonly KYBER_1024: "Kyber1024";
/**
* Kyber parameters including key and ciphertext sizes
*/
static readonly KYBER_PARAMS: {
[key: string]: {
name: string;
securityLevel: string;
publicKeySize: number;
privateKeySize: number;
ciphertextSize: number;
sharedSecretSize: number;
};
};
/**
* Dilithium security levels
*/
static readonly DILITHIUM_2: "Dilithium2";
static readonly DILITHIUM_3: "Dilithium3";
static readonly DILITHIUM_5: "Dilithium5";
/**
* Dilithium parameters including key and signature sizes
*/
static readonly DILITHIUM_PARAMS: {
[key: string]: {
name: string;
securityLevel: string;
publicKeySize: number;
privateKeySize: number;
signatureSize: number;
};
};
/**
* SHA-3 hash algorithms
*/
static readonly HASH_SHA3_256: "SHA3-256";
static readonly HASH_SHA3_384: "SHA3-384";
static readonly HASH_SHA3_512: "SHA3-512";
/**
* Supported Kyber levels
*/
static readonly SUPPORTED_KYBER_LEVELS: string[];
/**
* Supported Dilithium levels
*/
static readonly SUPPORTED_DILITHIUM_LEVELS: string[];
/**
* Returns true if PQC module is running as a placeholder/stub.
*/
static isStub(): boolean;
/**
* Enable or disable stub testing mode for unit tests.
* @param allow Enable stub testing mode if true
*/
static enableStubTesting(allow?: boolean): void;
constructor();
// ─────────────────────── Kyber KEM ───────────────────────
/**
* Generate a Kyber key pair for key encapsulation.
* @param level - Kyber level: "Kyber512" | "Kyber768" | "Kyber1024" (default: Kyber768)
*/
generateKyberKeyPair(level?: string): Promise<{
publicKey: Uint8Array;
privateKey: Uint8Array;
}>;
/**
* Encapsulate: Create a shared secret and ciphertext using recipient's Kyber public key.
* @param kyberPublicKey - Recipient's Kyber public key
* @param level - Kyber level (default: Kyber768)
* @returns Ciphertext and derived shared secret
*/
kyberEncapsulate(
kyberPublicKey: Uint8Array,
level?: string
): Promise<{
ciphertext: Uint8Array;
sharedSecret: Uint8Array;
}>;
/**
* Decapsulate: Recover the shared secret using private key and ciphertext.
* @param ciphertext - Encapsulated ciphertext from kyberEncapsulate
* @param kyberPrivateKey - Own Kyber private key
* @param level - Kyber level (default: Kyber768)
* @returns The shared secret
*/
kyberDecapsulate(
ciphertext: Uint8Array,
kyberPrivateKey: Uint8Array,
level?: string
): Promise<Uint8Array>;
// ─────────────────────── Dilithium Signatures ───────────────────────
/**
* Generate a Dilithium key pair for digital signatures.
* @param level - Dilithium level: "Dilithium2" | "Dilithium3" | "Dilithium5" (default: Dilithium3)
*/
generateDilithiumKeyPair(level?: string): Promise<{
publicKey: Uint8Array;
privateKey: Uint8Array;
}>;
/**
* Sign a message using Dilithium private key.
* @param message - Message to sign (string or Uint8Array)
* @param dilithiumPrivateKey - Dilithium private key
* @param level - Dilithium level (default: Dilithium3)
* @returns Digital signature
*/
dilithiumSign(
message: string | Uint8Array,
dilithiumPrivateKey: Uint8Array,
level?: string
): Promise<Uint8Array>;
/**
* Verify a Dilithium signature.
* @param message - Original message (string or Uint8Array)
* @param signature - Signature from dilithiumSign
* @param dilithiumPublicKey - Dilithium public key
* @param level - Dilithium level (default: Dilithium3)
* @returns True if valid
*/
dilithiumVerify(
message: string | Uint8Array,
signature: Uint8Array,
dilithiumPublicKey: Uint8Array,
level?: string
): Promise<boolean>;
// ─────────────────────── Hybrid Encryption ───────────────────────
/**
* Hybrid encapsulation: Use both Kyber (PQC) and RSA-OAEP.
* Combines classical and post-quantum key encapsulation for maximum security.
*
* @param rsaPublicKey - RSA-4096 public key (classical)
* @param kyberPublicKey - Kyber public key (post-quantum)
* @param kyberLevel - Kyber level (default: Kyber768)
* @returns Shared secret and ciphertexts for both KEM schemes
*/
hybridEncapsulate(
rsaPublicKey: CryptoKey,
kyberPublicKey: Uint8Array,
kyberLevel?: string
): Promise<{
sharedSecret: Uint8Array;
kyberCiphertext: Uint8Array;
rsaWrappedSharedSecret: Uint8Array;
}>;
/**
* Hybrid decapsulation: Recover shared secret using both Kyber and RSA private keys.
* Falls back to Kyber alone if RSA decryption fails (provides forward secrecy).
*
* @param kyberCiphertext - From hybridEncapsulate
* @param rsaWrappedSharedSecret - From hybridEncapsulate
* @param rsaPrivateKey - RSA-4096 private key
* @param kyberPrivateKey - Kyber private key
* @param kyberLevel - Kyber level (default: Kyber768)
* @returns The hybrid shared secret
*/
hybridDecapsulate(
kyberCiphertext: Uint8Array,
rsaWrappedSharedSecret: Uint8Array,
rsaPrivateKey: CryptoKey,
kyberPrivateKey: Uint8Array,
kyberLevel?: string
): Promise<Uint8Array>;
// ─────────────────────── Key Serialization ───────────────────────
kyberPublicKeyToBase64(publicKey: Uint8Array): string;
kyberPublicKeyFromBase64(b64: string): Uint8Array;
kyberPrivateKeyToBase64(privateKey: Uint8Array): string;
kyberPrivateKeyFromBase64(b64: string): Uint8Array;
dilithiumPublicKeyToBase64(publicKey: Uint8Array): string;
dilithiumPublicKeyFromBase64(b64: string): Uint8Array;
dilithiumPrivateKeyToBase64(privateKey: Uint8Array): string;
dilithiumPrivateKeyFromBase64(b64: string): Uint8Array;
}
// src/TimingSafeHelper.d.ts

@@ -1070,2 +41,2 @@

export { TimingSafeHelper, WebCrypt, WebCryptAsym, WebCryptPQC };
export { TimingSafeHelper };
+2
-1031
dist/index.d.ts

@@ -1,1032 +0,3 @@

// src/WebCrypt.d.ts
export { W as WebCrypt, a as WebCryptAsym, b as WebCryptPQC, c as arrayBufferToBase64, d as base64ToArrayBuffer, e as base64ToUint8Array, g as getCrypto, i as isValidBase64 } from './_crypto-B6690zvC.js';
/**
* WebCrypt – Zero-dependency quantum-resistant AES-256-GCM encryption
*
* Supports:
* - Text encryption/decryption
* - Large file encryption/decryption (streaming)
* - WebRTC Insertable Streams E2EE (video + audio)
* - HMAC for message authentication
*
* Works in Browser, Node.js 18+, Deno, Cloudflare Workers
*/
declare class WebCrypt {
static readonly ALGORITHM: "AES-GCM";
static readonly KEY_LENGTH: 256;
static readonly IV_LENGTH: 12;
static readonly SALT_LENGTH: 16;
static readonly PBKDF2_ITERATIONS: number;
static readonly HASH_ALGORITHM: "SHA-256";
static readonly CHUNK_SIZE: number;
static readonly WEBRTC_SALT: Uint8Array;
static readonly DEFAULT_HMAC_SALT: Uint8Array;
/**
* Generates a cryptographically secure random salt for HMAC key derivation.
* @param length Salt length in bytes (default: 16)
*/
static generateHmacSalt(length?: number): Uint8Array;
/**
* Encrypts a string and returns Base64-encoded ciphertext
* @param text Plain text to encrypt
* @param password Password (or shared secret)
* @returns Base64 string (salt + iv + ciphertext)
*/
encryptText(text: string, password: string): Promise<string>;
/**
* Decrypts a Base64 string produced by encryptText()
* @param base64 Encrypted data from encryptText()
* @param password Must match encryption password
* @returns Original plain text
* @throws If password is wrong or data is corrupted
*/
decryptText(base64: string, password: string): Promise<string>;
/**
* Encrypts a File or Blob using streaming (low memory, handles huge files)
* @param file File or Blob to encrypt
* @param password Encryption password
* @param options Optional configuration object ({ parallelChunks?: number })
* @returns Object with encrypted Blob and suggested filename
*/
encryptFile(
file: File | Blob,
password: string,
options?: { parallelChunks?: number }
): Promise<{
blob: Blob;
filename: string;
}>;
/**
* Decrypts a .encrypted file produced by encryptFile()
* @param file Encrypted File or Blob
* @param password Must match encryption password
* @param options Optional configuration object ({ parallelChunks?: number })
* @returns Object with decrypted Blob and original filename
* @throws If password is wrong or file is corrupted
*/
decryptFile(
file: File | Blob,
password: string,
options?: { parallelChunks?: number }
): Promise<{
blob: Blob;
filename: string;
}>;
/**
* Creates an encryption transform for WebRTC Insertable Streams
* Use with RTCRtpSender.transform
* @param password Shared secret both peers must know
*/
createEncryptTransform(
password: string
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Creates a decryption transform for WebRTC Insertable Streams
* Use with RTCRtpReceiver.transform
* @param password Must match sender's password
*/
createDecryptTransform(
password: string
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Generates or derives an HMAC key.
* @param password Optional password for PBKDF2 derivation (if provided, uses 600_000 iterations).
* @param hash Hash algorithm (default: 'SHA-256').
* @param salt Optional salt for deterministic derivation.
* @returns Usable HMAC key.
*/
generateHmacKey(
password?: string,
hash?: "SHA-256" | "SHA-384" | "SHA-512",
salt?: Uint8Array | string
): Promise<CryptoKey>;
/**
* Computes HMAC on data.
* @param data Text or ArrayBuffer to authenticate.
* @param key HMAC key from generateHmacKey.
* @returns Base64-encoded HMAC tag.
*/
computeHmac(data: string | ArrayBuffer, key: CryptoKey): Promise<string>;
/**
* Verifies HMAC on data.
* @param data Text or ArrayBuffer to verify.
* @param hmac Base64-encoded HMAC tag to check.
* @param key HMAC key.
* @returns True if valid.
*/
verifyHmac(data: string | ArrayBuffer, hmac: string, key: CryptoKey): Promise<boolean>;
/**
* Generate a quantum-resistant HMAC key using SHA-3 hash.
* @param password Optional password for derivation
* @param hash Hash algorithm: 'SHA3-256' | 'SHA3-384' | 'SHA3-512' (default: SHA3-256)
* @param salt Optional salt for deterministic derivation.
* @param iterations Iterations count for SHA-3 KDF derivation (default: 10,000)
* @returns Usable HMAC key with SHA-3
*/
generateHmacKeySHA3(
password?: string,
hash?: "SHA3-256" | "SHA3-384" | "SHA3-512",
salt?: Uint8Array | string,
iterations?: number
): Promise<CryptoKey>;
/**
* Compute HMAC using SHA-3 (quantum-resistant).
* @param data Data to authenticate
* @param key HMAC key from generateHmacKeySHA3
* @returns Base64-encoded HMAC tag
*/
computeHmacSHA3(data: string | ArrayBuffer, key: CryptoKey): Promise<string>;
/**
* Verify HMAC using SHA-3 (quantum-resistant).
* @param data Data to verify
* @param hmac Base64-encoded HMAC tag
* @param key HMAC key
* @returns True if valid
*/
verifyHmacSHA3(data: string | ArrayBuffer, hmac: string, key: CryptoKey): Promise<boolean>;
/**
* Automatically serializes any JavaScript object or array to JSON before encrypting.
*/
encryptData(data: any, password: string): Promise<string>;
/**
* Decrypts the data and automatically parses it back into a JavaScript object.
*/
decryptData(base64: string, password: string): Promise<any>;
/**
* Utility to generate a cryptographically secure random password or key string.
*/
generateRandomPassword(length?: number): string;
/**
* Clear entire key cache.
*/
clearKeyCache(): void;
/**
* Stop automatic cache cleanup interval.
*/
stopAutoCleanup(): void;
}
// WebCryptAsym.d.ts
/**
* Asymmetric encryption utility using RSA-OAEP + AES-GCM hybrid encryption.
* Supports text, file (streaming), and WebRTC insertable streams.
*/
declare class WebCryptAsym {
/**
* RSA-OAEP algorithm parameters
*/
static readonly RSA_ALGORITHM: AlgorithmIdentifier;
/**
* Parameters for RSA key generation (4096-bit, SHA-256)
*/
static readonly RSA_KEY_PARAMS: RsaHashedKeyGenParams;
/**
* AES-GCM algorithm name
*/
static readonly AES_ALGORITHM: "AES-GCM";
/**
* AES key length (256 bits)
*/
static readonly AES_LENGTH: 256;
/**
* IV length for AES-GCM (12 bytes recommended)
*/
static readonly IV_LENGTH: 12;
/**
* Chunk size for file streaming (8 MB)
*/
static readonly CHUNK_SIZE: number;
/**
* Fixed salt-like identifier for WebRTC transforms
*/
static readonly WEBRTC_SALT: Uint8Array;
/**
* PBKDF2 algorithm name
*/
static readonly PBKDF2_ALGORITHM: "PBKDF2";
/**
* Default PBKDF2 hash algorithm
*/
static readonly PBKDF2_HASH: "SHA-256";
/**
* Default number of PBKDF2 iterations
*/
static readonly PBKDF2_ITERATIONS: number;
/**
* Argon2 algorithm name
*/
static readonly ARGON2_ALGORITHM: "Argon2id";
/**
* RSA-PSS algorithm name
*/
static readonly RSA_PSS_ALGORITHM: "RSA-PSS";
/**
* EdDSA algorithm name
*/
static readonly ED25519_ALGORITHM: "EdDSA";
/**
* Ed25519 curve name
*/
static readonly ED25519_CURVE: "Ed25519";
constructor();
/**
* Generate a new RSA-4096 key pair
*/
generateKeyPair(): Promise<CryptoKeyPair>;
/**
* Generate an ECDSA signing key pair
* @param curve - Supported curves: 'P-256' (default), 'P-384'
*/
generateSigningKeyPair(curve?: string): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Generate an EdDSA signing key pair
*/
generateEdDSASigningKeyPair(): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Generate an RSA-PSS signing key pair
* @param modulusLength - RSA key size in bits (default: 2048)
*/
generateRSAPSSigningKeyPair(modulusLength?: number): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Export public key to Base64-encoded SPKI format
*/
exportPublicKey(publicKey: CryptoKey): Promise<string>;
/**
* Export private key to Base64-encoded PKCS8 format
*/
exportPrivateKey(privateKey: CryptoKey): Promise<string>;
/**
* Import public key from Base64 SPKI string
*/
importPublicKey(b64: string): Promise<CryptoKey>;
/**
* Import private key from Base64 PKCS8 string
*/
importPrivateKey(b64: string): Promise<CryptoKey>;
/**
* Encrypt text using recipient's public key (hybrid: RSA-wrapped AES-GCM)
* @returns Base64-encoded encrypted data
*/
encryptText(text: string, publicKey: CryptoKey): Promise<string>;
/**
* Decrypt text using own private key
*/
decryptText(encryptedB64: string, privateKey: CryptoKey): Promise<string>;
/**
* Encrypt a file/blob using recipient's public key (streaming)
* @returns Object with encrypted Blob and suggested filename
*/
encryptFile(
fileOrBlob: Blob | File,
publicKey: CryptoKey,
options?: { parallelChunks?: number }
): Promise<{ blob: Blob; filename: string }>;
/**
* Decrypt an asymmetrically encrypted file/blob
* @returns Object with decrypted Blob and original filename
*/
decryptFile(
fileOrBlob: Blob | File,
privateKey: CryptoKey,
options?: { parallelChunks?: number }
): Promise<{ blob: Blob; filename: string }>;
/**
* Create an encryption transform function for WebRTC insertable streams
* Sends encrypted session key in the first frame.
*/
createEncryptTransform(
publicKey: CryptoKey
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Create a decryption transform function for WebRTC insertable streams
* Extracts session key from first frame and decrypts subsequent frames.
*/
createDecryptTransform(
privateKey: CryptoKey
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Create a hybrid encryption transform that supports both classical and post-quantum approaches
* @param publicKey - RSA public key for hybrid encryption
* @param usePostQuantum - Whether to use post-quantum hybrid approach
*/
createHybridEncryptTransform(
publicKey: CryptoKey,
usePostQuantum?: boolean
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Enhanced WebRTC transform with progress tracking
* @param publicKey - RSA public key for hybrid encryption
* @param onProgress - Callback function to report encryption progress
*/
createEncryptTransformWithProgress(
publicKey: CryptoKey,
onProgress?: (bytesProcessed: number) => void
): Promise<
(
frame: RTCEncodedVideoFrame | RTCEncodedAudioFrame,
controller: TransformStreamDefaultController
) => Promise<void>
>;
/**
* Encrypt a file with progress tracking
* @param fileOrBlob - File or Blob to encrypt
* @param publicKey - RSA public key for hybrid encryption
* @param onProgress - Callback function to report encryption progress
*/
encryptFileWithProgress(
fileOrBlob: Blob | File,
publicKey: CryptoKey,
onProgress?: (bytesProcessed: number) => void
): Promise<{ blob: Blob; filename: string }>;
/**
* Decrypt a file with progress tracking
* @param fileOrBlob - File or Blob to decrypt
* @param privateKey - RSA private key for hybrid decryption
* @param onProgress - Callback function to report decryption progress
*/
decryptFileWithProgress(
fileOrBlob: Blob | File,
privateKey: CryptoKey,
onProgress?: (bytesProcessed: number) => void
): Promise<{ blob: Blob; filename: string }>;
/**
* Derive a key using PBKDF2 with configurable parameters
* @param password - The password to derive the key from
* @param salt - Salt for the derivation
* @param iterations - Number of PBKDF2 iterations (default: 600000)
* @param hash - Hash algorithm (default: SHA-256)
* @param keyLength - Length of the derived key in bits
*/
deriveKeyPBKDF2(
password: string,
salt: Uint8Array,
iterations?: number,
hash?: string,
keyLength?: number
): Promise<CryptoKey>;
/**
* Derive a key using Argon2id (where supported)
* @param password - The password to derive the key from
* @param salt - Salt for the derivation
* @param options - Argon2 configuration options
*/
deriveKeyArgon2(
password: string,
salt: Uint8Array,
options?: {
iterations?: number;
memoryCost?: number;
parallelism?: number;
}
): Promise<CryptoKey>;
/**
* Generate a key for symmetric encryption using password-based derivation
* @param password - Password to derive the key from
* @param salt - Salt for key derivation
* @param algorithm - Key derivation algorithm (PBKDF2 or Argon2)
*/
generateKeyFromPassword(
password: string,
salt: Uint8Array,
algorithm?: "PBKDF2" | "Argon2"
): Promise<CryptoKey>;
/**
* Generate a new key for symmetric encryption using password-based derivation with key rotation
* @param password - Password to derive the key from
* @param salt - Salt for key derivation
* @param algorithm - Key derivation algorithm (PBKDF2 or Argon2)
* @param rotationCount - Rotation counter for key derivation
*/
generateRotatingKey(
password: string,
salt: Uint8Array,
algorithm?: "PBKDF2" | "Argon2",
rotationCount?: number
): Promise<CryptoKey>;
/**
* Generate a hierarchical key structure
* @param masterPassword - Master password for the hierarchy
* @param path - Path components to derive child keys from
*/
generateHierarchicalKey(
masterPassword: string,
path: string[]
): Promise<{
masterKey: CryptoKey;
childKeys: { [key: string]: CryptoKey };
}>;
/**
* Generate a key from multiple inputs (e.g., password + salt + nonce)
* @param inputs - Array of input strings to combine
* @param salt - Salt for key derivation
* @param algorithm - Key derivation algorithm (PBKDF2 or Argon2)
*/
generateKeyFromMultipleInputs(
inputs: string[],
salt: Uint8Array,
algorithm?: "PBKDF2" | "Argon2"
): Promise<CryptoKey>;
/**
* Sign a text message or data string with configurable algorithms
* @param text - Text to sign
* @param privateKey - Private key for signing (ECDSA)
* @param algorithm - Signature algorithm to use (ECDSA, EdDSA, RSA-PSS)
*/
signTextWithAlgorithm(
text: string,
privateKey: CryptoKey,
algorithm?: "ECDSA" | "EdDSA" | "RSA-PSS"
): Promise<string>;
/**
* Verify a signed text message with configurable algorithms
* @param text - Text that was signed
* @param signatureB64 - Base64-encoded signature
* @param publicKey - Public key for verification (ECDSA)
* @param algorithm - Signature algorithm to use (ECDSA, EdDSA, RSA-PSS)
*/
verifyTextWithAlgorithm(
text: string,
signatureB64: string,
publicKey: CryptoKey,
algorithm?: "ECDSA" | "EdDSA" | "RSA-PSS"
): Promise<boolean>;
/**
* Create an HMAC signature using configurable hash algorithms
* @param data - Data to sign
* @param key - HMAC key
* @param hash - Hash algorithm (SHA-256, SHA-384, or SHA-512)
*/
signHMAC(data: string, key: CryptoKey, hash?: "SHA-256" | "SHA-384" | "SHA-512"): Promise<string>;
/**
* Verify an HMAC signature using configurable hash algorithms
* @param data - Data that was signed
* @param signatureB64 - Base64-encoded HMAC signature
* @param key - HMAC key
* @param hash - Hash algorithm (SHA-256, SHA-384, or SHA-512)
*/
verifyHMAC(
data: string,
signatureB64: string,
key: CryptoKey,
hash?: "SHA-256" | "SHA-384" | "SHA-512"
): Promise<boolean>;
/**
* @deprecated Poly1305 is not supported by standard Web Crypto API. Use signHMAC() instead.
* @param data - Data to authenticate
* @param key - Poly1305 key (should be 32 bytes)
*/
authenticatePoly1305(data: ArrayBuffer, key: CryptoKey): Promise<string>;
/**
* Secure random number generation with better entropy sources
* @param length - Number of bytes to generate
*/
secureRandom(length: number): Promise<Uint8Array>;
/**
* Clear the internal key cache
*/
clearKeyCache(): void;
/**
* Stop automatic cache cleanup interval
*/
stopAutoCleanup(): void;
// ═══════════════════════════ Post-Quantum Key Derivation ═══════════════════════════
/**
* Enhanced Argon2id KDF (quantum-resistant, GPU/ASIC resistant).
* Stronger than PBKDF2 for high-entropy passwords.
*
* @param password - Password to derive from
* @param salt - Random salt (16+ bytes recommended)
* @param options - Configuration object
* @param options.memory - Memory cost in KiB (default: 65536 = 64MB)
* @param options.iterations - Time cost (default: 3)
* @param options.parallelism - Parallelism factor (default: 1)
* @param options.keyLength - Output key length in bits (default: 256)
* @returns Derived AES key
*/
deriveKeyArgon2Enhanced(
password: string,
salt: Uint8Array,
options?: {
memory?: number;
iterations?: number;
parallelism?: number;
keyLength?: number;
}
): Promise<CryptoKey>;
/**
* SHA-3 based KDF (post-quantum collision-resistant).
* Alternative to PBKDF2/Argon2 using quantum-resistant SHA-3 hash.
*
* @param password - Password to derive from
* @param salt - Random salt
* @param iterations - KDF iterations (default: 50000)
* @param hash - Hash algorithm: 'SHA3-256' | 'SHA3-384' | 'SHA3-512'
* @param keyLength - Output key length in bits (default: 256)
* @returns Derived AES key
*/
deriveKeySHA3(
password: string,
iterations?: number,
algorithm?: "SHA3-256" | "SHA3-384" | "SHA3-512"
): Promise<CryptoKey>;
/**
* HKDF with SHA-3 (quantum-resistant key expansion).
* Suitable for deriving multiple independent keys from a master secret.
*
* @param secret - Input key material (IKM)
* @param salt - Optional salt (default: all zeros)
* @param info - Optional context/application-specific info
* @param keyLength - Output key length in bits (default: 256)
* @returns Derived AES key
*/
deriveKeyHKDFSHA3(
secret: Uint8Array,
salt?: Uint8Array,
info?: Uint8Array,
keyLength?: number
): Promise<CryptoKey>;
/**
* HKDF with SHA-256 (fallback variant).
*/
deriveKeyHKDFSHA2(
secret: Uint8Array,
salt?: Uint8Array,
info?: Uint8Array,
keyLength?: number
): Promise<CryptoKey>;
/**
* Key rotation: Derive new key with fresh salt.
* Enables periodic key rotation without data re-encryption (in some schemes).
*
* @param password - Original password
* @param newSalt - New salt for re-derivation
* @param method - KDF method: 'PBKDF2' | 'Argon2' | 'SHA3' | 'HKDF'
* @returns New derived key
*/
rotateKeyNew(
password: string,
newSalt: Uint8Array,
method?: "PBKDF2" | "Argon2" | "SHA3" | "HKDF"
): Promise<CryptoKey>;
/**
* Hierarchical key derivation: Create distinct keys for different purposes.
* Enables key structures where child keys are derived from a parent key.
*
* @param parentKey - Parent AES key
* @param childSalt - Context/application-specific salt
* @param purpose - Purpose string (e.g., 'encryption', 'signing', 'hmac')
* @returns Child derived key
*/
deriveChildKeyHierarchical(
parentKey: CryptoKey,
childSalt: Uint8Array,
purpose?: string
): Promise<CryptoKey>;
/**
* Secure key erasure: Overwrite sensitive key material in memory.
* Best-effort; true secure erasure depends on runtime guarantees.
*
* @param key - Key material to erase
*/
secureKeyErase(key: Uint8Array): void;
// ────────────────────── ECDH Key Exchange ──────────────────────
/**
* Generate an ECDH key pair for key exchange.
* @param curve - Elliptic curve to use (default: 'P-256')
*/
generateECDHKeyPair(curve?: string): Promise<{
publicKey: CryptoKey;
privateKey: CryptoKey;
publicKeyB64: string;
}>;
/**
* Export an ECDH public key to base64 for sharing.
*/
exportECDHPublicKey(publicKey: CryptoKey): Promise<string>;
/**
* Import an ECDH public key from base64.
* @param b64 - Base64 string of the public key
* @param curve - Curve used (default: 'P-256')
*/
importECDHPublicKey(b64: string, curve?: string): Promise<CryptoKey>;
/**
* Derive a shared secret using ECDH.
* @param privateKey - Your private key
* @param publicKey - The other party's public key
*/
deriveECDHSharedSecret(privateKey: CryptoKey, publicKey: CryptoKey): Promise<CryptoKey>;
/**
* Encrypt data automatically deriving an ECDH shared secret.
* @param data - Serializable data or string to encrypt
* @param privateKey - Sender's private key
* @param recipientPublicKey - Recipient's public key
*/
encryptWithECDH(data: any, privateKey: CryptoKey, recipientPublicKey: CryptoKey): Promise<string>;
/**
* Decrypt data automatically deriving an ECDH shared secret.
* @param b64 - Base64-encoded encrypted payload
* @param privateKey - Recipient's private key
* @param senderPublicKey - Sender's public key
*/
decryptWithECDH(b64: string, privateKey: CryptoKey, senderPublicKey: CryptoKey): Promise<any>;
/**
* Automatically serializes any JavaScript object or array to JSON before encrypting.
*/
encryptData(data: any, publicKey: CryptoKey): Promise<string>;
/**
* Decrypts the data and automatically parses it back into a JavaScript object.
*/
decryptData(b64: string, privateKey: CryptoKey): Promise<any>;
/**
* Import a public signing key from base64 (SPKI format)
* @param publicKeyB64 - Base64 encoded SPKI public key
* @param curve - Elliptic curve ('P-256' default, 'P-384')
*/
importPublicSigningKey(publicKeyB64: string, curve?: string): Promise<CryptoKey>;
/**
* Sign a text message or data string with ECDSA
* @param text - Text to sign
* @param privateKey - ECDSA private key
* @returns Base64-encoded detached signature
*/
signText(text: string, privateKey: CryptoKey): Promise<string>;
/**
* Verify a signed text message with ECDSA
* @param text - Text that was signed
* @param signatureB64 - Base64 signature
* @param publicKey - ECDSA public key
*/
verifyText(text: string, signatureB64: string, publicKey: CryptoKey): Promise<boolean>;
/**
* Create a detached signature for a file or blob
* @param fileOrBlob - File or Blob object to sign
* @param privateKey - ECDSA private key
*/
signFile(fileOrBlob: any, privateKey: CryptoKey): Promise<{ signatureB64: string; blob: any }>;
/**
* Verify a detached signature for a file or blob
* @param fileOrBlob - File or Blob object that was signed
* @param signatureB64 - Base64 signature
* @param publicKey - ECDSA public key
*/
verifyFile(fileOrBlob: any, signatureB64: string, publicKey: CryptoKey): Promise<boolean>;
// ────────────────────── JSON Web Encryption (JWE) ──────────────────────
/**
* Encrypts payload into a JWE Compact Serialization string.
* Uses RSA-OAEP-256 for key management and A256GCM for content encryption.
*
* @param payload - Data to encrypt (string or serializable object)
* @param publicKey - Recipient's RSA public key
* @param customHeaders - Additional JWE protected headers
* @returns JWE Token string
*/
encryptJWE(payload: any, publicKey: CryptoKey, customHeaders?: object): Promise<string>;
/**
* Decrypts a JWE Compact Serialization string.
*
* @param jweToken - JWE Token string
* @param privateKey - Recipient's RSA private key
* @returns Decrypted payload (parsed object if applicable, else string)
*/
decryptJWE(jweToken: string, privateKey: CryptoKey): Promise<any>;
}
// src/WebCryptPQC.d.ts
// Post-Quantum Cryptography type definitions
/**
* WebCryptPQC – Post-quantum key exchange and digital signatures
*
* Implements NIST PQC finalists:
* - Kyber: Lattice-based Key Encapsulation Mechanism (KEM)
* - Dilithium: Lattice-based Digital Signature Algorithm
*/
declare class WebCryptPQC {
/**
* Kyber security levels
*/
static readonly KYBER_512: "Kyber512";
static readonly KYBER_768: "Kyber768";
static readonly KYBER_1024: "Kyber1024";
/**
* Kyber parameters including key and ciphertext sizes
*/
static readonly KYBER_PARAMS: {
[key: string]: {
name: string;
securityLevel: string;
publicKeySize: number;
privateKeySize: number;
ciphertextSize: number;
sharedSecretSize: number;
};
};
/**
* Dilithium security levels
*/
static readonly DILITHIUM_2: "Dilithium2";
static readonly DILITHIUM_3: "Dilithium3";
static readonly DILITHIUM_5: "Dilithium5";
/**
* Dilithium parameters including key and signature sizes
*/
static readonly DILITHIUM_PARAMS: {
[key: string]: {
name: string;
securityLevel: string;
publicKeySize: number;
privateKeySize: number;
signatureSize: number;
};
};
/**
* SHA-3 hash algorithms
*/
static readonly HASH_SHA3_256: "SHA3-256";
static readonly HASH_SHA3_384: "SHA3-384";
static readonly HASH_SHA3_512: "SHA3-512";
/**
* Supported Kyber levels
*/
static readonly SUPPORTED_KYBER_LEVELS: string[];
/**
* Supported Dilithium levels
*/
static readonly SUPPORTED_DILITHIUM_LEVELS: string[];
/**
* Returns true if PQC module is running as a placeholder/stub.
*/
static isStub(): boolean;
/**
* Enable or disable stub testing mode for unit tests.
* @param allow Enable stub testing mode if true
*/
static enableStubTesting(allow?: boolean): void;
constructor();
// ─────────────────────── Kyber KEM ───────────────────────
/**
* Generate a Kyber key pair for key encapsulation.
* @param level - Kyber level: "Kyber512" | "Kyber768" | "Kyber1024" (default: Kyber768)
*/
generateKyberKeyPair(level?: string): Promise<{
publicKey: Uint8Array;
privateKey: Uint8Array;
}>;
/**
* Encapsulate: Create a shared secret and ciphertext using recipient's Kyber public key.
* @param kyberPublicKey - Recipient's Kyber public key
* @param level - Kyber level (default: Kyber768)
* @returns Ciphertext and derived shared secret
*/
kyberEncapsulate(
kyberPublicKey: Uint8Array,
level?: string
): Promise<{
ciphertext: Uint8Array;
sharedSecret: Uint8Array;
}>;
/**
* Decapsulate: Recover the shared secret using private key and ciphertext.
* @param ciphertext - Encapsulated ciphertext from kyberEncapsulate
* @param kyberPrivateKey - Own Kyber private key
* @param level - Kyber level (default: Kyber768)
* @returns The shared secret
*/
kyberDecapsulate(
ciphertext: Uint8Array,
kyberPrivateKey: Uint8Array,
level?: string
): Promise<Uint8Array>;
// ─────────────────────── Dilithium Signatures ───────────────────────
/**
* Generate a Dilithium key pair for digital signatures.
* @param level - Dilithium level: "Dilithium2" | "Dilithium3" | "Dilithium5" (default: Dilithium3)
*/
generateDilithiumKeyPair(level?: string): Promise<{
publicKey: Uint8Array;
privateKey: Uint8Array;
}>;
/**
* Sign a message using Dilithium private key.
* @param message - Message to sign (string or Uint8Array)
* @param dilithiumPrivateKey - Dilithium private key
* @param level - Dilithium level (default: Dilithium3)
* @returns Digital signature
*/
dilithiumSign(
message: string | Uint8Array,
dilithiumPrivateKey: Uint8Array,
level?: string
): Promise<Uint8Array>;
/**
* Verify a Dilithium signature.
* @param message - Original message (string or Uint8Array)
* @param signature - Signature from dilithiumSign
* @param dilithiumPublicKey - Dilithium public key
* @param level - Dilithium level (default: Dilithium3)
* @returns True if valid
*/
dilithiumVerify(
message: string | Uint8Array,
signature: Uint8Array,
dilithiumPublicKey: Uint8Array,
level?: string
): Promise<boolean>;
// ─────────────────────── Hybrid Encryption ───────────────────────
/**
* Hybrid encapsulation: Use both Kyber (PQC) and RSA-OAEP.
* Combines classical and post-quantum key encapsulation for maximum security.
*
* @param rsaPublicKey - RSA-4096 public key (classical)
* @param kyberPublicKey - Kyber public key (post-quantum)
* @param kyberLevel - Kyber level (default: Kyber768)
* @returns Shared secret and ciphertexts for both KEM schemes
*/
hybridEncapsulate(
rsaPublicKey: CryptoKey,
kyberPublicKey: Uint8Array,
kyberLevel?: string
): Promise<{
sharedSecret: Uint8Array;
kyberCiphertext: Uint8Array;
rsaWrappedSharedSecret: Uint8Array;
}>;
/**
* Hybrid decapsulation: Recover shared secret using both Kyber and RSA private keys.
* Falls back to Kyber alone if RSA decryption fails (provides forward secrecy).
*
* @param kyberCiphertext - From hybridEncapsulate
* @param rsaWrappedSharedSecret - From hybridEncapsulate
* @param rsaPrivateKey - RSA-4096 private key
* @param kyberPrivateKey - Kyber private key
* @param kyberLevel - Kyber level (default: Kyber768)
* @returns The hybrid shared secret
*/
hybridDecapsulate(
kyberCiphertext: Uint8Array,
rsaWrappedSharedSecret: Uint8Array,
rsaPrivateKey: CryptoKey,
kyberPrivateKey: Uint8Array,
kyberLevel?: string
): Promise<Uint8Array>;
// ─────────────────────── Key Serialization ───────────────────────
kyberPublicKeyToBase64(publicKey: Uint8Array): string;
kyberPublicKeyFromBase64(b64: string): Uint8Array;
kyberPrivateKeyToBase64(privateKey: Uint8Array): string;
kyberPrivateKeyFromBase64(b64: string): Uint8Array;
dilithiumPublicKeyToBase64(publicKey: Uint8Array): string;
dilithiumPublicKeyFromBase64(b64: string): Uint8Array;
dilithiumPrivateKeyToBase64(privateKey: Uint8Array): string;
dilithiumPrivateKeyFromBase64(b64: string): Uint8Array;
}
// src/TimingSafeHelper.d.ts

@@ -1070,2 +41,2 @@

export { TimingSafeHelper, WebCrypt, WebCryptAsym, WebCryptPQC };
export { TimingSafeHelper };
+116
-80
dist/WebCrypt.cjs

@@ -25,2 +25,35 @@ var __defProp = Object.defineProperty;

module.exports = __toCommonJS(WebCrypt_exports);
// src/_base64.js
var CHUNK_SIZE = 32768;
function arrayBufferToBase64(buffer) {
const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
let binary = "";
for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
binary += String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK_SIZE));
}
return btoa(binary);
}
function base64ToArrayBuffer(base64) {
if (typeof base64 !== "string") {
throw new TypeError("Base64 string expected");
}
let padded = base64.trim();
const mod = padded.length % 4;
if (mod > 0) {
padded += "=".repeat(4 - mod);
}
const bytes = Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
return bytes.buffer;
}
// src/_crypto.js
function getCrypto() {
if (typeof globalThis !== "undefined" && globalThis.crypto && globalThis.crypto.subtle) {
return globalThis.crypto;
}
throw new Error("Web Crypto API (crypto.subtle) is not available in this environment");
}
// src/WebCrypt.js
var WebCrypt = class _WebCrypt {

@@ -124,16 +157,3 @@ // AES-256-GCM: Provides 128-bit effective security against Grover's quantum algorithm

_getCrypto() {
if (typeof globalThis !== "undefined" && globalThis.crypto && globalThis.crypto.subtle) {
return globalThis.crypto;
}
if (typeof require !== "undefined") {
try {
const { webcrypto } = require("crypto");
if (webcrypto && webcrypto.subtle) return webcrypto;
} catch (e) {
}
}
if (typeof globalThis !== "undefined" && globalThis.crypto && globalThis.crypto.subtle) {
return globalThis.crypto;
}
throw new Error("Web Crypto API (crypto.subtle) is not available in this environment");
return getCrypto();
}

@@ -144,3 +164,3 @@ // Derives AES key using PBKDF2: High iterations ensure quantum-resistant key stretching

async _deriveKey(password, salt) {
const crypto2 = this._getCrypto();
const crypto = this._getCrypto();
const cacheKey = `${password}:${btoa(String.fromCharCode(...salt))}`;

@@ -153,3 +173,3 @@ if (this.keyCache.has(cacheKey)) {

const enc = new TextEncoder();
const keyMaterial = await crypto2.subtle.importKey(
const keyMaterial = await crypto.subtle.importKey(
"raw",

@@ -161,3 +181,3 @@ enc.encode(password),

);
const key = await crypto2.subtle.deriveKey(
const key = await crypto.subtle.deriveKey(
{

@@ -198,18 +218,6 @@ name: "PBKDF2",

_arrayBufferToBase64(buffer) {
const bytes = new Uint8Array(buffer);
const CHUNK_SIZE = 32768;
let binary = "";
for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
binary += String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK_SIZE));
}
return btoa(binary);
return arrayBufferToBase64(buffer);
}
_base64ToArrayBuffer(base64) {
let padded = base64;
const mod = base64.length % 4;
if (mod > 0) {
padded += "=".repeat(4 - mod);
}
const bytes = Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
return bytes.buffer;
return base64ToArrayBuffer(base64);
}

@@ -226,7 +234,12 @@ // ────────────────────── Text Encryption (now safe for 10 MB+) ──────────────────────

async encryptText(text, password) {
const cryptoInstance = this._getCrypto();
const data = new TextEncoder().encode(text);
const salt = crypto.getRandomValues(new Uint8Array(_WebCrypt.SALT_LENGTH));
const iv = crypto.getRandomValues(new Uint8Array(_WebCrypt.IV_LENGTH));
const salt = cryptoInstance.getRandomValues(new Uint8Array(_WebCrypt.SALT_LENGTH));
const iv = cryptoInstance.getRandomValues(new Uint8Array(_WebCrypt.IV_LENGTH));
const key = await this._deriveKey(password, salt);
const encrypted = await crypto.subtle.encrypt({ name: _WebCrypt.ALGORITHM, iv }, key, data);
const encrypted = await cryptoInstance.subtle.encrypt(
{ name: _WebCrypt.ALGORITHM, iv },
key,
data
);
const result = new Uint8Array(_WebCrypt.SALT_LENGTH + _WebCrypt.IV_LENGTH + encrypted.byteLength);

@@ -250,2 +263,3 @@ result.set(salt, 0);

try {
const cryptoInstance = this._getCrypto();
const combined = new Uint8Array(this._base64ToArrayBuffer(b64));

@@ -262,3 +276,3 @@ if (combined.length > _WebCrypt.MAX_ENCRYPTED_DATA_SIZE) {

const key = await this._deriveKey(password, salt);
const decrypted = await crypto.subtle.decrypt(
const decrypted = await cryptoInstance.subtle.decrypt(
{ name: _WebCrypt.ALGORITHM, iv },

@@ -278,13 +292,7 @@ key,

* Encrypt a File or Blob using streaming (constant memory usage).
* Each chunk is encrypted with a counter-derived IV for security.
* Plaintext is chunked into deterministic 8MB blocks, each encrypted with AES-256-GCM
* and a counter-derived IV.
*
* @param {File|Blob} fileOrBlob - File or Blob to encrypt
* @param {string} password - Encryption password
* @returns {Promise<{blob: Blob, filename: string}>} Encrypted blob and suggested filename
*/
/**
* Encrypt a File or Blob using password-derived key.
*
* @param {File|Blob} fileOrBlob - File or Blob to encrypt
* @param {string} password - Encryption password
* @param {Object} [options={}] - Optional options ({ parallelChunks: 1 })

@@ -295,4 +303,5 @@ * @returns {Promise<{blob: Blob, filename: string}>} Encrypted blob and suggested filename

const parallelChunks = options.parallelChunks || 1;
const salt = crypto.getRandomValues(new Uint8Array(_WebCrypt.SALT_LENGTH));
const baseIv = crypto.getRandomValues(new Uint8Array(_WebCrypt.IV_LENGTH));
const cryptoInstance = this._getCrypto();
const salt = cryptoInstance.getRandomValues(new Uint8Array(_WebCrypt.SALT_LENGTH));
const baseIv = cryptoInstance.getRandomValues(new Uint8Array(_WebCrypt.IV_LENGTH));
const key = await this._deriveKey(password, salt);

@@ -303,16 +312,39 @@ const chunks = [];

let pendingPromises = [];
while (true) {
const { done, value } = await reader.read();
if (done) break;
let buffer = new Uint8Array(0);
const encryptChunk = (plaintextChunk) => {
const iv = new Uint8Array(_WebCrypt.IV_LENGTH);
iv.set(baseIv);
new DataView(iv.buffer).setUint32(_WebCrypt.IV_LENGTH - 4, counter++, true);
const promise = crypto.subtle.encrypt({ name: _WebCrypt.ALGORITHM, iv }, key, value);
const promise = cryptoInstance.subtle.encrypt(
{ name: _WebCrypt.ALGORITHM, iv },
key,
plaintextChunk
);
pendingPromises.push(promise);
if (pendingPromises.length >= parallelChunks) {
const resolved = await Promise.all(pendingPromises);
chunks.push(...resolved);
pendingPromises = [];
};
while (true) {
const { done, value } = await reader.read();
if (done) break;
if (buffer.length === 0) {
buffer = value instanceof Uint8Array ? value : new Uint8Array(value);
} else {
const newBuf = new Uint8Array(buffer.length + value.byteLength);
newBuf.set(buffer, 0);
newBuf.set(value instanceof Uint8Array ? value : new Uint8Array(value), buffer.length);
buffer = newBuf;
}
while (buffer.length >= _WebCrypt.CHUNK_SIZE) {
const chunk = buffer.subarray(0, _WebCrypt.CHUNK_SIZE);
encryptChunk(chunk);
buffer = buffer.subarray(_WebCrypt.CHUNK_SIZE);
if (pendingPromises.length >= parallelChunks) {
const resolved = await Promise.all(pendingPromises);
chunks.push(...resolved);
pendingPromises = [];
}
}
}
if (buffer.length > 0 || counter === 0) {
encryptChunk(buffer);
}
if (pendingPromises.length > 0) {

@@ -337,6 +369,7 @@ const resolved = await Promise.all(pendingPromises);

* @returns {Promise<{blob: Blob, filename: string}>} Decrypted blob and original filename
* @throws {Error} If password is wrong, file is corrupted, or file exceeds 10 MB
* @throws {Error} If password is wrong, file is corrupted, or file exceeds 1 GB
*/
async decryptFile(fileOrBlob, password, options = {}) {
const parallelChunks = options.parallelChunks || 1;
const cryptoInstance = this._getCrypto();
const fileSize = fileOrBlob.size || fileOrBlob.blob && fileOrBlob.blob.size;

@@ -360,9 +393,10 @@ if (fileSize && fileSize > _WebCrypt.MAX_ENCRYPTED_DATA_SIZE) {

let pendingPromises = [];
const CIPHERTEXT_CHUNK_SIZE = _WebCrypt.CHUNK_SIZE + 16;
while (offset < ciphertext.byteLength) {
const size = Math.min(_WebCrypt.CHUNK_SIZE, ciphertext.byteLength - offset);
const chunk = ciphertext.slice(offset, offset + size);
const size = Math.min(CIPHERTEXT_CHUNK_SIZE, ciphertext.byteLength - offset);
const chunk = ciphertext.subarray(offset, offset + size);
const iv = new Uint8Array(_WebCrypt.IV_LENGTH);
iv.set(baseIv);
new DataView(iv.buffer).setUint32(_WebCrypt.IV_LENGTH - 4, counter++, true);
const promise = crypto.subtle.decrypt({ name: _WebCrypt.ALGORITHM, iv }, key, chunk);
const promise = cryptoInstance.subtle.decrypt({ name: _WebCrypt.ALGORITHM, iv }, key, chunk);
pendingPromises.push(promise);

@@ -391,6 +425,7 @@ offset += size;

async createEncryptTransform(password) {
const cryptoInstance = this._getCrypto();
const key = await this._deriveKey(password, _WebCrypt.WEBRTC_SALT);
return async (frame, controller) => {
const iv = crypto.getRandomValues(new Uint8Array(_WebCrypt.IV_LENGTH));
const encrypted = await crypto.subtle.encrypt(
const iv = cryptoInstance.getRandomValues(new Uint8Array(_WebCrypt.IV_LENGTH));
const encrypted = await cryptoInstance.subtle.encrypt(
{ name: _WebCrypt.ALGORITHM, iv },

@@ -415,2 +450,3 @@ key,

async createDecryptTransform(password) {
const cryptoInstance = this._getCrypto();
const key = await this._deriveKey(password, _WebCrypt.WEBRTC_SALT);

@@ -422,3 +458,3 @@ return async (frame, controller) => {

try {
const decrypted = await crypto.subtle.decrypt(
const decrypted = await cryptoInstance.subtle.decrypt(
{ name: _WebCrypt.ALGORITHM, iv },

@@ -443,3 +479,3 @@ key,

async generateHmacKey(password, hash = "SHA-256", customSalt = null) {
const crypto2 = this._getCrypto();
const crypto = this._getCrypto();
let keyMaterial;

@@ -454,3 +490,3 @@ if (password) {

};
const baseKey = await crypto2.subtle.importKey(
const baseKey = await crypto.subtle.importKey(
"raw",

@@ -462,7 +498,7 @@ new TextEncoder().encode(password),

);
keyMaterial = await crypto2.subtle.deriveBits(pbkdf2Params, baseKey, 256);
keyMaterial = await crypto.subtle.deriveBits(pbkdf2Params, baseKey, 256);
} else {
keyMaterial = crypto2.getRandomValues(new Uint8Array(32));
keyMaterial = crypto.getRandomValues(new Uint8Array(32));
}
return crypto2.subtle.importKey(
return crypto.subtle.importKey(
"raw",

@@ -483,5 +519,5 @@ keyMaterial,

async computeHmac(data, key) {
const crypto2 = this._getCrypto();
const crypto = this._getCrypto();
const dataBuffer = typeof data === "string" ? new TextEncoder().encode(data) : data;
const signature = await crypto2.subtle.sign("HMAC", key, dataBuffer);
const signature = await crypto.subtle.sign("HMAC", key, dataBuffer);
return this._arrayBufferToBase64(signature);

@@ -497,6 +533,6 @@ }

async verifyHmac(data, hmac, key) {
const crypto2 = this._getCrypto();
const crypto = this._getCrypto();
const dataBuffer = typeof data === "string" ? new TextEncoder().encode(data) : data;
const signatureBuffer = new Uint8Array(this._base64ToArrayBuffer(hmac));
return crypto2.subtle.verify("HMAC", key, signatureBuffer, dataBuffer);
return crypto.subtle.verify("HMAC", key, signatureBuffer, dataBuffer);
}

@@ -513,3 +549,3 @@ // ════════════════════════════ Post-Quantum HMAC (SHA-3) ════════════════════════════

async generateHmacKeySHA3(password, hash = "SHA3-256", customSalt = null, iterations = 1e4) {
const crypto2 = this._getCrypto();
const crypto = this._getCrypto();
let keyMaterial;

@@ -527,5 +563,5 @@ if (password) {

try {
material = new Uint8Array(await crypto2.subtle.digest(hash, hashInput));
material = new Uint8Array(await crypto.subtle.digest(hash, hashInput));
} catch (e) {
material = new Uint8Array(await crypto2.subtle.digest("SHA-256", hashInput));
material = new Uint8Array(await crypto.subtle.digest("SHA-256", hashInput));
}

@@ -535,3 +571,3 @@ }

} else {
keyMaterial = crypto2.getRandomValues(new Uint8Array(32));
keyMaterial = crypto.getRandomValues(new Uint8Array(32));
}

@@ -542,3 +578,3 @@ let hmacHash = hash;

}
return crypto2.subtle.importKey("raw", keyMaterial, { name: "HMAC", hash: hmacHash }, false, [
return crypto.subtle.importKey("raw", keyMaterial, { name: "HMAC", hash: hmacHash }, false, [
"sign",

@@ -555,5 +591,5 @@ "verify"

async computeHmacSHA3(data, key) {
const crypto2 = this._getCrypto();
const crypto = this._getCrypto();
const dataBuffer = typeof data === "string" ? new TextEncoder().encode(data) : data;
const signature = await crypto2.subtle.sign("HMAC", key, dataBuffer);
const signature = await crypto.subtle.sign("HMAC", key, dataBuffer);
return this._arrayBufferToBase64(signature);

@@ -569,6 +605,6 @@ }

async verifyHmacSHA3(data, hmac, key) {
const crypto2 = this._getCrypto();
const crypto = this._getCrypto();
const dataBuffer = typeof data === "string" ? new TextEncoder().encode(data) : data;
const signatureBuffer = Uint8Array.from(atob(hmac), (c) => c.charCodeAt(0));
return crypto2.subtle.verify("HMAC", key, signatureBuffer, dataBuffer);
return crypto.subtle.verify("HMAC", key, signatureBuffer, dataBuffer);
}

@@ -612,4 +648,4 @@ // ────────────────────── Human-Friendly Data Operations ──────────────────────

* Useful for generating strong unique keys for encryption passes.
* @param {number} length - Length of the generated password (default: 32)
* @returns {string} Base64-encoded random password
* @param {number} length - Length of the generated password in bytes (default: 32)
* @returns {string} Hex-encoded random password string
*/

@@ -616,0 +652,0 @@ generateRandomPassword(length = 32) {

+114
-80
dist/WebCrypt.js

@@ -8,2 +8,33 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {

// src/_base64.js
var CHUNK_SIZE = 32768;
function arrayBufferToBase64(buffer) {
const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
let binary = "";
for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
binary += String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK_SIZE));
}
return btoa(binary);
}
function base64ToArrayBuffer(base64) {
if (typeof base64 !== "string") {
throw new TypeError("Base64 string expected");
}
let padded = base64.trim();
const mod = padded.length % 4;
if (mod > 0) {
padded += "=".repeat(4 - mod);
}
const bytes = Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
return bytes.buffer;
}
// src/_crypto.js
function getCrypto() {
if (typeof globalThis !== "undefined" && globalThis.crypto && globalThis.crypto.subtle) {
return globalThis.crypto;
}
throw new Error("Web Crypto API (crypto.subtle) is not available in this environment");
}
// src/WebCrypt.js

@@ -108,16 +139,3 @@ var WebCrypt = class _WebCrypt {

_getCrypto() {
if (typeof globalThis !== "undefined" && globalThis.crypto && globalThis.crypto.subtle) {
return globalThis.crypto;
}
if (typeof __require !== "undefined") {
try {
const { webcrypto } = __require("crypto");
if (webcrypto && webcrypto.subtle) return webcrypto;
} catch (e) {
}
}
if (typeof globalThis !== "undefined" && globalThis.crypto && globalThis.crypto.subtle) {
return globalThis.crypto;
}
throw new Error("Web Crypto API (crypto.subtle) is not available in this environment");
return getCrypto();
}

@@ -128,3 +146,3 @@ // Derives AES key using PBKDF2: High iterations ensure quantum-resistant key stretching

async _deriveKey(password, salt) {
const crypto2 = this._getCrypto();
const crypto = this._getCrypto();
const cacheKey = `${password}:${btoa(String.fromCharCode(...salt))}`;

@@ -137,3 +155,3 @@ if (this.keyCache.has(cacheKey)) {

const enc = new TextEncoder();
const keyMaterial = await crypto2.subtle.importKey(
const keyMaterial = await crypto.subtle.importKey(
"raw",

@@ -145,3 +163,3 @@ enc.encode(password),

);
const key = await crypto2.subtle.deriveKey(
const key = await crypto.subtle.deriveKey(
{

@@ -182,18 +200,6 @@ name: "PBKDF2",

_arrayBufferToBase64(buffer) {
const bytes = new Uint8Array(buffer);
const CHUNK_SIZE = 32768;
let binary = "";
for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
binary += String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK_SIZE));
}
return btoa(binary);
return arrayBufferToBase64(buffer);
}
_base64ToArrayBuffer(base64) {
let padded = base64;
const mod = base64.length % 4;
if (mod > 0) {
padded += "=".repeat(4 - mod);
}
const bytes = Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
return bytes.buffer;
return base64ToArrayBuffer(base64);
}

@@ -210,7 +216,12 @@ // ────────────────────── Text Encryption (now safe for 10 MB+) ──────────────────────

async encryptText(text, password) {
const cryptoInstance = this._getCrypto();
const data = new TextEncoder().encode(text);
const salt = crypto.getRandomValues(new Uint8Array(_WebCrypt.SALT_LENGTH));
const iv = crypto.getRandomValues(new Uint8Array(_WebCrypt.IV_LENGTH));
const salt = cryptoInstance.getRandomValues(new Uint8Array(_WebCrypt.SALT_LENGTH));
const iv = cryptoInstance.getRandomValues(new Uint8Array(_WebCrypt.IV_LENGTH));
const key = await this._deriveKey(password, salt);
const encrypted = await crypto.subtle.encrypt({ name: _WebCrypt.ALGORITHM, iv }, key, data);
const encrypted = await cryptoInstance.subtle.encrypt(
{ name: _WebCrypt.ALGORITHM, iv },
key,
data
);
const result = new Uint8Array(_WebCrypt.SALT_LENGTH + _WebCrypt.IV_LENGTH + encrypted.byteLength);

@@ -234,2 +245,3 @@ result.set(salt, 0);

try {
const cryptoInstance = this._getCrypto();
const combined = new Uint8Array(this._base64ToArrayBuffer(b64));

@@ -246,3 +258,3 @@ if (combined.length > _WebCrypt.MAX_ENCRYPTED_DATA_SIZE) {

const key = await this._deriveKey(password, salt);
const decrypted = await crypto.subtle.decrypt(
const decrypted = await cryptoInstance.subtle.decrypt(
{ name: _WebCrypt.ALGORITHM, iv },

@@ -262,13 +274,7 @@ key,

* Encrypt a File or Blob using streaming (constant memory usage).
* Each chunk is encrypted with a counter-derived IV for security.
* Plaintext is chunked into deterministic 8MB blocks, each encrypted with AES-256-GCM
* and a counter-derived IV.
*
* @param {File|Blob} fileOrBlob - File or Blob to encrypt
* @param {string} password - Encryption password
* @returns {Promise<{blob: Blob, filename: string}>} Encrypted blob and suggested filename
*/
/**
* Encrypt a File or Blob using password-derived key.
*
* @param {File|Blob} fileOrBlob - File or Blob to encrypt
* @param {string} password - Encryption password
* @param {Object} [options={}] - Optional options ({ parallelChunks: 1 })

@@ -279,4 +285,5 @@ * @returns {Promise<{blob: Blob, filename: string}>} Encrypted blob and suggested filename

const parallelChunks = options.parallelChunks || 1;
const salt = crypto.getRandomValues(new Uint8Array(_WebCrypt.SALT_LENGTH));
const baseIv = crypto.getRandomValues(new Uint8Array(_WebCrypt.IV_LENGTH));
const cryptoInstance = this._getCrypto();
const salt = cryptoInstance.getRandomValues(new Uint8Array(_WebCrypt.SALT_LENGTH));
const baseIv = cryptoInstance.getRandomValues(new Uint8Array(_WebCrypt.IV_LENGTH));
const key = await this._deriveKey(password, salt);

@@ -287,16 +294,39 @@ const chunks = [];

let pendingPromises = [];
while (true) {
const { done, value } = await reader.read();
if (done) break;
let buffer = new Uint8Array(0);
const encryptChunk = (plaintextChunk) => {
const iv = new Uint8Array(_WebCrypt.IV_LENGTH);
iv.set(baseIv);
new DataView(iv.buffer).setUint32(_WebCrypt.IV_LENGTH - 4, counter++, true);
const promise = crypto.subtle.encrypt({ name: _WebCrypt.ALGORITHM, iv }, key, value);
const promise = cryptoInstance.subtle.encrypt(
{ name: _WebCrypt.ALGORITHM, iv },
key,
plaintextChunk
);
pendingPromises.push(promise);
if (pendingPromises.length >= parallelChunks) {
const resolved = await Promise.all(pendingPromises);
chunks.push(...resolved);
pendingPromises = [];
};
while (true) {
const { done, value } = await reader.read();
if (done) break;
if (buffer.length === 0) {
buffer = value instanceof Uint8Array ? value : new Uint8Array(value);
} else {
const newBuf = new Uint8Array(buffer.length + value.byteLength);
newBuf.set(buffer, 0);
newBuf.set(value instanceof Uint8Array ? value : new Uint8Array(value), buffer.length);
buffer = newBuf;
}
while (buffer.length >= _WebCrypt.CHUNK_SIZE) {
const chunk = buffer.subarray(0, _WebCrypt.CHUNK_SIZE);
encryptChunk(chunk);
buffer = buffer.subarray(_WebCrypt.CHUNK_SIZE);
if (pendingPromises.length >= parallelChunks) {
const resolved = await Promise.all(pendingPromises);
chunks.push(...resolved);
pendingPromises = [];
}
}
}
if (buffer.length > 0 || counter === 0) {
encryptChunk(buffer);
}
if (pendingPromises.length > 0) {

@@ -321,6 +351,7 @@ const resolved = await Promise.all(pendingPromises);

* @returns {Promise<{blob: Blob, filename: string}>} Decrypted blob and original filename
* @throws {Error} If password is wrong, file is corrupted, or file exceeds 10 MB
* @throws {Error} If password is wrong, file is corrupted, or file exceeds 1 GB
*/
async decryptFile(fileOrBlob, password, options = {}) {
const parallelChunks = options.parallelChunks || 1;
const cryptoInstance = this._getCrypto();
const fileSize = fileOrBlob.size || fileOrBlob.blob && fileOrBlob.blob.size;

@@ -344,9 +375,10 @@ if (fileSize && fileSize > _WebCrypt.MAX_ENCRYPTED_DATA_SIZE) {

let pendingPromises = [];
const CIPHERTEXT_CHUNK_SIZE = _WebCrypt.CHUNK_SIZE + 16;
while (offset < ciphertext.byteLength) {
const size = Math.min(_WebCrypt.CHUNK_SIZE, ciphertext.byteLength - offset);
const chunk = ciphertext.slice(offset, offset + size);
const size = Math.min(CIPHERTEXT_CHUNK_SIZE, ciphertext.byteLength - offset);
const chunk = ciphertext.subarray(offset, offset + size);
const iv = new Uint8Array(_WebCrypt.IV_LENGTH);
iv.set(baseIv);
new DataView(iv.buffer).setUint32(_WebCrypt.IV_LENGTH - 4, counter++, true);
const promise = crypto.subtle.decrypt({ name: _WebCrypt.ALGORITHM, iv }, key, chunk);
const promise = cryptoInstance.subtle.decrypt({ name: _WebCrypt.ALGORITHM, iv }, key, chunk);
pendingPromises.push(promise);

@@ -375,6 +407,7 @@ offset += size;

async createEncryptTransform(password) {
const cryptoInstance = this._getCrypto();
const key = await this._deriveKey(password, _WebCrypt.WEBRTC_SALT);
return async (frame, controller) => {
const iv = crypto.getRandomValues(new Uint8Array(_WebCrypt.IV_LENGTH));
const encrypted = await crypto.subtle.encrypt(
const iv = cryptoInstance.getRandomValues(new Uint8Array(_WebCrypt.IV_LENGTH));
const encrypted = await cryptoInstance.subtle.encrypt(
{ name: _WebCrypt.ALGORITHM, iv },

@@ -399,2 +432,3 @@ key,

async createDecryptTransform(password) {
const cryptoInstance = this._getCrypto();
const key = await this._deriveKey(password, _WebCrypt.WEBRTC_SALT);

@@ -406,3 +440,3 @@ return async (frame, controller) => {

try {
const decrypted = await crypto.subtle.decrypt(
const decrypted = await cryptoInstance.subtle.decrypt(
{ name: _WebCrypt.ALGORITHM, iv },

@@ -427,3 +461,3 @@ key,

async generateHmacKey(password, hash = "SHA-256", customSalt = null) {
const crypto2 = this._getCrypto();
const crypto = this._getCrypto();
let keyMaterial;

@@ -438,3 +472,3 @@ if (password) {

};
const baseKey = await crypto2.subtle.importKey(
const baseKey = await crypto.subtle.importKey(
"raw",

@@ -446,7 +480,7 @@ new TextEncoder().encode(password),

);
keyMaterial = await crypto2.subtle.deriveBits(pbkdf2Params, baseKey, 256);
keyMaterial = await crypto.subtle.deriveBits(pbkdf2Params, baseKey, 256);
} else {
keyMaterial = crypto2.getRandomValues(new Uint8Array(32));
keyMaterial = crypto.getRandomValues(new Uint8Array(32));
}
return crypto2.subtle.importKey(
return crypto.subtle.importKey(
"raw",

@@ -467,5 +501,5 @@ keyMaterial,

async computeHmac(data, key) {
const crypto2 = this._getCrypto();
const crypto = this._getCrypto();
const dataBuffer = typeof data === "string" ? new TextEncoder().encode(data) : data;
const signature = await crypto2.subtle.sign("HMAC", key, dataBuffer);
const signature = await crypto.subtle.sign("HMAC", key, dataBuffer);
return this._arrayBufferToBase64(signature);

@@ -481,6 +515,6 @@ }

async verifyHmac(data, hmac, key) {
const crypto2 = this._getCrypto();
const crypto = this._getCrypto();
const dataBuffer = typeof data === "string" ? new TextEncoder().encode(data) : data;
const signatureBuffer = new Uint8Array(this._base64ToArrayBuffer(hmac));
return crypto2.subtle.verify("HMAC", key, signatureBuffer, dataBuffer);
return crypto.subtle.verify("HMAC", key, signatureBuffer, dataBuffer);
}

@@ -497,3 +531,3 @@ // ════════════════════════════ Post-Quantum HMAC (SHA-3) ════════════════════════════

async generateHmacKeySHA3(password, hash = "SHA3-256", customSalt = null, iterations = 1e4) {
const crypto2 = this._getCrypto();
const crypto = this._getCrypto();
let keyMaterial;

@@ -511,5 +545,5 @@ if (password) {

try {
material = new Uint8Array(await crypto2.subtle.digest(hash, hashInput));
material = new Uint8Array(await crypto.subtle.digest(hash, hashInput));
} catch (e) {
material = new Uint8Array(await crypto2.subtle.digest("SHA-256", hashInput));
material = new Uint8Array(await crypto.subtle.digest("SHA-256", hashInput));
}

@@ -519,3 +553,3 @@ }

} else {
keyMaterial = crypto2.getRandomValues(new Uint8Array(32));
keyMaterial = crypto.getRandomValues(new Uint8Array(32));
}

@@ -526,3 +560,3 @@ let hmacHash = hash;

}
return crypto2.subtle.importKey("raw", keyMaterial, { name: "HMAC", hash: hmacHash }, false, [
return crypto.subtle.importKey("raw", keyMaterial, { name: "HMAC", hash: hmacHash }, false, [
"sign",

@@ -539,5 +573,5 @@ "verify"

async computeHmacSHA3(data, key) {
const crypto2 = this._getCrypto();
const crypto = this._getCrypto();
const dataBuffer = typeof data === "string" ? new TextEncoder().encode(data) : data;
const signature = await crypto2.subtle.sign("HMAC", key, dataBuffer);
const signature = await crypto.subtle.sign("HMAC", key, dataBuffer);
return this._arrayBufferToBase64(signature);

@@ -553,6 +587,6 @@ }

async verifyHmacSHA3(data, hmac, key) {
const crypto2 = this._getCrypto();
const crypto = this._getCrypto();
const dataBuffer = typeof data === "string" ? new TextEncoder().encode(data) : data;
const signatureBuffer = Uint8Array.from(atob(hmac), (c) => c.charCodeAt(0));
return crypto2.subtle.verify("HMAC", key, signatureBuffer, dataBuffer);
return crypto.subtle.verify("HMAC", key, signatureBuffer, dataBuffer);
}

@@ -596,4 +630,4 @@ // ────────────────────── Human-Friendly Data Operations ──────────────────────

* Useful for generating strong unique keys for encryption passes.
* @param {number} length - Length of the generated password (default: 32)
* @returns {string} Base64-encoded random password
* @param {number} length - Length of the generated password in bytes (default: 32)
* @returns {string} Hex-encoded random password string
*/

@@ -600,0 +634,0 @@ generateRandomPassword(length = 32) {

+110
-66
dist/WebCryptPQC.cjs

@@ -26,2 +26,36 @@ var __defProp = Object.defineProperty;

module.exports = __toCommonJS(WebCryptPQC_exports);
// src/_base64.js
var CHUNK_SIZE = 32768;
function arrayBufferToBase64(buffer) {
const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
let binary = "";
for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
binary += String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK_SIZE));
}
return btoa(binary);
}
function base64ToArrayBuffer(base64) {
if (typeof base64 !== "string") {
throw new TypeError("Base64 string expected");
}
let padded = base64.trim();
const mod = padded.length % 4;
if (mod > 0) {
padded += "=".repeat(4 - mod);
}
const bytes = Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
return bytes.buffer;
}
// src/_crypto.js
function getCrypto() {
if (typeof globalThis !== "undefined" && globalThis.crypto && globalThis.crypto.subtle) {
return globalThis.crypto;
}
throw new Error("Web Crypto API (crypto.subtle) is not available in this environment");
}
// src/WebCryptPQC.js
var warnedPQCStub = false;
var WebCryptPQC = class _WebCryptPQC {

@@ -128,21 +162,9 @@ static WARNING = "\u26A0\uFE0F CRITICAL: WebCryptPQC is PLACEHOLDER/STUB implementation. Kyber and Dilithium are NOT real PQC - they use SHA-3 hashing stubs. Not suitable for production security. Integrate liboqs-js or wait for official implementation.";

this._crypto = this._getCrypto();
if (typeof console !== "undefined" && console.warn) {
if (!warnedPQCStub && typeof console !== "undefined" && console.warn) {
console.warn(_WebCryptPQC.WARNING);
warnedPQCStub = true;
}
}
_getCrypto() {
if (typeof globalThis !== "undefined" && globalThis.crypto && globalThis.crypto.subtle) {
return globalThis.crypto;
}
if (typeof require !== "undefined") {
try {
const { webcrypto } = require("crypto");
if (webcrypto && webcrypto.subtle) return webcrypto;
} catch (e) {
}
}
if (typeof globalThis !== "undefined" && globalThis.crypto && globalThis.crypto.subtle) {
return globalThis.crypto;
}
throw new Error("Web Crypto API (crypto.subtle) is not available in this environment");
return getCrypto();
}

@@ -181,9 +203,12 @@ // ═══════════════════════════ Kyber KEM (Key Encapsulation) ═══════════════════════════

}
const nonce = this._crypto.getRandomValues(new Uint8Array(32));
const hashInput = new Uint8Array(kyberPublicKey.byteLength + 32);
hashInput.set(kyberPublicKey);
hashInput.set(this._crypto.getRandomValues(new Uint8Array(32)), kyberPublicKey.byteLength);
hashInput.set(nonce, kyberPublicKey.byteLength);
const digest = await this._sha3Hash(hashInput, 256);
const sharedSecret = digest.slice(0, params.sharedSecretSize);
const ciphertext = new Uint8Array(params.ciphertextSize);
const sharedSecret = digest.slice(0, params.sharedSecretSize);
ciphertext.set(digest.slice(0, params.ciphertextSize));
ciphertext.set(nonce, 0);
const ctHash = await this._sha3Hash(hashInput, 512);
ciphertext.set(ctHash.slice(0, Math.min(params.ciphertextSize - 32, ctHash.byteLength)), 32);
return { ciphertext, sharedSecret };

@@ -214,5 +239,8 @@ }

}
const hashInput = new Uint8Array(kyberPrivateKey.byteLength + ciphertext.byteLength);
hashInput.set(kyberPrivateKey);
hashInput.set(ciphertext, kyberPrivateKey.byteLength);
const pubKeyOffset = params.privateKeySize - params.publicKeySize;
const pubKey = kyberPrivateKey.slice(pubKeyOffset);
const nonce = ciphertext.slice(0, 32);
const hashInput = new Uint8Array(pubKey.byteLength + 32);
hashInput.set(pubKey);
hashInput.set(nonce, pubKey.byteLength);
const digest = await this._sha3Hash(hashInput, 256);

@@ -318,21 +346,27 @@ return digest.slice(0, params.sharedSecretSize);

* @param {string} kyberLevel - Kyber level (default: Kyber768)
* @returns {Promise<{sharedSecret: Uint8Array, kyberCiphertext: Uint8Array, rsaWrappedSharedSecret: Uint8Array}>}
* @returns {Promise<{sharedSecret: Uint8Array, hybridSecret: Uint8Array, kyberCiphertext: Uint8Array, rsaWrappedSharedSecret: Uint8Array, combinedCiphertext: Object}>}
*/
async hybridEncapsulate(rsaPublicKey, kyberPublicKey, kyberLevel = _WebCryptPQC.KYBER_768) {
const { ciphertext: kyberCiphertext, sharedSecret: kyberSharedSecret } = await this.kyberEncapsulate(kyberPublicKey, kyberLevel);
const rsaSecret = this._crypto.getRandomValues(new Uint8Array(32));
const rsaWrappedSharedSecret = await this._crypto.subtle.encrypt(
{ name: "RSA-OAEP", hash: "SHA-256" },
rsaPublicKey,
kyberSharedSecret
rsaSecret
);
const combinedInput = new Uint8Array(
kyberSharedSecret.byteLength + rsaWrappedSharedSecret.byteLength
);
const combinedInput = new Uint8Array(kyberSharedSecret.byteLength + rsaSecret.byteLength);
combinedInput.set(kyberSharedSecret);
combinedInput.set(new Uint8Array(rsaWrappedSharedSecret), kyberSharedSecret.byteLength);
combinedInput.set(rsaSecret, kyberSharedSecret.byteLength);
const finalSharedSecret = await this._sha3Hash(combinedInput, 256);
const kyberCiphertextBytes = new Uint8Array(kyberCiphertext);
const rsaWrappedBytes = new Uint8Array(rsaWrappedSharedSecret);
return {
sharedSecret: finalSharedSecret,
kyberCiphertext: new Uint8Array(kyberCiphertext),
rsaWrappedSharedSecret: new Uint8Array(rsaWrappedSharedSecret)
hybridSecret: finalSharedSecret,
kyberCiphertext: kyberCiphertextBytes,
rsaWrappedSharedSecret: rsaWrappedBytes,
combinedCiphertext: {
kyberCiphertext: kyberCiphertextBytes,
rsaWrappedSharedSecret: rsaWrappedBytes
}
};

@@ -342,12 +376,31 @@ }

* Hybrid decapsulation: Recover shared secret using both Kyber and RSA private keys.
* Supports both 5-argument positional style or 4-argument combined-object style.
*
* @param {Uint8Array} kyberCiphertext - From hybridEncapsulate
* @param {Uint8Array} rsaWrappedSharedSecret - From hybridEncapsulate
* @param {CryptoKey} rsaPrivateKey - RSA-4096 private key
* @param {Uint8Array} kyberPrivateKey - Kyber private key
* @param {string} kyberLevel - Kyber level (default: Kyber768)
* @param {Uint8Array|Object} kyberCiphertextOrCombined - From hybridEncapsulate
* @param {Uint8Array|CryptoKey} rsaWrappedSharedSecretOrRsaPrivKey - From hybridEncapsulate or RSA private key
* @param {CryptoKey|Uint8Array} rsaPrivateKeyOrKyberPrivKey - RSA private key or Kyber private key
* @param {Uint8Array|string} [kyberPrivateKeyOrLevel] - Kyber private key or Kyber level
* @param {string} [maybeKyberLevel='Kyber768'] - Kyber level (default: Kyber768)
* @returns {Promise<Uint8Array>} The hybrid shared secret
*/
async hybridDecapsulate(kyberCiphertext, rsaWrappedSharedSecret, rsaPrivateKey, kyberPrivateKey, kyberLevel = _WebCryptPQC.KYBER_768) {
async hybridDecapsulate(kyberCiphertextOrCombined, rsaWrappedSharedSecretOrRsaPrivKey, rsaPrivateKeyOrKyberPrivKey, kyberPrivateKeyOrLevel, maybeKyberLevel = _WebCryptPQC.KYBER_768) {
try {
let kyberCiphertext;
let rsaWrappedSharedSecret;
let rsaPrivateKey;
let kyberPrivateKey;
let kyberLevel = _WebCryptPQC.KYBER_768;
if (typeof kyberCiphertextOrCombined === "object" && !(kyberCiphertextOrCombined instanceof Uint8Array)) {
kyberCiphertext = kyberCiphertextOrCombined.kyberCiphertext;
rsaWrappedSharedSecret = kyberCiphertextOrCombined.rsaWrappedSharedSecret;
rsaPrivateKey = rsaWrappedSharedSecretOrRsaPrivKey;
kyberPrivateKey = rsaPrivateKeyOrKyberPrivKey;
kyberLevel = kyberPrivateKeyOrLevel || _WebCryptPQC.KYBER_768;
} else {
kyberCiphertext = kyberCiphertextOrCombined;
rsaWrappedSharedSecret = rsaWrappedSharedSecretOrRsaPrivKey;
rsaPrivateKey = rsaPrivateKeyOrKyberPrivKey;
kyberPrivateKey = kyberPrivateKeyOrLevel;
kyberLevel = maybeKyberLevel || _WebCryptPQC.KYBER_768;
}
const kyberSharedSecret = await this.kyberDecapsulate(

@@ -358,5 +411,5 @@ kyberCiphertext,

);
let rsaSharedSecret;
let rsaSecret;
try {
rsaSharedSecret = await this._crypto.subtle.decrypt(
const decrypted = await this._crypto.subtle.decrypt(
{ name: "RSA-OAEP", hash: "SHA-256" },

@@ -366,16 +419,15 @@ rsaPrivateKey,

);
rsaSecret = new Uint8Array(decrypted);
} catch (e) {
console.warn(
"Hybrid decapsulation: RSA decryption failed, falling back to Kyber shared secret"
);
rsaSharedSecret = kyberSharedSecret;
if (typeof console !== "undefined" && console.warn) {
console.warn(
"Hybrid decapsulation: RSA decryption failed, falling back to Kyber shared secret"
);
}
rsaSecret = kyberSharedSecret;
}
const rsaSecretBytes = !rsaSharedSecret ? kyberSharedSecret : rsaSharedSecret instanceof Uint8Array ? rsaSharedSecret : new Uint8Array(rsaSharedSecret);
const combinedInput = new Uint8Array(
kyberSharedSecret.byteLength + rsaSecretBytes.byteLength
);
const combinedInput = new Uint8Array(kyberSharedSecret.byteLength + rsaSecret.byteLength);
combinedInput.set(kyberSharedSecret);
combinedInput.set(rsaSecretBytes, kyberSharedSecret.byteLength);
const finalSharedSecret = await this._sha3Hash(combinedInput, 256);
return finalSharedSecret;
combinedInput.set(rsaSecret, kyberSharedSecret.byteLength);
return await this._sha3Hash(combinedInput, 256);
} catch (e) {

@@ -385,3 +437,3 @@ throw new Error(`Hybrid decapsulation failed: ${e.message}`);

}
// ═══════════════════════════ SHA-3 Hashing ═══════════════════════════
static _warnedHashes = {};
/**

@@ -402,6 +454,7 @@ * Hash data using SHA-3 (post-quantum secure hash).

const fallbackAlgorithm = bitLength <= 256 ? "SHA-256" : bitLength <= 384 ? "SHA-384" : "SHA-512";
if (typeof console !== "undefined" && console.warn) {
if (!_WebCryptPQC._warnedHashes[bitLength] && typeof console !== "undefined" && console.warn) {
console.warn(
`SHA3-${bitLength} not natively supported by Web Crypto, falling back to ${fallbackAlgorithm}`
);
_WebCryptPQC._warnedHashes[bitLength] = true;
}

@@ -464,3 +517,6 @@ const digest = await this._crypto.subtle.digest(fallbackAlgorithm, data);

const privHash = await this._sha3Hash(hashInput, 512);
privateKey.set(privHash.slice(0, Math.min(params.privateKeySize, privHash.byteLength)));
privateKey.set(
privHash.slice(0, Math.min(params.privateKeySize - params.publicKeySize, privHash.byteLength))
);
privateKey.set(publicKey, params.privateKeySize - params.publicKeySize);
return { publicKey, privateKey };

@@ -485,20 +541,8 @@ }

}
// Chunked block conversion avoids stack overflow and O(N^2) memory churn
// Safe Base64 helpers
_arrayBufferToBase64(buffer) {
const bytes = new Uint8Array(buffer);
const CHUNK_SIZE = 32768;
let binary = "";
for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
binary += String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK_SIZE));
}
return btoa(binary);
return arrayBufferToBase64(buffer);
}
_base64ToArrayBuffer(base64) {
let padded = base64;
const mod = base64.length % 4;
if (mod > 0) {
padded += "=".repeat(4 - mod);
}
const bytes = Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
return bytes.buffer;
return base64ToArrayBuffer(base64);
}

@@ -505,0 +549,0 @@ };

+107
-72
dist/WebCryptPQC.js

@@ -1,9 +0,34 @@

var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
}) : x)(function(x) {
if (typeof require !== "undefined") return require.apply(this, arguments);
throw Error('Dynamic require of "' + x + '" is not supported');
});
// src/_base64.js
var CHUNK_SIZE = 32768;
function arrayBufferToBase64(buffer) {
const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
let binary = "";
for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
binary += String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK_SIZE));
}
return btoa(binary);
}
function base64ToArrayBuffer(base64) {
if (typeof base64 !== "string") {
throw new TypeError("Base64 string expected");
}
let padded = base64.trim();
const mod = padded.length % 4;
if (mod > 0) {
padded += "=".repeat(4 - mod);
}
const bytes = Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
return bytes.buffer;
}
// src/_crypto.js
function getCrypto() {
if (typeof globalThis !== "undefined" && globalThis.crypto && globalThis.crypto.subtle) {
return globalThis.crypto;
}
throw new Error("Web Crypto API (crypto.subtle) is not available in this environment");
}
// src/WebCryptPQC.js
var warnedPQCStub = false;
var WebCryptPQC = class _WebCryptPQC {

@@ -110,21 +135,9 @@ static WARNING = "\u26A0\uFE0F CRITICAL: WebCryptPQC is PLACEHOLDER/STUB implementation. Kyber and Dilithium are NOT real PQC - they use SHA-3 hashing stubs. Not suitable for production security. Integrate liboqs-js or wait for official implementation.";

this._crypto = this._getCrypto();
if (typeof console !== "undefined" && console.warn) {
if (!warnedPQCStub && typeof console !== "undefined" && console.warn) {
console.warn(_WebCryptPQC.WARNING);
warnedPQCStub = true;
}
}
_getCrypto() {
if (typeof globalThis !== "undefined" && globalThis.crypto && globalThis.crypto.subtle) {
return globalThis.crypto;
}
if (typeof __require !== "undefined") {
try {
const { webcrypto } = __require("crypto");
if (webcrypto && webcrypto.subtle) return webcrypto;
} catch (e) {
}
}
if (typeof globalThis !== "undefined" && globalThis.crypto && globalThis.crypto.subtle) {
return globalThis.crypto;
}
throw new Error("Web Crypto API (crypto.subtle) is not available in this environment");
return getCrypto();
}

@@ -163,9 +176,12 @@ // ═══════════════════════════ Kyber KEM (Key Encapsulation) ═══════════════════════════

}
const nonce = this._crypto.getRandomValues(new Uint8Array(32));
const hashInput = new Uint8Array(kyberPublicKey.byteLength + 32);
hashInput.set(kyberPublicKey);
hashInput.set(this._crypto.getRandomValues(new Uint8Array(32)), kyberPublicKey.byteLength);
hashInput.set(nonce, kyberPublicKey.byteLength);
const digest = await this._sha3Hash(hashInput, 256);
const sharedSecret = digest.slice(0, params.sharedSecretSize);
const ciphertext = new Uint8Array(params.ciphertextSize);
const sharedSecret = digest.slice(0, params.sharedSecretSize);
ciphertext.set(digest.slice(0, params.ciphertextSize));
ciphertext.set(nonce, 0);
const ctHash = await this._sha3Hash(hashInput, 512);
ciphertext.set(ctHash.slice(0, Math.min(params.ciphertextSize - 32, ctHash.byteLength)), 32);
return { ciphertext, sharedSecret };

@@ -196,5 +212,8 @@ }

}
const hashInput = new Uint8Array(kyberPrivateKey.byteLength + ciphertext.byteLength);
hashInput.set(kyberPrivateKey);
hashInput.set(ciphertext, kyberPrivateKey.byteLength);
const pubKeyOffset = params.privateKeySize - params.publicKeySize;
const pubKey = kyberPrivateKey.slice(pubKeyOffset);
const nonce = ciphertext.slice(0, 32);
const hashInput = new Uint8Array(pubKey.byteLength + 32);
hashInput.set(pubKey);
hashInput.set(nonce, pubKey.byteLength);
const digest = await this._sha3Hash(hashInput, 256);

@@ -300,21 +319,27 @@ return digest.slice(0, params.sharedSecretSize);

* @param {string} kyberLevel - Kyber level (default: Kyber768)
* @returns {Promise<{sharedSecret: Uint8Array, kyberCiphertext: Uint8Array, rsaWrappedSharedSecret: Uint8Array}>}
* @returns {Promise<{sharedSecret: Uint8Array, hybridSecret: Uint8Array, kyberCiphertext: Uint8Array, rsaWrappedSharedSecret: Uint8Array, combinedCiphertext: Object}>}
*/
async hybridEncapsulate(rsaPublicKey, kyberPublicKey, kyberLevel = _WebCryptPQC.KYBER_768) {
const { ciphertext: kyberCiphertext, sharedSecret: kyberSharedSecret } = await this.kyberEncapsulate(kyberPublicKey, kyberLevel);
const rsaSecret = this._crypto.getRandomValues(new Uint8Array(32));
const rsaWrappedSharedSecret = await this._crypto.subtle.encrypt(
{ name: "RSA-OAEP", hash: "SHA-256" },
rsaPublicKey,
kyberSharedSecret
rsaSecret
);
const combinedInput = new Uint8Array(
kyberSharedSecret.byteLength + rsaWrappedSharedSecret.byteLength
);
const combinedInput = new Uint8Array(kyberSharedSecret.byteLength + rsaSecret.byteLength);
combinedInput.set(kyberSharedSecret);
combinedInput.set(new Uint8Array(rsaWrappedSharedSecret), kyberSharedSecret.byteLength);
combinedInput.set(rsaSecret, kyberSharedSecret.byteLength);
const finalSharedSecret = await this._sha3Hash(combinedInput, 256);
const kyberCiphertextBytes = new Uint8Array(kyberCiphertext);
const rsaWrappedBytes = new Uint8Array(rsaWrappedSharedSecret);
return {
sharedSecret: finalSharedSecret,
kyberCiphertext: new Uint8Array(kyberCiphertext),
rsaWrappedSharedSecret: new Uint8Array(rsaWrappedSharedSecret)
hybridSecret: finalSharedSecret,
kyberCiphertext: kyberCiphertextBytes,
rsaWrappedSharedSecret: rsaWrappedBytes,
combinedCiphertext: {
kyberCiphertext: kyberCiphertextBytes,
rsaWrappedSharedSecret: rsaWrappedBytes
}
};

@@ -324,12 +349,31 @@ }

* Hybrid decapsulation: Recover shared secret using both Kyber and RSA private keys.
* Supports both 5-argument positional style or 4-argument combined-object style.
*
* @param {Uint8Array} kyberCiphertext - From hybridEncapsulate
* @param {Uint8Array} rsaWrappedSharedSecret - From hybridEncapsulate
* @param {CryptoKey} rsaPrivateKey - RSA-4096 private key
* @param {Uint8Array} kyberPrivateKey - Kyber private key
* @param {string} kyberLevel - Kyber level (default: Kyber768)
* @param {Uint8Array|Object} kyberCiphertextOrCombined - From hybridEncapsulate
* @param {Uint8Array|CryptoKey} rsaWrappedSharedSecretOrRsaPrivKey - From hybridEncapsulate or RSA private key
* @param {CryptoKey|Uint8Array} rsaPrivateKeyOrKyberPrivKey - RSA private key or Kyber private key
* @param {Uint8Array|string} [kyberPrivateKeyOrLevel] - Kyber private key or Kyber level
* @param {string} [maybeKyberLevel='Kyber768'] - Kyber level (default: Kyber768)
* @returns {Promise<Uint8Array>} The hybrid shared secret
*/
async hybridDecapsulate(kyberCiphertext, rsaWrappedSharedSecret, rsaPrivateKey, kyberPrivateKey, kyberLevel = _WebCryptPQC.KYBER_768) {
async hybridDecapsulate(kyberCiphertextOrCombined, rsaWrappedSharedSecretOrRsaPrivKey, rsaPrivateKeyOrKyberPrivKey, kyberPrivateKeyOrLevel, maybeKyberLevel = _WebCryptPQC.KYBER_768) {
try {
let kyberCiphertext;
let rsaWrappedSharedSecret;
let rsaPrivateKey;
let kyberPrivateKey;
let kyberLevel = _WebCryptPQC.KYBER_768;
if (typeof kyberCiphertextOrCombined === "object" && !(kyberCiphertextOrCombined instanceof Uint8Array)) {
kyberCiphertext = kyberCiphertextOrCombined.kyberCiphertext;
rsaWrappedSharedSecret = kyberCiphertextOrCombined.rsaWrappedSharedSecret;
rsaPrivateKey = rsaWrappedSharedSecretOrRsaPrivKey;
kyberPrivateKey = rsaPrivateKeyOrKyberPrivKey;
kyberLevel = kyberPrivateKeyOrLevel || _WebCryptPQC.KYBER_768;
} else {
kyberCiphertext = kyberCiphertextOrCombined;
rsaWrappedSharedSecret = rsaWrappedSharedSecretOrRsaPrivKey;
rsaPrivateKey = rsaPrivateKeyOrKyberPrivKey;
kyberPrivateKey = kyberPrivateKeyOrLevel;
kyberLevel = maybeKyberLevel || _WebCryptPQC.KYBER_768;
}
const kyberSharedSecret = await this.kyberDecapsulate(

@@ -340,5 +384,5 @@ kyberCiphertext,

);
let rsaSharedSecret;
let rsaSecret;
try {
rsaSharedSecret = await this._crypto.subtle.decrypt(
const decrypted = await this._crypto.subtle.decrypt(
{ name: "RSA-OAEP", hash: "SHA-256" },

@@ -348,16 +392,15 @@ rsaPrivateKey,

);
rsaSecret = new Uint8Array(decrypted);
} catch (e) {
console.warn(
"Hybrid decapsulation: RSA decryption failed, falling back to Kyber shared secret"
);
rsaSharedSecret = kyberSharedSecret;
if (typeof console !== "undefined" && console.warn) {
console.warn(
"Hybrid decapsulation: RSA decryption failed, falling back to Kyber shared secret"
);
}
rsaSecret = kyberSharedSecret;
}
const rsaSecretBytes = !rsaSharedSecret ? kyberSharedSecret : rsaSharedSecret instanceof Uint8Array ? rsaSharedSecret : new Uint8Array(rsaSharedSecret);
const combinedInput = new Uint8Array(
kyberSharedSecret.byteLength + rsaSecretBytes.byteLength
);
const combinedInput = new Uint8Array(kyberSharedSecret.byteLength + rsaSecret.byteLength);
combinedInput.set(kyberSharedSecret);
combinedInput.set(rsaSecretBytes, kyberSharedSecret.byteLength);
const finalSharedSecret = await this._sha3Hash(combinedInput, 256);
return finalSharedSecret;
combinedInput.set(rsaSecret, kyberSharedSecret.byteLength);
return await this._sha3Hash(combinedInput, 256);
} catch (e) {

@@ -367,3 +410,3 @@ throw new Error(`Hybrid decapsulation failed: ${e.message}`);

}
// ═══════════════════════════ SHA-3 Hashing ═══════════════════════════
static _warnedHashes = {};
/**

@@ -384,6 +427,7 @@ * Hash data using SHA-3 (post-quantum secure hash).

const fallbackAlgorithm = bitLength <= 256 ? "SHA-256" : bitLength <= 384 ? "SHA-384" : "SHA-512";
if (typeof console !== "undefined" && console.warn) {
if (!_WebCryptPQC._warnedHashes[bitLength] && typeof console !== "undefined" && console.warn) {
console.warn(
`SHA3-${bitLength} not natively supported by Web Crypto, falling back to ${fallbackAlgorithm}`
);
_WebCryptPQC._warnedHashes[bitLength] = true;
}

@@ -446,3 +490,6 @@ const digest = await this._crypto.subtle.digest(fallbackAlgorithm, data);

const privHash = await this._sha3Hash(hashInput, 512);
privateKey.set(privHash.slice(0, Math.min(params.privateKeySize, privHash.byteLength)));
privateKey.set(
privHash.slice(0, Math.min(params.privateKeySize - params.publicKeySize, privHash.byteLength))
);
privateKey.set(publicKey, params.privateKeySize - params.publicKeySize);
return { publicKey, privateKey };

@@ -467,20 +514,8 @@ }

}
// Chunked block conversion avoids stack overflow and O(N^2) memory churn
// Safe Base64 helpers
_arrayBufferToBase64(buffer) {
const bytes = new Uint8Array(buffer);
const CHUNK_SIZE = 32768;
let binary = "";
for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
binary += String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK_SIZE));
}
return btoa(binary);
return arrayBufferToBase64(buffer);
}
_base64ToArrayBuffer(base64) {
let padded = base64;
const mod = base64.length % 4;
if (mod > 0) {
padded += "=".repeat(4 - mod);
}
const bytes = Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
return bytes.buffer;
return base64ToArrayBuffer(base64);
}

@@ -487,0 +522,0 @@ };

+1
-1
LICENSE
MIT License
Copyright (c) 2025-2026 PuterVision LLC (https://putervision.com)
Copyright (c) 2025-2026 PuterVision (https://putervision.com)

@@ -5,0 +5,0 @@ Permission is hereby granted, free of charge, to any person obtaining a copy

+36
-8
package.json
{
"name": "webcrypt",
"version": "0.8.0",
"description": "Zero-dependency JavaScript AES-256-GCM encryption suite for text, files & WebRTC E2EE. Supports symmetric password derivation, RSA-4096 hybrid encryption, and post-quantum cryptography via pure Web Crypto API.",
"version": "1.0.0",
"description": "Zero-dependency JavaScript AES-256-GCM encryption suite for text, files, WebRTC E2EE & AI Agent Tooling (MCP). Supports symmetric password derivation, RSA-4096 hybrid encryption, and post-quantum cryptography via pure Web Crypto API.",
"license": "MIT",
"author": "PuterVision LLC",
"homepage": "https://putervision.github.io/WebCrypt",
"author": "PuterVision",
"homepage": "https://putervision.github.io/webcrypt/",
"repository": {

@@ -44,3 +44,10 @@ "type": "git",

"jwe",
"json-web-encryption"
"json-web-encryption",
"mcp",
"model-context-protocol",
"ai-agent",
"ai-agents",
"security-vault",
"state-memory",
"putervision"
],

@@ -51,2 +58,6 @@ "type": "module",

"types": "./dist/index.d.ts",
"bin": {
"webcrypt": "./bin/webcrypt.js",
"webcrypt-mcp": "./bin/webcrypt-mcp.js"
},
"sideEffects": false,

@@ -57,3 +68,8 @@ "engines": {

"files": [
"dist"
"dist",
"bin",
"src",
"manifest.json",
"server.json",
"glama.json"
],

@@ -92,2 +108,10 @@ "exports": {

"default": "./dist/WebCryptPQC.js"
},
"./mcp": {
"types": "./dist/mcp/server.d.ts",
"import": "./dist/mcp/server.js",
"browser": "./dist/mcp/server.js",
"module": "./dist/mcp/server.js",
"require": "./dist/mcp/server.cjs",
"default": "./dist/mcp/server.js"
}

@@ -108,2 +132,5 @@ },

"dist/WebCryptPQC.d.ts"
],
"mcp": [
"dist/mcp/server.d.ts"
]

@@ -113,3 +140,4 @@ }

"scripts": {
"build": "tsup src/index.js src/WebCrypt.js src/WebCryptAsym.js src/WebCryptPQC.js --format esm,cjs --dts --clean --no-splitting",
"build": "tsup src/index.js src/WebCrypt.js src/WebCryptAsym.js src/WebCryptPQC.js src/mcp/server.js --format esm,cjs --dts --clean --no-splitting",
"ci": "npm run lint && npm run test && npm run build",
"test": "node --experimental-vm-modules node_modules/.bin/jest",

@@ -123,3 +151,3 @@ "test:watch": "jest --watch",

"prepare": "if [ \"$NODE_ENV\" != \"development\" ]; then npm run build; fi",
"prepublishOnly": "npm run format:check",
"prepublishOnly": "npm run build && npm run format:check && npm test",
"publish": "npm publish --access public"

@@ -126,0 +154,0 @@ },

+108
-58
README.md

@@ -1,97 +0,147 @@

# WebCrypt
# WebCrypt v1.0.0
**Zero-dependency end-to-end cryptography suite for the modern web.**
**Zero-dependency Web Crypto & native AI Agent Tooling (MCP) for modern JavaScript.**
[![npm version](https://img.shields.io/npm/v/webcrypt)](https://www.npmjs.com/package/webcrypt)
[![license](https://img.shields.io/npm/l/webcrypt)](./LICENSE)
[![tests](https://img.shields.io/badge/tests-191%20passed-brightgreen)](./__tests__)
[![coverage](https://img.shields.io/badge/coverage-91%25-brightgreen)](./__tests__)
[![npm version](https://img.shields.io/npm/v/webcrypt.svg)](https://www.npmjs.com/package/webcrypt)
[![npm downloads](https://img.shields.io/npm/dm/webcrypt.svg)](https://www.npmjs.com/package/webcrypt)
[![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-339933.svg?logo=node.js&logoColor=white)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-3178C6.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
[![MCP](https://img.shields.io/badge/MCP-Ready-blueviolet.svg?logo=json&logoColor=white)](https://modelcontextprotocol.io)
[![Tests](https://img.shields.io/badge/tests-247%20passed-brightgreen.svg)](./__tests__)
[![Coverage](https://img.shields.io/badge/coverage-93.8%25-success.svg)](./coverage)
[![PuterVision Triad](https://img.shields.io/badge/PuterVision-Triad%20Standard-6366f1.svg)](https://putervision.com)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
AES-256-GCM symmetric encryption, RSA-4096 hybrid asymmetric encryption, ECDH key agreement, digital signatures, JWE compact serialization (RFC 7516), and WebRTC insertable streams — built natively for browser and Node.js Web Crypto API environments.
AES-256-GCM symmetric encryption, RSA-4096 hybrid public keys, ECDH key agreement, ECDSA/HMAC digital signatures, and Post-Quantum KEM (Kyber/Dilithium) — zero runtime dependencies, pure Web Crypto API.
---
## Interactive Live Demo & Documentation
## ⚡ Quickstart (15 Seconds)
- 🚀 **[Try WebCrypt Live Playground](https://putervision.github.io/WebCrypt/)**: Test AES-256, RSA-4096, ECDH, digital signatures, and file encryption directly in your browser.
- 📚 **[Documentation Index](./docs/)**
### 1. Installation
```bash
# 📦 Install as project library (Node.js, TypeScript, Browser)
npm install webcrypt
# 🌐 Install globally (CLI utilities & global MCP tools)
npm install -g webcrypt
```
```javascript
import { WebCrypt, WebCryptAsym } from "webcrypt";
// 🔒 Symmetric AES-256-GCM (600k PBKDF2 iterations)
const wc = new WebCrypt();
const encrypted = await wc.encryptText("Secret payload", "password");
const decrypted = await wc.decryptText(encrypted, "password");
// 🔑 Asymmetric RSA-4096 Hybrid Encryption
const wca = new WebCryptAsym();
const keyPair = await wca.generateKeyPair(4096);
const cipher = await wca.encryptText("Secret payload", keyPair.publicKey);
const plain = await wca.decryptText(cipher, keyPair.privateKey);
```
---
## Installation
### 2. Auto-Setup for AI Agents & IDEs (MCP Server)
```bash
npm install webcrypt
# Initialize MCP server, agent skills, and rules across your project
npx webcrypt init # or `webcrypt init` if installed globally
```
_Supports **Google Antigravity**, **Cursor**, **Claude Desktop**, **VS Code / Copilot**, **Windsurf**, **Cline**, and **Zed**._
---
## Quick Start Code Examples
## 🤖 Why AI Agents Need WebCrypt MCP
### 1. Symmetric Text Encryption (AES-256-GCM)
Equip autonomous coding agents with an authenticated cryptographic vault directly in their toolbelt:
```js
import { WebCrypt } from "webcrypt";
const wc = new WebCrypt();
- 🔐 **Confidential Local Vaulting (`encrypt_payload`)**: Encrypt API keys and state memory before writing to disk to prevent prompt log leaks.
- 🛡️ **Tamper-Proof Provenance (`sign_verify`)**: Cryptographically sign test evidence packs, release binaries, and code diffs with ECDSA or HMAC.
- 🤝 **Inter-Agent Key Exchange (`manage_keys`)**: Ephemeral JWK keypairs (RSA-4096, ECDH P-256/P-384) for private agent-to-agent messaging.
- ⚛️ **Post-Quantum Guardrails (`pqc_kem_sign`)**: Built-in Kyber KEM and Dilithium signatures future-proof long-term agent artifacts.
- ⚡ **Zero Dependencies**: 100% native `crypto.subtle` execution across Node.js 18+, Bun, browsers, and Edge runtimes.
const encrypted = await wc.encryptText("Secret message", "my-password");
const decrypted = await wc.decryptText(encrypted, "my-password");
```
┌───────────────────────────────────────────────────────────┐
│ 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 │
└───────────────────┘└───────────────────┘└───────────────────┘
```
### 2. Large File Streaming Encryption (8MB Chunking)
---
```js
const { blob, filename } = await wc.encryptFile(file, "my-password", { parallelChunks: 4 });
const decrypted = await wc.decryptFile(blob, "my-password");
```
## 🛠️ MCP Tools Reference (6 Core Tools)
### 3. Public-Key Hybrid Encryption (RSA-4096)
| Tool | Action / Mode | Description |
| :-------------------- | :--------------------------------------- | :--------------------------------------------------------------------------- |
| **`encrypt_payload`** | `symmetric` \| `asymmetric` \| `data` | Encrypt text, JSON objects, or files with AES-256-GCM or RSA-4096. |
| **`decrypt_payload`** | `symmetric` \| `asymmetric` \| `data` | Decrypt ciphertext back to plaintext or structured JSON. |
| **`manage_keys`** | `generate` \| `generate_random_password` | Generate JWK keypairs (RSA, ECDH, ECDSA, RSA-PSS) or high-entropy passwords. |
| **`crypto_hash`** | `SHA-256` \| `SHA-512` \| `SHA-3` | Compute cryptographic hash digests in hex or base64. |
| **`sign_verify`** | `sign` \| `verify` | Sign and verify messages, release hashes, and evidence packs. |
| **`pqc_kem_sign`** | `kyber_*` \| `dilithium_*` \| `hybrid_*` | Post-quantum Kyber KEM encapsulation and Dilithium signatures. |
```js
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);
```
## 📚 Technical Documentation Directory
### 4. ECDH Key Agreement & One-Step Encryption
Explore dedicated guides in [`docs/`](docs/) and [`examples/`](examples/):
```js
const aliceKeys = await wca.generateECDHKeyPair("P-256");
const bobKeys = await wca.generateECDHKeyPair("P-256");
| Guide | Topic |
| :---------------------------------------------------------------------------- | :------------------------------------------------------------ |
| 🚀 **[Live Interactive Playground](https://putervision.github.io/webcrypt/)** | Test all crypto features in the browser demo. |
| 💻 **[CLI Reference Guide](docs/CLI.md)** | Scaffolding, global project scanning, and terminal utilities. |
| ⚙️ **[Multi-IDE MCP Setup Guide](docs/MCP_IDE_SETUP.md)** | Step-by-step MCP JSON configs for all major IDEs. |
| 🔒 **[Symmetric Encryption API (`WebCrypt`)](docs/API_SYMMETRIC.md)** | AES-256-GCM, streaming files, WebRTC E2EE, PBKDF2. |
| 🔑 **[Asymmetric Encryption API (`WebCryptAsym`)](docs/API_ASYMMETRIC.md)** | RSA-4096 hybrid, ECDH key agreement, ECDSA/RSA-PSS. |
| ⚛️ **[Post-Quantum Cryptography Guide](docs/PQC.md)** | Kyber KEM, Dilithium signatures, and Hybrid KEM. |
| 🏗️ **[Architecture & MCP Specifications](docs/ARCHITECTURE.md)** | Stdio JSON-RPC 2.0 protocol and chunk framing specs. |
| 🤖 **[Agent Skill Definition](.agents/skills/webcrypt-mcp/SKILL.md)** | Custom agent skill with automated test runner script. |
| 📋 **[Project Instructions Template](PROJECT_INSTRUCTIONS_TEMPLATE.md)** | Multi-agent rules template (`<!-- webcrypt-mcp:start -->`). |
| 💡 **[Code Examples Directory](examples/README.md)** | Ready-to-run Node.js & browser recipes. |
const encrypted = await wca.encryptWithECDH(
"Confidential data",
aliceKeys.privateKey,
bobKeys.publicKey
);
const decrypted = await wca.decryptWithECDH(encrypted, bobKeys.privateKey, aliceKeys.publicKey);
```
---
### 5. Digital Signatures (ECDSA P-256 / P-384)
## 🌐 PuterVision Triad Standard
```js
const signingKeys = await wca.generateSigningKeyPair("P-256");
const signature = await wca.signText("Tamper-proof payload", signingKeys.privateKey);
const isValid = await wca.verifyText("Tamper-proof payload", signature, signingKeys.publicKey);
```
- 📊 **[`@putervision/state-memory-mcp`](https://github.com/putervision/state-memory-mcp)**: Persistent SQLite graph for workflow states, task DAGs, and decision trails.
- 👁️ **[`@putervision/vision-memory-mcp`](https://github.com/putervision/vision-memory-mcp)**: Multimodal visual layout cache, AX grounding, and video replay analysis.
- 🔐 **[`webcrypt`](https://github.com/putervision/webcrypt)**: Zero-dependency cryptographic vault, payload encryption, key management, and digital signatures.
---
## Complete API & Technical Documentation
## 🧪 Testing & Diagnostics
For complete method signatures, options, and advanced usage, see our detailed documentation sub-documents:
```bash
# Run unit & integration test matrix (30 suites, 247 tests)
npm test
- 📖 **[Symmetric Encryption API (`WebCrypt`)](./docs/API_SYMMETRIC.md)** — AES-256-GCM, File Streaming, WebRTC E2EE, LRU Key Cache, HMAC.
- 📖 **[Asymmetric Encryption API (`WebCryptAsym`)](./docs/API_ASYMMETRIC.md)** — RSA-4096 Hybrid, ECDH, Signatures, JWE RFC 7516, HKDF.
- 🔒 **[Cryptographic Architecture & Security](./docs/ARCHITECTURE.md)** — Threat Model, Timing-Safe Helpers, Grover Quantum Resistance.
- ⚛️ **[Post-Quantum Cryptography Guide](./docs/PQC.md)** — Kyber/Dilithium stubs & liboqs-js migration path.
- 🛡️ **[Security Policy](./SECURITY.md)** — Vulnerability reporting and version support table.
# Run live MCP tool test runner (25 assertions, 100% verified)
node .agents/skills/webcrypt-mcp/scripts/exercise_tools.js
# Audit environment & project configuration health
webcrypt doctor
```
---
## License
## ⚖️ License & Disclaimers
[MIT](./LICENSE) © PuterVision LLC
Developed and maintained by [PuterVision](https://putervision.com). Released under the [MIT License](LICENSE).
- **100% Local Execution Guarantee**: All cryptographic operations execute locally in memory via standard W3C Web Crypto API (`crypto.subtle`). Zero external API calls, telemetry, or network transmissions.
- **Trademarks & Non-Affiliation**: Product names (Cursor, Claude, Google Antigravity, VS Code, GitHub Copilot, Windsurf, Cline, Zed) are property of their respective owners and used solely for compatibility identification.
dist/index.cjs

Sorry, the diff of this file is too big to display

dist/index.js

Sorry, the diff of this file is too big to display

dist/WebCryptAsym.cjs

Sorry, the diff of this file is too big to display

dist/WebCryptAsym.js

Sorry, the diff of this file is too big to display