fix(live): a phrase is four plain words and a tail, and nothing weaker

Two holes in the one credential a stream has.

The wordlist has four hyphenated entries (`drop-down`, `felt-tip`,
`t-shirt`, `yo-yo`). A phrase drawn from one is six tokens --
`abacus-drop-down-lantern-harbor-7k2qp` -- and a listener cannot hear where
the tail starts. `words()` now keeps only `^[a-z]+$`; 7772 words costs
0.003 bits, so the ~77.5-bit figure is unchanged. The shape test asserted
over 50 draws, which caught this about a tenth of the time; the property is
now asserted over the whole list.

`validate` accepted `a-b-c`. It is what an operator-supplied `--phrase` is
checked against, so everything it accepts is a password someone can choose
for a LAN-facing stream. The floor is now exactly what `generate` produces:
four `[a-z]{3,}` words and a five-character `[a-z0-9]` tail. The router
still looks phrases up without validating, so an unknown phrase is the same
empty 404 it was.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01URhyHGQnmKH9zBXxoznfQY
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-06 16:19:41 +00:00
1 parent 52e3786bfb
commit 19338af17c
3 files changed
+97 -28

No files matched your search

+13 -7
View File
@@ -85,14 +85,20 @@ session record so it survives a broker restart and a re-enable.
- Shape: `<word>-<word>-<word>-<word>-<xxxxx>`, 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
+38 -17
View File
@@ -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"]
+46 -4
View File
@@ -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))