capacitor-auth-manager 2.4.2 → 2.4.4

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 (4) hide show
  1. package/CHANGELOG.md +41 -1
  2. package/README.md +504 -0
  3. package/package.json +12 -24
  4. package/Readme.md +0 -203
package/CHANGELOG.md CHANGED
@@ -5,6 +5,40 @@ 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.4] - 2026-07-25
9
+
10
+ ### Fixed
11
+
12
+ - **The README stated the previous version.** The at-a-glance `Version` row is a static duplicate of
13
+ `package.json.version`, so it drifted the moment the version was bumped — it shipped stale in eight of the
14
+ fleet's packages at once. The row, and any native version string, now move with the release.
15
+
16
+ ## [2.4.3] — 2026-07-25
17
+
18
+ **Documentation and metadata only — no runtime changes.** Brings the package to the house README
19
+ standard and, importantly, **documents two High-severity defects that have been shipping since before
20
+ this release**. They are stated plainly in the README's Limitations section rather than left for a
21
+ consumer to discover at runtime:
22
+
23
+ - **The published ESM build does not resolve under bare Node.** `moduleResolution: "bundler"` emits 133
24
+ extensionless relative specifiers across 33 files. Bundlers resolve them; Node's ESM resolver does
25
+ not, so SSR, Node-resolution test runners and `node --import` all fail.
26
+ - **Importing the package throws `window is not defined`.** A module-scope singleton in
27
+ `src/core/auth-manager.ts` constructs a `WebStorage` that reads `window.localStorage` unguarded. This
28
+ also makes `sideEffects: false` untrue.
29
+
30
+ Neither is fixed here — both need a code change and a version bump beyond a documentation patch. Every
31
+ conventional gate passes while they ship: typecheck, lint, build, the exports-map walk and even an
32
+ esbuild bundle are all green. Only installing the tarball and importing it under bare Node catches them.
33
+ Tracked in `docs/REPORTED-ISSUES.md` as ISSUE-001 and ISSUE-002.
34
+
35
+ ### Changed
36
+
37
+ - README rewritten to the canonical package pattern; `Readme.md` renamed to `README.md`.
38
+ - `homepage` moved off the npmjs.com page onto the documentation site.
39
+ - `funding` added; `keywords` reduced from 24 to 9 honest terms.
40
+ - `files` allowlist corrected to include the `bin` script explicitly; inert `.npmignore` removed.
41
+
8
42
  ## [2.4.2] — 2026-06-30
9
43
 
10
44
  **Native now actually compiles — Google-only native (verified).** `2.4.1` shipped native sources that
@@ -177,4 +211,10 @@ as each is hardened and verified on device; until then they report a clear `PROV
177
211
 
178
212
  - `npm run build` succeeds; `npm run test:run` — 79 tests pass; `npm run lint` — 0 errors.
179
213
 
180
- [2.2.0]: https://github.com/aoneahsan/capacitor-auth-manager/releases/tag/v2.2.0
214
+ ## Earlier releases
215
+
216
+ `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
217
+ per-version record of them was kept. They are listed here so the gap is visible rather than silent; the
218
+ published artefacts remain on
219
+ [npm](https://www.npmjs.com/package/capacitor-auth-manager?activeTab=versions). Treat `2.2.0` as the first
220
+ release with a documented history.
package/README.md ADDED
@@ -0,0 +1,504 @@
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.4` |
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.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.
446
+
447
+ Full history: [CHANGELOG.md](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/CHANGELOG.md).
448
+
449
+ <a id="roadmap"></a>
450
+ ## 🗺️ Roadmap&nbsp;[#](#roadmap)
451
+
452
+ - Resolve the bare-Node ESM and server-side import limitations above.
453
+ - Re-enable the remaining providers one at a time, each hardened and then verified on a device.
454
+ - Android access-token and `serverAuthCode` support through the Google Authorization API.
455
+ - A `3.0.0` once every provider works again.
456
+
457
+ Dates are deliberately absent; each item ships when it is verified rather than when it is scheduled.
458
+
459
+ <a id="contributing"></a>
460
+ ## 🤝 Contributing&nbsp;[#](#contributing)
461
+
462
+ Fork and open a pull request — see
463
+ [CONTRIBUTING.md](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/.github/CONTRIBUTING.md) for
464
+ setup, standards, and how to request collaborator access. `main` is protected: every change lands through a
465
+ reviewed pull request. Security issues follow
466
+ [SECURITY.md](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/.github/SECURITY.md) rather than
467
+ the public tracker.
468
+
469
+ <a id="support"></a>
470
+ ## 💬 Support&nbsp;[#](#support)
471
+
472
+ Questions and bugs: [open an issue](https://github.com/aoneahsan/capacitor-auth-manager/issues).
473
+
474
+ If this package saves you time, you can support its maintenance at
475
+ [aoneahsan.com/payment](https://aoneahsan.com/payment?project-id=capacitor-auth-manager&project-identifier=capacitor-auth-manager).
476
+
477
+ <a id="license"></a>
478
+ ## 📄 License&nbsp;[#](#license)
479
+
480
+ MIT © Ahsan Mahmood — see
481
+ [LICENSE](https://github.com/aoneahsan/capacitor-auth-manager/blob/main/LICENSE).
482
+
483
+ <a id="author"></a>
484
+ ## 👤 Author&nbsp;[#](#author)
485
+
486
+ **Ahsan Mahmood** — [aoneahsan.com](https://aoneahsan.com) · [GitHub](https://github.com/aoneahsan) ·
487
+ [LinkedIn](https://linkedin.com/in/aoneahsan) · [aoneahsan@gmail.com](mailto:aoneahsan@gmail.com)
488
+
489
+ <a id="links"></a>
490
+ ## 🔗 Links&nbsp;[#](#links)
491
+
492
+ | | |
493
+ |---|---|
494
+ | Documentation | https://capacitor-auth-manager-docs.aoneahsan.com |
495
+ | npm | https://www.npmjs.com/package/capacitor-auth-manager |
496
+ | Repository | https://github.com/aoneahsan/capacitor-auth-manager |
497
+ | Issues | https://github.com/aoneahsan/capacitor-auth-manager/issues |
498
+ | Changelog | https://github.com/aoneahsan/capacitor-auth-manager/blob/main/CHANGELOG.md |
499
+ | Support the project | https://aoneahsan.com/payment |
500
+
501
+ <a id="keywords"></a>
502
+ ## 🏷️ Keywords&nbsp;[#](#keywords)
503
+
504
+ *capacitor · authentication · google-sign-in · oauth · id-token · capacitor-plugin · react · vue · angular*
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "capacitor-auth-manager",
3
- "version": "2.4.2",
3
+ "version": "2.4.4",
4
4
  "description": "Capacitor + web authentication. Firebase-agnostic native & web Google sign-in (idToken/accessToken) for React, Vue, Angular and vanilla JS — a drop-in alternative to @codetrix-studio/capacitor-google-auth. More providers shipping one at a time.",
5
5
  "main": "dist/plugin.cjs.js",
6
6
  "module": "dist/esm/index.js",
@@ -48,10 +48,11 @@
48
48
  "android/proguard-rules.pro",
49
49
  "dist/",
50
50
  "ios/Plugin/",
51
+ "scripts/configure.js",
51
52
  "CapacitorAuthManager.podspec",
53
+ "README.md",
52
54
  "CHANGELOG.md",
53
- "!**/CLAUDE.md",
54
- "!**/AGENTS.md"
55
+ "LICENSE"
55
56
  ],
56
57
  "author": {
57
58
  "email": "aoneahsan@gmail.com",
@@ -66,37 +67,24 @@
66
67
  "bugs": {
67
68
  "url": "https://github.com/aoneahsan/capacitor-auth-manager/issues"
68
69
  },
69
- "homepage": "https://npmjs.com/package/capacitor-auth-manager",
70
+ "homepage": "https://capacitor-auth-manager-docs.aoneahsan.com",
71
+ "funding": "https://aoneahsan.com/payment?project-id=capacitor-auth-manager&project-identifier=capacitor-auth-manager",
70
72
  "keywords": [
71
- "auth",
73
+ "capacitor",
72
74
  "authentication",
75
+ "google-sign-in",
73
76
  "oauth",
74
- "google",
75
- "apple",
76
- "microsoft",
77
- "facebook",
78
- "github",
79
- "slack",
80
- "linkedin",
81
- "firebase",
82
- "email-magic-link",
83
- "sms",
84
- "email-code",
85
- "biometric",
77
+ "id-token",
78
+ "capacitor-plugin",
86
79
  "react",
87
80
  "vue",
88
- "angular",
89
- "capacitor",
90
- "plugin",
91
- "native",
92
- "web",
93
- "pwa",
94
- "universal"
81
+ "angular"
95
82
  ],
96
83
  "scripts": {
97
84
  "build": "npm run clean && npm run tsc && rollup -c rollup.config.mjs",
98
85
  "clean": "rimraf ./dist",
99
86
  "tsc": "tsc -p tsconfig.build.json",
87
+ "typecheck": "tsc -p tsconfig.build.json --noEmit",
100
88
  "watch": "tsc --watch",
101
89
  "lint": "eslint .",
102
90
  "prettier": "prettier --write .",
package/Readme.md DELETED
@@ -1,203 +0,0 @@
1
- # Capacitor Auth Manager
2
-
3
- Firebase-agnostic **Google authentication** for Capacitor + web — a drop-in alternative to
4
- `@codetrix-studio/capacitor-google-auth`. One API (`signIn(AuthProvider.GOOGLE)`) returns a Google
5
- credential `{ idToken, accessToken?, serverAuthCode?, user }` on **web, iOS and Android**; your app feeds
6
- the `idToken` into Firebase (or anything else). Works with React, Vue, Angular, and vanilla JS.
7
-
8
- > **Status (2.4.x): Google-first.** The package is being brought to production **one provider at a time**.
9
- > Right now **Google is enabled** (web + iOS + Android). The other 14 providers' code lives in the repo but
10
- > is un-registered — calling them throws `AuthErrorCode.PROVIDER_NOT_ENABLED` — and each is re-enabled and
11
- > verified on device one at a time. See the [changelog](./CHANGELOG.md).
12
-
13
- ## Why this exists
14
-
15
- For native Google sign-in in a Capacitor app you normally reach for `@codetrix-studio/capacitor-google-auth`.
16
- This package does the same job (native Google ID token → your Firebase `signInWithCredential`) but is yours
17
- to maintain, uses the modern **Android Credential Manager** and **GoogleSignIn** SDKs, keeps the **same call
18
- on every platform**, and stays **Firebase-agnostic** (no `firebase` dependency pulled in).
19
-
20
- ## Install
21
-
22
- ```bash
23
- npm install capacitor-auth-manager
24
- # then, for the native plugin:
25
- npx cap sync
26
- ```
27
-
28
- `@capacitor/core` is an optional peer — needed only for the native (iOS/Android) plugin. Framework adapters
29
- (`react` / `vue` / `@angular/core`) are optional peers too; install only what you use.
30
-
31
- ## Provider support
32
-
33
- | Provider | Web | iOS | Android | Status |
34
- |---|---|---|---|---|
35
- | **Google** | ✅ GIS id-token | ✅ GoogleSignIn | ✅ Credential Manager | **Enabled** |
36
- | Apple, Microsoft, Facebook, GitHub, Slack, LinkedIn, Firebase, Magic-link, SMS, Email/Phone/Username+password, Email-code, Biometric | — | — | — | ⏳ coming, one at a time (`PROVIDER_NOT_ENABLED`) |
37
-
38
- ## Quick start
39
-
40
- Configure once, then sign in. Use the exported **`AuthProvider` enum** (recommended — typo-safe; the plain
41
- string `'google'` also works).
42
-
43
- ```ts
44
- import { auth, AuthProvider } from 'capacitor-auth-manager';
45
-
46
- auth.configure({
47
- providers: {
48
- [AuthProvider.GOOGLE]: {
49
- clientId: 'YOUR_WEB_OAUTH_CLIENT_ID', // web + Android serverClientId fallback
50
- serverClientId: 'YOUR_WEB_OAUTH_CLIENT_ID', // REQUIRED on Android to receive an idToken
51
- iosClientId: 'YOUR_IOS_OAUTH_CLIENT_ID', // iOS (or set GIDClientID in Info.plist)
52
- },
53
- },
54
- persistence: 'local',
55
- });
56
-
57
- const result = await auth.signIn(AuthProvider.GOOGLE);
58
- // The same field is populated on web, iOS and Android:
59
- const idToken = result.credential.idToken;
60
- ```
61
-
62
- ### Hand the credential to Firebase (identical on every platform)
63
-
64
- ```ts
65
- import { getAuth, GoogleAuthProvider, signInWithCredential } from 'firebase/auth';
66
-
67
- const result = await auth.signIn(AuthProvider.GOOGLE);
68
- await signInWithCredential(
69
- getAuth(),
70
- GoogleAuthProvider.credential(result.credential.idToken),
71
- );
72
- ```
73
-
74
- ### React
75
-
76
- ```tsx
77
- import { useAuth, AuthProvider } from 'capacitor-auth-manager/react';
78
-
79
- function LoginButton() {
80
- const { user, signIn, signOut } = useAuth();
81
- if (user) return <button onClick={() => signOut()}>Sign out</button>;
82
- return <button onClick={() => signIn(AuthProvider.GOOGLE)}>Sign in with Google</button>;
83
- }
84
- ```
85
-
86
- `useAuth()` also returns `isLoading`, `isAuthenticated`, `error`, `refreshToken`, `getIdToken`, and
87
- `revokeAccess`. Vue (`capacitor-auth-manager/vue`) and Angular (`capacitor-auth-manager/angular`) expose the
88
- same surface as composables / an injectable `AuthService`; both re-export `AuthProvider`.
89
-
90
- ## What you get back
91
-
92
- `signIn` resolves to an `AuthResult`:
93
-
94
- ```ts
95
- {
96
- user: { uid, email, emailVerified, displayName, photoURL, providerData: [...], metadata: {...} },
97
- credential: {
98
- providerId: 'google.com',
99
- signInMethod: 'google.com',
100
- idToken?: string, // present on web, iOS, Android
101
- accessToken?: string, // iOS; web/Android: see notes below
102
- serverAuthCode?: string, // iOS when serverClientId + offline access; exchange on YOUR server only
103
- },
104
- }
105
- ```
106
-
107
- Per-platform token availability (honest):
108
-
109
- - **Web** (Google Identity Services id-token flow): returns **`idToken`** only — no `accessToken`. If you
110
- need to call Google APIs from the browser, use the GIS token client separately.
111
- - **iOS** (GoogleSignIn): `idToken` + `accessToken` (+ `serverAuthCode` when `serverClientId` is set).
112
- - **Android** (Credential Manager): returns **`idToken`** reliably. `accessToken` / `serverAuthCode` require
113
- the separate Google Authorization API and are not returned by the sign-in call (planned).
114
-
115
- For the Firebase `signInWithCredential` handoff, the **`idToken` is all you need** on every platform.
116
-
117
- ## Native setup
118
-
119
- ### Android
120
-
121
- 1. In Google Cloud / Firebase, create an **Android** OAuth client and add your app's **SHA-1/SHA-256**
122
- signing fingerprints; create (or reuse) a **Web** OAuth client.
123
- 2. Pass that **Web** client id as `serverClientId` (Credential Manager needs it to return an idToken).
124
- 3. Add your app's `google-services.json` to the Android project as usual.
125
- 4. The device must have a Google account signed in (Credential Manager shows that account chooser).
126
-
127
- No extra AndroidManifest permissions are required by this plugin.
128
-
129
- ### iOS
130
-
131
- 1. Create an **iOS** OAuth client in Google Cloud.
132
- 2. Add `GIDClientID` (your iOS client id) to `Info.plist`, or pass it as `iosClientId`.
133
- 3. Add the **reversed client id** as a URL scheme in `Info.plist` → `CFBundleURLTypes`
134
- (e.g. `com.googleusercontent.apps.XXXX`).
135
- 4. For a `serverAuthCode`, also set `serverClientId` (your Web client id).
136
-
137
- ### Capacitor config
138
-
139
- You can also set the Google options in `capacitor.config` under the plugin block instead of `auth.configure`.
140
-
141
- ## Migrating from `@codetrix-studio/capacitor-google-auth`
142
-
143
- ```ts
144
- // before
145
- await GoogleAuth.initialize({ clientId });
146
- const u = await GoogleAuth.signIn();
147
- await signInWithCredential(getAuth(), GoogleAuthProvider.credential(u.authentication.idToken));
148
-
149
- // after
150
- import { auth, AuthProvider } from 'capacitor-auth-manager';
151
- auth.configure({ providers: { [AuthProvider.GOOGLE]: { clientId, serverClientId, iosClientId } } });
152
- const res = await auth.signIn(AuthProvider.GOOGLE);
153
- await signInWithCredential(getAuth(), GoogleAuthProvider.credential(res.credential.idToken));
154
- ```
155
-
156
- The id token moves from `result.authentication.idToken` to `result.credential.idToken`. Everything else
157
- (the native account chooser, the Firebase handoff) behaves the same.
158
-
159
- ## Configuration (`GoogleAuthOptions`)
160
-
161
- | Option | Where | Purpose |
162
- |---|---|---|
163
- | `clientId` | web (required), Android fallback | Web OAuth client id; the id token's `aud`. |
164
- | `serverClientId` | Android (required for idToken), iOS | Web OAuth client id for Credential Manager / `serverAuthCode`. |
165
- | `iosClientId` | iOS | iOS OAuth client id (or set `GIDClientID` in Info.plist). |
166
- | `scopes` | all | Extra OAuth scopes (default `openid email profile`). |
167
- | `hostedDomain` / `loginHint` | all | Restrict to a Workspace domain / prefill an account. |
168
- | `filterByAuthorizedAccounts`, `autoSelectEnabled` | Android | Credential Manager UX (returning-user / one-tap auto-select). |
169
- | `nonce` | web | Bind the request to an id-token `nonce` claim (validated). |
170
-
171
- ## Security & storage
172
-
173
- - **No secrets are persisted by default.** Short-lived id tokens are re-derived from the Google SDK's silent
174
- restore rather than written to `localStorage` / `@capacitor/preferences`. Inject a `StorageInterface`
175
- (ideally Keychain/Keystore-backed) if you need token persistence at rest.
176
- - The web flow uses the GIS **id-token** flow specifically so **no client secret and no backend** are
177
- required. A `serverAuthCode` (iOS) must be exchanged on **your** server, never in the browser.
178
- - The package does not verify id-token signatures in the browser — validate the id token server-side (or via
179
- Firebase) before trusting its claims.
180
-
181
- ## Caveats
182
-
183
- - The iOS (Swift) and Android (Java) sources are written to the official SDK contracts but are **not compiled
184
- in CI**. Validate a new version in **one** app (web + one Android device + one iOS device) before rolling
185
- out to many apps.
186
- - Web Google sign-in uses One-Tap / FedCM `prompt()`; if One-Tap is suppressed (cooldown), render Google's
187
- official button via the provider's `renderButton(element)` escape hatch, or use your own Firebase popup on web.
188
-
189
- ## Contributing & support
190
-
191
- - [Contributing](./.github/CONTRIBUTING.md) · [Security policy](./.github/SECURITY.md) ·
192
- [Support](./.github/SUPPORT.md) · [Changelog](./CHANGELOG.md)
193
- - Docs: https://github.com/aoneahsan/capacitor-auth-manager-docs
194
- - Author: Ahsan Mahmood — aoneahsan@gmail.com — https://aoneahsan.com
195
-
196
- ## License
197
-
198
- [MIT](./LICENSE) © 2024–2026 Ahsan Mahmood
199
-
200
- ## Links
201
-
202
- - npm: https://www.npmjs.com/package/capacitor-auth-manager
203
- - Repository: https://github.com/aoneahsan/capacitor-auth-manager