@thirdfactor/web 1.0.0

package/README.md

@@ -0,0 +1,311 @@
+# @thirdfactor/web
+
+Web client SDK for the **ThirdFactor / Obsidian** native KYC engine. It opens the
+hosted verification flow in a **popup**, a cross-origin **modal** iframe, or a
+full-page **redirect**, listens to the flow over the shared bridge protocol, and
+resolves a single typed `VerificationResult`.
+
+The SDK is a thin shell: your backend creates the session and gets a hosted `url`;
+the browser hands that `url` to this SDK. Session creation needs your **secret API
+key** and is done on your server (an optional `@thirdfactor/web/server` helper is
+included).
+
+> **The client result is advisory.** It is a UX signal only. Grant access / move
+> money **only after** your backend confirms the decision from the signed webhook
+> (`identity.kyc.session.approved` / `.declined` / `.review` / `.expired`) or
+> `GET /v3/session/<id>/decision/`. A user can close the tab after approval or
+> tamper with the browser; the webhook is HMAC-signed and cannot be spoofed.
+
+- **Bridge protocol:** [`../../docs/sdk/PROTOCOL.md`](../../docs/sdk/PROTOCOL.md)
+- **REST reference:** [`../../OBSIDIAN_API.md`](../../OBSIDIAN_API.md)
+
+## Requirements
+
+| | |
+| --- | --- |
+| Browser | Any modern evergreen browser (Chromium, Firefox, Safari) with `postMessage` + camera (`getUserMedia`). |
+| Bundler / module system | ESM. Ships `.js` + `.d.ts`; works with Vite, webpack, Next.js, etc. |
+| Backend (for the session helper) | Node 18+ (global `fetch`) or any runtime with a WHATWG `fetch`. |
+| TypeScript | Optional; full types are bundled. |
+
+## Installation
+
+```bash
+npm install @thirdfactor/web
+```
+
+Two entry points, deliberately separated so your **browser bundle never imports
+anything that touches your API key**:
+
+```ts
+import { ThirdFactor } from "@thirdfactor/web";          // browser
+import { createSession } from "@thirdfactor/web/server"; // server only
+```
+
+## Permissions
+
+The hosted flow captures the camera (document + selfie/liveness) and may use the
+microphone. There is no manifest on the web — the browser prompts the user the
+first time the flow calls `getUserMedia`. What matters is the **browsing context**
+the camera runs in:
+
+- **`popup`** (and `redirect`) run the flow in a top-level context, so the camera
+  prompt and stream work everywhere, including iOS Safari.
+- **`modal`** runs the flow in a cross-origin iframe. The browser only grants it
+  camera/mic if the flow deployment allowlists your origin (see
+  [Configuration → `modal`](#enabling-modal-cross-origin-iframe)), and camera in a
+  cross-origin iframe is still unreliable on iOS Safari.
+
+The SDK already sets `allow="camera; microphone"` on the modal iframe; your app's
+own CSP `frame-src` must also permit the flow origin when you use `modal`.
+
+## Quick Start
+
+```ts
+// 1) Backend — create the session (secret key, never in the browser).
+import { createSession } from "@thirdfactor/web/server";
+const session = await createSession(
+  { baseUrl: process.env.TF_BASE_URL!, apiKey: process.env.TF_API_KEY! },
+  { vendorData: user.id, callbackUrl: "https://app.acme.com/kyc/done" },
+);
+// send { url: session.url, id: session.id } to the browser
+
+// 2) Browser — open the flow from a real click.
+import { ThirdFactor } from "@thirdfactor/web";
+button.addEventListener("click", async () => {
+  const result = await ThirdFactor.verify({ url: session.url });
+  if (result.status === "approved") showSuccess();   // then confirm server-side
+});
+```
+
+> Call `verify()` from a genuine click/tap — popup mode is blocked otherwise.
+
+## Integration Methods
+
+### Method 1 — Backend session helper (recommended)
+
+`@thirdfactor/web/server` wraps `POST /v3/session/` so you don't hand-roll the
+request. It runs **only** on your server.
+
+```ts
+import { createSession } from "@thirdfactor/web/server";
+
+const session = await createSession(
+  { baseUrl: process.env.TF_BASE_URL!, apiKey: process.env.TF_API_KEY! },
+  {
+    vendorData: user.id,                       // your reference for this user
+    callbackUrl: "https://app.acme.com/kyc/done",
+    contactEmail: user.email,
+    locale: "en",                              // hosted-flow language
+    prefill: { full_name: user.name },         // pre-populate the flow
+    idempotencyKey: `kyc-${user.id}`,          // safe retries, never double-charged
+  },
+);
+// → { id, url, status, decision, expiresAt, ... }; send { url, id } to the browser
+```
+
+On a non-2xx response it throws `ThirdFactorApiError` with `.status` and a stable
+`.code` (e.g. `insufficient_credits`).
+
+### Method 2 — Any backend + `verify({ url })`
+
+The helper is optional. `POST /v3/session/` is a single authenticated call; create
+the session however you like (cURL / Python / Go — see
+[`../../docs/sdk/README.md`](../../docs/sdk/README.md)) and pass the returned `url`
+to `ThirdFactor.verify({ url })`. The browser side is identical either way.
+
+### Presentation modes
+
+| Mode | Call | Best for | Notes |
+| --- | --- | --- | --- |
+| `auto` (default) | `verify({ url })` | Anything | Resolves to **popup** — a top-level context with reliable camera everywhere. |
+| `popup` | `verify({ url, mode: "popup" })` | Mobile web, zero-config | New window; most reliable camera. |
+| `modal` | `verify({ url, mode: "modal" })` | Desktop, in-page UX | Cross-origin iframe. **Opt-in** — the flow must allowlist your origin. |
+| `redirect` | `ThirdFactor.redirect(url)` | Max compatibility | Full-page navigate; does not return a Promise. Result arrives via `callback_url` + webhook. |
+
+## Configuration
+
+### `ThirdFactor.verify(options): Promise<VerificationResult>`
+
+Never rejects — always resolves a `VerificationResult`.
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `url` | `string` | — (required) | Hosted session URL from `POST /v3/session/`. |
+| `mode` | `"modal" \| "popup" \| "auto"` | `"auto"` | `auto` = popup. `modal` is opt-in (see below). |
+| `onEvent` | `(e: VerificationEvent) => void` | — | Called for every lifecycle event: `ready` / `completed` / `error` / `close`. |
+| `title` | `string` | `"Identity verification"` | Accessible aria-label for the modal dialog. |
+| `autoClose` | `boolean` | `true` | `false` keeps the flow's own result screen up until the user taps Done. |
+| `expectedOrigin` | `string` | origin of `url` | Only override behind a proxy that serves the flow on a different origin. |
+
+`ThirdFactor.redirect(url: string): void` navigates the whole page to the flow and
+does not return.
+
+### `createSession(config, input)` — server helper
+
+`config`: `{ baseUrl, apiKey, fetchImpl? }`. `input` (all optional):
+
+| Field | Type | Maps to `POST /v3/session/` | Notes |
+| --- | --- | --- | --- |
+| `workflowId` | `string` | `workflow_id` | KYC workflow UUID; tenant default when omitted. |
+| `vendorData` | `string` | `vendor_data` | Your external user reference (also the linked identity's external id). |
+| `callbackUrl` | `string` | `callback_url` | Where the applicant is redirected after finishing. |
+| `contactEmail` / `contactPhone` | `string` | `contact_email` / `contact_phone` | OTP + notifications. |
+| `expiresInHours` | `number` | `expires_in_hours` | Hosted-URL lifetime, `1..720` (default `48`). |
+| `locale` | `string` | `locale` | Hosted-flow language (default `en`). |
+| `prefill` | `Record<string,string>` | `prefill` | Applicant fields to pre-populate (only documented keys honored). |
+| `idempotencyKey` | `string` | `Idempotency-Key` header | Repeat creates return the original session, uncharged. |
+
+See [`OBSIDIAN_API.md`](../../OBSIDIAN_API.md#create-verification-session) for the
+authoritative field list.
+
+### Enabling `modal` (cross-origin iframe)
+
+`modal` embeds the flow in an iframe on **your** origin. For that to work the flow
+deployment must allowlist your app origin — otherwise the browser refuses the frame
+(`X-Frame-Options`) and denies the iframe camera (`Permissions-Policy`). On the
+Obsidian flow deployment set:
+
+```bash
+FLOW_EMBED_ORIGINS="https://app.acme.com https://staging.acme.com"
+```
+
+This adds your origins to the flow route's `frame-ancestors` and grants them
+`camera`/`microphone`. Every other route keeps `X-Frame-Options: DENY`. With it
+unset (the default), cross-origin `modal` is refused by design — use `auto` (popup)
+or `redirect`. Even correctly allowlisted, camera in a cross-origin iframe is
+unreliable on iOS Safari; that's why `auto` uses popup.
+
+## Language / Localization
+
+The hosted flow's language and copy are chosen at **session-create time**, not in
+the browser SDK. Pass `locale` to `createSession` (or `"locale"` in the raw
+`POST /v3/session/` body); the SDK renders whatever the flow serves — no
+per-platform i18n code. See
+[`OBSIDIAN_API.md`](../../OBSIDIAN_API.md#create-verification-session).
+
+## Advanced Options
+
+Prefill, expected identity details, and metadata are also **session-create
+concerns**, not browser options:
+
+- **Prefill** — pass `prefill` to `createSession` to pre-populate the flow
+  (`full_name`, `first_name`, `last_name`, `display_name`, `date_of_birth`,
+  `email`, `phone`, `nationality`, `address_line1/2`, `city`, `state`, `country`,
+  `zip_code`). Unknown keys are ignored.
+- **Metadata / your reference** — `vendorData` becomes the session's external
+  reference and the linked identity's `external_user_id`; it comes back on the
+  session and every webhook.
+- **Workflow selection** — `workflowId` picks a specific KYC workflow; omit it for
+  the tenant default.
+
+Browser-side advanced knobs are just `expectedOrigin` (proxy override) and
+`autoClose` (keep the flow's result screen visible until Done).
+
+## Result Handling
+
+Every SDK resolves the same small vocabulary:
+
+```ts
+interface VerificationResult {
+  status: "approved" | "declined" | "in_review" | "cancelled" | "error";
+  sessionId?: string;                          // echoed from the flow when available
+  error?: { code: string; message: string };  // present only when status === "error"
+  rawStatus?: string;                          // raw server status (e.g. "abandoned")
+}
+```
+
+| `status` | When | Your move |
+| --- | --- | --- |
+| `approved` | Flow approved the applicant | Continue (after server confirm) |
+| `declined` | Flow rejected the applicant | Block / offer appeal |
+| `in_review` | Needs an operator / AML hit / any unknown terminal status (conservative) | Show "pending", wait for webhook |
+| `cancelled` | User closed the surface, or server `abandoned` | Let them retry |
+| `error` | Invalid/expired session or load failure | Surface `error.code`, retry / re-mint session |
+
+### Error cases
+
+`status === "error"` carries a stable `error.code` — branch on it, never on
+`error.message`:
+
+| `error.code` | Cause |
+| --- | --- |
+| `invalid_session` | Token is not a valid session. |
+| `expired` | Session/URL expired. |
+| `popup_blocked` | `verify()` was not called from a user gesture. |
+| `load_error` | The flow surface failed to load. |
+| `missing_url` | `options.url` was empty. |
+| `no_window` | `verify()` ran outside a browser. |
+| `network` / `unknown` | Transport failure / unrecognized error. |
+
+### Full example
+
+```ts
+import { ThirdFactor } from "@thirdfactor/web";
+
+const result = await ThirdFactor.verify({
+  url: session.url,
+  mode: "auto",
+  autoClose: true,
+  onEvent: (e) => console.log(e.type),        // ready | completed | error | close
+});
+
+switch (result.status) {
+  case "approved":  showSuccess(); break;      // confirm server-side before trusting
+  case "declined":  showFailure(); break;
+  case "in_review": showPending(); break;
+  case "cancelled": /* user closed the flow — let them retry */ break;
+  case "error":
+    if (result.error?.code === "expired") reMintSession();
+    else showError(result.error);
+    break;
+}
+```
+
+## NFC Verification
+
+**The web SDK has no NFC module.** Reading an ePassport / eID chip requires the
+device NFC radio, which a browser/WebView cannot reach. NFC is therefore a
+**native-only** capability, implemented in the mobile SDKs:
+
+- [iOS — `ThirdFactorKYCNFC`](../ios/README.md#nfc-verification-epassport--eid)
+- [Android — `ThirdFactorNfc`](../android/README.md#nfc-verification-epassport--eid)
+- [Flutter — `ThirdFactorNfc`](../flutter/README.md#nfc-verification-epassport--eid)
+
+On the web, when a workflow includes an `NFC_VERIFICATION` step, the flow
+advertises no `nfc` capability, so the server-side fallback applies (the NFC step
+resolves to manual review). See [`PROTOCOL.md` §8](../../docs/sdk/PROTOCOL.md#8-native-capability-channel-bidirectional).
+
+## End-to-End Workflow
+
+```
+1. Backend  POST /v3/session/  (x-api-key: SECRET)          → { id, url }
+2. Backend  send { url } to the browser
+3. Browser  ThirdFactor.verify({ url })   → opens url?embed=1&sdk=web
+4. Flow     bridge events over postMessage → SDK resolves ONE advisory result
+5. Backend  AUTHORITATIVE decision — do this before granting access:
+              webhook identity.kyc.session.{approved|declined|review|expired}
+              or  GET /v3/session/<id>/decision/
+```
+
+Webhook signature verification (`X-Webhook-Signature: t=…,v1=…`) is documented in
+[`OBSIDIAN_API.md`](../../OBSIDIAN_API.md#verifying-webhook-signatures).
+
+### How it works
+
+`verify()` opens the hosted flow with `?embed=1&sdk=web` appended. In embed mode
+the flow reports lifecycle over `postMessage` instead of redirecting. The SDK
+validates every message against the flow's origin and the `thirdfactor` source tag
+before acting. The same bridge protocol backs the Flutter, iOS, and Android SDKs.
+
+## Local development
+
+```bash
+npm install
+npm run build
+# exercise the SDK against a mock flow — no backend required:
+npx http-server . -p 8899   # then visit /example/index.html
+```
+
+`example/` contains a self-contained test harness (`index.html`) and a mock flow
+(`mock-flow.html`) that speaks the real bridge protocol.

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import type { VerificationResult, VerifyOptions } from "./types.js";
+/**
+ * Open the hosted verification flow and resolve once it reaches a terminal
+ * state, the user cancels, or an error occurs. Never rejects — inspect
+ * `result.status` (and `result.error` when it is `"error"`).
+ *
+ * Call this from a user gesture (click/tap) so popup mode is not blocked.
+ *
+ * ```ts
+ * const result = await ThirdFactor.verify({ url: session.url });
+ * if (result.status === "approved") showSuccess();
+ * // Then confirm server-side before trusting it.
+ * ```
+ */
+export declare function verify(options: VerifyOptions): Promise<VerificationResult>;
+/**
+ * Navigate the whole page to the hosted flow. The flow returns the user to the
+ * session's `callback_url` on completion; read the authoritative decision from
+ * your backend / webhook there. Does not return.
+ */
+export declare function redirect(url: string): void;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,kBAAkB,EAAc,aAAa,EAAE,MAAM,YAAY,CAAC;AAYhF;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAqB1E;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAK1C"}

package/dist/client.js

@@ -0,0 +1,63 @@
+// Public entry points: verify() (modal/popup, resolves a result) and
+// redirect() (full-page navigation, result arrives via your callback_url +
+// webhook).
+import { createModalSurface } from "./modal.js";
+import { createPopupSurface } from "./popup.js";
+import { originOf, withEmbedParams } from "./protocol.js";
+import { runSession } from "./runner.js";
+function resolveMode(mode) {
+    if (mode === "modal" || mode === "popup")
+        return mode;
+    // `auto`: popup is a top-level browsing context, so it works with the flow's
+    // default (strict, anti-clickjacking) headers AND has the most reliable
+    // camera access on every platform. Cross-origin `modal` needs the operator to
+    // allowlist the app origin via FLOW_EMBED_ORIGINS on the flow deployment, and
+    // that can't be feature-detected from here — so it stays explicit opt-in.
+    return "popup";
+}
+/**
+ * Open the hosted verification flow and resolve once it reaches a terminal
+ * state, the user cancels, or an error occurs. Never rejects — inspect
+ * `result.status` (and `result.error` when it is `"error"`).
+ *
+ * Call this from a user gesture (click/tap) so popup mode is not blocked.
+ *
+ * ```ts
+ * const result = await ThirdFactor.verify({ url: session.url });
+ * if (result.status === "approved") showSuccess();
+ * // Then confirm server-side before trusting it.
+ * ```
+ */
+export function verify(options) {
+    if (typeof window === "undefined") {
+        return Promise.resolve({
+            status: "error",
+            error: { code: "no_window", message: "verify() must run in a browser." },
+        });
+    }
+    if (!options?.url) {
+        return Promise.resolve({
+            status: "error",
+            error: { code: "missing_url", message: "options.url is required." },
+        });
+    }
+    const mode = resolveMode(options.mode);
+    const expectedOrigin = options.expectedOrigin || originOf(options.url);
+    const embeddedUrl = withEmbedParams(options.url, "web");
+    const title = options.title || "Identity verification";
+    const surface = mode === "popup" ? createPopupSurface() : createModalSurface(title);
+    return runSession(embeddedUrl, expectedOrigin, options, surface);
+}
+/**
+ * Navigate the whole page to the hosted flow. The flow returns the user to the
+ * session's `callback_url` on completion; read the authoritative decision from
+ * your backend / webhook there. Does not return.
+ */
+export function redirect(url) {
+    if (typeof window === "undefined")
+        return;
+    // Redirect mode has no embedding host, so the flow uses its normal
+    // callback_url redirect — do NOT append the embed flag.
+    window.location.assign(url);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,2EAA2E;AAC3E,YAAY;AAEZ,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,SAAS,WAAW,CAAC,IAA4B;IAC/C,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IACtD,6EAA6E;IAC7E,wEAAwE;IACxE,8EAA8E;IAC9E,8EAA8E;IAC9E,0EAA0E;IAC1E,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,MAAM,CAAC,OAAsB;IAC3C,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO,OAAO,CAAC,OAAO,CAAC;YACrB,MAAM,EAAE,OAAO;YACf,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,iCAAiC,EAAE;SACzE,CAAC,CAAC;IACL,CAAC;IACD,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC;QAClB,OAAO,OAAO,CAAC,OAAO,CAAC;YACrB,MAAM,EAAE,OAAO;YACf,KAAK,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,0BAA0B,EAAE;SACpE,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACvE,MAAM,WAAW,GAAG,eAAe,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,uBAAuB,CAAC;IAEvD,MAAM,OAAO,GAAG,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACpF,OAAO,UAAU,CAAC,WAAW,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AACnE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,OAAO;IAC1C,mEAAmE;IACnE,wDAAwD;IACxD,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC9B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { redirect, verify } from "./client.js";
+export { verify, redirect };
+export type { VerificationEvent, VerificationError, VerificationResult, VerificationStatus, VerifyMode, VerifyOptions, } from "./types.js";
+export { BRIDGE_SOURCE, normalizeStatus, parseBridgeMessage } from "./protocol.js";
+/** Namespace object for `import { ThirdFactor } from "@thirdfactor/web"`. */
+export declare const ThirdFactor: {
+    readonly verify: typeof verify;
+    readonly redirect: typeof redirect;
+};
+export default ThirdFactor;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC5B,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnF,6EAA6E;AAC7E,eAAO,MAAM,WAAW;;;CAAgC,CAAC;AAEzD,eAAe,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+// @thirdfactor/web — browser entry point.
+//
+// Server-side session creation lives in the separate "@thirdfactor/web/server"
+// entry so the browser bundle never imports anything that touches your API key.
+import { redirect, verify } from "./client.js";
+export { verify, redirect };
+export { BRIDGE_SOURCE, normalizeStatus, parseBridgeMessage } from "./protocol.js";
+/** Namespace object for `import { ThirdFactor } from "@thirdfactor/web"`. */
+export const ThirdFactor = { verify, redirect };
+export default ThirdFactor;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAEhF,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAS5B,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnF,6EAA6E;AAC7E,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAW,CAAC;AAEzD,eAAe,WAAW,CAAC"}

package/dist/modal.d.ts

@@ -0,0 +1,3 @@
+import type { Surface } from "./runner.js";
+export declare function createModalSurface(title: string): Surface;
+//# sourceMappingURL=modal.d.ts.map

package/dist/modal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modal.d.ts","sourceRoot":"","sources":["../src/modal.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAK3C,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAyHzD"}

package/dist/modal.js

@@ -0,0 +1,121 @@
+// Full-screen overlay modal surface: a branded backdrop + centered iframe with
+// a close affordance. Camera/microphone are granted to the iframe via `allow`;
+// note that some mobile browsers (notably iOS Safari) restrict getUserMedia in
+// cross-origin iframes — that is why `mode: "auto"` prefers a popup on mobile.
+const OVERLAY_ID = "tf-verify-overlay";
+const Z = 2147483000; // just under max, above app chrome
+export function createModalSurface(title) {
+    let overlay = null;
+    let cancelHandler = null;
+    let onKeyDown = null;
+    let priorOverflow = "";
+    let priorActive = null;
+    const triggerCancel = () => cancelHandler?.();
+    return {
+        onCancel(handler) {
+            cancelHandler = handler;
+        },
+        mount(url) {
+            priorActive = document.activeElement;
+            priorOverflow = document.body.style.overflow;
+            document.body.style.overflow = "hidden"; // lock background scroll
+            overlay = document.createElement("div");
+            overlay.id = OVERLAY_ID;
+            overlay.setAttribute("role", "dialog");
+            overlay.setAttribute("aria-modal", "true");
+            overlay.setAttribute("aria-label", title);
+            Object.assign(overlay.style, {
+                position: "fixed",
+                inset: "0",
+                zIndex: String(Z),
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "center",
+                padding: "0",
+                background: "rgba(15, 23, 42, 0.55)",
+                backdropFilter: "blur(2px)",
+                // Fade in without a stylesheet dependency.
+                animation: "none",
+                opacity: "1",
+            });
+            const frameWrap = document.createElement("div");
+            Object.assign(frameWrap.style, {
+                position: "relative",
+                width: "100%",
+                height: "100%",
+                maxWidth: "480px",
+                maxHeight: "820px",
+                background: "#fff",
+                borderRadius: "16px",
+                overflow: "hidden",
+                boxShadow: "0 24px 60px rgba(0,0,0,0.35)",
+            });
+            // On small viewports go edge-to-edge.
+            if (window.innerWidth < 520 || window.innerHeight < 860) {
+                frameWrap.style.maxWidth = "100%";
+                frameWrap.style.maxHeight = "100%";
+                frameWrap.style.borderRadius = "0";
+            }
+            const iframe = document.createElement("iframe");
+            iframe.src = url;
+            iframe.title = title;
+            iframe.allow = "camera; microphone; fullscreen; geolocation; clipboard-write";
+            iframe.setAttribute("allowfullscreen", "true");
+            Object.assign(iframe.style, {
+                width: "100%",
+                height: "100%",
+                border: "0",
+                display: "block",
+            });
+            const closeBtn = document.createElement("button");
+            closeBtn.type = "button";
+            closeBtn.setAttribute("aria-label", "Close verification");
+            closeBtn.innerHTML =
+                '<svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true">' +
+                    '<path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" stroke-width="1.75" stroke-linecap="round"/></svg>';
+            Object.assign(closeBtn.style, {
+                position: "absolute",
+                top: "12px",
+                right: "12px",
+                width: "32px",
+                height: "32px",
+                display: "grid",
+                placeItems: "center",
+                borderRadius: "9999px",
+                border: "0",
+                cursor: "pointer",
+                color: "#0f172a",
+                background: "rgba(255,255,255,0.9)",
+                boxShadow: "0 1px 4px rgba(0,0,0,0.2)",
+            });
+            closeBtn.addEventListener("click", triggerCancel);
+            frameWrap.appendChild(iframe);
+            frameWrap.appendChild(closeBtn);
+            overlay.appendChild(frameWrap);
+            document.body.appendChild(overlay);
+            // Esc closes; backdrop click closes.
+            onKeyDown = (e) => {
+                if (e.key === "Escape")
+                    triggerCancel();
+            };
+            document.addEventListener("keydown", onKeyDown);
+            overlay.addEventListener("click", (e) => {
+                if (e.target === overlay)
+                    triggerCancel();
+            });
+            closeBtn.focus();
+        },
+        unmount() {
+            if (onKeyDown) {
+                document.removeEventListener("keydown", onKeyDown);
+                onKeyDown = null;
+            }
+            overlay?.remove();
+            overlay = null;
+            document.body.style.overflow = priorOverflow;
+            if (priorActive instanceof HTMLElement)
+                priorActive.focus();
+        },
+    };
+}
+//# sourceMappingURL=modal.js.map

package/dist/modal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modal.js","sourceRoot":"","sources":["../src/modal.ts"],"names":[],"mappings":"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"}

package/dist/popup.d.ts

@@ -0,0 +1,3 @@
+import { type Surface } from "./runner.js";
+export declare function createPopupSurface(): Surface;
+//# sourceMappingURL=popup.d.ts.map

package/dist/popup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"popup.d.ts","sourceRoot":"","sources":["../src/popup.ts"],"names":[],"mappings":"AAIA,OAAO,EAAqB,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAE9D,wBAAgB,kBAAkB,IAAI,OAAO,CA6C5C"}

package/dist/popup.js

@@ -0,0 +1,49 @@
+// Popup / new-tab surface. A top-level browsing context has the most reliable
+// camera access, which is why `mode: "auto"` uses it on mobile. Must be invoked
+// synchronously from a user gesture or the browser will block window.open.
+import { PopupBlockedError } from "./runner.js";
+export function createPopupSurface() {
+    let popup = null;
+    let poll = null;
+    let cancelHandler = null;
+    const stopPoll = () => {
+        if (poll !== null) {
+            window.clearInterval(poll);
+            poll = null;
+        }
+    };
+    return {
+        onCancel(handler) {
+            cancelHandler = handler;
+        },
+        mount(url) {
+            const w = 480;
+            const h = Math.min(820, window.screen.availHeight || 820);
+            const left = window.screenX + Math.max(0, ((window.outerWidth || w) - w) / 2);
+            const top = window.screenY + Math.max(0, ((window.outerHeight || h) - h) / 2);
+            const features = `popup=yes,width=${w},height=${h},left=${Math.round(left)},top=${Math.round(top)}`;
+            popup = window.open(url, "thirdfactor-verify", features);
+            if (!popup)
+                throw new PopupBlockedError();
+            // Detect a user closing the tab/window before the flow reports a result.
+            poll = window.setInterval(() => {
+                if (popup && popup.closed) {
+                    stopPoll();
+                    cancelHandler?.();
+                }
+            }, 500);
+        },
+        unmount() {
+            stopPoll();
+            try {
+                if (popup && !popup.closed)
+                    popup.close();
+            }
+            catch {
+                /* cross-origin close guard */
+            }
+            popup = null;
+        },
+    };
+}
+//# sourceMappingURL=popup.js.map

package/dist/popup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"popup.js","sourceRoot":"","sources":["../src/popup.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,gFAAgF;AAChF,2EAA2E;AAE3E,OAAO,EAAE,iBAAiB,EAAgB,MAAM,aAAa,CAAC;AAE9D,MAAM,UAAU,kBAAkB;IAChC,IAAI,KAAK,GAAkB,IAAI,CAAC;IAChC,IAAI,IAAI,GAAkB,IAAI,CAAC;IAC/B,IAAI,aAAa,GAAwB,IAAI,CAAC;IAE9C,MAAM,QAAQ,GAAG,GAAG,EAAE;QACpB,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;YAC3B,IAAI,GAAG,IAAI,CAAC;QACd,CAAC;IACH,CAAC,CAAC;IAEF,OAAO;QACL,QAAQ,CAAC,OAAO;YACd,aAAa,GAAG,OAAO,CAAC;QAC1B,CAAC;QAED,KAAK,CAAC,GAAG;YACP,MAAM,CAAC,GAAG,GAAG,CAAC;YACd,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,WAAW,IAAI,GAAG,CAAC,CAAC;YAC1D,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,UAAU,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC9E,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,WAAW,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC9E,MAAM,QAAQ,GAAG,mBAAmB,CAAC,WAAW,CAAC,SAAS,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YACpG,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,oBAAoB,EAAE,QAAQ,CAAC,CAAC;YACzD,IAAI,CAAC,KAAK;gBAAE,MAAM,IAAI,iBAAiB,EAAE,CAAC;YAE1C,yEAAyE;YACzE,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE;gBAC7B,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;oBAC1B,QAAQ,EAAE,CAAC;oBACX,aAAa,EAAE,EAAE,CAAC;gBACpB,CAAC;YACH,CAAC,EAAE,GAAG,CAAC,CAAC;QACV,CAAC;QAED,OAAO;YACL,QAAQ,EAAE,CAAC;YACX,IAAI,CAAC;gBACH,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM;oBAAE,KAAK,CAAC,KAAK,EAAE,CAAC;YAC5C,CAAC;YAAC,MAAM,CAAC;gBACP,8BAA8B;YAChC,CAAC;YACD,KAAK,GAAG,IAAI,CAAC;QACf,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,27 @@
+import type { VerificationEvent, VerificationStatus } from "./types.js";
+/** Must match TF_BRIDGE_SOURCE in the flow bridge. */
+export declare const BRIDGE_SOURCE = "thirdfactor";
+/**
+ * Validate and narrow an untrusted postMessage payload into a typed event.
+ * Returns null for anything that isn't one of our bridge events, so callers can
+ * safely ignore unrelated messages (analytics beacons, other embeds, etc.).
+ *
+ * Origin checking is the CALLER's job and must happen before this — see
+ * `messageMatches`.
+ */
+export declare function parseBridgeMessage(data: unknown): VerificationEvent | null;
+/**
+ * Map a raw server session status onto the normalized SDK status.
+ * Unknown terminal statuses fall back to `in_review` — the conservative choice,
+ * since an unrecognized outcome should get a human look rather than silently
+ * pass or fail.
+ */
+export declare function normalizeStatus(raw: string): VerificationStatus;
+/** Origin of a URL string, or "" if it can't be parsed. */
+export declare function originOf(url: string): string;
+/**
+ * Append the embed flag + platform tag the flow's bridge looks for, preserving
+ * any existing query/hash on the URL.
+ */
+export declare function withEmbedParams(url: string, platform?: string): string;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAExE,sDAAsD;AACtD,eAAO,MAAM,aAAa,gBAAgB,CAAC;AAE3C;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAwB1E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAkB/D;AAED,2DAA2D;AAC3D,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM5C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAQ,GAAG,MAAM,CAWrE"}

package/dist/protocol.js

@@ -0,0 +1,92 @@
+// Wire protocol shared with the hosted flow's bridge
+// (frontend/components/verify/sdk-bridge.ts). Keep the source tag and event
+// shapes in lock-step with that file.
+/** Must match TF_BRIDGE_SOURCE in the flow bridge. */
+export const BRIDGE_SOURCE = "thirdfactor";
+/**
+ * Validate and narrow an untrusted postMessage payload into a typed event.
+ * Returns null for anything that isn't one of our bridge events, so callers can
+ * safely ignore unrelated messages (analytics beacons, other embeds, etc.).
+ *
+ * Origin checking is the CALLER's job and must happen before this — see
+ * `messageMatches`.
+ */
+export function parseBridgeMessage(data) {
+    if (!data || typeof data !== "object")
+        return null;
+    const d = data;
+    if (d.source !== BRIDGE_SOURCE)
+        return null;
+    switch (d.type) {
+        case "ready":
+            return { type: "ready" };
+        case "completed":
+            return {
+                type: "completed",
+                status: String(d.status ?? ""),
+                sessionId: d.sessionId != null ? String(d.sessionId) : undefined,
+            };
+        case "error":
+            return {
+                type: "error",
+                code: String(d.code ?? "unknown"),
+                message: d.message != null ? String(d.message) : undefined,
+            };
+        case "close":
+            return { type: "close" };
+        default:
+            return null;
+    }
+}
+/**
+ * Map a raw server session status onto the normalized SDK status.
+ * Unknown terminal statuses fall back to `in_review` — the conservative choice,
+ * since an unrecognized outcome should get a human look rather than silently
+ * pass or fail.
+ */
+export function normalizeStatus(raw) {
+    switch (raw) {
+        case "approved":
+            return "approved";
+        case "declined":
+            return "declined";
+        case "in_review":
+        case "review":
+        case "manual_review":
+        case "pending":
+            return "in_review";
+        case "abandoned":
+        case "cancelled":
+        case "canceled":
+            return "cancelled";
+        default:
+            return "in_review";
+    }
+}
+/** Origin of a URL string, or "" if it can't be parsed. */
+export function originOf(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Append the embed flag + platform tag the flow's bridge looks for, preserving
+ * any existing query/hash on the URL.
+ */
+export function withEmbedParams(url, platform = "web") {
+    try {
+        const u = new URL(url);
+        u.searchParams.set("embed", "1");
+        u.searchParams.set("sdk", platform);
+        return u.toString();
+    }
+    catch {
+        // Fall back to a naive append if URL() is unavailable/relative.
+        const sep = url.includes("?") ? "&" : "?";
+        return `${url}${sep}embed=1&sdk=${platform}`;
+    }
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,4EAA4E;AAC5E,sCAAsC;AAItC,sDAAsD;AACtD,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAC;AAE3C;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAa;IAC9C,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACnD,MAAM,CAAC,GAAG,IAA+B,CAAC;IAC1C,IAAI,CAAC,CAAC,MAAM,KAAK,aAAa;QAAE,OAAO,IAAI,CAAC;IAC5C,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,OAAO;YACV,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QAC3B,KAAK,WAAW;YACd,OAAO;gBACL,IAAI,EAAE,WAAW;gBACjB,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC;gBAC9B,SAAS,EAAE,CAAC,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS;aACjE,CAAC;QACJ,KAAK,OAAO;YACV,OAAO;gBACL,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,SAAS,CAAC;gBACjC,OAAO,EAAE,CAAC,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS;aAC3D,CAAC;QACJ,KAAK,OAAO;YACV,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QAC3B;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,UAAU;YACb,OAAO,UAAU,CAAC;QACpB,KAAK,UAAU;YACb,OAAO,UAAU,CAAC;QACpB,KAAK,WAAW,CAAC;QACjB,KAAK,QAAQ,CAAC;QACd,KAAK,eAAe,CAAC;QACrB,KAAK,SAAS;YACZ,OAAO,WAAW,CAAC;QACrB,KAAK,WAAW,CAAC;QACjB,KAAK,WAAW,CAAC;QACjB,KAAK,UAAU;YACb,OAAO,WAAW,CAAC;QACrB;YACE,OAAO,WAAW,CAAC;IACvB,CAAC;AACH,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,QAAQ,GAAG,KAAK;IAC3D,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACjC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACpC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,gEAAgE;QAChE,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;QAC1C,OAAO,GAAG,GAAG,GAAG,GAAG,eAAe,QAAQ,EAAE,CAAC;IAC/C,CAAC;AACH,CAAC"}

package/dist/runner.d.ts

@@ -0,0 +1,16 @@
+import type { VerificationResult, VerifyOptions } from "./types.js";
+/** A presentation surface (modal iframe or popup window). */
+export interface Surface {
+    /** Show the surface pointed at `url`. Throws on hard failure (e.g. popup
+     *  blocked) so the runner can resolve an error result. */
+    mount(url: string): void;
+    /** Tear the surface down. Idempotent. */
+    unmount(): void;
+    /** Register the user-initiated dismiss handler (× button, Esc, closed tab). */
+    onCancel(handler: () => void): void;
+}
+export declare function runSession(embeddedUrl: string, expectedOrigin: string, opts: VerifyOptions, surface: Surface): Promise<VerificationResult>;
+export declare class PopupBlockedError extends Error {
+    constructor();
+}
+//# sourceMappingURL=runner.d.ts.map

package/dist/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEpE,6DAA6D;AAC7D,MAAM,WAAW,OAAO;IACtB;8DAC0D;IAC1D,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,yCAAyC;IACzC,OAAO,IAAI,IAAI,CAAC;IAChB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CACrC;AAED,wBAAgB,UAAU,CACxB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,kBAAkB,CAAC,CAsE7B;AAED,qBAAa,iBAAkB,SAAQ,KAAK;;CAK3C"}

package/dist/runner.js

@@ -0,0 +1,84 @@
+// Shared session runner used by both the modal and popup surfaces.
+//
+// It owns the one piece of logic that must be identical across surfaces: the
+// origin-validated message loop and how bridge events resolve into a single
+// VerificationResult. Surfaces only handle presentation + user-cancel.
+import { parseBridgeMessage, normalizeStatus } from "./protocol.js";
+export function runSession(embeddedUrl, expectedOrigin, opts, surface) {
+    return new Promise((resolve) => {
+        let settled = false;
+        // The authoritative result from a `completed`/`error` bridge event, if one
+        // arrived. A subsequent `close` (user tapped Done) then dismisses with THIS
+        // result rather than treating the dismiss as a cancel.
+        let pending = null;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            window.removeEventListener("message", onMessage);
+            surface.unmount();
+            resolve(result);
+        };
+        const onMessage = (ev) => {
+            if (expectedOrigin && ev.origin !== expectedOrigin)
+                return;
+            const event = parseBridgeMessage(ev.data);
+            if (!event)
+                return;
+            opts.onEvent?.(event);
+            switch (event.type) {
+                case "ready":
+                    return;
+                case "completed": {
+                    const result = {
+                        status: normalizeStatus(event.status),
+                        sessionId: event.sessionId,
+                        rawStatus: event.status,
+                    };
+                    if (opts.autoClose === false) {
+                        // Keep the flow's result screen up; dismiss on the later `close`.
+                        pending = result;
+                    }
+                    else {
+                        finish(result);
+                    }
+                    return;
+                }
+                case "error": {
+                    finish({
+                        status: "error",
+                        error: { code: event.code, message: event.message ?? event.code },
+                    });
+                    return;
+                }
+                case "close": {
+                    // User acknowledged. If a terminal result is pending, deliver it;
+                    // otherwise the user dismissed mid-flow → cancelled.
+                    finish(pending ?? { status: "cancelled" });
+                    return;
+                }
+            }
+        };
+        window.addEventListener("message", onMessage);
+        surface.onCancel(() => finish(pending ?? { status: "cancelled" }));
+        try {
+            surface.mount(embeddedUrl);
+        }
+        catch (err) {
+            finish({
+                status: "error",
+                error: {
+                    code: err instanceof PopupBlockedError ? "popup_blocked" : "load_error",
+                    message: err instanceof Error ? err.message : String(err),
+                },
+            });
+        }
+    });
+}
+export class PopupBlockedError extends Error {
+    constructor() {
+        super("The verification popup was blocked. Call verify() from a click handler.");
+        this.name = "PopupBlockedError";
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,57 @@
+export interface CreateSessionInput {
+    /** KYC workflow UUID. Omit to use the tenant's default workflow. */
+    workflowId?: string;
+    /** Your external user reference; becomes the linked identity's external id. */
+    vendorData?: string;
+    /** Where the applicant is redirected after finishing (redirect mode). */
+    callbackUrl?: string;
+    contactEmail?: string;
+    contactPhone?: string;
+    /** Hosted URL lifetime in hours, 1..720 (default 48). */
+    expiresInHours?: number;
+    /** UI language, e.g. "en" | "ne". */
+    locale?: string;
+    /** Applicant fields to pre-fill (only the documented keys are honored). */
+    prefill?: Record<string, string>;
+    /** Idempotency key — repeat creates return the original session, uncharged. */
+    idempotencyKey?: string;
+}
+export interface Session {
+    id: string;
+    status: string;
+    /** Hand this to `ThirdFactor.verify({ url })` (or redirect) in the browser. */
+    url: string;
+    decision: string;
+    vendorData?: string | null;
+    expiresAt?: string | null;
+    createdAt?: string | null;
+    /** The raw response body, in case you need a field not surfaced above. */
+    raw: Record<string, unknown>;
+}
+export interface CreateSessionConfig {
+    /** Your Obsidian base URL, e.g. "https://kyc.acme.com". No trailing slash. */
+    baseUrl: string;
+    /** Tenant API key (Console → Settings → API keys). Server-side only. */
+    apiKey: string;
+    /** Override fetch (tests, custom agents). Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+export declare class ThirdFactorApiError extends Error {
+    status: number;
+    code: string;
+    constructor(status: number, code: string, message: string);
+}
+/**
+ * Create a verification session via `POST /v3/session/`.
+ *
+ * ```ts
+ * import { createSession } from "@thirdfactor/web/server";
+ * const session = await createSession(
+ *   { baseUrl: process.env.TF_BASE_URL!, apiKey: process.env.TF_API_KEY! },
+ *   { vendorData: user.id, callbackUrl: "https://app.acme.com/kyc/done" },
+ * );
+ * // return { url: session.url, id: session.id } to the browser.
+ * ```
+ */
+export declare function createSession(config: CreateSessionConfig, input?: CreateSessionInput): Promise<Session>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,+EAA+E;IAC/E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;gBACD,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAM1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,mBAAmB,EAC3B,KAAK,GAAE,kBAAuB,GAC7B,OAAO,CAAC,OAAO,CAAC,CAmDlB"}

package/dist/server.js

@@ -0,0 +1,82 @@
+// Optional server helper (`@thirdfactor/web/server`) for creating a KYC session
+// from your Node backend. Runs ONLY on the server — it uses your secret API
+// key, which must never reach the browser. Node 18+ (global fetch) or any
+// runtime with a WHATWG `fetch`.
+export class ThirdFactorApiError extends Error {
+    constructor(status, code, message) {
+        super(message);
+        this.name = "ThirdFactorApiError";
+        this.status = status;
+        this.code = code;
+    }
+}
+/**
+ * Create a verification session via `POST /v3/session/`.
+ *
+ * ```ts
+ * import { createSession } from "@thirdfactor/web/server";
+ * const session = await createSession(
+ *   { baseUrl: process.env.TF_BASE_URL!, apiKey: process.env.TF_API_KEY! },
+ *   { vendorData: user.id, callbackUrl: "https://app.acme.com/kyc/done" },
+ * );
+ * // return { url: session.url, id: session.id } to the browser.
+ * ```
+ */
+export async function createSession(config, input = {}) {
+    const doFetch = config.fetchImpl ?? globalThis.fetch;
+    if (typeof doFetch !== "function") {
+        throw new ThirdFactorApiError(0, "no_fetch", "No fetch implementation available (Node 18+ or pass fetchImpl).");
+    }
+    const base = config.baseUrl.replace(/\/+$/, "");
+    const body = {};
+    if (input.workflowId)
+        body.workflow_id = input.workflowId;
+    if (input.vendorData)
+        body.vendor_data = input.vendorData;
+    if (input.callbackUrl)
+        body.callback_url = input.callbackUrl;
+    if (input.contactEmail)
+        body.contact_email = input.contactEmail;
+    if (input.contactPhone)
+        body.contact_phone = input.contactPhone;
+    if (input.expiresInHours != null)
+        body.expires_in_hours = input.expiresInHours;
+    if (input.locale)
+        body.locale = input.locale;
+    if (input.prefill)
+        body.prefill = input.prefill;
+    const headers = {
+        "content-type": "application/json",
+        "x-api-key": config.apiKey,
+    };
+    if (input.idempotencyKey)
+        headers["Idempotency-Key"] = input.idempotencyKey;
+    const res = await doFetch(`${base}/v3/session/`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    let json = {};
+    try {
+        json = text ? JSON.parse(text) : {};
+    }
+    catch {
+        /* non-JSON error body */
+    }
+    if (!res.ok) {
+        const code = typeof json.detail === "string" ? json.detail : `http_${res.status}`;
+        throw new ThirdFactorApiError(res.status, code, `Session create failed (${res.status}): ${code}`);
+    }
+    return {
+        id: String(json.id ?? ""),
+        status: String(json.status ?? ""),
+        url: String(json.url ?? ""),
+        decision: String(json.decision ?? ""),
+        vendorData: json.vendor_data ?? null,
+        expiresAt: json.expires_at ?? null,
+        createdAt: json.created_at ?? null,
+        raw: json,
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,69 @@
+/** Normalized terminal outcome the SDK resolves with. */
+export type VerificationStatus = "approved" | "declined" | "in_review" | "cancelled" | "error";
+export interface VerificationError {
+    /** Stable machine code: invalid_session | expired | popup_blocked |
+     *  load_error | network | unknown. Branch on this, not `message`. */
+    code: string;
+    message: string;
+}
+export interface VerificationResult {
+    status: VerificationStatus;
+    /** The verification session id (echoed from the flow when available). */
+    sessionId?: string;
+    /** Populated only when `status === "error"`. */
+    error?: VerificationError;
+    /** The raw server status when it differs from the normalized one
+     *  (e.g. "abandoned" normalizes to "cancelled"). */
+    rawStatus?: string;
+}
+/** Lifecycle events emitted while the flow is open. */
+export type VerificationEvent = {
+    type: "ready";
+} | {
+    type: "completed";
+    status: string;
+    sessionId?: string;
+} | {
+    type: "error";
+    code: string;
+    message?: string;
+} | {
+    type: "close";
+};
+/**
+ * How the hosted flow is presented.
+ * - `modal`   — full-screen overlay iframe. Best desktop UX.
+ * - `popup`   — a new tab/window. Most reliable camera access on mobile.
+ * - `auto`    — modal on desktop, popup on mobile (default).
+ *
+ * Full-page `redirect` is a separate call, `ThirdFactor.redirect(url)`, because
+ * it navigates away and cannot return a Promise.
+ */
+export type VerifyMode = "modal" | "popup" | "auto";
+export interface VerifyOptions {
+    /**
+     * The hosted session URL returned by `POST /v3/session/` (the `url` field),
+     * e.g. `https://kyc.acme.com/verify/<token>`. Create the session from your
+     * backend with your secret API key — never in the browser.
+     */
+    url: string;
+    /** Presentation mode. Default `auto`. */
+    mode?: VerifyMode;
+    /** Called for every lifecycle event (ready/completed/error/close). */
+    onEvent?: (event: VerificationEvent) => void;
+    /** Accessible label for the modal dialog. Default "Identity verification". */
+    title?: string;
+    /**
+     * Origin the SDK will accept postMessage from. Defaults to the origin of
+     * `url`. Only override if the flow renders on a different origin than the URL
+     * you pass (rare — e.g. a proxy).
+     */
+    expectedOrigin?: string;
+    /**
+     * Auto-dismiss the surface once a terminal result arrives. Default `true`.
+     * Set `false` to keep the flow's own result screen visible until the user
+     * taps "Done" (which then dismisses).
+     */
+    autoClose?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAaA,yDAAyD;AACzD,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,UAAU,GACV,WAAW,GACX,WAAW,GACX,OAAO,CAAC;AAEZ,MAAM,WAAW,iBAAiB;IAChC;yEACqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B;wDACoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,uDAAuD;AACvD,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AAEpD,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,sEAAsE;IACtE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC7C,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB"}

package/dist/types.js

@@ -0,0 +1,14 @@
+// Public type surface for @thirdfactor/web.
+//
+// The result vocabulary is deliberately small and identical across all four
+// ThirdFactor SDKs (web / Flutter / iOS / Android):
+//
+//   approved | declined | in_review | cancelled | error
+//
+// The client-reported result is a UX signal, NOT the source of truth. Always
+// confirm the authoritative decision server-side — via the KYC webhook
+// (identity.kyc.session.*) or GET /v3/session/<id>/decision/ — before granting
+// access or moving money. A user can close the tab after approval, or tamper
+// with the browser; the webhook cannot be spoofed (it is HMAC-signed).
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,EAAE;AACF,4EAA4E;AAC5E,oDAAoD;AACpD,EAAE;AACF,wDAAwD;AACxD,EAAE;AACF,6EAA6E;AAC7E,uEAAuE;AACvE,+EAA+E;AAC/E,6EAA6E;AAC7E,uEAAuE"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@thirdfactor/web",
+  "version": "1.0.0",
+  "description": "ThirdFactor / Obsidian KYC — web client SDK. Opens the hosted verification flow in a modal, popup, or full-page redirect and returns a typed result.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "keywords": ["kyc", "identity", "verification", "thirdfactor", "obsidian", "aml"],
+  "license": "UNLICENSED",
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}