@brashkie/signalis-core 0.1.0 → 0.2.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,27 @@ Built with **Rust** for safety and speed, exposed to Node.js via [napi-rs](https
 
 ---
 
+## 🎉 What's New in v0.2.0
+
+**v0.2.0 introduces digital signatures and AAD authenticated encryption — fully backwards compatible with v0.1.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 |
+
+See [MIGRATION.md](./MIGRATION.md) for upgrade details (it's a drop-in replacement).
+
+---
+
 ## 📋 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)
   - [📋 Table of Contents](#-table-of-contents)
   - [🚀 Features](#-features)
   - [🤔 Why Signalis Core?](#-why-signalis-core)
@@ -49,6 +66,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 +78,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 +103,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 |
+| ✅ **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) |
 | 🔒 **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 +257,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 +386,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
@@ -364,6 +487,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 +498,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 +511,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 +567,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 +634,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 +678,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 +714,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 +760,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 +814,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 +842,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 +867,4 @@ See [LICENSE](./LICENSE) and [NOTICE](./NOTICE) for full details.
 
 [GitHub](https://github.com/Brashkie) · [npm](https://www.npmjs.com/~brashkie)
 
-</div>
+</div>

package/SECURITY.md

@@ -0,0 +1,191 @@
+# 🛡️ Security Policy
+
+## Supported Versions
+
+| Version | Supported | Status |
+|---------|-----------|--------|
+| 0.2.x | ✅ | Active development |
+| 0.1.x | ⚠️ | Security fixes only (until 2026-08-01) |
+| < 0.1 | ❌ | Not supported |
+
+When a new minor version is released, the previous minor enters **3 months of security-only support**.
+
+---
+
+## 🚨 Reporting a Vulnerability
+
+**Please do NOT open public GitHub issues for security bugs.**
+
+### Reporting Channels
+
+Use one of these private channels:
+
+1. **GitHub Security Advisories** (preferred):
+   - https://github.com/Brashkie/signalis-core/security/advisories/new
+
+2. **Email**: brashkie@hepein.com
+   - PGP key: [download from GitHub profile]
+   - Subject: `[SECURITY] signalis-core: <brief description>`
+
+### What to Include
+
+To help us triage quickly, please provide:
+
+- **Description** of the vulnerability
+- **Affected versions** (if known)
+- **Reproduction steps** (proof of concept welcome)
+- **Impact assessment** (your view on severity)
+- **Suggested fix** (if any)
+- **Your contact info** (for follow-up)
+
+### Response Timeline
+
+| Severity | First response | Fix target |
+|----------|---------------|------------|
+| **Critical** (remote exploit, key recovery) | 24 hours | 7 days |
+| **High** (timing leaks, DoS) | 3 days | 30 days |
+| **Medium** (specific edge cases) | 7 days | Next minor release |
+| **Low** (theoretical, hard to exploit) | 14 days | Best effort |
+
+### Disclosure Process
+
+1. We acknowledge receipt within the timeframes above
+2. We investigate and confirm the issue
+3. We develop a fix in a private branch
+4. We prepare a security advisory
+5. We coordinate a release (typically 7-30 days from confirmation)
+6. **You are credited** in the advisory (unless you prefer anonymity)
+
+### Bounty Program
+
+We do **not** currently offer monetary bounties, but we:
+- Publicly credit researchers (with permission)
+- Provide signed acknowledgment letters
+- Add you to the contributors hall of fame
+
+If you're interested in funded research, please reach out.
+
+---
+
+## 🔒 Security Considerations
+
+### Cryptographic Implementation
+
+All primitives use **audited, widely-deployed Rust crates**:
+
+| Primitive | Crate | Last audited |
+|-----------|-------|--------------|
+| Curve25519 | `curve25519-dalek` 4.x | 2023 (Cure53) |
+| Ed25519 | `ed25519-dalek` 2.x | 2023 (Cure53) |
+| AES-GCM | `aes-gcm` (RustCrypto) | 2022 |
+| SHA-256/HMAC | `sha2`, `hmac` (RustCrypto) | 2022 |
+| HKDF | `hkdf` (RustCrypto) | 2022 |
+
+We do **not** implement primitives ourselves. Our work is:
+- Glue code (NAPI bindings)
+- Validation logic
+- Type safety wrappers
+- Test infrastructure
+
+### Side-Channel Resistance
+
+The underlying Rust crates provide:
+- ✅ **Constant-time** scalar multiplication (Curve25519, Ed25519)
+- ✅ **Constant-time** equality checks (HMAC verify, point equality)
+- ✅ **AES-NI** hardware acceleration (when available)
+- ✅ **Zeroization** of private key buffers on drop
+
+### Known Limitations
+
+#### XEd25519 (v0.2.0)
+
+XEd25519 implementation follows the [Signal specification](https://signal.org/docs/specifications/xeddsa/). While Signal has deployed this in production for years, our implementation is **new** and has not been independently audited.
+
+**Mitigation:** We use `curve25519-dalek`'s low-level primitives and `ed25519-dalek`'s `hazmat` API, both of which ARE audited. Only the high-level XEd25519 logic is ours.
+
+If you require audited XEd25519, consider waiting for v1.0.0 (audited release).
+
+#### Random Number Generation
+
+We use `OsRng` from the `rand` crate, which sources entropy from:
+- **Linux**: `getrandom()` syscall
+- **macOS**: `SecRandomCopyBytes`
+- **Windows**: `BCryptGenRandom`
+- **iOS**: same as macOS
+
+These are the standard, recommended sources. However:
+- 🚨 **VMs with poor entropy** can produce weak keys
+- 🚨 **Hibernation/snapshots** can reuse RNG state
+
+Mitigation: Generate keys after the system has accumulated entropy, especially in VM contexts.
+
+### Memory Safety
+
+- **Rust side**: Compile-time memory safety, zeroization on drop
+- **JS/Node side**: Buffers can be GC'd at any time
+
+If you need guaranteed key wiping in JS:
+```typescript
+// Explicit overwrite (best effort)
+function wipeKey(buf: Buffer) {
+  buf.fill(0);
+}
+```
+
+**Note:** Due to JS GC behavior, this is best-effort. For highest assurance, use HSM/TPM-backed keys.
+
+### Network Security
+
+This library provides **cryptographic primitives only**. It does NOT:
+- ❌ Establish network connections
+- ❌ Implement TLS/HTTPS
+- ❌ Validate certificates
+- ❌ Manage sessions
+
+Your application is responsible for transport-layer security.
+
+---
+
+## 🚫 Out of Scope
+
+The following are **not considered vulnerabilities**:
+
+- 🔵 **Performance issues** (open as feature request)
+- 🔵 **API ergonomics** (open as feature request)
+- 🔵 **Documentation typos** (open as PR)
+- 🔵 **Behavior on invalid inputs** that throws clear errors (working as intended)
+- 🔵 **Side-channels in user code** (your code's responsibility)
+- 🔵 **Issues in dependencies** (report upstream, but tell us too)
+- 🔵 **Hypothetical attacks** without practical demonstration
+
+---
+
+## 🏆 Hall of Fame
+
+We thank the following security researchers for responsible disclosure:
+
+_(Empty for now — be the first!)_
+
+---
+
+## 📚 Security Resources
+
+For learning about cryptographic security:
+
+- 📘 [Cryptography Engineering](https://www.schneier.com/books/cryptography-engineering/) — Schneier, Ferguson, Kohno
+- 📘 [Real-World Cryptography](https://www.manning.com/books/real-world-cryptography) — David Wong
+- 📘 [Serious Cryptography](https://nostarch.com/seriouscrypto) — Jean-Philippe Aumasson
+- 🌐 [Signal Protocol Documentation](https://signal.org/docs/)
+- 🌐 [Cryptography Stack Exchange](https://crypto.stackexchange.com/)
+
+---
+
+## 🔄 Policy Updates
+
+This policy may be updated. Significant changes will be:
+1. Committed to the repo with a clear commit message
+2. Announced in the next release notes
+3. Posted in GitHub Discussions
+
+**Last updated:** May 2026
+**Next scheduled review:** November 2026