central-auth-js-sdk 1.0.10

package/README.md

@@ -0,0 +1,386 @@
+# Central Auth Welcome Flow SDK
+
+Vanilla JavaScript signup and login flows — embeddable into any web application. No React, Angular, or Vue.
+
+**Integrators:** See **[INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md)** for how to pull the SDK and use all functionalities (install, config, signup/login, callbacks, tokens, and a full example).
+
+## Distributing the SDK
+
+**Simplest options:**
+
+### 1. **npm (recommended)**
+
+Publish the `sdk` folder as its own package so integrators can install it with one command.
+
+- Log in to npm (one-time): `npm login` (you need an account at [npmjs.com](https://www.npmjs.com/signup)).
+- From the repo root, go to the SDK folder and publish:
+  ```bash
+  cd sdk
+  npm publish
+  ```
+  Use `npm publish --access public` if the package name is scoped (e.g. `@your-org/central-auth-sdk`).
+
+- Integrators then:
+  ```bash
+  npm install central-auth-sdk
+  ```
+  ```javascript
+  import { startSignup, startLogin } from 'central-auth-sdk';
+  ```
+  They also need to load the CSS (e.g. in their app entry or HTML):
+  ```javascript
+  import 'central-auth-sdk/styles.css';
+  ```
+  or
+  ```html
+  <link rel="stylesheet" href="./node_modules/central-auth-sdk/styles.css" />
+  ```
+
+**Pros:** Versioning, semver, one install command, works with any bundler.  
+**Cons:** Integrators need Node/npm (or equivalent).
+
+### 2. **Copy / embed (no build)**
+
+Ship the SDK as source in a zip, Git repo, or copy the `sdk` folder into the parent app. The parent app points at the folder (e.g. Vite alias or relative path).
+
+- Example (parent app has `sdk/` at repo root):
+  ```html
+  <link rel="stylesheet" href="/sdk/styles.css" />
+  <script type="module">
+    import { startLogin } from '/sdk/index.js';
+    startLogin({ container: '#auth', env: 'dev', loginMethods: { emailPassword: true } });
+  </script>
+  ```
+
+**Pros:** No publish step, no npm; works with any dev server that serves the `sdk` folder.  
+**Cons:** No versioning via registry; updates are manual (replace files or pull from Git).
+
+### 3. **CDN / single-file bundle (optional)**
+
+For environments without a bundler, you can add a build step that bundles the SDK into a single JS file (and keep `styles.css` separate). Then host it (or publish to npm and use unpkg/jsDelivr). This requires a small Vite/Rollup config that builds `sdk/index.js` into e.g. `dist/central-auth-sdk.js`. Many teams skip this and use option 1 or 2.
+
+---
+
+## Public API (recommended)
+
+The SDK exposes **callable functions** so the host application can **initialize and trigger** Sign-Up or Login **programmatically** with **static configuration parameters**.
+
+### initializeAuth(config)
+
+Call once (e.g. at app load) to set **default configuration**. Optional; you can pass all config when calling `startSignup` / `startLogin` instead.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `env` | string | `'local'` | Environment: `'local'` \| `'dev'` \| `'staging'` \| `'prod'`. SDK uses the predefined API URL for that env. |
+| `appIdentifier` | string | `'control-center'` | App identifier for OAuth and custom login |
+| `defaultContainer` | string \| HTMLElement | — | Default container for rendering (can override in `startSignup` / `startLogin`) |
+| `loginMethods` | object | — | Default enabled login methods (see Login config below) |
+| `frsAsSecondFactor` | boolean | `false` | Default: require face verification after primary auth |
+| `enableFaceRegistration` | boolean | `true` | Whether sign-up flow includes face registration step |
+
+**Returns:** `{ startSignup, startLogin, getConfig }`
+
+### startSignup(config)
+
+Starts the **Sign-Up flow** in the given container. Configuration is **static** (passed when triggering, not collected from the user).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `container` | string \| HTMLElement | yes* | DOM selector or element where the SDK renders (*or set `defaultContainer` in `initializeAuth`) |
+| `env` | string | no | Environment: `'local'` \| `'dev'` \| `'staging'` \| `'prod'` (default from init or `'local'`) |
+| `appIdentifier` | string | no | Override app identifier |
+| `enableFaceRegistration` | boolean | no | Include face registration step (default from init or `true`) |
+
+**Returns:** `{ unmount, getState, getFlow, getCurrentStep }` or `null` if container invalid.
+
+### startLogin(config)
+
+Starts the **Login flow** in the given container with **configurable login methods**.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `container` | string \| HTMLElement | yes* | DOM selector or element where the SDK renders |
+| `env` | string | no | Environment: `'local'` \| `'dev'` \| `'staging'` \| `'prod'` (default from init or `'local'`) |
+| `appIdentifier` | string | no | Override app identifier |
+| `loginMethods` | object | no | Which login methods are enabled (see below) |
+| `frsAsSecondFactor` | boolean | no | Require face verification after primary auth |
+| `onSignUp` | function | no | Callback when user clicks “Sign up” (e.g. switch to signup) |
+
+**Enabled login methods** (`loginMethods`):
+
+- `emailPassword` — Email + Password  
+- `mobilePassword` — Mobile + Password  
+- `emailOtp` — Email + OTP  
+- `mobileOtp` — Mobile + OTP  
+- `social.google` / `social.microsoft` — Social login  
+- `emailFrs` — Email + Face (FRS only, no password/OTP)
+
+**Returns:** `{ unmount, getState, getFlow, getCurrentStep }` or `null` if container invalid.
+
+### Theming (optional)
+
+Pass a `theme` object to match the SDK to your app's look. All properties are optional — omit any to keep the SDK default.
+
+```javascript
+startSignup({
+  container: '#auth-container',
+  env: 'dev',
+  theme: {
+    primaryColor: '#2563EB',       // buttons, links, accent
+    backgroundColor: '#EFF6FF',    // page background
+    backgroundImage: 'https://…',  // optional full-bleed image
+    cardColor: '#FFFFFF',          // card panel
+    textColor: '#1A1714',          // primary text
+    fontFamily: '"DM Sans", sans-serif',
+    mode: 'auto',                  // 'light' | 'dark' | 'auto'
+  },
+});
+```
+
+Built-in presets: `import { THEME_PRESETS } from 'central-auth-sdk'` — keys: `default`, `dark`, `ocean`, `forest`, `purple`, `rose`, `midnight`.
+
+See [INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md) § 5.1 for full details.
+
+### Example: initialize once, then trigger flows
+
+```html
+<div id="auth-container"></div>
+<link rel="stylesheet" href="/path/to/sdk/styles.css" />
+<script type="module">
+  import { initializeAuth, startSignup, startLogin } from '/path/to/sdk/index.js';
+
+  const auth = initializeAuth({
+    env: 'dev',
+    appIdentifier: 'my-app',
+    defaultContainer: '#auth-container',
+    loginMethods: {
+      emailPassword: true,
+      emailOtp: true,
+      social: { google: true, microsoft: true },
+      emailFrs: false,
+    },
+    frsAsSecondFactor: true,
+  });
+
+  let currentInstance = null;
+
+  function showSignup() {
+    if (currentInstance) currentInstance.unmount();
+    currentInstance = auth.startSignup({});  // uses defaultContainer + init config
+  }
+
+  function showLogin() {
+    if (currentInstance) currentInstance.unmount();
+    currentInstance = auth.startLogin({
+      onSignUp: showSignup,
+    });
+  }
+
+  showLogin();  // or showSignup()
+</script>
+```
+
+### Example: trigger without initializeAuth
+
+You can pass **all configuration** when starting a flow (no need to call `initializeAuth`):
+
+```javascript
+import { startSignup, startLogin } from '/path/to/sdk/index.js';
+
+const signupInstance = startSignup({
+  container: '#auth-container',
+  env: 'dev',
+  appIdentifier: 'my-app',
+});
+
+const loginInstance = startLogin({
+  container: '#auth-container',
+  env: 'dev',
+  appIdentifier: 'my-app',
+  loginMethods: {
+    emailPassword: true,
+    mobilePassword: true,
+    emailOtp: true,
+    mobileOtp: true,
+    social: { google: true, microsoft: true },
+    emailFrs: true,
+  },
+  frsAsSecondFactor: false,
+  onSignUp() {
+    loginInstance.unmount();
+    startSignup({ container: '#auth-container', env: 'dev' });
+  },
+});
+```
+
+### Sending signup result (token + details) back to the parent app
+
+When signup **completes** (after the final step, e.g. face registration), the SDK gives the parent app the result in two ways:
+
+1. **`onSignupComplete(payload)`** — Pass this callback when starting signup. The SDK calls it **once** when signup finishes, with a single `payload` object that includes:
+   - `email`, `mobile`, `userId` (from the flow)
+   - Any fields returned by the **final API** call (e.g. `access_token`, `refresh_token`, `user_id`) — the backend can return whatever it needs here.
+
+2. **`instance.getState()`** — At any time (including on the success screen), the parent can call `getState()` to read current flow data. After completion, state also includes `signupResult` (the raw final API response).
+
+**Example:**
+
+```javascript
+const instance = startSignup({
+  container: '#auth-container',
+  env: 'dev',
+  appIdentifier: 'my-app',
+  onSignupComplete(payload) {
+    // payload.email, payload.mobile, payload.userId
+    // payload.access_token, payload.refresh_token (if your API returns them)
+    console.log('Signup complete', payload);
+    myApp.saveSession(payload.access_token);
+    instance.unmount();
+    myApp.redirectToDashboard();
+  },
+  onContinue() {
+    // User clicked "Go to Dashboard" / "Back to Home" on the success screen
+    instance.unmount();
+    myApp.redirectToDashboard();
+  },
+});
+```
+
+The backend should return token (and any other session data) in the **final signup API response** (e.g. `POST /signup/fr/enroll` or the social FR enroll endpoint). The SDK forwards that response into `payload` and into `getState().signupResult`.
+
+### Sending login result (token + details) back to the parent app
+
+When **login completes** (after the final successful API call — password, OTP, or FRS), the SDK gives the parent app the result in the same way as signup:
+
+1. **`onLoginComplete(payload)`** — Pass this callback when starting login. The SDK calls it **once** when login finishes, with a single `payload` object that includes:
+   - `identifier` (email or mobile used to sign in)
+   - Any fields returned by the **final API** call (e.g. `access_token`, `refresh_token`, `user_id`)
+
+2. **`instance.getState()`** — After completion, state includes `loginResult` (the raw final API response).
+
+3. **`onContinue()`** — Called when the user clicks **Continue** on the login success screen (e.g. to unmount and redirect).
+
+**Example:**
+
+```javascript
+const instance = startLogin({
+  container: '#auth-container',
+  env: 'dev',
+  appIdentifier: 'my-app',
+  loginMethods: { emailPassword: true },
+  onLoginComplete(payload) {
+    // payload.identifier, payload.access_token, payload.refresh_token (if API returns them)
+    myApp.saveSession(payload.access_token);
+    instance.unmount();
+    myApp.redirectToApp();
+  },
+  onContinue() {
+    instance.unmount();
+    myApp.redirectToApp();
+  },
+  onSignUp() { /* switch to signup */ },
+});
+```
+
+The backend should return token (and any session data) in the **final login API response** (e.g. `POST /login/custom`, `POST /otp/verify`, `POST /login/email/fr`, or social FR enroll). The SDK forwards that response into `payload` and into `getState().loginResult`.
+
+### Instance API (returned by startSignup / startLogin)
+
+```javascript
+instance.unmount()        // Remove the flow from DOM
+instance.getState()      // Read form data (email, mobile, userId, signupResult / loginResult, etc.)
+instance.getCurrentStep() // Current step name
+instance.getFlow()       // FlowController reference
+```
+
+---
+
+## Architecture
+
+- **UI layer** (`sdk/ui/`) — Screens and layout, pure DOM
+- **Core layer** (`sdk/core/`) — Flow, state, events; ready for API integration
+- **Separation of concerns** — UI emits actions; core handles logic; APIs plug in later
+
+## Lower-level embedding (mount / mountLogin)
+
+If you prefer not to use `initializeAuth` / `startSignup` / `startLogin`, you can use the same underlying functions:
+
+### 1. Include styles and mount
+
+```html
+<div id="signup-container"></div>
+<link rel="stylesheet" href="/path/to/sdk/styles.css" />
+<script type="module">
+  import { mount } from '/path/to/sdk/index.js';
+  const instance = mount('#signup-container');
+</script>
+```
+
+### 2. Mount options
+
+```javascript
+mount('#signup', {
+  env: 'local',
+  appIdentifier: 'control-center',       // for social OAuth
+});
+```
+
+Entity is derived from email in the backend; no need to pass entity name/domain.
+
+### 3. Login flow (lower-level)
+
+```javascript
+import { mountLogin } from '/path/to/sdk/index.js';
+
+const loginInstance = mountLogin('#login-container', {
+  env: 'local',
+  appIdentifier: 'control-center',
+  loginMethods: { emailPassword: true, /* ... */ },
+  frsAsSecondFactor: true,
+  onSignUp() { /* switch to signup */ },
+});
+```
+
+### 4. Integration with existing apps
+
+- Use any container selector or `HTMLElement`
+- No global pollution; all logic is scoped
+- Styles use `wf-` prefix to avoid conflicts
+
+## UI design rules
+
+When adding or changing screens, follow **[DESIGN_RULES.md](DESIGN_RULES.md)** for tokens, typography, spacing, component patterns, and a new-screen checklist.
+
+## File structure
+
+```
+sdk/
+├── core/
+│   ├── api.js         # Central Auth API client (central_auth_collection.json)
+│   ├── flow.js        # Step navigation, flow type (standard/social)
+│   ├── state.js       # Form data
+│   ├── login-config.js
+│   ├── login-flow.js
+│   ├── login-state.js
+│   └── events.js      # Event bus (optional)
+├── ui/
+│   ├── layout.js
+│   ├── components.js
+│   ├── screens/
+│   │   ├── (signup screens)
+│   │   └── login/
+│   │       ├── entry.js, identifier-email.js, identifier-mobile.js
+│   │       ├── password.js, otp.js, frs.js, success.js
+│   │       └── index.js
+│   └── screens/index.js
+├── index.js       # Main entry: initializeAuth, startSignup, startLogin, mount, mountLogin
+├── auth.js        # Public API: initializeAuth, startSignup, startLogin
+├── signup.js      # Sign-up flow: mount()
+├── login.js       # Login flow: mountLogin()
+├── styles.css
+└── README.md
+```
+
+## API integration
+
+APIs from `central_auth_collection.json` are wired in `core/api.js`. See [API_INTEGRATION.md](API_INTEGRATION.md) for endpoint mapping, options (`entityName`, `entityDomain`), and response assumptions (`user_id` from email verify).

package/auth.js

@@ -0,0 +1,159 @@
+/**
+ * Central Auth SDK — Public API for host applications
+ * Exposes initializeAuth, startSignup, startLogin with configurable static parameters.
+ */
+
+import { resolveApiBaseUrl } from './core/env-config.js';
+import { mount } from './signup.js';
+import { mountLogin } from './login.js';
+
+/** Default configuration stored after initializeAuth() */
+let defaultConfig = {};
+
+/**
+ * Merge config with defaults. Passed config overrides defaults.
+ * @param {Object} overrides - config passed to startSignup / startLogin
+ * @returns {Object} merged config
+ */
+function mergeConfig(overrides = {}) {
+  return {
+    ...defaultConfig,
+    ...overrides,
+    loginMethods: overrides.loginMethods != null
+      ? { ...defaultConfig.loginMethods, ...overrides.loginMethods }
+      : defaultConfig.loginMethods,
+    social: overrides.social != null || (overrides.loginMethods && overrides.loginMethods.social != null)
+      ? { ...defaultConfig.social, ...(overrides.social || overrides.loginMethods?.social || {}) }
+      : defaultConfig.social,
+    theme: overrides.theme != null
+      ? { ...defaultConfig.theme, ...overrides.theme }
+      : defaultConfig.theme,
+  };
+}
+
+/**
+ * Resolve container: string selector or HTMLElement. Throws if missing/invalid.
+ * @param {string|HTMLElement} container
+ * @returns {HTMLElement}
+ */
+function resolveContainer(container) {
+  if (container == null) return null;
+  const el = typeof container === 'string' ? document.querySelector(container) : container;
+  return el && el.nodeType === 1 ? el : 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.
+ *
+ * @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 {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 }}
+ */
+export function initializeAuth(config = {}) {
+  defaultConfig = {
+    env: 'local',
+    appIdentifier: undefined,
+    defaultContainer: null,
+    loginMethods: null,
+    frsAsSecondFactor: false,
+    enableFaceRegistration: true,
+    theme: null,
+    ...config,
+  };
+  return {
+    startSignup: startSignup,
+    startLogin: startLogin,
+    getConfig() {
+      return { ...defaultConfig };
+    },
+  };
+}
+
+/**
+ * Start the Sign-Up flow. Renders into the given container and runs the signup wizard.
+ *
+ * @param {Object} config - Static configuration for this flow (merged with initializeAuth defaults)
+ * @param {string|HTMLElement} config.container - DOM selector or element where the SDK will render (required)
+ * @param {string} [config.env] - Environment: 'local' | 'dev' | 'staging' | 'prod' (default from init or 'local')
+ * @param {string} [config.appIdentifier] - Override app identifier
+ * @param {boolean} [config.enableFaceRegistration] - Include face registration step (default from init or true)
+ * @param {Function} [config.onSignupComplete] - Called when signup completes with (payload). Payload: email, mobile, userId, plus any token/fields from the final API response (e.g. access_token, refresh_token).
+ * @param {Function} [config.onContinue] - Called when user clicks Continue on the success screen (e.g. unmount and redirect).
+ * @param {Function} [config.onSwitchToLogin] - Called when user clicks "Sign in" (e.g. unmount signup and start login, e.g. login + FRS).
+ * @param {Function} [config.onBack] - Called when user clicks Back on the first screen (e.g. unmount and return to parent app).
+ * @param {Object} [config.theme] - Optional theme overrides (primaryColor, secondaryColor, backgroundColor, backgroundImage, cardColor, textColor, fontFamily, mode)
+ * @returns {{ unmount: Function, getState: Function, getFlow: Function, getCurrentStep: Function }|null} SDK instance or null if container invalid
+ */
+export function startSignup(config = {}) {
+  const merged = mergeConfig(config);
+  const container = config.container ?? merged.defaultContainer;
+  const el = resolveContainer(container);
+  if (!el) {
+    console.error('[Central Auth SDK] startSignup: container is required (pass config.container or set defaultContainer in initializeAuth)');
+    return null;
+  }
+  const options = {
+    apiBaseUrl: resolveApiBaseUrl(merged),
+    appIdentifier: merged.appIdentifier,
+    enableFaceRegistration: merged.enableFaceRegistration,
+    theme: merged.theme || undefined,
+    onSignupComplete: config.onSignupComplete ?? merged.onSignupComplete,
+    onContinue: config.onContinue ?? merged.onContinue,
+    onSwitchToLogin: config.onSwitchToLogin ?? merged.onSwitchToLogin,
+    onBack: config.onBack ?? merged.onBack,
+  };
+  return mount(el, options);
+}
+
+/**
+ * Start the Login flow. Renders into the given container with configurable login methods.
+ *
+ * @param {Object} config - Static configuration for this flow (merged with initializeAuth defaults)
+ * @param {string|HTMLElement} config.container - DOM selector or element where the SDK will render (required)
+ * @param {string} [config.env] - Environment: 'local' | 'dev' | 'staging' | 'prod' (default from init or 'local')
+ * @param {string} [config.appIdentifier] - Override app identifier
+ * @param {Object} [config.loginMethods] - Which login methods are enabled
+ * @param {boolean} [config.loginMethods.emailPassword] - Email + Password
+ * @param {boolean} [config.loginMethods.mobilePassword] - Mobile + Password
+ * @param {boolean} [config.loginMethods.emailOtp] - Email + OTP
+ * @param {boolean} [config.loginMethods.mobileOtp] - Mobile + OTP
+ * @param {Object} [config.loginMethods.social] - Social login
+ * @param {boolean} [config.loginMethods.social.google] - Google
+ * @param {boolean} [config.loginMethods.social.microsoft] - Microsoft
+ * @param {boolean} [config.loginMethods.emailFrs] - Email + Face (FRS only)
+ * @param {boolean} [config.frsAsSecondFactor] - Require face verification after primary auth
+ * @param {Function} [config.onSignUp] - Callback when user clicks "Sign up" (e.g. switch to signup flow)
+ * @param {Function} [config.onLoginComplete] - Called when login completes with (payload). Payload: identifier, plus any token/fields from the final API response (e.g. access_token, refresh_token).
+ * @param {Function} [config.onContinue] - Called when user clicks Continue on the success screen (e.g. unmount and redirect).
+ * @param {Function} [config.onBack] - Called when user clicks Back on the first screen (e.g. unmount and return to parent app).
+ * @param {Object} [config.theme] - Optional theme overrides (primaryColor, secondaryColor, backgroundColor, backgroundImage, cardColor, textColor, fontFamily, mode)
+ * @returns {{ unmount: Function, getState: Function, getFlow: Function, getCurrentStep: Function }|null} SDK instance or null if container invalid
+ */
+export function startLogin(config = {}) {
+  const merged = mergeConfig(config);
+  const container = config.container ?? merged.defaultContainer;
+  const el = resolveContainer(container);
+  if (!el) {
+    console.error('[Central Auth SDK] startLogin: container is required (pass config.container or set defaultContainer in initializeAuth)');
+    return null;
+  }
+  const options = {
+    apiBaseUrl: resolveApiBaseUrl(merged),
+    appIdentifier: merged.appIdentifier,
+    loginMethods: merged.loginMethods,
+    frsAsSecondFactor: merged.frsAsSecondFactor,
+    theme: merged.theme || undefined,
+    onSignUp: config.onSignUp ?? merged.onSignUp,
+    onLoginComplete: config.onLoginComplete ?? merged.onLoginComplete,
+    onContinue: config.onContinue ?? merged.onContinue,
+    onBack: config.onBack ?? merged.onBack,
+  };
+  return mountLogin(el, options);
+}