voltaire-effect 0.2.23

package/src/crypto/ChaCha20Poly1305/ChaCha20Poly1305.test.ts

@@ -0,0 +1,199 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import {
+	ChaCha20Poly1305Live,
+	ChaCha20Poly1305Service,
+	ChaCha20Poly1305Test,
+	decrypt,
+	encrypt,
+	generateKey,
+	generateNonce,
+	InvalidKeyError,
+	InvalidNonceError,
+} from "./index.js";
+
+describe("ChaCha20Poly1305Service", () => {
+	describe("ChaCha20Poly1305Live", () => {
+		it.effect("generates a 32-byte key", () =>
+			Effect.gen(function* () {
+				const service = yield* ChaCha20Poly1305Service;
+				const result = yield* service.generateKey();
+				expect(result).toBeInstanceOf(Uint8Array);
+				expect(result.length).toBe(32);
+			}).pipe(Effect.provide(ChaCha20Poly1305Live)),
+		);
+
+		it.effect("generates a 12-byte nonce", () =>
+			Effect.gen(function* () {
+				const service = yield* ChaCha20Poly1305Service;
+				const result = yield* service.generateNonce();
+				expect(result).toBeInstanceOf(Uint8Array);
+				expect(result.length).toBe(12);
+			}).pipe(Effect.provide(ChaCha20Poly1305Live)),
+		);
+
+		it.effect("encrypts and decrypts data correctly", () =>
+			Effect.gen(function* () {
+				const plaintext = new TextEncoder().encode("Hello, ChaCha20!");
+				const service = yield* ChaCha20Poly1305Service;
+				const key = yield* service.generateKey();
+				const nonce = yield* service.generateNonce();
+				const ciphertext = yield* service.encrypt(plaintext, key, nonce);
+				const decrypted = yield* service.decrypt(ciphertext, key, nonce);
+				expect(ciphertext).toBeInstanceOf(Uint8Array);
+				expect(ciphertext.length).toBeGreaterThan(plaintext.length);
+				expect(decrypted).toEqual(plaintext);
+			}).pipe(Effect.provide(ChaCha20Poly1305Live)),
+		);
+
+		it.effect("encrypts with additional authenticated data", () =>
+			Effect.gen(function* () {
+				const plaintext = new TextEncoder().encode("Secret message");
+				const aad = new TextEncoder().encode("header data");
+				const service = yield* ChaCha20Poly1305Service;
+				const key = yield* service.generateKey();
+				const nonce = yield* service.generateNonce();
+				const ciphertext = yield* service.encrypt(plaintext, key, nonce, aad);
+				const decrypted = yield* service.decrypt(ciphertext, key, nonce, aad);
+				expect(decrypted).toEqual(plaintext);
+			}).pipe(Effect.provide(ChaCha20Poly1305Live)),
+		);
+	});
+
+	describe("ChaCha20Poly1305Test", () => {
+		it.effect("returns deterministic test values", () =>
+			Effect.gen(function* () {
+				const service = yield* ChaCha20Poly1305Service;
+				const key = yield* service.generateKey();
+				const nonce = yield* service.generateNonce();
+				expect(key.length).toBe(32);
+				expect(nonce.length).toBe(12);
+				expect(key.every((b) => b === 0)).toBe(true);
+				expect(nonce.every((b) => b === 0)).toBe(true);
+			}).pipe(Effect.provide(ChaCha20Poly1305Test)),
+		);
+	});
+});
+
+describe("operations", () => {
+	it.effect("generateKey works with service dependency", () =>
+		Effect.gen(function* () {
+			const result = yield* generateKey();
+			expect(result).toBeInstanceOf(Uint8Array);
+			expect(result.length).toBe(32);
+		}).pipe(Effect.provide(ChaCha20Poly1305Live)),
+	);
+
+	it.effect("generateNonce works with service dependency", () =>
+		Effect.gen(function* () {
+			const result = yield* generateNonce();
+			expect(result).toBeInstanceOf(Uint8Array);
+			expect(result.length).toBe(12);
+		}).pipe(Effect.provide(ChaCha20Poly1305Live)),
+	);
+
+	it.effect("encrypt/decrypt roundtrip works", () =>
+		Effect.gen(function* () {
+			const plaintext = new TextEncoder().encode("Test message");
+			const key = yield* generateKey();
+			const nonce = yield* generateNonce();
+			const ciphertext = yield* encrypt(plaintext, key, nonce);
+			const decrypted = yield* decrypt(ciphertext, key, nonce);
+			expect(decrypted).toEqual(plaintext);
+		}).pipe(Effect.provide(ChaCha20Poly1305Live)),
+	);
+
+	it.effect("works with test layer", () =>
+		Effect.gen(function* () {
+			const key = yield* generateKey();
+			const nonce = yield* generateNonce();
+			expect(key.every((b) => b === 0)).toBe(true);
+			expect(nonce.every((b) => b === 0)).toBe(true);
+		}).pipe(Effect.provide(ChaCha20Poly1305Test)),
+	);
+});
+
+describe("input validation", () => {
+	it.effect("rejects invalid key size on encrypt", () =>
+		Effect.gen(function* () {
+			const plaintext = new Uint8Array([1, 2, 3]);
+			const invalidKey = new Uint8Array(16);
+			const nonce = new Uint8Array(12);
+			const exit = yield* Effect.exit(encrypt(plaintext, invalidKey, nonce));
+			expect(Exit.isFailure(exit)).toBe(true);
+			if (Exit.isFailure(exit)) {
+				const error = exit.cause;
+				expect(error._tag).toBe("Fail");
+				if (error._tag === "Fail") {
+					expect(error.error).toBeInstanceOf(InvalidKeyError);
+					expect((error.error as InvalidKeyError).keyLength).toBe(16);
+					expect((error.error as InvalidKeyError).expectedLength).toBe(32);
+				}
+			}
+		}).pipe(Effect.provide(ChaCha20Poly1305Live)),
+	);
+
+	it.effect("rejects invalid nonce size on encrypt", () =>
+		Effect.gen(function* () {
+			const plaintext = new Uint8Array([1, 2, 3]);
+			const key = new Uint8Array(32);
+			const invalidNonce = new Uint8Array(8);
+			const exit = yield* Effect.exit(encrypt(plaintext, key, invalidNonce));
+			expect(Exit.isFailure(exit)).toBe(true);
+			if (Exit.isFailure(exit)) {
+				const error = exit.cause;
+				expect(error._tag).toBe("Fail");
+				if (error._tag === "Fail") {
+					expect(error.error).toBeInstanceOf(InvalidNonceError);
+					expect((error.error as InvalidNonceError).nonceLength).toBe(8);
+					expect((error.error as InvalidNonceError).expectedLength).toBe(12);
+				}
+			}
+		}).pipe(Effect.provide(ChaCha20Poly1305Live)),
+	);
+
+	it.effect("rejects invalid key size on decrypt", () =>
+		Effect.gen(function* () {
+			const ciphertext = new Uint8Array(32);
+			const invalidKey = new Uint8Array(24);
+			const nonce = new Uint8Array(12);
+			const exit = yield* Effect.exit(decrypt(ciphertext, invalidKey, nonce));
+			expect(Exit.isFailure(exit)).toBe(true);
+			if (Exit.isFailure(exit)) {
+				const error = exit.cause;
+				expect(error._tag).toBe("Fail");
+				if (error._tag === "Fail") {
+					expect(error.error).toBeInstanceOf(InvalidKeyError);
+				}
+			}
+		}).pipe(Effect.provide(ChaCha20Poly1305Live)),
+	);
+
+	it.effect("rejects invalid nonce size on decrypt", () =>
+		Effect.gen(function* () {
+			const ciphertext = new Uint8Array(32);
+			const key = new Uint8Array(32);
+			const invalidNonce = new Uint8Array(16);
+			const exit = yield* Effect.exit(decrypt(ciphertext, key, invalidNonce));
+			expect(Exit.isFailure(exit)).toBe(true);
+			if (Exit.isFailure(exit)) {
+				const error = exit.cause;
+				expect(error._tag).toBe("Fail");
+				if (error._tag === "Fail") {
+					expect(error.error).toBeInstanceOf(InvalidNonceError);
+				}
+			}
+		}).pipe(Effect.provide(ChaCha20Poly1305Live)),
+	);
+
+	it.effect("accepts valid key and nonce sizes", () =>
+		Effect.gen(function* () {
+			const plaintext = new Uint8Array([1, 2, 3]);
+			const key = yield* generateKey();
+			const nonce = yield* generateNonce();
+			const ciphertext = yield* encrypt(plaintext, key, nonce);
+			expect(ciphertext.length).toBeGreaterThan(plaintext.length);
+		}).pipe(Effect.provide(ChaCha20Poly1305Live)),
+	);
+});

package/src/crypto/ChaCha20Poly1305/ChaCha20Poly1305Service.ts

@@ -0,0 +1,177 @@
+/**
+ * @fileoverview ChaCha20Poly1305Service Effect service definition for AEAD encryption.
+ * @module ChaCha20Poly1305/ChaCha20Poly1305Service
+ * @since 0.0.1
+ */
+import { ChaCha20Poly1305 } from "@tevm/voltaire";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { InvalidKeyError, InvalidNonceError } from "./errors.js";
+
+const KEY_LENGTH = 32;
+const NONCE_LENGTH = 12;
+
+const validateKey = (key: Uint8Array) =>
+	key.length === KEY_LENGTH
+		? Effect.void
+		: Effect.fail(
+				new InvalidKeyError({
+					message: `Key must be ${KEY_LENGTH} bytes, got ${key.length}`,
+					keyLength: key.length,
+					expectedLength: KEY_LENGTH,
+				}),
+			);
+
+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,
+				}),
+			);
+
+/**
+ * Shape interface for ChaCha20-Poly1305 encryption service operations.
+ *
+ * @description
+ * Defines the contract for ChaCha20-Poly1305 implementations. All methods return
+ * Effect types for composable, type-safe async/error handling.
+ *
+ * @since 0.0.1
+ */
+export interface ChaCha20Poly1305ServiceShape {
+	/**
+	 * Encrypts plaintext using ChaCha20-Poly1305.
+	 * @param plaintext - Data to encrypt
+	 * @param key - 32-byte (256-bit) key
+	 * @param nonce - 12-byte (96-bit) nonce (must be unique per key)
+	 * @param additionalData - Optional additional authenticated data
+	 * @returns Effect containing ciphertext with appended 16-byte auth tag
+	 */
+	readonly encrypt: (
+		plaintext: Uint8Array,
+		key: Uint8Array,
+		nonce: Uint8Array,
+		additionalData?: Uint8Array,
+	) => Effect.Effect<Uint8Array, InvalidKeyError | InvalidNonceError>;
+	/**
+	 * Decrypts ciphertext using ChaCha20-Poly1305.
+	 * @param ciphertext - Encrypted data with appended auth tag
+	 * @param key - Same 32-byte key used for encryption
+	 * @param nonce - Same 12-byte nonce used for encryption
+	 * @param additionalData - Same AAD used for encryption (if any)
+	 * @returns Effect containing decrypted plaintext
+	 */
+	readonly decrypt: (
+		ciphertext: Uint8Array,
+		key: Uint8Array,
+		nonce: Uint8Array,
+		additionalData?: Uint8Array,
+	) => Effect.Effect<Uint8Array, InvalidKeyError | InvalidNonceError>;
+	/**
+	 * Generates a cryptographically random 256-bit key.
+	 * @returns Effect containing 32-byte random key
+	 */
+	readonly generateKey: () => Effect.Effect<Uint8Array>;
+	/**
+	 * Generates a cryptographically random 96-bit nonce.
+	 * @returns Effect containing 12-byte random nonce
+	 */
+	readonly generateNonce: () => Effect.Effect<Uint8Array>;
+}
+
+/**
+ * ChaCha20-Poly1305 AEAD service for Effect-based applications.
+ *
+ * @description
+ * Provides authenticated encryption using ChaCha20 stream cipher with Poly1305 MAC.
+ * Offers excellent performance on systems without AES hardware acceleration.
+ *
+ * @example
+ * ```typescript
+ * import { ChaCha20Poly1305Service, ChaCha20Poly1305Live } from 'voltaire-effect/crypto/ChaCha20Poly1305'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const chacha = yield* ChaCha20Poly1305Service
+ *   const key = yield* chacha.generateKey()
+ *   const nonce = yield* chacha.generateNonce()
+ *   return yield* chacha.encrypt(plaintext, key, nonce)
+ * }).pipe(Effect.provide(ChaCha20Poly1305Live))
+ * ```
+ *
+ * @since 0.0.1
+ */
+export class ChaCha20Poly1305Service extends Context.Tag(
+	"ChaCha20Poly1305Service",
+)<ChaCha20Poly1305Service, ChaCha20Poly1305ServiceShape>() {}
+
+/**
+ * Production layer for ChaCha20Poly1305Service using native implementation.
+ *
+ * @description
+ * Provides real ChaCha20-Poly1305 operations with constant-time implementation.
+ * Uses cryptographically secure random number generation for keys and nonces.
+ *
+ * @example
+ * ```typescript
+ * import { ChaCha20Poly1305Service, ChaCha20Poly1305Live } from 'voltaire-effect/crypto/ChaCha20Poly1305'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const chacha = yield* ChaCha20Poly1305Service
+ *   return yield* chacha.generateKey()
+ * }).pipe(Effect.provide(ChaCha20Poly1305Live))
+ * ```
+ *
+ * @since 0.0.1
+ * @see {@link ChaCha20Poly1305Test} for unit testing
+ */
+export const ChaCha20Poly1305Live = Layer.succeed(ChaCha20Poly1305Service, {
+	encrypt: (plaintext, key, nonce, additionalData) =>
+		Effect.gen(function* () {
+			yield* validateKey(key);
+			yield* validateNonce(nonce);
+			return ChaCha20Poly1305.encrypt(plaintext, key, nonce, additionalData);
+		}),
+	decrypt: (ciphertext, key, nonce, additionalData) =>
+		Effect.gen(function* () {
+			yield* validateKey(key);
+			yield* validateNonce(nonce);
+			return ChaCha20Poly1305.decrypt(ciphertext, key, nonce, additionalData);
+		}),
+	generateKey: () => Effect.sync(() => ChaCha20Poly1305.generateKey()),
+	generateNonce: () => Effect.sync(() => ChaCha20Poly1305.generateNonce()),
+});
+
+/**
+ * Test layer for ChaCha20Poly1305Service 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 { ChaCha20Poly1305Service, ChaCha20Poly1305Test, encrypt } from 'voltaire-effect/crypto/ChaCha20Poly1305'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const testProgram = encrypt(plaintext, key, nonce).pipe(Effect.provide(ChaCha20Poly1305Test))
+ * // Returns Uint8Array(32) filled with zeros
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const ChaCha20Poly1305Test = Layer.succeed(ChaCha20Poly1305Service, {
+	encrypt: (_plaintext, _key, _nonce, _additionalData) =>
+		Effect.sync(() => new Uint8Array(32)),
+	decrypt: (_ciphertext, _key, _nonce, _additionalData) =>
+		Effect.sync(() => new Uint8Array(16)),
+	generateKey: () => Effect.sync(() => new Uint8Array(32)),
+	generateNonce: () => Effect.sync(() => new Uint8Array(12)),
+});

package/src/crypto/ChaCha20Poly1305/errors.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Error types for ChaCha20-Poly1305 encryption operations.
+ * @module ChaCha20Poly1305/errors
+ * @since 0.0.1
+ */
+
+import * as Data from "effect/Data";
+
+/**
+ * Invalid key size for ChaCha20-Poly1305 encryption.
+ * Key must be 32 bytes (256-bit).
+ *
+ * @since 0.0.1
+ */
+export class InvalidKeyError extends Data.TaggedError("InvalidKeyError")<{
+	readonly message: string;
+	readonly keyLength: number;
+	readonly expectedLength: number;
+}> {}
+
+/**
+ * Invalid nonce size for ChaCha20-Poly1305 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 ChaCha20-Poly1305 error types.
+ *
+ * @since 0.0.1
+ */
+export type ChaCha20Poly1305Error = InvalidKeyError | InvalidNonceError;

package/src/crypto/ChaCha20Poly1305/index.ts

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview ChaCha20-Poly1305 authenticated encryption module for Effect.
+ * Provides high-performance AEAD encryption with 256-bit keys.
+ *
+ * @module ChaCha20Poly1305
+ * @since 0.0.1
+ *
+ * @description
+ * ChaCha20-Poly1305 is an AEAD (Authenticated Encryption with Associated Data)
+ * cipher combining the ChaCha20 stream cipher and Poly1305 MAC. Key features:
+ *
+ * - 256-bit keys (32 bytes)
+ * - 96-bit (12-byte) nonces
+ * - 128-bit authentication tag
+ * - Constant-time implementation (resistant to timing attacks)
+ * - No AES hardware required (good for mobile/embedded)
+ *
+ * @example
+ * ```typescript
+ * import { ChaCha20Poly1305Service, ChaCha20Poly1305Live, encrypt, decrypt, generateKey, generateNonce } from 'voltaire-effect/crypto/ChaCha20Poly1305'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const key = yield* generateKey()
+ *   const nonce = yield* generateNonce()
+ *   const plaintext = new TextEncoder().encode('hello')
+ *   const ciphertext = yield* encrypt(plaintext, key, nonce)
+ *   const decrypted = yield* decrypt(ciphertext, key, nonce)
+ *   return decrypted
+ * }).pipe(Effect.provide(ChaCha20Poly1305Live))
+ * ```
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc8439 | RFC 8439}
+ */
+export {
+	ChaCha20Poly1305Live,
+	ChaCha20Poly1305Service,
+	type ChaCha20Poly1305ServiceShape,
+	ChaCha20Poly1305Test,
+} from "./ChaCha20Poly1305Service.js";
+export {
+	type ChaCha20Poly1305Error,
+	InvalidKeyError,
+	InvalidNonceError,
+} from "./errors.js";
+export { decrypt, encrypt, generateKey, generateNonce } from "./operations.js";

package/src/crypto/ChaCha20Poly1305/operations.ts

@@ -0,0 +1,161 @@
+/**
+ * @fileoverview ChaCha20-Poly1305 encryption operations for Effect.
+ * @module ChaCha20Poly1305/operations
+ * @since 0.0.1
+ */
+import * as Effect from "effect/Effect";
+import { ChaCha20Poly1305Service } from "./ChaCha20Poly1305Service.js";
+import type { InvalidKeyError, InvalidNonceError } from "./errors.js";
+
+/**
+ * Encrypts plaintext using ChaCha20-Poly1305.
+ *
+ * @description
+ * Encrypts data using the ChaCha20 stream cipher and authenticates with Poly1305 MAC.
+ * The ciphertext includes a 16-byte authentication tag appended at the end.
+ *
+ * @param plaintext - Data to encrypt (any length)
+ * @param key - 32-byte (256-bit) symmetric key
+ * @param nonce - 12-byte (96-bit) nonce - MUST be unique per key
+ * @param additionalData - Optional additional authenticated data (authenticated but not encrypted)
+ * @returns Effect containing ciphertext (plaintext.length + 16 bytes for auth tag), requiring ChaCha20Poly1305Service
+ *
+ * @example
+ * ```typescript
+ * import { encrypt, generateKey, generateNonce, ChaCha20Poly1305Live } from 'voltaire-effect/crypto/ChaCha20Poly1305'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const key = yield* generateKey()
+ *   const nonce = yield* generateNonce()
+ *   return yield* encrypt(new Uint8Array([1, 2, 3]), key, nonce)
+ * }).pipe(Effect.provide(ChaCha20Poly1305Live))
+ * ```
+ *
+ * @throws Never fails if inputs are valid
+ * @see {@link decrypt} to decrypt the ciphertext
+ * @since 0.0.1
+ */
+export const encrypt = (
+	plaintext: Uint8Array,
+	key: Uint8Array,
+	nonce: Uint8Array,
+	additionalData?: Uint8Array,
+): Effect.Effect<
+	Uint8Array,
+	InvalidKeyError | InvalidNonceError,
+	ChaCha20Poly1305Service
+> =>
+	Effect.gen(function* () {
+		const service = yield* ChaCha20Poly1305Service;
+		return yield* service.encrypt(plaintext, key, nonce, additionalData);
+	});
+
+/**
+ * Decrypts ciphertext using ChaCha20-Poly1305.
+ *
+ * @description
+ * Decrypts and authenticates ChaCha20-Poly1305 ciphertext. Verifies the 128-bit
+ * Poly1305 authentication tag appended to the ciphertext.
+ *
+ * @param ciphertext - Encrypted data with 16-byte auth tag appended
+ * @param key - Same 32-byte key used for encryption
+ * @param nonce - Same 12-byte nonce used for encryption
+ * @param additionalData - Same additional authenticated data used for encryption (if any)
+ * @returns Effect containing decrypted plaintext, requiring ChaCha20Poly1305Service
+ *
+ * @example
+ * ```typescript
+ * import { decrypt, encrypt, generateKey, generateNonce, ChaCha20Poly1305Live } from 'voltaire-effect/crypto/ChaCha20Poly1305'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const key = yield* generateKey()
+ *   const nonce = yield* generateNonce()
+ *   const ciphertext = yield* encrypt(plaintext, key, nonce)
+ *   return yield* decrypt(ciphertext, key, nonce)
+ * }).pipe(Effect.provide(ChaCha20Poly1305Live))
+ * ```
+ *
+ * @throws Error if authentication fails (data tampered or wrong key/nonce)
+ * @see {@link encrypt} to encrypt data
+ * @since 0.0.1
+ */
+export const decrypt = (
+	ciphertext: Uint8Array,
+	key: Uint8Array,
+	nonce: Uint8Array,
+	additionalData?: Uint8Array,
+): Effect.Effect<
+	Uint8Array,
+	InvalidKeyError | InvalidNonceError,
+	ChaCha20Poly1305Service
+> =>
+	Effect.gen(function* () {
+		const service = yield* ChaCha20Poly1305Service;
+		return yield* service.decrypt(ciphertext, key, nonce, additionalData);
+	});
+
+/**
+ * Generates a cryptographically random 256-bit key.
+ *
+ * @description
+ * Uses cryptographically secure random number generation to create
+ * a 32-byte key suitable for ChaCha20-Poly1305 encryption.
+ *
+ * @returns Effect containing 32-byte random key, requiring ChaCha20Poly1305Service
+ *
+ * @example
+ * ```typescript
+ * import { generateKey, ChaCha20Poly1305Live } from 'voltaire-effect/crypto/ChaCha20Poly1305'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = generateKey().pipe(Effect.provide(ChaCha20Poly1305Live))
+ * // Returns: Uint8Array(32)
+ * ```
+ *
+ * @throws Never fails
+ * @see {@link generateNonce} to generate a nonce
+ * @since 0.0.1
+ */
+export const generateKey = (): Effect.Effect<
+	Uint8Array,
+	never,
+	ChaCha20Poly1305Service
+> =>
+	Effect.gen(function* () {
+		const service = yield* ChaCha20Poly1305Service;
+		return yield* service.generateKey();
+	});
+
+/**
+ * Generates a cryptographically random 96-bit nonce.
+ *
+ * @description
+ * Generates a 12-byte nonce suitable for ChaCha20-Poly1305. Each nonce MUST be
+ * unique for a given key - reusing a nonce completely breaks the security.
+ *
+ * @returns Effect containing 12-byte random nonce, requiring ChaCha20Poly1305Service
+ *
+ * @example
+ * ```typescript
+ * import { generateNonce, ChaCha20Poly1305Live } from 'voltaire-effect/crypto/ChaCha20Poly1305'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = generateNonce().pipe(Effect.provide(ChaCha20Poly1305Live))
+ * // Returns: Uint8Array(12)
+ * ```
+ *
+ * @throws Never fails
+ * @see {@link generateKey} to generate a key
+ * @since 0.0.1
+ */
+export const generateNonce = (): Effect.Effect<
+	Uint8Array,
+	never,
+	ChaCha20Poly1305Service
+> =>
+	Effect.gen(function* () {
+		const service = yield* ChaCha20Poly1305Service;
+		return yield* service.generateNonce();
+	});

package/src/crypto/CryptoLive.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import { CryptoTest } from "./CryptoTest.js";
+import { KeccakService } from "./Keccak256/KeccakService.js";
+import { Secp256k1Service } from "./Secp256k1/Secp256k1Service.js";
+
+describe("CryptoTest", () => {
+	it.effect("provides KeccakService", () =>
+		Effect.gen(function* () {
+			const svc = yield* KeccakService;
+			expect(typeof svc.hash === "function").toBe(true);
+		}).pipe(Effect.provide(CryptoTest)),
+	);
+
+	it.effect("provides Secp256k1Service", () =>
+		Effect.gen(function* () {
+			const svc = yield* Secp256k1Service;
+			expect(
+				typeof svc.sign === "function" && typeof svc.recover === "function",
+			).toBe(true);
+		}).pipe(Effect.provide(CryptoTest)),
+	);
+
+	it.effect("KeccakService.hash returns 32 bytes", () =>
+		Effect.gen(function* () {
+			const svc = yield* KeccakService;
+			const result = yield* svc.hash(new Uint8Array([1, 2, 3]));
+			expect(result).toBeInstanceOf(Uint8Array);
+			expect(result.length).toBe(32);
+		}).pipe(Effect.provide(CryptoTest)),
+	);
+
+	it.effect("composes Keccak and Secp256k1 in single program", () =>
+		Effect.gen(function* () {
+			const keccak = yield* KeccakService;
+			const msgHash = yield* keccak.hash(
+				new Uint8Array([0xde, 0xad, 0xbe, 0xef]),
+			);
+			expect(msgHash.length).toBe(32);
+		}).pipe(Effect.provide(CryptoTest)),
+	);
+});