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. - Shape: `<word>-<word>-<word>-<word>-<xxxxx>`, e.g.
`amber-otter-lantern-harbor-7k2qp`. `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 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 of `[a-z0-9]`. Four of those lines are hyphenated (`drop-down`, `felt-tip`,
`5 · log2(36) ≈ 25.8`, for **≈ 77.5 bits** — comfortably past anything a LAN `t-shirt`, `yo-yo`) and are dropped on load, because a hyphen is the phrase's
request rate can enumerate, and the operator's stated shape ("5 with a random own separator and such a word would make a six-token phrase nobody could hear
5 character string for the last word"). the shape of; **7772 words** are usable. Four words is `4 · log2(7772) ≈ 51.7`
- `--phrase` on enable sets your own (checked against the shape); `disable` bits and the tail adds `5 · log2(36) ≈ 25.8`, for **≈ 77.5 bits** —
then `enable` **rotates** it. A rotation is one record write. 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 - 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 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 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. """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 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 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. 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. stream); only the shape is chosen for a human.
The list is vendored (`wordlist.txt`, 7776 lines) so a stream never needs the 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 network to start. Four of those lines are hyphenated (`drop-down`, `felt-tip`,
not reproducible from the process seed. `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 from __future__ import annotations
@@ -24,18 +29,29 @@ import secrets
from pathlib import Path from pathlib import Path
#: Four words plus the tail. The plan's answer to "how many"; four is #: 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 WORD_COUNT = 4
SUFFIX_LEN = 5 SUFFIX_LEN = 5
#: Lowercase letters and digits: what a person can retype without a shift key, #: Lowercase letters and digits: what a person can retype without a shift key,
#: and 36 symbols is still `5 * log2(36)` ~= 25.8 bits. #: and 36 symbols is still `5 * log2(36)` ~= 25.8 bits.
SUFFIX_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789" SUFFIX_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789"
#: A phrase is one or more hyphen-joined tokens of lowercase letters/digits, #: The smallest token a word may be. The wordlist's own floor is 3, so this
#: at least three of them (so a caller-supplied phrase cannot be a single word #: rejects nothing `generate` can produce and everything an operator might type
#: or a passcode-free stub). Generated phrases are five tokens; this is the #: as a stand-in ("a-b-c-d-12345").
#: looser shape a `--phrase` must satisfy. MIN_WORD_LEN = 3
_SHAPE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+){2,}$") #: 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 MAX_LENGTH = 96
_WORDLIST = Path(__file__).with_name("wordlist.txt") _WORDLIST = Path(__file__).with_name("wordlist.txt")
@@ -43,7 +59,11 @@ _cache: tuple[str, ...] | None = None
def words() -> tuple[str, ...]: 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 Raises `RuntimeError` on an empty file rather than returning nothing: a
generator that picks from an empty list would raise a confusing `IndexError` generator that picks from an empty list would raise a confusing `IndexError`
@@ -52,9 +72,10 @@ def words() -> tuple[str, ...]:
global _cache global _cache
if _cache is None: if _cache is None:
text = _WORDLIST.read_text(encoding="utf-8") 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: if not loaded:
raise RuntimeError(f"wordlist {_WORDLIST} is empty") raise RuntimeError(f"wordlist {_WORDLIST} has no usable words")
_cache = loaded _cache = loaded
return _cache return _cache
@@ -91,12 +112,12 @@ def validate(phrase: str) -> str:
raise ValueError(f"phrase is {len(normalized)} characters; the maximum is {MAX_LENGTH}") raise ValueError(f"phrase is {len(normalized)} characters; the maximum is {MAX_LENGTH}")
if not _SHAPE.match(normalized): if not _SHAPE.match(normalized):
raise ValueError( raise ValueError(
"phrase must be lowercase words/digits joined by hyphens, at least " f"phrase must be {WORD_COUNT} lowercase words of at least "
"three tokens (e.g. four-words-and-a-tail), not " f"{MIN_WORD_LEN} letters plus a {SUFFIX_LEN}-character [a-z0-9] "
f"{phrase!r}" f"tail (e.g. amber-otter-lantern-harbor-7k2qp), not {phrase!r}"
) )
return normalized return normalized
__all__ = ["WORD_COUNT", "SUFFIX_LEN", "generate", "normalize", "validate", __all__ = ["WORD_COUNT", "SUFFIX_LEN", "MIN_WORD_LEN", "generate", "normalize",
"entropy_bits", "words", "MAX_LENGTH"] "validate", "entropy_bits", "words", "MAX_LENGTH"]
+46 -4
View File
@@ -8,6 +8,7 @@ import pytest
from hhstream_live import phrase from hhstream_live import phrase
SHAPE = re.compile(r"^[a-z]+(-[a-z]+){3}-[a-z0-9]{5}$") 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(): 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 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() words = phrase.words()
assert len(words) == 7776 # The file is the EFF large list, 7776 lines; four of them are hyphenated
assert len(set(words)) == 7776 # 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 "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(): 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(): 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", @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) 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(): def test_validate_rejects_an_overlong_phrase():
with pytest.raises(ValueError): with pytest.raises(ValueError):
phrase.validate("-".join(["averyverylongword"] * 8)) phrase.validate("-".join(["averyverylongword"] * 8))