merge: Drive sign-in diagnostics

Author: joanroig

docs/guides/google-drive-sync.md

@@ -64,8 +64,34 @@ package/signature pair and is not passed through `--dart-define`. Android also
 uses the Web client ID created above as its server client ID.
 
 For the debug fingerprint, run `./gradlew signingReport` from `android/` (or
-`gradlew.bat signingReport` on Windows). Configure a real release signing key
-before publishing; the current project release build still uses the debug key.
+`gradlew.bat signingReport` on Windows).
+
+For the release fingerprint, read it from the keystore itself:
+
+```powershell
+keytool -list -v -keystore admincraft-release.jks -alias admincraft
+```
+
+!!! warning "Changing the signing key breaks Drive sign-in"
+
+    Google identifies an Android app by package name **and** signing
+    certificate. A build signed with a different key than the registered
+    Android client matches nothing, and sign-in fails with
+    `[16] Account reauth failed` even though the client IDs are correct.
+    Registering a release key after shipping debug-signed builds, as this
+    project did in v2.2.0, is exactly that situation: the release fingerprint
+    needs its own Android client.
+
+    The fingerprint of an already published build can be read from the APK
+    itself, which is worth doing to confirm what actually shipped:
+
+    ```powershell
+    apksigner verify --print-certs admincraft-v2.2.0-android.apk
+    ```
+
+    `apksigner` comes with the Android SDK build-tools. `keytool -printcert
+    -jarfile` will not do here: it reads only v1 JAR signatures, and these
+    APKs are signed with the v2/v3 schemes alone.
 
 #### Windows client
 
@@ -139,3 +165,18 @@ for explicit recovery.
 !!! warning
     Google cannot recover the encryption passphrase. Keep a manual exported
     backup somewhere safe before relying on sync alone.
+
+## When sign-in fails
+
+| What the app says | What it usually means |
+| --- | --- |
+| This build is not registered in its Google Cloud project | No Android OAuth client matches this package name and signing certificate. Register the fingerprint of the build you are running, as above. |
+| Setup required | The build carries no client IDs. They are compiled in, so a build made without them cannot sign in at all; check the repository secrets and rebuild. |
+| Sign-in was cancelled | The account chooser was dismissed. |
+
+Two things that look like app faults and are not:
+
+- The account must be listed under **Test users** while the Google Auth
+  Platform app is in testing. Any other account is refused.
+- The Drive API must be enabled in the same project the OAuth clients belong
+  to. Sign-in can succeed while every sync then fails.

lib/controllers/google_drive_sync_controller.dart

@@ -85,12 +85,38 @@ class GoogleDriveSyncController with ChangeNotifier {
       notifyListeners();
       return result;
     } catch (error) {
-      _error = 'Google sign-in failed: $error';
+      _error = _signInMessage(error);
       notifyListeners();
       return false;
     }
   }
 
+  /// Turns a sign-in failure into something the reader can act on.
+  ///
+  /// The plugin's own text describes what the credential layer saw, not what
+  /// is wrong. "Account reauth failed" in particular is what Android reports
+  /// when it cannot match the running app to an OAuth client, which is a
+  /// setup problem in the Google Cloud project rather than anything the user
+  /// did, and is easy to hit after the app's signing key changes.
+  static String _signInMessage(Object error) {
+    final text = error.toString();
+
+    if (text.contains('reauth failed') || text.contains('10:')) {
+      return 'Google refused the sign-in because this build is not '
+          'registered in its Google Cloud project. An Android OAuth client '
+          'is needed for the package name and the signing certificate of this '
+          'exact build. See the Google Drive sync guide in the docs.';
+    }
+    if (text.contains('canceled') || text.contains('cancelled')) {
+      return 'Sign-in was cancelled.';
+    }
+    if (text.contains('network') || text.contains('SocketException')) {
+      return 'Sign-in could not reach Google. Check the connection and try '
+          'again.';
+    }
+    return 'Google sign-in failed: $error';
+  }
+
   Future<void> disconnect() async {
     _syncTimer?.cancel();
     await _auth.signOut();

pubspec.yaml

@@ -15,7 +15,7 @@ publish_to: "none" # Remove this line if you wish to publish to pub.dev
 # https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html
 # In Windows, build-name is used as the major, minor, and patch parts
 # of the product and file versions while build-number is used as the build suffix.
-version: 2.2.0
+version: 2.2.1
 environment:
   sdk: ^3.12.0
 # Dependencies specify other packages that your package needs in order to work.