Module storage 

Credential storage primitives for World ID v4.

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 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.

Modules

cache

Encrypted cache database for credential storage.

credential_storage

Storage facade implementing the credential storage API.

credential_vault

Encrypted vault database for credential storage.

error

Error types for credential storage components.

keys

Key management for credential storage.

paths

Storage path helpers.

traits

Platform interfaces for credential storage.

types

Public types for credential storage.

Structs

ActivityEntry

A single row of credential activity history.

ActivityMetadata

Aggregate counts over credential activity history.

ActivityQuery

Filtering/sorting options for super::CredentialStore::list_activities.

CacheDb

Encrypted cache database wrapper.

CredentialRecord

In-memory representation of stored credential metadata.

CredentialStore

Concrete storage implementation backed by SQLCipher databases.

CredentialVault

Encrypted vault database wrapper around walletkit_db::Vault.

ReplayGuardResult

Replay guard result.

StorageKeys

In-memory account keys derived from the account key envelope.

StorageLock

File-backed cross-process exclusive lock. See the module docs for what it’s for (and what it isn’t).

StorageLockGuard

Guard that holds an exclusive lock for its lifetime.

StoragePaths

Paths for credential storage artifacts under <root>/worldid.

Enums

ActivityFailureReason

Reasons a proof fails.

ActivityOutcome

Terminal outcome of a proof-share request.

BlobKind

Kind of blob stored in the vault.

ProtocolVersion

Which World ID protocol handled a proof-share request.

ReplayGuardKind

FFI-friendly replay guard result kind.

StorageError

Errors raised by credential storage primitives.

Traits

ActivityChangedListener

Listener notified when credential-activity history changes.

AtomicBlobStore

Atomic blob store for small binary files (e.g., account_keys.bin).

DeviceKeystore

Device keystore interface used to seal and open account keys.

StorageProvider

Provider responsible for platform-specific storage components and paths.

VaultChangedListener

Listener notified when the credential vault contents change and a new backup is needed.

Type Aliases

ContentId

32-byte content identifier for a stored blob.

Nullifier

Nullifier identifier used for replay safety.

RequestId

Request identifier for replay guard.

StorageResult

Result type for storage operations.