SeedPass/docs/entropy_audit_2026-07-31.md

SeedPass — randomness and RNG-integration audit, 2026-07-31

Audit of every security-sensitive random value in src/, against a Coldcard-class checklist: where each bit of unpredictability originates, whether that source is present in the production artifact, and what happens when it fails.

Verdict

No predictable-fallback defect exists. Every non-deterministic secret comes from an OS CSPRNG and fails closed:

• Master seed — core/manager.py:1810, os.urandom(32)
• AES-GCM nonces — core/encryption.py:106, nostr/snapshot.py:57, core/memory_protection.py:21
• TOTP secrets — core/totp.py:22, os.urandom(20)
• Argon2 salts — utils/key_derivation.py:67, core/agent_secret_isolation.py:92
• API tokens, agent leases and approvals — secrets.token_urlsafe / secrets.token_bytes in seedpass/api.py:201,340, cli/agent.py:720,804, core/agent_approval.py:65, core/agent_secret_lease.py:71, core/agent_export_policy.py:74, core/agent_recovery.py:168

The random module is not imported anywhere in non-test source. I checked explicitly; there are no hits outside src/tests/. Nothing seeds a CSPRNG manually, and nothing uses timestamps, PIDs or device identifiers as entropy. Master-seed generation re-raises on failure rather than substituting a value.

The deterministic derivation in core/password_generation.py is intentional and correct in kind — deriving passwords reproducibly from a BIP-85 seed is the product. The findings below are about how much entropy survives that derivation, not about whether it should be deterministic.

---

The compatibility constraint that governs this whole document

Passwords are never stored. _generate_password_for_entry (core/manager.py:3140) re-derives them on demand from (seed, index, length, policy, gen_version) every time an entry is displayed.

At the time of this audit an entry record held index, length, type and an optional policy override — and no algorithm version. Any change to generate_password therefore silently changed every existing password in every vault, with no record of the old value and no way for a user to recover it. This is the same class of constraint BitLogin documents as its "derivation chain is a compatibility contract" standing rule.

As of 2026-07-31 entries carry gen_version, and the parameter defaults to 1 so an absent field means v1. The rule this constraint implies is permanent: no change may ever alter the output of a version that already exists in the wild. v1 is frozen forever; a fix that changes derivation goes into a new version, never into an old one. A patch that "just fixes the bias" in place is a data-loss event, not an improvement.

src/tests/test_entropy_integrity.py enforces this with 18 v1 vectors. A failure there is never "update the expected value".

---

Status, 2026-07-31

M4, L1 and M1/M2/M3 have landed. generate_password now takes a gen_version argument defaulting to 1; v1 is frozen and pinned by 18 vectors, and new password entries are stamped gen_version: 2.

Property (length 16, 200 samples)	v1	v2	ceiling
distinct class compositions	1	82	—
per-character entropy	6.42 b	6.53 b	6.555 b
chi-square over the 94-char alphabet	biased	96.1 (df=93)	crit ~147
lag-32 repeat rate	repeating pad	0.0110	chance 0.0106

Existing entries are untouched and stay on v1 until the opt-in upgrade ships. The remaining open items are L2, L4, L5 and that upgrade UX.

Open items

M1 — Every generated password has an identical character-class composition — DONE 2026-07-31

Fixed in v2 by deleting the _balance_distribution call from the v2 path and keeping only _enforce_minimum_counts-style policy minima. v1 retains it, frozen. The original analysis follows.

This is the main finding.

_balance_distribution (core/password_generation.py:367-408) partitions the password into one segment per character class and overwrites every position in each segment with a character of that class. The subsequent HMAC-Fisher-Yates shuffle randomizes the arrangement but cannot change the multiset.

Measured, 300 passwords per length against a fixed seed:

len=  16   distinct class compositions = 1   {U:4,  l:4,  d:4,  s:4}   x300/300
len=  24   distinct class compositions = 1   {U:6,  l:6,  d:6,  s:6}   x300/300
len=  32   distinct class compositions = 1   {U:8,  l:8,  d:8,  s:8}   x300/300
len=  64   distinct class compositions = 1   {U:16, l:16, d:16, s:16}  x300/300
len= 128   distinct class compositions = 1   {U:32, l:32, d:32, s:32}  x300/300

Exactly 25% of each class, every time, zero variance. Measured per-character entropy was 6.42 bits against a 94-character alphabet. The analytic prediction for a forced 25/25/25/25 split is 0.25·log₂(26)·2 + 0.25·log₂(10) + 0.25·log₂(32) + 2 = 6.43 bits — the measurement matches, confirming the constraint fully accounts for the deficit.

Cost against an unconstrained draw from the same alphabet:

length	unconstrained	actual	loss
8	52.4 b	46.7 b	5.7 b
16 (default)	104.9 b	96.8 b	8.1 b
24	157.3 b	147.4 b	9.9 b
32	209.7 b	198.2 b	11.5 b

Two things to weigh, honestly. The entropy loss alone is not alarming — 96.8 bits at the default length is far beyond brute-force reach, and nothing in the docs or code advertises a bits figure that this contradicts. The more material issue is that the invariant is a fingerprint: a password containing exactly L/4 of each class is a strong signal it came from SeedPass, and it tells an attacker who has one leaked hash to search the 96.8-bit structured space rather than the 104.9-bit unstructured one. Unlinkability, not raw strength, is what this costs.

_balance_distribution also buys nothing. _enforce_minimum_counts (password_generation.py:300) already guarantees the policy minima — 2 upper, 2 lower, 2 digits, 2 special by default. Forcing the remaining ~92% of positions into a rigid quota adds no compliance value that the minima do not already provide.

Fix.

1. Add a gen_version: int field to password entries, defaulting to 1 when absent. Thread it through _generate_password_for_entry alongside the existing policy override.
2. Branch in generate_password. Version 1 must be byte-identical to today's behaviour — do not refactor it, do not "clean it up", pin it with vectors (see M4).
3. Version 2: keep _enforce_minimum_counts, delete the _balance_distribution call, and fold in the M2/M3 fixes. New entries get gen_version: 2.
4. Offer an explicit, opt-in per-entry upgrade in the TUI/CLI that makes the consequence unmissable: "This will change this password. Update it at the site first, then confirm." Never bulk-migrate.

Acceptance. Regenerating any pre-existing entry yields the identical password it yielded before the change (v1 vectors green). A fresh entry produces varied class compositions — assert that 300 v2 passwords at length 16 yield more than 20 distinct compositions, against exactly 1 today.

---

M2 — Modulo bias in character and index selection — DONE 2026-07-31

_map_entropy_to_chars (password_generation.py:160):

password = "".join(alphabet[byte % len(alphabet)] for byte in dk)

With the default 94-character alphabet, 256 % 94 = 68, so 68 characters draw with probability 3/256 and 26 draw with 2/256. DeterministicStream consumers have the same shape: % 26 for letters (256 % 26 = 22), % 10 for digits. The 32-character special set is unbiased only by luck (256 % 32 = 0).

The effect is small — roughly 0.02 bits per character — and largely masked by M1, which overwrites most positions anyway. It is worth fixing because it is exactly the defect BitLogin's randomUniformInt was written to avoid, and because once M1 lands it stops being masked.

Fix (v2 only). Rejection-sample against the derived stream:

def _uniform_index(stream: "DeterministicStream", max_exclusive: int) -> int:
    """Rejection sampling — no modulo bias. Mirrors BitLogin's randomUniformInt."""
    limit = 256 - (256 % max_exclusive)
    while True:
        value = stream.get_value()
        if value < limit:
            return value % max_exclusive

Rejection consumes a variable number of stream bytes, which makes M3 a prerequisite rather than an optional companion — the stream must not run short.

Acceptance. Chi-square over 200k v2 draws at modulus 94 is below the p<0.001 critical value (~147 for df=93). v1 vectors unchanged.

---

M3 — DeterministicStream cycles a 32-byte key — DONE 2026-07-31

password_generation.py:87:

value = self.dk[self.index % self.length]

dk is 32 bytes. MAX_PASSWORD_LENGTH is 128. For any password longer than 32 characters, _balance_distribution consumes the same 32 bytes cyclically, so positions j and j+32 within a segment are driven by the identical byte. Wrapping a fixed key is not a stream cipher — it is a repeating pad.

_add_additional_symbols already senses the problem and works around it by breaking when stream.current_index >= stream.length (password_generation.py:360), which is a symptom, not a fix.

Fix (v2 only). Replace the wrap with a proper expansion. HKDF-Expand dk to the number of bytes actually needed — generously, since M2's rejection sampling consumes a variable amount — or make DeterministicStream generate on demand:

class DeterministicStream:
    def __init__(self, dk: bytes) -> None:
        self._key, self._block, self._pos, self._counter = dk, b"", 0, 0

    def get_value(self) -> int:
        if self._pos >= len(self._block):
            self._block = hmac.new(
                self._key, self._counter.to_bytes(4, "big"), hashlib.sha256
            ).digest()
            self._counter += 1
            self._pos = 0
        value = self._block[self._pos]
        self._pos += 1
        return value

This never repeats within any practical length and keeps the derivation fully deterministic. Delete the current_index >= length break in _add_additional_symbols once it lands.

Acceptance. A 128-character v2 password shows no period-32 correlation: assert positional autocorrelation at lag 32 is within noise across 1,000 samples. v1 vectors unchanged.

---

M4 — No RNG failure tests, and no v1 pinning vectors — DONE 2026-07-31

Landed as src/tests/test_entropy_integrity.py: 26 tests, inside the --determinism-only gate that scripts/run_ci_tests.sh runs before anything else. 18 frozen vectors span every policy in POLICIES and both sides of the 32-byte stream-wrap boundary (lengths 8/16/20/32/33/40/64/128).

Each guard was mutation-verified rather than assumed:

Mutation	Result
Remove the _balance_distribution call (the M1 change)	all 18 vectors red
Perturb the DeterministicStream wrap (the M3 change)	all 18 vectors red
Change alphabet[byte % len(alphabet)] (the M2 change)	all 18 vectors red
Add a sha256(time.time()) fallback to generate_bip85_seed	fail-closed test red ("DID NOT RAISE")

test_all_zero_entropy_is_not_currently_detected deliberately pins a gap rather than a guarantee: SeedPass would accept an all-zero os.urandom return and mint a valid-looking mnemonic from it. Read that test's docstring before "fixing" it — the point is that closing the gap should be a visible, deliberate change.

M1, M2 and M3 are now safe to attempt. The original problem statement follows.

Two gaps, one fix.

Nothing asserts the RNG fails closed. No test makes os.urandom raise and checks that seed generation aborts rather than returning something. The current behaviour is correct — generate_bip85_seed re-raises — but nothing in CI would report it if a future edit added a fallback. A deterministic stream passes every self-consistency test in the suite; that is precisely how the Coldcard defect survived its own health check.

Nothing pins v1 output. Without vectors, M1–M3 cannot be landed safely at all, because there is no way to prove v1 still derives what it derived before.

Fix. Add src/tests/test_entropy_integrity.py:

def test_seed_generation_aborts_when_urandom_fails(monkeypatch):
    monkeypatch.setattr(os, "urandom", _raise(OSError("entropy pool unavailable")))
    with pytest.raises((SeedPassError, OSError)):
        manager.generate_bip85_seed()          # must NOT return a value

def test_encryption_nonce_is_fresh_per_call():
    a, b = em.encrypt_data(b"same"), em.encrypt_data(b"same")
    assert a[3:15] != b[3:15]                  # V3| + 12-byte nonce

def test_v1_password_vectors_are_frozen():
    """Compatibility contract: these outputs are what live vaults re-derive.
    A failure here is never 'update the expected value'."""
    for idx, length, expected in V1_VECTORS:
        assert pg.generate_password(length=length, index=idx) == expected

Generate V1_VECTORS from the current main before touching anything — several indices, several lengths, at least one over 32 characters to cover M3's territory, and one for each non-default policy (exclude_ambiguous, special_mode="safe", include_special_chars=False).

Acceptance. All three pass on main today. Deliberately breaking generate_bip85_seed to swallow the error must turn the first red — verify locally, then revert.

---

L1 — Dead HKDF, and a docstring that documents the wrong algorithm — DONE 2026-07-31

_derive_password_entropy (password_generation.py:144-156) builds an HKDF instance, derives hkdf_derived, and never uses it — the function returns the PBKDF2 output. generate_password's docstring nonetheless states "Use HKDF-HMAC-SHA256 to derive a key from entropy."

Not a vulnerability: PBKDF2-HMAC-SHA256 over 64 bytes of BIP-85 entropy is sound, and 100,000 iterations over an already-high-entropy input is harmless overkill. It is recorded because it is exactly the doc-vs-code drift the checklist's §5 warns about — a reassuring name in front of a different implementation is how the Coldcard chain hid.

Fix. Delete the unused HKDF block and correct the docstring to describe PBKDF2. Removing dead code cannot change output, so this one is safe to land independently of the gen_version work — but add it to the v1 vector run anyway, to prove that.

---

L2 — Master seed entropy accounting — DONE 2026-07-31

generate_bip85_seed and create_profile_from_generated_seed now take words_num, accepting 12 or 24 and rejecting anything else. The default stays 12: every existing profile uses it, it is entirely adequate, and moving the default would surprise without improving any existing vault. 24 is now available for a 256-bit master seed, which removes the oddity that the secret protecting the whole vault was shorter than the seeds derived beneath it (those default to 24).

The original note follows.

L2 (original) — Master seed entropy accounting

generate_bip85_seed (core/manager.py:1810-1812) draws os.urandom(32) — 256 bits — then derives a 12-word mnemonic, which encodes 128. The word count is hardcoded, while derived seed phrases (derive_seed_phrase, password_generation.py:519) default to 24.

128 bits is entirely adequate and this is not a defect. It is recorded because §6 asks for the accounting to be written down, and because the asymmetry is surprising: the master secret protecting the whole vault is shorter than the seeds derived beneath it.

Fix (optional). Offer 24 words at profile creation. It costs one parameter and gives users who want a 256-bit master the option. Existing profiles are unaffected — this only changes what new seeds look like.

---

L3 — Broad except Exception around crypto — DONE 2026-07-31 (for the RNG path)

Fixed structurally rather than by narrowing exception types. os.urandom(32) now sits outside the try block in generate_bip85_seed, so no handler can stand between the entropy draw and the caller. The redundant duplicate except Exception — whose body was identical to the Bip85Error branch above it — is gone.

This is stronger than listing which exceptions to catch: an entropy failure is now unreachable by any handler that could substitute a value, and test_entropy_draw_sits_outside_the_try_block asserts the raised OSError arrives as the same object that os.urandom threw, which is only true if nothing caught and repackaged it.

The remaining broad handlers in password_generation.py (lines 280, 485) wrap deterministic derivation with no RNG in it, and they log and re-raise rather than substituting. They are covered by the general "replace broad except Exception" item in TODO.md rather than being an entropy concern.

The original note follows.

L3 (original) — Broad except Exception around crypto

password_generation.py:280, :485, core/manager.py:1817. All of these log-and-re-raise, so there is no silent fallback — the operation aborts, as it should. Recorded because §13 flags the pattern: a bare except Exception wrapped around key generation is one careless edit away from becoming a fallback, and it is where the reviewer's eye should go first.

Overlaps with the existing "Replace broad except Exception: pass blocks" item in ../TODO.md; these three are the crypto-path instances and should be narrowed to the specific exceptions each path can raise.

---

L4 — torch/ subsystem — PARTLY DONE 2026-07-31

Fixed: the temp filename in services/memory/index.js now uses randomBytes(8) instead of Date.now() + Math.random(), and the Math.random-derived value in relay-health.mjs that was called a nonce is renamed probeSuffix and drawn from randomBytes(6) — it is a public probe tag, but the name invited reuse of the pattern somewhere it would matter.

Still open, and it needs a decision: torch/_backups/ holds 5240 tracked files across six dated snapshots. Untracking them is a large deletion, so it is not something to do as a side effect of an entropy audit. Two concrete costs today: they duplicate every security-relevant grep hit, and bare node --test in torch/ discovers them and fails 18 tests from stale snapshot code. (The npm test script uses explicit paths, so CI is unaffected.)

Separately noted: torch/ has no test/ directory in the repo at all, so npm test there cannot run as written. Out of scope here, but worth knowing.

The original note follows.

L4 (original) — torch/ subsystem

• torch/src/services/memory/index.js:60 builds a temp filename from Date.now() + Math.random() before an atomic rename. Predictable name; low impact in a user-owned directory, but §1 lists unguessable temp names. Use crypto.randomBytes(8).toString('hex') — a one-line change.
• torch/src/relay-health.mjs:95 names a Math.random-derived value a nonce. It is a probe tag, not a cryptographic nonce, and is fine as-is — but the naming invites a future mistake. Rename to probeSuffix.
• torch/_backups/ contains three stale in-tree copies of this code (backup_2026-02-25T20-04-27-295Z, backup_2026-02-26T02-09-18-956Z, backup_2026-02-26T13-32-51-188Z). They pollute every security grep with duplicate hits. Move out of the working tree or add to .gitignore.

---

L5 — No SBOM — DONE 2026-07-31

dependency-audit.yml now generates a CycloneDX SBOM from requirements.lock and uploads it. Verified locally with the real tool rather than assumed: the first flag spelling I wrote (--output-format / --outfile) does not exist in cyclonedx-py and would have failed in CI. The working form is --of json --output-reproducible -o <file>, which emits CycloneDX 1.6 with 96 components and records the crypto chain at exact versions — [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected].

The original note follows.

L5 (original) — No SBOM

dependency-audit.yml and release-integrity.yml cover part of §11/§12, but no workflow emits a dependency manifest artifact. Add CycloneDX generation (pip install cyclonedx-bom && cyclonedx-py requirements requirements.lock) and upload it alongside the existing release-integrity artifacts.

Folds naturally into the open supply-chain item in ../TODO.md.

---

Sequencing

The order matters more here than in the sibling repos, because the compatibility constraint makes the wrong order destructive.

1. M4 first, and specifically the v1 vectors. Nothing else can land safely until v1 output is pinned. Generate them from current main.
2. L1 — dead-code deletion, proves the vector harness works.
3. M1's scaffolding — the gen_version field, defaulted to 1, with v2 not yet differing. Confirm every existing entry still derives identically.
4. M3, then M2 into v2 (stream expansion before rejection sampling — the latter needs an unbounded stream).
5. M1's substance — drop _balance_distribution from v2.
6. The opt-in upgrade UX. Ship last, and only once v2 is settled; a user who upgrades an entry has changed a live password at a real site.
7. L2, L4, L5 whenever convenient — none interact with the derivation chain.

Related

• crypto_key_management_review.md
• security_readiness_checklist.md