capacitor-auth-manager 2.4.4 → 3.0.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 (80) hide show
  1. package/AI-INTEGRATION-GUIDE.md +174 -0
  2. package/CHANGELOG.md +119 -0
  3. package/CapacitorAuthManager.podspec +3 -3
  4. package/README.md +91 -72
  5. package/android/build.gradle +17 -25
  6. package/android/consumer-rules.pro +2 -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/AuthErrorCodes.java +32 -0
  10. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/AuthException.java +34 -0
  11. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/AuthStorage.java +46 -25
  12. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/CapacitorAuthManager.java +54 -38
  13. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/CapacitorAuthManagerPlugin.java +77 -54
  14. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/GoogleAuthProvider.java +171 -41
  15. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/ProviderFactory.java +5 -0
  16. package/dist/angular.cjs.js +421 -3376
  17. package/dist/core.cjs.js +589 -149
  18. package/dist/esm/angular/auth.guard.d.ts +1 -1
  19. package/dist/esm/angular/auth.module.d.ts +1 -1
  20. package/dist/esm/angular/auth.module.js +1 -1
  21. package/dist/esm/angular/auth.service.d.ts +2 -2
  22. package/dist/esm/angular/auth.service.js +1 -1
  23. package/dist/esm/angular/index.d.ts +4 -4
  24. package/dist/esm/angular/index.js +4 -4
  25. package/dist/esm/capacitor-plugin.d.ts +2 -3
  26. package/dist/esm/capacitor-plugin.js +14 -4
  27. package/dist/esm/core/auth-manager.d.ts +20 -2
  28. package/dist/esm/core/auth-manager.js +68 -12
  29. package/dist/esm/core/index.d.ts +5 -4
  30. package/dist/esm/core/index.js +5 -4
  31. package/dist/esm/core/provider-manifests.d.ts +1 -1
  32. package/dist/esm/core/provider-manifests.js +12 -13
  33. package/dist/esm/core/provider-registry.d.ts +8 -5
  34. package/dist/esm/core/provider-registry.js +41 -10
  35. package/dist/esm/core/types.d.ts +2 -2
  36. package/dist/esm/definitions.d.ts +26 -0
  37. package/dist/esm/index.d.ts +12 -12
  38. package/dist/esm/index.js +7 -7
  39. package/dist/esm/package.json +1 -0
  40. package/dist/esm/providers/base-provider.d.ts +7 -8
  41. package/dist/esm/providers/base-provider.js +7 -8
  42. package/dist/esm/providers/native/google-native-provider.d.ts +13 -2
  43. package/dist/esm/providers/native/google-native-provider.js +50 -6
  44. package/dist/esm/providers/oauth-provider.d.ts +2 -2
  45. package/dist/esm/providers/oauth-provider.js +3 -3
  46. package/dist/esm/providers/provider-factory.d.ts +5 -5
  47. package/dist/esm/providers/provider-factory.js +2 -2
  48. package/dist/esm/providers/web/google-provider.d.ts +74 -18
  49. package/dist/esm/providers/web/google-provider.js +391 -117
  50. package/dist/esm/providers/web/index.d.ts +1 -1
  51. package/dist/esm/providers/web/index.js +1 -1
  52. package/dist/esm/react/hooks.d.ts +2 -2
  53. package/dist/esm/react/hooks.js +2 -2
  54. package/dist/esm/react/index.d.ts +3 -3
  55. package/dist/esm/react/index.js +3 -3
  56. package/dist/esm/react/types.d.ts +1 -1
  57. package/dist/esm/utils/auth-error.d.ts +1 -1
  58. package/dist/esm/utils/auth-error.js +1 -1
  59. package/dist/esm/utils/event-emitter.d.ts +1 -1
  60. package/dist/esm/utils/event-emitter.js +1 -1
  61. package/dist/esm/utils/pending-verification-store.js +1 -1
  62. package/dist/esm/utils/storage.d.ts +2 -2
  63. package/dist/esm/utils/storage.js +31 -7
  64. package/dist/esm/vue/composables.d.ts +2 -2
  65. package/dist/esm/vue/composables.js +1 -1
  66. package/dist/esm/vue/index.d.ts +2 -2
  67. package/dist/esm/vue/index.js +2 -2
  68. package/dist/esm/web.d.ts +1 -1
  69. package/dist/esm/web.js +6 -6
  70. package/dist/plugin.cjs.js +291 -2771
  71. package/dist/plugin.js +585 -147
  72. package/dist/providers-web.cjs.js +1317 -0
  73. package/dist/react.cjs.js +310 -3265
  74. package/dist/vue.cjs.js +266 -3221
  75. package/ios/Plugin/AuthStorage.swift +3 -1
  76. package/ios/Plugin/GoogleAuthProvider.swift +7 -4
  77. package/ios/Plugin/Models.swift +28 -0
  78. package/ios/Plugin/Plugin.swift +64 -40
  79. package/package.json +55 -33
  80. 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)
@@ -78,7 +77,7 @@ handling.
78
77
 
79
78
  This package collapses that into `auth.signIn(AuthProvider.GOOGLE)`. It routes to Google Identity Services on
80
79
  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,
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.
99
+ - **Firebase-agnostic** — returns Google credentials, and pulls no `firebase` package into your tree.
102
100
  - **Modern native SDKs** — Android Credential Manager and iOS GoogleSignIn rather than deprecated APIs.
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 | ✅ | Credential Manager bottom sheet, falling back to the Sign in with Google button flow (`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,18 @@ 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
152
+ - **Android** — register the app's SHA-1 and SHA-256 fingerprints against an
156
153
  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.
154
+ return an `idToken` without 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
155
  - **iOS** — add `GIDClientID` to `Info.plist` (or pass `iosClientId`), and add the reversed client ID as a URL
159
156
  scheme under `CFBundleURLTypes`.
160
157
 
161
- The bundled [command-line helper](#command-line) can write most of this for you.
158
+ 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
159
 
163
160
  <a id="quick-start"></a>
164
161
  ## 🚀 Quick Start&nbsp;[#](#quick-start)
@@ -180,7 +177,8 @@ auth.configure({
180
177
  });
181
178
 
182
179
  const result = await auth.signIn(AuthProvider.GOOGLE);
183
- console.log(result.user.email, result.credential.idToken);
180
+ // Hand credential.idToken OR credential.accessToken to Firebase; see Usage.
181
+ // Never log credential tokens.
184
182
  ```
185
183
 
186
184
  `AuthProvider.GOOGLE` is the typo-safe form of the string `'google'`; either works.
@@ -190,19 +188,20 @@ console.log(result.user.email, result.credential.idToken);
190
188
 
191
189
  ### Hand the credential to Firebase
192
190
 
193
- Identical on web, iOS and Android — the `idToken` is all Firebase needs.
191
+ Firebase accepts the One-Tap/native ID token or the web popup access token. Initialize Firebase in your app first.
194
192
 
195
193
  ```ts
196
194
  import { getAuth, GoogleAuthProvider, signInWithCredential } from 'firebase/auth';
197
195
 
198
196
  const result = await auth.signIn(AuthProvider.GOOGLE);
199
- await signInWithCredential(getAuth(), GoogleAuthProvider.credential(result.credential.idToken));
197
+ await signInWithCredential(getAuth(), GoogleAuthProvider.credential(result.credential.idToken ?? null, result.credential.accessToken ?? null));
200
198
  ```
201
199
 
202
200
  ### Verify on your own backend instead
203
201
 
204
202
  ```ts
205
203
  const { credential } = await auth.signIn(AuthProvider.GOOGLE);
204
+ if (!credential.idToken) throw new Error('This backend requires an ID token; use webFlow one-tap');
206
205
  await fetch('/api/session', {
207
206
  method: 'POST',
208
207
  headers: { 'Content-Type': 'application/json' },
@@ -211,17 +210,25 @@ await fetch('/api/session', {
211
210
  ```
212
211
 
213
212
  Always verify the token's signature server-side. This package does not verify it in the browser.
213
+ Use Firebase state for app sessions and protected routes; the package's state describes only the local Google flow.
214
+ Call `await auth.prepare(AuthProvider.GOOGLE)` during browser startup before enabling a sign-in button.
215
+ Call `auth.signOut()` and Firebase `signOut()` when signing out of the app.
214
216
 
215
217
  ### React
216
218
 
219
+ 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.
220
+
217
221
  ```tsx
218
222
  import { useAuth, AuthProvider } from 'capacitor-auth-manager/react';
219
223
 
220
224
  function LoginButton() {
221
- const { user, signIn, signOut, isLoading } = useAuth();
225
+ const { user, signIn, signOut, isLoading, error } = useAuth();
222
226
  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>;
227
+ if (user) return <button onClick={() => { void signOut().catch(() => undefined); }}>Sign out {user.email}</button>;
228
+ return <>
229
+ <button onClick={() => { void signIn(AuthProvider.GOOGLE).catch(() => undefined); }}>Sign in with Google</button>
230
+ {error && <p role="alert">{error.message}</p>}
231
+ </>;
225
232
  }
226
233
  ```
227
234
 
@@ -277,6 +284,8 @@ Google provider options:
277
284
  | `filterByAuthorizedAccounts` | Android | Show only previously authorised accounts. |
278
285
  | `autoSelectEnabled` | Android | Allow one-tap auto-select for returning users. |
279
286
  | `nonce` | web | Bind the request to an id-token `nonce` claim, which the package validates. |
287
+ | `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 })`. |
288
+ | `androidFlow` | Android | `'auto'` (default: bottom sheet, then the Sign in with Google button flow if no account is offered) · `'bottom-sheet'` · `'button'`. Also accepted per call. |
280
289
 
281
290
  The same Google options can live in `capacitor.config` under the plugin block instead of in application code.
282
291
  Full reference: [Configuration](https://capacitor-auth-manager-docs.aoneahsan.com/getting-started/configuration).
@@ -319,8 +328,8 @@ interface AuthResult {
319
328
  interface AuthCredential {
320
329
  providerId: string; // 'google.com'
321
330
  signInMethod: string;
322
- idToken?: string; // web, iOS, Android
323
- accessToken?: string; // iOS only for Google
331
+ idToken?: string; // web One-Tap, iOS, Android
332
+ accessToken?: string; // web popup flow, iOS
324
333
  serverAuthCode?: string; // iOS, when serverClientId is set — exchange it on your server
325
334
  }
326
335
 
@@ -343,15 +352,15 @@ interface StorageInterface {
343
352
  <a id="command-line"></a>
344
353
  ## 💻 Command Line&nbsp;[#](#command-line)
345
354
 
346
- An interactive helper that writes the platform OAuth wiring described in [Installation](#installation).
355
+ An interactive Google-only helper for new configuration files; native OAuth wiring remains an app setup step.
347
356
 
348
357
  ```bash
349
- npx capacitor-auth-configure
358
+ yarn exec capacitor-auth-configure --help
359
+ yarn exec capacitor-auth-configure --dry-run
360
+ yarn exec capacitor-auth-configure
350
361
  ```
351
362
 
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.
363
+ 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
364
 
356
365
  <a id="advanced-features"></a>
357
366
  ## 🎛️ Advanced Features&nbsp;[#](#advanced-features)
@@ -359,8 +368,22 @@ run it in a real terminal rather than in CI.
359
368
  - **Custom secure storage** — implement `StorageInterface` over Keychain or Keystore and pass it as
360
369
  `storage` instead of the default web storage.
361
370
  - **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.
371
+ - **Google's own button** — when One-Tap is inside its cooldown window you can draw Google's official
372
+ button yourself. `renderButton` lives on the web provider class rather than on the `auth` singleton,
373
+ so construct it directly:
374
+
375
+ ```ts
376
+ import { GoogleAuthProviderWeb } from 'capacitor-auth-manager/providers/web';
377
+
378
+ const google = new GoogleAuthProviderWeb({ clientId: import.meta.env.VITE_GOOGLE_WEB_CLIENT_ID });
379
+ // renderButton initializes the provider on demand; options default to { theme: 'outline', size: 'large' }
380
+ await google.renderButton(document.getElementById('google-btn')!);
381
+ // Arm the credential promise before clicking the rendered button:
382
+ const result = await google.signIn({ options: { webFlow: 'one-tap' } });
383
+ ```
384
+
385
+ The button shares the One-Tap credential callback, so a click resolves the same
386
+ `signIn()` promise shape.
364
387
  - **Log level control** — `defaultLogger.setLevel('debug')`, or the `VITE_LOG_LEVEL` / `LOG_LEVEL` build
365
388
  variables, without touching `console` directly.
366
389
  - **Config in `capacitor.config`** — keep the Google block in native config instead of application code.
@@ -371,12 +394,14 @@ run it in a real terminal rather than in CI.
371
394
  | Symptom | Cause | Fix |
372
395
  |---|---|---|
373
396
  | `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 |
397
+ | `PROVIDER_NOT_ENABLED` | that provider is not enabled yet in `3.x` | Only Google is available today — see [Roadmap](#roadmap) |
398
+ | `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` |
399
+ | `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` |
400
+ | `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) |
401
+ | `USER_CANCELLED` / `POPUP_CLOSED_BY_USER` | the user closed One-Tap or the popup | Expected — show your own "try again" |
402
+ | No Google account offered on Android | the bottom sheet has no authorized account | The default `androidFlow: 'auto'` falls back to the Sign in with Google button flow, which can add an account |
403
+ | `Cannot find module '@capacitor/core'` | the peer is not installed | `yarn add @capacitor/core` — it is a required peer |
404
+ | Native plugin never runs | `yarn cap sync` was not run after install | Run it, then rebuild the native project |
380
405
 
381
406
  <a id="limitations"></a>
382
407
  ## 🚧 Limitations&nbsp;[#](#limitations)
@@ -385,15 +410,12 @@ Stated as plainly as the features, because each one otherwise costs an afternoon
385
410
 
386
411
  - **Google is the only working provider.** Fourteen others exist in the source and throw
387
412
  `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.
413
+ - **`@capacitor/core` is a required peer.** The native bridge imports it even in a web-only build.
414
+ - **Web returns one token per flow.** One-Tap yields an `idToken` and no `accessToken`; the OAuth2 popup
415
+ yields an `accessToken` and no `idToken`. Firebase accepts either
416
+ (`GoogleAuthProvider.credential(idToken ?? null, accessToken)`); an ID-token-only backend must explicitly select One-Tap and reject a missing ID token.
417
+ - **Android returns an `idToken` only.** Access tokens and `serverAuthCode` come from the separate Google
418
+ Authorization API, not from Credential Manager sign-in. Only iOS returns everything.
397
419
  - **No id-token verification in the browser.** Signature and claim checks belong to your server, or Firebase.
398
420
  - **Native runtime is not covered by CI.** Both platforms are verified to compile, not to sign in. Test a new
399
421
  version on one real device before rolling it out widely.
@@ -403,15 +425,14 @@ Stated as plainly as the features, because each one otherwise costs an afternoon
403
425
  ## ❓ FAQ&nbsp;[#](#faq)
404
426
 
405
427
  **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
428
+ No. It returns Google ID or access tokens and never imports `firebase`. Handing that token to Firebase is one supported
407
429
  option among several.
408
430
 
409
431
  **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.
432
+ Yes — skip `yarn cap sync`. You still need `@capacitor/core` installed, because the published bundle imports it.
411
433
 
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.
434
+ **Which token does web return?**
435
+ 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
436
 
416
437
  **Which client ID goes where?**
417
438
  The **Web** client ID is used as `clientId` on web and as `serverClientId` on Android. The iOS client ID is
@@ -421,8 +442,7 @@ separate. This catches nearly everyone once.
421
442
  One at a time, each verified on a device first. See [Roadmap](#roadmap).
422
443
 
423
444
  **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).
445
+ 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
446
 
427
447
  <a id="documentation"></a>
428
448
  ## 📚 Documentation&nbsp;[#](#documentation)
@@ -442,17 +462,16 @@ Only in client components, or behind a dynamic import. A top-level server import
442
462
  <a id="changelog"></a>
443
463
  ## 🔄 Changelog&nbsp;[#](#changelog)
444
464
 
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.
465
+ 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
466
 
447
467
  Full history: [CHANGELOG.md](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/CHANGELOG.md).
448
468
 
449
469
  <a id="roadmap"></a>
450
470
  ## 🗺️ Roadmap&nbsp;[#](#roadmap)
451
471
 
452
- - Resolve the bare-Node ESM and server-side import limitations above.
453
472
  - Re-enable the remaining providers one at a time, each hardened and then verified on a device.
454
473
  - Android access-token and `serverAuthCode` support through the Google Authorization API.
455
- - A `3.0.0` once every provider works again.
474
+ - Additional providers only after their own native and web verification.
456
475
 
457
476
  Dates are deliberately absent; each item ships when it is verified rather than when it is scheduled.
458
477
 
@@ -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,13 +50,9 @@ 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
 
64
58
  // NOTE: Google-first build (2.4.x). The Facebook SDK + Microsoft MSAL dependencies were removed so
@@ -66,8 +60,6 @@ dependencies {
66
60
  // android/disabled-native-providers/ (not compiled, not shipped). Re-add a dependency here when its
67
61
  // provider is re-enabled.
68
62
 
69
- // Security (AuthStorage uses EncryptedSharedPreferences)
70
- implementation 'androidx.security:security-crypto:1.1.0-alpha06'
71
63
 
72
64
  testImplementation "junit:junit:$junitVersion"
73
65
  androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
@@ -0,0 +1,2 @@
1
+ # Capacitor discovers plugin entry points and invokes methods by reflection.
2
+ -keep @com.getcapacitor.annotation.CapacitorPlugin class * { *; }
@@ -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,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
+ }
@@ -0,0 +1,34 @@
1
+ package com.aoneahsan.capacitor_auth_manager;
2
+
3
+ /**
4
+ * An {@link Exception} that carries a stable {@link AuthErrorCodes} value.
5
+ *
6
+ * <p>Before this existed every native failure crossed the bridge as a bare message and the JS side
7
+ * guessed the code by substring-matching ({@code AuthError.fromError}), so anything that did not
8
+ * literally contain "cancelled"/"network"/"timeout" surfaced as {@code auth/internal-error}. The
9
+ * plugin now rejects with {@code call.reject(message, code)}; Capacitor puts that code on the
10
+ * rejected error and {@code AuthError.fromError} adopts it verbatim.
11
+ */
12
+ public class AuthException extends Exception {
13
+
14
+ private final String code;
15
+
16
+ public AuthException(String code, String message) {
17
+ super(message);
18
+ this.code = code;
19
+ }
20
+
21
+ public AuthException(String code, String message, Throwable cause) {
22
+ super(message, cause);
23
+ this.code = code;
24
+ }
25
+
26
+ public String getCode() {
27
+ return code;
28
+ }
29
+
30
+ /** The code carried by {@code error}, or {@code fallback} for a plain exception. */
31
+ public static String codeOf(Throwable error, String fallback) {
32
+ return error instanceof AuthException ? ((AuthException) error).getCode() : fallback;
33
+ }
34
+ }