@brashkie/signalis-core 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+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.2.0] — 2026-05-22
+
+### ✨ Added
+
+- **Ed25519 signatures** (RFC 8032) — new `Ed25519` namespace
+  - `Ed25519.generateKeyPair()`
+  - `Ed25519.keyPairFromSeed(seed)` — deterministic from 32-byte seed
+  - `Ed25519.publicFromPrivate(privateKey)`
+  - `Ed25519.sign(privateKey, message)` — deterministic
+  - `Ed25519.verify(publicKey, message, signature)` — throws on failure
+  - `Ed25519.verifyBool(publicKey, message, signature)` — returns boolean
+  - Constants: `Ed25519.PRIVATE_KEY_SIZE`, `PUBLIC_KEY_SIZE`, `SIGNATURE_SIZE`, `SEED_SIZE`
+
+- **XEd25519 signatures** (Signal Protocol style) — new `XEd25519` namespace
+  - Sign with Curve25519 keys: ONE keypair for both ECDH and signing
+  - `XEd25519.sign(privateKey, message)` — uses OS RNG, non-deterministic
+  - `XEd25519.signWithRandom(privateKey, message, random)` — deterministic with 64-byte nonce
+  - `XEd25519.verify(publicKey, message, signature)`
+  - `XEd25519.verifyBool(publicKey, message, signature)`
+  - Constants: `XEd25519.PRIVATE_KEY_SIZE`, `PUBLIC_KEY_SIZE`, `SIGNATURE_SIZE`, `RANDOM_SIZE`
+
+- **AES-GCM with AAD** — Additional Authenticated Data support
+  - `AES_GCM.encryptWithAad(key, nonce, plaintext, aad)`
+  - `AES_GCM.decryptWithAad(key, nonce, ciphertext, aad)`
+  - Bind metadata (headers) to ciphertext without encrypting them
+  - Tampering with AAD fails decryption (just like tampering with ciphertext)
+
+- **New error class:**
+  - `SignatureError extends CryptoError` — thrown by `Ed25519.verify` / `XEd25519.verify`
+
+- **New type:**
+  - `Signature = Buffer & { __brand?: 'Signature' }` — branded type for signatures
+  - Helper: `asSignature(buf): Signature`
+
+- **New constants exported:**
+  - `ED25519_PRIVATE_KEY_SIZE`, `ED25519_PUBLIC_KEY_SIZE`, `ED25519_SIGNATURE_SIZE`, `ED25519_SEED_SIZE`
+  - `XED25519_PRIVATE_KEY_SIZE`, `XED25519_PUBLIC_KEY_SIZE`, `XED25519_SIGNATURE_SIZE`, `XED25519_RANDOM_SIZE`
+
+- **New Rust crates:**
+  - `sc-ed25519` — Ed25519 signing (built on `ed25519-dalek`)
+  - `sc-xed25519` — XEd25519 with Curve25519 keys (built on `curve25519-dalek`)
+
+- **New runnable examples** in `examples/`:
+  - `basic.mjs` — ECDH + HKDF + AES-GCM
+  - `signing.mjs` — Ed25519 + XEd25519
+  - `aad.mjs` — AES-GCM with AAD
+  - `e2e-channel.mjs` — Complete E2E channel
+
+- **New documentation:**
+  - `MIGRATION.md` — Upgrade guide v0.1 → v0.2
+  - Updated `README.md`, `README.es.md`, `API.md`, `EXAMPLES.md`
+
+### 🔄 Changed
+
+- `VERSION` constant bumped to `'0.2.0'`
+- `package.json` keywords expanded with `ed25519`, `xed25519`, `aead`
+- `AesGcmParams` interface now includes optional `aad?: Buffer`
+
+### 🔒 Security
+
+- All new primitives use audited crates:
+  - `ed25519-dalek 2.x` — RFC 8032 reference implementation
+  - `curve25519-dalek 4.x` — Constant-time scalar operations
+- XEd25519 implementation follows the [Signal spec](https://signal.org/docs/specifications/xeddsa/)
+- All new Rust modules carry `#![deny(missing_docs)] #![deny(unsafe_code)] #![deny(clippy::unwrap_used)]`
+
+### ✅ Compatibility
+
+**100% backwards compatible with v0.1.0.** Every existing API works unchanged:
+
+- All existing imports continue to work
+- All existing function signatures unchanged
+- All existing error classes preserved
+- All existing constants preserved
+- Drop-in upgrade: just bump the version
+
+### 🧪 Testing
+
+- **Total: ~269 tests passing**
+- **Rust:** 48 tests (8 sc-aes incl. 3 AAD + 10 sc-ed25519 + 8 sc-xed25519 + existing)
+- **Vitest:** 172 tests across 4 files
+- **CJS:** 12 assertions
+- **ESM:** 15 assertions
+
+## [0.1.0] — 2026-05-18
+
+### ✨ Initial release
+
+- `Curve25519` — X25519 ECDH key agreement
+- `HKDF` — RFC 5869 key derivation (extract, expand, derive, deriveMultiple)
+- `AES_GCM` — AES-256-GCM authenticated encryption
+- `AES_CBC` — AES-256-CBC block cipher (paired with HMAC)
+- `HMAC` — HMAC-SHA256 with constant-time verification
+- `SHA256` — SHA-256 hashing (hash, hashAll)
+- Utility helpers: `secureRandom`, `randomNonce`, `randomIv`, `randomKey`, `toHex`, `fromHex`, `toBase64`, `fromBase64`, `toBase64Url`, `fromBase64Url`, `concat`, `zeroize`, `xor`, `constantTimeEqual`
+- Validators: `assertBuffer`, `assertBufferLength`, `assertBufferOfSize`, `assertPositiveInteger`, `assertHkdfLength`
+- Errors: `SignalisError`, `ValidationError`, `CryptoError`, `AuthenticationError`, `KeyDerivationError`, `LengthError`
+- TypeScript types: `KeyPair`, `PublicKey`, `PrivateKey`, `SharedSecret`, `HkdfParams`, etc.
+- Native bindings via napi-rs (7 platforms supported)
+- 172 tests passing
+
+[0.2.0]: https://github.com/Brashkie/signalis-core/releases/tag/v0.2.0
+[0.1.0]: https://github.com/Brashkie/signalis-core/releases/tag/v0.1.0

package/MIGRATION.md

@@ -0,0 +1,256 @@
+# Migration Guide
+
+## v0.1.0 → v0.2.0
+
+**TL;DR:** It's a 100% drop-in replacement. Just bump the version.
+
+```bash
+npm install @brashkie/signalis-core@^0.2.0
+```
+
+No code changes needed. All v0.1.0 APIs continue to work identically.
+
+---
+
+## What's New
+
+You now have access to:
+
+- **`Ed25519`** namespace for standard digital signatures
+- **`XEd25519`** namespace for Signal-style signatures with Curve25519 keys
+- **`AES_GCM.encryptWithAad()` / `decryptWithAad()`** for authenticated encryption with associated data
+- **`SignatureError`** class for signature verification failures
+- **`Signature`** branded type and **`asSignature()`** helper
+- New constants: `ED25519_*` and `XED25519_*`
+
+---
+
+## What's NOT Changed
+
+These continue to work exactly as in v0.1.0:
+
+| API | Status |
+|-----|--------|
+| `Curve25519.generateKeyPair()` | ✅ Unchanged — still returns `{ privateKey, publicKey }`, still frozen |
+| `Curve25519.publicFromPrivate()` | ✅ Unchanged |
+| `Curve25519.diffieHellman()` | ✅ Unchanged |
+| `HKDF.extract()`, `expand()`, `derive()`, `deriveMultiple()`, `deriveFromParams()` | ✅ Unchanged |
+| `AES_GCM.encrypt()`, `decrypt()` | ✅ Unchanged |
+| `AES_CBC.encrypt()`, `decrypt()` | ✅ Unchanged |
+| `HMAC.sha256()`, `verifySha256()` | ✅ Unchanged |
+| `SHA256.hash()`, `hashAll()` | ✅ Unchanged |
+| All utilities (`secureRandom`, `toHex`, etc.) | ✅ Unchanged |
+| All errors (`SignalisError`, `ValidationError`, etc.) | ✅ Unchanged |
+| All constants (`CURVE25519_*`, `AES_*`, `HKDF_*`, etc.) | ✅ Unchanged |
+| Default export (`SignalisCore`) | ✅ Unchanged (now includes `Ed25519` and `XEd25519`) |
+
+The only change you'll observe in your code base is that `VERSION === '0.2.0'`.
+
+---
+
+## Step-by-Step Migration
+
+### 1. Update the package
+
+```bash
+npm install @brashkie/signalis-core@^0.2.0
+```
+
+### 2. Verify
+
+```bash
+node -e "console.log(require('@brashkie/signalis-core').VERSION)"
+# Should print: 0.2.0
+```
+
+### 3. Run your tests
+
+Your existing test suite should pass without modifications. If anything fails, [open an issue](https://github.com/Brashkie/signalis-core/issues) — that would be a bug in v0.2.0.
+
+### 4. (Optional) Use new features
+
+#### Adopt Ed25519 for separate signing keys
+
+```typescript
+import { Ed25519 } from '@brashkie/signalis-core';
+
+const keys = Ed25519.generateKeyPair();
+const sig = Ed25519.sign(keys.privateKey, message);
+Ed25519.verify(keys.publicKey, message, sig);
+```
+
+#### Or adopt XEd25519 (Signal-style)
+
+```typescript
+import { Curve25519, XEd25519 } from '@brashkie/signalis-core';
+
+const identity = Curve25519.generateKeyPair();
+
+// Use the SAME key for both ECDH and signing:
+const shared = Curve25519.diffieHellman(identity.privateKey, peer);
+const sig = XEd25519.sign(identity.privateKey, message);
+XEd25519.verify(identity.publicKey, message, sig);
+```
+
+#### Bind metadata to ciphertext with AAD
+
+```typescript
+import { AES_GCM } from '@brashkie/signalis-core';
+
+const header = Buffer.from('msg_id=42|sender=alice');
+const ct = AES_GCM.encryptWithAad(key, nonce, plaintext, header);
+
+// Decrypt MUST pass same AAD or fails
+const pt = AES_GCM.decryptWithAad(key, nonce, ct, header);
+```
+
+---
+
+## Common Patterns
+
+### Pattern: Replacing HMAC-based authentication with proper signatures
+
+**Before (v0.1.0):**
+
+```typescript
+// Using HMAC over arbitrary data — symmetric, both parties share the key
+const tag = HMAC.sha256(sharedKey, dataToAuthenticate);
+const valid = HMAC.verifySha256(sharedKey, dataToAuthenticate, receivedTag);
+```
+
+**After (v0.2.0):**
+
+```typescript
+// Using Ed25519 — asymmetric, sender signs, anyone with public key verifies
+const sig = Ed25519.sign(signerPrivateKey, dataToAuthenticate);
+Ed25519.verify(signerPublicKey, dataToAuthenticate, sig);
+```
+
+**When to use which:**
+
+- **HMAC** — When both parties already share a secret (e.g., session key)
+- **Ed25519/XEd25519** — When sender's identity needs to be verified by parties who only have the sender's public key
+
+### Pattern: Single identity key for ECDH + Signing
+
+**Before (v0.1.0):**
+
+```typescript
+// Needed two separate keypairs
+const ecdhKeys = Curve25519.generateKeyPair();
+// (no native signing — would need to roll your own)
+```
+
+**After (v0.2.0):**
+
+```typescript
+// One keypair for both!
+const identity = Curve25519.generateKeyPair();
+
+// ECDH:
+const shared = Curve25519.diffieHellman(identity.privateKey, peerPublic);
+
+// Signing with the SAME key:
+const sig = XEd25519.sign(identity.privateKey, message);
+```
+
+This is the Signal Protocol's design: one identity key, multiple uses.
+
+### Pattern: Authenticated metadata in encrypted messages
+
+**Before (v0.1.0):**
+
+```typescript
+// Had to manually MAC the header alongside ciphertext
+const ciphertext = AES_GCM.encrypt(key, nonce, body);
+const headerMac = HMAC.sha256(key, header);
+const packet = Buffer.concat([header, headerMac, ciphertext]);
+// Receiver: verify MAC, then decrypt
+```
+
+**After (v0.2.0):**
+
+```typescript
+// AES-GCM with AAD handles both at once
+const ciphertext = AES_GCM.encryptWithAad(key, nonce, body, header);
+const packet = Buffer.concat([header, ciphertext]);
+// Receiver: decrypt with same header
+const body = AES_GCM.decryptWithAad(key, nonce, ciphertext, header);
+// Header tampering → AuthenticationError automatically
+```
+
+---
+
+## Performance Notes
+
+- **No regressions** — all v0.1.0 paths are unchanged
+- **New primitives:**
+  - Ed25519 signing: ~25,000 ops/sec
+  - Ed25519 verification: ~10,000 ops/sec
+  - XEd25519 signing: ~20,000 ops/sec
+  - XEd25519 verification: ~10,000 ops/sec
+  - AAD adds <5% overhead vs no AAD
+- **Bundle size:** +~50 KB (Ed25519 + XEd25519 Rust bindings, compressed)
+
+---
+
+## Compatibility Matrix
+
+| Node.js | Status |
+|---------|--------|
+| 18.x | ✅ Supported |
+| 20.x | ✅ Supported |
+| 22.x | ✅ Supported |
+| 24.x | ✅ Supported |
+
+| Platform | Status |
+|----------|--------|
+| Windows x64 (MSVC) | ✅ Prebuilt |
+| macOS x64 | ✅ Prebuilt |
+| macOS ARM64 | ✅ Prebuilt |
+| Linux x64 (glibc) | ✅ Prebuilt |
+| Linux x64 (musl) | ✅ Prebuilt |
+| Linux ARM64 (glibc) | ✅ Prebuilt |
+| Linux ARM64 (musl) | ✅ Prebuilt |
+
+---
+
+## FAQ
+
+### Q: Do I have to change anything in my code?
+
+**A:** No. v0.2.0 is 100% backwards compatible.
+
+### Q: When should I use Ed25519 vs XEd25519?
+
+**A:**
+- **Ed25519** if you want clean separation between signing and ECDH keys, or you need deterministic signatures.
+- **XEd25519** if you want to follow the Signal Protocol design (one identity key for both).
+
+### Q: Is XEd25519 less secure than Ed25519?
+
+**A:** No. Both provide the same 128-bit security level. XEd25519 is a clever construction that lets you reuse a Curve25519 key for signing without compromising security. It's been used by Signal in production for years.
+
+### Q: Does AAD add overhead?
+
+**A:** Negligible (<5%). AES-GCM natively supports AAD without performance penalty in the cryptographic operation; the small overhead is just the extra data passed across the NAPI boundary.
+
+### Q: Will there be a v0.3.0?
+
+**A:** Yes, but it will be handled by the higher-level `@brashkie/signalis` package, which builds X3DH and Double Ratchet on top of these primitives.
+
+### Q: What if I find a bug?
+
+**A:** [Open an issue](https://github.com/Brashkie/signalis-core/issues) on GitHub. For security issues, see [SECURITY.md](SECURITY.md) for the responsible disclosure process.
+
+---
+
+## Resources
+
+- [README.md](README.md) — Library overview
+- [API.md](API.md) — Full API reference
+- [EXAMPLES.md](EXAMPLES.md) — More usage examples
+- [`examples/`](examples/) — Runnable code samples
+- [CHANGELOG.md](CHANGELOG.md) — Full release history
+
+🦀 + ❤️ Hepein Oficial

package/NOTICE

@@ -1,12 +1,110 @@
-Signalis Core
-Copyright 2026 Brashkie (Hepein)
+@brashkie/signalis-core
+Copyright 2026 Brashkie / Hepein Oficial
 
-This product includes software developed by:
-  - The curve25519-dalek authors (https://github.com/dalek-cryptography/curve25519-dalek)
-  - The RustCrypto project (https://github.com/RustCrypto)
-  - The napi-rs project (https://github.com/napi-rs/napi-rs)
+This product is licensed under the Apache License, Version 2.0
+(see LICENSE file in the project root).
 
-Signal Protocol design © Open Whisper Systems / Signal Foundation.
-This implementation is independent and not affiliated with Signal Foundation.
+═══════════════════════════════════════════════════════════════════════════
+Third-party software included
+═══════════════════════════════════════════════════════════════════════════
 
-For the full list of dependencies and their licenses, see Cargo.lock and package.json.
+This product includes the following third-party software, licensed under
+their respective terms:
+
+─── Rust Dependencies ─────────────────────────────────────────────────────
+
+curve25519-dalek 4.x
+  Copyright (c) Isis Lovecruft, Henry de Valence
+  Licensed under BSD-3-Clause
+  https://github.com/dalek-cryptography/curve25519-dalek
+
+ed25519-dalek 2.x
+  Copyright (c) Isis Lovecruft
+  Licensed under BSD-3-Clause
+  https://github.com/dalek-cryptography/ed25519-dalek
+
+x25519-dalek 2.x
+  Copyright (c) Isis Lovecruft, Henry de Valence
+  Licensed under BSD-3-Clause
+  https://github.com/dalek-cryptography/x25519-dalek
+
+aes-gcm (RustCrypto)
+  Copyright (c) RustCrypto Developers
+  Licensed under Apache-2.0 OR MIT
+  https://github.com/RustCrypto/AEADs
+
+aes (RustCrypto)
+  Copyright (c) RustCrypto Developers
+  Licensed under Apache-2.0 OR MIT
+  https://github.com/RustCrypto/block-ciphers
+
+cbc (RustCrypto)
+  Copyright (c) RustCrypto Developers
+  Licensed under Apache-2.0 OR MIT
+  https://github.com/RustCrypto/block-modes
+
+sha2 (RustCrypto)
+  Copyright (c) RustCrypto Developers
+  Licensed under Apache-2.0 OR MIT
+  https://github.com/RustCrypto/hashes
+
+hmac (RustCrypto)
+  Copyright (c) RustCrypto Developers
+  Licensed under Apache-2.0 OR MIT
+  https://github.com/RustCrypto/MACs
+
+hkdf (RustCrypto)
+  Copyright (c) RustCrypto Developers
+  Licensed under Apache-2.0 OR MIT
+  https://github.com/RustCrypto/KDFs
+
+zeroize
+  Copyright (c) Tony Arcieri
+  Licensed under Apache-2.0 OR MIT
+  https://github.com/RustCrypto/utils/tree/master/zeroize
+
+subtle
+  Copyright (c) Isis Lovecruft, Henry de Valence
+  Licensed under BSD-3-Clause
+  https://github.com/dalek-cryptography/subtle
+
+rand
+  Licensed under Apache-2.0 OR MIT
+  https://github.com/rust-random/rand
+
+thiserror
+  Copyright (c) David Tolnay
+  Licensed under Apache-2.0 OR MIT
+  https://github.com/dtolnay/thiserror
+
+─── NAPI Bindings ────────────────────────────────────────────────────────
+
+napi-rs
+  Copyright (c) napi-rs contributors
+  Licensed under MIT
+  https://github.com/napi-rs/napi-rs
+
+═══════════════════════════════════════════════════════════════════════════
+Specifications referenced
+═══════════════════════════════════════════════════════════════════════════
+
+- RFC 7748 — Elliptic Curves for Security
+- RFC 8032 — Edwards-Curve Digital Signature Algorithm (EdDSA)
+- RFC 5869 — HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
+- NIST SP 800-38D — AES-GCM
+- FIPS 180-4 — Secure Hash Standard (SHA-256)
+- FIPS 198-1 — HMAC
+
+Signal Protocol specifications:
+- X3DH: https://signal.org/docs/specifications/x3dh/
+- Double Ratchet: https://signal.org/docs/specifications/doubleratchet/
+- XEdDSA: https://signal.org/docs/specifications/xeddsa/
+
+═══════════════════════════════════════════════════════════════════════════
+
+The full text of all third-party licenses can be found in the respective
+crate repositories linked above, or obtained by running:
+
+  cargo about generate licenses.html
+
+For questions about licensing, contact: brashkie@hepein.com