Skip to content

Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.

Add Rust bindings for manifest-v1 materialize/canonicalize (#2159)

Leendert de Borstaefa3ed68e14
diff --git a/core/rust/Cargo.lock b/core/rust/Cargo.lock
index fce11cd03..dc0d2c218 100644
--- a/core/rust/Cargo.lock
+++ b/core/rust/Cargo.lock
@@ -2,14 +2,22 @@
# It is not intended for manual editing.
version = 4
+[[package]]
+name = "adler2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
+
[[package]]
name = "aliasvault-core"
version = "0.31.0"
dependencies = [
"argon2",
+ "base64",
"chrono",
"console_error_panic_hook",
"digest",
+ "flate2",
"getrandom",
"num-bigint",
"rand",
@@ -139,6 +147,12 @@ version = "1.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
+[[package]]
+name = "base64"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
+
[[package]]
name = "base64ct"
version = "1.8.3"
@@ -306,6 +320,15 @@ dependencies = [
"libc",
]
+[[package]]
+name = "crc32fast"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9481c1c90cbf2ac953f07c8d4a58aa3945c425b7185c9154d67a65e4230da511"
+dependencies = [
+ "cfg-if",
+]
+
[[package]]
name = "crypto-common"
version = "0.1.7"
@@ -327,6 +350,16 @@ dependencies = [
"subtle",
]
+[[package]]
+name = "flate2"
+version = "1.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c"
+dependencies = [
+ "crc32fast",
+ "miniz_oxide",
+]
+
[[package]]
name = "fs-err"
version = "2.11.0"
@@ -451,6 +484,16 @@ version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
+[[package]]
+name = "miniz_oxide"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
[[package]]
name = "nom"
version = "7.1.3"
@@ -699,6 +742,12 @@ dependencies = [
"digest",
]
+[[package]]
+name = "simd-adler32"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "703d5c7ef118737c72f1af64ad2f6f8c5e1921f818cdcb97b8fe6fc69bf66214"
+
[[package]]
name = "siphasher"
version = "0.3.11"
diff --git a/core/rust/Cargo.toml b/core/rust/Cargo.toml
index 49d1092fa..703496eaf 100644
--- a/core/rust/Cargo.toml
+++ b/core/rust/Cargo.toml
@@ -48,6 +48,12 @@ getrandom = { version = "0.3", features = ["wasm_js"] }
# Argon2 password hashing
argon2 = "0.5"
+# gzip compression for the vault_codec packaged format
+flate2 = { version = "1.0", default-features = false, features = ["rust_backend"] }
+
+# base64 for vault_codec blob byte transport + ciphertext hashing
+base64 = "0.22"
+
# UniFFI for Swift/Kotlin bindings (optional)
# Note: Don't add "cli" feature here - it pulls in heavy bindgen dependencies
# The uniffi-cli feature enables CLI separately for the uniffi-bindgen binary only
diff --git a/core/rust/src/credential_matcher/mod.rs b/core/rust/src/credential_matcher/mod.rs
index 606e898b4..017136618 100644
--- a/core/rust/src/credential_matcher/mod.rs
+++ b/core/rust/src/credential_matcher/mod.rs
@@ -265,8 +265,8 @@ pub fn filter_credentials(input: CredentialMatcherInput) -> CredentialMatcherOut
// from ONLY the root domain (no subdomains, no path/query) against item names.
// Same anti-phishing rule: only credentials with NO URLs are eligible.
// IMPORTANT: Extract words only from root domain to avoid false positives:
- // - outlook.office.com → extract from "office.com" only (not "outlook")
- // - www.dumpert.nl → extract from "dumpert.nl" only (not "www")
+ // - outlook.office.com > extract from "office.com" only (not "outlook")
+ // - www.dumpert.nl > extract from "dumpert.nl" only (not "www")
// - Don't match "mail" from "/mail/" path
// ═══════════════════════════════════════════════════════════════════════════
let root_domain = extract_root_domain(&current_domain_info.domain);
diff --git a/core/rust/src/credential_matcher/tests.rs b/core/rust/src/credential_matcher/tests.rs
index e2cf0ef78..bf43d53d7 100644
--- a/core/rust/src/credential_matcher/tests.rs
+++ b/core/rust/src/credential_matcher/tests.rs
@@ -400,7 +400,7 @@ fn test_empty_url() {
}
/// Test that the default cap (DEFAULT_MAX_RESULTS = 10) bounds the output.
-/// Twelve candidates → exactly 10 returned.
+/// Twelve candidates > exactly 10 returned.
#[test]
fn test_default_max_results_caps_at_ten() {
let credentials: Vec<Credential> = (1..=12)
diff --git a/core/rust/src/ffi.rs b/core/rust/src/ffi.rs
index 657428a1f..9820e8919 100644
--- a/core/rust/src/ffi.rs
+++ b/core/rust/src/ffi.rs
@@ -190,6 +190,150 @@ fn create_error_response(message: &str) -> *mut c_char {
string_to_c_char(error_json)
}
+// ═══════════════════════════════════════════════════════════════════════════════
+// Vault Codec FFI Functions (manifest-v1 storage format)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/// Read a JSON c-string argument, returning an error response on null / invalid UTF-8.
+macro_rules! ffi_read_str {
+ ($ptr:expr, $name:literal) => {{
+ if $ptr.is_null() {
+ return create_error_response(concat!("Null pointer argument: ", $name));
+ }
+ match CStr::from_ptr($ptr).to_str() {
+ Ok(s) => s,
+ Err(_) => return create_error_response(concat!("Invalid UTF-8 in ", $name)),
+ }
+ }};
+}
+
+/// Wrap a `fn(&str) -> VaultResult<String>` codec entry point as a C FFI function.
+unsafe fn codec_json_ffi(
+ input_json: *const c_char,
+ arg_name: &'static str,
+ f: impl Fn(&str) -> crate::error::VaultResult<String>,
+) -> *mut c_char {
+ if input_json.is_null() {
+ return create_error_response(&format!("Null pointer argument: {}", arg_name));
+ }
+ let c_str = match CStr::from_ptr(input_json).to_str() {
+ Ok(s) => s,
+ Err(_) => return create_error_response(&format!("Invalid UTF-8 in {}", arg_name)),
+ };
+ match f(c_str) {
+ Ok(json) => string_to_c_char(json),
+ Err(e) => create_error_response(&format!("vault_codec error: {}", e)),
+ }
+}
+
+/// Canonicalize normalized tables. Input: `CanonicalizeInput` JSON. Output: `CanonicalizedVault` JSON.
+///
+/// # Safety
+/// `input_json` must be a valid null-terminated C string; free the result with `free_string`.
+#[no_mangle]
+pub unsafe extern "C" fn vault_codec_canonicalize_from_sqlite_ffi(input_json: *const c_char) -> *mut c_char {
+ codec_json_ffi(input_json, "input_json", crate::vault_codec::canonicalize_from_sqlite_json)
+}
+
+/// Materialize manifest + metadata. Input: `MaterializeInput` JSON. Output: `MaterializedTables` JSON.
+///
+/// # Safety
+/// `input_json` must be a valid null-terminated C string; free the result with `free_string`.
+#[no_mangle]
+pub unsafe extern "C" fn vault_codec_materialize_as_sqlite_ffi(input_json: *const c_char) -> *mut c_char {
+ codec_json_ffi(input_json, "input_json", crate::vault_codec::materialize_as_sqlite_json)
+}
+
+/// Build a single data bucket. Input: `{ category, tables }` JSON. Output: `DataBucket` JSON.
+///
+/// # Safety
+/// `input_json` must be a valid null-terminated C string; free the result with `free_string`.
+#[no_mangle]
+pub unsafe extern "C" fn vault_codec_extract_bucket_ffi(input_json: *const c_char) -> *mut c_char {
+ codec_json_ffi(input_json, "input_json", crate::vault_codec::extract_bucket_json)
+}
+
+/// Validate a manifest. Input: `Manifest` JSON. Output: `ValidationResult` JSON.
+///
+/// # Safety
+/// `input_json` must be a valid null-terminated C string; free the result with `free_string`.
+#[no_mangle]
+pub unsafe extern "C" fn vault_codec_validate_manifest_ffi(input_json: *const c_char) -> *mut c_char {
+ codec_json_ffi(input_json, "input_json", crate::vault_codec::validate_manifest_json)
+}
+
+/// Validate a data bucket. Input: `DataBucket` JSON. Output: `ValidationResult` JSON.
+///
+/// # Safety
+/// `input_json` must be a valid null-terminated C string; free the result with `free_string`.
+#[no_mangle]
+pub unsafe extern "C" fn vault_codec_validate_data_bucket_ffi(input_json: *const c_char) -> *mut c_char {
+ codec_json_ffi(input_json, "input_json", crate::vault_codec::validate_data_bucket_json)
+}
+
+/// Blob upload diff. Input: `{ "manifest": <manifest>, "knownHashes": [..] }`. Output: JSON array of hashes.
+///
+/// # Safety
+/// `input_json` must be a valid null-terminated C string; free the result with `free_string`.
+#[no_mangle]
+pub unsafe extern "C" fn vault_codec_which_blobs_to_upload_ffi(input_json: *const c_char) -> *mut c_char {
+ codec_json_ffi(input_json, "input_json", crate::vault_codec::which_blobs_to_upload_json)
+}
+
+/// Generate a fresh per-user salt (lowercase hex).
+///
+/// # Safety
+/// Free the result with `free_string`.
+#[no_mangle]
+pub extern "C" fn vault_codec_generate_user_salt_ffi() -> *mut c_char {
+ string_to_c_char(crate::vault_codec::generate_user_salt())
+}
+
+/// SHA-256 (lowercase hex) of a base64 ciphertext string.
+///
+/// # Safety
+/// `base64_ciphertext` must be a valid null-terminated C string; free the result with `free_string`.
+#[no_mangle]
+pub unsafe extern "C" fn vault_codec_compute_ciphertext_hash_ffi(base64_ciphertext: *const c_char) -> *mut c_char {
+ let s = ffi_read_str!(base64_ciphertext, "base64_ciphertext");
+ string_to_c_char(crate::vault_codec::compute_ciphertext_hash(s))
+}
+
+/// Pack a payload JSON string. Output: base64 of gzip(envelope{contentHash, payload}). The caller
+/// base64-decodes, then encrypts.
+///
+/// # Safety
+/// `payload_json` must be a valid null-terminated C string; free the result with `free_string`.
+#[no_mangle]
+pub unsafe extern "C" fn vault_codec_pack_payload_ffi(payload_json: *const c_char) -> *mut c_char {
+ use base64::engine::general_purpose::STANDARD as BASE64;
+ use base64::Engine;
+ let s = ffi_read_str!(payload_json, "payload_json");
+ match crate::vault_codec::pack_payload(s) {
+ Ok(bytes) => string_to_c_char(BASE64.encode(bytes)),
+ Err(e) => create_error_response(&format!("pack_payload error: {}", e)),
+ }
+}
+
+/// Unpack a payload supplied as base64 of the decrypted bytes. Output: payload JSON string.
+///
+/// # Safety
+/// `base64_plain_bytes` must be a valid null-terminated C string; free the result with `free_string`.
+#[no_mangle]
+pub unsafe extern "C" fn vault_codec_unpack_payload_ffi(base64_plain_bytes: *const c_char) -> *mut c_char {
+ use base64::engine::general_purpose::STANDARD as BASE64;
+ use base64::Engine;
+ let s = ffi_read_str!(base64_plain_bytes, "base64_plain_bytes");
+ let bytes = match BASE64.decode(s) {
+ Ok(b) => b,
+ Err(e) => return create_error_response(&format!("invalid base64: {}", e)),
+ };
+ match crate::vault_codec::unpack_payload(&bytes) {
+ Ok(json) => string_to_c_char(json),
+ Err(e) => create_error_response(&format!("unpack_payload error: {}", e)),
+ }
+}
+
// ═══════════════════════════════════════════════════════════════════════════════
// SRP (Secure Remote Password) FFI Functions
// ═══════════════════════════════════════════════════════════════════════════════
diff --git a/core/rust/src/lib.rs b/core/rust/src/lib.rs
index a0a9676b8..12e1ec48d 100644
--- a/core/rust/src/lib.rs
+++ b/core/rust/src/lib.rs
@@ -12,6 +12,7 @@
pub mod error;
pub mod vault_merge;
+pub mod vault_codec;
pub mod vault_pruner;
pub mod credential_matcher;
pub mod password_generator;
@@ -22,6 +23,13 @@ pub use vault_merge::{
merge_vaults, MergeInput, MergeOutput, MergeStats, SqlStatement, TableData,
SYNCABLE_TABLE_NAMES,
};
+pub use vault_codec::{
+ compute_ciphertext_hash, canonicalize_from_sqlite,
+ extract_bucket, generate_user_salt, unpack_payload, materialize_as_sqlite, pack_payload,
+ validate_manifest, validate_data_bucket, which_blobs_to_upload, BlobEntry,
+ CanonicalizeInput, CanonicalizedVault, CodecRecord, CodecTableData, DataBucket, Manifest,
+ MaterializeInput, MaterializedTables, ValidationResult,
+};
pub use vault_pruner::{
prune_vault, PruneInput, PruneOutput, PruneStats,
};
diff --git a/core/rust/src/uniffi_api.rs b/core/rust/src/uniffi_api.rs
index c52e2fc67..e28e2c8c7 100644
--- a/core/rust/src/uniffi_api.rs
+++ b/core/rust/src/uniffi_api.rs
@@ -148,6 +148,73 @@ pub fn get_diceware_languages() -> Vec<String> {
crate::password_generator::available_languages()
}
+// ═══════════════════════════════════════════════════════════════════════════════
+// Vault Codec Functions (manifest-v1 storage format) — JSON-string in/out.
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/// Canonicalize normalized tables into manifest + metadata + blob map.
+/// Input: `CanonicalizeInput` JSON. Output: `CanonicalizedVault` JSON.
+#[uniffi::export]
+pub fn vault_codec_canonicalize_from_sqlite(input_json: String) -> Result<String, VaultError> {
+ crate::vault_codec::canonicalize_from_sqlite_json(&input_json)
+}
+
+/// Materialize manifest + metadata into the table set the platform inserts.
+/// Input: `MaterializeInput` JSON. Output: `MaterializedTables` JSON.
+#[uniffi::export]
+pub fn vault_codec_materialize_as_sqlite(input_json: String) -> Result<String, VaultError> {
+ crate::vault_codec::materialize_as_sqlite_json(&input_json)
+}
+
+/// Build a single data bucket. Input: `{ category, tables }` JSON. Output: `DataBucket` JSON.
+#[uniffi::export]
+pub fn vault_codec_extract_bucket(input_json: String) -> Result<String, VaultError> {
+ crate::vault_codec::extract_bucket_json(&input_json)
+}
+
+/// Generate a fresh 32-byte per-user salt (lowercase hex).
+#[uniffi::export]
+pub fn vault_codec_generate_user_salt() -> String {
+ crate::vault_codec::generate_user_salt()
+}
+
+/// Pack a payload JSON string into gzip(envelope{contentHash, payload}). The caller encrypts the result.
+#[uniffi::export]
+pub fn vault_codec_pack_payload(payload_json: String) -> Result<Vec<u8>, VaultError> {
+ crate::vault_codec::pack_payload(&payload_json)
+}
+
+/// Unpack a (decrypted) payload: gunzip > verify content hash > return payload JSON string.
+#[uniffi::export]
+pub fn vault_codec_unpack_payload(plain_bytes: Vec<u8>) -> Result<String, VaultError> {
+ crate::vault_codec::unpack_payload(&plain_bytes)
+}
+
+/// Structurally validate a manifest. Input: `Manifest` JSON. Output: `ValidationResult` JSON.
+#[uniffi::export]
+pub fn vault_codec_validate_manifest(manifest_json: String) -> Result<String, VaultError> {
+ crate::vault_codec::validate_manifest_json(&manifest_json)
+}
+
+/// Validate a data bucket. Input: `DataBucket` JSON. Output: `ValidationResult` JSON.
+#[uniffi::export]
+pub fn vault_codec_validate_data_bucket(data_bucket_json: String) -> Result<String, VaultError> {
+ crate::vault_codec::validate_data_bucket_json(&data_bucket_json)
+}
+
+/// SHA-256 (lowercase hex) of a base64 ciphertext string.
+#[uniffi::export]
+pub fn vault_codec_compute_ciphertext_hash(base64_ciphertext: String) -> String {
+ crate::vault_codec::compute_ciphertext_hash(&base64_ciphertext)
+}
+
+/// Return the manifest's referenced blob hashes not present in `knownHashes`.
+/// Input: `{ "manifest": <manifest>, "knownHashes": [..] }`.
+#[uniffi::export]
+pub fn vault_codec_which_blobs_to_upload(input_json: String) -> Result<String, VaultError> {
+ crate::vault_codec::which_blobs_to_upload_json(&input_json)
+}
+
// ═══════════════════════════════════════════════════════════════════════════════
// SRP (Secure Remote Password) Functions
// ═══════════════════════════════════════════════════════════════════════════════
diff --git a/core/rust/src/vault_codec/canonicalize.rs b/core/rust/src/vault_codec/canonicalize.rs
new file mode 100644
index 000000000..839a23d98
--- /dev/null
+++ b/core/rust/src/vault_codec/canonicalize.rs
@@ -0,0 +1,122 @@
+//! Canonicalize a SQLite source dataset into the canonical vault manifest-v1 persisted representation:
+//! normalized `CodecTableData[]` + salt > manifest + data buckets + content-addressed blob map.
+//!
+//! The input rows are already JSON-normalized by the platform read. Every SQLite byte column
+//! arrives as `{ "__b64": <base64> }`. This module applies the *format* rules:
+//! - each bucketed table (see `BUCKET_TABLES`; `Settings` today) is split out into its data bucket;
+//! - skip-tables are dropped;
+//! - the two blob columns (`Logos.FileData`, `Attachments.Blob`) have their bytes extracted into a
+//! content-addressed blob map (hash = `sha256(salt ‖ bytes)`) and the cell replaced with
+//! `{ "__blobRef": hash, "__blobKind": kind }`;
+//! - every other column (including non-blob `{ "__b64" }` inline bytes) is copied verbatim.
+
+use std::collections::HashMap;
+
+use base64::engine::general_purpose::STANDARD as BASE64;
+use base64::Engine;
+use serde_json::json;
+
+use super::hash::salted_blob_hash;
+use super::manifest::{BlobEntry, CanonicalizeInput, CanonicalizedVault, DataBucket, Manifest, CodecRecord};
+use super::types::{blob_spec_for, bucket_categories, bucket_category_for, is_skip_table, SCHEMA_VERSION};
+use crate::error::VaultResult;
+
+/// Canonicalize normalized tables into the split resources: the manifest, one data bucket per declared
+/// category (see [`BUCKET_TABLES`](super::types::BUCKET_TABLES)), and the content-addressed blob map.
+pub fn canonicalize_from_sqlite(input: CanonicalizeInput) -> VaultResult<CanonicalizedVault> {
+ let mut blobs: HashMap<String, BlobEntry> = HashMap::new();
+ let mut manifest_tables: HashMap<String, Vec<CodecRecord>> = HashMap::new();
+
+ // category > (table > rows). Seed every declared bucket so the emitted set is stable even when a
+ // bucket has no rows yet (e.g. empty tables).
+ let mut bucketed: HashMap<String, HashMap<String, Vec<CodecRecord>>> = HashMap::new();
+ for category in bucket_categories() {
+ bucketed.insert(category.to_string(), HashMap::new());
+ }
+
+ for table in &input.tables {
+ let name = table.name.as_str();
+ if is_skip_table(name) {
+ continue;
+ }
+
+ // Bucketed table: carried verbatim in its bucket (bucketed tables own no blob columns today).
+ if let Some(category) = bucket_category_for(name) {
+ bucketed
+ .get_mut(category)
+ .expect("declared bucket category is seeded above")
+ .insert(name.to_string(), table.records.clone());
+ continue;
+ }
+
+ // Manifest table: extract any blob column into the content-addressed map.
+ let blob_spec = blob_spec_for(name);
+ let mut out_rows: Vec<CodecRecord> = Vec::with_capacity(table.records.len());
+ for row in &table.records {
+ let mut row = row.clone();
+ if let Some((_, blob_col, kind)) = blob_spec {
+ let extracted = extract_blob_cell(row.get(*blob_col), &input.user_salt, kind, &mut blobs);
+ row.insert((*blob_col).to_string(), extracted);
+ }
+ out_rows.push(row);
+ }
+ manifest_tables.insert(name.to_string(), out_rows);
+ }
+
+ let manifest = Manifest {
+ schema_version: SCHEMA_VERSION,
+ migration_id: input.migration_id,
+ version: input.version,
+ user_salt: input.user_salt,
+ canonicalized_at: input.canonicalized_at,
+ tables: manifest_tables,
+ extra: HashMap::new(),
+ };
+
+ // Deterministic bucket order (HashMap iteration is unordered) so canonicalize is reproducible.
+ let mut data_buckets: Vec<DataBucket> = bucketed
+ .into_iter()
+ .map(|(category, tables)| DataBucket::new(category, tables))
+ .collect();
+ data_buckets.sort_by(|a, b| a.category.cmp(&b.category));
+
+ Ok(CanonicalizedVault {
+ manifest,
+ data_buckets,
+ blobs,
+ })
+}
+
+/// Extract a blob column cell: if it holds non-empty `{ "__b64" }` bytes, hash + register them and
+/// return a blob-ref; otherwise return JSON null.
+fn extract_blob_cell(
+ cell: Option<&serde_json::Value>,
+ user_salt: &str,
+ kind: &str,
+ blobs: &mut HashMap<String, BlobEntry>,
+) -> serde_json::Value {
+ let b64 = match cell.and_then(|v| v.get("__b64")).and_then(|v| v.as_str()) {
+ Some(s) => s,
+ None => return serde_json::Value::Null,
+ };
+
+ let bytes = match BASE64.decode(b64) {
+ Ok(b) if !b.is_empty() => b,
+ _ => return serde_json::Value::Null,
+ };
+
+ let hash = salted_blob_hash(&bytes, user_salt);
+ blobs.entry(hash.clone()).or_insert_with(|| BlobEntry {
+ kind: kind.to_string(),
+ bytes_base64: b64.to_string(),
+ });
+
+ json!({ "__blobRef": hash, "__blobKind": kind })
+}
+
+/// Build a single data bucket for `category` from its already-normalized tables (name > rows).
+/// The bucket-only push path (a bucket changed but the manifest didn't). Input rows are
+/// already normalized by the platform read logic.
+pub fn extract_bucket(category: String, tables: HashMap<String, Vec<CodecRecord>>) -> DataBucket {
+ DataBucket::new(category, tables)
+}
diff --git a/core/rust/src/vault_codec/compress.rs b/core/rust/src/vault_codec/compress.rs
new file mode 100644
index 000000000..ff0bbe2a1
--- /dev/null
+++ b/core/rust/src/vault_codec/compress.rs
@@ -0,0 +1,43 @@
+//! gzip compress / gunzip decompress.
+
+use std::io::{Read, Write};
+
+use flate2::read::GzDecoder;
+use flate2::write::GzEncoder;
+use flate2::Compression;
+
+use crate::error::{VaultError, VaultResult};
+
+/// gzip the given bytes.
+pub fn gzip(bytes: &[u8]) -> VaultResult<Vec<u8>> {
+ let mut encoder = GzEncoder::new(Vec::new(), Compression::default());
+ encoder
+ .write_all(bytes)
+ .map_err(|e| VaultError::General(format!("gzip write failed: {}", e)))?;
+ encoder
+ .finish()
+ .map_err(|e| VaultError::General(format!("gzip finish failed: {}", e)))
+}
+
+/// Decompress gzipped bytes into a UTF-8 string.
+pub fn gunzip_to_string(bytes: &[u8]) -> VaultResult<String> {
+ let mut decoder = GzDecoder::new(bytes);
+ let mut out = String::new();
+ decoder
+ .read_to_string(&mut out)
+ .map_err(|e| VaultError::General(format!("gunzip failed: {}", e)))?;
+ Ok(out)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn gzip_roundtrips() {
+ let text = r#"{"hello":"world","n":42}"#;
+ let gz = gzip(text.as_bytes()).unwrap();
+ assert_eq!(&gz[0..2], &[0x1f, 0x8b]);
+ assert_eq!(gunzip_to_string(&gz).unwrap(), text);
+ }
+}
diff --git a/core/rust/src/vault_codec/hash.rs b/core/rust/src/vault_codec/hash.rs
new file mode 100644
index 000000000..34c302851
--- /dev/null
+++ b/core/rust/src/vault_codec/hash.rs
@@ -0,0 +1,149 @@
+//! Hashing + canonical JSON for the vault_codec format.
+//!
+//! ## Why canonical JSON lives here
+//!
+//! Each encrypted blob embeds an integrity envelope `{ schemaVersion, contentHash, payload }` where
+//! `contentHash = sha256(canonical(payload))`. JSON serialization is NOT canonical across languages
+//! (key order, number formatting, whitespace, unicode escaping all differ), so a manifest written by
+//! one platform and re-hashed by another would fail integrity even when byte-identical. This module is
+//! the single canonical-serialization contract every binding reproduces.
+//!
+//! [`canonical_json`] is intentionally byte-compatible with the original `VaultIntegrity.ts`
+//! `canonicalize()`:
+//! - object keys sorted ascending, recursively;
+//! - arrays kept in order;
+//! - primitives serialized exactly as `JSON.stringify` would (serde_json matches JS for the
+//! escaping + integer cases that occur in vault data).
+
+use sha2::{Digest, Sha256};
+
+/// Lowercase hex of a byte slice. Matches the browser extension's lowercase hashing.
+pub fn bytes_to_hex(bytes: &[u8]) -> String {
+ let mut s = String::with_capacity(bytes.len() * 2);
+ for b in bytes {
+ s.push_str(&format!("{:02x}", b));
+ }
+ s
+}
+
+/// Decode a lowercase/uppercase hex string into bytes. Returns `None` on malformed input.
+pub fn hex_to_bytes(hex: &str) -> Option<Vec<u8>> {
+ if hex.len() % 2 != 0 {
+ return None;
+ }
+ let mut out = Vec::with_capacity(hex.len() / 2);
+ let bytes = hex.as_bytes();
+ let mut i = 0;
+ while i < bytes.len() {
+ let hi = (bytes[i] as char).to_digit(16)?;
+ let lo = (bytes[i + 1] as char).to_digit(16)?;
+ out.push(((hi << 4) | lo) as u8);
+ i += 2;
+ }
+ Some(out)
+}
+
+/// SHA-256 of arbitrary bytes, returned as lowercase hex.
+pub fn sha256_hex(bytes: &[u8]) -> String {
+ let mut hasher = Sha256::new();
+ hasher.update(bytes);
+ bytes_to_hex(&hasher.finalize())
+}
+
+/// Canonicalize a JSON value into a stable string for hashing.
+///
+/// Serializes JSON with object keys sorted recursively, arrays kept in order,
+// and primitives serialized using `serde_json::to_string` for string-escaping
+// and integer values present in vault data.
+pub fn canonical_json(value: &serde_json::Value) -> String {
+ match value {
+ serde_json::Value::Object(map) => {
+ let mut keys: Vec<&String> = map.keys().collect();
+ keys.sort();
+ let mut s = String::from("{");
+ for (i, k) in keys.iter().enumerate() {
+ if i > 0 {
+ s.push(',');
+ }
+ // Key rendered the same way JSON.stringify renders a string key.
+ s.push_str(&serde_json::to_string(k).unwrap_or_else(|_| String::from("\"\"")));
+ s.push(':');
+ s.push_str(&canonical_json(&map[*k]));
+ }
+ s.push('}');
+ s
+ }
+ serde_json::Value::Array(arr) => {
+ let mut s = String::from("[");
+ for (i, v) in arr.iter().enumerate() {
+ if i > 0 {
+ s.push(',');
+ }
+ s.push_str(&canonical_json(v));
+ }
+ s.push(']');
+ s
+ }
+ // Strings, numbers, booleans, null: serde_json's output matches JSON.stringify here.
+ other => serde_json::to_string(other).unwrap_or_else(|_| String::from("null")),
+ }
+}
+
+/// Content hash = `sha256(canonical(payload))`, lowercase hex.
+pub fn content_hash(value: &serde_json::Value) -> String {
+ sha256_hex(canonical_json(value).as_bytes())
+}
+
+/// Per-user salted blob hash `sha256(salt_bytes ‖ plaintext_bytes)`, lowercase hex.
+///
+/// `user_salt` is a hex string (decoded to bytes before concatenation).
+/// Per-user salt means the server cannot enumerate which blobs a user has across users.
+pub fn salted_blob_hash(bytes: &[u8], user_salt: &str) -> String {
+ let salt_bytes = hex_to_bytes(user_salt).unwrap_or_default();
+ let mut hasher = Sha256::new();
+ hasher.update(&salt_bytes);
+ hasher.update(bytes);
+ bytes_to_hex(&hasher.finalize())
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use serde_json::json;
+
+ #[test]
+ fn canonical_sorts_keys_recursively() {
+ let v = json!({ "b": 1, "a": { "d": 2, "c": 3 } });
+ assert_eq!(canonical_json(&v), r#"{"a":{"c":3,"d":2},"b":1}"#);
+ }
+
+ #[test]
+ fn canonical_keeps_array_order() {
+ let v = json!([3, 1, 2]);
+ assert_eq!(canonical_json(&v), "[3,1,2]");
+ }
+
+ #[test]
+ fn canonical_matches_js_string_escaping() {
+ // Control chars use short forms; quotes/backslashes escaped; non-ascii left raw.
+ let v = json!("a\"b\\c\nd\té");
+ assert_eq!(canonical_json(&v), "\"a\\\"b\\\\c\\nd\\té\"");
+ }
+
+ #[test]
+ fn hex_roundtrip() {
+ let bytes = vec![0x00u8, 0x1f, 0xab, 0xff];
+ let hex = bytes_to_hex(&bytes);
+ assert_eq!(hex, "001fabff");
+ assert_eq!(hex_to_bytes(&hex).unwrap(), bytes);
+ }
+
+ #[test]
+ fn salted_hash_is_stable() {
+ // Pinned vector: salt "00ff", bytes [1,2,3].
+ let h = salted_blob_hash(&[1, 2, 3], "00ff");
+ // sha256(00 ff 01 02 03)
+ assert_eq!(h, sha256_hex(&[0x00, 0xff, 0x01, 0x02, 0x03]));
+ assert_eq!(h.len(), 64);
+ }
+}
diff --git a/core/rust/src/vault_codec/manifest.rs b/core/rust/src/vault_codec/manifest.rs
new file mode 100644
index 000000000..f99a1699b
--- /dev/null
+++ b/core/rust/src/vault_codec/manifest.rs
@@ -0,0 +1,116 @@
+//! Serde structs for the manifest-v1 data format shapes.
+
+use std::collections::HashMap;
+
+use serde::{Deserialize, Serialize};
+
+use super::types::SCHEMA_VERSION;
+
+/// A codec record is a map of column names to JSON values.
+pub type CodecRecord = HashMap<String, serde_json::Value>;
+
+/// Manifest-v1 manifest
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Manifest {
+ pub schema_version: u32,
+ /// Latest EF migration ID.
+ pub migration_id: String,
+ /// Human-readable data-model version label (e.g. "2.0.0").
+ pub version: String,
+ /// Per-user salt for blob hashing (hex).
+ pub user_salt: String,
+ /// Timestamp when this canonical snapshot was produced (ISO-8601).
+ pub canonicalized_at: String,
+ /// Tables mapped to arrays of row objects. Blob columns replaced with `{ "__blobRef", "__blobKind" }`.
+ pub tables: HashMap<String, Vec<CodecRecord>>,
+ /// Forward-compat: unknown top-level keys preserved on round-trip.
+ #[serde(flatten)]
+ pub extra: HashMap<String, serde_json::Value>,
+}
+
+/// One data bucket: a slice of the vault kept OUT of the manifest so it can sync on its own server
+/// revision without rewriting the manifest. `category` mirrors the server `VaultDataBucketCategory`
+/// (e.g. "Settings"). `tables` holds the bucket's tables (name > rows).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DataBucket {
+ pub schema_version: u32,
+ pub category: String,
+ pub tables: HashMap<String, Vec<CodecRecord>>,
+ #[serde(flatten)]
+ pub extra: HashMap<String, serde_json::Value>,
+}
+
+impl DataBucket {
+ /// Build a data bucket for `category` from its already-normalized tables (name > rows).
+ pub fn new(category: impl Into<String>, tables: HashMap<String, Vec<CodecRecord>>) -> Self {
+ Self {
+ schema_version: SCHEMA_VERSION,
+ category: category.into(),
+ tables,
+ extra: HashMap::new(),
+ }
+ }
+}
+
+/// A decoded blob entry. `bytes_base64` is the plaintext blob, base64-encoded for transport
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BlobEntry {
+ /// "favicon" | "attachment".
+ pub kind: String,
+ pub bytes_base64: String,
+}
+
+/// Result of canonicalizing a vault: the manifest, its data buckets (one per category, e.g. Settings),
+/// and the content-addressed blob map.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CanonicalizedVault {
+ pub manifest: Manifest,
+ pub data_buckets: Vec<DataBucket>,
+ /// hash > blob plaintext (base64).
+ pub blobs: HashMap<String, BlobEntry>,
+}
+
+/// A single table's rows for reassembly.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CodecTableData {
+ pub name: String,
+ pub records: Vec<CodecRecord>,
+}
+
+/// Materialized tables the platform inserts into a fresh schema DB. Blob columns carry
+/// `{ "__blobRef": hash }`; inline byte columns carry `{ "__b64": ... }`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct MaterializedTables {
+ pub tables: Vec<CodecTableData>,
+ pub migration_id: String,
+}
+
+/// Input for [`crate::vault_codec::canonicalize_from_sqlite`].
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CanonicalizeInput {
+ pub tables: Vec<CodecTableData>,
+ pub user_salt: String,
+ pub migration_id: String,
+ #[serde(default = "default_version")]
+ pub version: String,
+ pub canonicalized_at: String,
+}
+
+fn default_version() -> String {
+ String::from("2.0.0")
+}
+
+/// Input for [`crate::vault_codec::materialize_as_sqlite`].
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct MaterializeInput {
+ pub manifest: Manifest,
+ #[serde(default)]
+ pub data_buckets: Vec<DataBucket>,
+}
diff --git a/core/rust/src/vault_codec/materialize.rs b/core/rust/src/vault_codec/materialize.rs
new file mode 100644
index 000000000..fc5866108
--- /dev/null
+++ b/core/rust/src/vault_codec/materialize.rs
@@ -0,0 +1,41 @@
+//! Materialize the canonical persisted representation as a concrete SQLite projection.
+//!
+//! `materialize_as_sqlite` is the SQLite adapter of the materialize direction. SQLite is one possible
+//! projection of the canonical dataset, not an authoritative destination. Future targets would add
+//! sibling `materialize_as_*` entry points. The inverse direction lives in `canonicalize`.
+//!
+//! Rust does not handle actual SQLite operations. It only emits the destination table rows as-is
+//! to the caller and let the caller handle the actual SQLite database creation and data insertion.
+
+use super::manifest::{MaterializeInput, MaterializedTables, CodecTableData};
+use super::types::is_skip_table;
+use crate::error::VaultResult;
+
+/// Materialize the manifest + its data buckets into the table set the platform inserts.
+pub fn materialize_as_sqlite(input: MaterializeInput) -> VaultResult<MaterializedTables> {
+ let MaterializeInput { manifest, data_buckets } = input;
+
+ let mut tables: Vec<CodecTableData> = Vec::with_capacity(manifest.tables.len() + data_buckets.len());
+
+ for (name, records) in manifest.tables {
+ if is_skip_table(&name) {
+ continue;
+ }
+ tables.push(CodecTableData { name, records });
+ }
+
+ // Reconstitute every data bucket's tables back into the flat set.
+ for bucket in data_buckets {
+ for (name, records) in bucket.tables {
+ if is_skip_table(&name) {
+ continue;
+ }
+ tables.push(CodecTableData { name, records });
+ }
+ }
+
+ Ok(MaterializedTables {
+ tables,
+ migration_id: manifest.migration_id,
+ })
+}
diff --git a/core/rust/src/vault_codec/mod.rs b/core/rust/src/vault_codec/mod.rs
new file mode 100644
index 000000000..e606055fa
--- /dev/null
+++ b/core/rust/src/vault_codec/mod.rs
@@ -0,0 +1,216 @@
+//! Vault codec: logic for translating between the canonical manifest-v1 storage format (as persisted on the server)
+//! and local vault formats (e.g., SQLite, or others), including integrity envelope (canonical hash),
+//! gzip packing/unpacking, structural validation, and blob-upload diff detection.
+//!
+//! This module defines the *format* codec that maps between canonical artifacts (manifest, data buckets,
+//! content-addressed blobs) and platform-specific representations, without embedding knowledge of encryption
+//! or storage engine internals. Each platform interacts with its own storage and applies encryption/decryption
+//! outside of this codec.
+
+mod compress;
+mod canonicalize;
+mod hash;
+mod manifest;
+mod materialize;
+mod types;
+mod validate;
+
+use std::collections::HashSet;
+
+use base64::engine::general_purpose::STANDARD as BASE64;
+use base64::Engine;
+use serde_json::json;
+
+use crate::error::{VaultError, VaultResult};
+
+pub use hash::{canonical_json, content_hash};
+pub use manifest::{
+ BlobEntry, CanonicalizeInput, CanonicalizedVault, DataBucket, Manifest, MaterializeInput,
+ MaterializedTables, CodecRecord, CodecTableData,
+};
+pub use types::{
+ bucket_categories, bucket_category_for, BLOB_COLUMNS, BUCKET_TABLES, SCHEMA_VERSION,
+ SKIP_TABLES,
+};
+pub use validate::ValidationResult;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// canonicalize_from_sqlite / materialize_as_sqlite
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Canonicalize normalized tables into manifest + data buckets + blob map.
+pub fn canonicalize_from_sqlite(input: CanonicalizeInput) -> VaultResult<CanonicalizedVault> {
+ canonicalize::canonicalize_from_sqlite(input)
+}
+
+/// Materialize the manifest + data buckets into the table set the platform inserts into a fresh schema DB.
+pub fn materialize_as_sqlite(input: MaterializeInput) -> VaultResult<MaterializedTables> {
+ materialize::materialize_as_sqlite(input)
+}
+
+/// Build a single data bucket for `category` from its tables (bucket-only push path).
+pub fn extract_bucket(category: String, tables: std::collections::HashMap<String, Vec<CodecRecord>>) -> DataBucket {
+ canonicalize::extract_bucket(category, tables)
+}
+
+/// Generate a fresh 32-byte per-user salt as a lowercase hex string.
+pub fn generate_user_salt() -> String {
+ use rand::RngCore;
+ let mut bytes = [0u8; 32];
+ rand::rng().fill_bytes(&mut bytes);
+ hash::bytes_to_hex(&bytes)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// packing: envelope + canonical hash + gzip.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Wrap a payload JSON string in an integrity envelope (`{ schemaVersion, contentHash, payload }`)
+/// and gzip it.
+pub fn pack_payload(payload_json: &str) -> VaultResult<Vec<u8>> {
+ let payload: serde_json::Value = serde_json::from_str(payload_json)?;
+ let content_hash = hash::content_hash(&payload);
+ let envelope = json!({
+ "schemaVersion": SCHEMA_VERSION,
+ "contentHash": content_hash,
+ "payload": payload,
+ });
+ let envelope_json = serde_json::to_string(&envelope)?;
+ compress::gzip(envelope_json.as_bytes())
+}
+
+/// Unpack a payload: gunzip > parse envelope > verify the embedded content hash.
+pub fn unpack_payload(plain_bytes: &[u8]) -> VaultResult<String> {
+ let envelope_json = compress::gunzip_to_string(plain_bytes)?;
+ let envelope: serde_json::Value = serde_json::from_str(&envelope_json)?;
+
+ if !envelope.get("schemaVersion").map(|v| v.is_number()).unwrap_or(false) {
+ return Err(VaultError::General("envelope missing schemaVersion".to_string()));
+ }
+
+ let content_hash = envelope
+ .get("contentHash")
+ .and_then(|v| v.as_str())
+ .filter(|s| s.len() == 64)
+ .ok_or_else(|| VaultError::General("envelope missing or malformed contentHash".to_string()))?;
+
+ let payload = envelope
+ .get("payload")
+ .ok_or_else(|| VaultError::General("envelope missing payload".to_string()))?;
+
+ let expected = hash::content_hash(payload);
+ if expected != content_hash {
+ return Err(VaultError::General(format!(
+ "contentHash mismatch (expected {}, got {}). Vault may be corrupt — do not load.",
+ content_hash, expected
+ )));
+ }
+
+ Ok(serde_json::to_string(payload)?)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// integrity checks
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Structurally validate a manifest before upload.
+pub fn validate_manifest(m: &Manifest) -> ValidationResult {
+ validate::validate_manifest(m)
+}
+
+/// Validate a data bucket before upload.
+pub fn validate_data_bucket(b: &DataBucket) -> ValidationResult {
+ validate::validate_data_bucket(b)
+}
+
+/// SHA-256 (lowercase hex) of a base64 ciphertext string — storage-layer integrity.
+pub fn compute_ciphertext_hash(base64_ciphertext: &str) -> String {
+ match BASE64.decode(base64_ciphertext) {
+ Ok(raw) => hash::sha256_hex(&raw),
+ // Mirror nothing weird: an undecodable input hashes to a stable but obviously-wrong value;
+ // callers compare equality so a malformed input simply fails the check.
+ Err(_) => hash::sha256_hex(base64_ciphertext.as_bytes()),
+ }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// blob diff
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Return the manifest's referenced blob hashes that are NOT already known.
+pub fn which_blobs_to_upload(manifest: &Manifest, known_hashes: Vec<String>) -> Vec<String> {
+ let known: HashSet<String> = known_hashes.into_iter().collect();
+ let mut seen: HashSet<String> = HashSet::new();
+ let mut out: Vec<String> = Vec::new();
+
+ for rows in manifest.tables.values() {
+ for row in rows {
+ for value in row.values() {
+ if let Some(hash) = value.get("__blobRef").and_then(|v| v.as_str()) {
+ if !known.contains(hash) && seen.insert(hash.to_string()) {
+ out.push(hash.to_string());
+ }
+ }
+ }
+ }
+ }
+
+ out
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// JSON-string siblings (FFI / UniFFI interface)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// JSON-string sibling of [`canonicalize_from_sqlite`].
+pub fn canonicalize_from_sqlite_json(input_json: &str) -> VaultResult<String> {
+ let input: CanonicalizeInput = serde_json::from_str(input_json)?;
+ Ok(serde_json::to_string(&canonicalize_from_sqlite(input)?)?)
+}
+
+/// JSON-string sibling of [`materialize_as_sqlite`].
+pub fn materialize_as_sqlite_json(input_json: &str) -> VaultResult<String> {
+ let input: MaterializeInput = serde_json::from_str(input_json)?;
+ Ok(serde_json::to_string(&materialize_as_sqlite(input)?)?)
+}
+
+/// JSON-string sibling of [`extract_bucket`]. Input: `{ "category": <str>, "tables": { <name>: [rows] } }`.
+pub fn extract_bucket_json(input_json: &str) -> VaultResult<String> {
+ #[derive(serde::Deserialize)]
+ struct Input {
+ category: String,
+ #[serde(default)]
+ tables: std::collections::HashMap<String, Vec<CodecRecord>>,
+ }
+ let input: Input = serde_json::from_str(input_json)?;
+ Ok(serde_json::to_string(&extract_bucket(input.category, input.tables))?)
+}
+
+/// JSON-string sibling of [`validate_manifest`].
+pub fn validate_manifest_json(manifest_json: &str) -> VaultResult<String> {
+ let m: Manifest = serde_json::from_str(manifest_json)?;
+ Ok(serde_json::to_string(&validate_manifest(&m))?)
+}
+
+/// JSON-string sibling of [`validate_data_bucket`].
+pub fn validate_data_bucket_json(data_bucket_json: &str) -> VaultResult<String> {
+ let b: DataBucket = serde_json::from_str(data_bucket_json)?;
+ Ok(serde_json::to_string(&validate_data_bucket(&b))?)
+}
+
+/// JSON-string sibling of [`which_blobs_to_upload`]. Input:
+/// `{ "manifest": <manifest>, "knownHashes": [..] }`.
+pub fn which_blobs_to_upload_json(input_json: &str) -> VaultResult<String> {
+ #[derive(serde::Deserialize)]
+ #[serde(rename_all = "camelCase")]
+ struct Input {
+ manifest: Manifest,
+ #[serde(default)]
+ known_hashes: Vec<String>,
+ }
+ let input: Input = serde_json::from_str(input_json)?;
+ Ok(serde_json::to_string(&which_blobs_to_upload(&input.manifest, input.known_hashes))?)
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/core/rust/src/vault_codec/tests.rs b/core/rust/src/vault_codec/tests.rs
new file mode 100644
index 000000000..44722ea2e
--- /dev/null
+++ b/core/rust/src/vault_codec/tests.rs
@@ -0,0 +1,270 @@
+//! Unit tests for vault_codec, covering the round-trip contract.
+use super::*;
+use base64::engine::general_purpose::STANDARD as BASE64;
+use base64::Engine;
+use serde_json::json;
+
+fn b64(bytes: &[u8]) -> String {
+ BASE64.encode(bytes)
+}
+
+fn row(pairs: &[(&str, serde_json::Value)]) -> CodecRecord {
+ pairs.iter().map(|(k, v)| (k.to_string(), v.clone())).collect()
+}
+
+/// The rows of `table` inside the data bucket for `category` (empty if absent).
+fn bucket_rows<'a>(out: &'a CanonicalizedVault, category: &str, table: &str) -> &'a [CodecRecord] {
+ out.data_buckets
+ .iter()
+ .find(|b| b.category == category)
+ .and_then(|b| b.tables.get(table))
+ .map(Vec::as_slice)
+ .unwrap_or(&[])
+}
+
+fn basic_input(tables: Vec<CodecTableData>) -> CanonicalizeInput {
+ CanonicalizeInput {
+ tables,
+ user_salt: "00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff".to_string(),
+ migration_id: "20250101000000_Init".to_string(),
+ version: "2.0.0".to_string(),
+ canonicalized_at: "2026-01-01T00:00:00.000Z".to_string(),
+ }
+}
+
+#[test]
+fn canonicalize_from_sqlite_splits_settings_into_data_bucket() {
+ let input = basic_input(vec![
+ CodecTableData { name: "Items".to_string(), records: vec![row(&[("Id", json!("i1"))])] },
+ CodecTableData { name: "Settings".to_string(), records: vec![row(&[("Key", json!("k")), ("Value", json!("v"))])] },
+ ]);
+ let out = canonicalize_from_sqlite(input).unwrap();
+ assert!(out.manifest.tables.contains_key("Items"));
+ assert!(!out.manifest.tables.contains_key("Settings"));
+ assert_eq!(bucket_rows(&out, "Settings", "Settings").len(), 1);
+}
+
+#[test]
+fn canonicalize_from_sqlite_skips_internal_tables() {
+ // Gotcha #4: skip-tables must never enter the manifest.
+ let input = basic_input(vec![
+ CodecTableData { name: "Items".to_string(), records: vec![] },
+ CodecTableData { name: "__EFMigrationsHistory".to_string(), records: vec![row(&[("MigrationId", json!("x"))])] },
+ CodecTableData { name: "android_metadata".to_string(), records: vec![row(&[("locale", json!("en_US"))])] },
+ CodecTableData { name: "sqlite_sequence".to_string(), records: vec![] },
+ ]);
+ let out = canonicalize_from_sqlite(input).unwrap();
+ assert!(out.manifest.tables.contains_key("Items"));
+ assert!(!out.manifest.tables.contains_key("__EFMigrationsHistory"));
+ assert!(!out.manifest.tables.contains_key("android_metadata"));
+ assert!(!out.manifest.tables.contains_key("sqlite_sequence"));
+}
+
+#[test]
+fn canonicalize_from_sqlite_extracts_blob_columns_and_hashes() {
+ let favicon = vec![0xde, 0xad, 0xbe, 0xef];
+ let input = basic_input(vec![CodecTableData {
+ name: "Logos".to_string(),
+ records: vec![row(&[("Id", json!("l1")), ("FileData", json!({ "__b64": b64(&favicon) }))])],
+ }]);
+ let out = canonicalize_from_sqlite(input).unwrap();
+ assert_eq!(out.blobs.len(), 1);
+ let (hash, entry) = out.blobs.iter().next().unwrap();
+ assert_eq!(entry.kind, "favicon");
+ assert_eq!(hash, &hash::salted_blob_hash(&favicon, "00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff"));
+
+ let logos = &out.manifest.tables["Logos"][0];
+ let cell = &logos["FileData"];
+ assert_eq!(cell["__blobRef"], json!(hash));
+ assert_eq!(cell["__blobKind"], json!("favicon"));
+}
+
+#[test]
+fn canonicalize_from_sqlite_nulls_empty_blob_cells() {
+ let input = basic_input(vec![CodecTableData {
+ name: "Attachments".to_string(),
+ records: vec![
+ row(&[("Id", json!("a1")), ("Blob", serde_json::Value::Null)]),
+ row(&[("Id", json!("a2")), ("Blob", json!({ "__b64": "" }))]),
+ ],
+ }]);
+ let out = canonicalize_from_sqlite(input).unwrap();
+ assert_eq!(out.blobs.len(), 0);
+ assert_eq!(out.manifest.tables["Attachments"][0]["Blob"], serde_json::Value::Null);
+ assert_eq!(out.manifest.tables["Attachments"][1]["Blob"], serde_json::Value::Null);
+}
+
+#[test]
+fn inline_b64_columns_survive_roundtrip() {
+ // Non-blob byte columns (e.g. a TOTP secret) keep their {__b64} marker verbatim.
+ let secret = vec![1u8, 2, 3, 4, 5];
+ let input = basic_input(vec![CodecTableData {
+ name: "Items".to_string(),
+ records: vec![row(&[("Id", json!("i1")), ("Secret", json!({ "__b64": b64(&secret) }))])],
+ }]);
+ let out = canonicalize_from_sqlite(input).unwrap();
+ let cell = &out.manifest.tables["Items"][0]["Secret"];
+ assert_eq!(cell["__b64"], json!(b64(&secret)));
+
+ let re = materialize_as_sqlite(MaterializeInput { manifest: out.manifest, data_buckets: out.data_buckets }).unwrap();
+ let items = re.tables.iter().find(|t| t.name == "Items").unwrap();
+ assert_eq!(items.records[0]["Secret"]["__b64"], json!(b64(&secret)));
+}
+
+#[test]
+fn materialize_as_sqlite_emits_settings_table_and_migration_id() {
+ // Migration id is carried through; Settings reconstituted from the bucket.
+ let input = basic_input(vec![
+ CodecTableData { name: "Items".to_string(), records: vec![row(&[("Id", json!("i1"))])] },
+ CodecTableData { name: "Settings".to_string(), records: vec![row(&[("Key", json!("k"))])] },
+ ]);
+ let out = canonicalize_from_sqlite(input).unwrap();
+ let re = materialize_as_sqlite(MaterializeInput { manifest: out.manifest, data_buckets: out.data_buckets }).unwrap();
+ assert_eq!(re.migration_id, "20250101000000_Init");
+ assert!(re.tables.iter().any(|t| t.name == "Settings" && t.records.len() == 1));
+ assert!(re.tables.iter().any(|t| t.name == "Items"));
+}
+
+#[test]
+fn materialize_as_sqlite_drops_skip_tables() {
+ // A manifest carrying a platform bookkeeping table (android_metadata) must not be re-emitted.
+ let mut manifest = canonicalize_from_sqlite(basic_input(vec![CodecTableData { name: "Items".to_string(), records: vec![] }]))
+ .unwrap()
+ .manifest;
+ manifest
+ .tables
+ .insert("android_metadata".to_string(), vec![row(&[("locale", json!("en_US"))])]);
+ let re = materialize_as_sqlite(MaterializeInput { manifest, data_buckets: vec![] }).unwrap();
+ assert!(!re.tables.iter().any(|t| t.name == "android_metadata"));
+}
+
+#[test]
+fn full_roundtrip_with_blobs_is_semantically_equal() {
+ let favicon = vec![0x01, 0x02, 0x03];
+ let attachment = vec![0xaa, 0xbb, 0xcc, 0xdd, 0xee];
+ let tables = vec![
+ CodecTableData { name: "Items".to_string(), records: vec![row(&[("Id", json!("i1")), ("FolderId", serde_json::Value::Null)])] },
+ CodecTableData { name: "Logos".to_string(), records: vec![row(&[("Id", json!("l1")), ("FileData", json!({ "__b64": b64(&favicon) }))])] },
+ CodecTableData { name: "Attachments".to_string(), records: vec![row(&[("Id", json!("a1")), ("ItemId", json!("i1")), ("Blob", json!({ "__b64": b64(&attachment) }))])] },
+ CodecTableData { name: "Settings".to_string(), records: vec![row(&[("Key", json!("theme")), ("Value", json!("dark"))])] },
+ ];
+ let out = canonicalize_from_sqlite(basic_input(tables)).unwrap();
+ assert_eq!(out.blobs.len(), 2);
+
+ let re = materialize_as_sqlite(MaterializeInput { manifest: out.manifest.clone(), data_buckets: out.data_buckets.clone() }).unwrap();
+ // Items/Logos/Attachments/Settings all present (skip tables aside).
+ for name in ["Items", "Logos", "Attachments", "Settings"] {
+ assert!(re.tables.iter().any(|t| t.name == name), "missing table {name}");
+ }
+ // Blob cells are refs the platform will rebind from the blob map.
+ let logos = re.tables.iter().find(|t| t.name == "Logos").unwrap();
+ assert!(logos.records[0]["FileData"].get("__blobRef").is_some());
+}
+
+#[test]
+fn pack_unpack_roundtrip_verifies_content_hash() {
+ let payload = json!({ "schemaVersion": 1, "tables": { "Items": [] }, "userSalt": "abcd" });
+ let payload_json = serde_json::to_string(&payload).unwrap();
+ let packed = pack_payload(&payload_json).unwrap();
+ // Packed output is gzip (magic bytes present).
+ assert_eq!(&packed[0..2], &[0x1f, 0x8b]);
+ let unpacked = unpack_payload(&packed).unwrap();
+ let unpacked_val: serde_json::Value = serde_json::from_str(&unpacked).unwrap();
+ assert_eq!(unpacked_val, payload);
+}
+
+#[test]
+fn unpack_payload_rejects_tampered_payload() {
+ let payload = json!({ "a": 1 });
+ let content_hash = hash::content_hash(&payload);
+ // Tamper: keep the original hash but change the payload, then pack it.
+ let envelope = json!({ "schemaVersion": 1, "contentHash": content_hash, "payload": { "a": 2 } });
+ let packed = super::compress::gzip(serde_json::to_string(&envelope).unwrap().as_bytes()).unwrap();
+ assert!(unpack_payload(&packed).is_err());
+}
+
+#[test]
+fn content_hash_is_key_order_independent() {
+ let a = json!({ "x": 1, "y": 2 });
+ let b = json!({ "y": 2, "x": 1 });
+ assert_eq!(hash::content_hash(&a), hash::content_hash(&b));
+}
+
+#[test]
+fn validate_manifest_catches_broken_fk() {
+ let mut manifest = canonicalize_from_sqlite(basic_input(vec![
+ CodecTableData { name: "Items".to_string(), records: vec![row(&[("Id", json!("i1")), ("FolderId", json!("missing"))])] },
+ CodecTableData { name: "Folders".to_string(), records: vec![] },
+ ]))
+ .unwrap()
+ .manifest;
+ manifest.tables.entry("Folders".to_string()).or_default();
+ let result = validate_manifest(&manifest);
+ assert!(!result.ok);
+ assert!(result.failed_rules.iter().any(|r| r == "item-folder-fk-broken"));
+}
+
+#[test]
+fn validate_manifest_ok_for_clean_vault() {
+ let manifest = canonicalize_from_sqlite(basic_input(vec![
+ CodecTableData { name: "Items".to_string(), records: vec![row(&[("Id", json!("i1")), ("FolderId", json!("f1"))])] },
+ CodecTableData { name: "Folders".to_string(), records: vec![row(&[("Id", json!("f1"))])] },
+ ]))
+ .unwrap()
+ .manifest;
+ assert!(validate_manifest(&manifest).ok);
+}
+
+#[test]
+fn which_blobs_to_upload_excludes_known() {
+ let favicon = vec![0x09, 0x08, 0x07];
+ let out = canonicalize_from_sqlite(basic_input(vec![CodecTableData {
+ name: "Logos".to_string(),
+ records: vec![row(&[("Id", json!("l1")), ("FileData", json!({ "__b64": b64(&favicon) }))])],
+ }]))
+ .unwrap();
+ let hash = out.blobs.keys().next().unwrap().clone();
+
+ assert_eq!(which_blobs_to_upload(&out.manifest, vec![]), vec![hash.clone()]);
+ assert!(which_blobs_to_upload(&out.manifest, vec![hash]).is_empty());
+}
+
+#[test]
+fn generate_user_salt_is_64_hex_chars() {
+ let salt = generate_user_salt();
+ assert_eq!(salt.len(), 64);
+ assert!(salt.chars().all(|c| c.is_ascii_hexdigit()));
+}
+
+#[test]
+fn forward_compat_unknown_manifest_fields_preserved() {
+ // The plan's document-store rule: unknown top-level keys round-trip verbatim.
+ let manifest_json = json!({
+ "schemaVersion": 1,
+ "migrationId": "m",
+ "version": "2.0.0",
+ "userSalt": "00112233445566778899aabbccddeeff",
+ "canonicalizedAt": "2026-01-01T00:00:00.000Z",
+ "tables": { "Items": [] },
+ "futureField": { "nested": true }
+ })
+ .to_string();
+ let manifest: Manifest = serde_json::from_str(&manifest_json).unwrap();
+ assert!(manifest.extra.contains_key("futureField"));
+ let reser = serde_json::to_value(&manifest).unwrap();
+ assert_eq!(reser["futureField"], json!({ "nested": true }));
+}
+
+#[test]
+fn json_siblings_roundtrip() {
+ let input = basic_input(vec![CodecTableData { name: "Items".to_string(), records: vec![row(&[("Id", json!("i1"))])] }]);
+ let input_json = serde_json::to_string(&input).unwrap();
+ let canonicalized_json = canonicalize_from_sqlite_json(&input_json).unwrap();
+ let canonicalized: CanonicalizedVault = serde_json::from_str(&canonicalized_json).unwrap();
+ assert!(canonicalized.manifest.tables.contains_key("Items"));
+
+ let materialize_input = json!({ "manifest": canonicalized.manifest, "dataBuckets": canonicalized.data_buckets }).to_string();
+ let materialized_json = materialize_as_sqlite_json(&materialize_input).unwrap();
+ let materialized: MaterializedTables = serde_json::from_str(&materialized_json).unwrap();
+ assert!(materialized.tables.iter().any(|t| t.name == "Items"));
+}
diff --git a/core/rust/src/vault_codec/types.rs b/core/rust/src/vault_codec/types.rs
new file mode 100644
index 000000000..66aaaad9a
--- /dev/null
+++ b/core/rust/src/vault_codec/types.rs
@@ -0,0 +1,59 @@
+//! Format constants for the manifest-v1 storage layout.
+//!
+//! These constants are defined here so every platform shares the exact same rules.
+
+/// The SQLite columns whose contents are extracted into content-addressed blobs rather than
+/// kept inline in the manifest. Tuple form `(table_name, blob_column, kind_label)`. The kind label
+/// is reported to the server on upload (used for metrics / retention).
+pub static BLOB_COLUMNS: &[(&str, &str, &str)] = &[
+ ("Logos", "FileData", "favicon"),
+ ("Attachments", "Blob", "attachment"),
+];
+
+/// Tables never serialized into the manifest: internal SQLite, platform, or EF bookkeeping.
+pub static SKIP_TABLES: &[&str] = &[
+ "__EFMigrationsHistory",
+ "__EFMigrationsLock",
+ "sqlite_sequence",
+ "android_metadata",
+];
+
+/// Tables split OUT of the manifest into a data bucket, keyed by category, so each bucket syncs on its
+/// own server revision without rewriting the manifest. Tuple form `(table_name, bucket_category)`;
+/// `category` mirrors the server `VaultDataBucketCategory`. Several tables may share a category to sync together.
+pub static BUCKET_TABLES: &[(&str, &str)] = &[
+ ("Settings", "Settings"),
+];
+
+/// The data-bucket category a table belongs to, if it is bucketed out of the manifest.
+pub fn bucket_category_for(table_name: &str) -> Option<&'static str> {
+ BUCKET_TABLES.iter().find(|(t, _)| *t == table_name).map(|(_, c)| *c)
+}
+
+/// All distinct bucket categories, in declaration order. Lets the codec always emit a stable set of
+/// buckets even when a bucket's tables are empty.
+pub fn bucket_categories() -> Vec<&'static str> {
+ let mut out: Vec<&'static str> = Vec::new();
+ for (_, category) in BUCKET_TABLES {
+ if !out.contains(category) {
+ out.push(category);
+ }
+ }
+ out
+}
+
+/// Manifest / metadata schema version. This is the manifest *wire structure* version and is its own
+/// axis, independent of the data-model `version` string (which tracks EF migrations).
+/// It starts at 1 for the first manifest generation; bump only on a breaking structural change
+/// (field type changes, removed fields).
+pub const SCHEMA_VERSION: u32 = 1;
+
+/// Returns the blob `(table, column, kind)` tuple for a table, if it owns an extracted blob column.
+pub fn blob_spec_for(table_name: &str) -> Option<&'static (&'static str, &'static str, &'static str)> {
+ BLOB_COLUMNS.iter().find(|(t, _, _)| *t == table_name)
+}
+
+/// True when a table must never be serialized into / inserted from the manifest.
+pub fn is_skip_table(table_name: &str) -> bool {
+ SKIP_TABLES.contains(&table_name)
+}
diff --git a/core/rust/src/vault_codec/validate.rs b/core/rust/src/vault_codec/validate.rs
new file mode 100644
index 000000000..e01b5d49c
--- /dev/null
+++ b/core/rust/src/vault_codec/validate.rs
@@ -0,0 +1,140 @@
+//! Validate structure for the manifest-v1 format.
+//!
+//! We refuse obviously-broken manifests before they are encrypted/uploaded.
+
+use serde::{Deserialize, Serialize};
+
+use super::manifest::{DataBucket, Manifest, CodecRecord};
+
+/// Outcome of a structural validation run.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ValidationResult {
+ pub ok: bool,
+ /// Stable rule identifiers that failed. Empty when ok.
+ pub failed_rules: Vec<String>,
+ /// Human-readable explanation. Empty when ok.
+ pub message: String,
+}
+
+impl ValidationResult {
+ fn ok() -> Self {
+ Self { ok: true, failed_rules: Vec::new(), message: String::new() }
+ }
+}
+
+fn table<'a>(m: &'a Manifest, name: &str) -> &'a [CodecRecord] {
+ m.tables.get(name).map(|v| v.as_slice()).unwrap_or(&[])
+}
+
+fn str_field<'a>(r: &'a CodecRecord, key: &str) -> Option<&'a str> {
+ r.get(key).and_then(|v| v.as_str())
+}
+
+/// Structurally validate a fresh manifest before it is encrypted/uploaded.
+pub fn validate_manifest(manifest: &Manifest) -> ValidationResult {
+ let mut failed: Vec<String> = Vec::new();
+ let mut explain: Vec<String> = Vec::new();
+
+ if manifest.schema_version < 1 {
+ failed.push("schemaVersion-missing-or-too-low".to_string());
+ }
+ if manifest.user_salt.len() < 32 {
+ failed.push("userSalt-missing-or-short".to_string());
+ }
+
+ if manifest.tables.is_empty() {
+ failed.push("tables-missing".to_string());
+ return ValidationResult {
+ ok: false,
+ failed_rules: failed,
+ message: "Manifest has no tables — refusing upload.".to_string(),
+ };
+ }
+
+ let items = table(manifest, "Items");
+ let folders = table(manifest, "Folders");
+ let tags = table(manifest, "Tags");
+ let item_tags = table(manifest, "ItemTags");
+ let field_values = table(manifest, "FieldValues");
+ let field_defs = table(manifest, "FieldDefinitions");
+
+ let item_ids: std::collections::HashSet<&str> = items.iter().filter_map(|i| str_field(i, "Id")).collect();
+ let folder_ids: std::collections::HashSet<&str> = folders.iter().filter_map(|f| str_field(f, "Id")).collect();
+ let tag_ids: std::collections::HashSet<&str> = tags.iter().filter_map(|t| str_field(t, "Id")).collect();
+ let field_def_ids: std::collections::HashSet<&str> = field_defs.iter().filter_map(|f| str_field(f, "Id")).collect();
+
+ // Referential integrity.
+ for item in items {
+ if let Some(folder_id) = str_field(item, "FolderId") {
+ if !folder_ids.contains(folder_id) {
+ failed.push("item-folder-fk-broken".to_string());
+ explain.push(format!("Item {} references missing folder {}", str_field(item, "Id").unwrap_or(""), folder_id));
+ break;
+ }
+ }
+ }
+
+ for it in item_tags {
+ if let Some(item_id) = str_field(it, "ItemId") {
+ if !item_ids.contains(item_id) {
+ failed.push("itemtag-item-fk-broken".to_string());
+ explain.push(format!("ItemTag {} references missing item {}", str_field(it, "Id").unwrap_or(""), item_id));
+ break;
+ }
+ }
+ }
+ for it in item_tags {
+ if let Some(tag_id) = str_field(it, "TagId") {
+ if !tag_ids.contains(tag_id) {
+ failed.push("itemtag-tag-fk-broken".to_string());
+ explain.push(format!("ItemTag {} references missing tag {}", str_field(it, "Id").unwrap_or(""), tag_id));
+ break;
+ }
+ }
+ }
+
+ for fv in field_values {
+ if let Some(item_id) = str_field(fv, "ItemId") {
+ if !item_ids.contains(item_id) {
+ failed.push("fieldvalue-item-fk-broken".to_string());
+ explain.push(format!("FieldValue {} references missing item {}", str_field(fv, "Id").unwrap_or(""), item_id));
+ break;
+ }
+ }
+ }
+ for fv in field_values {
+ if let Some(field_def_id) = str_field(fv, "FieldDefinitionId") {
+ if !field_def_ids.contains(field_def_id) {
+ failed.push("fieldvalue-fielddef-fk-broken".to_string());
+ break;
+ }
+ }
+ }
+
+ // Uniqueness.
+ if item_ids.len() != items.len() {
+ failed.push("item-ids-not-unique".to_string());
+ }
+ if folder_ids.len() != folders.len() {
+ failed.push("folder-ids-not-unique".to_string());
+ }
+
+ ValidationResult {
+ ok: failed.is_empty(),
+ failed_rules: failed,
+ message: explain.join("; "),
+ }
+}
+
+/// Validate a data bucket before upload.
+pub fn validate_data_bucket(bucket: &DataBucket) -> ValidationResult {
+ if bucket.schema_version < 1 {
+ return ValidationResult {
+ ok: false,
+ failed_rules: vec!["dataBucket-schemaVersion-missing".to_string()],
+ message: "Data bucket missing schemaVersion".to_string(),
+ };
+ }
+ ValidationResult::ok()
+}
diff --git a/core/rust/src/wasm.rs b/core/rust/src/wasm.rs
index a1f572aec..3290bee09 100644
--- a/core/rust/src/wasm.rs
+++ b/core/rust/src/wasm.rs
@@ -6,6 +6,9 @@ use crate::credential_matcher::{
filter_credentials, CredentialMatcherInput, CredentialMatcherOutput,
};
use crate::password_generator::{available_languages, generate_password};
+use crate::vault_codec::{
+ self, CanonicalizeInput, CodecRecord, DataBucket, Manifest, MaterializeInput,
+};
use crate::vault_merge::{merge_vaults, MergeInput, MergeOutput};
use crate::vault_pruner::{prune_vault, PruneInput, PruneOutput};
@@ -109,6 +112,108 @@ pub fn get_prune_table_queries_js() -> Result<JsValue, JsValue> {
.map_err(|e| JsValue::from_str(&format!("Failed to serialize output: {}", e)))
}
+// ═══════════════════════════════════════════════════════════════════════════════
+// Vault Codec WASM Bindings (manifest-v1 storage format)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/// Serialize a codec output to a JsValue with Rust maps rendered as plain JS objects.
+fn codec_to_js<T: serde::Serialize>(value: &T) -> Result<JsValue, JsValue> {
+ value
+ .serialize(&serde_wasm_bindgen::Serializer::new().serialize_maps_as_objects(true))
+ .map_err(|e| JsValue::from_str(&format!("Failed to serialize codec output: {}", e)))
+}
+
+/// Canonicalize normalized tables into manifest + data buckets.
+/// Input: `CanonicalizeInput`. Output: `CanonicalizedVault`.
+#[wasm_bindgen(js_name = vaultCodecCanonicalizeFromSqlite)]
+pub fn vault_codec_canonicalize_from_sqlite_js(input: JsValue) -> Result<JsValue, JsValue> {
+ let input: CanonicalizeInput = serde_wasm_bindgen::from_value(input)
+ .map_err(|e| JsValue::from_str(&format!("Failed to parse canonicalize_from_sqlite input: {}", e)))?;
+ let output = vault_codec::canonicalize_from_sqlite(input)
+ .map_err(|e| JsValue::from_str(&format!("canonicalize_from_sqlite failed: {}", e)))?;
+ codec_to_js(&output)
+}
+
+/// Materialize the manifest + data buckets into the table set the platform inserts into a fresh schema DB.
+/// Input: `MaterializeInput`. Output: `MaterializedTables`.
+#[wasm_bindgen(js_name = vaultCodecMaterializeAsSqlite)]
+pub fn vault_codec_materialize_as_sqlite_js(input: JsValue) -> Result<JsValue, JsValue> {
+ let input: MaterializeInput = serde_wasm_bindgen::from_value(input)
+ .map_err(|e| JsValue::from_str(&format!("Failed to parse materialize_as_sqlite input: {}", e)))?;
+ let output = vault_codec::materialize_as_sqlite(input)
+ .map_err(|e| JsValue::from_str(&format!("materialize_as_sqlite failed: {}", e)))?;
+ codec_to_js(&output)
+}
+
+/// Build a single data bucket. Input: `{ category, tables: { <name>: [rows] } }`. Output: `DataBucket`.
+#[wasm_bindgen(js_name = vaultCodecExtractBucket)]
+pub fn vault_codec_extract_bucket_js(input: JsValue) -> Result<JsValue, JsValue> {
+ #[derive(serde::Deserialize)]
+ struct Input {
+ category: String,
+ #[serde(default)]
+ tables: std::collections::HashMap<String, Vec<CodecRecord>>,
+ }
+ let input: Input = serde_wasm_bindgen::from_value(input)
+ .map_err(|e| JsValue::from_str(&format!("Failed to parse extract-bucket input: {}", e)))?;
+ codec_to_js(&vault_codec::extract_bucket(input.category, input.tables))
+}
+
+/// Generate a fresh 32-byte per-user salt (lowercase hex).
+#[wasm_bindgen(js_name = vaultCodecGenerateUserSalt)]
+pub fn vault_codec_generate_user_salt_js() -> String {
+ vault_codec::generate_user_salt()
+}
+
+/// Pack a payload JSON string into gzip(envelope{contentHash, payload}). Encryption is done by platform.
+#[wasm_bindgen(js_name = vaultCodecPackPayload)]
+pub fn vault_codec_pack_payload_js(payload_json: &str) -> Result<Vec<u8>, JsValue> {
+ vault_codec::pack_payload(payload_json)
+ .map_err(|e| JsValue::from_str(&format!("pack_payload failed: {}", e)))
+}
+
+/// Unpack a (decrypted) payload: gunzip > verify content hash > return payload JSON string.
+#[wasm_bindgen(js_name = vaultCodecUnpackPayload)]
+pub fn vault_codec_unpack_payload_js(plain_bytes: &[u8]) -> Result<String, JsValue> {
+ vault_codec::unpack_payload(plain_bytes)
+ .map_err(|e| JsValue::from_str(&format!("unpack_payload failed: {}", e)))
+}
+
+/// Structurally validate a manifest. Input: `Manifest`. Output: `ValidationResult`.
+#[wasm_bindgen(js_name = vaultCodecValidateManifest)]
+pub fn vault_codec_validate_manifest_js(manifest: JsValue) -> Result<JsValue, JsValue> {
+ let m: Manifest = serde_wasm_bindgen::from_value(manifest)
+ .map_err(|e| JsValue::from_str(&format!("Failed to parse manifest: {}", e)))?;
+ serde_wasm_bindgen::to_value(&vault_codec::validate_manifest(&m))
+ .map_err(|e| JsValue::from_str(&format!("Failed to serialize result: {}", e)))
+}
+
+/// Validate a data bucket. Input: `DataBucket`. Output: `ValidationResult`.
+#[wasm_bindgen(js_name = vaultCodecValidateDataBucket)]
+pub fn vault_codec_validate_data_bucket_js(data_bucket: JsValue) -> Result<JsValue, JsValue> {
+ let b: DataBucket = serde_wasm_bindgen::from_value(data_bucket)
+ .map_err(|e| JsValue::from_str(&format!("Failed to parse data bucket: {}", e)))?;
+ serde_wasm_bindgen::to_value(&vault_codec::validate_data_bucket(&b))
+ .map_err(|e| JsValue::from_str(&format!("Failed to serialize result: {}", e)))
+}
+
+/// SHA-256 (lowercase hex) of a base64 ciphertext string.
+#[wasm_bindgen(js_name = vaultCodecComputeCiphertextHash)]
+pub fn vault_codec_compute_ciphertext_hash_js(base64_ciphertext: &str) -> String {
+ vault_codec::compute_ciphertext_hash(base64_ciphertext)
+}
+
+/// Return the manifest's referenced blob hashes not present in `known_hashes`.
+#[wasm_bindgen(js_name = vaultCodecWhichBlobsToUpload)]
+pub fn vault_codec_which_blobs_to_upload_js(manifest: JsValue, known_hashes: JsValue) -> Result<JsValue, JsValue> {
+ let m: Manifest = serde_wasm_bindgen::from_value(manifest)
+ .map_err(|e| JsValue::from_str(&format!("Failed to parse manifest: {}", e)))?;
+ let known: Vec<String> = serde_wasm_bindgen::from_value(known_hashes)
+ .map_err(|e| JsValue::from_str(&format!("Failed to parse known hashes: {}", e)))?;
+ serde_wasm_bindgen::to_value(&vault_codec::which_blobs_to_upload(&m, known))
+ .map_err(|e| JsValue::from_str(&format!("Failed to serialize result: {}", e)))
+}
+
// ═══════════════════════════════════════════════════════════════════════════════
// Credential Matcher WASM Bindings
// ═══════════════════════════════════════════════════════════════════════════════