feat(entropy): add secure entropy generator with injectable provider

Author: xt0x

src/DESIGN.md

@@ -6,6 +6,8 @@
 - `src/bip39/` contains core BIP39 conversion functions.
 - `src/errors/` defines standard error codes and priority ordering.
 - `src/crypto/` wraps SHA-256 and PBKDF2-HMAC-SHA512 using standard libraries.
+- `src/normalize/` provides a compatibility input adapter (trim, NFKD, lowercase).
 - `src/parser/` implements strict mnemonic parsing contracts.
+- `src/entropy/` generates entropy via secure randomness with injectable providers for tests.
 - `src/types/` defines shared DTOs such as `ValidationResult`.
 - `src/index.ts` re-exports the public surface for these foundational modules.

src/entropy/DESIGN.md

@@ -0,0 +1,5 @@
+# entropy design
+
+- Purpose: Provide secure entropy generation with injectable providers for testing.
+- Scope: Validation of allowed byte lengths and delegation to a randomness provider.
+- Output: JavaScript is emitted to `dist/`; keep this directory TypeScript-only.

src/entropy/entropyGenerator.ts

@@ -0,0 +1,39 @@
+import { randomBytes } from "node:crypto";
+
+import { ENTROPY_BYTES } from "../constants/bip39.js";
+
+export class InvalidEntropyLengthError extends Error {
+	constructor(message = "Invalid entropy length") {
+		super(message);
+		this.name = "InvalidEntropyLengthError";
+	}
+}
+
+export type EntropyGenerator = {
+	generate: (bytes: number) => Uint8Array;
+};
+
+const isValidEntropyLength = (bytes: number): boolean =>
+	(ENTROPY_BYTES as readonly number[]).includes(bytes);
+
+export const createEntropyGenerator = (
+	provider: (bytes: number) => Uint8Array,
+): EntropyGenerator => ({
+	generate: (bytes: number) => {
+		if (!isValidEntropyLength(bytes)) {
+			throw new InvalidEntropyLengthError(
+				`Entropy must be ${ENTROPY_BYTES.join("/")} bytes`,
+			);
+		}
+		const output = provider(bytes);
+		if (!(output instanceof Uint8Array) || output.length !== bytes) {
+			throw new Error("Entropy provider returned invalid output");
+		}
+		return output;
+	},
+});
+
+export const generateEntropy = (bytes: number): Uint8Array =>
+	createEntropyGenerator(
+		(length) => new Uint8Array(randomBytes(length)),
+	).generate(bytes);

src/index.ts

@@ -5,6 +5,8 @@ export * from "./bip39/validateMnemonic.js";
 export * from "./bits/bitOps.js";
 export * from "./constants/bip39.js";
 export * from "./crypto/crypto.js";
+export * from "./entropy/entropyGenerator.js";
 export * from "./errors/errorCodes.js";
+export * from "./normalize/normalizeMnemonicInput.js";
 export * from "./parser/strictMnemonic.js";
 export * from "./types/validationResult.js";

src/normalize/DESIGN.md

@@ -0,0 +1,5 @@
+# normalize design
+
+- Purpose: Provide a compatibility adapter for mnemonic input.
+- Scope: Trim, whitespace normalization, NFKD normalization, and lowercase for English profile.
+- Output: JavaScript is emitted to `dist/`; keep this directory TypeScript-only.

src/normalize/normalizeMnemonicInput.ts

@@ -0,0 +1,14 @@
+export const normalizeMnemonicInput = (input: string): string => {
+	if (typeof input !== "string") {
+		throw new TypeError("Mnemonic input must be a string");
+	}
+
+	const replaced = input.replace(/[\t\n\r]/gu, " ");
+	const trimmed = replaced.trim();
+	if (trimmed.length === 0) {
+		return "";
+	}
+	const collapsed = trimmed.replace(/\s+/gu, " ");
+	const normalized = collapsed.normalize("NFKD");
+	return normalized.toLowerCase();
+};

test/entropy-generator.spec.ts

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+	createEntropyGenerator,
+	type EntropyGenerator,
+	generateEntropy,
+	InvalidEntropyLengthError,
+} from "../src/entropy/entropyGenerator.ts";
+
+const allowed = [16, 20, 24, 28, 32];
+
+test("generateEntropy returns allowed lengths", () => {
+	for (const length of allowed) {
+		const entropy = generateEntropy(length);
+		assert.equal(entropy.length, length);
+	}
+});
+
+test("generateEntropy rejects invalid lengths", () => {
+	assert.throws(() => generateEntropy(15), InvalidEntropyLengthError);
+	assert.throws(() => generateEntropy(33), InvalidEntropyLengthError);
+});
+
+test("EntropyGenerator allows deterministic output in tests", () => {
+	const fixed = Uint8Array.from({ length: 16 }, (_, i) => i);
+	const generator = createEntropyGenerator(() => fixed);
+	const entropy = generator.generate(16);
+	assert.equal(entropy.length, 16);
+	assert.deepEqual(Array.from(entropy), Array.from(fixed));
+});
+
+// Validate the interface shape used by callers
+const _typecheck: EntropyGenerator = {
+	generate: (bytes) => new Uint8Array(bytes),
+};
+void _typecheck;

test/normalize-mnemonic.spec.ts

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { normalizeMnemonicInput } from "../src/normalize/normalizeMnemonicInput.ts";
+
+test("normalizeMnemonicInput trims and collapses whitespace", () => {
+	const input = "  Abandon\tabandon\nABOUT  ";
+	assert.equal(normalizeMnemonicInput(input), "abandon abandon about");
+});
+
+test("normalizeMnemonicInput replaces CR and multiple spaces", () => {
+	const input = "abandon\rabandon   about";
+	assert.equal(normalizeMnemonicInput(input), "abandon abandon about");
+});
+
+test("normalizeMnemonicInput applies NFKD and lowercases", () => {
+	const input = "\u00c1"; // Á
+	assert.equal(normalizeMnemonicInput(input), "a\u0301");
+});
+
+test("normalizeMnemonicInput rejects non-string input", () => {
+	assert.throws(() => normalizeMnemonicInput(123 as unknown as string));
+});