oqs.js: Node.js bindings for liboqs

Post-quantum cryptography for Node.js with automatic liboqs build. No system dependencies—fully reproducible install—just run npm install! Currently supports KEM (Key Encapsulation Mechanisms) APIs (not yet signature APIs).

Supported Platforms

• macOS (x64/arm64)
• Linux (x64/arm64, most distros)
• (Windows: Not yet supported)

Installation

npm install oqs.js

On first install, liboqs will be automatically cloned, built, and native addon compiled.

Usage

const oqs = require('oqs.js');

// List available KEM algorithms
console.log(oqs.listKEMs()); // e.g. ['Kyber512', ...]

const alg = oqs.listKEMs()[0];
const { publicKey, secretKey } = oqs.kemKeypair(alg);
const { ciphertext, sharedSecret } = oqs.encapsulate(alg, publicKey);
const recoveredSecret = oqs.decapsulate(alg, ciphertext, secretKey);
console.log('Shared secrets match:', sharedSecret.equals(recoveredSecret));

API Reference

All functions throw if given invalid arguments or data of the wrong length/type.

oqs.listKEMs() : string[]

List all enabled KEM algorithm names (e.g. 'Kyber512', ...).

oqs.kemKeypair(algorithm: string) : { publicKey: Buffer, secretKey: Buffer }

Generate a KEM keypair for the specified algorithm name.

oqs.encapsulate(algorithm: string, publicKey: Buffer) : { ciphertext: Buffer, sharedSecret: Buffer }

Generate a ciphertext and encapsulated secret for the provided algorithm/public key.

oqs.decapsulate(algorithm: string, ciphertext: Buffer, secretKey: Buffer) : Buffer

Recover the shared secret using private key and ciphertext for the given algorithm.

How it Works

• Installs liboqs from source via CMake at npm install time, then builds Node native binding.
• Does not require pre-installed system dependencies except C++ build tools (git, cmake, make).

Troubleshooting

• Build time depends on your CPU/network (~1-3min typical).
• Not yet available for Windows (PRs welcome).

Contributing & Development

Tests use Node's core assert:

node test/basic.js

License

MIT