Skip to content

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.ts
index 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.tsx
index 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.cs
index 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.ts
index 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.ts
index 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.ts
index 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.cjs
index 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.ts
index 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 the
diff --git a/core/rust/src/bindings/uniffi_api.rs b/core/rust/src/bindings/uniffi_api.rs
index 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.rs
index 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.rs
index 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.rs
index 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 filter
pub 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(&current_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, &current_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(&current_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, &current, 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(&current.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(&current_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_subdomai
continue;
}
- // 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_subdomai
best
}
-/// 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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::LanguageD
return 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::LanguageD
if 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.rs
index 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.rs
index 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 name
0 => format!("{}{}", first_chars(&first, 1), last),
- // Full name
1 => format!("{}{}", first, last),
- // First name + last initial
2 => 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.rs
index 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) -> St
password.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: &mut
mandatory
}
-/// 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.rs
index 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, S
const 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) -> St
add_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.rs
index 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.rs
index 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.rs
index 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.rs
index 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<Canonic
return 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<Canonic
normalize_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, overfl
DataBucket { 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<Strin
grouped
}
-/// 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: &s
Ok(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.rs
index 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.rs
index 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.rs
index 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: &CodecR
return;
}
- // 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.rs
index 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.rs
index 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<Materialize
let 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<Materialize
Ok(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.rs
index 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.rs
index 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: &HashSe
for ((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: &HashSe
row.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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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 at
diff --git a/core/rust/src/vault_codec/types.rs b/core/rust/src/vault_codec/types.rs
index 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.rs
index 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.rs
index 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<Date
return 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<Date
live.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.rs
index 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>) -> CanonicalMan
CanonicalManifestMerge { 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.rs
index 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.rs
index 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 database
pub 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.rs
index 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 deleted
pub 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 pruned
pub stats: PruneStats,
}
/// A per-table SELECT query for building `PruneInput`.
#[derive(Debug, Clone)]
pub struct PruneTableQuery {
- /// Table name
pub name: String,
- /// SELECT query reading only the columns the pruner inspects
pub 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<(S
expired
}
-/// 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.rs
index 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.rs
index 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.rs
index 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<Vec
Ok(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 WHERE
const 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.rs
index 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.rs
index 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, ResolveVaultKeyResul
use 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, FullS
if 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<LogoutRea
server_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) -> SyncR
Ok(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_change
let 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.rs
index 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.rs
index 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.rs
index 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, larg
async 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>(ho
parse(&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) -> u
batches
}
-/// 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.rs
index 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) -> Syn
Ok(())
}
-/// 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_k
Ok(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<Strin
Ok(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) -> SyncRes
ctx.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) -> Sy
Ok(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, priva
std::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.rs
index 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.rs
index 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<PullAndMergeOutc
let 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<PullAndMergeOutc
match 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.rs
index 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: Op
Ok(())
}
-/// 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.rs
index 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.rs
index 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, snapshot
continue;
}
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) -> SyncRes
Ok(())
}
-/// 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_ke
if !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.rs
index 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, SecretStrin
Ok(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, Canonicalize
Ok(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<Pus
Ok(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>, kind
ctx.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, key
Ok(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<Canonicalized
let 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<Canonicalized
complete_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<'_>], base
Ok(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: &LegacyAccount
Ok(())
}
-/// 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.rs
index 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, &params, &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, &params, &personal_manifest_id, &rotated, &new_vek, &applied, &reencrypted_blob_keys, &reencrypted_grants, &fingerprints).await?;
+ store_rotated_keys(ctx, &params, &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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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();