capacitor-auth-manager 2.4.1 → 2.4.3

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.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,63 @@ All notable changes to `capacitor-auth-manager` are documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [2.4.3] — 2026-07-25
9
+
10
+ **Documentation and metadata only — no runtime changes.** Brings the package to the house README
11
+ standard and, importantly, **documents two High-severity defects that have been shipping since before
12
+ this release**. They are stated plainly in the README's Limitations section rather than left for a
13
+ consumer to discover at runtime:
14
+
15
+ - **The published ESM build does not resolve under bare Node.** `moduleResolution: "bundler"` emits 133
16
+ extensionless relative specifiers across 33 files. Bundlers resolve them; Node's ESM resolver does
17
+ not, so SSR, Node-resolution test runners and `node --import` all fail.
18
+ - **Importing the package throws `window is not defined`.** A module-scope singleton in
19
+ `src/core/auth-manager.ts` constructs a `WebStorage` that reads `window.localStorage` unguarded. This
20
+ also makes `sideEffects: false` untrue.
21
+
22
+ Neither is fixed here — both need a code change and a version bump beyond a documentation patch. Every
23
+ conventional gate passes while they ship: typecheck, lint, build, the exports-map walk and even an
24
+ esbuild bundle are all green. Only installing the tarball and importing it under bare Node catches them.
25
+ Tracked in `docs/REPORTED-ISSUES.md` as ISSUE-001 and ISSUE-002.
26
+
27
+ ### Changed
28
+
29
+ - README rewritten to the canonical package pattern; `Readme.md` renamed to `README.md`.
30
+ - `homepage` moved off the npmjs.com page onto the documentation site.
31
+ - `funding` added; `keywords` reduced from 24 to 9 honest terms.
32
+ - `files` allowlist corrected to include the `bin` script explicitly; inert `.npmignore` removed.
33
+
34
+ ## [2.4.2] — 2026-06-30
35
+
36
+ **Native now actually compiles — Google-only native (verified).** `2.4.1` shipped native sources that
37
+ had never been built in a real app; an end-to-end integration compile (a throwaway Capacitor app, real
38
+ Android `gradle assembleDebug` + iOS `pod lib lint`) surfaced and fixed the breakage. **Use `2.4.2`, not
39
+ `2.4.1`** (which is deprecated).
40
+
41
+ ### Changed
42
+
43
+ - **Native is Google-only.** Removed the Facebook (`FBSDKLoginKit` / `facebook-login`) and Microsoft
44
+ (`MSAL`) native dependencies so the plugin no longer drags heavy auth SDKs into every consumer app. The
45
+ disabled providers' native code moved to `android/disabled-native-providers/` and
46
+ `ios/disabled-native-providers/` (kept for re-enablement; not compiled, not shipped). `ProviderFactory`
47
+ (Android) and `createProvider` (iOS) are trimmed to Google; the JS layer already reports
48
+ `PROVIDER_NOT_ENABLED` for the rest.
49
+ - iOS podspec slimmed to `Capacitor` + `GoogleSignIn ~> 7.1`; removed the dangling
50
+ `SWIFT_OBJC_BRIDGING_HEADER` (the file never existed; GoogleSignIn 7 is pure Swift).
51
+
52
+ ### Fixed (native compile errors that blocked every consumer build)
53
+
54
+ - **Android:** `com.facebook.android:facebook-login:17.0.3` was unresolvable → build failed before any
55
+ Java compiled. `GoogleAuthProvider` caught `GoogleIdTokenParsingException`, a checked exception
56
+ `GoogleIdTokenCredential.createFrom` doesn't declare in googleid 1.1.1. `getIdToken` called the throwing
57
+ `JSObject.getBoolean(...)` unguarded → unreported `JSONException`. Verified with `gradle :…:assembleDebug`.
58
+ - **iOS:** `CapacitorAuthManager` passed `AuthPersistence` / `AuthProvider` enums where the storage API
59
+ expects `String` (`.rawValue`). `Plugin.removeAllListeners(_:)` now `override public`s Capacitor 8's
60
+ built-in and delegates to `super`. Verified with `pod lib lint`.
61
+
62
+ > Both platforms now build in a clean Capacitor 8 app. Still verify Google sign-in on a real device before
63
+ > the fleet rollout (a successful compile is not a runtime test).
64
+
8
65
  ## [2.4.1] — 2026-06-30
9
66
 
10
67
  **Google-first production refocus.** This release turns the package into a working, **Firebase-agnostic
@@ -146,4 +203,10 @@ as each is hardened and verified on device; until then they report a clear `PROV
146
203
 
147
204
  - `npm run build` succeeds; `npm run test:run` — 79 tests pass; `npm run lint` — 0 errors.
148
205
 
149
- [2.2.0]: https://github.com/aoneahsan/capacitor-auth-manager/releases/tag/v2.2.0
206
+ ## Earlier releases
207
+
208
+ `0.0.1`, `0.0.2`, `1.0.0`, `1.1.0` and `2.1.0` were published before this changelog was started, and no
209
+ per-version record of them was kept. They are listed here so the gap is visible rather than silent; the
210
+ published artefacts remain on
211
+ [npm](https://www.npmjs.com/package/capacitor-auth-manager?activeTab=versions). Treat `2.2.0` as the first
212
+ release with a documented history.
@@ -14,23 +14,15 @@ Pod::Spec.new do |s|
14
14
  s.ios.deployment_target = '14.0'
15
15
  s.swift_version = '5.9'
16
16
  s.dependency 'Capacitor'
17
-
18
- # Auth Provider Dependencies
17
+
18
+ # Google Sign-In — the only enabled provider as of 2.4.x (Firebase-agnostic). Pure-Swift SDK,
19
+ # no Objective-C bridging header required.
19
20
  s.dependency 'GoogleSignIn', '~> 7.1'
20
- s.dependency 'FBSDKLoginKit', '~> 17.0'
21
-
22
- # Apple Sign In is built into iOS
23
-
24
- # Microsoft Authentication Library
25
- s.dependency 'MSAL', '~> 1.5'
26
-
27
- # Firebase Auth (optional, can be added when needed)
28
- # s.dependency 'Firebase/Auth'
29
-
21
+
22
+ # NOTE: Google-first build. The Facebook (FBSDKLoginKit) and Microsoft (MSAL) pod dependencies were
23
+ # removed so this plugin no longer pulls heavy auth SDKs into every consumer app. Those providers'
24
+ # Swift lives in ios/disabled-native-providers/ (not compiled, not shipped). Re-add a dependency here
25
+ # when its provider is re-enabled.
26
+
30
27
  s.static_framework = true
31
-
32
- # Required for Google Sign In
33
- s.pod_target_xcconfig = {
34
- 'SWIFT_OBJC_BRIDGING_HEADER' => '$(PODS_TARGET_SRCROOT)/ios/Plugin/Plugin-Bridging-Header.h'
35
- }
36
28
  end
package/README.md ADDED
@@ -0,0 +1,505 @@
1
+ <div align="center">
2
+
3
+ <img src="https://capacitor-auth-manager-docs.aoneahsan.com/img/logo.svg" alt="Capacitor Auth Manager logo" width="120" />
4
+
5
+ <h1>capacitor-auth-manager</h1>
6
+
7
+ <p><strong>Firebase-agnostic Google sign-in for Capacitor and the web — one call, same result on every platform.</strong></p>
8
+
9
+ [![npm version](https://img.shields.io/npm/v/capacitor-auth-manager.svg)](https://www.npmjs.com/package/capacitor-auth-manager)
10
+ [![downloads](https://img.shields.io/npm/dm/capacitor-auth-manager.svg)](https://www.npmjs.com/package/capacitor-auth-manager)
11
+ [![license](https://img.shields.io/npm/l/capacitor-auth-manager.svg)](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/LICENSE)
12
+ [![types](https://img.shields.io/npm/types/capacitor-auth-manager.svg)](https://www.npmjs.com/package/capacitor-auth-manager)
13
+ [![bundle size](https://img.shields.io/bundlephobia/minzip/capacitor-auth-manager.svg)](https://bundlephobia.com/package/capacitor-auth-manager)
14
+ [![node](https://img.shields.io/node/v/capacitor-auth-manager.svg)](https://nodejs.org)
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)
17
+
18
+ </div>
19
+
20
+ > [!IMPORTANT]
21
+ > - **Google is the only enabled provider in `2.4.x`.** The other fourteen are present in the source but
22
+ > un-registered — calling one throws `AuthErrorCode.PROVIDER_NOT_ENABLED`. They are re-enabled one at a
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).
27
+
28
+ 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
30
+ apps built on Firebase Auth and apps built on their own backend equally well. Typed React, Vue and Angular
31
+ adapters ship with it, so the sign-in button is a few lines in whichever framework you already use.
32
+
33
+ | | |
34
+ |---|---|
35
+ | **Version** | `2.4.2` |
36
+ | **License** | MIT |
37
+ | **Node** | `>=18.0.0` |
38
+ | **Platforms** | Web · iOS · Android |
39
+ | **Install size** | 264 kB tarball · ~17.4 kB min+gzip for the root entry |
40
+ | **Types** | Bundled `.d.ts` (ESM + CJS) |
41
+ | **Status** | Google provider in production use · remaining providers staged |
42
+
43
+ <a id="table-of-contents"></a>
44
+ ## 🧭 Table of Contents&nbsp;[#](#table-of-contents)
45
+
46
+ - [💡 Why capacitor-auth-manager](#why-capacitor-auth-manager)
47
+ - [✨ Features](#features)
48
+ - [📱 Platform Support](#platform-support)
49
+ - [📋 Requirements](#requirements)
50
+ - [📦 Installation](#installation)
51
+ - [🚀 Quick Start](#quick-start)
52
+ - [🛠️ Usage](#usage)
53
+ - [⚙️ Configuration](#configuration)
54
+ - [🔧 API Reference](#api-reference)
55
+ - [🧩 Types](#types)
56
+ - [💻 Command Line](#command-line)
57
+ - [🎛️ Advanced Features](#advanced-features)
58
+ - [🚑 Recovery & Troubleshooting](#recovery-troubleshooting)
59
+ - [🚧 Limitations](#limitations)
60
+ - [❓ FAQ](#faq)
61
+ - [📚 Documentation](#documentation)
62
+ - [🔄 Changelog](#changelog)
63
+ - [🗺️ Roadmap](#roadmap)
64
+ - [🤝 Contributing](#contributing)
65
+ - [💬 Support](#support)
66
+ - [📄 License](#license)
67
+ - [👤 Author](#author)
68
+ - [🔗 Links](#links)
69
+ - [🏷️ Keywords](#keywords)
70
+
71
+ <a id="why-capacitor-auth-manager"></a>
72
+ ## 💡 Why capacitor-auth-manager&nbsp;[#](#why-capacitor-auth-manager)
73
+
74
+ Google sign-in in a Capacitor app is normally two implementations wearing one button. On the web you open a
75
+ Firebase popup; inside the native webview that popup is unreliable, so you add a native plugin and a second
76
+ code path with a different result shape. The branch then leaks into your UI, your tests and your error
77
+ handling.
78
+
79
+ 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,
82
+ or verify it on your own server — stays your decision.
83
+
84
+ | | `capacitor-auth-manager` | Firebase popup + a separate native plugin |
85
+ |---|---|---|
86
+ | Call sites for one button | one | two, behind a platform branch |
87
+ | Result shape | identical on all three platforms | differs per path |
88
+ | `firebase` dependency | none | required on web |
89
+ | Framework adapters | React, Vue, Angular included | write your own |
90
+ | Providers available today | Google | whatever each piece supports |
91
+
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.
96
+
97
+ <a id="features"></a>
98
+ ## ✨ Features&nbsp;[#](#features)
99
+
100
+ - **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.
103
+ - **Typed framework adapters** — a `useAuth` hook for React, composables for Vue, an injectable
104
+ `AuthService` and route guards for Angular.
105
+ - **Observable auth state** — subscribe once with `onAuthStateChange` and let the UI follow.
106
+ - **Pluggable storage** — web and Capacitor Preferences backends ship with it, and it accepts your own
107
+ `StorageInterface` when you need Keychain or Keystore.
108
+ - **No token persistence by default** — sessions restore through the Google SDK rather than through
109
+ `localStorage`.
110
+
111
+ <a id="platform-support"></a>
112
+ ## 📱 Platform Support&nbsp;[#](#platform-support)
113
+
114
+ | Platform | Supported | Notes |
115
+ |---|---|---|
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). |
120
+
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.
124
+
125
+ <a id="requirements"></a>
126
+ ## 📋 Requirements&nbsp;[#](#requirements)
127
+
128
+ | Requirement | Version | Why |
129
+ |---|---|---|
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 |
132
+ | `@capacitor/preferences` | `^6 \|\| ^7 \|\| ^8` | optional peer — only for `CapacitorPreferencesStorage` |
133
+ | `react` | `^16.8 \|\| ^17 \|\| ^18 \|\| ^19` | optional peer — only for `capacitor-auth-manager/react` |
134
+ | `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` |
136
+
137
+ You also need Google OAuth client IDs: a **Web** client for every platform, plus an **Android** client
138
+ registered with your signing fingerprints and an **iOS** client if you ship those platforms.
139
+
140
+ <a id="installation"></a>
141
+ ## 📦 Installation&nbsp;[#](#installation)
142
+
143
+ ```bash
144
+ yarn add capacitor-auth-manager @capacitor/core
145
+ ```
146
+
147
+ For the native plugin, sync it into the platform projects. Without this step iOS and Android never load it:
148
+
149
+ ```bash
150
+ npx cap sync
151
+ ```
152
+
153
+ Then finish the per-platform OAuth setup, which cannot be done from JavaScript:
154
+
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.
158
+ - **iOS** — add `GIDClientID` to `Info.plist` (or pass `iosClientId`), and add the reversed client ID as a URL
159
+ scheme under `CFBundleURLTypes`.
160
+
161
+ The bundled [command-line helper](#command-line) can write most of this for you.
162
+
163
+ <a id="quick-start"></a>
164
+ ## 🚀 Quick Start&nbsp;[#](#quick-start)
165
+
166
+ Configure once at startup, then sign in from anywhere.
167
+
168
+ ```ts
169
+ import { auth, AuthProvider } from 'capacitor-auth-manager';
170
+
171
+ auth.configure({
172
+ providers: {
173
+ [AuthProvider.GOOGLE]: {
174
+ clientId: 'YOUR_WEB_OAUTH_CLIENT_ID',
175
+ serverClientId: 'YOUR_WEB_OAUTH_CLIENT_ID', // required on Android for an idToken
176
+ iosClientId: 'YOUR_IOS_OAUTH_CLIENT_ID',
177
+ },
178
+ },
179
+ persistence: 'local',
180
+ });
181
+
182
+ const result = await auth.signIn(AuthProvider.GOOGLE);
183
+ console.log(result.user.email, result.credential.idToken);
184
+ ```
185
+
186
+ `AuthProvider.GOOGLE` is the typo-safe form of the string `'google'`; either works.
187
+
188
+ <a id="usage"></a>
189
+ ## 🛠️ Usage&nbsp;[#](#usage)
190
+
191
+ ### Hand the credential to Firebase
192
+
193
+ Identical on web, iOS and Android — the `idToken` is all Firebase needs.
194
+
195
+ ```ts
196
+ import { getAuth, GoogleAuthProvider, signInWithCredential } from 'firebase/auth';
197
+
198
+ const result = await auth.signIn(AuthProvider.GOOGLE);
199
+ await signInWithCredential(getAuth(), GoogleAuthProvider.credential(result.credential.idToken));
200
+ ```
201
+
202
+ ### Verify on your own backend instead
203
+
204
+ ```ts
205
+ const { credential } = await auth.signIn(AuthProvider.GOOGLE);
206
+ await fetch('/api/session', {
207
+ method: 'POST',
208
+ headers: { 'Content-Type': 'application/json' },
209
+ body: JSON.stringify({ idToken: credential.idToken }),
210
+ });
211
+ ```
212
+
213
+ Always verify the token's signature server-side. This package does not verify it in the browser.
214
+
215
+ ### React
216
+
217
+ ```tsx
218
+ import { useAuth, AuthProvider } from 'capacitor-auth-manager/react';
219
+
220
+ function LoginButton() {
221
+ const { user, signIn, signOut, isLoading } = useAuth();
222
+ 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>;
225
+ }
226
+ ```
227
+
228
+ Vue exposes the same surface as composables from `capacitor-auth-manager/vue`, and Angular as an injectable
229
+ `AuthService` plus `AuthGuard` from `capacitor-auth-manager/angular`.
230
+
231
+ ### React to auth state anywhere
232
+
233
+ ```ts
234
+ const unsubscribe = auth.onAuthStateChange((state) => {
235
+ console.log(state.user ? `signed in as ${state.user.email}` : 'signed out');
236
+ });
237
+ ```
238
+
239
+ ### Migrating from `@codetrix-studio/capacitor-google-auth`
240
+
241
+ The token moves from `result.authentication.idToken` to `result.credential.idToken`; the native account
242
+ chooser and the Firebase handoff behave as before.
243
+
244
+ ```ts
245
+ // before
246
+ await GoogleAuth.initialize({ clientId });
247
+ const u = await GoogleAuth.signIn();
248
+ const token = u.authentication.idToken;
249
+
250
+ // after
251
+ auth.configure({ providers: { [AuthProvider.GOOGLE]: { clientId, serverClientId, iosClientId } } });
252
+ const res = await auth.signIn(AuthProvider.GOOGLE);
253
+ const token = res.credential.idToken;
254
+ ```
255
+
256
+ <a id="configuration"></a>
257
+ ## ⚙️ Configuration&nbsp;[#](#configuration)
258
+
259
+ `auth.configure()` takes the manager options; each provider takes its own block.
260
+
261
+ | Option | Type | Default | What it does |
262
+ |---|---|---|---|
263
+ | `providers` | `Record<AuthProvider, ProviderOptions>` | `{}` | Per-provider configuration. |
264
+ | `persistence` | `'local' \| 'session' \| 'none'` | `'local'` | Where auth state is kept between loads. |
265
+ | `storage` | `StorageInterface` | web storage | Custom backend — pass `CapacitorPreferencesStorage` or your own. |
266
+
267
+ Google provider options:
268
+
269
+ | Option | Platform | What it does |
270
+ |---|---|---|
271
+ | `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`. |
273
+ | `iosClientId` | iOS | iOS OAuth client ID, if not set as `GIDClientID` in `Info.plist`. |
274
+ | `scopes` | all | Extra OAuth scopes. Defaults to `openid email profile`. |
275
+ | `hostedDomain` | all | Restrict sign-in to one Google Workspace domain. |
276
+ | `loginHint` | all | Pre-fill an account. |
277
+ | `filterByAuthorizedAccounts` | Android | Show only previously authorised accounts. |
278
+ | `autoSelectEnabled` | Android | Allow one-tap auto-select for returning users. |
279
+ | `nonce` | web | Bind the request to an id-token `nonce` claim, which the package validates. |
280
+
281
+ The same Google options can live in `capacitor.config` under the plugin block instead of in application code.
282
+ Full reference: [Configuration](https://capacitor-auth-manager-docs.aoneahsan.com/getting-started/configuration).
283
+
284
+ <a id="api-reference"></a>
285
+ ## 🔧 API Reference&nbsp;[#](#api-reference)
286
+
287
+ A signature index. Full documentation is on the
288
+ [docs site](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton).
289
+
290
+ | Export | Signature | Docs |
291
+ |---|---|---|
292
+ | `auth.configure` | `(config: AuthManagerConfig) => void` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
293
+ | `auth.signIn` | `(provider: AuthProvider, options?: SignInOptions) => Promise<AuthResult>` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
294
+ | `auth.signOut` | `(options?: SignOutOptions) => Promise<void>` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
295
+ | `auth.getCurrentUser` | `() => AuthUser \| null` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
296
+ | `auth.isAuthenticated` | `() => boolean` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
297
+ | `auth.onAuthStateChange` | `(cb: AuthStateChangeCallback) => () => void` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
298
+ | `auth.getIdToken` | `(options?: GetIdTokenOptions) => Promise<string \| null>` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
299
+ | `auth.refreshToken` | `(options?: RefreshTokenOptions) => Promise<AuthResult>` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
300
+ | `auth.revokeAccess` | `() => Promise<void>` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
301
+ | `auth.deleteAccount` | `() => Promise<void>` | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) |
302
+ | `AuthError` · `isAuthError` | error class and type guard | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/errors) |
303
+ | `WebStorage` · `CapacitorPreferencesStorage` | `StorageInterface` implementations | [→](https://capacitor-auth-manager-docs.aoneahsan.com/api/storage) |
304
+
305
+ Subpath exports: `capacitor-auth-manager`, `/react`, `/vue`, `/angular`, `/core`, `/providers/web`.
306
+
307
+ <a id="types"></a>
308
+ ## 🧩 Types&nbsp;[#](#types)
309
+
310
+ The shapes you actually touch. Every export is typed; see
311
+ [Types](https://capacitor-auth-manager-docs.aoneahsan.com/api/types) for the full set.
312
+
313
+ ```ts
314
+ interface AuthResult {
315
+ user: AuthUser;
316
+ credential: AuthCredential;
317
+ }
318
+
319
+ interface AuthCredential {
320
+ providerId: string; // 'google.com'
321
+ signInMethod: string;
322
+ idToken?: string; // web, iOS, Android
323
+ accessToken?: string; // iOS only for Google
324
+ serverAuthCode?: string; // iOS, when serverClientId is set — exchange it on your server
325
+ }
326
+
327
+ interface AuthUser {
328
+ uid: string;
329
+ email: string | null;
330
+ emailVerified: boolean;
331
+ displayName: string | null;
332
+ photoURL: string | null;
333
+ }
334
+
335
+ interface StorageInterface {
336
+ get<T>(key: string): Promise<T | null>;
337
+ set<T>(key: string, value: T): Promise<void>;
338
+ remove(key: string): Promise<void>;
339
+ clear(): Promise<void>;
340
+ }
341
+ ```
342
+
343
+ <a id="command-line"></a>
344
+ ## 💻 Command Line&nbsp;[#](#command-line)
345
+
346
+ An interactive helper that writes the platform OAuth wiring described in [Installation](#installation).
347
+
348
+ ```bash
349
+ npx capacitor-auth-configure
350
+ ```
351
+
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.
355
+
356
+ <a id="advanced-features"></a>
357
+ ## 🎛️ Advanced Features&nbsp;[#](#advanced-features)
358
+
359
+ - **Custom secure storage** — implement `StorageInterface` over Keychain or Keystore and pass it as
360
+ `storage` instead of the default web storage.
361
+ - **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.
364
+ - **Log level control** — `defaultLogger.setLevel('debug')`, or the `VITE_LOG_LEVEL` / `LOG_LEVEL` build
365
+ variables, without touching `console` directly.
366
+ - **Config in `capacitor.config`** — keep the Google block in native config instead of application code.
367
+
368
+ <a id="recovery-troubleshooting"></a>
369
+ ## 🚑 Recovery & Troubleshooting&nbsp;[#](#recovery-troubleshooting)
370
+
371
+ | Symptom | Cause | Fix |
372
+ |---|---|---|
373
+ | `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 |
380
+
381
+ <a id="limitations"></a>
382
+ ## 🚧 Limitations&nbsp;[#](#limitations)
383
+
384
+ Stated as plainly as the features, because each one otherwise costs an afternoon.
385
+
386
+ - **Google is the only working provider.** Fourteen others exist in the source and throw
387
+ `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.
397
+ - **No id-token verification in the browser.** Signature and claim checks belong to your server, or Firebase.
398
+ - **Native runtime is not covered by CI.** Both platforms are verified to compile, not to sign in. Test a new
399
+ version on one real device before rolling it out widely.
400
+ - **`serverAuthCode` must never be exchanged client-side.** It is returned on iOS for your backend to use.
401
+
402
+ <a id="faq"></a>
403
+ ## ❓ FAQ&nbsp;[#](#faq)
404
+
405
+ **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
407
+ option among several.
408
+
409
+ **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.
411
+
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.
415
+
416
+ **Which client ID goes where?**
417
+ The **Web** client ID is used as `clientId` on web and as `serverClientId` on Android. The iOS client ID is
418
+ separate. This catches nearly everyone once.
419
+
420
+ **When will the other providers land?**
421
+ One at a time, each verified on a device first. See [Roadmap](#roadmap).
422
+
423
+ **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).
426
+
427
+ <a id="documentation"></a>
428
+ ## 📚 Documentation&nbsp;[#](#documentation)
429
+
430
+ | Document | Read it when |
431
+ |---|---|
432
+ | [Introduction](https://capacitor-auth-manager-docs.aoneahsan.com/intro) | deciding whether this fits your app |
433
+ | [Installation](https://capacitor-auth-manager-docs.aoneahsan.com/getting-started/installation) | setting it up the first time |
434
+ | [Quick start](https://capacitor-auth-manager-docs.aoneahsan.com/getting-started/quick-start) | you want a working button in five minutes |
435
+ | [Configuration](https://capacitor-auth-manager-docs.aoneahsan.com/getting-started/configuration) | tuning manager or provider options |
436
+ | [Google provider](https://capacitor-auth-manager-docs.aoneahsan.com/providers/google) | wiring client IDs and scopes correctly |
437
+ | [Android](https://capacitor-auth-manager-docs.aoneahsan.com/platforms/android) · [iOS](https://capacitor-auth-manager-docs.aoneahsan.com/platforms/ios) · [Web](https://capacitor-auth-manager-docs.aoneahsan.com/platforms/web) | one platform behaves differently from the others |
438
+ | [React](https://capacitor-auth-manager-docs.aoneahsan.com/frameworks/react) · [Vue](https://capacitor-auth-manager-docs.aoneahsan.com/frameworks/vue) · [Angular](https://capacitor-auth-manager-docs.aoneahsan.com/frameworks/angular) · [Vanilla JS](https://capacitor-auth-manager-docs.aoneahsan.com/frameworks/vanilla-js) | integrating with your framework |
439
+ | [API reference](https://capacitor-auth-manager-docs.aoneahsan.com/api/auth-singleton) | you need an exact signature |
440
+ | [FAQ](https://capacitor-auth-manager-docs.aoneahsan.com/faq) | something surprised you |
441
+
442
+ <a id="changelog"></a>
443
+ ## 🔄 Changelog&nbsp;[#](#changelog)
444
+
445
+ Latest release: **`2.4.2`** — native sources now compile in a real Capacitor 8 app, and the heavy Facebook and
446
+ Microsoft native SDKs were dropped so the plugin no longer drags them into every consumer build.
447
+
448
+ Full history: [CHANGELOG.md](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/CHANGELOG.md).
449
+
450
+ <a id="roadmap"></a>
451
+ ## 🗺️ Roadmap&nbsp;[#](#roadmap)
452
+
453
+ - Resolve the bare-Node ESM and server-side import limitations above.
454
+ - Re-enable the remaining providers one at a time, each hardened and then verified on a device.
455
+ - Android access-token and `serverAuthCode` support through the Google Authorization API.
456
+ - A `3.0.0` once every provider works again.
457
+
458
+ Dates are deliberately absent; each item ships when it is verified rather than when it is scheduled.
459
+
460
+ <a id="contributing"></a>
461
+ ## 🤝 Contributing&nbsp;[#](#contributing)
462
+
463
+ Fork and open a pull request — see
464
+ [CONTRIBUTING.md](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/.github/CONTRIBUTING.md) for
465
+ setup, standards, and how to request collaborator access. `main` is protected: every change lands through a
466
+ reviewed pull request. Security issues follow
467
+ [SECURITY.md](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/.github/SECURITY.md) rather than
468
+ the public tracker.
469
+
470
+ <a id="support"></a>
471
+ ## 💬 Support&nbsp;[#](#support)
472
+
473
+ Questions and bugs: [open an issue](https://github.com/aoneahsan/capacitor-auth-manager/issues).
474
+
475
+ If this package saves you time, you can support its maintenance at
476
+ [aoneahsan.com/payment](https://aoneahsan.com/payment?project-id=capacitor-auth-manager&project-identifier=capacitor-auth-manager).
477
+
478
+ <a id="license"></a>
479
+ ## 📄 License&nbsp;[#](#license)
480
+
481
+ MIT © Ahsan Mahmood — see
482
+ [LICENSE](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/LICENSE).
483
+
484
+ <a id="author"></a>
485
+ ## 👤 Author&nbsp;[#](#author)
486
+
487
+ **Ahsan Mahmood** — [aoneahsan.com](https://aoneahsan.com) · [GitHub](https://github.com/aoneahsan) ·
488
+ [LinkedIn](https://linkedin.com/in/aoneahsan) · [aoneahsan@gmail.com](mailto:aoneahsan@gmail.com)
489
+
490
+ <a id="links"></a>
491
+ ## 🔗 Links&nbsp;[#](#links)
492
+
493
+ | | |
494
+ |---|---|
495
+ | Documentation | https://capacitor-auth-manager-docs.aoneahsan.com |
496
+ | npm | https://www.npmjs.com/package/capacitor-auth-manager |
497
+ | Repository | https://github.com/aoneahsan/capacitor-auth-manager |
498
+ | Issues | https://github.com/aoneahsan/capacitor-auth-manager/issues |
499
+ | Changelog | https://github.com/aoneahsan/capacitor-auth-manager/blob/main/CHANGELOG.md |
500
+ | Support the project | https://aoneahsan.com/payment |
501
+
502
+ <a id="keywords"></a>
503
+ ## 🏷️ Keywords&nbsp;[#](#keywords)
504
+
505
+ *capacitor · authentication · google-sign-in · oauth · id-token · capacitor-plugin · react · vue · angular*
@@ -61,22 +61,12 @@ dependencies {
61
61
  implementation 'androidx.credentials:credentials-play-services-auth:1.3.0'
62
62
  implementation 'com.google.android.libraries.identity.googleid:googleid:1.1.1'
63
63
 
64
- // Facebook SDK
65
- implementation 'com.facebook.android:facebook-login:17.0.3'
66
-
67
- // Microsoft Authentication Library (MSAL)
68
- implementation 'com.microsoft.identity.client:msal:5.2.0'
69
-
70
- // Firebase Auth (optional)
71
- // implementation 'com.google.firebase:firebase-auth:23.2.0'
72
-
73
- // Biometric
74
- implementation 'androidx.biometric:biometric:1.1.0'
75
-
76
- // Coroutines for async operations
77
- implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0'
78
-
79
- // Security
64
+ // NOTE: Google-first build (2.4.x). The Facebook SDK + Microsoft MSAL dependencies were removed so
65
+ // this plugin no longer pulls heavy auth SDKs into every consumer app. Their native providers live in
66
+ // android/disabled-native-providers/ (not compiled, not shipped). Re-add a dependency here when its
67
+ // provider is re-enabled.
68
+
69
+ // Security (AuthStorage uses EncryptedSharedPreferences)
80
70
  implementation 'androidx.security:security-crypto:1.1.0-alpha06'
81
71
 
82
72
  testImplementation "junit:junit:$junitVersion"
@@ -425,7 +425,7 @@ public class CapacitorAuthManager {
425
425
  return;
426
426
  }
427
427
 
428
- boolean forceRefresh = options != null && options.has("forceRefresh") ? options.getBoolean("forceRefresh") : false;
428
+ boolean forceRefresh = options != null && options.optBoolean("forceRefresh", false);
429
429
  authProvider.getIdToken(forceRefresh, callback);
430
430
  }
431
431