π End-to-end encrypted cloud for everything.
Dart 2faandroidauthye2eeencryptionend-to-end-encryptionfluttergolanggoogle-photosgoogle-photos-alternativeiosopensourcephotosprivacyprivacy-toolstypescriptzero-knowledge
Add offline key recovery guidance
Neeraj Guptab70feafd1de2
diff --git a/docs/docs/.vitepress/sidebar.ts b/docs/docs/.vitepress/sidebar.tsindex 4609379be8..0ca750ba6f 100644--- a/docs/docs/.vitepress/sidebar.ts+++ b/docs/docs/.vitepress/sidebar.ts@@ -396,6 +396,10 @@ export const sidebar = [text: "Troubleshooting",collapsed: true,items: [+ {+ text: "Offline codes unavailable",+ link: "/auth/troubleshooting/offline-codes-unavailable",+ },{text: "Linux system authentication",link: "/auth/troubleshooting/linux-system-auth",diff --git a/docs/docs/auth/features/offline-mode.md b/docs/docs/auth/features/offline-mode.mdindex c7f4b243e1..af86dbb11b 100644--- a/docs/docs/auth/features/offline-mode.md+++ b/docs/docs/auth/features/offline-mode.md@@ -24,3 +24,5 @@ App lock protects access to the app UI. It is not a recovery password for your c## Back up your codesOpen `Settings > Data > Local backup` to enable automatic local backups, or create an encrypted export from the Data settings. Keep your backup or export files and password somewhere safe.++If Ente Auth cannot access your offline codes, follow the [offline-code recovery steps](/auth/troubleshooting/offline-codes-unavailable) before resetting the app.diff --git a/docs/docs/auth/troubleshooting/offline-codes-unavailable.md b/docs/docs/auth/troubleshooting/offline-codes-unavailable.mdnew file mode 100644index 0000000000..f3374fed03--- /dev/null+++ b/docs/docs/auth/troubleshooting/offline-codes-unavailable.md@@ -0,0 +1,70 @@+---+title: Offline codes unavailable - Auth+description: Recover or reset Ente Auth when the key for offline codes is unavailable+---++# Offline codes unavailable++Ente Auth shows **Unable to access your codes** when the app was configured for offline mode but its encryption key is no longer available from the operating system's secure storage.++## When this can happen++**On iOS:**++- After restoring or transferring Ente Auth to another iPhone. The device-only Keychain key does not transfer with the app's data.++**On macOS:**++- After restoring application data without the corresponding login Keychain.+- If Ente Auth loses access to its existing Keychain entry.++**On Linux:**++- After an update or restart changes which service provides Secret Service.+- If the original GNOME Keyring, KWallet, KeePassXC, or other provider is locked, disabled, missing, or damaged.++**On Windows:**++- After moving or restoring Ente Auth data to another computer or Windows user profile.+- After reinstalling Windows or recreating the user profile.+- After an administrative or offline password reset performed without the old password. A normal password change should not usually cause this.+- If access to Ente Auth's secure-storage file is blocked or the file is damaged.++## Recover or reset Ente Auth++Choose the first case that applies.++### Your codes were already synced to Ente++Reset Ente Auth using the steps below, then select **Log in**. Signing in restores the codes already stored in that Ente account. It does not recover codes that existed only in the inaccessible offline database.++### You have a local backup or encrypted export++Before resetting Ente Auth, confirm that the backup file is stored outside the app's data and that you know its encryption password.++After resetting the app, select **Use without backups**, then open `Settings > Data > Import codes > Ente encrypted`. Automatic local backups use the Ente encrypted format. For an export from another authenticator, select its importer instead.++### You do not have a synced copy or usable backup++> [!WARNING]+>+> Do not reset, uninstall, or clear Ente Auth's data yet. Try to restore access to the original secure storage first. If its key has been permanently lost, the encrypted offline database cannot be recovered.++- **On iOS:** Try the original iPhone. A device-only key cannot be recovered from data restored to another device.+- **On macOS:** Restore access to the original login Keychain or a system backup containing both the Keychain and Ente Auth data.+- **On Linux:** Unlock or restore the Secret Service provider that Ente Auth originally used.+- **On Windows:** Use the original Windows profile. If an administrator reset a domain account's password, contact the administrator before changing app data because its protected keys may still be recoverable.++## Reset the app++Reset only after confirming that your codes are synced to Ente or that you have a usable backup and its password. Keep a copy of the existing app data until recovery or import succeeds.++**On iOS:** Delete Ente Auth rather than offloading it, then reinstall it.++**On macOS:** Quit Ente Auth, move `~/Library/Application Support/io.ente.auth.mac` to a safe location, and run `defaults delete io.ente.auth.mac` in Terminal. If the legacy `ente.authenticator.db` or `ente.offline_authenticator.db` file exists in Documents, move it aside too.++**On Linux:** Quit Ente Auth and move the `io.ente.auth` directory under `$XDG_DATA_HOME` to a safe location. The default location is `~/.local/share/io.ente.auth`. Move legacy `ente_auth` or `enteauth` directories in the same location if they exist.++**On Windows:** Quit Ente Auth and rename `%APPDATA%\Ente Technologies, Inc\Ente Auth` in File Explorer. If an `ente` or `enteauth` folder from an older installation exists in Documents, rename it too.++Open Ente Auth again, then log in or import the backup. Remove the saved app data only after confirming that all codes have been restored.diff --git a/mobile/apps/auth/lib/app/view/app.dart b/mobile/apps/auth/lib/app/view/app.dartindex 7a94fc5250..0fa2ee55f2 100644--- a/mobile/apps/auth/lib/app/view/app.dart+++ b/mobile/apps/auth/lib/app/view/app.dart@@ -151,7 +151,9 @@ class _AppState extends State<App> with WidgetsBindingObserver {config.hasConfiguredAccount() ||(hasOfflineAccount && !isOfflineKeyMissing)? const HomePage()- : OnboardingPage(recoverOfflineMode: isOfflineKeyMissing),+ : OnboardingPage(+ showOfflineKeyUnavailableDialog: isOfflineKeyMissing,+ ),};}diff --git a/mobile/apps/auth/lib/onboarding/view/onboarding_page.dart b/mobile/apps/auth/lib/onboarding/view/onboarding_page.dartindex 6d63eb515d..d92258e194 100644--- a/mobile/apps/auth/lib/onboarding/view/onboarding_page.dart+++ b/mobile/apps/auth/lib/onboarding/view/onboarding_page.dart@@ -11,10 +11,10 @@ import 'package:ente_auth/app/view/app.dart';import 'package:ente_auth/core/configuration.dart';import 'package:ente_auth/events/trigger_logout_event.dart';import 'package:ente_auth/locale.dart';-import 'package:ente_auth/store/offline_authenticator_db.dart';import 'package:ente_auth/theme/colors.dart';import 'package:ente_auth/theme/ente_theme.dart';import 'package:ente_auth/ui/account/logout_dialog.dart';+import 'package:ente_auth/ui/components/dialog_widget.dart';import 'package:ente_auth/ui/home/widgets/rounded_action_buttons.dart';import 'package:ente_auth/ui/home_page.dart';import 'package:ente_auth/ui/settings/developer_settings_widget.dart';@@ -22,6 +22,7 @@ import 'package:ente_auth/ui/settings/language_picker.dart';import 'package:ente_auth/utils/debug_build_flags.dart';import 'package:ente_auth/utils/dialog_util.dart';import 'package:ente_auth/utils/navigation_util.dart';+import 'package:ente_auth/utils/platform_util.dart';import 'package:ente_auth/utils/toast_util.dart';import 'package:ente_components/ente_components.dart';import 'package:ente_events/event_bus.dart';@@ -29,15 +30,19 @@ import 'package:ente_strings/ente_strings.dart';import 'package:ente_ui/components/alert_bottom_sheet.dart';import 'package:ente_ui/components/buttons/button_widget.dart';import 'package:ente_ui/components/buttons/models/button_result.dart';+import 'package:ente_ui/components/buttons/models/button_type.dart';import 'package:flutter/material.dart';import 'package:flutter/rendering.dart';import 'package:flutter_svg/flutter_svg.dart';import 'package:local_auth/local_auth.dart';class OnboardingPage extends StatefulWidget {- final bool recoverOfflineMode;+ final bool showOfflineKeyUnavailableDialog;- const OnboardingPage({super.key, this.recoverOfflineMode = false});+ const OnboardingPage({+ super.key,+ this.showOfflineKeyUnavailableDialog = false,+ });@overrideState<OnboardingPage> createState() => _OnboardingPageState();@@ -56,7 +61,6 @@ class _OnboardingPageState extends State<OnboardingPage> {int _activeDotIndex = 0;int _currentPage = 0;bool _autoScrollDisabled = false;- bool _isRecoveringOfflineMode = false;@overridevoid initState() {@@ -72,9 +76,9 @@ class _OnboardingPageState extends State<OnboardingPage> {await autoLogoutAlert(context);});_startAutoScroll();- if (widget.recoverOfflineMode) {+ if (widget.showOfflineKeyUnavailableDialog) {WidgetsBinding.instance.addPostFrameCallback((_) {- unawaited(_recoverOfflineMode());+ unawaited(_showOfflineKeyUnavailableDialog());});}super.initState();@@ -265,7 +269,7 @@ class _OnboardingPageState extends State<OnboardingPage> {final bool hasOptedBefore = Configuration.instance.hasOptedForOfflineMode();if (hasOptedBefore &&Configuration.instance.getOfflineSecretKey() == null) {- await _recoverOfflineMode();+ await _showOfflineKeyUnavailableDialog();return;}ButtonResult? result;@@ -297,38 +301,24 @@ class _OnboardingPageState extends State<OnboardingPage> {}}- Future<void> _recoverOfflineMode() async {- if (_isRecoveringOfflineMode) return;- _isRecoveringOfflineMode = true;- try {- final offlineDatabase = OfflineAuthenticatorDB.instance;- if (await offlineDatabase.hasEntries()) {- if (!mounted) return;- final l10n = context.strings;- final result = await showChoiceDialog(- context,- title: l10n.unableToAccessYourCodes,- body: l10n.offlineKeyUnavailableMessage,- firstButtonLabel: l10n.startFresh,- secondButtonLabel: l10n.cancel,- isCritical: true,- isDismissible: false,- );- if (result?.action != ButtonAction.first) return;- await offlineDatabase.clearTable();- }- await Configuration.instance.optForOfflineMode();- if (!mounted) return;- unawaited(- Navigator.of(context).pushReplacement(- MaterialPageRoute(- builder: (BuildContext context) => const HomePage(),+ Future<void> _showOfflineKeyUnavailableDialog() async {+ if (!mounted) return;+ final l10n = context.strings;+ await showDialogWidget(+ context: context,+ title: l10n.unableToAccessYourCodes,+ body: l10n.offlineKeyUnavailableMessage,+ buttons: [+ ButtonWidget(+ buttonType: ButtonType.neutral,+ labelText: l10n.troubleshooting,+ onTap: () => PlatformUtil.openUrlInBrowser(+ "https://ente.com/help/auth/troubleshooting/offline-codes-unavailable",),),- );- } finally {- _isRecoveringOfflineMode = false;- }+ ],+ isDismissible: false,+ );}void _startAutoScroll() {diff --git a/mobile/apps/auth/lib/store/offline_authenticator_db.dart b/mobile/apps/auth/lib/store/offline_authenticator_db.dartindex 12cb81c349..9fe86f2660 100644--- a/mobile/apps/auth/lib/store/offline_authenticator_db.dart+++ b/mobile/apps/auth/lib/store/offline_authenticator_db.dart@@ -146,16 +146,6 @@ class OfflineAuthenticatorDB {return _convertRows(rows);}- Future<bool> hasEntries() async {- final db = await instance.database;- final rows = await db.query(- entityTable,- columns: ['_generatedID'],- limit: 1,- );- return rows.isNotEmpty;- }-Future<void> deleteByIDs({List<int>? generatedIDs, List<String>? ids}) async {final db = await instance.database;final batch = db.batch();diff --git a/mobile/packages/strings/lib/l10n/arb/strings_en.arb b/mobile/packages/strings/lib/l10n/arb/strings_en.arbindex 6d5042e61a..b6a23ea04a 100644--- a/mobile/packages/strings/lib/l10n/arb/strings_en.arb+++ b/mobile/packages/strings/lib/l10n/arb/strings_en.arb@@ -2926,7 +2926,7 @@"offlineHomeSignupBannerAction": "Back up now","offlineHomeSignupBannerDescription": "Encrypted backups across 3 locations to keep your memories safe.","offlineHomeSignupBannerTitle": "Protect your memories forever",- "offlineKeyUnavailableMessage": "The encryption key for your offline codes is unavailable. Starting fresh will permanently remove these codes from this device.",+ "offlineKeyUnavailableMessage": "Ente Auth cannot access the key for your offline codes.","offlineModeWarning": "You have chosen to proceed without backups. Please take manual backups to make sure your codes are safe.","offlineNameFaceBannerSubtitle": "Sign up to tag them and easily find their photos later.","offlineNameFaceBannerTitle": "Give this face a name",@@ -4297,7 +4297,6 @@"spotlightOnYourself": "Spotlight on yourself","stargazing": "Under the stars","startBackup": "Start backup",- "startFresh": "Start fresh","startRecovery": "Start recovery","startRecoveryDesc": "Are you sure you want to initiate recovery for {email}'s account?","@startRecoveryDesc": {