Harden self-test and optional QR packaging

Author: Ambrogio

README.md

@@ -12,7 +12,7 @@ The original webcam/audio/mouse implementation is preserved unchanged under `leg
 
 ## Release Status
 
-Current project version: **2.3.0**
+Current project version: **2.3.1**
 
 The maintained CLI is tested on Windows and Linux with Python 3.11, 3.12, and 3.13 through GitHub Actions.
 
@@ -25,7 +25,6 @@ Python 3.11 or newer is recommended.
 Install the CLI from a local checkout:
 
 ```bash
-python -m pip install -r requirements.txt
 python -m pip install .
 entropyseed --self-test
 ```
@@ -42,19 +41,25 @@ The base install has no runtime dependency beyond Python's standard library. Ins
 python -m pip install '.[qr]'
 ```
 
+For development and test runs, install the test dependencies:
+
+```bash
+python -m pip install -r requirements.txt
+python -m pytest -q
+```
+
 ---
 
 ## Running From The Repository
 
 You can also run the repository entry point directly:
 
 ```bash
-python -m pip install -r requirements.txt
 python seedgen.py --self-test
 python seedgen.py
 ```
 
-The generator uses the Python standard library for normal mnemonic generation. `qrcode` is used only for optional terminal QR output, and `pytest` is listed for the test suite.
+The generator uses the Python standard library for normal mnemonic generation. `pytest` is listed only for development and test runs. `qrcode` is installed only through the optional `.[qr]` extra when terminal QR output is wanted.
 
 ---
 
@@ -128,14 +133,16 @@ If `--qr` is requested without QR support installed, the program exits before co
 
 ## Entropy Sources
 
-OS CSPRNG entropy from `secrets.token_bytes` is always included and cannot be disabled. Manual typing, dice rolls, and timer jitter are supplemental only — they strengthen the pool, they do not replace it.
+OS CSPRNG entropy from `secrets.token_bytes` is the mandatory foundation and cannot be disabled. Dice rolls are a strong independent supplement when the dice are fair, private, and used correctly. Manual typing is an optional supplement, but the tool does not assume or quantify its entropy. Timer jitter is an opportunistic local supplement, not a substitute for the OS CSPRNG.
 
 Generation fails if the mandatory OS CSPRNG source is missing or returns an unexpected amount of entropy. The tool is designed to fail closed rather than silently downgrade to weaker supplemental sources.
 
 Dice input accepts digits `1` through `6`; spaces are ignored. For 12-word generation, at least 50 dice rolls are required. For 24-word generation, at least 99 dice rolls are required.
 
 Timer jitter displays a short collection message and progress dots. It is collected in memory and should complete quickly.
 
+The supported CLI path is `collect_sources() -> derive_mnemonic()`. Internally, `derive_mnemonic()` requires the mandatory OS source label (`os-csprng`) before mixing; this is a fail-closed software check for the supported path, not cryptographic proof of byte provenance.
+
 ---
 
 ## Security Notes

entropyseed/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "2.3.0"
+__version__ = "2.3.1"

entropyseed/cli.py

@@ -77,6 +77,8 @@ def collect_sources(args: argparse.Namespace) -> list[EntropySource]:
 
 
 def derive_mnemonic(sources: list[EntropySource], strength: int) -> str:
+    # Supported CLI path: collect_sources() labels the mandatory OS CSPRNG source.
+    # This fail-closed check is not cryptographic proof of byte provenance.
     if not any(source.name == MANDATORY_OS_SOURCE for source in sources):
         raise ValueError("mandatory OS CSPRNG entropy source is missing")
 

entropyseed/selftest.py

@@ -22,7 +22,6 @@ def run_self_tests() -> list[SelfTestResult]:
         _check_bip39_vectors(),
         _check_hkdf_vectors(),
         _check_entropy_mixer_os_source(),
-        _check_no_file_output_required(),
     ]
 
 
@@ -71,7 +70,3 @@ def _check_entropy_mixer_os_source() -> SelfTestResult:
     except Exception as exc:
         return SelfTestResult("entropy mixer OS source", False, str(exc))
 
-
-def _check_no_file_output_required() -> SelfTestResult:
-    return SelfTestResult("no file output required", True)
-

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "entropyseed"
-version = "2.3.0"
+version = "2.3.1"
 description = "Offline BIP39 mnemonic generator with mandatory OS CSPRNG entropy."
 readme = "README.md"
 requires-python = ">=3.11"

requirements.txt

@@ -1,2 +1 @@
 pytest>=8.0
-qrcode>=8.0

tests/test_cli.py

@@ -1,6 +1,7 @@
 import subprocess
 import sys
 import types
+from pathlib import Path
 
 from entropyseed.cli import (
     build_parser,
@@ -48,6 +49,19 @@ def fail_print_mnemonic_qr(mnemonic):
     assert main([]) == 0
 
 
+def test_main_without_arguments_does_not_create_files(monkeypatch, tmp_path, capsys):
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr("entropyseed.cli.word_count_for_strength", lambda strength: 3)
+    monkeypatch.setattr("entropyseed.cli.collect_sources", lambda args: ["controlled-source"])
+    monkeypatch.setattr("entropyseed.cli.derive_mnemonic", lambda sources, strength: "alpha beta gamma")
+
+    assert main([]) == 0
+
+    captured = capsys.readouterr()
+    assert "alpha beta gamma" in captured.out
+    assert list(Path(tmp_path).iterdir()) == []
+
+
 def test_parser_accepts_qr():
     args = build_parser().parse_args(["--qr"])
     assert args.qr is True
@@ -190,6 +204,7 @@ def print_ascii(self, out):
 def test_main_prints_qr_when_requested(monkeypatch, capsys):
     calls = {}
 
+    monkeypatch.setattr("entropyseed.cli.qr_support_available", lambda: True)
     monkeypatch.setattr("entropyseed.cli.word_count_for_strength", lambda strength: 3)
     monkeypatch.setattr("entropyseed.cli.collect_sources", lambda args: ["source"])
     monkeypatch.setattr("entropyseed.cli.derive_mnemonic", lambda sources, strength: "alpha beta gamma")