@brashkie/signalis-core 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="https://github.com/Brashkie/signalis-core/blob/main/media/logo.png" alt="Signalis Core" width="200" />
+<img src="media/logo.png" alt="Signalis Core" width="200" />
 
 # 🔐 Signalis Core
 
@@ -13,7 +13,7 @@
 [![Rust](https://img.shields.io/badge/rust-1.80%2B-orange.svg)](https://www.rust-lang.org/)
 [![Node](https://img.shields.io/badge/node-%E2%89%A518-339933.svg)](https://nodejs.org/)
 [![Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen.svg)](#testing)
-[![Tests](https://img.shields.io/badge/tests-100%2B%20passing-success.svg)](#testing)
+[![Tests](https://img.shields.io/badge/tests-269%2B%20passing-success.svg)](#testing)
 
 [**English**](./README.md) · [**Español**](./README.es.md) · [Docs](./docs) · [Roadmap](./ROADMAP.md) · [Changelog](./CHANGELOG.md)
 
@@ -32,10 +32,96 @@ Built with **Rust** for safety and speed, exposed to Node.js via [napi-rs](https
 
 ---
 
+## 🎉 What's New in v0.3.0
+
+**v0.3.0 ships Android support + ChaCha20-Poly1305 — fully backwards compatible with v0.2.0.**
+
+| New | Description |
+|-----|-------------|
+| 🆕 **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.3.0](#-whats-new-in-v030)
+  - [🌍 Supported Platforms](#-supported-platforms)
   - [📋 Table of Contents](#-table-of-contents)
   - [🚀 Features](#-features)
   - [🤔 Why Signalis Core?](#-why-signalis-core)
@@ -49,6 +135,8 @@ Built with **Rust** for safety and speed, exposed to Node.js via [napi-rs](https
     - [Default Import](#default-import)
   - [📚 API Reference](#-api-reference)
     - [Curve25519 / X25519](#curve25519--x25519)
+    - [Ed25519](#ed25519)
+    - [XEd25519](#xed25519)
     - [HKDF-SHA256](#hkdf-sha256)
     - [AES-256-GCM](#aes-256-gcm)
     - [AES-256-CBC](#aes-256-cbc)
@@ -59,6 +147,8 @@ Built with **Rust** for safety and speed, exposed to Node.js via [napi-rs](https
   - [💡 Examples](#-examples)
     - [Example: Secure file encryption](#example-secure-file-encryption)
     - [Example: Signal-style "Triple DH"](#example-signal-style-triple-dh)
+    - [Example: Signing identity assertions (NEW v0.2.0)](#example-signing-identity-assertions-new-v020)
+    - [Example: Encrypted messages with authenticated headers (NEW v0.2.0)](#example-encrypted-messages-with-authenticated-headers-new-v020)
   - [🏗️ Architecture](#️-architecture)
     - [Build Output](#build-output)
   - [🛡️ Security](#️-security)
@@ -82,14 +172,16 @@ Built with **Rust** for safety and speed, exposed to Node.js via [napi-rs](https
 | Feature | Description |
 |---------|-------------|
 | 🔥 **Blazing Fast** | Native Rust implementation via napi-rs (10-100x faster than pure JS) |
-| 🛡️ **Audited Crypto** | Built on `curve25519-dalek`, RustCrypto suite — battle-tested libraries |
+| 🛡️ **Audited Crypto** | Built on `curve25519-dalek`, `ed25519-dalek`, RustCrypto suite — battle-tested libraries |
+| ✍️ **Digital Signatures** | Ed25519 (RFC 8032) and XEd25519 (Signal-style) — **NEW v0.2.0** |
+| 🔐 **AEAD with AAD** | AES-256-GCM with Additional Authenticated Data — **NEW v0.2.0** |
 | 📦 **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 4231, and NIST vectors |
-| 🌍 **Cross-Platform** | Prebuilt binaries for Windows, macOS, Linux (x64, ARM) |
+| ✅ **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) + **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 100+ assertions |
+| 📊 **99%+ Coverage** | Comprehensive test suite with 269+ assertions |
 | 📖 **Well Documented** | Complete JSDoc + inline examples for every function |
 
 ---
@@ -234,6 +326,86 @@ Curve25519.PUBLIC_KEY_SIZE;       // 32
 Curve25519.SHARED_SECRET_SIZE;    // 32
 ```
 
+### Ed25519
+
+**NEW in v0.2.0.** Standard Ed25519 digital signatures (RFC 8032). Deterministic — same input always produces the same signature.
+
+```typescript
+import { Ed25519, type KeyPair, type Signature } from '@brashkie/signalis-core';
+
+// Generate a new signing keypair
+const keys: KeyPair = Ed25519.generateKeyPair();
+// → { privateKey: Buffer(32), publicKey: Buffer(32) }
+
+// Deterministic from a 32-byte seed
+const fromSeed = Ed25519.keyPairFromSeed(seed);
+
+// Derive public from private
+const pub = Ed25519.publicFromPrivate(privateKey);
+
+// Sign a message → 64-byte signature
+const sig: Signature = Ed25519.sign(privateKey, message);
+
+// Verify (throws SignatureError on failure)
+Ed25519.verify(publicKey, message, sig);
+
+// Verify (returns boolean, no throw)
+const ok = Ed25519.verifyBool(publicKey, message, sig);
+
+// Constants
+Ed25519.PRIVATE_KEY_SIZE;    // 32
+Ed25519.PUBLIC_KEY_SIZE;     // 32
+Ed25519.SIGNATURE_SIZE;      // 64
+Ed25519.SEED_SIZE;           // 32
+```
+
+### XEd25519
+
+**NEW in v0.2.0.** Sign with the **SAME** Curve25519 keypair used for ECDH. This is what the Signal Protocol uses for identity keys.
+
+```typescript
+import { Curve25519, XEd25519 } from '@brashkie/signalis-core';
+
+// ONE keypair for both ECDH and signing
+const identity = Curve25519.generateKeyPair();
+
+// Use for ECDH:
+const shared = Curve25519.diffieHellman(identity.privateKey, peerPublic);
+
+// Use the SAME key to sign:
+const sig = XEd25519.sign(identity.privateKey, message);
+
+// Verify with the SAME Curve25519 public key
+XEd25519.verify(identity.publicKey, message, sig);
+
+// XEd25519 signatures are NOT deterministic (use OS RNG)
+const sig1 = XEd25519.sign(identity.privateKey, message);
+const sig2 = XEd25519.sign(identity.privateKey, message);
+// sig1.equals(sig2) → false (intentionally probabilistic)
+
+// For deterministic signing (testing), provide explicit 64-byte random:
+const random = secureRandom(64);
+const detSig = XEd25519.signWithRandom(identity.privateKey, message, random);
+
+// Verify (boolean, no throw)
+const ok = XEd25519.verifyBool(identity.publicKey, message, sig);
+
+// Constants
+XEd25519.PRIVATE_KEY_SIZE;   // 32 (same as Curve25519)
+XEd25519.PUBLIC_KEY_SIZE;    // 32 (same as Curve25519)
+XEd25519.SIGNATURE_SIZE;     // 64
+XEd25519.RANDOM_SIZE;        // 64
+```
+
+**When to use Ed25519 vs XEd25519:**
+
+| Need | Use |
+|------|-----|
+| Standard Ed25519, deterministic, RFC 8032 compliant | **Ed25519** |
+| Single identity key for ECDH + signing (Signal style) | **XEd25519** |
+| Reproducible signatures from seed | **Ed25519** |
+| Compatibility with Signal Protocol semantics | **XEd25519** |
+
 ### HKDF-SHA256
 
 Key derivation per RFC 5869.
@@ -283,6 +455,26 @@ const pt = AES_GCM.decrypt(key, nonce, ct);
 // Throws AuthenticationError if tampered
 ```
 
+**With Additional Authenticated Data (AAD) — NEW in v0.2.0:**
+
+```typescript
+import { AES_GCM } from '@brashkie/signalis-core';
+
+// AAD is authenticated but NOT encrypted — useful for headers/metadata
+const header = Buffer.from('msg_id=42|sender=alice');
+const body = Buffer.from('encrypted body content');
+
+const ct = AES_GCM.encryptWithAad(key, nonce, body, header);
+
+// Decrypt — MUST pass same AAD, or AuthenticationError
+const pt = AES_GCM.decryptWithAad(key, nonce, ct, header);
+
+// Tampering with header (AAD) → fails
+const tampered = Buffer.from(header);
+tampered[0] ^= 0xff;
+AES_GCM.decryptWithAad(key, nonce, ct, tampered);  // throws AuthenticationError
+```
+
 > **⚠️ CRITICAL:** Never reuse a `(key, nonce)` pair. Use `randomNonce()` for every message, or use a deterministic counter under the same key (max 2³² messages).
 
 ### AES-256-CBC
@@ -303,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.
@@ -344,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
@@ -353,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`:
@@ -364,6 +603,7 @@ import {
   CryptoError,              // Crypto op failed
   AuthenticationError,      // Tag/MAC verification failed (extends CryptoError)
   KeyDerivationError,       // HKDF or similar failed (extends CryptoError)
+  SignatureError,           // Ed25519/XEd25519 verify failed (extends CryptoError) — NEW v0.2.0
   LengthError,              // Output length out of bounds (extends ValidationError)
 } from '@brashkie/signalis-core';
 
@@ -374,6 +614,8 @@ try {
     console.error('Tampering detected!');
   } else if (e instanceof ValidationError) {
     console.error(`Invalid parameter: ${e.parameter}`);
+  } else if (e instanceof SignatureError) {
+    console.error('Invalid signature!');
   }
 }
 ```
@@ -385,10 +627,13 @@ try {
 The `examples/` directory contains complete working demos:
 
 ```bash
-npm run example:cjs    # CommonJS (10 demos)
-npm run example:esm    # ESM (Alice ↔ Bob channel)
-npm run example:ts     # TypeScript (type-safe patterns)
-npm run examples       # Run all three
+npm run example:cjs        # CommonJS (10 demos)
+npm run example:esm        # ESM (Alice ↔ Bob channel)
+npm run example:ts         # TypeScript (type-safe patterns)
+npm run example:signing    # Ed25519 + XEd25519 — NEW v0.2.0
+npm run example:aad        # AES-GCM with AAD — NEW v0.2.0
+npm run example:e2e        # Complete E2E channel — NEW v0.2.0
+npm run examples           # Run all
 ```
 
 ### Example: Secure file encryption
@@ -438,6 +683,66 @@ function tripleDH(IK_A_priv: Buffer, EK_A_priv: Buffer,
 }
 ```
 
+### Example: Signing identity assertions (NEW v0.2.0)
+
+```typescript
+import { Curve25519, XEd25519 } from '@brashkie/signalis-core';
+
+// Alice's long-term identity key (Curve25519/XEd25519)
+const aliceIdentity = Curve25519.generateKeyPair();
+
+// Alice generates an ephemeral session key
+const aliceEphemeral = Curve25519.generateKeyPair();
+
+// Alice signs her ephemeral with her identity — proves "this ephemeral is mine"
+const authProof = XEd25519.sign(
+  aliceIdentity.privateKey,
+  aliceEphemeral.publicKey,
+);
+
+// Bob verifies the authorization:
+// 1. Got Alice's identity public key from a trusted source
+// 2. Receives ephemeral + signature
+try {
+  XEd25519.verify(aliceIdentity.publicKey, aliceEphemeral.publicKey, authProof);
+  // ✅ Bob now trusts the ephemeral key belongs to Alice
+} catch {
+  // ❌ Mallory tried to MITM with her own ephemeral
+}
+```
+
+### Example: Encrypted messages with authenticated headers (NEW v0.2.0)
+
+```typescript
+import { AES_GCM, secureRandom } from '@brashkie/signalis-core';
+
+const sessionKey = derivedFromECDHandHKDF;
+
+function sendMessage(body: Buffer, msgId: number) {
+  const nonce = secureRandom(12);
+  const header = Buffer.from(JSON.stringify({
+    msg_id: msgId,
+    timestamp: Date.now(),
+    sender: 'alice',
+  }));
+
+  // Header is authenticated but NOT encrypted (receiver needs it as plaintext)
+  const ciphertext = AES_GCM.encryptWithAad(sessionKey, nonce, body, header);
+
+  return { header, nonce, ciphertext };
+}
+
+function receiveMessage(packet: { header: Buffer; nonce: Buffer; ciphertext: Buffer }) {
+  // Decryption fails if EITHER ciphertext OR header was tampered
+  return AES_GCM.decryptWithAad(
+    sessionKey,
+    packet.nonce,
+    packet.ciphertext,
+    packet.header,
+  );
+}
+```
+
 ---
 
 ## 🏗️ Architecture
@@ -445,18 +750,20 @@ function tripleDH(IK_A_priv: Buffer, EK_A_priv: Buffer,
 ```
 @brashkie/signalis-core
 │
-├── 🦀 Rust Workspace (5 crates)
+├── 🦀 Rust Workspace (8 crates)
 │   ├── sc-curve25519    →  X25519 ECDH operations
+│   ├── sc-ed25519       →  Ed25519 signatures (RFC 8032) — NEW v0.2.0
+│   ├── sc-xed25519      →  XEd25519 Signal-style signatures — NEW v0.2.0
 │   ├── sc-hkdf          →  HKDF-SHA256 derivation
-│   ├── sc-aes           →  AES-256-GCM & CBC
+│   ├── sc-aes           →  AES-256-GCM (with AAD) & CBC
 │   ├── sc-hmac          →  HMAC-SHA256 with constant-time verify
 │   ├── sc-sha256        →  SHA-256 hashing
 │   └── sc-node          →  NAPI-RS bindings (cdylib)
 │
 └── 📦 TypeScript Layer
     ├── core.ts          →  Crypto wrappers with validation
-    ├── types.ts         →  Type definitions (KeyPair, etc.)
-    ├── errors.ts        →  Typed error classes
+    ├── types.ts         →  Type definitions (KeyPair, Signature, etc.)
+    ├── errors.ts        →  Typed error classes (incl. SignatureError)
     ├── validators.ts    →  Input assertions
     ├── utils.ts         →  Encoding + random + buffer helpers
     ├── constants.ts     →  Public constants (sizes, limits)
@@ -487,8 +794,10 @@ dist/
 | Primitive | Spec | Implementation |
 |-----------|------|----------------|
 | X25519 | [RFC 7748](https://datatracker.ietf.org/doc/html/rfc7748) | [`curve25519-dalek`](https://github.com/dalek-cryptography/curve25519-dalek) (audited by NCC Group) |
+| Ed25519 | [RFC 8032](https://datatracker.ietf.org/doc/html/rfc8032) | [`ed25519-dalek`](https://github.com/dalek-cryptography/ed25519-dalek) (audited) — **NEW v0.2.0** |
+| XEd25519 | [Signal Spec](https://signal.org/docs/specifications/xeddsa/) | Custom impl over `curve25519-dalek` — **NEW v0.2.0** |
 | HKDF-SHA256 | [RFC 5869](https://datatracker.ietf.org/doc/html/rfc5869) | [`hkdf`](https://github.com/RustCrypto/KDFs) (RustCrypto) |
-| AES-256-GCM | [NIST SP 800-38D](https://csrc.nist.gov/publications/detail/sp/800-38d/final) | [`aes-gcm`](https://github.com/RustCrypto/AEADs) (RustCrypto) |
+| AES-256-GCM | [NIST SP 800-38D](https://csrc.nist.gov/publications/detail/sp/800-38d/final) | [`aes-gcm`](https://github.com/RustCrypto/AEADs) (RustCrypto, AAD support) |
 | AES-256-CBC | [NIST SP 800-38A](https://csrc.nist.gov/publications/detail/sp/800-38a/final) | [`aes`](https://github.com/RustCrypto/block-ciphers) (RustCrypto) |
 | HMAC-SHA256 | [RFC 2104](https://datatracker.ietf.org/doc/html/rfc2104) | [`hmac`](https://github.com/RustCrypto/MACs) (RustCrypto) |
 | SHA-256 | [FIPS 180-4](https://csrc.nist.gov/publications/detail/fips/180/4/final) | [`sha2`](https://github.com/RustCrypto/hashes) (RustCrypto) |
@@ -521,12 +830,17 @@ Benchmarks (Node 22, x86_64):
 |-----------|------------|-------------|
 | Curve25519 keygen | ~50,000 ops/sec | **15×** faster than tweetnacl |
 | X25519 ECDH | ~25,000 ops/sec | **20×** faster |
+| Ed25519 sign | ~25,000 ops/sec | **20×** faster — NEW v0.2.0 |
+| Ed25519 verify | ~10,000 ops/sec | **15×** faster — NEW v0.2.0 |
+| XEd25519 sign | ~20,000 ops/sec | — — NEW v0.2.0 |
+| XEd25519 verify | ~10,000 ops/sec | — — NEW v0.2.0 |
 | HKDF derive (32 bytes) | ~500,000 ops/sec | **30×** faster |
 | AES-256-GCM encrypt (1 KB) | ~2 GB/sec | **80×** faster |
+| AES-GCM with AAD | <5% overhead vs no AAD | — NEW v0.2.0 |
 | SHA-256 (1 KB) | ~3 GB/sec | **50×** faster |
 | HMAC-SHA256 (1 KB) | ~2.5 GB/sec | **40×** faster |
 
-*Run `npm run bench` to benchmark on your machine (coming in v0.2).*
+*Run `npm run bench` to benchmark on your machine (coming in v0.3).*
 
 ---
 
@@ -562,15 +876,20 @@ npm run test:coverage:ui
 
 ### What's Tested
 
-- ✅ All RFC test vectors (RFC 5869, 7748, 4231)
+- ✅ All RFC test vectors (RFC 5869, 7748, 8032, 4231)
 - ✅ All NIST test vectors (AES, SHA-256)
+- ✅ Ed25519 RFC 8032 vector 1 (empty message) — NEW v0.2.0
+- ✅ XEd25519 round-trips with deterministic + probabilistic signing — NEW v0.2.0
+- ✅ AES-GCM AAD authentication (tampered AAD fails decryption) — NEW v0.2.0
 - ✅ Input validation for every public function
 - ✅ Error handling for every code path
 - ✅ Round-trip encryption / decryption
-- ✅ Tampering detection (AES-GCM tag failures)
+- ✅ Tampering detection (AES-GCM tag failures, signature failures)
 - ✅ Both CommonJS and ESM consumption paths
 - ✅ Default export and named exports
 
+**Test count: 269+ assertions across Rust (48) + Vitest (172) + CJS (12) + ESM (15) + new v0.2.0 tests (49).**
+
 ---
 
 ## 🔨 Building from Source
@@ -611,9 +930,10 @@ npm run examples
 See [ROADMAP.md](./ROADMAP.md) for detailed plans.
 
 **TL;DR:**
-- **v0.1** ✅ — Cryptographic primitives (current)
-- **v0.2** — Benchmarks, Ed25519 signatures, X448 support
-- **v1.0** — Stable API, audit
+- **v0.1** ✅ — Cryptographic primitives (Curve25519, HKDF, AES, HMAC, SHA-256)
+- **v0.2** ✅ — Ed25519, XEd25519, AES-GCM with AAD (current release)
+- **v0.3** — Benchmarks, X448 support, more test vectors
+- **v1.0** — Stable API, external audit
 - **Then:** [@brashkie/signalis](https://github.com/Brashkie/signalis) (X3DH + Double Ratchet)
 - **Then:** [@brashkie/waproto](https://github.com/Brashkie/waproto) (WhatsApp Protocol)
 - **Then:** HepeinBaileys 2.0 (full WhatsApp client from scratch)
@@ -638,9 +958,10 @@ Please also read our [Code of Conduct](./CODE_OF_CONDUCT.md).
 Built on the shoulders of giants:
 
 - **[curve25519-dalek](https://github.com/dalek-cryptography/curve25519-dalek)** — Curve25519 in pure Rust
+- **[ed25519-dalek](https://github.com/dalek-cryptography/ed25519-dalek)** — Ed25519 in pure Rust (added in v0.2.0)
 - **[RustCrypto](https://github.com/RustCrypto)** — `aes`, `hkdf`, `hmac`, `sha2`
 - **[napi-rs](https://napi.rs)** — Rust ↔ Node bindings
-- **Signal Foundation** — [Protocol specifications](https://signal.org/docs/)
+- **Signal Foundation** — [Protocol specifications](https://signal.org/docs/) (including [XEd25519](https://signal.org/docs/specifications/xeddsa/))
 - **[tsup](https://tsup.egoist.dev/)** — Dual ESM/CJS bundler
 - **[Vitest](https://vitest.dev/)** — Modern test runner
 
@@ -662,4 +983,4 @@ See [LICENSE](./LICENSE) and [NOTICE](./NOTICE) for full details.
 
 [GitHub](https://github.com/Brashkie) · [npm](https://www.npmjs.com/~brashkie)
 
-</div>
+</div>