capacitor-auth-manager 2.3.0 → 2.4.1

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 (141) hide show
  1. package/CHANGELOG.md +149 -0
  2. package/CapacitorAuthManager.podspec +1 -1
  3. package/LICENSE +1 -1
  4. package/Readme.md +136 -595
  5. package/android/build.gradle +8 -2
  6. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/CapacitorAuthManager.java +43 -15
  7. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/CapacitorAuthManagerPlugin.java +24 -3
  8. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/GoogleAuthProvider.java +427 -226
  9. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/ProviderFactory.java +28 -0
  10. package/dist/angular.cjs.js +971 -4542
  11. package/dist/core.cjs.js +944 -4514
  12. package/dist/esm/angular/auth.guard.js +0 -1
  13. package/dist/esm/angular/auth.module.d.ts +2 -1
  14. package/dist/esm/angular/auth.module.js +0 -1
  15. package/dist/esm/angular/auth.service.d.ts +5 -5
  16. package/dist/esm/angular/auth.service.js +0 -1
  17. package/dist/esm/angular/index.d.ts +1 -0
  18. package/dist/esm/angular/index.js +4 -1
  19. package/dist/esm/capacitor-plugin.js +0 -1
  20. package/dist/esm/core/auth-manager.d.ts +6 -0
  21. package/dist/esm/core/auth-manager.js +27 -4
  22. package/dist/esm/core/index.js +0 -1
  23. package/dist/esm/core/platform.js +0 -1
  24. package/dist/esm/core/provider-manifests.js +0 -1
  25. package/dist/esm/core/provider-registry.d.ts +9 -2
  26. package/dist/esm/core/provider-registry.js +63 -57
  27. package/dist/esm/core/types.js +0 -1
  28. package/dist/esm/definitions.d.ts +30 -1
  29. package/dist/esm/definitions.js +8 -1
  30. package/dist/esm/index.js +0 -1
  31. package/dist/esm/providers/base-provider.js +0 -1
  32. package/dist/esm/providers/native/google-native-provider.d.ts +26 -0
  33. package/dist/esm/providers/native/google-native-provider.js +114 -0
  34. package/dist/esm/providers/oauth-provider.js +0 -1
  35. package/dist/esm/providers/provider-factory.d.ts +9 -0
  36. package/dist/esm/providers/provider-factory.js +20 -57
  37. package/dist/esm/providers/web/google-provider.d.ts +70 -92
  38. package/dist/esm/providers/web/google-provider.js +262 -205
  39. package/dist/esm/providers/web/index.d.ts +0 -14
  40. package/dist/esm/providers/web/index.js +7 -16
  41. package/dist/esm/react/hooks.js +0 -1
  42. package/dist/esm/react/index.d.ts +1 -0
  43. package/dist/esm/react/index.js +4 -1
  44. package/dist/esm/react/types.js +0 -1
  45. package/dist/esm/utils/auth-error.js +0 -1
  46. package/dist/esm/utils/error-message.d.ts +8 -0
  47. package/dist/esm/utils/error-message.js +20 -0
  48. package/dist/esm/utils/event-emitter.js +0 -1
  49. package/dist/esm/utils/logger.js +0 -1
  50. package/dist/esm/utils/pending-verification-store.js +0 -1
  51. package/dist/esm/utils/storage.d.ts +11 -6
  52. package/dist/esm/utils/storage.js +3 -2
  53. package/dist/esm/vue/composables.js +0 -1
  54. package/dist/esm/vue/index.d.ts +1 -0
  55. package/dist/esm/vue/index.js +4 -1
  56. package/dist/esm/web.js +0 -1
  57. package/dist/plugin.cjs.js +468 -4663
  58. package/dist/plugin.js +468 -4663
  59. package/dist/react.cjs.js +972 -4543
  60. package/dist/vue.cjs.js +972 -4543
  61. package/ios/Plugin/CapacitorAuthManager.swift +6 -6
  62. package/ios/Plugin/GoogleAuthProvider.swift +213 -105
  63. package/ios/Plugin/Models.swift +35 -4
  64. package/package.json +31 -30
  65. package/dist/angular.cjs.js.map +0 -1
  66. package/dist/core.cjs.js.map +0 -1
  67. package/dist/esm/angular/auth.guard.js.map +0 -1
  68. package/dist/esm/angular/auth.module.js.map +0 -1
  69. package/dist/esm/angular/auth.service.js.map +0 -1
  70. package/dist/esm/angular/index.js.map +0 -1
  71. package/dist/esm/capacitor-plugin.js.map +0 -1
  72. package/dist/esm/core/auth-manager.js.map +0 -1
  73. package/dist/esm/core/index.js.map +0 -1
  74. package/dist/esm/core/platform.js.map +0 -1
  75. package/dist/esm/core/provider-manifests.js.map +0 -1
  76. package/dist/esm/core/provider-registry.js.map +0 -1
  77. package/dist/esm/core/types.js.map +0 -1
  78. package/dist/esm/definitions.js.map +0 -1
  79. package/dist/esm/index.js.map +0 -1
  80. package/dist/esm/providers/base-provider.js.map +0 -1
  81. package/dist/esm/providers/oauth-provider.js.map +0 -1
  82. package/dist/esm/providers/provider-factory.js.map +0 -1
  83. package/dist/esm/providers/web/apple-provider.d.ts +0 -61
  84. package/dist/esm/providers/web/apple-provider.js +0 -293
  85. package/dist/esm/providers/web/apple-provider.js.map +0 -1
  86. package/dist/esm/providers/web/biometric-provider.d.ts +0 -60
  87. package/dist/esm/providers/web/biometric-provider.js +0 -368
  88. package/dist/esm/providers/web/biometric-provider.js.map +0 -1
  89. package/dist/esm/providers/web/email-code-provider.d.ts +0 -46
  90. package/dist/esm/providers/web/email-code-provider.js +0 -294
  91. package/dist/esm/providers/web/email-code-provider.js.map +0 -1
  92. package/dist/esm/providers/web/email-password-provider.d.ts +0 -52
  93. package/dist/esm/providers/web/email-password-provider.js +0 -429
  94. package/dist/esm/providers/web/email-password-provider.js.map +0 -1
  95. package/dist/esm/providers/web/facebook-provider.d.ts +0 -80
  96. package/dist/esm/providers/web/facebook-provider.js +0 -249
  97. package/dist/esm/providers/web/facebook-provider.js.map +0 -1
  98. package/dist/esm/providers/web/firebase-provider.d.ts +0 -22
  99. package/dist/esm/providers/web/firebase-provider.js +0 -338
  100. package/dist/esm/providers/web/firebase-provider.js.map +0 -1
  101. package/dist/esm/providers/web/github-provider.d.ts +0 -34
  102. package/dist/esm/providers/web/github-provider.js +0 -325
  103. package/dist/esm/providers/web/github-provider.js.map +0 -1
  104. package/dist/esm/providers/web/google-provider.js.map +0 -1
  105. package/dist/esm/providers/web/index.js.map +0 -1
  106. package/dist/esm/providers/web/linkedin-provider.d.ts +0 -37
  107. package/dist/esm/providers/web/linkedin-provider.js +0 -178
  108. package/dist/esm/providers/web/linkedin-provider.js.map +0 -1
  109. package/dist/esm/providers/web/magic-link-provider.d.ts +0 -44
  110. package/dist/esm/providers/web/magic-link-provider.js +0 -311
  111. package/dist/esm/providers/web/magic-link-provider.js.map +0 -1
  112. package/dist/esm/providers/web/microsoft-provider.d.ts +0 -23
  113. package/dist/esm/providers/web/microsoft-provider.js +0 -236
  114. package/dist/esm/providers/web/microsoft-provider.js.map +0 -1
  115. package/dist/esm/providers/web/phone-password-provider.d.ts +0 -63
  116. package/dist/esm/providers/web/phone-password-provider.js +0 -440
  117. package/dist/esm/providers/web/phone-password-provider.js.map +0 -1
  118. package/dist/esm/providers/web/slack-provider.d.ts +0 -39
  119. package/dist/esm/providers/web/slack-provider.js +0 -175
  120. package/dist/esm/providers/web/slack-provider.js.map +0 -1
  121. package/dist/esm/providers/web/sms-provider.d.ts +0 -46
  122. package/dist/esm/providers/web/sms-provider.js +0 -306
  123. package/dist/esm/providers/web/sms-provider.js.map +0 -1
  124. package/dist/esm/providers/web/username-password-provider.d.ts +0 -59
  125. package/dist/esm/providers/web/username-password-provider.js +0 -434
  126. package/dist/esm/providers/web/username-password-provider.js.map +0 -1
  127. package/dist/esm/react/hooks.js.map +0 -1
  128. package/dist/esm/react/index.js.map +0 -1
  129. package/dist/esm/react/types.js.map +0 -1
  130. package/dist/esm/utils/auth-error.js.map +0 -1
  131. package/dist/esm/utils/event-emitter.js.map +0 -1
  132. package/dist/esm/utils/logger.js.map +0 -1
  133. package/dist/esm/utils/pending-verification-store.js.map +0 -1
  134. package/dist/esm/utils/storage.js.map +0 -1
  135. package/dist/esm/vue/composables.js.map +0 -1
  136. package/dist/esm/vue/index.js.map +0 -1
  137. package/dist/esm/web.js.map +0 -1
  138. package/dist/plugin.cjs.js.map +0 -1
  139. package/dist/plugin.js.map +0 -1
  140. package/dist/react.cjs.js.map +0 -1
  141. package/dist/vue.cjs.js.map +0 -1
package/Readme.md CHANGED
@@ -1,662 +1,203 @@
1
1
  # Capacitor Auth Manager
2
2
 
3
- Universal authentication manager with 15 web providers. Framework-agnostic, works with React, Vue, Angular, and vanilla JS. Optional Capacitor support for mobile apps.
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.
4
7
 
5
- ## Current State
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).
6
12
 
7
- - Current package version: `2.2.0`
8
- - Verified on: `2026-05-26`
9
- - Tests: `79/79` passing via `npm run test:run`
10
- - Build: `npm run build` succeeds
11
- - Current package shape:
12
- - core auth manager API (the `auth` singleton)
13
- - 15 web provider modules under `src/providers/web/`
14
- - React hooks export
15
- - Vue composables export
16
- - Angular service/module/guard export
17
- - optional Capacitor plugin surfaces for native integrations
13
+ ## Why this exists
18
14
 
19
- ## Supported Environments
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).
20
19
 
21
- | Peer | Supported range |
22
- |------|-----------------|
23
- | `@capacitor/core` | `^7` or `^8` (optional — only needed for the native plugin / `CapacitorPreferencesStorage`) |
24
- | `@angular/core` | up to `^21` (only for the Angular adapter) |
25
- | `react` | `16.8`–`19` (only for the React adapter) |
26
- | `vue` | `^3` (only for the Vue adapter) |
27
- | iOS deployment target | 14 |
28
-
29
- `@capacitor/preferences` is an **optional** peer — install it only if you inject `CapacitorPreferencesStorage` for native token storage.
30
-
31
- ## What's New in 2.2.0
32
-
33
- 2.2.0 is a backward-compatible minor release. No public method signatures were removed. Highlights:
34
-
35
- - **PKCE on the authorization-code OAuth flow.** Manual OAuth flows (Slack, LinkedIn) now send a SHA-256 (`S256`) code challenge/verifier per RFC 7636. OIDC `nonce` and the ID-token `exp` claim are validated. The library does **not** verify ID-token signatures in the browser — re-validate ID tokens server-side before trusting their claims.
36
- - **Pluggable secure storage.** `configure()` accepts a `storage` option (any `StorageInterface`). A new exported `CapacitorPreferencesStorage` backs storage with `@capacitor/preferences` (an optional peer) so native tokens live in native key-value storage instead of the webview's `localStorage`. Default web storage is still `localStorage`, which is readable by any XSS/third-party script — inject secure storage on native. (Capacitor Preferences is not hardware-encrypted; use a Keychain/Keystore-backed adapter for secrecy at rest.)
37
- - **Real biometric web fallback encryption.** Stored biometric material now uses AES-GCM with a non-extractable IndexedDB key instead of base64 encoding.
38
- - **Account-management methods on the singleton and all adapters.** `linkAccount`, `unlinkAccount`, `revokeAccess`, `getIdToken`, `updateProfile`, `deleteAccount`, plus `isProviderConfigured()` / `getConfiguredProviders()` are now available on the `auth` singleton and surfaced through the React/Vue/Angular adapters.
39
- - **GitHub sign-in completes via a backend proxy.** A new `tokenExchangeProxy` config field points at a developer-supplied endpoint that exchanges the GitHub `code` for a token. GitHub cannot do secure token exchange purely in-browser; without the proxy you get a clear `MISSING_CONFIG` error.
40
- - **Slack and LinkedIn fetch real user profiles** (Slack `openid.connect.userInfo`, LinkedIn `/v2/userinfo`) instead of placeholder identities.
41
- - **Firebase sign-in method** is derived from your standard options/credentials, with a new `defaultMethod` config field as the fallback.
42
- - **All errors use the `AuthErrorCode` enum.** Standalone providers no longer throw bare string codes — switch on `error.code` reliably.
43
- - **Centralized logger.** A shared `defaultLogger` is exported; adjust verbosity via `VITE_LOG_LEVEL` / `LOG_LEVEL` (build-time) or `defaultLogger.setLevel('debug')` (runtime). Default level is `warn`.
44
-
45
- One exported type was tightened (non-breaking widening to a precise type): `AuthManagerConfig.providers` is now `Record<string, ProviderOptions>` instead of `any`. See [MIGRATION.md](./docs/MIGRATION.md) for the full 2.1.0 → 2.2.0 notes.
46
-
47
- ## Why This Package Exists
48
-
49
- Capacitor Auth Manager standardizes authentication across web and mobile projects so teams do not have to rebuild auth orchestration, state handling, provider configuration, and framework glue for every new product.
50
-
51
- ## Highlights
52
-
53
- - **No Provider Wrappers** - Works like Zustand, no context providers needed
54
- - **Framework Agnostic** - One package for React, Vue, Angular, and vanilla JS
55
- - **Optional Capacitor** - Use in regular web apps without Capacitor
56
- - **Dynamic Loading** - Providers load only when used (better tree-shaking)
57
- - **Broad Provider Coverage** - Major OAuth, credential, passwordless, and biometric flows live behind one API
58
-
59
- ## Features
60
-
61
- - 🎯 **Framework Agnostic** - Use with React, Vue, Angular, or vanilla JavaScript
62
- - 📦 **Tree-shakeable** - Only includes the providers you use
63
- - 🔌 **15 Auth Providers** - Google, Apple, Microsoft, Facebook, GitHub, Slack, LinkedIn, Firebase, and password/passwordless/biometric flows
64
- - 🔄 **Provider-less Design** - No context providers required (like Zustand)
65
- - 📱 **Optional Capacitor** - Works in web apps without Capacitor
66
- - 🎨 **TypeScript First** - Full type safety and IntelliSense
67
- - 🔐 **PKCE + pluggable storage** - S256 PKCE on manual OAuth flows; inject secure storage on native
68
- - ⚡ **Dynamic Loading** - Providers load only when used
69
-
70
- ## Verification Snapshot
71
-
72
- ```bash
73
- npm run test:run
74
- npm run build
75
- ```
76
-
77
- Build remediation completed:
78
-
79
- - Rollup now runs from `rollup.config.mjs`, eliminating the Node ESM reparsing warning
80
- - `capacitor-biometric-authentication` is declared as an explicit optional dependency
81
- - TypeScript helper imports now use `tslib`, eliminating the Angular rewritten-`this` warnings
82
-
83
- ## Quick Start
84
-
85
- ### Installation
20
+ ## Install
86
21
 
87
22
  ```bash
88
23
  npm install capacitor-auth-manager
89
- # or
90
- yarn add capacitor-auth-manager
91
- ```
92
-
93
- ### Basic Usage (Vanilla JavaScript)
94
-
95
- ```javascript
96
- import { auth } from 'capacitor-auth-manager';
97
-
98
- // Configure providers
99
- auth.configure({
100
- providers: {
101
- google: {
102
- clientId: 'YOUR_GOOGLE_CLIENT_ID',
103
- },
104
- apple: {
105
- clientId: 'YOUR_APPLE_CLIENT_ID',
106
- redirectUri: 'YOUR_REDIRECT_URI',
107
- },
108
- },
109
- });
110
-
111
- // Sign in
112
- const result = await auth.signIn('google');
113
- console.log('Welcome', result.user.displayName);
114
-
115
- // Listen to auth state changes
116
- auth.onAuthStateChange((state) => {
117
- console.log('User:', state.user);
118
- console.log('Authenticated:', state.isAuthenticated);
119
- });
120
-
121
- // Sign out
122
- await auth.signOut();
123
- ```
124
-
125
- ### React Usage
126
-
127
- ```tsx
128
- import { useAuth } from 'capacitor-auth-manager/react';
129
-
130
- function LoginButton() {
131
- const { user, signIn, signOut, isLoading } = useAuth();
132
-
133
- if (isLoading) return <div>Loading...</div>;
134
-
135
- if (user) {
136
- return (
137
- <div>
138
- <p>Welcome, {user.displayName}!</p>
139
- <button onClick={() => signOut()}>Sign Out</button>
140
- </div>
141
- );
142
- }
143
-
144
- return <button onClick={() => signIn('google')}>Sign In with Google</button>;
145
- }
146
- ```
147
-
148
- No providers or context wrappers needed! Just import and use.
149
-
150
- ### Vue 3 Usage
151
-
152
- ```vue
153
- <script setup>
154
- import { useAuth } from 'capacitor-auth-manager/vue';
155
-
156
- const { user, signIn, signOut, isLoading } = useAuth();
157
- </script>
158
-
159
- <template>
160
- <div v-if="isLoading">Loading...</div>
161
- <div v-else-if="user">
162
- <p>Welcome, {{ user.displayName }}!</p>
163
- <button @click="signOut">Sign Out</button>
164
- </div>
165
- <button
166
- v-else
167
- @click="signIn('google')"
168
- >
169
- Sign In with Google
170
- </button>
171
- </template>
172
- ```
173
-
174
- ### Angular Usage
175
-
176
- ```typescript
177
- import { Component } from '@angular/core';
178
- import { AuthService } from 'capacitor-auth-manager/angular';
179
-
180
- @Component({
181
- selector: 'app-login',
182
- template: `
183
- <div *ngIf="authService.isLoading$ | async">Loading...</div>
184
- <div *ngIf="authService.user$ | async as user">
185
- <p>Welcome, {{ user.displayName }}!</p>
186
- <button (click)="signOut()">Sign Out</button>
187
- </div>
188
- <button
189
- *ngIf="!(authService.user$ | async)"
190
- (click)="signIn('google')"
191
- >
192
- Sign In with Google
193
- </button>
194
- `,
195
- })
196
- export class LoginComponent {
197
- constructor(public authService: AuthService) {}
198
-
199
- signIn(provider: string) {
200
- this.authService.signIn(provider).subscribe();
201
- }
202
-
203
- signOut() {
204
- this.authService.signOut().subscribe();
205
- }
206
- }
24
+ # then, for the native plugin:
25
+ npx cap sync
207
26
  ```
208
27
 
209
- ## Supported Providers
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.
210
30
 
211
- All 15 providers ship a web implementation (the primary path). The "Backend" column is the one to plan around — it states whether a provider completes sign-in in the browser or needs server-side support.
31
+ ## Provider support
212
32
 
213
- | Provider | Web | Backend required? |
214
- | ------------------- | --- | -------------------------------------------------- |
215
- | Google | ✅ | No (Google Identity Services manages PKCE) |
216
- | Apple | ✅ | No for sign-in; re-validate the ID token server-side |
217
- | Microsoft | ✅ | No (MSAL Browser, must be loaded on the page) |
218
- | Facebook | ✅ | No (Facebook JS SDK) |
219
- | GitHub | ✅ | **Yes** — set `tokenExchangeProxy`; no in-browser exchange |
220
- | Slack | ✅ | Optional — manual code flow + real profile fetch |
221
- | LinkedIn | ✅ | Optional — manual code flow + real profile fetch |
222
- | Firebase | ✅ | No (Firebase JS SDK) |
223
- | Email + Password | ✅ | Yes — credential verify/persist endpoint |
224
- | Phone + Password | ✅ | Yes — credential verify endpoint |
225
- | Username + Password | ✅ | Yes — credential verify (+ optional uniqueness) |
226
- | Email Code (OTP) | ✅ | Yes — send/verify endpoint |
227
- | SMS (OTP) | ✅ | Yes — Twilio / Firebase / custom backend |
228
- | Magic Link | ✅ | Yes — send/verify endpoints |
229
- | Biometric | ✅ | No — device-local; AES-GCM web fallback |
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`) |
230
37
 
231
- The implementation is strongest on the web/provider orchestration layer. The native Capacitor plugin (iOS/Android) is a secondary surface — validate any native flow against the platform code before relying on it. See [docs/api-reference/CAPABILITY_MATRIX.md](./docs/api-reference/CAPABILITY_MATRIX.md) for native status and full per-provider caveats.
38
+ ## Quick start
232
39
 
233
- ## Package Architecture
40
+ Configure once, then sign in. Use the exported **`AuthProvider` enum** (recommended — typo-safe; the plain
41
+ string `'google'` also works).
234
42
 
235
- - `src/core/` contains the auth manager, provider registry, platform helpers, and shared types.
236
- - `src/providers/web/` contains the provider implementations.
237
- - `src/react/`, `src/vue/`, and `src/angular/` expose framework-specific adapters on top of the same core auth manager.
238
- - `src/__tests__/` currently covers exported APIs, shared definitions, and selected provider/error flows with Vitest.
239
- - `docs/` contains setup, API reference, migration, and production-readiness notes.
240
-
241
- ## Configuration
242
-
243
- ### Complete Configuration Example
244
-
245
- ```typescript
246
- import { auth } from 'capacitor-auth-manager';
43
+ ```ts
44
+ import { auth, AuthProvider } from 'capacitor-auth-manager';
247
45
 
248
46
  auth.configure({
249
- // Provider configurations (field names match the typed *AuthOptions interfaces)
250
47
  providers: {
251
- google: {
252
- clientId: 'YOUR_CLIENT_ID',
253
- scopes: ['email', 'profile'],
254
- },
255
- apple: {
256
- clientId: 'YOUR_SERVICE_ID',
257
- redirectUri: 'https://your-app.com/auth/callback',
258
- },
259
- microsoft: {
260
- clientId: 'YOUR_CLIENT_ID',
261
- redirectUri: 'https://your-app.com/auth/callback',
262
- authority: 'https://login.microsoftonline.com/common',
263
- },
264
- facebook: {
265
- appId: 'YOUR_APP_ID',
266
- version: 'v18.0',
267
- },
268
- github: {
269
- clientId: 'YOUR_CLIENT_ID',
270
- redirectUri: 'YOUR_REDIRECT_URI',
271
- // Required: GitHub cannot exchange the code in-browser. This endpoint receives
272
- // { code, redirectUri, state } and returns GitHub's token JSON.
273
- tokenExchangeProxy: 'https://your-api.com/auth/github/token',
274
- },
275
- firebase: {
276
- apiKey: 'YOUR_API_KEY',
277
- authDomain: 'YOUR_AUTH_DOMAIN',
278
- projectId: 'YOUR_PROJECT_ID',
279
- appId: 'YOUR_APP_ID',
280
- defaultMethod: 'google', // fallback sub-method when none is specified
281
- },
282
- 'magic-link': {
283
- endpoint: 'https://your-api.com/magic-link',
284
- redirectUrl: 'https://your-app.com/auth/callback',
285
- },
286
- sms: {
287
- provider: 'twilio',
288
- twilioConfig: {
289
- accountSid: 'YOUR_SID',
290
- authToken: 'YOUR_TOKEN',
291
- fromNumber: '+1234567890',
292
- },
293
- },
294
- 'email-password': {
295
- strengthRequirements: {
296
- minLength: 8,
297
- requireUppercase: true,
298
- requireNumbers: true,
299
- },
300
- requireEmailVerification: true,
301
- },
302
- biometric: {
303
- title: 'Authentication Required',
304
- description: 'Authenticate to access your account',
305
- },
306
- slack: {
307
- clientId: 'YOUR_CLIENT_ID',
308
- redirectUri: 'https://your-app.com/auth/slack/callback',
309
- teamId: 'OPTIONAL_TEAM_ID', // Restrict to a specific workspace
310
- },
311
- linkedin: {
312
- clientId: 'YOUR_CLIENT_ID',
313
- redirectUri: 'https://your-app.com/auth/linkedin/callback',
314
- scopes: ['openid', 'profile', 'email'],
315
- },
316
- 'username-password': {
317
- usernameRequirements: {
318
- minLength: 3,
319
- maxLength: 20,
320
- },
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)
321
52
  },
322
53
  },
323
-
324
- // Optional secure storage on native (requires the optional @capacitor/preferences peer).
325
- // Default web storage is localStorage, which is readable by any XSS/3rd-party script.
326
- // storage: new CapacitorPreferencesStorage(),
327
-
328
- // Global options
329
- persistence: 'local', // 'local' | 'session' | 'memory'
330
- autoRefreshToken: true,
331
- tokenRefreshBuffer: 300000, // 5 minutes before expiry
332
- enableLogging: true,
333
- logLevel: 'debug', // 'debug' | 'info' | 'warn' | 'error'
334
- });
335
- ```
336
-
337
- ### Provider-Specific Setup
338
-
339
- Each provider may require additional setup. The package provides helpful error messages when dependencies are missing.
340
-
341
- ## Portfolio Info File
342
-
343
- For resume, portfolio, and social-content source material, use the root project file:
344
-
345
- - `CAPACITOR-AUTH-MANAGER_portfolio-info_2026-03-25.md`
346
-
347
- ## Framework-Specific APIs
348
-
349
- All three adapters surface the same account-management methods added in 2.2.0 (`linkAccount`, `unlinkAccount`, `revokeAccess`, `getIdToken`, `updateProfile`, `deleteAccount`).
350
-
351
- ### React Hooks
352
-
353
- - `useAuth()` - Complete authentication functionality
354
- - `useAuthState()` - Read-only authentication state
355
- - `useUser()` - Just the current user
356
- - `useToken()` - Access token management
357
- - `useIsAuthenticated()` - Boolean authentication status
358
-
359
- ### Vue 3 Composables
360
-
361
- - `useAuth()` - Complete authentication functionality with reactive refs
362
- - `useAuthState()` - Reactive auth state
363
- - `useUser()` - Reactive user ref
364
- - `useToken()` - Reactive token management
365
-
366
- ### Angular Service
367
-
368
- ```typescript
369
- import { AuthModule } from 'capacitor-auth-manager/angular';
370
-
371
- // In your app module
372
- imports: [
373
- AuthModule.forRoot({
374
- providers: {
375
- /* ... */
376
- },
377
- }),
378
- ];
379
- ```
380
-
381
- ## Advanced Usage
382
-
383
- ### Email Magic Link
384
-
385
- ```typescript
386
- import { auth } from 'capacitor-auth-manager';
387
-
388
- // Send the magic link. The user receives an email; verification completes on the
389
- // link-click page load (pending metadata is persisted so it survives the redirect).
390
- await auth.signIn({
391
- provider: 'magic-link',
392
- credentials: { email: 'user@example.com' },
54
+ persistence: 'local',
393
55
  });
394
- ```
395
-
396
- ### SMS Authentication
397
-
398
- ```typescript
399
- import { auth } from 'capacitor-auth-manager';
400
-
401
- // Send the SMS code
402
- await auth.signIn({
403
- provider: 'sms',
404
- credentials: { phoneNumber: '+1234567890' },
405
- });
406
-
407
- // Verify the SMS code
408
- await auth.signIn({
409
- provider: 'sms',
410
- credentials: { phoneNumber: '+1234567890', code: '123456' },
411
- });
412
- ```
413
56
 
414
- ### Email/Password
415
-
416
- Credentials are passed under `credentials` in the object form of `signIn`. The email/password provider requires a backend to verify and persist credentials.
417
-
418
- ```typescript
419
- import { auth } from 'capacitor-auth-manager';
420
-
421
- await auth.signIn({
422
- provider: 'email-password',
423
- credentials: { email: 'user@example.com', password: 'secure-password' },
424
- });
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;
425
60
  ```
426
61
 
427
- ### Biometric Authentication
428
-
429
- The web fallback stores credential material encrypted with AES-GCM (non-extractable IndexedDB key). On native, biometric verification runs through the optional native plugin.
62
+ ### Hand the credential to Firebase (identical on every platform)
430
63
 
431
- ```typescript
432
- import { auth } from 'capacitor-auth-manager';
64
+ ```ts
65
+ import { getAuth, GoogleAuthProvider, signInWithCredential } from 'firebase/auth';
433
66
 
434
- // Sign in with biometrics (after the provider is configured and credentials are stored)
435
- await auth.signIn('biometric');
67
+ const result = await auth.signIn(AuthProvider.GOOGLE);
68
+ await signInWithCredential(
69
+ getAuth(),
70
+ GoogleAuthProvider.credential(result.credential.idToken),
71
+ );
436
72
  ```
437
73
 
438
- ### Username/Password Authentication
74
+ ### React
439
75
 
440
- ```typescript
441
- import { auth } from 'capacitor-auth-manager';
76
+ ```tsx
77
+ import { useAuth, AuthProvider } from 'capacitor-auth-manager/react';
442
78
 
443
- await auth.signIn({
444
- provider: 'username-password',
445
- credentials: { username: 'johndoe', password: 'secure-password' },
446
- });
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
+ }
447
84
  ```
448
85
 
449
- ### Slack Authentication
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`.
450
89
 
451
- ```typescript
452
- // Sign in with Slack
453
- await auth.signIn('slack');
90
+ ## What you get back
454
91
 
455
- // Restrict to specific workspace
456
- auth.configure({
457
- providers: {
458
- slack: {
459
- clientId: 'YOUR_CLIENT_ID',
460
- redirectUri: 'YOUR_REDIRECT_URI',
461
- teamId: 'SPECIFIC_TEAM_ID', // Optional
462
- },
463
- },
464
- });
465
- ```
92
+ `signIn` resolves to an `AuthResult`:
466
93
 
467
- ### LinkedIn Authentication
468
-
469
- ```typescript
470
- // Sign in with LinkedIn
471
- await auth.signIn('linkedin');
472
-
473
- // Configure with scopes
474
- auth.configure({
475
- providers: {
476
- linkedin: {
477
- clientId: 'YOUR_CLIENT_ID',
478
- redirectUri: 'YOUR_REDIRECT_URI',
479
- scopes: ['openid', 'profile', 'email'],
480
- },
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
481
103
  },
482
- });
483
- ```
484
-
485
- ### Multiple Sign-In Options
486
-
487
- `signIn` accepts either a provider id string or a `SignInOptions` object. Provider-specific options go under `options`.
488
-
489
- ```typescript
490
- // Simple provider name
491
- await auth.signIn('google');
492
-
493
- // With scopes
494
- await auth.signIn({
495
- provider: 'google',
496
- options: { scopes: ['https://www.googleapis.com/auth/calendar'] },
497
- });
498
-
499
- // With login hint
500
- await auth.signIn({
501
- provider: 'google',
502
- options: { loginHint: 'user@example.com' },
503
- });
504
- ```
505
-
506
- ### Token Management
507
-
508
- `AuthState` exposes `{ user, isLoading, isAuthenticated, provider }` — it does not carry raw tokens. Read an ID token via `getIdToken()` and refresh via `refreshToken()`.
509
-
510
- ```typescript
511
- // Manual token refresh (provider-dependent)
512
- await auth.refreshToken();
513
-
514
- // Get a fresh ID token for server-side verification (provider-dependent).
515
- // Note: the library does NOT verify ID-token signatures client-side — verify on your server.
516
- const idToken = await auth.getIdToken({ forceRefresh: true });
517
-
518
- // Inspect current state
519
- const state = auth.getAuthState();
520
- console.log(state.isAuthenticated, state.provider, state.user?.email);
521
- ```
522
-
523
- ### Account Management (2.2.0)
524
-
525
- These delegate to the active provider; an unsupported provider throws `AuthErrorCode.OPERATION_NOT_ALLOWED`.
526
-
527
- ```typescript
528
- import { auth } from 'capacitor-auth-manager';
529
-
530
- await auth.linkAccount({ provider: 'facebook' });
531
- await auth.unlinkAccount({ provider: 'facebook' });
532
- await auth.updateProfile({ displayName: 'New Name' });
533
- await auth.revokeAccess();
534
- await auth.deleteAccount();
535
-
536
- // Inspect configuration
537
- auth.isProviderConfigured('google'); // boolean
538
- auth.getConfiguredProviders(); // string[]
104
+ }
539
105
  ```
540
106
 
541
- ### Secure Storage on Native (2.2.0)
542
-
543
- Default web storage is `localStorage` (readable by XSS). On native, inject `CapacitorPreferencesStorage` (requires the optional `@capacitor/preferences` peer) so tokens live in native key-value storage. Capacitor Preferences is not hardware-encrypted — for secrecy at rest, supply a Keychain/Keystore-backed `StorageInterface`.
544
-
545
- ```typescript
546
- import { auth, CapacitorPreferencesStorage } from 'capacitor-auth-manager';
547
-
548
- auth.configure({
549
- storage: new CapacitorPreferencesStorage(),
550
- providers: { google: { clientId: 'YOUR_CLIENT_ID' } },
551
- });
552
- ```
107
+ Per-platform token availability (honest):
553
108
 
554
- ## Examples
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).
555
114
 
556
- Check out the [examples](./examples) directory for complete applications:
115
+ For the Firebase `signInWithCredential` handoff, the **`idToken` is all you need** on every platform.
557
116
 
558
- - [Vanilla JavaScript](./examples/vanilla-js) - Pure JS implementation
559
- - [React Example](./examples/react) - React 18+ with TypeScript
560
- - [Vue 3 Example](./examples/vue) - Vue 3 Composition API
561
- - [Angular Example](./examples/angular) - Angular 16+ with standalone components
117
+ ## Native setup
562
118
 
563
- ## Migration from v1.x
119
+ ### Android
564
120
 
565
- ### Before (v1.x)
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).
566
126
 
567
- ```typescript
568
- // Required Capacitor
569
- import { CapacitorAuthManager } from 'capacitor-auth-manager';
127
+ No extra AndroidManifest permissions are required by this plugin.
570
128
 
571
- await CapacitorAuthManager.initialize({
572
- providers: [
573
- /* ... */
574
- ],
575
- });
129
+ ### iOS
576
130
 
577
- await CapacitorAuthManager.signIn({ provider: AuthProvider.GOOGLE });
578
- ```
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).
579
136
 
580
- ### After (v2.0)
137
+ ### Capacitor config
581
138
 
582
- ```typescript
583
- // Works without Capacitor
584
- import { auth } from 'capacitor-auth-manager';
139
+ You can also set the Google options in `capacitor.config` under the plugin block instead of `auth.configure`.
585
140
 
586
- auth.configure({
587
- providers: { google: { clientId: '...' } },
588
- });
141
+ ## Migrating from `@codetrix-studio/capacitor-google-auth`
589
142
 
590
- await auth.signIn('google');
591
- ```
143
+ ```ts
144
+ // before
145
+ await GoogleAuth.initialize({ clientId });
146
+ const u = await GoogleAuth.signIn();
147
+ await signInWithCredential(getAuth(), GoogleAuthProvider.credential(u.authentication.idToken));
592
148
 
593
- ## Why v2.0?
594
-
595
- 1. **No Context Providers** - Works like Zustand, cleaner component trees
596
- 2. **Framework Agnostic** - One package, multiple frameworks
597
- 3. **Better Tree-shaking** - Only pay for what you use
598
- 4. **Optional Capacitor** - Use in any web app
599
- 5. **All Providers Ready** - No more "coming soon"
600
-
601
- ## TypeScript Support
602
-
603
- Full TypeScript support with detailed types:
604
-
605
- ```typescript
606
- import type {
607
- AuthUser,
608
- AuthResult,
609
- SignInOptions,
610
- AuthState,
611
- AuthProvider,
612
- AuthCredential,
613
- AuthManagerConfig, // providers is Record<string, ProviderOptions> as of 2.2.0
614
- ProviderOptions,
615
- StorageInterface, // for custom secure-storage adapters
616
- } from 'capacitor-auth-manager';
617
-
618
- // Runtime exports include the auth singleton, storage backends, the logger, and helpers:
619
- import {
620
- auth,
621
- WebStorage,
622
- CapacitorPreferencesStorage,
623
- defaultLogger,
624
- AuthError,
625
- isAuthError,
626
- AuthProvider as AuthProviderEnum,
627
- AuthErrorCode,
628
- } from 'capacitor-auth-manager';
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));
629
154
  ```
630
155
 
631
- ## Platform Notes
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.
632
158
 
633
- ### Web
159
+ ## Configuration (`GoogleAuthOptions`)
634
160
 
635
- - All providers work without additional setup
636
- - Some providers (SMS, Magic Link, Email/Password) require backend services
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). |
637
170
 
638
- ### iOS
171
+ ## Security & storage
639
172
 
640
- - Requires Capacitor (`@capacitor/core` `^7` or `^8`) for native functionality; deployment target 14
641
- - Biometric auth requires Face ID/Touch ID capability
642
- - Some providers need URL schemes configuration
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.
643
180
 
644
- ### Android
181
+ ## Caveats
645
182
 
646
- - Requires Capacitor (`@capacitor/core` `^7` or `^8`) for native functionality
647
- - Biometric auth requires fingerprint hardware
648
- - Configure `AndroidManifest.xml` for OAuth redirects
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.
649
188
 
650
- ## Contributing
189
+ ## Contributing & support
651
190
 
652
- Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md).
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
653
195
 
654
196
  ## License
655
197
 
656
- MIT © [Ahsan Mahmood](https://github.com/aoneahsan)
198
+ [MIT](./LICENSE) © 2024–2026 Ahsan Mahmood
657
199
 
658
- ## Support
200
+ ## Links
659
201
 
660
- - 📧 Email: aoneahsan@gmail.com
661
- - 🐛 Issues: [GitHub Issues](https://github.com/aoneahsan/capacitor-auth-manager/issues)
662
- - 💬 Discussions: [GitHub Discussions](https://github.com/aoneahsan/capacitor-auth-manager/discussions)
202
+ - npm: https://www.npmjs.com/package/capacitor-auth-manager
203
+ - Repository: https://github.com/aoneahsan/capacitor-auth-manager