entropyseed is designed for offline use on Windows and Linux.

This project is intended to reduce mistakes while generating a BIP39 English mnemonic on a trusted offline machine. It does not make an untrusted computer safe.

In scope:

• Correct BIP39 checksum handling for generated and test-vector mnemonics.
• Mandatory operating-system CSPRNG entropy.
• Optional local supplemental entropy from manual typing, dice rolls, and timer jitter.
• In-memory entropy mixing with SHA-512 source hashing and HKDF-SHA512.
• Avoiding project-created files containing mnemonics, entropy, seed material, QR codes, audio, or video.
• Avoiding clipboard use, telemetry, and network functionality.

Out of scope:

• Malware, keyloggers, terminal capture, screen capture, compromised firmware, or a hostile operating system.
• Weak backups, photographed mnemonics, cloud sync, printers, password managers, or other user-chosen storage.
• Supply-chain compromise before the code reaches the offline machine.
• Physical observation, coercion, theft, or device tampering.
• Wallet software bugs or incorrect wallet derivation paths after the mnemonic is generated.

• OS CSPRNG entropy from secrets.token_bytes is mandatory.
• Mnemonic derivation fails if the mandatory OS CSPRNG source is missing.
• OS entropy collection fails if the CSPRNG returns an unexpected byte count.
• Manual typing, dice rolls, and timer jitter are optional additive sources.
• Each source is SHA-512 hashed independently before HKDF-SHA512 mixing.
• The default behavior never writes mnemonic, entropy, seed, QR, audio, or video data to disk.
• QR support is optional and is checked before mnemonic generation when --qr is requested.
• Clipboard integration is intentionally disabled.
• Webcam, audio, and mouse collection are intentionally not part of the maintained implementation.

The core rule is fail closed: supplemental sources must never silently replace the mandatory cryptographic source.

This matters because seed-generation failures are permanent. If a mnemonic is created from less entropy than expected, later software updates, moving the mnemonic to another wallet, or re-importing it elsewhere cannot repair the already-generated seed.

For that reason:

• The maintained CLI always collects OS CSPRNG entropy first.
• derive_mnemonic() rejects source lists that do not include the os-csprng source.
• Manual typing, dice rolls, and timer jitter are mixed only as additional sources.
• A failure to collect mandatory OS entropy aborts generation instead of falling back to weaker local signals.

Dice rolls can provide strong independent entropy when they are fair, private, and numerous enough. This project still keeps OS CSPRNG entropy mandatory by design, so dice are an additional defense rather than an alternate default mode.

Run this project on a trusted offline machine. Verify the displayed mnemonic on paper or another durable offline medium. Do not photograph, paste, upload, print through networked services, or store the mnemonic in a password manager unless that is part of your own threat model.

Before generating a mnemonic, run:

python seedgen.py --self-test

The self-test checks the wordlist shape, known BIP39 vectors, HKDF vectors, and basic entropy mixing. Passing self-tests do not prove the machine is safe.

Do not include generated mnemonics, entropy, or private wallet details in bug reports. Share only code paths, command lines, and non-secret diagnostics.