oqs.js/README.md


# oqs.js: Node.js bindings for [liboqs](https://open-quantum-safe.org)

![N-API](https://img.shields.io/badge/node--api-stable-brightgreen)

Post-quantum cryptography for Node.js with automatic [liboqs](https://github.com/open-quantum-safe/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

```sh
npm install oqs.js
```

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

---

## Usage

```js
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`:

```sh
node test/basic.js
```

---

## License
MIT