diff --git a/docs/plans/2026-10-04-session-stream-webapp.md b/docs/plans/2026-10-04-session-stream-webapp.md index d86516c..2796523 100644 --- a/docs/plans/2026-10-04-session-stream-webapp.md +++ b/docs/plans/2026-10-04-session-stream-webapp.md @@ -85,14 +85,20 @@ session record so it survives a broker restart and a re-enable. - Shape: `----`, e.g. `amber-otter-lantern-harbor-7k2qp`. -- Words come from a **vendored EFF large wordlist** (7776 words, ~70 KB, in the +- Words come from a **vendored EFF large wordlist** (7776 lines, ~70 KB, in the repo — no network at runtime, no dependency) and the tail is five characters - of `[a-z0-9]`. Four words is `4 · log2(7776) ≈ 51.7` bits and the tail adds - `5 · log2(36) ≈ 25.8`, for **≈ 77.5 bits** — comfortably past anything a LAN - request rate can enumerate, and the operator's stated shape ("5 with a random - 5 character string for the last word"). -- `--phrase` on enable sets your own (checked against the shape); `disable` - then `enable` **rotates** it. A rotation is one record write. + of `[a-z0-9]`. Four of those lines are hyphenated (`drop-down`, `felt-tip`, + `t-shirt`, `yo-yo`) and are dropped on load, because a hyphen is the phrase's + own separator and such a word would make a six-token phrase nobody could hear + the shape of; **7772 words** are usable. Four words is `4 · log2(7772) ≈ 51.7` + bits and the tail adds `5 · log2(36) ≈ 25.8`, for **≈ 77.5 bits** — + comfortably past anything a LAN request rate can enumerate, and the operator's + stated shape ("5 with a random 5 character string for the last word"). +- `--phrase` on enable sets your own, and it is held to **exactly the generated + shape** (four `[a-z]{3,}` words plus a five-character `[a-z0-9]` tail): the + phrase is the stream's only credential, so anything a `--phrase` may be is a + password an operator can choose, and a looser check would accept `a-b-c`. + `disable` then `enable` **rotates** it. A rotation is one record write. - The phrase is the only credential. It is in the URL, in cleartext on the LAN when the LAN is opted into — the threat model is "another device on the LAN can watch if it can guess the phrase", not "the phrase is hidden from the diff --git a/src/hhstream_live/phrase.py b/src/hhstream_live/phrase.py index f5a7c03..be94a3d 100644 --- a/src/hhstream_live/phrase.py +++ b/src/hhstream_live/phrase.py @@ -1,7 +1,7 @@ """The phrase: a stream's only credential, shaped to be said out loud. A phrase is ``word-word-word-word-xxxxx``: four words off the EFF large -wordlist and a five-character base-36 tail. That is ``4*log2(7776) + +wordlist and a five-character base-36 tail. That is ``4*log2(7772) + 5*log2(36)`` ~= **77.5 bits** of entropy, against a word set small enough to be a file in the repository and a tail short enough to type on a phone. @@ -11,8 +11,13 @@ base64 string is not. The job is identical (it *is* the password to the stream); only the shape is chosen for a human. The list is vendored (`wordlist.txt`, 7776 lines) so a stream never needs the -network to start. `generate` uses `SystemRandom`/`secrets`, so the phrase is -not reproducible from the process seed. +network to start. Four of those lines are hyphenated (`drop-down`, `felt-tip`, +`t-shirt`, `yo-yo`) and are dropped on load: a hyphen is the phrase's own +separator, so a phrase built from one would be six tokens and a listener could +not hear where the tail starts. 7772 words costs 0.003 bits. + +`generate` uses `SystemRandom`/`secrets`, so the phrase is not reproducible +from the process seed. """ from __future__ import annotations @@ -24,18 +29,29 @@ import secrets from pathlib import Path #: Four words plus the tail. The plan's answer to "how many"; four is -#: `4 * log2(7776)` ~= 51.7 bits on its own, and the tail pushes it past 77. +#: `4 * log2(7772)` ~= 51.7 bits on its own, and the tail pushes it past 77. WORD_COUNT = 4 SUFFIX_LEN = 5 #: Lowercase letters and digits: what a person can retype without a shift key, #: and 36 symbols is still `5 * log2(36)` ~= 25.8 bits. SUFFIX_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789" -#: A phrase is one or more hyphen-joined tokens of lowercase letters/digits, -#: at least three of them (so a caller-supplied phrase cannot be a single word -#: or a passcode-free stub). Generated phrases are five tokens; this is the -#: looser shape a `--phrase` must satisfy. -_SHAPE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+){2,}$") +#: The smallest token a word may be. The wordlist's own floor is 3, so this +#: rejects nothing `generate` can produce and everything an operator might type +#: as a stand-in ("a-b-c-d-12345"). +MIN_WORD_LEN = 3 +#: A phrase is exactly what `generate` makes: `WORD_COUNT` alphabetic words of +#: at least `MIN_WORD_LEN` characters, then a `SUFFIX_LEN` tail of `[a-z0-9]`. +#: An operator-supplied `--phrase` is a password for a LAN-facing stream, so it +#: is held to the generated shape rather than to a looser "looks like a phrase" +#: pattern -- a looser one accepts `a-b-c`, and nothing stops an operator from +#: typing that. +_SHAPE = re.compile( + rf"^[a-z]{{{MIN_WORD_LEN},}}(?:-[a-z]{{{MIN_WORD_LEN},}}){{{WORD_COUNT - 1}}}" + rf"-[a-z0-9]{{{SUFFIX_LEN}}}$" +) +#: Only the words whose letters are the whole line; see the module docstring. +_WORD_SHAPE = re.compile(r"^[a-z]+$") MAX_LENGTH = 96 _WORDLIST = Path(__file__).with_name("wordlist.txt") @@ -43,7 +59,11 @@ _cache: tuple[str, ...] | None = None def words() -> tuple[str, ...]: - """The wordlist, read once and remembered. + """The usable wordlist, read once and remembered. + + Only plain `[a-z]+` lines survive: the EFF list contains four hyphenated + entries and the hyphen is the phrase's separator, so one of them would make + a six-token phrase nobody could read out correctly. Raises `RuntimeError` on an empty file rather than returning nothing: a generator that picks from an empty list would raise a confusing `IndexError` @@ -52,9 +72,10 @@ def words() -> tuple[str, ...]: global _cache if _cache is None: text = _WORDLIST.read_text(encoding="utf-8") - loaded = tuple(word.strip() for word in text.splitlines() if word.strip()) + stripped = (line.strip() for line in text.splitlines()) + loaded = tuple(word for word in stripped if _WORD_SHAPE.match(word)) if not loaded: - raise RuntimeError(f"wordlist {_WORDLIST} is empty") + raise RuntimeError(f"wordlist {_WORDLIST} has no usable words") _cache = loaded return _cache @@ -91,12 +112,12 @@ def validate(phrase: str) -> str: raise ValueError(f"phrase is {len(normalized)} characters; the maximum is {MAX_LENGTH}") if not _SHAPE.match(normalized): raise ValueError( - "phrase must be lowercase words/digits joined by hyphens, at least " - "three tokens (e.g. four-words-and-a-tail), not " - f"{phrase!r}" + f"phrase must be {WORD_COUNT} lowercase words of at least " + f"{MIN_WORD_LEN} letters plus a {SUFFIX_LEN}-character [a-z0-9] " + f"tail (e.g. amber-otter-lantern-harbor-7k2qp), not {phrase!r}" ) return normalized -__all__ = ["WORD_COUNT", "SUFFIX_LEN", "generate", "normalize", "validate", - "entropy_bits", "words", "MAX_LENGTH"] +__all__ = ["WORD_COUNT", "SUFFIX_LEN", "MIN_WORD_LEN", "generate", "normalize", + "validate", "entropy_bits", "words", "MAX_LENGTH"] diff --git a/tests/live/test_live_phrase.py b/tests/live/test_live_phrase.py index 0a4df90..2c17b30 100644 --- a/tests/live/test_live_phrase.py +++ b/tests/live/test_live_phrase.py @@ -8,6 +8,7 @@ import pytest from hhstream_live import phrase SHAPE = re.compile(r"^[a-z]+(-[a-z]+){3}-[a-z0-9]{5}$") +WORD = re.compile(r"^[a-z]+$") def test_generated_phrase_has_the_agreed_shape(): @@ -24,11 +25,24 @@ def test_entropy_is_what_the_plan_claims(): assert phrase.entropy_bits() > 75 -def test_wordlist_is_the_eff_large_list(): +def test_wordlist_is_the_eff_large_list_minus_its_hyphenated_entries(): words = phrase.words() - assert len(words) == 7776 - assert len(set(words)) == 7776 + # The file is the EFF large list, 7776 lines; four of them are hyphenated + # and the loader drops them, because a hyphen is the phrase's separator. + assert len(words) == 7772 + assert len(set(words)) == 7772 assert "abacus" in words + assert "drop-down" not in words + + +def test_every_loaded_word_is_plain_lowercase_letters(): + """Not a sampling test: one hyphenated word makes a six-token phrase. + + `test_generated_phrase_has_the_agreed_shape` would only catch that by luck + -- four draws out of 7776 hit a hyphenated entry about 0.2% of the time -- + so the property is asserted over the whole list instead. + """ + assert all(WORD.match(word) for word in phrase.words()) def test_generate_is_not_reproducible_from_a_seed(): @@ -47,7 +61,15 @@ def test_normalize_lowercases_and_trims(): def test_validate_accepts_a_good_phrase_and_returns_the_normalized_form(): - assert phrase.validate("Amber-Otter-Lantern-7K2QP") == "amber-otter-lantern-7k2qp" + assert phrase.validate("Amber-Otter-Lantern-Harbor-7K2QP") == ( + "amber-otter-lantern-harbor-7k2qp" + ) + + +def test_validate_accepts_everything_generate_produces(): + for _ in range(50): + generated = phrase.generate() + assert phrase.validate(generated) == generated @pytest.mark.parametrize("bad", ["", "single", "two-tokens", "has space-phrase-x", @@ -58,6 +80,26 @@ def test_validate_rejects_a_phrase_that_is_not_the_shape(bad): phrase.validate(bad) +@pytest.mark.parametrize("weak", [ + "a-b-c", # the reviewer's example: three letters + "ab-cd-ef-gh-12345", # four "words" of two letters + "amber-otter-lantern-7k2qp", # three words, not four + "amber-otter-lantern-harbor", # four words, no tail + "amber-otter-lantern-harbor-7k2", # a three-character tail + "amber-otter-lantern-harbor-7k2qpz", # a six-character tail + "amber-otter-lantern-harbor-hill-7k2qp", # five words + "amber-0tter-lantern-harbor-7k2qp", # a digit inside a word +]) +def test_validate_rejects_a_phrase_weaker_than_the_generated_shape(weak): + """`--phrase` is a password for a LAN-facing stream, not a label. + + Anything `validate` accepts is something an operator can set, so the floor + has to be the shape `generate` produces -- otherwise `a-b-c` opens a stream. + """ + with pytest.raises(ValueError): + phrase.validate(weak) + + def test_validate_rejects_an_overlong_phrase(): with pytest.raises(ValueError): phrase.validate("-".join(["averyverylongword"] * 8))