voltaire-effect 0.2.23

package/src/crypto/Bip39/index.ts

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview BIP-39 mnemonic module for Effect.
+ * Generates and validates mnemonic phrases for HD wallet derivation.
+ *
+ * @module Bip39
+ * @since 0.0.1
+ *
+ * @description
+ * BIP-39 defines how mnemonic sentences (12-24 words from a 2048-word list) can be
+ * used to derive cryptographic seeds. This enables human-readable backup of wallets.
+ *
+ * Supported entropy levels:
+ * - 128 bits → 12 words
+ * - 160 bits → 15 words
+ * - 192 bits → 18 words
+ * - 224 bits → 21 words
+ * - 256 bits → 24 words
+ *
+ * @example
+ * ```typescript
+ * import { Bip39Service, Bip39Live, generateMnemonic, validateMnemonic, mnemonicToSeed } from 'voltaire-effect/crypto/Bip39'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const mnemonic = yield* generateMnemonic(128)
+ *   const isValid = yield* validateMnemonic(mnemonic)
+ *   const seed = yield* mnemonicToSeed(mnemonic)
+ *   return { mnemonic, isValid, seed }
+ * }).pipe(Effect.provide(Bip39Live))
+ * ```
+ *
+ * @see {@link https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki | BIP-39 Specification}
+ */
+export {
+	Bip39Live,
+	Bip39Service,
+	type Bip39ServiceShape,
+	Bip39Test,
+} from "./Bip39Service.js";
+export {
+	generateMnemonic,
+	getWordCount,
+	mnemonicToSeed,
+	mnemonicToSeedSync,
+	validateMnemonic,
+} from "./operations.js";
+export { type MnemonicStrength, WORD_COUNTS } from "./types.js";
+export {
+	mnemonicToWords,
+	validateWordCount,
+	wordsToMnemonic,
+} from "./utils.js";

package/src/crypto/Bip39/operations.ts

@@ -0,0 +1,168 @@
+/**
+ * @fileoverview BIP-39 mnemonic operations for Effect.
+ * @module Bip39/operations
+ * @since 0.0.1
+ */
+import * as Effect from "effect/Effect";
+import { Bip39Service } from "./Bip39Service.js";
+import type { MnemonicStrength } from "./types.js";
+
+/**
+ * Generates a random BIP-39 mnemonic phrase.
+ *
+ * @description
+ * Creates a cryptographically random mnemonic using the BIP-39 wordlist.
+ * The mnemonic includes a checksum for error detection.
+ *
+ * @param strength - Entropy bits: 128=12 words, 160=15, 192=18, 224=21, 256=24 words
+ * @returns Effect containing the space-separated mnemonic sentence, requiring Bip39Service
+ *
+ * @example
+ * ```typescript
+ * import { generateMnemonic, Bip39Live } from 'voltaire-effect/crypto/Bip39'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = generateMnemonic(128).pipe(Effect.provide(Bip39Live))
+ * // Returns: "word1 word2 word3 ... word12"
+ * ```
+ *
+ * @throws Never fails
+ * @see {@link validateMnemonic} to verify mnemonic validity
+ * @since 0.0.1
+ */
+export const generateMnemonic = (
+	strength?: MnemonicStrength,
+): Effect.Effect<string, never, Bip39Service> =>
+	Effect.gen(function* () {
+		const bip39 = yield* Bip39Service;
+		return yield* bip39.generateMnemonic(strength);
+	});
+
+/**
+ * Validates a BIP-39 mnemonic phrase.
+ *
+ * @description
+ * Checks that the mnemonic uses valid BIP-39 words and has a correct checksum.
+ * Does not validate word count alone - must be 12, 15, 18, 21, or 24 words.
+ *
+ * @param mnemonic - The mnemonic string to validate (space-separated words)
+ * @returns Effect containing true if valid, requiring Bip39Service
+ *
+ * @example
+ * ```typescript
+ * import { validateMnemonic, Bip39Live } from 'voltaire-effect/crypto/Bip39'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = validateMnemonic('abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about')
+ *   .pipe(Effect.provide(Bip39Live))
+ * // Returns: true
+ * ```
+ *
+ * @throws Never fails
+ * @see {@link generateMnemonic} to create valid mnemonics
+ * @since 0.0.1
+ */
+export const validateMnemonic = (
+	mnemonic: string,
+): Effect.Effect<boolean, never, Bip39Service> =>
+	Effect.gen(function* () {
+		const bip39 = yield* Bip39Service;
+		return yield* bip39.validateMnemonic(mnemonic);
+	});
+
+/**
+ * Converts a mnemonic to a seed asynchronously.
+ *
+ * @description
+ * Uses PBKDF2-SHA512 with 2048 iterations and salt "mnemonic" + passphrase
+ * to derive a 64-byte seed. The async version is preferred for non-blocking.
+ *
+ * @param mnemonic - The mnemonic string (space-separated words)
+ * @param passphrase - Optional passphrase for additional security (default: "")
+ * @returns Effect containing the 64-byte seed, requiring Bip39Service
+ *
+ * @example
+ * ```typescript
+ * import { mnemonicToSeed, Bip39Live } from 'voltaire-effect/crypto/Bip39'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = mnemonicToSeed('abandon abandon ...', 'my-secret-passphrase')
+ *   .pipe(Effect.provide(Bip39Live))
+ * // Returns: Uint8Array(64)
+ * ```
+ *
+ * @throws Never fails if mnemonic is valid
+ * @see {@link mnemonicToSeedSync} for synchronous version
+ * @since 0.0.1
+ */
+export const mnemonicToSeed = (
+	mnemonic: string,
+	passphrase?: string,
+): Effect.Effect<Uint8Array, never, Bip39Service> =>
+	Effect.gen(function* () {
+		const bip39 = yield* Bip39Service;
+		return yield* bip39.mnemonicToSeed(mnemonic, passphrase);
+	});
+
+/**
+ * Converts a mnemonic to a seed synchronously.
+ *
+ * @description
+ * Uses PBKDF2-SHA512 with 2048 iterations. Blocks the thread during
+ * computation. Use async version for better performance in concurrent code.
+ *
+ * @param mnemonic - The mnemonic string (space-separated words)
+ * @param passphrase - Optional passphrase for additional security (default: "")
+ * @returns Effect containing the 64-byte seed, requiring Bip39Service
+ *
+ * @example
+ * ```typescript
+ * import { mnemonicToSeedSync, Bip39Live } from 'voltaire-effect/crypto/Bip39'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = mnemonicToSeedSync('abandon abandon ...')
+ *   .pipe(Effect.provide(Bip39Live))
+ * ```
+ *
+ * @throws Never fails if mnemonic is valid
+ * @see {@link mnemonicToSeed} for async version (preferred)
+ * @since 0.0.1
+ */
+export const mnemonicToSeedSync = (
+	mnemonic: string,
+	passphrase?: string,
+): Effect.Effect<Uint8Array, never, Bip39Service> =>
+	Effect.gen(function* () {
+		const bip39 = yield* Bip39Service;
+		return yield* bip39.mnemonicToSeedSync(mnemonic, passphrase);
+	});
+
+/**
+ * Returns the word count for a given entropy strength.
+ *
+ * @description
+ * Maps entropy bits to the number of mnemonic words per BIP-39 spec.
+ * Formula: (entropyBits + entropyBits/32) / 11 = wordCount
+ *
+ * @param entropyBits - The entropy in bits (128, 160, 192, 224, or 256)
+ * @returns Effect containing the word count, requiring Bip39Service
+ *
+ * @example
+ * ```typescript
+ * import { getWordCount, Bip39Live } from 'voltaire-effect/crypto/Bip39'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = getWordCount(256).pipe(Effect.provide(Bip39Live))
+ * // Returns: 24
+ * ```
+ *
+ * @throws Never fails
+ * @since 0.0.1
+ */
+export const getWordCount = (
+	entropyBits: MnemonicStrength,
+): Effect.Effect<number, never, Bip39Service> =>
+	Effect.gen(function* () {
+		const bip39 = yield* Bip39Service;
+		return yield* bip39.getWordCount(entropyBits);
+	});

package/src/crypto/Bip39/types.ts

@@ -0,0 +1,16 @@
+/**
+ * Valid entropy strengths for BIP-39 mnemonic generation.
+ * Maps to word counts: 128 -> 12, 160 -> 15, 192 -> 18, 224 -> 21, 256 -> 24.
+ */
+export type MnemonicStrength = 128 | 160 | 192 | 224 | 256;
+
+/**
+ * Word count for each entropy strength.
+ */
+export const WORD_COUNTS: Record<MnemonicStrength, number> = {
+	128: 12,
+	160: 15,
+	192: 18,
+	224: 21,
+	256: 24,
+} as const;

package/src/crypto/Bip39/utils.ts

@@ -0,0 +1,42 @@
+import { type MnemonicStrength, WORD_COUNTS } from "./types.js";
+
+/**
+ * Splits a BIP-39 mnemonic sentence into words.
+ *
+ * @param mnemonic - Space-separated mnemonic sentence
+ * @returns Array of mnemonic words
+ */
+export const mnemonicToWords = (mnemonic: string): string[] => {
+	return mnemonic
+		.normalize("NFKD")
+		.split(" ")
+		.filter((word) => word.length > 0);
+};
+
+/**
+ * Joins mnemonic words into a space-separated sentence.
+ *
+ * @param words - Array of mnemonic words
+ * @returns Space-separated mnemonic sentence
+ */
+export const wordsToMnemonic = (words: readonly string[]): string => {
+	return words.join(" ");
+};
+
+/**
+ * Validates mnemonic word count per BIP-39.
+ *
+ * @param mnemonic - Space-separated mnemonic sentence
+ * @returns True if word count is valid (12, 15, 18, 21, or 24)
+ */
+export const validateWordCount = (mnemonic: string): boolean => {
+	const count = mnemonicToWords(mnemonic).length;
+	return [12, 15, 18, 21, 24].includes(count);
+};
+
+/**
+ * Gets the expected word count for an entropy strength.
+ */
+export const getWordCount = (strength: MnemonicStrength): number => {
+	return WORD_COUNTS[strength];
+};

package/src/crypto/Blake2/Blake2.test.ts

@@ -0,0 +1,317 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import { Blake2Live, Blake2Service, Blake2Test, hash } from "./index.js";
+
+const bytesToHex = (bytes: Uint8Array): string => {
+	return (
+		"0x" +
+		Array.from(bytes)
+			.map((b) => b.toString(16).padStart(2, "0"))
+			.join("")
+	);
+};
+
+describe("Blake2Service", () => {
+	describe("Blake2Live", () => {
+		it.effect("hashes data using Voltaire Blake2", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new Uint8Array([1, 2, 3]));
+				expect(result).toBeInstanceOf(Uint8Array);
+				expect(result.length).toBe(64);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+
+		it.effect("supports custom output length", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new Uint8Array([1, 2, 3]), 32);
+				expect(result).toBeInstanceOf(Uint8Array);
+				expect(result.length).toBe(32);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+
+		it.effect("produces correct hash for known input", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new Uint8Array([]));
+				expect(result[0]).toBe(0x78);
+				expect(result[1]).toBe(0x6a);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+	});
+
+	describe("Known Vector Tests (RFC 7693)", () => {
+		it.effect("matches known vector: empty string (64 bytes)", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new Uint8Array(0));
+				expect(bytesToHex(result)).toBe(
+					"0x786a02f742015903c6c6fd852552d272912f4740e15847618a86e217f71f5419d25e1031afee585313896444934eb04b903a685b1448b755d56f701afe9be2ce",
+				);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+
+		it.effect('matches known vector: "abc"', () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new TextEncoder().encode("abc"));
+				expect(bytesToHex(result)).toBe(
+					"0xba80a53f981c4d0d6a2797b69f12f6e94c212f14685ac4b74b12bb6fdbffa2d17d87c5392aab792dc252d5de4533cc9518d38aa8dbf1925ab92386edd4009923",
+				);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+
+		it.effect('matches known vector: "hello"', () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new TextEncoder().encode("hello"));
+				expect(result.length).toBe(64);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+
+		it.effect("matches known vector: single zero byte", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new Uint8Array([0x00]));
+				expect(result.length).toBe(64);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+
+		it.effect("matches known vector: 0xff byte", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new Uint8Array([0xff]));
+				expect(result.length).toBe(64);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+	});
+
+	describe("Output length variations", () => {
+		it.effect("produces 1-byte output", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new Uint8Array([1, 2, 3]), 1);
+				expect(result.length).toBe(1);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+
+		it.effect("produces 16-byte output", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new Uint8Array([1, 2, 3]), 16);
+				expect(result.length).toBe(16);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+
+		it.effect("produces 32-byte output", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new Uint8Array([1, 2, 3]), 32);
+				expect(result.length).toBe(32);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+
+		it.effect("produces 48-byte output", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new Uint8Array([1, 2, 3]), 48);
+				expect(result.length).toBe(48);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+
+		it.effect("produces 64-byte output (default)", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new Uint8Array([1, 2, 3]));
+				expect(result.length).toBe(64);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+	});
+
+	describe("Input size variations", () => {
+		it.effect("hashes empty input", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new Uint8Array(0));
+				expect(result.length).toBe(64);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+
+		it.effect("hashes single byte", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new Uint8Array([0x42]));
+				expect(result.length).toBe(64);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+
+		it.effect("hashes 128 bytes (block size)", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new Uint8Array(128).fill(0x11));
+				expect(result.length).toBe(64);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+
+		it.effect("hashes 129 bytes (block size + 1)", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new Uint8Array(129).fill(0x22));
+				expect(result.length).toBe(64);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+
+		it.effect("hashes 1KB input", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new Uint8Array(1024).fill(0x33));
+				expect(result.length).toBe(64);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+
+		it.effect("hashes 64KB input", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new Uint8Array(65536).fill(0x44));
+				expect(result.length).toBe(64);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+
+		it.effect("hashes 1MB input", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(
+					new Uint8Array(1024 * 1024).fill(0x55),
+				);
+				expect(result.length).toBe(64);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+	});
+
+	describe("Determinism", () => {
+		it.effect("produces same hash for same input", () =>
+			Effect.gen(function* () {
+				const input = new Uint8Array([1, 2, 3, 4, 5]);
+				const blake2 = yield* Blake2Service;
+				const hash1 = yield* blake2.hash(input);
+				const hash2 = yield* blake2.hash(input);
+				expect(bytesToHex(hash1)).toBe(bytesToHex(hash2));
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+
+		it.effect("produces different hash for different input", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const hash1 = yield* blake2.hash(new Uint8Array([1, 2, 3]));
+				const hash2 = yield* blake2.hash(new Uint8Array([1, 2, 4]));
+				expect(bytesToHex(hash1)).not.toBe(bytesToHex(hash2));
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+
+		it.effect("produces different hash for different output lengths", () =>
+			Effect.gen(function* () {
+				const input = new Uint8Array([1, 2, 3]);
+				const blake2 = yield* Blake2Service;
+				const hash32 = yield* blake2.hash(input, 32);
+				const hash64 = yield* blake2.hash(input, 64);
+				expect(hash32.length).toBe(32);
+				expect(hash64.length).toBe(64);
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+
+		it.effect("is sensitive to single bit change", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const hash1 = yield* blake2.hash(new Uint8Array([0b00000000]));
+				const hash2 = yield* blake2.hash(new Uint8Array([0b00000001]));
+				expect(bytesToHex(hash1)).not.toBe(bytesToHex(hash2));
+			}).pipe(Effect.provide(Blake2Live)),
+		);
+	});
+
+	describe("Blake2Test", () => {
+		it.effect("returns deterministic zero-filled hash", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new Uint8Array([1, 2, 3]));
+				expect(result).toBeInstanceOf(Uint8Array);
+				expect(result.length).toBe(64);
+				expect(result.every((b) => b === 0)).toBe(true);
+			}).pipe(Effect.provide(Blake2Test)),
+		);
+
+		it.effect("respects custom output length in test layer", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const result = yield* blake2.hash(new Uint8Array([1, 2, 3]), 32);
+				expect(result.length).toBe(32);
+				expect(result.every((b) => b === 0)).toBe(true);
+			}).pipe(Effect.provide(Blake2Test)),
+		);
+
+		it.effect("returns same result for different inputs", () =>
+			Effect.gen(function* () {
+				const blake2 = yield* Blake2Service;
+				const hash1 = yield* blake2.hash(new Uint8Array([1, 2, 3]));
+				const hash2 = yield* blake2.hash(new Uint8Array([4, 5, 6]));
+				expect(bytesToHex(hash1)).toBe(bytesToHex(hash2));
+			}).pipe(Effect.provide(Blake2Test)),
+		);
+	});
+});
+
+describe("hash", () => {
+	it.effect("hashes data with Blake2Service dependency", () =>
+		Effect.gen(function* () {
+			const data = new Uint8Array([104, 101, 108, 108, 111]);
+			const result = yield* hash(data);
+			expect(result).toBeInstanceOf(Uint8Array);
+			expect(result.length).toBe(64);
+		}).pipe(Effect.provide(Blake2Live)),
+	);
+
+	it.effect("supports custom output length", () =>
+		Effect.gen(function* () {
+			const data = new Uint8Array([104, 101, 108, 108, 111]);
+			const result = yield* hash(data, 32);
+			expect(result.length).toBe(32);
+		}).pipe(Effect.provide(Blake2Live)),
+	);
+
+	it.effect("works with test layer", () =>
+		Effect.gen(function* () {
+			const data = new Uint8Array([1, 2, 3]);
+			const result = yield* hash(data);
+			expect(result.every((b) => b === 0)).toBe(true);
+		}).pipe(Effect.provide(Blake2Test)),
+	);
+
+	it("matches service result", async () => {
+		const data = new Uint8Array([104, 101, 108, 108, 111]);
+		const [hashResult, serviceResult] = await Promise.all([
+			Effect.runPromise(hash(data).pipe(Effect.provide(Blake2Live))),
+			Effect.runPromise(
+				Effect.gen(function* () {
+					const blake2 = yield* Blake2Service;
+					return yield* blake2.hash(data);
+				}).pipe(Effect.provide(Blake2Live)),
+			),
+		]);
+		expect(bytesToHex(hashResult)).toBe(bytesToHex(serviceResult));
+	});
+
+	it("matches service result with custom length", async () => {
+		const data = new Uint8Array([104, 101, 108, 108, 111]);
+		const [hashResult, serviceResult] = await Promise.all([
+			Effect.runPromise(hash(data, 32).pipe(Effect.provide(Blake2Live))),
+			Effect.runPromise(
+				Effect.gen(function* () {
+					const blake2 = yield* Blake2Service;
+					return yield* blake2.hash(data, 32);
+				}).pipe(Effect.provide(Blake2Live)),
+			),
+		]);
+		expect(bytesToHex(hashResult)).toBe(bytesToHex(serviceResult));
+	});
+});