capacitor-auth-manager 2.4.4 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/AI-INTEGRATION-GUIDE.md +176 -0
  2. package/CHANGELOG.md +143 -0
  3. package/CapacitorAuthManager.podspec +3 -3
  4. package/README.md +99 -76
  5. package/android/build.gradle +23 -25
  6. package/android/consumer-rules.pro +14 -0
  7. package/android/proguard-rules.pro +5 -30
  8. package/android/src/main/AndroidManifest.xml +4 -9
  9. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/ActivityLauncher.java +26 -0
  10. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/AuthErrorCodes.java +32 -0
  11. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/AuthException.java +34 -0
  12. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/AuthStorage.java +46 -25
  13. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/CapacitorAuthManager.java +62 -40
  14. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/CapacitorAuthManagerPlugin.java +124 -66
  15. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/GoogleAuthProvider.java +225 -374
  16. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/GoogleCredentialManagerSignIn.java +175 -0
  17. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/GoogleLegacySignIn.java +133 -0
  18. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/GoogleProfileCallback.java +8 -0
  19. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/GoogleResultMapper.java +158 -0
  20. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/ProviderFactory.java +11 -3
  21. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/SigningDiagnostics.java +76 -0
  22. package/dist/angular.cjs.js +421 -3376
  23. package/dist/core.cjs.js +589 -149
  24. package/dist/esm/angular/auth.guard.d.ts +1 -1
  25. package/dist/esm/angular/auth.module.d.ts +1 -1
  26. package/dist/esm/angular/auth.module.js +1 -1
  27. package/dist/esm/angular/auth.service.d.ts +2 -2
  28. package/dist/esm/angular/auth.service.js +1 -1
  29. package/dist/esm/angular/index.d.ts +4 -4
  30. package/dist/esm/angular/index.js +4 -4
  31. package/dist/esm/capacitor-plugin.d.ts +2 -3
  32. package/dist/esm/capacitor-plugin.js +14 -4
  33. package/dist/esm/core/auth-manager.d.ts +20 -2
  34. package/dist/esm/core/auth-manager.js +68 -12
  35. package/dist/esm/core/index.d.ts +5 -4
  36. package/dist/esm/core/index.js +5 -4
  37. package/dist/esm/core/provider-manifests.d.ts +1 -1
  38. package/dist/esm/core/provider-manifests.js +12 -13
  39. package/dist/esm/core/provider-registry.d.ts +8 -5
  40. package/dist/esm/core/provider-registry.js +41 -10
  41. package/dist/esm/core/types.d.ts +2 -2
  42. package/dist/esm/definitions.d.ts +29 -0
  43. package/dist/esm/index.d.ts +12 -12
  44. package/dist/esm/index.js +7 -7
  45. package/dist/esm/package.json +1 -0
  46. package/dist/esm/providers/base-provider.d.ts +7 -8
  47. package/dist/esm/providers/base-provider.js +7 -8
  48. package/dist/esm/providers/native/google-native-provider.d.ts +13 -2
  49. package/dist/esm/providers/native/google-native-provider.js +50 -6
  50. package/dist/esm/providers/oauth-provider.d.ts +2 -2
  51. package/dist/esm/providers/oauth-provider.js +3 -3
  52. package/dist/esm/providers/provider-factory.d.ts +5 -5
  53. package/dist/esm/providers/provider-factory.js +2 -2
  54. package/dist/esm/providers/web/google-provider.d.ts +74 -18
  55. package/dist/esm/providers/web/google-provider.js +391 -117
  56. package/dist/esm/providers/web/index.d.ts +1 -1
  57. package/dist/esm/providers/web/index.js +1 -1
  58. package/dist/esm/react/hooks.d.ts +2 -2
  59. package/dist/esm/react/hooks.js +2 -2
  60. package/dist/esm/react/index.d.ts +3 -3
  61. package/dist/esm/react/index.js +3 -3
  62. package/dist/esm/react/types.d.ts +1 -1
  63. package/dist/esm/utils/auth-error.d.ts +1 -1
  64. package/dist/esm/utils/auth-error.js +1 -1
  65. package/dist/esm/utils/event-emitter.d.ts +1 -1
  66. package/dist/esm/utils/event-emitter.js +1 -1
  67. package/dist/esm/utils/pending-verification-store.js +1 -1
  68. package/dist/esm/utils/storage.d.ts +2 -2
  69. package/dist/esm/utils/storage.js +31 -7
  70. package/dist/esm/vue/composables.d.ts +2 -2
  71. package/dist/esm/vue/composables.js +1 -1
  72. package/dist/esm/vue/index.d.ts +2 -2
  73. package/dist/esm/vue/index.js +2 -2
  74. package/dist/esm/web.d.ts +1 -1
  75. package/dist/esm/web.js +6 -6
  76. package/dist/plugin.cjs.js +291 -2771
  77. package/dist/plugin.js +585 -147
  78. package/dist/providers-web.cjs.js +1317 -0
  79. package/dist/react.cjs.js +310 -3265
  80. package/dist/vue.cjs.js +266 -3221
  81. package/ios/Plugin/AuthStorage.swift +3 -1
  82. package/ios/Plugin/GoogleAuthProvider.swift +7 -4
  83. package/ios/Plugin/Models.swift +28 -0
  84. package/ios/Plugin/Plugin.swift +64 -40
  85. package/package.json +54 -32
  86. package/scripts/configure.js +71 -325
package/README.md CHANGED
@@ -13,32 +13,31 @@
13
13
  [![bundle size](https://img.shields.io/bundlephobia/minzip/capacitor-auth-manager.svg)](https://bundlephobia.com/package/capacitor-auth-manager)
14
14
  [![node](https://img.shields.io/node/v/capacitor-auth-manager.svg)](https://nodejs.org)
15
15
 
16
- [Docs](https://capacitor-auth-manager-docs.aoneahsan.com) · [npm](https://www.npmjs.com/package/capacitor-auth-manager) · [GitHub](https://github.com/aoneahsan/capacitor-auth-manager) · [Changelog](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/CHANGELOG.md) · [Support](https://github.com/aoneahsan/capacitor-auth-manager/issues)
16
+ [Docs](https://capacitor-auth-manager-docs.aoneahsan.com) · [npm](https://www.npmjs.com/package/capacitor-auth-manager) · [GitHub](https://github.com/aoneahsan/capacitor-auth-manager) · [Changelog](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/CHANGELOG.md) · [AI Guide](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/AI-INTEGRATION-GUIDE.md) · [Support](https://github.com/aoneahsan/capacitor-auth-manager/issues)
17
17
 
18
18
  </div>
19
19
 
20
20
  > [!IMPORTANT]
21
- > - **Google is the only enabled provider in `2.4.x`.** The other fourteen are present in the source but
21
+ > - **Google is the only enabled provider in `3.x`.** The other fourteen are present in the source but
22
22
  > un-registered — calling one throws `AuthErrorCode.PROVIDER_NOT_ENABLED`. They are re-enabled one at a
23
23
  > time, each verified on a device first.
24
- > - **Import it from a bundler, not from bare Node.** The published ESM build resolves under Vite, webpack,
25
- > Metro and esbuild, but not under Node's own ESM resolver, and importing the package in a server or SSR
26
- > context throws `window is not defined`. See [Limitations](#limitations).
24
+ > - **`@capacitor/core` is a required peer** as of `3.0.0` — the native bridge imports Capacitor core
25
+ > even for a web-only build. Bare Node ESM and server-side imports work since `3.0.0`.
27
26
 
28
27
  Capacitor Auth Manager gives a Capacitor app one Google sign-in call that behaves the same on web, iOS and
29
- Android, and hands back a raw `idToken` to use as you like. It pulls in no `firebase` dependency, so it fits
28
+ Android, and hands back a Google ID token or web popup access token to use as you like. It pulls in no `firebase` dependency, so it fits
30
29
  apps built on Firebase Auth and apps built on their own backend equally well. Typed React, Vue and Angular
31
30
  adapters ship with it, so the sign-in button is a few lines in whichever framework you already use.
32
31
 
33
32
  | | |
34
33
  |---|---|
35
- | **Version** | `2.4.4` |
34
+ | **Version** | `3.0.0` |
36
35
  | **License** | MIT |
37
- | **Node** | `>=18.0.0` |
36
+ | **Node** | `>=24.0.0` |
38
37
  | **Platforms** | Web · iOS · Android |
39
- | **Install size** | 264 kB tarball · ~17.4 kB min+gzip for the root entry |
38
+ | **Install size** | See the npm tarball and bundle-size badge for current measurements |
40
39
  | **Types** | Bundled `.d.ts` (ESM + CJS) |
41
- | **Status** | Google provider in production use · remaining providers staged |
40
+ | **Status** | Google enabled; verify OAuth setup and runtime sign-in in your app |
42
41
 
43
42
  <a id="table-of-contents"></a>
44
43
  ## 🧭 Table of Contents&nbsp;[#](#table-of-contents)
@@ -77,8 +76,8 @@ code path with a different result shape. The branch then leaks into your UI, you
77
76
  handling.
78
77
 
79
78
  This package collapses that into `auth.signIn(AuthProvider.GOOGLE)`. It routes to Google Identity Services on
80
- the web, the GoogleSignIn SDK on iOS and Credential Manager on Android, and returns the same
81
- `{ user, credential }` shape from all three. What you do with the `idToken` afterwards — hand it to Firebase,
79
+ the web, the GoogleSignIn SDK on iOS and GoogleSignIn with a Credential Manager fallback on Android, and returns the same
80
+ `{ user, credential }` shape from all three. What you do with the returned credential afterwards — hand it to Firebase,
82
81
  or verify it on your own server — stays your decision.
83
82
 
84
83
  | | `capacitor-auth-manager` | Firebase popup + a separate native plugin |
@@ -89,50 +88,48 @@ or verify it on your own server — stays your decision.
89
88
  | Framework adapters | React, Vue, Angular included | write your own |
90
89
  | Providers available today | Google | whatever each piece supports |
91
90
 
92
- **Not the right tool when** — you need a provider other than Google today; you need a Google **access token**
93
- in the browser to call Google APIs (the web flow is id-token only); you import packages in bare Node or render
94
- on a server (see [Limitations](#limitations)); or you already have a Firebase-popup web flow that works and no
95
- native build to support.
91
+ **Not the right tool when** — you need a provider other than Google today; you need a Google **refresh
92
+ token** in the browser (neither web flow issues one — use a backend exchange); or you already have a
93
+ Firebase-popup web flow that works and no native build to support.
96
94
 
97
95
  <a id="features"></a>
98
96
  ## ✨ Features&nbsp;[#](#features)
99
97
 
100
98
  - **One call per platform** — the same `signIn` on web, iOS and Android, returning the same shape.
101
- - **Firebase-agnostic** — returns a raw `idToken`, and pulls no `firebase` package into your tree.
102
- - **Modern native SDKs** — Android Credential Manager and iOS GoogleSignIn rather than deprecated APIs.
99
+ - **Firebase-agnostic** — returns Google credentials, and pulls no `firebase` package into your tree.
100
+ - **Proven native SDKs** — GoogleSignIn on iOS and Android (the same Android path `@codetrix-studio/capacitor-google-auth` used), with Android Credential Manager as the automatic fallback.
103
101
  - **Typed framework adapters** — a `useAuth` hook for React, composables for Vue, an injectable
104
102
  `AuthService` and route guards for Angular.
105
103
  - **Observable auth state** — subscribe once with `onAuthStateChange` and let the UI follow.
106
104
  - **Pluggable storage** — web and Capacitor Preferences backends ship with it, and it accepts your own
107
105
  `StorageInterface` when you need Keychain or Keystore.
108
- - **No token persistence by default** — sessions restore through the Google SDK rather than through
109
- `localStorage`.
106
+ - **No token strings in default JS storage** — cached profile metadata can restore locally; Android credentials stay in memory and iOS uses the Google SDK Keychain. Firebase owns the app session.
110
107
 
111
108
  <a id="platform-support"></a>
112
109
  ## 📱 Platform Support&nbsp;[#](#platform-support)
113
110
 
114
111
  | Platform | Supported | Notes |
115
112
  |---|---|---|
116
- | Web | ✅ | Google Identity Services id-token flow. Returns `idToken` only — no `accessToken`. |
117
- | Android | ✅ | Credential Manager. `serverClientId` is required to receive an `idToken`. |
118
- | iOS | ✅ | GoogleSignIn 7.x. Returns `idToken`, `accessToken`, and `serverAuthCode` when configured. |
119
- | Node / SSR | ❌ | Importing the package on a server throws `window is not defined`. See [Limitations](#limitations). |
113
+ | Web | ✅ | Google Identity Services. One-Tap / FedCM returns an `idToken`; the OAuth2 popup fallback returns an `accessToken` (`webFlow`). |
114
+ | Android | ✅ | GoogleSignIn account chooser, falling back to Credential Manager (bottom sheet, then the Sign in with Google button) — `androidFlow`. `serverClientId` is required to receive an `idToken`. |
115
+ | iOS | ✅ | GoogleSignIn 10.x; iOS 15+. Returns `idToken`, `accessToken`, and `serverAuthCode` when configured. |
116
+ | Node / SSR | ✅ import | Importing is side-effect free since `3.0.0`; sign-in itself still needs a browser or a device. |
120
117
 
121
- Native sources for both platforms compile in a clean Capacitor 8 app, verified with Gradle `assembleDebug`
122
- and `pod lib lint`. A successful compile is not a runtime test — sign in once on a real device before rolling
123
- a new version across several apps.
118
+ Package CI compiles a clean Capacitor 8 consumer with Android debug/minified-release builds and an iOS simulator build. A compile check is not a runtime test: verify real Google sign-in with your app’s OAuth clients on each deployed platform.
124
119
 
125
120
  <a id="requirements"></a>
126
121
  ## 📋 Requirements&nbsp;[#](#requirements)
127
122
 
128
123
  | Requirement | Version | Why |
129
124
  |---|---|---|
130
- | Node | `>=18.0.0` | build and install only; the package itself runs in a browser or a webview |
131
- | `@capacitor/core` | `^7.4.2 \|\| ^8.0.0` | peer — imported by the published bundle, so install it even for a web-only build |
125
+ | Node | `>=24.0.0` | build and install only; the package itself runs in a browser or a webview. Current + latest Node only — no legacy targets |
126
+ | `@capacitor/core` | `^7.4.2 \|\| ^8.0.0` | **required** peer — the native bridge imports it, including in web-only builds |
132
127
  | `@capacitor/preferences` | `^6 \|\| ^7 \|\| ^8` | optional peer — only for `CapacitorPreferencesStorage` |
133
128
  | `react` | `^16.8 \|\| ^17 \|\| ^18 \|\| ^19` | optional peer — only for `capacitor-auth-manager/react` |
134
129
  | `vue` | `^3.0.0` | optional peer — only for `capacitor-auth-manager/vue` |
135
- | `@angular/core` | `^12` – `^22` | optional peer — only for `capacitor-auth-manager/angular` |
130
+ | `@angular/core`, `@angular/common`, `@angular/router` | `^22` | optional peers — Angular adapter |
131
+ | `rxjs` | `^7` | optional peer — Angular observables |
132
+ | Native build tools | JDK 21; iOS 15+ with CocoaPods | Android and iOS consumers |
136
133
 
137
134
  You also need Google OAuth client IDs: a **Web** client for every platform, plus an **Android** client
138
135
  registered with your signing fingerprints and an **iOS** client if you ship those platforms.
@@ -147,18 +144,19 @@ yarn add capacitor-auth-manager @capacitor/core
147
144
  For the native plugin, sync it into the platform projects. Without this step iOS and Android never load it:
148
145
 
149
146
  ```bash
150
- npx cap sync
147
+ yarn cap sync
151
148
  ```
152
149
 
153
150
  Then finish the per-platform OAuth setup, which cannot be done from JavaScript:
154
151
 
155
- - **Android** — add your `google-services.json`, register the app's SHA-1 and SHA-256 fingerprints against an
156
- Android OAuth client, and pass your **Web** client ID as `serverClientId`. Credential Manager will not
157
- return an `idToken` without it. The plugin adds no manifest permissions of its own.
152
+ - **Android** — register the app's SHA-1 and SHA-256 fingerprints against an
153
+ Android OAuth client, and pass your **Web** client ID as `serverClientId`; Google returns no `idToken`
154
+ without it. Register **every** signing key: the debug key, the upload key (locally signed APKs) and the
155
+ **Play App Signing** key (every Play-installed copy is re-signed with it). The plugin declares only `INTERNET`, without SMS or biometric permissions. It does not require a Firebase native SDK or `google-services.json` of its own.
158
156
  - **iOS** — add `GIDClientID` to `Info.plist` (or pass `iosClientId`), and add the reversed client ID as a URL
159
157
  scheme under `CFBundleURLTypes`.
160
158
 
161
- The bundled [command-line helper](#command-line) can write most of this for you.
159
+ The [AI integration guide](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/AI-INTEGRATION-GUIDE.md) covers the full React/Firebase setup. The bundled [command-line helper](#command-line) creates new JavaScript configuration files and prints native setup instructions.
162
160
 
163
161
  <a id="quick-start"></a>
164
162
  ## 🚀 Quick Start&nbsp;[#](#quick-start)
@@ -180,7 +178,8 @@ auth.configure({
180
178
  });
181
179
 
182
180
  const result = await auth.signIn(AuthProvider.GOOGLE);
183
- console.log(result.user.email, result.credential.idToken);
181
+ // Hand credential.idToken OR credential.accessToken to Firebase; see Usage.
182
+ // Never log credential tokens.
184
183
  ```
185
184
 
186
185
  `AuthProvider.GOOGLE` is the typo-safe form of the string `'google'`; either works.
@@ -190,19 +189,20 @@ console.log(result.user.email, result.credential.idToken);
190
189
 
191
190
  ### Hand the credential to Firebase
192
191
 
193
- Identical on web, iOS and Android — the `idToken` is all Firebase needs.
192
+ Firebase accepts the One-Tap/native ID token or the web popup access token. Initialize Firebase in your app first.
194
193
 
195
194
  ```ts
196
195
  import { getAuth, GoogleAuthProvider, signInWithCredential } from 'firebase/auth';
197
196
 
198
197
  const result = await auth.signIn(AuthProvider.GOOGLE);
199
- await signInWithCredential(getAuth(), GoogleAuthProvider.credential(result.credential.idToken));
198
+ await signInWithCredential(getAuth(), GoogleAuthProvider.credential(result.credential.idToken ?? null, result.credential.accessToken ?? null));
200
199
  ```
201
200
 
202
201
  ### Verify on your own backend instead
203
202
 
204
203
  ```ts
205
204
  const { credential } = await auth.signIn(AuthProvider.GOOGLE);
205
+ if (!credential.idToken) throw new Error('This backend requires an ID token; use webFlow one-tap');
206
206
  await fetch('/api/session', {
207
207
  method: 'POST',
208
208
  headers: { 'Content-Type': 'application/json' },
@@ -211,17 +211,25 @@ await fetch('/api/session', {
211
211
  ```
212
212
 
213
213
  Always verify the token's signature server-side. This package does not verify it in the browser.
214
+ Use Firebase state for app sessions and protected routes; the package's state describes only the local Google flow.
215
+ Call `await auth.prepare(AuthProvider.GOOGLE)` during browser startup before enabling a sign-in button.
216
+ Call `auth.signOut()` and Firebase `signOut()` when signing out of the app.
214
217
 
215
218
  ### React
216
219
 
220
+ These hooks reflect the local Google session. For Firebase login and protected routes, use the [AI integration guide](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/AI-INTEGRATION-GUIDE.md). Catch event-handler rejections and translate displayed messages through your app’s i18n.
221
+
217
222
  ```tsx
218
223
  import { useAuth, AuthProvider } from 'capacitor-auth-manager/react';
219
224
 
220
225
  function LoginButton() {
221
- const { user, signIn, signOut, isLoading } = useAuth();
226
+ const { user, signIn, signOut, isLoading, error } = useAuth();
222
227
  if (isLoading) return <span>Checking…</span>;
223
- if (user) return <button onClick={() => signOut()}>Sign out {user.email}</button>;
224
- return <button onClick={() => signIn(AuthProvider.GOOGLE)}>Sign in with Google</button>;
228
+ if (user) return <button onClick={() => { void signOut().catch(() => undefined); }}>Sign out {user.email}</button>;
229
+ return <>
230
+ <button onClick={() => { void signIn(AuthProvider.GOOGLE).catch(() => undefined); }}>Sign in with Google</button>
231
+ {error && <p role="alert">{error.message}</p>}
232
+ </>;
225
233
  }
226
234
  ```
227
235
 
@@ -269,7 +277,7 @@ Google provider options:
269
277
  | Option | Platform | What it does |
270
278
  |---|---|---|
271
279
  | `clientId` | web (required), Android fallback | Web OAuth client ID; becomes the id token's `aud`. |
272
- | `serverClientId` | Android (required), iOS | Web OAuth client ID. Credential Manager needs it to return an `idToken`. |
280
+ | `serverClientId` | Android (required), iOS | Web OAuth client ID. Google needs it to return an `idToken`. |
273
281
  | `iosClientId` | iOS | iOS OAuth client ID, if not set as `GIDClientID` in `Info.plist`. |
274
282
  | `scopes` | all | Extra OAuth scopes. Defaults to `openid email profile`. |
275
283
  | `hostedDomain` | all | Restrict sign-in to one Google Workspace domain. |
@@ -277,6 +285,8 @@ Google provider options:
277
285
  | `filterByAuthorizedAccounts` | Android | Show only previously authorised accounts. |
278
286
  | `autoSelectEnabled` | Android | Allow one-tap auto-select for returning users. |
279
287
  | `nonce` | web | Bind the request to an id-token `nonce` claim, which the package validates. |
288
+ | `webFlow` | web | `'auto'` (default: One-Tap, then the OAuth2 popup if One-Tap is not shown) · `'one-tap'` · `'popup'`. Also accepted per call in `signIn({ options })`. |
289
+ | `androidFlow` | Android | `'auto'` (default: GoogleSignIn, then Credential Manager if it fails for any reason other than a cancel) · `'legacy'` · `'credential-manager'` · `'bottom-sheet'` · `'button'`. Also accepted per call. |
280
290
 
281
291
  The same Google options can live in `capacitor.config` under the plugin block instead of in application code.
282
292
  Full reference: [Configuration](https://capacitor-auth-manager-docs.aoneahsan.com/getting-started/configuration).
@@ -319,8 +329,8 @@ interface AuthResult {
319
329
  interface AuthCredential {
320
330
  providerId: string; // 'google.com'
321
331
  signInMethod: string;
322
- idToken?: string; // web, iOS, Android
323
- accessToken?: string; // iOS only for Google
332
+ idToken?: string; // web One-Tap, iOS, Android
333
+ accessToken?: string; // web popup flow, iOS
324
334
  serverAuthCode?: string; // iOS, when serverClientId is set — exchange it on your server
325
335
  }
326
336
 
@@ -343,15 +353,15 @@ interface StorageInterface {
343
353
  <a id="command-line"></a>
344
354
  ## 💻 Command Line&nbsp;[#](#command-line)
345
355
 
346
- An interactive helper that writes the platform OAuth wiring described in [Installation](#installation).
356
+ An interactive Google-only helper for new configuration files; native OAuth wiring remains an app setup step.
347
357
 
348
358
  ```bash
349
- npx capacitor-auth-configure
359
+ yarn exec capacitor-auth-configure --help
360
+ yarn exec capacitor-auth-configure --dry-run
361
+ yarn exec capacitor-auth-configure
350
362
  ```
351
363
 
352
- It asks which platforms you target and which client IDs you hold, then updates `capacitor.config`,
353
- `Info.plist` and the Android configuration accordingly. It takes no flags and prompts for every answer, so
354
- run it in a real terminal rather than in CI.
364
+ It asks for Web/iOS OAuth client IDs and creates `capacitor-auth.config.json` plus `src/auth-init.ts` only when neither exists. It prints native setup instructions and never rewrites native projects. `--dry-run` prints configuration without writing; `--help` is non-interactive. Run configuration in a real terminal; AI agents should follow the packaged integration guide.
355
365
 
356
366
  <a id="advanced-features"></a>
357
367
  ## 🎛️ Advanced Features&nbsp;[#](#advanced-features)
@@ -359,8 +369,22 @@ run it in a real terminal rather than in CI.
359
369
  - **Custom secure storage** — implement `StorageInterface` over Keychain or Keystore and pass it as
360
370
  `storage` instead of the default web storage.
361
371
  - **Nonce validation** — supply `nonce` on web and the package checks the returned id token's claim against it.
362
- - **Google's own button** — when One-Tap is inside its cooldown window, the web provider exposes a
363
- `renderButton(element)` escape hatch that draws Google's official button.
372
+ - **Google's own button** — when One-Tap is inside its cooldown window you can draw Google's official
373
+ button yourself. `renderButton` lives on the web provider class rather than on the `auth` singleton,
374
+ so construct it directly:
375
+
376
+ ```ts
377
+ import { GoogleAuthProviderWeb } from 'capacitor-auth-manager/providers/web';
378
+
379
+ const google = new GoogleAuthProviderWeb({ clientId: import.meta.env.VITE_GOOGLE_WEB_CLIENT_ID });
380
+ // renderButton initializes the provider on demand; options default to { theme: 'outline', size: 'large' }
381
+ await google.renderButton(document.getElementById('google-btn')!);
382
+ // Arm the credential promise before clicking the rendered button:
383
+ const result = await google.signIn({ options: { webFlow: 'one-tap' } });
384
+ ```
385
+
386
+ The button shares the One-Tap credential callback, so a click resolves the same
387
+ `signIn()` promise shape.
364
388
  - **Log level control** — `defaultLogger.setLevel('debug')`, or the `VITE_LOG_LEVEL` / `LOG_LEVEL` build
365
389
  variables, without touching `console` directly.
366
390
  - **Config in `capacitor.config`** — keep the Google block in native config instead of application code.
@@ -371,12 +395,15 @@ run it in a real terminal rather than in CI.
371
395
  | Symptom | Cause | Fix |
372
396
  |---|---|---|
373
397
  | `idToken` is `null` on Android | `serverClientId` missing, or the SHA fingerprint is not registered | Pass your **Web** client ID as `serverClientId` and register the app's SHA-1/SHA-256 on the Android OAuth client |
374
- | `PROVIDER_NOT_ENABLED` | that provider is not enabled in `2.4.x` | Only Google is available today — see [Roadmap](#roadmap) |
375
- | `window is not defined` on the server | the package reads browser storage when imported | Import it only in client code, or behind a dynamic import — see [Limitations](#limitations) |
376
- | `Cannot find module '…/core/auth-manager'` under Node | Node's ESM resolver rejects the published extensionless paths | Import through a bundler; bare Node ESM is unsupported today |
377
- | Nothing happens on web sign-in | One-Tap is inside its cooldown window | Render Google's official button via `renderButton(element)` |
378
- | `Cannot find module '@capacitor/core'` | the peer is not installed | `yarn add @capacitor/core` — it is needed even for a web-only build |
379
- | Native plugin never runs | `npx cap sync` was not run after install | Run it, then rebuild the native project |
398
+ | `PROVIDER_NOT_ENABLED` | that provider is not enabled yet in `3.x` | Only Google is available today — see [Roadmap](#roadmap) |
399
+ | `window is not defined` on the server | you are on `< 3.0.0` | Upgrade — the singleton is lazy and storage is guarded since `3.0.0` |
400
+ | `Cannot find module '…/core/auth-manager'` under Node | you are on `< 3.0.0` | Upgrade — every relative specifier carries its `.js` extension since `3.0.0` |
401
+ | `POPUP_BLOCKED` on web with `webFlow: 'one-tap'` | One-Tap is suppressed (cooldown, FedCM opt-out, third-party cookies) | Use the default `webFlow: 'auto'` (falls back to the popup) or `'popup'`, or draw Google's button with `GoogleAuthProviderWeb.renderButton` — see [Advanced Features](#advanced-features) |
402
+ | `USER_CANCELLED` / `POPUP_CLOSED_BY_USER` | the user closed One-Tap or the popup | Expected — show your own "try again" |
403
+ | Android error names `signing SHA-1=…` | Google has no Android OAuth client for that package + certificate | Register that exact SHA-1 for the app (a Play-installed build reports the Play App Signing key). No new build is needed |
404
+ | Play builds fail with no account picker on `3.0.0` | Credential Manager refused the request (on Android 14+ it depends on the device's credential-provider settings) | Upgrade to `3.1.0`: the default flow uses GoogleSignIn first |
405
+ | `Cannot find module '@capacitor/core'` | the peer is not installed | `yarn add @capacitor/core` — it is a required peer |
406
+ | Native plugin never runs | `yarn cap sync` was not run after install | Run it, then rebuild the native project |
380
407
 
381
408
  <a id="limitations"></a>
382
409
  ## 🚧 Limitations&nbsp;[#](#limitations)
@@ -385,15 +412,14 @@ Stated as plainly as the features, because each one otherwise costs an afternoon
385
412
 
386
413
  - **Google is the only working provider.** Fourteen others exist in the source and throw
387
414
  `PROVIDER_NOT_ENABLED` when called.
388
- - **Bare Node ESM does not resolve.** The published `dist/esm` uses extensionless relative paths, which
389
- bundlers accept and Node's ESM resolver rejects. Vite, webpack, Metro and esbuild are fine; `node --import`
390
- and Node-resolution test runners are not.
391
- - **No server-side rendering.** Importing the package evaluates a singleton that reads browser storage, so it
392
- throws `window is not defined` in Node. Load it in client code or behind a dynamic import.
393
- - **`@capacitor/core` is effectively required**, despite being declared an optional peer — the published
394
- bundle imports it even in a web-only build.
395
- - **No `accessToken` on web or Android.** The web flow is id-token only; Android's Credential Manager returns
396
- an `idToken` and leaves access tokens to the separate Google Authorization API. Only iOS returns both.
415
+ - **`@capacitor/core` is a required peer.** The native bridge imports it even in a web-only build.
416
+ - **Web returns one token per flow.** One-Tap yields an `idToken` and no `accessToken`; the OAuth2 popup
417
+ yields an `accessToken` and no `idToken`. Firebase accepts either
418
+ (`GoogleAuthProvider.credential(idToken ?? null, accessToken)`); an ID-token-only backend must explicitly select One-Tap and reject a missing ID token.
419
+ - **Android returns an `idToken` only.** Access tokens come from the separate Google Authorization API.
420
+ Only iOS returns everything.
421
+ - **Android GoogleSignIn is deprecated by Google** and was removed in `play-services-auth` 22, so the
422
+ package pins 21.x. Do not force `play-services-auth` 22 in your app, or `'auto'` falls through to Credential Manager.
397
423
  - **No id-token verification in the browser.** Signature and claim checks belong to your server, or Firebase.
398
424
  - **Native runtime is not covered by CI.** Both platforms are verified to compile, not to sign in. Test a new
399
425
  version on one real device before rolling it out widely.
@@ -403,15 +429,14 @@ Stated as plainly as the features, because each one otherwise costs an afternoon
403
429
  ## ❓ FAQ&nbsp;[#](#faq)
404
430
 
405
431
  **Do I need Firebase to use this?**
406
- No. It returns a raw `idToken` and never imports `firebase`. Handing that token to Firebase is one supported
432
+ No. It returns Google ID or access tokens and never imports `firebase`. Handing that token to Firebase is one supported
407
433
  option among several.
408
434
 
409
435
  **Can I use it on the web only, without a native build?**
410
- Yes — skip `npx cap sync`. You still need `@capacitor/core` installed, because the published bundle imports it.
436
+ Yes — skip `yarn cap sync`. You still need `@capacitor/core` installed, because the published bundle imports it.
411
437
 
412
- **Why is there no `accessToken` on web?**
413
- The web path uses the Google Identity Services id-token flow, which is what lets it work with no client secret
414
- and no backend. To call Google APIs from the browser, use the GIS token client alongside this package.
438
+ **Which token does web return?**
439
+ One-Tap returns `idToken`; popup returns `accessToken`. The default auto flow can return either. Firebase accepts both fields through `GoogleAuthProvider.credential(idToken ?? null, accessToken ?? null)`.
415
440
 
416
441
  **Which client ID goes where?**
417
442
  The **Web** client ID is used as `clientId` on web and as `serverClientId` on Android. The iOS client ID is
@@ -421,8 +446,7 @@ separate. This catches nearly everyone once.
421
446
  One at a time, each verified on a device first. See [Roadmap](#roadmap).
422
447
 
423
448
  **Is it safe to use in a Next.js or Nuxt app?**
424
- Only in client components, or behind a dynamic import. A top-level server import throws — see
425
- [Limitations](#limitations).
449
+ Server imports are safe. Configure/prepare/sign in in browser code or client components; a server import does not make interactive Google sign-in available on the server.
426
450
 
427
451
  <a id="documentation"></a>
428
452
  ## 📚 Documentation&nbsp;[#](#documentation)
@@ -442,17 +466,16 @@ Only in client components, or behind a dynamic import. A top-level server import
442
466
  <a id="changelog"></a>
443
467
  ## 🔄 Changelog&nbsp;[#](#changelog)
444
468
 
445
- Latest release: **`2.4.4`** — documentation only: the at-a-glance table above reported the previous version, because it is a static duplicate of `package.json`. Full history in the changelog.
469
+ Latest release: **`3.0.0`** — Google-flow hardening, corrected native packaging and shared CommonJS state, updated dependencies, and the packaged AI integration guide. See the changelog for breaking requirements.
446
470
 
447
471
  Full history: [CHANGELOG.md](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/CHANGELOG.md).
448
472
 
449
473
  <a id="roadmap"></a>
450
474
  ## 🗺️ Roadmap&nbsp;[#](#roadmap)
451
475
 
452
- - Resolve the bare-Node ESM and server-side import limitations above.
453
476
  - Re-enable the remaining providers one at a time, each hardened and then verified on a device.
454
477
  - Android access-token and `serverAuthCode` support through the Google Authorization API.
455
- - A `3.0.0` once every provider works again.
478
+ - Additional providers only after their own native and web verification.
456
479
 
457
480
  Dates are deliberately absent; each item ships when it is verified rather than when it is scheduled.
458
481
 
@@ -1,8 +1,8 @@
1
1
  ext {
2
2
  junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
3
- androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.0'
4
- androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.2.1'
5
- androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.6.1'
3
+ androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.8.0'
4
+ androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
5
+ androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
6
6
  }
7
7
 
8
8
  buildscript {
@@ -11,34 +11,32 @@ buildscript {
11
11
  mavenCentral()
12
12
  }
13
13
  dependencies {
14
- classpath 'com.android.tools.build:gradle:8.5.2'
14
+ classpath 'com.android.tools.build:gradle:8.13.0'
15
15
  }
16
16
  }
17
17
 
18
18
  apply plugin: 'com.android.library'
19
19
 
20
20
  android {
21
- namespace "com.aoneahsan.capacitor_auth_manager"
22
- compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 35
21
+ namespace = "com.aoneahsan.capacitor_auth_manager"
22
+ compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
23
23
  defaultConfig {
24
- minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
25
- targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 35
26
- versionCode 1
27
- versionName "1.0"
28
- testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
24
+ minSdk = project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
25
+ targetSdk = project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
26
+ versionCode = 1
27
+ versionName = "1.0"
28
+ consumerProguardFiles 'consumer-rules.pro'
29
+ testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
29
30
  }
30
31
  buildTypes {
31
32
  release {
32
- minifyEnabled false
33
+ minifyEnabled = false
33
34
  proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
34
35
  }
35
36
  }
36
- lintOptions {
37
- abortOnError false
38
- }
39
37
  compileOptions {
40
- sourceCompatibility JavaVersion.VERSION_17
41
- targetCompatibility JavaVersion.VERSION_17
38
+ sourceCompatibility = JavaVersion.VERSION_21
39
+ targetCompatibility = JavaVersion.VERSION_21
42
40
  }
43
41
  }
44
42
 
@@ -52,22 +50,22 @@ dependencies {
52
50
  implementation project(':capacitor-android')
53
51
  implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
54
52
 
55
- // Google Sign-In (legacy play-services-auth kept for transitive/other use; the Google provider
56
- // now uses Credential Manager + Google Identity below, not the deprecated GoogleSignIn API)
57
- implementation 'com.google.android.gms:play-services-auth:21.3.0'
58
-
59
53
  // Credential Manager (modern Google sign-in — replaces deprecated GoogleSignIn/startActivityForResult)
60
- implementation 'androidx.credentials:credentials:1.3.0'
61
- implementation 'androidx.credentials:credentials-play-services-auth:1.3.0'
54
+ implementation 'androidx.credentials:credentials:1.6.0'
55
+ implementation 'androidx.credentials:credentials-play-services-auth:1.6.0'
62
56
  implementation 'com.google.android.libraries.identity.googleid:googleid:1.1.1'
63
57
 
58
+ // Legacy GoogleSignIn: the automatic fallback when Credential Manager refuses a request (the API
59
+ // @codetrix-studio/capacitor-google-auth used). Pinned to 21.x: play-services-auth 22.0.0 REMOVED
60
+ // com.google.android.gms.auth.api.signin.* (verified 2026-10-29 by listing both AARs' classes).
61
+ // Re-check when Google ships a 22.x replacement for silent ID-token sign-in, then drop the fallback.
62
+ implementation 'com.google.android.gms:play-services-auth:21.6.0'
63
+
64
64
  // NOTE: Google-first build (2.4.x). The Facebook SDK + Microsoft MSAL dependencies were removed so
65
65
  // this plugin no longer pulls heavy auth SDKs into every consumer app. Their native providers live in
66
66
  // android/disabled-native-providers/ (not compiled, not shipped). Re-add a dependency here when its
67
67
  // provider is re-enabled.
68
68
 
69
- // Security (AuthStorage uses EncryptedSharedPreferences)
70
- implementation 'androidx.security:security-crypto:1.1.0-alpha06'
71
69
 
72
70
  testImplementation "junit:junit:$junitVersion"
73
71
  androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
@@ -0,0 +1,14 @@
1
+ # Shipped into every consuming app's R8 run (consumerProguardFiles). android/proguard-rules.pro only
2
+ # applies to this library's own unminified build, so any rule a release app needs must live here.
3
+
4
+ # Capacitor discovers plugin entry points and invokes methods by reflection.
5
+ -keep @com.getcapacitor.annotation.CapacitorPlugin class * { *; }
6
+ -keep class com.aoneahsan.capacitor_auth_manager.** { *; }
7
+
8
+ # Credential Manager finds its Play Services provider by class name from the merged manifest.
9
+ -keep class androidx.credentials.playservices.** { *; }
10
+ -keep class com.google.android.libraries.identity.googleid.** { *; }
11
+
12
+ # Legacy GoogleSignIn fallback (play-services-auth 21.x).
13
+ -keep class com.google.android.gms.auth.api.signin.** { *; }
14
+ -keep class com.google.android.gms.common.api.ApiException { *; }
@@ -1,38 +1,13 @@
1
- # Add project specific ProGuard rules here.
2
- # You can control the set of applied configuration files using the
3
- # proguardFiles setting in build.gradle.
4
- #
5
- # For more details, see
6
- # http://developer.android.com/guide/developing/tools/proguard.html
1
+ # ProGuard / R8 rules for capacitor-auth-manager (Google-first build).
7
2
 
8
- # If your project uses WebView with JS, uncomment the following
9
- # and specify the fully qualified class name to the JavaScript interface
10
- # class:
11
- #-keepclassmembers class fqcn.of.javascript.interface.for.webview {
12
- # public *;
13
- #}
14
-
15
- # Uncomment this to preserve the line number information for
16
- # debugging stack traces.
17
- #-keepattributes SourceFile,LineNumberTable
18
-
19
- # If you keep the line number information, uncomment this to
20
- # hide the original source file name.
21
- #-renamesourcefileattribute SourceFile
22
-
23
- # Google Sign-In
3
+ # Credential Manager + Google Identity (Sign in with Google)
4
+ -keep class androidx.credentials.** { *; }
5
+ -keep class com.google.android.libraries.identity.googleid.** { *; }
24
6
  -keep class com.google.android.gms.auth.** { *; }
25
7
  -keep class com.google.android.gms.common.** { *; }
26
8
 
27
- # Facebook SDK
28
- -keep class com.facebook.** { *; }
29
-
30
- # Microsoft Authentication Library
31
- -keep class com.microsoft.identity.** { *; }
32
- -keep class com.microsoft.device.** { *; }
33
-
34
9
  # Capacitor
35
10
  -keep class com.getcapacitor.** { *; }
36
11
 
37
12
  # Plugin classes
38
- -keep class com.aoneahsan.capacitor_auth_manager.** { *; }
13
+ -keep class com.aoneahsan.capacitor_auth_manager.** { *; }
@@ -1,11 +1,6 @@
1
1
  <manifest xmlns:android="http://schemas.android.com/apk/res/android">
2
- <!-- Required for OAuth flows -->
2
+ <!-- Google sign-in (Credential Manager) only needs network access. No SMS / biometric permissions
3
+ are declared: those providers are disabled in the Google-first build, and READ_SMS / RECEIVE_SMS
4
+ are Play-restricted permissions that get consumer apps rejected. -->
3
5
  <uses-permission android:name="android.permission.INTERNET" />
4
-
5
- <!-- Required for biometric authentication -->
6
- <uses-permission android:name="android.permission.USE_BIOMETRIC" />
7
-
8
- <!-- Required for SMS authentication -->
9
- <uses-permission android:name="android.permission.RECEIVE_SMS" />
10
- <uses-permission android:name="android.permission.READ_SMS" />
11
- </manifest>
6
+ </manifest>
@@ -0,0 +1,26 @@
1
+ package com.aoneahsan.capacitor_auth_manager;
2
+
3
+ import android.content.Intent;
4
+
5
+ /**
6
+ * Starts an Activity for a result on behalf of a provider and hands the result back.
7
+ *
8
+ * <p>Implemented by {@link CapacitorAuthManagerPlugin} through Capacitor's
9
+ * {@code startActivityForResult(call, intent, callbackName)} + {@code @ActivityCallback}, which is
10
+ * the piece the 2.x GoogleSignIn flow lacked: it called {@code startActivityForResult} on the
11
+ * Activity directly, the result never reached the plugin, and sign-in hung.</p>
12
+ */
13
+ public interface ActivityLauncher {
14
+
15
+ /** Receives the finished Activity's result code and data (data may be {@code null}). */
16
+ interface ResultHandler {
17
+ void onResult(int resultCode, Intent data);
18
+ }
19
+
20
+ /**
21
+ * Launch {@code intent} for the plugin call currently in flight.
22
+ *
23
+ * @return {@code false} when no plugin call is in flight to attach the result to.
24
+ */
25
+ boolean launch(Intent intent, ResultHandler handler);
26
+ }
@@ -0,0 +1,32 @@
1
+ package com.aoneahsan.capacitor_auth_manager;
2
+
3
+ /**
4
+ * The subset of {@code AuthErrorCode} (see {@code src/definitions.ts}) that the Android layer can
5
+ * raise. The string values MUST stay identical to the TypeScript enum: they travel to JS as the
6
+ * Capacitor error code, and {@code AuthError.fromError} promotes a recognised value straight into
7
+ * {@code AuthError.code}. An unrecognised string silently degrades to {@code INTERNAL_ERROR}, so
8
+ * never invent a code here that the enum does not define.
9
+ */
10
+ public final class AuthErrorCodes {
11
+
12
+ public static final String USER_CANCELLED = "auth/user-cancelled";
13
+ public static final String SIGN_IN_FAILED = "auth/sign-in-failed";
14
+ public static final String SIGN_OUT_FAILED = "auth/sign-out-failed";
15
+ public static final String NETWORK_ERROR = "auth/network-error";
16
+ public static final String INVALID_CREDENTIALS = "auth/invalid-credentials";
17
+ public static final String INTERNAL_ERROR = "auth/internal-error";
18
+ public static final String PROVIDER_NOT_INITIALIZED = "auth/provider-not-initialized";
19
+ public static final String PROVIDER_NOT_ENABLED = "auth/provider-not-enabled";
20
+ public static final String PROVIDER_INIT_FAILED = "auth/provider-init-failed";
21
+ public static final String MISSING_CONFIGURATION = "auth/missing-configuration";
22
+ public static final String CREDENTIALS_REQUIRED = "auth/credentials-required";
23
+ public static final String EMAIL_REQUIRED = "auth/email-required";
24
+ public static final String PHONE_REQUIRED = "auth/phone-required";
25
+ public static final String NO_AUTH_SESSION = "auth/no-auth-session";
26
+ public static final String TOKEN_REFRESH_FAILED = "auth/token-refresh-failed";
27
+ public static final String OPERATION_NOT_ALLOWED = "auth/operation-not-allowed";
28
+ public static final String UNSUPPORTED_PROVIDER = "auth/unsupported-provider";
29
+
30
+ private AuthErrorCodes() {
31
+ }
32
+ }