voltaire-effect 0.2.23

package/src/crypto/AesGcm/errors.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Error types for AES-GCM encryption operations.
+ * @module AesGcm/errors
+ * @since 0.0.1
+ */
+
+import * as Data from "effect/Data";
+
+/**
+ * Invalid key size for AES-GCM encryption.
+ * Key must be 16 bytes (128-bit), 24 bytes (192-bit), or 32 bytes (256-bit).
+ *
+ * @since 0.0.1
+ */
+export class InvalidKeyError extends Data.TaggedError("InvalidKeyError")<{
+	readonly message: string;
+	readonly keyLength: number;
+	readonly expectedLengths: readonly number[];
+}> {}
+
+/**
+ * Invalid nonce size for AES-GCM encryption.
+ * Nonce must be 12 bytes (96-bit).
+ *
+ * @since 0.0.1
+ */
+export class InvalidNonceError extends Data.TaggedError("InvalidNonceError")<{
+	readonly message: string;
+	readonly nonceLength: number;
+	readonly expectedLength: number;
+}> {}
+
+/**
+ * Union of all AES-GCM error types.
+ *
+ * @since 0.0.1
+ */
+export type AesGcmError = InvalidKeyError | InvalidNonceError;

package/src/crypto/AesGcm/index.ts

@@ -0,0 +1,101 @@
+/**
+ * @fileoverview AES-GCM authenticated encryption module for Effect.
+ * Provides 128/256-bit AES encryption with Galois/Counter Mode for authenticated encryption.
+ *
+ * @module AesGcm
+ * @since 0.0.1
+ *
+ * @description
+ * AES-GCM (Advanced Encryption Standard - Galois/Counter Mode) provides both
+ * confidentiality and authentication. Key features:
+ *
+ * - 128-bit or 256-bit keys
+ * - 96-bit (12-byte) nonces (IVs)
+ * - 128-bit authentication tag appended to ciphertext
+ * - Optional additional authenticated data (AAD)
+ *
+ * @example
+ * ```typescript
+ * import { AesGcmService, AesGcmLive, encrypt, decrypt, generateKey, generateNonce } from 'voltaire-effect/crypto/AesGcm'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const key = yield* generateKey(256)
+ *   const nonce = yield* generateNonce()
+ *   const plaintext = new TextEncoder().encode('hello')
+ *   const ciphertext = yield* encrypt(key, plaintext, nonce)
+ *   const decrypted = yield* decrypt(key, ciphertext, nonce)
+ *   return decrypted
+ * }).pipe(Effect.provide(AesGcmLive))
+ * ```
+ *
+ * @see {@link https://csrc.nist.gov/pubs/sp/800/38/d/final | NIST SP 800-38D}
+ */
+export { AesGcmService, type AesGcmServiceShape } from "./AesGcmService.js";
+export {
+	type AesGcmError,
+	InvalidKeyError,
+	InvalidNonceError,
+} from "./errors.js";
+export { decrypt, encrypt, generateKey, generateNonce } from "./operations.js";
+
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { AesGcmService } from "./AesGcmService.js";
+import { decrypt, encrypt, generateKey, generateNonce } from "./operations.js";
+
+/**
+ * Production layer for AesGcmService using Web Crypto API.
+ *
+ * @description
+ * Provides real AES-GCM operations using the browser's native Web Crypto API.
+ * Uses cryptographically secure random number generation for keys and nonces.
+ *
+ * @example
+ * ```typescript
+ * import { AesGcmService, AesGcmLive } from 'voltaire-effect/crypto/AesGcm'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const aes = yield* AesGcmService
+ *   const key = yield* aes.generateKey(256)
+ *   return key
+ * }).pipe(Effect.provide(AesGcmLive))
+ * ```
+ *
+ * @since 0.0.1
+ * @see {@link AesGcmTest} for unit testing
+ */
+export const AesGcmLive = Layer.succeed(AesGcmService, {
+	encrypt: (key, plaintext, nonce, aad) => encrypt(key, plaintext, nonce, aad),
+	decrypt: (key, ciphertext, nonce, aad) =>
+		decrypt(key, ciphertext, nonce, aad),
+	generateKey: (bits) => generateKey(bits ?? 256),
+	generateNonce: () => generateNonce(),
+});
+
+/**
+ * Test layer for AesGcmService returning deterministic mock values.
+ *
+ * @description
+ * Provides mock implementations for unit testing. Returns zero-filled
+ * arrays for encrypted data and keys.
+ * Use when testing application logic without cryptographic overhead.
+ *
+ * @example
+ * ```typescript
+ * import { AesGcmService, AesGcmTest, encrypt } from 'voltaire-effect/crypto/AesGcm'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const testProgram = encrypt(key, plaintext, nonce).pipe(Effect.provide(AesGcmTest))
+ * // Returns Uint8Array(32) filled with zeros
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const AesGcmTest = Layer.succeed(AesGcmService, {
+	encrypt: () => Effect.succeed(new Uint8Array(32)),
+	decrypt: () => Effect.succeed(new Uint8Array(16)),
+	generateKey: () => Effect.succeed(new Uint8Array(32)),
+	generateNonce: () => Effect.succeed(new Uint8Array(12)),
+});

package/src/crypto/AesGcm/operations.ts

@@ -0,0 +1,191 @@
+/**
+ * @fileoverview AES-GCM encryption operations for Effect.
+ * @module AesGcm/operations
+ * @since 0.0.1
+ */
+
+import { AesGcm } from "@tevm/voltaire";
+import * as Effect from "effect/Effect";
+import { InvalidKeyError, InvalidNonceError } from "./errors.js";
+
+// Only AES-128 (16 bytes) and AES-256 (32 bytes) are supported
+// AES-192 (24 bytes) is not supported by the underlying implementation
+const VALID_KEY_LENGTHS = [16, 32] as const;
+const NONCE_LENGTH = 12;
+
+const validateKey = (key: Uint8Array) =>
+	VALID_KEY_LENGTHS.includes(key.length as 16 | 32)
+		? Effect.void
+		: Effect.fail(
+				new InvalidKeyError({
+					message: `Key must be 16 or 32 bytes, got ${key.length}`,
+					keyLength: key.length,
+					expectedLengths: VALID_KEY_LENGTHS,
+				}),
+			);
+
+const validateNonce = (nonce: Uint8Array) =>
+	nonce.length === NONCE_LENGTH
+		? Effect.void
+		: Effect.fail(
+				new InvalidNonceError({
+					message: `Nonce must be ${NONCE_LENGTH} bytes, got ${nonce.length}`,
+					nonceLength: nonce.length,
+					expectedLength: NONCE_LENGTH,
+				}),
+			);
+
+/**
+ * Encrypts plaintext using AES-GCM.
+ *
+ * @description
+ * Encrypts data using AES-GCM mode with a 128-bit authentication tag.
+ * The ciphertext includes the auth tag appended at the end.
+ *
+ * @param key - 16-byte (128-bit) or 32-byte (256-bit) symmetric key
+ * @param plaintext - Data to encrypt (any length)
+ * @param nonce - 12-byte (96-bit) nonce/IV - MUST be unique per key
+ * @param aad - Optional additional authenticated data (authenticated but not encrypted)
+ * @returns Effect containing ciphertext (plaintext.length + 16 bytes for auth tag)
+ *
+ * @example
+ * ```typescript
+ * import { encrypt, generateKey, generateNonce } from 'voltaire-effect/crypto/AesGcm'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const key = yield* generateKey(256)
+ *   const nonce = yield* generateNonce()
+ *   return yield* encrypt(key, new Uint8Array([1, 2, 3]), nonce)
+ * })
+ * ```
+ *
+ * @throws Error if key or nonce has invalid length
+ * @see {@link decrypt} to decrypt the ciphertext
+ * @since 0.0.1
+ */
+export const encrypt = (
+	key: Uint8Array,
+	plaintext: Uint8Array,
+	nonce: Uint8Array,
+	aad?: Uint8Array,
+): Effect.Effect<Uint8Array, Error | InvalidKeyError | InvalidNonceError> =>
+	Effect.gen(function* () {
+		yield* validateKey(key);
+		yield* validateNonce(nonce);
+		return yield* Effect.tryPromise({
+			try: async () => {
+				const cryptoKey = await AesGcm.importKey(key);
+				return AesGcm.encrypt(plaintext, cryptoKey, nonce, aad);
+			},
+			catch: (e) => e as Error,
+		});
+	});
+
+/**
+ * Decrypts ciphertext using AES-GCM.
+ *
+ * @description
+ * Decrypts and authenticates AES-GCM ciphertext. Verifies the 128-bit
+ * authentication tag appended to the ciphertext.
+ *
+ * @param key - Same key used for encryption
+ * @param ciphertext - Encrypted data with 16-byte auth tag appended
+ * @param nonce - Same 12-byte nonce used for encryption
+ * @param aad - Same additional authenticated data used for encryption (if any)
+ * @returns Effect containing decrypted plaintext
+ *
+ * @example
+ * ```typescript
+ * import { decrypt, encrypt, generateKey, generateNonce } from 'voltaire-effect/crypto/AesGcm'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const key = yield* generateKey(256)
+ *   const nonce = yield* generateNonce()
+ *   const ciphertext = yield* encrypt(key, plaintext, nonce)
+ *   return yield* decrypt(key, ciphertext, nonce)
+ * })
+ * ```
+ *
+ * @throws Error if authentication fails (data tampered or wrong key/nonce)
+ * @see {@link encrypt} to encrypt data
+ * @since 0.0.1
+ */
+export const decrypt = (
+	key: Uint8Array,
+	ciphertext: Uint8Array,
+	nonce: Uint8Array,
+	aad?: Uint8Array,
+): Effect.Effect<Uint8Array, Error | InvalidKeyError | InvalidNonceError> =>
+	Effect.gen(function* () {
+		yield* validateKey(key);
+		yield* validateNonce(nonce);
+		return yield* Effect.tryPromise({
+			try: async () => {
+				const cryptoKey = await AesGcm.importKey(key);
+				return AesGcm.decrypt(ciphertext, cryptoKey, nonce, aad);
+			},
+			catch: (e) => e as Error,
+		});
+	});
+
+/**
+ * Generates a cryptographically random AES key.
+ *
+ * @description
+ * Uses the Web Crypto API to generate a cryptographically secure
+ * random key suitable for AES-GCM encryption.
+ *
+ * @param bits - Key size: 128 or 256 bits (default: 256)
+ * @returns Effect containing the raw key bytes (16 or 32 bytes)
+ *
+ * @example
+ * ```typescript
+ * import { generateKey } from 'voltaire-effect/crypto/AesGcm'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = generateKey(256) // 32-byte key
+ * ```
+ *
+ * @throws Never fails
+ * @see {@link generateNonce} to generate a nonce
+ * @since 0.0.1
+ */
+export const generateKey = (
+	bits: 128 | 256 = 256,
+): Effect.Effect<Uint8Array, Error> =>
+	Effect.tryPromise({
+		try: async () => {
+			const cryptoKey = await AesGcm.generateKey(bits);
+			return AesGcm.exportKey(cryptoKey);
+		},
+		catch: (e) => e as Error,
+	});
+
+/**
+ * Generates a cryptographically random 96-bit nonce.
+ *
+ * @description
+ * Generates a 12-byte nonce suitable for AES-GCM. Each nonce MUST be
+ * unique for a given key - reusing a nonce breaks the security of GCM.
+ *
+ * @returns Effect containing 12-byte random nonce
+ *
+ * @example
+ * ```typescript
+ * import { generateNonce } from 'voltaire-effect/crypto/AesGcm'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = generateNonce() // 12-byte nonce
+ * ```
+ *
+ * @throws Never fails
+ * @see {@link generateKey} to generate a key
+ * @since 0.0.1
+ */
+export const generateNonce = (): Effect.Effect<Uint8Array, Error> =>
+	Effect.try({
+		try: () => AesGcm.generateNonce(),
+		catch: (e) => e as Error,
+	});

package/src/crypto/Bip39/Bip39.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import {
+	Bip39Live,
+	Bip39Service,
+	Bip39Test,
+	generateMnemonic,
+	getWordCount,
+	mnemonicToSeed,
+	mnemonicToWords,
+	validateMnemonic,
+	validateWordCount,
+	wordsToMnemonic,
+} from "./index.js";
+
+const TEST_MNEMONIC =
+	"abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
+
+describe("Bip39Service", () => {
+	describe("Bip39Live", () => {
+		it.effect("generates 12-word mnemonic (128 bits)", () =>
+			Effect.gen(function* () {
+				const bip39 = yield* Bip39Service;
+				const result = yield* bip39.generateMnemonic(128);
+				expect(typeof result).toBe("string");
+				expect(result.split(" ").length).toBe(12);
+			}).pipe(Effect.provide(Bip39Live)),
+		);
+
+		it.effect("generates 24-word mnemonic (256 bits)", () =>
+			Effect.gen(function* () {
+				const bip39 = yield* Bip39Service;
+				const result = yield* bip39.generateMnemonic(256);
+				expect(result.split(" ").length).toBe(24);
+			}).pipe(Effect.provide(Bip39Live)),
+		);
+
+		it.effect("validates known valid mnemonic", () =>
+			Effect.gen(function* () {
+				const bip39 = yield* Bip39Service;
+				const result = yield* bip39.validateMnemonic(TEST_MNEMONIC);
+				expect(result).toBe(true);
+			}).pipe(Effect.provide(Bip39Live)),
+		);
+
+		it.effect("rejects invalid mnemonic", () =>
+			Effect.gen(function* () {
+				const bip39 = yield* Bip39Service;
+				const result = yield* bip39.validateMnemonic("invalid mnemonic phrase");
+				expect(result).toBe(false);
+			}).pipe(Effect.provide(Bip39Live)),
+		);
+
+		it.effect("converts mnemonic to seed", () =>
+			Effect.gen(function* () {
+				const bip39 = yield* Bip39Service;
+				const result = yield* bip39.mnemonicToSeed(TEST_MNEMONIC);
+				expect(result).toBeInstanceOf(Uint8Array);
+				expect(result.length).toBe(64);
+			}).pipe(Effect.provide(Bip39Live)),
+		);
+
+		it.effect("converts mnemonic to seed with passphrase", () =>
+			Effect.gen(function* () {
+				const bip39 = yield* Bip39Service;
+				const seedWithPass = yield* bip39.mnemonicToSeed(
+					TEST_MNEMONIC,
+					"password",
+				);
+				const seedWithoutPass = yield* bip39.mnemonicToSeed(TEST_MNEMONIC);
+				expect(seedWithPass.length).toBe(64);
+				expect(seedWithoutPass.length).toBe(64);
+				expect(Buffer.from(seedWithPass).toString("hex")).not.toBe(
+					Buffer.from(seedWithoutPass).toString("hex"),
+				);
+			}).pipe(Effect.provide(Bip39Live)),
+		);
+
+		it.effect("gets word count from entropy bits", () =>
+			Effect.gen(function* () {
+				const bip39 = yield* Bip39Service;
+				const result = yield* bip39.getWordCount(128);
+				expect(result).toBe(12);
+			}).pipe(Effect.provide(Bip39Live)),
+		);
+
+		it.effect("gets word count for 256 bits", () =>
+			Effect.gen(function* () {
+				const bip39 = yield* Bip39Service;
+				const result = yield* bip39.getWordCount(256);
+				expect(result).toBe(24);
+			}).pipe(Effect.provide(Bip39Live)),
+		);
+	});
+
+	describe("Bip39Test", () => {
+		it.effect("returns test mnemonic", () =>
+			Effect.gen(function* () {
+				const bip39 = yield* Bip39Service;
+				const result = yield* bip39.generateMnemonic();
+				expect(result).toBe(TEST_MNEMONIC);
+			}).pipe(Effect.provide(Bip39Test)),
+		);
+
+		it.effect("always validates as true", () =>
+			Effect.gen(function* () {
+				const bip39 = yield* Bip39Service;
+				const result = yield* bip39.validateMnemonic("anything");
+				expect(result).toBe(true);
+			}).pipe(Effect.provide(Bip39Test)),
+		);
+	});
+});
+
+describe("convenience functions", () => {
+	it.effect("generateMnemonic works with service dependency", () =>
+		Effect.gen(function* () {
+			const result = yield* generateMnemonic(128);
+			expect(result.split(" ").length).toBe(12);
+		}).pipe(Effect.provide(Bip39Live)),
+	);
+
+	it.effect("validateMnemonic works with service dependency", () =>
+		Effect.gen(function* () {
+			const result = yield* validateMnemonic(TEST_MNEMONIC);
+			expect(result).toBe(true);
+		}).pipe(Effect.provide(Bip39Live)),
+	);
+
+	it.effect("mnemonicToSeed works with service dependency", () =>
+		Effect.gen(function* () {
+			const result = yield* mnemonicToSeed(TEST_MNEMONIC);
+			expect(result).toBeInstanceOf(Uint8Array);
+			expect(result.length).toBe(64);
+		}).pipe(Effect.provide(Bip39Live)),
+	);
+
+	it.effect("getWordCount works with service dependency", () =>
+		Effect.gen(function* () {
+			const result = yield* getWordCount(128);
+			expect(result).toBe(12);
+		}).pipe(Effect.provide(Bip39Live)),
+	);
+});
+
+describe("mnemonic utilities", () => {
+	it("mnemonicToWords splits mnemonic into words", () => {
+		const words = mnemonicToWords(TEST_MNEMONIC);
+		expect(words.length).toBe(12);
+		expect(words[0]).toBe("abandon");
+		expect(words[11]).toBe("about");
+	});
+
+	it("mnemonicToWords trims extra whitespace", () => {
+		const words = mnemonicToWords("  abandon   abandon  about  ");
+		expect(words).toEqual(["abandon", "abandon", "about"]);
+	});
+
+	it("wordsToMnemonic joins words with single spaces", () => {
+		const result = wordsToMnemonic(["abandon", "abandon", "about"]);
+		expect(result).toBe("abandon abandon about");
+	});
+
+	it("validateWordCount accepts valid counts", () => {
+		expect(validateWordCount("a ".repeat(12).trim())).toBe(true);
+		expect(validateWordCount("a ".repeat(15).trim())).toBe(true);
+		expect(validateWordCount("a ".repeat(18).trim())).toBe(true);
+		expect(validateWordCount("a ".repeat(21).trim())).toBe(true);
+		expect(validateWordCount("a ".repeat(24).trim())).toBe(true);
+	});
+
+	it("validateWordCount rejects invalid counts", () => {
+		expect(validateWordCount("a ".repeat(11).trim())).toBe(false);
+		expect(validateWordCount("a ".repeat(13).trim())).toBe(false);
+		expect(validateWordCount("a ".repeat(25).trim())).toBe(false);
+		expect(validateWordCount("")).toBe(false);
+	});
+
+	it("mnemonicToWords and wordsToMnemonic roundtrip", () => {
+		const restored = wordsToMnemonic(mnemonicToWords(TEST_MNEMONIC));
+		expect(restored).toBe(TEST_MNEMONIC);
+	});
+});

package/src/crypto/Bip39/Bip39Service.ts

@@ -0,0 +1,160 @@
+/**
+ * @fileoverview Bip39Service Effect service definition for BIP-39 mnemonic operations.
+ * @module Bip39/Bip39Service
+ * @since 0.0.1
+ */
+import { Bip39 } from "@tevm/voltaire";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type { MnemonicStrength } from "./types.js";
+
+/**
+ * Shape interface for BIP-39 mnemonic operations.
+ *
+ * @description
+ * Defines the contract for BIP-39 implementations. All methods return Effect
+ * types for composable, type-safe async/error handling.
+ *
+ * @since 0.0.1
+ */
+export interface Bip39ServiceShape {
+	/**
+	 * Generates a BIP-39 mnemonic sentence.
+	 *
+	 * @param strength - Entropy bits: 128=12 words, 160=15, 192=18, 224=21, 256=24
+	 * @returns Effect containing the space-separated mnemonic sentence
+	 *
+	 * @see {@link https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki | BIP-39 Specification}
+	 */
+	readonly generateMnemonic: (
+		strength?: MnemonicStrength,
+	) => Effect.Effect<string>;
+
+	/**
+	 * Validates a BIP-39 mnemonic phrase.
+	 * @param mnemonic - The mnemonic string to validate
+	 * @returns Effect containing true if valid
+	 */
+	readonly validateMnemonic: (mnemonic: string) => Effect.Effect<boolean>;
+
+	/**
+	 * Converts a mnemonic to a seed asynchronously.
+	 * @param mnemonic - The mnemonic string
+	 * @param passphrase - Optional passphrase
+	 * @returns Effect containing the 64-byte seed
+	 */
+	readonly mnemonicToSeed: (
+		mnemonic: string,
+		passphrase?: string,
+	) => Effect.Effect<Uint8Array>;
+
+	/**
+	 * Converts a mnemonic to a seed synchronously.
+	 * @param mnemonic - The mnemonic string
+	 * @param passphrase - Optional passphrase
+	 * @returns Effect containing the 64-byte seed
+	 */
+	readonly mnemonicToSeedSync: (
+		mnemonic: string,
+		passphrase?: string,
+	) => Effect.Effect<Uint8Array>;
+
+	/**
+	 * Returns the word count for a given entropy strength.
+	 * @param entropyBits - The entropy in bits
+	 * @returns Effect containing the word count
+	 */
+	readonly getWordCount: (
+		entropyBits: MnemonicStrength,
+	) => Effect.Effect<number>;
+}
+
+/**
+ * BIP-39 mnemonic service for Effect-based applications.
+ * Generates and validates mnemonic phrases for HD wallet derivation.
+ *
+ * @example
+ * ```typescript
+ * import { Bip39Service, Bip39Live } from 'voltaire-effect/crypto'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const bip39 = yield* Bip39Service
+ *   const mnemonic = yield* bip39.generateMnemonic(128)
+ *   const isValid = yield* bip39.validateMnemonic(mnemonic)
+ *   return yield* bip39.mnemonicToSeed(mnemonic)
+ * }).pipe(Effect.provide(Bip39Live))
+ * ```
+ * @since 0.0.1
+ */
+export class Bip39Service extends Context.Tag("Bip39Service")<
+	Bip39Service,
+	Bip39ServiceShape
+>() {}
+
+/**
+ * Production layer for Bip39Service using native BIP-39 implementation.
+ *
+ * @description
+ * Provides real cryptographic BIP-39 operations. Uses secure random number
+ * generation and proper PBKDF2-SHA512 for seed derivation.
+ *
+ * @example
+ * ```typescript
+ * import { Bip39Service, Bip39Live } from 'voltaire-effect/crypto/Bip39'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const bip39 = yield* Bip39Service
+ *   return yield* bip39.generateMnemonic(256)
+ * }).pipe(Effect.provide(Bip39Live))
+ * ```
+ *
+ * @since 0.0.1
+ * @see {@link Bip39Test} for unit testing
+ */
+export const Bip39Live = Layer.succeed(Bip39Service, {
+	generateMnemonic: (strength = 128) =>
+		Effect.sync(() => Bip39.generateMnemonic(strength)),
+	validateMnemonic: (mnemonic) =>
+		Effect.sync(() => Bip39.validateMnemonic(mnemonic)),
+	mnemonicToSeed: (mnemonic, passphrase) =>
+		Effect.promise(() => Bip39.mnemonicToSeed(mnemonic, passphrase)),
+	mnemonicToSeedSync: (mnemonic, passphrase) =>
+		Effect.sync(() => Bip39.mnemonicToSeedSync(mnemonic, passphrase)),
+	getWordCount: (entropyBits) =>
+		Effect.sync(() => Bip39.getWordCount(entropyBits)),
+});
+
+const TEST_MNEMONIC =
+	"abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
+
+/**
+ * Test layer for Bip39Service returning deterministic mock values.
+ *
+ * @description
+ * Provides mock implementations for unit testing. Returns the standard
+ * BIP-39 test vector mnemonic and always validates as true.
+ * Use when testing application logic without cryptographic overhead.
+ *
+ * @example
+ * ```typescript
+ * import { Bip39Service, Bip39Test, generateMnemonic } from 'voltaire-effect/crypto/Bip39'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const testProgram = generateMnemonic(128).pipe(Effect.provide(Bip39Test))
+ * // Always returns test vector mnemonic
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const Bip39Test = Layer.succeed(Bip39Service, {
+	generateMnemonic: (_strength) => Effect.succeed(TEST_MNEMONIC),
+	validateMnemonic: (_mnemonic) => Effect.succeed(true),
+	mnemonicToSeed: (_mnemonic, _passphrase) =>
+		Effect.succeed(new Uint8Array(64)),
+	mnemonicToSeedSync: (_mnemonic, _passphrase) =>
+		Effect.succeed(new Uint8Array(64)),
+	getWordCount: (_entropyBits) => Effect.succeed(12),
+});