Skip to content

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

Improve mobile app error reporting to be more specific for login/unlock sequence (#1698)

Leendert de Borst2959b7769559
diff --git a/apps/mobile-app/android/app/src/main/java/net/aliasvault/app/vaultstore/AppError.kt b/apps/mobile-app/android/app/src/main/java/net/aliasvault/app/vaultstore/AppError.kt
index 276c3a934..5e6eb203e 100644
--- a/apps/mobile-app/android/app/src/main/java/net/aliasvault/app/vaultstore/AppError.kt
+++ b/apps/mobile-app/android/app/src/main/java/net/aliasvault/app/vaultstore/AppError.kt
@@ -186,6 +186,46 @@ sealed class AppError(message: String, cause: Throwable? = null) : Exception(mes
cause: Throwable? = null,
) : AppError(message, cause)
+ /**
+ * Error indicating keystore access was denied (permission or key invalidation).
+ */
+ class KeystoreAccessDenied(
+ message: String = "Keystore access denied",
+ cause: Throwable? = null,
+ ) : AppError(message, cause)
+
+ /**
+ * Error indicating keystore item was not found (may need re-login).
+ */
+ class KeystoreItemNotFound(
+ message: String = "Keystore item not found - may need to log out and back in",
+ cause: Throwable? = null,
+ ) : AppError(message, cause)
+
+ /**
+ * Error indicating biometric authentication is not available on the device.
+ */
+ class BiometricNotAvailable(
+ message: String = "Biometric authentication not available on this device",
+ cause: Throwable? = null,
+ ) : AppError(message, cause)
+
+ /**
+ * Error indicating no biometrics are enrolled on the device.
+ */
+ class BiometricNotEnrolled(
+ message: String = "No biometrics enrolled on device",
+ cause: Throwable? = null,
+ ) : AppError(message, cause)
+
+ /**
+ * Error indicating biometric authentication is locked out due to too many failed attempts.
+ */
+ class BiometricLockout(
+ message: String = "Biometric authentication locked out",
+ cause: Throwable? = null,
+ ) : AppError(message, cause)
+
// Storage errors
/**
* Error indicating encryption key not available.
@@ -293,6 +333,11 @@ sealed class AppError(message: String, cause: Throwable? = null) : Exception(mes
is BiometricCancelled -> "E-509"
is BiometricFailed -> "E-510"
is KeystoreKeyNotFound -> "E-511"
+ is KeystoreAccessDenied -> "E-512"
+ is KeystoreItemNotFound -> "E-513"
+ is BiometricNotAvailable -> "E-514"
+ is BiometricNotEnrolled -> "E-515"
+ is BiometricLockout -> "E-516"
is VaultStoreFailed -> "E-604"
is VaultMergeFailed -> "E-701"
is MergeUploadFailed -> "E-705"
diff --git a/apps/mobile-app/android/app/src/main/java/net/aliasvault/app/vaultstore/keystoreprovider/AndroidKeystoreProvider.kt b/apps/mobile-app/android/app/src/main/java/net/aliasvault/app/vaultstore/keystoreprovider/AndroidKeystoreProvider.kt
index 48f5a20d3..18c012290 100644
--- a/apps/mobile-app/android/app/src/main/java/net/aliasvault/app/vaultstore/keystoreprovider/AndroidKeystoreProvider.kt
+++ b/apps/mobile-app/android/app/src/main/java/net/aliasvault/app/vaultstore/keystoreprovider/AndroidKeystoreProvider.kt
@@ -196,17 +196,7 @@ class AndroidKeystoreProvider(
errString: CharSequence,
) {
Log.e(TAG, "Authentication error: $errorCode - $errString")
- val error = when (errorCode) {
- BiometricPrompt.ERROR_USER_CANCELED,
- BiometricPrompt.ERROR_NEGATIVE_BUTTON,
- BiometricPrompt.ERROR_CANCELED,
- -> AppError.BiometricCancelled(
- "Biometric authentication cancelled: $errString",
- )
- else -> AppError.BiometricFailed(
- "Biometric authentication error: $errString (code: $errorCode)",
- )
- }
+ val error = mapBiometricErrorToAppError(errorCode, errString.toString())
callback.onError(error)
}
@@ -377,9 +367,7 @@ class AndroidKeystoreProvider(
-> AppError.BiometricCancelled(
"Biometric authentication cancelled: $errString",
)
- else -> AppError.BiometricFailed(
- "Biometric authentication error: $errString (code: $errorCode)",
- )
+ else -> mapBiometricErrorToAppError(errorCode, errString.toString())
}
callback.onError(error)
}
@@ -489,4 +477,50 @@ class AndroidKeystoreProvider(
}
}
}
+
+ /**
+ * Maps BiometricPrompt error codes to specific AppError types for better debugging.
+ */
+ private fun mapBiometricErrorToAppError(errorCode: Int, errString: String): AppError {
+ return when (errorCode) {
+ // User cancellation errors
+ BiometricPrompt.ERROR_USER_CANCELED,
+ BiometricPrompt.ERROR_NEGATIVE_BUTTON,
+ BiometricPrompt.ERROR_CANCELED,
+ -> AppError.BiometricCancelled("Biometric authentication cancelled: $errString")
+
+ // Hardware/availability errors
+ BiometricPrompt.ERROR_HW_NOT_PRESENT,
+ BiometricPrompt.ERROR_HW_UNAVAILABLE,
+ -> AppError.BiometricNotAvailable("Biometric hardware not available: $errString")
+
+ // Enrollment errors
+ BiometricPrompt.ERROR_NO_BIOMETRICS,
+ -> AppError.BiometricNotEnrolled("No biometrics enrolled: $errString")
+
+ // Lockout errors
+ BiometricPrompt.ERROR_LOCKOUT,
+ BiometricPrompt.ERROR_LOCKOUT_PERMANENT,
+ -> AppError.BiometricLockout("Biometric locked out: $errString (code: $errorCode)")
+
+ // Security/key errors - may need re-authentication
+ BiometricPrompt.ERROR_SECURITY_UPDATE_REQUIRED,
+ -> AppError.KeystoreAccessDenied("Security update required: $errString")
+
+ // Timeout and other errors
+ BiometricPrompt.ERROR_TIMEOUT,
+ -> AppError.BiometricFailed("Biometric authentication timed out: $errString")
+
+ BiometricPrompt.ERROR_NO_DEVICE_CREDENTIAL,
+ -> AppError.BiometricFailed("No device credential available: $errString")
+
+ BiometricPrompt.ERROR_UNABLE_TO_PROCESS,
+ BiometricPrompt.ERROR_NO_SPACE,
+ BiometricPrompt.ERROR_VENDOR,
+ -> AppError.BiometricFailed("Biometric error: $errString (code: $errorCode)")
+
+ // Default fallback
+ else -> AppError.BiometricFailed("Biometric authentication error: $errString (code: $errorCode)")
+ }
+ }
}
diff --git a/apps/mobile-app/hooks/useVaultSync.ts b/apps/mobile-app/hooks/useVaultSync.ts
index 007eb320d..ae443095d 100644
--- a/apps/mobile-app/hooks/useVaultSync.ts
+++ b/apps/mobile-app/hooks/useVaultSync.ts
@@ -176,10 +176,17 @@ export const useVaultSync = (): {
return false;
}
- console.error('Failed to unlock vault:', err);
+ // Extract the specific error code from native layer if available
+ // This preserves detailed error info (E-501 to E-511) for debugging
+ const nativeErrorCode = getAppErrorCode(err);
+ const errorCode = nativeErrorCode ?? AppErrorCode.NATIVE_UNLOCK_FAILED;
+
+ console.error(`Failed to unlock vault (${errorCode}):`, err);
+
+ // Re-throw with the specific error code for proper handling
throw new Error(formatErrorWithCode(
- t('common.errors.unknownErrorTryAgain'),
- AppErrorCode.NATIVE_UNLOCK_FAILED
+ t(getErrorTranslationKey(errorCode)),
+ errorCode
));
}
} catch (err) {
diff --git a/apps/mobile-app/ios/VaultStoreKit/Enums/AppError.swift b/apps/mobile-app/ios/VaultStoreKit/Enums/AppError.swift
index baa460035..d82189a8b 100644
--- a/apps/mobile-app/ios/VaultStoreKit/Enums/AppError.swift
+++ b/apps/mobile-app/ios/VaultStoreKit/Enums/AppError.swift
@@ -33,6 +33,11 @@ public enum AppError: Error {
case biometricCancelled
case biometricFailed
case keystoreKeyNotFound
+ case keychainAccessDenied(status: OSStatus)
+ case keychainItemNotFound
+ case biometricNotAvailable
+ case biometricNotEnrolled
+ case biometricLockout
// Storage errors
case encryptionKeyNotFound
@@ -111,6 +116,16 @@ public enum AppError: Error {
return "E-510"
case .keystoreKeyNotFound:
return "E-511"
+ case .keychainAccessDenied:
+ return "E-512"
+ case .keychainItemNotFound:
+ return "E-513"
+ case .biometricNotAvailable:
+ return "E-514"
+ case .biometricNotEnrolled:
+ return "E-515"
+ case .biometricLockout:
+ return "E-516"
case .vaultStoreFailed:
return "E-604"
case .vaultMergeFailed:
@@ -175,6 +190,16 @@ public enum AppError: Error {
return "Biometric authentication failed"
case .keystoreKeyNotFound:
return "Encryption key not found in keychain"
+ case .keychainAccessDenied(let status):
+ return "Keychain access denied (status: \(status))"
+ case .keychainItemNotFound:
+ return "Keychain item not found - may need to log out and back in"
+ case .biometricNotAvailable:
+ return "Biometric authentication not available on this device"
+ case .biometricNotEnrolled:
+ return "No biometrics enrolled on device"
+ case .biometricLockout:
+ return "Biometric authentication locked out"
case .vaultStoreFailed(let message):
return "Failed to store vault: \(message)"
case .vaultMergeFailed(let message):
diff --git a/apps/mobile-app/ios/VaultStoreKit/VaultStore+Crypto.swift b/apps/mobile-app/ios/VaultStoreKit/VaultStore+Crypto.swift
index 5692bafac..9d9ac071c 100644
--- a/apps/mobile-app/ios/VaultStoreKit/VaultStore+Crypto.swift
+++ b/apps/mobile-app/ios/VaultStoreKit/VaultStore+Crypto.swift
@@ -174,7 +174,21 @@ extension VaultStore {
#if targetEnvironment(simulator)
print("Simulator detected, skipping biometric policy evaluation check and continuing with key retrieval from keychain")
#else
- guard context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &error) else {
+ if !context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &error) {
+ // Map LAError codes to specific error types for better debugging
+ if let laError = error as? LAError {
+ switch laError.code {
+ case .biometryNotAvailable:
+ throw AppError.biometricNotAvailable
+ case .biometryNotEnrolled:
+ throw AppError.biometricNotEnrolled
+ case .biometryLockout:
+ throw AppError.biometricLockout
+ default:
+ print("LAError code: \(laError.code.rawValue), description: \(laError.localizedDescription)")
+ throw AppError.biometricFailed
+ }
+ }
throw AppError.biometricFailed
}
#endif
@@ -266,11 +280,31 @@ extension VaultStore {
guard status == errSecSuccess,
let keyData = result as? Data else {
- if status == errSecUserCanceled {
+ // Map keychain status codes to specific errors for better debugging
+ switch status {
+ case errSecUserCanceled:
throw AppError.biometricCancelled
- } else if status == errSecAuthFailed {
+ case errSecAuthFailed:
throw AppError.biometricFailed
- } else {
+ case errSecItemNotFound:
+ // Key not found in keychain - user may need to re-login
+ print("Keychain item not found (errSecItemNotFound: \(status))")
+ throw AppError.keychainItemNotFound
+ case errSecInteractionNotAllowed:
+ // Access denied - may happen if app is in background or screen is locked
+ print("Keychain interaction not allowed (errSecInteractionNotAllowed: \(status))")
+ throw AppError.keychainAccessDenied(status: status)
+ case errSecMissingEntitlement:
+ // Missing keychain-access-groups entitlement or access group mismatch
+ print("Missing keychain entitlement (errSecMissingEntitlement: \(status))")
+ throw AppError.keychainAccessDenied(status: status)
+ case errSecDecode:
+ // Data corruption or format issue
+ print("Keychain decode error (errSecDecode: \(status))")
+ throw AppError.keychainAccessDenied(status: status)
+ default:
+ // Log the specific status code for debugging
+ print("Keychain error - status: \(status)")
throw AppError.keystoreKeyNotFound
}
}
diff --git a/apps/mobile-app/utils/types/errors/AppErrorCodes.ts b/apps/mobile-app/utils/types/errors/AppErrorCodes.ts
index 1cc7c065d..f46fa07f0 100644
--- a/apps/mobile-app/utils/types/errors/AppErrorCodes.ts
+++ b/apps/mobile-app/utils/types/errors/AppErrorCodes.ts
@@ -57,6 +57,11 @@ export enum AppErrorCode {
BIOMETRIC_CANCELLED = 'E-509', // AppError: biometric authentication cancelled
BIOMETRIC_FAILED = 'E-510', // AppError: biometric authentication failed
KEYSTORE_KEY_NOT_FOUND = 'E-511', // AppError: encryption key not found in keystore
+ KEYCHAIN_ACCESS_DENIED = 'E-512', // iOS: keychain access denied (entitlement or access group issue)
+ KEYCHAIN_ITEM_NOT_FOUND = 'E-513', // iOS: keychain item not found (may need re-login)
+ BIOMETRIC_NOT_AVAILABLE = 'E-514', // iOS: biometric not available on device
+ BIOMETRIC_NOT_ENROLLED = 'E-515', // iOS: no biometrics enrolled on device
+ BIOMETRIC_LOCKOUT = 'E-516', // iOS: biometric locked out due to too many failed attempts
// Database/Storage errors (E-6xx) - from VaultSync.kt
VAULT_STORE_FAILED = 'E-604', // AppError: failed to store vault
@@ -205,9 +210,14 @@ export function getErrorTranslationKey(code: AppErrorCode): string {
[AppErrorCode.DATABASE_MEMORY_FAILED]: 'common.errors.unknownErrorTryAgain',
[AppErrorCode.DATABASE_BACKUP_FAILED]: 'common.errors.unknownErrorTryAgain',
[AppErrorCode.DATABASE_PRAGMA_FAILED]: 'common.errors.unknownErrorTryAgain',
- [AppErrorCode.BIOMETRIC_CANCELLED]: 'auth.errors.biometricCancelled',
- [AppErrorCode.BIOMETRIC_FAILED]: 'auth.errors.biometricFailed',
+ [AppErrorCode.BIOMETRIC_CANCELLED]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.BIOMETRIC_FAILED]: 'common.errors.unknownErrorTryAgain',
[AppErrorCode.KEYSTORE_KEY_NOT_FOUND]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.KEYCHAIN_ACCESS_DENIED]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.KEYCHAIN_ITEM_NOT_FOUND]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.BIOMETRIC_NOT_AVAILABLE]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.BIOMETRIC_NOT_ENROLLED]: 'common.errors.unknownErrorTryAgain',
+ [AppErrorCode.BIOMETRIC_LOCKOUT]: 'common.errors.unknownErrorTryAgain',
// Database/Storage errors
[AppErrorCode.VAULT_STORE_FAILED]: 'common.errors.unknownErrorTryAgain',