@brashkie/signalis-core 0.1.0

package/dist/index.mjs

@@ -0,0 +1,622 @@
+// src/core.ts
+import * as native from "../index.js";
+
+// src/constants.ts
+var CURVE25519_PRIVATE_KEY_SIZE = 32;
+var CURVE25519_PUBLIC_KEY_SIZE = 32;
+var CURVE25519_SHARED_SECRET_SIZE = 32;
+var HKDF_PRK_SIZE = 32;
+var HKDF_MAX_OUTPUT_SIZE = 8160;
+var AES_256_KEY_SIZE = 32;
+var AES_256_GCM_NONCE_SIZE = 12;
+var AES_256_GCM_TAG_SIZE = 16;
+var AES_256_CBC_IV_SIZE = 16;
+var AES_BLOCK_SIZE = 16;
+var SHA256_OUTPUT_SIZE = 32;
+var HMAC_SHA256_TAG_SIZE = 32;
+var SHA256_BLOCK_SIZE = 64;
+var AES_GCM_MAX_PLAINTEXT_SIZE = 64 * 1024 * 1024 * 1024;
+var AES_GCM_RECOMMENDED_MESSAGES_PER_KEY = 4294967296;
+
+// src/errors.ts
+var SignalisError = class extends Error {
+  /** Error code for programmatic handling. */
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "SignalisError";
+    this.code = code;
+    if (typeof Error.captureStackTrace === "function") {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var ValidationError = class extends SignalisError {
+  /** Name of the parameter that failed validation. */
+  parameter;
+  /** Expected value description. */
+  expected;
+  /** Actual value received. */
+  actual;
+  constructor(message, options = {}) {
+    super(message, "VALIDATION_ERROR");
+    this.name = "ValidationError";
+    this.parameter = options.parameter;
+    this.expected = options.expected;
+    this.actual = options.actual;
+  }
+};
+var CryptoError = class extends SignalisError {
+  /** The crypto operation that failed. */
+  operation;
+  constructor(message, operation) {
+    super(message, "CRYPTO_ERROR");
+    this.name = "CryptoError";
+    this.operation = operation;
+  }
+};
+var AuthenticationError = class extends CryptoError {
+  constructor(message = "Authentication tag verification failed") {
+    super(message, "authenticate");
+    this.name = "AuthenticationError";
+  }
+};
+var KeyDerivationError = class extends CryptoError {
+  constructor(message) {
+    super(message, "derive_key");
+    this.name = "KeyDerivationError";
+  }
+};
+var LengthError = class extends ValidationError {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "LengthError";
+  }
+};
+
+// src/validators.ts
+function assertBuffer(value, parameter) {
+  if (!Buffer.isBuffer(value)) {
+    throw new ValidationError(`${parameter} must be a Buffer`, {
+      parameter,
+      expected: "Buffer",
+      actual: typeof value
+    });
+  }
+}
+function assertBufferLength(value, expectedLength, parameter) {
+  if (value.length !== expectedLength) {
+    throw new ValidationError(
+      `${parameter} must be ${expectedLength} bytes, got ${value.length}`,
+      {
+        parameter,
+        expected: `${expectedLength} bytes`,
+        actual: value.length
+      }
+    );
+  }
+}
+function assertBufferOfSize(value, expectedLength, parameter) {
+  assertBuffer(value, parameter);
+  assertBufferLength(value, expectedLength, parameter);
+}
+function assertPositiveInteger(value, parameter) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    throw new ValidationError(`${parameter} must be a non-negative integer`, {
+      parameter,
+      expected: "non-negative integer",
+      actual: String(value)
+    });
+  }
+}
+function assertHkdfLength(length) {
+  assertPositiveInteger(length, "length");
+  if (length > HKDF_MAX_OUTPUT_SIZE) {
+    throw new LengthError(
+      `HKDF output length cannot exceed ${HKDF_MAX_OUTPUT_SIZE} bytes (255 * 32)`,
+      {
+        expected: `<= ${HKDF_MAX_OUTPUT_SIZE}`,
+        actual: length
+      }
+    );
+  }
+  if (length === 0) {
+    throw new LengthError("HKDF output length must be greater than 0", {
+      expected: "> 0",
+      actual: 0
+    });
+  }
+}
+function buffersSameLength(a, b) {
+  return a.length === b.length;
+}
+
+// src/core.ts
+var Curve25519 = Object.freeze({
+  /**
+   * Generate a new random Curve25519 keypair.
+   *
+   * Uses the OS's cryptographically secure RNG (via Rust's `OsRng`).
+   *
+   * @returns A {@link KeyPair} with private and public keys (32 bytes each)
+   */
+  generateKeyPair() {
+    const kp = native.curve25519GenerateKeypair();
+    return Object.freeze({
+      privateKey: kp.private,
+      publicKey: kp.public
+    });
+  },
+  /**
+   * Derive the public key corresponding to a given private key.
+   *
+   * @param privateKey - 32-byte private key
+   * @returns The corresponding 32-byte public key
+   * @throws {ValidationError} If `privateKey` is not a 32-byte Buffer.
+   */
+  publicFromPrivate(privateKey) {
+    assertBufferOfSize(privateKey, CURVE25519_PRIVATE_KEY_SIZE, "privateKey");
+    return native.curve25519PublicFromPrivate(privateKey);
+  },
+  /**
+   * Perform X25519 Diffie-Hellman key agreement.
+   *
+   * Both parties run this with swapped (private, peer-public) arguments
+   * and obtain the same 32-byte shared secret.
+   *
+   * **⚠️ CRITICAL:** Do NOT use the returned secret directly as an
+   * encryption key. Always derive an actual key through HKDF:
+   *
+   * @example
+   * ```ts
+   * const shared = Curve25519.diffieHellman(myPriv, theirPub);
+   * const key = HKDF.derive(salt, shared, Buffer.from('aes-key'), 32);
+   * ```
+   *
+   * @param privateKey - Your 32-byte private key
+   * @param peerPublicKey - Peer's 32-byte public key
+   * @returns 32-byte shared secret
+   * @throws {ValidationError} If keys are not 32 bytes.
+   * @throws {CryptoError} If the operation fails.
+   */
+  diffieHellman(privateKey, peerPublicKey) {
+    assertBufferOfSize(privateKey, CURVE25519_PRIVATE_KEY_SIZE, "privateKey");
+    assertBufferOfSize(peerPublicKey, CURVE25519_PUBLIC_KEY_SIZE, "peerPublicKey");
+    return native.curve25519DiffieHellman(privateKey, peerPublicKey);
+  },
+  /**
+   * The size of a Curve25519 private key in bytes (32).
+   */
+  PRIVATE_KEY_SIZE: CURVE25519_PRIVATE_KEY_SIZE,
+  /**
+   * The size of a Curve25519 public key in bytes (32).
+   */
+  PUBLIC_KEY_SIZE: CURVE25519_PUBLIC_KEY_SIZE,
+  /**
+   * The size of an X25519 shared secret in bytes (32).
+   */
+  SHARED_SECRET_SIZE: CURVE25519_SHARED_SECRET_SIZE
+});
+var HKDF = Object.freeze({
+  /**
+   * HKDF-Extract: produces a 32-byte pseudorandom key (PRK).
+   *
+   * @param salt - Optional salt (pass `Buffer.alloc(0)` if not available)
+   * @param ikm - Input keying material
+   * @returns 32-byte PRK
+   * @throws {ValidationError} If inputs are not Buffers.
+   */
+  extract(salt, ikm) {
+    assertBuffer(salt, "salt");
+    assertBuffer(ikm, "ikm");
+    return native.hkdfExtract(salt, ikm);
+  },
+  /**
+   * HKDF-Expand: produces `length` bytes of output keying material.
+   *
+   * @param prk - 32-byte pseudorandom key from {@link extract}
+   * @param info - Context-specific information (binds output to a usage)
+   * @param length - Desired output length (1 to 8160 bytes)
+   * @returns OKM of requested length
+   * @throws {ValidationError} If PRK is not 32 bytes or length is out of bounds.
+   */
+  expand(prk, info, length) {
+    assertBufferOfSize(prk, HKDF_PRK_SIZE, "prk");
+    assertBuffer(info, "info");
+    assertHkdfLength(length);
+    return native.hkdfExpand(prk, info, length);
+  },
+  /**
+   * HKDF one-shot: extract + expand in a single call.
+   *
+   * Use this whenever possible — it's the standard HKDF API.
+   *
+   * @param salt - Optional salt
+   * @param ikm - Input keying material
+   * @param info - Context info
+   * @param length - Desired output length
+   * @returns OKM of requested length
+   */
+  derive(salt, ikm, info, length) {
+    assertBuffer(salt, "salt");
+    assertBuffer(ikm, "ikm");
+    assertBuffer(info, "info");
+    assertHkdfLength(length);
+    return native.hkdfDerive(salt, ikm, info, length);
+  },
+  /**
+   * Derive multiple keys from the same shared secret in a single call.
+   *
+   * Useful for deriving e.g., a send key AND a receive key simultaneously.
+   *
+   * @example
+   * ```ts
+   * const [sendKey, recvKey] = HKDF.deriveMultiple(
+   *   salt,
+   *   sharedSecret,
+   *   Buffer.from('signalis-channel-v1'),
+   *   [32, 32],
+   * );
+   * ```
+   *
+   * @param salt - Optional salt
+   * @param ikm - Input keying material
+   * @param info - Context info
+   * @param lengths - Array of output lengths
+   * @returns Array of derived keys, one per requested length
+   */
+  deriveMultiple(salt, ikm, info, lengths) {
+    assertBuffer(salt, "salt");
+    assertBuffer(ikm, "ikm");
+    assertBuffer(info, "info");
+    if (!Array.isArray(lengths) || lengths.length === 0) {
+      throw new TypeError("lengths must be a non-empty array of integers");
+    }
+    const total = lengths.reduce((sum, len) => sum + len, 0);
+    assertHkdfLength(total);
+    const okm = this.derive(salt, ikm, info, total);
+    const results = [];
+    let offset = 0;
+    for (const len of lengths) {
+      results.push(okm.subarray(offset, offset + len));
+      offset += len;
+    }
+    return results;
+  },
+  /**
+   * Derive a key using an {@link HkdfParams} object (alternative API).
+   */
+  deriveFromParams(params) {
+    return this.derive(params.salt, params.ikm, params.info, params.length);
+  },
+  /**
+   * The size of an HKDF PRK in bytes (32).
+   */
+  PRK_SIZE: HKDF_PRK_SIZE
+});
+var AES_GCM = Object.freeze({
+  /**
+   * Encrypt plaintext.
+   *
+   * Returns: ciphertext || 16-byte authentication tag (concatenated).
+   *
+   * @param key - 32-byte symmetric key
+   * @param nonce - 12-byte unique nonce (NEVER reuse with same key)
+   * @param plaintext - Data to encrypt
+   * @returns Ciphertext + auth tag (output is `plaintext.length + 16` bytes)
+   * @throws {ValidationError} On invalid sizes.
+   * @throws {CryptoError} If the operation fails.
+   */
+  encrypt(key, nonce, plaintext) {
+    assertBufferOfSize(key, AES_256_KEY_SIZE, "key");
+    assertBufferOfSize(nonce, AES_256_GCM_NONCE_SIZE, "nonce");
+    assertBuffer(plaintext, "plaintext");
+    return native.aes256GcmEncrypt(key, nonce, plaintext);
+  },
+  /**
+   * Decrypt ciphertext and verify authentication tag.
+   *
+   * @param key - 32-byte symmetric key (same as encryption)
+   * @param nonce - 12-byte nonce (same as encryption)
+   * @param ciphertext - Ciphertext || auth tag
+   * @returns Original plaintext
+   * @throws {ValidationError} On invalid sizes.
+   * @throws {AuthenticationError} If the tag is invalid (tampered or wrong key).
+   */
+  decrypt(key, nonce, ciphertext) {
+    assertBufferOfSize(key, AES_256_KEY_SIZE, "key");
+    assertBufferOfSize(nonce, AES_256_GCM_NONCE_SIZE, "nonce");
+    assertBuffer(ciphertext, "ciphertext");
+    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"
+      );
+    }
+    try {
+      return native.aes256GcmDecrypt(key, nonce, ciphertext);
+    } catch (e) {
+      throw new AuthenticationError(
+        `AES-256-GCM authentication failed: ${e.message}`
+      );
+    }
+  },
+  /** Key size in bytes (32). */
+  KEY_SIZE: AES_256_KEY_SIZE,
+  /** Nonce size in bytes (12). */
+  NONCE_SIZE: AES_256_GCM_NONCE_SIZE,
+  /** Tag size in bytes (16). */
+  TAG_SIZE: AES_256_GCM_TAG_SIZE
+});
+var AES_CBC = Object.freeze({
+  /**
+   * Encrypt with PKCS#7 padding.
+   *
+   * @param key - 32-byte symmetric key
+   * @param iv - 16-byte initialization vector
+   * @param plaintext - Data to encrypt
+   * @returns Ciphertext (padded to nearest 16-byte block)
+   */
+  encrypt(key, iv, plaintext) {
+    assertBufferOfSize(key, AES_256_KEY_SIZE, "key");
+    assertBufferOfSize(iv, AES_256_CBC_IV_SIZE, "iv");
+    assertBuffer(plaintext, "plaintext");
+    return native.aes256CbcEncrypt(key, iv, plaintext);
+  },
+  /**
+   * Decrypt with PKCS#7 padding (no authentication).
+   *
+   * @param key - 32-byte symmetric key
+   * @param iv - 16-byte IV (same as encryption)
+   * @param ciphertext - Ciphertext
+   * @returns Original plaintext
+   * @throws {CryptoError} On padding errors.
+   */
+  decrypt(key, iv, ciphertext) {
+    assertBufferOfSize(key, AES_256_KEY_SIZE, "key");
+    assertBufferOfSize(iv, AES_256_CBC_IV_SIZE, "iv");
+    assertBuffer(ciphertext, "ciphertext");
+    try {
+      return native.aes256CbcDecrypt(key, iv, ciphertext);
+    } catch (e) {
+      throw new CryptoError(
+        `AES-256-CBC decryption failed: ${e.message}`,
+        "aes_cbc_decrypt"
+      );
+    }
+  },
+  /** Key size in bytes (32). */
+  KEY_SIZE: AES_256_KEY_SIZE,
+  /** IV size in bytes (16). */
+  IV_SIZE: AES_256_CBC_IV_SIZE
+});
+var HMAC = Object.freeze({
+  /**
+   * Compute HMAC-SHA256 of `data` using `key`.
+   *
+   * @param key - Authentication key (any length)
+   * @param data - Data to authenticate
+   * @returns 32-byte HMAC tag
+   */
+  sha256(key, data) {
+    assertBuffer(key, "key");
+    assertBuffer(data, "data");
+    return native.hmacSha256(key, data);
+  },
+  /**
+   * Verify an HMAC-SHA256 tag in **constant time**.
+   *
+   * Always use this instead of `===` to prevent timing attacks.
+   *
+   * @param key - Authentication key
+   * @param data - Original data
+   * @param expectedTag - Tag to verify
+   * @returns `true` if tag matches, `false` otherwise
+   */
+  verifySha256(key, data, expectedTag) {
+    assertBuffer(key, "key");
+    assertBuffer(data, "data");
+    assertBuffer(expectedTag, "expectedTag");
+    return native.hmacSha256Verify(key, data, expectedTag);
+  },
+  /** Tag size in bytes (32). */
+  TAG_SIZE: HMAC_SHA256_TAG_SIZE
+});
+var SHA256 = Object.freeze({
+  /**
+   * Compute SHA-256 hash of `data`.
+   *
+   * @param data - Data to hash
+   * @returns 32-byte digest
+   */
+  hash(data) {
+    assertBuffer(data, "data");
+    return native.sha256(data);
+  },
+  /**
+   * Hash multiple Buffers concatenated together.
+   *
+   * Equivalent to `SHA256.hash(Buffer.concat([...]))` but slightly more
+   * efficient (avoids the intermediate concat).
+   */
+  hashAll(buffers) {
+    if (!Array.isArray(buffers)) {
+      throw new TypeError("buffers must be an array");
+    }
+    for (let i = 0; i < buffers.length; i++) {
+      assertBuffer(buffers[i], `buffers[${i}]`);
+    }
+    return this.hash(Buffer.concat(buffers));
+  },
+  /** Output size in bytes (32). */
+  OUTPUT_SIZE: SHA256_OUTPUT_SIZE
+});
+var nativeVersion = native.version();
+
+// src/types.ts
+function asPublicKey(buf) {
+  return buf;
+}
+function asPrivateKey(buf) {
+  return buf;
+}
+function asSharedSecret(buf) {
+  return buf;
+}
+
+// src/utils.ts
+import { randomBytes, timingSafeEqual } from "crypto";
+function secureRandom(length) {
+  if (!Number.isInteger(length) || length < 0) {
+    throw new RangeError(`length must be a non-negative integer, got ${length}`);
+  }
+  return randomBytes(length);
+}
+function randomNonce() {
+  return randomBytes(12);
+}
+function randomIv() {
+  return randomBytes(16);
+}
+function randomKey() {
+  return randomBytes(32);
+}
+function toHex(buf) {
+  return buf.toString("hex");
+}
+function fromHex(hex) {
+  if (!/^[0-9a-fA-F]*$/.test(hex)) {
+    throw new Error("Invalid hex string: contains non-hex characters");
+  }
+  if (hex.length % 2 !== 0) {
+    throw new Error("Invalid hex string: odd number of characters");
+  }
+  return Buffer.from(hex, "hex");
+}
+function toBase64(buf) {
+  return buf.toString("base64");
+}
+function fromBase64(b64) {
+  return Buffer.from(b64, "base64");
+}
+function toBase64Url(buf) {
+  return buf.toString("base64url");
+}
+function fromBase64Url(b64url) {
+  return Buffer.from(b64url, "base64url");
+}
+function bufferToString(buf, encoding = "hex") {
+  return buf.toString(encoding);
+}
+function stringToBuffer(str, encoding = "hex") {
+  return Buffer.from(str, encoding);
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) {
+    timingSafeEqual(a, a);
+    return false;
+  }
+  return timingSafeEqual(a, b);
+}
+function concat(buffers) {
+  return Buffer.concat(buffers);
+}
+function zeroize(buf) {
+  buf.fill(0);
+}
+function xor(a, b) {
+  if (a.length !== b.length) {
+    throw new Error(`XOR operands must have equal length: ${a.length} vs ${b.length}`);
+  }
+  const result = Buffer.alloc(a.length);
+  for (let i = 0; i < a.length; i++) {
+    result[i] = a[i] ^ b[i];
+  }
+  return result;
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+var SignalisCore = Object.freeze({
+  // Crypto primitives
+  Curve25519,
+  HKDF,
+  AES_GCM,
+  AES_CBC,
+  HMAC,
+  SHA256,
+  // Random
+  secureRandom,
+  randomNonce,
+  randomIv,
+  randomKey,
+  // Encoding
+  toHex,
+  fromHex,
+  toBase64,
+  fromBase64,
+  // Security
+  constantTimeEqual,
+  // Version
+  VERSION: "0.1.0",
+  nativeVersion
+});
+var index_default = SignalisCore;
+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,
+  AuthenticationError,
+  CURVE25519_PRIVATE_KEY_SIZE,
+  CURVE25519_PUBLIC_KEY_SIZE,
+  CURVE25519_SHARED_SECRET_SIZE,
+  CryptoError,
+  Curve25519,
+  HKDF,
+  HKDF_MAX_OUTPUT_SIZE,
+  HKDF_PRK_SIZE,
+  HMAC,
+  HMAC_SHA256_TAG_SIZE,
+  KeyDerivationError,
+  LengthError,
+  SHA256,
+  SHA256_BLOCK_SIZE,
+  SHA256_OUTPUT_SIZE,
+  SignalisError,
+  VERSION,
+  ValidationError,
+  asPrivateKey,
+  asPublicKey,
+  asSharedSecret,
+  assertBuffer,
+  assertBufferLength,
+  assertBufferOfSize,
+  assertHkdfLength,
+  assertPositiveInteger,
+  bufferToString,
+  buffersSameLength,
+  concat,
+  constantTimeEqual,
+  index_default as default,
+  fromBase64,
+  fromBase64Url,
+  fromHex,
+  nativeVersion,
+  randomIv,
+  randomKey,
+  randomNonce,
+  secureRandom,
+  stringToBuffer,
+  toBase64,
+  toBase64Url,
+  toHex,
+  xor,
+  zeroize
+};
+//# sourceMappingURL=index.mjs.map