Skip to content

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

Add AppErrorCodes handling to browser extension (#1619)

Leendert de Borstb6c7484e6077
diff --git a/apps/browser-extension/src/entrypoints/background/VaultMessageHandler.ts b/apps/browser-extension/src/entrypoints/background/VaultMessageHandler.ts
index 74b6fc042..beca2fd1f 100644
--- a/apps/browser-extension/src/entrypoints/background/VaultMessageHandler.ts
+++ b/apps/browser-extension/src/entrypoints/background/VaultMessageHandler.ts
@@ -8,6 +8,7 @@ import { EncryptionUtility } from '@/utils/EncryptionUtility';
import { SqliteClient } from '@/utils/SqliteClient';
import { getItemWithFallback } from '@/utils/StorageUtility';
import { ApiAuthError } from '@/utils/types/errors/ApiAuthError';
+import { AppErrorCode, formatErrorWithCode } from '@/utils/types/errors/AppErrorCodes';
import { NetworkError } from '@/utils/types/errors/NetworkError';
import { VaultVersionIncompatibleError } from '@/utils/types/errors/VaultVersionIncompatibleError';
import { BoolResponse as messageBoolResponse } from '@/utils/types/messaging/BoolResponse';
@@ -124,7 +125,8 @@ export async function handleStoreVaultMetadata(
return { success: true };
} catch (error) {
console.error('Failed to store vault metadata:', error);
- return { success: false, error: await t('common.errors.unknownError') };
+ // E-602: Storage write failed during metadata store
+ return { success: false, error: formatErrorWithCode(await t('common.errors.unknownError'), AppErrorCode.STORAGE_WRITE_FAILED) };
}
}
@@ -139,7 +141,8 @@ export async function handleStoreEncryptionKey(
return { success: true };
} catch (error) {
console.error('Failed to store encryption key:', error);
- return { success: false, error: await t('common.errors.unknownErrorTryAgain') };
+ // E-602: Storage write failed during encryption key store
+ return { success: false, error: formatErrorWithCode(await t('common.errors.unknownErrorTryAgain'), AppErrorCode.STORAGE_WRITE_FAILED) };
}
}
@@ -155,7 +158,8 @@ export async function handleStoreEncryptionKeyDerivationParams(
return { success: true };
} catch (error) {
console.error('Failed to store encryption key derivation params:', error);
- return { success: false, error: await t('common.errors.unknownErrorTryAgain') };
+ // E-602: Storage write failed during derivation params store
+ return { success: false, error: formatErrorWithCode(await t('common.errors.unknownErrorTryAgain'), AppErrorCode.STORAGE_WRITE_FAILED) };
}
}
@@ -212,12 +216,14 @@ export async function handleGetVault(
if (!encryptedVault) {
console.error('Vault not available');
- return { success: false, error: await t('common.errors.vaultNotAvailable') };
+ // E-201: No encrypted vault in storage
+ return { success: false, error: formatErrorWithCode(await t('common.errors.vaultNotAvailable'), AppErrorCode.VAULT_NOT_FOUND) };
}
if (!encryptionKey) {
console.error('Encryption key not available');
- return { success: false, error: await t('common.errors.vaultIsLocked') };
+ // E-202: No encryption key available (vault is locked)
+ return { success: false, error: formatErrorWithCode(await t('common.errors.vaultIsLocked'), AppErrorCode.VAULT_LOCKED) };
}
const decryptedVault = await EncryptionUtility.symmetricDecrypt(
@@ -235,7 +241,8 @@ export async function handleGetVault(
};
} catch (error) {
console.error('Failed to get vault:', error);
- return { success: false, error: await t('common.errors.unknownError') };
+ // E-203: Vault decryption failed during get
+ return { success: false, error: formatErrorWithCode(await t('common.errors.unknownError'), AppErrorCode.VAULT_DECRYPT_FAILED) };
}
}
@@ -309,7 +316,8 @@ export async function handleCreateItem(
const encryptionKey = await handleGetEncryptionKey();
if (!encryptionKey) {
- return { success: false, error: await t('common.errors.vaultIsLocked') };
+ // E-202: Vault is locked
+ return { success: false, error: formatErrorWithCode(await t('common.errors.vaultIsLocked'), AppErrorCode.VAULT_LOCKED) };
}
try {
@@ -324,7 +332,8 @@ export async function handleCreateItem(
return { success: true };
} catch (error) {
console.error('Failed to create item:', error);
- return { success: false, error: await t('common.errors.unknownError') };
+ // E-301: Item create failed
+ return { success: false, error: formatErrorWithCode(await t('common.errors.unknownError'), AppErrorCode.ITEM_CREATE_FAILED) };
}
}
@@ -340,7 +349,8 @@ export async function handleGetFilteredItems(
const encryptionKey = await handleGetEncryptionKey();
if (!encryptionKey) {
- return { success: false, error: await t('common.errors.vaultIsLocked') };
+ // E-202: Vault is locked
+ return { success: false, error: formatErrorWithCode(await t('common.errors.vaultIsLocked'), AppErrorCode.VAULT_LOCKED) };
}
try {
@@ -366,7 +376,8 @@ export async function handleGetFilteredItems(
return { success: true, items: filteredItems };
} catch (error) {
console.error('Error getting filtered items:', error);
- return { success: false, error: await t('common.errors.unknownError') };
+ // E-304: Item read failed
+ return { success: false, error: formatErrorWithCode(await t('common.errors.unknownError'), AppErrorCode.ITEM_READ_FAILED) };
}
}
@@ -382,7 +393,8 @@ export async function handleGetSearchItems(
const encryptionKey = await handleGetEncryptionKey();
if (!encryptionKey) {
- return { success: false, error: await t('common.errors.vaultIsLocked') };
+ // E-202: Vault is locked
+ return { success: false, error: formatErrorWithCode(await t('common.errors.vaultIsLocked'), AppErrorCode.VAULT_LOCKED) };
}
try {
@@ -428,7 +440,8 @@ export async function handleGetSearchItems(
return { success: true, items: searchResults };
} catch (error) {
console.error('Error searching items:', error);
- return { success: false, error: await t('common.errors.unknownError') };
+ // E-304: Item read failed during search
+ return { success: false, error: formatErrorWithCode(await t('common.errors.unknownError'), AppErrorCode.ITEM_READ_FAILED) };
}
}
@@ -469,7 +482,8 @@ export function handleGetDefaultEmailDomain(): Promise<stringResponse> {
return { success: true, value: domain || undefined };
} catch (error) {
console.error('Error getting default email domain:', error);
- return { success: false, error: await t('common.errors.unknownError') };
+ // E-601: Storage read failed
+ return { success: false, error: formatErrorWithCode(await t('common.errors.unknownError'), AppErrorCode.STORAGE_READ_FAILED) };
}
})();
}
@@ -494,7 +508,8 @@ export async function handleGetDefaultIdentitySettings(
};
} catch (error) {
console.error('Error getting default identity settings:', error);
- return { success: false, error: await t('common.errors.unknownError') };
+ // E-601: Storage read failed
+ return { success: false, error: formatErrorWithCode(await t('common.errors.unknownError'), AppErrorCode.STORAGE_READ_FAILED) };
}
}
@@ -510,7 +525,8 @@ export async function handleGetPasswordSettings(
return { success: true, settings: passwordSettings };
} catch (error) {
console.error('Error getting password settings:', error);
- return { success: false, error: await t('common.errors.unknownError') };
+ // E-601: Storage read failed
+ return { success: false, error: formatErrorWithCode(await t('common.errors.unknownError'), AppErrorCode.STORAGE_READ_FAILED) };
}
}
@@ -565,7 +581,8 @@ export async function handleUploadVault(
};
} catch (error) {
console.error('Failed to upload vault:', error);
- return { success: false, error: await t('common.errors.unknownError') };
+ // E-801: Upload failed
+ return { success: false, error: formatErrorWithCode(await t('common.errors.unknownError'), AppErrorCode.UPLOAD_FAILED) };
}
}
@@ -576,7 +593,8 @@ export async function handleUploadVault(
export async function handlePersistFormValues(data: any): Promise<void> {
const encryptionKey = await handleGetEncryptionKey();
if (!encryptionKey) {
- throw new Error(await t('common.errors.unknownError'));
+ // E-504: Encryption key not found
+ throw new Error(formatErrorWithCode(await t('common.errors.unknownError'), AppErrorCode.ENCRYPTION_KEY_NOT_FOUND));
}
// Always stringify the data properly
@@ -628,7 +646,8 @@ async function uploadNewVaultToServer(sqliteClient: SqliteClient) : Promise<Vaul
const encryptionKey = await handleGetEncryptionKey();
if (!encryptionKey) {
- throw new Error(await t('common.errors.vaultIsLocked'));
+ // E-202: Vault is locked
+ throw new Error(formatErrorWithCode(await t('common.errors.vaultIsLocked'), AppErrorCode.VAULT_LOCKED));
}
/**
@@ -690,9 +709,12 @@ async function uploadNewVaultToServer(sqliteClient: SqliteClient) : Promise<Vaul
if (response.status === 0) {
// Upload succeeded - update server revision
await storage.setItem('local:serverRevision', response.newRevisionNumber);
+ } else if (response.status === 2) {
+ // Outdated - server has newer version
+ throw new Error(formatErrorWithCode(await t('common.errors.unknownError'), AppErrorCode.UPLOAD_OUTDATED));
} else {
// Upload failed
- throw new Error(await t('common.errors.unknownError'));
+ throw new Error(formatErrorWithCode(await t('common.errors.unknownError'), AppErrorCode.UPLOAD_FAILED));
}
return response;
@@ -706,8 +728,13 @@ async function createVaultSqliteClient() : Promise<SqliteClient> {
// Read from local: storage for persistent vault access
const encryptedVault = await storage.getItem('local:encryptedVault') as string;
const encryptionKey = await handleGetEncryptionKey();
- if (!encryptedVault || !encryptionKey) {
- throw new Error(await t('common.errors.unknownError'));
+ if (!encryptedVault) {
+ // E-201: Vault not found in storage
+ throw new Error(formatErrorWithCode(await t('common.errors.vaultNotAvailable'), AppErrorCode.VAULT_NOT_FOUND));
+ }
+ if (!encryptionKey) {
+ // E-202: Vault is locked
+ throw new Error(formatErrorWithCode(await t('common.errors.vaultIsLocked'), AppErrorCode.VAULT_LOCKED));
}
// Check if we have a valid cached client
@@ -925,7 +952,8 @@ export async function handleFullVaultSync(): Promise<FullVaultSyncResult> {
}
if (authStatus.isVaultLocked) {
- return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: false, error: await t('common.errors.vaultIsLocked') };
+ // 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) };
}
// Check app status and vault revision
@@ -1080,7 +1108,11 @@ export async function handleFullVaultSync(): Promise<FullVaultSyncResult> {
if (error instanceof VaultVersionIncompatibleError) {
return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: true, error: error.message };
}
- throw new Error('Vault could not be decrypted, if the problem persists please logout and login again.');
+ // E-501: Vault decryption failed
+ throw new Error(formatErrorWithCode(
+ 'Vault could not be decrypted, if the problem persists please logout and login again.',
+ AppErrorCode.VAULT_DECRYPT_FAILED
+ ));
}
} else if (statusResponse.vaultRevision === syncState.serverRevision) {
/**
@@ -1136,7 +1168,8 @@ export async function handleFullVaultSync(): Promise<FullVaultSyncResult> {
return handleFullVaultSync();
} else {
console.error('Server recovery failed:', uploadResponse.error);
- return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: false, error: await t('common.errors.unknownError') };
+ // E-801: Upload failed during server recovery
+ return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: false, error: formatErrorWithCode(await t('common.errors.unknownError'), AppErrorCode.UPLOAD_FAILED) };
}
}
@@ -1153,12 +1186,11 @@ export async function handleFullVaultSync(): Promise<FullVaultSyncResult> {
return { success: true, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: false };
} catch (err) {
- const errorMessage = err instanceof Error ? err.message : 'Unknown error during vault sync';
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: errorMessage };
+ return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: true, error: err.message };
}
// Auth error (session expired) - signal popup to trigger logout
@@ -1175,6 +1207,13 @@ export async function handleFullVaultSync(): Promise<FullVaultSyncResult> {
}
}
+ // For all other errors, include an error code so users can report it
+ const baseMessage = err instanceof Error ? err.message : 'Unknown error during vault sync';
+ // Check if message already has an error code (E-XXX format)
+ const hasErrorCode = /E-\d{3}/.test(baseMessage);
+ const errorMessage = hasErrorCode
+ ? baseMessage
+ : formatErrorWithCode(baseMessage, AppErrorCode.UNKNOWN_ERROR);
return { success: false, hasNewVault: false, wasOffline: false, upgradeRequired: false, requiresLogout: false, error: errorMessage };
}
}
diff --git a/apps/browser-extension/src/entrypoints/contentScript/Popup.ts b/apps/browser-extension/src/entrypoints/contentScript/Popup.ts
index adc04e3e6..0afa81621 100644
--- a/apps/browser-extension/src/entrypoints/contentScript/Popup.ts
+++ b/apps/browser-extension/src/entrypoints/contentScript/Popup.ts
@@ -356,9 +356,14 @@ export async function createAutofillPopup(input: HTMLInputElement, items: Item[]
}
// Create item in background.
- await sendMessage('CREATE_ITEM', {
+ const createResponse = await sendMessage('CREATE_ITEM', {
item: JSON.parse(JSON.stringify(newItem))
- }, 'background');
+ }, 'background') as { success: boolean; error?: string };
+
+ // Check if item creation succeeded
+ if (!createResponse.success) {
+ throw new Error(createResponse.error || 'Failed to create item');
+ }
// Close popup.
removeExistingPopup(rootContainer);
diff --git a/apps/browser-extension/src/entrypoints/popup/components/Folders/FolderModal.tsx b/apps/browser-extension/src/entrypoints/popup/components/Folders/FolderModal.tsx
index 6d1b500a0..50e6b2bad 100644
--- a/apps/browser-extension/src/entrypoints/popup/components/Folders/FolderModal.tsx
+++ b/apps/browser-extension/src/entrypoints/popup/components/Folders/FolderModal.tsx
@@ -3,6 +3,8 @@ import { useTranslation } from 'react-i18next';
import ModalWrapper from '@/entrypoints/popup/components/Dialogs/ModalWrapper';
+import { hasErrorCode, getErrorMessage } from '@/utils/types/errors/AppErrorCodes';
+
type FolderModalProps = {
isOpen: boolean;
onClose: () => void;
@@ -52,7 +54,11 @@ const FolderModal: React.FC<FolderModalProps> = ({
await onSave(trimmedName);
onClose();
} catch (err) {
- setError(t('common.errors.unknownErrorTryAgain'));
+ if (hasErrorCode(err)) {
+ setError(getErrorMessage(err, t('common.errors.unknownErrorTryAgain')));
+ } else {
+ setError(t('common.errors.unknownErrorTryAgain'));
+ }
console.error('Error saving folder:', err);
} finally {
setIsSubmitting(false);
diff --git a/apps/browser-extension/src/entrypoints/popup/context/DbContext.tsx b/apps/browser-extension/src/entrypoints/popup/context/DbContext.tsx
index 062d90474..9d088b31b 100644
--- a/apps/browser-extension/src/entrypoints/popup/context/DbContext.tsx
+++ b/apps/browser-extension/src/entrypoints/popup/context/DbContext.tsx
@@ -169,11 +169,18 @@ export const DbProvider: React.FC<{ children: React.ReactNode }> = ({ children }
/**
* Load the stored (encrypted) vault from background storage into memory.
- * Returns the SqliteClient if vault was loaded successfully, null otherwise.
+ * Returns the SqliteClient if vault was loaded successfully.
+ * Throws an error if the background returns an error (all errors now have E-XXX codes).
*/
const loadStoredDatabase = useCallback(async (): Promise<SqliteClient | null> => {
try {
const response = await sendMessage('GET_VAULT', {}, 'background') as messageVaultResponse;
+
+ // Check if response contains an error - throw it so callers can handle
+ if (!response?.success && response?.error) {
+ throw new Error(response.error);
+ }
+
if (response?.vault) {
const client = new SqliteClient();
await client.initializeFromBase64(response.vault);
@@ -183,6 +190,7 @@ export const DbProvider: React.FC<{ children: React.ReactNode }> = ({ children }
setDbAvailable(true);
return client;
} else {
+ // No vault and no error - this shouldn't happen but handle gracefully
setDbInitialized(true);
setDbAvailable(false);
return null;
@@ -191,7 +199,8 @@ export const DbProvider: React.FC<{ children: React.ReactNode }> = ({ children }
console.error('Error retrieving vault from background:', error);
setDbInitialized(true);
setDbAvailable(false);
- return null;
+ // Re-throw all errors so callers can display them with proper codes
+ throw error;
}
}, []);
diff --git a/apps/browser-extension/src/entrypoints/popup/pages/Reinitialize.tsx b/apps/browser-extension/src/entrypoints/popup/pages/Reinitialize.tsx
index c14bfec87..948b7e05d 100644
--- a/apps/browser-extension/src/entrypoints/popup/pages/Reinitialize.tsx
+++ b/apps/browser-extension/src/entrypoints/popup/pages/Reinitialize.tsx
@@ -168,7 +168,7 @@ const Reinitialize: React.FC = () => {
};
handleInitialization();
- }, [isFullyInitialized, requiresAuth, isLoggedIn, dbAvailable, navigate, setIsInitialLoading, syncVault, restoreLastPage, refreshSyncState]);
+ }, [isFullyInitialized, requiresAuth, isLoggedIn, dbAvailable, navigate, setIsInitialLoading, syncVault, restoreLastPage, refreshSyncState, hasPendingMigrations]);
// This component doesn't render anything visible - it just handles initialization
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 bb54f8673..5a398269e 100644
--- a/apps/browser-extension/src/entrypoints/popup/pages/auth/Login.tsx
+++ b/apps/browser-extension/src/entrypoints/popup/pages/auth/Login.tsx
@@ -21,6 +21,7 @@ import { SrpAuthService } from '@/utils/auth/SrpAuthService';
import type { VaultResponse, LoginResponse } from '@/utils/dist/core/models/webapi';
import { EncryptionUtility } from '@/utils/EncryptionUtility';
import { ApiAuthError } from '@/utils/types/errors/ApiAuthError';
+import { hasErrorCode, getErrorMessage } from '@/utils/types/errors/AppErrorCodes';
import type { MobileLoginResult } from '@/utils/types/messaging/MobileLoginResult';
import { storage } from '#imports';
@@ -284,6 +285,9 @@ const Login: React.FC = () => {
// Show API authentication errors as-is.
if (err instanceof ApiAuthError) {
setError(t('common.apiErrors.' + err.message));
+ } else if (hasErrorCode(err)) {
+ // Error contains an error code (E-XXX), show the formatted message as-is
+ setError(getErrorMessage(err, t('auth.errors.serverError')));
} else {
setError(t('auth.errors.serverError'));
}
@@ -345,6 +349,9 @@ const Login: React.FC = () => {
console.error('2FA error:', err);
if (err instanceof ApiAuthError) {
setError(t('common.apiErrors.' + err.message));
+ } else if (hasErrorCode(err)) {
+ // Error contains an error code (E-XXX), show the formatted message as-is
+ setError(getErrorMessage(err, t('auth.errors.serverError')));
} else {
setError(t('auth.errors.serverError'));
}
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 672b10c84..84aefa1ba 100644
--- a/apps/browser-extension/src/entrypoints/popup/pages/auth/Unlock.tsx
+++ b/apps/browser-extension/src/entrypoints/popup/pages/auth/Unlock.tsx
@@ -31,6 +31,7 @@ import {
resetFailedAttempts,
unlockWithPin
} from '@/utils/PinUnlockService';
+import { hasErrorCode, getErrorMessage } from '@/utils/types/errors/AppErrorCodes';
import { VaultVersionIncompatibleError } from '@/utils/types/errors/VaultVersionIncompatibleError';
import type { MobileLoginResult } from '@/utils/types/messaging/MobileLoginResult';
@@ -273,13 +274,14 @@ const Unlock: React.FC = () => {
// Store the encryption key in session storage.
await dbContext.storeEncryptionKey(passwordHashBase64);
- // Load the stored vault from background (decrypts using stored encryption key)
+ /*
+ * Load the stored vault from background (decrypts using stored encryption key).
+ * Throws an error with E-XXX code if decryption fails.
+ */
const sqliteClient = await dbContext.loadStoredDatabase();
if (!sqliteClient) {
- // Decryption failed - likely wrong password
- setError(t('auth.errors.wrongPassword'));
- hideLoading();
- return;
+ // Edge case: no vault loaded but no error thrown (shouldn't happen)
+ throw new Error(t('auth.errors.wrongPassword'));
}
// Check if there are pending migrations
@@ -301,6 +303,9 @@ const Unlock: React.FC = () => {
// Check if it's a version incompatibility error
if (err instanceof VaultVersionIncompatibleError) {
await app.logout(err.message);
+ } else if (hasErrorCode(err)) {
+ // Error contains an error code (E-XXX), show the formatted message as-is
+ setError(getErrorMessage(err, t('auth.errors.wrongPassword')));
} else {
setError(t('auth.errors.wrongPassword'));
}
@@ -373,10 +378,12 @@ const Unlock: React.FC = () => {
* - Checking if server has newer version
* - Merging local changes with server if isDirty is true
* - Overwriting local with server if no local changes
+ *
+ * Throws an error with E-XXX code if decryption fails.
*/
const sqliteClient = await dbContext.loadStoredDatabase();
if (!sqliteClient) {
- // Decryption failed - likely wrong PIN
+ // Edge case: no vault loaded but no error thrown (shouldn't happen)
throw new IncorrectPinError(3);
}
@@ -410,6 +417,11 @@ const Unlock: React.FC = () => {
} else if (err instanceof InvalidPinFormatError) {
setError(t('settings.unlockMethod.invalidPinFormat'));
setPin('');
+ } else if (hasErrorCode(err)) {
+ // Error contains an error code (E-XXX), show the formatted message as-is
+ console.error('PIN unlock failed:', err);
+ setError(getErrorMessage(err, t('common.errors.unknownErrorTryAgain')));
+ setPin('');
} else {
console.error('PIN unlock failed:', err);
setError(t('common.errors.unknownErrorTryAgain'));
@@ -466,13 +478,13 @@ const Unlock: React.FC = () => {
* - Checking if server has newer version
* - Merging local changes with server if isDirty is true
* - Overwriting local with server if no local changes
+ *
+ * Throws an error with E-XXX code if decryption fails.
*/
const sqliteClient = await dbContext.loadStoredDatabase();
if (!sqliteClient) {
- // Decryption failed
- setError(t('common.errors.unknownErrorTryAgain'));
- hideLoading();
- return;
+ // Edge case: no vault loaded but no error thrown (shouldn't happen)
+ throw new Error(t('common.errors.unknownErrorTryAgain'));
}
// Check if there are pending migrations
@@ -494,6 +506,9 @@ const Unlock: React.FC = () => {
// Check if it's a version incompatibility error
if (err instanceof VaultVersionIncompatibleError) {
await app.logout(err.message);
+ } else if (hasErrorCode(err)) {
+ // Error contains an error code (E-XXX), show the formatted message as-is
+ setError(getErrorMessage(err, t('common.errors.unknownErrorTryAgain')));
} else {
setError(t('common.errors.unknownErrorTryAgain'));
}
diff --git a/apps/browser-extension/src/utils/types/errors/AppErrorCodes.ts b/apps/browser-extension/src/utils/types/errors/AppErrorCodes.ts
new file mode 100644
index 000000000..61024b770
--- /dev/null
+++ b/apps/browser-extension/src/utils/types/errors/AppErrorCodes.ts
@@ -0,0 +1,206 @@
+/**
+ * Application error codes for the browser extension.
+ *
+ * These codes serve two purposes:
+ * 1. Enable multi-language support by mapping codes to translation keys
+ * 2. Provide debugging information when users report "unknown errors"
+ *
+ * When displayed to users, show: "Error occurred (Code: E-XXX)"
+ * This allows users to report the code for debugging while keeping messages translatable.
+ *
+ * Code ranges:
+ * - E-0xx: Generic errors
+ * - E-1xx: Auth status check errors
+ * - E-2xx: Vault retrieval errors (handleGetVault)
+ * - E-3xx: Item/credential operations
+ * - E-4xx: Passkey operations
+ * - E-5xx: Sync operations (handleFullVaultSync)
+ * - E-6xx: Storage read/write errors
+ * - E-7xx: Merge operations
+ * - E-8xx: Upload operations
+ * - E-9xx: Migration/version errors
+ */
+export enum AppErrorCode {
+ // Generic errors (E-0xx)
+ UNKNOWN_ERROR = 'E-001',
+
+ // Auth status check errors (E-1xx) - handleCheckAuthStatus
+ AUTH_STATUS_CHECK_FAILED = 'E-101',
+ AUTH_STATUS_MIGRATION_CHECK_FAILED = 'E-102',
+ AUTH_VERSION_CHECK_FAILED = 'E-103',
+
+ // Vault retrieval errors (E-2xx) - handleGetVault
+ VAULT_NOT_FOUND = 'E-201', // No encrypted vault in storage
+ VAULT_LOCKED = 'E-202', // No encryption key available
+ VAULT_DECRYPT_FAILED = 'E-203', // Decryption failed
+ VAULT_METADATA_READ_FAILED = 'E-204', // Failed to read vault metadata
+
+ // Item/credential operations (E-3xx) - handleCreateItem, handleUpdateItem, etc.
+ ITEM_CREATE_FAILED = 'E-301',
+ ITEM_UPDATE_FAILED = 'E-302',
+ ITEM_DELETE_FAILED = 'E-303',
+ ITEM_READ_FAILED = 'E-304',
+
+ // Passkey operations (E-4xx)
+ PASSKEY_CREATE_FAILED = 'E-401',
+ PASSKEY_GET_FAILED = 'E-402',
+
+ // Sync operations (E-5xx) - handleFullVaultSync
+ SYNC_STATUS_CHECK_FAILED = 'E-501', // Failed to get server status
+ SYNC_VAULT_FETCH_FAILED = 'E-502', // Failed to fetch vault from server
+ SYNC_VAULT_DECRYPT_FAILED = 'E-503', // Failed to decrypt server vault
+ SYNC_STORE_FAILED = 'E-504', // Failed to store synced vault locally
+
+ // Storage read/write errors (E-6xx)
+ STORAGE_READ_FAILED = 'E-601',
+ STORAGE_WRITE_FAILED = 'E-602',
+ DATABASE_INIT_FAILED = 'E-603',
+ ENCRYPTION_KEY_NOT_FOUND = 'E-604',
+
+ // Merge operations (E-7xx)
+ MERGE_FAILED = 'E-701',
+ MERGE_CONFLICT = 'E-702',
+ MERGE_UPLOAD_FAILED = 'E-703',
+
+ // Upload operations (E-8xx)
+ UPLOAD_FAILED = 'E-801',
+ UPLOAD_OUTDATED = 'E-802', // Server has newer version
+ UPLOAD_ENCRYPT_FAILED = 'E-803',
+
+ // Migration/version errors (E-9xx)
+ MIGRATION_CHECK_FAILED = 'E-901',
+ VERSION_INCOMPATIBLE = 'E-902',
+}
+
+/**
+ * All valid error code values for quick lookup
+ */
+const ERROR_CODE_VALUES = new Set(Object.values(AppErrorCode));
+
+/**
+ * Check if a string is a valid error code (E-XXX format)
+ */
+export function isErrorCode(code: string): code is AppErrorCode {
+ return ERROR_CODE_VALUES.has(code as AppErrorCode);
+}
+
+/**
+ * Extract error code from a string (e.g., "Error occurred (Code: E-501)" -> "E-501")
+ */
+export function extractErrorCode(message: string): AppErrorCode | null {
+ // Match E-XXX pattern
+ const match = message.match(/E-\d{3}/);
+ if (match && isErrorCode(match[0])) {
+ return match[0] as AppErrorCode;
+ }
+ return null;
+}
+
+/**
+ * Format an error message with an error code for user display.
+ * This allows users to report the code for debugging while keeping the message readable.
+ *
+ * @param message - The user-friendly error message (translated)
+ * @param code - The error code for debugging
+ * @returns Formatted message like "Error occurred (Code: E-501)"
+ */
+export function formatErrorWithCode(message: string, code: AppErrorCode): string {
+ return `${message} (Code: ${code})`;
+}
+
+/**
+ * Map error codes to translation keys for localized error messages.
+ * Returns the translation key that should be used with t() function.
+ */
+export function getErrorTranslationKey(code: AppErrorCode): string {
+ const codeToKeyMap: Record<AppErrorCode, string> = {
+ // Generic errors (E-0xx)
+ [AppErrorCode.UNKNOWN_ERROR]: 'common.errors.unknownErrorTryAgain',
+
+ // Auth status check errors (E-1xx)
+ [AppErrorCode.AUTH_STATUS_CHECK_FAILED]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.AUTH_STATUS_MIGRATION_CHECK_FAILED]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.AUTH_VERSION_CHECK_FAILED]: 'common.errors.unknownErrorTryAgain',
+
+ // Vault retrieval errors (E-2xx)
+ [AppErrorCode.VAULT_NOT_FOUND]: 'common.errors.vaultNotAvailable',
+ [AppErrorCode.VAULT_LOCKED]: 'common.errors.vaultIsLocked',
+ [AppErrorCode.VAULT_DECRYPT_FAILED]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.VAULT_METADATA_READ_FAILED]: 'common.errors.unknownErrorTryAgain',
+
+ // Item/credential operations (E-3xx)
+ [AppErrorCode.ITEM_CREATE_FAILED]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.ITEM_UPDATE_FAILED]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.ITEM_DELETE_FAILED]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.ITEM_READ_FAILED]: 'common.errors.unknownErrorTryAgain',
+
+ // Passkey operations (E-4xx)
+ [AppErrorCode.PASSKEY_CREATE_FAILED]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.PASSKEY_GET_FAILED]: 'common.errors.unknownErrorTryAgain',
+
+ // Sync operations (E-5xx)
+ [AppErrorCode.SYNC_STATUS_CHECK_FAILED]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.SYNC_VAULT_FETCH_FAILED]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.SYNC_VAULT_DECRYPT_FAILED]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.SYNC_STORE_FAILED]: 'common.errors.unknownErrorTryAgain',
+
+ // Storage read/write errors (E-6xx)
+ [AppErrorCode.STORAGE_READ_FAILED]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.STORAGE_WRITE_FAILED]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.DATABASE_INIT_FAILED]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.ENCRYPTION_KEY_NOT_FOUND]: 'common.errors.vaultIsLocked',
+
+ // Merge operations (E-7xx)
+ [AppErrorCode.MERGE_FAILED]: 'common.errors.mergeFailed',
+ [AppErrorCode.MERGE_CONFLICT]: 'common.errors.mergeFailed',
+ [AppErrorCode.MERGE_UPLOAD_FAILED]: 'common.errors.unknownErrorTryAgain',
+
+ // Upload operations (E-8xx)
+ [AppErrorCode.UPLOAD_FAILED]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.UPLOAD_OUTDATED]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.UPLOAD_ENCRYPT_FAILED]: 'common.errors.unknownErrorTryAgain',
+
+ // Migration/version errors (E-9xx)
+ [AppErrorCode.MIGRATION_CHECK_FAILED]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.VERSION_INCOMPATIBLE]: 'common.errors.browserExtensionOutdated',
+ };
+
+ return codeToKeyMap[code] || 'common.errors.unknownErrorTryAgain';
+}
+
+/**
+ * Check if an error has an embedded error code (E-XXX format).
+ * Use this to determine if an error message should be shown as-is (preserving the code)
+ * rather than being replaced with a generic error message.
+ *
+ * @param err - The error (can be Error, string, or unknown)
+ * @returns true if the error contains an E-XXX code
+ */
+export function hasErrorCode(err: unknown): boolean {
+ if (err instanceof Error) {
+ return extractErrorCode(err.message) !== null;
+ }
+ if (typeof err === 'string') {
+ return extractErrorCode(err) !== null;
+ }
+ return false;
+}
+
+/**
+ * Get the error message from an error, preserving error codes if present.
+ * Use this when you want to display an error to the user and want to preserve
+ * any embedded error codes for debugging/reporting purposes.
+ *
+ * @param err - The error (can be Error, string, or unknown)
+ * @param fallback - Fallback message if error has no message
+ * @returns The error message (with code if present)
+ */
+export function getErrorMessage(err: unknown, fallback: string): string {
+ if (err instanceof Error) {
+ return err.message;
+ }
+ if (typeof err === 'string') {
+ return err;
+ }
+ return fallback;
+}