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:
1 parent
52e3786bfb
commit
19338af17c
3 files changed
+97
-28
No files matched your search
@@ -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
@@ -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"]
|
||||
@@ -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))
|
||||
Reference in new issue
Block a user