Ship a working download, verify the password, and make the docs true

[aquaxs1]

Started as two reported problems, grew to cover what reviewing the tool end to end turned up. Two commits: the reported fixes, then the follow-ups.

---

Part 1 — the two reported problems

The download buttons were dead

The site linked to cipherbox-windows-x64.zip, cipherbox-macos-arm64.zip and cipherbox-linux-x64.tar.gz under releases/latest/download/. All three returned 404 — the release workflow that would produce them has never run, and the only published artefact is a hand-uploaded CipherBox.exe.

The executable is now the primary path: hero and download section link straight to it, with the SmartScreen warning and certutil verification explained beside the button. macOS, Linux and the pip/source install moved into a collapsed secondary block. The release workflow now also publishes the Windows binary under the fixed name CipherBox.exe, so that URL keeps resolving for future releases.

Old residue could lock you out of a fresh install

~/.cipherbox/config.json counted as an existing install purely because the file existed. A config from an interrupted setup or an old test run holds no usable salt, so the app skipped setup, showed a password prompt where nothing could ever work, and dead-ended on "Configuration error. Please reinstall." — advice that cannot help, since the residue lives in the home directory, not the install.

Such a config is now detected and cleared, and setup runs again with a visible reason. A config carrying a real salt is never touched — deleting that would make encrypted files unreadable forever. Writes are atomic at 0600, so an interrupted write leaves neither a half-written config nor a stray temp file. Plus a .gitignore, a CI clean step that fails the build if dist/ holds anything but the expected binary, and the removal of test_imports.py and five stale session documents.

---

Part 2 — follow-ups

verify_password() never verified anything

It derived a key and opened the main window:

self.encryption_key = self.crypto.derive_key(password, salt)
self.show_main_interface()   # any password lands here

So a typo got you in, and surfaced later as "Wrong password or corrupted file" against your own files — which reads like the file is damaged, not the password wrong. Setup now stores a token encrypted with the derived key; login rejects a password whose key cannot decrypt it.

Older configs keep working: the password is genuinely unverifiable there, so the token is backfilled after a successful decryption proves the key, never guessed at login.

The multi-GB claim was not true

Files are not streamed. The original bytes, the payload built around them and Fernet's base64 ciphertext all sit in memory at once. Measured:

File	Peak RAM	Factor
8 MB	79 MB	9.9x
32 MB	303 MB	9.5x
96 MB	858 MB	8.9x

A 1 GB file needs several GB and dies with a MemoryError. The app now warns before starting on anything above 256 MB, naming each file and its estimated cost. The site, README, GUIDE and QUICKSTART carry measured numbers — GUIDE's old benchmark table claimed a 1 GB file encrypts in 30 seconds and that key derivation takes 1.5 s (actually ~124 ms here).

Secure deletion did not reach the disk

The three overwrite passes were never flushed, so the OS was free to cache and collapse them — the original bytes could survive untouched. Each pass is now flushed and fsync'd, and written in 4 MB chunks rather than allocating a buffer the size of the file.

The docs no longer imply this defeats recovery on flash storage: wear levelling writes each pass to a fresh block and leaves the original unreachable through any file API. Full-disk encryption is the dependable answer, and the README now says so.

The docs pointed at files that do not exist

QUICKSTART and GUIDE told users to double-click install.bat or run ./install.sh. Neither exists in the repo — the documented installation path simply could not be followed. Both now describe the real ones, executable first. GUIDE's file tree matches the repo again, and each document states who it is for.

Smaller

LISENCE → LICENSE, titled so GitHub detects MIT (three site links updated). New tests.yml runs the suite on Linux, Windows and macOS against Python 3.10 and 3.12 — with PYTHONIOENCODING: utf-8, since the suite's check marks otherwise crash on a Windows runner's legacy code page (verified: it exits 1 without it).

---

Verification

• 12 tests pass, up from 9, and the suite numbers itself now instead of by hand — I misnumbered it twice while adding cases.
• Driven against the real GUI under Xvfb, not just the library: first-launch wizard, verifier written to config, relaunch reaching the prompt rather than the wizard, residue cleared and setup completing over it, the large-file warning firing with correct figures (big.bin — 512 MB, needs about 4,608 MB of RAM), and an encrypt round-trip through the app's own worker.
• Real PyInstaller build: exactly one file in dist/, app modules bundled, zero test modules.
• Every site link checked, no 404s; page rendered desktop and mobile, one horizontal-overflow regression found and fixed.

Important

The .exe the site links to is still the May build and does not contain these fixes. It needs a v* tag after merge to trigger the release workflow — that also produces the macOS and Linux binaries, which have never been built. Until then those platforms point at the releases page and the source install rather than at a link that would 404.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cipher-box-file-encrypter	Ready	Preview	Aug 26, 2026 11:07am