gabriel / muse public
test_core_bip39.py python
529 lines 22.0 KB
Raw
sha256:d11a87833d5fad6059b7662844bf5448a8911a17cce7a51811f71ad394f248eb bump to v0.2.0rc13 Human patch 6 days ago
1 """Tests for muse.core.bip39 — BIP39 mnemonic generation, validation, and seed derivation.
2
3 Test categories
4 ---------------
5 - Unit: individual function contracts, argument validation, return types
6 - Integration: round-trip (generate → validate → seed), known-vector verification
7 - Stress: entropy quality across 1 000 independent mnemonics
8 - Security: no module-level CSPRNG, NFKD normalization, passphrase isolation
9 - Data integrity: official BIP39 test vectors from the Trezor reference suite
10
11 Official test vectors
12 ---------------------
13 BIP39 specifies a set of test vectors (mnemonic + passphrase → seed). The
14 vectors used here come from the Trezor python-mnemonic test suite, which is
15 the same library we delegate to. Each vector is independently verifiable at
16 https://github.com/trezor/python-mnemonic/blob/master/vectors.json
17
18 The vectors include the standard "TREZOR" passphrase as well as the empty
19 passphrase case, covering both branches of the PBKDF2 derivation.
20 """
21
22 from __future__ import annotations
23
24 import unicodedata
25 from typing import NamedTuple
26
27 import pytest
28
29 from muse.core.bip39 import (
30 FUNCTIONAL_LANGUAGES,
31 STRENGTH_HIGH,
32 STRENGTH_LOW,
33 STRENGTH_MEDIUM,
34 STRENGTH_PARANOID,
35 STRENGTH_STANDARD,
36 SUPPORTED_LANGUAGES,
37 Bip39Error,
38 detect_language,
39 generate_mnemonic,
40 mnemonic_to_seed,
41 validate_mnemonic,
42 word_count,
43 )
44
45
46 # ---------------------------------------------------------------------------
47 # Official BIP39 test vectors (subset from Trezor reference)
48 # ---------------------------------------------------------------------------
49 # Format: (mnemonic, passphrase, expected_seed_hex)
50 # Source: https://github.com/trezor/python-mnemonic/blob/master/vectors.json
51 _BIP39_VECTORS = [
52 # ── Official Trezor BIP39 test vectors ───────────────────────────────
53 # Source: https://github.com/trezor/python-mnemonic/blob/master/vectors.json
54 # All seeds verified against the live mnemonic library and cross-checked
55 # against the BIP39 specification.
56 (
57 "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
58 "TREZOR",
59 "c55257c360c07c72029aebc1b53c05ed0362ada38ead3e3e9efa3708e53495531f09a6987599d18264c1e1c92f2cf141630c7a3c4ab7c81b2f001698e7463b04",
60 ),
61 (
62 "legal winner thank year wave sausage worth useful legal winner thank yellow",
63 "TREZOR",
64 "2e8905819b8723fe2c1d161860e5ee1830318dbf49a83bd451cfb8440c28bd6fa457fe1296106559a3c80937a1c1069be3a3a5bd381ee6260e8d9739fce1f607",
65 ),
66 (
67 "letter advice cage absurd amount doctor acoustic avoid letter advice cage above",
68 "TREZOR",
69 "d71de856f81a8acc65e6fc851a38d4d7ec216fd0796d0a6827a3ad6ed5511a30fa280f12eb2e47ed2ac03b5c462a0358d18d69fe4f985ec81778c1b370b652a8",
70 ),
71 (
72 "zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong",
73 "TREZOR",
74 "ac27495480225222079d7be181583751e86f571027b0497b5b5d11218e0a8a13332572917f0f8e5a589620c6f15b11c61dee327651a14c34e18231052e48c069",
75 ),
76 # 24-word (256-bit entropy)
77 (
78 "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon "
79 "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon art",
80 "TREZOR",
81 "bda85446c68413707090a52022edd26a1c9462295029f2e60cd7c4f2bbd3097170af7a4d73245cafa9c3cca8d561a7c3de6f5d4a10be8ed2a5e608d68f92fcc8",
82 ),
83 # Empty passphrase
84 (
85 "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
86 "",
87 "5eb00bbddcf069084889a8ab9155568165f5c453ccb85e70811aaed6f6da5fc19a5ac40b389cd370d086206dec8aa6c43daea6690f20ad3d8d48b2d2ce9e38e4",
88 ),
89 ]
90
91
92 class _Vector(NamedTuple):
93 mnemonic: str
94 passphrase: str
95 expected_hex: str
96
97
98 _VECTORS = [_Vector(*v) for v in _BIP39_VECTORS]
99
100
101 # ---------------------------------------------------------------------------
102 # Unit — generate_mnemonic
103 # ---------------------------------------------------------------------------
104
105
106 class TestGenerateMnemonic:
107 # ── word counts for all five strengths ───────────────────────────────
108 @pytest.mark.parametrize("strength,expected_words", [
109 (STRENGTH_STANDARD, 12),
110 (STRENGTH_LOW, 15),
111 (STRENGTH_MEDIUM, 18),
112 (STRENGTH_HIGH, 21),
113 (STRENGTH_PARANOID, 24),
114 ])
115 def test_word_count_for_strength(self, strength: int, expected_words: int) -> None:
116 words = generate_mnemonic(strength=strength) # type: ignore[arg-type]
117 assert len(words.split()) == expected_words
118
119 def test_default_returns_12_words(self) -> None:
120 assert len(generate_mnemonic().split()) == 12
121
122 def test_returns_string(self) -> None:
123 assert isinstance(generate_mnemonic(), str)
124
125 def test_english_all_lowercase(self) -> None:
126 words = generate_mnemonic()
127 assert words == words.lower()
128
129 def test_no_leading_trailing_whitespace(self) -> None:
130 words = generate_mnemonic()
131 assert words == words.strip()
132
133 def test_english_single_space_separator(self) -> None:
134 assert " " not in generate_mnemonic()
135
136 def test_generated_passes_validation(self) -> None:
137 assert validate_mnemonic(generate_mnemonic()) is True
138
139 def test_all_strengths_pass_validation(self) -> None:
140 for strength in (STRENGTH_STANDARD, STRENGTH_LOW, STRENGTH_MEDIUM,
141 STRENGTH_HIGH, STRENGTH_PARANOID):
142 words = generate_mnemonic(strength=strength) # type: ignore[arg-type]
143 assert validate_mnemonic(words), f"Failed for strength={strength}"
144
145 # ── language coverage (functional languages only) ────────────────────
146 @pytest.mark.parametrize("language", FUNCTIONAL_LANGUAGES)
147 def test_functional_languages_generate_and_validate(self, language: str) -> None:
148 words = generate_mnemonic(language=language)
149 assert validate_mnemonic(words), f"Validation failed for language={language}"
150
151 @pytest.mark.parametrize("language", FUNCTIONAL_LANGUAGES)
152 def test_functional_languages_detect_correctly(self, language: str) -> None:
153 words = generate_mnemonic(language=language)
154 assert detect_language(words) == language
155
156 def test_japanese_uses_ideographic_separator(self) -> None:
157 words = generate_mnemonic(language="japanese")
158 # Japanese BIP39 uses U+3000 (ideographic space) as separator
159 assert "\u3000" in words
160
161 def test_invalid_language_raises(self) -> None:
162 with pytest.raises(Bip39Error, match="Unsupported BIP39 language"):
163 generate_mnemonic(language="klingon")
164
165 # ── invalid strengths ────────────────────────────────────────────────
166 def test_invalid_strength_raises(self) -> None:
167 with pytest.raises(Bip39Error, match="Unsupported BIP39 strength"):
168 generate_mnemonic(strength=64) # type: ignore[arg-type]
169
170 def test_invalid_strength_100_raises(self) -> None:
171 with pytest.raises(Bip39Error):
172 generate_mnemonic(strength=100) # type: ignore[arg-type]
173
174
175 # ---------------------------------------------------------------------------
176 # Unit — validate_mnemonic
177 # ---------------------------------------------------------------------------
178
179
180 class TestValidateMnemonic:
181 def test_known_valid_12_word(self) -> None:
182 assert validate_mnemonic("abandon abandon abandon abandon abandon abandon "
183 "abandon abandon abandon abandon abandon about") is True
184
185 def test_known_valid_24_word(self) -> None:
186 assert validate_mnemonic(
187 "abandon abandon abandon abandon abandon abandon abandon abandon "
188 "abandon abandon abandon abandon abandon abandon abandon abandon "
189 "abandon abandon abandon abandon abandon abandon abandon art"
190 ) is True
191
192 def test_bad_checksum_returns_false(self) -> None:
193 # 12 "abandon"s has a bad checksum (last word should be "about")
194 assert validate_mnemonic("abandon " * 12) is False
195
196 def test_unknown_word_returns_false(self) -> None:
197 assert validate_mnemonic("notaword " * 11 + "about") is False
198
199 def test_empty_string_returns_false(self) -> None:
200 assert validate_mnemonic("") is False
201
202 def test_too_few_words_returns_false(self) -> None:
203 assert validate_mnemonic("abandon") is False
204
205 def test_strips_and_normalizes_whitespace(self) -> None:
206 # extra spaces should be tolerated
207 spaced = " abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about "
208 assert validate_mnemonic(spaced) is True
209
210 def test_returns_bool_not_truthy(self) -> None:
211 result = validate_mnemonic("abandon abandon abandon abandon abandon abandon "
212 "abandon abandon abandon abandon abandon about")
213 assert result is True
214 bad = validate_mnemonic("not a valid mnemonic phrase at all here")
215 assert bad is False
216
217
218 # ---------------------------------------------------------------------------
219 # Unit — mnemonic_to_seed
220 # ---------------------------------------------------------------------------
221
222
223 class TestMnemonicToSeed:
224 def test_returns_64_bytes(self) -> None:
225 seed = mnemonic_to_seed("abandon abandon abandon abandon abandon abandon "
226 "abandon abandon abandon abandon abandon about")
227 assert isinstance(seed, (bytes, bytearray))
228 assert len(seed) == 64
229
230 def test_empty_passphrase_default(self) -> None:
231 words = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
232 seed_explicit = mnemonic_to_seed(words, passphrase="")
233 seed_default = mnemonic_to_seed(words)
234 assert seed_explicit == seed_default
235
236 def test_different_passphrase_different_seed(self) -> None:
237 words = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
238 s1 = mnemonic_to_seed(words, passphrase="")
239 s2 = mnemonic_to_seed(words, passphrase="horse")
240 assert s1 != s2
241
242 def test_deterministic(self) -> None:
243 words = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
244 assert mnemonic_to_seed(words) == mnemonic_to_seed(words)
245
246 def test_nfkd_normalization_passphrase(self) -> None:
247 """Both composed and decomposed unicode should produce the same seed."""
248 words = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
249 composed = "caf\u00e9" # é as single code point (NFC)
250 decomposed = "cafe\u0301" # é as e + combining accent (NFD)
251 # After NFKD both normalise to the same sequence
252 assert (
253 unicodedata.normalize("NFKD", composed)
254 == unicodedata.normalize("NFKD", decomposed)
255 )
256 seed_composed = mnemonic_to_seed(words, passphrase=composed)
257 seed_decomposed = mnemonic_to_seed(words, passphrase=decomposed)
258 assert seed_composed == seed_decomposed
259
260 def test_nfkd_normalization_mnemonic(self) -> None:
261 """Mnemonic whitespace normalisation should be transparent."""
262 words_normal = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
263 words_extra_space = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
264 seed_normal = mnemonic_to_seed(words_normal)
265 seed_extra = mnemonic_to_seed(words_extra_space)
266 assert seed_normal == seed_extra
267
268
269 # ---------------------------------------------------------------------------
270 # Unit — word_count
271 # ---------------------------------------------------------------------------
272
273
274 class TestWordCount:
275 @pytest.mark.parametrize("strength,expected", [
276 (STRENGTH_STANDARD, 12),
277 (STRENGTH_LOW, 15),
278 (STRENGTH_MEDIUM, 18),
279 (STRENGTH_HIGH, 21),
280 (STRENGTH_PARANOID, 24),
281 ])
282 def test_all_strengths(self, strength: int, expected: int) -> None:
283 assert word_count(strength) == expected # type: ignore[arg-type]
284
285 def test_default(self) -> None:
286 assert word_count() == 12
287
288 def test_invalid_raises(self) -> None:
289 with pytest.raises(Bip39Error):
290 word_count(64) # type: ignore[arg-type]
291
292
293 class TestDetectLanguage:
294 @pytest.mark.parametrize("language", FUNCTIONAL_LANGUAGES)
295 def test_detect_all_languages(self, language: str) -> None:
296 words = generate_mnemonic(language=language)
297 assert detect_language(words) == language
298
299 def test_unknown_words_raises(self) -> None:
300 with pytest.raises(Bip39Error):
301 detect_language("zzz qqq xxx invalid nonsense words here blah")
302
303 def test_empty_raises(self) -> None:
304 with pytest.raises(Bip39Error):
305 detect_language("")
306
307
308 class TestSupportedLanguages:
309 def test_is_list_of_strings(self) -> None:
310 assert isinstance(SUPPORTED_LANGUAGES, list)
311 assert all(isinstance(l, str) for l in SUPPORTED_LANGUAGES)
312
313 def test_includes_english(self) -> None:
314 assert "english" in SUPPORTED_LANGUAGES
315
316 def test_includes_japanese(self) -> None:
317 assert "japanese" in SUPPORTED_LANGUAGES
318
319 def test_includes_korean(self) -> None:
320 assert "korean" in SUPPORTED_LANGUAGES
321
322 def test_at_least_10_languages(self) -> None:
323 assert len(SUPPORTED_LANGUAGES) >= 10
324
325
326 # ---------------------------------------------------------------------------
327 # Data integrity — official BIP39 test vectors
328 # ---------------------------------------------------------------------------
329
330
331 class TestOfficialVectors:
332 """Verify mnemonic_to_seed against official Trezor BIP39 test vectors.
333
334 These vectors are independently verifiable and cover both 12-word (128-bit)
335 and 24-word (256-bit) entropy, with and without passphrase.
336 """
337
338 @pytest.mark.parametrize("vector", _VECTORS, ids=[v.mnemonic[:20] for v in _VECTORS])
339 def test_seed_matches_vector(self, vector: _Vector) -> None:
340 seed = mnemonic_to_seed(vector.mnemonic, passphrase=vector.passphrase)
341 # Strip whitespace from hex — test vectors may have formatting
342 expected = bytes.fromhex(vector.expected_hex.replace(" ", "").replace("\n", ""))
343 assert seed == expected, (
344 f"Seed mismatch for mnemonic '{vector.mnemonic[:30]}...' "
345 f"with passphrase '{vector.passphrase}'"
346 )
347
348 def test_all_vectors_produce_64_bytes(self) -> None:
349 for v in _VECTORS:
350 seed = mnemonic_to_seed(v.mnemonic, passphrase=v.passphrase)
351 assert len(seed) == 64, f"Expected 64 bytes, got {len(seed)}"
352
353
354 # ---------------------------------------------------------------------------
355 # Integration — round-trip
356 # ---------------------------------------------------------------------------
357
358
359 class TestRoundTrip:
360 def test_generate_validate_seed_pipeline(self) -> None:
361 mnemonic = generate_mnemonic()
362 assert validate_mnemonic(mnemonic)
363 seed = mnemonic_to_seed(mnemonic)
364 assert len(seed) == 64
365 assert isinstance(seed, (bytes, bytearray))
366
367 def test_paranoid_generate_validate_seed_pipeline(self) -> None:
368 mnemonic = generate_mnemonic(strength=STRENGTH_PARANOID)
369 assert validate_mnemonic(mnemonic)
370 seed = mnemonic_to_seed(mnemonic)
371 assert len(seed) == 64
372
373 def test_seed_is_deterministic_across_calls(self) -> None:
374 mnemonic = generate_mnemonic()
375 seed1 = mnemonic_to_seed(mnemonic)
376 seed2 = mnemonic_to_seed(mnemonic)
377 assert seed1 == seed2
378
379
380 # ---------------------------------------------------------------------------
381 # Stress — entropy quality
382 # ---------------------------------------------------------------------------
383
384
385 class TestEntropyQuality:
386 """Verify that generated mnemonics are not duplicated across a large sample.
387
388 A collision in 1 000 independent 128-bit entropy samples is so unlikely
389 (probability ≈ 1/(2^128)) that any collision indicates a CSPRNG failure.
390 """
391
392 def test_no_duplicates_in_1000_standard_mnemonics(self) -> None:
393 seen: set[str] = set()
394 for _ in range(1_000):
395 m = generate_mnemonic(strength=STRENGTH_STANDARD)
396 assert m not in seen, "Duplicate mnemonic generated — CSPRNG failure"
397 seen.add(m)
398
399 def test_no_duplicates_in_100_paranoid_mnemonics(self) -> None:
400 seen: set[str] = set()
401 for _ in range(100):
402 m = generate_mnemonic(strength=STRENGTH_PARANOID)
403 assert m not in seen, "Duplicate paranoid mnemonic generated — CSPRNG failure"
404 seen.add(m)
405
406 def test_seeds_differ_across_distinct_mnemonics(self) -> None:
407 seeds: set[bytes] = set()
408 for _ in range(100):
409 m = generate_mnemonic()
410 seeds.add(bytes(mnemonic_to_seed(m)))
411 assert len(seeds) == 100, "Seed collision detected — derivation is not injective"
412
413
414 # ---------------------------------------------------------------------------
415 # Security
416 # ---------------------------------------------------------------------------
417
418
419 class TestSecurity:
420 def test_passphrase_isolation(self) -> None:
421 """Every distinct passphrase should yield a completely different seed."""
422 words = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
423 passphrases = ["", "a", "ab", "abc", "TREZOR", "hunter2", " ", "\t", "日本語"]
424 seeds = [bytes(mnemonic_to_seed(words, p)) for p in passphrases]
425 assert len(set(seeds)) == len(passphrases), "Passphrase collision — derivation is broken"
426
427 def test_single_word_change_completely_changes_seed(self) -> None:
428 """Changing one word should produce a completely different, unrelated seed."""
429 base = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
430 alt = "zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong"
431 seed_base = mnemonic_to_seed(base)
432 seed_alt = mnemonic_to_seed(alt)
433 # Seeds should differ in most bytes — definitely not equal
434 assert seed_base != seed_alt
435 # At least 50% of bytes should differ (approximate avalanche)
436 diff = sum(a != b for a, b in zip(seed_base, seed_alt))
437 assert diff >= 20, f"Only {diff}/64 bytes differ — suspiciously low avalanche"
438
439 def test_mnemonic_to_seed_does_not_raise_on_invalid_mnemonic(self) -> None:
440 """BIP39 spec: seed derivation succeeds even for invalid mnemonics.
441
442 Validation is separate. mnemonic_to_seed should not raise on invalid
443 input — it just produces a seed with no well-defined derivation. The
444 caller is responsible for calling validate_mnemonic first.
445 """
446 # Should not raise
447 seed = mnemonic_to_seed("these are not bip39 words at all")
448 assert len(seed) == 64
449
450
451 # ---------------------------------------------------------------------------
452 # Performance
453 # ---------------------------------------------------------------------------
454
455
456 class TestPerformance:
457 """Timing budgets for BIP39 operations.
458
459 These tests enforce upper bounds on latency. mnemonic_to_seed is
460 intentionally the slowest operation (PBKDF2 with 2 048 iterations is
461 designed to be slow for brute-force resistance); all other operations
462 must complete in well under 100 ms.
463 """
464
465 def test_generate_mnemonic_under_100ms(self) -> None:
466 import time
467 start = time.perf_counter()
468 for _ in range(10):
469 generate_mnemonic()
470 elapsed = (time.perf_counter() - start) / 10
471 assert elapsed < 0.1, f"generate_mnemonic averaged {elapsed*1000:.1f}ms — too slow"
472
473 def test_validate_mnemonic_under_10ms(self) -> None:
474 import time
475 words = generate_mnemonic()
476 start = time.perf_counter()
477 for _ in range(20):
478 validate_mnemonic(words)
479 elapsed = (time.perf_counter() - start) / 20
480 assert elapsed < 0.01, f"validate_mnemonic averaged {elapsed*1000:.1f}ms — too slow"
481
482 def test_mnemonic_to_seed_under_500ms(self) -> None:
483 """PBKDF2 budget: intentionally slow by spec, but must complete < 500ms."""
484 import time
485 words = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
486 start = time.perf_counter()
487 mnemonic_to_seed(words, "TREZOR")
488 elapsed = time.perf_counter() - start
489 assert elapsed < 0.5, f"mnemonic_to_seed took {elapsed*1000:.1f}ms — exceeds 500ms budget"
490
491 def test_detect_language_under_50ms(self) -> None:
492 import time
493 words = generate_mnemonic()
494 start = time.perf_counter()
495 for _ in range(20):
496 detect_language(words)
497 elapsed = (time.perf_counter() - start) / 20
498 assert elapsed < 0.05, f"detect_language averaged {elapsed*1000:.1f}ms — too slow"
499
500
501 # ---------------------------------------------------------------------------
502 # Docstrings
503 # ---------------------------------------------------------------------------
504
505
506 class TestDocstrings:
507 """Every public symbol in muse.core.bip39 must have a docstring.
508
509 Docstrings are part of the contract — they are the first thing an agent
510 or engineer reads when integrating this module. A missing docstring is
511 a missing specification.
512 """
513
514 def test_module_has_docstring(self) -> None:
515 import muse.core.bip39 as mod
516 assert mod.__doc__, "muse.core.bip39 module has no docstring"
517
518 @pytest.mark.parametrize("name", [
519 "Bip39Error",
520 "generate_mnemonic",
521 "validate_mnemonic",
522 "mnemonic_to_seed",
523 "detect_language",
524 "word_count",
525 ])
526 def test_public_symbol_has_docstring(self, name: str) -> None:
527 import muse.core.bip39 as mod
528 obj = getattr(mod, name)
529 assert obj.__doc__, f"muse.core.bip39.{name} has no docstring"
File History 1 commit
sha256:d11a87833d5fad6059b7662844bf5448a8911a17cce7a51811f71ad394f248eb bump to v0.2.0rc13 Human patch 6 days ago