# walletkit-sqlite
Low-level encrypted SQLite support for WalletKit.
The crate provides safe Rust wrappers for connections, statements,
transactions, values, and sqlite3mc cipher operations. On native targets it
builds and statically links sqlite3mc; on WASM it delegates to
`sqlite-wasm-rs` and stores encrypted database pages in OPFS through the
SAH-pool VFS.
Browser hosts must run WalletKit in a dedicated worker and await
`walletkit_core::storage::initialize_persistent_storage()` before initializing
the credential store. The page key remains in Rust memory for the unlocked
store lifetime; persistent connections fail closed until the encrypted OPFS
VFS is installed.
## Native SQLite isolation
Native apps may also link system SQLite or another SQLite distribution. The
bundled sqlite3mc API has internal C linkage, and Rust uses only the
`walletkit_sqlite3_*` wrappers in `src/native_sqlite.c`. This prevents link
order from substituting the host engine for WalletKit's encrypted engine or
replacing the host engine with WalletKit's copy. New native FFI functions must
add a matching prefixed wrapper; visibility attributes alone do not isolate
symbols when linking static archives.
## Encryption format compatibility
WalletKit leaves the first 32 bytes of every encrypted database header in
plaintext on all targets. The visible header contains SQLite format metadata;
database pages and application data remain encrypted with the supplied
WalletKit key.
On the first successful read-write open, WalletKit migrates databases created
with the earlier fully encrypted header format to the plaintext-header format.
It also preserves and encrypts records if a host previously caused WalletKit to
create a plaintext database. Migration checkpoints any existing WAL, switches
temporarily to a rollback journal because sqlite3mc cannot rekey in WAL mode,
and restores the target's normal journal policy afterward.
This format migration is forward-only. WalletKit versions that predate the
32-byte plaintext header cannot open a newly created or migrated database. To
support application rollback, preserve a compatible database backup before
upgrading.