Package Exports

libsilver-nodejs
libsilver-nodejs/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (libsilver-nodejs) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

LibSilver Node.js Bindings

High-performance cryptography library for Node.js, built with Rust and RustCrypto.

🚀 Features

Post-Quantum Cryptography: ML-KEM (Key Encapsulation) and ML-DSA (Digital Signatures) - NIST standardized algorithms
Symmetric Encryption: AES-256-GCM (RustCrypto + AWS-LC-RS), ChaCha20-Poly1305
Asymmetric Encryption: RSA-OAEP (2048+ bit keys)
Digital Signatures: ECDSA P-256, Ed25519, ML-DSA (Post-Quantum)
Key Encapsulation: ML-KEM (Post-Quantum Key Exchange)
Cryptographic Hashing: SHA-256, SHA-512, BLAKE3, HMAC
Key Derivation Functions: Argon2, HKDF, PBKDF2
Secure Random Generation: OS-backed cryptographically secure random number generation
Memory Safety: Automatic zeroization of sensitive data
Cross-Platform: Works on Windows (x64/ARM64), macOS (Intel/ARM64), and Linux (via CI/CD)
TypeScript Support: Full TypeScript definitions included

📦 Installation

npm install libsilver-nodejs

🔧 Quick Start

const {
  SymmetricCrypto, AwsLcAesCrypto, AsymmetricCrypto, HashFunctions, KeyDerivation, RandomGenerator,
  MlKem768Crypto, MlDsa65Crypto  // Post-Quantum Cryptography
} = require('libsilver-nodejs');

// Symmetric encryption
const key = SymmetricCrypto.generateAesKey();
const plaintext = Buffer.from('Hello, World!', 'utf8');
const ciphertext = SymmetricCrypto.encryptAes(plaintext, key);
const decrypted = SymmetricCrypto.decryptAes(ciphertext, key);

console.log('Decrypted:', decrypted.toString('utf8')); // "Hello, World!"

// Post-Quantum Key Encapsulation (ML-KEM-768)
const kemKeypair = MlKem768Crypto.generateKeypair();
const encapsulation = MlKem768Crypto.encapsulate(kemKeypair.publicKeyBytes);
const sharedSecret = MlKem768Crypto.decapsulate(encapsulation.ciphertext, kemKeypair.privateKeyBytes);

console.log('Post-quantum shared secret established!');

📚 API Documentation

Post-Quantum Cryptography

LibSilver provides NIST-standardized post-quantum cryptographic algorithms to protect against quantum computer attacks.

NIST Security Levels

Security Level	Classical Security	Quantum Security	Key Sizes	Performance	Recommended Use
Level 1	AES-128	Grover's algorithm	Smallest	Fastest	IoT, embedded systems
Level 3	AES-192	Grover's algorithm	Medium	Balanced	General purpose (recommended)
Level 5	AES-256	Grover's algorithm	Largest	Slowest	High-security applications

ML-KEM (Key Encapsulation Mechanism)

ML-KEM provides quantum-resistant key exchange. Three security levels are available:

ML-KEM-512 (NIST Level 1)

const { MlKem512Crypto } = require('libsilver-nodejs');

// Generate key pair
const keypair = MlKem512Crypto.generateKeypair();

// Encapsulate shared secret
const encapsulation = MlKem512Crypto.encapsulate(keypair.publicKeyBytes);

// Decapsulate shared secret
const sharedSecret = MlKem512Crypto.decapsulate(
  encapsulation.ciphertext,
  keypair.privateKeyBytes
);

// Get size constants
const sizes = MlKem512Crypto.getSizes();
console.log('Public key size:', sizes.publicKeySize);
console.log('Private key size:', sizes.privateKeySize);
console.log('Ciphertext size:', sizes.ciphertextSize);
console.log('Shared secret size:', sizes.sharedSecretSize);

ML-KEM-768 (NIST Level 3) - Recommended

const { MlKem768Crypto } = require('libsilver-nodejs');

// Same API as ML-KEM-512, but with higher security level
const keypair = MlKem768Crypto.generateKeypair();
const encapsulation = MlKem768Crypto.encapsulate(keypair.publicKeyBytes);
const sharedSecret = MlKem768Crypto.decapsulate(
  encapsulation.ciphertext,
  keypair.privateKeyBytes
);

ML-KEM-1024 (NIST Level 5)

const { MlKem1024Crypto } = require('libsilver-nodejs');

// Same API as ML-KEM-512, but with highest security level
const keypair = MlKem1024Crypto.generateKeypair();
const encapsulation = MlKem1024Crypto.encapsulate(keypair.publicKeyBytes);
const sharedSecret = MlKem1024Crypto.decapsulate(
  encapsulation.ciphertext,
  keypair.privateKeyBytes
);

ML-DSA (Digital Signature Algorithm)

ML-DSA provides quantum-resistant digital signatures. Three security levels are available:

ML-DSA-44 (NIST Level 2)

const { MlDsa44Crypto } = require('libsilver-nodejs');

// Generate key pair
const keypair = MlDsa44Crypto.generateKeypair();

// Sign message
const message = Buffer.from('Hello, post-quantum world!', 'utf8');
const signature = MlDsa44Crypto.sign(message, keypair.privateKeyBytes);

// Verify signature
const isValid = MlDsa44Crypto.verify(message, signature, keypair.publicKeyBytes);

// Get size constants
const sizes = MlDsa44Crypto.getSizes();
console.log('Public key size:', sizes.publicKeySize);
console.log('Private key size:', sizes.privateKeySize);
console.log('Max signature size:', sizes.maxSignatureSize);

ML-DSA-65 (NIST Level 3) - Recommended

const { MlDsa65Crypto } = require('libsilver-nodejs');

// Same API as ML-DSA-44, but with higher security level
const keypair = MlDsa65Crypto.generateKeypair();
const signature = MlDsa65Crypto.sign(message, keypair.privateKeyBytes);
const isValid = MlDsa65Crypto.verify(message, signature, keypair.publicKeyBytes);

ML-DSA-87 (NIST Level 5)

const { MlDsa87Crypto } = require('libsilver-nodejs');

// Same API as ML-DSA-44, but with highest security level
const keypair = MlDsa87Crypto.generateKeypair();
const signature = MlDsa87Crypto.sign(message, keypair.privateKeyBytes);
const isValid = MlDsa87Crypto.verify(message, signature, keypair.publicKeyBytes);

Hybrid Encryption Example

Combine ML-KEM with symmetric encryption for secure communication:

const { MlKem768Crypto, SymmetricCrypto } = require('libsilver-nodejs');

// Alice generates key pair
const aliceKeypair = MlKem768Crypto.generateKeypair();

// Bob wants to send encrypted message to Alice
const message = Buffer.from('Confidential message', 'utf8');

// Bob encapsulates shared secret using Alice's public key
const encapsulation = MlKem768Crypto.encapsulate(aliceKeypair.publicKeyBytes);

// Bob encrypts message with shared secret
const encryptedMessage = SymmetricCrypto.encryptAes(message, encapsulation.sharedSecret);

// Alice decapsulates shared secret
const aliceSharedSecret = MlKem768Crypto.decapsulate(
  encapsulation.ciphertext,
  aliceKeypair.privateKeyBytes
);

// Alice decrypts message
const decryptedMessage = SymmetricCrypto.decryptAes(encryptedMessage, aliceSharedSecret);

Symmetric Encryption

AES-256-GCM (Default - AWS-LC-RS)

const { SymmetricCrypto } = require('libsilver-nodejs');

// Basic encryption/decryption (uses AWS-LC-RS by default)
const key = SymmetricCrypto.generateAesKey();
const plaintext = Buffer.from('Hello, World!', 'utf8');
const ciphertext = SymmetricCrypto.encryptAes(plaintext, key);
const decrypted = SymmetricCrypto.decryptAes(ciphertext, key);

// With Additional Authenticated Data (AAD)
const aad = Buffer.from('user_id:12345,session:abc123', 'utf8');
const ciphertextWithAad = SymmetricCrypto.encryptAesWithAad(plaintext, key, aad);
const decryptedWithAad = SymmetricCrypto.decryptAesWithAad(ciphertextWithAad, key, aad);

// With fixed nonce (for testing only)
const nonce = Buffer.alloc(12, 0x42);
const deterministicCiphertext = SymmetricCrypto.encryptAesWithNonce(plaintext, key, nonce);

Default Benefits (AWS-LC-RS):

🚀 5-20x faster than RustCrypto AES-GCM
🔒 FIPS 140-2 Level 1 validated cryptography
⚡ Hardware acceleration (AES-NI support)
🏷️ AAD support for additional authentication

AES-256-GCM (AWS-LC-RS Explicit)

const { AwsLcAesCrypto } = require('libsilver-nodejs');

// Same as SymmetricCrypto but explicitly using AWS-LC-RS
const key = AwsLcAesCrypto.generateKey();
const ciphertext = AwsLcAesCrypto.encrypt(plaintext, key);
const decrypted = AwsLcAesCrypto.decrypt(ciphertext, key);

AES-256-GCM (RustCrypto Alternative)

const { RustCryptoAesCrypto } = require('libsilver-nodejs');

// For users who specifically want RustCrypto implementation
const key = RustCryptoAesCrypto.generateKey();
const ciphertext = RustCryptoAesCrypto.encrypt(plaintext, key);
const decrypted = RustCryptoAesCrypto.decrypt(ciphertext, key);

// RustCrypto also supports AAD
const ciphertextWithAad = RustCryptoAesCrypto.encryptWithAad(plaintext, key, aad);
const decryptedWithAad = RustCryptoAesCrypto.decryptWithAad(ciphertextWithAad, key, aad);

ChaCha20-Poly1305

const key = SymmetricCrypto.generateChacha20Key();
const ciphertext = SymmetricCrypto.encryptChacha20(plaintext, key);
const decrypted = SymmetricCrypto.decryptChacha20(ciphertext, key);

Asymmetric Encryption

RSA-OAEP

const keypair = AsymmetricCrypto.generateRsaKeypair();
const ciphertext = AsymmetricCrypto.encryptRsa(plaintext, keypair.publicKeyPem);
const decrypted = AsymmetricCrypto.decryptRsa(ciphertext, keypair.privateKeyPem);

Digital Signatures

Ed25519

const keypair = AsymmetricCrypto.generateEd25519Keypair();
const signature = AsymmetricCrypto.signEd25519(message, keypair.signingKeyBytes);
const isValid = AsymmetricCrypto.verifyEd25519(message, signature, keypair.verifyingKeyBytes);

ECDSA P-256

const keypair = AsymmetricCrypto.generateEcdsaKeypair();
const signature = AsymmetricCrypto.signEcdsa(message, keypair.signingKeyBytes);
const isValid = AsymmetricCrypto.verifyEcdsa(message, signature, keypair.verifyingKeyBytes);

Cryptographic Hashing

// SHA-256
const hash = HashFunctions.sha256(data);
const hexHash = HashFunctions.sha256Hex(data);

// BLAKE3
const blake3Hash = HashFunctions.blake3(data);
const customLengthHash = HashFunctions.blake3WithLength(data, 64);

// HMAC
const mac = HashFunctions.hmacSha256(key, message);
const isValid = HashFunctions.verifyHmacSha256(key, message, mac);

Key Derivation Functions

// Argon2 (recommended for password hashing)
const salt = RandomGenerator.generateSalt();
const key = KeyDerivation.argon2(password, salt, 32);

// PBKDF2
const pbkdf2Key = KeyDerivation.pbkdf2Sha256(password, salt, 100000, 32);

// HKDF (for key expansion)
const hkdfKey = KeyDerivation.hkdfSha256(inputKey, salt, info, 32);

Secure Random Generation

const randomBytes = RandomGenerator.generateBytes(32);
const secureKey = RandomGenerator.generateKey(32);
const nonce = RandomGenerator.generateNonce(12);
const salt = RandomGenerator.generateSalt();

🛡️ Security Features

Post-Quantum Security: NIST-standardized ML-KEM and ML-DSA algorithms protect against quantum computer attacks
Memory Safety: All sensitive data is automatically zeroized when no longer needed
Secure Defaults: Uses secure parameters and algorithms by default
Constant-Time Operations: Leverages RustCrypto's constant-time implementations
No Unsafe Code: Pure safe Rust implementation with secure FFI bindings
Audited Dependencies: Built on well-audited RustCrypto crates and NIST reference implementations

🏗️ Building from Source

# Clone the repository
git clone https://github.com/DangVTNhan/libsilver.git
cd libsilver

# Install dependencies
npm install

# Build the native module
npm run build

# Run tests
npm test

# Run examples
npm run example                    # Basic cryptography examples
npm run example:post-quantum       # Post-quantum cryptography examples
node examples/aws-lc-aes-example.js  # AWS-LC-RS AES performance demo

🧪 Testing

# Run basic tests
npm test

# Run post-quantum cryptography tests
npm run test:post-quantum

# Run all comprehensive tests
npm run test:all

# Run specific test suites
npm run test:basic          # Basic cryptography tests
npm run test:integration    # Integration tests
npm run test:performance    # Performance benchmarks

🖥️ Platform Support

Platform	Architecture	Status	Notes
macOS	ARM64 (M1/M2)	✅	Native compilation
macOS	Intel x64	✅	Cross-compilation
Windows	x64	✅	Cross-compilation
Windows	ARM64	✅	Cross-compilation
Linux	x64	⚠️	CI/CD builds
Linux	ARM64	⚠️	CI/CD builds

Pre-built binaries are available for all supported platforms via npm.

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

LibSilver Core - The main Rust library
LibSilver Swift - Swift bindings
LibSilver Kotlin - Kotlin/Android bindings