docs(adr): record the sealed-wallet at-rest encryption design as ADR 0012

[zancas]

Closes nothing yet — this is the documentation half of #2494, which tracks the implementation. This PR preserves the complete sealed-wallet design so the plan survives independent of any session: ADR 0012, five glossary terms, and the .agent-plans stream declaration. Implementation is deliberately deferred.

The design being recorded

The goal is to protect all on-disk wallet data from any reader of the device's storage, with unlock delegated to the consumer (biometrics on mobile, a passphrase on the CLI). A grilling session on 2026-07-21 resolved every branch of the decision tree:

Trust boundary. zingolib defines the sealed wallet-file format and performs all encryption; its entire key interface is a raw 32-byte Unlock Key presented at open time. zingo-mobile guards that key with the platform keystore behind a biometric prompt; zingo-cli derives it from a passphrase. The library never sees a passphrase, a biometric, or a keystore. (Rejected: biometric APIs in the library; trusting OS file encryption alone.)

Envelope encryption. A random inner data-encryption key encrypts the wallet bytes with ChaCha20-Poly1305; the Unlock Key wraps only that inner key, so rekeying rewraps one blob without rewriting the wallet. After open, only the inner key stays in memory (secrecy-held, zeroized on drop), letting the autosave task re-seal without the Unlock Key.

One seal, no tier split. The seal covers the whole file. The background-sync trade-off is the consumer's key-release policy — a keystore key minted "available after first device unlock" preserves background sync; "require per-use authentication" trades it for strength. (Rejected: a two-tier sync/spend format, which doubles serialization, API, and save paths for a knob the keystore already provides.)

Opt-in, sticky, reversible. Plaintext remains legitimate; a sealed file carries a magic header with format version and KDF identifier, and anything else parses as legacy. Once sealed, every save re-seals and only an explicit unseal goes back. (Rejected: mandatory sealing; irreversible sealing — the seed restores anywhere, so irreversibility only bricks files.)

Four operations, no mid-session lock. Open, seal(key), rekey(new_key), unseal(key). No locked-while-alive state: the zecwallet-era lock poisoned every method with a key-absent error path, and dropping the client reaches the same security state.

CLI KDF. PBKDF2 from the in-tree crate (HMAC-SHA-512, hundreds of thousands of iterations, per-wallet salt in the header), honestly documented as weaker than argon2, which would need a dependency ratification; the header's KDF identifier permits a later argon2 format without a break. The mobile path never touches a KDF.

No new dependencies. Everything builds from crates already in Cargo.lock: chacha20poly1305, blake2b_simd, getrandom, secrecy, zeroize, pbkdf2.

The rest of the disk. The wallet file is the only artifact zingolib writes to the wallet directory. Nym mixnet state stays off disk (new_ephemeral()), pinned as an invariant by the ADR. The debug log is starved of secrets rather than encrypted, and file logging stays off by default for connected use.

Contents

• docs/adr/0012-sealed-wallet-at-rest-encryption.md — the decision record with the rejected alternatives.
• zingolib/CONTEXT.md — glossary entries for Sealed Wallet, Unlock Key, Unlock, Seal / Unseal, and Rekey in the Persistence section.
• .agent-plans/sealed-wallet.md — the stream declaration and file claims for the eventual implementation.

Caveats for review

The ADR is numbered 0012 while dev holds ADRs through 0008: numbers 0009–0011 belong to the in-flight nym stream, which this ADR references (ADR 0011 and the new_ephemeral() construction do not exist on dev yet). If the nym stream's docs land first this merges cleanly; if this merges first, the references are forward-looking until it does.

🤖 Generated with Claude Code