@bcts/crypto 1.0.0-alpha.5

package/src/index.ts

@@ -0,0 +1,115 @@
+// Ported from bc-crypto-rust/src/lib.rs
+
+// Re-export all modules
+
+// Error types
+export { CryptoError, AeadError, type CryptoResult } from "./error.js";
+
+// Memory zeroing
+export { memzero, memzeroVecVecU8 } from "./memzero.js";
+
+// Hash constants
+export { CRC32_SIZE, SHA256_SIZE, SHA512_SIZE } from "./hash.js";
+
+// Hash functions
+export {
+  crc32,
+  crc32Data,
+  crc32DataOpt,
+  sha256,
+  doubleSha256,
+  sha512,
+  hmacSha256,
+  hmacSha512,
+  pbkdf2HmacSha256,
+  pbkdf2HmacSha512,
+  hkdfHmacSha256,
+  hkdfHmacSha512,
+} from "./hash.js";
+
+// Symmetric encryption constants
+export {
+  SYMMETRIC_KEY_SIZE,
+  SYMMETRIC_NONCE_SIZE,
+  SYMMETRIC_AUTH_SIZE,
+} from "./symmetric-encryption.js";
+
+// Symmetric encryption functions
+export {
+  aeadChaCha20Poly1305Encrypt,
+  aeadChaCha20Poly1305EncryptWithAad,
+  aeadChaCha20Poly1305Decrypt,
+  aeadChaCha20Poly1305DecryptWithAad,
+} from "./symmetric-encryption.js";
+
+// Public key encryption constants
+export {
+  GENERIC_PRIVATE_KEY_SIZE,
+  GENERIC_PUBLIC_KEY_SIZE,
+  X25519_PRIVATE_KEY_SIZE,
+  X25519_PUBLIC_KEY_SIZE,
+} from "./public-key-encryption.js";
+
+// Public key encryption functions
+export {
+  deriveAgreementPrivateKey,
+  deriveSigningPrivateKey,
+  x25519NewPrivateKeyUsing,
+  x25519PublicKeyFromPrivateKey,
+  x25519SharedKey,
+} from "./public-key-encryption.js";
+
+// ECDSA key constants
+export {
+  ECDSA_PRIVATE_KEY_SIZE,
+  ECDSA_PUBLIC_KEY_SIZE,
+  ECDSA_UNCOMPRESSED_PUBLIC_KEY_SIZE,
+  ECDSA_MESSAGE_HASH_SIZE,
+  ECDSA_SIGNATURE_SIZE,
+  SCHNORR_PUBLIC_KEY_SIZE,
+} from "./ecdsa-keys.js";
+
+// ECDSA key functions
+export {
+  ecdsaNewPrivateKeyUsing,
+  ecdsaPublicKeyFromPrivateKey,
+  ecdsaDecompressPublicKey,
+  ecdsaCompressPublicKey,
+  ecdsaDerivePrivateKey,
+  schnorrPublicKeyFromPrivateKey,
+} from "./ecdsa-keys.js";
+
+// ECDSA signing functions
+export { ecdsaSign, ecdsaVerify } from "./ecdsa-signing.js";
+
+// Schnorr signing constants
+export { SCHNORR_SIGNATURE_SIZE } from "./schnorr-signing.js";
+
+// Schnorr signing functions
+export {
+  schnorrSign,
+  schnorrSignUsing,
+  schnorrSignWithAuxRand,
+  schnorrVerify,
+} from "./schnorr-signing.js";
+
+// Ed25519 constants
+export {
+  ED25519_PUBLIC_KEY_SIZE,
+  ED25519_PRIVATE_KEY_SIZE,
+  ED25519_SIGNATURE_SIZE,
+} from "./ed25519-signing.js";
+
+// Ed25519 functions
+export {
+  ed25519NewPrivateKeyUsing,
+  ed25519PublicKeyFromPrivateKey,
+  ed25519Sign,
+  ed25519Verify,
+} from "./ed25519-signing.js";
+
+// Scrypt
+export { scrypt, scryptOpt } from "./scrypt.js";
+
+// Argon2id
+export { argon2idHash, argon2idHashOpt } from "./argon.js";

package/src/memzero.ts

@@ -0,0 +1,37 @@
+// Ported from bc-crypto-rust/src/memzero.rs
+
+/**
+ * Securely zero out a typed array.
+ *
+ * **IMPORTANT: This is a best-effort implementation.** Unlike the Rust reference
+ * implementation which uses `std::ptr::write_volatile()` for guaranteed volatile
+ * writes, JavaScript engines and JIT compilers can still potentially optimize
+ * away these zeroing operations. The check at the end helps prevent optimization,
+ * but it is not foolproof.
+ *
+ * For truly sensitive cryptographic operations, consider using the Web Crypto API's
+ * `crypto.subtle` with non-extractable keys when possible, as it provides stronger
+ * guarantees than what can be achieved with pure JavaScript.
+ *
+ * This function attempts to prevent the compiler from optimizing away
+ * the zeroing operation by using a verification check after the zeroing loop.
+ */
+export function memzero(data: Uint8Array | Uint32Array): void {
+  const len = data.length;
+  for (let i = 0; i < len; i++) {
+    data[i] = 0;
+  }
+  // Force a side effect to prevent optimization
+  if (data.length > 0 && data[0] !== 0) {
+    throw new Error("memzero failed");
+  }
+}
+
+/**
+ * Securely zero out an array of Uint8Arrays.
+ */
+export function memzeroVecVecU8(arrays: Uint8Array[]): void {
+  for (const arr of arrays) {
+    memzero(arr);
+  }
+}

package/src/public-key-encryption.ts

@@ -0,0 +1,68 @@
+// Ported from bc-crypto-rust/src/public_key_encryption.rs
+
+import { x25519 } from "@noble/curves/ed25519";
+import type { RandomNumberGenerator } from "@bcts/rand";
+import { hkdfHmacSha256 } from "./hash.js";
+
+// Constants
+export const GENERIC_PRIVATE_KEY_SIZE = 32;
+export const GENERIC_PUBLIC_KEY_SIZE = 32;
+export const X25519_PRIVATE_KEY_SIZE = 32;
+export const X25519_PUBLIC_KEY_SIZE = 32;
+
+/**
+ * Derive an X25519 agreement private key from key material.
+ * Uses HKDF with "agreement" as domain separation salt.
+ */
+export function deriveAgreementPrivateKey(keyMaterial: Uint8Array): Uint8Array {
+  const salt = new TextEncoder().encode("agreement");
+  return hkdfHmacSha256(keyMaterial, salt, X25519_PRIVATE_KEY_SIZE);
+}
+
+/**
+ * Derive a signing private key from key material.
+ * Uses HKDF with "signing" as domain separation salt.
+ */
+export function deriveSigningPrivateKey(keyMaterial: Uint8Array): Uint8Array {
+  const salt = new TextEncoder().encode("signing");
+  return hkdfHmacSha256(keyMaterial, salt, 32);
+}
+
+/**
+ * Generate a new random X25519 private key.
+ */
+export function x25519NewPrivateKeyUsing(rng: RandomNumberGenerator): Uint8Array {
+  return rng.randomData(X25519_PRIVATE_KEY_SIZE);
+}
+
+/**
+ * Derive an X25519 public key from a private key.
+ */
+export function x25519PublicKeyFromPrivateKey(privateKey: Uint8Array): Uint8Array {
+  if (privateKey.length !== X25519_PRIVATE_KEY_SIZE) {
+    throw new Error(`Private key must be ${X25519_PRIVATE_KEY_SIZE} bytes`);
+  }
+  return x25519.getPublicKey(privateKey);
+}
+
+/**
+ * Compute a shared secret using X25519 key agreement (ECDH).
+ *
+ * **Security Note**: The resulting shared secret should be used with a KDF
+ * (like HKDF) before using it as an encryption key. Never use the raw
+ * shared secret directly for encryption.
+ *
+ * @param x25519Private - 32-byte X25519 private key
+ * @param x25519Public - 32-byte X25519 public key from the other party
+ * @returns 32-byte shared secret
+ * @throws {Error} If private key is not 32 bytes or public key is not 32 bytes
+ */
+export function x25519SharedKey(x25519Private: Uint8Array, x25519Public: Uint8Array): Uint8Array {
+  if (x25519Private.length !== X25519_PRIVATE_KEY_SIZE) {
+    throw new Error(`Private key must be ${X25519_PRIVATE_KEY_SIZE} bytes`);
+  }
+  if (x25519Public.length !== X25519_PUBLIC_KEY_SIZE) {
+    throw new Error(`Public key must be ${X25519_PUBLIC_KEY_SIZE} bytes`);
+  }
+  return x25519.getSharedSecret(x25519Private, x25519Public);
+}

package/src/schnorr-signing.ts

@@ -0,0 +1,90 @@
+// Ported from bc-crypto-rust/src/schnorr_signing.rs
+
+import { schnorr } from "@noble/curves/secp256k1";
+import type { RandomNumberGenerator } from "@bcts/rand";
+import { SecureRandomNumberGenerator } from "@bcts/rand";
+import { ECDSA_PRIVATE_KEY_SIZE, SCHNORR_PUBLIC_KEY_SIZE } from "./ecdsa-keys.js";
+
+// Constants
+export const SCHNORR_SIGNATURE_SIZE = 64;
+
+/**
+ * Sign a message using Schnorr signature (BIP-340).
+ * Uses secure random auxiliary randomness.
+ *
+ * @param ecdsaPrivateKey - 32-byte private key
+ * @param message - Message to sign (not pre-hashed, per BIP-340)
+ * @returns 64-byte Schnorr signature
+ */
+export function schnorrSign(ecdsaPrivateKey: Uint8Array, message: Uint8Array): Uint8Array {
+  const rng = new SecureRandomNumberGenerator();
+  return schnorrSignUsing(ecdsaPrivateKey, message, rng);
+}
+
+/**
+ * Sign a message using Schnorr signature with a custom RNG.
+ *
+ * @param ecdsaPrivateKey - 32-byte private key
+ * @param message - Message to sign
+ * @param rng - Random number generator for auxiliary randomness
+ * @returns 64-byte Schnorr signature
+ */
+export function schnorrSignUsing(
+  ecdsaPrivateKey: Uint8Array,
+  message: Uint8Array,
+  rng: RandomNumberGenerator,
+): Uint8Array {
+  const auxRand = rng.randomData(32);
+  return schnorrSignWithAuxRand(ecdsaPrivateKey, message, auxRand);
+}
+
+/**
+ * Sign a message using Schnorr signature with specific auxiliary randomness.
+ * This is useful for deterministic signing in tests.
+ *
+ * @param ecdsaPrivateKey - 32-byte private key
+ * @param message - Message to sign
+ * @param auxRand - 32-byte auxiliary randomness (per BIP-340)
+ * @returns 64-byte Schnorr signature
+ */
+export function schnorrSignWithAuxRand(
+  ecdsaPrivateKey: Uint8Array,
+  message: Uint8Array,
+  auxRand: Uint8Array,
+): Uint8Array {
+  if (ecdsaPrivateKey.length !== ECDSA_PRIVATE_KEY_SIZE) {
+    throw new Error(`Private key must be ${ECDSA_PRIVATE_KEY_SIZE} bytes`);
+  }
+  if (auxRand.length !== 32) {
+    throw new Error("Auxiliary randomness must be 32 bytes");
+  }
+
+  return schnorr.sign(message, ecdsaPrivateKey, auxRand);
+}
+
+/**
+ * Verify a Schnorr signature (BIP-340).
+ *
+ * @param schnorrPublicKey - 32-byte x-only public key
+ * @param signature - 64-byte Schnorr signature
+ * @param message - Original message
+ * @returns true if signature is valid
+ */
+export function schnorrVerify(
+  schnorrPublicKey: Uint8Array,
+  signature: Uint8Array,
+  message: Uint8Array,
+): boolean {
+  if (schnorrPublicKey.length !== SCHNORR_PUBLIC_KEY_SIZE) {
+    throw new Error(`Public key must be ${SCHNORR_PUBLIC_KEY_SIZE} bytes`);
+  }
+  if (signature.length !== SCHNORR_SIGNATURE_SIZE) {
+    throw new Error(`Signature must be ${SCHNORR_SIGNATURE_SIZE} bytes`);
+  }
+
+  try {
+    return schnorr.verify(signature, message, schnorrPublicKey);
+  } catch {
+    return false;
+  }
+}

package/src/scrypt.ts

@@ -0,0 +1,50 @@
+// Ported from bc-crypto-rust/src/scrypt.rs
+
+import { scrypt as nobleScrypt } from "@noble/hashes/scrypt";
+
+/**
+ * Derive a key using Scrypt with recommended parameters.
+ * Uses N=2^15 (32768), r=8, p=1 as recommended defaults.
+ *
+ * @param password - Password or passphrase
+ * @param salt - Salt value
+ * @param outputLen - Desired output length
+ * @returns Derived key
+ */
+export function scrypt(password: Uint8Array, salt: Uint8Array, outputLen: number): Uint8Array {
+  return scryptOpt(password, salt, outputLen, 15, 8, 1);
+}
+
+/**
+ * Derive a key using Scrypt with custom parameters.
+ *
+ * @param password - Password or passphrase
+ * @param salt - Salt value
+ * @param outputLen - Desired output length
+ * @param logN - Log2 of the CPU/memory cost parameter N (must be <64)
+ * @param r - Block size parameter (must be >0)
+ * @param p - Parallelization parameter (must be >0)
+ * @returns Derived key
+ */
+export function scryptOpt(
+  password: Uint8Array,
+  salt: Uint8Array,
+  outputLen: number,
+  logN: number,
+  r: number,
+  p: number,
+): Uint8Array {
+  if (logN >= 64) {
+    throw new Error("logN must be <64");
+  }
+  if (r === 0) {
+    throw new Error("r must be >0");
+  }
+  if (p === 0) {
+    throw new Error("p must be >0");
+  }
+
+  const N = 1 << logN; // 2^logN
+
+  return nobleScrypt(password, salt, { N, r, p, dkLen: outputLen });
+}

package/src/symmetric-encryption.ts

@@ -0,0 +1,133 @@
+// Ported from bc-crypto-rust/src/symmetric_encryption.rs
+
+import { chacha20poly1305 } from "@noble/ciphers/chacha";
+import { CryptoError, AeadError } from "./error.js";
+
+// Constants
+export const SYMMETRIC_KEY_SIZE = 32;
+export const SYMMETRIC_NONCE_SIZE = 12;
+export const SYMMETRIC_AUTH_SIZE = 16;
+
+/**
+ * Encrypt data using ChaCha20-Poly1305 AEAD cipher.
+ *
+ * **Security Warning**: The nonce MUST be unique for every encryption operation
+ * with the same key. Reusing a nonce completely breaks the security of the
+ * encryption scheme and can reveal plaintext.
+ *
+ * @param plaintext - The data to encrypt
+ * @param key - 32-byte encryption key
+ * @param nonce - 12-byte nonce (MUST be unique per encryption with the same key)
+ * @returns Tuple of [ciphertext, authTag] where authTag is 16 bytes
+ * @throws {CryptoError} If key is not 32 bytes or nonce is not 12 bytes
+ */
+export function aeadChaCha20Poly1305Encrypt(
+  plaintext: Uint8Array,
+  key: Uint8Array,
+  nonce: Uint8Array,
+): [Uint8Array, Uint8Array] {
+  return aeadChaCha20Poly1305EncryptWithAad(plaintext, key, nonce, new Uint8Array(0));
+}
+
+/**
+ * Encrypt data using ChaCha20-Poly1305 AEAD cipher with additional authenticated data.
+ *
+ * **Security Warning**: The nonce MUST be unique for every encryption operation
+ * with the same key. Reusing a nonce completely breaks the security of the
+ * encryption scheme and can reveal plaintext.
+ *
+ * @param plaintext - The data to encrypt
+ * @param key - 32-byte encryption key
+ * @param nonce - 12-byte nonce (MUST be unique per encryption with the same key)
+ * @param aad - Additional authenticated data (not encrypted, but integrity-protected)
+ * @returns Tuple of [ciphertext, authTag] where authTag is 16 bytes
+ * @throws {CryptoError} If key is not 32 bytes or nonce is not 12 bytes
+ */
+export function aeadChaCha20Poly1305EncryptWithAad(
+  plaintext: Uint8Array,
+  key: Uint8Array,
+  nonce: Uint8Array,
+  aad: Uint8Array,
+): [Uint8Array, Uint8Array] {
+  if (key.length !== SYMMETRIC_KEY_SIZE) {
+    throw CryptoError.invalidParameter(`Key must be ${SYMMETRIC_KEY_SIZE} bytes`);
+  }
+  if (nonce.length !== SYMMETRIC_NONCE_SIZE) {
+    throw CryptoError.invalidParameter(`Nonce must be ${SYMMETRIC_NONCE_SIZE} bytes`);
+  }
+
+  const cipher = chacha20poly1305(key, nonce, aad);
+  const sealed = cipher.encrypt(plaintext);
+
+  // The sealed output contains ciphertext + 16-byte auth tag
+  const ciphertext = sealed.slice(0, sealed.length - SYMMETRIC_AUTH_SIZE);
+  const authTag = sealed.slice(sealed.length - SYMMETRIC_AUTH_SIZE);
+
+  return [ciphertext, authTag];
+}
+
+/**
+ * Decrypt data using ChaCha20-Poly1305 AEAD cipher.
+ *
+ * @param ciphertext - The encrypted data
+ * @param key - 32-byte encryption key (must match key used for encryption)
+ * @param nonce - 12-byte nonce (must match nonce used for encryption)
+ * @param authTag - 16-byte authentication tag from encryption
+ * @returns Decrypted plaintext
+ * @throws {CryptoError} If key/nonce/authTag sizes are invalid
+ * @throws {CryptoError} If authentication fails (tampered data or wrong key/nonce)
+ */
+export function aeadChaCha20Poly1305Decrypt(
+  ciphertext: Uint8Array,
+  key: Uint8Array,
+  nonce: Uint8Array,
+  authTag: Uint8Array,
+): Uint8Array {
+  return aeadChaCha20Poly1305DecryptWithAad(ciphertext, key, nonce, new Uint8Array(0), authTag);
+}
+
+/**
+ * Decrypt data using ChaCha20-Poly1305 AEAD cipher with additional authenticated data.
+ *
+ * @param ciphertext - The encrypted data
+ * @param key - 32-byte encryption key (must match key used for encryption)
+ * @param nonce - 12-byte nonce (must match nonce used for encryption)
+ * @param aad - Additional authenticated data (must exactly match AAD used for encryption)
+ * @param authTag - 16-byte authentication tag from encryption
+ * @returns Decrypted plaintext
+ * @throws {CryptoError} If key/nonce/authTag sizes are invalid
+ * @throws {CryptoError} If authentication fails (tampered data, wrong key/nonce, or AAD mismatch)
+ */
+export function aeadChaCha20Poly1305DecryptWithAad(
+  ciphertext: Uint8Array,
+  key: Uint8Array,
+  nonce: Uint8Array,
+  aad: Uint8Array,
+  authTag: Uint8Array,
+): Uint8Array {
+  if (key.length !== SYMMETRIC_KEY_SIZE) {
+    throw CryptoError.invalidParameter(`Key must be ${SYMMETRIC_KEY_SIZE} bytes`);
+  }
+  if (nonce.length !== SYMMETRIC_NONCE_SIZE) {
+    throw CryptoError.invalidParameter(`Nonce must be ${SYMMETRIC_NONCE_SIZE} bytes`);
+  }
+  if (authTag.length !== SYMMETRIC_AUTH_SIZE) {
+    throw CryptoError.invalidParameter(`Auth tag must be ${SYMMETRIC_AUTH_SIZE} bytes`);
+  }
+
+  // Combine ciphertext and auth tag for decryption
+  const sealed = new Uint8Array(ciphertext.length + authTag.length);
+  sealed.set(ciphertext);
+  sealed.set(authTag, ciphertext.length);
+
+  try {
+    const cipher = chacha20poly1305(key, nonce, aad);
+    return cipher.decrypt(sealed);
+  } catch (error) {
+    // Preserve the original error for debugging while wrapping in our error type
+    const aeadError = new AeadError(
+      `Decryption failed: ${error instanceof Error ? error.message : "authentication error"}`,
+    );
+    throw CryptoError.aead(aeadError);
+  }
+}