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

+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"]