walletkit-core 0.21.6

Reference implementation for the World ID Protocol. Core functionality to use a World ID.
Documentation 
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
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

//! Platform interfaces for credential storage.
//!
//! These traits are the platform integration boundary. The host selects the storage
//! root and provides a [`DeviceKeystore`] and [`AtomicBlobStore`]; core storage code
//! is root-agnostic and consumes a provider-supplied [`StoragePaths`].
//!
//! # Expected platform components
//!
//! - **iOS (Swift):** [`DeviceKeystore`] backed by Keychain / Secure Enclave;
//!   [`AtomicBlobStore`] over the app container filesystem (atomic replace).
//! - **Android (Kotlin):** [`DeviceKeystore`] backed by the Android Keystore;
//!   [`AtomicBlobStore`] over app internal storage (atomic replace).
//! - **Node.js:** file-backed [`DeviceKeystore`] (development; production can use an
//!   OS keystore); [`AtomicBlobStore`] over app internal storage.
//! - **Browser (WASM):** `WebCrypto`-backed [`DeviceKeystore`]; [`AtomicBlobStore`]
//!   over an origin-private storage namespace.

use std::sync::Arc;

use super::error::StorageResult;
use super::paths::StoragePaths;

/// Device keystore interface used to seal and open account keys.
#[uniffi::export(with_foreign)]
pub trait DeviceKeystore: Send + Sync {
    /// Seals plaintext under the device-bound key, authenticating `associated_data`.
    ///
    /// The associated data is not encrypted, but it is integrity-protected as part
    /// of the seal operation. Any mismatch when opening must fail.
    ///
    /// # Errors
    ///
    /// Returns an error if the keystore refuses the operation or the seal fails.
    fn seal(
        &self,
        associated_data: Vec<u8>,
        plaintext: Vec<u8>,
    ) -> StorageResult<Vec<u8>>;

    /// Opens ciphertext under the device-bound key, verifying `associated_data`.
    ///
    /// The same associated data used during sealing must be supplied or the open
    /// operation must fail.
    ///
    /// # Errors
    ///
    /// Returns an error if authentication fails or the keystore cannot open.
    fn open_sealed(
        &self,
        associated_data: Vec<u8>,
        ciphertext: Vec<u8>,
    ) -> StorageResult<Vec<u8>>;
}

/// Atomic blob store for small binary files (e.g., `account_keys.bin`).
#[uniffi::export(with_foreign)]
pub trait AtomicBlobStore: Send + Sync {
    /// Reads the blob at `path`, if present.
    ///
    /// # Errors
    ///
    /// Returns an error if the read fails.
    fn read(&self, path: String) -> StorageResult<Option<Vec<u8>>>;

    /// Writes bytes atomically to `path`.
    ///
    /// # Errors
    ///
    /// Returns an error if the write fails.
    fn write_atomic(&self, path: String, bytes: Vec<u8>) -> StorageResult<()>;

    /// Deletes the blob at `path`.
    ///
    /// # Errors
    ///
    /// Returns an error if the delete fails.
    fn delete(&self, path: String) -> StorageResult<()>;
}

/// Provider responsible for platform-specific storage components and paths.
#[uniffi::export(with_foreign)]
pub trait StorageProvider: Send + Sync {
    /// Returns the device keystore implementation.
    fn keystore(&self) -> Arc<dyn DeviceKeystore>;

    /// Returns the blob store implementation.
    fn blob_store(&self) -> Arc<dyn AtomicBlobStore>;

    /// Returns the storage paths selected by the platform.
    fn paths(&self) -> Arc<StoragePaths>;
}

/// Listener notified when the credential vault contents change and a new
/// backup is needed.
///
/// Register via [`super::CredentialStore::set_vault_changed_listener`]. The
/// callback is delivered on a dedicated background thread to avoid re-entering
/// the `UniFFI` call stack (see `logger.rs` for rationale).
///
/// This is only called when individual credentials are added or removed.
///
/// # Expected usage
///
/// The host app should treat this as a trigger to schedule a backup of the
/// vault. It should contain synchronous actions only.
///
/// # Safety
///
/// **Warning:** implementors **must not** call back into
/// [`super::CredentialStore`] from
/// [`on_vault_changed`](VaultChangedListener::on_vault_changed) — doing so
/// will deadlock.
#[cfg_attr(not(target_arch = "wasm32"), uniffi::export(with_foreign))]
pub trait VaultChangedListener: Send + Sync {
    /// Called after a credential is added or removed.
    fn on_vault_changed(&self);
}

/// Listener notified when credential-activity history changes.
///
/// Register via [`super::CredentialStore::set_activity_changed_listener`]. The
/// callback is delivered on a dedicated background thread to avoid re-entering
/// the `UniFFI` call stack (see `logger.rs` for rationale).
///
/// This is only called when an activity entry is recorded.
///
/// # Expected usage
///
/// The host app should treat this as a trigger to refresh from the store. It
/// is a signal only and is not intended to carry the changed data with it.
///
/// # Safety
///
/// **Warning:** implementors **must not** call back into
/// [`super::CredentialStore`] from
/// [`on_activity_changed`](ActivityChangedListener::on_activity_changed) —
/// doing so will deadlock.
#[cfg_attr(not(target_arch = "wasm32"), uniffi::export(with_foreign))]
pub trait ActivityChangedListener: Send + Sync {
    /// Called after an activity entry is recorded, finalized, or reconciled.
    fn on_activity_changed(&self);
}