@brashkie/signalis-core 0.1.0 → 0.3.0

package/dist/index.mjs

@@ -5,6 +5,14 @@ import * as native from "../index.js";
 var CURVE25519_PRIVATE_KEY_SIZE = 32;
 var CURVE25519_PUBLIC_KEY_SIZE = 32;
 var CURVE25519_SHARED_SECRET_SIZE = 32;
+var ED25519_PRIVATE_KEY_SIZE = 32;
+var ED25519_PUBLIC_KEY_SIZE = 32;
+var ED25519_SIGNATURE_SIZE = 64;
+var ED25519_SEED_SIZE = 32;
+var XED25519_PRIVATE_KEY_SIZE = 32;
+var XED25519_PUBLIC_KEY_SIZE = 32;
+var XED25519_SIGNATURE_SIZE = 64;
+var XED25519_RANDOM_SIZE = 64;
 var HKDF_PRK_SIZE = 32;
 var HKDF_MAX_OUTPUT_SIZE = 8160;
 var AES_256_KEY_SIZE = 32;
@@ -67,6 +75,12 @@ var KeyDerivationError = class extends CryptoError {
     this.name = "KeyDerivationError";
   }
 };
+var SignatureError = class extends CryptoError {
+  constructor(message = "Signature verification failed") {
+    super(message, "verify_signature");
+    this.name = "SignatureError";
+  }
+};
 var LengthError = class extends ValidationError {
   constructor(message, options = {}) {
     super(message, options);
@@ -346,7 +360,53 @@ var AES_GCM = Object.freeze({
   /** Nonce size in bytes (12). */
   NONCE_SIZE: AES_256_GCM_NONCE_SIZE,
   /** Tag size in bytes (16). */
-  TAG_SIZE: AES_256_GCM_TAG_SIZE
+  TAG_SIZE: AES_256_GCM_TAG_SIZE,
+  /**
+   * 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, nonce, plaintext, aad) {
+    assertBufferOfSize(key, AES_256_KEY_SIZE, "key");
+    assertBufferOfSize(nonce, AES_256_GCM_NONCE_SIZE, "nonce");
+    assertBuffer(plaintext, "plaintext");
+    assertBuffer(aad, "aad");
+    return native.aes256GcmEncryptWithAad(key, nonce, plaintext, aad);
+  },
+  /**
+   * 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, nonce, ciphertext, aad) {
+    assertBufferOfSize(key, AES_256_KEY_SIZE, "key");
+    assertBufferOfSize(nonce, AES_256_GCM_NONCE_SIZE, "nonce");
+    assertBuffer(ciphertext, "ciphertext");
+    assertBuffer(aad, "aad");
+    if (ciphertext.length < AES_256_GCM_TAG_SIZE) {
+      throw new CryptoError(
+        `Ciphertext too short: must be at least ${AES_256_GCM_TAG_SIZE} bytes (tag size)`,
+        "aes_gcm_decrypt_with_aad"
+      );
+    }
+    try {
+      return native.aes256GcmDecryptWithAad(key, nonce, ciphertext, aad);
+    } catch (e) {
+      throw new AuthenticationError(
+        `AES-256-GCM authentication failed: ${e.message}`
+      );
+    }
+  }
 });
 var AES_CBC = Object.freeze({
   /**
@@ -451,7 +511,220 @@ var SHA256 = Object.freeze({
   /** Output size in bytes (32). */
   OUTPUT_SIZE: SHA256_OUTPUT_SIZE
 });
+var Ed25519 = Object.freeze({
+  /**
+   * Generate a new random Ed25519 keypair.
+   */
+  generateKeyPair() {
+    const kp = native.ed25519GenerateKeypair();
+    return Object.freeze({
+      privateKey: kp.private,
+      publicKey: kp.public
+    });
+  },
+  /**
+   * Derive a deterministic Ed25519 keypair from a 32-byte seed.
+   */
+  keyPairFromSeed(seed) {
+    assertBufferOfSize(seed, ED25519_SEED_SIZE, "seed");
+    const kp = native.ed25519KeypairFromSeed(seed);
+    return Object.freeze({
+      privateKey: kp.private,
+      publicKey: kp.public
+    });
+  },
+  /**
+   * Derive the public key from a private key.
+   */
+  publicFromPrivate(privateKey) {
+    assertBufferOfSize(privateKey, ED25519_PRIVATE_KEY_SIZE, "privateKey");
+    return native.ed25519PublicFromPrivate(privateKey);
+  },
+  /**
+   * Sign a message. Ed25519 signatures are deterministic (RFC 8032).
+   */
+  sign(privateKey, message) {
+    assertBufferOfSize(privateKey, ED25519_PRIVATE_KEY_SIZE, "privateKey");
+    assertBuffer(message, "message");
+    return native.ed25519Sign(privateKey, message);
+  },
+  /**
+   * Verify a signature. Throws on failure.
+   *
+   * @throws {SignatureError} If signature is invalid.
+   */
+  verify(publicKey, message, signature) {
+    assertBufferOfSize(publicKey, ED25519_PUBLIC_KEY_SIZE, "publicKey");
+    assertBuffer(message, "message");
+    assertBufferOfSize(signature, ED25519_SIGNATURE_SIZE, "signature");
+    try {
+      native.ed25519Verify(publicKey, message, signature);
+    } catch (e) {
+      throw new SignatureError(e.message);
+    }
+  },
+  /**
+   * Verify a signature. Returns boolean (does not throw).
+   */
+  verifyBool(publicKey, message, signature) {
+    if (!Buffer.isBuffer(publicKey) || publicKey.length !== ED25519_PUBLIC_KEY_SIZE) return false;
+    if (!Buffer.isBuffer(message)) return false;
+    if (!Buffer.isBuffer(signature) || signature.length !== ED25519_SIGNATURE_SIZE) return false;
+    return native.ed25519VerifyBool(publicKey, message, signature);
+  },
+  /** Private key size in bytes (32). */
+  PRIVATE_KEY_SIZE: ED25519_PRIVATE_KEY_SIZE,
+  /** Public key size in bytes (32). */
+  PUBLIC_KEY_SIZE: ED25519_PUBLIC_KEY_SIZE,
+  /** Signature size in bytes (64). */
+  SIGNATURE_SIZE: ED25519_SIGNATURE_SIZE,
+  /** Seed size for deterministic keypair derivation (32). */
+  SEED_SIZE: ED25519_SEED_SIZE
+});
+var XEd25519 = Object.freeze({
+  /**
+   * Sign a message using a Curve25519 private key. Uses OS RNG.
+   * Signatures are NOT deterministic (different each call).
+   */
+  sign(privateKey, message) {
+    assertBufferOfSize(privateKey, XED25519_PRIVATE_KEY_SIZE, "privateKey");
+    assertBuffer(message, "message");
+    return native.xed25519Sign(privateKey, message);
+  },
+  /**
+   * Sign with explicit 64-byte random nonce (for testing/reproducibility).
+   */
+  signWithRandom(privateKey, message, random) {
+    assertBufferOfSize(privateKey, XED25519_PRIVATE_KEY_SIZE, "privateKey");
+    assertBuffer(message, "message");
+    assertBufferOfSize(random, XED25519_RANDOM_SIZE, "random");
+    return native.xed25519SignWithRandom(privateKey, message, random);
+  },
+  /**
+   * Verify a XEd25519 signature. Throws on failure.
+   *
+   * @throws {SignatureError} If signature is invalid.
+   */
+  verify(publicKey, message, signature) {
+    assertBufferOfSize(publicKey, XED25519_PUBLIC_KEY_SIZE, "publicKey");
+    assertBuffer(message, "message");
+    assertBufferOfSize(signature, XED25519_SIGNATURE_SIZE, "signature");
+    try {
+      native.xed25519Verify(publicKey, message, signature);
+    } catch (e) {
+      throw new SignatureError(e.message);
+    }
+  },
+  /**
+   * Verify a XEd25519 signature. Returns boolean (does not throw).
+   */
+  verifyBool(publicKey, message, signature) {
+    if (!Buffer.isBuffer(publicKey) || publicKey.length !== XED25519_PUBLIC_KEY_SIZE) return false;
+    if (!Buffer.isBuffer(message)) return false;
+    if (!Buffer.isBuffer(signature) || signature.length !== XED25519_SIGNATURE_SIZE) return false;
+    return native.xed25519VerifyBool(publicKey, message, signature);
+  },
+  /** Private key size in bytes (32, same as Curve25519). */
+  PRIVATE_KEY_SIZE: XED25519_PRIVATE_KEY_SIZE,
+  /** Public key size in bytes (32, same as Curve25519). */
+  PUBLIC_KEY_SIZE: XED25519_PUBLIC_KEY_SIZE,
+  /** Signature size in bytes (64). */
+  SIGNATURE_SIZE: XED25519_SIGNATURE_SIZE,
+  /** Random nonce size for signing (64). */
+  RANDOM_SIZE: XED25519_RANDOM_SIZE
+});
 var nativeVersion = native.version();
+var CHACHA20_POLY1305_KEY_SIZE = 32;
+var CHACHA20_POLY1305_NONCE_SIZE = 12;
+var CHACHA20_POLY1305_TAG_SIZE = 16;
+var ChaCha20Poly1305 = Object.freeze({
+  /**
+   * Encrypt + authenticate `plaintext`.
+   *
+   * @param key 32-byte key
+   * @param nonce 12-byte nonce — MUST be unique per (key, plaintext)
+   * @param plaintext data to encrypt
+   * @returns ciphertext || tag (16 bytes appended)
+   */
+  encrypt(key, nonce, plaintext) {
+    if (!Buffer.isBuffer(key) || key.length !== CHACHA20_POLY1305_KEY_SIZE) {
+      throw new RangeError(`key must be ${CHACHA20_POLY1305_KEY_SIZE} bytes`);
+    }
+    if (!Buffer.isBuffer(nonce) || nonce.length !== CHACHA20_POLY1305_NONCE_SIZE) {
+      throw new RangeError(`nonce must be ${CHACHA20_POLY1305_NONCE_SIZE} bytes`);
+    }
+    if (!Buffer.isBuffer(plaintext)) {
+      throw new TypeError("plaintext must be a Buffer");
+    }
+    return native.chacha20Poly1305Encrypt(key, nonce, plaintext);
+  },
+  /**
+   * Verify-then-decrypt. Returns plaintext on success, throws on auth failure.
+   */
+  decrypt(key, nonce, ciphertext) {
+    if (!Buffer.isBuffer(key) || key.length !== CHACHA20_POLY1305_KEY_SIZE) {
+      throw new RangeError(`key must be ${CHACHA20_POLY1305_KEY_SIZE} bytes`);
+    }
+    if (!Buffer.isBuffer(nonce) || nonce.length !== CHACHA20_POLY1305_NONCE_SIZE) {
+      throw new RangeError(`nonce must be ${CHACHA20_POLY1305_NONCE_SIZE} bytes`);
+    }
+    if (!Buffer.isBuffer(ciphertext)) {
+      throw new TypeError("ciphertext must be a Buffer");
+    }
+    return native.chacha20Poly1305Decrypt(key, nonce, ciphertext);
+  },
+  /**
+   * Encrypt + authenticate with Additional Authenticated Data.
+   *
+   * AAD is NOT encrypted but IS authenticated. Use for plaintext metadata
+   * (e.g., message headers) that must not be tampered with.
+   */
+  encryptWithAad(key, nonce, plaintext, aad) {
+    if (!Buffer.isBuffer(key) || key.length !== CHACHA20_POLY1305_KEY_SIZE) {
+      throw new RangeError(`key must be ${CHACHA20_POLY1305_KEY_SIZE} bytes`);
+    }
+    if (!Buffer.isBuffer(nonce) || nonce.length !== CHACHA20_POLY1305_NONCE_SIZE) {
+      throw new RangeError(`nonce must be ${CHACHA20_POLY1305_NONCE_SIZE} bytes`);
+    }
+    if (!Buffer.isBuffer(plaintext) || !Buffer.isBuffer(aad)) {
+      throw new TypeError("plaintext and aad must be Buffers");
+    }
+    return native.chacha20Poly1305EncryptWithAad(key, nonce, plaintext, aad);
+  },
+  /**
+   * Verify (key + nonce + ciphertext + AAD) and decrypt.
+   */
+  decryptWithAad(key, nonce, ciphertext, aad) {
+    if (!Buffer.isBuffer(key) || key.length !== CHACHA20_POLY1305_KEY_SIZE) {
+      throw new RangeError(`key must be ${CHACHA20_POLY1305_KEY_SIZE} bytes`);
+    }
+    if (!Buffer.isBuffer(nonce) || nonce.length !== CHACHA20_POLY1305_NONCE_SIZE) {
+      throw new RangeError(`nonce must be ${CHACHA20_POLY1305_NONCE_SIZE} bytes`);
+    }
+    if (!Buffer.isBuffer(ciphertext) || !Buffer.isBuffer(aad)) {
+      throw new TypeError("ciphertext and aad must be Buffers");
+    }
+    return native.chacha20Poly1305DecryptWithAad(key, nonce, ciphertext, aad);
+  },
+  /** Key size in bytes (32). */
+  KEY_SIZE: CHACHA20_POLY1305_KEY_SIZE,
+  /** Nonce size in bytes (12). */
+  NONCE_SIZE: CHACHA20_POLY1305_NONCE_SIZE,
+  /** Authentication tag size in bytes (16), appended to ciphertext. */
+  TAG_SIZE: CHACHA20_POLY1305_TAG_SIZE
+});
+function constantTimeEq2(a, b) {
+  if (!Buffer.isBuffer(a) || !Buffer.isBuffer(b)) {
+    throw new TypeError("constantTimeEq: both arguments must be Buffers");
+  }
+  return native.constantTimeEq(a, b);
+}
+function nativeSecureRandom(size) {
+  if (!Number.isInteger(size) || size <= 0) {
+    throw new RangeError(`size must be a positive integer, got ${size}`);
+  }
+  return native.secureRandom(size);
+}
 
 // src/types.ts
 function asPublicKey(buf) {
@@ -463,10 +736,13 @@ function asPrivateKey(buf) {
 function asSharedSecret(buf) {
   return buf;
 }
+function asSignature(buf) {
+  return buf;
+}
 
 // src/utils.ts
 import { randomBytes, timingSafeEqual } from "crypto";
-function secureRandom(length) {
+function secureRandom2(length) {
   if (!Number.isInteger(length) || length < 0) {
     throw new RangeError(`length must be a non-negative integer, got ${length}`);
   }
@@ -536,17 +812,19 @@ function xor(a, b) {
 }
 
 // src/index.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 var SignalisCore = Object.freeze({
   // Crypto primitives
   Curve25519,
+  Ed25519,
+  XEd25519,
   HKDF,
   AES_GCM,
   AES_CBC,
   HMAC,
   SHA256,
   // Random
-  secureRandom,
+  secureRandom: secureRandom2,
   randomNonce,
   randomIv,
   randomKey,
@@ -558,7 +836,7 @@ var SignalisCore = Object.freeze({
   // Security
   constantTimeEqual,
   // Version
-  VERSION: "0.1.0",
+  VERSION: "0.2.0",
   nativeVersion
 });
 var index_default = SignalisCore;
@@ -573,11 +851,20 @@ export {
   AES_GCM_MAX_PLAINTEXT_SIZE,
   AES_GCM_RECOMMENDED_MESSAGES_PER_KEY,
   AuthenticationError,
+  CHACHA20_POLY1305_KEY_SIZE,
+  CHACHA20_POLY1305_NONCE_SIZE,
+  CHACHA20_POLY1305_TAG_SIZE,
   CURVE25519_PRIVATE_KEY_SIZE,
   CURVE25519_PUBLIC_KEY_SIZE,
   CURVE25519_SHARED_SECRET_SIZE,
+  ChaCha20Poly1305,
   CryptoError,
   Curve25519,
+  ED25519_PRIVATE_KEY_SIZE,
+  ED25519_PUBLIC_KEY_SIZE,
+  ED25519_SEED_SIZE,
+  ED25519_SIGNATURE_SIZE,
+  Ed25519,
   HKDF,
   HKDF_MAX_OUTPUT_SIZE,
   HKDF_PRK_SIZE,
@@ -589,11 +876,18 @@ export {
   SHA256_BLOCK_SIZE,
   SHA256_OUTPUT_SIZE,
   SignalisError,
+  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,
@@ -602,16 +896,18 @@ export {
   bufferToString,
   buffersSameLength,
   concat,
+  constantTimeEq2 as constantTimeEq,
   constantTimeEqual,
   index_default as default,
   fromBase64,
   fromBase64Url,
   fromHex,
+  nativeSecureRandom,
   nativeVersion,
   randomIv,
   randomKey,
   randomNonce,
-  secureRandom,
+  secureRandom2 as secureRandom,
   stringToBuffer,
   toBase64,
   toBase64Url,