Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.
Refactor definitions across all platforms
Leendert de Borst86096bb87adc
diff --git a/apps/browser-extension/src/entrypoints/background/PasskeyHandler.ts b/apps/browser-extension/src/entrypoints/background/PasskeyHandler.tsindex e3fef4db5..9e0dfba4d 100644--- a/apps/browser-extension/src/entrypoints/background/PasskeyHandler.ts+++ b/apps/browser-extension/src/entrypoints/background/PasskeyHandler.ts@@ -256,7 +256,7 @@ export async function handleWebAuthnGetAssertion(const sqliteClient = await createVaultSqliteClient();const credential = await buildPasskeyAssertion(sqliteClient, { origin, publicKey }, passkeyId, manifestId);- // Signing an assertion is a use of the item the passkey hangs off.+ // Signing an assertion is a use of the item the passkey belongs to.const itemId = sqliteClient.passkeys.getById(passkeyId, manifestId)?.ItemId;if (itemId) {void handleRecordItemUsage({ itemId, manifestId, action: 'passkey' });diff --git a/apps/browser-extension/src/entrypoints/popup/pages/passkeys/PasskeyAuthenticate.tsx b/apps/browser-extension/src/entrypoints/popup/pages/passkeys/PasskeyAuthenticate.tsxindex aa2b9ac58..e87b7285a 100644--- a/apps/browser-extension/src/entrypoints/popup/pages/passkeys/PasskeyAuthenticate.tsx+++ b/apps/browser-extension/src/entrypoints/popup/pages/passkeys/PasskeyAuthenticate.tsx@@ -152,7 +152,7 @@ const PasskeyAuthenticate: React.FC = () => {// Build the assertion from the selected passkey using the shared service.const credential = await buildPasskeyAssertion(dbContext.sqliteClient, request, selected.id, selected.manifestId);- // Signing an assertion is a use of the item the passkey hangs off.+ // Signing an assertion is a use of the item the passkey belongs to.sendMessage('RECORD_ITEM_USAGE', { itemId: selected.itemId, manifestId: selected.manifestId, action: 'passkey' }).catch(() => {// Ignore errors});diff --git a/apps/server/Databases/AliasClientDb/Models/VaultTableRegistry.cs b/apps/server/Databases/AliasClientDb/Models/VaultTableRegistry.csindex 0a286f652..65abcead4 100644--- a/apps/server/Databases/AliasClientDb/Models/VaultTableRegistry.cs+++ b/apps/server/Databases/AliasClientDb/Models/VaultTableRegistry.cs@@ -44,5 +44,5 @@ public static class VaultTableRegistry/// <param name="Name">Table name in the client SQLite database.</param>/// <param name="PrimaryKey">The columns that name a row within its manifest, excluding ManifestId.</param>/// <param name="ManifestScoped">True when the table's rows are namespaced per manifest.</param>-/// <param name="ItemChild">True when the table's rows hang off an Item row.</param>+/// <param name="ItemChild">True when the table's rows are child rows of an Item row.</param>public sealed record VaultTableDefinition(string Name, IReadOnlyList<string> PrimaryKey, bool ManifestScoped, bool ItemChild);diff --git a/core/client/src/database/queries/ItemQueries.ts b/core/client/src/database/queries/ItemQueries.tsindex 8a27ce40e..3978ef568 100644--- a/core/client/src/database/queries/ItemQueries.ts+++ b/core/client/src/database/queries/ItemQueries.ts@@ -351,7 +351,7 @@ export class FieldValueQueries {ORDER BY ValueIndex`;/**- * Insert a new field value, into the manifest of the item it hangs off.+ * Insert a new field value, into the manifest of the item it belongs to.*/public static readonly INSERT = `INSERT INTO FieldValues (Id, ItemId, ManifestId, FieldDefinitionId, FieldKey, Value, Weight, ValueIndex, CreatedAt, UpdatedAt, IsDeleted)@@ -424,7 +424,7 @@ export class FieldDefinitionQueries {*/export class FieldHistoryQueries {/**- * Insert a history record, into the manifest of the item it hangs off.+ * Insert a history record, into the manifest of the item it belongs to.*/public static readonly INSERT = `INSERT INTO FieldHistories (Id, ItemId, ManifestId, FieldDefinitionId, FieldKey, ValueSnapshot, ChangedAt, CreatedAt, UpdatedAt, IsDeleted)@@ -492,7 +492,7 @@ export class TotpCodeQueries {WHERE ItemId = ? AND ManifestId = ? AND IsDeleted = 0`;/**- * Insert a new TOTP code, into the manifest of the item it hangs off.+ * Insert a new TOTP code, into the manifest of the item it belongs to.*/public static readonly INSERT = `INSERT INTO TotpCodes (Id, Name, SecretKey, Algorithm, Digits, Period, ItemId, ManifestId, CreatedAt, UpdatedAt, IsDeleted)@@ -542,7 +542,7 @@ export class AttachmentQueries {WHERE ItemId = ? AND ManifestId = ? AND IsDeleted = 0`;/**- * Insert a new attachment, into the manifest of the item it hangs off.+ * Insert a new attachment, into the manifest of the item it belongs to.*/public static readonly INSERT = `INSERT INTO Attachments (Id, Filename, Blob, ItemId, ManifestId, CreatedAt, UpdatedAt, IsDeleted)diff --git a/core/client/src/database/queries/PasskeyQueries.ts b/core/client/src/database/queries/PasskeyQueries.tsindex da0be47aa..198a7cbd6 100644--- a/core/client/src/database/queries/PasskeyQueries.ts+++ b/core/client/src/database/queries/PasskeyQueries.ts@@ -81,7 +81,7 @@ export class PasskeyQueries {ORDER BY p.CreatedAt DESC`;/**- * Insert a new passkey into the manifest of the item it hangs off.+ * Insert a new passkey into the manifest of the item it belongs to.*/public static readonly INSERT = `INSERT INTO Passkeys (diff --git a/core/client/src/database/repositories/ImportExportRepository.ts b/core/client/src/database/repositories/ImportExportRepository.tsindex 7239f302f..af95b555d 100644--- a/core/client/src/database/repositories/ImportExportRepository.ts+++ b/core/client/src/database/repositories/ImportExportRepository.ts@@ -29,7 +29,7 @@ export function createImportWriteSession(): ImportWriteSession {return { writtenDefinitionIds: new Set(), tagIds: new Map() };}-/** A row of a manifest-scoped child table, with the key of the item it hangs off. */+/** A row of a manifest-scoped child table, with the key of the item it belongs to. */type ChildRow = { ItemId: string; ManifestId: string };/** The tables a vault reset empties, dependents first. */diff --git a/core/models/scripts/lib/vault-table-registry-emit.cjs b/core/models/scripts/lib/vault-table-registry-emit.cjsindex bdcb8a987..e14f23f04 100644--- a/core/models/scripts/lib/vault-table-registry-emit.cjs+++ b/core/models/scripts/lib/vault-table-registry-emit.cjs@@ -258,7 +258,7 @@ ${entries}/// <param name="Name">Table name in the client SQLite database.</param>/// <param name="PrimaryKey">The columns that name a row within its manifest, excluding ManifestId.</param>/// <param name="ManifestScoped">True when the table's rows are namespaced per manifest.</param>-/// <param name="ItemChild">True when the table's rows hang off an Item row.</param>+/// <param name="ItemChild">True when the table's rows are child rows of an Item row.</param>public sealed record VaultTableDefinition(string Name, IReadOnlyList<string> PrimaryKey, bool ManifestScoped, bool ItemChild);`;}diff --git a/core/models/src/vault/VaultTableRegistry.ts b/core/models/src/vault/VaultTableRegistry.tsindex 5b674c7db..e7c63fb85 100644--- a/core/models/src/vault/VaultTableRegistry.ts+++ b/core/models/src/vault/VaultTableRegistry.ts@@ -26,7 +26,7 @@ export type VaultTableDefinition = {* tables keyed differently (Settings by Key, ItemTags by its natural key) override this.*/PrimaryKey: string[];- /** True when the table's rows hang off an Item row (re-stamped with their item, cascaded on delete). */+ /** True when the table's rows are child rows of an Item row (re-stamped with their item, cascaded on delete). */ItemChild: boolean;/*** Merge match columns, applied after both sides are normalized to the manifest shape (see thediff --git a/core/rust/src/bindings/uniffi_api.rs b/core/rust/src/bindings/uniffi_api.rsindex b26a5550d..3176da55d 100644--- a/core/rust/src/bindings/uniffi_api.rs+++ b/core/rust/src/bindings/uniffi_api.rs@@ -1,6 +1,4 @@-//! UniFFI API module for Swift and Kotlin bindings.-//!-//! This module exposes the core vault operations via UniFFI for mobile platforms.+//! UniFFI bindings for the iOS and Android apps.use crate::crypto::argon2::Argon2Error;use crate::crypto::{KeyChainError, SrpInputError};@@ -40,17 +38,13 @@ pub fn is_related_origin_allowed(caller_origin: String, origins: Vec<String>) ->crate::credential_matcher::is_related_origin_allowed(&caller_origin, &origins)}-/// Pick the favicon target for an item from its URLs, in the order the item lists them.-///-/// Returns the URL to fetch from and the `Logos.Source` key to store the result under, or-/// `None` when no URL qualifies.+/// The favicon target for an item's URLs (in item order): the URL to fetch and the `Logos.Source` key, or None.#[uniffi::export]pub fn select_favicon_target(urls: Vec<String>) -> Option<crate::favicon::FaviconTarget> {crate::favicon::select_favicon_target(&urls)}-/// Derive the `Logos.Source` key for a URL.-/// Returns an empty string when the URL is not something a favicon can be fetched from.+/// The `Logos.Source` key of a URL, or an empty string when no favicon can be fetched for it.#[uniffi::export]pub fn favicon_source_key(url: String) -> String {crate::favicon::favicon_source_key(&url)@@ -75,22 +69,19 @@ pub fn get_diceware_languages() -> Vec<String> {crate::password_generator::available_languages()}-/// Generate a random identity from `IdentityRequest` JSON (`language`, `gender`, `ageRange`, `birthdateOptions`);-/// returns `Identity` JSON with camelCase fields.+/// Generate a random identity from `IdentityRequest` JSON; returns `Identity` JSON.#[uniffi::export]pub fn generate_identity(request_json: String) -> Result<String, VaultError> {crate::identity_generator::generate_identity(&request_json)}-/// Generate a username from a JSON-serialized name input-/// (`{"firstName":"...","lastName":"...","birthDate":"1990-05-15"}`).+/// Generate a username from name input JSON (`firstName`, `lastName`, `birthDate`).#[uniffi::export]pub fn generate_identity_username(input_json: String) -> Result<String, VaultError> {crate::identity_generator::generate_username(&input_json)}-/// Generate an email prefix from a JSON-serialized name input-/// (`{"firstName":"...","lastName":"...","birthDate":"1990-05-15"}`).+/// Generate an email prefix from name input JSON (`firstName`, `lastName`, `birthDate`).#[uniffi::export]pub fn generate_identity_email_prefix(input_json: String) -> Result<String, VaultError> {crate::identity_generator::generate_email_prefix(&input_json)@@ -114,22 +105,19 @@ pub fn get_identity_age_ranges() -> Vec<String> {crate::identity_generator::available_age_ranges()}-/// Parse a raw RFC 822 email source into its html/plain bodies and attachment metadata, returned as-/// a JSON string (`{htmlBody, textBody, attachments: [{filename, mimeType, size, detached, partIndex}]}`). Input that-/// starts with the gzip magic bytes (0x1f 0x8b) is gunzipped, so the decrypted-/// `MessageSource` of both legacy and source-only emails can be passed as-is.+/// Parse a stored email source into its bodies and attachment metadata, as `ParsedEmail` JSON.#[uniffi::export]pub fn parse_email_source(source: Vec<u8>) -> Result<String, VaultError> {crate::email_parser::parse_email_source_json(&source)}-/// Turn a stored email source into the raw RFC 822 message bytes for showing the message source without parsing it.+/// The raw RFC 822 bytes of a stored email source.#[uniffi::export]pub fn decode_email_source(source: Vec<u8>) -> Result<Vec<u8>, VaultError> {crate::email_parser::decode_email_source(&source)}-/// Extract the decoded bytes of one attachment, identified by its index in the parsed attachment list.+/// The decoded bytes of the attachment at `index`, with its separately fetched body when it is detached.#[uniffi::export]pub fn extract_email_attachment(source: Vec<u8>, index: u32, detached_body: Option<Vec<u8>>) -> Result<Vec<u8>, VaultError> {crate::email_parser::extract_email_attachment(&source, index as usize, detached_body.as_deref())@@ -394,7 +382,7 @@ impl VaultSyncSession {}}-/// An in-memory SQLite database that can be used by host applications to have uniform access to the database.+/// An in-memory SQLite database the host reads and writes through.#[derive(uniffi::Object)]pub struct SqliteMemoryDatabase {inner: MemoryDatabase,@@ -441,7 +429,6 @@ impl SqliteMemoryDatabase {}}-/// Item, passkey and usage-statistics operations on the open vault. Writes open no transaction of their own:/// the host wraps each call in the transaction whose commit persists the vault.#[uniffi::export]diff --git a/core/rust/src/bindings/wasm.rs b/core/rust/src/bindings/wasm.rsindex 14233b91a..5ca6d29a5 100644--- a/core/rust/src/bindings/wasm.rs+++ b/core/rust/src/bindings/wasm.rs@@ -41,9 +41,7 @@ pub fn vault_codec_logo_id_for_js(manifest_id: String, kind: String, source: Str#[wasm_bindgen(js_name = filterCredentials)]pub fn filter_credentials_js(input: JsValue) -> Result<JsValue, JsValue> {let input: CredentialMatcherInput = serde_wasm_bindgen::from_value(input).map_err(js_err)?;-let output: CredentialMatcherOutput = filter_credentials(input);-to_js(&output)}@@ -98,22 +96,19 @@ pub fn get_diceware_languages_js() -> Vec<String> {available_languages()}-/// Generate a random identity from `IdentityRequest` JSON (`language`, `gender`, `ageRange`, `birthdateOptions`);-/// returns `Identity` JSON.+/// Generate a random identity from `IdentityRequest` JSON; returns `Identity` JSON.#[wasm_bindgen(js_name = generateIdentity)]pub fn generate_identity_js(request_json: &str) -> Result<String, JsValue> {crate::identity_generator::generate_identity(request_json).map_err(js_err)}-/// Generate a username from a JSON-serialized name input-/// (`firstName`, `lastName`, `birthDate`).+/// Generate a username from name input JSON (`firstName`, `lastName`, `birthDate`).#[wasm_bindgen(js_name = generateIdentityUsername)]pub fn generate_identity_username_js(input_json: &str) -> Result<String, JsValue> {crate::identity_generator::generate_username(input_json).map_err(js_err)}-/// Generate an email prefix from a JSON-serialized name input-/// (`firstName`, `lastName`, `birthDate`).+/// Generate an email prefix from name input JSON (`firstName`, `lastName`, `birthDate`).#[wasm_bindgen(js_name = generateIdentityEmailPrefix)]pub fn generate_identity_email_prefix_js(input_json: &str) -> Result<String, JsValue> {crate::identity_generator::generate_email_prefix(input_json).map_err(js_err)@@ -137,23 +132,19 @@ pub fn get_identity_age_ranges_js() -> Vec<String> {crate::identity_generator::available_age_ranges()}-/// Parse a raw RFC 822 email source into its html/plain bodies and attachment metadata.-/// Input that starts with the gzip magic bytes (0x1f 0x8b) is gunzipped, so the-/// decrypted `MessageSource` of both legacy and source-only emails can be passed as-is.+/// Parse a stored email source into its bodies and attachment metadata.#[wasm_bindgen(js_name = parseEmailSource)]pub fn parse_email_source_js(source: &[u8]) -> Result<JsValue, JsValue> {to_js(&crate::email_parser::parse_email_source(source).map_err(js_err)?)}-/// Turn a stored email source into the raw RFC 822 message bytes for showing the message source without parsing it.+/// The raw RFC 822 bytes of a stored email source.#[wasm_bindgen(js_name = decodeEmailSource)]pub fn decode_email_source_js(source: &[u8]) -> Result<Vec<u8>, JsValue> {crate::email_parser::decode_email_source(source).map_err(js_err)}-/// Extract the decoded bytes of one attachment, identified by its index in the parsed attachment list.-/// An attachment the parse result flagged as `detached` carries no body in the source; pass its separately-/// fetched body as `detachedBody`. It is ignored for attachments that are still inline.+/// The decoded bytes of the attachment at `index`, with its separately fetched body when it is `detached`.#[wasm_bindgen(js_name = extractEmailAttachment)]pub fn extract_email_attachment_js(source: &[u8], index: usize, detached_body: Option<Box<[u8]>>) -> Result<Vec<u8>, JsValue> {crate::email_parser::extract_email_attachment(source, index, detached_body.as_deref()).map_err(js_err)@@ -371,15 +362,13 @@ pub fn srp_derive_verifier_js(private_key: &str) -> Result<String, JsValue> {/// A client ephemeral pair as `{ public, secret }` (uppercase hex).#[wasm_bindgen(js_name = srpGenerateEphemeral)]pub fn srp_generate_ephemeral_js() -> Result<JsValue, JsValue> {- let ephemeral = crate::crypto::srp::srp_generate_ephemeral();- to_js(&ephemeral)+ to_js(&crate::crypto::srp::srp_generate_ephemeral())}/// The client session as `{ proof, key }` (uppercase hex) from the server's public ephemeral; hex inputs.#[wasm_bindgen(js_name = srpDeriveSession)]pub fn srp_derive_session_js(client_secret: &str, server_public: &str, salt: &str, identity: &str, private_key: &str) -> Result<JsValue, JsValue> {- let session = crate::crypto::srp::srp_derive_session(client_secret, server_public, salt, identity, private_key).map_err(js_err)?;- to_js(&session)+ to_js(&crate::crypto::srp::srp_derive_session(client_secret, server_public, salt, identity, private_key).map_err(js_err)?)}/// Whether the server's proof (M2) matches, which confirms it derived the same session key; hex inputs.@@ -432,7 +421,7 @@ mod sqlite_js {/// JavaScript's `Number.MAX_SAFE_INTEGER` (2^53 - 1).const MAX_SAFE_INTEGER: f64 = 9_007_199_254_740_991.0;- /// An in-memory SQLite database that can be used by host applications to have uniform access to the database.+ /// An in-memory SQLite database the host reads and writes through.#[wasm_bindgen(js_name = SqliteMemoryDatabase)]pub struct SqliteMemoryDatabaseJs {inner: Option<MemoryDatabase>,diff --git a/core/rust/src/credential_matcher/domain.rs b/core/rust/src/credential_matcher/domain.rsindex 4eaf73e87..1f52cfc45 100644--- a/core/rust/src/credential_matcher/domain.rs+++ b/core/rust/src/credential_matcher/domain.rs@@ -1,13 +1,11 @@-//! Domain extraction and matching utilities.+//! Domain extraction and matching.use std::collections::HashSet;use std::sync::LazyLock;use super::public_suffix;-/// Common top-level domains (TLDs) used for app package name detection.-/// When a search string starts with one of these TLDs followed by a dot (e.g., "com.coolblue.app"),-/// it's identified as a reversed domain name (app package name) rather than a regular URL.+/// The TLDs that, as the first label of a dotted string, mark it as an app package name (a reversed domain).static COMMON_TLDS: &[&str] = &[// Generic TLDs"com", "net", "org", "edu", "gov", "mil", "int",@@ -25,22 +23,18 @@ static COMMON_TLDS: &[&str] = &[/// [`COMMON_TLDS`] as a set for constant-time lookup.static COMMON_TLD_SET: LazyLock<HashSet<&'static str>> = LazyLock::new(|| COMMON_TLDS.iter().copied().collect());-/// Check if a string is likely an app package name (reversed domain).-/// Package names start with TLD followed by dot (e.g., "com.example", "nl.app").+/// Whether the text is an app package name: a reversed domain whose first label is a TLD.pub fn is_app_package_name(text: &str) -> bool {if !text.contains('.') || text.starts_with("http://") || text.starts_with("https://") {return false;}- // A first label that is a TLD indicates a reversed domain (package name).let first_part = text.split('.').next().unwrap_or("").to_lowercase();COMMON_TLD_SET.contains(first_part.as_str())}-/// Split a URL into its scheme, authority (host and port) and the path/query/fragment remainder.-///-/// The scheme is returned as written; use [`is_web_scheme`] to test it. A host followed by a-/// numeric port ("example.com:8080") is not mistaken for a scheme.+/// Split a URL into its scheme (as written), authority (host and port) and the rest; a host with a numeric port is not+/// mistaken for a scheme.pub(crate) fn split_url(url: &str) -> (Option<&str>, &str, &str) {let (scheme, after_scheme) = match url.split_once(':') {Some((scheme, rest)) if is_scheme(scheme) && !is_port(rest) => (Some(scheme), rest.strip_prefix("//").unwrap_or(rest)),@@ -68,7 +62,7 @@ fn is_port(rest: &str) -> bool {!port.is_empty() && port.chars().all(|c| c.is_ascii_digit())}-/// Result of domain extraction containing both the domain and optional port.+/// A domain and its port, as extracted from a URL.#[derive(Debug, Clone, PartialEq, Default)]pub struct DomainWithPort {pub domain: String,@@ -76,7 +70,7 @@ pub struct DomainWithPort {}impl DomainWithPort {- /// Returns the domain with port if present (e.g., "example.com:8080")+ /// The domain with its port when it has one.pub fn with_port(&self) -> String {match &self.port {Some(p) => format!("{}:{}", self.domain, p),@@ -85,24 +79,21 @@ impl DomainWithPort {}}-/// Extract domain and port from URL, handling both full URLs and partial domains.-/// Returns DomainWithPort with empty domain if not a valid URL/domain.+/// The domain and port of a URL or partial domain; an empty domain when it is neither.pub fn extract_domain_with_port(url: &str) -> DomainWithPort {let lowered = url.trim().to_lowercase();- // A blob URL ("blob:https://example.com/<uuid>") belongs to the origin it wraps.+ // A blob URL belongs to the origin it wraps.let lowered = lowered.strip_prefix("blob:").unwrap_or(&lowered);let (scheme, authority, _) = split_url(lowered);- // A web scheme is what allows single-word hostnames like "http://plex" or "https://nas",- // common in self-hosted setups. Any other scheme names something that is not a website.+ // A web scheme allows single-word hostnames (self-hosted "https://nas"); any other scheme is not a website.let has_protocol = match scheme {Some(scheme) if is_web_scheme(scheme) => true,Some(_) => return DomainWithPort::default(),None => false,};- // Without a scheme, text starting with a TLD and a dot is an app package name, not a domain.if !has_protocol && is_app_package_name(authority) {return DomainWithPort::default();}@@ -130,7 +121,6 @@ pub fn extract_domain_with_port(url: &str) -> DomainWithPort {/// The host and numeric port of a URL authority, without userinfo and without the trailing dot of a fully qualified name.pub(crate) fn authority_host_port(authority: &str) -> (&str, Option<String>) {- // The host is what follows any userinfo: "https://[email protected]" opens example.com.let host_and_port = authority.rsplit_once('@').map_or(authority, |(_, host)| host);let (host, port) = split_host_port(host_and_port);(host.strip_suffix('.').unwrap_or(host), port)@@ -152,15 +142,12 @@ fn split_host_port(authority: &str) -> (&str, Option<String>) {(host, port)}-/// Extract domain from URL, handling both full URLs and partial domains.-/// Returns empty string if not a valid URL/domain.-/// This strips port numbers; use extract_domain_with_port() to preserve port info.+/// The domain of a URL or partial domain without its port; empty when it is neither.pub fn extract_domain(url: &str) -> String {extract_domain_with_port(url).domain}-/// Check if a host string is an IP address literal (IPv4 with an optional trailing dot, or IPv6, optionally bracketed).-/// IP addresses have no domain hierarchy, so they must never be reduced to a "root domain".+/// Whether a host is an IP literal (IPv4 with an optional trailing dot, or IPv6, optionally bracketed).fn is_ip_literal(host: &str) -> bool {let bare = host.strip_prefix('[').and_then(|h| h.strip_suffix(']')).unwrap_or(host);let bare = bare.strip_suffix('.').unwrap_or(bare);@@ -182,8 +169,7 @@ pub fn domains_match(domain1: &str, domain2: &str) -> bool {return false;}- // IP address literals have no subdomain structure: only the exact same address matches.- // Without this guard, "192.168.1.5" and "10.0.1.5" would both reduce to root "1.5" and match.+ // An IP literal has no domain hierarchy: only the same address matches, never a shared "root" like "1.5".if is_ip_literal(domain1) || is_ip_literal(domain2) {return domain1 == domain2;}@@ -192,17 +178,14 @@ pub fn domains_match(domain1: &str, domain2: &str) -> bool {return true;}- /*- * Anti-phishing: only a shared registrable domain matches. Two hosts under a public suffix ("victim.vercel.app",- * "attacker.vercel.app") never match, and neither do a suffix and a host under it (it has no registrable domain).- */+ // Anti-phishing: only a shared registrable domain matches, so two hosts under a public suffix never do.match (public_suffix::registrable_domain(domain1), public_suffix::registrable_domain(domain2)) {(Some(root1), Some(root2)) => root1 == root2,_ => false,}}-/// Check if a WebAuthn rpId is allowed for a host based on the Public Suffix List.+/// Whether a page on `host` may use `rp_id` as its WebAuthn relying party id: the host or a parent that is not a public suffix.pub fn is_rp_id_allowed_for_host(rp_id: &str, host: &str) -> bool {let (Some(rp_id), Some(host)) = (normalize_rp_host(rp_id), normalize_rp_host(host)) else {return false;@@ -224,7 +207,7 @@ pub fn is_rp_id_allowed_for_host(rp_id: &str, host: &str) -> bool {/// At most this many distinct registrable domain labels are read from a `/.well-known/webauthn` file.pub(super) const MAX_RELATED_ORIGIN_LABELS: usize = 10;-/// WebAuthn related origins validation.+/// Whether `caller_origin` is listed in the `origins` of an rp id's `/.well-known/webauthn` file, within the label cap.pub fn is_related_origin_allowed(caller_origin: &str, origins: &[String]) -> bool {let mut labels_seen: Vec<&str> = Vec::new();for origin in origins {diff --git a/core/rust/src/credential_matcher/mod.rs b/core/rust/src/credential_matcher/mod.rsindex d83bcecd0..86391a0a8 100644--- a/core/rust/src/credential_matcher/mod.rs+++ b/core/rust/src/credential_matcher/mod.rs@@ -28,7 +28,7 @@ use stop_words::STOP_WORD_SET;/// Default per-priority cap on returned matches when the caller does not supply `max_results`.const DEFAULT_MAX_RESULTS: usize = 10;-/// Matching mode for credential filtering.+/// How far a URL match may reach: subdomains and root domain words, subdomains only, or the exact domain.#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]#[serde(rename_all = "camelCase")]pub enum AutofillMatchingMode {@@ -38,49 +38,43 @@ pub enum AutofillMatchingMode {UrlSubdomain,}-/// A credential record for matching.+/// An item as the matcher sees it.#[derive(Debug, Clone, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub struct Credential {pub id: String,pub item_name: Option<String>,- /// List of URLs associated with this item (supports multi-value URL fields)#[serde(default)]pub item_urls: Vec<String>,#[serde(default)]pub username: Option<String>,}-/// Input for credential filtering.+/// What to match against what.#[derive(Debug, Clone, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub struct CredentialMatcherInput {- /// List of credentials to filterpub credentials: Vec<Credential>,- /// Current URL or app package name+ /// The current URL, app package name or search text.pub current_url: String,- /// Current page title (optional)#[serde(default)]pub page_title: String,- /// Matching mode#[serde(default)]pub matching_mode: AutofillMatchingMode,- /// When true, skip port matching entirely (useful for Android where port info is unavailable).- /// All domain matches will be treated equally regardless of port.+ /// Match domains regardless of port (Android has no port information).#[serde(default)]pub ignore_port: bool,- /// Per-priority cap on returned matches, 10 when omitted by the caller.+ /// Cap on returned matches, 10 when omitted.#[serde(default)]pub max_results: Option<usize>,}-/// Output from credential filtering.+/// The matches of the best matching stage.#[derive(Debug, Clone, Default, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub struct CredentialMatcherOutput {- /// IDs of matched credentials, in priority order, capped at `input.max_results` (10 by default).pub matched_ids: Vec<String>,- /// Which priority level matched (1-4, or 0 if no match).+ /// The priority of the stage that matched (1 to 4), or 0 for no match.pub matched_priority: u8,}@@ -91,9 +85,14 @@ impl CredentialMatcherOutput {}}-/// Filter credentials based on current URL and page context with anti-phishing protection.-///-/// Returns the credentials of the best matching priority stage, capped per `input.max_results` (10 by default).+/*+ * The stages run in order and the first one with a match wins: app package name (priority 1), URL domain (2), root+ * domain words or page title words against item names (3), the search text against item names (4).+ * Anti-phishing: the name stages only consider items without URLs, and a URL whose host cannot be extracted matches+ * nothing instead of falling through to them.+ */++/// The credentials of the best matching stage.pub fn filter_credentials(input: CredentialMatcherInput) -> CredentialMatcherOutput {let CredentialMatcherInput { credentials, current_url, page_title, matching_mode, ignore_port, max_results } = input;let max_results = max_results.unwrap_or(DEFAULT_MAX_RESULTS);@@ -103,27 +102,22 @@ pub fn filter_credentials(input: CredentialMatcherInput) -> CredentialMatcherOut}if is_app_package_name(¤t_url) {- // Stage 1: app package name exact match (e.g. com.coolblue.app).+ // Stage 1: app package name. A package name that matches nothing falls through to the text stages.let ids = match_package_name(&credentials, ¤t_url, max_results);if !ids.is_empty() {return CredentialMatcherOutput::matched(1, ids);}- // A package name that matched nothing skips URL matching and falls through to the text stages.} else {let current = extract_domain_with_port(¤t_url);if !current.domain.is_empty() {- // Stage 2: URL domain matching (exact domain+port, exact domain, then subdomain/root domain).+ // Stage 2: URL domain.let allow_subdomain = matches!(matching_mode, AutofillMatchingMode::Default | AutofillMatchingMode::UrlSubdomain);let ids = match_domains(&credentials, ¤t, allow_subdomain, ignore_port, max_results);if !ids.is_empty() {return CredentialMatcherOutput::matched(2, ids);}- /*- * Stage 3: words from only the root domain against item names, e.g. outlook.office.com contributes "office" but not- * "outlook". Only credentials with no URLs are eligible. This is what Default mode adds on top of URL matching, so the- * URL-only modes must not fall back to it.- */+ // Stage 3: root domain words against item names, in Default mode only; the URL-only modes must not fall back to it.if matching_mode == AutofillMatchingMode::Default {let domain_words = extract_words(&extract_root_domain(¤t.domain));let ids = match_item_names(&credentials, &domain_words, max_results);@@ -142,16 +136,14 @@ pub fn filter_credentials(input: CredentialMatcherInput) -> CredentialMatcherOut}}- // Stage 4: page title against item names for input that is neither a URL nor a linked app package.- // Anti-phishing: only credentials with no URLs are eligible.+ // Stage 4: page title words against item names.let title_words = extract_words(&page_title);let ids = match_item_names(&credentials, &title_words, max_results);if !ids.is_empty() {return CredentialMatcherOutput::matched(3, ids);}- // Stage 5: the search string itself against item names. Anti-phishing: only credentials with no URLs- // are eligible, so an app package like "com.paypal.rewards" never gets the PayPal website credential.+ // Stage 5: the search text against item names.let search_words = extract_words(¤t_url);let ids = match_item_names(&credentials, &search_words, max_results);if !ids.is_empty() {@@ -171,19 +163,15 @@ fn match_package_name(credentials: &[Credential], package_name: &str, max_result.collect()}-/// Ids of the credentials at the best domain match rank; only that rank is returned.-///-/// Ranks: 1 exact domain+port, 2 exact domain ignoring port, 3 subdomain/root domain. If any credential-/// matches on domain+port, credentials on the same domain with another port are left out.+/// Ids of the credentials at the best domain match rank (1 domain and port, 2 domain, 3 subdomain or root domain);+/// lower ranks are left out.fn match_domains(credentials: &[Credential], current: &DomainWithPort, allow_subdomain: bool, ignore_port: bool, max_results: usize) -> Vec<String> {let ranked: Vec<(&str, u8)> = credentials.iter().filter_map(|cred| domain_match_rank(cred, current, allow_subdomain, ignore_port).map(|rank| (cred.id.as_str(), rank))).collect();- let Some(best) = ranked.iter().map(|(_, rank)| *rank).min() else {- return vec![];- };+ let Some(best) = ranked.iter().map(|(_, rank)| *rank).min() else { return vec![] };ranked.into_iter().filter(|(_, rank)| *rank == best).map(|(id, _)| id.to_string()).take(max_results).collect()}@@ -198,8 +186,7 @@ fn domain_match_rank(cred: &Credential, current: &DomainWithPort, allow_subdomaicontinue;}- // Rank 1 needs the same domain AND the same port (or both no port). Android does not provide- // port information, so with ignore_port the plain domain match is the best available.+ // Rank 1 needs the same domain and port (or both none); with ignore_port the plain domain match is the best there is.if !ignore_port && current.domain == item.domain && current.port == item.port {return Some(1);}@@ -219,9 +206,8 @@ fn domain_match_rank(cred: &Credential, current: &DomainWithPort, allow_subdomaibest}-/// Ids of credentials without URLs whose item name shares a complete word with `words`.-///-/// Credentials that have any URL are skipped: a name match must never surface a credential bound to another site (anti-phishing).+/// Ids of credentials without URLs whose item name shares a complete word with `words`; a credential with a URL never+/// matches by name (anti-phishing).fn match_item_names(credentials: &[Credential], words: &[String], max_results: usize) -> Vec<String> {if words.is_empty() {return vec![];@@ -241,10 +227,10 @@ fn match_item_names(credentials: &[Credential], words: &[String], max_results: u.collect()}-/// Title words of this many characters or fewer are too generic to match on.+/// Words of this many characters or fewer are too generic to match on.const MAX_IGNORED_WORD_CHARS: usize = 3;-/// Extract meaningful words from text, removing punctuation and filtering stop words.+/// The lowercase words of a text, without punctuation, short words and stop words.fn extract_words(text: &str) -> Vec<String> {if text.is_empty() {return vec![];@@ -260,7 +246,7 @@ fn extract_words(text: &str) -> Vec<String> {.collect()}-/// JSON sibling of [`filter_credentials`]. Input: `CredentialMatcherInput`. Output: `CredentialMatcherOutput`.+/// [`filter_credentials`] over JSON, for the uniffi bindings.pub fn filter_credentials_json(input_json: &str) -> crate::common::error::VaultResult<String> {crate::common::error::json_call(input_json, |input| Ok(filter_credentials(input)))}diff --git a/core/rust/src/credential_matcher/stop_words.rs b/core/rust/src/credential_matcher/stop_words.rsindex 9809be0cc..cdc6b5cfc 100644--- a/core/rust/src/credential_matcher/stop_words.rs+++ b/core/rust/src/credential_matcher/stop_words.rs@@ -1,5 +1,4 @@-//! Stop words for filtering page titles during credential matching.-//!+//! Stop words left out of the words a credential name is matched on.use std::collections::HashSet;use std::sync::LazyLock;diff --git a/core/rust/src/email_parser/mod.rs b/core/rust/src/email_parser/mod.rsindex 609344fb5..e840816a6 100644--- a/core/rust/src/email_parser/mod.rs+++ b/core/rust/src/email_parser/mod.rs@@ -1,51 +1,48 @@-//! Email MIME parsing for source-only stored emails.+//! Email MIME parsing: the bodies and attachment metadata of a stored RFC 822 source.++#[cfg(test)]+mod tests;+use mail_parser::{GetHeader, Message, MessageParser, MessagePart, MimeHeaders};use serde::Serialize;use crate::common::error::{VaultError, VaultResult};use crate::common::gzip::{gunzip, is_gzip};-/// Header the server stamps on an attachment whose body it detached from the source at ingest, carrying the-/// index that body is stored and requested under. Reading the index from the message itself keeps it-/// independent of how any given MIME parser happens to order a message's attachments.+/// Header the server stamps on an attachment whose body it detached from the source, carrying the index that body is stored under.const DETACHED_PART_INDEX_HEADER: &str = "X-AliasVault-Part";-/// Header the server stamps on a detached attachment carrying its decoded size, so the size can be shown in-/// the attachment list without downloading the body.+/// Header the server stamps on a detached attachment, carrying its decoded size.const DETACHED_PART_LENGTH_HEADER: &str = "X-AliasVault-Detached-Length";/// Cap on a gunzipped email source or detached part, with headroom over the ~14 MB the SMTP service accepts.const MAX_DECOMPRESSED_EMAIL_BYTES: u64 = 64 * 1024 * 1024;-/// A single attachment of a parsed email message. Metadata only: fetch the bytes with-/// [`extract_email_attachment`] using this attachment's index in [`ParsedEmail::attachments`].+/// An attachment of a parsed email, metadata only.#[derive(Debug, Clone, Serialize)]#[serde(rename_all = "camelCase")]pub struct ParsedEmailAttachment {pub filename: String,pub mime_type: String,- /// The decoded attachment size in bytes.+ /// The decoded size in bytes.pub size: u64,- /// Whether this attachment's body lives outside the message source and has to be fetched separately- /// before [`extract_email_attachment`] can return its bytes.+ /// Whether the body lives outside the source and has to be fetched separately.pub detached: bool,- /// The index the detached body is stored under, to request it by. `None` for an attachment whose body- /// is still inline in the source.+ /// The index a detached body is stored under; None while the body is inline.pub part_index: Option<u32>,}-/// The result of parsing a raw RFC 822 email source.+/// The bodies and attachments of a parsed email.#[derive(Debug, Clone, Serialize)]#[serde(rename_all = "camelCase")]pub struct ParsedEmail {pub html_body: Option<String>,pub text_body: Option<String>,- /// The attachments contained in the message, in the index order [`extract_email_attachment`] expects.+ /// In the order [`extract_email_attachment`] indexes them.pub attachments: Vec<ParsedEmailAttachment>,}-/// Parse a raw RFC 822 email source into its bodies and attachment metadata, transparently-/// gunzipping gzip-compressed input.+/// Parse a stored email source into its bodies and attachment metadata.pub fn parse_email_source(source: &[u8]) -> VaultResult<ParsedEmail> {let raw = decode_email_source(source)?;let message = parse_message(&raw)?;@@ -68,7 +65,7 @@ pub fn parse_email_source(source: &[u8]) -> VaultResult<ParsedEmail> {None => content_type.ctype().to_string(),}).unwrap_or_else(|| "application/octet-stream".to_string()),- // The real size of a detached attachment comes from the header the server stamped on it.+ // A detached body is not in the source, so its size comes from the stamped header.size: header_u64(part, DETACHED_PART_LENGTH_HEADER).unwrap_or_else(|| part.contents().len() as u64),detached: part_index.is_some(),part_index,@@ -79,99 +76,76 @@ pub fn parse_email_source(source: &[u8]) -> VaultResult<ParsedEmail> {Ok(ParsedEmail { html_body, text_body, attachments })}-/// Turn a stored email source into the raw RFC 822 message bytes: gunzip the source-only storage-/// format, repair the double encoding of the legacy format. Clients use this for the source view.+/// The raw RFC 822 bytes of a stored email source.pub fn decode_email_source(source: &[u8]) -> VaultResult<Vec<u8>> {if is_gzip(source) {return gunzip(source, MAX_DECOMPRESSED_EMAIL_BYTES);}+ // LEGACY: sources stored before 0.31.0 are not gzipped and are double encoded. TODO: remove once no such sources are served.Ok(repair_legacy_double_encoding(source.to_vec()))}-/// Extract the decoded bytes of a single attachment, identified by its index in-/// [`ParsedEmail::attachments`].+/// The decoded bytes of the attachment at `index`, with its detached body when it has one.pub fn extract_email_attachment(source: &[u8], index: usize, detached_body: Option<&[u8]>) -> VaultResult<Vec<u8>> {let raw = decode_email_source(source)?;- // Resolve what the attachment needs before splicing: the parsed message borrows `raw`, so nothing that- // borrows it may outlive this block.+ // The parsed message borrows `raw`, so what the splice needs is read out before `raw` is used again.let (body_range, detached_body) = {let message = parse_message(&raw)?;let part = attachment_at(&message, index)?;match (detached_part_index(part).is_some(), detached_body) {(false, _) => return Ok(part.contents().to_vec()),- (true, None) => {- return Err(VaultError::General(format!(- "Attachment at index {} was detached from the source at ingest; its body has to be fetched separately",- index- )))- }+ (true, None) => return Err(VaultError::General(format!("Attachment at index {} is detached; its body has to be fetched separately", index))),(true, Some(body)) => (part.offset_body as usize..part.offset_end as usize, body),}};- let body = decode_detached_part(detached_body)?;+ let body = gunzip(detached_body, MAX_DECOMPRESSED_EMAIL_BYTES)?;let mut spliced = Vec::with_capacity(raw.len() + body.len());spliced.extend_from_slice(&raw[..body_range.start]);spliced.extend_from_slice(&body);spliced.extend_from_slice(&raw[body_range.end..]);let message = parse_message(&spliced)?;- let extracted = attachment_at(&message, index)?.contents().to_vec();-- Ok(extracted)+ Ok(attachment_at(&message, index)?.contents().to_vec())}-/// Parse a raw RFC 822 email source and return the result as a JSON string (for uniffi/ffi callers).+/// [`parse_email_source`] as JSON, for the uniffi bindings.pub fn parse_email_source_json(source: &[u8]) -> VaultResult<String> {Ok(serde_json::to_string(&parse_email_source(source)?)?)}-/// Parse raw RFC 822 bytes into a message, turning the parser's `None` into a proper error.+/// Parse raw RFC 822 bytes into a message.fn parse_message(raw: &[u8]) -> VaultResult<Message<'_>> {- MessageParser::default()- .parse(raw)- .ok_or_else(|| VaultError::General("Failed to parse email source as a MIME message".to_string()))+ MessageParser::default().parse(raw).ok_or_else(|| VaultError::General("Failed to parse email source as a MIME message".to_string()))}-/// Look up an attachment by its index in the message's attachment list.+/// The attachment at `index` in the message's attachment list.fn attachment_at<'x>(message: &'x Message<'x>, index: usize) -> VaultResult<&'x MessagePart<'x>> {- message- .attachments()- .nth(index)- .ok_or_else(|| VaultError::General(format!("Email has no attachment at index {}", index)))+ message.attachments().nth(index).ok_or_else(|| VaultError::General(format!("Email has no attachment at index {}", index)))}-/// Read the index a detached attachment's body is stored under, or `None` when the body is still inline.+/// The index a detached attachment's body is stored under, or None while the body is inline.fn detached_part_index(part: &MessagePart<'_>) -> Option<u32> {header_u64(part, DETACHED_PART_INDEX_HEADER).and_then(|index| u32::try_from(index).ok())}-/// Read a header of a part as an unsigned number, ignoring it when absent or not numeric.+/// A header of a part as an unsigned number, or None when absent or not numeric.fn header_u64(part: &MessagePart<'_>, name: &str) -> Option<u64> {- part.headers- .header(name)- .and_then(|header| header.value().as_text())- .and_then(|value| value.trim().parse::<u64>().ok())-}--/// Decompress a stored detached attachment body. Unlike the message source there is no legacy encoding to-/// repair: detached parts only exist in the source-only storage format.-fn decode_detached_part(body: &[u8]) -> VaultResult<Vec<u8>> {- gunzip(body, MAX_DECOMPRESSED_EMAIL_BYTES)+ part.headers.header(name).and_then(|header| header.value().as_text()).and_then(|value| value.trim().parse::<u64>().ok())}-/// Undo the Latin-1 then UTF-8 double encoding of legacy (pre-0.31.0) stored sources, where `é` (`C3 A9`) became `C3 83 C2 A9`.-/// A no-op for anything that is not valid UTF-8 made only of characters up to U+00FF, such as an already correct source.+/// LEGACY: undo the Latin-1 then UTF-8 double encoding of sources stored before 0.31.0, where `C3 A9` became `C3 83 C2 A9`.+/// A no-op for bytes that are not valid UTF-8 or contain a character above U+00FF, such as a correct source.fn repair_legacy_double_encoding(raw: Vec<u8>) -> Vec<u8> {let text = match std::str::from_utf8(&raw) {Ok(text) => text,Err(_) => return raw,};+ // Pure ASCII was not changed by the double encoding.if !text.chars().any(|c| c as u32 > 0x7f) {- // Pure ASCII: the double encoding was a no-op, so there is nothing to undo.return raw;}@@ -181,6 +155,3 @@ fn repair_legacy_double_encoding(raw: Vec<u8>) -> Vec<u8> {text.chars().map(|c| c as u8).collect()}--#[cfg(test)]-mod tests;diff --git a/core/rust/src/identity_generator/dictionaries/mod.rs b/core/rust/src/identity_generator/dictionaries/mod.rsindex d394939be..f306396bd 100644--- a/core/rust/src/identity_generator/dictionaries/mod.rs+++ b/core/rust/src/identity_generator/dictionaries/mod.rs@@ -13,11 +13,9 @@//! (e.g. `firstnames_male_1980_1989.txt`), so generated first names match names//! that were popular around the generated birth year. Used by de, it and ro.-/// First names that were popular for births within `[start_year, end_year]`.+/// First names popular for births in `start_year..=end_year`.pub(crate) struct DecadeNames {- /// First birth year covered by this list (inclusive).pub start_year: i32,- /// Last birth year covered by this list (inclusive).pub end_year: i32,raw: &'static str,}@@ -29,26 +27,26 @@ impl DecadeNames {}}-/// All embedded name lists for one language.+/// The name lists of one language.pub(crate) struct LanguageDictionary {- /// Two-letter ISO 639-1 language code.+ /// The ISO 639-1 language code.pub code: &'static str,firstnames_male: &'static str,firstnames_female: &'static str,lastnames: &'static str,- /// Decade-based male first names; empty for languages with flat lists.+ /// Empty for a language with flat lists.pub firstnames_male_by_decade: &'static [DecadeNames],- /// Decade-based female first names; empty for languages with flat lists.+ /// Empty for a language with flat lists.pub firstnames_female_by_decade: &'static [DecadeNames],}impl LanguageDictionary {- /// Flat male first names (empty for decade-based languages).+ /// Flat male first names; empty for a decade-based language.pub fn firstnames_male(&self) -> Vec<&'static str> {parse_names(self.firstnames_male).collect()}- /// Flat female first names (empty for decade-based languages).+ /// Flat female first names; empty for a decade-based language.pub fn firstnames_female(&self) -> Vec<&'static str> {parse_names(self.firstnames_female).collect()}@@ -59,7 +57,7 @@ impl LanguageDictionary {}}-/// Shorthand for a flat-list language entry.+/// A language with flat first name lists.macro_rules! flat_language {($code:literal) => {LanguageDictionary {@@ -73,20 +71,14 @@ macro_rules! flat_language {};}-/// Shorthand for one decade entry of a decade-based language.+/// One decade list of a decade-based language.macro_rules! decade {($code:literal, $gender:literal, $start:literal, $end:literal) => {- DecadeNames {- start_year: $start,- end_year: $end,- raw: include_str!(concat!(- $code, "/firstnames_", $gender, "_", $start, "_", $end, ".txt"- )),- }+ DecadeNames { start_year: $start, end_year: $end, raw: include_str!(concat!($code, "/firstnames_", $gender, "_", $start, "_", $end, ".txt")) }};}-/// Shorthand for a decade-based language entry (no flat first name lists).+/// A language with first name lists per birth decade.macro_rules! decade_language {($code:literal, $(($start:literal, $end:literal)),+ $(,)?) => {LanguageDictionary {@@ -94,18 +86,13 @@ macro_rules! decade_language {firstnames_male: "",firstnames_female: "",lastnames: include_str!(concat!($code, "/lastnames.txt")),- firstnames_male_by_decade: &[- $(decade!($code, "male", $start, $end)),+- ],- firstnames_female_by_decade: &[- $(decade!($code, "female", $start, $end)),+- ],+ firstnames_male_by_decade: &[$(decade!($code, "male", $start, $end)),+],+ firstnames_female_by_decade: &[$(decade!($code, "female", $start, $end)),+],}};}-/// The registry of bundled language dictionaries. The order here is the order returned-/// by the language list APIs. English is the fallback for unknown codes.+/// The bundled languages, in the order the language list reports them.pub(crate) static DICTIONARIES: &[LanguageDictionary] = &[flat_language!("da"),decade_language!(@@ -148,28 +135,18 @@ pub(crate) static DICTIONARIES: &[LanguageDictionary] = &[flat_language!("fa"),];-/// Resolve a language code (case-insensitive) to its dictionary, falling back to-/// English for any unknown or empty code.+/// The dictionary of a language (case-insensitive code); an unknown or empty code gives English.pub(crate) fn resolve(code: &str) -> &'static LanguageDictionary {- DICTIONARIES- .iter()- .find(|d| d.code.eq_ignore_ascii_case(code))- .unwrap_or_else(|| {- DICTIONARIES- .iter()- .find(|d| d.code == "en")- .expect("English dictionary must be registered")- })+ let by_code = |wanted: &str| DICTIONARIES.iter().find(|d| d.code.eq_ignore_ascii_case(wanted));+ by_code(code).unwrap_or_else(|| by_code("en").expect("English dictionary must be registered"))}-/// List the codes of all bundled languages, in registry order.+/// The codes of the bundled languages, in registry order.pub(crate) fn available_codes() -> Vec<&'static str> {DICTIONARIES.iter().map(|d| d.code).collect()}-/// Split raw embedded text into trimmed, non-empty names.+/// The trimmed, non-empty lines of an embedded name file.fn parse_names(raw: &'static str) -> impl Iterator<Item = &'static str> {- raw.lines()- .map(|line| line.trim())- .filter(|line| !line.is_empty())+ raw.lines().map(|line| line.trim()).filter(|line| !line.is_empty())}diff --git a/core/rust/src/identity_generator/mod.rs b/core/rust/src/identity_generator/mod.rsindex 35caa5734..5b4144a64 100644--- a/core/rust/src/identity_generator/mod.rs+++ b/core/rust/src/identity_generator/mod.rs@@ -21,98 +21,85 @@ use serde::{Deserialize, Serialize};use crate::common::error::{json_call, VaultError};use crate::common::rng::{make_rng, unbiased_index};-/// Gender value used in generated identities.pub const GENDER_MALE: &str = "Male";-/// Gender value used in generated identities.pub const GENDER_FEMALE: &str = "Female";-/// Default minimum age (in years) for generated birth dates.+// The age window of a generated birth date when the request names no age range or birth year.const DEFAULT_MIN_AGE: i32 = 21;-/// Default maximum age (in years) for generated birth dates.const DEFAULT_MAX_AGE: i32 = 65;/// The age range option values offered by the settings UIs; "random" means the default 21-65 range.const AGE_RANGES: &[&str] = &["random", "21-25", "26-30", "31-35", "36-40", "41-45", "46-50", "51-55", "56-60", "61-65"];-/// A generated identity, serialized with camelCase field names to match the JSON contract shared by all clients.+/// A generated identity.#[derive(Debug, Clone, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub struct Identity {- /// First name, matching the requested language and the birth decade where available.pub first_name: String,- /// Last name, matching the requested language.pub last_name: String,- /// Gender the first name was drawn from: "Male" or "Female".+ /// "Male" or "Female".pub gender: String,- /// Birth date in `yyyy-MM-dd` format.+ /// `yyyy-MM-dd`.pub birth_date: String,- /// Email prefix derived from the name and birth year.pub email_prefix: String,- /// Username derived from the name and birth year (alphanumeric only).+ /// ASCII alphanumeric only.pub nick_name: String,}-/// Explicit birth year window for generation: a target year plus/minus a deviation.+/// A birth year window: a target year plus or minus a deviation.#[derive(Debug, Clone, Copy, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub struct BirthdateOptions {- /// The central birth year.pub target_year: i32,- /// Allowed deviation in years around the target (0 = within the target year only).+ /// 0 keeps the birth date within the target year.pub year_deviation: i32,}-/// Request controlling identity generation. Every field is optional; unknown languages fall back to English.+/// Request controlling identity generation; every field is optional.#[derive(Debug, Clone, Default, Deserialize)]#[serde(rename_all = "camelCase", default)]pub struct IdentityRequest {- /// Dictionary language code (e.g. "en", "nl"). Empty or unknown falls back to English.+ /// Dictionary language code; empty or unknown falls back to English.pub language: String,- /// Gender preference: "male", "female" or "random" (default).+ /// "male", "female" or anything else for a coin flip.pub gender: Option<String>,- /// Age range preference as stored in settings (e.g. "21-25" or "random"). Ignored when `birthdate_options` is set.+ /// An [`AGE_RANGES`] value; ignored when `birthdate_options` is set.pub age_range: Option<String>,- /// Explicit birth year window. Takes precedence over `age_range`.pub birthdate_options: Option<BirthdateOptions>,- /// Optional 32-byte RNG seed as a 64-character hex string for deterministic output (used by tests).+ /// Optional 32-byte RNG seed as 64 hex characters; the same seed gives the same output.pub seed: Option<String>,}-/// Name and birth date input for username/email prefix generation, from a generated identity or persona fields typed by the user.+/// Name and birth date input for username and email prefix generation.#[derive(Debug, Clone, Default, Deserialize)]#[serde(rename_all = "camelCase", default)]pub struct NameInput {- /// First name.pub first_name: String,- /// Last name.pub last_name: String,- /// Birth date; only the leading `yyyy` year part is used.+ /// Only the leading `yyyy` year is used.pub birth_date: String,- /// Optional 32-byte RNG seed as a 64-character hex string (used by tests).+ /// Optional 32-byte RNG seed as 64 hex characters; the same seed gives the same output.pub seed: Option<String>,}-/// Generate a random identity from a JSON-serialized [`IdentityRequest`].-///-/// Returns the generated [`Identity`] as a JSON string, or a [`VaultError`] if the request JSON is invalid.+/// Generate a random identity from a JSON-serialized [`IdentityRequest`], as JSON.pub fn generate_identity(request_json: &str) -> Result<String, VaultError> {json_call(request_json, |request: IdentityRequest| Ok(generate_from_request(&request)))}-/// Generate a random identity from an already-parsed request.+/// Generate a random identity from a parsed request.fn generate_from_request(request: &IdentityRequest) -> Identity {let mut rng = make_rng(request.seed.as_deref());let dictionary = dictionaries::resolve(&request.language);- // Determine gender: explicit "male"/"female" wins, anything else is a coin flip.let is_male = match request.gender.as_deref() {Some("male") => true,Some("female") => false,_ => unbiased_index(&mut rng, 2) == 0,};- // Generate the birth date first: decade-based languages select first names by birth year.- let birthdate_options = request.birthdate_options.or_else(|| age_range_to_birthdate_options(request.age_range.as_deref().unwrap_or("")));+ // The birth date comes first: decade-based dictionaries select first names by birth year.+ let birthdate_options = request.birthdate_options.or_else(|| age_range_to_birthdate_options(request.age_range.as_deref().unwrap_or(""), Utc::now().year()));let birth_date = random_birth_date(&mut rng, birthdate_options, Utc::now().date_naive());let first_names = select_firstnames_for_birth_year(dictionary, birth_date.year(), is_male);@@ -122,7 +109,6 @@ fn generate_from_request(request: &IdentityRequest) -> Identity {let last_name = last_names[unbiased_index(&mut rng, last_names.len())].to_string();let birth_year = Some(birth_date.year());- // The email prefix and nickname are generated independently (separate random rolls).let email_prefix = username_email::generate_email_prefix(&mut rng, &first_name, &last_name, birth_year);let nick_name = username_email::generate_username(&mut rng, &first_name, &last_name, birth_year);@@ -150,45 +136,36 @@ pub fn generate_email_prefix(input_json: &str) -> Result<String, VaultError> {Ok(username_email::generate_email_prefix(&mut rng, &input.first_name, &input.last_name, parse_birth_year(&input.birth_date)))}-/// Generate a random alphanumeric email prefix that is not based on any identity, for credentials without persona fields.+/// Generate a random alphanumeric email prefix of `length` characters (1 to 64), not based on any identity.pub fn generate_random_email_prefix(length: u32) -> String {let mut rng = make_rng(None);username_email::generate_random_string(&mut rng, length.clamp(1, 64) as usize)}-/// List the language codes of all bundled identity dictionaries.+/// The language codes of the bundled name dictionaries.pub fn available_languages() -> Vec<String> {dictionaries::available_codes().into_iter().map(|c| c.to_string()).collect()}-/// List the age range option values offered by the settings UIs ("random" plus 5-year ranges from 21-25 to 61-65).+/// The age range option values offered by the settings UIs.pub fn available_age_ranges() -> Vec<String> {AGE_RANGES.iter().map(|r| r.to_string()).collect()}-/// Birth year options for an age range (e.g. "21-25") relative to the current year; `None` (default 21-65) for anything else.-fn age_range_to_birthdate_options(age_range: &str) -> Option<BirthdateOptions> {- age_range_to_birthdate_options_at(age_range, Utc::now().year())-}--/// [`age_range_to_birthdate_options`] with an explicit current year, for testability.-fn age_range_to_birthdate_options_at(age_range: &str, current_year: i32) -> Option<BirthdateOptions> {+/// The birth year window of an age range like "21-25" relative to `current_year`; `None` for anything else.+fn age_range_to_birthdate_options(age_range: &str, current_year: i32) -> Option<BirthdateOptions> {let (min_part, max_part) = age_range.split_once('-')?;let min_age: i32 = min_part.parse().ok()?;let max_age: i32 = max_part.parse().ok()?;let middle_age = (min_age + max_age).div_euclid(2);- Some(BirthdateOptions {- target_year: current_year - middle_age,- year_deviation: (max_age - min_age).div_euclid(2),- })+ Some(BirthdateOptions { target_year: current_year - middle_age, year_deviation: (max_age - min_age).div_euclid(2) })}/// A random birth date, uniform within the options' year window, or else between 65 and 21 years before `today`.fn random_birth_date<R: Rng + ?Sized>(rng: &mut R, options: Option<BirthdateOptions>, today: NaiveDate) -> NaiveDate {let (start, end) = match options {Some(BirthdateOptions { target_year, year_deviation }) => {- // Sanity check for overflows in the calculation.let deviation = year_deviation.saturating_abs();(first_day_of_year(target_year.saturating_sub(deviation)), last_day_of_year(target_year.saturating_add(deviation)))}@@ -209,7 +186,6 @@ fn select_firstnames_for_birth_year(dictionary: &'static dictionaries::LanguageDreturn matching;}- // No decade covers this birth year: fall back to all decade names combined.let all: Vec<&'static str> = decades.iter().flat_map(|d| d.names()).collect();if !all.is_empty() {return all;@@ -219,7 +195,7 @@ fn select_firstnames_for_birth_year(dictionary: &'static dictionaries::LanguageDif is_male { dictionary.firstnames_male() } else { dictionary.firstnames_female() }}-/// The leading `yyyy` year of a date string like `1990-05-15` or an ISO 8601 timestamp, or `None` when absent.+/// The leading `yyyy` year of a date string or ISO 8601 timestamp, or `None` when absent.fn parse_birth_year(birth_date: &str) -> Option<i32> {let digits: String = birth_date.trim().chars().take(4).collect();if digits.len() == 4 && digits.chars().all(|c| c.is_ascii_digit()) {@@ -229,18 +205,17 @@ fn parse_birth_year(birth_date: &str) -> Option<i32> {}}-/// January 1 of the given year.+/// January 1 of a year.fn first_day_of_year(year: i32) -> NaiveDate {NaiveDate::from_ymd_opt(year, 1, 1).unwrap_or(NaiveDate::MIN)}-/// December 31 of the given year.+/// December 31 of a year.fn last_day_of_year(year: i32) -> NaiveDate {NaiveDate::from_ymd_opt(year, 12, 31).unwrap_or(NaiveDate::MAX)}/// The same calendar day `years` years before `date` (Feb 29 maps to Feb 28).fn years_ago(date: NaiveDate, years: i32) -> NaiveDate {- date.with_year(date.year() - years)- .unwrap_or_else(|| NaiveDate::from_ymd_opt(date.year() - years, 2, 28).unwrap_or(NaiveDate::MIN))+ date.with_year(date.year() - years).unwrap_or_else(|| NaiveDate::from_ymd_opt(date.year() - years, 2, 28).unwrap_or(NaiveDate::MIN))}diff --git a/core/rust/src/identity_generator/tests/mod.rs b/core/rust/src/identity_generator/tests/mod.rsindex 1f13089ea..b97996902 100644--- a/core/rust/src/identity_generator/tests/mod.rs+++ b/core/rust/src/identity_generator/tests/mod.rs@@ -206,7 +206,7 @@ fn age_range_conversion_matches_reference_values() {("20-24", 2003, 2),];for (range, target_year, year_deviation) in cases {- let options = age_range_to_birthdate_options_at(range, 2025).unwrap();+ let options = age_range_to_birthdate_options(range, 2025).unwrap();assert_eq!(options.target_year, target_year, "range {range}");assert_eq!(options.year_deviation, year_deviation, "range {range}");}@@ -216,7 +216,7 @@ fn age_range_conversion_matches_reference_values() {fn age_range_conversion_rejects_invalid_input() {for input in ["random", "", "2125", "21-25-30", "abc-def", "21-abc"] {assert!(- age_range_to_birthdate_options_at(input, 2025).is_none(),+ age_range_to_birthdate_options(input, 2025).is_none(),"expected None for {input:?}");}diff --git a/core/rust/src/identity_generator/username_email.rs b/core/rust/src/identity_generator/username_email.rsindex 98d3fee5b..88f1f6426 100644--- a/core/rust/src/identity_generator/username_email.rs+++ b/core/rust/src/identity_generator/username_email.rs@@ -1,4 +1,5 @@-//! Username and email prefix generation based on an identity's name and birth year.+//! Username and email prefix generation from a name and birth year.+use rand::Rng;use crate::common::rng::unbiased_index;@@ -9,29 +10,19 @@ const SYMBOLS: [char; 2] = ['.', '-'];const RANDOM_CHARS: &[u8] = b"abcdefghijklmnopqrstuvwxyz0123456789";/// Generate an email prefix from a first name, last name and optional birth year.-pub fn generate_email_prefix<R: Rng + ?Sized>(- rng: &mut R,- first_name: &str,- last_name: &str,- birth_year: Option<i32>,-) -> String {+pub fn generate_email_prefix<R: Rng + ?Sized>(rng: &mut R, first_name: &str, last_name: &str, birth_year: Option<i32>) -> String {let first = first_name.to_lowercase();let last = last_name.to_lowercase();let name_part = match unbiased_index(rng, 4) {- // First initial + last name0 => format!("{}{}", first_chars(&first, 1), last),- // Full name1 => format!("{}{}", first, last),- // First name + last initial2 => format!("{}{}", first, first_chars(&last, 1)),- // First 3 chars of first name + last name_ => format!("{}{}", first_chars(&first, 3), last),};let mut parts = vec![name_part];- // Add a birth year variation for uniqueness (full year or last two digits).if let Some(year) = birth_year {let year = year.to_string();parts.push(match unbiased_index(rng, 2) {@@ -40,18 +31,13 @@ pub fn generate_email_prefix<R: Rng + ?Sized>(});}- // Join parts with a random symbol (2 in 3 chance of no symbol at all).let mut prefix = parts.join(&random_symbol(rng));- // 50% chance to insert one extra random symbol at a random position.+ // One extra symbol at a random position, half of the time.if unbiased_index(rng, 2) == 0 && !prefix.is_empty() {let char_count = prefix.chars().count();let position = unbiased_index(rng, char_count);- let byte_index = prefix- .char_indices()- .nth(position)- .map(|(i, _)| i)- .unwrap_or(prefix.len());+ let byte_index = prefix.char_indices().nth(position).map(|(i, _)| i).unwrap_or(prefix.len());prefix.insert_str(byte_index, &random_symbol(rng));}@@ -59,28 +45,16 @@ pub fn generate_email_prefix<R: Rng + ?Sized>(adjust_length(rng, prefix)}-/// Generate a username from a first name, last name and optional birth year.-///-/// Uses the same construction as the email prefix but strips all non-alphanumeric-/// characters. Note this rolls its own randomness, so a username generated alongside-/// an email prefix is not simply the stripped version of that prefix.-pub fn generate_username<R: Rng + ?Sized>(- rng: &mut R,- first_name: &str,- last_name: &str,- birth_year: Option<i32>,-) -> String {+/// Generate a username: an email prefix from its own random rolls, stripped to ASCII alphanumerics.+pub fn generate_username<R: Rng + ?Sized>(rng: &mut R, first_name: &str, last_name: &str, birth_year: Option<i32>) -> String {let prefix = generate_email_prefix(rng, first_name, last_name, birth_year);let username: String = prefix.chars().filter(|c| c.is_ascii_alphanumeric()).collect();adjust_length(rng, username)}-/// Generate a random alphanumeric string, suitable for email prefixes that are not-/// based on any identity (e.g. login-type credentials without persona fields).+/// A random string of lowercase letters and digits.pub fn generate_random_string<R: Rng + ?Sized>(rng: &mut R, length: usize) -> String {- (0..length)- .map(|_| RANDOM_CHARS[unbiased_index(rng, RANDOM_CHARS.len())] as char)- .collect()+ (0..length).map(|_| RANDOM_CHARS[unbiased_index(rng, RANDOM_CHARS.len())] as char).collect()}/// Pad a too-short value with random characters or truncate a too-long one.@@ -94,7 +68,7 @@ fn adjust_length<R: Rng + ?Sized>(rng: &mut R, mut value: String) -> String {value}-/// Return a random symbol 1 in 3 times, otherwise an empty string.+/// A random symbol one time in three, otherwise an empty string.fn random_symbol<R: Rng + ?Sized>(rng: &mut R) -> String {if unbiased_index(rng, 3) == 0 {SYMBOLS[unbiased_index(rng, SYMBOLS.len())].to_string()@@ -103,13 +77,9 @@ fn random_symbol<R: Rng + ?Sized>(rng: &mut R) -> String {}}-/// Keep only ASCII letters, digits, dots, underscores and hyphens; collapse-/// consecutive separator characters to one; trim leading and trailing separators.+/// Keep only ASCII letters, digits, dots, underscores and hyphens; collapse runs of separators and trim them from the ends.fn sanitize_email_prefix(input: &str) -> String {- let filtered: String = input- .chars()- .filter(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-'))- .collect();+ let filtered: String = input.chars().filter(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-')).collect();let mut collapsed = String::with_capacity(filtered.len());let mut previous_was_separator = false;@@ -122,12 +92,10 @@ fn sanitize_email_prefix(input: &str) -> String {previous_was_separator = is_separator;}- collapsed- .trim_matches(|c: char| matches!(c, '.' | '_' | '-'))- .to_string()+ collapsed.trim_matches(|c: char| matches!(c, '.' | '_' | '-')).to_string()}-/// First `n` characters of a string (character based, not byte based).+/// The first `n` characters of a string.fn first_chars(value: &str, n: usize) -> String {value.chars().take(n).collect()}diff --git a/core/rust/src/password_generator/basic.rs b/core/rust/src/password_generator/basic.rsindex 47bb6ebc9..4537b9f9f 100644--- a/core/rust/src/password_generator/basic.rs+++ b/core/rust/src/password_generator/basic.rs@@ -1,7 +1,4 @@-//! Basic character-set password generator.-//!-//! Builds a character set from the enabled options and constructs the password so that it is guaranteed to contain at least-//! one character from every enabled set (as some websites require this).+//! Character-set password generator; the result contains at least one character of every enabled class.use rand::Rng;@@ -12,25 +9,21 @@ const UPPERCASE_CHARS: &str = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";const NUMBER_CHARS: &str = "0123456789";const SPECIAL_CHARS: &str = "!@#$%^&*()_+-=[]{}|;:,.<>?";-/// Ambiguous characters that look similar and are easy to confuse when typing.+/// Characters that are easy to confuse when reading or typing.const AMBIGUOUS_CHARS: &str = "Il1O0oZzSsBbGg2568|[]{}()<>;:,.`'\"_-";-/// Generate a basic password based on the supplied settings.+/// Generate a password from the supplied settings.pub fn generate<R: Rng + ?Sized>(settings: &PasswordSettings, rng: &mut R) -> String {let chars = build_character_set(settings);let length = settings.length as usize;- // Reserve one mandatory character per enabled class so the result is guaranteed to contain at least one of each.+ // When the length cannot fit one character per enabled class, a random subset of the classes wins.let mut mandatory = mandatory_characters(settings, rng);-- // If the requested length cannot fit every mandatory character (e.g. length 2 with four enabled classes), shuffle and- // truncate so we never exceed the requested length. Which classes "win" is then random rather than always the same ones.if mandatory.len() > length {shuffle(&mut mandatory, rng);mandatory.truncate(length);}- // Fill the remaining positions from the full character set, then shuffle so the mandatory characters are not clustered at the front.let mut password = mandatory;while password.len() < length {password.push(chars[unbiased_index(rng, chars.len())]);@@ -40,7 +33,7 @@ pub fn generate<R: Rng + ?Sized>(settings: &PasswordSettings, rng: &mut R) -> Stpassword.into_iter().collect()}-/// Build the character set based on the selected options.+/// The character set of the enabled classes, lowercase when none is enabled.fn build_character_set(settings: &PasswordSettings) -> Vec<char> {let mut chars = String::new();@@ -57,7 +50,6 @@ fn build_character_set(settings: &PasswordSettings) -> Vec<char> {chars.push_str(SPECIAL_CHARS);}- // Ensure at least one character set is selected, otherwise default to lowercase.if chars.is_empty() {chars.push_str(LOWERCASE_CHARS);}@@ -71,7 +63,7 @@ fn build_character_set(settings: &PasswordSettings) -> Vec<char> {chars.chars().filter(|c| !settings.use_non_ambiguous_chars || !AMBIGUOUS_CHARS.contains(*c)).collect()}-/// Collect one mandatory character per enabled class, so the password contains at least one character from each.+/// One random character per enabled class.fn mandatory_characters<R: Rng + ?Sized>(settings: &PasswordSettings, rng: &mut R) -> Vec<char> {let mut mandatory = Vec::new();if settings.use_lowercase {@@ -89,7 +81,7 @@ fn mandatory_characters<R: Rng + ?Sized>(settings: &PasswordSettings, rng: &mutmandatory}-/// Pick one random character from the (ambiguity-filtered) class set and push it onto `out`.+/// Push one random character of `char_set` onto `out`, unless the settings exclude the whole set.fn push_one<R: Rng + ?Sized>(out: &mut Vec<char>, char_set: &str, settings: &PasswordSettings, rng: &mut R) {let safe = safe_character_set(char_set, settings);if !safe.is_empty() {@@ -97,7 +89,7 @@ fn push_one<R: Rng + ?Sized>(out: &mut Vec<char>, char_set: &str, settings: &Pas}}-/// Get a character set with the user's excluded characters removed, and the ambiguous ones if that option is enabled.+/// A character set without the excluded characters, and without the ambiguous ones when that option is on.fn safe_character_set(char_set: &str, settings: &PasswordSettings) -> Vec<char> {char_set.chars()@@ -106,7 +98,7 @@ fn safe_character_set(char_set: &str, settings: &PasswordSettings) -> Vec<char>.collect()}-/// Shuffle a slice in place with an unbiased Fisher-Yates shuffle, reusing [`unbiased_index`] so a fixed seed stays deterministic.+/// Fisher-Yates shuffle over `unbiased_index`, so a seed keeps giving the same password.fn shuffle<R: Rng + ?Sized>(items: &mut [char], rng: &mut R) {for i in (1..items.len()).rev() {let j = unbiased_index(rng, i + 1);diff --git a/core/rust/src/password_generator/diceware.rs b/core/rust/src/password_generator/diceware.rsindex 1e0d79201..866f85f94 100644--- a/core/rust/src/password_generator/diceware.rs+++ b/core/rust/src/password_generator/diceware.rs@@ -1,8 +1,5 @@-//! Diceware passphrase generator.-//!-//! Ported from the MIT-licensed `SpamOK.PasswordGenerator` Diceware algorithm. Picks `word_count` words uniformly at random-//! from the selected language wordlist, applies capitalization, joins them with a separator, and optionally adds a random-//! alphanumeric "salt" character.+//! Diceware passphrase generator: random words from a language wordlist, capitalized, joined and optionally salted.+//! Ported from the MIT-licensed SpamOK.PasswordGenerator Diceware algorithm.use rand::Rng;@@ -10,7 +7,7 @@ use super::{unbiased_index, wordlists, Capitalization, PasswordSettings, Salt, Sconst ALPHANUMERIC: &str = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";-/// Generate a Diceware passphrase based on the supplied settings.+/// Generate a passphrase from the supplied settings.pub fn generate<R: Rng + ?Sized>(settings: &PasswordSettings, rng: &mut R) -> String {let words = wordlists::list(&settings.language);@@ -29,7 +26,7 @@ pub fn generate<R: Rng + ?Sized>(settings: &PasswordSettings, rng: &mut R) -> Stadd_salt(passphrase, settings.salt, rng)}-/// Map a separator option to its character (`None` means no separator at all).+/// The character of a separator option.fn separator_char(separator: Separator) -> Option<char> {match separator {Separator::None => None,@@ -40,7 +37,7 @@ fn separator_char(separator: Separator) -> Option<char> {}}-/// Apply the configured capitalization to a single word.+/// Apply a capitalization to one word.fn capitalize_word<R: Rng + ?Sized>(word: &str, capitalization: Capitalization, rng: &mut R) -> String {match capitalization {Capitalization::None => word.to_string(),@@ -66,7 +63,7 @@ fn capitalize_word<R: Rng + ?Sized>(word: &str, capitalization: Capitalization,}}-/// Add a random alphanumeric salt character to the passphrase based on the salt option.+/// Add a random alphanumeric character where the salt option says.fn add_salt<R: Rng + ?Sized>(passphrase: String, salt: Salt, rng: &mut R) -> String {match salt {Salt::None => passphrase,@@ -82,7 +79,7 @@ fn add_salt<R: Rng + ?Sized>(passphrase: String, salt: Salt, rng: &mut R) -> Str}}-/// Pick one random alphanumeric character.+/// One random alphanumeric character.fn random_alphanumeric<R: Rng + ?Sized>(rng: &mut R) -> char {char::from(ALPHANUMERIC.as_bytes()[unbiased_index(rng, ALPHANUMERIC.len())])}diff --git a/core/rust/src/password_generator/mod.rs b/core/rust/src/password_generator/mod.rsindex 1ab1d156b..410d9ca6c 100644--- a/core/rust/src/password_generator/mod.rs+++ b/core/rust/src/password_generator/mod.rs@@ -25,10 +25,8 @@ use crate::common::rng::{make_rng, unbiased_index};#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]#[serde(rename_all = "lowercase")]pub(crate) enum GeneratorType {- /// Character-set password generator.#[default]Basic,- /// Diceware passphrase generator.Diceware,}@@ -36,16 +34,13 @@ pub(crate) enum GeneratorType {#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]#[serde(rename_all = "PascalCase")]pub enum Capitalization {- /// Leave each word as-is.None,- /// Uppercase the first letter of each word, lowercase the rest.+ /// First letter uppercase, the rest lowercase.TitleCase,- /// Uppercase every letter.Uppercase,- /// Lowercase every letter (default, matches the UI default).#[default]Lowercase,- /// Randomize the capitalization of each letter.+ /// Each letter uppercase or lowercase at random.Random,}@@ -53,85 +48,67 @@ pub enum Capitalization {#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]#[serde(rename_all = "PascalCase")]pub enum Separator {- /// No separator (words are concatenated).None,- /// A dash (default, matches the UI default).#[default]Dash,- /// A space.Space,- /// An underscore.Underscore,- /// A dot.Dot,}-/// Optional random salt character added to a Diceware passphrase.+/// Where a random alphanumeric salt character goes in a Diceware passphrase.#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]#[serde(rename_all = "PascalCase")]pub enum Salt {- /// No salt (default).#[default]None,- /// Prepend a random alphanumeric character.Prefix,- /// Insert a random alphanumeric character at a random position.+ /// At a random position.Sprinkle,- /// Append a random alphanumeric character.Suffix,}-/// Settings controlling password/passphrase generation.-///-/// Field names use PascalCase to match the JSON blob persisted by the apps under the `PasswordGenerationSettings` settings key.-/// Every field has a serde default so that older blobs (which lack the Diceware fields) deserialize cleanly.+/*+ * The JSON shape of the `PasswordGenerationSettings` settings blob the apps persist: PascalCase keys, and a serde+ * default on every field so blobs written before the Diceware fields existed still deserialize.+ */++/// Settings controlling password or passphrase generation.#[derive(Debug, Clone, Serialize, Deserialize)]#[serde(rename_all = "PascalCase")]pub(crate) struct PasswordSettings {- /// Which generator to use.#[serde(rename = "Type", default)]pub generator_type: GeneratorType,- /// Length of the generated password.#[serde(default = "default_length")]pub length: u32,- /// Whether to include lowercase letters.#[serde(default = "default_true")]pub use_lowercase: bool,- /// Whether to include uppercase letters.#[serde(default = "default_true")]pub use_uppercase: bool,- /// Whether to include numbers.#[serde(default = "default_true")]pub use_numbers: bool,- /// Whether to include special characters.#[serde(default = "default_true")]pub use_special_chars: bool,- /// Whether to exclude ambiguous characters.#[serde(default)]pub use_non_ambiguous_chars: bool,- /// Characters that must never appear in the password (user supplied).+ /// Characters that must never appear in the password.#[serde(default)]pub excluded_chars: String,- /// Number of words in the passphrase.#[serde(default = "default_word_count")]pub word_count: u32,- /// Wordlist language code (free text, case-insensitive). Unknown codes fall back to English, so the TypeScript model and- /// apps never need updating to add a language.+ /// Wordlist language code, case-insensitive; unknown codes fall back to English.#[serde(default = "default_language")]pub language: String,- /// Capitalization applied to each word.#[serde(default)]pub capitalization: Capitalization,- /// Separator between words.#[serde(default)]pub separator: Separator,- /// Optional random salt character.#[serde(default)]pub salt: Salt,- /// Optional 32-byte RNG seed as 64 hex characters; the same seed gives the same output, absent means a fresh OS random seed.+ /// Optional 32-byte RNG seed as 64 hex characters; the same seed gives the same output.#[serde(default)]pub seed: Option<String>,}@@ -144,11 +121,6 @@ fn default_word_count() -> u32 {defaults::DEFAULT_WORD_COUNT}-/// Minimum password length.-const HARD_MIN_PASSWORD_LENGTH: u32 = 1;-/// Minimum passphrase word count.-const HARD_MIN_WORD_COUNT: u32 = 1;-fn default_true() -> bool {true}@@ -157,24 +129,25 @@ fn default_language() -> String {"en".to_string()}-/// List the language codes of all bundled Diceware wordlists (first is the default, English).+// The floors the generator clamps to; the UI sliders start higher (`defaults::MIN_*`).+const HARD_MIN_PASSWORD_LENGTH: u32 = 1;+const HARD_MIN_WORD_COUNT: u32 = 1;++/// The language codes of the bundled Diceware wordlists, English first.pub fn available_languages() -> Vec<String> {wordlists::available_codes().into_iter().map(|c| c.to_string()).collect()}/// Generate a password or passphrase from a JSON-serialized [`PasswordSettings`].-///-/// Returns the generated string, or a [`VaultError`] if the settings JSON is invalid.pub fn generate_password(settings_json: &str) -> Result<String, VaultError> {let settings: PasswordSettings = serde_json::from_str(settings_json)?;Ok(generate_from_settings(&settings))}-/// Generate a password or passphrase from already-parsed settings.+/// Generate a password or passphrase from parsed settings.fn generate_from_settings(settings: &PasswordSettings) -> String {let mut rng = make_rng(settings.seed.as_deref());- // Clamp length and word count.let mut settings = settings.clone();settings.length = settings.length.clamp(HARD_MIN_PASSWORD_LENGTH, defaults::MAX_PASSWORD_LENGTH);settings.word_count = settings.word_count.clamp(HARD_MIN_WORD_COUNT, defaults::MAX_WORD_COUNT);@@ -184,4 +157,3 @@ fn generate_from_settings(settings: &PasswordSettings) -> String {GeneratorType::Diceware => diceware::generate(&settings, &mut rng),}}-diff --git a/core/rust/src/password_generator/wordlists/mod.rs b/core/rust/src/password_generator/wordlists/mod.rsindex 55ed72e72..295cca014 100644--- a/core/rust/src/password_generator/wordlists/mod.rs+++ b/core/rust/src/password_generator/wordlists/mod.rs@@ -1,16 +1,6 @@-//! Embedded Diceware wordlists.-//!-//! Each list contains exactly 7776 words (6^5), one word per line, in dice order.-//! The lists are embedded into the binary via `include_str!`.-//!-//! Languages are keyed by a free-text code (case-insensitive). Adding a new language is a-//! Rust-only change: drop the `<code>.diceware` file in this directory and add one entry to-//! the `WORDLISTS` registry below; no changes are needed in the TypeScript model or the-//! apps. Unknown codes fall back to English.+//! The embedded Diceware wordlists: 7776 words each, one per line in dice order, keyed by language code.-/// The registry of bundled wordlists, as `(code, raw text)`. The code is the normalized two-letter-/// ISO 639-1 language code; the first entry is the default/fallback (English). To add a language,-/// add one line here plus the matching `.diceware` file.+/// The bundled wordlists as `(ISO 639-1 code, raw text)`; the first entry is the fallback (English).static WORDLISTS: &[(&str, &str)] = &[("en", include_str!("en.diceware")),("nl", include_str!("nl.diceware")),@@ -21,30 +11,13 @@ static WORDLISTS: &[(&str, &str)] = &[("ro", include_str!("ro.diceware")),];-/// Resolve a language code (case-insensitive) to its raw wordlist text, falling back to-/// English (the first registry entry) for any unknown or empty code.-fn resolve_raw(code: &str) -> &'static str {- WORDLISTS- .iter()- .find(|(c, _)| c.eq_ignore_ascii_case(code))- .map(|(_, raw)| *raw)- .unwrap_or(WORDLISTS[0].1)-}--/// Get the wordlist for the given language code as a vector of words.-///-/// Unknown codes fall back to the English list. Parsing is cheap (~7776 line splits) and-/// happens once per generation call.+/// The words of a language (case-insensitive code); an unknown or empty code gives the English list.pub fn list(code: &str) -> Vec<&'static str> {- resolve_raw(code)- .lines()- .map(|line| line.trim_end_matches('\r'))- .filter(|line| !line.is_empty())- .collect()+ let raw = WORDLISTS.iter().find(|(c, _)| c.eq_ignore_ascii_case(code)).map(|(_, raw)| *raw).unwrap_or(WORDLISTS[0].1);+ raw.lines().map(|line| line.trim_end_matches('\r')).filter(|line| !line.is_empty()).collect()}-/// List the codes of all bundled languages (first is the default, English).-/// Used to build a language picker in the UI without hard-coding the set there.+/// The codes of the bundled languages, the default (English) first.pub fn available_codes() -> Vec<&'static str> {WORDLISTS.iter().map(|(code, _)| *code).collect()}diff --git a/core/rust/src/sqlite_host/mod.rs b/core/rust/src/sqlite_host/mod.rsindex 9ddf5cbbb..33c7e8142 100644--- a/core/rust/src/sqlite_host/mod.rs+++ b/core/rust/src/sqlite_host/mod.rs@@ -1,7 +1,4 @@-//! An in-memory SQLite database that host applications use for uniform access to the database.-//!-//! The database lives in SQLite's own memory and is never persisted to the filesystem; temporary tables and the-//! scratch copy a VACUUM builds stay in memory too (`temp_store = MEMORY`), so no plaintext page spills to disk.+//! An in-memory SQLite database that host applications use for uniform access to the vault database.use std::sync::Mutex;@@ -20,10 +17,10 @@ const VACUUM_MIN_FREE_PAGES: i64 = 64;/// A VACUUM runs when the freelist holds at least this fraction (1/n) of the database's pages.const VACUUM_FREE_PAGE_RATIO: i64 = 10;-/// The complete client vault schema, generated from `core/vault/src/sql/SqlConstants.ts` by `core/vault/build.sh`.+/// The complete client vault schema, generated into `vault_schema.sql`.pub const VAULT_SCHEMA_SQL: &str = include_str!("vault_schema.sql");-/// One parameterized SQL statement, as the bindings and the sync engine hand it to a host.+/// One parameterized SQL statement.#[derive(Debug, Clone, Serialize, Deserialize)]pub struct SqlStatement {pub sql: String,@@ -31,7 +28,7 @@ pub struct SqlStatement {pub params: Vec<Value>,}-/// A SQLite value as the bindings see it, typed and without JSON encoding.+/// A typed SQLite value.#[derive(Debug, Clone, PartialEq)]#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]pub enum SqlValue {@@ -114,7 +111,7 @@ impl MemoryDatabase {Ok(SqlResult { columns, rows: out })}- /// Run one DML statement with typed parameters and return the rows it changed (stale for a SELECT, which changes nothing).+ /// Run one DML statement with typed parameters and return the number of rows it changed.pub fn execute(&self, sql: &str, params: &[SqlValue]) -> VaultResult<u64> {let conn = self.lock();let mut statement = conn.prepare_cached(sql).map_err(sql_error_at(sql))?;@@ -147,7 +144,7 @@ fn open_connection() -> VaultResult<Connection> {Ok(conn)}-/// Rebuild the database to reclaim free pages if there are enough free pages to make it worth it.+/// VACUUM when the freelist is large enough to be worth a full rewrite; a no-op inside an open transaction.fn vacuum_if_fragmented(conn: &Connection) -> VaultResult<()> {if !conn.is_autocommit() {return Ok(());@@ -168,6 +165,7 @@ pub fn deserialize_into(conn: &mut Connection, bytes: &[u8]) -> VaultResult<()>conn.deserialize_read_exact(MAIN_DB, bytes, bytes.len(), false).map_err(sql_error)}+/// A rusqlite error as a `VaultError`.pub(crate) fn sql_error(error: rusqlite::Error) -> VaultError {VaultError::General(error.to_string())}@@ -246,18 +244,13 @@ pub fn query(conn: &Connection, sql: &str, params: &[Value]) -> VaultResult<Vec</// Run statements on a connection atomically.pub fn exec(conn: &Connection, statements: &[SqlStatement]) -> VaultResult<()> {conn.execute_batch("SAVEPOINT exec_batch").map_err(sql_error)?;- for statement in statements {- let values = match statement.params.iter().map(to_sql).collect::<VaultResult<Vec<RsValue>>>() {- Ok(values) => values,- Err(error) => {- let _ = conn.execute_batch("ROLLBACK TO exec_batch; RELEASE exec_batch");- return Err(error);- }- };- if let Err(error) = conn.execute(&statement.sql, params_from_iter(values.iter())) {- let _ = conn.execute_batch("ROLLBACK TO exec_batch; RELEASE exec_batch");- return Err(sql_error_at(&statement.sql)(error));- }+ let result = statements.iter().try_for_each(|statement| {+ let values = statement.params.iter().map(to_sql).collect::<VaultResult<Vec<RsValue>>>()?;+ conn.execute(&statement.sql, params_from_iter(values.iter())).map(drop).map_err(sql_error_at(&statement.sql))+ });+ if let Err(error) = result {+ let _ = conn.execute_batch("ROLLBACK TO exec_batch; RELEASE exec_batch");+ return Err(error);}conn.execute_batch("RELEASE exec_batch").map_err(sql_error)}diff --git a/core/rust/src/vault_codec/canonicalize.rs b/core/rust/src/vault_codec/canonicalize.rsindex 1aa66ce9d..b239aa02d 100644--- a/core/rust/src/vault_codec/canonicalize.rs+++ b/core/rust/src/vault_codec/canonicalize.rs@@ -1,14 +1,5 @@-//! Canonicalize a SQLite source dataset into the manifest-v1 persisted representation: normalized tables plus a-//! salt per manifest > one manifest per declared manifest, data buckets and content-addressed blob maps.-//!-//! 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:-//! - skip-tables are dropped and the codec overflow row is folded back into the rows it came from;-//! - every row routes to the manifest its `ManifestId` names (see [`sharing`](super::sharing));-//! - each bucketed table is split out into a data bucket per manifest;-//! - the blob columns (`Logos.FileData`, `Attachments.Blob`) have their bytes extracted into a content-addressed-//! blob map (hash = `HMAC-SHA256(salt, bytes)`) and the cell replaced with `{ "__blobRef": hash, "__blobKind": kind }`;-//! - every other column (including non-blob `{ "__b64" }` inline bytes) is copied as-is.+//! Canonicalize the local SQLite tables into the manifest-v1 representation: one manifest per declared manifest, data+//! buckets, and a content-addressed blob map per manifest.use std::collections::HashMap;@@ -27,8 +18,8 @@ use crate::vault_model::{ids_equal, MANIFEST_ID_COL, OVERFLOW_TABLE};type Tables = HashMap<String, Vec<CodecRecord>>;-/// Canonicalize normalized tables into the split resources: one manifest per spec (in spec order), one data-/// bucket per declared category per manifest, and the content-addressed blob map of each manifest.+/// Canonicalize normalized tables into one manifest per spec (in spec order), one data bucket per declared category+/// per manifest, and the content-addressed blob map of each manifest.pub fn canonicalize_from_sqlite(input: CanonicalizeInput) -> VaultResult<CanonicalizedVault> {if input.manifests.is_empty() {return Err(VaultError::General("canonicalize input declares no manifests".to_string()));@@ -37,9 +28,8 @@ pub fn canonicalize_from_sqlite(input: CanonicalizeInput) -> VaultResult<Canonicreturn Err(VaultError::General("canonicalize requires a manifest id on every manifest".to_string()));}- // Collect every non-skip table into a name > rows map (row order preserved per table). The OVERFLOW_TABLE row- // carries a newer writer's tables/columns this client's schema could not hold (written by the last materialize);- // it is consumed here, folded back below, and never emitted into a manifest itself.+ // The overflow row carries a newer writer's tables and columns this schema could not hold; it is folded back into+ // the rows below and never emitted into a manifest itself.let mut all_tables = Tables::new();let mut overflow = CodecOverflow::default();for table in &input.tables {@@ -57,7 +47,8 @@ pub fn canonicalize_from_sqlite(input: CanonicalizeInput) -> VaultResult<Canonicnormalize_id_spelling(bucket_tables);}- // LEGACY: stamp unstamped rows with the manifest named by the sqlite-blob migration. Remove with that migration.+ // LEGACY: the sqlite-blob migration hands over rows without a manifest stamp and names the manifest they belong to.+ // TODO: remove once every account has migrated to manifest-v1.if let Some(stamp_into) = input.stamp_unstamped_into.as_deref() {stamp_unstamped_rows(&mut all_tables, stamp_into);}@@ -105,8 +96,7 @@ fn bucket_with_extra(manifest_id: String, category: &str, tables: Tables, overflDataBucket { extra, ..DataBucket::new(manifest_id, category, tables) }}-/// Every bucket category to emit: the declared ones plus any a newer writer put in the overflow (a category this-/// client's schema does not know yet still has to be carried forward). Sorted, so output stays stable.+/// Every bucket category to emit: the declared ones, then any a newer writer put in the overflow, sorted.fn categories_present(overflow: &CodecOverflow) -> Vec<String> {let mut categories: Vec<String> = bucket_categories().into_iter().map(str::to_string).collect();let mut extra: Vec<String> = overflow.bucket_tables.keys().filter(|category| !categories.contains(category)).cloned().collect();@@ -115,23 +105,21 @@ fn categories_present(overflow: &CodecOverflow) -> Vec<String> {categories}-/// The tables read for one bucket category: the ones the local schema holds, plus whole tables a newer writer put-/// in that bucket which this client's schema cannot hold (carried in the overflow). Local rows win.+/// The tables of one bucket category: the local ones plus the whole tables the overflow carries for it; local rows win.fn category_tables(category: &str, bucketed_rows: &Tables, overflow: &CodecOverflow) -> Tables {let mut tables: Tables = bucketed_rows.iter().filter(|(name, _)| bucket_category_for(name) == Some(category)).map(|(name, rows)| (name.clone(), rows.clone())).collect();fold_overflow_tables(&mut tables, overflow.bucket_tables.get(category));tables}-/// Split one bucket category's tables into the table set each manifest owns: the single grouping rule behind both-/// the full push ([`build_data_buckets`]) and the bucket-only push ([`extract_buckets`]).+/// Split one bucket category's tables into the table set each manifest owns.fn group_category_rows(tables: Tables, manifest_ids: &[String]) -> HashMap<String, Tables> {let empty: Tables = tables.keys().map(|name| (name.clone(), Vec::new())).collect();let mut grouped: HashMap<String, Tables> = manifest_ids.iter().map(|id| (id.clone(), empty.clone())).collect();for (name, rows) in tables {for mut row in rows {let Some(owner) = owning_manifest(&row, manifest_ids) else { continue };- // Normalize the stamp to the spelling the bucket declares the id with.+ // The stamp takes the spelling the bucket declares the id with.row.insert(MANIFEST_ID_COL.to_string(), json!(owner));grouped.entry(owner).or_default().entry(name.clone()).or_default().push(row);}@@ -139,8 +127,8 @@ fn group_category_rows(tables: Tables, manifest_ids: &[String]) -> HashMap<Stringrouped}-/// The manifest a bucketed row belongs to, spelled the way `manifest_ids` spells it, or `None` when the row names-/// no manifest or one this vault does not carry.+/// The manifest a bucketed row belongs to, spelled as `manifest_ids` spells it, or `None` when the row names no+/// manifest or one this vault does not carry.fn owning_manifest(row: &CodecRecord, manifest_ids: &[String]) -> Option<String> {let stamp = str_col(row, MANIFEST_ID_COL)?;if is_unstamped_manifest_id(Some(stamp)) {@@ -149,8 +137,8 @@ fn owning_manifest(row: &CodecRecord, manifest_ids: &[String]) -> Option<String>manifest_ids.iter().find(|id| ids_equal(id, stamp)).cloned()}-/// LEGACY: stamp every unstamped row of a manifest-scoped table with `manifest_id`. Only the sqlite-blob migration-/// stamps rows; remove once every account has migrated to manifest-v1.+/// LEGACY: stamp every unstamped row of a manifest-scoped table with `manifest_id`, for the sqlite-blob migration.+/// TODO: remove once every account has migrated to manifest-v1.fn stamp_unstamped_rows(tables: &mut Tables, manifest_id: &str) {for name in manifest_scoped_tables() {let Some(rows) = tables.get_mut(name) else { continue };@@ -175,7 +163,7 @@ fn reject_unstamped_rows(tables: &Tables) -> VaultResult<()> {Ok(())}-/// True when a row carries no usable `ManifestId`: absent, JSON null, a non-string, or the empty string.+/// True when a row carries no usable `ManifestId`.fn is_unstamped(row: &CodecRecord) -> bool {is_unstamped_manifest_id(str_col(row, MANIFEST_ID_COL))}@@ -199,8 +187,8 @@ fn extract_table_blobs(table: &str, records: Vec<CodecRecord>, manifest_salt: &sOk(out_rows)}-/// Extract a blob column cell: non-empty `{ "__b64" }` bytes are hashed and registered and the cell becomes a-/// blob reference; anything else becomes JSON null.+/// Extract a blob cell: non-empty inline bytes are registered in `blobs` and replaced by a blob reference; anything+/// else becomes JSON null.fn extract_blob_cell(cell: Option<&Value>, manifest_salt: &str, kind: &str, blobs: &mut HashMap<String, BlobEntry>) -> VaultResult<Value> {let Some(b64) = cell.and_then(inline_b64) else { return Ok(Value::Null) };let bytes = match crate::common::encoding::base64_decode(b64) {@@ -246,10 +234,9 @@ fn primary_key_of<'a>(table_name: &str, identity: &'a str) -> &'a str {identity.rmatch_indices('\u{1f}').nth(parts - 1).map_or(identity, |(at, _)| &identity[at + 1..])}-/// Build `category`'s data buckets, one per manifest in `manifest_ids`, from the category's tables as the platform-/// reads them out of its local vault (name > rows): the bucket-only push path. Rows route by the manifest each one-/// names, exactly as the full push routes them. Include the [`OVERFLOW_TABLE`] row in `tables` so a newer writer's-/// columns and tables re-merge and survive; it is consumed and never emitted into a bucket.+/// Build `category`'s data buckets, one per manifest in `manifest_ids`, from the category's tables as read out of the+/// local vault: the bucket-only push path. `tables` should include the `OVERFLOW_TABLE` row so a newer writer's columns+/// and tables survive; it is consumed and never emitted into a bucket.pub fn extract_buckets(category: String, manifest_ids: Vec<String>, mut tables: Tables) -> VaultResult<Vec<DataBucket>> {if manifest_ids.is_empty() {return Err(VaultError::General("extract_buckets declares no manifests; a bucket write needs the manifests it may be addressed to".to_string()));diff --git a/core/rust/src/vault_codec/hash.rs b/core/rust/src/vault_codec/hash.rsindex fb41a8c4d..437ab9ad2 100644--- a/core/rust/src/vault_codec/hash.rs+++ b/core/rust/src/vault_codec/hash.rs@@ -1,9 +1,4 @@//! Hashing and canonical JSON for the vault_codec format.-//!-//! Each encrypted payload embeds an integrity envelope `{ schemaVersion, contentHash, payload }` where-//! `contentHash = sha256(canonical(payload))`. [`canonical_json`] is the canonical form: object keys sorted-//! ascending, recursively; arrays kept in order; primitives as serde_json renders them. Every client hashes through-//! this crate, so the form only has to stay stable against itself, and stored vaults depend on it staying so.use hmac::{Hmac, Mac};use sha2::{Digest, Sha256};@@ -24,8 +19,8 @@ pub fn sha256_hex(bytes: &[u8]) -> String {hex_encode_lower(&Sha256::digest(bytes))}-/// Canonicalize a JSON value into a stable string for hashing: object keys sorted recursively, arrays-/// kept in order, primitives as `serde_json::to_string` renders them.+/// The canonical JSON a content hash covers: object keys sorted recursively, arrays in order, primitives as+/// `serde_json::to_string` renders them. Every stored vault depends on this form staying stable.pub fn canonical_json(value: &serde_json::Value) -> String {match value {serde_json::Value::Object(map) => {@@ -36,7 +31,6 @@ pub fn canonical_json(value: &serde_json::Value) -> String {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]));@@ -55,18 +49,17 @@ pub fn canonical_json(value: &serde_json::Value) -> String {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.+/// Content hash `sha256(canonical(payload))`, lowercase hex.pub fn content_hash(value: &serde_json::Value) -> String {sha256_hex(canonical_json(value).as_bytes())}-/// Per-manifest blob address `HMAC-SHA256(key = salt_bytes, plaintext_bytes)`, lowercase hex.-/// A missing or malformed salt is an error, since hashing without it would break the per-manifest separation.+/// Per-manifest blob address `HMAC-SHA256(key = salt_bytes, plaintext_bytes)`, lowercase hex. A missing or malformed+/// salt is an error, since hashing without it would break the per-manifest separation.pub fn salted_blob_hash(bytes: &[u8], manifest_salt: &str) -> VaultResult<String> {let salt_bytes = hex_decode(manifest_salt).filter(|salt| !salt.is_empty()).ok_or_else(|| VaultError::General("manifest salt is missing or not valid hex".to_string()))?;let mut mac = Hmac::<Sha256>::new_from_slice(&salt_bytes).expect("HMAC takes a key of any length");diff --git a/core/rust/src/vault_codec/integrity.rs b/core/rust/src/vault_codec/integrity.rsindex e1434776c..9aa6473c1 100644--- a/core/rust/src/vault_codec/integrity.rs+++ b/core/rust/src/vault_codec/integrity.rs@@ -1,9 +1,6 @@-//! Referential integrity of one manifest's table set: the references a row may carry and what to do when one-//! dangles. Every foreign key is composite, `(ManifestId, Id)`, so a reference that resolves only in another-//! manifest is as dangling as one that resolves nowhere.-//!-//! The same rule table serves both directions: `repair` is what canonicalize and combine apply, `violations` is-//! what validation reports. Validation therefore cannot refuse anything a repair leaves behind.+//! Referential integrity of one manifest's table set: the references a row may carry and what happens when one+//! is unresolved. Every foreign key is composite `(ManifestId, Id)`, so a reference into another manifest is+//! unresolved too.use std::collections::{HashMap, HashSet};@@ -17,12 +14,12 @@ use crate::vault_model::{id_key, MANIFEST_ID_COL, SYNCABLE_TABLES};type Tables = HashMap<String, Vec<CodecRecord>>;-/// What becomes of a row whose reference dangles.+/// What becomes of a row whose reference is unresolved.#[derive(Debug, Clone, Copy, PartialEq, Eq)]-enum OnDangling {- /// The column is nullable and the row still means something without it (an item outside any folder).+enum OnUnresolved {+ /// The column is nullable and the row still means something without it.Null,- /// The reference is the row's reason to exist (a child row of an item, a tag link).+ /// The reference is the row's reason to exist.DropRow,}@@ -31,7 +28,7 @@ struct Reference {table: String,column: &'static str,target: &'static str,- on_dangling: OnDangling,+ on_unresolved: OnUnresolved,}impl Reference {@@ -41,57 +38,58 @@ impl Reference {}}-/// Every reference rule, parents before children so a repair never dangles what a later rule relies on.+/// Every reference rule, parents before children so a repair never leaves a reference unresolved for a rule that+/// already ran. Both `repair` and `violations` read this one table, so validation never refuses what a repair leaves+/// behind.fn rules() -> Vec<Reference> {let mut rules = vec![- Reference { table: FOLDERS_TABLE.to_string(), column: PARENT_FOLDER_ID_COL, target: FOLDERS_TABLE, on_dangling: OnDangling::Null },- Reference { table: ITEMS_TABLE.to_string(), column: FOLDER_ID_COL, target: FOLDERS_TABLE, on_dangling: OnDangling::Null },+ Reference { table: FOLDERS_TABLE.to_string(), column: PARENT_FOLDER_ID_COL, target: FOLDERS_TABLE, on_unresolved: OnUnresolved::Null },+ Reference { table: ITEMS_TABLE.to_string(), column: FOLDER_ID_COL, target: FOLDERS_TABLE, on_unresolved: OnUnresolved::Null },];- // Every registered table whose rows hang off an item through `ItemId`; the stats bucket keys on the item id itself and syncs apart.+ // The stats bucket keys on the item id itself and syncs apart, so it is not repaired here.for child in SYNCABLE_TABLES.iter().filter(|t| t.item_child && !is_bucketed_table(t.name) && t.item_ref_column() == ITEM_ID_COL) {- rules.push(Reference { table: child.name.to_string(), column: ITEM_ID_COL, target: ITEMS_TABLE, on_dangling: OnDangling::DropRow });+ rules.push(Reference { table: child.name.to_string(), column: ITEM_ID_COL, target: ITEMS_TABLE, on_unresolved: OnUnresolved::DropRow });}- rules.push(Reference { table: ITEM_TAGS_TABLE.to_string(), column: TAG_ID_COL, target: TAGS_TABLE, on_dangling: OnDangling::DropRow });+ rules.push(Reference { table: ITEM_TAGS_TABLE.to_string(), column: TAG_ID_COL, target: TAGS_TABLE, on_unresolved: OnUnresolved::DropRow });// A value with no definition is how a system field is stored, so nulling keeps what the user typed.- rules.push(Reference { table: FIELD_VALUES_TABLE.to_string(), column: FIELD_DEFINITION_ID_COL, target: FIELD_DEFINITIONS_TABLE, on_dangling: OnDangling::Null });- rules.push(Reference { table: FIELD_HISTORIES_TABLE.to_string(), column: FIELD_DEFINITION_ID_COL, target: FIELD_DEFINITIONS_TABLE, on_dangling: OnDangling::Null });+ rules.push(Reference { table: FIELD_VALUES_TABLE.to_string(), column: FIELD_DEFINITION_ID_COL, target: FIELD_DEFINITIONS_TABLE, on_unresolved: OnUnresolved::Null });+ rules.push(Reference { table: FIELD_HISTORIES_TABLE.to_string(), column: FIELD_DEFINITION_ID_COL, target: FIELD_DEFINITIONS_TABLE, on_unresolved: OnUnresolved::Null });rules}-/// Repair every dangling reference in a manifest's table set, and drop the rows of tombstoned items: an item is-/// deleted as a unit, so children a merge or an older client left under a tombstone leave with it. A rule whose+/// Repair every unresolved reference in a manifest's table set and drop the rows of tombstoned items. A rule whose/// target table is absent from the set is skipped: that is a partial table set, not a vault without that table.pub(crate) fn repair(tables: &mut Tables) {for rule in rules() {let Some(targets) = qualified_ids(tables, rule.target) else { continue };let Some(rows) = tables.get_mut(&rule.table) else { continue };- match rule.on_dangling {- OnDangling::Null => {- for row in rows.iter_mut().filter(|row| dangles(row, rule.column, &targets)) {+ match rule.on_unresolved {+ OnUnresolved::Null => {+ for row in rows.iter_mut().filter(|row| is_unresolved(row, rule.column, &targets)) {row.insert(rule.column.to_string(), Value::Null);}}- OnDangling::DropRow => rows.retain(|row| !dangles(row, rule.column, &targets)),+ OnUnresolved::DropRow => rows.retain(|row| !is_unresolved(row, rule.column, &targets)),}}drop_children_of_tombstoned_items(tables);}-/// Every dangling reference in a manifest's table set, as `(rule id, description)`, at most one per rule.+/// Every unresolved reference in a manifest's table set, as `(rule id, description)`, at most one per rule.pub(crate) fn violations(tables: &Tables) -> Vec<(String, String)> {let mut out = Vec::new();for rule in rules() {let Some(targets) = qualified_ids(tables, rule.target) else { continue };let Some(rows) = tables.get(&rule.table) else { continue };- if let Some(row) = rows.iter().find(|row| dangles(row, rule.column, &targets)) {+ if let Some(row) = rows.iter().find(|row| is_unresolved(row, rule.column, &targets)) {out.push((rule.id(), format!("{} {} references missing {} {}", rule.table, str_col(row, ID_COL).unwrap_or(""), rule.target, str_col(row, rule.column).unwrap_or(""))));}}out}-/// Whether `row.column` names something that is not in `targets` (an absent or null column dangles nothing).-fn dangles(row: &CodecRecord, column: &str, targets: &HashSet<(String, String)>) -> bool {+/// Whether `row.column` names something not in `targets`; an absent or null column is never unresolved.+fn is_unresolved(row: &CodecRecord, column: &str, targets: &HashSet<(String, String)>) -> bool {match str_col(row, column) {None => false,Some(reference) => !targets.contains(&qualified(row, reference)),@@ -108,7 +106,7 @@ fn qualified(row: &CodecRecord, id: &str) -> (String, String) {(id_key(str_col(row, MANIFEST_ID_COL).unwrap_or_default()), id_key(id))}-/// Remove every row hanging off a tombstoned item.+/// Remove every child row of a tombstoned item.fn drop_children_of_tombstoned_items(tables: &mut Tables) {let deleted: HashSet<(String, String)> = tables.get(ITEMS_TABLE)diff --git a/core/rust/src/vault_codec/logos.rs b/core/rust/src/vault_codec/logos.rsindex 255b22866..92c04b0ce 100644--- a/core/rust/src/vault_codec/logos.rs+++ b/core/rust/src/vault_codec/logos.rs@@ -1,16 +1,5 @@-//! Logo identity: one `Logos` row per `(ManifestId, Kind, Source)` per *manifest*.-//!-//! One row shape covers every logo an item can have, and `Items.LogoId` is the single pointer to it:-//! - `Kind = "favicon"`, `Source` = the domain the logo was fetched from (`github.com`);-//! - `Kind = "builtin"`, `Source` = a key into the shared built-in catalog (`shopping`), no image bytes:-//! every platform draws that logo itself;-//! - `Kind = "custom"`, `Source` = the sha256 of the image the user uploaded.-//!-//! A logo belongs to the manifest that owns it: `ManifestId` is that manifest's id, and `Id` derives from-//! `(manifest id, Kind, Source)` (see [`logo_id_for`]), so every writer derives the same id for the same logo in-//! the same manifest and the uniqueness invariant is self-enforcing rather than repaired after the fact. A logo-//! is never shared across manifests: an item that moves into another manifest gets a copy under that manifest's-//! id, and a favicon nothing references any more is dropped, since the client can fetch it again.+//! Logo identity: one `Logos` row per `(ManifestId, Kind, Source)`, its `Id` derived from that key so every writer+//! derives the same id, and no logo shared across manifests: an item moving into another manifest gets a copy there.use std::collections::{HashMap, HashSet};@@ -24,19 +13,17 @@ use crate::vault_model::{id_key, ids_equal, MANIFEST_ID_COL};type Tables = HashMap<String, Vec<CodecRecord>>;-/// Domain-separation prefix for favicon ids. It predates the `Kind` column and is kept as-is so every favicon row-/// that already exists keeps its id: changing it would re-derive the logo id of every item in every vault.+/// Domain-separation prefix for favicon ids; it predates the `Kind` column, and changing it would re-derive the logo+/// id of every item in every vault.const FAVICON_ID_NAMESPACE: &str = "aliasvault:logo:v1";-/// The `Id` of the logo `(manifest id, kind, source)`: a UUIDv8 whose bytes come from-/// `sha256(namespace | manifest id | source)`, with a namespace per kind so the three key spaces (a domain, a-/// catalog key, a content hash) can never collide. `source` is matched case-insensitively.+/// The `Id` of the logo `(manifest id, kind, source)`: a UUIDv8 of `sha256(namespace | manifest id | source)`, with+/// `source` matched case-insensitively.pub fn logo_id_for(manifest_id: &str, kind: &str, source: &str) -> String {super::hash::derived_uuid(&format!("{}\n{}\n{}", namespace_for_kind(kind), id_key(manifest_id), source.to_lowercase()))}-/// The derivation namespace for a kind. An unknown kind gets one derived from its own name, so a newer client-/// can add a kind without this one having to know about it.+/// The derivation namespace of a kind; an unknown kind derives one from its own name.fn namespace_for_kind(kind: &str) -> String {match normalize_logo_kind(kind) {k if k == LOGO_KIND_FAVICON => FAVICON_ID_NAMESPACE.to_string(),@@ -44,7 +31,7 @@ fn namespace_for_kind(kind: &str) -> String {}}-/// True when a row holds an image the user supplied themselves, which the client cannot produce again.+/// True when a row holds an image the user uploaded, which the client cannot produce again.fn is_custom_logo(row: &CodecRecord) -> bool {logo_kind(row) == LOGO_KIND_CUSTOM}@@ -55,9 +42,8 @@ fn natural_key(row: &CodecRecord) -> Option<(String, String)> {Some((logo_kind(row), source))}-/// Bring one manifest's logos into that manifest: clone in the logos its items reference from elsewhere, derive every-/// row's id from `(manifest id, Kind, Source)` and collapse rows that then share one, repoint `Items.LogoId`, and drop-/// the favicons nothing references. `all_logos` is the vault-wide snapshot the clones come from.+/// Bring one manifest's logos into that manifest: clone the logos its items reference from elsewhere, derive every+/// row's id, repoint `Items.LogoId` and drop the favicons nothing references. `all_logos` is the vault-wide snapshot.pub(super) fn localize_logos(tables: &mut Tables, manifest_id: &str, all_logos: &[CodecRecord]) {reconcile_logo_references(tables, manifest_id, all_logos);let remap = rewrite_logo_rows(tables, manifest_id);@@ -65,8 +51,7 @@ pub(super) fn localize_logos(tables: &mut Tables, manifest_id: &str, all_logos:prune_unreferenced_logos(tables);}-/// Stamp and re-derive one manifest's logos without cloning or pruning: the combine direction, where a manifest-/// written before logos were per manifest (random ids, no stamps) has to land in its own uniqueness bucket.+/// Stamp and re-derive one manifest's logos without cloning or pruning: the combine direction.pub(super) fn restamp_logos(tables: &mut Tables, manifest_id: &str) {let remap = rewrite_logo_rows(tables, manifest_id);repoint_items(tables, &remap);@@ -81,7 +66,7 @@ fn rewrite_logo_rows(tables: &mut Tables, manifest_id: &str) -> HashMap<String,_ => return remap,};- // (kind, source) -> index of the row that survives (deterministic, see `is_better_logo`).+ // (kind, source) -> index of the row whose content survives.let mut survivor_idx: HashMap<(String, String), usize> = HashMap::new();for (idx, row) in logos.iter().enumerate() {let Some(key) = natural_key(row) else { continue };@@ -93,7 +78,6 @@ fn rewrite_logo_rows(tables: &mut Tables, manifest_id: &str) -> HashMap<String,}}- // Every row with a natural key maps onto that key's survivor id, and the survivor itself is rewritten in place.let survivors: HashSet<usize> = survivor_idx.values().copied().collect();for (idx, row) in logos.iter().enumerate() {let (Some((kind, source)), Some(old_id)) = (natural_key(row), str_col(row, ID_COL)) else { continue };@@ -123,8 +107,7 @@ fn rewrite_logo_rows(tables: &mut Tables, manifest_id: &str) -> HashMap<String,remap}-/// Repair every `Items.LogoId` in this table set: follow `remap`, then null a reference that resolves to no logo-/// present here (dangling, like the FK's `ON DELETE SET NULL`).+/// Follow `remap` for every `Items.LogoId` and null a reference that resolves to no logo present here.fn repoint_items(tables: &mut Tables, remap: &HashMap<String, String>) {let valid_ids = logo_ids(tables);let Some(items) = tables.get_mut(ITEMS_TABLE) else { return };@@ -155,7 +138,6 @@ fn reconcile_logo_references(tables: &mut Tables, manifest_id: &str, all_logos:let mut clones: Vec<CodecRecord> = Vec::new();let manifest_id_value = json!(manifest_id);for missing_id in missing {- // The referenced row as it exists in its original manifest, if it exists at all.let Some(origin) = all_logos.iter().find(|row| str_col(row, ID_COL).is_some_and(|id| ids_equal(id, &missing_id))) else { continue };let Some((kind, source)) = natural_key(origin) else { continue };@@ -191,8 +173,8 @@ fn refill_empty_logo_row(tables: &mut Tables, existing_id: &str, origin: &CodecRreturn;}- // Take the origin's content, keep this manifest's identity, and never move the row's clock backwards: the healed- // row has to win last-writer-wins against the empty one still sitting on other devices.+ // Keep this manifest's identity and never move the row's clock backwards: the healed row has to win+ // last-writer-wins against the empty one still sitting on other devices.let (previous, previous_at) = (existing.get(UPDATED_AT_COL).cloned(), updated_at(existing));for (column, value) in origin.iter() {if column == ID_COL || column == MANIFEST_ID_COL {@@ -205,8 +187,8 @@ fn refill_empty_logo_row(tables: &mut Tables, existing_id: &str, origin: &CodecR}}-/// Drop the logos no item in this table set references, except the ones the user uploaded: a favicon or built-in-/// logo can be produced again, an uploaded image cannot.+/// Drop the logos no item in this table set references, except the ones the user uploaded, which cannot be produced+/// again.fn prune_unreferenced_logos(tables: &mut Tables) {let referenced: HashSet<String> = tables.get(ITEMS_TABLE).map(|rows| rows.iter().filter_map(|r| str_col(r, LOGO_ID_COL)).map(id_key).collect()).unwrap_or_default();if let Some(logos) = tables.get_mut(LOGOS_TABLE) {@@ -219,8 +201,8 @@ fn logo_ids(tables: &Tables) -> HashSet<String> {tables.get(LOGOS_TABLE).map(|rows| rows.iter().filter_map(|r| str_col(r, ID_COL).map(id_key)).collect()).unwrap_or_default()}-/// Which row's *content* survives a natural-key collision within one manifest (the id is derived either way): a live-/// row beats a tombstoned one, a row with image bytes beats an empty one, and the highest `Id` breaks the tie.+/// Which row's content survives a natural-key collision within one manifest: a live row beats a tombstoned one, a row+/// with image bytes beats an empty one, and the highest `Id` breaks the tie.fn is_better_logo(candidate: &CodecRecord, incumbent: &CodecRecord) -> bool {let (cand_live, inc_live) = (!is_deleted(candidate), !is_deleted(incumbent));if cand_live != inc_live {@@ -233,7 +215,7 @@ fn is_better_logo(candidate: &CodecRecord, incumbent: &CodecRecord) -> bool {str_col(candidate, ID_COL).unwrap_or("") > str_col(incumbent, ID_COL).unwrap_or("")}-/// True when `FileData` holds actual bytes; a tombstoned row's NULL must not beat a row with an image.+/// True when `FileData` holds bytes.fn has_file_data(row: &CodecRecord) -> bool {has_bytes(row.get(FILE_DATA_COL))}diff --git a/core/rust/src/vault_codec/manifest.rs b/core/rust/src/vault_codec/manifest.rsindex 3bd612fee..63be40112 100644--- a/core/rust/src/vault_codec/manifest.rs+++ b/core/rust/src/vault_codec/manifest.rs@@ -1,6 +1,6 @@-//! Serde structs for the manifest-v1 data format shapes.+//! Serde structs of the manifest-v1 data format.-use std::collections::HashMap;+use std::collections::{BTreeMap, HashMap};use serde::{Deserialize, Serialize};@@ -9,7 +9,7 @@ use super::types::SCHEMA_VERSION;use crate::vault_model::names::ID_COL;use crate::vault_model::OVERFLOW_ROW_ID;-/// A codec record is a map of column names to JSON values.+/// A row: column name to JSON value.pub type CodecRecord = HashMap<String, serde_json::Value>;/// Manifest-v1 manifest.@@ -17,24 +17,19 @@ pub type CodecRecord = HashMap<String, serde_json::Value>;#[serde(rename_all = "camelCase")]pub struct Manifest {pub schema_version: u32,- /// Per-manifest salt for blob hashing (hex). For a shared manifest this salt is shared by- /// every participant (it lives inside the encrypted manifest itself) so all of them compute the- /// same content-addressed blob hashes.+ /// Per-manifest blob-hashing salt (hex), shared by every participant of a shared manifest.pub manifest_salt: String,- /// Timestamp when this canonical snapshot was produced (ISO-8601).pub canonicalized_at: String,- /// The server-side id of the manifest this snapshot belongs to.pub manifest_id: String,- /// Tables mapped to arrays of row objects. Blob columns replaced with `{ "__blobRef", "__blobKind" }`.+ /// Tables to rows; blob columns hold `{ "__blobRef", "__blobKind" }` references.#[serde(default)]pub tables: HashMap<String, Vec<CodecRecord>>,- /// Unknown top-level keys from a newer writer, carried through the local vault in [`CodecOverflow`].+ /// Unknown top-level keys from a newer writer.#[serde(flatten)]pub extra: HashMap<String, serde_json::Value>,}-/// One data bucket: a part of one manifest (one or more tables) kept out of the manifest blob so it can-/// sync on its own server revision without rewriting the manifest.+/// One data bucket: tables of one manifest kept out of the manifest blob so they sync on their own server revision.#[derive(Debug, Clone, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub struct DataBucket {@@ -48,15 +43,9 @@ pub struct DataBucket {}impl DataBucket {- /// Build the `(manifest_id, category)` data bucket from its already-normalized tables.+ /// The `(manifest_id, category)` data bucket of already-normalized tables.pub fn new(manifest_id: impl Into<String>, category: impl Into<String>, tables: HashMap<String, Vec<CodecRecord>>) -> Self {- Self {- schema_version: SCHEMA_VERSION,- manifest_id: manifest_id.into(),- category: category.into(),- tables,- extra: HashMap::new(),- }+ Self { schema_version: SCHEMA_VERSION, manifest_id: manifest_id.into(), category: category.into(), tables, extra: HashMap::new() }}}@@ -72,7 +61,6 @@ pub struct BucketLayoutEntry {#[derive(Debug, Clone, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub struct BlobEntry {- /// "favicon" | "attachment".pub kind: String,pub bytes: Vec<u8>,}@@ -82,21 +70,19 @@ pub struct BlobEntry {#[serde(rename_all = "camelCase")]pub struct ManifestSpec {pub manifest_id: String,- /// Per-manifest salt for this manifest's blob hashing.pub manifest_salt: String,}-/// One manifest produced by canonicalize: the manifest blob and the blob map hashed with its own salt.+/// One manifest produced by canonicalize: the manifest and the blob map hashed with its own salt.#[derive(Debug, Clone, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub struct CanonicalizedManifest {pub manifest: Manifest,- /// hash > blob plaintext (base64), hashed with this manifest's salt.+ /// Hash to blob, hashed with this manifest's salt.pub blobs: HashMap<String, BlobEntry>,}-/// Result of canonicalizing a vault: one entry per manifest, in the order the specs were given, plus-/// the data buckets, each addressed by the manifest that owns it.+/// Result of canonicalizing a vault: one entry per manifest in spec order, plus the data buckets.#[derive(Debug, Clone, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub struct CanonicalizedVault {@@ -104,7 +90,7 @@ pub struct CanonicalizedVault {pub data_buckets: Vec<DataBucket>,}-/// A single table's rows for reassembly.+/// One table's rows.#[derive(Debug, Clone, Serialize, Deserialize)]pub struct CodecTableData {pub name: String,@@ -116,41 +102,40 @@ pub struct CodecTableData {#[derive(Debug, Clone, Default, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub struct CodecOverflow {- /// Whole manifest tables the local schema doesn't know: name > rows, re-emitted as-is.+ /// Unknown manifest tables: name > rows.#[serde(default)]pub tables: HashMap<String, Vec<CodecRecord>>,- /// Whole bucket tables the local schema doesn't know: category > (name > rows). Kept per- /// category so both full pushes and bucket-only pushes re-emit them into the right bucket.+ /// Unknown bucket tables: category > name > rows.#[serde(default)]pub bucket_tables: HashMap<String, HashMap<String, Vec<CodecRecord>>>,- /// Unknown columns split off rows of known tables: table > row identity > {column: value}.+ /// Unknown columns of known tables: table > row identity > column > value.#[serde(default)]pub columns: HashMap<String, HashMap<String, CodecRecord>>,- /// Unknown top-level manifest keys: lowercased manifest id > {key: value}.+ /// Unknown top-level manifest keys: lowercased manifest id > key > value.#[serde(default)]pub manifest_extras: HashMap<String, HashMap<String, serde_json::Value>>,- /// Unknown top-level data bucket keys: lowercased manifest id > category > {key: value}.+ /// Unknown top-level data bucket keys: lowercased manifest id > category > key > value.#[serde(default)]pub bucket_extras: HashMap<String, HashMap<String, HashMap<String, serde_json::Value>>>,}impl CodecOverflow {- /// True when nothing was split off (the common case: reader and writer share a schema).+ /// True when nothing was split off.pub fn is_empty(&self) -> bool {self.tables.is_empty() && self.bucket_tables.is_empty() && self.columns.is_empty() && self.manifest_extras.is_empty() && self.bucket_extras.is_empty()}- /// The unknown top-level keys last seen on `manifest_id`, to write back into it.+ /// The unknown top-level keys last seen on `manifest_id`.pub fn manifest_extra(&self, manifest_id: &str) -> HashMap<String, serde_json::Value> {self.manifest_extras.get(&crate::vault_model::id_key(manifest_id)).cloned().unwrap_or_default()}- /// The unknown top-level keys last seen on the `category` bucket of `manifest_id`, to write back into it.+ /// The unknown top-level keys last seen on the `category` bucket of `manifest_id`.pub fn bucket_extra(&self, manifest_id: &str, category: &str) -> HashMap<String, serde_json::Value> {self.bucket_extras.get(&crate::vault_model::id_key(manifest_id)).and_then(|by_category| by_category.get(category)).cloned().unwrap_or_default()}- /// Render this overflow as the single `OVERFLOW_TABLE` row the platform inserts into the vault DB.+ /// This overflow as the single `OVERFLOW_TABLE` row the platform inserts into the vault DB.pub fn to_table_records(&self) -> Vec<CodecRecord> {let mut row: CodecRecord = HashMap::new();row.insert(ID_COL.to_string(), serde_json::Value::String(OVERFLOW_ROW_ID.to_string()));@@ -158,22 +143,17 @@ impl CodecOverflow {vec![row]}- /// Parse an `OVERFLOW_TABLE` row set read back from the vault DB. Tolerant to: no rows, a missing- /// `Data` column, or unparseable JSON all yield an empty overflow (better to push what we have- /// than refuse to push at all).+ /// Parse the `OVERFLOW_TABLE` row set read back from the vault DB; anything unreadable is an empty overflow, so a+ /// push is never refused for it.pub fn from_table_records(records: &[CodecRecord]) -> Self {- records- .first()- .and_then(|row| str_col(row, "Data"))- .and_then(|json| serde_json::from_str(json).ok())- .unwrap_or_default()+ records.first().and_then(|row| str_col(row, "Data")).and_then(|json| serde_json::from_str(json).ok()).unwrap_or_default()}}impl Manifest {/// Every blob this manifest's rows reference as `(hash, kind)`, sorted by hash, each hash once.pub fn referenced_blobs(&self) -> Vec<(String, String)> {- let mut refs: std::collections::BTreeMap<String, String> = std::collections::BTreeMap::new();+ let mut refs: BTreeMap<String, String> = BTreeMap::new();for (name, rows) in &self.tables {let Some(spec) = super::types::blob_spec_for(name) else { continue };for cell in rows.iter().filter_map(|row| row.get(spec.column)) {@@ -186,8 +166,8 @@ impl Manifest {}}-/// Materialized tables the platform inserts into a fresh schema DB, the overflow included as the `OVERFLOW_TABLE` row.-/// `overflow` is a diagnostics copy of that row, not something the platform must store.+/// The tables the platform inserts into a fresh schema DB, the overflow included as the `OVERFLOW_TABLE` row;+/// `overflow` is a diagnostics copy of that row.#[derive(Debug, Clone, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub struct MaterializedTables {@@ -199,14 +179,12 @@ pub struct MaterializedTables {#[derive(Debug, Clone, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub struct CanonicalizeInput {- /// All local vault tables (a plain `SELECT *` read from the vault DB). When the read includes the- /// [`OVERFLOW_TABLE`](crate::vault_model::OVERFLOW_TABLE) row written by the last materialize, its overflow- /// (a newer writer's tables/columns this schema can't hold) is re-merged automatically.+ /// All local vault tables, the `OVERFLOW_TABLE` row included so its overflow is re-merged.pub tables: Vec<CodecTableData>,pub canonicalized_at: String,pub manifests: Vec<ManifestSpec>,- /// LEGACY: for the sqlite-blob migration, the manifest that unstamped rows are stamped with. Remove once every- /// account has migrated to manifest-v1.+ /// LEGACY: the manifest the sqlite-blob migration stamps unstamped rows with. TODO: remove once every account has+ /// migrated to manifest-v1.#[serde(default)]pub stamp_unstamped_into: Option<String>,}@@ -215,9 +193,9 @@ pub struct CanonicalizeInput {#[derive(Debug, Clone, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub struct MaterializeInput {- /// Every manifest to combine, the caller's own manifest first: the others are combined into it.+ /// Every manifest to combine, the caller's own manifest first.pub manifests: Vec<Manifest>,pub data_buckets: Vec<DataBucket>,- /// The caller's local schema, table name > column names; what it cannot hold goes to [`CodecOverflow`].+ /// The caller's local schema, table name > column names.pub schema_columns: HashMap<String, Vec<String>>,}diff --git a/core/rust/src/vault_codec/materialize.rs b/core/rust/src/vault_codec/materialize.rsindex be257387a..82fce5af3 100644--- a/core/rust/src/vault_codec/materialize.rs+++ b/core/rust/src/vault_codec/materialize.rs@@ -1,8 +1,5 @@-//! Materialize the canonical representation as SQLite tables; the inverse of `canonicalize`.-//!-//! Whatever the caller's schema (`schema_columns`) cannot hold is split into [`CodecOverflow`] and emitted as the-//! `OVERFLOW_TABLE` row, so it lives in the vault DB and `canonicalize_from_sqlite` re-merges it on the next push.-//! A manifest or bucket written at a newer major format version is refused.+//! Materialize the canonical representation as SQLite tables; the inverse of `canonicalize`. What the caller's schema+//! cannot hold goes into the `OVERFLOW_TABLE` row, so the next canonicalize re-merges it.use std::collections::{HashMap, HashSet};@@ -35,7 +32,6 @@ pub fn materialize_as_sqlite(input: MaterializeInput) -> VaultResult<Materialize}let mut overflow = CodecOverflow::default();- // Top-level keys a newer writer added to a manifest or bucket; the next canonicalize writes them back.for manifest in manifests.iter().filter(|manifest| !manifest.extra.is_empty()) {overflow.manifest_extras.insert(id_key(&manifest.manifest_id), manifest.extra.clone());}@@ -45,19 +41,14 @@ pub fn materialize_as_sqlite(input: MaterializeInput) -> VaultResult<Materializelet manifest_records = manifest_bookkeeping_records(&manifests);let mut combined = super::sharing::combine_manifest_tables(manifests);-- // The wire omits derived row ids (single-value FieldValues, FieldHistories); derive them back so the- // SQLite projection has the primary keys it expects back, identical on every device.super::normalize::derive_missing_ids(&mut combined);-super::normalize::normalize_id_spelling(&mut combined);let mut tables: Vec<CodecTableData> = Vec::with_capacity(combined.len() + data_buckets.len());for (name, mut records) in combined {store_blob_hashes(&name, &mut records, &schema_columns);- // A local-only table must never occur in a manifest, and passing an OVERFLOW_TABLE row- // through would collide with the row this function emits below.+ // A local-only table never occurs in a manifest, and an OVERFLOW_TABLE row would collide with the one emitted below.if is_local_only_table(&name) {continue;}@@ -69,7 +60,6 @@ pub fn materialize_as_sqlite(input: MaterializeInput) -> VaultResult<Materialize}}- // Put every data bucket's tables back into the flat set.let mut bucket_tables: HashMap<String, Vec<CodecRecord>> = HashMap::new();for bucket in data_buckets {for (name, mut records) in bucket.tables {@@ -90,7 +80,6 @@ pub fn materialize_as_sqlite(input: MaterializeInput) -> VaultResult<Materialize}tables.extend(bucket_tables.into_iter().map(|(name, records)| CodecTableData { name, records }));- // Carry the overflow inside the vault DB itself: one OVERFLOW_TABLE row, inserted like any table.if !overflow.is_empty() {tables.push(CodecTableData { name: OVERFLOW_TABLE.to_string(), records: overflow.to_table_records() });}@@ -102,8 +91,8 @@ pub fn materialize_as_sqlite(input: MaterializeInput) -> VaultResult<MaterializeOk(MaterializedTables { tables, overflow })}-/// Write each row's blob hash into the local hash column of its table (when the caller's schema has it), so a row-/// whose bytes are not loaded still knows its blob and canonicalize can keep the reference.+/// Write each row's blob hash into its table's local hash column (when the caller's schema has it), so a row whose+/// bytes are not loaded still knows its blob.fn store_blob_hashes(table_name: &str, records: &mut [CodecRecord], schema_columns: &HashMap<String, Vec<String>>) {let Some(spec) = blob_spec_for(table_name) else { return };if !schema_columns.get(table_name).is_some_and(|columns| columns.iter().any(|column| column == spec.hash_column)) {@@ -134,19 +123,14 @@ fn manifest_bookkeeping_records(manifests: &[Manifest]) -> Vec<CodecRecord> {/// Outcome of fitting one table's rows to the caller's schema.enum SplitResult {- /// Rows the schema can insert (unknown columns already split off into overflow).+ /// Rows the schema can insert, unknown columns already split off.Fits(Vec<CodecRecord>),- /// The schema has no such table at all; the whole table belongs in overflow.+ /// The schema has no such table; the whole table belongs in the overflow.UnknownTable(Vec<CodecRecord>),}-/// Fit `records` to the caller's schema. Unknown columns are stashed in `column_overflow` keyed by row identity.-fn split_for_schema(- table_name: &str,- records: Vec<CodecRecord>,- schema_columns: &HashMap<String, Vec<String>>,- column_overflow: &mut HashMap<String, HashMap<String, CodecRecord>>,-) -> SplitResult {+/// Fit `records` to the caller's schema; unknown columns go to `column_overflow`, keyed by row identity.+fn split_for_schema(table_name: &str, records: Vec<CodecRecord>, schema_columns: &HashMap<String, Vec<String>>, column_overflow: &mut HashMap<String, HashMap<String, CodecRecord>>) -> SplitResult {let known_columns: HashSet<&str> = match schema_columns.get(table_name) {None => return SplitResult::UnknownTable(records),Some(columns) => columns.iter().map(String::as_str).collect(),@@ -160,11 +144,10 @@ fn split_for_schema(column_overflow.entry(table_name.to_string()).or_default().insert(identity, unknown);}}- // A row with no insertable columns would produce invalid SQL (`INSERT INTO t () VALUES ()`); skip it.+ // A row with no insertable columns would produce invalid SQL (`INSERT INTO t () VALUES ()`).if !known.is_empty() {fitted.push(known);}}SplitResult::Fits(fitted)}-diff --git a/core/rust/src/vault_codec/mod.rs b/core/rust/src/vault_codec/mod.rsindex 032fee1ea..2c113b6f1 100644--- a/core/rust/src/vault_codec/mod.rs+++ b/core/rust/src/vault_codec/mod.rs@@ -1,7 +1,5 @@//! The manifest-v1 storage format: `canonicalize` maps the local SQLite tables to manifests, data buckets and-//! content-addressed blobs, `materialize` maps them back. The codec knows the format rules (routing by manifest,-//! `integrity`, `logos`, `normalize`), the payload envelope (`hash`, gzip) and `validate`; encryption and-//! storage stay with the caller.+//! content-addressed blobs, `materialize` maps them back. Encryption and storage stay with the caller.mod canonicalize;pub(crate) mod integrity;@@ -29,7 +27,6 @@ pub use manifest::{};pub use materialize::materialize_as_sqlite;pub use logos::logo_id_for;-pub use sharing::extract_encryption_key_for_public_key;pub(crate) use hash::salted_blob_hash;pub(crate) use types::{blob_spec_for, ensure_readable_schema_version};pub use types::{bucket_categories, identity_part, is_bucketed_table, is_readable_schema_version, is_skip_table, manifest_scoped_tables, tables_for_category};@@ -46,19 +43,17 @@ pub fn bucket_layout() -> Vec<BucketLayoutEntry> {.collect()}-/// The sha256 (lowercase hex) of an uploaded logo's bytes: the `Source` of a-/// [`LOGO_KIND_CUSTOM`](crate::vault_model::names::LOGO_KIND_CUSTOM) row. Exposed so every platform hashes identically.+/// The sha256 (lowercase hex) of an uploaded logo's bytes: the `Source` of a custom logo row.pub fn logo_content_hash(bytes: &[u8]) -> String {hash::sha256_hex(bytes)}-/// Generate a fresh 32-byte per-manifest blob-hashing salt as a lowercase hex string.+/// A new 32-byte per-manifest blob-hashing salt as lowercase hex.pub fn generate_manifest_salt() -> String {hex_encode_lower(&crate::common::rng::random_array::<32>())}-/// Wrap a payload JSON string in an integrity envelope (`{ schemaVersion, contentHash, payload }`)-/// and gzip it.+/// Wrap a payload JSON string in the 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);@@ -71,9 +66,8 @@ pub fn pack_payload(payload_json: &str) -> VaultResult<Vec<u8>> {gzip(envelope_json.as_bytes())}-/// Cap on a decompressed payload, so a gzip bomb in a shared manifest cannot exhaust memory. Derived from the-/// server's default `MAX_UPLOAD_SIZE_MB` (100 MB per vault write, compressed): 5x that leaves room for highly-/// compressible JSON.+/// Cap on a decompressed payload, so a gzip bomb in a shared manifest cannot exhaust memory: 5x the server's default+/// 100 MB upload cap, which leaves room for highly compressible JSON.const MAX_DECOMPRESSED_PAYLOAD_BYTES: u64 = 512 * 1024 * 1024;/// A decompressed payload envelope: its content, or the format version of one this build cannot read.@@ -82,14 +76,13 @@ pub enum UnpackedPayload {NewerFormat(u32),}-/// Unpack a payload: gunzip > parse envelope > verify the embedded content hash. A newer format version is reported-/// as a value instead of an error, read before the content hash, since a newer format may hash differently and must not-/// read as corruption.+/// Unpack a payload: gunzip, parse the envelope and verify the embedded content hash.pub fn unpack_payload(plain_bytes: &[u8]) -> VaultResult<UnpackedPayload> {let decompressed = gunzip(plain_bytes, MAX_DECOMPRESSED_PAYLOAD_BYTES)?;let envelope_json = std::str::from_utf8(&decompressed).map_err(|e| VaultError::General(format!("payload is not valid UTF-8: {}", e)))?;let envelope: serde_json::Value = serde_json::from_str(envelope_json)?;+ // The version is checked before the content hash: a newer format may hash differently and must not read as corruption.let version = envelope.get("schemaVersion").and_then(|v| v.as_u64()).ok_or_else(|| VaultError::General("envelope missing schemaVersion".to_string()))?;let version = u32::try_from(version).unwrap_or(u32::MAX);if !types::is_readable_schema_version(version) {@@ -104,30 +97,23 @@ pub fn unpack_payload(plain_bytes: &[u8]) -> VaultResult<UnpackedPayload> {.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 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- )));+ return Err(VaultError::General(format!("contentHash mismatch (expected {}, got {}). Vault may be corrupt, do not load.", content_hash, expected)));}Ok(UnpackedPayload::Readable(serde_json::to_string(payload)?))}-/// SHA-256 (lowercase hex) of a ciphertext: storage-layer integrity.+/// SHA-256 (lowercase hex) of a ciphertext.pub fn compute_ciphertext_hash(ciphertext: &[u8]) -> String {hash::sha256_hex(ciphertext)}-/// Content fingerprint of a manifest / data-bucket payload for client-side change detection: SHA-256-/// (lowercase hex) of the canonical JSON with the volatile top-level `canonicalizedAt` timestamp removed-/// (it is regenerated on every canonicalize and must not read as a content change).+/// Content fingerprint of a manifest or data bucket payload for change detection: SHA-256 (lowercase hex) of the+/// canonical JSON without the volatile top-level `canonicalizedAt`.pub fn compute_content_fingerprint(payload_json: &str) -> String {match serde_json::from_str::<serde_json::Value>(payload_json) {Ok(mut value) => {@@ -136,8 +122,7 @@ pub fn compute_content_fingerprint(payload_json: &str) -> String {}hash::content_hash(&value)}- // An unparsable payload hashes to a stable but obviously-wrong value; callers compare equality, so- // a malformed input simply reads as "changed" (safe: it only forces an upload).+ // An unparsable payload hashes to a stable value that reads as changed, which only forces an upload.Err(_) => hash::sha256_hex(payload_json.as_bytes()),}}diff --git a/core/rust/src/vault_codec/normalize.rs b/core/rust/src/vault_codec/normalize.rsindex b4efd292f..05e9cb8a4 100644--- a/core/rust/src/vault_codec/normalize.rs+++ b/core/rust/src/vault_codec/normalize.rs@@ -21,27 +21,25 @@ const FIELD_VALUE_ID_NAMESPACE: &str = "aliasvault:fieldvalue:v1";/// Domain-separation prefix for derived field history ids.const FIELD_HISTORY_ID_NAMESPACE: &str = "aliasvault:fieldhistory:v1";-/// The `FieldValues.Id` of the single-value row `(manifest, item, field, position)`: a UUIDv8 whose-/// bytes come from `sha256(namespace | manifest | item | field | position)`.+/// The `FieldValues.Id` of the row `(manifest, item, field, position)`: a UUIDv8 of+/// `sha256(namespace | manifest | item | field | position)`.pub fn field_value_id_for(manifest_id: &str, item_id: &str, field_key: &str, field_definition_id: &str, value_index: i64) -> String {derived_field_id(FIELD_VALUE_ID_NAMESPACE, manifest_id, item_id, field_key, field_definition_id, &value_index.to_string())}-/// The `FieldHistories.Id` of the history row `(manifest, item, field, changed at)`; two snapshots of one field in the-/// same millisecond collapse to one.+/// The `FieldHistories.Id` of the row `(manifest, item, field, changed at)`; two snapshots of one field in the same+/// millisecond collapse to one.pub fn field_history_id_for(manifest_id: &str, item_id: &str, field_key: &str, field_definition_id: &str, changed_at: &str) -> String {derived_field_id(FIELD_HISTORY_ID_NAMESPACE, manifest_id, item_id, field_key, field_definition_id, changed_at)}-/// A UUIDv8 from `sha256(namespace | manifest | item | field | tail)`, ids lowercased.+/// A UUIDv8 of `sha256(namespace | manifest | item | field | tail)`, ids lowercased.fn derived_field_id(namespace: &str, manifest_id: &str, item_id: &str, field_key: &str, field_definition_id: &str, tail: &str) -> String {let field = field_discriminator_of(field_key, field_definition_id);super::hash::derived_uuid(&format!("{}\n{}\n{}\n{}\n{}", namespace, id_key(manifest_id), id_key(item_id), field, tail))}-/// Lowercase every id in `tables` which is the normalized spelling expected by all AliasVault clients.-///-/// Only [`is_id_column`] columns are touched.+/// Lowercase every id column of every row.pub(crate) fn normalize_id_spelling(tables: &mut HashMap<String, Vec<CodecRecord>>) {for rows in tables.values_mut() {for row in rows.iter_mut() {@@ -50,7 +48,7 @@ pub(crate) fn normalize_id_spelling(tables: &mut HashMap<String, Vec<CodecRecord}}-/// Lowercase every id of one row. See [`normalize_id_spelling`].+/// Lowercase every id column of one row.pub(crate) fn normalize_row_id_spelling(row: &mut CodecRecord) {for (column, value) in row.iter_mut() {if !is_id_column(column) {@@ -63,8 +61,8 @@ pub(crate) fn normalize_row_id_spelling(row: &mut CodecRecord) {}}-/// Normalize the rows of the tables whose wire shape differs from their SQLite shape. The caller repairs-/// referential integrity first (see [`integrity`](super::integrity)); this only reshapes rows.+/// Normalize the rows of the tables whose wire shape differs from their SQLite shape; the caller repairs referential+/// integrity first.pub(crate) fn normalize_row_shapes(tables: &mut HashMap<String, Vec<CodecRecord>>) {let multi_value_defs = multi_value_definition_ids(tables);if let Some(rows) = tables.get_mut(FIELD_VALUES_TABLE) {@@ -79,17 +77,15 @@ pub(crate) fn normalize_row_shapes(tables: &mut HashMap<String, Vec<CodecRecord>drop_deviceless_item_stats(tables);}-/// Drop ItemStats rows written before stats were kept per device. They carry no DeviceId, so on materialize they-/// would take the column default and collide with the same item's other device-less row.+/// Drop `ItemStats` rows without a `DeviceId` (written before stats were kept per device): on materialize they would+/// take the column default and collide with the same item's other device-less row.pub(crate) fn drop_deviceless_item_stats(tables: &mut HashMap<String, Vec<CodecRecord>>) {if let Some(rows) = tables.get_mut(ITEM_STATS_TABLE) {rows.retain(|row| str_col(row, DEVICE_ID_COL).is_some_and(|device| !device.is_empty()));}}-/// The materialize direction: a FieldValues or FieldHistories row without an `Id` is a row whose-/// derived id the wire omits; derive it from the row's own natural key so every device materializes-/// the same SQLite row.+/// Give every FieldValues or FieldHistories row without an `Id` the one derived from its natural key.pub(crate) fn derive_missing_ids(tables: &mut HashMap<String, Vec<CodecRecord>>) {if let Some(rows) = tables.get_mut(FIELD_VALUES_TABLE) {for row in rows.iter_mut().filter(|row| !has_id(row)) {@@ -108,18 +104,15 @@ pub(crate) fn derive_missing_ids(tables: &mut HashMap<String, Vec<CodecRecord>>)/// The `(manifest, definition id)` pairs (lowercased) of every custom field definition marked multi-value.fn multi_value_definition_ids(tables: &HashMap<String, Vec<CodecRecord>>) -> HashSet<(String, String)> {let Some(rows) = tables.get(FIELD_DEFINITIONS_TABLE) else { return HashSet::new() };- rows.iter()- .filter(|row| truthy(row.get(IS_MULTI_VALUE_COL)))- .filter_map(|row| Some((lower_str(row, MANIFEST_ID_COL)?, lower_str(row, ID_COL)?)))- .collect()+ rows.iter().filter(|row| truthy(row.get(IS_MULTI_VALUE_COL))).filter_map(|row| Some((lower_str(row, MANIFEST_ID_COL)?, lower_str(row, ID_COL)?))).collect()}/// How many values a field holds, which decides the shape its rows take on the wire.enum FieldShape {MultiValue,SingleValue,- /// Nothing says: a system field this build's registry does not list, or a custom field whose definition is gone.- /// Its rows keep the ids they carry, so none of their values is lost.+ /// A system field this registry does not list, or a custom field whose definition is gone; its rows keep the ids+ /// they carry.Unknown,}@@ -139,7 +132,6 @@ fn field_shape(row: &CodecRecord, manifest: &str, multi_value_defs: &HashSet<(St/// Renumber, collapse and re-id one FieldValues row set, per `(manifest, item, field)` group.fn normalize_field_values(rows: &mut Vec<CodecRecord>, multi_value_defs: &HashSet<(String, String)>) {- // Group row positions by natural key, preserving read order within each group.let mut groups: HashMap<(String, String, String), Vec<usize>> = HashMap::new();for (position, row) in rows.iter().enumerate() {let manifest = lower_str(row, MANIFEST_ID_COL).unwrap_or_default();@@ -151,7 +143,7 @@ fn normalize_field_values(rows: &mut Vec<CodecRecord>, multi_value_defs: &HashSefor ((manifest, _, _), mut positions) in groups {match field_shape(&rows[positions[0]], &manifest, multi_value_defs) {FieldShape::MultiValue => {- // Stable order: declared position first (a row written before the column existed sorts last), read order breaks ties.+ // Declared position first (a row written before the column existed sorts last), read order breaks ties.positions.sort_by_key(|p| value_index_of(&rows[*p]).unwrap_or(i64::MAX));for (index, position) in positions.iter().enumerate() {let row = &mut rows[*position];@@ -163,8 +155,7 @@ fn normalize_field_values(rows: &mut Vec<CodecRecord>, multi_value_defs: &HashSe}}FieldShape::SingleValue => {- // A single-value field is one row; duplicates collapse to the newest UpdatedAt instead of- // materializing into a primary-key violation.+ // Duplicates collapse to the newest UpdatedAt instead of materializing into a primary-key violation.let winner = *positions.iter().max_by_key(|p| (updated_at(&rows[**p]), std::cmp::Reverse(**p))).unwrap();removed.extend(positions.iter().filter(|p| **p != winner));let row = &mut rows[winner];@@ -172,7 +163,7 @@ fn normalize_field_values(rows: &mut Vec<CodecRecord>, multi_value_defs: &HashSerow.remove(ID_COL);}FieldShape::Unknown => {- // Only rows naming one row collapse (one carrying the id the other would derive), since they would materialize into one primary key.+ // Only rows that would materialize into one primary key collapse.let mut newest: HashMap<String, usize> = HashMap::new();for position in positions {let id = materialized_id(&rows[position]);@@ -199,8 +190,8 @@ fn normalize_field_values(rows: &mut Vec<CodecRecord>, multi_value_defs: &HashSe}}-/// Strip every history row's id (all of them derive it) and collapse rows sharing a natural key,-/// which takes two same-millisecond snapshots of one field, to the newest `UpdatedAt`.+/// Strip every history row's id and collapse rows sharing a natural key (two same-millisecond snapshots of one field)+/// to the newest `UpdatedAt`.fn normalize_field_histories(rows: &mut Vec<CodecRecord>) {strip_ids(rows);collapse_newest_by_key(rows, |row| {@@ -209,7 +200,7 @@ fn normalize_field_histories(rows: &mut Vec<CodecRecord>) {});}-/// Drop the legacy surrogate `Id` and collapse duplicates to the newest `UpdatedAt` per natural key.+/// Drop the surrogate `Id` and collapse duplicates to the newest `UpdatedAt` per natural key.fn normalize_item_tags(rows: &mut Vec<CodecRecord>) {strip_ids(rows);collapse_newest_by_key(rows, |row| {@@ -224,8 +215,7 @@ fn strip_ids(rows: &mut [CodecRecord]) {}}-/// Keep one row per `key_of` value: the newest `UpdatedAt`, ties keeping the earlier row (matching-/// the single-value collapse rule). Row order is preserved.+/// Keep one row per `key_of` value, the newest `UpdatedAt`, ties keeping the earlier row; row order is preserved.fn collapse_newest_by_key<K: std::hash::Hash + Eq>(rows: &mut Vec<CodecRecord>, key_of: impl Fn(&CodecRecord) -> K) {let mut winners: HashMap<K, usize> = HashMap::new();for (position, row) in rows.iter().enumerate() {@@ -250,18 +240,18 @@ fn retain_positions(rows: &mut Vec<CodecRecord>, keep: &HashSet<usize>) {});}-/// The derived id for a normalized FieldValues row at `value_index`.+/// The derived id of a normalized FieldValues row at `value_index`.fn derive_row_id(row: &CodecRecord, value_index: i64) -> String {let [manifest, item, field_key, field_def] = field_key_parts(row);field_value_id_for(manifest, item, field_key, field_def, value_index)}-/// The id a row materializes under: the one it carries, or the one [`derive_missing_ids`] would give it.+/// The id a row materializes under: the one it carries, or the one it would derive.fn materialized_id(row: &CodecRecord) -> String {lower_str(row, ID_COL).unwrap_or_else(|| derive_row_id(row, value_index_of(row).unwrap_or(0)))}-/// The derived id for a normalized FieldHistories row.+/// The derived id of a normalized FieldHistories row.fn derive_history_row_id(row: &CodecRecord) -> String {let [manifest, item, field_key, field_def] = field_key_parts(row);field_history_id_for(manifest, item, field_key, field_def, str_col(row, CHANGED_AT_COL).unwrap_or_default())@@ -272,7 +262,7 @@ fn field_key_parts(row: &CodecRecord) -> [&str; 4] {[MANIFEST_ID_COL, ITEM_ID_COL, FIELD_KEY_COL, FIELD_DEFINITION_ID_COL].map(|column| str_col(row, column).unwrap_or_default())}-/// The field half of a FieldValues row's natural key, see [`field_discriminator_of`].+/// The field half of a FieldValues row's natural key.fn field_discriminator(row: &CodecRecord) -> String {let [_, _, field_key, field_def] = field_key_parts(row);field_discriminator_of(field_key, field_def)@@ -288,6 +278,7 @@ pub(super) fn has_id(row: &CodecRecord) -> bool {str_col(row, ID_COL).is_some_and(|s| !s.is_empty())}+/// The `ValueIndex` of a row, from a number or a numeric string.fn value_index_of(row: &CodecRecord) -> Option<i64> {match row.get(VALUE_INDEX_COL)? {serde_json::Value::Number(n) => n.as_i64(),diff --git a/core/rust/src/vault_codec/row.rs b/core/rust/src/vault_codec/row.rsindex 6cf7ecca3..ded98a910 100644--- a/core/rust/src/vault_codec/row.rs+++ b/core/rust/src/vault_codec/row.rs@@ -1,6 +1,5 @@-//! Reading cells out of a row as the platforms hand them over: SQLite booleans arrive as 0/1-//! numbers, JSON booleans or "1"/"true" strings, byte cells as `{ "__b64" }` (inline bytes) or-//! `{ "__blobRef", "__blobKind" }` (an extracted blob) markers, and a missing table reads as no rows.+//! Reading cells out of a row as the platforms hand them over: booleans as 0/1 numbers, JSON booleans or "1"/"true"+//! strings, bytes as `{ "__b64" }` (inline) or `{ "__blobRef", "__blobKind" }` (an extracted blob) markers.use std::collections::HashMap;@@ -44,14 +43,14 @@ pub(crate) fn rows_of<'a>(tables: &'a HashMap<String, Vec<CodecRecord>>, table:tables.get(table).map(Vec::as_slice).unwrap_or(&[])}-/// A logo `Kind` in its comparison form: trimmed and lowercased, empty meaning [`LOGO_KIND_FAVICON`]-/// (the row was written before the column existed, when every logo was a favicon).+/// A logo `Kind` in its comparison form: trimmed and lowercased, empty meaning favicon, as every logo was before the+/// column existed.pub(crate) fn normalize_logo_kind(kind: &str) -> String {let trimmed = kind.trim();if trimmed.is_empty() { LOGO_KIND_FAVICON.to_string() } else { trimmed.to_lowercase() }}-/// A logo row's `Kind`, normalized (see [`normalize_logo_kind`]).+/// A logo row's `Kind`, normalized.pub(crate) fn logo_kind(row: &CodecRecord) -> String {normalize_logo_kind(str_col(row, KIND_COL).unwrap_or(""))}@@ -77,9 +76,8 @@ pub(crate) fn blob_ref_of(value: &Value) -> Option<(&str, Option<&str>)> {Some((hash, value.get(BLOB_KIND_KEY).and_then(Value::as_str)))}-/// True when a cell holds bytes: a non-empty inline `{ __b64 }`, an extracted `{ __blobRef }`, or any-/// other non-empty string, array or object (the 1-byte presence marker the prune queries select).-/// A tombstoned row drops its bytes (NULL), which is present but carries nothing.+/// True when a cell holds bytes: a non-empty inline `{ __b64 }`, an extracted `{ __blobRef }`, or any other non-empty+/// string, array or object (the presence marker the prune queries select).pub(crate) fn has_bytes(value: Option<&Value>) -> bool {match value {None | Some(Value::Null) => false,diff --git a/core/rust/src/vault_codec/sharing.rs b/core/rust/src/vault_codec/sharing.rsindex b14c9cedd..45d74dece 100644--- a/core/rust/src/vault_codec/sharing.rs+++ b/core/rust/src/vault_codec/sharing.rs@@ -1,23 +1,5 @@-//! Split/combine logic for multi-manifest vaults.-//!-//! A manifest is a namespace: an id, a display name, its own VEK and blob salt, and the rows carrying its id in-//! their `ManifestId` column. No manifest is privileged and there is no fallback manifest: every row routes by its own-//! stamp, canonicalize rejects an unstamped one, and a row stamped for a manifest this vault no longer carries is-//! dropped, since there is no namespace left to write it to.-//!-//! **partition** (canonicalize side) routes every row of the unified table set to the manifest its stamp names,-//! with two refinements: a row hanging off an item follows its item (the parent's location is leading), and a-//! folder whose parent lives in another manifest has its `ParentFolderId` nulled. Each manifest is then made-//! self-contained: it gets its own copy of the content its rows reference (see [`clone_referenced_rows`]) and its-//! own logos (see [`logos`](super::logos)).-//!-//! **combine** (materialize side) stamps every manifest's rows with the manifest they arrived in, drops the-//! `EncryptionKeys` rows it may not publish plus the bucketed, personal and bookkeeping tables no manifest may-//! carry, and repairs the references a namespace boundary leaves dangling (see [`integrity`](super::integrity)).-//!-//! **Referenced content** is copied, never moved. A foreign key is composite, so a row in another namespace is as-//! absent as a deleted one, and the manifest referencing it gets its own stamped copy: two members editing "the-//! same" tag or logo then never overwrite each other.+//! Split and combine of multi-manifest vaults: partition routes every row to the manifest its `ManifestId` names+//! (the canonicalize side), combine stamps every manifest's rows with the manifest they arrived in (the materialize side).use std::collections::{HashMap, HashSet};@@ -26,16 +8,21 @@ use serde_json::{json, Value};use super::integrity;use super::logos::{localize_logos, restamp_logos};use super::manifest::{CodecRecord, Manifest, ManifestSpec};-use super::row::{is_deleted, rows_of, str_col};+use super::row::{rows_of, str_col};use super::types::{is_bucketed_table, is_local_only_table, is_manifest_scoped, is_personal_table, row_identity};use crate::common::error::{VaultError, VaultResult};-use crate::vault_model::names::{ENCRYPTION_KEYS_TABLE, FOLDERS_TABLE, ID_COL, ITEMS_TABLE, ITEM_ID_COL, LOGOS_TABLE, PARENT_FOLDER_ID_COL, PUBLIC_KEY_COL};+use crate::vault_model::names::{ENCRYPTION_KEYS_TABLE, FOLDERS_TABLE, ID_COL, ITEMS_TABLE, ITEM_ID_COL, LOGOS_TABLE, PARENT_FOLDER_ID_COL};use crate::vault_model::{ids_equal, MANIFEST_ID_COL, REFERENCED_TABLES};type Tables = HashMap<String, Vec<CodecRecord>>;-/// The tables a caller must snapshot before routing, so the referenced content can be copied out of them-/// afterwards: every [`REFERENCED_TABLES`] target plus `Logos`.+/*+ * No manifest is privileged: every row routes by its own stamp, canonicalize rejects an unstamped row, and a row stamped+ * for a manifest this vault no longer carries is dropped. Referenced content (tags, logos) is copied into every manifest+ * that references it, never moved.+ */++/// The tables to snapshot before routing, so the referenced content can be copied out of them afterwards.pub(super) fn referenced_tables() -> Vec<&'static str> {let mut out: Vec<&'static str> = vec![LOGOS_TABLE];out.extend(REFERENCED_TABLES.iter().map(|(target, _)| *target));@@ -48,9 +35,9 @@ pub(super) struct ManifestPartition {pub tables: Tables,}-/// Where each item was routed, so the rows hanging off it follow it. Children resolve by `(ManifestId, ItemId)`, never by-/// bare `ItemId`: two manifests may hold the same item id, and that would leak personal rows into a shared manifest.-/// `by_id` covers an item moved without re-stamping its children, and only while exactly one item carries that id.+/// Where each item was routed, so its child rows follow it. Children resolve by `(ManifestId, ItemId)`, never+/// by bare `ItemId`, since two manifests may hold the same item id and that would leak personal rows into a shared+/// manifest; `by_id` covers an item moved without re-stamping its children, and only while one item carries that id.#[derive(Default)]struct ItemRoutes {by_identity: HashMap<(String, String), Option<usize>>,@@ -94,19 +81,18 @@ pub(super) fn partition_by_manifest(mut tables: Tables, specs: &[ManifestSpec],}}- // Where a row goes, read straight off its `ManifestId` stamp.let route = |row: &CodecRecord| -> Option<usize> {let manifest_id = str_col(row, MANIFEST_ID_COL)?;specs.iter().position(|spec| ids_equal(&spec.manifest_id, manifest_id))};- // The `(ManifestId, Id)` of every folder, so a folder's parent link can be checked within its own namespace.+ // The `(ManifestId, Id)` of every folder, so a parent link is checked within the folder's own namespace.let folder_identities: HashSet<(String, String)> = rows_of(&tables, FOLDERS_TABLE).iter().filter_map(|row| Some((str_col(row, MANIFEST_ID_COL)?.to_string(), str_col(row, ID_COL)?.to_string()))).collect();let mut partitions: Vec<ManifestPartition> = specs.iter().map(|spec| ManifestPartition { spec: spec.clone(), tables: Tables::new() }).collect();let mut item_routes = ItemRoutes::default();- // Items first, so the rows hanging off them can follow; every other table routes by its rows' own stamps.+ // Items first, so their child rows can follow; every other table routes by its rows' own stamps.let item_child_tables: Vec<String> = tables.iter().filter(|(name, rows)| is_manifest_scoped(name) && !is_bucketed_table(name) && !is_personal_table(name) && *name != ITEMS_TABLE && rows.iter().any(|r| r.contains_key(ITEM_ID_COL))).map(|(name, _)| name.clone()).collect();let mut order: Vec<String> = vec![ITEMS_TABLE.to_string()];order.extend(tables.keys().filter(|name| *name != ITEMS_TABLE).cloned());@@ -140,7 +126,6 @@ pub(super) fn partition_by_manifest(mut tables: Tables, specs: &[ManifestSpec],}}- // Each manifest ends up self-contained: the logos and referenced rows its own rows point at, under its own id.let all_logos = rows_of(snapshots, LOGOS_TABLE);let writing_manifest_id = specs.first().map(|spec| spec.manifest_id.as_str()).unwrap_or_default();for partition in partitions.iter_mut() {@@ -185,21 +170,18 @@ fn pick_source_row<'a>(rows: &'a [CodecRecord], id: &str, preferred_manifest_id:candidates.into_iter().min_by_key(|row| str_col(row, MANIFEST_ID_COL).unwrap_or_default().to_ascii_lowercase())}-/// Combine every manifest's tables into one unified set. Every manifest is held to the same rules: its rows are-/// stamped with its own id, it may publish only its own key material, and it may carry no bucketed, personal or-/// bookkeeping table. The references a namespace boundary leaves dangling are repaired at the end.+/// Combine every manifest's tables into one unified set: each manifest's rows stamped with its own id, only its own+/// key material published, no bucketed, personal or bookkeeping table carried, and unresolved references repaired.pub(super) fn combine_manifest_tables(manifests: Vec<Manifest>) -> Tables {let mut combined = Tables::new();- // First-manifest-wins per row identity. The identity folds the stamp in, so this can never fire across manifests;- // it only dedupes a truly duplicated row inside one manifest.+ // First manifest wins per row identity; the identity folds the stamp in, so this only dedupes within one manifest.let mut seen: HashMap<String, HashSet<String>> = HashMap::new();for mut manifest in manifests {let manifest_id = manifest.manifest_id.clone();stamp_manifest_rows(&mut manifest.tables, &manifest_id);for (name, rows) in manifest.tables {- // Bucketed tables sync beside the manifest, a personal table may not leave the user's own vault, and local- // bookkeeping never travels inside one. Dropping them here also keeps a manifest authored by another user- // from injecting rows into this vault's personal manifest.+ // Dropping these here also keeps a manifest authored by another user from injecting rows into this vault's+ // personal manifest.if is_local_only_table(&name) || is_bucketed_table(&name) || is_personal_table(&name) {continue;}@@ -216,8 +198,8 @@ pub(super) fn combine_manifest_tables(manifests: Vec<Manifest>) -> Tables {combined}-/// Stamp every row of one manifest's tables with `manifest_id`, so the next push routes it by the manifest it arrived in.-/// `EncryptionKeys` are never stamped: their stamp is a claim [`retain_own_encryption_keys`] checks, and stamping would make it true.+/// Stamp every row of one manifest's tables with `manifest_id`, so the next push routes it by the manifest it arrived+/// in. `EncryptionKeys` are never stamped: their stamp is a claim that is checked, and stamping would make it true.fn stamp_manifest_rows(tables: &mut Tables, manifest_id: &str) {restamp_logos(tables, manifest_id);retain_own_encryption_keys(tables, manifest_id);@@ -228,18 +210,10 @@ fn stamp_manifest_rows(tables: &mut Tables, manifest_id: &str) {}}-/// Keep only the `EncryptionKeys` rows a manifest may legitimately publish: the ones stamped with its own id. An-/// unstamped row is dropped rather than stamped: it is a manifest asking to have key material moved into a manifest it-/// never proved it owns.+/// Keep only the `EncryptionKeys` rows stamped with the manifest's own id; an unstamped row is dropped rather than+/// stamped, since that would move key material into a manifest it never proved it owns.fn retain_own_encryption_keys(tables: &mut Tables, manifest_id: &str) {if let Some(rows) = tables.get_mut(ENCRYPTION_KEYS_TABLE) {rows.retain(|row| str_col(row, MANIFEST_ID_COL).is_some_and(|stamp| ids_equal(stamp, manifest_id)));}}--/// The encryption-key row whose `PublicKey` matches `public_key`, from a decrypted manifest. The row must be-/// stamped with the manifest's own id, so a caller that skips the combine step still cannot be tricked into using-/// another manifest's key material. Deleted rows are skipped.-pub fn extract_encryption_key_for_public_key(manifest: &Manifest, public_key: &str) -> Option<CodecRecord> {- manifest.tables.get(ENCRYPTION_KEYS_TABLE)?.iter().find(|row| str_col(row, PUBLIC_KEY_COL) == Some(public_key) && str_col(row, MANIFEST_ID_COL).is_some_and(|stamp| ids_equal(stamp, &manifest.manifest_id)) && !is_deleted(row)).cloned()-}diff --git a/core/rust/src/vault_codec/tests/integrity.rs b/core/rust/src/vault_codec/tests/integrity.rsindex b1d9febbd..887c04672 100644--- a/core/rust/src/vault_codec/tests/integrity.rs+++ b/core/rust/src/vault_codec/tests/integrity.rs@@ -11,7 +11,7 @@ fn tables(entries: &[(&str, Vec<CodecRecord>)]) -> HashMap<String, Vec<CodecReco}#[test]-fn a_reference_that_resolves_only_in_another_manifest_dangles() {+fn a_reference_that_resolves_only_in_another_manifest_is_unresolved() {let mut set = tables(&[("Folders", vec![row(&[("ManifestId", json!("m-other")), ("Id", json!("f-1"))])]),("Items", vec![stamped(M, &[("Id", json!("i-1")), ("FolderId", json!("f-1"))])]),diff --git a/core/rust/src/vault_codec/tests/mod.rs b/core/rust/src/vault_codec/tests/mod.rsindex 62bd52ad2..7ead47976 100644--- a/core/rust/src/vault_codec/tests/mod.rs+++ b/core/rust/src/vault_codec/tests/mod.rs@@ -184,7 +184,7 @@ fn unknown_top_level_manifest_fields_round_trip() {#[test]fn canonicalize_repairs_what_validation_would_refuse() {- // Dangling references are nulled or dropped on the way out, so a push is never refused for them; a manifest+ // Unresolved references are nulled or dropped on the way out, so a push is never refused for them; a manifest// handed to validation with them still in place is refused, with a stable rule id per reference.let out = canonicalize(vec![table("Items", vec![row(&[("Id", json!("i1")), ("FolderId", json!("missing"))]), row(&[("Id", json!("i2")), ("FolderId", json!(""))])]),diff --git a/core/rust/src/vault_codec/tests/sharing.rs b/core/rust/src/vault_codec/tests/sharing.rsindex 9fec3d8d3..d5537c397 100644--- a/core/rust/src/vault_codec/tests/sharing.rs+++ b/core/rust/src/vault_codec/tests/sharing.rs@@ -178,7 +178,7 @@ fn every_row_routes_to_the_manifest_its_stamp_names() {assert_eq!(ids(rows_of(&shared.tables, "Items")), vec!["i-shared", "i-sub"]);assert_eq!(ids(rows_of(&personal.tables, "Items")), vec!["i-nofolder", "i-personal"]);- // Every table of rows hanging off an item follows it, with zero per-table wiring, and claims the manifest it joined.+ // Every child table of an item follows it, with zero per-table wiring, and claims the manifest it joined.assert_eq!(values(rows_of(&shared.tables, "FieldValues")), vec!["family", "hunter2"]);assert_eq!(values(rows_of(&personal.tables, "FieldValues")), vec!["me"]);assert_eq!(ids(rows_of(&shared.tables, "TotpCodes")), vec!["totp-shared"]);@@ -826,24 +826,6 @@ fn combine_accepts_a_manifests_own_keypair_and_drops_every_other_claim() {assert_eq!(ids(&materialized_map(&re)["EncryptionKeys"]), vec!["ek-1", "sfk-1"]);}-#[test]-fn a_keypair_resolves_by_public_key_within_its_manifest_only() {- // After a rotation the superseded row stays so older mail remains decryptable; only the live primary is the- // delivery key. A caller that skips combine must still not be handed another manifest's key material.- let out = canonicalize(owner_tables_with_keys(vec![keypair("sfk-old", SHARED, "pub-old", 0), keypair("sfk-cur", SHARED, "pub-cur", 1)]), &[SHARED]);- let mut shared = manifest(&out, SHARED).manifest.clone();- assert_eq!(extract_encryption_key_for_public_key(&shared, "pub-old").unwrap()["PrivateKey"], json!("priv-pub-old"), "a rotated key still resolves");- assert_eq!(extract_encryption_key_for_public_key(&shared, "pub-cur").unwrap()["Id"], json!("sfk-cur"));- assert!(extract_encryption_key_for_public_key(&shared, "pub-nonexistent").is_none());-- shared.tables.get_mut("EncryptionKeys").unwrap().push(keypair("sfk-foreign", "m-other", "pub-foreign", 1));- let mut deleted = keypair("sfk-dead", SHARED, "pub-dead", 0);- deleted.insert("IsDeleted".to_string(), json!(1));- shared.tables.get_mut("EncryptionKeys").unwrap().push(deleted);- assert!(extract_encryption_key_for_public_key(&shared, "pub-foreign").is_none(), "another manifest's row ignored");- assert!(extract_encryption_key_for_public_key(&shared, "pub-dead").is_none(), "deleted row ignored");-}-#[test]fn validation_refuses_a_manifest_carrying_what_is_not_its_own() {// Catching this at validate time means a tampered vault fails loudly on push instead of quietly losing rows atdiff --git a/core/rust/src/vault_codec/types.rs b/core/rust/src/vault_codec/types.rsindex b1e266760..c1686ee04 100644--- a/core/rust/src/vault_codec/types.rs+++ b/core/rust/src/vault_codec/types.rs@@ -1,9 +1,6 @@-//! Format constants for the manifest-v1 storage layout.-//!-//! The datamodel registry data (tables, keys, bucket layout, blob columns, sentinels) lives in-//! [`crate::vault_model`], generated from the TypeScript source of truth in-//! core/models/src/vault/VaultTableRegistry.ts; this module adds the codec-owned accessors on top.+//! Format constants and table classification for the manifest-v1 storage layout.+use crate::common::error::{VaultError, VaultResult};use crate::vault_model::names::ID_COL;use crate::vault_model::{ids_equal, BlobColumn, BLOB_COLUMNS, BUCKET_TABLES, MANIFEST_ID_COL, OVERFLOW_TABLE, PERSONAL_TABLES, SKIP_TABLES, SYNCABLE_TABLES, UNSTAMPED_MANIFEST_ID};@@ -16,15 +13,14 @@ pub fn is_readable_schema_version(schema_version: u32) -> bool {}/// Refuse a manifest or data bucket written at a format version this build cannot read.-pub(crate) fn ensure_readable_schema_version(schema_version: u32, label: &str) -> crate::common::error::VaultResult<()> {+pub(crate) fn ensure_readable_schema_version(schema_version: u32, label: &str) -> VaultResult<()> {if is_readable_schema_version(schema_version) {return Ok(());}- Err(crate::common::error::VaultError::General(format!("{} has format version {}, this build reads up to {}", label, schema_version, SCHEMA_VERSION)))+ Err(VaultError::General(format!("{} has format version {}, this build reads up to {}", label, schema_version, SCHEMA_VERSION)))}-/// One identity component of a row, as a string: a GUID lowercased, any other string as-is,-/// anything else canonical JSON.+/// One identity component of a row, as a string: a GUID lowercased, any other string as-is, anything else canonical JSON.pub fn identity_part(value: &serde_json::Value) -> String {match value.as_str() {Some(text) if is_guid(text) => text.to_ascii_lowercase(),@@ -52,7 +48,7 @@ pub fn blob_spec_for(table_name: &str) -> Option<&'static BlobColumn> {BLOB_COLUMNS.iter().find(|spec| spec.table == table_name)}-/// True when a table must never be serialized into / inserted from the manifest.+/// True when a table must never be serialized into or inserted from the manifest.pub fn is_skip_table(table_name: &str) -> bool {SKIP_TABLES.contains(&table_name)}@@ -67,8 +63,7 @@ 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.+/// All distinct bucket categories, in declaration order.pub fn bucket_categories() -> Vec<&'static str> {let mut out: Vec<&'static str> = Vec::new();for (_, category) in BUCKET_TABLES {@@ -79,7 +74,7 @@ pub fn bucket_categories() -> Vec<&'static str> {out}-/// The tables that make up a bucket category, in declaration order. Empty if the category is unknown.+/// The tables of a bucket category, in declaration order; empty for an unknown category.pub fn tables_for_category(category: &str) -> Vec<&'static str> {BUCKET_TABLES.iter().filter(|(_, c)| *c == category).map(|(t, _)| *t).collect()}@@ -92,17 +87,17 @@ pub fn is_unstamped_manifest_id(manifest_id: Option<&str>) -> bool {}}-/// True when a table is personal-only (see [`PERSONAL_TABLES`]): never part of a shared manifest.+/// True when a table is personal-only: never part of a shared manifest.pub fn is_personal_table(table_name: &str) -> bool {PERSONAL_TABLES.contains(&table_name)}-/// True when a table syncs in a data bucket (see [`BUCKET_TABLES`]) rather than inside the manifest.+/// True when a table syncs in a data bucket rather than inside the manifest.pub fn is_bucketed_table(table_name: &str) -> bool {bucket_category_for(table_name).is_some()}-/// Get the primary key columns for a table.+/// The primary key columns of a table.pub(crate) fn primary_key_columns_for(table_name: &str) -> &'static [&'static str] {SYNCABLE_TABLES.iter().find(|t| t.name == table_name).map(|t| t.primary_key_columns).unwrap_or(&[ID_COL])}@@ -122,22 +117,15 @@ pub(crate) fn identity_columns_for(table_name: &str) -> Vec<&'static str> {SYNCABLE_TABLES.iter().find(|t| t.name == table_name).map(|t| t.identity_columns()).unwrap_or_else(|| vec![ID_COL])}-/// Stable string key identifying `row` within `table_name`: the identity parts joined by `\u{1f}`, a-/// null or absent column skipped. See also `vault_merge::get_key`, whose empty-part rule the merge relies on.+/// Stable string key identifying `row` within `table_name`: the identity parts joined by `\u{1f}`, a null or absent+/// column skipped; `None` for a row missing a primary key column, which cannot be addressed at all.pub fn row_identity(table_name: &str, row: &super::manifest::CodecRecord) -> Option<String> {let mut columns = identity_columns_for(table_name);if !columns.contains(&MANIFEST_ID_COL) && row.get(MANIFEST_ID_COL).filter(|value| !value.is_null()).is_some() {columns.insert(0, MANIFEST_ID_COL);}- // A row missing any primary key column cannot be addressed at all.for column in primary_key_columns_for(table_name) {row.get(*column)?;}- Some(- columns- .iter()- .filter_map(|column| row.get(*column).filter(|v| !v.is_null()).map(identity_part))- .collect::<Vec<_>>()- .join("\u{1f}"),- )+ Some(columns.iter().filter_map(|column| row.get(*column).filter(|v| !v.is_null()).map(identity_part)).collect::<Vec<_>>().join("\u{1f}"))}diff --git a/core/rust/src/vault_codec/validate.rs b/core/rust/src/vault_codec/validate.rsindex 74923f02f..74ebd5221 100644--- a/core/rust/src/vault_codec/validate.rs+++ b/core/rust/src/vault_codec/validate.rs@@ -19,9 +19,9 @@ const MIN_MANIFEST_SALT_LEN: usize = 32;#[serde(rename_all = "camelCase")]pub struct ValidationResult {pub ok: bool,- /// Stable rule identifiers that failed. Empty when ok.+ /// Stable rule identifiers that failed, empty when ok.pub failed_rules: Vec<String>,- /// Human-readable explanation. Empty when ok.+ /// Human-readable explanation, empty when ok.pub message: String,}@@ -51,7 +51,6 @@ pub fn validate_manifest(manifest: &Manifest) -> ValidationResult {return ValidationResult::from_failures(failed);}- // A bucketed table syncs as its own resource, so no manifest may carry it; a personal table may not leave the user's own vault.let carried = |predicate: fn(&str) -> bool| manifest.tables.iter().find(|(name, rows)| !rows.is_empty() && predicate(name)).map(|(name, _)| name.clone());if let Some(name) = carried(is_bucketed_table) {fail("manifest-carries-bucketed-table", format!("Manifest carries bucketed table {}, which belongs in its data bucket", name));@@ -82,7 +81,7 @@ pub fn validate_manifest(manifest: &Manifest) -> ValidationResult {fail(rule, String::new());}}- // A logo belongs to exactly one manifest: (ManifestId, Kind, Source) is UNIQUE in the client schema.+ // (ManifestId, Kind, Source) is UNIQUE in the client schema.let logos = rows_of(&manifest.tables, LOGOS_TABLE);let logo_keys: HashSet<(String, String)> = logos.iter().filter_map(|l| Some((logo_kind(l), str_col(l, SOURCE_COL)?.to_lowercase()))).collect();if logo_keys.len() != logos.iter().filter(|l| str_col(l, SOURCE_COL).is_some()).count() {diff --git a/core/rust/src/vault_merge/item_deletes.rs b/core/rust/src/vault_merge/item_deletes.rsindex daab0497b..828b2bfc2 100644--- a/core/rust/src/vault_merge/item_deletes.rs+++ b/core/rust/src/vault_merge/item_deletes.rs@@ -1,12 +1,4 @@-//! Item deletes in the canonical merge, decided once per item instead of row by row.-//!-//! A permanent delete tombstones the item and takes the rows hanging off it along, so the item and-//! its children are one unit. Row-level LWW breaks that unit both ways: children the deleting side-//! removed come back from the other side under a tombstoned item, and child tombstones stamped at-//! delete time wipe the untouched fields of an item whose delete lost. So a delete only one side made-//! is settled here first, against everything the other side did to that item (a field edit does not-//! touch the item row), and the losing side's rows of the item leave the merge. A delete that stands-//! needs nothing more: the merged output drops a tombstoned item's children when it is normalized.+//! Item deletes in the canonical merge, resolved for the item and all of its child rows together.use std::collections::{HashMap, HashSet};@@ -21,8 +13,21 @@ use crate::vault_model::{MANIFEST_ID_COL, SYNCABLE_TABLES};type Tables = HashMap<String, Vec<CodecRecord>>;-/// Settle every delete only one side made: a delete the other side outlived is taken out of the deleting-/// side's input together with that side's rows of the item, so the surviving side's rows pass through whole.+/*+ * An item is its Items row plus its rows in the child tables (field values, attachments, TOTP codes, passkeys, tags).+ * Merging every row on its own (last write wins) splits that unit when one side deleted the item and the other side+ * kept changing it:+ * - child rows the other side edited after the delete come back, under a deleted item;+ * - when the other side's edit wins the Items row, the child tombstones written at delete time still wipe every child+ * row that side did not touch.+ * So a delete only one side made is resolved first, for the item as a whole: the delete is compared with the other+ * side's latest change to the item, counting its child rows too (a field edit updates the FieldValues row, not the+ * Items row). When that change is later, the delete loses and the deleting side's Items row and child rows leave the+ * merge. When the delete wins, nothing more is needed: normalizing the merged output drops a deleted item's children.+ */++/// Resolve every item delete only one side made: when the other side changed the item or its child rows later, the+/// deleting side's rows of that item are removed from its input, so the kept item comes through whole.pub(super) fn resolve_item_deletes(base: &mut Tables, incoming: &mut Tables) {// The base keeps ties, exactly as it does for a single row.let lost_in_base = lost_deletes(base, incoming, |delete, activity| activity > delete);@@ -43,8 +48,8 @@ fn lost_deletes(deleting: &Tables, other: &Tables, outlives: impl Fn(Option<Datereturn HashSet::new();}- // What the surviving side last did to the item: its own row, or any row hanging off it. Bucketed- // tables stay out, since a usage counter ticking is not an edit.+ // What the surviving side last did to the item: its own row, or any of its child rows. Bucketed tables stay out,+ // since a usage counter ticking is not an edit.for child in SYNCABLE_TABLES.iter().filter(|table| table.item_child && !is_bucketed_table(table.name)) {for row in rows_of(other, child.name) {if let Some(activity) = live.get_mut(&item_key(row, child.item_ref_column())) {@@ -56,7 +61,7 @@ fn lost_deletes(deleting: &Tables, other: &Tables, outlives: impl Fn(Option<Datelive.into_iter().filter(|(key, activity)| outlives(tombstones[key], *activity)).map(|(key, _)| key).collect()}-/// Remove the item rows named by `keys` and every row hanging off them.+/// Remove the item rows named by `keys` and all of their child rows.fn remove_items(tables: &mut Tables, keys: &HashSet<String>) {if keys.is_empty() {return;diff --git a/core/rust/src/vault_merge/mod.rs b/core/rust/src/vault_merge/mod.rsindex e7659ba88..9fd82291c 100644--- a/core/rust/src/vault_merge/mod.rs+++ b/core/rust/src/vault_merge/mod.rs@@ -1,11 +1,5 @@-//! Vault merge: Last-Write-Wins over manifest JSON + data buckets, rows in, rows out.-//!-//! Both sides arrive in canonical form and the output is the merged canonical form, which the platform then-//! materializes once.-//!-//! Each manifest is merged independently (the server manifest set is the universe), so a broken-//! manifest can never affect another manifest's rows, and blob columns carry `__blobRef` markers-//! rather than bytes, so no byte payload ever crosses the merge.+//! Last-write-wins merge of the canonical vault (manifests and data buckets), one manifest at a time, rows in and+//! rows out. Both sides arrive in canonical form and the output is the merged canonical form.use std::collections::{BTreeSet, HashMap, HashSet};@@ -24,13 +18,13 @@ mod tests;#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub struct MergeStats {- /// Rows both sides hold where the base row stood (older or same-aged incoming row).+ /// Rows both sides hold where the base row stood.pub base_kept: u32,/// Rows both sides hold where the newer incoming row replaced the base row.pub incoming_won: u32,/// Rows only the base holds.pub base_only: u32,- /// Rows only the incoming side holds (made offline).+ /// Rows only the incoming side holds.pub incoming_only: u32,}@@ -44,8 +38,7 @@ impl MergeStats {}}-/// Input of the canonical merge. The server side is the base (kept on ties); the local side is the-/// incoming set produced by `canonicalize_from_sqlite`.+/// Input of the canonical merge: the server side is the base (kept on ties), the local side the incoming set.#[derive(Debug, Clone, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub struct CanonicalMergeInput {@@ -123,21 +116,14 @@ fn group_buckets(buckets: Vec<DataBucket>) -> HashMap<String, Vec<DataBucket>> {grouped}-/// Merge one manifest: LWW over the flattened table view of both sides, then split the bucketed-/// tables back out. The merged `Manifest` is the server one with only its tables replaced.-fn merge_manifest_pair(- server: Manifest,- server_buckets: Vec<DataBucket>,- local: Option<Manifest>,- local_buckets: Vec<DataBucket>,- schema_columns: &HashMap<String, Vec<String>>,-) -> CanonicalManifestMerge {+/// Merge one manifest: LWW over the flattened table view of both sides, then split the bucketed tables back out. The+/// merged `Manifest` is the server one with only its tables replaced.+fn merge_manifest_pair(server: Manifest, server_buckets: Vec<DataBucket>, local: Option<Manifest>, local_buckets: Vec<DataBucket>, schema_columns: &HashMap<String, Vec<String>>) -> CanonicalManifestMerge {let manifest_id = server.manifest_id.clone();let mut stats = MergeStats::default();- // A bucket of a category this build does not know cannot be flattened without losing its- // category; the server's ride through as-is and the local ones are dropped with the rest of- // the local carrier, exactly as the base-wins rule treats every unknown table.+ // A bucket of a category this build does not know cannot be flattened without losing its category: the server's+ // ride through as-is and the local ones are dropped, exactly as the base-wins rule treats every unknown table.let server_bucket_extras: HashMap<String, HashMap<String, serde_json::Value>> = server_buckets.iter().map(|bucket| (bucket.category.clone(), bucket.extra.clone())).collect();let (server_bucket_tables, unknown_server_buckets) = split_known_buckets(server_buckets);let (local_bucket_tables, _) = split_known_buckets(local_buckets);@@ -147,7 +133,6 @@ fn merge_manifest_pair(let mut incoming_tables = local.map(|m| m.tables).unwrap_or_default();incoming_tables.extend(local_bucket_tables);- // An item is deleted as a unit including any child rows.item_deletes::resolve_item_deletes(&mut base_tables, &mut incoming_tables);let table_names: BTreeSet<String> = base_tables.keys().chain(incoming_tables.keys()).cloned().collect();@@ -163,23 +148,19 @@ fn merge_manifest_pair(// Not a syncable table (a skip table, or one from a newer writer): the base wins as-is.None => base_rows,};- /*- * A table the base carried stays in the output even when it merged to nothing, so the merged- * manifest keeps the base's shape.- */+ // A table the base carried stays in the output even when it merged to nothing, so the manifest keeps the base's shape.if base_carried_table || !merged_rows.is_empty() {merged.insert(name, merged_rows);}}// A delete that won can leave the other side's children under a tombstoned item, and a union of concurrently- // added multi-value rows can leave two rows at the same ValueIndex: repair and normalize the output like any- // canonicalized manifest.+ // added multi-value rows can leave two rows at the same ValueIndex: repair and normalize like any canonicalized manifest.crate::vault_codec::integrity::repair(&mut merged);crate::vault_codec::normalize::normalize_row_shapes(&mut merged);// One bucket per category: the merged rows of the tables this build buckets, plus the server's tables of that- // category it does not know. A merged bucket keeps the server's extra top-level keys.+ // category it does not know; a merged bucket keeps the server's extra top-level keys.let mut buckets: Vec<DataBucket> = Vec::new();for category in bucket_categories() {let mut bucket_tables: HashMap<String, Vec<CodecRecord>> = HashMap::new();@@ -202,8 +183,8 @@ fn merge_manifest_pair(CanonicalManifestMerge { manifest_id, manifest, buckets, stats }}-/// Split buckets into the flattened rows of the tables this build buckets itself, and leftover-/// buckets holding every other table (a newer writer's), kept under their served category.+/// Split buckets into the flattened rows of the tables this build buckets itself, and leftover buckets holding every+/// other table (a newer writer's), kept under their served category.fn split_known_buckets(buckets: Vec<DataBucket>) -> (HashMap<String, Vec<CodecRecord>>, Vec<DataBucket>) {let mut tables: HashMap<String, Vec<CodecRecord>> = HashMap::new();let mut unknown: Vec<DataBucket> = Vec::new();@@ -223,8 +204,7 @@ fn split_known_buckets(buckets: Vec<DataBucket>) -> (HashMap<String, Vec<CodecRe(tables, unknown)}-/// A contentless server manifest's local counterpart passes through whole: every row is an-/// offline-kept row.+/// A contentless server manifest's local counterpart passes through whole: every row is an incoming-only row.fn pass_through(local: Manifest, local_buckets: Vec<DataBucket>) -> CanonicalManifestMerge {let row_count = |tables: &HashMap<String, Vec<CodecRecord>>| tables.values().map(|rows| rows.len() as u32).sum::<u32>();let stats = MergeStats { incoming_only: row_count(&local.tables) + local_buckets.iter().map(|b| row_count(&b.tables)).sum::<u32>(), ..MergeStats::default() };@@ -232,18 +212,11 @@ fn pass_through(local: Manifest, local_buckets: Vec<DataBucket>) -> CanonicalManCanonicalManifestMerge { manifest_id: local.manifest_id.clone(), manifest: local, buckets: local_buckets, stats }}-/// LWW one table, rows out: base rows in order (replaced where the incoming row is strictly-/// newer), then incoming-only rows in first-occurrence order.-fn merge_rows(- config: &TableConfig,- base_rows: Vec<CodecRecord>,- incoming_rows: Vec<CodecRecord>,- schema_columns: &HashMap<String, Vec<String>>,- stats: &mut MergeStats,-) -> Vec<CodecRecord> {+/// LWW one table, rows out: base rows in order (replaced where the incoming row is strictly newer), then+/// incoming-only rows in first-occurrence order.+fn merge_rows(config: &TableConfig, base_rows: Vec<CodecRecord>, incoming_rows: Vec<CodecRecord>, schema_columns: &HashMap<String, Vec<String>>, stats: &mut MergeStats) -> Vec<CodecRecord> {let identity_columns = config.identity_columns();- // Rows arrive normalized to the wire shape here, so a canonical-only key may rely on stripped- // derived ids (see the FieldValues registry comment).+ // Rows arrive in wire shape, so a canonical key may rely on stripped derived ids.let match_columns: &[&str] = if config.canonical_key_columns.is_empty() { &identity_columns } else { config.canonical_key_columns };let known_columns: Option<HashSet<&str>> = schema_columns.get(config.name).map(|cols| cols.iter().map(String::as_str).collect());@@ -304,10 +277,8 @@ fn overlay_winner(mut winner: CodecRecord, base: &CodecRecord, identity_columns:winner}-/// Stable string key over `columns`. A column the record does not carry contributes an empty part,-/// so a row missing one still matches its counterpart rather than dropping out of the merge; that is-/// why this is not `vault_codec::row_identity`, which skips absent parts. Ids compare-/// case-insensitively (see [`identity_part`]), everything else exactly as spelled.+/// Stable string key over `columns`, ids compared case-insensitively. Unlike `vault_codec::row_identity`, a column the+/// record does not carry contributes an empty part, so a row missing one still matches its counterpart.fn get_key(record: &CodecRecord, columns: &[&str]) -> String {let parts: Vec<String> = columns.iter().map(|column| record.get(*column).filter(|v| !v.is_null()).map(identity_part).unwrap_or_default()).collect();parts.join("\u{1f}")diff --git a/core/rust/src/vault_merge/tests/mod.rs b/core/rust/src/vault_merge/tests/mod.rsindex d0a1a5f24..940f081c1 100644--- a/core/rust/src/vault_merge/tests/mod.rs+++ b/core/rust/src/vault_merge/tests/mod.rs@@ -196,7 +196,7 @@ struct Concurrent {}#[test]-fn concurrent_edits_to_an_item_and_its_children_settle_row_by_row() {+fn concurrent_edits_to_an_item_and_its_children_resolve_row_by_row() {let bank = || trashable("Bank", None, T_OLD);let code = |secret: &str, deleted: bool, updated_at: &str| totp("totp-1", secret, deleted, updated_at);let case = |what: &str, server: (CodecRecord, Vec<CodecRecord>), local: (CodecRecord, Vec<CodecRecord>), item: &str, live_secrets: Vec<&'static str>| Concurrent { what: what.to_string(), server, local, item: item.to_string(), live_secrets };@@ -313,7 +313,7 @@ fn manifests_merge_independently_and_a_lost_one_is_reported() {}/*- * An item is deleted as a unit: a permanent delete only one side made is settled against everything the other+ * An item is deleted as a unit: a permanent delete only one side made is resolved against everything the other* side did to the item (a field edit does not touch the item row), both ways, and the losing side's rows leave.*/@@ -326,7 +326,7 @@ fn live_values(merged: &CanonicalManifestMerge) -> Vec<&str> {}#[test]-fn a_permanent_delete_is_settled_against_the_item_as_a_unit_both_ways() {+fn a_permanent_delete_is_resolved_against_the_item_as_a_unit_both_ways() {let deleting = item_manifest(vec![tombstone("item-1", T_MID)], vec![field("login.username", "user", true, T_MID), field("login.password", "old-secret", true, T_MID)]);for (edit_at, survives) in [(T_NEW, true), (T_OLD, false)] {let editing = item_manifest(vec![item("item-1", "item", T_OLD)], vec![field("login.username", "user", false, T_OLD), field("login.password", "new-secret", false, edit_at)]);diff --git a/core/rust/src/vault_model/mod.rs b/core/rust/src/vault_model/mod.rsindex d8a45f095..7b2fded30 100644--- a/core/rust/src/vault_model/mod.rs+++ b/core/rust/src/vault_model/mod.rs@@ -13,7 +13,7 @@ pub fn id_key(id: &str) -> String {id.trim().to_ascii_lowercase()}-/// True when two ids name the same row.+/// Whether two ids name the same row.pub fn ids_equal(a: &str, b: &str) -> bool {a.trim().eq_ignore_ascii_case(b.trim())}@@ -38,28 +38,25 @@ pub fn system_field(key: &str) -> Option<&'static SystemField> {#[derive(Debug, Clone)]pub struct BlobColumn {pub table: &'static str,- /// The column holding the bytes locally, and the `{ __blobRef }` marker in a manifest.+ /// The column holding the bytes locally and the blob reference in a manifest.pub column: &'static str,- /// The local bookkeeping column holding the blob's hash, so a row whose bytes are not loaded still knows its blob.+ /// The local column holding the blob's hash, so a row whose bytes are not loaded still knows its blob.pub hash_column: &'static str,- /// The label reported to the server on upload (metrics / retention).+ /// The label reported to the server on upload.pub kind: &'static str,}-/// Configuration for a syncable table.+/// A syncable table.#[derive(Debug, Clone)]pub struct TableConfig {- /// Table name in the databasepub name: &'static str,- /// Merge match columns, applied after both sides are normalized to the manifest shape (see- /// `vault_codec::normalize`). Empty means rows match on [`identity_columns`](TableConfig::identity_columns).+ /// Merge match columns in the manifest shape; empty means rows match on their identity columns.pub canonical_key_columns: &'static [&'static str],- /// The columns that name a row within its manifest. Defaults to `["Id"]`; tables keyed- /// differently (Settings by "Key", ItemTags by its natural key) override this.+ /// The columns that name a row within its manifest, `["Id"]` unless overridden.pub primary_key_columns: &'static [&'static str],- /// True when the table's rows are namespaced per manifest.+ /// Whether rows are namespaced per manifest.pub manifest_scoped: bool,- /// True when the table's rows hang off an Item row (re-stamped with their item, cascaded on delete).+ /// Whether rows are child rows of an Item row (re-stamped with it, cascaded on delete).pub item_child: bool,}@@ -94,13 +91,12 @@ impl TableConfig {self}- /// The column of an item-child table that carries the owning item's id: `Id` for ItemStats (its `Id` is the item's id), `ItemId` everywhere else.+ /// The column of an item-child table that carries the owning item's id: `Id` for ItemStats, `ItemId` elsewhere.pub fn item_ref_column(&self) -> &'static str {if self.name == names::ITEM_STATS_TABLE { names::ID_COL } else { names::ITEM_ID_COL }}- /// The columns that together identify one row of this table: `(ManifestId, primary key columns)`- /// for a manifest-scoped table, the primary key columns alone otherwise.+ /// The columns that identify one row: the primary key columns, behind `ManifestId` for a manifest-scoped table.pub fn identity_columns(&self) -> Vec<&'static str> {if self.manifest_scoped {let mut columns = Vec::with_capacity(1 + self.primary_key_columns.len());diff --git a/core/rust/src/vault_pruner/mod.rs b/core/rust/src/vault_pruner/mod.rsindex 411feb488..88af85bee 100644--- a/core/rust/src/vault_pruner/mod.rs+++ b/core/rust/src/vault_pruner/mod.rs@@ -1,39 +1,37 @@-//! Vault pruner: SQL statements that permanently delete (IsDeleted = true) items that have been in the trash longer-//! than the retention period, along with their related entities.+//! SQL statements that tombstone items whose trash retention has expired, with their child rows, orphan favicons and+//! the blob bytes of tombstoned rows.use chrono::{DateTime, Duration, Utc};use std::collections::{HashMap, HashSet};use crate::common::error::{VaultError, VaultResult};+use crate::common::timestamp::{iso_utc, parse_vault_datetime};use crate::sqlite_host::SqlStatement;use crate::vault_codec::row::{has_bytes, is_deleted, logo_kind, str_col};-use crate::vault_codec::blob_spec_for;-use crate::vault_codec::{CodecRecord, CodecTableData};+use crate::vault_codec::{blob_spec_for, CodecRecord, CodecTableData};use crate::vault_model::names::{DELETED_AT_COL, FILE_DATA_COL, ID_COL, IS_DELETED_COL, ITEMS_TABLE, KIND_COL, LOGOS_TABLE,LOGO_ID_COL, LOGO_KIND_FAVICON, UPDATED_AT_COL,};-use crate::vault_model::{id_key, ids_equal, BLOB_COLUMNS, MANIFEST_ID_COL, SYNCABLE_TABLES};+use crate::vault_model::{id_key, ids_equal, TableConfig, BLOB_COLUMNS, MANIFEST_ID_COL, SYNCABLE_TABLES};/// Input for the prune operation.#[derive(Debug, Clone)]pub struct PruneInput {- /// Tables from the local database (at minimum, Items table is required)+ /// The tables read with [`get_prune_table_queries`]; without `Items` nothing is pruned.pub tables: Vec<CodecTableData>,- /// Current time in ISO 8601 UTC format: `YYYY-MM-DDTHH:MM:SS.sssZ`.+ /// ISO 8601 UTC.pub current_time: String,- /// Retention period in days.pub retention_days: u32,}-/// Statistics about what was pruned.+/// Counts of what was pruned.#[derive(Debug, Clone, Default)]pub struct PruneStats {- /// Number of items permanently deletedpub items_pruned: u32,/// Rows tombstoned per item-child table, keyed by table name.pub child_rows_pruned: HashMap<String, u32>,- /// Number of orphan logos soft-deleted (no remaining active item references them)+ /// Orphan favicons tombstoned.pub logos_pruned: u32,/// Tombstoned rows whose blob bytes were cleared, keyed by table name.pub blobs_cleared: HashMap<String, u32>,@@ -42,33 +40,24 @@ pub struct PruneStats {/// Output of the prune operation.#[derive(Debug, Clone)]pub struct PruneOutput {- /// SQL statements to execute on the local database (in order)pub statements: Vec<SqlStatement>,- /// Statistics about what was prunedpub stats: PruneStats,}/// A per-table SELECT query for building `PruneInput`.#[derive(Debug, Clone)]pub struct PruneTableQuery {- /// Table namepub name: String,- /// SELECT query reading only the columns the pruner inspectspub query: String,}-/// Get the per-table SELECT queries clients should run to build `PruneInput`.-///-/// Only the columns the pruner inspects are selected; blob columns are reduced-/// to a 1-byte presence marker (via `substr`) to avoid serializing large binary-/// data to JSON on every prune.+/// The per-table SELECT queries a client runs to build `PruneInput`.pub fn get_prune_table_queries() -> Vec<PruneTableQuery> {+ // Blob columns are read as a 1-byte presence marker so a prune never serializes whole blobs.let mut queries = vec![PruneTableQuery {name: ITEMS_TABLE.to_string(),query: format!("SELECT {}, {}, {}, {}, {} FROM {}", MANIFEST_ID_COL, ID_COL, IS_DELETED_COL, DELETED_AT_COL, LOGO_ID_COL, ITEMS_TABLE),}];- // One query per registered item-child table (TableConfig::item_child), so a table added to the- // registry is read by the pruner automatically.for child in item_child_tables() {let query = match blob_column_for(child.name) {Some(blob_col) => format!("SELECT {}, {}, {}, {}, substr({}, 1, 1) AS {} FROM {}", MANIFEST_ID_COL, ID_COL, child.item_ref_column(), IS_DELETED_COL, blob_col, blob_col, child.name),@@ -83,8 +72,8 @@ pub fn get_prune_table_queries() -> Vec<PruneTableQuery> {queries}-/// The registered item-child tables (TableConfig::item_child), in registry order.-fn item_child_tables() -> impl Iterator<Item = &'static crate::vault_model::TableConfig> {+/// The registered item-child tables, in registry order.+fn item_child_tables() -> impl Iterator<Item = &'static TableConfig> {SYNCABLE_TABLES.iter().filter(|t| t.item_child)}@@ -93,7 +82,7 @@ fn blob_column_for(table_name: &str) -> Option<&'static str> {blob_spec_for(table_name).map(|spec| spec.column)}-/// The `, <blob> = NULL` SET fragment that drops a table's blob bytes, empty for a table without one.+/// The `, <blob> = NULL` SET fragment of a table, empty for a table without a blob column.fn blob_clear_fragment(table_name: &str) -> String {blob_column_for(table_name).map(|col| format!(", {} = NULL", col)).unwrap_or_default()}@@ -108,21 +97,16 @@ fn manifest_of(record: &CodecRecord) -> &str {str_col(record, MANIFEST_ID_COL).unwrap_or("")}-/// Main entry point: prune expired items from trash.-///-/// Finds all Items with DeletedAt older than `retention_days` and generates SQL statements that mark-/// them and their related entities as permanently deleted (IsDeleted = true), then reclaims orphan-/// favicons and the blob bytes of tombstoned rows.+/// Tombstone the items trashed before the retention cutoff with their child rows, then reclaim orphan favicons and+/// the blob bytes of tombstoned rows.pub fn prune_vault(input: PruneInput) -> VaultResult<PruneOutput> {let mut stats = PruneStats::default();let mut statements: Vec<SqlStatement> = Vec::new();- let now = crate::common::timestamp::parse_vault_datetime(&input.current_time)- .ok_or_else(|| VaultError::General(format!("Invalid current_time format: {}", input.current_time)))?;- let now_str = crate::common::timestamp::iso_utc(&now);+ let now = parse_vault_datetime(&input.current_time).ok_or_else(|| VaultError::General(format!("Invalid current_time format: {}", input.current_time)))?;+ let now_str = iso_utc(&now);let cutoff_date = now - Duration::days(input.retention_days as i64);- // Items table is required for both the trash purge and the logo orphan check.let Some(items) = records_of(&input.tables, ITEMS_TABLE) else {return Ok(PruneOutput { statements, stats });};@@ -143,12 +127,12 @@ pub fn prune_vault(input: PruneInput) -> VaultResult<PruneOutput> {Ok(PruneOutput { statements, stats })}-/// Pass 1: the `(ManifestId, Id)` of live items whose trash date (`DeletedAt`) lies before the cutoff.+/// The `(ManifestId, Id)` of live items whose `DeletedAt` lies before the cutoff.fn expired_item_ids(items: &[CodecRecord], cutoff_date: DateTime<Utc>) -> Vec<(String, String)> {let mut expired = Vec::new();for item in items.iter().filter(|item| !is_deleted(item)) {let Some(deleted_at) = str_col(item, DELETED_AT_COL) else { continue };- let Some(deleted_date) = crate::common::timestamp::parse_vault_datetime(deleted_at) else { continue };+ let Some(deleted_date) = parse_vault_datetime(deleted_at) else { continue };if deleted_date < cutoff_date {if let Some(id) = str_col(item, ID_COL) {expired.push((manifest_of(item).to_string(), id.to_string()));@@ -158,7 +142,7 @@ fn expired_item_ids(items: &[CodecRecord], cutoff_date: DateTime<Utc>) -> Vec<(Sexpired}-/// Pass 1 cascade: tombstone one purged item's rows in every item-child table, dropping blob bytes in the same statement.+/// Tombstone one purged item's rows in every item-child table, dropping blob bytes in the same statement.fn tombstone_item_children(tables: &[CodecTableData], manifest_id: &str, item_id: &str, now_str: &str, statements: &mut Vec<SqlStatement>, stats: &mut PruneStats) {for child in item_child_tables() {let Some(records) = records_of(tables, child.name) else { continue };@@ -179,15 +163,8 @@ fn tombstone_item_children(tables: &[CodecTableData], manifest_id: &str, item_id}}-/// Pass 2: tombstone favicons no live (and not just purged) item references; built-in and uploaded logos are the user's choice and stay.-fn sweep_orphan_favicons(- tables: &[CodecTableData],- items: &[CodecRecord],- expired: &[(String, String)],- now_str: &str,- statements: &mut Vec<SqlStatement>,- stats: &mut PruneStats,-) {+/// Tombstone favicons no live (and not just purged) item references; built-in and uploaded logos are the user's choice and stay.+fn sweep_orphan_favicons(tables: &[CodecTableData], items: &[CodecRecord], expired: &[(String, String)], now_str: &str, statements: &mut Vec<SqlStatement>, stats: &mut PruneStats) {let Some(logos) = records_of(tables, LOGOS_TABLE) else { return };let blob_clear = blob_clear_fragment(LOGOS_TABLE);let expired_set: HashSet<(String, String)> = expired.iter().map(|(manifest_id, id)| (id_key(manifest_id), id_key(id))).collect();@@ -214,7 +191,7 @@ fn sweep_orphan_favicons(}}-/// Pass 3: clear the blob bytes of tombstoned rows that still carry them.+/// Clear the blob bytes of tombstoned rows that still carry them.fn clear_tombstoned_blobs(tables: &[CodecTableData], now_str: &str, statements: &mut Vec<SqlStatement>, stats: &mut PruneStats) {for spec in BLOB_COLUMNS {let (table, blob_col) = (spec.table, spec.column);diff --git a/core/rust/src/vault_pruner/tests/mod.rs b/core/rust/src/vault_pruner/tests/mod.rsindex c3e5d915b..e2ae2f1fd 100644--- a/core/rust/src/vault_pruner/tests/mod.rs+++ b/core/rust/src/vault_pruner/tests/mod.rs@@ -1,4 +1,4 @@-//! The pruner: expired trash is tombstoned with everything hanging off it, orphan favicons and the bytes of+//! The pruner: expired trash items are tombstoned with their child rows, orphan favicons and the bytes of//! tombstoned blob rows are reclaimed, and every statement names the manifest it addresses.use super::*;@@ -11,7 +11,7 @@ fn item(id: &str, trashed_days_ago: Option<i64>, deleted: bool, logo_id: Option<row(&[("ManifestId", json!(M)), ("Id", json!(id)), ("UpdatedAt", json!("2024-01-01T00:00:00Z")), ("IsDeleted", json!(deleted as i32)), ("DeletedAt", trashed_days_ago.map(days_ago_iso).map(Value::String).unwrap_or(Value::Null)), ("LogoId", logo_id.map(|l| json!(l)).unwrap_or(Value::Null))])}-/// A row hanging off `item_id` in manifest `M`, with a `Blob` cell when given.+/// A child row of `item_id` in manifest `M`, with a `Blob` cell when given.fn child(id: &str, item_id: &str, deleted: bool, blob: Option<Value>) -> CodecRecord {let mut r = row(&[("ManifestId", json!(M)), ("Id", json!(id)), ("ItemId", json!(item_id)), ("IsDeleted", json!(deleted as i32))]);if let Some(blob) = blob {diff --git a/core/rust/src/vault_sync/blob_keys.rs b/core/rust/src/vault_sync/blob_keys.rsindex 88427ef83..51906ce7c 100644--- a/core/rust/src/vault_sync/blob_keys.rs+++ b/core/rust/src/vault_sync/blob_keys.rs@@ -2,23 +2,23 @@use serde::{Deserialize, Serialize};-use crate::crypto::{self, aad};use crate::common::encoding::{base64_decode, base64_encode};use crate::common::error::{VaultError, VaultResult};+use crate::crypto::{self, aad};use crate::vault_codec;/// A blob as the server stores it.#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub(crate) struct EncryptedBlob {- /// The bytes, encrypted with the blob key. Persisted as base64 under the old field name, so existing caches still read.+ /// The bytes, encrypted with the blob key; cached as base64 under `encryptedDataBase64`, the name existing caches use.#[serde(rename = "encryptedDataBase64", with = "base64_bytes")]pub encrypted_data: Vec<u8>,/// The blob key, encrypted with the manifest's VEK.pub encrypted_blob_key: String,}-/// Encrypt blob bytes with a fresh blob key, and that key with the manifest's VEK, both bound to the blob's address.+/// Encrypt blob bytes with a new blob key, and that key with the manifest's VEK, both bound to the blob's address.pub(crate) fn encrypt_blob(bytes: &[u8], vek: &str, manifest_id: &str, hash: &str) -> VaultResult<EncryptedBlob> {let blob_key = crypto::aes_gcm::generate_key();Ok(EncryptedBlob {diff --git a/core/rust/src/vault_sync/db.rs b/core/rust/src/vault_sync/db.rsindex 12c360dff..9ad9ea3b3 100644--- a/core/rust/src/vault_sync/db.rs+++ b/core/rust/src/vault_sync/db.rs@@ -5,12 +5,12 @@ use std::collections::HashMap;use serde_json::{json, Map, Value};use super::errors::{SyncError, SyncResult};+use super::legacy;use super::session::Host;use super::types::{Ack, Command, Db, DbRows, LogLevel};-use super::legacy;use crate::common::encoding::uuid_from_bytes;-use crate::sqlite_host::{MemoryDatabase, SqlStatement};use crate::common::timestamp::{now_iso_utc, now_vault_datetime};+use crate::sqlite_host::{MemoryDatabase, SqlStatement};use crate::vault_codec::row::{blob_ref_of, inline_bytes};use crate::vault_codec::{is_skip_table, manifest_scoped_tables, CodecRecord, CodecTableData, MaterializedTables};use crate::vault_model::{id_key, ids_equal, MANIFEST_ID_COL, UNSTAMPED_MANIFEST_ID};@@ -129,12 +129,13 @@ pub(crate) enum SchemaState {Current,}-/// Classify the local vault's schema against the current one (whose stamp the staging database carries).+/// Where the local vault's schema stands against `current_migration_id`.pub(crate) async fn schema_state(host: &Host, current_migration_id: &str) -> SyncResult<SchemaState> {let local = latest_migration_id(host, Db::Local).await?;if local.is_empty() {return Err(SyncError::Other("No migrations found in the database.".to_string()));}+ // LEGACY: a pre-2.0.0 stamp still walks the frozen sqlite-blob chain. TODO: remove with `legacy.rs`.if legacy::stamp_predates_manifest_schema(&local)? {return Ok(SchemaState::LegacyChain);}@@ -169,8 +170,7 @@ pub(crate) async fn manifest_ids_in_vault(host: &Host, db: Db) -> SyncResult<VecOk(ids)}-/// Load materialized tables into the (fresh) staging database, re-embedding blob bytes, and verify its-/// referential integrity.+/// Load materialized tables into the fresh staging database, re-embedding blob bytes, and check its foreign keys.pub(crate) async fn insert_materialized(host: &Host, materialized: &MaterializedTables, schema_columns: &HashMap<String, Vec<String>>, blobs: &HashMap<String, Vec<u8>>) -> SyncResult<()> {for table in &materialized.tables {if table.records.is_empty() {@@ -248,24 +248,20 @@ const PRIMARY_KEY_IDS_FOR_MANIFEST: &str = "SELECT Id FROM EncryptionKeys WHEREconst DELETE_KEY: &str = "DELETE FROM EncryptionKeys WHERE Id = ?";const PROMOTE_KEY: &str = "UPDATE EncryptionKeys SET IsPrimary = 1 WHERE Id = ?";-/// [`set_active_key_for_manifest`], remembering what it changed so [`undo_active_key_change`] can put it back.+/// Make a keypair the manifest's active one, remembering what changed so it can be undone.pub(crate) async fn rotate_active_key_for_manifest(host: &Host, manifest_id: &str, public_key: &str, private_key: &str) -> SyncResult<DeliveryKeyChange> {let previous_primary_ids = query(host, Db::Local, PRIMARY_KEY_IDS_FOR_MANIFEST, vec![json!(manifest_id)]).await?.iter().filter_map(|row| row.get("Id").and_then(Value::as_str)).map(str::to_string).collect();let new_key_id = new_id();let now = now_vault_datetime();- exec(- host,- Db::Local,- vec![- SqlStatement { sql: DEMOTE_KEYS_FOR_MANIFEST.to_string(), params: vec![json!(now), json!(manifest_id)] },- SqlStatement { sql: INSERT_KEY_FOR_MANIFEST.to_string(), params: vec![json!(new_key_id), json!(manifest_id), json!(public_key), json!(private_key), json!(now), json!(now)] },- ],- )- .await?;+ let statements = vec![+ SqlStatement { sql: DEMOTE_KEYS_FOR_MANIFEST.to_string(), params: vec![json!(now), json!(manifest_id)] },+ SqlStatement { sql: INSERT_KEY_FOR_MANIFEST.to_string(), params: vec![json!(new_key_id), json!(manifest_id), json!(public_key), json!(private_key), json!(now), json!(now)] },+ ];+ exec(host, Db::Local, statements).await?;Ok(DeliveryKeyChange { new_key_id, previous_primary_ids })}-/// Put the delivery keypair back the way it was before [`rotate_active_key_for_manifest`].+/// Undo a delivery keypair change.pub(crate) async fn undo_active_key_change(host: &Host, change: &DeliveryKeyChange) -> SyncResult<()> {let mut statements = vec![SqlStatement { sql: DELETE_KEY.to_string(), params: vec![json!(change.new_key_id)] }];statements.extend(change.previous_primary_ids.iter().map(|id| SqlStatement { sql: PROMOTE_KEY.to_string(), params: vec![json!(id)] }));@@ -275,20 +271,16 @@ pub(crate) async fn undo_active_key_change(host: &Host, change: &DeliveryKeyChan/// Make a keypair the manifest's active one, demoting (never deleting) whatever it supersedes.pub(crate) async fn set_active_key_for_manifest(host: &Host, manifest_id: &str, public_key: &str, private_key: &str) -> SyncResult<()> {let now = now_vault_datetime();- exec(- host,- Db::Local,- vec![- SqlStatement { sql: DEMOTE_KEYS_FOR_MANIFEST.to_string(), params: vec![json!(now), json!(manifest_id)] },- SqlStatement { sql: INSERT_KEY_FOR_MANIFEST.to_string(), params: vec![json!(new_id()), json!(manifest_id), json!(public_key), json!(private_key), json!(now), json!(now)] },- ],- )- .await+ let statements = vec![+ SqlStatement { sql: DEMOTE_KEYS_FOR_MANIFEST.to_string(), params: vec![json!(now), json!(manifest_id)] },+ SqlStatement { sql: INSERT_KEY_FOR_MANIFEST.to_string(), params: vec![json!(new_id()), json!(manifest_id), json!(public_key), json!(private_key), json!(now), json!(now)] },+ ];+ exec(host, Db::Local, statements).await}/// What each manifest is called, keyed by lower-cased id.pub(crate) async fn manifest_display_names(host: &Host) -> SyncResult<HashMap<String, String>> {- // A vault whose schema predates the table names none.+ // A vault whose schema predates the Manifests table names none.if !has_column(host, Db::Local, "Manifests", "Name").await? {return Ok(HashMap::new());}diff --git a/core/rust/src/vault_sync/email_routing.rs b/core/rust/src/vault_sync/email_routing.rsindex c9849db56..0e315021a 100644--- a/core/rust/src/vault_sync/email_routing.rs+++ b/core/rust/src/vault_sync/email_routing.rs@@ -4,8 +4,8 @@ use std::collections::{HashMap, HashSet};use serde_json::Value;-use super::types::{ClaimedEmailAddress, EmailRoutingPush, ManifestRevision};use super::db::value_string;+use super::types::{ClaimedEmailAddress, EmailRoutingPush, ManifestRevision};use crate::vault_codec::row::{is_deleted, rows_of, str_col, truthy};use crate::vault_codec::Manifest;use crate::vault_model::names::{DELETED_AT_COL, FIELD_KEY_COL, FIELD_VALUES_TABLE, ID_COL, ITEMS_TABLE, ITEM_ID_COL};diff --git a/core/rust/src/vault_sync/engine.rs b/core/rust/src/vault_sync/engine.rsindex 0756efab7..527f40ccd 100644--- a/core/rust/src/vault_sync/engine.rs+++ b/core/rust/src/vault_sync/engine.rs@@ -15,8 +15,7 @@ use super::types::{FailureFields, FullSyncResult, LogLevel, ResolveVaultKeyResuluse super::{db, http, keys, migration, rotation, sharing};use crate::vault_model::id_key;-/// How many times a chain of syncs may re-sync after an outdated push before giving up. Two clients pushing at the-/// same time race on the server's revision gate; the loser pulls, merges and pushes again, up to this many times.+/// How many times a sync may pull, merge and push again after an outdated push before giving up.const MAX_OUTDATED_RESYNCS: u32 = 3;/// Run one operation to completion; the value is the `done` command's result.@@ -40,7 +39,7 @@ pub(crate) async fn run(host: Host, request: SyncRequest) -> Value {finish(&ctx, result.unwrap_or(Value::Null))}-/// Attach the sync outcome (what every operation reports on top of its own) onto a serialized result.+/// Add `vaultChanged` to a serialized result.fn finish(ctx: &Ctx, mut result: Value) -> Value {if let Some(object) = result.as_object_mut() {object.insert("vaultChanged".to_string(), Value::Bool(ctx.vault_changed));@@ -74,14 +73,11 @@ fn logout(reason: LogoutReason) -> FullSyncResult {FullSyncResult { failure: FailureFields::logout(reason), ..Default::default() }}-/// Turn an error thrown during a sync into the outcome the host acts on. A transport failure with a local vault-/// to fall back on is not a failure but puts the host in offline mode instead.+/// The outcome of an error thrown during a sync: offline mode when the server is unreachable and a local vault exists.async fn map_sync_failure(ctx: &mut Ctx, error: SyncError) -> FullSyncResult {ctx.warn(format!("[Sync] Sync failed: {}", error)).await;- if let SyncError::Network(_) = &error {- if let Ok(true) = ctx.has_local_vault().await {- return offline();- }+ if matches!(error, SyncError::Network(_)) && ctx.has_local_vault().await.is_ok_and(|has_vault| has_vault) {+ return offline();}failure(&error)}@@ -105,7 +101,6 @@ pub(crate) async fn full_sync(ctx: &mut Ctx) -> SyncResult<FullSyncResult> {if dropped_local_vault || !matches!(error, SyncError::VaultDecryptFailed(_)) {return Err(error);}- // A stored vault that does not decrypt is useless to every reader, so it is dropped and the server's vault pulled over it, once.ctx.warn(format!("[Sync] The stored vault does not decrypt with the session key; dropping it and pulling the server's vault. {}", error)).await;dropped_local_vault = true;ctx.discard_local_vault();@@ -144,7 +139,7 @@ async fn full_sync_once(ctx: &mut Ctx) -> SyncResult<Flow> {let mut needs_pull = ctx.request.force_pull || server_state_needs_pull(ctx, &status).await?;ctx.log(format!("[Sync] Status received (needsPull {}, isDirty {})", needs_pull, ctx.is_dirty)).await;- // A hierarchy another device created since this legacy login shows up as a revision change, so it is checked here.+ // A key hierarchy another device created shows up as a revision change, so it is checked here.if needs_pull || ctx.is_dirty {keys::ensure_key_chain_accepted(ctx).await?;}@@ -152,8 +147,7 @@ async fn full_sync_once(ctx: &mut Ctx) -> SyncResult<Flow> {let server_directed_changes = refresh_manifest_names(ctx, &status, needs_pull).await?;- // A dirty vault on the current schema: drop the dirty flag when nothing changed, and pull first when it holds- // rows this session cannot write (a share that was revoked), since a push would refuse them.+ // A dirty vault: drop the dirty flag when nothing changed, and pull first when it holds rows this session cannot write.let mut canonicalize_cache = None;if !needs_pull && ctx.is_dirty && !migration::vault_predates_current_schema(ctx).await? {canonicalize_cache = clear_no_op_mutation(ctx).await;@@ -166,13 +160,11 @@ async fn full_sync_once(ctx: &mut Ctx) -> SyncResult<Flow> {let flow = if needs_pull {pull_and_materialize_server_vault(ctx, server_directed_changes).await?} else if ctx.is_dirty && !migration::vault_predates_current_schema(ctx).await? {- // Server and client agree on every revision, so the pending local changes upload as-is.match push_local_changes(ctx, canonicalize_cache, WriteKind::Changes { buckets_only: true }).await? {Some(vault_changed) => Flow::Done(FullSyncResult { success: true, has_new_vault: vault_changed || server_directed_changes, ..Default::default() }),None => Flow::Resync { outdated: true },}} else {- // A vault the codec cannot canonicalize has no way to the server; the upgrade gate takes it from here.Flow::Done(migration::pending_migration_result(ctx).await?.unwrap_or_else(success))};@@ -189,8 +181,7 @@ async fn full_sync_once(ctx: &mut Ctx) -> SyncResult<Flow> {})}-/// The checks before the sync touches the vault: a usable session, a reachable server at a compatible version, and-/// an unchanged password. `Err` carries the final outcome of a sync that stops here.+/// The checks before the sync touches the vault; `Err` carries the outcome of a sync that stops here.async fn check_session(ctx: &mut Ctx) -> SyncResult<Result<StatusResponse, FullSyncResult>> {if ctx.request.username.is_empty() {return Ok(Err(failure(&SyncError::Other("no username in the sync request".to_string()))));@@ -205,12 +196,11 @@ async fn check_session(ctx: &mut Ctx) -> SyncResult<Result<StatusResponse, FullSif let Some(reason) = version_logout_reason(ctx, &status) {return Ok(Err(logout(reason)));}- // A changed server salt means the password was changed elsewhere, which warrants a logout.assert_salt_unchanged(ctx, status.srp_salt.as_deref()).await?;Ok(Ok(status))}-/// Tell the host what the sync is about to do, so it can show a pull or push indicator.+/// Tell the host which phase the sync enters.async fn announce_phase(ctx: &Ctx, needs_pull: bool, is_dirty: bool) {if needs_pull {ctx.host.log(LogLevel::Phase, "pull").await;@@ -219,8 +209,7 @@ async fn announce_phase(ctx: &Ctx, needs_pull: bool, is_dirty: bool) {}}-/// Clear the dirty flag of a vault whose content equals the last known server state. Returns the canonicalize result-/// when the vault did change, so the push right after does not canonicalize again.+/// Clear the dirty flag of a vault that equals the last known server state, else return the canonicalize result for the push.async fn clear_no_op_mutation(ctx: &mut Ctx) -> Option<(u64, CanonicalizedSet)> {match push::detect_no_op_mutation(ctx).await {Ok((true, _)) => {@@ -246,8 +235,7 @@ fn version_logout_reason(ctx: &Ctx, status: &StatusResponse) -> Option<LogoutReaserver_too_old.then_some(LogoutReason::ServerVersionNotSupported)}-/// Whether `version1 >= version2` under the client's SemVer rules: a pre-release sorts below its release, and-/// two pre-releases compare lexically.+/// Whether `version1 >= version2`, a pre-release sorting below its release.pub(super) fn version_gte(version1: &str, version2: &str) -> bool {let (core1, pre1) = split_version(version1);let (core2, pre2) = split_version(version2);@@ -270,7 +258,7 @@ pub(super) fn version_gte(version1: &str, version2: &str) -> bool {}}-/// A version's `core` and optional pre-release tag (`0.12.0-dev`).+/// A version's core and optional pre-release tag.fn split_version(version: &str) -> (&str, Option<&str>) {match version.split_once('-') {Some((core, pre)) if !pre.is_empty() => (core, Some(pre)),@@ -279,7 +267,7 @@ fn split_version(version: &str) -> (&str, Option<&str>) {}}-/// Whether the client has to pull and re-materialize: any manifest or data bucket changed on the server.+/// Whether any manifest or data bucket changed on the server.pub(crate) async fn server_state_needs_pull(ctx: &Ctx, status: &StatusResponse) -> SyncResult<bool> {let server_manifests: HashMap<String, i64> = status.manifest_revisions.iter().map(|m| (m.manifest_id.clone(), m.revision)).collect();let server_buckets: HashMap<String, i64> = status.bucket_revisions.iter().map(|b| (state::bucket_revision_key(&b.manifest_id, &b.category), b.revision)).collect();@@ -301,6 +289,7 @@ fn requiring_pull(server: &HashMap<String, i64>, local: &HashMap<String, i64>) -server.iter().filter(|(id, revision)| local.get(*id) != Some(revision)).count() + local.keys().filter(|id| !server.contains_key(*id)).count()}+/// Fail with `PasswordChangedElsewhere` when the server's salt differs from the one this device derived its keys from.pub(crate) async fn assert_salt_unchanged(ctx: &Ctx, server_salt: Option<&str>) -> SyncResult<()> {let stored: Option<Value> = state::get(&ctx.host, state::UNLOCK_KEY_DERIVATION_PARAMS).await?;let stored_salt = stored.as_ref().and_then(|params| params.get("salt")).and_then(Value::as_str).map(str::to_string);@@ -358,8 +347,7 @@ async fn materialized_vault_result(ctx: &mut Ctx, pulled: &PulledVault) -> SyncROk(FullSyncResult { success: true, has_new_vault: true, sqlite_blob_upgrade_required: legacy_chain, manifest_migration_required: migration_required, pulled_revision: Some(pulled.personal_revision), ..Default::default() })}-/// Store a pulled vault, then commit its revisions; a refused store (a mutation raced the pull) returns a resync.-/// A never-written new vault is stored dirty, so a push that does not land now is retried by the next sync.+/// Store a pulled vault and commit its revisions; a store refused by a raced mutation returns a resync.async fn commit_pulled_vault(ctx: &mut Ctx, pulled: &PulledVault) -> SyncResult<Option<Flow>> {let stored = ctx.store_vault(&pulled.encrypted_vault, pulled.needs_first_write, Some(ctx.mutation_sequence), Some(pulled.personal_revision)).await?;if !stored.success {@@ -398,7 +386,6 @@ async fn pull_and_materialize_server_vault(ctx: &mut Ctx, server_directed_changelet pulled = pull::pull(ctx).await?;return store_server_vault(ctx, &pulled).await;}- // A dirty vault the codec cannot canonicalize is not merged.if migration::vault_predates_current_schema(ctx).await? {ctx.warn("[Sync] The local vault predates the current storage model, so its pending changes can be neither merged nor uploaded; taking the server's vault.").await;let pulled = pull::pull(ctx).await?;@@ -440,7 +427,7 @@ async fn push_local_changes(ctx: &mut Ctx, cache: Option<(u64, CanonicalizedSet)}}-/// The login-time key resolution; see `keys::resolve_vault_key`.+/// The login-time key resolution.async fn resolve_vault_key(ctx: &mut Ctx) -> ResolveVaultKeyResult {match keys::resolve_vault_key(ctx).await {Ok(has_vault_key) => ResolveVaultKeyResult { success: true, has_vault_key, encryption_key: ctx.encryption_key.clone(), ..Default::default() },diff --git a/core/rust/src/vault_sync/errors.rs b/core/rust/src/vault_sync/errors.rsindex 260943fe4..d12b06081 100644--- a/core/rust/src/vault_sync/errors.rs+++ b/core/rust/src/vault_sync/errors.rs@@ -1,14 +1,12 @@-//! Sync related error definitions.+//! The engine's errors and the codes the host reports them as.use serde::{Deserialize, Serialize};use crate::common::error::VaultError;-/// Client error codes, shared with the client apps (`AppErrorCodes` in the client core).+/// The client error codes the engine reports.#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]pub enum ErrorCode {- #[serde(rename = "E-001")]- UnknownError,/// No encryption key in the session.#[serde(rename = "E-202")]VaultLocked,@@ -48,17 +46,15 @@ pub enum ErrorCode {/// The engine hit a state it has no rule for; the message says which.#[serde(rename = "E-509")]SyncEngineFailed,- /// The host failed a read command (state, database, at-rest blob).+ /// The host failed a read command.#[serde(rename = "E-601")]StorageReadFailed,- /// The host failed a write command (state, database, at-rest blob, dirty flag).+ /// The host failed a write command.#[serde(rename = "E-602")]StorageWriteFailed,/// The engine's staging database failed.#[serde(rename = "E-603")]DatabaseInitFailed,- #[serde(rename = "E-701")]- MergeFailed,/// The server kept refusing the write as outdated after the re-sync limit.#[serde(rename = "E-702")]MergeConflict,@@ -69,14 +65,14 @@ pub enum ErrorCode {UploadTooLarge,#[serde(rename = "E-805")]UploadTimeout,- /// LEGACY: a migration cannot run yet (the vault is not on the latest pre-manifest-v1 schema).+ /// LEGACY: the vault is not on the latest pre-manifest-v1 schema, so the migration cannot run yet.#[serde(rename = "E-901")]MigrationCheckFailed,#[serde(rename = "E-903")]ServerUpdateRequired,}-/// Why the sync has to end and host needs to logout user session.+/// Why the host has to log the user out.#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub enum LogoutReason {@@ -96,13 +92,13 @@ pub enum Failure {#[derive(Debug, thiserror::Error)]pub enum SyncError {- /// The server could not be reached (transport failure).+ /// The server could not be reached.#[error("Network error: {0}")]Network(String),/// A request exceeded its timeout.#[error("Request timed out: {0}")]Timeout(String),- /// The session is no longer valid (401/403 after the host's token refresh).+ /// The session is no longer valid.#[error("Session expired")]Auth,/// The server refuses this client version (HTTP 426).@@ -165,7 +161,7 @@ pub enum SyncError {/// The engine's in-process staging database failed.#[error("Staging database failed: {0}")]Staging(String),- /// The host reported a failure for a command (named by its wire tag, `dbExec`).+ /// The host reported a failure for a command.#[error("Host command {command} failed: {message}")]Host { command: &'static str, message: String },#[error("JSON error: {0}")]@@ -181,7 +177,7 @@ pub enum SyncError {impl From<crate::crypto::KeyChainError> for SyncError {fn from(error: crate::crypto::KeyChainError) -> Self {match error {- // The engine opens chains with the unlock key only; either rejection is the same E-206 "wrong key" to the host.+ // Either rejection is a wrong key to the host.crate::crypto::KeyChainError::UnlockKeyRejected | crate::crypto::KeyChainError::AccountKeyRejected => SyncError::UnlockKeyRejected,crate::crypto::KeyChainError::KeyChainUnreadable(message) => SyncError::KeyChainUnreadable(message),}@@ -232,7 +228,7 @@ impl SyncError {}}-/// The client error code a host failure of the named command maps to; the error detail names the command.+/// The error code a failed host command maps to.fn storage_error_code(command: &str) -> ErrorCode {match command {"stateGet" | "dbQuery" | "dbExport" | "vaultLoad" => ErrorCode::StorageReadFailed,diff --git a/core/rust/src/vault_sync/frame.rs b/core/rust/src/vault_sync/frame.rsindex d342ced65..f1c31974f 100644--- a/core/rust/src/vault_sync/frame.rs+++ b/core/rust/src/vault_sync/frame.rs@@ -1,14 +1,12 @@//! The binary body of the v2 vault transfers: a 4-byte big-endian header length, a JSON header, then the raw-//! ciphertexts. Each header entry that carries a ciphertext gives its `offset` (counted from the first byte after the-//! header) and `size`, so a reader skips entries and bytes it does not know, as it skips unknown JSON fields.-//! Mirrors the server's `BinaryFrame`.+//! ciphertexts, each located by the `offset` (from the first byte after the header) and `size` its header entry carries.use serde::de::DeserializeOwned;use serde::{Deserialize, Serialize};use super::errors::{SyncError, SyncResult};-/// A ciphertext sent after the frame header; the header carries its `offset` and `size`.+/// A ciphertext sent after the frame header.#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]pub struct FramePart {#[serde(default)]@@ -25,7 +23,7 @@ impl From<Vec<u8>> for FramePart {}}-/// A frame header: the entries whose ciphertext follows it, in frame order.+/// A frame header, which lists its ciphertext parts in frame order.pub(crate) trait FrameBody {fn parts(&mut self) -> Vec<&mut FramePart>;}diff --git a/core/rust/src/vault_sync/http.rs b/core/rust/src/vault_sync/http.rsindex 4585f3031..5cfedeb65 100644--- a/core/rust/src/vault_sync/http.rs+++ b/core/rust/src/vault_sync/http.rs@@ -8,14 +8,14 @@ use super::frame::{self, FrameBody};use super::session::Host;use super::types::{Command, HttpMethod, HttpResponse, LogLevel, StatusResponse};-/// A request body: none, JSON text, or a binary frame the host sends as `application/octet-stream`.+/// A request body.enum Body {None,Json(String),Frame(Vec<u8>),}-/// Send a request; with `binary_response` a successful response comes back as raw bytes instead of as `body` text.+/// Send a request, reading a `binary_response` as raw bytes instead of `body` text.async fn send(host: &Host, method: HttpMethod, path: &str, body: Body, large_transfer: bool, binary_response: bool) -> SyncResult<(HttpResponse, Option<Vec<u8>>)> {let (body, binary_body, bytes) = match body {Body::None => (None, false, None),@@ -43,24 +43,24 @@ async fn send_json(host: &Host, method: HttpMethod, path: &str, body: Body, largasync fn send_for_frame<T: FrameBody + DeserializeOwned>(host: &Host, method: HttpMethod, path: &str, body: Body) -> SyncResult<T> {let (response, bytes) = send(host, method, path, body, true, true).await?;check(response)?;- // A host that could not read the body hands back no bytes: a transfer failure, not a damaged vault.+ // No bytes means the host could not read the body: a transfer failure, not a damaged vault.frame::decode(&bytes.ok_or_else(|| SyncError::Network(format!("{} answered without a body", path)))?)}-/// The body of a successful response, or the error a refused or failed request maps to.+/// The body of a successful response, or the error the status maps to.pub(super) fn check(response: HttpResponse) -> SyncResult<String> {let code = api_error_code(&response.body);match response.status {200..=299 => Ok(response.body),401 => Err(SyncError::Auth),- // A coded 403 is a refusal (e.g. `CAPABILITY_NOT_AVAILABLE`), not a dead session.+ // A coded 403 is a refusal, not a dead session.403 if code.is_none() => Err(SyncError::Auth),413 => Err(SyncError::PayloadTooLarge),status => Err(SyncError::Http { status, code, body: response.body }),}}-/// The API error code a v2 error body (`{"code": "...", "statusCode": ...}`) names.+/// The API error code an error body names.pub(crate) fn api_error_code(body: &str) -> Option<String> {let parsed: serde_json::Value = serde_json::from_str(body).ok()?;parsed.get("code")?.as_str().filter(|code| is_api_error_code(code)).map(str::to_string)@@ -106,20 +106,21 @@ pub(crate) async fn post_frame<B: FrameBody + Serialize, T: DeserializeOwned>(hoparse(&send_json(host, HttpMethod::Post, path, Body::Frame(frame::encode(body)?), true).await?)}-/// The v2 vault endpoint (`GET`/`POST v2/Vault`).+/// `GET`/`POST v2/Vault`.pub(crate) const VAULT_ENDPOINT: &str = "Vault";-/// The v2 vault key endpoint (`GET v2/VaultKey/Password`): the account's key chain encrypted under the password.-// TODO: switch to "UnlockMethod/Password" after minimum API is 0.32.0+ that has the new URL.+/// `GET v2/VaultKey/Password`: the account's key chain encrypted under the password.+// LEGACY: servers before 0.32.0 serve the key chain at this URL only. TODO: switch to "UnlockMethod/Password" once the+// minimum API version is 0.32.0+.pub(crate) const VAULT_KEY_PASSWORD_ENDPOINT: &str = "VaultKey/Password";/// Max ciphertext bytes in one blob transfer request or response body.pub(crate) const BLOB_TRANSFER_BATCH_MAX_BYTES: usize = 4 * 1024 * 1024;-/// Upper bound on the number of blobs in one transfer batch (the server's `VaultWriteLimits.MaxBlobsPerUpload`).+/// The server's cap on blobs per transfer batch.pub(crate) const BLOB_TRANSFER_BATCH_MAX_COUNT: usize = 100;-/// Upper bound on the number of hashes in one `blobs/missing` or `blobs/download` request (the server's `VaultWriteLimits.MaxHashesPerRequest`).+/// The server's cap on hashes per `blobs/missing` or `blobs/download` request.pub(crate) const BLOB_HASH_REQUEST_MAX_COUNT: usize = 1000;/// Split items into transfer batches bounded by both blob transfer limits.@@ -142,7 +143,7 @@ pub(crate) fn batch_by_transfer_cost<T>(items: Vec<T>, cost_of: impl Fn(&T) -> ubatches}-/// Turn an uncoded 404 (a route miss) from a v2 vault endpoint into "the server predates the v2 API".+/// Read an uncoded 404 as a server that predates the v2 API.pub(crate) fn with_outdated_server_guard<T>(result: SyncResult<T>) -> SyncResult<T> {match result {Err(SyncError::Http { status: 404, code: None, .. }) => Err(SyncError::ServerUpdateRequired),@@ -153,8 +154,7 @@ pub(crate) fn with_outdated_server_guard<T>(result: SyncResult<T>) -> SyncResult/// The server version a status call reports when the server cannot be reached.pub(crate) const SERVER_UNREACHABLE_VERSION: &str = "0.0.0";-/// `GET v2/Status`. A transport failure or a 5xx reads as "server unreachable", reported as server version-/// [`SERVER_UNREACHABLE_VERSION`] so the caller can go offline; every other failure is returned.+/// `GET v2/Status`; a transport failure or a 5xx reads as server version [`SERVER_UNREACHABLE_VERSION`].pub(crate) async fn get_status(host: &Host) -> SyncResult<StatusResponse> {match with_outdated_server_guard(get::<StatusResponse>(host, "Status", false).await) {Err(error @ (SyncError::Network(_) | SyncError::Timeout(_) | SyncError::Http { status: 500..=599, .. })) => {diff --git a/core/rust/src/vault_sync/keys.rs b/core/rust/src/vault_sync/keys.rsindex 71df9a794..1ea3b0817 100644--- a/core/rust/src/vault_sync/keys.rs+++ b/core/rust/src/vault_sync/keys.rs@@ -2,19 +2,19 @@use std::collections::HashMap;+use secrecy::{ExposeSecret, SecretString};use zeroize::Zeroizing;use super::errors::{SyncError, SyncResult};+use super::http;use super::session::Host;use super::state::{self, Ctx};use super::types::{ManifestDto, SharedManifestDto, VaultKeyGetResponse, VaultKeyResponse, ALGORITHM_AES256_GCM, ALGORITHM_RSA_OAEP_SHA256};-use super::http;use crate::common::error::{VaultError, VaultResult};use crate::common::secret::from_zeroizing;-use secrecy::{ExposeSecret, SecretString};use crate::crypto;-/// Whether this device has the account's key chain cached (the encrypted Account Key).+/// Whether this device has the account's key chain cached.pub(crate) async fn has_cached_key_chain(host: &Host) -> SyncResult<bool> {Ok(state::get::<String>(host, state::ENCRYPTED_ACCOUNT_KEY).await?.is_some())}@@ -36,7 +36,7 @@ fn ensure_known_unlock_algorithm(vault_key: &VaultKeyResponse) -> SyncResult<()>Err(SyncError::VaultVersionIncompatible(format!("the Account Key is encrypted with '{}', which this app cannot open; update the app", vault_key.algorithm)))}-/// The state keys the key chain is cached under; `cache_vault_key_blobs` pairs them with the server fields by position.+/// The state keys the key chain is cached under, paired by position with the server fields in `cache_vault_key_blobs`.const CHAIN_STATE: [&str; 6] = [state::ENCRYPTED_ACCOUNT_KEY, state::ENCRYPTED_VEK, state::ACCOUNT_PUBLIC_KEY, state::ENCRYPTED_ACCOUNT_PRIVATE_KEY, state::SIGNING_PUBLIC_KEY, state::ENCRYPTED_SIGNING_PRIVATE_KEY];/// Cache a server vault-key response's encrypted blobs; a half the server does not hold is removed.@@ -51,7 +51,7 @@ async fn cache_vault_key_blobs(host: &Host, vault_key: &VaultKeyResponse) -> SynOk(())}-/// Clear the cached key chain: the account has none (legacy), so the unlock key is the vault key.+/// Clear the cached key chain.async fn clear_cached_chain(host: &Host) -> SyncResult<()> {for key in CHAIN_STATE {state::remove(host, key).await?;@@ -59,8 +59,7 @@ async fn clear_cached_chain(host: &Host) -> SyncResult<()> {Ok(())}-/// Open a key chain with the unlock key: stages the Account Key and the account private key for this run and returns-/// the VEK, which the caller makes the session key.+/// Open a key chain with the unlock key, keep the Account Key and account private key on the session, and return the VEK.async fn open_chain(ctx: &mut Ctx, encrypted_account_key: &str, encrypted_vek: &str, encrypted_private_key: Option<&str>, unlock_key: &str) -> SyncResult<SecretString> {let mut opened = crypto::open_key_chain_with_unlock_key(unlock_key, encrypted_account_key, encrypted_vek, None)?;let account_key = from_zeroizing(std::mem::take(&mut opened.account_key));@@ -74,8 +73,7 @@ async fn open_chain(ctx: &mut Ctx, encrypted_account_key: &str, encrypted_vek: &Ok(from_zeroizing(std::mem::take(&mut opened.vault_encryption_key)))}-/// Open the chain of a server vault-key response with `unlock_key`, refusing an unknown unlock algorithm first and a-/// served account public key that is not the public half of the private key.+/// Open the chain of a server vault-key response with `unlock_key`.async fn open_server_chain(ctx: &mut Ctx, vault_key: &VaultKeyResponse, unlock_key: &str) -> SyncResult<SecretString> {ensure_known_unlock_algorithm(vault_key)?;let vek = open_chain(ctx, &vault_key.encrypted_account_key, vault_key.encrypted_vek.as_deref().unwrap_or_default(), vault_key.encrypted_account_private_key.as_deref(), unlock_key).await?;@@ -86,7 +84,7 @@ async fn open_server_chain(ctx: &mut Ctx, vault_key: &VaultKeyResponse, unlock_kOk(vek)}-/// Refuse an account public key the server serves as this account's unless it is the public half of the held private key.+/// Refuse a served account public key that is not the public half of the private key this session holds.fn ensure_own_key_pair(public_key: &str, private_key: &str) -> SyncResult<()> {let pair = crypto::RsaKeyPair { public_key: public_key.to_string(), private_key: private_key.to_string() };crypto::rsa_oaep::validate_rsa_key_pair(&pair).map_err(|_| SyncError::AccountKeyMismatch)@@ -106,8 +104,7 @@ pub(crate) async fn own_account_public_key(ctx: &Ctx) -> SyncResult<Option<StrinOk(Some(public_key))}-/// The login-time key resolution (the `resolveVaultKey` operation): open the server's chain with the session key,-/// cache it for offline unlock, and make the VEK the session key. Returns whether the account has a chain.+/// Open the account's key chain at login with the session key, cache it, and make the VEK the session key; returns whether the account has a chain.pub(crate) async fn resolve_vault_key(ctx: &mut Ctx) -> SyncResult<bool> {let unlock_key = ctx.encryption_key()?;ctx.vault_key_probed = true;@@ -120,6 +117,8 @@ pub(crate) async fn resolve_vault_key(ctx: &mut Ctx) -> SyncResult<bool> {Ok(true)}Ok(_) => {+ // LEGACY: a sqlite-blob account has no key chain, so the unlock key stays the vault key. TODO: remove once+ // every account has upgraded.clear_cached_chain(&ctx.host).await?;ctx.log("[Keys] The account has no key chain yet (legacy vault); the unlock key is the vault key.").await;Ok(false)@@ -136,9 +135,10 @@ pub(crate) async fn resolve_vault_key(ctx: &mut Ctx) -> SyncResult<bool> {}}-/// Accept a key hierarchy another device created since this legacy-login device last looked (probed once per run).-/// False only when the session key does not open it, which needs a re-login.+/// Accept a key hierarchy another device created since this device logged in; false when the session key does not open it.pub(crate) async fn accept_hierarchy_created_elsewhere(ctx: &mut Ctx) -> SyncResult<bool> {+ // LEGACY: only a device that logged in to a sqlite-blob account, before another device upgraded it, gets here.+ // TODO: remove once every account has upgraded.if ctx.vault_key_probed {return Ok(true);}@@ -156,7 +156,6 @@ pub(crate) async fn accept_hierarchy_created_elsewhere(ctx: &mut Ctx) -> SyncResctx.warn("[Keys] The session key does not open the key hierarchy the server holds; a re-login is needed.").await;return Ok(false);}- // A storage failure or an unreadable stored vault is its own failure, not a key mismatch.Err(error) => return Err(error),};// The chain is cached before the vault is stored under the VEK: hosts hold the unlock key and derive the vault key from it.@@ -182,7 +181,7 @@ pub(crate) async fn ensure_key_chain_accepted(ctx: &mut Ctx) -> SyncResult<bool>has_cached_key_chain(&ctx.host).await}-/// This account's signing public key, derived from the private key so that it never depends on what the server serves.+/// This account's signing public key, derived from the private key and never taken from what the server serves.pub(crate) async fn own_signing_public_key(ctx: &mut Ctx) -> SyncResult<Option<String>> {match signing_private_key(ctx).await? {Some(private_key) => Ok(Some(crypto::signing::signing_public_key_of(private_key.expose_secret())?)),@@ -190,8 +189,7 @@ pub(crate) async fn own_signing_public_key(ctx: &mut Ctx) -> SyncResult<Option<S}}-/// The account signing private key, opened on first use from the cached encrypted copy with the session's Account Key.-/// None when that key or the cached copy is missing or does not open it.+/// The account signing private key, opened once per run from the cached encrypted copy; `None` when it is missing or does not open.pub(crate) async fn signing_private_key(ctx: &mut Ctx) -> SyncResult<Option<SecretString>> {if ctx.signing_private_key.is_some() {return Ok(ctx.signing_private_key.clone());@@ -246,7 +244,7 @@ pub(crate) async fn resolve_grant_private_key(ctx: &Ctx, public_key: &str) -> SyOk(ctx.account_private_key.clone())}-/// Encrypt a manifest's VEK for one recipient key, bound to the manifest (see [`crypto::aad::grant`]).+/// Encrypt a manifest's VEK for one recipient key, bound to the manifest.pub(crate) fn encrypt_manifest_vek(manifest_vek: &str, manifest_id: &str, recipient_public_key_jwk: &str) -> SyncResult<String> {Ok(crypto::rsa_oaep::encrypt(manifest_vek.as_bytes(), recipient_public_key_jwk, &crypto::aad::grant(manifest_id))?)}@@ -257,12 +255,12 @@ pub(crate) fn decrypt_manifest_vek(encrypted_vek: &str, manifest_id: &str, privastd::str::from_utf8(&plaintext).map(SecretString::from).map_err(|_| SyncError::Other("Decrypted manifest key is not valid text".to_string()))}-/// Encrypt a shared manifest's name into an invitation for one recipient key, bound to the manifest (see [`crypto::aad::invitation_name`]).+/// Encrypt a shared manifest's name into an invitation for one recipient key, bound to the manifest.pub(crate) fn encrypt_manifest_invitation_name(name: &str, manifest_id: &str, recipient_public_key_jwk: &str) -> VaultResult<String> {crypto::rsa_oaep::encrypt(name.as_bytes(), recipient_public_key_jwk, &crypto::aad::invitation_name(manifest_id))}-/// Decrypt the shared manifest name encrypted into an invitation for this JWK private key, as UTF-8 text.+/// Decrypt a shared manifest's name from an invitation made out to this private key.pub(crate) fn decrypt_manifest_invitation_name(encrypted_name: &str, manifest_id: &str, private_key_jwk: &str) -> VaultResult<String> {let plaintext = crypto::rsa_oaep::decrypt(encrypted_name, private_key_jwk, &crypto::aad::invitation_name(manifest_id))?;String::from_utf8(plaintext).map_err(|_| VaultError::General("Decrypted invitation name is not valid text".to_string()))@@ -287,7 +285,7 @@ pub(crate) async fn open_shared_manifest_vek(ctx: &Ctx, record: &SharedManifestD}}-/// The VEK of every shared manifest this account holds a grant on, keyed by manifest id. Decrypted once per run.+/// The VEK of every shared manifest this account holds a grant on, keyed by manifest id; decrypted once per run.pub(crate) async fn open_shared_manifest_veks(ctx: &Ctx) -> SyncResult<HashMap<String, SecretString>> {if let Some(cached) = ctx.cached_shared_veks() {return Ok(cached);diff --git a/core/rust/src/vault_sync/legacy.rs b/core/rust/src/vault_sync/legacy.rsindex bf02ec118..61919407d 100644--- a/core/rust/src/vault_sync/legacy.rs+++ b/core/rust/src/vault_sync/legacy.rs@@ -1,7 +1,9 @@//! LEGACY: what old sqlite-blob accounts need, including their one-time upgrade from sqlite-blob to manifest-v1//! ([`upgrade_account_to_manifest_v1`]). TODO: remove this module once every account has upgraded, together with the-//! `Snapshot::LegacySqliteBlob` arm in `pull.rs` and `merge.rs`, `db::schema_state`'s frozen chain check, the-//! branch without a vault key in `migration::migrate_manifest` and the upgrade-elsewhere check in `migration::migration_status`.+//! `Snapshot::LegacySqliteBlob` arm in `pull.rs` and `merge.rs`, `db::schema_state`'s frozen chain check, the branch+//! without a key chain in `keys::resolve_vault_key`, `keys::accept_hierarchy_created_elsewhere`, the branch without a+//! vault key in `migration::migrate_manifest`, the upgrade-elsewhere check in `migration::migration_status` and the+//! unsigned approval in `sharing::approve_mobile_login`.use std::collections::HashMap;@@ -9,12 +11,12 @@ use serde_json::Value;use super::db::{self, SchemaState};use super::errors::{SyncError, SyncResult};+use super::keys;use super::migration;use super::pull::{self, PulledVault};use super::push::{resolve_personal_manifest_id, WriteKind};use super::state::{self, Ctx};use super::types::{Db, GetResponse};-use super::keys;use crate::common::encoding::base64_decode;use crate::sqlite_host::SqlStatement;use crate::vault_codec::row::inline_bytes;@@ -22,10 +24,9 @@ use crate::vault_codec::row::inline_bytes;/// The `storageFormat` of a legacy sqlite-blob snapshot; an absent value means the same.pub(crate) const STORAGE_FORMAT_SQLITE_BLOB: &str = "sqlite-blob";-/// Take a legacy snapshot apart for local storage: the blob passes through untouched, the manifest-v1 fingerprints-/// are reset, and the personal manifest id is recorded for the migration push.+/// Take a legacy snapshot apart for local storage: the blob passes through as-is and the personal manifest id is recorded for the upgrade push.pub(crate) async fn open_legacy_snapshot(ctx: &Ctx, snapshot: &GetResponse) -> SyncResult<PulledVault> {- // Sanity check: a server that serves a sqlite-blob vault to a device holding a key chain is behind the session.+ // A server that serves a sqlite-blob vault to a device holding a key chain is behind the session.if keys::has_cached_key_chain(&ctx.host).await? {return Err(SyncError::KeyOutOfSync);}@@ -47,9 +48,8 @@ pub(crate) async fn open_legacy_snapshot(ctx: &Ctx, snapshot: &GetResponse) -> S/// Every column declared BLOB, as (TableName, ColumnName) rows.const BLOB_TYPED_COLUMNS: &str = "SELECT m.name AS TableName, p.name AS ColumnName FROM sqlite_master m JOIN pragma_table_info(m.name) p WHERE m.type = 'table' AND upper(p.type) = 'BLOB'";-/// Upgrade a sqlite-blob account to manifest-v1: the local vault is rebuilt onto the current schema with its unstamped-/// rows stamped with the personal manifest, and the push that carries it creates the account key hierarchy. Returns-/// whether that push reached the server.+/// Upgrade a sqlite-blob account to manifest-v1: rebuild the local vault onto the current schema with its unstamped rows+/// stamped with the personal manifest, and push it, which creates the key hierarchy; returns whether the push reached the server.pub(crate) async fn upgrade_account_to_manifest_v1(ctx: &mut Ctx) -> SyncResult<bool> {if accept_upgrade_done_elsewhere(ctx).await? {return migration::migrate_schema(ctx).await;@@ -58,12 +58,11 @@ pub(crate) async fn upgrade_account_to_manifest_v1(ctx: &mut Ctx) -> SyncResult<return Err(SyncError::LegacyUpgradePending);}record_server_baseline_if_missing(ctx).await?;+ // The baseline pull may have stored an upgraded vault, or one still on the chain.if keys::has_cached_key_chain(&ctx.host).await? {- // The baseline pull turned up an account that is upgraded already; a schema rebuild is all that can remain.return migration::migrate_schema(ctx).await;}if migration::schema_state(ctx).await? == SchemaState::LegacyChain {- // The baseline pull stored a server vault that is still on the chain.return Err(SyncError::LegacyUpgradePending);}let personal = resolve_personal_manifest_id(ctx).await?;@@ -72,9 +71,8 @@ pub(crate) async fn upgrade_account_to_manifest_v1(ctx: &mut Ctx) -> SyncResult<migration::push_migrated_vault(ctx, WriteKind::AccountKeyMigration).await}-/// Accept a key hierarchy another device created since this session logged in, and replace the local sqlite-blob vault-/// with the server's: that device already upgraded the account, and the local rows that name no manifest cannot be-/// canonicalized. Returns whether that happened. Call only while no key chain is cached.+/// Replace the local sqlite-blob vault with the server's when another device upgraded the account since this session+/// logged in; returns whether that happened. Call only while no key chain is cached.pub(crate) async fn accept_upgrade_done_elsewhere(ctx: &mut Ctx) -> SyncResult<bool> {// Accepting swaps the session key to the VEK, which the pull below needs.if !keys::ensure_key_chain_accepted(ctx).await? {@@ -108,8 +106,7 @@ async fn record_server_baseline_if_missing(ctx: &mut Ctx) -> SyncResult<()> {pull::commit_revisions(ctx, &pulled).await}-/// Decode base64 TEXT in BLOB columns back to bytes, in place; text that is not base64 is left as-is.-/// The 0.30.x merges (Android, iOS, Blazor) bound every value as text, storing BLOB cells as base64 TEXT.+/// Decode the base64 TEXT the 0.30.x merges wrote into BLOB columns back to bytes, in place; text that is not base64 is left as-is.async fn decode_base64_text_in_blob_columns(ctx: &Ctx) -> SyncResult<()> {let mut decoded = 0usize;for column in db::query(&ctx.host, Db::Local, BLOB_TYPED_COLUMNS, vec![]).await? {@@ -131,8 +128,7 @@ async fn decode_base64_text_in_blob_columns(ctx: &Ctx) -> SyncResult<()> {Ok(())}-/// The frozen sqlite-blob upgrade chain: (revision, data version). It ends at 2.0.0, the first schema compatible-/// with manifest-v1; later schema changes ship through the full schema only, which every materialization uses directly.+/// The frozen sqlite-blob upgrade chain as (revision, data version), ending at 2.0.0, the first schema compatible with manifest-v1.const LEGACY_VAULT_VERSIONS: &[(u32, &str)] = &[(1, "1.0.0"),(2, "1.0.1"),@@ -167,8 +163,7 @@ fn is_well_formed_version(version: &str) -> bool {version.split('.').count() == 3 && version.split('.').all(|part| !part.is_empty() && part.chars().all(|c| c.is_ascii_digit()))}-/// The legacy-chain revision a database version maps to. A known version maps to its entry; an unknown but-/// well-formed version is treated as the latest (backwards compatible); a malformed version is incompatible.+/// The legacy-chain revision of a database version; an unknown but well-formed version counts as the latest, a malformed one is incompatible.pub(super) fn legacy_revision_for(database_version: &str) -> Result<u32, String> {if let Some((revision, _)) = LEGACY_VAULT_VERSIONS.iter().find(|(_, version)| *version == database_version) {return Ok(*revision);diff --git a/core/rust/src/vault_sync/merge.rs b/core/rust/src/vault_sync/merge.rsindex b7ea6cc6c..af2d69951 100644--- a/core/rust/src/vault_sync/merge.rs+++ b/core/rust/src/vault_sync/merge.rs@@ -17,9 +17,9 @@ use crate::vault_merge::{merge_canonical, CanonicalManifestMerge, CanonicalMerge/// What a dirty pull (pull and merge) produced.pub(crate) enum PullAndMergeOutcome {/// LEGACY: the server's vault is still a sqlite blob at this revision; the caller pushes the local vault over it.+ /// TODO: remove once every account has upgraded to manifest-v1.LegacyServer { revision: i64 },- /// The merged vault, with the canonical set the push right after it writes from (none when a manifest fell back- /// to the server's version, which the push then has to canonicalize again).+ /// The merged vault, with the canonical set the push writes from unless a manifest fell back to the server's version.Merged { pulled: PulledVault, push_canonical: Option<CanonicalizedSet> },/// The merge failed, so the server's vault stands as pulled and the local changes are dropped.ServerOnly(PulledVault),@@ -30,7 +30,8 @@ pub(crate) async fn pull_and_merge(ctx: &mut Ctx) -> SyncResult<PullAndMergeOutclet vek = ctx.encryption_key()?;ctx.log("[Merge] Fetching vault snapshot for canonical merge (GET /v2/Vault)...").await;let snapshot = match pull::fetch_snapshot(ctx).await? {- // LEGACY: a server still on the sqlite-blob format cannot merge with a manifest-v1 vault; the caller pushes over it.+ // LEGACY: a server still on the sqlite-blob format cannot merge with a manifest-v1 vault, so the caller pushes+ // over it. TODO: remove once every account has upgraded to manifest-v1.Snapshot::LegacySqliteBlob(snapshot) => {let legacy = legacy::open_legacy_snapshot(ctx, &snapshot).await?;pull::commit_revisions(ctx, &legacy).await?;@@ -52,7 +53,6 @@ pub(crate) async fn pull_and_merge(ctx: &mut Ctx) -> SyncResult<PullAndMergeOutcmatch merge_onto_opened_manifests(ctx, &opened, local_side, vek.expose_secret()).await {Ok(outcome) => Ok(outcome),Err(merge_error) => {- // The merge-failure fallback, from the same snapshot: the server vault stands, local changes are dropped.ctx.warn(format!("[Merge] Canonical merge failed, falling back to the server vault: {}", merge_error)).await;let sqlite_bytes = pull::materialize_to_sqlite(ctx, &opened.manifests(), &opened.data_buckets, &opened.blob_map, &opened.manifest_names).await?;Ok(PullAndMergeOutcome::ServerOnly(opened.pulled_vault(state::encrypt_vault_blob(&sqlite_bytes, vek.expose_secret())?)))@@ -176,8 +176,7 @@ fn validate_merged_manifest(entry: &CanonicalManifestMerge) -> Option<String> {None}-/// The bytes at hand for the blobs the merged manifests reference, per manifest. A blob without bytes is not loaded-/// (yet) by the client: its row keeps the reference, and the push only uploads what the server lacks and this device has.+/// The bytes at hand for the blobs the merged manifests reference, per manifest; a blob without bytes keeps its reference.fn collect_merged_blobs(manifests: &[Manifest], blob_map: &HashMap<String, Vec<u8>>, local_blobs: &HashMap<String, BlobEntry>) -> HashMap<String, HashMap<String, BlobEntry>> {let mut by_manifest: HashMap<String, HashMap<String, BlobEntry>> = HashMap::new();for manifest in manifests {diff --git a/core/rust/src/vault_sync/migration.rs b/core/rust/src/vault_sync/migration.rsindex caafa0016..41126740f 100644--- a/core/rust/src/vault_sync/migration.rs+++ b/core/rust/src/vault_sync/migration.rs@@ -1,7 +1,8 @@-//! The local storage-model migrations: where the vault's schema stands, the rebuild of a stale one, and the-//! operations the upgrade gate drives (`migrationStatus`, `migrateManifest`).+//! The local storage-model migrations: where the vault's schema stands, the rebuild of a stale one, and the operations+//! behind the upgrade gate.use std::collections::HashMap;+use secrecy::ExposeSecret;use super::db::{self, SchemaState};@@ -54,6 +55,7 @@ pub(crate) async fn migration_status(ctx: &mut Ctx) -> MigrationStatusResult {if schema_state(ctx).await? == SchemaState::LegacyChain {return Ok(MigrationKind::None);}+ // LEGACY: an account without a key chain is still on sqlite-blob. TODO: remove with `legacy.rs`.if !keys::has_cached_key_chain(&ctx.host).await? && !legacy::accept_upgrade_done_elsewhere(ctx).await? {return Ok(MigrationKind::StorageFormatUpgrade);}@@ -71,10 +73,11 @@ pub(crate) async fn migration_status(ctx: &mut Ctx) -> MigrationStatusResult {MigrationStatusResult { kind }}-/// Bring the local vault onto the current storage model and push it: a schema rebuild for a migrated account, the-/// one-time account upgrade (`legacy::upgrade_account_to_manifest_v1`) for an account without a key hierarchy yet.+/// Bring the local vault onto the current storage model and push it: a schema rebuild, or the one-time account upgrade+/// for an account without a key chain yet.pub(crate) async fn migrate_manifest(ctx: &mut Ctx) -> MigrateManifestResult {let migrated: SyncResult<bool> = async {+ // LEGACY: an account without a key chain is still on sqlite-blob. TODO: remove with `legacy.rs`.if !keys::has_cached_key_chain(&ctx.host).await? {ensure_server_ready(ctx).await?;return legacy::upgrade_account_to_manifest_v1(ctx).await;@@ -91,7 +94,7 @@ pub(crate) async fn migrate_manifest(ctx: &mut Ctx) -> MigrateManifestResult {}}-/// Refuse the one-time account upgrade before it touches the local vault unless the server is reachable and serves the v2 API.+/// Refuse the account upgrade before it touches the local vault unless the server is reachable.async fn ensure_server_ready(ctx: &Ctx) -> SyncResult<()> {if http::get_status(&ctx.host).await?.server_version == http::SERVER_UNREACHABLE_VERSION {return Err(SyncError::Network("the server is unreachable; the migration needs it".to_string()));@@ -99,8 +102,8 @@ async fn ensure_server_ready(ctx: &Ctx) -> SyncResult<()> {Ok(())}-/// The permanent migration: rebuild a stale local schema onto the current one and push it. Returns whether the-/// push reached the server; a vault already on the current schema counts as pushed.+/// Rebuild a stale local schema onto the current one and push it; returns whether the push reached the server, with a+/// vault already on the current schema counting as pushed.pub(crate) async fn migrate_schema(ctx: &mut Ctx) -> SyncResult<bool> {match schema_state(ctx).await? {SchemaState::Current => Ok(true),@@ -112,8 +115,8 @@ pub(crate) async fn migrate_schema(ctx: &mut Ctx) -> SyncResult<bool> {}}-/// Rebuild the local vault onto the current schema locally and store it as a pending change; `stamp_unstamped_into`-/// stamps rows that carry no manifest yet (sqlite-blob vaults only).+/// Rebuild the local vault onto the current schema and store it as a pending change; `stamp_unstamped_into` stamps+/// rows that carry no manifest yet.pub(crate) async fn rebuild_local_schema(ctx: &mut Ctx, stamp_unstamped_into: Option<String>) -> SyncResult<()> {ctx.log("[Migration] Migrating local vault onto the current schema (local round-trip, no server involved)...").await;let set = push::canonicalize_vault(ctx, stamp_unstamped_into).await?;@@ -134,8 +137,8 @@ pub(crate) async fn rebuild_local_schema(ctx: &mut Ctx, stamp_unstamped_into: OpOk(())}-/// Push the migrated vault and clear the dirty flag. A refused or failed push leaves the vault dirty for the next sync,-/// except a failure that ends the session. Returns whether the push reached the server.+/// Push the migrated vault and clear the dirty flag; returns whether the push reached the server, a refused or failed push+/// leaving the vault dirty for the next sync unless the failure ends the session.pub(crate) async fn push_migrated_vault(ctx: &mut Ctx, kind: WriteKind) -> SyncResult<bool> {match push::upload_vault(ctx, None, kind).await {Ok(upload) if upload.status == PushStatus::Ok => {diff --git a/core/rust/src/vault_sync/mod.rs b/core/rust/src/vault_sync/mod.rsindex 1b9be9d46..a28a4dc43 100644--- a/core/rust/src/vault_sync/mod.rs+++ b/core/rust/src/vault_sync/mod.rs@@ -1,10 +1,10 @@-//! The vault sync engine that all AliasVault clients use to synchronize their vaults with the server.+//! The vault sync engine every client runs its vault synchronization with the server through.mod blob_keys;-pub(crate) mod db;+mod db;mod email_routing;mod engine;-pub(crate) mod errors;+mod errors;mod frame;mod http;pub(crate) mod keys;@@ -16,8 +16,8 @@ mod push;mod rotation;mod session;mod sharing;-pub(crate) mod state;-pub(crate) mod types;+mod state;+mod types;mod write_set;#[cfg(test)]diff --git a/core/rust/src/vault_sync/pull.rs b/core/rust/src/vault_sync/pull.rsindex f7a8f0f17..aa60e9484 100644--- a/core/rust/src/vault_sync/pull.rs+++ b/core/rust/src/vault_sync/pull.rs@@ -51,13 +51,13 @@ impl OpenedManifestSet {}}-/// A pulled vault, encrypted for local storage, with the revisions that become the local truth once it is stored.+/// A pulled vault, encrypted for local storage, with the revisions it was pulled at.pub(crate) struct PulledVault {pub encrypted_vault: String,pub personal_revision: i64,pub manifest_revisions: HashMap<String, i64>,pub bucket_revisions: HashMap<String, i64>,- /// The vault is new and has never been written to the server; it is stored dirty and pushed by the same sync.+ /// The vault was never written to the server; it is stored dirty and pushed by the same sync.pub needs_first_write: bool,}@@ -67,11 +67,11 @@ const STORAGE_FORMAT_MANIFEST: &str = "manifest";/// A server snapshot by storage format.pub(crate) enum Snapshot {Manifest(GetResponse),- /// LEGACY: the account's vault is still one sqlite blob.+ /// LEGACY: the account's vault is still one sqlite blob. TODO: remove once every account has upgraded to manifest-v1.LegacySqliteBlob(GetResponse),}-/// `GET v2/Vault`. A snapshot in a storage format newer than this build knows is refused, never read as legacy.+/// `GET v2/Vault`; a storage format newer than this build knows is refused, never read as legacy.pub(crate) async fn fetch_snapshot(ctx: &Ctx) -> SyncResult<Snapshot> {let snapshot: GetResponse = http::with_outdated_server_guard(http::get_frame(&ctx.host, http::VAULT_ENDPOINT).await)?;match snapshot.storage_format.as_deref() {@@ -96,7 +96,7 @@ pub(crate) fn verify_decrypt_unpack(ciphertext: &[u8], vek: &str, aad: &[u8], ex}}-/// Refuse a manifest or data bucket written at a format version this build cannot read: the app is outdated.+/// Refuse a payload written at a format version this build cannot read.fn ensure_readable(schema_version: u32, label: &str) -> SyncResult<()> {if vault_codec::is_readable_schema_version(schema_version) {return Ok(());@@ -127,6 +127,7 @@ pub(crate) async fn pull(ctx: &mut Ctx) -> SyncResult<PulledVault> {let vek = ctx.encryption_key()?;ctx.log("[Pull] Fetching vault snapshot (GET /v2/Vault)...").await;let snapshot = match fetch_snapshot(ctx).await? {+ // LEGACY: a sqlite-blob account's vault is opened as one blob. TODO: remove once every account has upgraded to manifest-v1.Snapshot::LegacySqliteBlob(snapshot) => return legacy::open_legacy_snapshot(ctx, &snapshot).await,Snapshot::Manifest(snapshot) => snapshot,};@@ -139,7 +140,6 @@ pub(crate) async fn pull(ctx: &mut Ctx) -> SyncResult<PulledVault> {}/// Open every manifest a snapshot carries, personal first, and record the snapshot as this device's sync state.-/// The revision maps travel on the result for the caller to commit once the pulled vault is stored.pub(crate) async fn open_manifests_and_record_sync_state(ctx: &mut Ctx, snapshot: &GetResponse, vek: &str) -> SyncResult<OpenedManifestSet> {let personal_dto = select_personal_manifest(snapshot).ok_or_else(|| SyncError::Snapshot("server returned no personal manifest, refusing to assemble".to_string()))?;// Registration creates the personal manifest without content at revision 0; any later revision without content is damage.@@ -173,7 +173,7 @@ pub(crate) async fn open_manifests_and_record_sync_state(ctx: &mut Ctx, snapshotcontinue;}if !dto.has_content() {- // A shared manifest served without content yet (created but never written); its grant and revision are still tracked.+ // A shared manifest created but never written; its grant and revision are still tracked.if dto.revision != 0 {return Err(SyncError::Snapshot(format!("shared manifest {} was served without content at revision {}, nothing to assemble", dto.manifest_id, dto.revision)));}@@ -255,7 +255,7 @@ pub(crate) fn encrypt_manifest_name(name: &str, manifest_id: &str, manifest_key:Ok(crypto::aes_gcm::encrypt_text(name, manifest_key, &crypto::aad::manifest_name(manifest_id))?)}-/// Commit a pulled vault's revisions as the local believed-current revisions, manifests and buckets together.+/// Commit a pulled vault's manifest and bucket revisions as the local ones.pub(crate) async fn commit_revisions(ctx: &Ctx, pulled: &PulledVault) -> SyncResult<()> {state::set(&ctx.host, state::SERVER_MANIFEST_REVISIONS, &pulled.manifest_revisions).await?;state::set(&ctx.host, state::VAULT_BUCKET_REVISIONS, &pulled.bucket_revisions).await?;@@ -263,7 +263,7 @@ pub(crate) async fn commit_revisions(ctx: &Ctx, pulled: &PulledVault) -> SyncResOk(())}-/// Open every data bucket a snapshot carries, record the snapshot's bucket revisions.+/// Open every data bucket a snapshot carries, with their fingerprints and revisions.async fn open_data_buckets(ctx: &Ctx, snapshot: &GetResponse, resolved: &[ResolvedManifest]) -> SyncResult<(Vec<DataBucket>, HashMap<String, String>, HashMap<String, i64>)> {let key_by_manifest: HashMap<&str, &str> = resolved.iter().map(|m| (m.manifest_id.as_str(), m.vek.expose_secret())).collect();let mut buckets = Vec::new();@@ -359,7 +359,6 @@ pub(crate) async fn materialize_to_sqlite(ctx: &mut Ctx, manifests: &[Manifest],ctx.warn(format!("[Pull] Newer-schema data preserved as overflow: {} unknown table(s), unknown columns on [{}].", overflow_tables, materialized.overflow.columns.keys().cloned().collect::<Vec<_>>().join(", "))).await;}- // Use a fresh staging database for every materialize.ctx.host.open_staging()?;db::insert_materialized(&ctx.host, &materialized, &schema.columns, blob_map).await?;@@ -404,7 +403,8 @@ async fn empty_personal_manifest(ctx: &Ctx, dto: &ManifestDto, vek: &str) -> Syn/// The key that opens one snapshot manifest.async fn resolve_manifest_vek(ctx: &Ctx, dto: &ManifestDto, personal_manifest_id: &str, personal_vek: &str, is_personal: bool, own_signing_public_key: Option<&str>) -> SyncResult<SecretString> {- // Only a personal manifest that predates the account key hierarchy has no key type; a shared one always states it.+ // LEGACY: a personal manifest written before the account key hierarchy states no key type. TODO: remove the+ // `None if is_personal` arm once every account has upgraded.let key_type = match dto.key_type.clone() {Some(key_type) => key_type,None if is_personal => types::KEY_TYPE_ACCOUNT_KEY.to_string(),@@ -432,7 +432,7 @@ async fn resolve_granted_vek(ctx: &Ctx, dto: &ManifestDto, own_signing_public_keif !keys::grant_signed_by_self(dto, signing_public_key, &public_key, &algorithm, &encrypted_vek) {return Err(SyncError::ServerVaultUnreadable(format!("the grant on shared manifest {} is not signed by this account, refusing to assemble", dto.manifest_id)));}- // Sanity check: no key this session holds opens the grant, so the session is behind the server.+ // No key this session holds opens the grant: the session is behind the server.let private_key = keys::resolve_grant_private_key(ctx, &public_key).await?.ok_or(SyncError::KeyOutOfSync)?;keys::decrypt_manifest_vek(&encrypted_vek, &dto.manifest_id, private_key.expose_secret()).map_err(|e| SyncError::ServerVaultUnreadable(format!("failed to decrypt the VEK of shared manifest {}, refusing to assemble: {}", dto.manifest_id, e)))}diff --git a/core/rust/src/vault_sync/push.rs b/core/rust/src/vault_sync/push.rsindex 9de96634b..c6950f5cd 100644--- a/core/rust/src/vault_sync/push.rs+++ b/core/rust/src/vault_sync/push.rs@@ -27,13 +27,11 @@ const MANIFEST_SCOPE: &str = "Main";/// What a push writes.#[derive(Debug, Clone, Copy, PartialEq, Eq)]pub(crate) enum WriteKind {- /// What changed against the last known server state. With `buckets_only`, a host that recorded only- /// bucket-scoped mutations gets away with writing those buckets, never canonicalizing the manifests.+ /// What changed against the last known server state; `buckets_only` writes the dirty buckets without canonicalizing the manifests.Changes { buckets_only: bool },/// Every manifest and bucket, whatever the fingerprints say: the server never saw this vault.Everything,- /// The one-time account upgrade: creates the key hierarchy and encrypts every personal blob again under the- /// new key, so the whole vault is written.+ /// The one-time account upgrade, which creates the key hierarchy and writes the whole vault under it.AccountKeyMigration,}@@ -63,7 +61,7 @@ pub(crate) enum PushStatus {pub(crate) struct UploadOutcome {pub status: PushStatus,pub mutation_seq_at_start: u64,- /// Whether the stored vault was rewritten under the upload (pruned or keypair added).+ /// Whether the stored vault was rewritten under the upload.pub vault_changed: bool,}@@ -105,7 +103,7 @@ async fn resolve_manifest_records(ctx: &Ctx) -> SyncResult<Vec<ManifestRecord>>Ok(records)}-/// The personal manifest id as the last pull recorded it. Pushing without one is impossible.+/// The personal manifest id the last pull recorded.pub(crate) async fn resolve_personal_manifest_id(ctx: &Ctx) -> SyncResult<String> {state::get::<String>(&ctx.host, state::VAULT_PERSONAL_MANIFEST_ID).await?.ok_or_else(|| SyncError::Other("no personal manifest id available (no snapshot baseline recorded); pull once before pushing".to_string()))}@@ -117,8 +115,7 @@ async fn resolve_write_keys(ctx: &Ctx) -> SyncResult<HashMap<String, SecretStrinOk(keys_by_manifest)}-/// Whether the local vault is canonically identical to the last-known server state. Returns the canonicalize-/// result too, so a push right after does not canonicalize a second time.+/// Whether the local vault equals the last known server state, with the canonicalize result for the push.pub(crate) async fn detect_no_op_mutation(ctx: &Ctx) -> SyncResult<(bool, CanonicalizedSet)> {let set = canonicalize_vault(ctx, None).await?;let baselines = PushBaselines::load(ctx).await?;@@ -164,8 +161,7 @@ pub(crate) async fn vault_holds_unwritable_manifests(ctx: &Ctx) -> bool {* The upload as the flow drives it.*/-/// Upload the stored vault. Fails with `KeyOutOfSync` when the session key does not open a hierarchy another-/// device created meanwhile; an account without a hierarchy gets the migration write whatever `kind` asked for.+/// Upload the stored vault; an account without a key hierarchy gets the migration write whatever `kind` asked for.pub(crate) async fn upload_vault(ctx: &mut Ctx, cache: Option<(u64, CanonicalizedSet)>, kind: WriteKind) -> SyncResult<UploadOutcome> {let mutation_seq_at_start = ctx.mutation_sequence;let kind = if keys::ensure_key_chain_accepted(ctx).await? { kind } else { WriteKind::AccountKeyMigration };@@ -181,8 +177,7 @@ pub(crate) async fn upload_vault(ctx: &mut Ctx, cache: Option<(u64, CanonicalizeOk(UploadOutcome { status, mutation_seq_at_start, vault_changed })}-/// The bucket categories a bucket-only write covers, or `None` when the write has to go through the manifests: no-/// scopes recorded, a manifest scope among them, an unknown scope, or a personal delivery key still to be published.+/// The bucket categories a bucket-only write covers, or `None` when the write has to go through the manifests.async fn bucket_only_categories(ctx: &Ctx) -> SyncResult<Option<Vec<String>>> {let scopes = &ctx.request.dirty_scopes;if scopes.is_empty() || scopes.iter().any(|s| s == MANIFEST_SCOPE) {@@ -235,8 +230,8 @@ async fn write_dirty_buckets(ctx: &Ctx, categories: &[String]) -> SyncResult<PusOk(PushStatus::Ok)}-/// Write the whole vault: prune expired trash and create a missing personal delivery keypair first, then the gated-/// write. Returns the status and whether the stored vault was rewritten (pruned or keypair added).+/// Write the whole vault after pruning expired trash and creating a missing delivery keypair; returns the status and+/// whether the stored vault was rewritten.async fn write_whole_vault(ctx: &mut Ctx, cached: Option<CanonicalizedSet>, kind: WriteKind) -> SyncResult<(PushStatus, bool)> {let key_before = ctx.encryption_key()?;let mut cached = cached;@@ -266,19 +261,15 @@ async fn write_whole_vault(ctx: &mut Ctx, cached: Option<CanonicalizedSet>, kindctx.set_encryption_key(new_key);}- // Store the vault again only when it changed or its key did.if vault_rewritten || ctx.encryption_key()?.expose_secret() != key_before.expose_secret() {ctx.persist_local_vault(false).await?;}Ok((status, vault_rewritten))}-/// Whether the personal manifest has no active mail delivery keypair. Without one the server has no public key to-/// encrypt incoming mail with, and rejects every email sent to the vault's aliases.+/// Whether the personal manifest has no active mail delivery keypair.async fn personal_delivery_key_missing(ctx: &Ctx) -> SyncResult<bool> {- let Some(personal_manifest_id) = state::get::<String>(&ctx.host, state::VAULT_PERSONAL_MANIFEST_ID).await? else {- return Ok(false);- };+ let Some(personal_manifest_id) = state::get::<String>(&ctx.host, state::VAULT_PERSONAL_MANIFEST_ID).await? else { return Ok(false) };Ok(db::active_public_key_for_manifest(&ctx.host, &personal_manifest_id).await?.is_none())}@@ -325,11 +316,7 @@ struct Candidate<'a> {impl Candidate<'_> {fn label(&self) -> String {- if self.record.is_personal {- "Personal manifest".to_string()- } else {- format!("Shared manifest {}", self.record.manifest_id)- }+ if self.record.is_personal { "Personal manifest".to_string() } else { format!("Shared manifest {}", self.record.manifest_id) }}}@@ -353,7 +340,7 @@ impl UploadBlobs {self.order.iter().filter(|h| self.entries[*h].from_personal == from_personal).cloned().collect()}- /// The given hashes grouped by the manifest that owns them, in first-seen order; the server stores blobs per manifest.+ /// The given hashes grouped by the manifest that owns them, in first-seen order.fn by_manifest(&self, hashes: &[String]) -> Vec<(String, Vec<String>)> {let mut groups: Vec<(String, Vec<String>)> = Vec::new();for hash in hashes {@@ -367,28 +354,12 @@ impl UploadBlobs {}}-/// The freshly generated key hierarchy for one migration push.-#[derive(zeroize::Zeroize, zeroize::ZeroizeOnDrop)]-struct LegacyAccountKeyMigration {- content_key: SecretString,-- /// Ciphertext only, so there is nothing here to wipe.- #[zeroize(skip)]- account_keys: crypto::AccountKeyBlobs,- account_private_key: String,- signing_private_key: String,-}--/// The content fingerprints one write carried, keyed like the baselines, to become the new baselines on success.+/// The content fingerprints one write carried, which become the baselines on success.type WrittenFingerprints = HashMap<String, String>;/// A byte or character count for log lines.fn format_kb(chars: usize) -> String {- if chars < 1024 {- format!("{} B", chars)- } else {- format!("{:.1} KB", chars as f64 / 1024.0)- }+ if chars < 1024 { format!("{} B", chars) } else { format!("{:.1} KB", chars as f64 / 1024.0) }}/// A payload as JSON text plus its content fingerprint.@@ -413,8 +384,7 @@ pub(crate) async fn encrypt_payload(ctx: &Ctx, label: &str, plaintext: &str, keyOk(EncryptedPayload { ciphertext, hash })}-/// Canonicalize, gate by content fingerprint, encrypt and `POST v2/Vault`. Returns the outcome and, on a-/// migration push, the new content key the session switches to.+/// Canonicalize, gate by content fingerprint, encrypt and `POST v2/Vault`; a migration push also returns the new content key.async fn write_manifests_and_buckets(ctx: &mut Ctx, cached: Option<CanonicalizedSet>, kind: WriteKind) -> SyncResult<(PushStatus, Option<SecretString>)> {let vek = ctx.encryption_key()?;@@ -425,7 +395,7 @@ async fn write_manifests_and_buckets(ctx: &mut Ctx, cached: Option<Canonicalized}let migration = start_account_key_migration(ctx, vek.expose_secret(), kind).await?;- let content_key = migration.as_ref().map(|m| m.content_key.clone()).unwrap_or_else(|| vek.clone());+ let content_key = migration.as_ref().map(|m| SecretString::from(m.vault_encryption_key.as_str())).unwrap_or_else(|| vek.clone());let set = match cached {Some(set) => {@@ -466,7 +436,6 @@ async fn write_manifests_and_buckets(ctx: &mut Ctx, cached: Option<Canonicalizedlet response = write_vault(ctx, &mut payload, &blobs, overwrite_personal_blobs, &mut uploaded).await?;if response.status != VaultWriteStatus::Ok {- // All-or-nothing: a single stale manifest or bucket rejected the whole write; the caller pulls, merges and retries.return Ok((PushStatus::Outdated, None));}@@ -476,23 +445,17 @@ async fn write_manifests_and_buckets(ctx: &mut Ctx, cached: Option<Canonicalizedcomplete_account_key_migration(ctx, migration).await?;ctx.log("[Push] Account-key migration complete: hierarchy created server-side, blob chain cached locally.").await;}- Ok((PushStatus::Ok, migration.map(|m| m.content_key.clone())))+ Ok((PushStatus::Ok, migration.map(|_| content_key)))}-/// Generate the account key hierarchy for a migration push. The session key of a legacy account is its unlock key,-/// which the hierarchy derives its KEK from.-async fn start_account_key_migration(ctx: &Ctx, unlock_key: &str, kind: WriteKind) -> SyncResult<Option<LegacyAccountKeyMigration>> {+/// The key hierarchy a migration push creates, with its KEK derived from the legacy session key (the unlock key).+async fn start_account_key_migration(ctx: &Ctx, unlock_key: &str, kind: WriteKind) -> SyncResult<Option<crypto::AccountKeyHierarchy>> {if kind != WriteKind::AccountKeyMigration {return Ok(None);}let hierarchy = crypto::create_account_key_hierarchy(unlock_key)?;ctx.log("[Push] Account-key migration: generated new VEK, AK, account keypair and signing keypair; vault content and all blobs will be re-encrypted and re-uploaded.").await;- Ok(Some(LegacyAccountKeyMigration {- content_key: SecretString::from(hierarchy.vault_encryption_key.as_str()),- account_keys: hierarchy.account_keys.clone(),- account_private_key: hierarchy.account_private_key.clone(),- signing_private_key: hierarchy.signing_private_key.clone(),- }))+ Ok(Some(hierarchy))}/// Every canonicalized manifest a record exists for, with the key it encrypts under.@@ -523,8 +486,7 @@ fn collect_upload_blobs(candidates: &[Candidate]) -> SyncResult<UploadBlobs> {Ok(blobs)}-/// A migration push uploads every personal blob again under the new key. A blob whose bytes are not loaded on this-/// device would keep its old server copy under the old key, never to open again, while its manifest moves on: refuse.+/// Refuse a migration push when a personal blob is not loaded on this device, since its server copy would stay under the old key.fn refuse_overwrite_without_bytes(candidates: &[Candidate], blobs: &UploadBlobs) -> SyncResult<()> {let not_loaded = candidates.iter().filter(|c| c.record.is_personal).flat_map(|c| c.manifest.referenced_blobs()).filter(|(hash, _)| !blobs.entries.contains_key(hash)).count();if not_loaded == 0 {@@ -614,8 +576,7 @@ async fn encrypt_changed_manifests(ctx: &Ctx, candidates: &[Candidate<'_>], baseOk(writes)}-/// Encrypt and upload only the blobs the server does not already have. On a migration push every personal-/// blob is re-encrypted under the new key and overwritten. Returns hash to ciphertext for the local cache.+/// Encrypt and upload the blobs the server lacks, or every personal blob on a migration push; returns hash to ciphertext.async fn upload_missing_blobs(ctx: &Ctx, blobs: &UploadBlobs, baselines: &PushBaselines, overwrite_personal_blobs: bool) -> SyncResult<HashMap<String, EncryptedBlob>> {let personal_hashes = blobs.hashes(true);let shared_hashes = blobs.hashes(false);@@ -646,8 +607,7 @@ async fn missing_on_server(ctx: &Ctx, blobs: &UploadBlobs, hashes: &[String]) ->Ok(missing)}-/// `POST v2/Vault`. When the server reports blobs it lacks (stale local knowledge of its blob set), upload-/// them and retry the identical write once; blobs this client cannot supply fail the push.+/// `POST v2/Vault`, uploading the blobs the server reports missing and retrying the same write once.async fn write_vault(ctx: &Ctx, payload: &mut VaultWriteRequest, blobs: &UploadBlobs, overwrite_personal_blobs: bool, uploaded: &mut HashMap<String, EncryptedBlob>) -> SyncResult<VaultWriteResponse> {let response: VaultWriteResponse = http::post_frame(&ctx.host, http::VAULT_ENDPOINT, payload).await?;if response.missing_blob_hashes.is_empty() {@@ -701,7 +661,7 @@ async fn commit_blob_baselines(ctx: &Ctx, blobs: &UploadBlobs, uploaded: &HashMa}/// Store the hierarchy a migration push just committed: cache the encrypted chain and stage the private keys.-async fn complete_account_key_migration(ctx: &mut Ctx, migration: &LegacyAccountKeyMigration) -> SyncResult<()> {+async fn complete_account_key_migration(ctx: &mut Ctx, migration: &crypto::AccountKeyHierarchy) -> SyncResult<()> {let blobs = &migration.account_keys;state::set(&ctx.host, state::ENCRYPTED_ACCOUNT_KEY, &blobs.encrypted_account_key).await?;state::set(&ctx.host, state::ENCRYPTED_VEK, &blobs.encrypted_vek).await?;@@ -715,8 +675,7 @@ async fn complete_account_key_migration(ctx: &mut Ctx, migration: &LegacyAccountOk(())}-/// Encrypt the given blobs (each under its own key) and upload them in size-capped batches per owning manifest.-/// Returns hash to ciphertext for the local encrypted blob cache.+/// Encrypt and upload the given blobs in batches per owning manifest; returns hash to ciphertext.async fn upload_blobs(ctx: &Ctx, blobs: &UploadBlobs, hashes: &[String], overwrite: bool) -> SyncResult<HashMap<String, EncryptedBlob>> {let mut encrypted_blobs = HashMap::new();for (manifest_id, hashes) in blobs.by_manifest(hashes) {diff --git a/core/rust/src/vault_sync/rotation.rs b/core/rust/src/vault_sync/rotation.rsindex e4fba1be0..25e8baea9 100644--- a/core/rust/src/vault_sync/rotation.rs+++ b/core/rust/src/vault_sync/rotation.rs@@ -208,7 +208,7 @@ async fn rotate(ctx: &mut Ctx) -> Outcome {let posted = build_and_post(ctx, ¶ms, &personal_manifest_id, &rotated, signing_key.expose_secret(), &new_vek, &vek, &shared_records, &shared_veks, &blob_keys.blob_keys, &certifications, &delivery_pair.public_key).await;match posted {Ok(Ok((applied, reencrypted_blob_keys, reencrypted_grants, fingerprints))) => {- adopt(ctx, ¶ms, &personal_manifest_id, &rotated, &new_vek, &applied, &reencrypted_blob_keys, &reencrypted_grants, &fingerprints).await?;+ store_rotated_keys(ctx, ¶ms, &personal_manifest_id, &rotated, &new_vek, &applied, &reencrypted_blob_keys, &reencrypted_grants, &fingerprints).await?;ctx.log("[KeyRotation] The server applied the rotation; this device now holds the new keys.").await;Ok(Ok((SecretString::from(rotated.account_key.as_str()), new_vek)))}@@ -402,10 +402,10 @@ fn ensure_opens(opens: bool, what: &str) -> SyncResult<()> {Err(SyncError::Other(format!("The rotation was not sent: {} does not open under the new keys.", what)))}-/// Take the new keys over: the cached chain, the derivation parameters, the revisions and fingerprints the server+/// Store the new keys: the cached chain, the derivation parameters, the revisions and fingerprints the server/// now holds, the blob keys and grants under the new keys, and the stored vault under the new VEK.#[allow(clippy::too_many_arguments)]-async fn adopt(ctx: &mut Ctx, params: &KeyRotationParams, personal_manifest_id: &str, rotated: &crypto::AccountKeyHierarchy, new_vek: &SecretString, applied: &Applied, reencrypted_blob_keys: &HashMap<String, String>, reencrypted_grants: &HashMap<String, SharedManifestDto>, fingerprints: &HashMap<String, String>) -> SyncResult<()> {+async fn store_rotated_keys(ctx: &mut Ctx, params: &KeyRotationParams, personal_manifest_id: &str, rotated: &crypto::AccountKeyHierarchy, new_vek: &SecretString, applied: &Applied, reencrypted_blob_keys: &HashMap<String, String>, reencrypted_grants: &HashMap<String, SharedManifestDto>, fingerprints: &HashMap<String, String>) -> SyncResult<()> {let blobs = &rotated.account_keys;state::set(&ctx.host, state::ENCRYPTED_ACCOUNT_KEY, &blobs.encrypted_account_key).await?;state::set(&ctx.host, state::ENCRYPTED_VEK, &blobs.encrypted_vek).await?;diff --git a/core/rust/src/vault_sync/session.rs b/core/rust/src/vault_sync/session.rsindex a76fe021d..a064ce69f 100644--- a/core/rust/src/vault_sync/session.rs+++ b/core/rust/src/vault_sync/session.rs@@ -18,10 +18,10 @@ use crate::sqlite_host::MemoryDatabase;#[derive(Default)]pub(crate) struct Slot {pub pending: Option<Command>,- /// Raw bytes sent with the pending command (the body of a binary `http` request), until the host takes them.+ /// Raw bytes sent with the pending command, until the host takes them.pub pending_bytes: Option<Vec<u8>>,pub response: Option<Value>,- /// Raw bytes the host handed back with the response (a `dbExport` file or a binary `http` response).+ /// Raw bytes the host handed back with the response.pub response_bytes: Option<Vec<u8>>,}@@ -52,12 +52,12 @@ impl Host {f(db).map_err(|e| SyncError::Staging(e.to_string()))}- /// Send a command and wait for the host's typed response. A `{ "error": ... }` response becomes an error.+ /// Send a command and wait for the host's typed response.pub async fn call<R: DeserializeOwned>(&self, command: Command) -> SyncResult<R> {Ok(self.call_with_bytes(command, None).await?.0)}- /// Like [`Host::call`], with raw bytes sent alongside the command and those the host attached to its response.+ /// Send a command with raw bytes and wait for the host's typed response plus the bytes it attached.pub async fn call_with_bytes<R: DeserializeOwned>(&self, command: Command, command_bytes: Option<Vec<u8>>) -> SyncResult<(R, Option<Vec<u8>>)> {let kind = command.name();let (response, bytes) = CommandFuture { slot: self.slot.clone(), command: Some(command), command_bytes, sent: false }.await;@@ -148,14 +148,14 @@ impl SyncSession {}}- /// Take the raw bytes attached to the last command (the body of a binary `http` request), if any.+ /// Take the raw bytes attached to the last command, if any.pub fn command_bytes(&self) -> VaultResult<Option<Vec<u8>>> {let inner = self.inner.lock().map_err(|_| VaultError::General("sync session poisoned".to_string()))?;let mut slot = inner.slot.lock().map_err(|_| VaultError::General("sync host slot poisoned".to_string()))?;Ok(slot.pending_bytes.take())}- /// Hand the host's response to the last command back, with raw bytes for a `dbExport` or a binary `http` response.+ /// Hand the host's response to the last command back, with any raw bytes the host attached.pub fn resume(&self, response_json: &str, bytes: Option<Vec<u8>>) -> VaultResult<()> {let response: Value = if response_json.trim().is_empty() {Value::Object(Default::default())diff --git a/core/rust/src/vault_sync/sharing.rs b/core/rust/src/vault_sync/sharing.rsindex 3af6d1315..166d7ea1f 100644--- a/core/rust/src/vault_sync/sharing.rs+++ b/core/rust/src/vault_sync/sharing.rs@@ -1,16 +1,9 @@-//! The sharing operations that take vault keys or sign something: creating a group's shared manifest, updating one,-//! inviting to a group or a shared manifest, accepting those invitations, moving an email alias to another manifest, and-//! approving a Login with Mobile request.-//!-//! Trust between two accounts rests on key certifications: once a user has checked another account's signing key (outside-//! AliasVault) against that account's account fingerprint (the key's fingerprint), a client signs a-//! statement that the served key belongs to that account. A certification is only ever checked under the certifier's own signing key,-//! derived from their private key, so the server can hide one but not forge one. An admin certifies a member before inviting them anywhere;-//! a member certifies the admin before accepting anything from them. A grant opens only once signed by its holder.+//! The sharing operations that take vault keys or sign something: creating and updating a shared manifest, inviting to+//! one, accepting an invitation, moving an email alias to another manifest and approving a Login with Mobile request.use std::collections::HashMap;-use secrecy::ExposeSecret;+use secrecy::{ExposeSecret, SecretString};use serde::{Deserialize, Serialize};use super::errors::{SyncError, SyncResult};@@ -24,35 +17,36 @@ use crate::vault_model::{id_key, ids_equal};/// The role of a group member who may not administer it.const ROLE_MEMBER: &str = "member";-/// The API error code for a recipient whose account has no keypair yet (legacy non-migrated user account).+/// The API error code for a recipient whose account has no keypair yet.const INVITE_RECIPIENT_NOT_READY: &str = "INVITE_RECIPIENT_NOT_READY";-/// The API error code for a member whose signing key this account has not certified with their account fingerprint.+/// The API error code for a member whose signing key this account has not certified.const MEMBER_NOT_VERIFIED: &str = "MEMBER_NOT_VERIFIED";-/// The API error code for an inviter whose signing key this account has not certified with their account fingerprint.+/// The API error code for an inviter whose signing key this account has not certified.const INVITER_NOT_VERIFIED: &str = "INVITER_NOT_VERIFIED";/// The refusal code for an account fingerprint that is not the fingerprint of the key the server served.const ACCOUNT_FINGERPRINT_MISMATCH: &str = "ACCOUNT_FINGERPRINT_MISMATCH";-/// The refusal code for an account fingerprint that is this account's own, typed where the other person's code was asked for.+/// The refusal code for an account fingerprint that is this account's own.const ACCOUNT_FINGERPRINT_IS_OWN: &str = "ACCOUNT_FINGERPRINT_IS_OWN";-/// The longest name an invitation can carry: RSA-2048 OAEP-SHA256 fits 190 bytes. The UI caps names well below this.+/// The longest name an invitation can carry, the RSA-2048 OAEP-SHA256 plaintext limit.const MAX_SHARED_MANIFEST_NAME_BYTES: usize = 190;+/// `GET v2/Groups`.#[derive(Debug, Clone, Default, Deserialize)]#[serde(rename_all = "camelCase")]struct GroupOverview {- /// The caller's own user id, which the certifications and grants it signs name.+ /// The caller's own user id.#[serde(default)]user_id: String,#[serde(default)]groups: Vec<GroupInfo>,#[serde(default)]received_invitations: Vec<ReceivedManifestInvitation>,- /// The people whose current signing key the caller certified, who can be invited without their account fingerprint.+ /// The people whose current signing key the caller certified.#[serde(default)]verified_people: Vec<GroupMemberInfo>,}@@ -80,7 +74,7 @@ struct ReceivedManifestInvitation {recipient_account_public_key: Option<String>,#[serde(default)]algorithm: String,- /// This account's certification of `signer_public_key`, when it certified the inviter before.+ /// This account's certification of `signer_public_key`, if it made one.#[serde(default)]inviter_certification: Option<String>,}@@ -91,6 +85,7 @@ struct AccountFingerprintLookupRequest<'a> {code: &'a str,}+/// `POST v2/Groups/lookup`.#[derive(Debug, Clone, Deserialize)]#[serde(rename_all = "camelCase")]struct AccountFingerprintLookupResponse {@@ -106,16 +101,6 @@ struct AccountFingerprintLookupResponse {account_public_key_signature: Option<String>,}-/// The account a shared manifest's key is encrypted for: a group member, or an account found by its account fingerprint.-struct Recipient {- user_id: String,- username: String,- account_public_key: Option<String>,- account_public_key_id: Option<String>,- account_public_key_signature: Option<String>,- signing_public_key: Option<String>,-}-#[derive(Debug, Serialize)]#[serde(rename_all = "camelCase")]struct CertifyKeyRequest<'a> {@@ -170,6 +155,7 @@ struct GroupManifestInfo {key_version: i64,}+/// A group member or verified person, and the recipient a shared manifest's key is encrypted for.#[derive(Debug, Clone, Default, Deserialize)]#[serde(rename_all = "camelCase")]struct GroupMemberInfo {@@ -184,7 +170,7 @@ struct GroupMemberInfo {account_public_key_signature: Option<String>,#[serde(default)]signing_public_key: Option<String>,- /// This account's certification of `signing_public_key`, made when it checked the member's account fingerprint.+ /// This account's certification of `signing_public_key`, if it made one.#[serde(default)]key_certification: Option<String>,}@@ -207,6 +193,7 @@ struct UpdateSharedManifestRequest<'a> {encrypted_name: Option<&'a str>,}+/// `POST v2/Groups/manifests`.#[derive(Debug, Deserialize)]#[serde(rename_all = "camelCase")]struct CreateSharedManifestResponse {@@ -318,7 +305,7 @@ async fn finish(ctx: &Ctx, what: &str, outcome: Outcome) -> SharingOperationResu}}-/// A refusal the sharing screen has words for: only the API error code, no engine failure.+/// A result that carries only an API error code.fn refused(code: String) -> SharingOperationResult {SharingOperationResult { failure: FailureFields { api_error_code: Some(code), ..Default::default() }, ..Default::default() }}@@ -338,7 +325,7 @@ fn invitation_id(target: &SharingParams) -> SyncResult<String> {target.invitation_id.clone().ok_or_else(|| SyncError::Other("The sharing operation names no invitation".to_string()))}-/// `GET Groups`: the caller's groups and open invitations, with the caller's own user id.+/// `GET v2/Groups`: the caller's groups, open invitations and own user id.async fn fetch_overview(ctx: &Ctx) -> SyncResult<GroupOverview> {let overview: GroupOverview = http::get(&ctx.host, "Groups", false).await?;if overview.user_id.is_empty() {@@ -366,10 +353,18 @@ fn check_name_length(name: &str) -> SyncResult<()> {Ok(())}-/// This account as a signer: its user id, which everything it signs names, and its signing keys (public key derived from the private one).+/*+ * Trust between two accounts rests on key certifications: after checking another account's signing key against the+ * account fingerprint that person gave them outside AliasVault, a user signs that the served key belongs to that+ * account. A certification is only ever checked under the certifier's own signing key, derived from their private key,+ * so the server can hide one but not forge one. An admin certifies a member before inviting them anywhere; a member+ * certifies the admin before accepting anything from them. A grant opens only once signed by its holder.+ */++/// This account as a signer: its user id and its signing keypair.struct OwnIdentity {user_id: String,- signing_key: secrecy::SecretString,+ signing_key: SecretString,signing_public_key: String,}@@ -395,8 +390,7 @@ impl OwnIdentity {certification.is_some_and(|certification| crypto::signing::verify(&self.signing_public_key, &crypto::signing::key_certification_message(&self.user_id, subject_user_id, subject_key), certification))}- /// Make sure this account certified `subject_key` as `subject_user_id`'s: before (`certification`), or now from the- /// typed `account_fingerprint`. Without either, the refusal says whose fingerprint is needed (`not_verified`).+ /// Make sure this account certified `subject_key` as `subject_user_id`'s, before or now from `account_fingerprint`; refuse with `not_verified` otherwise.async fn ensure_certified(&self, ctx: &Ctx, subject_user_id: &str, subject_key: &str, certification: Option<&str>, account_fingerprint: Option<&str>, not_verified: &str) -> SyncResult<Result<(), Refusal>> {if self.certified(subject_user_id, subject_key, certification) {return Ok(Ok(()));@@ -407,7 +401,7 @@ impl OwnIdentity {}}- /// Certify `subject_key` as `subject_user_id`'s after checking it against the account fingerprint the user typed, and store the certification.+ /// Check `subject_key` against the typed account fingerprint and store this account's certification of it.async fn certify_with_fingerprint(&self, ctx: &Ctx, subject_user_id: &str, subject_key: &str, code: &str) -> SyncResult<Result<(), Refusal>> {if self.is_own_fingerprint(code) {return Ok(Err(Refusal::Api(ACCOUNT_FINGERPRINT_IS_OWN.to_string())));@@ -422,7 +416,7 @@ impl OwnIdentity {}}-/// The VEK generation a new shared manifest starts at; its self-grant is signed over it.+/// The key version a new shared manifest starts at.const NEW_MANIFEST_KEY_VERSION: i64 = 0;async fn create_shared_manifest(ctx: &mut Ctx) -> Outcome {@@ -433,8 +427,6 @@ async fn create_shared_manifest(ctx: &mut Ctx) -> Outcome {let overview = fetch_overview(ctx).await?;- // The new manifest's VEK is encrypted only for this account's own public key upon creation, other users are invited separately.- // The server creates a group for it, owned by this account.let Some(self_public_key) = keys::own_account_public_key(ctx).await? else { return Ok(Err(Refusal::VaultUpgradeRequired)) };let Some(me) = OwnIdentity::open(ctx, &overview).await? else { return Ok(Err(Refusal::VaultUpgradeRequired)) };if state::get::<String>(&ctx.host, state::VAULT_PERSONAL_MANIFEST_ID).await?.is_none() {@@ -444,18 +436,14 @@ async fn create_shared_manifest(ctx: &mut Ctx) -> Outcome {return Ok(Err(Refusal::VaultUpgradeRequired));}+ // The VEK is encrypted for this account's own key only; other members are invited separately.let manifest_vek = crypto::aes_gcm::generate_key();let requested_id = db::new_id();let self_encrypted_vek = keys::encrypt_manifest_vek(&manifest_vek, &requested_id, &self_public_key)?;let self_grant_signature = me.sign(&crypto::signing::grant_message(&requested_id, NEW_MANIFEST_KEY_VERSION, &me.user_id, &self_public_key, ALGORITHM_RSA_OAEP_SHA256, &self_encrypted_vek))?;let encrypted_name = pull::encrypt_manifest_name(&name, &requested_id, &manifest_vek)?;- let response: CreateSharedManifestResponse = http::post(- &ctx.host,- "Groups/manifests",- &CreateSharedManifestRequest { manifest_id: &requested_id, self_encrypted_vek: &self_encrypted_vek, self_account_public_key: &self_public_key, algorithm: ALGORITHM_RSA_OAEP_SHA256, self_grant_signature: &self_grant_signature, encrypted_name: Some(&encrypted_name) },- false,- )- .await?;+ let request = CreateSharedManifestRequest { manifest_id: &requested_id, self_encrypted_vek: &self_encrypted_vek, self_account_public_key: &self_public_key, algorithm: ALGORITHM_RSA_OAEP_SHA256, self_grant_signature: &self_grant_signature, encrypted_name: Some(&encrypted_name) };+ let response: CreateSharedManifestResponse = http::post(&ctx.host, "Groups/manifests", &request, false).await?;let manifest_id = response.manifest_id;if !ids_equal(&manifest_id, &requested_id) {return Err(SyncError::Other(format!("The server created shared manifest {} instead of the requested {}, whose key and name are bound to the requested id", manifest_id, requested_id)));@@ -487,14 +475,14 @@ async fn create_shared_manifest(ctx: &mut Ctx) -> Outcome {let delivery_keys = crypto::generate_rsa_key_pair()?;db::set_active_key_for_manifest(&ctx.host, &manifest_id, &delivery_keys.public_key, &delivery_keys.private_key).await?;- // The name and keypair ride out on the host's next sync, which the dirty flag asks for.+ // The dirty flag makes the host's next sync push the name and keypair.ctx.persist_local_vault(true).await?;ctx.log(format!("[Sharing] Created shared manifest {} with group {}.", manifest_id, response.group_id)).await;Ok(Ok(Done::manifest(manifest_id)))}-/// The details an update can change (e.g. the name of a shared manifest).+/// Rename a shared manifest.async fn update_shared_manifest(ctx: &mut Ctx) -> Outcome {let key = ctx.encryption_key()?;let target = params(ctx)?;@@ -535,10 +523,7 @@ async fn invite_to_shared_manifest(ctx: &mut Ctx) -> Outcome {let manifest = group.manifests.iter().find(|candidate| ids_equal(&candidate.manifest_id, &manifest_id)).ok_or_else(|| SyncError::Other("The shared manifest does not belong to the group".to_string()))?;let Some(me) = OwnIdentity::open(ctx, &overview).await? else { return Ok(Err(Refusal::VaultUpgradeRequired)) };- /*- * The recipient is either an account found by the account fingerprint the user typed, whose key is certified with it now- * (accepting then also makes them a member), or a member this account certified before.- */+ // The recipient is an account found by a typed account fingerprint, certified with it now, or a member or verified person certified before.let recipient = match target.account_fingerprint.as_deref().map(str::trim).filter(|code| !code.is_empty()) {Some(code) => {if me.is_own_fingerprint(code) {@@ -548,43 +533,34 @@ async fn invite_to_shared_manifest(ctx: &mut Ctx) -> Outcome {if let Err(refusal) = me.certify_with_fingerprint(ctx, &account.user_id, &account.signing_public_key, code).await? {return Ok(Err(refusal));}- Recipient {+ GroupMemberInfo {user_id: account.user_id,username: account.username,- account_public_key: account.account_public_key,account_public_key_id: account.account_public_key_id,+ account_public_key: account.account_public_key,account_public_key_signature: account.account_public_key_signature,signing_public_key: Some(account.signing_public_key),+ key_certification: None,}}None => {- // A member of the group, or a person verified before who is not in it yet.let user_id = target.user_id.clone().ok_or_else(|| SyncError::Other("The invitation names no recipient".to_string()))?;let member = group.members.iter().chain(overview.verified_people.iter()).find(|candidate| candidate.user_id == user_id).ok_or_else(|| SyncError::Other("The recipient is neither in the group nor verified".to_string()))?;- // The served signing key is trusted only through this account's own certification of it, made with the member's account fingerprint.if member.signing_public_key.as_deref().is_some_and(|key| !me.certified(&member.user_id, key, member.key_certification.as_deref())) {return Ok(Err(Refusal::Api(MEMBER_NOT_VERIFIED.to_string())));}- Recipient {- user_id: member.user_id.clone(),- username: member.username.clone(),- account_public_key: member.account_public_key.clone(),- account_public_key_id: member.account_public_key_id.clone(),- account_public_key_signature: member.account_public_key_signature.clone(),- signing_public_key: member.signing_public_key.clone(),- }+ member.clone()}};let (Some(recipient_public_key), Some(recipient_public_key_id), Some(signature), Some(signing_public_key)) = (recipient.account_public_key.clone(), recipient.account_public_key_id.clone(), recipient.account_public_key_signature.as_deref(), recipient.signing_public_key.as_deref()) else {return Ok(Err(Refusal::Api(INVITE_RECIPIENT_NOT_READY.to_string())));};- // Only encrypt the key for a public key its owner signed with their (certified) signing key.+ // Only encrypt the key for a public key its owner signed with their certified signing key.if !crypto::signing::verify(signing_public_key, &crypto::signing::account_public_key_message(&recipient_public_key), signature) {return Err(SyncError::Other(format!("The public key of {} carries no valid signature by their signing key", recipient.user_id)));}- // Find this account's own grant on the manifest.let mut record = held_record(ctx, &manifest.manifest_id).await?;if record.is_none() {ctx.warn(format!("[Sharing] No key record stored for shared manifest {}; pulling to re-record it before inviting.", manifest.manifest_id)).await;@@ -608,20 +584,15 @@ async fn invite_to_shared_manifest(ctx: &mut Ctx) -> Outcome {encrypted_name,};- http::post_no_content(- &ctx.host,- &format!("Groups/{}/manifests/{}/access", group.group_id, manifest.manifest_id),- &GrantManifestAccessRequest { user_id: &recipient.user_id, grant, algorithm: ALGORITHM_RSA_OAEP_SHA256 },- )- .await?;+ let request = GrantManifestAccessRequest { user_id: &recipient.user_id, grant, algorithm: ALGORITHM_RSA_OAEP_SHA256 };+ http::post_no_content(&ctx.host, &format!("Groups/{}/manifests/{}/access", group.group_id, manifest.manifest_id), &request).await?;ctx.log(format!("[Sharing] Invited {} to shared manifest {} with its key encrypted for them.", recipient.user_id, manifest.manifest_id)).await;Ok(Ok(Done { manifest_id: Some(manifest.manifest_id.clone()), username: Some(recipient.username), ..Default::default() }))}-/// Look up the account behind an account fingerprint and check the fingerprint against the key the server returns, so the user can-/// confirm who they invite, also before the folder they invite to is shared. Nothing is certified or invited;-/// `invite_to_shared_manifest` looks the fingerprint up again. With a group, the result says whether the account is in it.+/// Look up the account behind an account fingerprint and check the fingerprint against the served key, without certifying+/// or inviting it; with a group, the result says whether the account is in it.async fn lookup_account_fingerprint(ctx: &mut Ctx) -> Outcome {let target = params(ctx)?;let code = target.account_fingerprint.as_deref().map(str::trim).filter(|code| !code.is_empty()).ok_or_else(|| SyncError::Other("The lookup carries no account fingerprint".to_string()))?;@@ -658,7 +629,7 @@ async fn transfer_email_claim(ctx: &mut Ctx) -> Outcome {}/// Hand the Account Key, encrypted for the requesting client, to a Login with Mobile request, signed with this account's-/// own key so a stolen session token alone cannot approve a request. An account without a signing key yet sends it unsigned.+/// own key so a stolen session token alone cannot approve a request.async fn approve_mobile_login(ctx: &mut Ctx) -> Outcome {let target = params(ctx)?;let request_id = target.request_id.as_deref().ok_or_else(|| SyncError::Other("The approval names no request".to_string()))?;@@ -666,6 +637,7 @@ async fn approve_mobile_login(ctx: &mut Ctx) -> Outcome {let algorithm = target.algorithm.as_deref().ok_or_else(|| SyncError::Other("The approval names no algorithm".to_string()))?;let signature = match keys::signing_private_key(ctx).await? {Some(signing_key) => Some(crypto::signing::sign(signing_key.expose_secret(), &crypto::signing::mobile_login_approval_message(request_id, algorithm, encrypted_account_key))?),+ // LEGACY: an account without a signing key yet sends the approval unsigned. TODO: remove once every account has upgraded.None => None,};http::post_no_content(&ctx.host, "Auth/mobile-login/submit", &MobileLoginSubmitRequest { request_id, encrypted_account_key, algorithm, signature }).await?;@@ -673,8 +645,8 @@ async fn approve_mobile_login(ctx: &mut Ctx) -> Outcome {Ok(Ok(Done::default()))}-/// Accept an invitation to a shared manifest: check the certified inviter signed it and the key inside opens for this-/// account, then sign the grant as this account's own.+/// Accept an invitation to a shared manifest: check that the certified inviter signed it and that the key inside opens for+/// this account, then sign the grant as this account's own.async fn accept_shared_manifest_invitation(ctx: &mut Ctx) -> Outcome {ctx.encryption_key()?;let target = params(ctx)?;@@ -695,7 +667,7 @@ async fn accept_shared_manifest_invitation(ctx: &mut Ctx) -> Outcome {return Ok(Err(refusal));}- // The offer has to be the certified inviter's own work, made out to this account's key, and the key inside has to open.+ // The grant and the name have to be signed by the certified inviter, made out to this account's key, and the key inside has to open.let grant_message = crypto::signing::grant_message(&invitation.manifest_id, invitation.key_version, &invitation.inviter_user_id, recipient_public_key, &invitation.algorithm, encrypted_vek);if !crypto::signing::verify(signer_public_key, &grant_message, grant_signature) {return Err(SyncError::Other(format!("The grant in invitation {} is not signed by the inviter", invitation.id)));diff --git a/core/rust/src/vault_sync/state.rs b/core/rust/src/vault_sync/state.rsindex faa7f6c4c..f193ee0d5 100644--- a/core/rust/src/vault_sync/state.rs+++ b/core/rust/src/vault_sync/state.rs@@ -32,13 +32,13 @@ pub(crate) struct Ctx {pub vault_key_probed: bool,pub served_manifest_names: HashMap<String, String>,has_local_vault: bool,- /// The stored vault did not decrypt with the session key, so this run treats it as absent until a store replaces it.+ /// The stored vault did not decrypt, so this run treats it as absent until a store replaces it.local_vault_discarded: bool,/// The VEK of every shared manifest this account holds a grant on, decrypted once per run.shared_veks: Mutex<Option<HashMap<String, SecretString>>>,}-/// What a fresh staging database tells about the current client schema.+/// The current client schema.#[derive(Debug, Clone)]pub(crate) struct SchemaInfo {pub columns: HashMap<String, Vec<String>>,@@ -105,7 +105,7 @@ impl Ctx {Ok(stored)}- /// Re-read a failed local database command as `VaultDecryptFailed` when the stored vault does not decrypt with the session key.+ /// Report a failed local database command as `VaultDecryptFailed` when the stored vault does not decrypt.pub async fn diagnose_local_vault_failure(&self, error: SyncError) -> SyncError {if !matches!(error, SyncError::Host { command: "dbQuery" | "dbExec" | "dbExport", .. }) {return error;@@ -118,8 +118,7 @@ impl Ctx {}}- /// Write the local database as the at-rest vault under the session key. `dirty` records it as a pending change- /// the next push carries; a clean store only refreshes what the host shows.+ /// Write the local database as the at-rest vault under the session key, `dirty` marking it as a pending change.pub async fn persist_local_vault(&mut self, dirty: bool) -> SyncResult<()> {let key = self.encryption_key()?;let bytes = db::export(&self.host, Db::Local).await?;@@ -148,7 +147,7 @@ impl Ctx {self.shared_veks.lock().unwrap_or_else(|poisoned| poisoned.into_inner()).clone()}- /// Remember the decrypted shared-manifest keys; `None` forgets them (the records changed).+ /// Remember the decrypted shared-manifest keys; `None` forgets them.pub fn cache_shared_veks(&self, veks: Option<HashMap<String, SecretString>>) {*self.shared_veks.lock().unwrap_or_else(|poisoned| poisoned.into_inner()) = veks;}diff --git a/core/rust/src/vault_sync/types.rs b/core/rust/src/vault_sync/types.rsindex f765d57f2..d8b7f7e0e 100644--- a/core/rust/src/vault_sync/types.rs+++ b/core/rust/src/vault_sync/types.rs@@ -15,7 +15,7 @@ use crate::sqlite_host::SqlStatement;#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub enum SyncOperation {- /// Status check, server-directed changes, then pull (and merge) or push based on the revision counters.+ /// Pull (and merge) or push, as the revisions decide.FullSync,/// Classify the pending local migration.MigrationStatus,@@ -23,29 +23,27 @@ pub enum SyncOperation {MigrateManifest,/// Run a status check.StatusCheck,- /// Open the account's key chain with the password-derived key right after login; see `ResolveVaultKeyResult`.+ /// Open the account's key chain with the password-derived key right after login.ResolveVaultKey,- /// Create a shared manifest, with a group of its own that this account owns; see `SharingParams`.+ /// Create a shared manifest, with a group of its own that this account owns.CreateSharedManifest,- /// Invite somebody to a shared manifest (by account fingerprint, or a person verified before), handing them its key encrypted- /// for their account keypair.+ /// Invite somebody to a shared manifest, handing them its key encrypted for their account keypair.InviteToSharedManifest,- /// Change the details of a shared manifest (its name); the server refuses anyone but an administrator of its group.+ /// Change the name of a shared manifest.UpdateSharedManifest,- /// Find the account behind an account fingerprint and check the fingerprint against its key, without certifying or inviting it.+ /// Find the account behind an account fingerprint and check the fingerprint against its key.LookupAccountFingerprint,/// Accept an invitation to a shared manifest, signing the grant with this account's own key.AcceptSharedManifestInvitation,- /// Rotate the account's keys and re-encrypt the personal vault under them; see `KeyRotationParams`.+ /// Rotate the account's keys and re-encrypt the personal vault under them.RotateAccountKeys,- /// Move an email alias to another manifest (`SharingParams.manifest_id`), signed with this account's own key.+ /// Move an email alias to another manifest, signed with this account's own key.TransferEmailClaim,/// Approve a Login with Mobile request with the Account Key encrypted for the requesting client, signed with this account's own key.ApproveMobileLogin,}-/// What a key rotation needs from the host: the proof of the current password and the new unlock method, both-/// derived from the master password on the host.+/// What a key rotation needs from the host: the proof of the current password and the new unlock method.#[derive(Debug, Clone, Deserialize)]#[serde(rename_all = "camelCase")]pub struct KeyRotationParams {@@ -98,7 +96,7 @@ pub struct SharingParams {pub algorithm: Option<String>,}-/// Sync request.+/// What the host starts a session with.#[derive(Debug, Clone, Deserialize)]#[serde(rename_all = "camelCase")]pub struct SyncRequest {@@ -224,8 +222,7 @@ pub struct MigrateManifestResult {pub failure: FailureFields,}-/// Outcome of the login-time key resolution: the vault key the host stores as its session key (the VEK behind-/// the account's key chain, or the password-derived key itself for a legacy account without a chain).+/// Outcome of the login-time key resolution: the vault key the host stores as its session key.#[derive(Debug, Clone, Default, Serialize, Deserialize)]#[serde(rename_all = "camelCase")]pub struct ResolveVaultKeyResult {@@ -253,8 +250,8 @@ pub struct SharingOperationResult {pub already_member: bool,/// The vault (or the account's key hierarchy) has to finish upgrading before it can be shared.pub vault_upgrade_required: bool,- /// A refusal carries only `failure.api_error_code` (e.g. `INVITATION_ALREADY_EXISTS`), which the sharing screen has- /// words for. `INVITE_RECIPIENT_NOT_READY` is also reported when the engine sees the recipient has no key yet.+ /// A refusal carries only `failure.api_error_code`; the engine reports `INVITE_RECIPIENT_NOT_READY` itself when the+ /// recipient has no key yet.#[serde(flatten)]pub failure: FailureFields,}@@ -320,7 +317,6 @@ pub struct StatusCheckResult {pub enum HttpMethod {Get,Post,- Delete,}/// The databases the engine reads and writes.@@ -328,13 +324,11 @@ pub enum HttpMethod {pub enum Db {/// The vault the host has open, reached through the `db*` commands.Local,- /// A throwaway database the engine keeps in-process: it materializes a pulled vault into it before that- /// becomes the new local vault, and probes the current client schema by opening a fresh one.+ /// A throwaway in-process database a pulled vault is materialized into, which also probes the current client schema.Staging,}-/// The levels of a `log` command. `Phase` carries a sync phase (`pull` or `push`) for a host that shows what-/// the sync is doing; the others are development logging a host may ignore.+/// The levels of a `log` command; `Phase` carries the sync phase (`pull` or `push`) for the host to show.#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]#[serde(rename_all = "lowercase")]pub enum LogLevel {@@ -354,12 +348,12 @@ pub enum Command {#[serde(skip_serializing_if = "Option::is_none")]body: Option<String>,auth: bool,- /// A vault transfer, which the host may give a longer timeout than a status call (which uses default).+ /// A vault transfer, which the host may give a longer timeout.large_transfer: bool,- /// On success the host returns the body as raw bytes (the `bytes` argument of `SyncSession::resume`), not as `body` text.+ /// On success the host returns the body as raw bytes through `SyncSession::resume`, not as `body` text.#[serde(default, skip_serializing_if = "std::ops::Not::not")]binary_response: bool,- /// The request body is raw bytes, which the host takes with `SyncSession::command_bytes` and sends as `application/octet-stream`.+ /// The request body is raw bytes, taken with `SyncSession::command_bytes` and sent as `application/octet-stream`.#[serde(default, skip_serializing_if = "std::ops::Not::not")]binary_body: bool,},@@ -373,8 +367,7 @@ pub enum Command {DbQuery { sql: String, params: Vec<Value> },/// Run statements on the local vault inside one transaction; response [`Ack`]. A `{ "__b64": ... }` parameter binds a BLOB.DbExec { statements: Vec<SqlStatement> },- /// Serialize the local vault; response [`Ack`], with the SQLite file handed back as raw bytes through- /// `SyncSession::resume` (never base64 inside the JSON).+ /// Serialize the local vault; response [`Ack`], with the SQLite file as raw bytes through `SyncSession::resume`.DbExport,/// Persist the at-rest vault blob; response [`StoreOutcome`].VaultStore {@@ -398,7 +391,7 @@ pub enum Command {}impl Command {- /// The command's wire tag (`dbExec`), as error reports name it.+ /// The command's wire tag, as error reports name it.pub fn name(&self) -> &'static str {match self {Command::Http { .. } => "http",@@ -709,11 +702,11 @@ impl FrameBody for VaultWriteRequest {}}-/// One-time migrations applied atomically with a vault write (optional field).+/// One-time migrations applied with a vault write.#[derive(Debug, Clone, Serialize)]#[serde(rename_all = "camelCase")]pub struct VaultWriteMigration {- /// The newly created key hierarchy for a legacy vault's first manifest-v1 push (pre-0.31.0).+ /// LEGACY: the key hierarchy a pre-0.31.0 account's first manifest-v1 push creates.#[serde(skip_serializing_if = "Option::is_none")]pub account_keys: Option<crate::crypto::AccountKeyBlobs>,}@@ -819,7 +812,9 @@ pub struct VaultKeyResponse {pub struct SharedManifestDto {pub manifest_id: String,pub encrypted_vek: String,- /// The account public key the grant was encrypted to (stored as `encryptionPublicKey` before 0.31.0 shipped).+ /// The account public key the grant was encrypted to.+ // LEGACY: builds before 0.31.0 stored this record with `encryptionPublicKey`. TODO: remove the alias once every+ // client has re-stored its records on 0.31.0+.#[serde(alias = "encryptionPublicKey")]pub account_public_key: String,pub algorithm: String,diff --git a/core/rust/src/vault_sync/write_set.rs b/core/rust/src/vault_sync/write_set.rsindex fac0a1395..629dcbdfb 100644--- a/core/rust/src/vault_sync/write_set.rs+++ b/core/rust/src/vault_sync/write_set.rs@@ -1,5 +1,4 @@-//! Which manifests a push writes, and which rows it may not: a row stamped for a manifest this session cannot-//! write has no namespace to go to, so a push holding one is refused until a pull restores the vault.+//! Which manifests a push writes, and which manifests in the vault it cannot.use std::collections::HashMap;@@ -23,14 +22,13 @@ pub(crate) struct ManifestRecord {/// Why a held shared manifest is left out of a write.#[derive(Debug, Clone, Copy, PartialEq, Eq)]pub(crate) enum SkipReason {- /// The vault holds no rows for it, so writing it would empty it server-side.+ /// The vault holds no rows for it.NoRowsInVault,- /// Its grant did not decrypt in this session.+ /// Its grant did not open in this session.KeyDidNotOpen,}-/// The manifests the next push writes, personal first, plus the held shared manifests left out and why. A shared-/// manifest is written when the vault holds rows for it (`stamped`) and its key opened (`opened`, id to VEK).+/// The manifests the next push writes, personal first, plus the held shared manifests left out and why.pub(crate) fn resolve_write_set(personal_manifest_id: &str, personal_salt: &str, stamped: &[String], opened: &HashMap<String, SecretString>, held: &HashMap<String, SharedManifestDto>) -> (Vec<ManifestRecord>, Vec<(String, SkipReason)>) {let mut records = vec![ManifestRecord { manifest_id: personal_manifest_id.to_string(), is_personal: true, salt: personal_salt.to_string(), can_administer: false, vek: None }];let mut skipped = Vec::new();