@oqs/liboqs-js 0.15.0

package/README.md

@@ -0,0 +1,829 @@
+# @oqs/liboqs-js
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-22+-green.svg)](https://nodejs.org/)
+
+A JavaScript/TypeScript wrapper for [LibOQS](https://github.com/open-quantum-safe/liboqs), providing access to post-quantum cryptographic algorithms for key encapsulation mechanisms (KEM) and digital signatures.
+
+## Overview
+
+This library provides WebAssembly bindings to LibOQS, part of the [Open Quantum Safe](https://openquantumsafe.org/) project. It includes:
+
+- Individual WASM modules per algorithm for optimal bundle sizes
+- TypeScript definitions for complete type safety
+- Support for Node.js and browser environments
+- SIMD-optimized builds for maximum performance
+- Tree-shakable ES module exports to minimize bundle size
+- Automatic memory management and secure cleanup
+
+## Status
+
+### ⚠️ Important Notice
+
+**This library is meant for research, prototyping, and experimentation.** While the underlying LibOQS library is well-maintained by the Open Quantum Safe project, both projects carry important caveats:
+
+- Most post-quantum algorithms have not received the same level of scrutiny as traditional cryptography
+- Algorithm support may change rapidly as research advances
+- Some algorithms may prove insecure against classical or quantum computers
+- This library has not received a formal security audit
+
+**If you must use post-quantum cryptography in production environments**, use **hybrid approaches** that combine post-quantum algorithms with traditional algorithms (e.g., ML-KEM with X25519, ML-DSA with Ed25519). This provides defense-in-depth during the transition period.
+
+For production deployments, follow guidance from NIST's [Post-Quantum Cryptography Standardization](https://csrc.nist.gov/Projects/post-quantum-cryptography) project.
+
+### NIST Standardized Algorithms
+
+The algorithms implementing NIST FIPS standards are:
+- **ML-KEM** (FIPS 203, formerly Kyber): ML-KEM-512, ML-KEM-768, ML-KEM-1024
+- **ML-DSA** (FIPS 204, formerly Dilithium): ML-DSA-44, ML-DSA-65, ML-DSA-87
+- **SLH-DSA** (FIPS 205, formerly SPHINCS+): 12 variants (SHA2 and SHAKE, 128/192/256-bit security, f/s modes)
+
+These algorithm names are stable and will be maintained. If NIST updates implementation details, this library will track those changes as closely as possible.
+
+### Available Algorithms
+
+The library provides JavaScript wrappers for **103 algorithms** including experimental and alternative post-quantum schemes:
+
+<details>
+<summary>Key Encapsulation Mechanisms (38 algorithms)</summary>
+
+- **Kyber** (legacy, use ML-KEM): `Kyber512`, `Kyber768`, `Kyber1024`
+- **Classic McEliece**: 10 variants (`Classic-McEliece-348864` through `Classic-McEliece-8192128f`)
+- **FrodoKEM**: 6 salted variants (AES and SHAKE, 640/976/1344-bit)
+- **eFrodoKEM**: 6 ephemeral variants (AES and SHAKE, 640/976/1344-bit)
+- **HQC**: `HQC-128`, `HQC-192`, `HQC-256`
+- **NTRU**: 6 variants (HPS and HRSS families)
+- **NTRU Prime**: `sntrup761`
+
+**Note**: BIKE family is not supported due to WASM incompatibility (requires platform-specific optimizations).
+
+</details>
+
+<details>
+<summary>Digital Signatures (65 algorithms)</summary>
+
+- **Falcon**: `Falcon-512`, `Falcon-1024`, `Falcon-padded-512`, `Falcon-padded-1024`
+- **SLH-DSA** (FIPS 205): 12 variants (SHA2 and SHAKE, 128/192/256-bit security, f/s modes)
+- **CROSS**: 18 variants (RSDP and RSDPG parameter sets with balanced/fast/small tradeoffs)
+- **MAYO**: `MAYO-1`, `MAYO-2`, `MAYO-3`, `MAYO-5`
+- **SNOVA**: 12 variants (various parameter sets)
+- **UOV**: 12 variants (Ip, Is, III, V with different optimization levels)
+
+</details>
+
+See `algorithms.json` for the complete algorithm registry, or [the algorithms section](#available-algorithms-1). All 103 algorithms have WASM modules, JavaScript wrappers, TypeScript definitions, and test coverage.
+
+## Installation
+
+This package works with all major JavaScript package managers:
+
+```bash
+# bun (recommended - fastest)
+bun add @oqs/liboqs-js
+
+# npm
+npm install @oqs/liboqs-js
+
+# pnpm
+pnpm add @oqs/liboqs-js
+
+# yarn
+yarn add @oqs/liboqs-js
+
+# deno (via npm: specifier - no install needed)
+# See "Deno Usage" section below
+```
+
+This project uses **bun** by default for development, but all package managers are fully supported.
+
+### Deno Usage
+
+✅ **Fully Supported** - Available through **npm** only due to package size limitations on JSR:
+
+```typescript
+// Alternative: Import from npm
+import { createMLKEM768 } from "npm:@oqs/liboqs-js";
+
+const kem = await createMLKEM768();
+const { publicKey, secretKey } = kem.generateKeyPair();
+kem.destroy();
+```
+
+**How it works:** The library automatically detects the Deno runtime and loads optimized WASM modules built for deno compatibility (`ENVIRONMENT='web'` Emscripten build).
+
+**Recommended Setup** - Create a `deno.json` for cleaner imports:
+```json
+{
+  "imports": {
+    "liboqs": "npm:@oqs/liboqs-js@^0.15.0"
+  }
+}
+```
+
+Then import like:
+```typescript
+import { createMLKEM768 } from "liboqs";
+```
+
+**Using the CLI with Deno:**
+```bash
+# Run CLI directly (JSR)
+deno run --allow-read npm:@oqs/liboqs-js/cli kem keygen ml-kem-768
+
+# Or from npm
+deno run --allow-read npm:@oqs/liboqs-js/cli kem keygen ml-kem-768
+```
+
+```json
+# Or add to deno.json tasks:
+{
+  "tasks": {
+    "liboqs": "deno run --allow-read npm:@oqs/liboqs-js/cli"
+  }
+}
+```
+```bash
+# Then run:
+deno task liboqs list --kem
+```
+
+**Permissions:**
+```bash
+# Library usage (cryptographic operations only)
+deno run --allow-read your-script.ts
+
+# CLI usage (may need write for output files)
+deno run --allow-read --allow-write npm:@oqs/liboqs-js/cli kem keygen ml-kem-768 --output-dir ./keys
+```
+
+Deno automatically caches packages on first run - no separate install step needed.
+
+## Requirements
+
+- **Node.js 22.0 or higher** (for WASM SIMD support)
+- **Package Managers**: Bun 1.0+, npm 10+, pnpm 8+, yarn 4+ (for Node.js)
+- **Deno 2.0+** (available only through npm)
+- **Modern browsers** with WebAssembly support (Chrome 91+, Firefox 89+, Edge 91+, Safari 16.4+ - Safari is untested)
+
+## Quick Start
+
+### Command Line Interface
+
+The package includes a CLI for cryptographic operations without writing code:
+
+```bash
+# Generate ML-KEM-768 keypair
+npx @oqs/liboqs-js kem keygen ml-kem-768 --output-dir ./keys
+
+# Encapsulate to create shared secret
+npx @oqs/liboqs-js kem encapsulate ml-kem-768 ./keys/public.key --format base64
+
+# Sign a message
+npx @oqs/liboqs-js sig sign ml-dsa-65 message.txt ./keys/secret.key -o signature.sig
+
+# Verify signature
+npx @oqs/liboqs-js sig verify ml-dsa-65 message.txt signature.sig ./keys/public.key
+
+# List available algorithms
+npx @oqs/liboqs-js list --kem
+
+# Get algorithm info
+npx @oqs/liboqs-js info ml-kem-768
+```
+
+**Works with all package managers:**
+- `npx @oqs/liboqs-js` (npm)
+- `bunx @oqs/liboqs-js` (bun)
+- `pnpm dlx @oqs/liboqs-js` (pnpm)
+- `yarn dlx @oqs/liboqs-js` (yarn)
+
+**For full CLI documentation, run:**
+```bash
+npx @oqs/liboqs-js --help
+```
+
+### Key Encapsulation (ML-KEM)
+
+```javascript
+import { createMLKEM768 } from '@oqs/liboqs-js';
+
+// Alice generates keypair
+const alice = await createMLKEM768();
+const { publicKey, secretKey } = alice.generateKeyPair();
+
+// Bob encapsulates shared secret
+const bob = await createMLKEM768();
+const { ciphertext, sharedSecret } = bob.encapsulate(publicKey);
+
+// Alice decapsulates
+const aliceSecret = alice.decapsulate(ciphertext, secretKey);
+
+// Verify shared secrets match
+console.log('Secrets match:', Buffer.compare(sharedSecret, aliceSecret) === 0);
+
+// Cleanup
+alice.destroy();
+bob.destroy();
+```
+
+### Digital Signatures (ML-DSA)
+
+```javascript
+import { createMLDSA65 } from '@oqs/liboqs-js';
+
+const signer = await createMLDSA65();
+const { publicKey, secretKey } = signer.generateKeyPair();
+
+const message = new TextEncoder().encode('Hello, quantum world!');
+const signature = signer.sign(message, secretKey);
+
+const isValid = signer.verify(message, signature, publicKey);
+console.log('Valid:', isValid); // true
+
+signer.destroy();
+```
+
+## Available Algorithms
+
+### NIST Standardized (Recommended)
+
+These are the officially standardized post-quantum cryptographic algorithms approved by NIST for production use.
+
+#### Key Encapsulation - ML-KEM (Module-Lattice-Based KEM)
+
+| Algorithm | Security Level | Public Key | Secret Key | Ciphertext | Factory Function |
+|-----------|----------------|------------|------------|------------|------------------|
+| ML-KEM-512 | Level 1 (128-bit) | 800 B | 1,632 B | 768 B | `createMLKEM512()` |
+| ML-KEM-768 | Level 3 (192-bit) | 1,184 B | 2,400 B | 1,088 B | `createMLKEM768()` |
+| ML-KEM-1024 | Level 5 (256-bit) | 1,568 B | 3,168 B | 1,568 B | `createMLKEM1024()` |
+
+**Formerly known as**: CRYSTALS-Kyber
+
+#### Digital Signatures - ML-DSA (Module-Lattice-Based DSA)
+
+| Algorithm | Security Level | Public Key | Secret Key | Signature | Factory Function |
+|-----------|----------------|------------|------------|-----------|------------------|
+| ML-DSA-44 | Level 2 (128-bit) | 1,312 B | 2,560 B | ~2,420 B | `createMLDSA44()` |
+| ML-DSA-65 | Level 3 (192-bit) | 1,952 B | 4,032 B | ~3,309 B | `createMLDSA65()` |
+| ML-DSA-87 | Level 5 (256-bit) | 2,592 B | 4,896 B | ~4,627 B | `createMLDSA87()` |
+
+**Formerly known as**: CRYSTALS-Dilithium
+
+#### Digital Signatures - SLH-DSA (Stateless Hash-Based DSA)
+
+| Algorithm | Security Level | Public Key | Secret Key | Signature | Factory Function |
+|-----------|----------------|------------|------------|-----------|------------------|
+| SLH-DSA-SHA2-128f | Level 1 (128-bit) | 32 B | 64 B | 17,088 B | `createSLHDSASHA2128f()` |
+| SLH-DSA-SHA2-128s | Level 1 (128-bit) | 32 B | 64 B | 7,856 B | `createSLHDSASHA2128s()` |
+| SLH-DSA-SHA2-192f | Level 3 (192-bit) | 48 B | 96 B | 35,664 B | `createSLHDSASHA2192f()` |
+| SLH-DSA-SHA2-192s | Level 3 (192-bit) | 48 B | 96 B | 16,224 B | `createSLHDSASHA2192s()` |
+| SLH-DSA-SHA2-256f | Level 5 (256-bit) | 64 B | 128 B | 49,856 B | `createSLHDSASHA2256f()` |
+| SLH-DSA-SHA2-256s | Level 5 (256-bit) | 64 B | 128 B | 29,792 B | `createSLHDSASHA2256s()` |
+| SLH-DSA-SHAKE-128f | Level 1 (128-bit) | 32 B | 64 B | 17,088 B | `createSLHDSASHAKE128f()` |
+| SLH-DSA-SHAKE-128s | Level 1 (128-bit) | 32 B | 64 B | 7,856 B | `createSLHDSASHAKE128s()` |
+| SLH-DSA-SHAKE-192f | Level 3 (192-bit) | 48 B | 96 B | 35,664 B | `createSLHDSASHAKE192f()` |
+| SLH-DSA-SHAKE-192s | Level 3 (192-bit) | 48 B | 96 B | 16,224 B | `createSLHDSASHAKE192s()` |
+| SLH-DSA-SHAKE-256f | Level 5 (256-bit) | 64 B | 128 B | 49,856 B | `createSLHDSASHAKE256f()` |
+| SLH-DSA-SHAKE-256s | Level 5 (256-bit) | 64 B | 128 B | 29,792 B | `createSLHDSASHAKE256s()` |
+
+**Formerly known as**: SPHINCS+
+**Variants**: `f` = fast signing/slower verification, `s` = small signatures/slower signing
+
+### Additional Algorithms
+
+Beyond the NIST-standardized algorithms, this library includes experimental and alternative post-quantum schemes for research purposes.
+
+#### Legacy Kyber (Deprecated)
+
+| Algorithm | Security Level | Public Key | Secret Key | Ciphertext | Factory Function |
+|-----------|----------------|------------|------------|------------|------------------|
+| Kyber512 | Level 1 (128-bit) | 800 B | 1,632 B | 768 B | `createKyber512()` |
+| Kyber768 | Level 3 (192-bit) | 1,184 B | 2,400 B | 1,088 B | `createKyber768()` |
+| Kyber1024 | Level 5 (256-bit) | 1,568 B | 3,168 B | 1,568 B | `createKyber1024()` |
+
+**Note**: Use ML-KEM instead. Kyber is the pre-standardization version.
+
+#### Key Encapsulation - Classic McEliece (10 variants)
+
+| Algorithm | Security Level | Public Key | Secret Key | Ciphertext | Factory Function |
+|-----------|----------------|------------|------------|------------|------------------|
+| Classic-McEliece-348864 | Level 1 (128-bit) | 261,120 B | 6,492 B | 96 B | `createClassicMcEliece348864()` |
+| Classic-McEliece-348864f | Level 1 (128-bit) | 261,120 B | 6,492 B | 96 B | `createClassicMcEliece348864f()` |
+| Classic-McEliece-460896 | Level 3 (192-bit) | 524,160 B | 13,608 B | 156 B | `createClassicMcEliece460896()` |
+| Classic-McEliece-460896f | Level 3 (192-bit) | 524,160 B | 13,608 B | 156 B | `createClassicMcEliece460896f()` |
+| Classic-McEliece-6688128 | Level 5 (256-bit) | 1,044,992 B | 13,932 B | 208 B | `createClassicMcEliece6688128()` |
+| Classic-McEliece-6688128f | Level 5 (256-bit) | 1,044,992 B | 13,932 B | 208 B | `createClassicMcEliece6688128f()` |
+| Classic-McEliece-6960119 | Level 5 (256-bit) | 1,047,319 B | 13,948 B | 194 B | `createClassicMcEliece6960119()` |
+| Classic-McEliece-6960119f | Level 5 (256-bit) | 1,047,319 B | 13,948 B | 194 B | `createClassicMcEliece6960119f()` |
+| Classic-McEliece-8192128 | Level 5 (256-bit) | 1,357,824 B | 14,120 B | 208 B | `createClassicMcEliece8192128()` |
+| Classic-McEliece-8192128f | Level 5 (256-bit) | 1,357,824 B | 14,120 B | 208 B | `createClassicMcEliece8192128f()` |
+
+#### Key Encapsulation - FrodoKEM (6 salted variants)
+
+| Algorithm | Security Level | Public Key | Secret Key | Ciphertext | Factory Function |
+|-----------|----------------|------------|------------|------------|------------------|
+| FrodoKEM-640-AES | Level 1 (128-bit) | 9,616 B | 19,888 B | 9,752 B | `createFrodoKEM640AES()` |
+| FrodoKEM-640-SHAKE | Level 1 (128-bit) | 9,616 B | 19,888 B | 9,752 B | `createFrodoKEM640SHAKE()` |
+| FrodoKEM-976-AES | Level 3 (192-bit) | 15,632 B | 31,296 B | 15,792 B | `createFrodoKEM976AES()` |
+| FrodoKEM-976-SHAKE | Level 3 (192-bit) | 15,632 B | 31,296 B | 15,792 B | `createFrodoKEM976SHAKE()` |
+| FrodoKEM-1344-AES | Level 5 (256-bit) | 21,520 B | 43,088 B | 21,696 B | `createFrodoKEM1344AES()` |
+| FrodoKEM-1344-SHAKE | Level 5 (256-bit) | 21,520 B | 43,088 B | 21,696 B | `createFrodoKEM1344SHAKE()` |
+
+#### Key Encapsulation - eFrodoKEM (6 ephemeral variants)
+
+| Algorithm | Security Level | Public Key | Secret Key | Ciphertext | Factory Function |
+|-----------|----------------|------------|------------|------------|------------------|
+| eFrodoKEM-640-AES | Level 1 (128-bit) | 9,616 B | 19,888 B | 9,720 B | `createEFrodoKEM640AES()` |
+| eFrodoKEM-640-SHAKE | Level 1 (128-bit) | 9,616 B | 19,888 B | 9,720 B | `createEFrodoKEM640SHAKE()` |
+| eFrodoKEM-976-AES | Level 3 (192-bit) | 15,632 B | 31,296 B | 15,744 B | `createEFrodoKEM976AES()` |
+| eFrodoKEM-976-SHAKE | Level 3 (192-bit) | 15,632 B | 31,296 B | 15,744 B | `createEFrodoKEM976SHAKE()` |
+| eFrodoKEM-1344-AES | Level 5 (256-bit) | 21,520 B | 43,088 B | 21,632 B | `createEFrodoKEM1344AES()` |
+| eFrodoKEM-1344-SHAKE | Level 5 (256-bit) | 21,520 B | 43,088 B | 21,632 B | `createEFrodoKEM1344SHAKE()` |
+
+#### Key Encapsulation - HQC (3 variants)
+
+| Algorithm | Security Level | Public Key | Secret Key | Ciphertext | Factory Function |
+|-----------|----------------|------------|------------|------------|------------------|
+| HQC-128 | Level 1 (128-bit) | 2,249 B | 2,305 B | 4,433 B | `createHQC128()` |
+| HQC-192 | Level 3 (192-bit) | 4,522 B | 4,586 B | 8,978 B | `createHQC192()` |
+| HQC-256 | Level 5 (256-bit) | 7,245 B | 7,317 B | 14,421 B | `createHQC256()` |
+
+#### Key Encapsulation - NTRU (6 variants)
+
+| Algorithm | Security Level | Public Key | Secret Key | Ciphertext | Factory Function |
+|-----------|----------------|------------|------------|------------|------------------|
+| NTRU-HPS-2048-509 | Level 1 (128-bit) | 699 B | 935 B | 699 B | `createNTRUHPS2048509()` |
+| NTRU-HPS-2048-677 | Level 3 (192-bit) | 930 B | 1,234 B | 930 B | `createNTRUHPS2048677()` |
+| NTRU-HPS-4096-821 | Level 5 (256-bit) | 1,230 B | 1,590 B | 1,230 B | `createNTRUHPS4096821()` |
+| NTRU-HPS-4096-1229 | Level 5 (256-bit) | 1,842 B | 2,366 B | 1,842 B | `createNTRUHPS40961229()` |
+| NTRU-HRSS-701 | Level 3 (192-bit) | 1,138 B | 1,450 B | 1,138 B | `createNTRUHRSS701()` |
+| NTRU-HRSS-1373 | Level 5 (256-bit) | 2,401 B | 2,983 B | 2,401 B | `createNTRUHRSS1373()` |
+
+#### Key Encapsulation - NTRU Prime
+
+| Algorithm | Security Level | Public Key | Secret Key | Ciphertext | Factory Function |
+|-----------|----------------|------------|------------|------------|------------------|
+| sntrup761 | Level 3 (192-bit) | 1,158 B | 1,763 B | 1,039 B | `createSntrup761()` |
+
+**Note**: `sntrup761` is included primarily for interoperability testing.
+
+#### Digital Signatures - Falcon (4 variants)
+
+| Algorithm | Security Level | Public Key | Secret Key | Signature | Factory Function |
+|-----------|----------------|------------|------------|-----------|------------------|
+| Falcon-512 | Level 1 (128-bit) | 897 B | 1,281 B | ~752 B | `createFalcon512()` |
+| Falcon-1024 | Level 5 (256-bit) | 1,793 B | 2,305 B | ~1,462 B | `createFalcon1024()` |
+| Falcon-padded-512 | Level 1 (128-bit) | 897 B | 1,281 B | 666 B | `createFalconPadded512()` |
+| Falcon-padded-1024 | Level 5 (256-bit) | 1,793 B | 2,305 B | 1,280 B | `createFalconPadded1024()` |
+
+#### Digital Signatures - CROSS (18 variants)
+
+| Algorithm | Security Level | Public Key | Secret Key | Signature | Factory Function |
+|-----------|----------------|------------|------------|-----------|------------------|
+| CROSS-rsdp-128-balanced | Level 1 (128-bit) | 77 B | 32 B | 13,152 B | `createCROSSRSDP128Balanced()` |
+| CROSS-rsdp-128-fast | Level 1 (128-bit) | 77 B | 32 B | 18,432 B | `createCROSSRSDP128Fast()` |
+| CROSS-rsdp-128-small | Level 1 (128-bit) | 77 B | 32 B | 12,432 B | `createCROSSRSDP128Small()` |
+| CROSS-rsdp-192-balanced | Level 3 (192-bit) | 115 B | 48 B | 29,853 B | `createCROSSRSDP192Balanced()` |
+| CROSS-rsdp-192-fast | Level 3 (192-bit) | 115 B | 48 B | 41,406 B | `createCROSSRSDP192Fast()` |
+| CROSS-rsdp-192-small | Level 3 (192-bit) | 115 B | 48 B | 28,391 B | `createCROSSRSDP192Small()` |
+| CROSS-rsdp-256-balanced | Level 5 (256-bit) | 153 B | 64 B | 53,527 B | `createCROSSRSDP256Balanced()` |
+| CROSS-rsdp-256-fast | Level 5 (256-bit) | 153 B | 64 B | 74,590 B | `createCROSSRSDP256Fast()` |
+| CROSS-rsdp-256-small | Level 5 (256-bit) | 153 B | 64 B | 50,818 B | `createCROSSRSDP256Small()` |
+| CROSS-rsdpg-128-balanced | Level 1 (128-bit) | 54 B | 32 B | 9,120 B | `createCROSSRSDPG128Balanced()` |
+| CROSS-rsdpg-128-fast | Level 1 (128-bit) | 54 B | 32 B | 11,980 B | `createCROSSRSDPG128Fast()` |
+| CROSS-rsdpg-128-small | Level 1 (128-bit) | 54 B | 32 B | 8,960 B | `createCROSSRSDPG128Small()` |
+| CROSS-rsdpg-192-balanced | Level 3 (192-bit) | 83 B | 48 B | 22,464 B | `createCROSSRSDPG192Balanced()` |
+| CROSS-rsdpg-192-fast | Level 3 (192-bit) | 83 B | 48 B | 26,772 B | `createCROSSRSDPG192Fast()` |
+| CROSS-rsdpg-192-small | Level 3 (192-bit) | 83 B | 48 B | 20,452 B | `createCROSSRSDPG192Small()` |
+| CROSS-rsdpg-256-balanced | Level 5 (256-bit) | 106 B | 64 B | 40,100 B | `createCROSSRSDPG256Balanced()` |
+| CROSS-rsdpg-256-fast | Level 5 (256-bit) | 106 B | 64 B | 48,102 B | `createCROSSRSDPG256Fast()` |
+| CROSS-rsdpg-256-small | Level 5 (256-bit) | 106 B | 64 B | 36,454 B | `createCROSSRSDPG256Small()` |
+
+#### Digital Signatures - MAYO (4 variants)
+
+| Algorithm | Security Level | Public Key | Secret Key | Signature | Factory Function |
+|-----------|----------------|------------|------------|-----------|------------------|
+| MAYO-1 | Level 1 (128-bit) | 1,420 B | 24 B | 454 B | `createMAYO1()` |
+| MAYO-2 | Level 1 (128-bit) | 4,912 B | 24 B | 186 B | `createMAYO2()` |
+| MAYO-3 | Level 3 (192-bit) | 2,986 B | 32 B | 681 B | `createMAYO3()` |
+| MAYO-5 | Level 5 (256-bit) | 5,554 B | 40 B | 964 B | `createMAYO5()` |
+
+#### Digital Signatures - SNOVA (12 variants)
+
+| Algorithm | Security Level | Public Key | Secret Key | Signature | Factory Function |
+|-----------|----------------|------------|------------|-----------|------------------|
+| SNOVA-24-5-4 | Level 1 (128-bit) | 1,016 B | 48 B | 248 B | `createSNOVA2454()` |
+| SNOVA-24-5-4-esk | Level 1 (128-bit) | 1,016 B | 36,848 B | 248 B | `createSNOVA2454ESK()` |
+| SNOVA-24-5-4-SHAKE | Level 1 (128-bit) | 1,016 B | 48 B | 248 B | `createSNOVA2454SHAKE()` |
+| SNOVA-24-5-4-SHAKE-esk | Level 1 (128-bit) | 1,016 B | 36,848 B | 248 B | `createSNOVA2454SHAKEESK()` |
+| SNOVA-24-5-5 | Level 1 (128-bit) | 1,579 B | 48 B | 379 B | `createSNOVA2455()` |
+| SNOVA-25-8-3 | Level 1 (128-bit) | 2,320 B | 48 B | 165 B | `createSNOVA2583()` |
+| SNOVA-29-6-5 | Level 3 (192-bit) | 2,716 B | 48 B | 454 B | `createSNOVA2965()` |
+| SNOVA-37-17-2 | Level 3 (192-bit) | 9,842 B | 48 B | 124 B | `createSNOVA37172()` |
+| SNOVA-37-8-4 | Level 3 (192-bit) | 4,112 B | 48 B | 376 B | `createSNOVA3784()` |
+| SNOVA-49-11-3 | Level 5 (256-bit) | 6,006 B | 48 B | 286 B | `createSNOVA49113()` |
+| SNOVA-56-25-2 | Level 5 (256-bit) | 31,266 B | 48 B | 178 B | `createSNOVA56252()` |
+| SNOVA-60-10-4 | Level 5 (256-bit) | 8,016 B | 48 B | 576 B | `createSNOVA60104()` |
+
+#### Digital Signatures - UOV (12 variants)
+
+| Algorithm | Security Level | Public Key | Secret Key | Signature | Factory Function |
+|-----------|----------------|------------|------------|-----------|------------------|
+| OV-Ip | Level 1 (128-bit) | 278,432 B | 237,896 B | 128 B | `createOVIp()` |
+| OV-Ip-pkc | Level 1 (128-bit) | 43,576 B | 237,896 B | 128 B | `createOVIpPKC()` |
+| OV-Ip-pkc-skc | Level 1 (128-bit) | 43,576 B | 32 B | 128 B | `createOVIpPKCSKC()` |
+| OV-Is | Level 1 (128-bit) | 412,160 B | 348,704 B | 96 B | `createOVIs()` |
+| OV-Is-pkc | Level 1 (128-bit) | 66,576 B | 348,704 B | 96 B | `createOVIsPKC()` |
+| OV-Is-pkc-skc | Level 1 (128-bit) | 66,576 B | 32 B | 96 B | `createOVIsPKCSKC()` |
+| OV-III | Level 3 (192-bit) | 1,225,440 B | 1,044,320 B | 200 B | `createOVIII()` |
+| OV-III-pkc | Level 3 (192-bit) | 189,232 B | 1,044,320 B | 200 B | `createOVIIIPKC()` |
+| OV-III-pkc-skc | Level 3 (192-bit) | 189,232 B | 32 B | 200 B | `createOVIIIPKCSKC()` |
+| OV-V | Level 5 (256-bit) | 2,869,440 B | 2,436,704 B | 260 B | `createOVV()` |
+| OV-V-pkc | Level 5 (256-bit) | 446,992 B | 2,436,704 B | 260 B | `createOVVPKC()` |
+| OV-V-pkc-skc | Level 5 (256-bit) | 446,992 B | 32 B | 260 B | `createOVVPKCSKC()` |
+
+**Notes:**
+- UOV variants with `-pkc` (public key compression) have smaller public keys
+- UOV variants with `-skc` (secret key compression) have smaller secret keys
+- `-esk` SNOVA variants use expanded secret keys for faster signing
+
+## Bundle Size Optimization
+
+Each algorithm is compiled separately into individual WASM modules, so you only bundle what you use:
+
+```javascript
+// Single algorithm (~80-160KB depending on algorithm complexity)
+import { createMLKEM768 } from '@oqs/liboqs-js';
+const kem = await createMLKEM768();
+
+// Multiple algorithms - each adds its own WASM module
+import { createMLKEM768, createMLDSA65 } from '@oqs/liboqs-js';
+const kem = await createMLKEM768();
+const sig = await createMLDSA65();
+```
+
+Tree-shaking ensures unused algorithms are never included in your bundle. Each algorithm's WASM is embedded in its module and loaded when you import the factory function.
+
+## Package Structure
+
+### Exports
+
+```javascript
+// Main entry - all 103 algorithm factory functions, classes, and metadata
+import { createMLKEM768, MLKEM768, ML_KEM_768_INFO } from '@oqs/liboqs-js';
+
+// KEM-only exports (32 algorithms)
+import {
+  createMLKEM512,
+  createClassicMcEliece348864,
+  createFrodoKEM640AES
+} from '@oqs/liboqs-js/kem';
+
+// Signature-only exports (65 algorithms)
+import {
+  createMLDSA44,
+  createFalcon512,
+  createSphincsSha2128fSimple
+} from '@oqs/liboqs-js/sig';
+
+// Error classes only
+import { LibOQSError, LibOQSInitError } from '@oqs/liboqs-js/errors';
+```
+
+### File Structure
+
+```
+@oqs/liboqs-js/
+├── src/
+│   ├── algorithms/
+│   │   ├── kem/
+│   │   │   ├── ml-kem/           # ML-KEM (3 variants)
+│   │   │   ├── kyber/            # Legacy Kyber (3 variants)
+│   │   │   ├── classic-mceliece/ # Classic McEliece (10 variants)
+│   │   │   ├── frodokem/         # FrodoKEM (6 variants)
+│   │   │   ├── hqc/              # HQC (3 variants)
+│   │   │   └── ntru/             # NTRU + sntrup761 (7 variants)
+│   │   └── sig/
+│   │       ├── ml-dsa/           # ML-DSA (3 variants)
+│   │       ├── falcon/           # Falcon (4 variants)
+│   │       ├── slh-dsa/          # SLH-DSA (12 variants)
+│   │       ├── cross/            # CROSS (18 variants)
+│   │       ├── mayo/             # MAYO (4 variants)
+│   │       ├── snova/            # SNOVA (12 variants)
+│   │       └── uov/              # UOV (12 variants)
+│   ├── cli/
+│   │   ├── commands/             # CLI command implementations
+│   │   │   ├── info.js           # Algorithm information
+│   │   │   ├── kem.js            # KEM operations (keygen, encaps, decaps)
+│   │   │   ├── sig.js            # Signature operations (keygen, sign, verify)
+│   │   │   └── list.js           # List available algorithms
+│   │   ├── algorithms.js         # Algorithm registry
+│   │   ├── index.js              # CLI entry point
+│   │   ├── io.js                 # File I/O utilities
+│   │   └── parser.js             # Command parser
+│   ├── core/
+│   │   ├── errors.js             # Error classes
+│   │   └── validation.js         # Input validation utilities
+│   ├── types/                    # TypeScript definitions
+│   │   ├── algorithms.d.ts
+│   │   ├── errors.d.ts
+│   │   └── index.d.ts
+│   ├── index.js                  # Main entry (all 103 algorithms)
+│   ├── kem.js                    # KEM exports (38 algorithms)
+│   └── sig.js                    # Signature exports (65 algorithms)
+├── bin/
+│   └── cli.js                    # CLI executable entry point
+├── tests/
+│   ├── kem.test.ts
+│   ├── sig.test.ts
+│   ├── cli.test.ts
+│   └── deno/                     # Deno-specific tests
+│       ├── kem.test.ts
+│       ├── sig.test.ts
+│       └── cli.test.ts
+├── dist/                         # WASM modules (97 × 2 = 194 files, ~100-500KB each)
+│   ├── ml-kem-512.min.js         # Node.js/Browser module
+│   ├── ml-kem-512.deno.js        # Deno module
+│   ├── falcon-512.min.js
+│   ├── falcon-512.deno.js
+│   └── ... (and 190 others)
+├── algorithms.json               # Algorithm registry and metadata
+└── build.sh                      # WASM build script
+```
+
+## Architecture
+
+The library is organized in layers:
+
+1. **WASM Modules**: Emscripten-compiled LibOQS binaries (one per algorithm)
+2. **Low-level Bindings**: Direct WASM function calls (`_OQS_KEM_*`, `_OQS_SIG_*`)
+3. **High-level Wrappers**: User-friendly classes (`MLKEM768`, `MLDSA65`)
+4. **Public API**: Factory functions and exports
+
+### Memory Management
+
+**IMPORTANT**: Always call `destroy()` when finished with an algorithm instance. WASM memory is not garbage-collected by JavaScript.
+
+#### Why This Matters
+
+WebAssembly modules allocate native memory outside the JavaScript heap. When you create an algorithm instance, LibOQS allocates C structures that JavaScript's garbage collector cannot reclaim. Without calling `destroy()`, this memory leaks permanently.
+
+**Long-running applications** (servers, single-page apps, daemons) that don't call `destroy()` will experience:
+- Increasing memory usage over time
+- Eventually: allocation failures or crashes when the 256MB WASM heap limit is reached
+
+**Short-lived scripts** are less affected since the OS reclaims all memory when the process exits.
+
+#### Best Practices
+
+```javascript
+// Pattern 1: Simple cleanup
+const kem = await createMLKEM768();
+const { publicKey, secretKey } = kem.generateKeyPair();
+kem.destroy();
+
+// Pattern 2: Error-safe cleanup (recommended)
+const kem = await createMLKEM768();
+try {
+  const { publicKey, secretKey } = kem.generateKeyPair();
+  const { ciphertext, sharedSecret } = kem.encapsulate(publicKey);
+  // ... use results ...
+} finally {
+  kem.destroy(); // Always runs, even if errors occur
+}
+
+// Pattern 3: Multiple operations
+const sig = await createMLDSA65();
+try {
+  const { publicKey, secretKey } = sig.generateKeyPair();
+  const message = new TextEncoder().encode('Hello!');
+  const signature = sig.sign(message, secretKey);
+  const isValid = sig.verify(message, signature, publicKey);
+  return isValid;
+} finally {
+  sig.destroy();
+}
+```
+
+#### Additional Notes
+
+- Secret keys, shared secrets, and signatures are handled via WASM memory
+- Keys and secrets are not automatically zeroed (limitation of JavaScript/WASM)
+- Each algorithm instance must be destroyed individually
+- After calling `destroy()`, the instance cannot be reused
+
+### Thread Safety
+
+- Individual algorithm instances are **not** thread-safe
+- For concurrent operations, create separate instances per worker/thread
+- WASM modules can be instantiated multiple times safely
+
+## Security Considerations
+
+1. **Use NIST Standardized Algorithms**: ML-KEM, ML-DSA, and SLH-DSA are recommended for production
+2. **Hybrid Cryptography**: We, as well as OQS, strongly recommend combining with traditional algorithms (X25519/Ed25519) during transition
+3. **Key Storage**: Store secret keys securely, never in plain text or localStorage
+4. **Stay Updated**: Monitor NIST guidance and update regularly
+5. **Audit Your Deployment**: Consult cryptographic experts for production use
+6. **Random Number Generation**: This library uses system entropy (Node.js `crypto.randomBytes()`, browser `crypto.getRandomValues()`)
+
+### Reporting Security Issues
+
+See [SECURITY.md](SECURITY.md) for our vulnerability disclosure policy. Issues specific to the LibOQS C library should be reported to the [LibOQS project](https://github.com/open-quantum-safe/liboqs/security).
+
+## Building from Source
+
+### Prerequisites
+
+- **Node.js 22+**
+- **Emscripten** (latest stable release)
+- **Git**
+- **CMake 3.20+**
+- **Python 3** (for Emscripten)
+- **jq** (for JSON parsing in build.sh)
+
+### Build Steps
+
+```bash
+# Clone repository
+git clone https://github.com/open-quantum-safe/liboqs-js.git
+cd liboqs-js
+
+# Build all algorithms
+./build.sh
+
+# Build specific algorithm
+./build.sh ml-kem-768
+
+# Setup only (clone liboqs without building)
+./build.sh --setup-only
+
+# Clean build artifacts
+./build.sh --clean
+```
+
+### Build System
+
+The build system is **data-driven** using `algorithms.json`:
+
+```json
+{
+  "kem": {
+    "ml-kem": {
+      "ML-KEM-768": {
+        "slug": "ml-kem-768",
+        "cmake_var": "ML_KEM_768",
+        "security": 3,
+        "standardized": true
+      }
+    }
+  }
+}
+```
+
+The `build.sh` script:
+1. Parses `algorithms.json` with jq
+2. Dynamically generates CMake flags to build single-algorithm WASM modules
+3. Compiles with Emscripten optimizations (Closure compiler, WASM SIMD)
+4. Outputs standalone `.min.js` files with embedded WASM
+
+**No build script changes needed to add new algorithms** - just update the JSON registry.
+
+### Adding New Algorithms
+
+#### Quick Start
+
+```bash
+# 1. Add algorithm metadata to algorithms.json
+# 2. Create the algorithm wrapper file (see existing files for patterns)
+# 3. Build WASM module
+./build.sh <algorithm-slug>
+
+# 4. Export from src/index.js, src/kem.js, or src/sig.js
+```
+
+#### Key Size Management
+
+The `fetch-key-sizes.js` script extracts key sizes from existing algorithm files and updates `algorithms.json`:
+
+```bash
+node scripts/fetch-key-sizes.js
+# Scans src/algorithms/**/*.js for keySize data
+# Updates algorithms.json with found key sizes
+```
+
+This is useful when:
+- Updating key sizes after LibOQS version changes
+- Ensuring consistency across the codebase
+- Adding new algorithms
+
+#### Steps
+
+1. **Add to `algorithms.json`**: Include the algorithm metadata (slug, cmake_var, security level, key sizes)
+2. **Create wrapper file**: Follow patterns in existing files under `src/algorithms/kem/` or `src/algorithms/sig/`
+3. **Export in index files**: Add to `src/index.js`, `src/kem.js`, or `src/sig.js`
+4. **Add tests**: Follow patterns in `tests/kem.test.ts` or `tests/sig.test.ts`
+5. **Update TypeScript definitions**: If needed, update `src/types/algorithms.d.ts`
+
+All 103 algorithms maintain consistent APIs, documentation, and error handling patterns.
+
+## Testing
+
+The library includes comprehensive test coverage using Vitest:
+
+```bash
+# Run all tests (1400+ tests across 103 algorithms for both node and browser environments)
+bun test
+
+# Or use your preferred package manager
+npm test
+pnpm test
+yarn test
+
+# Or with Deno:
+deno test --allow-read --allow-write --allow-run --allow-env --no-check tests/deno/
+```
+
+Test coverage includes:
+- **Algorithm correctness**: All algorithms tested for basic functionality
+- **Round-trip verification**: KEM encapsulation/decapsulation, signature sign/verify
+- **Key generation**: Validates key sizes match specifications
+- **Cross-environment**: Node.js and browser (jsdom) compatibility
+- **Error handling**: Validates proper error messages and types
+- **Memory safety**: Ensures cleanup via destroy() methods
+- **Edge cases**: Empty messages, invalid signatures, destroyed instances
+
+## Contributing
+
+Contributions are welcome! Please:
+
+- **Tests must pass**: Run `bun run test` (or `npm run test`) and `deno test --allow-read --allow-write --allow-run --allow-env --no-check tests/deno/` before submitting
+- **Follow existing code style**: Use ESM, async/await, JSDoc comments
+- **Document public APIs**: Add comprehensive JSDoc for all exported functions and classes
+- **Security first**: Consider security implications, especially for cryptographic operations
+- **Consistency matters**: Follow established patterns in existing wrappers
+
+For larger changes, open an issue first to discuss the approach.
+
+### Development Workflow
+
+1. Fork the repository
+2. Create a feature branch
+3. Install dependencies: `bun install` (or `npm install`, `pnpm install`, etc.)
+4. Make your changes (add tests if applicable)
+5. Run tests: `bun run test` (or `npm run test`)
+6. Build and test locally
+7. Submit a pull request
+
+### Package Manager Notes
+
+```bash
+# Using bun (recommended/default for contributors)
+bun install
+bun run test
+bun run build
+
+# Using npm
+npm install
+npm run test
+npm run build
+
+# Using pnpm
+pnpm install
+pnpm runtest
+pnpm run build
+
+# Using yarn
+yarn install
+yarn run test
+yarn run build
+```
+
+Contributions that add new algorithm wrappers, improve documentation, add tests, or enhance the build system are especially appreciated.
+
+## Documentation
+
+- **[Security Policy](SECURITY.md)** - Vulnerability reporting and security guidance
+- **[LibOQS Documentation](https://github.com/open-quantum-safe/liboqs)** - Underlying C library
+
+## License
+
+MIT License - see [LICENSE.md](LICENSE.md) for details.
+
+## Acknowledgments
+
+- [Open Quantum Safe](https://openquantumsafe.org/) project for LibOQS
+- [NIST Post-Quantum Cryptography Standardization](https://csrc.nist.gov/Projects/post-quantum-cryptography)
+- The cryptographic research community
+- Emscripten team for excellent WASM tooling
+
+## Versioning
+
+This library's version tracks the bundled LibOQS version:
+- `@oqs/liboqs-js 0.15.x` includes `LibOQS 0.15.0`
+
+## Disclaimer
+
+This library provides access to cryptographic algorithms believed to be quantum-resistant based on current research. The field of post-quantum cryptography is evolving. Algorithm support may change as research advances. Always consult with cryptographic experts for production deployments and follow NIST recommendations.
+
+The LibOQS project states: **"WE DO NOT CURRENTLY RECOMMEND RELYING ON THIS LIBRARY IN A PRODUCTION ENVIRONMENT OR TO PROTECT ANY SENSITIVE DATA."** This guidance applies to this JavaScript/WebAssembly wrapper as well.