Skip to content

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

27.8 KB
Raw Blame
//! Pull: fetch the server snapshot, open every manifest and bucket this session holds a key for, download the
//! referenced blobs and materialize the whole into a fresh SQLite database.

use std::collections::HashMap;
use secrecy::{ExposeSecret, SecretString};

use crate::vault_model::{id_key, ids_equal};
use super::errors::{SyncError, SyncResult};
use super::state::{self, Ctx};
use super::types::{self, BlobDownloadResponse, BlobHashesRequest, Db, GetResponse, ManifestDto, SharedManifestDto, StoredBlobRef};
use super::blob_keys::{self, EncryptedBlob};
use super::{db, http, keys, legacy};
use crate::crypto;
use crate::vault_codec::{self, CanonicalizeInput, CodecTableData, DataBucket, Manifest, ManifestSpec, MaterializeInput, UnpackedPayload};
use crate::vault_model::SYNCABLE_TABLE_NAMES;

const BLOBS_DOWNLOAD_ENDPOINT: &str = "Vault/blobs/download";

/// One manifest of a pull, opened.
pub(crate) struct ResolvedManifest {
    pub manifest_id: String,
    pub is_personal: bool,
    pub manifest: Manifest,
    pub vek: SecretString,
    pub revision: i64,
    pub blob_references: Vec<StoredBlobRef>,
    pub content_fingerprint: String,
}

/// Every manifest of one snapshot, decrypted, with the sync state learned from it.
pub(crate) struct OpenedManifestSet {
    pub resolved: Vec<ResolvedManifest>,
    pub data_buckets: Vec<DataBucket>,
    pub blob_map: HashMap<String, Vec<u8>>,
    pub manifest_names: HashMap<String, String>,
    pub contentless_manifest_ids: Vec<String>,
    pub personal_needs_first_write: bool,
    pub personal_revision: i64,
    pub manifest_revisions: HashMap<String, i64>,
    pub bucket_revisions: HashMap<String, i64>,
}

impl OpenedManifestSet {
    pub fn manifests(&self) -> Vec<Manifest> {
        self.resolved.iter().map(|m| m.manifest.clone()).collect()
    }

    /// The opened set as a vault ready to become the local one.
    pub fn pulled_vault(&self, encrypted_vault: String) -> PulledVault {
        PulledVault { encrypted_vault, personal_revision: self.personal_revision, manifest_revisions: self.manifest_revisions.clone(), bucket_revisions: self.bucket_revisions.clone(), needs_first_write: self.personal_needs_first_write }
    }
}

/// 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 was never written to the server; it is stored dirty and pushed by the same sync.
    pub needs_first_write: bool,
}

/// The `storageFormat` a manifest-v1 snapshot declares.
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. TODO: remove once every account has upgraded to manifest-v1.
    LegacySqliteBlob(GetResponse),
}

/// `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() {
        None | Some(legacy::STORAGE_FORMAT_SQLITE_BLOB) => Ok(Snapshot::LegacySqliteBlob(snapshot)),
        Some(STORAGE_FORMAT_MANIFEST) => Ok(Snapshot::Manifest(snapshot)),
        Some(format) => Err(SyncError::VaultVersionIncompatible(format!("vault has storage format {}, this app reads up to {}; update the app", format, STORAGE_FORMAT_MANIFEST))),
    }
}

/// Verify a ciphertext against the server's hash, decrypt it bound to `aad` and open it via the codec.
pub(crate) fn verify_decrypt_unpack(ciphertext: &[u8], vek: &str, aad: &[u8], expected_ciphertext_hash: Option<&str>, label: &str) -> SyncResult<String> {
    if let Some(expected) = expected_ciphertext_hash.filter(|hash| !hash.is_empty()) {
        if vault_codec::compute_ciphertext_hash(ciphertext) != expected {
            return Err(SyncError::ServerVaultUnreadable(format!("{} ciphertext hash mismatch, refusing to load (possible storage corruption)", label)));
        }
    }
    let unreadable = |e: crate::common::error::VaultError| SyncError::ServerVaultUnreadable(format!("{}: {}", label, e));
    let plain = crypto::aes_gcm::decrypt(ciphertext, vek, aad).map_err(unreadable)?;
    match vault_codec::unpack_payload(&plain).map_err(unreadable)? {
        UnpackedPayload::Readable(payload_json) => Ok(payload_json),
        UnpackedPayload::NewerFormat(version) => Err(newer_format(label, version)),
    }
}

/// 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(());
    }
    Err(newer_format(label, schema_version))
}

/// The error for data written by a newer app than this one.
fn newer_format(label: &str, version: u32) -> SyncError {
    SyncError::VaultVersionIncompatible(format!("{} has format version {}, this app reads up to {}; update the app", label, version, vault_codec::SCHEMA_VERSION))
}

/// The grant a shared manifest is remembered by, when the snapshot carries a complete one.
fn grant_of(dto: &ManifestDto) -> Option<(String, String, String)> {
    match (&dto.encrypted_vek, &dto.account_public_key, &dto.algorithm) {
        (Some(vek), Some(public), Some(algorithm)) if !vek.is_empty() && !public.is_empty() && !algorithm.is_empty() => Some((vek.clone(), public.clone(), algorithm.clone())),
        _ => None,
    }
}

fn select_personal_manifest(snapshot: &GetResponse) -> Option<&ManifestDto> {
    let personal_id = snapshot.personal_manifest_id.as_deref()?;
    snapshot.manifests.iter().find(|m| m.manifest_id == personal_id)
}

/// Pull the latest vault: fetch, open, materialize and re-encrypt for local storage.
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,
    };

    ctx.log("[Pull] Decrypting the manifests and reassembling the local SQLite...").await;
    let opened = open_manifests_and_record_sync_state(ctx, &snapshot, vek.expose_secret()).await?;
    let sqlite_bytes = materialize_to_sqlite(ctx, &opened.manifests(), &opened.data_buckets, &opened.blob_map, &opened.manifest_names).await?;
    ctx.log(format!("[Pull] Materialized SQLite ({} bytes); re-encrypting for local storage...", sqlite_bytes.len())).await;
    Ok(opened.pulled_vault(state::encrypt_vault_blob(&sqlite_bytes, vek.expose_secret())?))
}

/// Open every manifest a snapshot carries, personal first, and record the snapshot as this device's sync state.
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.
    let personal_needs_first_write = !personal_dto.has_content();
    if personal_needs_first_write && personal_dto.revision != 0 {
        return Err(SyncError::Snapshot(format!("server returned no manifest blob at revision {}, nothing to assemble", personal_dto.revision)));
    }

    let mut pulled_fingerprints: HashMap<String, String> = HashMap::new();
    let mut resolved: Vec<ResolvedManifest> = Vec::new();
    let mut shared_records: HashMap<String, SharedManifestDto> = HashMap::new();
    let mut contentless_revisions: HashMap<String, i64> = HashMap::new();
    let mut manifest_names: HashMap<String, String> = HashMap::new();
    let previous_records = keys::shared_manifest_records(ctx).await?;
    let own_signing_public_key = keys::own_signing_public_key(ctx).await?;

    let ordered: Vec<&ManifestDto> = std::iter::once(personal_dto).chain(snapshot.manifests.iter().filter(|m| m.manifest_id != personal_dto.manifest_id)).collect();
    for dto in ordered {
        let is_personal = dto.manifest_id == personal_dto.manifest_id;
        let manifest_key = resolve_manifest_vek(ctx, dto, &personal_dto.manifest_id, vek, is_personal, own_signing_public_key.as_deref()).await?;
        if is_personal {
            let entry = if personal_needs_first_write {
                ctx.log("[Pull] Personal manifest has no content yet (new account); starting from an empty vault.").await;
                empty_personal_manifest(ctx, dto, manifest_key.expose_secret()).await?
            } else {
                open_logged_manifest(ctx, dto, manifest_key.expose_secret(), true).await?
            };
            state::set(&ctx.host, state::VAULT_MANIFEST_SALT, &entry.manifest.manifest_salt).await?;
            state::set(&ctx.host, state::VAULT_PERSONAL_MANIFEST_ID, &entry.manifest_id).await?;
            resolved.push(entry);
            continue;
        }
        if !dto.has_content() {
            // 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)));
            }
            let (encrypted_vek, account_public_key, algorithm) = grant_of(dto).ok_or_else(|| SyncError::Snapshot(format!("shared manifest {} was served without content and without a grant, refusing to assemble", dto.manifest_id)))?;
            let encrypted_name = served_encrypted_name(ctx, &previous_records, &dto.manifest_id);
            shared_records.insert(dto.manifest_id.clone(), SharedManifestDto { manifest_id: dto.manifest_id.clone(), encrypted_vek, account_public_key, algorithm, salt: vault_codec::generate_manifest_salt(), encrypted_name, can_administer: dto.can_administer, key_version: dto.key_version });
            contentless_revisions.insert(dto.manifest_id.clone(), dto.revision);
            continue;
        }

        let entry = open_logged_manifest(ctx, dto, manifest_key.expose_secret(), false).await?;
        let (encrypted_vek, account_public_key, algorithm) = grant_of(dto).ok_or_else(|| SyncError::Snapshot(format!("shared manifest {} carries no grant this account can re-open, refusing to assemble", entry.manifest_id)))?;
        let encrypted_name = served_encrypted_name(ctx, &previous_records, &entry.manifest_id);
        if let Some(ciphertext) = &encrypted_name {
            match open_manifest_name(ciphertext, &entry.manifest_id, manifest_key.expose_secret()) {
                Some(name) => drop(manifest_names.insert(id_key(&entry.manifest_id), name)),
                None => ctx.warn(format!("[Pull] The name of shared manifest {} did not open with its key; leaving it unnamed.", entry.manifest_id)).await,
            }
        }
        shared_records.insert(entry.manifest_id.clone(), SharedManifestDto { manifest_id: entry.manifest_id.clone(), encrypted_vek, account_public_key, algorithm, salt: entry.manifest.manifest_salt.clone(), encrypted_name, can_administer: dto.can_administer, key_version: dto.key_version });
        resolved.push(entry);
    }
    keys::set_shared_manifest_records(ctx, &shared_records, vek).await?;

    let personal_revision = resolved[0].revision;

    let (data_buckets, bucket_fingerprints, bucket_revisions) = open_data_buckets(ctx, snapshot, &resolved).await?;
    pulled_fingerprints.extend(bucket_fingerprints);

    let mut manifest_revisions: HashMap<String, i64> = resolved.iter().map(|m| (m.manifest_id.clone(), m.revision)).collect();
    manifest_revisions.extend(contentless_revisions.iter().map(|(id, rev)| (id.clone(), *rev)));

    let blob_map = download_referenced_blobs(ctx, &resolved).await?;

    // An empty personal manifest has no server content to compare a push against, so it gets no baseline.
    for entry in resolved.iter().filter(|m| !(m.is_personal && personal_needs_first_write)) {
        pulled_fingerprints.insert(state::fingerprint_manifest_key(&entry.manifest_id), entry.content_fingerprint.clone());
    }
    state::set(&ctx.host, state::VAULT_CONTENT_FINGERPRINTS, &pulled_fingerprints).await?;
    ctx.log(format!("[Pull] Stored {} content fingerprint baseline(s) for push-side change detection.", pulled_fingerprints.len())).await;

    Ok(OpenedManifestSet {
        resolved,
        data_buckets,
        blob_map,
        manifest_names,
        contentless_manifest_ids: contentless_revisions.keys().cloned().collect(),
        personal_needs_first_write,
        personal_revision,
        manifest_revisions,
        bucket_revisions,
    })
}

/// Open one manifest with content, logging what it holds.
async fn open_logged_manifest(ctx: &Ctx, dto: &ManifestDto, manifest_key: &str, is_personal: bool) -> SyncResult<ResolvedManifest> {
    ctx.log(format!("[Pull] Verifying ciphertext hash; decrypting + opening {}...", if is_personal { "personal manifest".to_string() } else { format!("shared manifest {}", dto.manifest_id) })).await;
    let entry = open_manifest(dto, manifest_key, is_personal)?;
    let table_summary: Vec<String> = entry.manifest.tables.iter().map(|(t, rows)| format!("{}={}", t, rows.len())).collect();
    ctx.log(format!("[Pull] Manifest {} opened: tables: {}", entry.manifest_id, table_summary.join(", "))).await;
    Ok(entry)
}

/// A manifest's encrypted name: the one the status served, else the one last recorded.
fn served_encrypted_name(ctx: &Ctx, previous: &HashMap<String, SharedManifestDto>, manifest_id: &str) -> Option<String> {
    ctx.served_manifest_names
        .get(&id_key(manifest_id))
        .cloned()
        .or_else(|| previous.values().find(|record| ids_equal(&record.manifest_id, manifest_id)).and_then(|record| record.encrypted_name.clone()))
}

/// Decrypt a shared manifest's name with the manifest's own key.
pub(crate) fn open_manifest_name(ciphertext: &str, manifest_id: &str, manifest_key: &str) -> Option<String> {
    crypto::aes_gcm::decrypt_text(ciphertext, manifest_key, &crypto::aad::manifest_name(manifest_id)).ok().filter(|name| !name.is_empty())
}

/// Encrypt a shared manifest's name with the manifest's own key.
pub(crate) fn encrypt_manifest_name(name: &str, manifest_id: &str, manifest_key: &str) -> SyncResult<String> {
    Ok(crypto::aes_gcm::encrypt_text(name, manifest_key, &crypto::aad::manifest_name(manifest_id))?)
}

/// 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?;
    ctx.log(format!("[Pull] Stored local manifest revisions from snapshot: {:?}; bucket revisions: {:?}.", pulled.manifest_revisions, pulled.bucket_revisions)).await;
    Ok(())
}

/// 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();
    let mut fingerprints = HashMap::new();
    let mut revisions = HashMap::new();
    for dto in &snapshot.buckets {
        if dto.ciphertext.bytes.is_empty() {
            continue;
        }
        let key = key_by_manifest.get(dto.manifest_id.as_str()).ok_or_else(|| SyncError::Snapshot(format!("data bucket \"{}\" belongs to manifest {}, which this vault did not open, refusing to assemble", dto.category, dto.manifest_id)))?;
        let label = format!("\"{}\" bucket of manifest {}", dto.category, dto.manifest_id);
        let bucket_json = verify_decrypt_unpack(&dto.ciphertext.bytes, key, &crypto::aad::bucket(&dto.manifest_id, &dto.category), dto.ciphertext_hash.as_deref(), &label)?;
        let bucket: DataBucket = serde_json::from_str(&bucket_json)?;
        ensure_readable(bucket.schema_version, &label)?;
        if !ids_equal(&bucket.manifest_id, &dto.manifest_id) || bucket.category != dto.category {
            return Err(SyncError::Snapshot(format!("{} declares a different address (manifest {}, category \"{}\") inside its encrypted payload, refusing to assemble", label, bucket.manifest_id, bucket.category)));
        }
        let rows: usize = bucket.tables.values().map(Vec::len).sum();
        ctx.log(format!("[Pull] Data bucket {} opened: {} rows (revision {:?}).", label, rows, dto.revision)).await;
        fingerprints.insert(state::fingerprint_bucket_key(&dto.manifest_id, &dto.category), vault_codec::compute_content_fingerprint(&bucket_json));
        if let Some(revision) = dto.revision {
            revisions.insert(state::bucket_revision_key(&dto.manifest_id, &dto.category), revision);
        }
        buckets.push(bucket);
    }
    Ok((buckets, fingerprints, revisions))
}

/// Fetch every referenced blob not cached locally, decrypt it, and prune the cache to the referenced set.
async fn download_referenced_blobs(ctx: &Ctx, resolved: &[ResolvedManifest]) -> SyncResult<HashMap<String, Vec<u8>>> {
    let mut owners: HashMap<String, &ResolvedManifest> = HashMap::new();
    let mut refs: Vec<StoredBlobRef> = Vec::new();
    for entry in resolved {
        for reference in &entry.blob_references {
            if owners.contains_key(&reference.hash) {
                continue;
            }
            owners.insert(reference.hash.clone(), entry);
            refs.push(reference.clone());
        }
    }

    let mut cache: HashMap<String, EncryptedBlob> = state::get(&ctx.host, state::VAULT_BLOB_CIPHER_CACHE).await?.unwrap_or_default();
    let missing: Vec<StoredBlobRef> = refs.iter().filter(|r| !cache.contains_key(&r.hash)).cloned().collect();
    ctx.log(format!("[Pull] Blob refs: {} referenced, {} cached locally, {} to download.", refs.len(), refs.len() - missing.len(), missing.len())).await;

    // The server stores blobs per manifest, so each batch names the manifest that owns its hashes.
    let mut batches: Vec<(String, Vec<StoredBlobRef>)> = Vec::new();
    for entry in resolved {
        let owned: Vec<StoredBlobRef> = missing.iter().filter(|r| owners.get(&r.hash).is_some_and(|o| o.manifest_id == entry.manifest_id)).cloned().collect();
        batches.extend(http::batch_by_transfer_cost(owned, |r| r.size_bytes.max(0) as usize).into_iter().map(|chunk| (entry.manifest_id.clone(), chunk)));
    }
    let batch_count = batches.len();
    for (index, (manifest_id, chunk)) in batches.into_iter().enumerate() {
        let request = BlobHashesRequest { manifest_id, hashes: chunk.iter().map(|r| r.hash.clone()).collect() };
        let blobs = http::post_for_frame::<_, BlobDownloadResponse>(&ctx.host, BLOBS_DOWNLOAD_ENDPOINT, &request).await?.blobs;
        let bytes: usize = blobs.iter().map(|b| b.ciphertext.size).sum();
        ctx.log(format!("[Pull] Downloaded blob batch {}/{}: requested {}, received {} ({} bytes).", index + 1, batch_count, chunk.len(), blobs.len(), bytes)).await;
        for dto in blobs {
            cache.insert(dto.hash, EncryptedBlob { encrypted_data: dto.ciphertext.bytes, encrypted_blob_key: dto.encrypted_blob_key });
        }
    }

    let mut pruned_cache: HashMap<String, EncryptedBlob> = HashMap::new();
    let mut blob_map = HashMap::new();
    for reference in &refs {
        let Some(encrypted) = cache.get(&reference.hash) else {
            ctx.warn(format!("[Pull] Referenced {} blob {} was not served; its row stays not loaded and keeps the reference.", reference.category, reference.hash)).await;
            continue;
        };
        let owner = owners[&reference.hash];
        match blob_keys::decrypt_blob(encrypted, owner.vek.expose_secret(), &owner.manifest_id, &owner.manifest.manifest_salt, &reference.hash) {
            Ok(bytes) => {
                blob_map.insert(reference.hash.clone(), bytes);
                pruned_cache.insert(reference.hash.clone(), encrypted.clone());
            }
            Err(_) => ctx.warn(format!("[Pull] Referenced {} blob {} did not decrypt with the manifest key or does not hash to its address; its row stays not loaded and keeps the reference.", reference.category, reference.hash)).await,
        }
    }
    state::set(&ctx.host, state::VAULT_BLOB_CIPHER_CACHE, &pruned_cache).await?;
    state::set(&ctx.host, state::VAULT_SERVER_BLOB_HASHES, &refs.iter().map(|r| r.hash.clone()).collect::<Vec<_>>()).await?;
    Ok(blob_map)
}

/// Materialize manifests and buckets into a fresh database and return its bytes.
pub(crate) async fn materialize_to_sqlite(ctx: &mut Ctx, manifests: &[Manifest], data_buckets: &[DataBucket], blob_map: &HashMap<String, Vec<u8>>, opened_names: &HashMap<String, String>) -> SyncResult<Vec<u8>> {
    ctx.log(format!("[Pull] {} blobs decrypted; running codec reassembly into a fresh SQLite ({} manifest(s) combined)...", blob_map.len(), manifests.len())).await;
    let schema = ctx.schema().await?;
    let materialized = vault_codec::materialize_as_sqlite(MaterializeInput { manifests: manifests.to_vec(), data_buckets: data_buckets.to_vec(), schema_columns: schema.columns.clone() })?;

    let overflow_tables = materialized.overflow.tables.len() + materialized.overflow.bucket_tables.values().map(HashMap::len).sum::<usize>();
    if overflow_tables > 0 || !materialized.overflow.columns.is_empty() {
        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;
    }

    ctx.host.open_staging()?;
    db::insert_materialized(&ctx.host, &materialized, &schema.columns, blob_map).await?;

    // Names are not part of a manifest: the ones the vault already shows are kept, the ones this run opened win.
    let mut names = if ctx.has_local_vault().await? { db::manifest_display_names(&ctx.host).await? } else { HashMap::new() };
    names.extend(opened_names.clone());
    db::apply_manifest_names(&ctx.host, Db::Staging, &names).await?;
    let bytes = db::export(&ctx.host, Db::Staging).await?;
    ctx.log(format!("[Pull] Codec reassembly complete: {} bytes.", bytes.len())).await;
    Ok(bytes)
}

fn open_manifest(dto: &ManifestDto, vek: &str, is_personal: bool) -> SyncResult<ResolvedManifest> {
    let label = if is_personal { "manifest".to_string() } else { format!("shared manifest {}", dto.manifest_id) };
    let manifest_json = verify_decrypt_unpack(&dto.ciphertext.bytes, vek, &crypto::aad::manifest(&dto.manifest_id), dto.ciphertext_hash.as_deref(), &label)?;
    let manifest: Manifest = serde_json::from_str(&manifest_json)?;
    ensure_readable(manifest.schema_version, &label)?;
    if !ids_equal(&manifest.manifest_id, &dto.manifest_id) {
        return Err(SyncError::Snapshot(format!("manifest {} declares a different id ({}) inside its encrypted payload, refusing to open it", dto.manifest_id, manifest.manifest_id)));
    }
    Ok(ResolvedManifest {
        manifest_id: dto.manifest_id.clone(),
        is_personal,
        manifest,
        vek: SecretString::from(vek),
        revision: dto.revision,
        blob_references: dto.blob_references.clone(),
        content_fingerprint: vault_codec::compute_content_fingerprint(&manifest_json),
    })
}

/// The empty personal manifest of a new account, canonicalized from every syncable table with no rows.
async fn empty_personal_manifest(ctx: &Ctx, dto: &ManifestDto, vek: &str) -> SyncResult<ResolvedManifest> {
    // A salt from an earlier attempt is kept, so blob hashes stay stable until the first write lands.
    let manifest_salt = state::get::<String>(&ctx.host, state::VAULT_MANIFEST_SALT).await?.unwrap_or_else(vault_codec::generate_manifest_salt);
    let tables = SYNCABLE_TABLE_NAMES.iter().map(|name| CodecTableData { name: name.to_string(), records: Vec::new() }).collect();
    let spec = ManifestSpec { manifest_id: dto.manifest_id.clone(), manifest_salt };
    let canonicalized = vault_codec::canonicalize_from_sqlite(CanonicalizeInput { tables, canonicalized_at: crate::common::timestamp::now_iso_utc(), manifests: vec![spec], stamp_unstamped_into: None })?;
    let manifest = canonicalized.manifests.into_iter().next().map(|m| m.manifest).ok_or_else(|| SyncError::Other("canonicalize returned no manifest for the empty vault".to_string()))?;
    Ok(ResolvedManifest { manifest_id: dto.manifest_id.clone(), is_personal: true, manifest, vek: SecretString::from(vek), revision: dto.revision, blob_references: Vec::new(), content_fingerprint: String::new() })
}

/// 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> {
    // 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(),
        None => return Err(SyncError::Snapshot(format!("shared manifest {} states no key type, refusing to assemble", dto.manifest_id))),
    };
    if key_type == types::KEY_TYPE_ACCOUNT_KEY {
        if dto.manifest_id != personal_manifest_id {
            return Err(SyncError::Snapshot(format!("manifest {} is unlocked by the account key hierarchy, but this session holds no key for it, refusing to assemble", dto.manifest_id)));
        }
        return Ok(SecretString::from(personal_vek));
    }
    if key_type != types::KEY_TYPE_GRANT_KEY {
        return Err(SyncError::VaultVersionIncompatible(format!("manifest {} states an unknown key type \"{}\"; update the app", dto.manifest_id, key_type)));
    }
    resolve_granted_vek(ctx, dto, own_signing_public_key).await
}

/// The VEK of a shared manifest from the grant it was served with, which has to be signed by this account itself.
async fn resolve_granted_vek(ctx: &Ctx, dto: &ManifestDto, own_signing_public_key: Option<&str>) -> SyncResult<SecretString> {
    let (encrypted_vek, public_key, algorithm) = grant_of(dto).ok_or_else(|| SyncError::Snapshot(format!("shared manifest {} carries no grant to open it with, refusing to assemble", dto.manifest_id)))?;
    if algorithm != types::ALGORITHM_RSA_OAEP_SHA256 {
        return Err(SyncError::VaultVersionIncompatible(format!("shared manifest {} grants its VEK under an unsupported algorithm \"{}\"; update the app", dto.manifest_id, algorithm)));
    }
    let signing_public_key = own_signing_public_key.ok_or_else(|| SyncError::ServerVaultUnreadable(format!("this session holds no signing key to check the grant on shared manifest {} with, refusing to assemble", dto.manifest_id)))?;
    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)));
    }
    // 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)))
}