@oqs/liboqs-js

A JavaScript/TypeScript wrapper for 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 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 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:

• 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).

• 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)

See algorithms.json for the complete algorithm registry, or the algorithms section. All 103 algorithms have WASM modules, JavaScript wrappers, TypeScript definitions, and test coverage.

Installation

This package works with all major JavaScript package managers:

# 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:

// 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:

{
  "imports": {
    "liboqs": "npm:@oqs/liboqs-js@^0.15.1"
  }
}

Then import like:

import { createMLKEM768 } from "liboqs";

Using the CLI with Deno:

# 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

# Or add to deno.json tasks:
{
  "tasks": {
    "liboqs": "deno run --allow-read npm:@oqs/liboqs-js/cli"
  }
}

# Then run:
deno task liboqs list --kem

Permissions:

# 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:

# 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:

npx @oqs/liboqs-js --help

Key Encapsulation (ML-KEM)

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)

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:

// 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

// 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

// 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 for our vulnerability disclosure policy. Issues specific to the LibOQS C library should be reported to the LibOQS project.

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

# 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:

{
  "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

# 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:

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:

# 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

# 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 - Vulnerability reporting and security guidance
• LibOQS Documentation - Underlying C library

License

MIT License - see LICENSE.md for details.

Acknowledgments

• Open Quantum Safe project for LibOQS
• NIST Post-Quantum Cryptography Standardization
• 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.1

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.