rivide

v1.1.5

Published

a month ago

Official Node.js native bindings for Rivide Post-Quantum Cryptography (NIST FIPS 203 ML-KEM & NIST FIPS 204 ML-DSA) C99 Library.

0High
0Medium
0Low

mrvlous

post-quantum pqc ml-kem ml-dsa fips-203 fips-204 kyber dilithium quantum-safe cryptography nist sha3 aes-gcm

Rivide: Post-Quantum Cryptography Node.js Bindings

Rivide for Node.js (rivide) provides high-performance, zero-dependency, ABI-stable Node-API (N-API) native bindings for the Rivide Post-Quantum Cryptography (PQC) C99 library. It implements official NIST FIPS 203 (ML-KEM) and NIST FIPS 204 (ML-DSA) standards with full TypeScript definitions and dual ESM/CommonJS module support.

Key Features

Official NIST Post-Quantum Standards:
- ML-KEM (FIPS 203): Module-Lattice-Based Key Encapsulation Mechanism (ML-KEM-768 and ML-KEM-1024).
- ML-DSA (FIPS 204): Module-Lattice-Based Digital Signature Algorithm (ML-DSA-65 and ML-DSA-87).
Node-API (N-API) C99 Native Engine: ABI-stable across all Node.js versions (Node.js 16, 18, 20, 22, 24+) with zero runtime npm dependencies.
Hardware SIMD Vector Acceleration: Executes native AVX2 (256-bit) and ARM NEON (128-bit) vectorized polynomial math directly in C.
100% TypeScript Coverage: Complete type declarations (index.d.ts) with comprehensive JSDoc hover documentation.
Dual Module Exports (ESM & CommonJS): Works out-of-the-box with import { mlKem768 } from 'rivide' and const { mlKem768 } = require('rivide').
Constant-Time Side-Channel Protection: Built-in constant-time byte comparisons (utils.ctMemcmp).
Volatile Memory Cleansing: Explicit RAM zeroization helper (utils.cleanse) to prevent private key leakage.
Integrated Symmetric Primitives: Native implementations of SHA3-256/512, SHAKE-128/256, and AES-128/256-GCM AEAD.

Installation & Quick Start

1. Installation

Install the package into your Node.js or TypeScript project using your preferred package manager:

# npm
npm install rivide

# pnpm
pnpm add rivide

# yarn
yarn add rivide

2. Building from Source

Clone the repository and compile using node-gyp:

# Clone the repository
git clone https://github.com/mrvlous/rivide.git
cd rivide/bindings/node

# Install dependencies and compile native addon
npm install
npm run build

# Run automated test suite
npm test

# Run performance benchmark suite
npm run bench

Code Tutorials & Usage Examples

Tutorial 1: ML-KEM-768 Quantum-Safe Key Exchange

This tutorial demonstrates post-quantum key encapsulation mechanism (KEM) between Alice and Bob:

import { mlKem768, ctMemcmp, utils, constants } from 'rivide';

// 1. [Alice] Generate ML-KEM-768 keypair
console.log('[Alice] Generating ML-KEM-768 key pair...');
const alice = mlKem768.keypair();
// alice.publicKey  -> Buffer (1184 bytes)
// alice.secretKey -> Buffer (2400 bytes)

// 2. [Bob] Encapsulate a 32-byte shared secret under Alice's public key
console.log("[Bob] Encapsulating shared secret under Alice's public key...");
const bob = mlKem768.encaps(alice.publicKey);
// bob.ciphertext   -> Buffer (1088 bytes)
// bob.sharedSecret -> Buffer (32 bytes)

// 3. [Alice] Decapsulate the ciphertext using her secret key
console.log('[Alice] Decapsulating shared secret from ciphertext...');
const aliceSharedSecret = mlKem768.decaps(bob.ciphertext, alice.secretKey);

// 4. Verify that both shared secrets match in constant-time
if (ctMemcmp(aliceSharedSecret, bob.sharedSecret) === 0) {
    console.log('SUCCESS: Quantum-safe shared secret established!');
} else {
    throw new Error('Shared secret mismatch!');
}

// 5. Securely wipe sensitive private keys from RAM
utils.cleanse(alice.secretKey);
utils.cleanse(aliceSharedSecret);
utils.cleanse(bob.sharedSecret);

Tutorial 2: ML-DSA-65 Digital Signature & Verification

This tutorial demonstrates signing arbitrary payloads and verifying authenticity using ML-DSA-65:

import { mlDsa65, utils } from 'rivide';

// 1. Generate ML-DSA-65 signing keypair
console.log('[Signer] Generating ML-DSA-65 signature key pair...');
const signer = mlDsa65.keypair();
// signer.publicKey  -> Buffer (1952 bytes)
// signer.secretKey -> Buffer (4032 bytes)

// 2. Sign an arbitrary message payload
const message = Buffer.from('Post-quantum signed payload: Approve transaction $50,000 to Alice.');
console.log('[Signer] Signing message payload...');
const signature = mlDsa65.sign(message, signer.secretKey);
// signature -> Buffer (3309 bytes)

// 3. [Verifier] Verify signature authenticity against message and public key
console.log('[Verifier] Verifying digital signature...');
const isValid = mlDsa65.verify(signature, message, signer.publicKey);

if (isValid) {
    console.log('SUCCESS: Signature is VALID and AUTHENTIC!');
} else {
    throw new Error('Signature verification failed!');
}

// 4. Cleanse sensitive private key
utils.cleanse(signer.secretKey);

Tutorial 3: Hybrid PQC + AES-256-GCM Secure Channel

This tutorial demonstrates end-to-end encrypted payload exchange combining ML-KEM-768 with AES-256-GCM AEAD:

import { mlKem768, aesGcm, utils } from 'rivide';

// 1. [Server] Generate ephemeral ML-KEM-768 keypair
const server = mlKem768.keypair();

// 2. [Client] Encapsulate 256-bit symmetric session key
const kem = mlKem768.encaps(server.publicKey);
const sessionKey = kem.sharedSecret; // 32-byte quantum-safe symmetric key

// 3. [Client] Encrypt payload using AES-256-GCM AEAD
const payload = Buffer.from('Confidential financial instructions: Wire transfer confirmed.');
const iv = utils.randombytes(12);
const aad = Buffer.from('Protocol:TLS1.3-Hybrid-PQC');

const encrypted = aesGcm.encrypt256(sessionKey, iv, payload, aad);
// encrypted.ciphertext -> Buffer (same length as payload)
// encrypted.tag        -> Buffer (16 bytes)

// 4. [Server] Decapsulate symmetric key and authenticate/decrypt payload
const serverKey = mlKem768.decaps(kem.ciphertext, server.secretKey);
const decrypted = aesGcm.decrypt256(serverKey, iv, encrypted.ciphertext, encrypted.tag, aad);

console.log('Decrypted Payload:', decrypted.toString('utf8'));

// 5. Cleanse memory
utils.cleanse(server.secretKey);
utils.cleanse(sessionKey);
utils.cleanse(serverKey);

Parameter & Specification Summary

Package Scripts & Automation

The package provides automated npm scripts for development and verification:

API Reference & Namespaces

Namespaces

Buffer Size Constants

import { constants } from 'rivide';

console.log(constants.ML_KEM_768_PK_BYTES); // 1184
console.log(constants.ML_KEM_768_SK_BYTES); // 2400
console.log(constants.ML_KEM_768_CT_BYTES); // 1088
console.log(constants.ML_KEM_768_SS_BYTES); // 32
console.log(constants.ML_DSA_65_PK_BYTES); // 1952
console.log(constants.ML_DSA_65_SK_BYTES); // 4032
console.log(constants.ML_DSA_65_SIG_BYTES); // 3309

Documentation Map

For detailed guides, refer to the package documentation:

License & Maintainers

This project is licensed under the MIT License - see the LICENSE file for details.

Author & Maintainer: Moh. Ananda Firmansyah Putra (@mrvlous)
Maintainers Roster: MAINTAINERS
Contributors & Credits: CREDITS