Skip to content

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

Add auto-migrate flow (#2159)

Leendert de Borst48e37ec31a9b
diff --git a/apps/browser-extension/src/entrypoints/background.ts b/apps/browser-extension/src/entrypoints/background.ts
index a7a7af3ac..d951a9f9f 100644
--- a/apps/browser-extension/src/entrypoints/background.ts
+++ b/apps/browser-extension/src/entrypoints/background.ts
@@ -9,7 +9,7 @@ import { handleGetWebAuthnSettings, handleWebAuthnCreate, handleWebAuthnGet, han
import { handleOpenPopup, handlePopupWithItem, handleOpenPopupCreateCredential, handleToggleContextMenu } from '@/entrypoints/background/PopupMessageHandler';
import { handleStoreSavePromptState, handleGetSavePromptState, handleClearSavePromptState, handleStoreLastAutofilled, handleGetLastAutofilled, handleClearLastAutofilled } from '@/entrypoints/background/SavePromptStateHandler';
import { handleStoreTwoFactorState, handleGetTwoFactorState, handleClearTwoFactorState } from '@/entrypoints/background/TwoFactorStateHandler';
-import { handleCheckAuthStatus, handleClearPersistedFormValues, handleClearSession, handleClearVaultData, handleLockVault, handleGetFilteredItems, handleGetSearchItems, handleGetDefaultEmailDomain, handleGetDefaultIdentitySettings, handleGetEncryptionKey, handleGetEncryptionKeyDerivationParams, handleGetPasswordSettings, handleGeneratePassword, handleGetPersistedFormValues, handleGetVault, handlePersistFormValues, handleStoreEncryptionKey, handleStoreEncryptionKeyDerivationParams, handleStoreVaultMetadata, handleSyncVault, handleUploadVault, handleGetEncryptedVault, handleStoreEncryptedVault, handleGetSyncState, handleMarkVaultClean, handleGetServerRevision, handleFullVaultSync, handleCheckLoginDuplicate, handleSaveLoginCredential, handleAddUrlToCredential, handleIsUrlLinkedToCredential, handleGetLoginSaveSettings, handleSetLoginSaveEnabled, handleGetItemsWithTotp, handleSearchItemsWithTotp, handleGetTotpSecrets, handleGenerateTotpCode, handleSetRecentlySelected, handleGetRecentlySelected } from '@/entrypoints/background/VaultMessageHandler';
+import { handleCheckAuthStatus, handleClearPersistedFormValues, handleClearSession, handleClearVaultData, handleLockVault, handleGetFilteredItems, handleGetSearchItems, handleGetDefaultEmailDomain, handleGetDefaultIdentitySettings, handleGetEncryptionKey, handleGetEncryptionKeyDerivationParams, handleGetPasswordSettings, handleGeneratePassword, handleGetPersistedFormValues, handleGetVault, handlePersistFormValues, handleStoreEncryptionKey, handleStoreEncryptionKeyDerivationParams, handleStoreVaultMetadata, handleSyncVault, handleUploadVault, handleGetEncryptedVault, handleStoreEncryptedVault, handleGetSyncState, handleMarkVaultClean, handleMigrateVaultManifest, handleGetServerRevision, handleFullVaultSync, handleCheckLoginDuplicate, handleSaveLoginCredential, handleAddUrlToCredential, handleIsUrlLinkedToCredential, handleGetLoginSaveSettings, handleSetLoginSaveEnabled, handleGetItemsWithTotp, handleSearchItemsWithTotp, handleGetTotpSecrets, handleGenerateTotpCode, handleSetRecentlySelected, handleGetRecentlySelected } from '@/entrypoints/background/VaultMessageHandler';
import { LocalPreferencesService } from '@/utils/LocalPreferencesService';
import { onMessage, sendMessage } from "@/utils/messaging/ExtensionMessaging";
@@ -248,6 +248,7 @@ export default defineBackground({
onMessage('UPLOAD_VAULT', () => handleUploadVault());
onMessage('SYNC_VAULT', () => handleSyncVault());
onMessage('FULL_VAULT_SYNC', () => handleFullVaultSync());
+ onMessage('MIGRATE_VAULT_MANIFEST', () => handleMigrateVaultManifest());
onMessage('LOCK_VAULT', () => handleLockVault());
onMessage('CLEAR_SESSION', () => handleClearSession());
onMessage('CLEAR_VAULT_DATA', () => handleClearVaultData());
diff --git a/apps/browser-extension/src/entrypoints/background/VaultMessageHandler.ts b/apps/browser-extension/src/entrypoints/background/VaultMessageHandler.ts
index 6418c7415..4862f75db 100644
--- a/apps/browser-extension/src/entrypoints/background/VaultMessageHandler.ts
+++ b/apps/browser-extension/src/entrypoints/background/VaultMessageHandler.ts
@@ -9,6 +9,7 @@ import type { EncryptionKeyDerivationParams } from '@/utils/dist/core/models/met
import { FieldKey, ItemTypes, createSystemField, type Item, type PasswordSettings } from '@/utils/dist/core/models/vault';
import type { VaultResponse, VaultPostResponse, StatusResponseV2, ManifestRevision } from '@/utils/dist/core/models/webapi';
import { EncryptionUtility } from '@/utils/EncryptionUtility';
+import { requiresLegacyVaultKeyMigration } from '@/utils/LegacyVaultKeyMigration';
import { LocalPreferencesService } from '@/utils/LocalPreferencesService';
import { sendMessage } from '@/utils/messaging/ExtensionMessaging';
import { RecentlySelectedItemService } from '@/utils/RecentlySelectedItemService';
@@ -36,6 +37,7 @@ import { VaultUploadResponse as messageVaultUploadResponse } from '@/utils/types
import { type VaultMutationScope, ALL_VAULT_MUTATION_SCOPES, DEFAULT_VAULT_MUTATION_SCOPE, isManifestScope } from '@/utils/types/VaultMutationScope';
import { VaultCodec } from '@/utils/VaultCodec';
import { VaultKeyService } from '@/utils/VaultKeyService';
+import { vaultRequiresManifestMigration } from '@/utils/VaultManifestMigration';
import { vaultMergeService } from '@/utils/VaultMergeService';
import { vaultSyncService, invalidateCanonicalizeCache } from '@/utils/VaultSyncService';
import { WebApiService } from '@/utils/WebApiService';
@@ -129,57 +131,37 @@ let isSyncInProgress = false;
let hasPendingSync = false;
/**
- * Check if the user is logged in and if the vault is locked, and also check for pending migrations.
+ * Check if the user is logged in and if the vault is locked, and also check for both kinds of pending vault.
*/
-export async function handleCheckAuthStatus() : Promise<{ isLoggedIn: boolean, isVaultLocked: boolean, hasPendingMigrations: boolean, error?: string }> {
+export async function handleCheckAuthStatus() : Promise<{ isLoggedIn: boolean, isVaultLocked: boolean, requiresLegacySqliteBlobMigration: boolean, requiresSchemaMigration: boolean, error?: string }> {
const [username, accessToken, vaultData, encryptionKey] = await Promise.all([storage.getItem(StorageKeys.USERNAME), storage.getItem(StorageKeys.ACCESS_TOKEN), storage.getItem(StorageKeys.ENCRYPTED_VAULT), handleGetEncryptionKey()]);
const isLoggedIn = username !== null && accessToken !== null;
const isVaultLocked = isLoggedIn && (vaultData === null || encryptionKey === null);
- // If vault is locked, we can't check for pending migrations
- if (isVaultLocked) {
- return {
- isLoggedIn,
- isVaultLocked,
- hasPendingMigrations: false
- };
- }
-
- // If not logged in, no need to check migrations
- if (!isLoggedIn) {
- return {
- isLoggedIn,
- isVaultLocked,
- hasPendingMigrations: false
- };
+ // A locked or logged-out vault can't be opened, so neither upgrade state can be determined.
+ if (isVaultLocked || !isLoggedIn) {
+ return { isLoggedIn, isVaultLocked, requiresLegacySqliteBlobMigration: false, requiresSchemaMigration: false };
}
// Vault is unlocked, check for pending migrations
try {
const sqliteClient = await createVaultSqliteClient();
- const hasPendingMigrations = await sqliteClient.hasPendingMigrations();
- return {
- isLoggedIn,
- isVaultLocked,
- hasPendingMigrations
- };
+ const requiresLegacySqliteBlobMigration = await sqliteClient.requiresLegacySqliteBlobMigration();
+ const requiresSchemaMigration = await sqliteClient.requiresSchemaMigration();
+ return { isLoggedIn, isVaultLocked, requiresLegacySqliteBlobMigration, requiresSchemaMigration };
} catch (error) {
// If it's a version incompatibility error, we need to handle it specially
if (error instanceof VaultVersionIncompatibleError) {
// Return the error so the UI can handle it appropriately (logout user)
- return {
- isLoggedIn,
- isVaultLocked,
- hasPendingMigrations: false,
- error: error.message
- };
+ return { isLoggedIn, isVaultLocked, requiresLegacySqliteBlobMigration: false, requiresSchemaMigration: false, error: error.message };
}
return {
isLoggedIn,
isVaultLocked,
- hasPendingMigrations: false,
+ requiresLegacySqliteBlobMigration: false,
+ requiresSchemaMigration: false,
error: error instanceof Error ? error.message : await t('common.errors.unknownError')
};
}
@@ -275,19 +257,13 @@ async function fetchLatestVaultFromServer(): Promise<VaultResponse> {
}
/**
- * Upload the current SQLite via the v2 storage format.
+ * Push the current SQLite vault to the server.
+ *
* @param sqliteClient - the in-memory SQLite client to upload
- * @param forceFullWrite - bypass the content-fingerprint gating and rewrite every manifest and bucket (server rollback recovery)
+ * @param options - forceFullWrite bypasses the content-fingerprint gating and rewrites every manifest and bucket
+ * (server rollback recovery); createVaultKey mints the VEK as part of this push (KEK/VEK migration)
*/
-async function uploadVaultV2(sqliteClient: SqliteClient, forceFullWrite: boolean = false): Promise<VaultPostResponse> {
- /*
- * A vault key another device created must be adopted before we decide anything, otherwise this push would try to
- * migrate an already-migrated vault and the server would reject it.
- */
- if (!await adoptRemoteVaultKeyIfNeeded()) {
- throw new Error(formatErrorWithCode('Vault encryption key out of sync with the server; please log in again', AppErrorCode.VAULT_DECRYPT_FAILED));
- }
-
+async function pushVaultToServer(sqliteClient: SqliteClient, options: { forceFullWrite: boolean; createVaultKey: boolean }): Promise<VaultPostResponse> {
const encryptionKey = await handleGetEncryptionKey();
if (!encryptionKey) {
throw new Error(formatErrorWithCode(await t('common.errors.vaultIsLocked'), AppErrorCode.VAULT_LOCKED));
@@ -296,18 +272,14 @@ async function uploadVaultV2(sqliteClient: SqliteClient, forceFullWrite: boolean
const username = (await storage.getItem(StorageKeys.USERNAME)) as string;
const emailAddresses = await getEmailAddressesForVault(sqliteClient);
- /*
- * KEK/VEK migration: a not-yet-migrated (legacy sqlite-blob) user has no vault key, so their first manifest
- * upload generates a VEK, re-encrypts everything with it, and creates the vault key server-side (wrapping the
- * VEK with the current password-derived key). The local wrapped-VEK cache is the source of truth here: it is
- * exactly "the session key is a VEK", which is the question this decision asks.
- */
- const hasVaultKey = await VaultKeyService.hasLocalVaultKey();
- const result = await vaultSyncService.push(sqliteClient, encryptionKey, username, emailAddresses, { createVaultKey: !hasVaultKey, forceFullWrite });
+ const result = await vaultSyncService.push(sqliteClient, encryptionKey, username, emailAddresses, options);
if (result.status === 'ok') {
if (result.newEncryptionKey) {
- // Migration succeeded: from now on the session key is the VEK, not the password-derived key.
+ /*
+ * Migration succeeded: from now on the session key is the VEK, not the password-derived key.
+ * TODO: this can be removed once all users have migrated to the manifest-v1 storage model.
+ */
await handleStoreEncryptionKey(result.newEncryptionKey);
}
@@ -820,16 +792,6 @@ async function uploadDirtyBucketsOnly(sqliteClient: SqliteClient, scopes: VaultM
throw new Error(formatErrorWithCode(await t('common.errors.vaultIsLocked'), AppErrorCode.VAULT_LOCKED));
}
- /*
- * A bucket-only push encrypts with the current session key. A not-yet-migrated user has no vault key yet, so the
- * full upload path must run instead to re-key the whole vault (KEK/VEK migration) in one atomic request. Answered
- * from the local wrapped-VEK cache, so the common (migrated) case costs no round-trip.
- */
- if (!await VaultKeyService.hasLocalVaultKey()) {
- devLog('[V2Push] User not yet migrated (no vault key), falling back to full vault upload to run the KEK/VEK migration.');
- return (await uploadNewVaultToServer(sqliteClient)).response;
- }
-
/*
* Which tables make up each bucket category is owned by the Rust layer.
*/
@@ -840,7 +802,7 @@ async function uploadDirtyBucketsOnly(sqliteClient: SqliteClient, scopes: VaultM
const spec = layout.find(entry => entry.category === category);
if (!spec) {
devWarn(`[V2Push] Unknown bucket scope "${category}", falling back to full vault upload.`);
- return (await uploadNewVaultToServer(sqliteClient)).response;
+ return (await uploadNewVaultToServer(sqliteClient, { forceFullWrite: false, createVaultKey: false })).response;
}
/*
@@ -868,11 +830,13 @@ async function uploadDirtyBucketsOnly(sqliteClient: SqliteClient, scopes: VaultM
* Bucket-aware: when every pending mutation is scoped to a data bucket (e.g. Settings), only those buckets
* are pushed. A dirty 'manifest' scope (or a dirty state with no recorded scopes) triggers the full upload path,
* whose content-fingerprint gating then narrows the write down to the manifests/buckets that actually changed.
+ *
* @param options - set forceFullWrite to rewrite every manifest and bucket regardless of change detection
- * (server rollback recovery)
+ * (server rollback recovery); set createVaultKey to mint the VEK as part of this push (the explicit storage
+ * migration passes this, and it is the only caller that should)
*/
export async function handleUploadVault(
- options?: { forceFullWrite?: boolean }
+ options?: { forceFullWrite?: boolean; createVaultKey?: boolean }
) : Promise<messageVaultUploadResponse> {
try {
// Capture mutation sequence at start of upload for race detection
@@ -881,10 +845,20 @@ export async function handleUploadVault(
// Create sqlite client from the already-stored vault blob.
const sqliteClient = await createVaultSqliteClient();
+ /*
+ * Check if vault key is available on server, if so, adopt it.
+ */
+ if (!await adoptRemoteVaultKeyIfNeeded()) {
+ throw new Error(formatErrorWithCode('Vault encryption key out of sync with the server; please log in again', AppErrorCode.VAULT_DECRYPT_FAILED));
+ }
+
+ // Handle creating a vault key if it is not available. TODO: delete once all users have migrated to the manifest-v1 storage model.
+ const createVaultKey = options?.createVaultKey === true || !await VaultKeyService.hasLocalVaultKey();
+
// Upload to the server: bucket-only when possible, full vault otherwise. A forced full write skips the bucket-only shortcut.
const forceFullWrite = options?.forceFullWrite === true;
const dirtyScopes = await getDirtyScopes();
- const bucketOnly = !forceFullWrite && dirtyScopes.length > 0 && !dirtyScopes.some(isManifestScope);
+ const bucketOnly = !forceFullWrite && !createVaultKey && dirtyScopes.length > 0 && !dirtyScopes.some(isManifestScope);
if (bucketOnly) {
devLog(`[V2Push] All pending mutations are bucket-scoped (${dirtyScopes.join(', ')}), skipping manifest upload.`);
}
@@ -894,7 +868,7 @@ export async function handleUploadVault(
// Bucket-only pushes never prune (settings buckets carry no trash items).
response = await uploadDirtyBucketsOnly(sqliteClient, dirtyScopes);
} else {
- ({ response, vaultPruned } = await uploadNewVaultToServer(sqliteClient, forceFullWrite));
+ ({ response, vaultPruned } = await uploadNewVaultToServer(sqliteClient, { forceFullWrite, createVaultKey }));
}
return {
@@ -1000,9 +974,9 @@ export async function handleClearPersistedFormValues(): Promise<void> {
* Upload a new version of the vault to the server using the provided sqlite client.
* Prunes expired trash items before uploading.
* @param sqliteClient - the in-memory SQLite client to upload
- * @param forceFullWrite - bypass the content-fingerprint gating and rewrite every manifest and bucket
+ * @param options - forceFullWrite: whether to force a full write of the vault, createVaultKey: whether to create a vault key
*/
-async function uploadNewVaultToServer(sqliteClient: SqliteClient, forceFullWrite: boolean = false) : Promise<{ response: VaultPostResponse; vaultPruned: boolean }> {
+async function uploadNewVaultToServer(sqliteClient: SqliteClient, options: { forceFullWrite: boolean; createVaultKey: boolean }) : Promise<{ response: VaultPostResponse; vaultPruned: boolean }> {
devLog('[VaultSync] Upload started');
let vaultPruned = false;
const encryptionKey = await handleGetEncryptionKey();
@@ -1030,9 +1004,9 @@ async function uploadNewVaultToServer(sqliteClient: SqliteClient, forceFullWrite
console.warn('[VaultSync] Failed to prune vault, continuing with upload:', pruneError);
}
- let v2Response: VaultPostResponse;
+ let pushResponse: VaultPostResponse;
try {
- v2Response = await uploadVaultV2(sqliteClient, forceFullWrite);
+ pushResponse = await pushVaultToServer(sqliteClient, options);
} catch (err) {
if (err instanceof ServerUpdateRequiredError) {
throw new Error(formatErrorWithCode(await t('common.errors.serverVersionNotSupported'), AppErrorCode.SERVER_UPDATE_REQUIRED));
@@ -1053,11 +1027,11 @@ async function uploadNewVaultToServer(sqliteClient: SqliteClient, forceFullWrite
cachedSqliteClient = sqliteClient;
cachedVaultBlob = reEncrypted;
}
- if (v2Response.status === 0) {
- await storage.setItem(StorageKeys.SERVER_REVISION, v2Response.newRevisionNumber);
+ if (pushResponse.status === 0) {
+ await storage.setItem(StorageKeys.SERVER_REVISION, pushResponse.newRevisionNumber);
}
- return { response: v2Response, vaultPruned };
+ return { response: pushResponse, vaultPruned };
}
/**
@@ -1082,6 +1056,25 @@ async function persistLocalVaultMutation(sqliteClient: SqliteClient, encryptionK
});
}
+/**
+ * Whether a decrypted vault database is still on the pre-manifest-v1 schema.
+ *
+ * TODO: delete once all users have migrated to the manifest-v1 storage model.
+ *
+ * @param decryptedBase64 - base64 of the plaintext SQLite database
+ */
+async function isLegacyStorageVault(decryptedBase64: string): Promise<boolean> {
+ const client = new SqliteClient();
+ try {
+ await client.initializeFromBase64(decryptedBase64);
+ return await client.requiresSchemaMigration();
+ } catch {
+ return false;
+ } finally {
+ client.close();
+ }
+}
+
/**
* Create a new sqlite client for the stored vault.
* Uses a cache to avoid repeated decryption and initialization for read operations.
@@ -1201,6 +1194,83 @@ export async function handleStoreEncryptedVault(request: {
return { success: true, mutationSequence };
}
+/**
+ * Result of the manifest migration.
+ */
+export type VaultManifestMigrationResult = {
+ success: boolean;
+ pushed: boolean;
+ error?: string;
+};
+
+/**
+ * Upgrade local manifest-v1 storage model to the current schema (if needed).
+ */
+export async function handleMigrateVaultManifest(): Promise<VaultManifestMigrationResult> {
+ try {
+ const encryptionKey = await handleGetEncryptionKey();
+ if (!encryptionKey) {
+ // E-202: Vault is locked
+ return { success: false, pushed: false, error: formatErrorWithCode(await t('common.errors.vaultIsLocked'), AppErrorCode.VAULT_LOCKED) };
+ }
+
+ const sqliteClient = await createVaultSqliteClient();
+
+ if (await sqliteClient.requiresLegacySqliteBlobMigration()) {
+ // The sqlite-blob upgrade chain has to bring the vault to 2.0.0 first; the codec cannot canonicalize what came before.
+ return { success: false, pushed: false, error: await t('content.vaultUpgradeRequired') };
+ }
+
+ // Check if vault key is available on server, if so, adopt it.
+ if (!await adoptRemoteVaultKeyIfNeeded()) {
+ return { success: false, pushed: false, error: formatErrorWithCode('Vault encryption key out of sync with the server; please log in again', AppErrorCode.VAULT_DECRYPT_FAILED) };
+ }
+
+ const needsSchemaMigration = await sqliteClient.requiresSchemaMigration();
+ const needsVaultKey = await requiresLegacyVaultKeyMigration();
+ if (!needsSchemaMigration && !needsVaultKey) {
+ devLog('[ManifestMigration] Vault is already on the current storage model, nothing to migrate.');
+ return { success: true, pushed: true };
+ }
+
+ // Step 1: local migration. Store it dirty so the vault is usable immediately, with or without a server.
+ if (needsSchemaMigration) {
+ const migratedBase64 = await vaultSyncService.migrateVaultToCurrentSchema(sqliteClient);
+ const migratedEncrypted = await EncryptionUtility.symmetricEncrypt(migratedBase64, encryptionKey);
+ await handleStoreEncryptedVault({ vaultBlob: migratedEncrypted, markDirty: true });
+
+ // Invalidate any local cached results that are now stale.
+ invalidateCanonicalizeCache();
+ devLog('[ManifestMigration] Local vault migrated and stored; pushing the migrated vault to the server...');
+ } else {
+ devLog('[ManifestMigration] Schema is current; pushing to mint the vault key.');
+ }
+
+ /*
+ * Step 2: push the migrated vault to the server.
+ */
+ try {
+ const uploadResponse = await handleUploadVault({ createVaultKey: needsVaultKey });
+ if (uploadResponse.success && uploadResponse.status === 0) {
+ await handleMarkVaultClean({
+ mutationSeqAtStart: uploadResponse.mutationSeqAtStart!,
+ newServerRevision: uploadResponse.newRevisionNumber!
+ });
+ devLog(`[ManifestMigration] Migration pushed, server now at revision ${uploadResponse.newRevisionNumber}.`);
+ return { success: true, pushed: true };
+ }
+ devWarn('[ManifestMigration] Migration push did not succeed, vault stays dirty for the next sync:', uploadResponse.error);
+ } catch (pushError) {
+ devWarn('[ManifestMigration] Migration push failed, vault stays dirty for the next sync:', pushError);
+ }
+
+ return { success: true, pushed: false };
+ } catch (error) {
+ devError('[ManifestMigration] Manifest migration failed:', error);
+ return { success: false, pushed: false, error: error instanceof Error ? error.message : await t('common.errors.unknownError') };
+ }
+}
+
/**
* Mark the vault as clean after successful sync.
* Only clears dirty flag if no mutations happened during sync.
@@ -1366,17 +1436,12 @@ function broadcastSyncPhase(phase: VaultSyncPhase): void {
*/
export type FullVaultSyncResult = {
success: boolean;
- /** True if a new vault was downloaded from server */
hasNewVault: boolean;
- /** True if entered offline mode */
wasOffline: boolean;
- /** True if vault upgrade is required */
- upgradeRequired: boolean;
- /** Error message if sync failed */
+ sqliteBlobUpgradeRequired: boolean;
+ manifestMigrationRequired?: boolean;
error?: string;
- /** Error key for translation (e.g. 'clientVersionNotSupported') */
errorKey?: string;
- /** True if user needs to be logged out */
requiresLogout: boolean;
};
@@ -1426,7 +1491,7 @@ async function handleFullVaultSyncInternal(): Promise<FullVaultSyncResult> {
// Mark that we need to sync again after current sync completes
hasPendingSync = true;
devLog('[VaultSync] Sync already in progress, queued for retry after completion');
- return { success: true, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: false };
+ return { success: true, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: false };
}
// Mark sync as in progress
@@ -1441,12 +1506,12 @@ async function handleFullVaultSyncInternal(): Promise<FullVaultSyncResult> {
// Check if user is logged in
const authStatus = await handleCheckAuthStatus();
if (!authStatus.isLoggedIn) {
- return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: false };
+ return { success: false, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: false };
}
if (authStatus.isVaultLocked) {
// E-202: Vault is locked
- return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: false, error: formatErrorWithCode(await t('common.errors.vaultIsLocked'), AppErrorCode.VAULT_LOCKED) };
+ return { success: false, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: false, error: formatErrorWithCode(await t('common.errors.vaultIsLocked'), AppErrorCode.VAULT_LOCKED) };
}
// Check app status and vault revision
@@ -1467,9 +1532,9 @@ async function handleFullVaultSyncInternal(): Promise<FullVaultSyncResult> {
const encryptedVault = await storage.getItem(StorageKeys.ENCRYPTED_VAULT);
if (encryptedVault) {
await storage.setItem(StorageKeys.IS_OFFLINE_MODE, true);
- return { success: true, hasNewVault: false, wasOffline: true, upgradeRequired: false, requiresLogout: false };
+ return { success: true, hasNewVault: false, wasOffline: true, sqliteBlobUpgradeRequired: false, requiresLogout: false };
} else {
- return { success: false, hasNewVault: false, wasOffline: true, upgradeRequired: false, requiresLogout: false, error: await t('common.errors.serverNotAvailable') };
+ return { success: false, hasNewVault: false, wasOffline: true, sqliteBlobUpgradeRequired: false, requiresLogout: false, error: await t('common.errors.serverNotAvailable') };
}
}
@@ -1477,15 +1542,15 @@ async function handleFullVaultSyncInternal(): Promise<FullVaultSyncResult> {
const statusError = webApi.validateStatusResponse(statusResponse);
if (statusError) {
if (statusError === 'clientVersionNotSupported' || statusError === 'serverVersionNotSupported') {
- return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: true, errorKey: statusError };
+ return { success: false, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: true, errorKey: statusError };
}
- return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: false, errorKey: statusError };
+ return { success: false, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: false, errorKey: statusError };
}
// Check if the SRP salt has changed (password change detection)
const storedEncryptionParams = await handleGetEncryptionKeyDerivationParams();
if (storedEncryptionParams && statusResponse.srpSalt && statusResponse.srpSalt !== storedEncryptionParams.salt) {
- return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: true, errorKey: 'passwordChanged' };
+ return { success: false, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: true, errorKey: 'passwordChanged' };
}
/*
@@ -1493,7 +1558,7 @@ async function handleFullVaultSyncInternal(): Promise<FullVaultSyncResult> {
* another device migrated. An unmigrated device with nothing to pull has nothing to adopt and skips the check.
*/
if (needsPull && !await adoptRemoteVaultKeyIfNeeded()) {
- return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: true, errorKey: 'passwordChanged' };
+ return { success: false, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: true, errorKey: 'passwordChanged' };
}
// Valid connection - exit offline mode if we were in it
@@ -1533,7 +1598,7 @@ async function handleFullVaultSyncInternal(): Promise<FullVaultSyncResult> {
const encryptionKey = await handleGetEncryptionKey();
if (!encryptionKey) {
- return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: false, error: await t('common.errors.vaultIsLocked') };
+ return { success: false, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: false, error: await t('common.errors.vaultIsLocked') };
}
if (needsPull) {
@@ -1555,6 +1620,25 @@ async function handleFullVaultSyncInternal(): Promise<FullVaultSyncResult> {
const localDecrypted = await EncryptionUtility.symmetricDecrypt(localEncryptedVault, encryptionKey);
const serverDecrypted = await EncryptionUtility.symmetricDecrypt(vaultResponseJson.vault.blob, encryptionKey);
+ /*
+ * Guard for the sqlite-blob to manifest-v1 migration window: this device has already migrated its vault onto the current
+ * schema but the push has not landed yet, while another (not-yet-updated) device advanced the server's
+ * legacy sqlite-blob. The two databases have different column sets, so merging them would throw an error.
+ * We assume here the migrated local vault is newer, so it's pushed as-is.
+ */
+ if (await isLegacyStorageVault(serverDecrypted) && !await isLegacyStorageVault(localDecrypted)) {
+ devWarn('[VaultSync] Server vault is still on the legacy storage format while the local vault is migrated; skipping the merge and pushing the local vault.');
+ const uploadResponse = await handleUploadVault({ forceFullWrite: true });
+ if (uploadResponse.success && uploadResponse.status === 0) {
+ await handleMarkVaultClean({ mutationSeqAtStart: uploadResponse.mutationSeqAtStart!, newServerRevision: uploadResponse.newRevisionNumber! });
+ return { success: true, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: false };
+ }
+ if (uploadResponse.status === 2) {
+ return handleFullVaultSync();
+ }
+ return { success: false, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: false, error: uploadResponse.error };
+ }
+
const mergeResult = await vaultMergeService.merge(localDecrypted, serverDecrypted);
if (mergeResult.success) {
@@ -1593,7 +1677,7 @@ async function handleFullVaultSyncInternal(): Promise<FullVaultSyncResult> {
return handleFullVaultSync();
} else {
console.error('Failed to upload merged vault:', uploadResponse.error);
- return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: false, error: uploadResponse.error };
+ return { success: false, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: false, error: uploadResponse.error };
}
// Store metadata
@@ -1605,9 +1689,10 @@ async function handleFullVaultSyncInternal(): Promise<FullVaultSyncResult> {
// Check for pending migrations
const sqliteClient = await createVaultSqliteClient();
- const hasPendingMigrations = await sqliteClient.hasPendingMigrations();
+ const requiresLegacySqliteBlobMigration = await sqliteClient.requiresLegacySqliteBlobMigration();
+ const manifestMigrationRequired = await vaultRequiresManifestMigration(sqliteClient);
- return { success: true, hasNewVault: true, wasOffline: false, upgradeRequired: hasPendingMigrations, requiresLogout: false };
+ return { success: true, hasNewVault: true, wasOffline: false, sqliteBlobUpgradeRequired: requiresLegacySqliteBlobMigration, manifestMigrationRequired, requiresLogout: false };
} else {
console.error('Vault merge failed during sync, using server vault');
// Fall through to use server vault
@@ -1638,12 +1723,13 @@ async function handleFullVaultSyncInternal(): Promise<FullVaultSyncResult> {
// Check for pending migrations
const sqliteClient = await createVaultSqliteClient();
- const hasPendingMigrations = await sqliteClient.hasPendingMigrations();
+ const requiresLegacySqliteBlobMigration = await sqliteClient.requiresLegacySqliteBlobMigration();
+ const manifestMigrationRequired = await vaultRequiresManifestMigration(sqliteClient);
- return { success: true, hasNewVault: true, wasOffline: false, upgradeRequired: hasPendingMigrations, requiresLogout: false };
+ return { success: true, hasNewVault: true, wasOffline: false, sqliteBlobUpgradeRequired: requiresLegacySqliteBlobMigration, manifestMigrationRequired, requiresLogout: false };
} catch (error) {
if (error instanceof VaultVersionIncompatibleError) {
- return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: true, error: error.message };
+ return { success: false, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: true, error: error.message };
}
// E-501: Vault decryption failed
throw new Error(formatErrorWithCode(
@@ -1669,7 +1755,7 @@ async function handleFullVaultSyncInternal(): Promise<FullVaultSyncResult> {
* so the popup reloads the pruned vault instead of resurrecting the items
* from its stale in-memory copy on the next mutation.
*/
- return { success: true, hasNewVault: uploadResponse.vaultPruned === true, wasOffline: false, upgradeRequired: false, requiresLogout: false };
+ return { success: true, hasNewVault: uploadResponse.vaultPruned === true, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: false };
} else if (uploadResponse.status === 2) {
/**
* Server returned Outdated - another device uploaded first.
@@ -1678,11 +1764,11 @@ async function handleFullVaultSyncInternal(): Promise<FullVaultSyncResult> {
return handleFullVaultSync();
} else {
console.error('Failed to upload pending vault:', uploadResponse.error);
- return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: false, error: uploadResponse.error };
+ return { success: false, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: false, error: uploadResponse.error };
}
}
- return { success: true, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: false };
+ return { success: true, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: false };
} else if (serverManifestRevision < syncState.serverRevision) {
/**
* Server revision DECREASED - server data loss/rollback detected.
@@ -1709,7 +1795,7 @@ async function handleFullVaultSyncInternal(): Promise<FullVaultSyncResult> {
`Server recovery complete: rev ${serverManifestRevision} → ${uploadResponse.newRevisionNumber}`
);
- return { success: true, hasNewVault: uploadResponse.vaultPruned === true, wasOffline: false, upgradeRequired: false, requiresLogout: false };
+ return { success: true, hasNewVault: uploadResponse.vaultPruned === true, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: false };
} else if (uploadResponse.status === 2) {
// Another client recovered first
devLog('[VaultSync] Another client recovered server first, re-syncing...');
@@ -1717,38 +1803,41 @@ async function handleFullVaultSyncInternal(): Promise<FullVaultSyncResult> {
} else {
console.error('Server recovery failed:', uploadResponse.error);
// E-801: Upload failed during server recovery - preserve the upload error detail when available
- return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: false, error: uploadResponse.error ?? formatErrorWithCode(await t('common.errors.unknownError'), AppErrorCode.UPLOAD_FAILED) };
+ return { success: false, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: false, error: uploadResponse.error ?? formatErrorWithCode(await t('common.errors.unknownError'), AppErrorCode.UPLOAD_FAILED) };
}
}
// Check for pending migrations (for paths that didn't initialize a new database)
try {
const sqliteClient = await createVaultSqliteClient();
- const hasPendingMigrations = await sqliteClient.hasPendingMigrations();
- if (hasPendingMigrations) {
- return { success: true, hasNewVault: false, wasOffline: false, upgradeRequired: true, requiresLogout: false };
+ const requiresLegacySqliteBlobMigration = await sqliteClient.requiresLegacySqliteBlobMigration();
+ if (requiresLegacySqliteBlobMigration) {
+ return { success: true, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: true, requiresLogout: false };
+ }
+ if (await vaultRequiresManifestMigration(sqliteClient)) {
+ return { success: true, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, manifestMigrationRequired: true, requiresLogout: false };
}
} catch {
// Ignore errors checking migrations
}
- return { success: true, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: false };
+ return { success: true, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: false };
} catch (err) {
console.error('Vault sync error:', err);
// Version incompatibility requires logout
if (err instanceof VaultVersionIncompatibleError) {
- return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: true, error: err.message };
+ return { success: false, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: true, error: err.message };
}
// Auth error (session expired) - signal popup to trigger logout
if (err instanceof ApiAuthError) {
- return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: true, errorKey: 'sessionExpired' };
+ return { success: false, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: true, errorKey: 'sessionExpired' };
}
// E-805: Vault transfer timed out - show a targeted error instead of entering offline mode
if (err instanceof RequestTimeoutError) {
- return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: false, error: formatErrorWithCode(await t('common.errors.vaultSyncTimeout'), AppErrorCode.UPLOAD_TIMEOUT) };
+ return { success: false, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: false, error: formatErrorWithCode(await t('common.errors.vaultSyncTimeout'), AppErrorCode.UPLOAD_TIMEOUT) };
}
// Network error - enter offline mode if we have a local vault
@@ -1756,7 +1845,7 @@ async function handleFullVaultSyncInternal(): Promise<FullVaultSyncResult> {
const encryptedVault = await storage.getItem(StorageKeys.ENCRYPTED_VAULT);
if (encryptedVault) {
await storage.setItem(StorageKeys.IS_OFFLINE_MODE, true);
- return { success: true, hasNewVault: false, wasOffline: true, upgradeRequired: false, requiresLogout: false };
+ return { success: true, hasNewVault: false, wasOffline: true, sqliteBlobUpgradeRequired: false, requiresLogout: false };
}
}
@@ -1767,7 +1856,7 @@ async function handleFullVaultSyncInternal(): Promise<FullVaultSyncResult> {
const errorMessage = hasErrorCode
? baseMessage
: formatErrorWithCode(baseMessage, AppErrorCode.UNKNOWN_ERROR);
- return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: false, error: errorMessage };
+ return { success: false, hasNewVault: false, wasOffline: false, sqliteBlobUpgradeRequired: false, requiresLogout: false, error: errorMessage };
} finally {
// Reset sync in progress flag
isSyncInProgress = false;
diff --git a/apps/browser-extension/src/entrypoints/content.ts b/apps/browser-extension/src/entrypoints/content.ts
index 7816e9f8e..6d69369b4 100644
--- a/apps/browser-extension/src/entrypoints/content.ts
+++ b/apps/browser-extension/src/entrypoints/content.ts
@@ -816,7 +816,10 @@ export default defineContentScript({
return;
}
- if (authStatus.hasPendingMigrations) {
+ /*
+ * Check if the vault requires a migration, if so, show a popup to the user.
+ */
+ if (authStatus.requiresLegacySqliteBlobMigration || authStatus.requiresSchemaMigration) {
// Show upgrade required popup
await createUpgradeRequiredPopup(inputElement, container, await t('content.vaultUpgradeRequired'));
return;
diff --git a/apps/browser-extension/src/entrypoints/popup/App.tsx b/apps/browser-extension/src/entrypoints/popup/App.tsx
index e00886535..f984c5b7c 100644
--- a/apps/browser-extension/src/entrypoints/popup/App.tsx
+++ b/apps/browser-extension/src/entrypoints/popup/App.tsx
@@ -12,6 +12,7 @@ import { useLoading } from '@/entrypoints/popup/context/LoadingContext';
import { NavigationProvider } from '@/entrypoints/popup/context/NavigationContext';
import AuthSettings from '@/entrypoints/popup/pages/auth/AuthSettings';
import Login from '@/entrypoints/popup/pages/auth/Login';
+import ManifestMigration from '@/entrypoints/popup/pages/auth/ManifestMigration';
import Unlock from '@/entrypoints/popup/pages/auth/Unlock';
import UnlockSuccess from '@/entrypoints/popup/pages/auth/UnlockSuccess';
import Upgrade from '@/entrypoints/popup/pages/auth/Upgrade';
@@ -187,6 +188,7 @@ const App: React.FC = () => {
{ path: '/unlock', element: <Unlock />, showBackButton: false, layout: LayoutType.AUTH },
{ path: '/unlock-success', element: <UnlockSuccess />, showBackButton: false },
{ path: '/upgrade', element: <Upgrade />, showBackButton: false },
+ { path: '/manifest-migration', element: <ManifestMigration />, showBackButton: false },
{ path: '/auth-settings', element: <AuthSettings />, showBackButton: true, title: t('common.settings') },
{ path: '/items', element: <ItemsList />, showBackButton: false },
{ path: '/items/folder/:folderId', element: <ItemsList />, showBackButton: true },
diff --git a/apps/browser-extension/src/entrypoints/popup/context/DbContext.tsx b/apps/browser-extension/src/entrypoints/popup/context/DbContext.tsx
index f18dd424d..f801e06f4 100644
--- a/apps/browser-extension/src/entrypoints/popup/context/DbContext.tsx
+++ b/apps/browser-extension/src/entrypoints/popup/context/DbContext.tsx
@@ -8,6 +8,7 @@ import SqliteClient from '@/utils/SqliteClient';
import { getItemWithFallback } from '@/utils/StorageUtility';
import { AppErrorCode, formatErrorWithCode } from '@/utils/types/errors/AppErrorCodes';
import type { VaultResponse as messageVaultResponse } from '@/utils/types/messaging/VaultResponse';
+import { vaultRequiresManifestMigration } from '@/utils/VaultManifestMigration';
import { markOwnEncryptionKey, vaultStateEvents } from '@/events/VaultStateEvents';
@@ -86,7 +87,8 @@ type DbContextType = {
* Refresh sync state (isDirty, serverRevision) from storage.
*/
refreshSyncState: () => Promise<void>;
- hasPendingMigrations: () => Promise<boolean>;
+ requiresLegacySqliteBlobMigration: () => Promise<boolean>;
+ requiresManifestMigration: () => Promise<boolean>;
/**
* Last sync error message persisted by the background sync. Surfaced as a popup
* alert. Null when no error is pending. Updated reactively via storage.watch so
@@ -353,11 +355,21 @@ export const DbProvider: React.FC<{ children: React.ReactNode }> = ({ children }
/**
* Check if there are pending migrations.
*/
- const hasPendingMigrations = useCallback(async () => {
+ const requiresLegacySqliteBlobMigration = useCallback(async () => {
if (!sqliteClient) {
return false;
}
- return await sqliteClient.hasPendingMigrations();
+ return await sqliteClient.requiresLegacySqliteBlobMigration();
+ }, [sqliteClient]);
+
+ /**
+ * Check if the vault still has to be migrated to the current storage model.
+ */
+ const requiresManifestMigration = useCallback(async () => {
+ if (!sqliteClient) {
+ return false;
+ }
+ return await vaultRequiresManifestMigration(sqliteClient);
}, [sqliteClient]);
/**
@@ -425,10 +437,11 @@ export const DbProvider: React.FC<{ children: React.ReactNode }> = ({ children }
clearDatabase,
getVaultMetadata,
refreshSyncState,
- hasPendingMigrations,
+ requiresLegacySqliteBlobMigration,
+ requiresManifestMigration,
syncError,
clearSyncError,
- }), [sqliteClient, dbInitialized, dbAvailable, isOffline, getIsOffline, isDirty, isSyncing, isUploading, serverRevision, setIsOffline, shouldSuppressEmailErrors, loadDatabase, loadStoredDatabase, storeEncryptionKey, storeEncryptionKeyDerivationParams, clearDatabase, getVaultMetadata, refreshSyncState, hasPendingMigrations, syncError, clearSyncError]);
+ }), [sqliteClient, dbInitialized, dbAvailable, isOffline, getIsOffline, isDirty, isSyncing, isUploading, serverRevision, setIsOffline, shouldSuppressEmailErrors, loadDatabase, loadStoredDatabase, storeEncryptionKey, storeEncryptionKeyDerivationParams, clearDatabase, getVaultMetadata, refreshSyncState, requiresLegacySqliteBlobMigration, requiresManifestMigration, syncError, clearSyncError]);
return (
<DbContext.Provider value={contextValue}>
diff --git a/apps/browser-extension/src/entrypoints/popup/hooks/useVaultSync.ts b/apps/browser-extension/src/entrypoints/popup/hooks/useVaultSync.ts
index cf613163b..920cdebe1 100644
--- a/apps/browser-extension/src/entrypoints/popup/hooks/useVaultSync.ts
+++ b/apps/browser-extension/src/entrypoints/popup/hooks/useVaultSync.ts
@@ -11,7 +11,8 @@ type VaultSyncOptions = {
onError?: (error: string) => void;
onStatus?: (message: string) => void;
onOffline?: () => void;
- onUpgradeRequired?: () => void;
+ onLegacySqliteBlobUpgradeRequired?: () => void;
+ onManifestMigrationRequired?: () => void;
}
/**
@@ -36,7 +37,7 @@ export const useVaultSync = (): { syncVault: (options?: VaultSyncOptions) => Pro
const dbContext = useDb();
const syncVault = useCallback(async (options: VaultSyncOptions = {}) => {
- const { onSuccess, onError, onStatus, onOffline, onUpgradeRequired } = options;
+ const { onSuccess, onError, onStatus, onOffline, onLegacySqliteBlobUpgradeRequired, onManifestMigrationRequired } = options;
try {
// Check if user is logged in first
@@ -74,9 +75,17 @@ export const useVaultSync = (): { syncVault: (options?: VaultSyncOptions) => Pro
await dbContext.setIsOffline(false);
}
- // Handle upgrade requirement
- if (result.upgradeRequired) {
- onUpgradeRequired?.();
+ // Handle upgrade requirement (sqlite-blob upgrade chain, needs the user to confirm)
+ if (result.sqliteBlobUpgradeRequired) {
+ onLegacySqliteBlobUpgradeRequired?.();
+ return false;
+ }
+
+ /*
+ * Handle the manifest migration.
+ */
+ if (result.manifestMigrationRequired) {
+ onManifestMigrationRequired?.();
return false;
}
diff --git a/apps/browser-extension/src/entrypoints/popup/pages/Reinitialize.tsx b/apps/browser-extension/src/entrypoints/popup/pages/Reinitialize.tsx
index 71b1d7ccb..4d16f7de3 100644
--- a/apps/browser-extension/src/entrypoints/popup/pages/Reinitialize.tsx
+++ b/apps/browser-extension/src/entrypoints/popup/pages/Reinitialize.tsx
@@ -35,7 +35,7 @@ const Reinitialize: React.FC = () => {
// Auth and DB state
const { isInitialized: authInitialized, isLoggedIn } = useApp();
- const { dbInitialized, dbAvailable, refreshSyncState, hasPendingMigrations } = useDb();
+ const { dbInitialized, dbAvailable, refreshSyncState, requiresLegacySqliteBlobMigration, requiresManifestMigration } = useDb();
// Derived state
const isFullyInitialized = authInitialized && dbInitialized;
@@ -148,11 +148,17 @@ const Reinitialize: React.FC = () => {
await refreshSyncState();
},
/**
- * Handle upgrade required - redirect to upgrade page.
+ * Handle sqlite-blob legacy upgrade.
*/
- onUpgradeRequired: () => {
+ onLegacySqliteBlobUpgradeRequired: () => {
navigate('/upgrade', { replace: true });
},
+ /**
+ * Handle sqlite-blob to manifest-v1 migration.
+ */
+ onManifestMigrationRequired: () => {
+ navigate('/manifest-migration', { replace: true });
+ },
/**
* Handle sync errors silently - user already has local vault.
* @param error Error message
@@ -192,13 +198,23 @@ const Reinitialize: React.FC = () => {
return;
}
- // Check for pending migrations before navigating
- if (await hasPendingMigrations()) {
+ /*
+ * Check both vault upgrade gates before navigating. Order matters: a pre-2.0.0 vault has to walk the
+ * sqlite-blob upgrade chain (/upgrade, user-confirmed) before it is eligible for the manifest migration
+ * (/manifest-migration, automatic). The apps queries assume the current schema, so rendering any other page
+ * before running the migrations would throw on the missing columns.
+ */
+ if (await requiresLegacySqliteBlobMigration()) {
setIsInitialLoading(false);
navigate('/upgrade', { replace: true });
return;
}
+ if (await requiresManifestMigration()) {
+ navigate('/manifest-migration', { replace: true });
+ return;
+ }
+
/**
* Navigate immediately using local vault without waiting for sync.
* This ensures the UI is responsive even if server is slow to respond.
@@ -222,7 +238,7 @@ const Reinitialize: React.FC = () => {
};
handleInitialization();
- }, [isFullyInitialized, requiresAuth, isLoggedIn, dbAvailable, location.key, navigate, setIsInitialLoading, restoreLastPage, hasPendingMigrations, runBackgroundSync]);
+ }, [isFullyInitialized, requiresAuth, isLoggedIn, dbAvailable, location.key, navigate, setIsInitialLoading, restoreLastPage, requiresLegacySqliteBlobMigration, requiresManifestMigration, runBackgroundSync]);
// This component doesn't render anything visible, it only handles initialization logic.
return null;
diff --git a/apps/browser-extension/src/entrypoints/popup/pages/auth/Login.tsx b/apps/browser-extension/src/entrypoints/popup/pages/auth/Login.tsx
index 7b522f148..2af8072e4 100644
--- a/apps/browser-extension/src/entrypoints/popup/pages/auth/Login.tsx
+++ b/apps/browser-extension/src/entrypoints/popup/pages/auth/Login.tsx
@@ -190,7 +190,7 @@ const Login: React.FC = () => {
/*
* Navigate to reinitialize page which will:
* 1. Call syncVault() to check version compatibility
- * 2. Handle pending migrations via onUpgradeRequired callback
+ * 2. Send the vault through /upgrade (legacy sqlite-blob chain) and/or /manifest-migration when those gates apply
* 3. Navigate to appropriate page
*
* Other windows on /login or /unlock pick up the encryption-key storage
@@ -487,7 +487,7 @@ const Login: React.FC = () => {
/*
* Navigate to reinitialize page which will:
* 1. Call syncVault() to check version compatibility
- * 2. Handle pending migrations via onUpgradeRequired callback
+ * 2. Send the vault through /upgrade (legacy sqlite-blob chain) and/or /manifest-migration when those gates apply
* 3. Navigate to appropriate page
*/
hideLoading();
diff --git a/apps/browser-extension/src/entrypoints/popup/pages/auth/ManifestMigration.tsx b/apps/browser-extension/src/entrypoints/popup/pages/auth/ManifestMigration.tsx
new file mode 100644
index 000000000..8375a21fb
--- /dev/null
+++ b/apps/browser-extension/src/entrypoints/popup/pages/auth/ManifestMigration.tsx
@@ -0,0 +1,160 @@
+import React, { useState, useEffect, useCallback, useRef } from 'react';
+import { useTranslation } from 'react-i18next';
+import { useNavigate } from 'react-router-dom';
+
+import Button from '@/entrypoints/popup/components/Button';
+import LogoutConfirmModal from '@/entrypoints/popup/components/Dialogs/LogoutConfirmModal';
+import HeaderButton from '@/entrypoints/popup/components/HeaderButton';
+import { HeaderIconType } from '@/entrypoints/popup/components/Icons/HeaderIcons';
+import LoadingSpinner from '@/entrypoints/popup/components/LoadingSpinner';
+import { useAuth } from '@/entrypoints/popup/context/AuthContext';
+import { useDb } from '@/entrypoints/popup/context/DbContext';
+import { useHeaderButtons } from '@/entrypoints/popup/context/HeaderButtonsContext';
+import { useLoading } from '@/entrypoints/popup/context/LoadingContext';
+import { useWebApi } from '@/entrypoints/popup/context/WebApiContext';
+import { PopoutUtility } from '@/entrypoints/popup/utils/PopoutUtility';
+
+import { sendMessage } from '@/utils/messaging/ExtensionMessaging';
+
+/**
+ * Manifest migration page.
+ *
+ * Rebuilds the local vault onto the current storage schema — the delivery path for all post-2.0.0 schema
+ * changes, including the initial legacy `sqlite-blob` to manifest-v1 transition. Migration is automatic by design.
+ */
+const ManifestMigration: React.FC = () => {
+ const { t } = useTranslation();
+ const auth = useAuth();
+ const webApi = useWebApi();
+ const navigate = useNavigate();
+ const { setHeaderButtons } = useHeaderButtons();
+ const { setIsInitialLoading } = useLoading();
+ const { loadStoredDatabase, refreshSyncState } = useDb();
+
+ const [error, setError] = useState<string | null>(null);
+ const [showLogoutConfirm, setShowLogoutConfirm] = useState(false);
+ const hasStarted = useRef(false);
+
+ // Set header buttons on mount and clear on unmount
+ useEffect((): (() => void) => {
+ const headerButtonsJSX = !PopoutUtility.isPopup() ? (
+ <HeaderButton
+ onClick={() => PopoutUtility.openInNewPopup()}
+ title={t('common.openInNewWindow')}
+ iconType={HeaderIconType.EXPAND}
+ />
+ ) : null;
+
+ setHeaderButtons(headerButtonsJSX);
+
+ return () => {
+ setHeaderButtons(null);
+ };
+ }, [setHeaderButtons, t]);
+
+ /**
+ * Run the migration and continue into the app as soon as the local vault is on the current schema.
+ */
+ const runMigration = useCallback(async (): Promise<void> => {
+ setError(null);
+
+ const result = await sendMessage('MIGRATE_VAULT_MANIFEST');
+
+ if (!result.success) {
+ setError(result.error ?? t('common.errors.unknownError'));
+ setIsInitialLoading(false);
+ return;
+ }
+
+ /*
+ * The background stored a new vault blob, so the popup's in-memory copy is stale. Reload before navigating,
+ * otherwise the items list would run its queries against the pre-migration database.
+ */
+ await loadStoredDatabase();
+ await refreshSyncState();
+
+ if (!result.pushed) {
+ // Local vault is migrated and usable; the upload stays pending and the next sync picks it up.
+ console.warn('Vault manifest migration completed locally but has not reached the server yet.');
+ }
+
+ navigate('/items', { replace: true });
+ }, [loadStoredDatabase, refreshSyncState, navigate, setIsInitialLoading, t]);
+
+ // Start automatically on mount; the ref keeps a re-render from launching a second migration.
+ useEffect(() => {
+ if (hasStarted.current) {
+ return;
+ }
+ hasStarted.current = true;
+ runMigration();
+ }, [runMigration]);
+
+ /**
+ * Retry after a failed migration.
+ */
+ const handleRetry = useCallback((): void => {
+ setIsInitialLoading(true);
+ runMigration();
+ }, [runMigration, setIsInitialLoading]);
+
+ /**
+ * Handle the logout (after confirmation).
+ * Uses clearAuthUserInitiated to fully clear vault data since user explicitly chose to logout.
+ */
+ const handleLogout = async (): Promise<void> => {
+ setShowLogoutConfirm(false);
+ try {
+ await webApi.revokeTokens();
+ await auth.clearAuthUserInitiated();
+ } catch (error) {
+ console.error('Error during logout:', error);
+ }
+ };
+
+ if (!error) {
+ return (
+ <div className="flex flex-col justify-center items-center py-12">
+ <LoadingSpinner />
+ <div className="text-sm text-gray-500 dark:text-gray-400 mt-4 px-6 text-center">
+ {t('manifestMigration.migrating')}
+ </div>
+ </div>
+ );
+ }
+
+ return (
+ <div className="w-full px-2 pt-2 pb-2 mb-4">
+ <LogoutConfirmModal
+ isOpen={showLogoutConfirm}
+ onClose={() => setShowLogoutConfirm(false)}
+ onConfirm={handleLogout}
+ />
+
+ <h2 className="text-xl font-bold dark:text-gray-200 mb-4">{t('manifestMigration.failedTitle')}</h2>
+
+ <p className="mb-4 text-sm text-gray-600 dark:text-gray-300">
+ {t('manifestMigration.failedDescription')}
+ </p>
+
+ <div className="mb-6 bg-gray-50 dark:bg-gray-800 rounded p-4 text-sm text-red-500 dark:text-red-400 break-words">
+ {error}
+ </div>
+
+ <div className="flex flex-col w-full space-y-2">
+ <Button type="button" id="manifest-migration-retry-button" onClick={handleRetry}>
+ {t('common.retry')}
+ </Button>
+ <button
+ type="button"
+ onClick={() => setShowLogoutConfirm(true)}
+ className="text-red-500 hover:text-red-700 dark:text-red-400 dark:hover:text-red-300 text-sm font-medium py-2"
+ >
+ {t('common.logout')}
+ </button>
+ </div>
+ </div>
+ );
+};
+
+export default ManifestMigration;
diff --git a/apps/browser-extension/src/entrypoints/popup/pages/auth/Unlock.tsx b/apps/browser-extension/src/entrypoints/popup/pages/auth/Unlock.tsx
index 9fcfbeb1e..29a6ced5a 100644
--- a/apps/browser-extension/src/entrypoints/popup/pages/auth/Unlock.tsx
+++ b/apps/browser-extension/src/entrypoints/popup/pages/auth/Unlock.tsx
@@ -333,7 +333,7 @@ const Unlock: React.FC = () => {
}
// Check if there are pending migrations
- if (await sqliteClient.hasPendingMigrations()) {
+ if (await sqliteClient.requiresLegacySqliteBlobMigration()) {
navigate('/upgrade', { replace: true });
hideLoading();
return;
@@ -456,7 +456,7 @@ const Unlock: React.FC = () => {
}
// Check if there are pending migrations
- if (await sqliteClient.hasPendingMigrations()) {
+ if (await sqliteClient.requiresLegacySqliteBlobMigration()) {
navigate('/upgrade', { replace: true });
hideLoading();
return;
@@ -609,7 +609,7 @@ const Unlock: React.FC = () => {
}
// Check if there are pending migrations
- if (await sqliteClient.hasPendingMigrations()) {
+ if (await sqliteClient.requiresLegacySqliteBlobMigration()) {
navigate('/upgrade', { replace: true });
hideLoading();
return;
diff --git a/apps/browser-extension/src/entrypoints/popup/pages/auth/Upgrade.tsx b/apps/browser-extension/src/entrypoints/popup/pages/auth/Upgrade.tsx
index 2d58febac..ac2a3a43e 100644
--- a/apps/browser-extension/src/entrypoints/popup/pages/auth/Upgrade.tsx
+++ b/apps/browser-extension/src/entrypoints/popup/pages/auth/Upgrade.tsx
@@ -23,6 +23,10 @@ import { VaultSqlGenerator } from '@/utils/dist/core/vault';
/**
* Upgrade page for handling vault version upgrades.
+ *
+ * TODO: this page walks the sqlite-blob upgrade chain (frozen at 2.0.0) and can be deleted, together with
+ * requiresLegacySqliteBlobMigration, once all users have migrated. New schema changes are handled via the automatic
+ * /manifest-migration flow (requiresSchemaMigration / migrateVaultToCurrentSchema) instead.
*/
const Upgrade: React.FC = () => {
const { t } = useTranslation();
@@ -174,6 +178,12 @@ const Upgrade: React.FC = () => {
// Navigate to items page
navigate('/items');
},
+ /**
+ * Handle the manifest migration that follows this upgrade.
+ */
+ onManifestMigrationRequired: () => {
+ navigate('/manifest-migration', { replace: true });
+ },
/**
* Handle sync error.
* @param error Error message
diff --git a/apps/browser-extension/src/utils/LegacyVaultKeyMigration.ts b/apps/browser-extension/src/utils/LegacyVaultKeyMigration.ts
new file mode 100644
index 000000000..a764c9e80
--- /dev/null
+++ b/apps/browser-extension/src/utils/LegacyVaultKeyMigration.ts
@@ -0,0 +1,12 @@
+import { VaultKeyService } from '@/utils/VaultKeyService';
+
+/**
+ * One-time KEK/VEK migration: vaults created before the vault key existed have to create one, which happens as
+ * part of their next full push (see `handleUploadVault`).
+ *
+ * TODO: this file is the legacy part of the /manifest-migration gate. This can be deleted once all users have
+ * migrated to the manifest-v1 storage model.
+ */
+export async function requiresLegacyVaultKeyMigration(): Promise<boolean> {
+ return !await VaultKeyService.hasLocalVaultKey();
+}
diff --git a/apps/browser-extension/src/utils/SqliteClient.ts b/apps/browser-extension/src/utils/SqliteClient.ts
index 2b12fe550..f3807874d 100644
--- a/apps/browser-extension/src/utils/SqliteClient.ts
+++ b/apps/browser-extension/src/utils/SqliteClient.ts
@@ -3,6 +3,7 @@ import initSqlJs, { Database } from 'sql.js';
import type { VaultVersion } from '@/utils/dist/core/vault';
import { VaultSqlGenerator, checkVersionCompatibility, extractVersionFromMigrationId } from '@/utils/dist/core/vault';
import { VaultVersionIncompatibleError } from '@/utils/types/errors/VaultVersionIncompatibleError';
+import { VaultCodec } from '@/utils/VaultCodec';
import { t } from '@/i18n/StandaloneI18n';
@@ -312,6 +313,9 @@ export class SqliteClient implements IDatabaseClient {
/**
* Get the current database version from the migrations history.
+ *
+ * TODO: part of the sqlite-blob upgrade chain (frozen up to 2.0.0); delete once all users
+ * have migrated. New schema changes ship via requiresSchemaMigration / migrateVaultToCurrentSchema instead.
* @returns The database version information
*/
public async getDatabaseVersion(): Promise<VaultVersion> {
@@ -366,6 +370,9 @@ export class SqliteClient implements IDatabaseClient {
/**
* Get the latest available database version.
+ *
+ * TODO: part of the sqlite-blob upgrade chain (frozen up to 2.0.0); delete once all users
+ * have migrated. New schema changes ship via requiresSchemaMigration / migrateVaultToCurrentSchema instead.
* @returns The latest VaultVersion
*/
public async getLatestDatabaseVersion(): Promise<VaultVersion> {
@@ -375,10 +382,14 @@ export class SqliteClient implements IDatabaseClient {
}
/**
- * Check if there are pending migrations.
+ * Whether the vault still has to walk the sqlite-blob upgrade chain (VAULT_VERSIONS, frozen at 2.0.0) via the /upgrade
+ * page before it is eligible for anything else.
+ *
+ * TODO: this is the legacy sqlite-blob migration path, which we will stop supporting later; delete once all
+ * users have migrated. New schema changes ship via requiresSchemaMigration / migrateVaultToCurrentSchema instead.
* @returns True if there are pending migrations
*/
- public async hasPendingMigrations(): Promise<boolean> {
+ public async requiresLegacySqliteBlobMigration(): Promise<boolean> {
try {
const currentVersion = await this.getDatabaseVersion();
const latestVersion = await this.getLatestDatabaseVersion();
@@ -390,6 +401,31 @@ export class SqliteClient implements IDatabaseClient {
}
}
+ /**
+ * Whether the local database schema is older than the current full schema (COMPLETE_SCHEMA_SQL).
+ *
+ * @returns True when the local schema predates the current full schema
+ */
+ public async requiresSchemaMigration(): Promise<boolean> {
+ if (await this.requiresLegacySqliteBlobMigration()) {
+ /*
+ * Still on the sqlite-blob upgrade chain: that upgrade has to run first, so the migration is not applicable yet.
+ * TODO: delete once all users have migrated.
+ */
+ return false;
+ }
+
+ const localMigrationId = VaultCodec.getLatestMigrationId(this);
+ const schemaMigrationId = VaultCodec.getSchemaMigrationId(new VaultSqlGenerator().getCompleteSchemaSql());
+
+ // An unstamped database or an unreadable schema constant gives no evidence of staleness; don't block on a guess.
+ if (!localMigrationId || !schemaMigrationId) {
+ return false;
+ }
+
+ return localMigrationId < schemaMigrationId;
+ }
+
/**
* Convert binary data to a base64 encoded image source.
* @param bytes - Binary image data
diff --git a/apps/browser-extension/src/utils/VaultCodec.ts b/apps/browser-extension/src/utils/VaultCodec.ts
index 3f41ba373..1c66e9784 100644
--- a/apps/browser-extension/src/utils/VaultCodec.ts
+++ b/apps/browser-extension/src/utils/VaultCodec.ts
@@ -86,6 +86,15 @@ export class VaultCodec {
}
}
+ /**
+ * The migration ID a freshly created database would be stamped with.
+ * @param schemaSql - the COMPLETE_SCHEMA_SQL string for the target client version
+ */
+ public static getSchemaMigrationId(schemaSql: string): string {
+ const ids = [...schemaSql.matchAll(/INSERT\s+INTO\s+"__EFMigrationsHistory"[^;]*?VALUES\s*\(\s*'([^']+)'/gi)].map(m => m[1]);
+ return ids.length === 0 ? '' : ids.reduce((a, b) => (b > a ? b : a));
+ }
+
/**
* The column set of the local client schema, per table: the input Rust's materialize uses to
* split off anything a newer writer stored that this schema cannot hold (see `CodecOverflow`).
diff --git a/apps/browser-extension/src/utils/VaultManifestMigration.ts b/apps/browser-extension/src/utils/VaultManifestMigration.ts
new file mode 100644
index 000000000..19d5583ec
--- /dev/null
+++ b/apps/browser-extension/src/utils/VaultManifestMigration.ts
@@ -0,0 +1,18 @@
+import { requiresLegacyVaultKeyMigration } from '@/utils/LegacyVaultKeyMigration';
+import type { SqliteClient } from '@/utils/SqliteClient';
+
+/**
+ * Whether the vault still has to run the manifest migration — the predicate behind the /manifest-migration gate,
+ * answered entirely from local state.
+ *
+ * Two conditions, carried independently of each other:
+ * 1. A stale local schema, rebuilt via `VaultSyncService.migrateVaultToCurrentSchema`. This is the permanent path:
+ * it delivered the initial sqlite-blob to manifest-v1 transition and fires again after every schema change we ship.
+ * 2. A missing vault key ({@link requiresLegacyVaultKeyMigration}), one-time and deletable — see that file.
+ *
+ * Callers must check `requiresLegacySqliteBlobMigration()` FIRST — a pre-2.0.0 vault has to walk the sqlite-blob upgrade chain before either condition here can be acted on.
+ * @param sqliteClient - the open local vault
+ */
+export async function vaultRequiresManifestMigration(sqliteClient: SqliteClient): Promise<boolean> {
+ return await sqliteClient.requiresSchemaMigration() || await requiresLegacyVaultKeyMigration();
+}
diff --git a/apps/browser-extension/src/utils/VaultSyncService.ts b/apps/browser-extension/src/utils/VaultSyncService.ts
index 4761cb6ff..09a9eec90 100644
--- a/apps/browser-extension/src/utils/VaultSyncService.ts
+++ b/apps/browser-extension/src/utils/VaultSyncService.ts
@@ -17,14 +17,11 @@ import { SharingService, type SessionSharedFolder } from '@/utils/SharingService
import { SqliteClient } from '@/utils/SqliteClient';
import { ServerUpdateRequiredError } from '@/utils/types/errors/ServerUpdateRequiredError';
import { VaultProcessingError } from '@/utils/types/errors/VaultProcessingError';
-import { type BlobEntry, type VaultManifest, type VaultDataBucket, VaultCodec } from '@/utils/VaultCodec';
-import { VaultKeyService } from '@/utils/VaultKeyService';
+import { type VaultManifest, type VaultDataBucket, VaultCodec } from '@/utils/VaultCodec';
import { WebApiService } from '@/utils/WebApiService';
-// Endpoints are relative; WebApiService resolves them under the API's /v2/ prefix.
-const SNAPSHOT_ENDPOINT = 'Vault';
-const UPLOAD_ENDPOINT = 'Vault';
-const BLOBS_UPLOAD_ENDPOINT = 'Vault/blobs';
+const VAULT_ENDPOINT = 'Vault';
+const BLOBS_VAULT_ENDPOINT = 'Vault/blobs';
const BLOBS_MISSING_ENDPOINT = 'Vault/blobs/missing';
const BLOBS_DOWNLOAD_ENDPOINT = 'Vault/blobs/download';
@@ -78,13 +75,18 @@ async function timedStage<T>(stage: string, fn: () => Promise<T> | T): Promise<T
}
/**
- * Decrypt a manifest/bucket ciphertext and open it via the Rust codec: gunzip, verify the embedded
- * content hash, and return the inner payload JSON string. Throws if the content hash mismatches
- * (possible application-layer corruption).
- * @param base64Ciphertext - base64(IV ‖ ciphertext ‖ tag) from the server
+ * Verify a ciphertext against the hash the server stored (storage-layer integrity, skipped when the server sent
+ * no hash), then decrypt it and open it via the Rust codec: gunzip, verify the embedded content hash, and return
+ * the inner payload JSON string. Throws on either hash mismatch (storage or application-layer corruption).
+ * @param base64Ciphertext - base64(IV | ciphertext | tag) from the server
* @param vek - symmetric encryption key
+ * @param expectedCiphertextHash - the ciphertext hash the server stored, when available
+ * @param label - what is being opened, for the mismatch error message (e.g. `manifest`, `"Settings" bucket`)
*/
-async function decryptUnpack(base64Ciphertext: string, vek: string): Promise<string> {
+async function verifyDecryptUnpack(base64Ciphertext: string, vek: string, expectedCiphertextHash: string | null | undefined, label: string): Promise<string> {
+ if (expectedCiphertextHash && await vaultCodecComputeCiphertextHash(base64Ciphertext) !== expectedCiphertextHash) {
+ throw new Error(`VaultSyncService: ${label} ciphertext hash mismatch, refusing to load. Possible storage corruption.`);
+ }
const encryptedBytes = Uint8Array.from(atob(base64Ciphertext), c => c.charCodeAt(0));
const plainBytes = await EncryptionUtility.symmetricDecryptBytes(encryptedBytes, vek);
return vaultCodecUnpackPayload(plainBytes);
@@ -101,26 +103,12 @@ const BLOB_UPLOAD_BATCH_MAX_CHARS = 4 * 1024 * 1024;
/** Hashes per POST /v2/Vault/blobs/download call. */
const BLOB_DOWNLOAD_BATCH_SIZE = 100;
-/** Bucket category for the encryption-keys data bucket (the user's asymmetric keypair). */
-const ENCRYPTION_KEYS_BUCKET_CATEGORY = VaultDataBucketCategory.EncryptionKeys;
-
-/**
- * Email routing block as returned by the snapshot (server-readable plaintext, used for email delivery).
- */
-export type EmailRouting = {
- emailAddressList: string[];
- privateEmailDomainList: string[];
- hiddenPrivateEmailDomainList: string[];
- publicEmailDomainList: string[];
-};
-
/**
- * Result of a pull: the materialized SQLite plus the side-channel data the caller needs to build a VaultResponse.
+ * Result of a pull: the materialized SQLite plus its manifest revision.
*/
-export type PullResult = {
+type PullResult = {
sqliteBase64: string;
manifestRevision: number;
- emailRouting: EmailRouting;
};
/**
@@ -140,6 +128,9 @@ export type PushResult = {
type BlobRefDto = { hash: string; category: string };
type BlobDto = { hash: string; category: string; encryptedDataBase64: string };
+/** A plaintext blob staged for upload: its bytes plus the key that encrypts it (root VEK or the folder's own VEK). */
+type UploadBlobEntry = { bytes: Uint8Array; kind: 'favicon' | 'attachment'; vek: string };
+
/**
* A single manifest as carried in the GET snapshot / single-manifest fetch.
*/
@@ -306,6 +297,50 @@ export class VaultSyncService {
}
}
+ /**
+ * Migrate the local vault onto the current full schema, entirely locally: canonicalize the database into
+ * manifest-v1 form and materialize it straight back out again so it works offline too.
+ *
+ * This is the permanent delivery path for client schema changes (`SqliteClient.requiresSchemaMigration`).
+ * It runs for a legacy `sqlite-blob` vault whose schema stops at the frozen sqlite-blob upgrade chain, and equally for a
+ * manifest-v1 vault materialized by an older client whenever a newer COMPLETE_SCHEMA_SQL ships.
+ * @param sqliteClient - the local vault to migrate
+ * @returns Base64 of the migrated SQLite database (plaintext; the caller encrypts and stores it)
+ */
+ public async migrateVaultToCurrentSchema(sqliteClient: SqliteClient): Promise<string> {
+ devLog('[ManifestMigration] Migrating local vault onto the current schema (local round-trip, no server involved)...');
+
+ try {
+ const { canonicalized } = await this.canonicalizeVault(sqliteClient);
+
+ /*
+ * Canonicalize already handed us every extracted favicon/attachment as plaintext bytes, so materialize can
+ * resolve its blob references without a single fetch.
+ */
+ const blobMap = new Map<string, Uint8Array>();
+ for (const [hash, entry] of Object.entries(canonicalized.blobs)) {
+ blobMap.set(hash, VaultCodec.base64ToBytes(entry.bytesBase64));
+ }
+ for (const sharedVault of canonicalized.sharedVaults ?? []) {
+ for (const [hash, entry] of Object.entries(sharedVault.blobs)) {
+ blobMap.set(hash, VaultCodec.base64ToBytes(entry.bytesBase64));
+ }
+ }
+
+ const schemaSql = new VaultSqlGenerator().getCompleteSchemaSql();
+ const schemaColumns = await VaultCodec.getSchemaColumns(schemaSql);
+ const sharedManifests = (canonicalized.sharedVaults ?? []).map(v => v.manifest);
+ const materialized = await vaultCodecMaterializeAsSqlite(canonicalized.manifest, canonicalized.dataBuckets, schemaColumns, sharedManifests);
+ const sqliteBase64 = await VaultCodec.insertTables(materialized, blobMap, schemaSql);
+
+ devLog(`[ManifestMigration] Migration complete: ${blobMap.size} blobs re-embedded, ${sqliteBase64.length} base64 chars.`);
+ return sqliteBase64;
+ } catch (error) {
+ devError('[ManifestMigration] FAILED to migrate the local vault:', error);
+ throw new VaultProcessingError('vault-storage-migration', error);
+ }
+ }
+
/**
* Run a write against the v2 API and translate the outdated-server 404 into {@link ServerUpdateRequiredError}.
* TODO: this wrapper can be deleted once enough time has passed since the v2 API was introduced (so all self-hosted installs have had time to upgrade).
@@ -326,15 +361,7 @@ export class VaultSyncService {
* Fetch the raw snapshot (GET /v2/Vault) without decrypting/reassembling. Throws error if the server predates the v2 API.
*/
private async fetchSnapshot(): Promise<GetResponseDto> {
- const webApi = new WebApiService();
- try {
- return await webApi.get<GetResponseDto>(SNAPSHOT_ENDPOINT);
- } catch (e) {
- if (isNotFoundError(e)) {
- throw new ServerUpdateRequiredError();
- }
- throw e;
- }
+ return this.withOutdatedServerGuard(() => new WebApiService().get<GetResponseDto>(VAULT_ENDPOINT));
}
/**
@@ -355,16 +382,8 @@ export class VaultSyncService {
throw new Error('VaultSyncService: server returned no manifest blob, nothing to assemble.');
}
- // Storage-layer integrity: verify the ciphertext we received matches the hash the server stored.
- if (rootManifest.ciphertextHash) {
- const actual = await vaultCodecComputeCiphertextHash(rootManifest.blob);
- if (actual !== rootManifest.ciphertextHash) {
- throw new Error('VaultSyncService: manifest ciphertext hash mismatch, refusing to load. Possible storage corruption.');
- }
- }
-
- devLog('[V2Pull] Manifest ciphertext hash verified; decrypting + opening manifest...');
- const manifestJson = await decryptUnpack(rootManifest.blob, vek);
+ devLog('[V2Pull] Verifying manifest ciphertext hash; decrypting + opening manifest...');
+ const manifestJson = await verifyDecryptUnpack(rootManifest.blob, vek, rootManifest.ciphertextHash, 'manifest');
const manifest = JSON.parse(manifestJson) as VaultManifest;
devLog(`[V2Pull] Manifest opened (content hash verified): schemaVersion=${manifest.schemaVersion}, migrationId=${manifest.migrationId}, tables: ${Object.entries(manifest.tables).map(([t, rows]) => `${t}=${rows.length}`).join(', ')}`);
@@ -396,13 +415,7 @@ export class VaultSyncService {
if (!bucketDto.blob) {
continue;
}
- if (bucketDto.ciphertextHash) {
- const actual = await vaultCodecComputeCiphertextHash(bucketDto.blob);
- if (actual !== bucketDto.ciphertextHash) {
- throw new Error(`VaultSyncService: "${bucketDto.category}" bucket ciphertext hash mismatch, refusing to load.`);
- }
- }
- const bucketJson = await decryptUnpack(bucketDto.blob, vek);
+ const bucketJson = await verifyDecryptUnpack(bucketDto.blob, vek, bucketDto.ciphertextHash, `"${bucketDto.category}" bucket`);
const bucket = JSON.parse(bucketJson) as VaultDataBucket;
dataBuckets.push(bucket);
pulledFingerprints[fingerprintBucketKey(bucketDto.category)] = await vaultCodecComputeContentFingerprint(bucketJson);
@@ -423,7 +436,7 @@ export class VaultSyncService {
const sharedManifestDtos = (snapshot.manifests ?? []).filter(m => !m.isRoot && m.blob);
const sharedManifests: VaultManifest[] = [];
const sessionSharedFolders: Record<string, SessionSharedFolder> = {};
- const encryptionKeysBucket = dataBuckets.find(b => b.category === ENCRYPTION_KEYS_BUCKET_CATEGORY) ?? null;
+ const encryptionKeysBucket = dataBuckets.find(b => b.category === VaultDataBucketCategory.EncryptionKeys) ?? null;
for (const dto of sharedManifestDtos) {
let vek: string | null = null;
if (dto.wrappedVek && dto.wrapPublicKey) {
@@ -447,13 +460,7 @@ export class VaultSyncService {
}
try {
- if (dto.ciphertextHash) {
- const actual = await vaultCodecComputeCiphertextHash(dto.blob!);
- if (actual !== dto.ciphertextHash) {
- throw new Error('ciphertext hash mismatch');
- }
- }
- const sharedManifestJson = await decryptUnpack(dto.blob!, vek);
+ const sharedManifestJson = await verifyDecryptUnpack(dto.blob!, vek, dto.ciphertextHash, `shared manifest ${dto.manifestId}`);
const sharedManifest = JSON.parse(sharedManifestJson) as VaultManifest;
const folderId = typeof sharedManifest.sharedFolderId === 'string' ? sharedManifest.sharedFolderId : null;
sharedManifests.push(sharedManifest);
@@ -582,16 +589,7 @@ export class VaultSyncService {
const sqliteBase64 = await VaultCodec.insertTables(materialized, blobMap, schemaSql);
devLog('[V2Pull] Codec reassembly complete.');
- return {
- sqliteBase64,
- manifestRevision,
- emailRouting: {
- emailAddressList: snapshot.emailRouting?.emailAddressList ?? [],
- privateEmailDomainList: snapshot.emailRouting?.privateEmailDomainList ?? [],
- hiddenPrivateEmailDomainList: snapshot.emailRouting?.hiddenPrivateEmailDomainList ?? [],
- publicEmailDomainList: snapshot.emailRouting?.publicEmailDomainList ?? [],
- },
- };
+ return { sqliteBase64, manifestRevision };
}
/**
@@ -652,8 +650,9 @@ export class VaultSyncService {
* which becomes the KEK; on a normal push it is the VEK itself)
* @param username - the user's username (sent in the upload payload for cross-check)
* @param emailAddressList - claimed email aliases (server needs these in plaintext for routing)
- * @param options - set createVaultKey to perform the KEK/VEK migration as part of this push; set forceFullWrite
- * to bypass the content-fingerprint gating and rewrite every manifest and bucket (server rollback recovery)
+ * @param options - set createVaultKey to perform the KEK/VEK migration as part of this push (decided once, in
+ * handleUploadVault); set forceFullWrite to bypass the content-fingerprint gating and
+ * rewrite every manifest and bucket (server rollback recovery)
* @returns Push outcome.
*/
public async push(
@@ -701,12 +700,9 @@ export class VaultSyncService {
}
const { canonicalized, sharedFolderRecords } = cachedSet ?? await this.canonicalizeVault(sqliteClient);
- // Plaintext blob bytes held platform-side for encryption/upload.
- const blobEntries = new Map<string, BlobEntry>(
- Object.entries(canonicalized.blobs).map(([hash, entry]) => [
- hash,
- { kind: entry.kind as 'favicon' | 'attachment', bytes: VaultCodec.base64ToBytes(entry.bytesBase64) },
- ])
+ // Plaintext blob bytes held platform-side for encryption/upload, each staged with the key that encrypts it.
+ const rootBlobEntries = new Map<string, UploadBlobEntry>(
+ Object.entries(canonicalized.blobs).map(([hash, entry]) => [hash, { kind: entry.kind as 'favicon' | 'attachment', bytes: VaultCodec.base64ToBytes(entry.bytesBase64), vek: contentKey }])
);
/*
@@ -798,8 +794,7 @@ export class VaultSyncService {
* the all-or-nothing gate, so another member's update to that folder can't fail an unrelated write.
*/
const sharedRevisions = ((await storage.getItem(StorageKeys.SERVER_MANIFEST_REVISIONS)) as Record<string, number> | null) ?? {};
- const rootBlobEntries = blobEntries;
- const sharedBlobEntries = new Map<string, { bytes: Uint8Array; kind: 'favicon' | 'attachment'; vek: string }>();
+ const sharedBlobEntries = new Map<string, UploadBlobEntry>();
const sharedManifestWrites: ManifestWriteDto[] = [];
const writtenSharedFingerprints: Record<string, string> = {};
for (const sharedVault of canonicalized.sharedVaults ?? []) {
@@ -893,12 +888,9 @@ export class VaultSyncService {
devLog(`[V2Push] Blob diff: ${allBlobHashes.length} blobs across ${1 + sharedManifestWrites.length} manifest(s), uploading ${rootToUpload.length} root + ${sharedToUpload.length} shared${migrateToVaultKey ? ' (root re-encrypted, VEK migration)' : ''}.`);
- /*
- * Pre-upload the missing bytes so the write below carries references only. Root uses the content key; shared
- * blobs use their own folder VEK (folded into each entry).
- */
- const uploadedCiphertexts = await this.uploadBlobs(webApi, rootBlobEntries, rootToUpload, contentKey, migrateToVaultKey);
- const uploadedShared = await this.uploadBlobsMultiKey(webApi, sharedBlobEntries, sharedToUpload);
+ // Pre-upload the missing bytes so the write below carries references only; each staged entry carries its own key.
+ const uploadedCiphertexts = await this.uploadBlobs(webApi, rootBlobEntries, rootToUpload, migrateToVaultKey);
+ const uploadedShared = await this.uploadBlobs(webApi, sharedBlobEntries, sharedToUpload);
for (const [hash, ciphertext] of uploadedShared) {
uploadedCiphertexts.set(hash, ciphertext);
}
@@ -932,7 +924,7 @@ export class VaultSyncService {
encryptionPublicKey: '',
};
- let resp = await webApi.post<typeof payload, VaultWriteResponseDto>(UPLOAD_ENDPOINT, payload);
+ let resp = await webApi.post<typeof payload, VaultWriteResponseDto>(VAULT_ENDPOINT, payload);
if (resp.missingBlobHashes && resp.missingBlobHashes.length > 0) {
/*
@@ -946,16 +938,13 @@ export class VaultSyncService {
}
devWarn(`[V2Sync] Server reported ${resp.missingBlobHashes.length} missing blob(s); uploading and retrying once.`);
- const retriedRoot = await this.uploadBlobs(webApi, rootBlobEntries, resp.missingBlobHashes.filter(h => rootBlobEntries.has(h)), contentKey, migrateToVaultKey);
- const retriedShared = await this.uploadBlobsMultiKey(webApi, sharedBlobEntries, resp.missingBlobHashes.filter(h => sharedBlobEntries.has(h)));
- for (const [hash, ciphertext] of retriedRoot) {
- uploadedCiphertexts.set(hash, ciphertext);
- }
- for (const [hash, ciphertext] of retriedShared) {
+ const retriedRoot = await this.uploadBlobs(webApi, rootBlobEntries, resp.missingBlobHashes.filter(h => rootBlobEntries.has(h)), migrateToVaultKey);
+ const retriedShared = await this.uploadBlobs(webApi, sharedBlobEntries, resp.missingBlobHashes.filter(h => sharedBlobEntries.has(h)));
+ for (const [hash, ciphertext] of [...retriedRoot, ...retriedShared]) {
uploadedCiphertexts.set(hash, ciphertext);
}
- resp = await webApi.post<typeof payload, VaultWriteResponseDto>(UPLOAD_ENDPOINT, payload);
+ resp = await webApi.post<typeof payload, VaultWriteResponseDto>(VAULT_ENDPOINT, payload);
if (resp.missingBlobHashes && resp.missingBlobHashes.length > 0) {
return { status: 'missing-blobs', newManifestRevision: currentManifestRevision, reasons: resp.missingBlobHashes };
}
@@ -1093,10 +1082,6 @@ export class VaultSyncService {
* @param mutationSequence - the current mutation sequence; the cached canonicalize result is handed to the push only while this sequence is unchanged
*/
public async detectNoOpMutation(sqliteClient: SqliteClient, mutationSequence: number): Promise<boolean> {
- if (!await VaultKeyService.hasLocalVaultKey()) {
- return false;
- }
-
const canonicalizedSet = await this.canonicalizeVault(sqliteClient);
canonicalizeCache = { client: sqliteClient, mutationSequence, ...canonicalizedSet };
@@ -1161,20 +1146,19 @@ export class VaultSyncService {
devLog(`[V2Push] Bucket "${category}" (bucket-only): raw ${formatKb(plaintext.length)} → compressed ${formatKb(compressedBytes)} → encrypted ${formatKb(ciphertext.length)}.`);
const webApi = new WebApiService();
- const bucketEntry = { category, blob: ciphertext, ciphertextHash };
+ /** POST the single-bucket write with the given believed-current revision (called again on the rebase retry). */
+ const postBucket = (currentRevision: number): Promise<VaultWriteResponseDto> => webApi.post<Record<string, unknown>, VaultWriteResponseDto>(VAULT_ENDPOINT, {
+ username, manifests: [], buckets: [{ category, blob: ciphertext, ciphertextHash, currentRevision }], newBlobs: [], emailRouting: null, encryptionPublicKey: '',
+ });
let currentRevision = (((await storage.getItem(bucketRevisionStorageKey(category))) as number | null) ?? 0);
- let resp = await webApi.post<Record<string, unknown>, VaultWriteResponseDto>(UPLOAD_ENDPOINT, {
- username, manifests: [], buckets: [{ ...bucketEntry, currentRevision }], newBlobs: [], emailRouting: null, encryptionPublicKey: '',
- });
+ let resp = await postBucket(currentRevision);
if (resp.status !== 0) {
const serverRevision = (resp.bucketRevisions ?? []).find(b => b.category === category)?.revision ?? currentRevision;
devWarn(`[V2Push] Bucket "${category}" outdated (server at revision ${serverRevision}, we assumed ${currentRevision}); rebasing and retrying once.`);
currentRevision = serverRevision;
- resp = await webApi.post<Record<string, unknown>, VaultWriteResponseDto>(UPLOAD_ENDPOINT, {
- username, manifests: [], buckets: [{ ...bucketEntry, currentRevision }], newBlobs: [], emailRouting: null, encryptionPublicKey: '',
- });
+ resp = await postBucket(currentRevision);
}
if (resp.status !== 0) {
@@ -1213,15 +1197,16 @@ export class VaultSyncService {
}
/**
- * Encrypt + upload blobs that each carry their own VEK (shared-folder blobs, one folder VEK per entry) via
- * POST /v2/Vault/blobs in size-capped batches. The `overwrite` flag is never needed here: shared-folder blobs
- * keep their folder VEK across a root KEK/VEK migration, so their ciphertext is never re-keyed.
+ * Encrypt the given blobs (each staged with its own VEK: root VEK or a folder VEK) and upload them via
+ * POST /v2/Vault/blobs in size-capped batches. `overwrite` is set only for root blobs on a KEK/VEK migration;
+ * shared-folder blobs keep their folder VEK across a migration, so their ciphertext is never re-keyed.
* @param webApi - API client to reuse
- * @param entries - hash → { bytes, kind, vek } for every candidate blob
- * @param hashes - the subset of hashes to upload (hashes without an entry are skipped)
+ * @param entries - hash → staged blob for every candidate (hashes without an entry are skipped)
+ * @param hashes - the subset of hashes to upload
+ * @param overwrite - ask the server to replace the ciphertext of blobs it already has (KEK/VEK migration)
* @returns Map of hash → uploaded ciphertext (base64), for the local encrypted blob cache.
*/
- private async uploadBlobsMultiKey(webApi: WebApiService, entries: Map<string, { bytes: Uint8Array; kind: 'favicon' | 'attachment'; vek: string }>, hashes: string[]): Promise<Map<string, string>> {
+ private async uploadBlobs(webApi: WebApiService, entries: Map<string, UploadBlobEntry>, hashes: string[], overwrite: boolean = false): Promise<Map<string, string>> {
const ciphertexts = new Map<string, string>();
if (hashes.length === 0) {
return ciphertexts;
@@ -1237,57 +1222,11 @@ export class VaultSyncService {
const ciphertext = await this.encryptBlobBytes(entry.bytes, entry.vek);
ciphertexts.set(hash, ciphertext);
- devLog(`[V2Push] Shared blob ${hash.substring(0, 12)}… (${entry.kind}): raw ${formatKb(entry.bytes.length)} → encrypted ${formatKb(ciphertext.length)}.`);
-
- if (batch.length > 0 && batchChars + ciphertext.length > BLOB_UPLOAD_BATCH_MAX_CHARS) {
- devLog(`[V2Push] Uploading shared blob batch: ${batch.length} blobs, ${formatKb(batchChars)}.`);
- await webApi.post(BLOBS_UPLOAD_ENDPOINT, { blobs: batch, overwrite: false });
- batch = [];
- batchChars = 0;
- }
-
- batch.push({ hash, category: entry.kind, encryptedDataBase64: ciphertext });
- batchChars += ciphertext.length;
- }
-
- if (batch.length > 0) {
- devLog(`[V2Push] Uploading shared blob batch: ${batch.length} blobs, ${formatKb(batchChars)}.`);
- await webApi.post(BLOBS_UPLOAD_ENDPOINT, { blobs: batch, overwrite: false });
- }
-
- return ciphertexts;
- }
-
- /**
- * Encrypt the given blobs and upload them via POST /v2/Vault/blobs in size-capped batches.
- * @param blobs - plaintext blob map keyed by content hash (source of the bytes)
- * @param hashes - the subset of hashes to upload (hashes without an entry in `blobs` are skipped)
- * @param vek - symmetric encryption key
- * @param webApi - API client to reuse
- * @param overwrite - ask the server to replace the ciphertext of blobs it already has (KEK/VEK migration)
- * @returns Map of hash → uploaded ciphertext (base64), for the local encrypted blob cache.
- */
- private async uploadBlobs(webApi: WebApiService, blobs: Map<string, BlobEntry>, hashes: string[], vek: string, overwrite: boolean = false): Promise<Map<string, string>> {
- const ciphertexts = new Map<string, string>();
- if (hashes.length === 0) {
- return ciphertexts;
- }
-
- let batch: BlobDto[] = [];
- let batchChars = 0;
- for (const hash of hashes) {
- const entry = blobs.get(hash);
- if (!entry) {
- continue;
- }
-
- const ciphertext = await this.encryptBlobBytes(entry.bytes, vek);
- ciphertexts.set(hash, ciphertext);
devLog(`[V2Push] Blob ${hash.substring(0, 12)}… (${entry.kind}): raw ${formatKb(entry.bytes.length)} → encrypted ${formatKb(ciphertext.length)}.`);
if (batch.length > 0 && batchChars + ciphertext.length > BLOB_UPLOAD_BATCH_MAX_CHARS) {
devLog(`[V2Push] Uploading blob batch: ${batch.length} blobs, ${formatKb(batchChars)}.`);
- await webApi.post(BLOBS_UPLOAD_ENDPOINT, { blobs: batch, overwrite });
+ await webApi.post(BLOBS_VAULT_ENDPOINT, { blobs: batch, overwrite });
batch = [];
batchChars = 0;
}
@@ -1298,7 +1237,7 @@ export class VaultSyncService {
if (batch.length > 0) {
devLog(`[V2Push] Uploading blob batch: ${batch.length} blobs, ${formatKb(batchChars)}.`);
- await webApi.post(BLOBS_UPLOAD_ENDPOINT, { blobs: batch, overwrite });
+ await webApi.post(BLOBS_VAULT_ENDPOINT, { blobs: batch, overwrite });
}
return ciphertexts;
diff --git a/apps/browser-extension/src/utils/messaging/ExtensionMessaging.ts b/apps/browser-extension/src/utils/messaging/ExtensionMessaging.ts
index 73c9b23f1..94399f4cf 100644
--- a/apps/browser-extension/src/utils/messaging/ExtensionMessaging.ts
+++ b/apps/browser-extension/src/utils/messaging/ExtensionMessaging.ts
@@ -7,7 +7,7 @@
import { defineExtensionMessaging } from '@webext-core/messaging';
import type { TwoFactorState } from '@/entrypoints/background/TwoFactorStateHandler';
-import type { FullVaultSyncResult, VaultSyncPhase } from '@/entrypoints/background/VaultMessageHandler';
+import type { FullVaultSyncResult, VaultManifestMigrationResult, VaultSyncPhase } from '@/entrypoints/background/VaultMessageHandler';
import type { EncryptionKeyDerivationParams } from '@/utils/dist/core/models/metadata';
import type { PasswordSettings } from '@/utils/dist/core/models/vault';
@@ -36,7 +36,7 @@ export interface IExtensionMessageProtocol {
ADD_URL_TO_CREDENTIAL(data: { itemId: string; url: string }): { success: boolean; error?: string };
AUTOFILL_CREATED_ITEM(data: { item: any; elementIdentifier?: string }): BoolResponse;
CANCEL_CLIPBOARD_CLEAR(): void;
- CHECK_AUTH_STATUS(): { isLoggedIn: boolean; isVaultLocked: boolean; hasPendingMigrations: boolean; error?: string };
+ CHECK_AUTH_STATUS(): { isLoggedIn: boolean; isVaultLocked: boolean; requiresLegacySqliteBlobMigration: boolean; requiresSchemaMigration: boolean; error?: string };
CHECK_LOGIN_DUPLICATE(data: { domain: string; username: string }): DuplicateCheckResponse;
CLEAR_LAST_AUTOFILLED(): { success: boolean };
CLEAR_PERSISTED_FORM_VALUES(): void;
@@ -79,6 +79,7 @@ export interface IExtensionMessageProtocol {
IS_URL_LINKED_TO_CREDENTIAL(data: { itemId: string; url: string }): { linked: boolean };
LOCK_VAULT(): BoolResponse;
MARK_VAULT_CLEAN(data: { mutationSeqAtStart: number; newServerRevision: number }): { cleared: boolean; currentMutationSeq: number };
+ MIGRATE_VAULT_MANIFEST(): VaultManifestMigrationResult;
OPEN_AUTOFILL_POPUP(data: { elementIdentifier: string; popupType?: string }): BoolResponse;
OPEN_POPUP(): BoolResponse;
OPEN_POPUP_CREATE_CREDENTIAL(data: { itemTitle?: string; currentUrl?: string; elementIdentifier?: string; left?: number; top?: number }): BoolResponse;