@brashkie/signalis-core 0.1.0 → 0.3.0

package/dist/index.d.mts

@@ -46,6 +46,12 @@ type PrivateKey = Buffer & {
 type SharedSecret = Buffer & {
     readonly __brand?: 'SharedSecret';
 };
+/**
+ * A digital signature (64 bytes) — Ed25519 or XEd25519.
+ */
+type Signature = Buffer & {
+    readonly __brand?: 'Signature';
+};
 /**
  * HKDF pseudorandom key (32 bytes), output of the Extract step.
  */
@@ -107,6 +113,10 @@ declare function asPrivateKey(buf: Buffer): PrivateKey;
  * Brand a Buffer as a {@link SharedSecret}.
  */
 declare function asSharedSecret(buf: Buffer): SharedSecret;
+/**
+ * Brand a Buffer as a {@link Signature} (NEW in v0.2.0).
+ */
+declare function asSignature(buf: Buffer): Signature;
 
 /**
  * Core cryptographic wrappers for signalis-core.
@@ -320,6 +330,28 @@ declare const AES_GCM: Readonly<{
     NONCE_SIZE: 12;
     /** Tag size in bytes (16). */
     TAG_SIZE: 16;
+    /**
+     * Encrypt with AES-256-GCM and Additional Authenticated Data (NEW in v0.2.0).
+     *
+     * AAD is authenticated but NOT encrypted. Useful for binding metadata
+     * (like message headers) to the ciphertext.
+     *
+     * @param key - 32-byte symmetric key
+     * @param nonce - 12-byte unique nonce
+     * @param plaintext - Data to encrypt
+     * @param aad - Additional authenticated data (any length, can be empty)
+     * @returns Ciphertext + auth tag
+     * @throws {ValidationError} On invalid sizes.
+     */
+    encryptWithAad(key: Buffer, nonce: Buffer, plaintext: Buffer, aad: Buffer): Buffer;
+    /**
+     * Decrypt with AES-256-GCM and AAD (NEW in v0.2.0).
+     *
+     * The same AAD used during encryption must be provided. Mismatch = failure.
+     *
+     * @throws {AuthenticationError} If tag verification fails (incl. AAD mismatch).
+     */
+    decryptWithAad(key: Buffer, nonce: Buffer, ciphertext: Buffer, aad: Buffer): Buffer;
 }>;
 /**
  * AES-256-CBC block cipher (NOT authenticated by itself).
@@ -415,10 +447,197 @@ declare const SHA256: Readonly<{
     /** Output size in bytes (32). */
     OUTPUT_SIZE: 32;
 }>;
+/**
+ * Ed25519 digital signatures (RFC 8032).
+ *
+ * Standard Ed25519 with deterministic signatures. Use when you want clean
+ * separation between signing and ECDH keys.
+ *
+ * @example
+ * ```ts
+ * import { Ed25519 } from '@brashkie/signalis-core';
+ *
+ * const keys = Ed25519.generateKeyPair();
+ * const sig = Ed25519.sign(keys.privateKey, Buffer.from('Hello'));
+ * Ed25519.verify(keys.publicKey, Buffer.from('Hello'), sig);
+ * ```
+ */
+declare const Ed25519: Readonly<{
+    /**
+     * Generate a new random Ed25519 keypair.
+     */
+    generateKeyPair(): KeyPair;
+    /**
+     * Derive a deterministic Ed25519 keypair from a 32-byte seed.
+     */
+    keyPairFromSeed(seed: Buffer): KeyPair;
+    /**
+     * Derive the public key from a private key.
+     */
+    publicFromPrivate(privateKey: Buffer): Buffer;
+    /**
+     * Sign a message. Ed25519 signatures are deterministic (RFC 8032).
+     */
+    sign(privateKey: Buffer, message: Buffer): Signature;
+    /**
+     * Verify a signature. Throws on failure.
+     *
+     * @throws {SignatureError} If signature is invalid.
+     */
+    verify(publicKey: Buffer, message: Buffer, signature: Buffer): void;
+    /**
+     * Verify a signature. Returns boolean (does not throw).
+     */
+    verifyBool(publicKey: Buffer, message: Buffer, signature: Buffer): boolean;
+    /** Private key size in bytes (32). */
+    PRIVATE_KEY_SIZE: 32;
+    /** Public key size in bytes (32). */
+    PUBLIC_KEY_SIZE: 32;
+    /** Signature size in bytes (64). */
+    SIGNATURE_SIZE: 64;
+    /** Seed size for deterministic keypair derivation (32). */
+    SEED_SIZE: 32;
+}>;
+/**
+ * XEd25519 — sign messages using the SAME Curve25519 keypair used for ECDH.
+ *
+ * This is what Signal Protocol uses to maintain a single identity key.
+ * Signatures are non-deterministic (each call gives a different valid sig).
+ *
+ * @example
+ * ```ts
+ * import { Curve25519, XEd25519 } from '@brashkie/signalis-core';
+ *
+ * const identity = Curve25519.generateKeyPair();
+ *
+ * // Use for ECDH:
+ * const shared = Curve25519.diffieHellman(identity.privateKey, peerPublic);
+ *
+ * // SAME key used to sign:
+ * const sig = XEd25519.sign(identity.privateKey, message);
+ * XEd25519.verify(identity.publicKey, message, sig);
+ * ```
+ */
+declare const XEd25519: Readonly<{
+    /**
+     * Sign a message using a Curve25519 private key. Uses OS RNG.
+     * Signatures are NOT deterministic (different each call).
+     */
+    sign(privateKey: Buffer, message: Buffer): Signature;
+    /**
+     * Sign with explicit 64-byte random nonce (for testing/reproducibility).
+     */
+    signWithRandom(privateKey: Buffer, message: Buffer, random: Buffer): Signature;
+    /**
+     * Verify a XEd25519 signature. Throws on failure.
+     *
+     * @throws {SignatureError} If signature is invalid.
+     */
+    verify(publicKey: Buffer, message: Buffer, signature: Buffer): void;
+    /**
+     * Verify a XEd25519 signature. Returns boolean (does not throw).
+     */
+    verifyBool(publicKey: Buffer, message: Buffer, signature: Buffer): boolean;
+    /** Private key size in bytes (32, same as Curve25519). */
+    PRIVATE_KEY_SIZE: 32;
+    /** Public key size in bytes (32, same as Curve25519). */
+    PUBLIC_KEY_SIZE: 32;
+    /** Signature size in bytes (64). */
+    SIGNATURE_SIZE: 64;
+    /** Random nonce size for signing (64). */
+    RANDOM_SIZE: 64;
+}>;
 /**
  * The version of the underlying Rust crate (from `Cargo.toml`).
  */
 declare const nativeVersion: string;
+/** ChaCha20-Poly1305 key size (bytes). */
+declare const CHACHA20_POLY1305_KEY_SIZE = 32;
+/** ChaCha20-Poly1305 nonce size (bytes). */
+declare const CHACHA20_POLY1305_NONCE_SIZE = 12;
+/** Poly1305 authentication tag size (bytes), appended to ciphertext. */
+declare const CHACHA20_POLY1305_TAG_SIZE = 16;
+/**
+ * ChaCha20-Poly1305 authenticated encryption with associated data (AEAD).
+ *
+ * RFC 8439-compliant alternative to AES-GCM. Same security guarantees,
+ * but typically 2-3x faster on platforms without AES-NI hardware
+ * (Android arm64-v8a without crypto extensions, IoT, older embedded).
+ *
+ * On servers and modern desktops with AES-NI, AES-GCM is usually faster
+ * — pick the cipher based on your deployment target.
+ *
+ * @example
+ * ```ts
+ * import { ChaCha20Poly1305, secureRandom } from '@brashkie/signalis-core';
+ *
+ * const key = secureRandom(32);
+ * const nonce = secureRandom(12);
+ * const ct = ChaCha20Poly1305.encrypt(key, nonce, Buffer.from('secret'));
+ * const pt = ChaCha20Poly1305.decrypt(key, nonce, ct);
+ * ```
+ */
+declare const ChaCha20Poly1305: Readonly<{
+    /**
+     * 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: Buffer, nonce: Buffer, plaintext: Buffer): Buffer;
+    /**
+     * Verify-then-decrypt. Returns plaintext on success, throws on auth failure.
+     */
+    decrypt(key: Buffer, nonce: Buffer, ciphertext: Buffer): Buffer;
+    /**
+     * 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: Buffer, nonce: Buffer, plaintext: Buffer, aad: Buffer): Buffer;
+    /**
+     * Verify (key + nonce + ciphertext + AAD) and decrypt.
+     */
+    decryptWithAad(key: Buffer, nonce: Buffer, ciphertext: Buffer, aad: Buffer): Buffer;
+    /** Key size in bytes (32). */
+    KEY_SIZE: 32;
+    /** Nonce size in bytes (12). */
+    NONCE_SIZE: 12;
+    /** Authentication tag size in bytes (16), appended to ciphertext. */
+    TAG_SIZE: 16;
+}>;
+/**
+ * Compare two buffers in constant time.
+ *
+ * Returns `true` only if both buffers have identical length AND contents.
+ *
+ * Use this for any secret comparison (MAC tags, signatures, tokens) where
+ * a fast-fail comparison could leak information via timing side-channels.
+ *
+ * **Wrong:**
+ * ```ts
+ * if (expectedMac.equals(receivedMac)) { ... }  // ← timing-vulnerable
+ * ```
+ *
+ * **Right:**
+ * ```ts
+ * if (constantTimeEq(expectedMac, receivedMac)) { ... }
+ * ```
+ */
+declare function constantTimeEq(a: Buffer, b: Buffer): boolean;
+/**
+ * Generate `size` cryptographically secure random bytes via the OS RNG
+ * (Rust side). Equivalent to {@link secureRandom} but routed through the
+ * native bindings — useful when you want to ensure entropy comes from the
+ * same source that the rest of the library uses internally.
+ *
+ * For most code, plain {@link secureRandom} (which uses `node:crypto`)
+ * is fine and avoids a NAPI hop.
+ */
+declare function nativeSecureRandom(size: number): Buffer;
 
 /**
  * Typed error classes for signalis-core.
@@ -485,6 +704,14 @@ declare class AuthenticationError extends CryptoError {
 declare class KeyDerivationError extends CryptoError {
     constructor(message: string);
 }
+/**
+ * Thrown when a digital signature verification fails (NEW in v0.2.0).
+ *
+ * Used by Ed25519 and XEd25519 verification.
+ */
+declare class SignatureError extends CryptoError {
+    constructor(message?: string);
+}
 /**
  * Thrown when the requested output length is invalid (e.g., HKDF > 8160 bytes).
  */
@@ -657,6 +884,22 @@ declare const CURVE25519_PRIVATE_KEY_SIZE = 32;
 declare const CURVE25519_PUBLIC_KEY_SIZE = 32;
 /** Size of an X25519 ECDH shared secret in bytes. */
 declare const CURVE25519_SHARED_SECRET_SIZE = 32;
+/** Size of an Ed25519 private key in bytes. */
+declare const ED25519_PRIVATE_KEY_SIZE = 32;
+/** Size of an Ed25519 public key in bytes. */
+declare const ED25519_PUBLIC_KEY_SIZE = 32;
+/** Size of an Ed25519 signature in bytes. */
+declare const ED25519_SIGNATURE_SIZE = 64;
+/** Size of an Ed25519 seed for deterministic key derivation. */
+declare const ED25519_SEED_SIZE = 32;
+/** Size of an XEd25519 private key in bytes (same as Curve25519). */
+declare const XED25519_PRIVATE_KEY_SIZE = 32;
+/** Size of an XEd25519 public key in bytes (same as Curve25519). */
+declare const XED25519_PUBLIC_KEY_SIZE = 32;
+/** Size of an XEd25519 signature in bytes. */
+declare const XED25519_SIGNATURE_SIZE = 64;
+/** Size of XEd25519 random nonce for signing (in bytes). */
+declare const XED25519_RANDOM_SIZE = 64;
 /** Size of HKDF-SHA256 PRK (pseudorandom key) in bytes. */
 declare const HKDF_PRK_SIZE = 32;
 /** Maximum HKDF-SHA256 output length: 255 * HashLen = 255 * 32 = 8160 bytes. */
@@ -695,7 +938,7 @@ declare const AES_GCM_RECOMMENDED_MESSAGES_PER_KEY = 4294967296;
  *
  * Bumped on every release.
  */
-declare const VERSION: "0.1.0";
+declare const VERSION: "0.2.0";
 
 /**
  * Default export — provides all primitives and helpers under one namespace.
@@ -717,6 +960,28 @@ declare const SignalisCore: Readonly<{
         PUBLIC_KEY_SIZE: 32;
         SHARED_SECRET_SIZE: 32;
     }>;
+    Ed25519: Readonly<{
+        generateKeyPair(): KeyPair;
+        keyPairFromSeed(seed: Buffer): KeyPair;
+        publicFromPrivate(privateKey: Buffer): Buffer;
+        sign(privateKey: Buffer, message: Buffer): Signature;
+        verify(publicKey: Buffer, message: Buffer, signature: Buffer): void;
+        verifyBool(publicKey: Buffer, message: Buffer, signature: Buffer): boolean;
+        PRIVATE_KEY_SIZE: 32;
+        PUBLIC_KEY_SIZE: 32;
+        SIGNATURE_SIZE: 64;
+        SEED_SIZE: 32;
+    }>;
+    XEd25519: Readonly<{
+        sign(privateKey: Buffer, message: Buffer): Signature;
+        signWithRandom(privateKey: Buffer, message: Buffer, random: Buffer): Signature;
+        verify(publicKey: Buffer, message: Buffer, signature: Buffer): void;
+        verifyBool(publicKey: Buffer, message: Buffer, signature: Buffer): boolean;
+        PRIVATE_KEY_SIZE: 32;
+        PUBLIC_KEY_SIZE: 32;
+        SIGNATURE_SIZE: 64;
+        RANDOM_SIZE: 64;
+    }>;
     HKDF: Readonly<{
         extract(salt: Buffer, ikm: Buffer): Buffer;
         expand(prk: Buffer, info: Buffer, length: number): Buffer;
@@ -731,6 +996,8 @@ declare const SignalisCore: Readonly<{
         KEY_SIZE: 32;
         NONCE_SIZE: 12;
         TAG_SIZE: 16;
+        encryptWithAad(key: Buffer, nonce: Buffer, plaintext: Buffer, aad: Buffer): Buffer;
+        decryptWithAad(key: Buffer, nonce: Buffer, ciphertext: Buffer, aad: Buffer): Buffer;
     }>;
     AES_CBC: Readonly<{
         encrypt(key: Buffer, iv: Buffer, plaintext: Buffer): Buffer;
@@ -757,8 +1024,8 @@ declare const SignalisCore: Readonly<{
     toBase64: typeof toBase64;
     fromBase64: typeof fromBase64;
     constantTimeEqual: typeof constantTimeEqual;
-    VERSION: "0.1.0";
+    VERSION: "0.2.0";
     nativeVersion: string;
 }>;
 
-export { AES_256_CBC_IV_SIZE, AES_256_GCM_NONCE_SIZE, AES_256_GCM_TAG_SIZE, AES_256_KEY_SIZE, AES_BLOCK_SIZE, AES_CBC, AES_GCM, AES_GCM_MAX_PLAINTEXT_SIZE, AES_GCM_RECOMMENDED_MESSAGES_PER_KEY, type AesCbcParams, type AesGcmParams, AuthenticationError, CURVE25519_PRIVATE_KEY_SIZE, CURVE25519_PUBLIC_KEY_SIZE, CURVE25519_SHARED_SECRET_SIZE, CryptoError, Curve25519, type Encoding, HKDF, HKDF_MAX_OUTPUT_SIZE, HKDF_PRK_SIZE, HMAC, HMAC_SHA256_TAG_SIZE, type HkdfParams, KeyDerivationError, type KeyPair, LengthError, type PrivateKey, type PseudoRandomKey, type PublicKey, SHA256, SHA256_BLOCK_SIZE, SHA256_OUTPUT_SIZE, type SharedSecret, SignalisError, VERSION, ValidationError, asPrivateKey, asPublicKey, asSharedSecret, assertBuffer, assertBufferLength, assertBufferOfSize, assertHkdfLength, assertPositiveInteger, bufferToString, buffersSameLength, concat, constantTimeEqual, SignalisCore as default, fromBase64, fromBase64Url, fromHex, nativeVersion, randomIv, randomKey, randomNonce, secureRandom, stringToBuffer, toBase64, toBase64Url, toHex, xor, zeroize };
+export { AES_256_CBC_IV_SIZE, AES_256_GCM_NONCE_SIZE, AES_256_GCM_TAG_SIZE, AES_256_KEY_SIZE, AES_BLOCK_SIZE, AES_CBC, AES_GCM, AES_GCM_MAX_PLAINTEXT_SIZE, AES_GCM_RECOMMENDED_MESSAGES_PER_KEY, type AesCbcParams, type AesGcmParams, 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, ED25519_PUBLIC_KEY_SIZE, ED25519_SEED_SIZE, ED25519_SIGNATURE_SIZE, Ed25519, type Encoding, HKDF, HKDF_MAX_OUTPUT_SIZE, HKDF_PRK_SIZE, HMAC, HMAC_SHA256_TAG_SIZE, type HkdfParams, KeyDerivationError, type KeyPair, LengthError, type PrivateKey, type PseudoRandomKey, type PublicKey, SHA256, SHA256_BLOCK_SIZE, SHA256_OUTPUT_SIZE, type SharedSecret, SignalisError, type Signature, SignatureError, VERSION, ValidationError, XED25519_PRIVATE_KEY_SIZE, XED25519_PUBLIC_KEY_SIZE, XED25519_RANDOM_SIZE, XED25519_SIGNATURE_SIZE, XEd25519, asPrivateKey, asPublicKey, asSharedSecret, asSignature, assertBuffer, assertBufferLength, assertBufferOfSize, assertHkdfLength, assertPositiveInteger, bufferToString, buffersSameLength, concat, constantTimeEq, constantTimeEqual, SignalisCore as default, fromBase64, fromBase64Url, fromHex, nativeSecureRandom, nativeVersion, randomIv, randomKey, randomNonce, secureRandom, stringToBuffer, toBase64, toBase64Url, toHex, xor, zeroize };

package/dist/index.d.ts

@@ -46,6 +46,12 @@ type PrivateKey = Buffer & {
 type SharedSecret = Buffer & {
     readonly __brand?: 'SharedSecret';
 };
+/**
+ * A digital signature (64 bytes) — Ed25519 or XEd25519.
+ */
+type Signature = Buffer & {
+    readonly __brand?: 'Signature';
+};
 /**
  * HKDF pseudorandom key (32 bytes), output of the Extract step.
  */
@@ -107,6 +113,10 @@ declare function asPrivateKey(buf: Buffer): PrivateKey;
  * Brand a Buffer as a {@link SharedSecret}.
  */
 declare function asSharedSecret(buf: Buffer): SharedSecret;
+/**
+ * Brand a Buffer as a {@link Signature} (NEW in v0.2.0).
+ */
+declare function asSignature(buf: Buffer): Signature;
 
 /**
  * Core cryptographic wrappers for signalis-core.
@@ -320,6 +330,28 @@ declare const AES_GCM: Readonly<{
     NONCE_SIZE: 12;
     /** Tag size in bytes (16). */
     TAG_SIZE: 16;
+    /**
+     * Encrypt with AES-256-GCM and Additional Authenticated Data (NEW in v0.2.0).
+     *
+     * AAD is authenticated but NOT encrypted. Useful for binding metadata
+     * (like message headers) to the ciphertext.
+     *
+     * @param key - 32-byte symmetric key
+     * @param nonce - 12-byte unique nonce
+     * @param plaintext - Data to encrypt
+     * @param aad - Additional authenticated data (any length, can be empty)
+     * @returns Ciphertext + auth tag
+     * @throws {ValidationError} On invalid sizes.
+     */
+    encryptWithAad(key: Buffer, nonce: Buffer, plaintext: Buffer, aad: Buffer): Buffer;
+    /**
+     * Decrypt with AES-256-GCM and AAD (NEW in v0.2.0).
+     *
+     * The same AAD used during encryption must be provided. Mismatch = failure.
+     *
+     * @throws {AuthenticationError} If tag verification fails (incl. AAD mismatch).
+     */
+    decryptWithAad(key: Buffer, nonce: Buffer, ciphertext: Buffer, aad: Buffer): Buffer;
 }>;
 /**
  * AES-256-CBC block cipher (NOT authenticated by itself).
@@ -415,10 +447,197 @@ declare const SHA256: Readonly<{
     /** Output size in bytes (32). */
     OUTPUT_SIZE: 32;
 }>;
+/**
+ * Ed25519 digital signatures (RFC 8032).
+ *
+ * Standard Ed25519 with deterministic signatures. Use when you want clean
+ * separation between signing and ECDH keys.
+ *
+ * @example
+ * ```ts
+ * import { Ed25519 } from '@brashkie/signalis-core';
+ *
+ * const keys = Ed25519.generateKeyPair();
+ * const sig = Ed25519.sign(keys.privateKey, Buffer.from('Hello'));
+ * Ed25519.verify(keys.publicKey, Buffer.from('Hello'), sig);
+ * ```
+ */
+declare const Ed25519: Readonly<{
+    /**
+     * Generate a new random Ed25519 keypair.
+     */
+    generateKeyPair(): KeyPair;
+    /**
+     * Derive a deterministic Ed25519 keypair from a 32-byte seed.
+     */
+    keyPairFromSeed(seed: Buffer): KeyPair;
+    /**
+     * Derive the public key from a private key.
+     */
+    publicFromPrivate(privateKey: Buffer): Buffer;
+    /**
+     * Sign a message. Ed25519 signatures are deterministic (RFC 8032).
+     */
+    sign(privateKey: Buffer, message: Buffer): Signature;
+    /**
+     * Verify a signature. Throws on failure.
+     *
+     * @throws {SignatureError} If signature is invalid.
+     */
+    verify(publicKey: Buffer, message: Buffer, signature: Buffer): void;
+    /**
+     * Verify a signature. Returns boolean (does not throw).
+     */
+    verifyBool(publicKey: Buffer, message: Buffer, signature: Buffer): boolean;
+    /** Private key size in bytes (32). */
+    PRIVATE_KEY_SIZE: 32;
+    /** Public key size in bytes (32). */
+    PUBLIC_KEY_SIZE: 32;
+    /** Signature size in bytes (64). */
+    SIGNATURE_SIZE: 64;
+    /** Seed size for deterministic keypair derivation (32). */
+    SEED_SIZE: 32;
+}>;
+/**
+ * XEd25519 — sign messages using the SAME Curve25519 keypair used for ECDH.
+ *
+ * This is what Signal Protocol uses to maintain a single identity key.
+ * Signatures are non-deterministic (each call gives a different valid sig).
+ *
+ * @example
+ * ```ts
+ * import { Curve25519, XEd25519 } from '@brashkie/signalis-core';
+ *
+ * const identity = Curve25519.generateKeyPair();
+ *
+ * // Use for ECDH:
+ * const shared = Curve25519.diffieHellman(identity.privateKey, peerPublic);
+ *
+ * // SAME key used to sign:
+ * const sig = XEd25519.sign(identity.privateKey, message);
+ * XEd25519.verify(identity.publicKey, message, sig);
+ * ```
+ */
+declare const XEd25519: Readonly<{
+    /**
+     * Sign a message using a Curve25519 private key. Uses OS RNG.
+     * Signatures are NOT deterministic (different each call).
+     */
+    sign(privateKey: Buffer, message: Buffer): Signature;
+    /**
+     * Sign with explicit 64-byte random nonce (for testing/reproducibility).
+     */
+    signWithRandom(privateKey: Buffer, message: Buffer, random: Buffer): Signature;
+    /**
+     * Verify a XEd25519 signature. Throws on failure.
+     *
+     * @throws {SignatureError} If signature is invalid.
+     */
+    verify(publicKey: Buffer, message: Buffer, signature: Buffer): void;
+    /**
+     * Verify a XEd25519 signature. Returns boolean (does not throw).
+     */
+    verifyBool(publicKey: Buffer, message: Buffer, signature: Buffer): boolean;
+    /** Private key size in bytes (32, same as Curve25519). */
+    PRIVATE_KEY_SIZE: 32;
+    /** Public key size in bytes (32, same as Curve25519). */
+    PUBLIC_KEY_SIZE: 32;
+    /** Signature size in bytes (64). */
+    SIGNATURE_SIZE: 64;
+    /** Random nonce size for signing (64). */
+    RANDOM_SIZE: 64;
+}>;
 /**
  * The version of the underlying Rust crate (from `Cargo.toml`).
  */
 declare const nativeVersion: string;
+/** ChaCha20-Poly1305 key size (bytes). */
+declare const CHACHA20_POLY1305_KEY_SIZE = 32;
+/** ChaCha20-Poly1305 nonce size (bytes). */
+declare const CHACHA20_POLY1305_NONCE_SIZE = 12;
+/** Poly1305 authentication tag size (bytes), appended to ciphertext. */
+declare const CHACHA20_POLY1305_TAG_SIZE = 16;
+/**
+ * ChaCha20-Poly1305 authenticated encryption with associated data (AEAD).
+ *
+ * RFC 8439-compliant alternative to AES-GCM. Same security guarantees,
+ * but typically 2-3x faster on platforms without AES-NI hardware
+ * (Android arm64-v8a without crypto extensions, IoT, older embedded).
+ *
+ * On servers and modern desktops with AES-NI, AES-GCM is usually faster
+ * — pick the cipher based on your deployment target.
+ *
+ * @example
+ * ```ts
+ * import { ChaCha20Poly1305, secureRandom } from '@brashkie/signalis-core';
+ *
+ * const key = secureRandom(32);
+ * const nonce = secureRandom(12);
+ * const ct = ChaCha20Poly1305.encrypt(key, nonce, Buffer.from('secret'));
+ * const pt = ChaCha20Poly1305.decrypt(key, nonce, ct);
+ * ```
+ */
+declare const ChaCha20Poly1305: Readonly<{
+    /**
+     * 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: Buffer, nonce: Buffer, plaintext: Buffer): Buffer;
+    /**
+     * Verify-then-decrypt. Returns plaintext on success, throws on auth failure.
+     */
+    decrypt(key: Buffer, nonce: Buffer, ciphertext: Buffer): Buffer;
+    /**
+     * 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: Buffer, nonce: Buffer, plaintext: Buffer, aad: Buffer): Buffer;
+    /**
+     * Verify (key + nonce + ciphertext + AAD) and decrypt.
+     */
+    decryptWithAad(key: Buffer, nonce: Buffer, ciphertext: Buffer, aad: Buffer): Buffer;
+    /** Key size in bytes (32). */
+    KEY_SIZE: 32;
+    /** Nonce size in bytes (12). */
+    NONCE_SIZE: 12;
+    /** Authentication tag size in bytes (16), appended to ciphertext. */
+    TAG_SIZE: 16;
+}>;
+/**
+ * Compare two buffers in constant time.
+ *
+ * Returns `true` only if both buffers have identical length AND contents.
+ *
+ * Use this for any secret comparison (MAC tags, signatures, tokens) where
+ * a fast-fail comparison could leak information via timing side-channels.
+ *
+ * **Wrong:**
+ * ```ts
+ * if (expectedMac.equals(receivedMac)) { ... }  // ← timing-vulnerable
+ * ```
+ *
+ * **Right:**
+ * ```ts
+ * if (constantTimeEq(expectedMac, receivedMac)) { ... }
+ * ```
+ */
+declare function constantTimeEq(a: Buffer, b: Buffer): boolean;
+/**
+ * Generate `size` cryptographically secure random bytes via the OS RNG
+ * (Rust side). Equivalent to {@link secureRandom} but routed through the
+ * native bindings — useful when you want to ensure entropy comes from the
+ * same source that the rest of the library uses internally.
+ *
+ * For most code, plain {@link secureRandom} (which uses `node:crypto`)
+ * is fine and avoids a NAPI hop.
+ */
+declare function nativeSecureRandom(size: number): Buffer;
 
 /**
  * Typed error classes for signalis-core.
@@ -485,6 +704,14 @@ declare class AuthenticationError extends CryptoError {
 declare class KeyDerivationError extends CryptoError {
     constructor(message: string);
 }
+/**
+ * Thrown when a digital signature verification fails (NEW in v0.2.0).
+ *
+ * Used by Ed25519 and XEd25519 verification.
+ */
+declare class SignatureError extends CryptoError {
+    constructor(message?: string);
+}
 /**
  * Thrown when the requested output length is invalid (e.g., HKDF > 8160 bytes).
  */
@@ -657,6 +884,22 @@ declare const CURVE25519_PRIVATE_KEY_SIZE = 32;
 declare const CURVE25519_PUBLIC_KEY_SIZE = 32;
 /** Size of an X25519 ECDH shared secret in bytes. */
 declare const CURVE25519_SHARED_SECRET_SIZE = 32;
+/** Size of an Ed25519 private key in bytes. */
+declare const ED25519_PRIVATE_KEY_SIZE = 32;
+/** Size of an Ed25519 public key in bytes. */
+declare const ED25519_PUBLIC_KEY_SIZE = 32;
+/** Size of an Ed25519 signature in bytes. */
+declare const ED25519_SIGNATURE_SIZE = 64;
+/** Size of an Ed25519 seed for deterministic key derivation. */
+declare const ED25519_SEED_SIZE = 32;
+/** Size of an XEd25519 private key in bytes (same as Curve25519). */
+declare const XED25519_PRIVATE_KEY_SIZE = 32;
+/** Size of an XEd25519 public key in bytes (same as Curve25519). */
+declare const XED25519_PUBLIC_KEY_SIZE = 32;
+/** Size of an XEd25519 signature in bytes. */
+declare const XED25519_SIGNATURE_SIZE = 64;
+/** Size of XEd25519 random nonce for signing (in bytes). */
+declare const XED25519_RANDOM_SIZE = 64;
 /** Size of HKDF-SHA256 PRK (pseudorandom key) in bytes. */
 declare const HKDF_PRK_SIZE = 32;
 /** Maximum HKDF-SHA256 output length: 255 * HashLen = 255 * 32 = 8160 bytes. */
@@ -695,7 +938,7 @@ declare const AES_GCM_RECOMMENDED_MESSAGES_PER_KEY = 4294967296;
  *
  * Bumped on every release.
  */
-declare const VERSION: "0.1.0";
+declare const VERSION: "0.2.0";
 
 /**
  * Default export — provides all primitives and helpers under one namespace.
@@ -717,6 +960,28 @@ declare const SignalisCore: Readonly<{
         PUBLIC_KEY_SIZE: 32;
         SHARED_SECRET_SIZE: 32;
     }>;
+    Ed25519: Readonly<{
+        generateKeyPair(): KeyPair;
+        keyPairFromSeed(seed: Buffer): KeyPair;
+        publicFromPrivate(privateKey: Buffer): Buffer;
+        sign(privateKey: Buffer, message: Buffer): Signature;
+        verify(publicKey: Buffer, message: Buffer, signature: Buffer): void;
+        verifyBool(publicKey: Buffer, message: Buffer, signature: Buffer): boolean;
+        PRIVATE_KEY_SIZE: 32;
+        PUBLIC_KEY_SIZE: 32;
+        SIGNATURE_SIZE: 64;
+        SEED_SIZE: 32;
+    }>;
+    XEd25519: Readonly<{
+        sign(privateKey: Buffer, message: Buffer): Signature;
+        signWithRandom(privateKey: Buffer, message: Buffer, random: Buffer): Signature;
+        verify(publicKey: Buffer, message: Buffer, signature: Buffer): void;
+        verifyBool(publicKey: Buffer, message: Buffer, signature: Buffer): boolean;
+        PRIVATE_KEY_SIZE: 32;
+        PUBLIC_KEY_SIZE: 32;
+        SIGNATURE_SIZE: 64;
+        RANDOM_SIZE: 64;
+    }>;
     HKDF: Readonly<{
         extract(salt: Buffer, ikm: Buffer): Buffer;
         expand(prk: Buffer, info: Buffer, length: number): Buffer;
@@ -731,6 +996,8 @@ declare const SignalisCore: Readonly<{
         KEY_SIZE: 32;
         NONCE_SIZE: 12;
         TAG_SIZE: 16;
+        encryptWithAad(key: Buffer, nonce: Buffer, plaintext: Buffer, aad: Buffer): Buffer;
+        decryptWithAad(key: Buffer, nonce: Buffer, ciphertext: Buffer, aad: Buffer): Buffer;
     }>;
     AES_CBC: Readonly<{
         encrypt(key: Buffer, iv: Buffer, plaintext: Buffer): Buffer;
@@ -757,8 +1024,8 @@ declare const SignalisCore: Readonly<{
     toBase64: typeof toBase64;
     fromBase64: typeof fromBase64;
     constantTimeEqual: typeof constantTimeEqual;
-    VERSION: "0.1.0";
+    VERSION: "0.2.0";
     nativeVersion: string;
 }>;
 
-export { AES_256_CBC_IV_SIZE, AES_256_GCM_NONCE_SIZE, AES_256_GCM_TAG_SIZE, AES_256_KEY_SIZE, AES_BLOCK_SIZE, AES_CBC, AES_GCM, AES_GCM_MAX_PLAINTEXT_SIZE, AES_GCM_RECOMMENDED_MESSAGES_PER_KEY, type AesCbcParams, type AesGcmParams, AuthenticationError, CURVE25519_PRIVATE_KEY_SIZE, CURVE25519_PUBLIC_KEY_SIZE, CURVE25519_SHARED_SECRET_SIZE, CryptoError, Curve25519, type Encoding, HKDF, HKDF_MAX_OUTPUT_SIZE, HKDF_PRK_SIZE, HMAC, HMAC_SHA256_TAG_SIZE, type HkdfParams, KeyDerivationError, type KeyPair, LengthError, type PrivateKey, type PseudoRandomKey, type PublicKey, SHA256, SHA256_BLOCK_SIZE, SHA256_OUTPUT_SIZE, type SharedSecret, SignalisError, VERSION, ValidationError, asPrivateKey, asPublicKey, asSharedSecret, assertBuffer, assertBufferLength, assertBufferOfSize, assertHkdfLength, assertPositiveInteger, bufferToString, buffersSameLength, concat, constantTimeEqual, SignalisCore as default, fromBase64, fromBase64Url, fromHex, nativeVersion, randomIv, randomKey, randomNonce, secureRandom, stringToBuffer, toBase64, toBase64Url, toHex, xor, zeroize };
+export { AES_256_CBC_IV_SIZE, AES_256_GCM_NONCE_SIZE, AES_256_GCM_TAG_SIZE, AES_256_KEY_SIZE, AES_BLOCK_SIZE, AES_CBC, AES_GCM, AES_GCM_MAX_PLAINTEXT_SIZE, AES_GCM_RECOMMENDED_MESSAGES_PER_KEY, type AesCbcParams, type AesGcmParams, 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, ED25519_PUBLIC_KEY_SIZE, ED25519_SEED_SIZE, ED25519_SIGNATURE_SIZE, Ed25519, type Encoding, HKDF, HKDF_MAX_OUTPUT_SIZE, HKDF_PRK_SIZE, HMAC, HMAC_SHA256_TAG_SIZE, type HkdfParams, KeyDerivationError, type KeyPair, LengthError, type PrivateKey, type PseudoRandomKey, type PublicKey, SHA256, SHA256_BLOCK_SIZE, SHA256_OUTPUT_SIZE, type SharedSecret, SignalisError, type Signature, SignatureError, VERSION, ValidationError, XED25519_PRIVATE_KEY_SIZE, XED25519_PUBLIC_KEY_SIZE, XED25519_RANDOM_SIZE, XED25519_SIGNATURE_SIZE, XEd25519, asPrivateKey, asPublicKey, asSharedSecret, asSignature, assertBuffer, assertBufferLength, assertBufferOfSize, assertHkdfLength, assertPositiveInteger, bufferToString, buffersSameLength, concat, constantTimeEq, constantTimeEqual, SignalisCore as default, fromBase64, fromBase64Url, fromHex, nativeSecureRandom, nativeVersion, randomIv, randomKey, randomNonce, secureRandom, stringToBuffer, toBase64, toBase64Url, toHex, xor, zeroize };