central-auth-js-sdk 1.0.13 → 1.2.0

package/INTEGRATION_GUIDE.md

@@ -13,7 +13,13 @@ npm install central-auth-js-sdk
 Use in your app (with a bundler such as Vite, Webpack, or Parcel):
 
 ```javascript
-import { initializeAuth, startSignup, startLogin } from 'central-auth-js-sdk';
+import {
+  initializeAuth,
+  startSignup,
+  startLogin,
+  autoResumeOAuthFlow,
+  hasPendingOAuthRedirect,
+} from 'central-auth-js-sdk';
 import 'central-auth-js-sdk/styles.css';
 ```
 
@@ -37,6 +43,8 @@ You need:
 2. The **SDK CSS** loaded (so the UI looks correct).
 3. A call to **`startSignup`** or **`startLogin`** with at least `container` and **`env`** (which backend to use: `local`, `dev`, `staging`, or `prod`). **`appIdentifier`** is optional; include it only if your backend expects it for OAuth or login APIs.
 
+For **Google/Microsoft OAuth**, also call **`initializeAuth`** once with **`defaultContainer`** and **`autoResumeOAuth: true`** (default). After the user returns from the provider, the SDK mounts the correct step automatically — see [§ 12 OAuth redirect & auto-resume](#12-oauth-redirect--auto-resume).
+
 **Minimal signup example:**
 
 ```html
@@ -76,27 +84,37 @@ You need:
 
 | Function | Purpose |
 |----------|--------|
-| **`initializeAuth(config)`** | (Optional) Set default config once; `startSignup` / `startLogin` can override per call. |
+| **`initializeAuth(config)`** | (Optional) Set default config once; enables OAuth auto-resume when `defaultContainer` is set. |
 | **`startSignup(config)`** | Run the sign-up flow in the given container. |
 | **`startLogin(config)`** | Run the login flow in the given container. |
+| **`autoResumeOAuthFlow(config)`** | After Google/Microsoft redirect, mount login or signup from URL params. No-op if URL has no OAuth params. |
+| **`hasPendingOAuthRedirect()`** | Returns `true` when the current URL contains OAuth callback query params. |
+
+Lower-level helpers (optional): `parseOAuthRedirect()`, `getOAuthRedirectFlowType()`, `markOAuthRedirectPending()`, `OAUTH_PENDING_CLASS`.
 
-You can use **only** `startSignup` and `startLogin` and pass full config each time. Or call **`initializeAuth`** once and then call **`auth.startSignup({})`** / **`auth.startLogin({})`** so they use the stored defaults.
+You can use **only** `startSignup` and `startLogin` and pass full config each time. Or call **`initializeAuth`** once and then call **`auth.startSignup({})`** / **`auth.startLogin({})`** so they use the stored defaults. For social login, prefer **`initializeAuth`** with **`autoResumeOAuth: true`** so the post-OAuth page reload is handled automatically.
 
 ---
 
 ## 4. initializeAuth(config)
 
-Call once (e.g. at app load) to set defaults. Returns `{ startSignup, startLogin, getConfig }`.
+Call once (e.g. at app load) to set defaults. Returns `{ startSignup, startLogin, autoResumeOAuthFlow, hasPendingOAuthRedirect, getConfig }`.
+
+When **`autoResumeOAuth`** is `true` (default) and **`defaultContainer`** is set, the SDK automatically calls **`autoResumeOAuthFlow`** on page load if the URL contains OAuth callback params (e.g. after Google redirects back).
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `env` | string | `'local'` | Environment: `'local'` \| `'dev'` \| `'staging'` \| `'prod'`. SDK uses the predefined API URL for that env. |
 | `appIdentifier` | string | — | Optional. When provided, sent with OAuth and login-related API requests; omit to not send `app_identifier`. |
-| `defaultContainer` | string \| HTMLElement | — | Default container; can override in `startSignup` / `startLogin` |
+| `defaultContainer` | string \| HTMLElement | — | Default container; can override in `startSignup` / `startLogin`. **Required for OAuth auto-resume.** |
+| `autoResumeOAuth` | boolean | `true` | When `true` and `defaultContainer` is set, auto-mount login/signup after OAuth redirect. |
 | `loginMethods` | object | — | Default login methods (see Login config) |
 | `frsAsSecondFactor` | boolean | `false` | Default: require face verification after primary auth |
 | `enableFaceRegistration` | boolean | `true` | Whether sign-up includes face registration step |
+| `onContinue` | function | — | Default callback when user clicks Continue on success (see [§ 9](#9-returning-to-the-parent-application)) |
 | `onBack` | function | — | Default callback when user clicks ← Back on the first screen of signup/login (see [§ 9](#9-returning-to-the-parent-application)) |
+| `onLoginComplete` | function | — | Default login-complete callback |
+| `onSignupComplete` | function | — | Default signup-complete callback |
 
 **Environments:** The SDK uses only `env` to choose the API base URL:
 
@@ -116,12 +134,15 @@ const auth = initializeAuth({
   env: 'dev',  // uses https://central-auth-dev.soham.ai/apis
   appIdentifier: 'my-app',
   defaultContainer: '#auth-container',
+  autoResumeOAuth: true,
   loginMethods: {
     emailPassword: true,
     emailOtp: true,
     social: { google: true, microsoft: true },
   },
   frsAsSecondFactor: true,
+  onContinue: goToApp,
+  onBack: goToApp,
 });
 
 // Later:
@@ -268,7 +289,7 @@ Starts the **login flow**. If the parent enables **only one** login method, the
 | `env` | string | no | Environment: `'local'` \| `'dev'` \| `'staging'` \| `'prod'` (default from init or `'local'`) |
 | `appIdentifier` | string | no | Optional. When provided, sent with login/OAuth API requests; omit to not send. |
 | **`loginMethods`** | object | no | Which login methods are enabled (see below) |
-| `frsAsSecondFactor` | boolean | no | Require face verification after password/OTP/social |
+| `frsAsSecondFactor` | boolean | no | Require face verification after password/OTP/social (client-side). Domain-based 2FA from the backend is handled automatically — see [§ 12](#12-oauth-redirect--auto-resume). |
 | **`onSignUp()`** | function | no | Called when user clicks **Sign up** on the login screen (e.g. unmount login and start signup in the **same container**). |
 | **`onLoginComplete(payload)`** | function | no | Called **once** when login completes. `payload`: `identifier` + any fields from final API (e.g. `access_token`, `refresh_token`). |
 | **`onContinue()`** | function | no | Called when user clicks **Continue to application** on the success screen. |
@@ -288,6 +309,13 @@ Starts the **login flow**. If the parent enables **only one** login method, the
 
 **Email + FRS:** On the face capture screen, if the user has no webcam, they can click **“No webcam? Sign in with OTP instead”**. The SDK sends an OTP to the email they entered and switches to the OTP step so they can complete login without face capture. No extra configuration is required.
 
+**Phone face capture:** If the user has no webcam, they can click **“Use phone instead”** on the face screen. The SDK shows a QR code + PIN and polls the backend until a face image is captured on the phone.
+
+**Backend-driven 2FA (face as second factor):** When your backend requires face verification (e.g. domain policy for `@gmail.com`), it returns `two_factor_required: true` and a short-lived `fr_token`. The SDK shows the face capture screen and submits the image with `fr_token` to complete login. This applies to:
+
+- **Password / OTP login** — response from `POST /login/custom` or `POST /otp/verify`
+- **Google / Microsoft login** — query params on the OAuth redirect URL (see [§ 12](#12-oauth-redirect--auto-resume))
+
 **Example — single method (no method picker):**
 
 ```javascript
@@ -376,12 +404,26 @@ instance.unmount();
 ## 8. Getting tokens and details back
 
 - **Signup:** Pass **`onSignupComplete(payload)`**. The SDK calls it once when signup finishes. `payload` includes `email`, `mobile`, `userId` and whatever your **final signup API** returns (e.g. `access_token`, `refresh_token`). Your backend should return these in the final signup response (e.g. `POST /signup/fr/enroll`).
-- **Login:** Pass **`onLoginComplete(payload)`**. The SDK calls it once when login finishes. `payload` includes `identifier` and whatever your **final login API** returns (e.g. `access_token`, `refresh_token`). Your backend should return these in the final login response (e.g. `POST /login/custom`, `POST /otp/verify`, etc.).
+- **Login:** Pass **`onLoginComplete(payload)`**. The SDK calls it once when login finishes. `payload` includes `identifier` and whatever your **final login API** returns (e.g. `access_token`, `refresh_token`, `token`). Your backend should return these in the final login response (e.g. `POST /login/custom`, `POST /otp/verify`, `POST /login/google/fr/enroll`, etc.).
+- **OAuth login complete:** When the backend redirects with `token=...` (JWT) and no further steps, the SDK lands on the success screen and includes `token`, `email`, `user_id`, etc. in the payload passed to **`onLoginComplete`**.
 
 You can also read **`instance.getState()`** after the flow completes; it includes **`signupResult`** or **`loginResult`** (the raw final API response).
 
 ---
 
+## 8.1 Troubleshooting Callbacks
+
+If you are not receiving the `onLoginComplete` callback, check the following common issues:
+
+1. **Social Login (OAuth) Page Reloads:** Social login requires a full browser redirect. If you only pass `onLoginComplete` to `startLogin()`, it will be lost when the page reloads. You **must** pass `onLoginComplete` directly into `initializeAuth()` so the SDK can trigger it when it auto-resumes the OAuth flow.
+2. **Differing Payload Structures:** The `payload` object returned by `onLoginComplete(payload)` differs slightly depending on the method. 
+   - Standard logins (Password/OTP/FRS) return the exact API response (e.g. `payload.access_token`).
+   - Social Login returns URL params (e.g. `payload.token`). 
+   - Always check for both (e.g., `payload.token || payload.access_token`) to prevent undefined errors in your callback.
+3. **FRS Fallbacks:** If a user uses an FRS fallback ("Sign in with OTP instead" or "Use phone instead"), the SDK automatically handles the fallback and **still fires `onLoginComplete`** upon successful authentication. No separate callback handles these cases.
+
+---
+
 ## 9. Returning to the parent application
 
 The SDK does **not** automatically navigate your app when the user leaves auth. Your parent app is responsible for showing/hiding the auth container and routing the user back to your own UI. Use the callbacks below.
@@ -462,80 +504,67 @@ Returning to the parent app is **not automatic** beyond SDK unmount. Integrators
 ## 10. Full integration example
 
 ```javascript
-import { initializeAuth, startSignup, startLogin } from 'central-auth-js-sdk';
+import { initializeAuth } from 'central-auth-js-sdk';
 import 'central-auth-js-sdk/styles.css';
 
+let currentInstance = null;
+
+function goToApp() {
+  if (currentInstance) currentInstance.unmount();
+  currentInstance = null;
+  document.getElementById('auth-container').style.display = 'none';
+  document.getElementById('app-root').style.display = 'block';
+}
+
+function saveToken(token) {
+  if (token) localStorage.setItem('access_token', token);
+}
+
 const auth = initializeAuth({
   env: 'dev',
   appIdentifier: 'my-app',
   defaultContainer: '#auth-container',
+  autoResumeOAuth: true, // auto-mount after Google/Microsoft redirect
   loginMethods: {
     emailPassword: true,
     emailOtp: true,
     social: { google: true, microsoft: true },
     emailFrs: true,
   },
-  frsAsSecondFactor: false,
+  onLoginComplete(payload) {
+    saveToken(payload.token || payload.access_token);
+  },
+  onSignupComplete(payload) {
+    saveToken(payload.access_token);
+  },
+  onContinue: goToApp,
+  onBack: goToApp,
 });
 
-let currentInstance = null;
-
-function goToApp() {
-  if (currentInstance) currentInstance.unmount();
-  currentInstance = null;
-  document.getElementById('auth-container').style.display = 'none';
-  document.getElementById('app-root').style.display = 'block';
-}
-
 function showSignup() {
   if (currentInstance) currentInstance.unmount();
   document.getElementById('auth-container').style.display = 'block';
+  document.getElementById('app-root').style.display = 'none';
   currentInstance = auth.startSignup({
-    onSignupComplete(payload) {
-      saveToken(payload.access_token);
-      goToApp();
-    },
-    onContinue: goToApp,
-    onBack: goToApp,
-    onSwitchToLogin: showLoginFrs,
-  });
-}
-
-function showLoginFrs() {
-  if (currentInstance) currentInstance.unmount();
-  document.getElementById('auth-container').style.display = 'block';
-  currentInstance = auth.startLogin({
-    loginMethods: { emailFrs: true },
-    onLoginComplete(payload) {
-      saveToken(payload.access_token);
-      goToApp();
-    },
-    onContinue: goToApp,
-    onBack: goToApp,
-    onSignUp: showSignup,
+    onSwitchToLogin: () => showLogin({ emailFrs: true }),
   });
 }
 
 function showLogin(loginMethods = { emailPassword: true }) {
   if (currentInstance) currentInstance.unmount();
   document.getElementById('auth-container').style.display = 'block';
+  document.getElementById('app-root').style.display = 'none';
   currentInstance = auth.startLogin({
     loginMethods,
-    onLoginComplete(payload) {
-      saveToken(payload.access_token);
-      goToApp();
-    },
-    onContinue: goToApp,
-    onBack: goToApp,
     onSignUp: showSignup,
   });
 }
 
-function saveToken(token) {
-  if (token) localStorage.setItem('access_token', token);
+// If OAuth redirect params are present, initializeAuth already resumed the flow.
+// Otherwise show your normal entry point:
+if (!auth.hasPendingOAuthRedirect()) {
+  showLogin();
 }
-
-showLogin();
 ```
 
 ---
@@ -544,8 +573,137 @@ showLogin();
 
 - **CORS:** Your API must allow requests from your app’s origin (e.g. `Access-Control-Allow-Origin`).
 - **Signup:** The SDK calls your signup endpoints (e.g. `/signup/start`, `/signup/email/verify`, `/signup/fr/enroll`). The **final** response can include `access_token`, `refresh_token`, etc.; the SDK forwards them in `onSignupComplete(payload)` and `getState().signupResult`.
-- **Login:** The SDK calls your login endpoints (e.g. `/login/custom`, `/otp/verify`, `/login/email/fr`). The **final** response can include tokens; the SDK forwards them in `onLoginComplete(payload)` and `getState().loginResult`.
-- **OAuth:** For Google/Microsoft, configure your backend with the same redirect URI your app uses. The SDK reads `login_token` and `provider` from the URL after redirect and continues the flow.
+- **Login:** The SDK calls your login endpoints (e.g. `/login/custom`, `/otp/verify`, `/login/email/fr`, `/login/google/fr/enroll`). The **final** response can include tokens; the SDK forwards them in `onLoginComplete(payload)` and `getState().loginResult`.
+- **2FA (face verification):** When face verification is required, the backend returns (JSON body or OAuth redirect query params):
+
+  ```json
+  {
+    "success": true,
+    "two_factor_required": true,
+    "next_step": "FR_VERIFICATION",
+    "login_token": "...",
+    "fr_token": "...",
+    "fr_token_expires_in_s": 300,
+    "message": "Facial recognition verification required"
+  }
+  ```
+
+  The SDK shows the face capture screen and submits `fr_token` + face image to the appropriate endpoint (e.g. `POST /login/google/fr/enroll` for social, `POST /login/custom` with `fr_image` for password login).
+- **OAuth:** Start Google/Microsoft login with `redirect_uri` pointing to the page where your SDK loads. After auth, the backend **302-redirects** to that URL with query params — see [§ 12](#12-oauth-redirect--auto-resume). The SDK reads those params and continues the flow (face verification, success, or error). Same behavior for Microsoft OAuth.
 - **app_identifier:** When the parent app passes **`appIdentifier`**, the SDK sends it as `app_identifier` on login-related requests (e.g. `/login/custom`, `/login/email/fr`, OAuth start URLs, social mobile/FR). If the parent omits it, the SDK does not send the parameter.
 
 For endpoint details and request/response shapes, see **API_INTEGRATION.md** and your backend docs.
+
+---
+
+## 12. OAuth redirect & auto-resume
+
+Google and Microsoft login use a full-page redirect. When the user returns, the browser reloads your app with query params on the URL. **The SDK handles parsing, routing, and cleanup** — you do not need custom “if URL has `login_token` then …” logic in your app.
+
+### What the parent app must do
+
+1. Call **`initializeAuth({ defaultContainer, autoResumeOAuth: true, ... })`** once at app load, **or** call **`autoResumeOAuthFlow({ container, ... })`** when your app boots.
+2. Pass the same **`redirect_uri`** to OAuth start that your app uses as the return page (the SDK builds this as `window.location.origin + window.location.pathname` when the user clicks Google/Microsoft).
+3. Provide **`onContinue`**, **`onBack`**, and optionally **`onLoginComplete`** callbacks.
+
+The SDK does **not** navigate your main app UI automatically. Hide/show your app shell in those callbacks (see [§ 9](#9-returning-to-the-parent-application)).
+
+### Optional: reduce “home screen flash” after OAuth
+
+When OAuth params are detected, the SDK adds **`central-auth-oauth-pending`** to `<html>`. Hide your main UI while the SDK loads:
+
+```css
+html.central-auth-oauth-pending [data-central-auth-main] {
+  display: none !important;
+}
+html.central-auth-oauth-pending [data-central-auth-sdk] {
+  display: flex !important;
+}
+```
+
+Mark your main content with `data-central-auth-main` and your auth container wrapper with `data-central-auth-sdk`.
+
+For the earliest possible switch (before the SDK module loads), you can add a tiny inline script in `<head>` that sets the same class when OAuth params are present — the demo app uses this pattern.
+
+### Backend redirect examples
+
+After Google auth, the backend redirects to your `redirect_uri` with query params:
+
+**Login complete:**
+
+```
+https://yourapp.com/auth?success=true&provider=google&token=eyJ...&user_id=...&email=...&entity_domain=gmail.com&message=Login+successful
+```
+
+**2FA — face verification required:**
+
+```
+https://yourapp.com/auth?success=true&two_factor_required=true&provider=google&next_step=FR_VERIFICATION&login_token=...&fr_token=...&fr_token_expires_in_s=300&message=Facial+recognition+verification+required&user_id=...&entity_domain=gmail.com
+```
+
+**Signup — face enrollment required:**
+
+```
+https://yourapp.com/auth?success=true&provider=google&next_step=FR_ENROLLMENT&login_token=...&user_id=...&entity_domain=gmail.com&message=Facial+recognition+enrollment+required
+```
+
+**Signup — mobile verification:**
+
+```
+https://yourapp.com/auth?success=true&provider=google&next_step=MOBILE_VERIFICATION&login_token=...&user_id=...
+```
+
+**Error:**
+
+```
+https://yourapp.com/auth?success=false&provider=google&error=Entity+not+found+for+email+domain+gmail.com
+```
+
+### How the SDK routes each case
+
+| Redirect | SDK action |
+|----------|------------|
+| `two_factor_required=true` or `next_step=FR_VERIFICATION` | Login flow → **face capture** → `POST /login/{google\|microsoft}/fr/enroll` with `login_token`, `fr_token`, `fr_image` |
+| `token=...` (login complete) | Login flow → **success screen** → `onLoginComplete` with JWT |
+| `next_step=FR_ENROLLMENT` | Signup flow → **face enrollment** |
+| `next_step=MOBILE_VERIFICATION` | Signup flow → **mobile entry** |
+| `success=false` or `error=...` | Login flow → show error banner |
+| Params cleaned from URL | SDK removes OAuth query params via `history.replaceState` (no reload) |
+
+### End-to-end flow (Google login + 2FA)
+
+```
+User clicks "Continue with Google"
+  → GET /login/google/start?redirect_uri=...&app_identifier=...
+  → Google OAuth
+  → Backend 302 to your app with two_factor_required=true, login_token, fr_token, ...
+  → SDK auto-resumes (face capture screen)
+  → User captures face
+  → POST /login/google/fr/enroll
+  → Success screen
+  → User clicks Continue → onContinue() → your app
+```
+
+### Manual auto-resume (without initializeAuth)
+
+```javascript
+import { autoResumeOAuthFlow, hasPendingOAuthRedirect } from 'central-auth-js-sdk';
+
+if (hasPendingOAuthRedirect()) {
+  const resumed = autoResumeOAuthFlow({
+    container: '#auth-container',
+    env: 'dev',
+    appIdentifier: 'my-app',
+    onContinue: goToApp,
+    onBack: goToApp,
+  });
+  if (resumed) {
+    currentInstance = resumed.instance;
+    // resumed.flow is 'login' or 'signup'
+  }
+}
+```
+
+### Persist `env` across OAuth reload
+
+OAuth causes a **full page reload**, so in-memory state is lost. Store `env` (and `appIdentifier` if needed) in **`sessionStorage`** before redirecting to Google, and pass the same values to **`autoResumeOAuthFlow`** or **`initializeAuth`**. The demo app uses `sessionStorage` for this.

package/auth.js

@@ -4,12 +4,23 @@
  */
 
 import { resolveApiBaseUrl } from './core/env-config.js';
+import {
+  hasOAuthRedirect,
+  parseOAuthRedirect,
+  getOAuthRedirectFlowType,
+  markOAuthRedirectPending,
+  clearOAuthRedirectPendingMark,
+} from './core/oauth-redirect.js';
 import { mount } from './signup.js';
 import { mountLogin } from './login.js';
 
 /** Default configuration stored after initializeAuth() */
 let defaultConfig = {};
 
+const DEFAULT_SOCIAL_LOGIN_METHODS = {
+  social: { google: true, microsoft: true },
+};
+
 /**
  * Merge config with defaults. Passed config overrides defaults.
  * @param {Object} overrides - config passed to startSignup / startLogin
@@ -42,38 +53,99 @@ function resolveContainer(container) {
   return el && el.nodeType === 1 ? el : null;
 }
 
+/**
+ * Resume login or signup automatically after an OAuth redirect.
+ * No-op when the URL has no OAuth callback params.
+ *
+ * @param {Object} [config] - Merged with initializeAuth defaults
+ * @param {string|HTMLElement} [config.container] - Required unless defaultContainer was set in initializeAuth
+ * @returns {{ flow: 'login'|'signup', instance: Object }|null}
+ */
+export function autoResumeOAuthFlow(config = {}) {
+  if (!hasOAuthRedirect()) return null;
+
+  markOAuthRedirectPending();
+
+  const merged = mergeConfig(config);
+  const container = config.container ?? merged.defaultContainer;
+  const el = resolveContainer(container);
+  if (!el) {
+    console.warn('[Central Auth SDK] autoResumeOAuthFlow: container is required (pass config.container or set defaultContainer in initializeAuth)');
+    return null;
+  }
+
+  const redirect = parseOAuthRedirect();
+  const flowType = getOAuthRedirectFlowType(redirect) || 'login';
+
+  let instance = null;
+  if (flowType === 'signup') {
+    instance = startSignup({ ...config, container: el });
+  } else {
+    instance = startLogin({
+      ...config,
+      container: el,
+      loginMethods: config.loginMethods ?? merged.loginMethods ?? DEFAULT_SOCIAL_LOGIN_METHODS,
+    });
+  }
+
+  if (instance) {
+    clearOAuthRedirectPendingMark();
+    return { flow: flowType, instance };
+  }
+  return null;
+}
+
 /**
  * Initialize the SDK with optional default configuration.
  * Call this once (e.g. at app load) to set shared defaults; startSignup/startLogin can override per call.
  *
+ * When `autoResumeOAuth` is true (default) and `defaultContainer` is set, the SDK automatically
+ * mounts the correct flow after Google/Microsoft OAuth redirects back to your app.
+ *
  * @param {Object} config - Default static configuration
  * @param {string} [config.env='local'] - Environment: 'local' | 'dev' | 'staging' | 'prod' — SDK uses the predefined API URL for that env
  * @param {string} [config.appIdentifier] - Optional app identifier for OAuth / custom login; only sent when provided
  * @param {string|HTMLElement} [config.defaultContainer] - Default container for rendering (can be overridden in start*)
+ * @param {boolean} [config.autoResumeOAuth=true] - Auto-mount login/signup when OAuth redirect params are in the URL
  * @param {Object} [config.loginMethods] - Default enabled login methods (see startLogin)
  * @param {boolean} [config.frsAsSecondFactor] - Default for FRS as second factor (see startLogin)
  * @param {boolean} [config.enableFaceRegistration=true] - Whether sign-up flow includes face registration step
  * @param {Object} [config.theme] - Optional theme overrides (primaryColor, secondaryColor, backgroundColor, backgroundImage, cardColor, textColor, fontFamily, mode)
- * @returns {{ startSignup: Function, startLogin: Function, getConfig: Function }}
+ * @returns {{ startSignup: Function, startLogin: Function, autoResumeOAuthFlow: Function, hasPendingOAuthRedirect: Function, getConfig: Function }}
  */
 export function initializeAuth(config = {}) {
   defaultConfig = {
     env: 'local',
     appIdentifier: undefined,
     defaultContainer: null,
+    autoResumeOAuth: true,
     loginMethods: null,
     frsAsSecondFactor: false,
     enableFaceRegistration: true,
     theme: null,
     ...config,
   };
-  return {
-    startSignup: startSignup,
-    startLogin: startLogin,
+
+  const api = {
+    startSignup,
+    startLogin,
+    autoResumeOAuthFlow,
+    hasPendingOAuthRedirect: hasOAuthRedirect,
     getConfig() {
       return { ...defaultConfig };
     },
   };
+
+  if (defaultConfig.autoResumeOAuth !== false && defaultConfig.defaultContainer && hasOAuthRedirect()) {
+    const run = () => { autoResumeOAuthFlow({}); };
+    if (typeof document !== 'undefined' && document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', run, { once: true });
+    } else {
+      run();
+    }
+  }
+
+  return api;
 }
 
 /**
@@ -100,6 +172,7 @@ export function startSignup(config = {}) {
     return null;
   }
   const options = {
+    env: merged.env,
     apiBaseUrl: resolveApiBaseUrl(merged),
     appIdentifier: merged.appIdentifier,
     enableFaceRegistration: merged.enableFaceRegistration,
@@ -145,6 +218,7 @@ export function startLogin(config = {}) {
     return null;
   }
   const options = {
+    env: merged.env,
     apiBaseUrl: resolveApiBaseUrl(merged),
     appIdentifier: merged.appIdentifier,
     loginMethods: merged.loginMethods,

package/core/api.js

@@ -116,12 +116,13 @@ export function createApi(baseUrl = DEFAULT_BASE, options = {}) {
       return request('POST', '/login/google/mobile/verify', body);
     },
 
-    async googleFrEnroll(loginToken, frImageFile1, frImageFile2 = null, appIdentifier) {
+    async googleFrEnroll(loginToken, frImageFile1, frImageFile2 = null, appIdentifier, frToken = null) {
       const fd = new FormData();
       fd.append('login_token', loginToken);
       fd.append('fr_image', frImageFile1);
       fd.append('fr_image2', frImageFile2 || frImageFile1);
       if (appIdentifier) fd.append('app_identifier', appIdentifier);
+      if (frToken) fd.append('fr_token', frToken);
       return request('POST', '/login/google/fr/enroll', fd);
     },
 
@@ -137,19 +138,20 @@ export function createApi(baseUrl = DEFAULT_BASE, options = {}) {
       return request('POST', '/login/microsoft/mobile/verify', body);
     },
 
-    async microsoftFrEnroll(loginToken, frImageFile1, frImageFile2 = null, appIdentifier) {
+    async microsoftFrEnroll(loginToken, frImageFile1, frImageFile2 = null, appIdentifier, frToken = null) {
       const fd = new FormData();
       fd.append('login_token', loginToken);
       fd.append('fr_image', frImageFile1);
       fd.append('fr_image2', frImageFile2 || frImageFile1);
       if (appIdentifier) fd.append('app_identifier', appIdentifier);
+      if (frToken) fd.append('fr_token', frToken);
       return request('POST', '/login/microsoft/fr/enroll', fd);
     },
 
     // --- Login (custom, OTP, email+FR) ---
 
     /** POST /login/custom — Email or mobile + password; optional fr_image, fr_image2 for FRS. app_identifier only when provided. */
-    async loginCustom(identifier, password, appIdentifier, frImageFiles = null) {
+    async loginCustom(identifier, password, appIdentifier, frImageFiles = null, frToken = null) {
       const body = { identifier, password };
       if (appIdentifier) body.app_identifier = appIdentifier;
       if (frImageFiles && frImageFiles.length) {
@@ -157,6 +159,7 @@ export function createApi(baseUrl = DEFAULT_BASE, options = {}) {
         fd.append('identifier', identifier);
         fd.append('password', password);
         if (appIdentifier) fd.append('app_identifier', appIdentifier);
+        if (frToken) fd.append('fr_token', frToken);
         fd.append('fr_image', frImageFiles[0]);
         fd.append('fr_image2', frImageFiles[1] || frImageFiles[0]);
         return request('POST', '/login/custom', fd);
@@ -170,13 +173,14 @@ export function createApi(baseUrl = DEFAULT_BASE, options = {}) {
     },
 
     /** POST /otp/verify — optional frImageFiles for 2FA */
-    async otpVerify(identifier, domain, channel, otp, frImageFiles = null) {
+    async otpVerify(identifier, domain, channel, otp, frImageFiles = null, frToken = null) {
       if (frImageFiles && frImageFiles.length) {
         const fd = new FormData();
         fd.append('identifier', identifier);
         if (domain) fd.append('domain', domain);
         fd.append('channel', channel);
         fd.append('otp', otp);
+        if (frToken) fd.append('fr_token', frToken);
         fd.append('fr_image', frImageFiles[0]);
         fd.append('fr_image2', frImageFiles[1] || frImageFiles[0]);
         return request('POST', '/otp/verify', fd);

package/core/login-flow.js

@@ -112,9 +112,10 @@ export class LoginFlowController {
   }
 
   /** After social OAuth callback: we're in social flow, optionally at FRS */
-  setSocialCallback(provider) {
+  setSocialCallback(provider, { twoFactorRequired = false } = {}) {
     this.currentMethod = provider === 'microsoft' ? LOGIN_METHODS.SOCIAL_MICROSOFT : LOGIN_METHODS.SOCIAL_GOOGLE;
-    this.steps = getStepsForMethod(this.currentMethod, this.config.frsAsSecondFactor);
+    const useFrs = twoFactorRequired || this.config.frsAsSecondFactor;
+    this.steps = getStepsForMethod(this.currentMethod, useFrs);
     this.stepIndex = 0;
     this._notify();
   }

package/core/login-state.js

@@ -12,6 +12,9 @@ export class LoginStateManager {
       faceCapture: null,
       loginToken: null,
       socialProvider: null,
+      frToken: null,
+      frTokenExpiresInS: null,
+      twoFactorMessage: '',
       error: '',
     };
     this.listeners = new Set();