CipherMoth v3.0.0

CipherMoth 3.0 encrypts entry metadata and introduces complete, authenticated encrypted backups.

Names, usernames, descriptions and all other user-entered entry contents now live inside authenticated AES-256-GCM documents. This release uses a random 256-bit vault key wrapped under an Argon2id-derived key, with a domain-separated password commitment instead of the old bcrypt verifier. Changing the master password generates a new vault key and re-encrypts every entry and attachment. Clients continue to receive opaque session tokens; the Python core owns the vault key.

Complete encrypted backups

• .cmbackup exports include active entries, Trash, password history, attachment names and bytes, timestamps and settings.
• Backups use Argon2id password protection and authenticated sequential frames. Wrong passwords, tampering, truncation, reordering and substitution are rejected atomically.
• The backup password is the master password at export time. Use that password when restoring, including after a password change or into another vault.
• Restoring into a populated vault merges entries. “Skip” keeps an existing active name; “overwrite” moves the existing entry, history and attachments to Trash before replacing it. Existing Trash entries with matching names and deletion times are skipped. Settings restore only into an empty vault.
• Limits: 1 GiB per complete backup, 1,000,001 frames including the envelope, 64 MiB per entry frame, and 5 MiB per attachment frame. Capacity checks reject supported writes before the vault exceeds backup capacity.
• Exports use a consistent read snapshot, bounded resources and cleanup after errors or cancellation. Check that your browser saved the downloaded file.

Damaged records are isolated and reported in the UI and CLI. Complete backups and master-password rotation refuse damaged records rather than silently omitting them. Recovery is an explicit removal of damaged rows or restoration of an earlier snapshot.

CipherMoth remains SQLite only: two Docker containers and one persistent vault volume. One-click updates remain unavailable; updates are manual.

Breaking change: existing v2.0.0 vaults

3.0 does not open or automatically migrate a v2.0.0 SQLite vault. It refuses the old file unchanged and never silently erases it. New vaults use the new format directly.

A v2.0.0 ZIP export restores active entries only. Old ZIP exports do not include Trash, history, attachments or settings. A raw v2 SQLite snapshot is for recovery with v2; it cannot be opened or imported by v3. Likewise, rolling back to v2 cannot open a v3 vault.

Follow the complete upgrade and rollback guide:

1. Before updating, export a backup from v2.0.0 and separately download any attachments you want to retain. Take an integrity-checked snapshot using ciphermoth-admin snapshot, and keep it for recovery with v2.

2. Set CIPHERMOTH_VERSION=3.0.0 in .env, pull the new images and verify their signatures as documented.

3. With the backend stopped, explicitly preserve the old vault:

   docker compose -f docker-compose.prod.yml pull
   docker compose -f docker-compose.prod.yml stop backend
   docker compose -f docker-compose.prod.yml run --rm backend ciphermoth-admin set-aside
   docker compose -f docker-compose.prod.yml up -d

   set-aside asks for confirmation and moves the old SQLite file and its WAL unchanged into /data/snapshots/set-aside-<time>/. It deletes nothing.

4. Create a new master password in the web UI, then import the v2 ZIP with the password used to create it. Restore downloaded attachments separately and make a new complete .cmbackup.

5. Keep the preserved old vault and snapshot until you no longer need rollback. They retain the old format's plaintext metadata; the guide explains deliberate cleanup and rollback. No automatic deletion runs.

Use the CLI shipped with v3.0.0. For PostgreSQL-era installations, follow the separate manual fresh-install procedure; the old Compose configuration is refused.

Security scope

Entry encryption does not encrypt the entire SQLite file. Counts, timestamps, sizes, Trash membership, attachment relationships, equal-name indexes and timeout settings remain visible. Rollback of a file or row and deletion are not detected. Earlier snapshots and backups retain the password and protection they were created with.

This release has automated verification and code-agent review, not a formal third-party security certification or human cryptographic audit. See the vault and backup format specification, security model, and full changelog.