@vollcrypt/messages-node

Cross-platform, quantum-resistant cryptography engine for Node.js - Native Binding

This package provides the high-performance native Node.js bindings for the Vollcrypt cryptography engine. It is compiled directly from Rust using NAPI-RS, offering maximum performance and utilizing hardware-accelerated instructions (such as AES-NI) where available.

Features

• Blazing Fast: Directly executes native machine code without the overhead of WebAssembly.
• Quantum-Resistant: Implements the NIST FIPS 203 (ML-KEM-768) standard combined with X25519 for hybrid key exchange.
• Secure Defaults: Provides AES-256-GCM, Ed25519, HKDF-SHA256, and post-compromise security ratchets out of the box.
• Cross-Platform: Pre-built native binaries are provided for Windows, macOS (Intel & Apple Silicon), and Linux (glibc & musl).

Installation

npm install @vollcrypt/messages-node

Note: When you install this package, npm will automatically download the correct pre-compiled native binary for your operating system and CPU architecture.

Quick Start

const vollcrypt = require('@vollcrypt/messages-node');

// Generate an Ed25519 Identity Keypair
const identity = vollcrypt.generateEd25519Keypair();
console.log("Public Key:", Buffer.from(identity[1]).toString('hex'));

// Sign and Verify
const message = Buffer.from("Hello from Vollcrypt Native!");
const signature = vollcrypt.signMessage(identity[0], message);
const isValid = vollcrypt.verifySignature(identity[1], message, signature);

console.log("Signature Valid:", isValid); // true

// Replay-safe verification for state-changing or network messages.
// Keep one store per trust domain; do not recreate it for every message.
const messageId = Buffer.from("018f-unique-message-id");
const timestamp = BigInt(Date.now());
const freshSignature = vollcrypt.signFreshMessage(
  identity[0],
  messageId,
  timestamp,
  message,
);
const replayStore = new vollcrypt.ReplayProtectionStore(300_000n, 100_000);
replayStore.verifyAndRecord(
  identity[1],
  messageId,
  timestamp,
  BigInt(Date.now()),
  message,
  freshSignature,
); // true; the same signed message is rejected on its second delivery

// Hybrid Key Exchange (X25519)
const alice = vollcrypt.generateX25519Keypair();
const bob = vollcrypt.generateX25519Keypair();
const sharedSecret = vollcrypt.ecdhSharedSecret(alice[0], bob[1]);

console.log("Shared Secret Derived successfully.");

Replay Safety

The raw verifySignature API verifies Ed25519 authenticity only; it is intentionally stateless and cannot detect replay by itself. Any message that changes application state must use signFreshMessage and ReplayProtectionStore.verifyAndRecord, with receiver-controlled current time. Persist replay state, or reconstruct it from a durable message ledger, when replay protection must survive process restarts.

Documentation

For full API documentation, architecture details, and the WebAssembly equivalent, please refer to the Vollcrypt Main Repository.

License

This project is dual-licensed under:

• GPL-3.0-only (for open-source distribution) — see the LICENSE-GPL file.
• Commercial License (for proprietary software integrations) — see the LICENSE-COMMERCIAL.md file.

For inquiries regarding commercial license purchases, pricing tiers, or custom enterprise terms, please contact Berat Vural at [email protected].