@brashkie/signalis-core 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,77 @@ All notable changes to `@brashkie/signalis-core` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] — 2026-06-17
+
+### ✨ Added — Multi-Platform Expansion + New Primitives
+
+**Focus: Android support + AEAD alternative for ARM-heavy deployments.**
+
+#### 🆕 New crates
+- **`sc-chacha20poly1305`** — RFC 8439 ChaCha20-Poly1305 AEAD
+  - Encrypt/decrypt with optional AAD
+  - Same API shape as `sc-aes`'s GCM helpers
+  - 2-3× faster than AES-GCM on ARM without AES-NI hardware
+  - Full RFC 8439 test vector compliance
+- **`sc-utils`** — public utility helpers
+  - `secure_random(buf)` / `random_bytes(size)` — OS-backed CSPRNG
+  - `constant_time_eq(a, b)` — timing-safe comparison
+  - `secure_zeroize(buf)` — guaranteed-not-elided buffer wipe
+  - 16 MiB cap on single random allocation (DoS guard)
+
+#### 🆕 New build targets
+- ✅ `aarch64-linux-android` — Android arm64-v8a (React Native, Termux, modern phones)
+- ✅ `armv7-linux-androideabi` — Android armv7 (older devices, IoT)
+
+#### 🆕 Public JS API
+- `ChaCha20Poly1305` namespace mirroring `AES_GCM`:
+  - `.encrypt(key, nonce, plaintext)`
+  - `.decrypt(key, nonce, ciphertext)`
+  - `.encryptWithAad(key, nonce, plaintext, aad)`
+  - `.decryptWithAad(key, nonce, ciphertext, aad)`
+  - Constants: `KEY_SIZE`, `NONCE_SIZE`, `TAG_SIZE`
+- `constantTimeEq(a, b)` — timing-safe Buffer comparison
+- `nativeSecureRandom(size)` — OS-backed CSPRNG via the native side
+
+#### 🆕 CI
+- `cargo-audit` pre-merge gate (fails PRs introducing vulnerable transitive deps)
+- Build matrix now includes both Android targets
+
+### 🔄 Changed
+- Workspace `Cargo.toml`: added `chacha20poly1305 = "0.10"` to shared deps
+- `sc-node` re-exports new primitives + helpers from the new crates
+- `package.json` lists `android-arm64` + `android-arm-eabi` as optional sub-packages
+
+### ✅ Compatibility
+**100% backwards compatible with v0.2.0.** All existing APIs (`Curve25519`,
+`Ed25519`, `XEd25519`, `HKDF`, `AES_GCM`, `AES_CBC`, `HMAC`, `SHA256`) are
+unchanged. `signalis@0.6.0` (the TypeScript Signal Protocol wrapper) continues
+to work without modifications.
+
+### 📦 New install footprint (Android)
+
+```bash
+npm i @brashkie/signalis-core
+# On Android (Termux / React Native), npm/yarn will automatically pull:
+#   @brashkie/signalis-core-android-arm64   (or)
+#   @brashkie/signalis-core-android-arm-eabi
+```
+
+### 🔒 Security
+- All new code follows the same audit-friendly patterns as v0.2.0
+- ChaCha20-Poly1305 backed by RustCrypto's `chacha20poly1305@0.10`
+- `secure_random` panics (not silently degrades) if OS RNG is unavailable
+- `constant_time_eq` backed by `subtle@2.5`
+- `secure_zeroize` backed by `zeroize@1.7`
+
+### 📋 What's next (v0.4.0)
+- iOS arm64 target
+- WASM target (browsers, via `wasm-bindgen`)
+- PBKDF2 + Argon2id (for the upcoming `signalis-vault` package)
+- Benchmark suite (criterion)
+
+---
+
 ## [0.2.0] — 2026-05-22
 
 ### ✨ Added

package/README.es.md

@@ -32,25 +32,94 @@ Construida con **Rust** para seguridad y velocidad, expuesta a Node.js mediante
 
 ---
 
-## 🎉 Novedades en v0.2.0
+## 🎉 Novedades en v0.3.0
 
-**v0.2.0 introduce firmas digitales y cifrado autenticado con AAD — totalmente retrocompatible con v0.1.0.**
+**v0.3.0 trae soporte Android + ChaCha20-Poly1305 — totalmente retrocompatible con v0.2.0.**
 
 | Nuevo | Descripción |
 |-------|-------------|
-| 🆕 **Ed25519** | Firmas digitales estándar (RFC 8032) — determinísticas |
-| 🆕 **XEd25519** | Firmas estilo Signal con llaves Curve25519 — una llave de identidad para ECDH + firmar |
-| 🆕 **AES-GCM con AAD** | Datos Autenticados Adicionales para vincular metadatos al cifrado |
-| 🆕 **SignatureError** | Nueva clase de error tipada para fallos de firma |
-| 🆕 **Tipo Signature** | Tipo branded con helper `asSignature()` |
+| 🆕 **Android arm64-v8a** | Binario nativo para celulares Android modernos (React Native, Termux) |
+| 🆕 **Android armv7** | Binario nativo para dispositivos Android más viejos (Android 4.4+) |
+| 🆕 **ChaCha20-Poly1305** | AEAD según RFC 8439 — 2-3× más rápido que AES-GCM en ARM sin AES-NI |
+| 🆕 **`constantTimeEq()`** | Comparación de Buffer en tiempo constante (para verificar MAC/firmas) |
+| 🆕 **`nativeSecureRandom()`** | CSPRNG basado en OS vía Rust (alternativa a `secureRandom` JS-side) |
+| 🆕 **Crate `sc-utils`** | Helpers utilitarios públicos (random, constant_time_eq, secure_zeroize) |
+| 🆕 **CI: gate cargo-audit** | Dependencias transitivas vulnerables ahora bloquean PRs automáticamente |
+
+### Ejemplo rápido: ChaCha20-Poly1305
+
+```ts
+import { ChaCha20Poly1305, secureRandom } from '@brashkie/signalis-core';
+
+const key = secureRandom(32);
+const nonce = secureRandom(12);
+
+const ct = ChaCha20Poly1305.encrypt(key, nonce, Buffer.from('¡Hola!'));
+const pt = ChaCha20Poly1305.decrypt(key, nonce, ct);  // → "¡Hola!"
+
+// Con Datos Autenticados Adicionales
+const aad = Buffer.from('metadata del header');
+const ct2 = ChaCha20Poly1305.encryptWithAad(key, nonce, plaintext, aad);
+const pt2 = ChaCha20Poly1305.decryptWithAad(key, nonce, ct2, aad);
+```
+
+### ¿Por qué usar ChaCha20-Poly1305 en lugar de AES-GCM?
+
+Usá **AES-GCM** cuando corras en:
+- Servidores x86_64 (Intel/AMD con hardware AES-NI)
+- Desktops modernos
+- CPUs ARM nuevos con Extensiones Cripto ARMv8
+
+Usá **ChaCha20-Poly1305** cuando corras en:
+- Celulares Android (la mayoría no tiene AES-NI)
+- IoT / dispositivos embebidos
+- Cualquier cosa sin hardware AES acelerado
+
+**Ambos tienen garantías de seguridad idénticas.** La diferencia es puramente de rendimiento, dependiendo de si tu target tiene hardware AES.
 
 Ver [MIGRATION.md](./MIGRATION.md) para detalles de upgrade (es un drop-in replacement).
 
 ---
 
+## 🌍 Plataformas Soportadas
+
+`@brashkie/signalis-core` envía binarios nativos pre-compilados para **9 plataformas** vía `optionalDependencies` de npm. El binario correcto se descarga automáticamente según tu sistema operativo + arquitectura.
+
+| SO | Arquitectura | Sub-paquete | Estado |
+|----|--------------|-------------|--------|
+| 🐧 Linux | x64 (glibc) | `signalis-core-linux-x64-gnu` | ✅ |
+| 🐧 Linux | x64 (musl) | `signalis-core-linux-x64-musl` | ✅ |
+| 🐧 Linux | arm64 (glibc) | `signalis-core-linux-arm64-gnu` | ✅ |
+| 🍎 macOS | x64 (Intel) | `signalis-core-darwin-x64` | ✅ |
+| 🍎 macOS | arm64 (Apple Silicon) | `signalis-core-darwin-arm64` | ✅ |
+| 🪟 Windows | x64 | `signalis-core-win32-x64-msvc` | ✅ |
+| 🪟 Windows | arm64 | `signalis-core-win32-arm64-msvc` | ✅ |
+| 🤖 Android | arm64-v8a | `signalis-core-android-arm64` | 🆕 v0.3.0 |
+| 🤖 Android | armv7 | `signalis-core-android-arm-eabi` | 🆕 v0.3.0 |
+
+Próximas plataformas en v0.4.0: **iOS arm64**, **WASM (navegadores)**, **FreeBSD x64**.
+
+### Instalación en Android
+
+El mismo `npm install` funciona en cualquier entorno Node.js corriendo en Android, incluyendo:
+- **Termux** en celulares Android (`pkg install nodejs`)
+- **React Native** con target Android
+- Apps con **NodeJS-Mobile**
+- Builds personalizados de Node embebido para IoT
+
+```bash
+# En Android (Termux por ejemplo):
+pkg install nodejs
+npm install @brashkie/signalis-core
+# → npm descarga automáticamente signalis-core-android-arm64
+```
+
+---
+
 ## 📋 Tabla de Contenido
 
 - [Características](#-características)
+- [Plataformas Soportadas](#-plataformas-soportadas)
 - [¿Por qué Signalis Core?](#-por-qué-signalis-core)
 - [Instalación](#-instalación)
 - [Inicio Rápido](#-inicio-rápido)
@@ -79,7 +148,7 @@ Ver [MIGRATION.md](./MIGRATION.md) para detalles de upgrade (es un drop-in repla
 | 📦 **Paquete Dual** | Funciona en proyectos CommonJS, ESM y TypeScript |
 | 🎯 **Tipado Estricto** | Definiciones TypeScript completas con tipos branded y clases de error |
 | ✅ **Vectores de Test** | Validado contra RFC 5869, RFC 7748, RFC 8032, RFC 4231 y vectores NIST |
-| 🌍 **Multi-Plataforma** | Binarios pre-compilados para Windows, macOS, Linux (x64, ARM) |
+| 🌍 **Multi-Plataforma** | Binarios pre-compilados para Windows, macOS, Linux (x64, ARM) + **Android arm64/armv7** |
 | 🔒 **Tiempo Constante** | Comparaciones resistentes a side-channel via crate `subtle` |
 | 🧹 **Auto-Borrado** | Secretos se borran de memoria automáticamente |
 | 📊 **Cobertura 99%+** | Suite de tests con 269+ aserciones |
@@ -392,6 +461,43 @@ if (HMAC.verifySha256(macKey, concat([iv, ct]), tag)) {
 }
 ```
 
+### ChaCha20-Poly1305 🆕
+
+Cifrado autenticado según RFC 8439. Alternativa a AES-GCM, más rápido en ARM sin AES-NI.
+
+```typescript
+import { ChaCha20Poly1305, secureRandom } from '@brashkie/signalis-core';
+
+const clave = secureRandom(32);    // ChaCha20Poly1305.KEY_SIZE
+const nonce = secureRandom(12);    // ChaCha20Poly1305.NONCE_SIZE
+
+// Cifrado/descifrado básico (sin AAD)
+const ct = ChaCha20Poly1305.encrypt(clave, nonce, textoplano);
+const pt = ChaCha20Poly1305.decrypt(clave, nonce, ct);
+
+// Con Datos Autenticados Adicionales
+const aad = Buffer.from('header público');
+const ct2 = ChaCha20Poly1305.encryptWithAad(clave, nonce, textoplano, aad);
+const pt2 = ChaCha20Poly1305.decryptWithAad(clave, nonce, ct2, aad);
+
+// Constantes
+ChaCha20Poly1305.KEY_SIZE;     // 32
+ChaCha20Poly1305.NONCE_SIZE;   // 12
+ChaCha20Poly1305.TAG_SIZE;     // 16 (anexado al ciphertext)
+```
+
+**Rendimiento vs AES-GCM:**
+
+| Target | Ganador | Por qué |
+|--------|---------|---------|
+| Server x86_64 (AES-NI) | AES-GCM | Aceleración por hardware |
+| Desktop moderno (AES-NI) | AES-GCM | Aceleración por hardware |
+| Android arm64 (sin ARMv8 crypto) | **ChaCha20-Poly1305** | CPU puro, ChaCha es más rápido |
+| IoT / embebido | **ChaCha20-Poly1305** | No requiere hardware AES |
+| Apple Silicon (serie M) | Cualquiera (parejos) | Ambos bien optimizados |
+
+**Seguridad:** ChaCha20-Poly1305 y AES-GCM tienen propiedades de seguridad equivalentes. La decisión es puramente sobre rendimiento en tu target.
+
 ### HMAC-SHA256
 
 Autenticación de mensajes.
@@ -433,7 +539,9 @@ import {
   fromBase64Url,
 
   // Seguridad
-  constantTimeEqual,  // (a, b) → boolean (timing-safe)
+  constantTimeEqual,    // (a, b) → boolean (timing-safe, JS-side)
+  constantTimeEq,       // 🆕 v0.3.0 — igual pero vía Rust side
+  nativeSecureRandom,   // 🆕 v0.3.0 — CSPRNG del OS vía Rust (vs node:crypto)
 
   // Operaciones Buffer
   concat,          // (buffers[]) → Buffer
@@ -442,6 +550,14 @@ import {
 } from '@brashkie/signalis-core';
 ```
 
+#### ¿Cuándo usar `constantTimeEq` vs `constantTimeEqual`?
+
+Ambos comparan en tiempo constante. `constantTimeEqual` usa la semántica de `Buffer.compare` de JavaScript (implementación JS-side). `constantTimeEq` (v0.3.0) pasa por la crate auditada `subtle::ConstantTimeEq` de Rust. Las dos son seguras — usá `constantTimeEq` si querés asegurarte de que tu camino timing-safe sea el mismo que usa el resto de la librería internamente.
+
+#### ¿Cuándo usar `nativeSecureRandom` vs `secureRandom`?
+
+`secureRandom(n)` usa `crypto.randomBytes()` de Node. `nativeSecureRandom(n)` (v0.3.0) pasa por `OsRng` de Rust (que llama directamente a `getrandom`/`BCryptGenRandom`/`SecRandomCopyBytes`). Ambos son criptográficamente seguros. Usá `nativeSecureRandom` si querés una sola superficie de auditoría para entropía en todo tu stack.
+
 ### Errores
 
 Todos los errores extienden `SignalisError`:

package/README.md

@@ -32,27 +32,96 @@ Built with **Rust** for safety and speed, exposed to Node.js via [napi-rs](https
 
 ---
 
-## 🎉 What's New in v0.2.0
+## 🎉 What's New in v0.3.0
 
-**v0.2.0 introduces digital signatures and AAD authenticated encryption — fully backwards compatible with v0.1.0.**
+**v0.3.0 ships Android support + ChaCha20-Poly1305 — fully backwards compatible with v0.2.0.**
 
 | New | Description |
 |-----|-------------|
-| 🆕 **Ed25519** | Standard digital signatures (RFC 8032) — deterministic |
-| 🆕 **XEd25519** | Signal-style signing with Curve25519 keys — one identity key for ECDH + signing |
-| 🆕 **AES-GCM with AAD** | Additional Authenticated Data for binding metadata to ciphertext |
-| 🆕 **SignatureError** | New typed error class for signature failures |
-| 🆕 **Signature type** | Branded type with `asSignature()` helper |
+| 🆕 **Android arm64-v8a** | Native binary for modern Android phones (React Native, Termux) |
+| 🆕 **Android armv7** | Native binary for older Android devices (Android 4.4+) |
+| 🆕 **ChaCha20-Poly1305** | RFC 8439 AEAD — 2-3× faster than AES-GCM on ARM without AES-NI |
+| 🆕 **`constantTimeEq()`** | Timing-safe Buffer comparison (for MAC/signature checking) |
+| 🆕 **`nativeSecureRandom()`** | OS-backed CSPRNG via Rust side (alternative to JS `secureRandom`) |
+| 🆕 **`sc-utils` crate** | Public utility helpers (random, constant_time_eq, secure_zeroize) |
+| 🆕 **CI: cargo-audit gate** | Vulnerable transitive dependencies now fail PRs automatically |
+
+### Quick Example: ChaCha20-Poly1305
+
+```ts
+import { ChaCha20Poly1305, secureRandom } from '@brashkie/signalis-core';
+
+const key = secureRandom(32);
+const nonce = secureRandom(12);
+
+const ct = ChaCha20Poly1305.encrypt(key, nonce, Buffer.from('Hello!'));
+const pt = ChaCha20Poly1305.decrypt(key, nonce, ct);  // → "Hello!"
+
+// With Additional Authenticated Data
+const aad = Buffer.from('header metadata');
+const ct2 = ChaCha20Poly1305.encryptWithAad(key, nonce, plaintext, aad);
+const pt2 = ChaCha20Poly1305.decryptWithAad(key, nonce, ct2, aad);
+```
+
+### Why Should I Use ChaCha20-Poly1305 Instead of AES-GCM?
+
+Use **AES-GCM** on:
+- x86_64 servers (Intel/AMD with AES-NI hardware)
+- Modern desktops
+- Newer ARM CPUs with ARMv8 Crypto Extensions
+
+Use **ChaCha20-Poly1305** on:
+- Android phones (most don't have AES-NI)
+- Embedded / IoT devices
+- Anything without hardware AES support
+
+Both have **identical security guarantees**. The difference is purely performance, depending on whether your target has AES-NI hardware.
 
 See [MIGRATION.md](./MIGRATION.md) for upgrade details (it's a drop-in replacement).
 
 ---
 
+## 🌍 Supported Platforms
+
+`@brashkie/signalis-core` ships prebuilt native binaries for **9 platforms** via npm `optionalDependencies`. The right binary downloads automatically based on your host OS + arch.
+
+| OS | Architecture | Sub-package | Status |
+|----|--------------|-------------|--------|
+| 🐧 Linux | x64 (glibc) | `signalis-core-linux-x64-gnu` | ✅ |
+| 🐧 Linux | x64 (musl) | `signalis-core-linux-x64-musl` | ✅ |
+| 🐧 Linux | arm64 (glibc) | `signalis-core-linux-arm64-gnu` | ✅ |
+| 🍎 macOS | x64 (Intel) | `signalis-core-darwin-x64` | ✅ |
+| 🍎 macOS | arm64 (Apple Silicon) | `signalis-core-darwin-arm64` | ✅ |
+| 🪟 Windows | x64 | `signalis-core-win32-x64-msvc` | ✅ |
+| 🪟 Windows | arm64 | `signalis-core-win32-arm64-msvc` | ✅ |
+| 🤖 Android | arm64-v8a | `signalis-core-android-arm64` | 🆕 v0.3.0 |
+| 🤖 Android | armv7 | `signalis-core-android-arm-eabi` | 🆕 v0.3.0 |
+
+Coming in v0.4.0: **iOS arm64**, **WASM (browsers)**, **FreeBSD x64**.
+
+### Android Installation
+
+Same `npm install` works in any Node.js environment running on Android, including:
+- **Termux** on Android phones (`pkg install nodejs`)
+- **React Native** with Android target
+- **NodeJS-Mobile** apps
+- Custom embedded Node builds for IoT
+
+```bash
+# On Android (Termux for example):
+pkg install nodejs
+npm install @brashkie/signalis-core
+# → npm automatically downloads signalis-core-android-arm64 sub-package
+```
+
+---
+
 ## 📋 Table of Contents
 
 - [🔐 Signalis Core](#-signalis-core)
   - [✨ What is Signalis Core?](#-what-is-signalis-core)
-  - [🎉 What's New in v0.2.0](#-whats-new-in-v020)
+  - [🎉 What's New in v0.3.0](#-whats-new-in-v030)
+  - [🌍 Supported Platforms](#-supported-platforms)
   - [📋 Table of Contents](#-table-of-contents)
   - [🚀 Features](#-features)
   - [🤔 Why Signalis Core?](#-why-signalis-core)
@@ -109,7 +178,7 @@ See [MIGRATION.md](./MIGRATION.md) for upgrade details (it's a drop-in replaceme
 | 📦 **Dual Package** | Works in CommonJS, ESM, and TypeScript projects |
 | 🎯 **Type-Safe** | Full TypeScript definitions with branded types and rich error classes |
 | ✅ **Test Vectors** | Validated against RFC 5869, RFC 7748, RFC 8032, RFC 4231, and NIST vectors |
-| 🌍 **Cross-Platform** | Prebuilt binaries for Windows, macOS, Linux (x64, ARM) |
+| 🌍 **Cross-Platform** | Prebuilt binaries for Windows, macOS, Linux (x64, ARM) + **Android arm64/armv7** |
 | 🔒 **Constant-Time** | Side-channel resistant comparisons via `subtle` crate |
 | 🧹 **Auto-Zeroization** | Secrets are wiped from memory automatically |
 | 📊 **99%+ Coverage** | Comprehensive test suite with 269+ assertions |
@@ -426,6 +495,43 @@ if (HMAC.verifySha256(macKey, concat([iv, ct]), tag)) {
 }
 ```
 
+### ChaCha20-Poly1305 🆕
+
+RFC 8439 authenticated encryption. Alternative to AES-GCM, faster on ARM without AES-NI.
+
+```typescript
+import { ChaCha20Poly1305, secureRandom } from '@brashkie/signalis-core';
+
+const key = secureRandom(32);     // ChaCha20Poly1305.KEY_SIZE
+const nonce = secureRandom(12);   // ChaCha20Poly1305.NONCE_SIZE
+
+// Basic encrypt/decrypt (no AAD)
+const ct = ChaCha20Poly1305.encrypt(key, nonce, plaintext);
+const pt = ChaCha20Poly1305.decrypt(key, nonce, ct);
+
+// With Additional Authenticated Data
+const aad = Buffer.from('public header');
+const ct2 = ChaCha20Poly1305.encryptWithAad(key, nonce, plaintext, aad);
+const pt2 = ChaCha20Poly1305.decryptWithAad(key, nonce, ct2, aad);
+
+// Constants
+ChaCha20Poly1305.KEY_SIZE;     // 32
+ChaCha20Poly1305.NONCE_SIZE;   // 12
+ChaCha20Poly1305.TAG_SIZE;     // 16 (appended to ciphertext)
+```
+
+**Performance vs AES-GCM:**
+
+| Target | Winner | Why |
+|--------|--------|-----|
+| Server x86_64 (AES-NI) | AES-GCM | Hardware acceleration |
+| Modern desktop (AES-NI) | AES-GCM | Hardware acceleration |
+| Android arm64 (no ARMv8 crypto) | **ChaCha20-Poly1305** | Pure CPU, ChaCha is faster |
+| IoT / embedded | **ChaCha20-Poly1305** | No AES hardware needed |
+| Apple Silicon (M-series) | Either (close) | Both well-optimized |
+
+**Security:** ChaCha20-Poly1305 and AES-GCM have equivalent security properties. The choice is purely about performance on your target.
+
 ### HMAC-SHA256
 
 Message authentication.
@@ -467,7 +573,9 @@ import {
   fromBase64Url,
 
   // Security
-  constantTimeEqual,  // (a, b) → boolean (timing-safe)
+  constantTimeEqual,    // (a, b) → boolean (timing-safe, JS-side)
+  constantTimeEq,       // 🆕 v0.3.0 — same but routed via Rust side
+  nativeSecureRandom,   // 🆕 v0.3.0 — OS CSPRNG via Rust (vs node:crypto)
 
   // Buffer ops
   concat,          // (buffers[]) → Buffer
@@ -476,6 +584,14 @@ import {
 } from '@brashkie/signalis-core';
 ```
 
+#### When to use `constantTimeEq` vs `constantTimeEqual`?
+
+Both compare in constant time. `constantTimeEqual` uses JavaScript's `Buffer.compare` semantics (the JS-side implementation). `constantTimeEq` (v0.3.0) routes through Rust's audited `subtle::ConstantTimeEq` crate. Either is safe — use `constantTimeEq` if you want to ensure your timing-safe code path matches what the rest of the library uses internally.
+
+#### When to use `nativeSecureRandom` vs `secureRandom`?
+
+`secureRandom(n)` uses Node's `crypto.randomBytes()`. `nativeSecureRandom(n)` (v0.3.0) routes through Rust's `OsRng` (which calls `getrandom`/`BCryptGenRandom`/`SecRandomCopyBytes` directly). Both are cryptographically secure. Use `nativeSecureRandom` if you want a single audit surface for entropy across your whole stack.
+
 ### Errors
 
 All errors extend `SignalisError`:

package/dist/index.cjs

@@ -40,9 +40,13 @@ __export(index_exports, {
   AES_GCM_MAX_PLAINTEXT_SIZE: () => AES_GCM_MAX_PLAINTEXT_SIZE,
   AES_GCM_RECOMMENDED_MESSAGES_PER_KEY: () => AES_GCM_RECOMMENDED_MESSAGES_PER_KEY,
   AuthenticationError: () => AuthenticationError,
+  CHACHA20_POLY1305_KEY_SIZE: () => CHACHA20_POLY1305_KEY_SIZE,
+  CHACHA20_POLY1305_NONCE_SIZE: () => CHACHA20_POLY1305_NONCE_SIZE,
+  CHACHA20_POLY1305_TAG_SIZE: () => CHACHA20_POLY1305_TAG_SIZE,
   CURVE25519_PRIVATE_KEY_SIZE: () => CURVE25519_PRIVATE_KEY_SIZE,
   CURVE25519_PUBLIC_KEY_SIZE: () => CURVE25519_PUBLIC_KEY_SIZE,
   CURVE25519_SHARED_SECRET_SIZE: () => CURVE25519_SHARED_SECRET_SIZE,
+  ChaCha20Poly1305: () => ChaCha20Poly1305,
   CryptoError: () => CryptoError,
   Curve25519: () => Curve25519,
   ED25519_PRIVATE_KEY_SIZE: () => ED25519_PRIVATE_KEY_SIZE,
@@ -81,16 +85,18 @@ __export(index_exports, {
   bufferToString: () => bufferToString,
   buffersSameLength: () => buffersSameLength,
   concat: () => concat,
+  constantTimeEq: () => constantTimeEq2,
   constantTimeEqual: () => constantTimeEqual,
   default: () => index_default,
   fromBase64: () => fromBase64,
   fromBase64Url: () => fromBase64Url,
   fromHex: () => fromHex,
+  nativeSecureRandom: () => nativeSecureRandom,
   nativeVersion: () => nativeVersion,
   randomIv: () => randomIv,
   randomKey: () => randomKey,
   randomNonce: () => randomNonce,
-  secureRandom: () => secureRandom,
+  secureRandom: () => secureRandom2,
   stringToBuffer: () => stringToBuffer,
   toBase64: () => toBase64,
   toBase64Url: () => toBase64Url,
@@ -736,6 +742,97 @@ var XEd25519 = Object.freeze({
   RANDOM_SIZE: XED25519_RANDOM_SIZE
 });
 var nativeVersion = native.version();
+var CHACHA20_POLY1305_KEY_SIZE = 32;
+var CHACHA20_POLY1305_NONCE_SIZE = 12;
+var CHACHA20_POLY1305_TAG_SIZE = 16;
+var ChaCha20Poly1305 = Object.freeze({
+  /**
+   * Encrypt + authenticate `plaintext`.
+   *
+   * @param key 32-byte key
+   * @param nonce 12-byte nonce — MUST be unique per (key, plaintext)
+   * @param plaintext data to encrypt
+   * @returns ciphertext || tag (16 bytes appended)
+   */
+  encrypt(key, nonce, plaintext) {
+    if (!Buffer.isBuffer(key) || key.length !== CHACHA20_POLY1305_KEY_SIZE) {
+      throw new RangeError(`key must be ${CHACHA20_POLY1305_KEY_SIZE} bytes`);
+    }
+    if (!Buffer.isBuffer(nonce) || nonce.length !== CHACHA20_POLY1305_NONCE_SIZE) {
+      throw new RangeError(`nonce must be ${CHACHA20_POLY1305_NONCE_SIZE} bytes`);
+    }
+    if (!Buffer.isBuffer(plaintext)) {
+      throw new TypeError("plaintext must be a Buffer");
+    }
+    return native.chacha20Poly1305Encrypt(key, nonce, plaintext);
+  },
+  /**
+   * Verify-then-decrypt. Returns plaintext on success, throws on auth failure.
+   */
+  decrypt(key, nonce, ciphertext) {
+    if (!Buffer.isBuffer(key) || key.length !== CHACHA20_POLY1305_KEY_SIZE) {
+      throw new RangeError(`key must be ${CHACHA20_POLY1305_KEY_SIZE} bytes`);
+    }
+    if (!Buffer.isBuffer(nonce) || nonce.length !== CHACHA20_POLY1305_NONCE_SIZE) {
+      throw new RangeError(`nonce must be ${CHACHA20_POLY1305_NONCE_SIZE} bytes`);
+    }
+    if (!Buffer.isBuffer(ciphertext)) {
+      throw new TypeError("ciphertext must be a Buffer");
+    }
+    return native.chacha20Poly1305Decrypt(key, nonce, ciphertext);
+  },
+  /**
+   * Encrypt + authenticate with Additional Authenticated Data.
+   *
+   * AAD is NOT encrypted but IS authenticated. Use for plaintext metadata
+   * (e.g., message headers) that must not be tampered with.
+   */
+  encryptWithAad(key, nonce, plaintext, aad) {
+    if (!Buffer.isBuffer(key) || key.length !== CHACHA20_POLY1305_KEY_SIZE) {
+      throw new RangeError(`key must be ${CHACHA20_POLY1305_KEY_SIZE} bytes`);
+    }
+    if (!Buffer.isBuffer(nonce) || nonce.length !== CHACHA20_POLY1305_NONCE_SIZE) {
+      throw new RangeError(`nonce must be ${CHACHA20_POLY1305_NONCE_SIZE} bytes`);
+    }
+    if (!Buffer.isBuffer(plaintext) || !Buffer.isBuffer(aad)) {
+      throw new TypeError("plaintext and aad must be Buffers");
+    }
+    return native.chacha20Poly1305EncryptWithAad(key, nonce, plaintext, aad);
+  },
+  /**
+   * Verify (key + nonce + ciphertext + AAD) and decrypt.
+   */
+  decryptWithAad(key, nonce, ciphertext, aad) {
+    if (!Buffer.isBuffer(key) || key.length !== CHACHA20_POLY1305_KEY_SIZE) {
+      throw new RangeError(`key must be ${CHACHA20_POLY1305_KEY_SIZE} bytes`);
+    }
+    if (!Buffer.isBuffer(nonce) || nonce.length !== CHACHA20_POLY1305_NONCE_SIZE) {
+      throw new RangeError(`nonce must be ${CHACHA20_POLY1305_NONCE_SIZE} bytes`);
+    }
+    if (!Buffer.isBuffer(ciphertext) || !Buffer.isBuffer(aad)) {
+      throw new TypeError("ciphertext and aad must be Buffers");
+    }
+    return native.chacha20Poly1305DecryptWithAad(key, nonce, ciphertext, aad);
+  },
+  /** Key size in bytes (32). */
+  KEY_SIZE: CHACHA20_POLY1305_KEY_SIZE,
+  /** Nonce size in bytes (12). */
+  NONCE_SIZE: CHACHA20_POLY1305_NONCE_SIZE,
+  /** Authentication tag size in bytes (16), appended to ciphertext. */
+  TAG_SIZE: CHACHA20_POLY1305_TAG_SIZE
+});
+function constantTimeEq2(a, b) {
+  if (!Buffer.isBuffer(a) || !Buffer.isBuffer(b)) {
+    throw new TypeError("constantTimeEq: both arguments must be Buffers");
+  }
+  return native.constantTimeEq(a, b);
+}
+function nativeSecureRandom(size) {
+  if (!Number.isInteger(size) || size <= 0) {
+    throw new RangeError(`size must be a positive integer, got ${size}`);
+  }
+  return native.secureRandom(size);
+}
 
 // src/types.ts
 function asPublicKey(buf) {
@@ -753,7 +850,7 @@ function asSignature(buf) {
 
 // src/utils.ts
 var import_node_crypto = require("crypto");
-function secureRandom(length) {
+function secureRandom2(length) {
   if (!Number.isInteger(length) || length < 0) {
     throw new RangeError(`length must be a non-negative integer, got ${length}`);
   }
@@ -835,7 +932,7 @@ var SignalisCore = Object.freeze({
   HMAC,
   SHA256,
   // Random
-  secureRandom,
+  secureRandom: secureRandom2,
   randomNonce,
   randomIv,
   randomKey,
@@ -863,9 +960,13 @@ var index_default = SignalisCore;
   AES_GCM_MAX_PLAINTEXT_SIZE,
   AES_GCM_RECOMMENDED_MESSAGES_PER_KEY,
   AuthenticationError,
+  CHACHA20_POLY1305_KEY_SIZE,
+  CHACHA20_POLY1305_NONCE_SIZE,
+  CHACHA20_POLY1305_TAG_SIZE,
   CURVE25519_PRIVATE_KEY_SIZE,
   CURVE25519_PUBLIC_KEY_SIZE,
   CURVE25519_SHARED_SECRET_SIZE,
+  ChaCha20Poly1305,
   CryptoError,
   Curve25519,
   ED25519_PRIVATE_KEY_SIZE,
@@ -904,10 +1005,12 @@ var index_default = SignalisCore;
   bufferToString,
   buffersSameLength,
   concat,
+  constantTimeEq,
   constantTimeEqual,
   fromBase64,
   fromBase64Url,
   fromHex,
+  nativeSecureRandom,
   nativeVersion,
   randomIv,
   randomKey,