central-auth-js-sdk 1.0.12 → 1.0.14

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,26 +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:
 
@@ -115,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:
@@ -142,6 +164,7 @@ Starts the **sign-up flow** (email + name → verify → mobile → verify → p
 | `enableFaceRegistration` | boolean | no | Include face registration step (default from init or `true`) |
 | **`onSignupComplete(payload)`** | function | no | Called **once** when signup completes. `payload`: `email`, `mobile`, `userId` + 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. Use to unmount and redirect. |
+| **`onBack()`** | function | no | Called when user clicks **← Back** on the **first screen** of signup. Use to unmount the SDK and return to your app. See [§ 9](#9-returning-to-the-parent-application). |
 | **`onSwitchToLogin()`** | function | no | Called when user clicks **Sign in** (e.g. “Already have an account? Sign in”). Use to unmount signup and start the login flow in the **same container** (e.g. login + FRS). |
 
 **Returns:** `{ unmount, getState, getFlow, getCurrentStep }` or `null` if container is invalid.
@@ -163,6 +186,10 @@ const instance = startSignup({
     instance.unmount();
     redirectToDashboard();
   },
+  onBack() {
+    instance.unmount();
+    showYourAppScreen();
+  },
   onSwitchToLogin() {
     instance.unmount();
     startLogin({ container: '#auth-container', env: 'dev', appIdentifier: 'my-app', loginMethods: { emailFrs: true }, onContinue: goToApp, onSignUp: showSignup });
@@ -262,10 +289,11 @@ 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. |
+| **`onBack()`** | function | no | Called when user clicks **← Back** on the **first screen** of login. Use to unmount the SDK and return to your app. See [§ 9](#9-returning-to-the-parent-application). |
 
 **Login methods** (`loginMethods`):
 
@@ -281,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
@@ -298,6 +333,10 @@ startLogin({
     instance.unmount();
     redirectToApp();
   },
+  onBack() {
+    instance.unmount();
+    redirectToApp();
+  },
   onSignUp() {
     instance.unmount();
     startSignup({ container: '#auth-container', env: 'dev', appIdentifier: '...', onContinue: goToApp, onSwitchToLogin: showLoginFrs });
@@ -321,6 +360,7 @@ startLogin({
   frsAsSecondFactor: true,
   onLoginComplete(payload) { /* ... */ },
   onContinue() { /* ... */ },
+  onBack() { /* unmount + return to parent app */ },
   onSignUp() { /* ... */ },
 });
 ```
@@ -364,7 +404,8 @@ 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).
 
@@ -372,92 +413,145 @@ You can also read **`instance.getState()`** after the flow completes; it include
 
 ## 9. Returning to the parent application
 
-When the user clicks **Continue to application** on the success screen, the SDK calls **`onContinue()`** if you provided it. Use it to unmount the SDK and show your app (e.g. redirect or switch view):
+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.
+
+### Two kinds of “Back”
+
+| Where | What happens |
+|-------|----------------|
+| **First screen** (signup email entry, login method picker, or single-method identifier screen) | **← Back** calls **`onBack()`** — intended to leave auth and return to your app |
+| **Later steps** (password, OTP, face capture, etc.) | **← Back** goes to the **previous step inside the SDK** only. Does **not** call `onBack()` |
+
+The first-screen back button is always shown. What happens when it is clicked depends on whether you pass **`onBack`**.
+
+### If you omit `onBack`
+
+The SDK uses a **default**: it unmounts itself (removes its UI from the container and cleans up theme). It does **not** show your app’s main screen, change routes, or hide overlays — you must do that yourself if needed.
+
+### What the parent app should do (recommended)
+
+Define one helper (e.g. `returnToApp`) and pass it to **`onBack`** and usually **`onContinue`** as well:
+
+```javascript
+let authInstance = null;
+
+function returnToApp() {
+  if (authInstance) authInstance.unmount();
+  authInstance = null;
+  document.getElementById('auth-container').style.display = 'none';
+  document.getElementById('app-root').style.display = 'block';
+  // or: router.push('/'); window.history.back(); etc.
+}
+
+authInstance = startLogin({
+  container: '#auth-container',
+  env: 'dev',
+  loginMethods: { emailPassword: true },
+  onBack: returnToApp,
+  onContinue: returnToApp,
+  onLoginComplete(payload) {
+    saveToken(payload.access_token);
+    returnToApp();
+  },
+});
+```
+
+**Typical steps inside `returnToApp` (or equivalent):**
+
+1. Call **`instance.unmount()`** — removes SDK DOM and theme
+2. Clear your reference to the instance (`authInstance = null`)
+3. Hide the auth container and show your main app UI (or navigate with your router)
+
+You can set **`onBack`** once in **`initializeAuth({ onBack: returnToApp, ... })`** and reuse it in `startSignup` / `startLogin` (per-call config overrides defaults).
+
+### Success screen — `onContinue()`
+
+When the user clicks **Continue to application** on the success screen, the SDK calls **`onContinue()`** if you provided it. Use the same pattern as **`onBack`**: unmount the SDK and show your app:
 
 ```javascript
 onContinue() {
   instance.unmount();
   window.location.href = '/dashboard';
-  // or: showYourAppView();
+  // or: returnToApp();
 }
 ```
 
+### Summary
+
+| Callback | When it fires | Parent app action |
+|----------|---------------|-------------------|
+| **`onBack()`** | User clicks ← Back on **first screen** | Unmount SDK + return to your app UI |
+| **`onContinue()`** | User clicks Continue on **success screen** | Unmount SDK + enter your app (often same as `onBack`) |
+| *(none)* | First-screen back, if `onBack` omitted | SDK unmounts only; parent UI unchanged |
+
+Returning to the parent app is **not automatic** beyond SDK unmount. Integrators should pass **`onBack`** (and **`onContinue`**) to fully control navigation in their application.
+
 ---
 
 ## 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,
-    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,
-    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,
     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();
 ```
 
 ---
@@ -466,8 +560,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();

package/core/oauth-redirect.js

@@ -0,0 +1,106 @@
+/**
+ * Shared OAuth redirect handling for login and signup flows.
+ * Backend 302-redirects to redirect_uri with query params after Google/Microsoft auth.
+ */
+
+export const OAUTH_PARAM_KEYS = [
+  'success', 'provider', 'token', 'login_token', 'two_factor_required', 'fr_token',
+  'fr_token_expires_in_s', 'next_step', 'message', 'user_id', 'email', 'entity_domain', 'error',
+];
+
+export const OAUTH_PENDING_CLASS = 'central-auth-oauth-pending';
+
+/** @returns {boolean} True when the URL looks like an OAuth redirect callback */
+export function hasOAuthRedirect() {
+  if (typeof window === 'undefined' || !window.location) return false;
+  const params = new URLSearchParams(window.location.search);
+  return params.has('provider')
+    || params.has('login_token')
+    || params.has('token')
+    || params.has('success');
+}
+
+/**
+ * Parse OAuth redirect query params.
+ * @returns {Object|null} Parsed redirect payload
+ */
+export function parseOAuthRedirect() {
+  if (!hasOAuthRedirect()) return null;
+
+  const params = new URLSearchParams(window.location.search);
+  const provider = (params.get('provider') || '').toLowerCase();
+  const hasProvider = provider === 'google' || provider === 'microsoft';
+  const loginToken = params.get('login_token');
+  const token = params.get('token');
+  const successParam = params.get('success');
+  const error = params.get('error');
+  const nextStep = (params.get('next_step') || '').toUpperCase();
+
+  const shared = {
+    provider: hasProvider ? provider : 'google',
+    email: params.get('email'),
+    userId: params.get('user_id'),
+    entityDomain: params.get('entity_domain'),
+    message: params.get('message'),
+    nextStep,
+  };
+
+  if (successParam === 'false' || error) {
+    return { ...shared, kind: 'error', error: error || 'Login failed' };
+  }
+
+  const twoFactorRaw = params.get('two_factor_required');
+  const twoFactorRequired = twoFactorRaw === 'true' || twoFactorRaw === '1' || nextStep === 'FR_VERIFICATION';
+
+  if (loginToken) {
+    return {
+      ...shared,
+      kind: 'pending',
+      loginToken,
+      twoFactorRequired,
+      frToken: params.get('fr_token') || null,
+      frTokenExpiresInS: params.get('fr_token_expires_in_s') || null,
+    };
+  }
+
+  if (token) {
+    return { ...shared, kind: 'complete', token };
+  }
+
+  return null;
+}
+
+/** @param {ReturnType<parseOAuthRedirect>} redirect */
+export function getOAuthRedirectFlowType(redirect) {
+  if (!redirect) return null;
+  if (redirect.nextStep === 'FR_ENROLLMENT' || redirect.nextStep === 'MOBILE_VERIFICATION') {
+    return 'signup';
+  }
+  return 'login';
+}
+
+/** Remove OAuth params from the URL without reloading */
+export function clearOAuthRedirectParams() {
+  if (typeof window === 'undefined' || !window.history) return;
+  const params = new URLSearchParams(window.location.search);
+  OAUTH_PARAM_KEYS.forEach((key) => params.delete(key));
+  const clean = params.toString();
+  const url = window.location.pathname + (clean ? '?' + clean : '') + window.location.hash;
+  window.history.replaceState({}, '', url);
+}
+
+/**
+ * Mark the document while OAuth resume is pending (reduces parent-app flash).
+ * Parent apps can hide main UI with:
+ *   html.central-auth-oauth-pending [data-central-auth-main] { display: none !important; }
+ *   html.central-auth-oauth-pending [data-central-auth-sdk] { display: block !important; }
+ */
+export function markOAuthRedirectPending() {
+  if (!hasOAuthRedirect() || typeof document === 'undefined') return;
+  document.documentElement.classList.add(OAUTH_PENDING_CLASS);
+}
+
+export function clearOAuthRedirectPendingMark() {
+  if (typeof document === 'undefined') return;
+  document.documentElement.classList.remove(OAUTH_PENDING_CLASS);
+}

package/index.js

@@ -4,17 +4,31 @@
  * APIs wired to Central Auth (central_auth_collection.json)
  *
  * Public API for host applications:
- *   initializeAuth(config) — set default configuration
+ *   initializeAuth(config) — set default configuration (+ auto-resume OAuth when configured)
  *   startSignup(config)    — run sign-up flow in a container
- *   startLogin(config)    — run login flow in a container
+ *   startLogin(config)       — run login flow in a container
+ *   autoResumeOAuthFlow(config) — mount login/signup after OAuth redirect (no-op otherwise)
  *
  * Lower-level: mount (signup), mountLogin (login)
  */
 
+import { markOAuthRedirectPending } from './core/oauth-redirect.js';
+
+markOAuthRedirectPending();
+
 export { mount } from './signup.js';
 export { FlowController, STEPS } from './core/flow.js';
 export { StateManager } from './core/state.js';
 export { createApi, dataUrlToFile, base64ToFile } from './core/api.js';
 export { mountLogin } from './login.js';
-export { initializeAuth, startSignup, startLogin } from './auth.js';
+export { initializeAuth, startSignup, startLogin, autoResumeOAuthFlow } from './auth.js';
 export { applyTheme, THEME_PRESETS } from './theme.js';
+export {
+  hasOAuthRedirect,
+  hasOAuthRedirect as hasPendingOAuthRedirect,
+  parseOAuthRedirect,
+  getOAuthRedirectFlowType,
+  markOAuthRedirectPending,
+  clearOAuthRedirectPendingMark,
+  OAUTH_PENDING_CLASS,
+} from './core/oauth-redirect.js';

package/login.js

@@ -8,29 +8,24 @@ import { resolveApiBaseUrl } from './core/env-config.js';
 import { normalizeLoginConfig, getEnabledLoginMethods, LOGIN_METHODS } from './core/login-config.js';
 import { LoginFlowController, LOGIN_STEPS } from './core/login-flow.js';
 import { LoginStateManager } from './core/login-state.js';
+import { parseOAuthRedirect, clearOAuthRedirectParams, clearOAuthRedirectPendingMark } from './core/oauth-redirect.js';
 import { createLayout } from './ui/layout.js';
 import { createLoginScreen } from './ui/screens/login/index.js';
 import { applyTheme } from './theme.js';
 
-/** Parse OAuth callback (login_token, provider) from URL */
-function parseOAuthCallback() {
-  if (typeof window === 'undefined' || !window.location) return null;
-  const params = new URLSearchParams(window.location.search);
-  const loginToken = params.get('login_token');
-  const provider = (params.get('provider') || '').toLowerCase();
-  if (!loginToken) return null;
-  if (provider !== 'google' && provider !== 'microsoft') return { loginToken, provider: 'google' };
-  return { loginToken, provider };
+function isTwoFactorRequired(res) {
+  if (!res || typeof res !== 'object') return false;
+  if (res.two_factor_required === true) return true;
+  const step = String(res.next_step || '').toUpperCase();
+  return step === 'FR_VERIFICATION';
 }
 
-function clearOAuthParams() {
-  if (typeof window === 'undefined' || !window.history) return;
-  const params = new URLSearchParams(window.location.search);
-  params.delete('login_token');
-  params.delete('provider');
-  const clean = params.toString();
-  const url = window.location.pathname + (clean ? '?' + clean : '') + window.location.hash;
-  window.history.replaceState({}, '', url);
+function applyTwoFactorFromResponse(res, state) {
+  if (res.login_token) state.set('loginToken', res.login_token);
+  if (res.fr_token) state.set('frToken', res.fr_token);
+  if (res.fr_token_expires_in_s != null) state.set('frTokenExpiresInS', res.fr_token_expires_in_s);
+  if (res.provider) state.set('socialProvider', String(res.provider).toLowerCase());
+  if (res.message) state.set('twoFactorMessage', res.message);
 }
 
 /**
@@ -65,12 +60,36 @@ export function mountLogin(container, options = {}) {
   const cleanupTheme = applyTheme(layout.root, theme);
   const showError = (msg) => layout.showError(msg);
 
-  const oauth = parseOAuthCallback();
+  const oauth = parseOAuthRedirect();
   if (oauth) {
-    state.set('loginToken', oauth.loginToken);
-    state.set('socialProvider', oauth.provider);
-    clearOAuthParams();
-    flow.setSocialCallback(oauth.provider);
+    clearOAuthRedirectParams();
+    if (oauth.kind === 'error') {
+      state.set('error', oauth.error);
+    } else if (oauth.kind === 'complete') {
+      if (oauth.email) state.set('identifier', oauth.email);
+      const result = {
+        token: oauth.token,
+        user_id: oauth.userId,
+        email: oauth.email,
+        entity_domain: oauth.entityDomain,
+        message: oauth.message,
+        provider: oauth.provider,
+      };
+      state.set('loginResult', result);
+      flow.setSocialCallback(oauth.provider, { twoFactorRequired: false });
+      flow.setStep(LOGIN_STEPS.SUCCESS);
+      if (typeof onLoginComplete === 'function') {
+        onLoginComplete(buildLoginCompletePayload(result));
+      }
+    } else if (oauth.kind === 'pending') {
+      state.set('loginToken', oauth.loginToken);
+      state.set('socialProvider', oauth.provider);
+      if (oauth.email) state.set('identifier', oauth.email);
+      if (oauth.frToken) state.set('frToken', oauth.frToken);
+      if (oauth.frTokenExpiresInS) state.set('frTokenExpiresInS', oauth.frTokenExpiresInS);
+      if (oauth.message) state.set('twoFactorMessage', oauth.message);
+      flow.setSocialCallback(oauth.provider, { twoFactorRequired: oauth.twoFactorRequired });
+    }
   }
 
   const enabled = getEnabledLoginMethods(config);
@@ -104,6 +123,19 @@ export function mountLogin(container, options = {}) {
     return payload;
   }
 
+  function completeLogin(apiResult) {
+    state.set('loginResult', apiResult);
+    flow.goNext();
+    if (typeof onLoginComplete === 'function') {
+      onLoginComplete(buildLoginCompletePayload(apiResult));
+    }
+  }
+
+  function requireFaceVerification(res) {
+    applyTwoFactorFromResponse(res, state);
+    flow.injectFrsStep();
+  }
+
   async function handleIdentifierEmail(email) {
     state.clearError();
     state.set('identifier', email);
@@ -153,11 +185,11 @@ export function mountLogin(container, options = {}) {
     }
     try {
       const res = await api.loginCustom(identifier, password, config.appIdentifier, null);
-      state.set('loginResult', res);
-      flow.goNext();
-      if (typeof onLoginComplete === 'function') {
-        onLoginComplete(buildLoginCompletePayload(res));
+      if (isTwoFactorRequired(res)) {
+        requireFaceVerification(res);
+        return;
       }
+      completeLogin(res);
     } catch (err) {
       if (isFrRequiredError(err)) {
         flow.injectFrsStep();
@@ -180,6 +212,10 @@ export function mountLogin(container, options = {}) {
     }
     try {
       const res = await api.otpVerify(identifier, '', channel, otp);
+      if (isTwoFactorRequired(res)) {
+        requireFaceVerification(res);
+        return;
+      }
       state.set('loginResult', res);
       flow.setStep(LOGIN_STEPS.SUCCESS);
       if (typeof onLoginComplete === 'function') {
@@ -206,30 +242,30 @@ export function mountLogin(container, options = {}) {
     }
     const method = flow.currentMethod;
     const identifier = state.get('identifier');
+    const frToken = state.get('frToken');
     let apiResult = null;
 
+    layout.setLoading(true, 'Verifying your face…');
     try {
       if (method === LOGIN_METHODS.EMAIL_FRS) {
         apiResult = await api.loginEmailFr(identifier, file, null, config.appIdentifier);
       } else if (method === LOGIN_METHODS.EMAIL_PASSWORD || method === LOGIN_METHODS.MOBILE_PASSWORD) {
-        apiResult = await api.loginCustom(identifier, state.get('password'), config.appIdentifier, [file, file]);
+        apiResult = await api.loginCustom(identifier, state.get('password'), config.appIdentifier, [file, file], frToken);
       } else if (method === LOGIN_METHODS.SOCIAL_GOOGLE) {
-        apiResult = await api.googleFrEnroll(state.get('loginToken'), file, null, config.appIdentifier);
+        apiResult = await api.googleFrEnroll(state.get('loginToken'), file, null, config.appIdentifier, frToken);
       } else if (method === LOGIN_METHODS.SOCIAL_MICROSOFT) {
-        apiResult = await api.microsoftFrEnroll(state.get('loginToken'), file, null, config.appIdentifier);
+        apiResult = await api.microsoftFrEnroll(state.get('loginToken'), file, null, config.appIdentifier, frToken);
       } else if (method === LOGIN_METHODS.EMAIL_OTP || method === LOGIN_METHODS.MOBILE_OTP) {
         const channel = identifier.includes('@') ? 'email' : 'sms';
-        apiResult = await api.otpVerify(identifier, '', channel, state.get('otp'), [file, file]);
-      }
-      state.set('loginResult', apiResult);
-      flow.goNext();
-      if (typeof onLoginComplete === 'function') {
-        onLoginComplete(buildLoginCompletePayload(apiResult));
+        apiResult = await api.otpVerify(identifier, '', channel, state.get('otp'), [file, file], frToken);
       }
+      completeLogin(apiResult);
     } catch (err) {
       const msg = err?.data?.error || err?.message || 'Verification failed';
       state.set('error', msg);
       showError(msg);
+    } finally {
+      layout.setLoading(false);
     }
   }
 
@@ -309,6 +345,12 @@ export function mountLogin(container, options = {}) {
 
   flow.subscribe(render);
   render();
+  if (oauth?.kind === 'error') {
+    showError(oauth.error);
+  }
+  if (oauth) {
+    clearOAuthRedirectPendingMark();
+  }
 
   return {
     unmount() { cleanupTheme(); layout.root.remove(); },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "central-auth-js-sdk",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "description": "Vanilla JS sign-up and login flow SDK — embeddable auth UI with configurable methods",
   "type": "module",
   "main": "index.js",

package/signup.js

@@ -7,30 +7,21 @@ import { FlowController, STEPS } from './core/flow.js';
 import { StateManager } from './core/state.js';
 import { createApi, dataUrlToFile } from './core/api.js';
 import { resolveApiBaseUrl } from './core/env-config.js';
+import { parseOAuthRedirect, clearOAuthRedirectParams } from './core/oauth-redirect.js';
 import { createLayout } from './ui/layout.js';
 import { createScreen } from './ui/screens/index.js';
 import { applyTheme } from './theme.js';
 
 /** Parse URL query for OAuth callback params (login_token, provider) */
-function parseOAuthCallback() {
-  if (typeof window === 'undefined' || !window.location) return null;
-  const params = new URLSearchParams(window.location.search);
-  const loginToken = params.get('login_token');
-  const provider = (params.get('provider') || '').toLowerCase();
-  if (!loginToken) return null;
-  if (provider !== 'google' && provider !== 'microsoft') return { loginToken, provider: 'google' };
-  return { loginToken, provider };
+function parseSignupOAuthCallback() {
+  const redirect = parseOAuthRedirect();
+  if (!redirect || !redirect.loginToken) return null;
+  return redirect;
 }
 
 /** Remove OAuth params from URL without reload */
 function clearOAuthParams() {
-  if (typeof window === 'undefined' || !window.history) return;
-  const params = new URLSearchParams(window.location.search);
-  params.delete('login_token');
-  params.delete('provider');
-  const clean = params.toString();
-  const url = window.location.pathname + (clean ? '?' + clean : '') + window.location.hash;
-  window.history.replaceState({}, '', url);
+  clearOAuthRedirectParams();
 }
 
 /** Map API next_step from POST /signup/start to our flow step */
@@ -90,12 +81,18 @@ export function mount(container, options = {}) {
   const showError = (msg) => layout.showError(msg);
 
   // SDK handles OAuth callback: if URL has login_token, resume social flow
-  const oauth = parseOAuthCallback();
+  const oauth = parseSignupOAuthCallback();
   if (oauth) {
     state.set('loginToken', oauth.loginToken);
     state.set('socialProvider', oauth.provider);
+    if (oauth.email) state.set('email', oauth.email);
     clearOAuthParams();
     flow.setSocialFlow();
+    if (oauth.nextStep === 'FR_ENROLLMENT') {
+      flow.setStep(STEPS.FACE);
+    } else if (oauth.nextStep === 'MOBILE_VERIFICATION') {
+      flow.setStep(STEPS.MOBILE);
+    }
   }
 
   const isSocial = () => !!state.get('loginToken');
@@ -229,6 +226,7 @@ export function mount(container, options = {}) {
       showError('Please capture your face first.');
       return;
     }
+    layout.setLoading(true, 'Registering your face…');
     try {
       let apiResult = null;
       if (isSocial()) {
@@ -253,6 +251,8 @@ export function mount(container, options = {}) {
       const msg = err?.data?.error || err?.message || 'Face registration failed';
       state.set('error', msg);
       showError(msg);
+    } finally {
+      layout.setLoading(false);
     }
   }
 

package/styles.css

@@ -300,6 +300,67 @@
   display: none;
 }
 
+/* ============================= LOADING BAR ============================= */
+
+.wf-loading-bar {
+  height: 3px;
+  margin: -0.25rem 0 1rem;
+  border-radius: 999px;
+  background: var(--wf-muted-bg, rgba(0, 0, 0, 0.06));
+  overflow: hidden;
+}
+
+.wf-loading-bar.hidden {
+  display: none;
+}
+
+.wf-loading-bar-indeterminate {
+  height: 100%;
+  width: 40%;
+  border-radius: 999px;
+  background: linear-gradient(90deg, var(--wf-primary-grad-start) 0%, var(--wf-primary) 50%, var(--wf-primary-grad-end) 100%);
+  animation: wf-loading-slide 1.2s ease-in-out infinite;
+}
+
+@keyframes wf-loading-slide {
+  0% { transform: translateX(-100%); }
+  100% { transform: translateX(350%); }
+}
+
+.wf-loading-status {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  margin-bottom: 1rem;
+  padding: 0.5rem 0.75rem;
+  border-radius: var(--wf-radius);
+  background: var(--wf-muted-bg, rgba(0, 0, 0, 0.04));
+  color: var(--wf-fg-soft);
+  font-size: 0.8125rem;
+  font-weight: 500;
+}
+
+.wf-loading-status.hidden {
+  display: none;
+}
+
+.wf-loading-status::before {
+  content: '';
+  width: 1rem;
+  height: 1rem;
+  border: 2px solid var(--wf-border);
+  border-top-color: var(--wf-primary);
+  border-radius: 50%;
+  animation: wf-spin 0.7s linear infinite;
+  flex-shrink: 0;
+}
+
+#wf-form-inner.wf-loading-active {
+  pointer-events: none;
+  opacity: 0.65;
+}
+
 /* ============================= PAGE FOOTER ============================= */
 
 .wf-page-footer {

package/ui/layout.js

@@ -45,6 +45,10 @@ export function createLayout(container) {
           </div>
         </div>
         <div class="wf-card-body">
+          <div class="wf-loading-bar hidden" id="wf-loading-bar" role="progressbar" aria-busy="false" aria-label="Loading">
+            <div class="wf-loading-bar-indeterminate"></div>
+          </div>
+          <div class="wf-loading-status hidden" id="wf-loading-status"></div>
           <div class="wf-error-banner hidden" id="wf-error-banner" role="alert"></div>
           <div id="wf-form-inner"></div>
         </div>
@@ -60,6 +64,8 @@ export function createLayout(container) {
   const ringNum = root.querySelector('#wf-ring-num');
   const ring = root.querySelector('.wf-ring');
   const errorBanner = root.querySelector('#wf-error-banner');
+  const loadingBar = root.querySelector('#wf-loading-bar');
+  const loadingStatus = root.querySelector('#wf-loading-status');
 
   function setContent(el) {
     formInner.innerHTML = '';
@@ -90,11 +96,33 @@ export function createLayout(container) {
     errorBanner.classList.remove('hidden');
   }
 
+  function setLoading(active, message = '') {
+    if (active) {
+      loadingBar.classList.remove('hidden');
+      loadingBar.setAttribute('aria-busy', 'true');
+      formInner.classList.add('wf-loading-active');
+      if (message) {
+        loadingStatus.textContent = message;
+        loadingStatus.classList.remove('hidden');
+      } else {
+        loadingStatus.textContent = '';
+        loadingStatus.classList.add('hidden');
+      }
+    } else {
+      loadingBar.classList.add('hidden');
+      loadingBar.setAttribute('aria-busy', 'false');
+      formInner.classList.remove('wf-loading-active');
+      loadingStatus.classList.add('hidden');
+      loadingStatus.textContent = '';
+    }
+  }
+
   return {
     root,
     setContent,
     updateProgress,
     showError,
+    setLoading,
     renderContent: setContent,
   };
 }