Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.
Add silent vault mutation scope support (#2159)
Leendert de Borst43aa9beb1499
diff --git a/apps/browser-extension/src/entrypoints/background/VaultMessageHandler.ts b/apps/browser-extension/src/entrypoints/background/VaultMessageHandler.tsindex c1ce8987d..b8d886bdc 100644--- a/apps/browser-extension/src/entrypoints/background/VaultMessageHandler.ts+++ b/apps/browser-extension/src/entrypoints/background/VaultMessageHandler.ts@@ -38,8 +38,9 @@ import type { SaveLoginResponse } from '@/utils/types/messaging/SaveLoginResponsimport type { StringResponse as stringResponse } from '@/utils/types/messaging/StringResponse';import type { VaultResponse as messageVaultResponse } from '@/utils/types/messaging/VaultResponse';import type { VaultUploadResponse as messageVaultUploadResponse } from '@/utils/types/messaging/VaultUploadResponse';-import { type VaultMutationScope, ALL_VAULT_MUTATION_SCOPES, DEFAULT_VAULT_MUTATION_SCOPE, isManifestScope } from '@/utils/types/VaultMutationScope';+import { type VaultMutationScope, DEFAULT_VAULT_MUTATION_SCOPE, hasUserVisibleScope, isManifestScope } from '@/utils/types/VaultMutationScope';import { VaultCodec } from '@/utils/VaultCodec';+import { clearDirtyScopes, getDirtyScopes } from '@/utils/VaultDirtyState';import { VaultKeyService } from '@/utils/VaultKeyService';import { vaultRequiresManifestMigration } from '@/utils/VaultManifestMigration';import { vaultMergeService } from '@/utils/VaultMergeService';@@ -712,27 +713,6 @@ export async function handleGetEncryptionKeyDerivationParams(return await getStorageItem<EncryptionKeyDerivationParams>(StorageKeys.ENCRYPTION_KEY_DERIVATION_PARAMS);}-/**- * Read the set of currently-dirty mutation scopes from their independent per-scope flags. Each scope is a- * separate idempotent boolean key (see {@link dirtyScopeStorageKey}), so concurrent mutations can never- * clobber each other's scope the way pushing onto one shared array could. Returns the dirty scopes in the- * stable {@link ALL_VAULT_MUTATION_SCOPES} order.- */-async function getDirtyScopes(): Promise<VaultMutationScope[]> {- const flags = await Promise.all(- ALL_VAULT_MUTATION_SCOPES.map(async scope => ((await storage.getItem(dirtyScopeStorageKey(scope))) === true ? scope : null))- );- return flags.filter((s): s is VaultMutationScope => s !== null);-}--/**- * Clear every per-scope dirty flag. Called once a sync has confirmed all pending changes are on the server- * (guarded by the mutation-sequence check in {@link handleMarkVaultClean}).- */-async function clearDirtyScopes(): Promise<void> {- await storage.removeItems(ALL_VAULT_MUTATION_SCOPES.map(scope => dirtyScopeStorageKey(scope)));-}-/*** Push only the data buckets named by the dirty scopes, no manifest upload. Used when every pending local* mutation since the last sync is bucket-scoped (e.g. a settings toggle): the server's vault content manifest@@ -1509,11 +1489,13 @@ async function handleFullVaultSyncInternal(): Promise<FullVaultSyncResult> {}/*- * Announce the sync phase to the popup so it can show the right indicator.+ * Announce the sync phase to the popup so it can show the right indicator. A push that carries nothing but+ * silent scopes (item usage statistics) stays unannounced: it is bookkeeping the user never initiated, so a+ * spinner for it would only imply something is at stake.*/if (needsPull) {broadcastSyncPhase('pull');- } else if (syncState.isDirty) {+ } else if (syncState.isDirty && hasUserVisibleScope(await getDirtyScopes())) {broadcastSyncPhase('push');}diff --git a/apps/browser-extension/src/entrypoints/popup/components/Dialogs/LogoutConfirmModal.tsx b/apps/browser-extension/src/entrypoints/popup/components/Dialogs/LogoutConfirmModal.tsxindex 5438da306..be2b1231d 100644--- a/apps/browser-extension/src/entrypoints/popup/components/Dialogs/LogoutConfirmModal.tsx+++ b/apps/browser-extension/src/entrypoints/popup/components/Dialogs/LogoutConfirmModal.tsx@@ -3,9 +3,7 @@ import { useTranslation } from 'react-i18next';import ModalWrapper from '@/entrypoints/popup/components/Dialogs/ModalWrapper';-import { StorageKeys } from '@/utils/constants/storageKeys';--import { storage } from '#imports';+import { hasUnsyncedUserChanges } from '@/utils/VaultDirtyState';interface ILogoutConfirmModalProps {isOpen: boolean;@@ -23,35 +21,37 @@ const LogoutConfirmModal: React.FC<ILogoutConfirmModalProps> = ({onConfirm}) => {const { t } = useTranslation();- const [isDirty, setIsDirty] = useState<boolean | null>(null);+ const [hasPendingChanges, setHasPendingChanges] = useState<boolean | null>(null);/**- * Check sync state every time the modal opens. The dirty flag lives in+ * Check sync state every time the modal opens. The dirty flags live in* local storage, so a direct read is equivalent to (and faster than) a* round-trip through the background script. The cancellation flag prevents* a stale response from overwriting state if the modal is closed and- * reopened before this read resolves.+ * reopened before this read resolves. Silent scopes (e.g. item usage+ * statistics) are excluded: warning about losing a last-used timestamp only+ * makes the user doubt a logout that costs them nothing.*/useEffect(() => {if (!isOpen) {- setIsDirty(null);+ setHasPendingChanges(null);return;}let cancelled = false;- setIsDirty(null);+ setHasPendingChanges(null);(async () : Promise<void> => {try {- const dirty = await storage.getItem(StorageKeys.IS_DIRTY) as boolean | null;+ const pending = await hasUnsyncedUserChanges();if (!cancelled) {- setIsDirty(dirty ?? false);+ setHasPendingChanges(pending);}} catch (error) {console.error('Failed to check sync state:', error);if (!cancelled) {// Default to showing the simple logout confirmation on error- setIsDirty(false);+ setHasPendingChanges(false);}}})();@@ -62,12 +62,12 @@ const LogoutConfirmModal: React.FC<ILogoutConfirmModalProps> = ({}, [isOpen]);// Don't render anything if not open or still loading- if (!isOpen || isDirty === null) {+ if (!isOpen || hasPendingChanges === null) {return null;}// Render dirty logout warning modal- if (isDirty) {+ if (hasPendingChanges) {return (<ModalWrapperisOpen={isOpen}diff --git a/apps/browser-extension/src/entrypoints/popup/components/Layout/ServerSyncIndicator.tsx b/apps/browser-extension/src/entrypoints/popup/components/Layout/ServerSyncIndicator.tsxindex 37c8422a9..e2f8aa42e 100644--- a/apps/browser-extension/src/entrypoints/popup/components/Layout/ServerSyncIndicator.tsx+++ b/apps/browser-extension/src/entrypoints/popup/components/Layout/ServerSyncIndicator.tsx@@ -50,13 +50,13 @@ const ServerSyncIndicator: React.FC = () => {* Only surface the pending indicator when the vault has stayed dirty for the grace period.*/useEffect(() => {- if (!dbContext.isDirty) {+ if (!dbContext.hasUnsyncedUserChanges) {setShowPending(false);return;}const timer = setTimeout((): void => setShowPending(true), PENDING_DISPLAY_DELAY);return (): void => clearTimeout(timer);- }, [dbContext.isDirty]);+ }, [dbContext.hasUnsyncedUserChanges]);/*** Handle syncing state changes with minimum display time.@@ -168,7 +168,7 @@ const ServerSyncIndicator: React.FC = () => {d="M18.364 5.636a9 9 0 010 12.728m0 0l-2.829-2.829m2.829 2.829L21 21M15.536 8.464a5 5 0 010 7.072m0 0l-2.829-2.829m-4.243 2.829a4.978 4.978 0 01-1.414-2.83m-1.414 5.658a9 9 0 01-2.167-9.238m7.824 2.167a1 1 0 111.414 1.414m-1.414-1.414L3 3m8.293 8.293l1.414 1.414"/></svg>- {dbContext.isDirty && (+ {dbContext.hasUnsyncedUserChanges && (<span className="absolute -top-0.5 -right-0.5 w-2 h-2 bg-red-500 rounded-full" />)}</>diff --git a/apps/browser-extension/src/entrypoints/popup/context/DbContext.tsx b/apps/browser-extension/src/entrypoints/popup/context/DbContext.tsxindex 96a2404a4..5862a2a1a 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 { getStorageItem } from '@/utils/StorageUtility';import { AppErrorCode, formatErrorWithCode } from '@/utils/types/errors/AppErrorCodes';import type { VaultResponse as messageVaultResponse } from '@/utils/types/messaging/VaultResponse';+import { hasUnsyncedUserChanges as hasUnsyncedUserChangesInStorage } from '@/utils/VaultDirtyState';import { vaultRequiresManifestMigration } from '@/utils/VaultManifestMigration';import { markOwnEncryptionKey, vaultStateEvents } from '@/events/VaultStateEvents';@@ -39,9 +40,11 @@ type DbContextType = {*/getIsOffline: () => boolean;/**- * True if local vault has changes not yet synced to server.+ * True if the local vault has user-initiated changes not yet synced to the server. Changes from silent+ * scopes (e.g. item usage statistics) sync just the same but are not reported here, so the UI stays quiet+ * about data the user never asked to save.*/- isDirty: boolean;+ hasUnsyncedUserChanges: boolean;/*** True if a background sync (download) is in progress.*/@@ -125,9 +128,9 @@ export const DbProvider: React.FC<{ children: React.ReactNode }> = ({ children }const isOfflineRef = useRef(false);/**- * Dirty state - true if local vault has unsynced changes.+ * Dirty state - true if the local vault has unsynced changes the user expects to get feedback on.*/- const [isDirty, setIsDirty] = useState(false);+ const [hasUnsyncedUserChanges, setHasUnsyncedUserChanges] = useState(false);/*** Syncing state - true if a background sync (download) is in progress.@@ -151,8 +154,8 @@ export const DbProvider: React.FC<{ children: React.ReactNode }> = ({ children }* as the server may not know about newly created items/aliases yet.*/const shouldSuppressEmailErrors = useCallback(() => {- return isDirty || isSyncing;- }, [isDirty, isSyncing]);+ return hasUnsyncedUserChanges || isSyncing;+ }, [hasUnsyncedUserChanges, isSyncing]);/*** Set the offline mode state and persist it to local storage.@@ -172,14 +175,14 @@ export const DbProvider: React.FC<{ children: React.ReactNode }> = ({ children }* Load the offline mode and sync state from local storage.*/const loadSyncState = async (): Promise<void> => {- const [offlineMode, dirty, lastError] = await Promise.all([+ const [offlineMode, pendingUserChanges, lastError] = await Promise.all([storage.getItem(StorageKeys.IS_OFFLINE_MODE) as Promise<boolean | null>,- storage.getItem(StorageKeys.IS_DIRTY) as Promise<boolean | null>,+ hasUnsyncedUserChangesInStorage(),storage.getItem(StorageKeys.LAST_SYNC_ERROR) as Promise<string | null>]);isOfflineRef.current = offlineMode ?? false;setIsOfflineState(offlineMode ?? false);- setIsDirty(dirty ?? false);+ setHasUnsyncedUserChanges(pendingUserChanges);setSyncError(lastError ?? null);};loadSyncState();@@ -330,7 +333,7 @@ export const DbProvider: React.FC<{ children: React.ReactNode }> = ({ children }* Refresh sync state from storage (called after background updates it).*/const refreshSyncState = useCallback(async (): Promise<void> => {- setIsDirty((await storage.getItem(StorageKeys.IS_DIRTY) as boolean | null) ?? false);+ setHasUnsyncedUserChanges(await hasUnsyncedUserChangesInStorage());}, []);/**@@ -403,7 +406,7 @@ export const DbProvider: React.FC<{ children: React.ReactNode }> = ({ children }dbAvailable,isOffline,getIsOffline,- isDirty,+ hasUnsyncedUserChanges,isSyncing,isUploading,setIsOffline,@@ -421,7 +424,7 @@ export const DbProvider: React.FC<{ children: React.ReactNode }> = ({ children }requiresManifestMigration,syncError,clearSyncError,- }), [sqliteClient, dbInitialized, dbAvailable, isOffline, getIsOffline, isDirty, isSyncing, isUploading, setIsOffline, shouldSuppressEmailErrors, loadDatabase, loadStoredDatabase, storeEncryptionKey, storeEncryptionKeyDerivationParams, clearDatabase, getVaultMetadata, refreshSyncState, requiresLegacySqliteBlobMigration, requiresManifestMigration, syncError, clearSyncError]);+ }), [sqliteClient, dbInitialized, dbAvailable, isOffline, getIsOffline, hasUnsyncedUserChanges, isSyncing, isUploading, 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/useVaultMutate.ts b/apps/browser-extension/src/entrypoints/popup/hooks/useVaultMutate.tsindex 68b58115a..6ca732db9 100644--- a/apps/browser-extension/src/entrypoints/popup/hooks/useVaultMutate.ts+++ b/apps/browser-extension/src/entrypoints/popup/hooks/useVaultMutate.ts@@ -5,7 +5,7 @@ import { useDb } from '@/entrypoints/popup/context/DbContext';import { devLog } from '@/utils/devLogger/DevLogger';import { EncryptionUtility } from '@/utils/EncryptionUtility';import { sendMessage } from '@/utils/messaging/ExtensionMessaging';-import type { VaultMutationOptions, VaultMutationScope } from '@/utils/types/VaultMutationScope';+import { isSilentScope, type VaultMutationOptions, type VaultMutationScope } from '@/utils/types/VaultMutationScope';/*** Hook to execute a vault mutation.@@ -114,10 +114,17 @@ export function useVaultMutate(): {* and continues even if the popup closes.** Always polls to detect completion since background sync may queue additional- * syncs that we cannot directly observe from the popup context.+ * syncs that we cannot directly observe from the popup context. A silent scope+ * (e.g. item usage statistics) syncs the same way but shows no indicator: the+ * user did not ask for that write and expects no feedback on it.+ * @param scope - what the mutation touched*/- const triggerBackgroundSync = useCallback((): void => {- dbContext.setIsUploading(true);+ const triggerBackgroundSync = useCallback((scope?: VaultMutationScope): void => {+ const silent = scope !== undefined && isSilentScope(scope);++ if (!silent) {+ dbContext.setIsUploading(true);+ }/** Fire-and-forget: send message to background without awaiting.@@ -127,10 +134,11 @@ export function useVaultMutate(): {* After sending message, we start polling to detect completion.*/void sendMessage('FULL_VAULT_SYNC').then(async (syncResult) => {- if (!syncResult.success && (syncResult.error || syncResult.errorKey)) {+ if (!silent && !syncResult.success && (syncResult.error || syncResult.errorKey)) {/** Permanent failure (e.g. HTTP 413 vault too large). Stop polling and clear the upload- * spinner.+ * spinner. Skipped for a silent scope: it owns neither the poll nor the spinner, both of+ * which may belong to a visible mutation still in flight.*/if (pollIntervalRef.current) {clearInterval(pollIntervalRef.current);@@ -146,8 +154,10 @@ export function useVaultMutate(): {console.error('Background sync error:', error);});- // Start polling for completion- startPollingForCompletion();+ // Start polling for completion (nothing to clear when no indicator was shown)+ if (!silent) {+ startPollingForCompletion();+ }}, [dbContext, startPollingForCompletion]);/**@@ -164,7 +174,7 @@ export function useVaultMutate(): {await saveLocally(operation, options?.scope);// 2. Trigger sync in background (fire-and-forget, continues even if popup closes)- triggerBackgroundSync();+ triggerBackgroundSync(options?.scope);}, [saveLocally, triggerBackgroundSync]);return {diff --git a/apps/browser-extension/src/utils/VaultDirtyState.ts b/apps/browser-extension/src/utils/VaultDirtyState.tsnew file mode 100644index 000000000..874e483e1--- /dev/null+++ b/apps/browser-extension/src/utils/VaultDirtyState.ts@@ -0,0 +1,41 @@+/**+ * VaultDirtyState.+ *+ * The local vault's pending-sync state: whether it holds changes the server does not have yet, and which+ * mutation scopes those changes belong to. Shared between the background sync (which decides what to push) and+ * the popup (which decides what to show).+ */++import { storage } from 'wxt/utils/storage';++import { dirtyScopeStorageKey, StorageKeys } from '@/utils/constants/storageKeys';+import { ALL_VAULT_MUTATION_SCOPES, hasUserVisibleScope, type VaultMutationScope } from '@/utils/types/VaultMutationScope';++/**+ * Read the set of currently-dirty mutation scopes from their independent per-scope flags.+ */+export async function getDirtyScopes(): Promise<VaultMutationScope[]> {+ const flags = await Promise.all(+ ALL_VAULT_MUTATION_SCOPES.map(async scope => ((await storage.getItem(dirtyScopeStorageKey(scope))) === true ? scope : null))+ );+ return flags.filter((s): s is VaultMutationScope => s !== null);+}++/**+ * Clear every per-scope dirty flag. Called once a sync has confirmed all pending changes are on the server.+ */+export async function clearDirtyScopes(): Promise<void> {+ await storage.removeItems(ALL_VAULT_MUTATION_SCOPES.map(scope => dirtyScopeStorageKey(scope)));+}++/**+ * Whether the vault holds unsynced changes the user should see an indicator for. A vault that is only dirty+ * from silent scopes (e.g. item usage statistics) syncs exactly like any other, but reports clean here so the+ * UI stays quiet about mutations the user did not explicitly request.+ */+export async function hasUnsyncedUserChanges(): Promise<boolean> {+ if (await storage.getItem(StorageKeys.IS_DIRTY) !== true) {+ return false;+ }+ return hasUserVisibleScope(await getDirtyScopes());+}diff --git a/apps/browser-extension/src/utils/types/VaultMutationScope.ts b/apps/browser-extension/src/utils/types/VaultMutationScope.tsindex f4e101bd5..c3f7f6f32 100644--- a/apps/browser-extension/src/utils/types/VaultMutationScope.ts+++ b/apps/browser-extension/src/utils/types/VaultMutationScope.ts@@ -20,6 +20,15 @@ export const ALL_VAULT_MUTATION_SCOPES: readonly VaultMutationScope[] = [...ALL_export const DEFAULT_VAULT_MUTATION_SCOPE: VaultMutationScope = 'Main';+/**+ * Scopes whose sync is deliberately kept out of the UI. These hold housekeeping data the user never asked to+ * save (per-item usage statistics are written as a side effect of autofilling or copying a field), so a spinner+ * or pending badge for them would only suggest that something important is in flight. The sync indicator is+ * reserved for user-initiated changes, where a confirmation that the change reached the server is the feedback+ * the user expects to get.+ */+export const SILENT_VAULT_MUTATION_SCOPES: readonly VaultMutationScope[] = [VaultDataBucketCategory.Stats];+/*** True when a scope is a manifest category (i.e. a dirty flag on it requires a full manifest push, not a* bucket-only push).@@ -28,6 +37,22 @@ export const DEFAULT_VAULT_MUTATION_SCOPE: VaultMutationScope = 'Main';export const isManifestScope = (scope: VaultMutationScope): scope is VaultManifestScope =>(ALL_VAULT_MANIFEST_SCOPES as readonly string[]).includes(scope);+/**+ * True when a scope's sync must stay invisible in the UI. It still syncs like any other scope; only the+ * indicators ignore it.+ * @param scope - the mutation scope+ */+export const isSilentScope = (scope: VaultMutationScope): boolean => SILENT_VAULT_MUTATION_SCOPES.includes(scope);++/**+ * True when the pending scopes hold at least one change worth showing an indicator for. An empty list counts as+ * visible: a vault marked dirty without any recorded scope predates per-scope tracking, and hiding a real+ * pending change is worse than showing a badge too many.+ * @param scopes - the currently pending mutation scopes+ */+export const hasUserVisibleScope = (scopes: readonly VaultMutationScope[]): boolean =>+ scopes.length === 0 || scopes.some(scope => !isSilentScope(scope));+/*** Options for executing a vault mutation.*/diff --git a/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/Manifest.cs b/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/Manifest.csindex c7a52f9ac..3320984e9 100644--- a/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/Manifest.cs+++ b/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/Manifest.cs@@ -41,7 +41,7 @@ public class Manifestpublic bool CanAdminister { get; set; }/// <summary>- /// Gets or sets how the caller's access to this manifest's VEK is encrypted.+ /// Gets or sets how the caller's access to this manifest's VEK is encrypted, as a ManifestKeyType token./// </summary>public string? KeyType { get; set; }@@ -50,7 +50,7 @@ public class Manifest/// </summary>public string? EncryptedVek { get; set; }- /// <summary>Gets or sets the algorithm of <see cref="EncryptedVek"/> (e.g. "rsa-oaep-sha256"). Null when <see cref="EncryptedVek"/> is null.</summary>+ /// <summary>Gets or sets the algorithm of <see cref="EncryptedVek"/>, as a VaultKeyAlgorithm token. Null when <see cref="EncryptedVek"/> is null.</summary>public string? Algorithm { get; set; }/// <summary>diff --git a/core/models/README.md b/core/models/README.mdindex 324d6413a..526e0ceda 100644--- a/core/models/README.md+++ b/core/models/README.md@@ -21,3 +21,19 @@ Automatically generates platform-specific models from TypeScript sources:| `src/vault/FieldKey.ts` | `apps/server/Databases/AliasClientDb/Models/FieldKey.cs` | C# || `src/vault/FieldKey.ts` | `apps/mobile-app/ios/AliasVault/VaultModels/FieldKey.swift` | Swift || `src/vault/FieldKey.ts` | `apps/mobile-app/android/.../vaultstore/models/FieldKey.kt` | Kotlin |++### 3. Generated Vocabularies (Not TypeScript-Sourced)++Two generators own a vocabulary outright and emit **all four** platforms, TypeScript included. Their outputs+under `src/` are generated files: edit the generator, not the output.++| Generator | Source of truth | Emits |+|-----------|-----------------|-------|+| `scripts/generate-bucket-categories.cjs` | `core/rust/src/vault_codec/types.rs` (`BUCKET_TABLES`) | `VaultDataBucketCategory` |+| `scripts/generate-key-vocabulary.cjs` | the `VOCABULARIES` table inside the script | `UnlockMethodType`, `ManifestKeyType`, `VaultKeyAlgorithm` |++The key vocabulary is the set of tokens naming how a vault key is protected — which unlock method encrypts a+user's Account Key, how a manifest's VEK reaches a given user, and which algorithm a piece of key ciphertext+uses. Each token is a contract shared by the API, the database and every client, so it is declared once and+emitted per platform. A member's `token` is the only identifier that is persisted or transmitted; the C# enum+ordinals follow declaration order and are cosmetic, so members can be reordered freely.