walletkit-core 0.20.1

Reference implementation for the World ID Protocol. Core functionality to use a World ID.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

//! # Credential Store
//!
//! On-device, consistent, encrypted storage for World ID credentials.
//!
//! The storage layer handles structured storage of all credentials and their
//! associated data (only storage, the semantics of the associated data is the
//! Issuer's responsibility). In addition the storage layer handles encryption
//! and clean up after expiration.
//!
//! ## Components
//!
//! [`crate::storage::CredentialStore`] is the facade exposed to hosts (via `UniFFI`).
//! It owns the account key envelope and two databases:
//!
//! 1. **Vault database (`account.vault.sqlite`)** — authoritative storage for
//!    credentials, associated data blobs, issuer subject blinding factors, and the account
//!    leaf index. Corruption is a hard failure. See [`crate::storage::CredentialVault`].
//! 2. **Cache database (`account.cache.sqlite`)** — non-authoritative, regenerable
//!    entries: Merkle inclusion proof cache, per-account session seed, and nullifier
//!    replay guards. Subject to TTL pruning and can be rebuilt at any time without
//!    correctness loss. See [`crate::storage::CacheDb`].
//!
//! The encrypted-storage primitives beneath these — the sealed key envelope, the
//! `K_device` → `K_intermediate` key hierarchy, sqlite3mc encryption, the
//! cross-process lock, content-addressed blobs, and the threat model are owned by
//! the [`walletkit-db`](https://docs.rs/crate/walletkit-db/latest) crate.
//!
//! ## Keys
//!
//! Both databases are opened with the single `K_intermediate` managed by
//! `walletkit-db`.
//!
//! ## On-disk layout
//!
//! The vault, cache, and lock live under `<root>/worldid/` — see
//! [`crate::storage::StoragePaths`]. The account key envelope (`account_keys.bin`) is
//! written separately through the host's [`crate::storage::AtomicBlobStore`] and its
//! location is host-determined (not necessarily under `worldid/`); backup and
//! deletion must include it.
//!
//! ## Security and privacy properties
//!
//! Encryption, the sealed-envelope threat model, and integrity checks are covered by
//! the `walletkit-db` README.

pub mod cache;
pub mod credential_storage;
pub mod credential_vault;
pub mod error;
#[cfg(all(not(target_arch = "wasm32"), feature = "embed-zkeys"))]
pub mod groth16_cache;
pub mod keys;
pub mod paths;
pub mod traits;
pub mod types;

pub use cache::CacheDb;
pub use credential_storage::CredentialStore;
pub use credential_vault::CredentialVault;
pub use error::{StorageError, StorageResult};
#[cfg(all(not(target_arch = "wasm32"), feature = "embed-zkeys"))]
pub use groth16_cache::cache_embedded_groth16_material;
pub use keys::StorageKeys;
pub use paths::StoragePaths;
pub use traits::{
    AtomicBlobStore, DeviceKeystore, StorageProvider, VaultChangedListener,
};
pub use types::{
    BlobKind, ContentId, CredentialRecord, Nullifier, ReplayGuardKind,
    ReplayGuardResult, RequestId,
};
pub use walletkit_db::{Lock as StorageLock, LockGuard as StorageLockGuard};

pub(crate) const ACCOUNT_KEYS_FILENAME: &str = "account_keys.bin";
pub(crate) const ACCOUNT_KEY_ENVELOPE_AD: &[u8] = b"worldid:account-key-envelope";

#[cfg(test)]
pub(crate) mod tests_utils;