@scintilla-network/ciphers

Simple, secure encryption for JavaScript. Easy nonce management - just encrypt and decrypt!

Features

• XChaCha20-Poly1305 — Recommended for most use cases (safe with random nonces)

• AES-GCM — Industry standard, widely supported

• ChaCha20-Poly1305 — Used in TLS 1.3.

• Simplified nonce management — Library handles nonces automatically (still allows for custom nonces)

• Audited implementations — Built on battle-tested noble-ciphers

• Zero dependencies beyond noble

• 256-bit security — Post-quantum resistant (Grover's algorithm only gives a quadratic speedup)

Installation

npm install @scintilla-network/ciphers

Usage

Quick Start (Recommended algorithm: xchacha20 - most secure)

import { xchacha20, utils } from '@scintilla-network/ciphers';

// Generate a random key
const key = utils.randomBytes(32);
// Convert the message to a Uint8Array
const message = new TextEncoder().encode("Hello World!");

// Encrypt (output is prepended with the nonce)
const encrypted = xchacha20.encrypt(message, key);

// Decrypt
const decrypted = xchacha20.decrypt(encrypted, key);
console.log(new TextDecoder().decode(decrypted)); // "Hello World!"

All Available Ciphers

import { xchacha20, aesgcm, chacha20, utils } from '@scintilla-network/ciphers';

const key = utils.randomBytes(32);
const message = new TextEncoder().encode("Secret message");

// XChaCha20-Poly1305 (recommended - safe with random nonces)
const encrypted1 = xchacha20.encrypt(message, key);
const decrypted1 = xchacha20.decrypt(encrypted1, key);

// AES-GCM (industry standard)
const encrypted2 = aesgcm.encrypt(message, key);
const decrypted2 = aesgcm.decrypt(encrypted2, key);

// ChaCha20-Poly1305 (TLS 1.3 standard)
const encrypted3 = chacha20.encrypt(message, key);
const decrypted3 = chacha20.decrypt(encrypted3, key);

Custom Nonces (Advanced)

import { xchacha20, utils } from '@scintilla-network/ciphers';

const key = utils.randomBytes(32);
const message = new TextEncoder().encode("Hello World!");

// Provide your own nonce if needed
const customNonce = utils.randomBytes(24); // XChaCha20 uses 24-byte nonces
const encrypted = xchacha20.encrypt(message, key, customNonce).slice(24); // We slice the nonce off from the encrypted data
const decrypted = xchacha20.decrypt(encrypted, key, customNonce);

Why XChaCha20-Poly1305?

XChaCha20-Poly1305 is recommended for most applications because:

• Safe with random nonces - No need to track nonce uniqueness
• Large nonce space - 24 bytes means virtually no collision risk
• Fast performance - Often faster than AES in JavaScript
• Modern design - Built for today's security needs

When to use others:

• AES-GCM: When you need maximum compatibility or hardware acceleration
• ChaCha20-Poly1305: When building TLS 1.3 compatible systems (is standardized in TLS 1.3)

Related Packages

• @scintilla-network/hashes: Hashes, KDFs, utilities
• @scintilla-network/signatures: Signatures and key exchange
• @scintilla-network/mnemonic: Mnemonics phrase generation and derivation

License

MIT License - see the LICENSE file for details

Credits

This library builds upon the excellent work of:

• noble-ciphers by Paul Miller