voltaire-effect 0.2.23

package/src/crypto/Keystore/Keystore.test.ts

@@ -0,0 +1,511 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Keystore from "./index.js";
+
+describe("Keystore", () => {
+	const testPrivateKey = new Uint8Array([
+		0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c,
+		0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18,
+		0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x20,
+	]) as any;
+
+	const testPassword = "test-password-123";
+
+	describe("encrypt", () => {
+		it.effect("encrypts a private key to keystore v3 format", () =>
+			Effect.gen(function* () {
+				const result = yield* Keystore.encrypt(testPrivateKey, testPassword, {
+					scryptN: 1024,
+					scryptR: 8,
+					scryptP: 1,
+				});
+				expect(result.version).toBe(3);
+				expect(result.id).toBeDefined();
+				expect(result.crypto.cipher).toBe("aes-128-ctr");
+				expect(result.crypto.kdf).toBe("scrypt");
+				expect(result.crypto.ciphertext).toBeDefined();
+				expect(result.crypto.mac).toBeDefined();
+			}),
+		);
+
+		it.effect("supports pbkdf2 kdf", () =>
+			Effect.gen(function* () {
+				const result = yield* Keystore.encrypt(testPrivateKey, testPassword, {
+					kdf: "pbkdf2",
+					pbkdf2C: 1000,
+				});
+				expect(result.crypto.kdf).toBe("pbkdf2");
+				expect((result.crypto.kdfparams as any).c).toBe(1000);
+			}),
+		);
+
+		it.effect("works with empty password", () =>
+			Effect.gen(function* () {
+				const result = yield* Keystore.encrypt(testPrivateKey, "", {
+					scryptN: 1024,
+					scryptR: 8,
+					scryptP: 1,
+				});
+				expect(result.version).toBe(3);
+				const decrypted = yield* Keystore.decrypt(result, "");
+				expect(decrypted).toEqual(testPrivateKey);
+			}),
+		);
+
+		it("encrypts private key of any length (no validation)", async () => {
+			const shortKey = new Uint8Array([0x01, 0x02, 0x03]) as any;
+			const exit = await Effect.runPromiseExit(
+				Keystore.encrypt(shortKey, testPassword, {
+					scryptN: 1024,
+					scryptR: 8,
+					scryptP: 1,
+				}),
+			);
+			expect(Exit.isSuccess(exit)).toBe(true);
+		});
+
+		it("encrypts with long private key (no validation)", async () => {
+			const longKey = new Uint8Array(64).fill(0xab) as any;
+			const exit = await Effect.runPromiseExit(
+				Keystore.encrypt(longKey, testPassword, {
+					scryptN: 1024,
+					scryptR: 8,
+					scryptP: 1,
+				}),
+			);
+			expect(Exit.isSuccess(exit)).toBe(true);
+		});
+	});
+
+	describe("decrypt", () => {
+		it.effect("decrypts keystore back to original private key", () =>
+			Effect.gen(function* () {
+				const encrypted = yield* Keystore.encrypt(
+					testPrivateKey,
+					testPassword,
+					{
+						scryptN: 1024,
+						scryptR: 8,
+						scryptP: 1,
+					},
+				);
+				const decrypted = yield* Keystore.decrypt(encrypted, testPassword);
+				expect(decrypted).toEqual(testPrivateKey);
+			}),
+		);
+
+		it("fails with wrong password", async () => {
+			const encrypted = await Effect.runPromise(
+				Keystore.encrypt(testPrivateKey, testPassword, {
+					scryptN: 1024,
+					scryptR: 8,
+					scryptP: 1,
+				}),
+			);
+			const exit = await Effect.runPromiseExit(
+				Keystore.decrypt(encrypted, "wrong-password"),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+
+		it("fails with unsupported version", async () => {
+			const badKeystore = {
+				version: 2 as any,
+				id: "test",
+				crypto: {
+					cipher: "aes-128-ctr" as const,
+					ciphertext: "00",
+					cipherparams: { iv: "00" },
+					kdf: "scrypt" as const,
+					kdfparams: { dklen: 32, n: 1024, r: 8, p: 1, salt: "00" },
+					mac: "00",
+				},
+			};
+			const exit = await Effect.runPromiseExit(
+				Keystore.decrypt(badKeystore as any, testPassword),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+
+		it("fails with unsupported KDF (argon2)", async () => {
+			const badKeystore = {
+				version: 3,
+				id: "test",
+				crypto: {
+					cipher: "aes-128-ctr" as const,
+					ciphertext:
+						"00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
+					cipherparams: { iv: "00112233445566778899aabbccddeeff" },
+					kdf: "argon2" as any,
+					kdfparams: { dklen: 32, salt: "00112233445566778899aabbccddeeff" },
+					mac: "00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
+				},
+			};
+			const exit = await Effect.runPromiseExit(
+				Keystore.decrypt(badKeystore as any, testPassword),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+			if (Exit.isFailure(exit)) {
+				const error = exit.cause;
+				expect(error).toBeDefined();
+			}
+		});
+
+		it("fails with unsupported KDF (junk)", async () => {
+			const badKeystore = {
+				version: 3,
+				id: "test",
+				crypto: {
+					cipher: "aes-128-ctr" as const,
+					ciphertext:
+						"00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
+					cipherparams: { iv: "00112233445566778899aabbccddeeff" },
+					kdf: "totally-not-a-kdf" as any,
+					kdfparams: { dklen: 32, salt: "00112233445566778899aabbccddeeff" },
+					mac: "00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
+				},
+			};
+			const exit = await Effect.runPromiseExit(
+				Keystore.decrypt(badKeystore as any, testPassword),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+
+		it("fails with corrupted MAC", async () => {
+			const encrypted = await Effect.runPromise(
+				Keystore.encrypt(testPrivateKey, testPassword, {
+					scryptN: 1024,
+					scryptR: 8,
+					scryptP: 1,
+				}),
+			);
+			const corruptedKeystore = {
+				...encrypted,
+				crypto: {
+					...encrypted.crypto,
+					mac: encrypted.crypto.mac.replace(
+						/^./,
+						encrypted.crypto.mac[0] === "0" ? "1" : "0",
+					),
+				},
+			};
+			const exit = await Effect.runPromiseExit(
+				Keystore.decrypt(corruptedKeystore, testPassword),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+
+		it("fails with corrupted ciphertext", async () => {
+			const encrypted = await Effect.runPromise(
+				Keystore.encrypt(testPrivateKey, testPassword, {
+					scryptN: 1024,
+					scryptR: 8,
+					scryptP: 1,
+				}),
+			);
+			const corruptedKeystore = {
+				...encrypted,
+				crypto: {
+					...encrypted.crypto,
+					ciphertext: encrypted.crypto.ciphertext.replace(
+						/^./,
+						encrypted.crypto.ciphertext[0] === "0" ? "1" : "0",
+					),
+				},
+			};
+			const exit = await Effect.runPromiseExit(
+				Keystore.decrypt(corruptedKeystore, testPassword),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+
+		it("fails with missing crypto section", async () => {
+			const badKeystore = {
+				version: 3,
+				id: "test",
+			};
+			const exit = await Effect.runPromiseExit(
+				Keystore.decrypt(badKeystore as any, testPassword),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+
+		it("fails with missing cipherparams.iv", async () => {
+			const badKeystore = {
+				version: 3,
+				id: "test",
+				crypto: {
+					cipher: "aes-128-ctr" as const,
+					ciphertext:
+						"00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
+					cipherparams: {},
+					kdf: "scrypt" as const,
+					kdfparams: {
+						dklen: 32,
+						n: 1024,
+						r: 8,
+						p: 1,
+						salt: "00112233445566778899aabbccddeeff",
+					},
+					mac: "00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
+				},
+			};
+			const exit = await Effect.runPromiseExit(
+				Keystore.decrypt(badKeystore as any, testPassword),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+
+		it("fails with invalid hex in ciphertext", async () => {
+			const badKeystore = {
+				version: 3,
+				id: "test",
+				crypto: {
+					cipher: "aes-128-ctr" as const,
+					ciphertext: "not-valid-hex-gggg",
+					cipherparams: { iv: "00112233445566778899aabbccddeeff" },
+					kdf: "scrypt" as const,
+					kdfparams: {
+						dklen: 32,
+						n: 1024,
+						r: 8,
+						p: 1,
+						salt: "00112233445566778899aabbccddeeff",
+					},
+					mac: "00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
+				},
+			};
+			const exit = await Effect.runPromiseExit(
+				Keystore.decrypt(badKeystore as any, testPassword),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+
+		it("fails with invalid hex in iv", async () => {
+			const badKeystore = {
+				version: 3,
+				id: "test",
+				crypto: {
+					cipher: "aes-128-ctr" as const,
+					ciphertext:
+						"00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
+					cipherparams: { iv: "zzzz-not-hex" },
+					kdf: "scrypt" as const,
+					kdfparams: {
+						dklen: 32,
+						n: 1024,
+						r: 8,
+						p: 1,
+						salt: "00112233445566778899aabbccddeeff",
+					},
+					mac: "00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
+				},
+			};
+			const exit = await Effect.runPromiseExit(
+				Keystore.decrypt(badKeystore as any, testPassword),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+
+		it("fails with invalid hex in salt", async () => {
+			const badKeystore = {
+				version: 3,
+				id: "test",
+				crypto: {
+					cipher: "aes-128-ctr" as const,
+					ciphertext:
+						"00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
+					cipherparams: { iv: "00112233445566778899aabbccddeeff" },
+					kdf: "scrypt" as const,
+					kdfparams: { dklen: 32, n: 1024, r: 8, p: 1, salt: "not-hex!!!" },
+					mac: "00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
+				},
+			};
+			const exit = await Effect.runPromiseExit(
+				Keystore.decrypt(badKeystore as any, testPassword),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+
+		it("fails with invalid hex in mac", async () => {
+			const badKeystore = {
+				version: 3,
+				id: "test",
+				crypto: {
+					cipher: "aes-128-ctr" as const,
+					ciphertext:
+						"00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
+					cipherparams: { iv: "00112233445566778899aabbccddeeff" },
+					kdf: "scrypt" as const,
+					kdfparams: {
+						dklen: 32,
+						n: 1024,
+						r: 8,
+						p: 1,
+						salt: "00112233445566778899aabbccddeeff",
+					},
+					mac: "invalid-mac-not-hex",
+				},
+			};
+			const exit = await Effect.runPromiseExit(
+				Keystore.decrypt(badKeystore as any, testPassword),
+			);
+			expect(Exit.isFailure(exit)).toBe(true);
+		});
+	});
+
+	describe("KeystoreService", () => {
+		it.effect("provides encrypt through service layer", () =>
+			Effect.gen(function* () {
+				const keystore = yield* Keystore.KeystoreService;
+				const result = yield* keystore.encrypt(testPrivateKey, testPassword, {
+					scryptN: 1024,
+				});
+				expect(result.version).toBe(3);
+				expect(result.crypto.cipher).toBe("aes-128-ctr");
+			}).pipe(Effect.provide(Keystore.KeystoreLive)),
+		);
+
+		it.effect("provides decrypt through service layer", () =>
+			Effect.gen(function* () {
+				const encrypted = yield* Keystore.encrypt(
+					testPrivateKey,
+					testPassword,
+					{
+						scryptN: 1024,
+					},
+				);
+				const keystore = yield* Keystore.KeystoreService;
+				const result = yield* keystore.decrypt(encrypted, testPassword);
+				expect(result).toEqual(testPrivateKey);
+			}).pipe(Effect.provide(Keystore.KeystoreLive)),
+		);
+
+		it.effect("test layer returns mock data", () =>
+			Effect.gen(function* () {
+				const keystore = yield* Keystore.KeystoreService;
+				const result = yield* keystore.encrypt(testPrivateKey, testPassword);
+				expect(result.version).toBe(3);
+				expect(result.id).toBe("test-uuid");
+			}).pipe(Effect.provide(Keystore.KeystoreTest)),
+		);
+	});
+
+	describe("roundtrip", () => {
+		it.effect("encrypts and decrypts with scrypt", () =>
+			Effect.gen(function* () {
+				const encrypted = yield* Keystore.encrypt(
+					testPrivateKey,
+					testPassword,
+					{
+						scryptN: 1024,
+						scryptR: 8,
+						scryptP: 1,
+					},
+				);
+				const decrypted = yield* Keystore.decrypt(encrypted, testPassword);
+				expect(decrypted).toEqual(testPrivateKey);
+			}),
+		);
+
+		it.effect("encrypts and decrypts with pbkdf2", () =>
+			Effect.gen(function* () {
+				const encrypted = yield* Keystore.encrypt(
+					testPrivateKey,
+					testPassword,
+					{
+						kdf: "pbkdf2",
+						pbkdf2C: 1000,
+					},
+				);
+				const decrypted = yield* Keystore.decrypt(encrypted, testPassword);
+				expect(decrypted).toEqual(testPrivateKey);
+			}),
+		);
+	});
+
+	describe("withDecryptedKey", () => {
+		it.effect("zeroes private key after use", () =>
+			Effect.gen(function* () {
+				const encrypted = yield* Keystore.encrypt(
+					testPrivateKey,
+					testPassword,
+					{
+						scryptN: 1024,
+						scryptR: 8,
+						scryptP: 1,
+					},
+				);
+
+				let capturedKey: Uint8Array | null = null;
+
+				yield* Keystore.withDecryptedKey(encrypted, testPassword, (key) =>
+					Effect.sync(() => {
+						capturedKey = key;
+						expect(key).toEqual(testPrivateKey);
+					}),
+				);
+
+				expect(capturedKey).not.toBeNull();
+				expect(
+					(capturedKey as unknown as Uint8Array).every((b: number) => b === 0),
+				).toBe(true);
+			}),
+		);
+
+		it.effect("zeroes private key even on error", () =>
+			Effect.gen(function* () {
+				const encrypted = yield* Keystore.encrypt(
+					testPrivateKey,
+					testPassword,
+					{
+						scryptN: 1024,
+						scryptR: 8,
+						scryptP: 1,
+					},
+				);
+
+				let capturedKey: Uint8Array | null = null;
+
+				const exit = yield* Effect.exit(
+					Keystore.withDecryptedKey(encrypted, testPassword, (key) =>
+						Effect.sync(() => {
+							capturedKey = key;
+							throw new Error("test error");
+						}),
+					),
+				);
+
+				expect(Exit.isFailure(exit)).toBe(true);
+				expect(capturedKey).not.toBeNull();
+				expect(
+					(capturedKey as unknown as Uint8Array).every((b: number) => b === 0),
+				).toBe(true);
+			}),
+		);
+
+		it("fails with wrong password and does not leak key", async () => {
+			const encrypted = await Effect.runPromise(
+				Keystore.encrypt(testPrivateKey, testPassword, {
+					scryptN: 1024,
+					scryptR: 8,
+					scryptP: 1,
+				}),
+			);
+
+			let useCalled = false;
+
+			const exit = await Effect.runPromiseExit(
+				Keystore.withDecryptedKey(encrypted, "wrong-password", (_key) =>
+					Effect.sync(() => {
+						useCalled = true;
+					}),
+				),
+			);
+
+			expect(Exit.isFailure(exit)).toBe(true);
+			expect(useCalled).toBe(false);
+		});
+	});
+});

package/src/crypto/Keystore/KeystoreLive.ts

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview Production implementation of KeystoreService.
+ * @module Keystore/KeystoreLive
+ * @since 0.0.1
+ */
+import * as Layer from "effect/Layer";
+import { decrypt } from "./decrypt.js";
+import { encrypt } from "./encrypt.js";
+import { KeystoreService } from "./KeystoreService.js";
+
+/**
+ * Production layer for KeystoreService using native implementation.
+ *
+ * @description
+ * Provides real keystore operations using scrypt/pbkdf2 key derivation
+ * and AES-128-CTR encryption. Creates Ethereum-compatible keystore files.
+ *
+ * @example
+ * ```typescript
+ * import { KeystoreService, KeystoreLive } from 'voltaire-effect/crypto/Keystore'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const ks = yield* KeystoreService
+ *   return yield* ks.encrypt(privateKey, 'password')
+ * }).pipe(Effect.provide(KeystoreLive))
+ * ```
+ *
+ * @since 0.0.1
+ * @see {@link KeystoreTest} for unit testing
+ */
+export const KeystoreLive = Layer.succeed(KeystoreService, {
+	encrypt,
+	decrypt,
+});

package/src/crypto/Keystore/KeystoreService.ts

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview KeystoreService Effect service definition for keystore encryption.
+ * @module Keystore/KeystoreService
+ * @since 0.0.1
+ */
+
+import type {
+	Keystore,
+	DecryptionError as KeystoreDecryptionError,
+	EncryptionError as KeystoreEncryptionError,
+	InvalidMacError as KeystoreInvalidMacError,
+	InvalidPbkdf2IterationsError as KeystoreInvalidPbkdf2IterationsError,
+	InvalidScryptNError as KeystoreInvalidScryptNError,
+	UnsupportedKdfError as KeystoreUnsupportedKdfError,
+	UnsupportedVersionError as KeystoreUnsupportedVersionError,
+} from "@tevm/voltaire/Keystore";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+
+type EncryptOptions = Parameters<typeof Keystore.encrypt>[2];
+type KeystoreV3 = Awaited<ReturnType<typeof Keystore.encrypt>>;
+type EncryptionError =
+	| KeystoreEncryptionError
+	| KeystoreInvalidScryptNError
+	| KeystoreInvalidPbkdf2IterationsError;
+
+/**
+ * PrivateKey type - 32 byte Uint8Array for cryptographic operations.
+ * @since 0.0.1
+ */
+export type PrivateKeyType = Uint8Array;
+
+/**
+ * Union of all possible decryption errors.
+ *
+ * @description
+ * Represents errors that can occur during keystore decryption:
+ * - DecryptionError: General decryption failure
+ * - InvalidMacError: MAC verification failed (wrong password or corrupted data)
+ * - UnsupportedVersionError: Keystore version not supported
+ * - UnsupportedKdfError: Key derivation function not supported
+ * - InvalidScryptNError: Invalid scrypt parameter from keystore
+ * - InvalidPbkdf2IterationsError: Invalid PBKDF2 iteration count from keystore
+ *
+ * @since 0.0.1
+ */
+export type DecryptError =
+	| KeystoreDecryptionError
+	| KeystoreInvalidMacError
+	| KeystoreUnsupportedVersionError
+	| KeystoreUnsupportedKdfError
+	| KeystoreInvalidScryptNError
+	| KeystoreInvalidPbkdf2IterationsError;
+
+/**
+ * Shape interface for keystore encryption service operations.
+ *
+ * @description
+ * Defines the contract for keystore implementations. All methods return Effect
+ * types for composable, type-safe async/error handling.
+ *
+ * @since 0.0.1
+ */
+export interface KeystoreServiceShape {
+	/**
+	 * Encrypts a private key with a password.
+	 * @param privateKey - The 32-byte private key to encrypt
+	 * @param password - Password for key derivation
+	 * @param options - Optional encryption parameters (kdf, cipher, etc.)
+	 * @returns Effect containing the KeystoreV3 JSON structure
+	 */
+	readonly encrypt: (
+		privateKey: PrivateKeyType,
+		password: string,
+		options?: EncryptOptions,
+	) => Effect.Effect<KeystoreV3, EncryptionError>;
+
+	/**
+	 * Decrypts a keystore with a password.
+	 * @param keystore - The KeystoreV3 JSON structure
+	 * @param password - Password used during encryption
+	 * @returns Effect containing the decrypted private key
+	 */
+	readonly decrypt: (
+		keystore: KeystoreV3,
+		password: string,
+	) => Effect.Effect<PrivateKeyType, DecryptError>;
+}
+
+/**
+ * Ethereum keystore service for Effect-based applications.
+ *
+ * @description
+ * Provides password-based encryption and decryption of private keys using
+ * the Web3 Secret Storage Definition (Keystore V3 format).
+ *
+ * @example
+ * ```typescript
+ * import { KeystoreService, KeystoreLive } from 'voltaire-effect/crypto/Keystore'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const ks = yield* KeystoreService
+ *   const keystore = yield* ks.encrypt(privateKey, 'password')
+ *   const decrypted = yield* ks.decrypt(keystore, 'password')
+ *   return decrypted
+ * }).pipe(Effect.provide(KeystoreLive))
+ * ```
+ *
+ * @since 0.0.1
+ */
+export class KeystoreService extends Context.Tag("KeystoreService")<
+	KeystoreService,
+	KeystoreServiceShape
+>() {}