Real encryption: AEAD + Ed25519 + OS keychain key storage

Status: Delivered
CAS: CAS-496
Delivered: 2026-04-24
PRs: #166, #167, #168

What’s new

All transaction data stored and synced by Casaconomy is now protected by real authenticated encryption. The previous placeholder (“mock crypto”) has been replaced by XSalsa20-Poly1305 for symmetric encryption and Ed25519 for device signatures, both from the industry-standard libsodium library. Encryption keys are generated once per key identity and stored in the OS keychain (macOS Keychain, eligible for Secure Enclave on Apple Silicon). A compile-time guard prevents debug-mode crypto from ever reaching a release build.

How to use it

There is nothing for the board to configure or interact with — encryption is fully automatic and transparent.

On first launch after this update, Casaconomy generates new keys and stores them in the OS keychain. You may see a single macOS “allow keychain access” prompt; click Always Allow.
Subsequent launches use the cached keys and are no faster than before.
If data is ever tampered with (disk corruption, manual edit, relay attack), decryption will fail with an authentication error rather than silently returning garbage. The app will surface this as an error.

What changed under the hood

New SodiumEncryptionProvider (Rust): encrypts with XSalsa20-Poly1305 (24-byte random nonce prepended to authenticated ciphertext) and signs with Ed25519 detached signatures. Replaced the no-op MockEncryptionProvider.
New KeyStore (Rust): thread-safe, lazily-initialised key manager. On first access per key ID, generates a key and stores it in the OS keychain; subsequent accesses use an in-process Zeroizing<T> cache (key bytes are overwritten on drop).
Two Cargo features: real-crypto (default, production) and mock-crypto (unit tests only). A compile-time assertion panics if mock-crypto is compiled into a release binary.
33 integration tests covering roundtrip encryption, nonce freshness, tamper detection, and Ed25519 sign/verify; Criterion benchmarks for encrypt and sign throughput.

Why we built it

The early phases of Casaconomy used a no-op encryption shim so that the data model, sync transport, and key-ID abstractions could be built and tested without requiring real crypto to be wired up. Phase 3b completes that work: the real libsodium implementation plugs into the same EncryptionProvider trait, so the rest of the codebase is unchanged. With real crypto in place, transaction data is genuinely confidential at rest and in transit, and relay sync requests carry cryptographically verifiable device signatures.

Known limitations / follow-on work

Key rotation is not yet implemented. If a key needs to be revoked (e.g., device lost), existing encrypted data cannot currently be re-keyed without re-importing from CSV.
Multi-device key distribution (sharing group keys across devices) is deferred to the sync transport phase.
The in-debug HashMap keystore means encrypted data written in a debug build is not readable by a release build (different key material). This is intentional and expected during development.
iOS / Windows keychain backends are not yet implemented; the release keychain path currently targets macOS only.