# Design
The crate enforces encryption at rest for every value using a simple envelope with XChaCha20-Poly1305. A master key is provided by a pluggable `KeyProvider`, and never written in plaintext. The storage backend is intentionally thin (sled) so the focus stays on key management and crypto hygiene.
## Components
- Crypto: XChaCha20-Poly1305 with versioned envelope. Associated data binds the namespace and key via BLAKE3, so ciphertext cannot be replayed under a different logical key.
- Key providers: abstractions that supply a 32-byte master key. Providers can fetch from OS vaults, wrap with passwords, accept foreign keys, or seal to local files. All providers avoid panics and return structured errors.
- Backend: sled key-value tree for persistence. Values are always encrypted before write and decrypted after read.
- Storage: `EncryptedStore` coordinates the backend, master key, and crypto to offer put/get/delete/flush operations.
## Flow
1. Select a provider. The application decides how to collect secrets or which OS vault to trust.
2. `EncryptedStore::open` asks the provider for the master key (creating it if needed).
3. Values are encrypted with the master key and stored in the backend.
4. Retrieval decrypts using the same key and validates the envelope version and AEAD tag.
## Platform support
Platform vault providers are optional features, compiled only on their target OS. Default builds rely on the file-sealed fallback and sled backend. Mobile platforms should integrate via `ForeignKeyProvider` and supply keys from the native keystore.