capacitor-auth-manager 1.1.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (161) hide show
  1. package/CapacitorAuthManager.podspec +1 -1
  2. package/Readme.md +495 -630
  3. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/AuthStorage.java +28 -0
  4. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/CapacitorAuthManager.java +109 -15
  5. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/FacebookAuthProvider.java +389 -0
  6. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/GoogleAuthProvider.java +353 -0
  7. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/MicrosoftAuthProvider.java +455 -0
  8. package/android/src/main/java/com/aoneahsan/capacitor_auth_manager/ProviderFactory.java +180 -0
  9. package/dist/angular.cjs.js +7017 -0
  10. package/dist/angular.cjs.js.map +1 -0
  11. package/dist/core.cjs.js +6663 -0
  12. package/dist/core.cjs.js.map +1 -0
  13. package/dist/esm/angular/auth.guard.d.ts +18 -0
  14. package/dist/esm/angular/auth.guard.js +82 -0
  15. package/dist/esm/angular/auth.guard.js.map +1 -0
  16. package/dist/esm/angular/auth.module.d.ts +18 -0
  17. package/dist/esm/angular/auth.module.js +56 -0
  18. package/dist/esm/angular/auth.module.js.map +1 -0
  19. package/dist/esm/angular/auth.service.d.ts +108 -0
  20. package/dist/esm/angular/auth.service.js +224 -0
  21. package/dist/esm/angular/auth.service.js.map +1 -0
  22. package/dist/esm/angular/index.d.ts +3 -0
  23. package/dist/esm/angular/index.js +4 -0
  24. package/dist/esm/angular/index.js.map +1 -0
  25. package/dist/esm/capacitor-plugin.d.ts +3 -0
  26. package/dist/esm/capacitor-plugin.js +7 -0
  27. package/dist/esm/capacitor-plugin.js.map +1 -0
  28. package/dist/esm/core/auth-manager.d.ts +93 -0
  29. package/dist/esm/core/auth-manager.js +557 -0
  30. package/dist/esm/core/auth-manager.js.map +1 -0
  31. package/dist/esm/core/index.d.ts +4 -0
  32. package/dist/esm/core/index.js +5 -0
  33. package/dist/esm/core/index.js.map +1 -0
  34. package/dist/esm/core/platform.d.ts +24 -0
  35. package/dist/esm/core/platform.js +100 -0
  36. package/dist/esm/core/platform.js.map +1 -0
  37. package/dist/esm/core/provider-manifests.d.ts +9 -0
  38. package/dist/esm/core/provider-manifests.js +471 -0
  39. package/dist/esm/core/provider-manifests.js.map +1 -0
  40. package/dist/esm/core/provider-registry.d.ts +39 -0
  41. package/dist/esm/core/provider-registry.js +197 -0
  42. package/dist/esm/core/provider-registry.js.map +1 -0
  43. package/dist/esm/core/types.d.ts +46 -0
  44. package/dist/esm/core/types.js +2 -0
  45. package/dist/esm/core/types.js.map +1 -0
  46. package/dist/esm/definitions.d.ts +81 -5
  47. package/dist/esm/definitions.js +42 -4
  48. package/dist/esm/definitions.js.map +1 -1
  49. package/dist/esm/index.d.ts +11 -5
  50. package/dist/esm/index.js +14 -7
  51. package/dist/esm/index.js.map +1 -1
  52. package/dist/esm/providers/base-provider.d.ts +6 -4
  53. package/dist/esm/providers/base-provider.js +34 -6
  54. package/dist/esm/providers/base-provider.js.map +1 -1
  55. package/dist/esm/providers/oauth-provider.d.ts +23 -2
  56. package/dist/esm/providers/oauth-provider.js +152 -33
  57. package/dist/esm/providers/oauth-provider.js.map +1 -1
  58. package/dist/esm/providers/provider-factory.d.ts +3 -1
  59. package/dist/esm/providers/provider-factory.js +30 -42
  60. package/dist/esm/providers/provider-factory.js.map +1 -1
  61. package/dist/esm/providers/web/apple-provider.d.ts +2 -1
  62. package/dist/esm/providers/web/apple-provider.js +52 -28
  63. package/dist/esm/providers/web/apple-provider.js.map +1 -1
  64. package/dist/esm/providers/web/biometric-provider.d.ts +61 -0
  65. package/dist/esm/providers/web/biometric-provider.js +365 -0
  66. package/dist/esm/providers/web/biometric-provider.js.map +1 -0
  67. package/dist/esm/providers/web/email-code-provider.d.ts +48 -0
  68. package/dist/esm/providers/web/email-code-provider.js +295 -0
  69. package/dist/esm/providers/web/email-code-provider.js.map +1 -0
  70. package/dist/esm/providers/web/email-password-provider.d.ts +55 -0
  71. package/dist/esm/providers/web/email-password-provider.js +430 -0
  72. package/dist/esm/providers/web/email-password-provider.js.map +1 -0
  73. package/dist/esm/providers/web/facebook-provider.d.ts +80 -0
  74. package/dist/esm/providers/web/facebook-provider.js +249 -0
  75. package/dist/esm/providers/web/facebook-provider.js.map +1 -0
  76. package/dist/esm/providers/web/firebase-provider.d.ts +22 -0
  77. package/dist/esm/providers/web/firebase-provider.js +338 -0
  78. package/dist/esm/providers/web/firebase-provider.js.map +1 -0
  79. package/dist/esm/providers/web/github-provider.d.ts +34 -0
  80. package/dist/esm/providers/web/github-provider.js +325 -0
  81. package/dist/esm/providers/web/github-provider.js.map +1 -0
  82. package/dist/esm/providers/web/google-provider.js +18 -14
  83. package/dist/esm/providers/web/google-provider.js.map +1 -1
  84. package/dist/esm/providers/web/index.d.ts +15 -0
  85. package/dist/esm/providers/web/index.js +17 -0
  86. package/dist/esm/providers/web/index.js.map +1 -0
  87. package/dist/esm/providers/web/linkedin-provider.d.ts +37 -0
  88. package/dist/esm/providers/web/linkedin-provider.js +178 -0
  89. package/dist/esm/providers/web/linkedin-provider.js.map +1 -0
  90. package/dist/esm/providers/web/magic-link-provider.d.ts +46 -0
  91. package/dist/esm/providers/web/magic-link-provider.js +312 -0
  92. package/dist/esm/providers/web/magic-link-provider.js.map +1 -0
  93. package/dist/esm/providers/web/microsoft-provider.d.ts +23 -0
  94. package/dist/esm/providers/web/microsoft-provider.js +236 -0
  95. package/dist/esm/providers/web/microsoft-provider.js.map +1 -0
  96. package/dist/esm/providers/web/phone-password-provider.d.ts +66 -0
  97. package/dist/esm/providers/web/phone-password-provider.js +438 -0
  98. package/dist/esm/providers/web/phone-password-provider.js.map +1 -0
  99. package/dist/esm/providers/web/slack-provider.d.ts +39 -0
  100. package/dist/esm/providers/web/slack-provider.js +175 -0
  101. package/dist/esm/providers/web/slack-provider.js.map +1 -0
  102. package/dist/esm/providers/web/sms-provider.d.ts +48 -0
  103. package/dist/esm/providers/web/sms-provider.js +308 -0
  104. package/dist/esm/providers/web/sms-provider.js.map +1 -0
  105. package/dist/esm/providers/web/username-password-provider.d.ts +62 -0
  106. package/dist/esm/providers/web/username-password-provider.js +433 -0
  107. package/dist/esm/providers/web/username-password-provider.js.map +1 -0
  108. package/dist/esm/react/hooks.d.ts +110 -0
  109. package/dist/esm/react/hooks.js +307 -0
  110. package/dist/esm/react/hooks.js.map +1 -0
  111. package/dist/esm/react/index.d.ts +2 -0
  112. package/dist/esm/react/index.js +3 -0
  113. package/dist/esm/react/index.js.map +1 -0
  114. package/dist/esm/react/types.d.ts +30 -0
  115. package/dist/esm/react/types.js +2 -0
  116. package/dist/esm/react/types.js.map +1 -0
  117. package/dist/esm/utils/auth-error.d.ts +7 -0
  118. package/dist/esm/utils/auth-error.js +38 -10
  119. package/dist/esm/utils/auth-error.js.map +1 -1
  120. package/dist/esm/utils/event-emitter.d.ts +7 -0
  121. package/dist/esm/utils/event-emitter.js +9 -3
  122. package/dist/esm/utils/event-emitter.js.map +1 -1
  123. package/dist/esm/utils/logger.d.ts +28 -1
  124. package/dist/esm/utils/logger.js +115 -1
  125. package/dist/esm/utils/logger.js.map +1 -1
  126. package/dist/esm/utils/pending-verification-store.d.ts +59 -0
  127. package/dist/esm/utils/pending-verification-store.js +103 -0
  128. package/dist/esm/utils/pending-verification-store.js.map +1 -0
  129. package/dist/esm/utils/storage.d.ts +33 -5
  130. package/dist/esm/utils/storage.js +77 -8
  131. package/dist/esm/utils/storage.js.map +1 -1
  132. package/dist/esm/vue/composables.d.ts +124 -0
  133. package/dist/esm/vue/composables.js +290 -0
  134. package/dist/esm/vue/composables.js.map +1 -0
  135. package/dist/esm/vue/index.d.ts +1 -0
  136. package/dist/esm/vue/index.js +2 -0
  137. package/dist/esm/vue/index.js.map +1 -0
  138. package/dist/esm/web.d.ts +32 -7
  139. package/dist/esm/web.js +254 -55
  140. package/dist/esm/web.js.map +1 -1
  141. package/dist/plugin.cjs.js +6625 -950
  142. package/dist/plugin.cjs.js.map +1 -1
  143. package/dist/plugin.js +6625 -950
  144. package/dist/plugin.js.map +1 -1
  145. package/dist/react.cjs.js +6972 -0
  146. package/dist/react.cjs.js.map +1 -0
  147. package/dist/vue.cjs.js +6955 -0
  148. package/dist/vue.cjs.js.map +1 -0
  149. package/ios/Plugin/AppleAuthProvider.swift +288 -0
  150. package/ios/Plugin/AuthStorage.swift +49 -1
  151. package/ios/Plugin/CapacitorAuthManager.swift +45 -23
  152. package/ios/Plugin/FacebookAuthProvider.swift +297 -0
  153. package/ios/Plugin/GitHubAuthProvider.swift +54 -0
  154. package/ios/Plugin/GoogleAuthProvider.swift +265 -0
  155. package/ios/Plugin/LinkedInAuthProvider.swift +63 -0
  156. package/ios/Plugin/MicrosoftAuthProvider.swift +315 -0
  157. package/ios/Plugin/Models.swift +4 -1
  158. package/ios/Plugin/OAuthWebProvider.swift +415 -0
  159. package/ios/Plugin/SlackAuthProvider.swift +108 -0
  160. package/package.json +106 -24
  161. package/scripts/configure.js +105 -61
package/Readme.md CHANGED
@@ -1,797 +1,662 @@
1
1
  # Capacitor Auth Manager
2
2
 
3
- A comprehensive authentication plugin for Capacitor that provides secure, type-safe, and framework-independent authentication implementations across Android, iOS, and Web platforms.
4
-
5
- ## 📚 Documentation
6
-
7
- - [**Installation Guide**](./docs/installation.md) - Get started with Capacitor Auth Manager
8
- - [**Configuration Options**](./docs/configuration.md) - Complete list of all configuration options
9
- - [**Provider Guides**](./docs/providers/) - Detailed setup guides for each authentication provider
10
- - [Google Auth](./docs/providers/google.md)
11
- - [Apple Auth](./docs/providers/apple.md)
12
- - [Microsoft Auth](./docs/providers/microsoft.md)
13
- - [Facebook Auth](./docs/providers/facebook.md)
14
- - [GitHub Auth](./docs/providers/github.md)
15
- - [And more...](./docs/providers/)
16
- - [**API Reference**](./docs/api/) - Complete API documentation
17
- - [**Examples**](./docs/examples/) - Sample implementations and use cases
18
- - [**Migration Guide**](./docs/migration.md) - Upgrading from previous versions
19
- - [**Troubleshooting**](./docs/troubleshooting.md) - Common issues and solutions
3
+ Universal authentication manager with 15 web providers. Framework-agnostic, works with React, Vue, Angular, and vanilla JS. Optional Capacitor support for mobile apps.
4
+
5
+ ## Current State
6
+
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
18
+
19
+ ## Supported Environments
20
+
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
20
58
 
21
59
  ## Features
22
60
 
23
- - 🔐 **13+ Authentication Providers**: Google, Apple, Microsoft, Facebook, GitHub, Slack, LinkedIn, Firebase, Email Magic Link, SMS, Email/Phone/Username + Password, Email Code, and Biometric Auth
24
- - 📱 **Cross-Platform**: Works seamlessly on iOS, Android, and Web
25
- - 🔄 **Subscribable Auth State**: Real-time authentication state updates
26
- - 🎯 **Type-Safe**: Full TypeScript support with comprehensive type definitions
27
- - 🏗️ **Framework Independent**: Works with any JavaScript framework
28
- - 🔒 **Secure**: Uses only official SDKs and follows security best practices
29
- - ⚡ **Performant**: Optimized for minimal overhead and fast authentication flows
30
- - 🔧 **Highly Configurable**: Each provider can be configured with all available options
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
31
69
 
32
- ## Installation
70
+ ## Verification Snapshot
33
71
 
34
72
  ```bash
35
- npm install capacitor-auth-manager
36
- npx cap sync
73
+ npm run test:run
74
+ npm run build
37
75
  ```
38
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
+
39
83
  ## Quick Start
40
84
 
41
- ```typescript
42
- import { CapacitorAuthManager, AuthProvider } from 'capacitor-auth-manager';
85
+ ### Installation
43
86
 
44
- // Initialize the auth manager
45
- await CapacitorAuthManager.initialize({
46
- providers: [
47
- {
48
- provider: AuthProvider.GOOGLE,
49
- options: {
50
- clientId: 'YOUR_GOOGLE_CLIENT_ID',
51
- scopes: ['email', 'profile']
52
- }
53
- },
54
- {
55
- provider: AuthProvider.APPLE,
56
- options: {
57
- clientId: 'YOUR_APPLE_CLIENT_ID',
58
- redirectUri: 'YOUR_REDIRECT_URI'
59
- }
60
- }
61
- ],
62
- persistence: 'local', // 'local' | 'session' | 'none'
63
- autoRefreshToken: true,
64
- enableLogging: true
65
- });
87
+ ```bash
88
+ npm install capacitor-auth-manager
89
+ # or
90
+ yarn add capacitor-auth-manager
91
+ ```
66
92
 
67
- // Sign in with Google
68
- const result = await CapacitorAuthManager.signIn({
69
- provider: AuthProvider.GOOGLE
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
+ },
70
109
  });
71
110
 
72
- console.log('Signed in user:', result.user);
111
+ // Sign in
112
+ const result = await auth.signIn('google');
113
+ console.log('Welcome', result.user.displayName);
73
114
 
74
115
  // Listen to auth state changes
75
- const listener = await CapacitorAuthManager.addAuthStateListener((user) => {
76
- console.log('Auth state changed:', user);
116
+ auth.onAuthStateChange((state) => {
117
+ console.log('User:', state.user);
118
+ console.log('Authenticated:', state.isAuthenticated);
77
119
  });
78
120
 
79
121
  // Sign out
80
- await CapacitorAuthManager.signOut();
122
+ await auth.signOut();
81
123
  ```
82
124
 
83
- ## Configuration
125
+ ### React Usage
84
126
 
85
- ### Platform-Specific Setup
86
-
87
- #### iOS Setup
88
-
89
- 1. Add required capabilities in Xcode:
90
- - Sign in with Apple (if using Apple Auth)
91
- - Keychain Sharing (for secure credential storage)
92
-
93
- 2. Update your `Info.plist`:
94
- ```xml
95
- <!-- For Google Sign-In -->
96
- <key>CFBundleURLTypes</key>
97
- <array>
98
- <dict>
99
- <key>CFBundleURLSchemes</key>
100
- <array>
101
- <string>YOUR_REVERSED_CLIENT_ID</string>
102
- </array>
103
- </dict>
104
- </array>
105
-
106
- <!-- For Facebook Login -->
107
- <key>FacebookAppID</key>
108
- <string>YOUR_FACEBOOK_APP_ID</string>
109
- <key>FacebookClientToken</key>
110
- <string>YOUR_FACEBOOK_CLIENT_TOKEN</string>
111
- <key>FacebookDisplayName</key>
112
- <string>YOUR_APP_NAME</string>
113
-
114
- <!-- For OAuth redirects -->
115
- <key>LSApplicationQueriesSchemes</key>
116
- <array>
117
- <string>fbapi</string>
118
- <string>fb-messenger-share-api</string>
119
- <string>fbauth2</string>
120
- <string>fbshareextension</string>
121
- </array>
122
- ```
127
+ ```tsx
128
+ import { useAuth } from 'capacitor-auth-manager/react';
129
+
130
+ function LoginButton() {
131
+ const { user, signIn, signOut, isLoading } = useAuth();
123
132
 
124
- #### Android Setup
133
+ if (isLoading) return <div>Loading...</div>;
125
134
 
126
- 1. Add to your `android/app/build.gradle`:
127
- ```gradle
128
- android {
129
- defaultConfig {
130
- manifestPlaceholders = [
131
- appAuthRedirectScheme: 'com.yourcompany.yourapp'
132
- ]
135
+ if (user) {
136
+ return (
137
+ <div>
138
+ <p>Welcome, {user.displayName}!</p>
139
+ <button onClick={() => signOut()}>Sign Out</button>
140
+ </div>
141
+ );
133
142
  }
143
+
144
+ return <button onClick={() => signIn('google')}>Sign In with Google</button>;
134
145
  }
135
146
  ```
136
147
 
137
- 2. Update your `AndroidManifest.xml`:
138
- ```xml
139
- <!-- For Google Sign-In -->
140
- <meta-data
141
- android:name="com.google.android.gms.auth.api.signin.GoogleSignInOptions"
142
- android:value="@string/default_web_client_id" />
143
-
144
- <!-- For Facebook Login -->
145
- <meta-data
146
- android:name="com.facebook.sdk.ApplicationId"
147
- android:value="@string/facebook_app_id"/>
148
- <meta-data
149
- android:name="com.facebook.sdk.ClientToken"
150
- android:value="@string/facebook_client_token"/>
151
- ```
148
+ No providers or context wrappers needed! Just import and use.
152
149
 
153
- #### Web Setup
150
+ ### Vue 3 Usage
154
151
 
155
- For web platform, make sure your redirect URIs are properly configured in each provider's console:
152
+ ```vue
153
+ <script setup>
154
+ import { useAuth } from 'capacitor-auth-manager/vue';
156
155
 
157
- - **Google**: Add your domain to authorized JavaScript origins
158
- - **Apple**: Configure your Service ID with proper domains and redirect URLs
159
- - **Facebook**: Add your domain to valid OAuth redirect URIs
160
- - **Microsoft**: Configure redirect URIs in Azure AD
156
+ const { user, signIn, signOut, isLoading } = useAuth();
157
+ </script>
161
158
 
162
- ## Authentication Providers
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
+ ```
163
173
 
164
- ### Google Authentication
174
+ ### Angular Usage
165
175
 
166
176
  ```typescript
167
- await CapacitorAuthManager.initialize({
168
- providers: [{
169
- provider: AuthProvider.GOOGLE,
170
- options: {
171
- clientId: 'YOUR_GOOGLE_CLIENT_ID',
172
- scopes: ['email', 'profile'],
173
- serverClientId: 'YOUR_SERVER_CLIENT_ID', // For Android
174
- offlineAccess: true, // To get refresh token
175
- hostedDomain: 'yourdomain.com', // Restrict to domain
176
- forceCodeForRefreshToken: true
177
- }
178
- }]
179
- });
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
+ }
180
202
 
181
- const result = await CapacitorAuthManager.signIn({
182
- provider: AuthProvider.GOOGLE,
183
- options: {
184
- loginHint: 'user@example.com', // Pre-fill email
185
- prompt: 'select_account' // Force account selection
203
+ signOut() {
204
+ this.authService.signOut().subscribe();
186
205
  }
187
- });
206
+ }
188
207
  ```
189
208
 
190
- ### Apple Authentication
209
+ ## Supported Providers
191
210
 
192
- ```typescript
193
- await CapacitorAuthManager.initialize({
194
- providers: [{
195
- provider: AuthProvider.APPLE,
196
- options: {
197
- clientId: 'YOUR_SERVICE_ID',
198
- redirectUri: 'https://yourapp.com/auth/callback',
199
- scopes: [AppleAuthScope.EMAIL, AppleAuthScope.NAME],
200
- usePopup: true,
201
- state: 'YOUR_STATE', // Optional state parameter
202
- nonce: 'YOUR_NONCE' // Optional nonce for security
203
- }
204
- }]
205
- });
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.
206
212
 
207
- const result = await CapacitorAuthManager.signIn({
208
- provider: AuthProvider.APPLE
209
- });
210
- ```
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 |
211
230
 
212
- ### Microsoft Authentication
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.
213
232
 
214
- ```typescript
215
- await CapacitorAuthManager.initialize({
216
- providers: [{
217
- provider: AuthProvider.MICROSOFT,
218
- options: {
219
- clientId: 'YOUR_AZURE_CLIENT_ID',
220
- tenantId: 'YOUR_TENANT_ID', // or 'common' for multi-tenant
221
- redirectUri: 'https://yourapp.com/auth/callback',
222
- scopes: ['openid', 'profile', 'email'],
223
- authority: 'https://login.microsoftonline.com/YOUR_TENANT_ID'
224
- }
225
- }]
226
- });
227
- ```
233
+ ## Package Architecture
228
234
 
229
- ### Firebase Authentication
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.
230
240
 
231
- ```typescript
232
- await CapacitorAuthManager.initialize({
233
- providers: [{
234
- provider: AuthProvider.FIREBASE,
235
- options: {
236
- apiKey: 'YOUR_FIREBASE_API_KEY',
237
- authDomain: 'your-app.firebaseapp.com',
238
- projectId: 'your-project-id',
239
- storageBucket: 'your-app.appspot.com',
240
- messagingSenderId: 'YOUR_SENDER_ID',
241
- appId: 'YOUR_APP_ID'
242
- }
243
- }]
244
- });
245
- ```
241
+ ## Configuration
246
242
 
247
- ### Email/Password Authentication
243
+ ### Complete Configuration Example
248
244
 
249
245
  ```typescript
250
- await CapacitorAuthManager.initialize({
251
- providers: [{
252
- provider: AuthProvider.EMAIL_PASSWORD,
253
- options: {
246
+ import { auth } from 'capacitor-auth-manager';
247
+
248
+ auth.configure({
249
+ // Provider configurations (field names match the typed *AuthOptions interfaces)
250
+ 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': {
254
295
  strengthRequirements: {
255
296
  minLength: 8,
256
297
  requireUppercase: true,
257
298
  requireNumbers: true,
258
- requireSpecialCharacters: true
259
299
  },
260
- allowPasswordReset: true,
261
- requireEmailVerification: true
262
- }
263
- }]
264
- });
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
+ },
321
+ },
322
+ },
265
323
 
266
- // Sign up
267
- const result = await CapacitorAuthManager.signIn({
268
- provider: AuthProvider.EMAIL_PASSWORD,
269
- credentials: {
270
- email: 'user@example.com',
271
- password: 'SecurePassword123!'
272
- }
273
- });
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(),
274
327
 
275
- // Password reset
276
- await CapacitorAuthManager.sendPasswordResetEmail({
277
- email: 'user@example.com'
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'
278
334
  });
279
335
  ```
280
336
 
281
- ### SMS Authentication
337
+ ### Provider-Specific Setup
282
338
 
283
- ```typescript
284
- await CapacitorAuthManager.initialize({
285
- providers: [{
286
- provider: AuthProvider.SMS,
287
- options: {
288
- provider: 'twilio', // or 'firebase', 'custom'
289
- twilioConfig: {
290
- accountSid: 'YOUR_ACCOUNT_SID',
291
- authToken: 'YOUR_AUTH_TOKEN',
292
- fromNumber: '+1234567890'
293
- },
294
- codeLength: 6,
295
- codeExpiration: 300000, // 5 minutes
296
- maxAttempts: 3
297
- }
298
- }]
299
- });
339
+ Each provider may require additional setup. The package provides helpful error messages when dependencies are missing.
300
340
 
301
- // Send SMS code
302
- await CapacitorAuthManager.sendSmsCode({
303
- phoneNumber: '+1234567890'
304
- });
341
+ ## Portfolio Info File
305
342
 
306
- // Verify SMS code
307
- const result = await CapacitorAuthManager.verifySmsCode({
308
- phoneNumber: '+1234567890',
309
- code: '123456'
310
- });
311
- ```
343
+ For resume, portfolio, and social-content source material, use the root project file:
312
344
 
313
- ### Biometric Authentication
345
+ - `CAPACITOR-AUTH-MANAGER_portfolio-info_2026-03-25.md`
314
346
 
315
- Note: For biometric authentication, this plugin integrates with [capacitor-biometric-authentication](https://www.npmjs.com/package/capacitor-biometric-authentication).
347
+ ## Framework-Specific APIs
316
348
 
317
- ```typescript
318
- await CapacitorAuthManager.initialize({
319
- providers: [{
320
- provider: AuthProvider.BIOMETRIC,
321
- options: {
322
- fallbackToPasscode: true,
323
- title: 'Authenticate',
324
- subtitle: 'Use your biometric to sign in',
325
- description: 'Place your finger on the sensor',
326
- negativeButtonText: 'Cancel',
327
- maxAttempts: 3
328
- }
329
- }]
330
- });
349
+ All three adapters surface the same account-management methods added in 2.2.0 (`linkAccount`, `unlinkAccount`, `revokeAccess`, `getIdToken`, `updateProfile`, `deleteAccount`).
331
350
 
332
- const result = await CapacitorAuthManager.signIn({
333
- provider: AuthProvider.BIOMETRIC
334
- });
335
- ```
351
+ ### React Hooks
336
352
 
337
- ## API Reference
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
338
358
 
339
- ### Core Methods
359
+ ### Vue 3 Composables
340
360
 
341
- #### initialize(options)
342
- Initializes the auth manager with provider configurations.
361
+ - `useAuth()` - Complete authentication functionality with reactive refs
362
+ - `useAuthState()` - Reactive auth state
363
+ - `useUser()` - Reactive user ref
364
+ - `useToken()` - Reactive token management
343
365
 
344
- ```typescript
345
- interface AuthManagerInitOptions {
346
- providers: AuthProviderConfig[];
347
- persistence?: 'local' | 'session' | 'none';
348
- autoRefreshToken?: boolean;
349
- tokenRefreshBuffer?: number; // ms before token expiry
350
- enableLogging?: boolean;
351
- logLevel?: 'debug' | 'info' | 'warn' | 'error';
352
- }
353
- ```
354
-
355
- #### signIn(options)
356
- Signs in a user with the specified provider.
366
+ ### Angular Service
357
367
 
358
368
  ```typescript
359
- interface SignInOptions {
360
- provider: AuthProvider;
361
- credentials?: AuthCredentials;
362
- options?: SignInProviderOptions;
363
- }
364
- ```
365
-
366
- #### signOut(options?)
367
- Signs out the current user or a specific provider.
369
+ import { AuthModule } from 'capacitor-auth-manager/angular';
368
370
 
369
- ```typescript
370
- interface SignOutOptions {
371
- provider?: AuthProvider;
372
- revokeToken?: boolean;
373
- clearCache?: boolean;
374
- redirectUrl?: string;
375
- }
371
+ // In your app module
372
+ imports: [
373
+ AuthModule.forRoot({
374
+ providers: {
375
+ /* ... */
376
+ },
377
+ }),
378
+ ];
376
379
  ```
377
380
 
378
- #### getCurrentUser()
379
- Returns the currently authenticated user.
381
+ ## Advanced Usage
382
+
383
+ ### Email Magic Link
380
384
 
381
385
  ```typescript
382
- const user = await CapacitorAuthManager.getCurrentUser();
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' },
393
+ });
383
394
  ```
384
395
 
385
- #### addAuthStateListener(callback)
386
- Subscribes to authentication state changes.
396
+ ### SMS Authentication
387
397
 
388
398
  ```typescript
389
- const listener = await CapacitorAuthManager.addAuthStateListener((user) => {
390
- if (user) {
391
- console.log('User signed in:', user);
392
- } else {
393
- console.log('User signed out');
394
- }
399
+ import { auth } from 'capacitor-auth-manager';
400
+
401
+ // Send the SMS code
402
+ await auth.signIn({
403
+ provider: 'sms',
404
+ credentials: { phoneNumber: '+1234567890' },
395
405
  });
396
406
 
397
- // Remove listener
398
- await listener.remove();
407
+ // Verify the SMS code
408
+ await auth.signIn({
409
+ provider: 'sms',
410
+ credentials: { phoneNumber: '+1234567890', code: '123456' },
411
+ });
399
412
  ```
400
413
 
401
- #### refreshToken(options?)
402
- Manually refreshes the authentication token.
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.
403
417
 
404
418
  ```typescript
405
- const result = await CapacitorAuthManager.refreshToken({
406
- provider: AuthProvider.GOOGLE,
407
- forceRefresh: true
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' },
408
424
  });
409
425
  ```
410
426
 
411
- ### Account Management
427
+ ### Biometric Authentication
412
428
 
413
- #### linkAccount(options)
414
- Links an additional authentication provider to the current user.
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.
415
430
 
416
431
  ```typescript
417
- await CapacitorAuthManager.linkAccount({
418
- provider: AuthProvider.GOOGLE
419
- });
432
+ import { auth } from 'capacitor-auth-manager';
433
+
434
+ // Sign in with biometrics (after the provider is configured and credentials are stored)
435
+ await auth.signIn('biometric');
420
436
  ```
421
437
 
422
- #### unlinkAccount(options)
423
- Unlinks an authentication provider from the current user.
438
+ ### Username/Password Authentication
424
439
 
425
440
  ```typescript
426
- await CapacitorAuthManager.unlinkAccount({
427
- provider: AuthProvider.GOOGLE
441
+ import { auth } from 'capacitor-auth-manager';
442
+
443
+ await auth.signIn({
444
+ provider: 'username-password',
445
+ credentials: { username: 'johndoe', password: 'secure-password' },
428
446
  });
429
447
  ```
430
448
 
431
- #### updateProfile(options)
432
- Updates the user's profile information.
449
+ ### Slack Authentication
433
450
 
434
451
  ```typescript
435
- await CapacitorAuthManager.updateProfile({
436
- displayName: 'John Doe',
437
- photoURL: 'https://example.com/photo.jpg'
452
+ // Sign in with Slack
453
+ await auth.signIn('slack');
454
+
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
+ },
438
464
  });
439
465
  ```
440
466
 
441
- #### deleteAccount(options?)
442
- Deletes the current user's account.
467
+ ### LinkedIn Authentication
443
468
 
444
469
  ```typescript
445
- await CapacitorAuthManager.deleteAccount({
446
- requireReauthentication: true
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
+ },
481
+ },
447
482
  });
448
483
  ```
449
484
 
450
- ### Utility Methods
485
+ ### Multiple Sign-In Options
451
486
 
452
- #### isSupported(options)
453
- Checks if a provider is supported on the current platform.
487
+ `signIn` accepts either a provider id string or a `SignInOptions` object. Provider-specific options go under `options`.
454
488
 
455
489
  ```typescript
456
- const result = await CapacitorAuthManager.isSupported({
457
- provider: AuthProvider.APPLE
458
- });
490
+ // Simple provider name
491
+ await auth.signIn('google');
459
492
 
460
- if (result.isSupported) {
461
- // Provider is available
462
- }
463
- ```
464
-
465
- #### getIdToken(options?)
466
- Gets the current ID token for the authenticated user.
493
+ // With scopes
494
+ await auth.signIn({
495
+ provider: 'google',
496
+ options: { scopes: ['https://www.googleapis.com/auth/calendar'] },
497
+ });
467
498
 
468
- ```typescript
469
- const token = await CapacitorAuthManager.getIdToken({
470
- forceRefresh: true
499
+ // With login hint
500
+ await auth.signIn({
501
+ provider: 'google',
502
+ options: { loginHint: 'user@example.com' },
471
503
  });
472
504
  ```
473
505
 
474
- ## Configuration Options
506
+ ### Token Management
475
507
 
476
- ### Global Configuration
477
-
478
- All configuration options available when initializing the auth manager:
508
+ `AuthState` exposes `{ user, isLoading, isAuthenticated, provider }` — it does not carry raw tokens. Read an ID token via `getIdToken()` and refresh via `refreshToken()`.
479
509
 
480
510
  ```typescript
481
- interface AuthManagerInitOptions {
482
- providers: AuthProviderConfig[]; // Required: Array of provider configurations
483
- persistence?: AuthPersistence; // 'local' | 'session' | 'none' (default: 'local')
484
- autoRefreshToken?: boolean; // Auto-refresh tokens before expiry (default: true)
485
- tokenRefreshBuffer?: number; // Ms before expiry to refresh (default: 300000 - 5 min)
486
- enableLogging?: boolean; // Enable debug logging (default: false)
487
- logLevel?: LogLevel; // 'debug' | 'info' | 'warn' | 'error' (default: 'info')
488
- }
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);
489
521
  ```
490
522
 
491
- ### Provider-Specific Options
523
+ ### Account Management (2.2.0)
492
524
 
493
- Each provider supports all options provided by their official SDKs:
525
+ These delegate to the active provider; an unsupported provider throws `AuthErrorCode.OPERATION_NOT_ALLOWED`.
494
526
 
495
- #### Google Auth Options
496
527
  ```typescript
497
- interface GoogleAuthOptions {
498
- clientId: string; // Required: Your Google Client ID
499
- serverClientId?: string; // Android: Server client ID for offline access
500
- scopes?: string[]; // OAuth scopes (default: ['openid', 'email', 'profile'])
501
- offlineAccess?: boolean; // Request refresh token (default: false)
502
- hostedDomain?: string; // Restrict to G Suite domain
503
- forceCodeForRefreshToken?: boolean; // Force auth code flow (default: false)
504
- }
505
- ```
528
+ import { auth } from 'capacitor-auth-manager';
506
529
 
507
- #### Apple Auth Options
508
- ```typescript
509
- interface AppleAuthOptions {
510
- clientId: string; // Required: Your Service ID
511
- redirectUri: string; // Required: Your redirect URI
512
- scopes?: AppleAuthScope[]; // [EMAIL, NAME] (default: [])
513
- usePopup?: boolean; // Use popup instead of redirect (default: true)
514
- state?: string; // OAuth state parameter
515
- nonce?: string; // OAuth nonce for security
516
- }
517
- ```
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();
518
535
 
519
- #### Microsoft Auth Options
520
- ```typescript
521
- interface MicrosoftAuthOptions {
522
- clientId: string; // Required: Your Azure AD Client ID
523
- redirectUri?: string; // Redirect URI (default: current URL)
524
- scopes?: string[]; // OAuth scopes
525
- tenantId?: string; // Azure AD tenant ID
526
- prompt?: string; // 'login' | 'consent' | 'select_account'
527
- loginHint?: string; // Pre-fill email
528
- domainHint?: string; // 'consumers' | 'organizations'
529
- responseType?: string; // OAuth response type
530
- responseMode?: string; // 'query' | 'fragment'
531
- codeChallenge?: string; // PKCE code challenge
532
- codeChallengeMethod?: string; // PKCE method
533
- state?: string; // OAuth state
534
- nonce?: string; // OAuth nonce
535
- }
536
+ // Inspect configuration
537
+ auth.isProviderConfigured('google'); // boolean
538
+ auth.getConfiguredProviders(); // string[]
536
539
  ```
537
540
 
538
- #### Facebook Auth Options
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
+
539
545
  ```typescript
540
- interface FacebookAuthOptions {
541
- appId: string; // Required: Your Facebook App ID
542
- permissions?: string[]; // Facebook permissions
543
- version?: string; // API version (default: 'v12.0')
544
- loginBehavior?: string; // iOS: 'browser' | 'native' | 'system'
545
- limitedLogin?: boolean; // iOS 14.5+: Use limited login
546
- nonce?: string; // Security nonce
547
- }
546
+ import { auth, CapacitorPreferencesStorage } from 'capacitor-auth-manager';
547
+
548
+ auth.configure({
549
+ storage: new CapacitorPreferencesStorage(),
550
+ providers: { google: { clientId: 'YOUR_CLIENT_ID' } },
551
+ });
548
552
  ```
549
553
 
550
- #### Sign In Options
554
+ ## Examples
551
555
 
552
- Additional options available when calling `signIn()`:
556
+ Check out the [examples](./examples) directory for complete applications:
553
557
 
554
- ```typescript
555
- interface SignInProviderOptions {
556
- scopes?: string[]; // Override default scopes
557
- customParameters?: Record<string, string>; // Provider-specific parameters
558
- loginHint?: string; // Pre-fill username/email
559
- prompt?: string; // UI behavior
560
- display?: string; // UI display mode
561
- accessType?: string; // 'online' | 'offline'
562
- includeGrantedScopes?: boolean; // Include previously granted scopes
563
- state?: string; // OAuth state
564
- nonce?: string; // OAuth nonce
565
- pkceEnabled?: boolean; // Enable PKCE (default: true where supported)
566
- }
567
- ```
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
562
+
563
+ ## Migration from v1.x
568
564
 
569
- ### Complete Example with All Options
565
+ ### Before (v1.x)
570
566
 
571
567
  ```typescript
568
+ // Required Capacitor
569
+ import { CapacitorAuthManager } from 'capacitor-auth-manager';
570
+
572
571
  await CapacitorAuthManager.initialize({
573
- // Global options
574
- persistence: 'local',
575
- autoRefreshToken: true,
576
- tokenRefreshBuffer: 300000,
577
- enableLogging: true,
578
- logLevel: 'debug',
579
-
580
- // Provider configurations
581
572
  providers: [
582
- {
583
- provider: AuthProvider.GOOGLE,
584
- options: {
585
- clientId: 'YOUR_GOOGLE_CLIENT_ID',
586
- serverClientId: 'YOUR_SERVER_CLIENT_ID',
587
- scopes: ['email', 'profile', 'https://www.googleapis.com/auth/calendar'],
588
- offlineAccess: true,
589
- hostedDomain: 'company.com',
590
- forceCodeForRefreshToken: true
591
- }
592
- },
593
- {
594
- provider: AuthProvider.APPLE,
595
- options: {
596
- clientId: 'com.company.service',
597
- redirectUri: 'https://company.com/auth/callback',
598
- scopes: [AppleAuthScope.EMAIL, AppleAuthScope.NAME],
599
- usePopup: true,
600
- state: crypto.randomUUID(),
601
- nonce: crypto.randomUUID()
602
- }
603
- },
604
- {
605
- provider: AuthProvider.MICROSOFT,
606
- options: {
607
- clientId: 'YOUR_AZURE_CLIENT_ID',
608
- redirectUri: 'https://company.com/auth/callback',
609
- scopes: ['openid', 'profile', 'email', 'User.Read'],
610
- tenantId: 'YOUR_TENANT_ID',
611
- prompt: 'select_account',
612
- responseType: 'code',
613
- responseMode: 'query',
614
- codeChallenge: 'YOUR_CODE_CHALLENGE',
615
- codeChallengeMethod: 'S256'
616
- }
617
- }
618
- ]
573
+ /* ... */
574
+ ],
619
575
  });
620
576
 
621
- // Sign in with custom options
622
- const result = await CapacitorAuthManager.signIn({
623
- provider: AuthProvider.GOOGLE,
624
- options: {
625
- scopes: ['email', 'profile', 'https://www.googleapis.com/auth/drive'],
626
- loginHint: 'user@company.com',
627
- prompt: 'consent',
628
- accessType: 'offline',
629
- includeGrantedScopes: true,
630
- customParameters: {
631
- 'approval_prompt': 'force'
632
- }
633
- }
634
- });
577
+ await CapacitorAuthManager.signIn({ provider: AuthProvider.GOOGLE });
635
578
  ```
636
579
 
637
- ## Error Handling
638
-
639
- The plugin provides detailed error codes for different scenarios:
580
+ ### After (v2.0)
640
581
 
641
582
  ```typescript
642
- try {
643
- await CapacitorAuthManager.signIn({
644
- provider: AuthProvider.GOOGLE
645
- });
646
- } catch (error) {
647
- switch (error.code) {
648
- case 'auth/user-cancelled':
649
- // User cancelled the sign-in flow
650
- break;
651
- case 'auth/network-error':
652
- // Network error occurred
653
- break;
654
- case 'auth/invalid-credentials':
655
- // Invalid credentials provided
656
- break;
657
- case 'auth/popup-blocked':
658
- // Popup was blocked by browser
659
- break;
660
- default:
661
- // Other error
662
- console.error('Auth error:', error);
663
- }
664
- }
665
- ```
666
-
667
- ## Security Considerations
583
+ // Works without Capacitor
584
+ import { auth } from 'capacitor-auth-manager';
668
585
 
669
- 1. **Client IDs and Secrets**: Never expose client secrets in your client-side code
670
- 2. **Token Storage**: Tokens are securely stored using platform-specific secure storage
671
- 3. **HTTPS Required**: Always use HTTPS in production for web implementations
672
- 4. **Validate Tokens**: Always validate tokens on your backend before trusting them
673
- 5. **Biometric Security**: Biometric data never leaves the device
586
+ auth.configure({
587
+ providers: { google: { clientId: '...' } },
588
+ });
674
589
 
675
- ## Migration Guide
590
+ await auth.signIn('google');
591
+ ```
676
592
 
677
- If you're migrating from other authentication solutions:
593
+ ## Why v2.0?
678
594
 
679
- ### From Firebase Auth
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"
680
600
 
681
- ```typescript
682
- // Before (Firebase Auth)
683
- import { getAuth, signInWithPopup, GoogleAuthProvider } from 'firebase/auth';
684
- const auth = getAuth();
685
- const provider = new GoogleAuthProvider();
686
- const result = await signInWithPopup(auth, provider);
687
-
688
- // After (Capacitor Auth Manager)
689
- import { CapacitorAuthManager, AuthProvider } from 'capacitor-auth-manager';
690
- const result = await CapacitorAuthManager.signIn({
691
- provider: AuthProvider.GOOGLE
692
- });
693
- ```
601
+ ## TypeScript Support
694
602
 
695
- ### From Capacitor Google Auth
603
+ Full TypeScript support with detailed types:
696
604
 
697
605
  ```typescript
698
- // Before
699
- import { GoogleAuth } from '@codetrix-studio/capacitor-google-auth';
700
- await GoogleAuth.initialize();
701
- const user = await GoogleAuth.signIn();
702
-
703
- // After
704
- import { CapacitorAuthManager, AuthProvider } from 'capacitor-auth-manager';
705
- await CapacitorAuthManager.initialize({
706
- providers: [{
707
- provider: AuthProvider.GOOGLE,
708
- options: { clientId: 'YOUR_CLIENT_ID' }
709
- }]
710
- });
711
- const result = await CapacitorAuthManager.signIn({
712
- provider: AuthProvider.GOOGLE
713
- });
714
- ```
715
-
716
- ## 📚 Documentation
717
-
718
- For comprehensive documentation, examples, and guides, visit our [Documentation](./docs/README.md):
719
-
720
- ### 🚀 Getting Started
721
- - [Installation Guide](./docs/getting-started/installation.md) - Step-by-step setup instructions
722
- - [Quick Start](./docs/getting-started/quick-start.md) - Get up and running in minutes
723
- - [Platform Setup](./docs/getting-started/platform-setup.md) - Platform-specific configuration
724
-
725
- ### 🔧 API Reference
726
- - [Core API](./docs/api-reference/core-api.md) - Complete method reference
727
- - [Authentication State](./docs/api-reference/auth-state.md) - Understanding auth state
728
- - [Error Handling](./docs/api-reference/error-handling.md) - Handle errors gracefully
729
-
730
- ### 🏢 Provider Guides
731
- - [Google Auth](./docs/providers/google.md) - Google Sign-In implementation
732
- - [Apple Auth](./docs/providers/apple.md) - Sign in with Apple
733
- - [Facebook Auth](./docs/providers/facebook.md) - Facebook Login
734
- - [Microsoft Auth](./docs/providers/microsoft.md) - Microsoft identity platform
735
- - [GitHub Auth](./docs/providers/github.md) - GitHub OAuth
736
- - [Firebase Auth](./docs/providers/firebase.md) - Firebase Authentication
737
- - [More providers...](./docs/providers/) - All 13+ supported providers
738
-
739
- ### 💡 Framework Examples
740
- - [React Integration](./docs/examples/react.md) - Complete React implementation
741
- - [Angular Example](./docs/examples/angular.md) - Angular integration
742
- - [Vue Example](./docs/examples/vue.md) - Vue.js implementation
743
- - [Ionic Example](./docs/examples/ionic.md) - Ionic Framework integration
744
-
745
- ### 📖 Advanced Guides
746
- - [Best Practices](./docs/guides/best-practices.md) - Authentication best practices
747
- - [Security Guide](./docs/guides/security.md) - Security considerations
748
- - [Token Management](./docs/guides/token-management.md) - Handling tokens
749
- - [Multi-Factor Auth](./docs/guides/mfa.md) - Implementing MFA
750
-
751
- ## Platform Compatibility
752
-
753
- ### Supported Platforms
754
-
755
- | Provider | iOS | Android | Web |
756
- |----------|-----|---------|-----|
757
- | Google | ✅ | ✅ | ✅ |
758
- | Apple | ✅ | ✅ | ✅ |
759
- | Microsoft | ✅ | ✅ | ✅ |
760
- | Facebook | ✅ | ✅ | ✅ |
761
- | GitHub | ✅ | ✅ | ✅ |
762
- | Slack | ✅ | ✅ | ✅ |
763
- | LinkedIn | ✅ | ✅ | ✅ |
764
- | Firebase | ✅ | ✅ | ✅ |
765
- | Email Magic Link | ✅ | ✅ | ✅ |
766
- | SMS | ✅ | ✅ | ✅ |
767
- | Email/Phone/Username + Password | ✅ | ✅ | ✅ |
768
- | Email Code | ✅ | ✅ | ✅ |
769
- | Biometric | ✅ | ✅ | ❌ |
770
-
771
- ### Platform Requirements
772
-
773
- - **iOS**: iOS 13.0+
774
- - **Android**: Android 5.0 (API 21)+
775
- - **Web**: Modern browsers with ES2017 support
776
-
777
- ### Capacitor Version
778
-
779
- - Capacitor 7.0.0+
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';
629
+ ```
630
+
631
+ ## Platform Notes
632
+
633
+ ### Web
634
+
635
+ - All providers work without additional setup
636
+ - Some providers (SMS, Magic Link, Email/Password) require backend services
637
+
638
+ ### iOS
639
+
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
643
+
644
+ ### Android
645
+
646
+ - Requires Capacitor (`@capacitor/core` `^7` or `^8`) for native functionality
647
+ - Biometric auth requires fingerprint hardware
648
+ - Configure `AndroidManifest.xml` for OAuth redirects
780
649
 
781
650
  ## Contributing
782
651
 
783
- Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
652
+ Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md).
784
653
 
785
654
  ## License
786
655
 
787
- MIT
656
+ MIT © [Ahsan Mahmood](https://github.com/aoneahsan)
788
657
 
789
658
  ## Support
790
659
 
791
660
  - 📧 Email: aoneahsan@gmail.com
792
661
  - 🐛 Issues: [GitHub Issues](https://github.com/aoneahsan/capacitor-auth-manager/issues)
793
662
  - 💬 Discussions: [GitHub Discussions](https://github.com/aoneahsan/capacitor-auth-manager/discussions)
794
-
795
- ## Credits
796
-
797
- Created by [Ahsan Mahmood](https://aoneahsan.com) - Open source for the community