walletkit_core/storage/
mod.rs

1//! # Credential Store
2//!
3//! On-device, consistent, encrypted storage for World ID credentials.
4//!
5//! The storage layer handles structured storage of all credentials and their
6//! associated data (only storage, the semantics of the associated data is the
7//! Issuer's responsibility). In addition the storage layer handles encryption
8//! and clean up after expiration.
9//!
10//! ## Components
11//!
12//! [`crate::storage::CredentialStore`] is the facade exposed to hosts (via `UniFFI`).
13//! It owns the account key envelope and two databases:
14//!
15//! 1. **Vault database (`account.vault.sqlite`)** — authoritative storage for
16//!    credentials, associated data blobs, issuer subject blinding factors, and the account
17//!    leaf index. Corruption is a hard failure. See [`crate::storage::CredentialVault`].
18//! 2. **Cache database (`account.cache.sqlite`)** — non-authoritative, regenerable
19//!    entries: Merkle inclusion proof cache, per-account session seed, and nullifier
20//!    replay guards. Subject to TTL pruning and can be rebuilt at any time without
21//!    correctness loss. See [`crate::storage::CacheDb`].
22//!
23//! The encrypted-storage primitives beneath these — the sealed key envelope, the
24//! `K_device` → `K_intermediate` key hierarchy, sqlite3mc encryption, the
25//! cross-process lock, content-addressed blobs, and the threat model are owned by
26//! the [`walletkit-db`](https://docs.rs/crate/walletkit-db/latest) crate.
27//!
28//! ## Keys
29//!
30//! Both databases are opened with the single `K_intermediate` managed by
31//! `walletkit-db`.
32//!
33//! ## On-disk layout
34//!
35//! The vault, cache, and lock live under `<root>/worldid/` — see
36//! [`crate::storage::StoragePaths`]. The account key envelope (`account_keys.bin`) is
37//! written separately through the host's [`crate::storage::AtomicBlobStore`] and its
38//! location is host-determined (not necessarily under `worldid/`); backup and
39//! deletion must include it.
40//!
41//! ## Security and privacy properties
42//!
43//! Encryption, the sealed-envelope threat model, and integrity checks are covered by
44//! the `walletkit-db` README.
45
46pub mod cache;
47pub mod credential_storage;
48pub mod credential_vault;
49pub mod error;
50pub mod keys;
51pub mod paths;
52pub mod traits;
53pub mod types;
54
55pub use cache::CacheDb;
56pub use credential_storage::CredentialStore;
57pub use credential_vault::CredentialVault;
58pub use error::{StorageError, StorageResult};
59pub use keys::StorageKeys;
60pub use paths::StoragePaths;
61pub use traits::{
62    ActivityChangedListener, AtomicBlobStore, DeviceKeystore, StorageProvider,
63    VaultChangedListener,
64};
65pub use types::{
66    ActivityEntry, ActivityFailureReason, ActivityMetadata, ActivityOutcome,
67    ActivityQuery, BlobKind, ContentId, CredentialRecord, Nullifier, ProtocolVersion,
68    ReplayGuardKind, ReplayGuardResult, RequestId,
69};
70pub use walletkit_db::{Lock as StorageLock, LockGuard as StorageLockGuard};
71
72/// Deletes a closed `SQLite` database and its journal sidecars.
73///
74/// Best effort - logs failed operations but does not return an error.
75pub(crate) fn delete_database_files(path: &std::path::Path) {
76    for path in [
77        path.to_path_buf(),
78        path.with_extension("sqlite-journal"),
79        path.with_extension("sqlite-wal"),
80        path.with_extension("sqlite-shm"),
81    ] {
82        if let Err(err) = delete_database_file(&path) {
83            tracing::error!("Failed to delete database file {}: {err}", path.display());
84        }
85    }
86}
87
88#[cfg(target_arch = "wasm32")]
89fn delete_database_file(path: &std::path::Path) -> Result<(), String> {
90    walletkit_sqlite::opfs::delete_file(path).map_err(|err| err.to_string())
91}
92
93#[cfg(not(target_arch = "wasm32"))]
94fn delete_database_file(path: &std::path::Path) -> Result<(), String> {
95    match std::fs::remove_file(path) {
96        Ok(()) => Ok(()),
97        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(()),
98        Err(err) => Err(err.to_string()),
99    }
100}
101
102/// Installs persistent encrypted browser storage in the current Web Worker.
103///
104/// This must be awaited once before initializing a [`CredentialStore`] on
105/// WASM. The function fails when called outside a supported dedicated worker
106/// or when another browsing context owns the same OPFS SAH pool.
107///
108/// # Errors
109///
110/// Returns [`StorageError::PersistentStorage`] when OPFS setup fails.
111#[cfg(target_arch = "wasm32")]
112#[uniffi::export]
113pub async fn initialize_persistent_storage() -> StorageResult<()> {
114    walletkit_sqlite::opfs::install()
115        .await
116        .map_err(|err| StorageError::PersistentStorage(err.to_string()))
117}
118
119pub(crate) const ACCOUNT_KEYS_FILENAME: &str = "account_keys.bin";
120pub(crate) const ACCOUNT_KEY_ENVELOPE_AD: &[u8] = b"worldid:account-key-envelope";
121
122#[cfg(test)]
123pub(crate) mod tests_utils;
walletkit_core/storage/mod.rs

walletkit_core/storage/
mod.rs
