@soliton-id/web-sdk 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to `@soliton-id/web-sdk`. The `soliton-v1` postMessage
+protocol is frozen: changes are additive only, so older SDK versions keep
+working against the hosted flow.
+
+## 1.0.0 — 2026-08-01
+
+First public release.
+
+- `open({ url, onComplete, onError, onClose, locale })` opens a verification
+  (minted server-side via `POST /api/v1/verifications`) in a full-viewport
+  overlay iframe and returns a handle with `close()`.
+- Ships ESM + CJS + TypeScript declarations; also available from the hosted
+  classic and cross-origin ESM bundles under `https://soliton.id/sdk/v1/`.
+- Refuses to frame attacker-controlled hosts: verification URLs are pinned to
+  the production/staging Soliton origins, with explicit HTTP localhost
+  exceptions for development.
+- Callbacks carry lifecycle only; verdicts are only ever released
+  server-to-server against your API key.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Soliton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# @soliton-id/web-sdk
+
+Soliton identity verification for the browser. `open()` overlays the Soliton
+hosted verification flow on your page in a full-viewport iframe, so your user
+never leaves your site, and reports lifecycle events back to your code. The
+capture engine itself always runs on soliton.id inside the iframe, which is
+why anti-injection and anti-deepfake defenses update continuously without you
+shipping anything.
+
+Web SDK guide (this package): <https://soliton.id/docs/integration/sdk>
+Server API guide (create, verdicts, portraits):
+<https://soliton.id/docs/integration/api>
+
+## Install
+
+```bash
+npm install @soliton-id/web-sdk
+```
+
+No runtime dependencies, no framework requirements, ~7 KB unminified.
+
+Prefer a script tag? The same API ships as a hosted bundle that updates with
+every Soliton deploy:
+
+```html
+<script src="https://soliton.id/sdk/v1/soliton-web-sdk.js"></script>
+<!-- exposes the global SolitonVerify; SolitonVerify.open({...}) -->
+```
+
+A cross-origin-enabled hosted ESM build is also available for direct browser
+imports at
+`https://soliton.id/sdk/v1/soliton-web-sdk.esm.js`. If you use either hosted
+build, allow `https://soliton.id` in your page's `script-src`; an app that
+bundles the npm package does not need that remote script source.
+
+## Quickstart
+
+Your backend creates a verification with your secret API key (never do this
+from the browser), hands the returned `url` to your page, and your page opens
+it:
+
+```ts
+import { open } from "@soliton-id/web-sdk";
+// also available: import SolitonVerify from "@soliton-id/web-sdk";
+//                 SolitonVerify.open({...})
+
+// Fetch this from YOUR backend, which called POST /api/v1/verifications.
+const { url } = await fetch("/your-api/start-verification").then(r => r.json());
+
+const handle = open({
+  url,
+  onComplete: ({ verificationId }) => {
+    // The flow reached a terminal state (pass OR final fail; deliberately
+    // not disclosed here). Treat this purely as a "check now" signal and
+    // have YOUR BACKEND fetch the result. See "Getting the result" below.
+  },
+  onError: ({ code, message }) => {
+    // link_expired | link_invalid | origin_not_allowed |
+    // storage_unavailable | internal
+  },
+  onClose: () => {
+    // The user dismissed the flow before completion.
+  },
+});
+
+// handle.close() dismisses the overlay programmatically.
+```
+
+The overlay is always full-viewport: the flow runs a screen-light challenge
+that needs the whole screen, so it cannot be clipped into a widget.
+
+## Callback semantics
+
+- `onComplete({ verificationId })`: fired once, when the user reaches a
+  terminal state. It carries ONLY the verification id, never a verdict.
+- `onError({ code, message })`: flow-level errors (`link_expired`,
+  `link_invalid`, `origin_not_allowed`, `storage_unavailable` when the user's
+  browser blocks the session storage the flow needs, `internal`). The overlay
+  stays open so the hosted page can show its own error card; call
+  `handle.close()` if you want it gone.
+- `onClose()`: the user dismissed the flow (the X button, the hosted Cancel,
+  or `handle.close()`) before completion. Not fired after `onComplete`.
+
+## Getting the result (server-to-server only)
+
+`onComplete` gives you an id. Everything sensitive is then fetched by YOUR
+BACKEND with your API key:
+
+1. `GET /api/v1/verifications/{id}`: the verdict (`verified`,
+   `partial_verification`, plus `portrait_available`).
+2. `GET /api/v1/verifications/{id}/portrait`: a JPEG portrait of the verified
+   user, selected server-side from the capture under neutral lighting.
+   Returns 404 until the verification is complete or when no acceptable
+   portrait frame existed. Right after completion, `portrait_available` can
+   briefly read `false` while extraction finishes; once status is `complete`
+   just fetch the portrait and treat a 404 after one short retry as final.
+
+Your page and the SDK never see the verdict or the portrait: callbacks and
+postMessage payloads carry only the verification id, and both results are
+released exclusively to your backend against your API key. The hosted screen
+does tell the end user how their own attempt went, with no detail about which
+checks ran or why, but that screen is for the user, not for your integration:
+the browser side (your user, your page, their extensions) is untrusted by
+design, and any machine-readable pass/fail surfaced to your page would hand
+fraudsters an oracle for tuning attacks. Your backend is the only place the
+result exists for you, which is also what makes it trustworthy.
+
+### Bind the verification to your user
+
+You already know the `verificationId` when you create the verification: store
+it server-side against your authenticated user or session at that moment.
+When `onComplete` fires, have your backend fetch the id it stored, never the
+id from the callback. An end user controls everything in their browser,
+including that callback value, and could substitute a different id, such as
+one that previously passed. Comparing the callback id against your stored one
+is fine; using it as the lookup key is not. Set `client_reference_id` at
+creation and check it on every status read to make this auditable.
+
+## Frame-origin registration
+
+Embedding is off by default and gated on BOTH layers:
+
+1. Your API key must have the exact origins of the pages that will embed the
+   flow registered (scheme + host + port, e.g. `https://app.example.com`).
+   Ask us to register yours.
+2. The same origins must be present in the soliton.id deploy-time frame
+   ancestors allowlist (we handle this when we register your key).
+
+A verification link opened inside an iframe on any other origin refuses to
+start and reports `origin_not_allowed`.
+
+During the invite-only pilot, Soliton manually manages both layers. Send your
+Soliton contact every exact production, staging, and local origin before
+testing. Wildcards are not accepted, and adding or changing an origin can
+require a Soliton deployment.
+
+## Customer security headers
+
+If your embedding page sends restrictive response headers, merge these
+sources into its existing policies (do not replace the rest of your policy
+with this example):
+
+```text
+Content-Security-Policy: frame-src https://soliton.id https://staging.soliton.id; script-src https://soliton.id https://staging.soliton.id
+Permissions-Policy: camera=(self "https://soliton.id" "https://staging.soliton.id"), microphone=(self "https://soliton.id" "https://staging.soliton.id")
+```
+
+- `frame-src` must include the Soliton origin you use because the capture flow
+  runs in a Soliton iframe.
+- `script-src` must include the Soliton origin you use only for the classic
+  script or hosted ESM distribution. It is not needed when your application
+  bundles the npm package.
+- If your top-level `Permissions-Policy` explicitly restricts camera or
+  microphone, delegate both features to the production and/or staging Soliton
+  origin you use. The SDK already sets the matching
+  `allow="camera; microphone"` attribute on its iframe.
+
+For local development, add the exact localhost origin (including its port) to
+the corresponding directives as well.
+
+## Pilot test keys
+
+`sk_test_` identifies a pilot credential; it is not an isolated or simulated
+sandbox. Test keys use the same hosted capture, biometric processing, and data
+handling as live keys. The prefix does not create synthetic results or trigger
+automatic deletion. Use only informed, consenting pilot participants, give
+them your applicable privacy notice, and follow your Soliton pilot terms.
+
+## How it works
+
+`open()` accepts hosted URLs only from `https://soliton.id` or
+`https://staging.soliton.id` (plus HTTP localhost/127.0.0.1 development URLs),
+requires a `/v/{token}` path, and preserves query parameters. It renders a
+full-viewport overlay with an iframe pointing at that validated origin and
+listens for the hosted page's lifecycle messages. Every message is checked
+three ways (origin, source window, protocol marker) before it reaches your
+callbacks, and unknown message types are ignored, so wrapper versions stay
+compatible as the hosted flow evolves. Redirect-style integration (no SDK,
+we redirect the user back to you) remains fully supported; the same
+verification URL works in both modes.

package/dist/hostedUrl.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Validation of the hosted verification URL handed to SolitonVerify.open().
+ *
+ * The SDK only ever frames URLs that look exactly like the ones minted by
+ * POST /api/v1/verifications: an approved Soliton origin (http strictly for
+ * localhost dev) and a bare /v/{32 hex} path. Everything else throws
+ * synchronously — a bad URL is an integration bug, not a runtime flow event,
+ * so it must fail loudly at the call site instead of rendering an
+ * attacker-chosen page in our overlay.
+ */
+export interface ParsedHostedUrl {
+    /** The validated URL, normalized by the URL parser. */
+    url: URL;
+    /** Origin the SDK will trust for postMessage events. */
+    hostedOrigin: string;
+}
+export declare function parseHostedUrl(raw: string): ParsedHostedUrl;

package/dist/index.cjs

@@ -0,0 +1,259 @@
+/* Soliton Web SDK v1. Built from sdk/src via `npm run build:sdk`; do not edit by hand. */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// sdk/src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SolitonVerify: () => SolitonVerify,
+  default: () => index_default,
+  open: () => open
+});
+module.exports = __toCommonJS(index_exports);
+
+// sdk/src/hostedUrl.ts
+var HOSTED_PATH_RE = /^\/v\/[0-9a-f]{32}$/;
+var ALLOWED_HTTPS_ORIGINS = /* @__PURE__ */ new Set([
+  "https://soliton.id",
+  "https://staging.soliton.id"
+]);
+function parseHostedUrl(raw) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch (e) {
+    throw new Error(`SolitonVerify: "url" is not a valid absolute URL`);
+  }
+  const isLocalHttp = url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
+  if (!ALLOWED_HTTPS_ORIGINS.has(url.origin) && !isLocalHttp) {
+    throw new Error(
+      'SolitonVerify: "url" must be hosted on https://soliton.id or https://staging.soliton.id (http is allowed for localhost/127.0.0.1 development only)'
+    );
+  }
+  if (url.username || url.password) {
+    throw new Error('SolitonVerify: "url" must not embed credentials');
+  }
+  if (!HOSTED_PATH_RE.test(url.pathname)) {
+    throw new Error(
+      'SolitonVerify: "url" does not look like a hosted verification URL (/v/{token})'
+    );
+  }
+  return { url, hostedOrigin: url.origin };
+}
+
+// sdk/src/overlay.ts
+var MAX_Z_INDEX = "2147483647";
+var openOverlayCount = 0;
+var savedBodyOverflow = "";
+function createOverlay(iframeSrc, onCloseClick) {
+  const doc = document;
+  const container = doc.createElement("div");
+  container.setAttribute("data-soliton-sdk", "overlay");
+  container.style.cssText = [
+    "position:fixed",
+    "inset:0",
+    `z-index:${MAX_Z_INDEX}`,
+    "background:#0f110b",
+    "display:block"
+  ].join(";");
+  const style = doc.createElement("style");
+  style.textContent = "@keyframes soliton-sdk-spin{to{transform:rotate(360deg)}}";
+  container.appendChild(style);
+  const loading = doc.createElement("div");
+  loading.setAttribute("data-soliton-sdk", "loading");
+  loading.style.cssText = [
+    "position:absolute",
+    "inset:0",
+    "display:flex",
+    "flex-direction:column",
+    "align-items:center",
+    "justify-content:center",
+    "gap:14px",
+    "color:rgba(255,255,255,0.75)",
+    "font:14px/1.4 -apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif"
+  ].join(";");
+  const spinner = doc.createElement("div");
+  spinner.style.cssText = [
+    "width:22px",
+    "height:22px",
+    "border-radius:999px",
+    "border:2px solid rgba(255,255,255,0.25)",
+    "border-top-color:rgba(255,255,255,0.9)",
+    "animation:soliton-sdk-spin 0.8s linear infinite"
+  ].join(";");
+  const loadingText = doc.createElement("div");
+  loadingText.textContent = "Loading secure verification...";
+  loading.appendChild(spinner);
+  loading.appendChild(loadingText);
+  container.appendChild(loading);
+  const iframe = doc.createElement("iframe");
+  iframe.setAttribute("allow", "camera; microphone; fullscreen; autoplay");
+  iframe.setAttribute("title", "Soliton identity verification");
+  iframe.style.cssText = [
+    "position:absolute",
+    "inset:0",
+    "width:100%",
+    "height:100%",
+    "border:0",
+    "display:block"
+  ].join(";");
+  iframe.src = iframeSrc;
+  container.appendChild(iframe);
+  const closeButton = doc.createElement("button");
+  closeButton.type = "button";
+  closeButton.setAttribute("aria-label", "Close verification");
+  closeButton.textContent = "\xD7";
+  closeButton.style.cssText = [
+    "position:absolute",
+    "top:14px",
+    "right:14px",
+    "width:36px",
+    "height:36px",
+    "border-radius:999px",
+    "border:1px solid rgba(255,255,255,0.3)",
+    "background:rgba(0,0,0,0.45)",
+    "color:rgba(255,255,255,0.85)",
+    "font:20px/1 -apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif",
+    "cursor:pointer",
+    "padding:0"
+  ].join(";");
+  closeButton.addEventListener("click", onCloseClick);
+  container.appendChild(closeButton);
+  if (openOverlayCount === 0) {
+    savedBodyOverflow = doc.body.style.overflow;
+  }
+  openOverlayCount += 1;
+  doc.body.style.overflow = "hidden";
+  doc.body.appendChild(container);
+  let destroyed = false;
+  return {
+    iframe,
+    markReady() {
+      loading.style.display = "none";
+    },
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      openOverlayCount -= 1;
+      if (openOverlayCount === 0) {
+        doc.body.style.overflow = savedBodyOverflow;
+      }
+      if (container.parentNode) container.parentNode.removeChild(container);
+    }
+  };
+}
+
+// sdk/src/types.ts
+var EMBED_PROTOCOL = "soliton-v1";
+
+// sdk/src/index.ts
+var AUTO_CLOSE_DELAY_MS = 250;
+var HELLO_INTERVAL_MS = 250;
+var HELLO_MAX_PINGS = 40;
+function open(options) {
+  if (!options || typeof options.url !== "string") {
+    throw new Error('SolitonVerify: open() requires an options object with a "url"');
+  }
+  if (typeof options.onComplete !== "function") {
+    throw new Error("SolitonVerify: open() requires an onComplete callback");
+  }
+  const { url, hostedOrigin } = parseHostedUrl(options.url);
+  const src = new URL(url.toString());
+  src.searchParams.set("mode", "embed");
+  src.searchParams.set("sdk", "1");
+  if (options.locale) src.searchParams.set("locale", options.locale);
+  let closed = false;
+  let terminalDelivered = false;
+  let autoCloseTimer = null;
+  const overlay = createOverlay(src.toString(), () => close());
+  let helloPings = 0;
+  const postHello = () => {
+    var _a;
+    helloPings += 1;
+    if (helloPings > HELLO_MAX_PINGS) {
+      stopHello();
+      return;
+    }
+    try {
+      (_a = overlay.iframe.contentWindow) == null ? void 0 : _a.postMessage(
+        { protocol: EMBED_PROTOCOL, type: "soliton:hello" },
+        hostedOrigin
+      );
+    } catch (e) {
+    }
+  };
+  const helloTimer = setInterval(postHello, HELLO_INTERVAL_MS);
+  const onIframeLoad = () => postHello();
+  overlay.iframe.addEventListener("load", onIframeLoad);
+  function stopHello() {
+    clearInterval(helloTimer);
+    overlay.iframe.removeEventListener("load", onIframeLoad);
+  }
+  const onMessage = (event) => {
+    var _a;
+    if (event.origin !== hostedOrigin) return;
+    if (!overlay.iframe.contentWindow || event.source !== overlay.iframe.contentWindow) {
+      return;
+    }
+    const data = event.data;
+    if (!data || typeof data !== "object" || data.protocol !== EMBED_PROTOCOL) {
+      return;
+    }
+    stopHello();
+    switch (data.type) {
+      case "soliton:ready":
+        overlay.markReady();
+        break;
+      case "soliton:complete": {
+        if (terminalDelivered) break;
+        terminalDelivered = true;
+        autoCloseTimer = setTimeout(() => close(), AUTO_CLOSE_DELAY_MS);
+        options.onComplete({
+          verificationId: typeof data.verificationId === "string" ? data.verificationId : ""
+        });
+        break;
+      }
+      case "soliton:error":
+        (_a = options.onError) == null ? void 0 : _a.call(options, {
+          code: typeof data.code === "string" ? data.code : "internal",
+          message: typeof data.message === "string" ? data.message : ""
+        });
+        break;
+      case "soliton:close":
+        close();
+        break;
+      default:
+        break;
+    }
+  };
+  window.addEventListener("message", onMessage);
+  function close() {
+    var _a;
+    if (closed) return;
+    closed = true;
+    if (autoCloseTimer !== null) clearTimeout(autoCloseTimer);
+    stopHello();
+    window.removeEventListener("message", onMessage);
+    overlay.destroy();
+    if (!terminalDelivered) (_a = options.onClose) == null ? void 0 : _a.call(options);
+  }
+  return { close };
+}
+var SolitonVerify = { open };
+var index_default = SolitonVerify;

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Soliton Web SDK v1: embedded verification widget (Stripe/Sumsub wrapper
+ * pattern). open() frames the EXISTING hosted verification page in a
+ * full-viewport overlay on the customer's site and relays its lifecycle via
+ * callbacks; the capture engine itself always runs on soliton.id inside the
+ * iframe, so anti-injection defenses update with every deploy and the
+ * verdict never touches the customer page (only the verification id does).
+ *
+ * Built artifacts (npm run build:sdk):
+ *   public/sdk/v1/soliton-web-sdk.js      IIFE, global `SolitonVerify`
+ *   public/sdk/v1/soliton-web-sdk.esm.js  ESM, `import { open } ...`
+ *   sdk/dist/index.mjs + index.cjs        npm package `@soliton-id/web-sdk`
+ */
+import type { SolitonVerifyHandle, SolitonVerifyOptions } from "./types";
+export type { SolitonVerifyHandle, SolitonVerifyOptions };
+export declare function open(options: SolitonVerifyOptions): SolitonVerifyHandle;
+export declare const SolitonVerify: {
+    open: typeof open;
+};
+export default SolitonVerify;

package/dist/index.mjs

@@ -0,0 +1,237 @@
+/* Soliton Web SDK v1. Built from sdk/src via `npm run build:sdk`; do not edit by hand. */
+
+// sdk/src/hostedUrl.ts
+var HOSTED_PATH_RE = /^\/v\/[0-9a-f]{32}$/;
+var ALLOWED_HTTPS_ORIGINS = /* @__PURE__ */ new Set([
+  "https://soliton.id",
+  "https://staging.soliton.id"
+]);
+function parseHostedUrl(raw) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch (e) {
+    throw new Error(`SolitonVerify: "url" is not a valid absolute URL`);
+  }
+  const isLocalHttp = url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
+  if (!ALLOWED_HTTPS_ORIGINS.has(url.origin) && !isLocalHttp) {
+    throw new Error(
+      'SolitonVerify: "url" must be hosted on https://soliton.id or https://staging.soliton.id (http is allowed for localhost/127.0.0.1 development only)'
+    );
+  }
+  if (url.username || url.password) {
+    throw new Error('SolitonVerify: "url" must not embed credentials');
+  }
+  if (!HOSTED_PATH_RE.test(url.pathname)) {
+    throw new Error(
+      'SolitonVerify: "url" does not look like a hosted verification URL (/v/{token})'
+    );
+  }
+  return { url, hostedOrigin: url.origin };
+}
+
+// sdk/src/overlay.ts
+var MAX_Z_INDEX = "2147483647";
+var openOverlayCount = 0;
+var savedBodyOverflow = "";
+function createOverlay(iframeSrc, onCloseClick) {
+  const doc = document;
+  const container = doc.createElement("div");
+  container.setAttribute("data-soliton-sdk", "overlay");
+  container.style.cssText = [
+    "position:fixed",
+    "inset:0",
+    `z-index:${MAX_Z_INDEX}`,
+    "background:#0f110b",
+    "display:block"
+  ].join(";");
+  const style = doc.createElement("style");
+  style.textContent = "@keyframes soliton-sdk-spin{to{transform:rotate(360deg)}}";
+  container.appendChild(style);
+  const loading = doc.createElement("div");
+  loading.setAttribute("data-soliton-sdk", "loading");
+  loading.style.cssText = [
+    "position:absolute",
+    "inset:0",
+    "display:flex",
+    "flex-direction:column",
+    "align-items:center",
+    "justify-content:center",
+    "gap:14px",
+    "color:rgba(255,255,255,0.75)",
+    "font:14px/1.4 -apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif"
+  ].join(";");
+  const spinner = doc.createElement("div");
+  spinner.style.cssText = [
+    "width:22px",
+    "height:22px",
+    "border-radius:999px",
+    "border:2px solid rgba(255,255,255,0.25)",
+    "border-top-color:rgba(255,255,255,0.9)",
+    "animation:soliton-sdk-spin 0.8s linear infinite"
+  ].join(";");
+  const loadingText = doc.createElement("div");
+  loadingText.textContent = "Loading secure verification...";
+  loading.appendChild(spinner);
+  loading.appendChild(loadingText);
+  container.appendChild(loading);
+  const iframe = doc.createElement("iframe");
+  iframe.setAttribute("allow", "camera; microphone; fullscreen; autoplay");
+  iframe.setAttribute("title", "Soliton identity verification");
+  iframe.style.cssText = [
+    "position:absolute",
+    "inset:0",
+    "width:100%",
+    "height:100%",
+    "border:0",
+    "display:block"
+  ].join(";");
+  iframe.src = iframeSrc;
+  container.appendChild(iframe);
+  const closeButton = doc.createElement("button");
+  closeButton.type = "button";
+  closeButton.setAttribute("aria-label", "Close verification");
+  closeButton.textContent = "\xD7";
+  closeButton.style.cssText = [
+    "position:absolute",
+    "top:14px",
+    "right:14px",
+    "width:36px",
+    "height:36px",
+    "border-radius:999px",
+    "border:1px solid rgba(255,255,255,0.3)",
+    "background:rgba(0,0,0,0.45)",
+    "color:rgba(255,255,255,0.85)",
+    "font:20px/1 -apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif",
+    "cursor:pointer",
+    "padding:0"
+  ].join(";");
+  closeButton.addEventListener("click", onCloseClick);
+  container.appendChild(closeButton);
+  if (openOverlayCount === 0) {
+    savedBodyOverflow = doc.body.style.overflow;
+  }
+  openOverlayCount += 1;
+  doc.body.style.overflow = "hidden";
+  doc.body.appendChild(container);
+  let destroyed = false;
+  return {
+    iframe,
+    markReady() {
+      loading.style.display = "none";
+    },
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      openOverlayCount -= 1;
+      if (openOverlayCount === 0) {
+        doc.body.style.overflow = savedBodyOverflow;
+      }
+      if (container.parentNode) container.parentNode.removeChild(container);
+    }
+  };
+}
+
+// sdk/src/types.ts
+var EMBED_PROTOCOL = "soliton-v1";
+
+// sdk/src/index.ts
+var AUTO_CLOSE_DELAY_MS = 250;
+var HELLO_INTERVAL_MS = 250;
+var HELLO_MAX_PINGS = 40;
+function open(options) {
+  if (!options || typeof options.url !== "string") {
+    throw new Error('SolitonVerify: open() requires an options object with a "url"');
+  }
+  if (typeof options.onComplete !== "function") {
+    throw new Error("SolitonVerify: open() requires an onComplete callback");
+  }
+  const { url, hostedOrigin } = parseHostedUrl(options.url);
+  const src = new URL(url.toString());
+  src.searchParams.set("mode", "embed");
+  src.searchParams.set("sdk", "1");
+  if (options.locale) src.searchParams.set("locale", options.locale);
+  let closed = false;
+  let terminalDelivered = false;
+  let autoCloseTimer = null;
+  const overlay = createOverlay(src.toString(), () => close());
+  let helloPings = 0;
+  const postHello = () => {
+    var _a;
+    helloPings += 1;
+    if (helloPings > HELLO_MAX_PINGS) {
+      stopHello();
+      return;
+    }
+    try {
+      (_a = overlay.iframe.contentWindow) == null ? void 0 : _a.postMessage(
+        { protocol: EMBED_PROTOCOL, type: "soliton:hello" },
+        hostedOrigin
+      );
+    } catch (e) {
+    }
+  };
+  const helloTimer = setInterval(postHello, HELLO_INTERVAL_MS);
+  const onIframeLoad = () => postHello();
+  overlay.iframe.addEventListener("load", onIframeLoad);
+  function stopHello() {
+    clearInterval(helloTimer);
+    overlay.iframe.removeEventListener("load", onIframeLoad);
+  }
+  const onMessage = (event) => {
+    var _a;
+    if (event.origin !== hostedOrigin) return;
+    if (!overlay.iframe.contentWindow || event.source !== overlay.iframe.contentWindow) {
+      return;
+    }
+    const data = event.data;
+    if (!data || typeof data !== "object" || data.protocol !== EMBED_PROTOCOL) {
+      return;
+    }
+    stopHello();
+    switch (data.type) {
+      case "soliton:ready":
+        overlay.markReady();
+        break;
+      case "soliton:complete": {
+        if (terminalDelivered) break;
+        terminalDelivered = true;
+        autoCloseTimer = setTimeout(() => close(), AUTO_CLOSE_DELAY_MS);
+        options.onComplete({
+          verificationId: typeof data.verificationId === "string" ? data.verificationId : ""
+        });
+        break;
+      }
+      case "soliton:error":
+        (_a = options.onError) == null ? void 0 : _a.call(options, {
+          code: typeof data.code === "string" ? data.code : "internal",
+          message: typeof data.message === "string" ? data.message : ""
+        });
+        break;
+      case "soliton:close":
+        close();
+        break;
+      default:
+        break;
+    }
+  };
+  window.addEventListener("message", onMessage);
+  function close() {
+    var _a;
+    if (closed) return;
+    closed = true;
+    if (autoCloseTimer !== null) clearTimeout(autoCloseTimer);
+    stopHello();
+    window.removeEventListener("message", onMessage);
+    overlay.destroy();
+    if (!terminalDelivered) (_a = options.onClose) == null ? void 0 : _a.call(options);
+  }
+  return { close };
+}
+var SolitonVerify = { open };
+var index_default = SolitonVerify;
+export {
+  SolitonVerify,
+  index_default as default,
+  open
+};

package/dist/overlay.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Full-viewport overlay hosting the verification iframe.
+ *
+ * The overlay is deliberately full-screen and opaque: the capture flow runs
+ * a screen-light challenge, and a small inline widget would both break that
+ * physics and shrink the camera view. Everything is plain DOM with inline
+ * styles so the SDK needs no stylesheet and cannot clash with host CSS
+ * (spinner keyframes ride in a scoped <style> tag inside the overlay).
+ */
+export interface Overlay {
+    iframe: HTMLIFrameElement;
+    /** Hide the loading state once the hosted page reports soliton:ready. */
+    markReady(): void;
+    /** Remove the overlay from the DOM and restore body scroll. Idempotent. */
+    destroy(): void;
+}
+export declare function createOverlay(iframeSrc: string, onCloseClick: () => void): Overlay;

package/dist/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Public types for the Soliton Web SDK, plus the child -> parent postMessage
+ * protocol shared with the hosted page (app/utils/embedMessaging.ts is the
+ * child-side counterpart; keep the two in sync).
+ *
+ * COMPATIBILITY CONTRACT (frozen since the SDK ships on npm): wrapper
+ * versions live inside customer bundles for months, so the soliton-v1
+ * message shapes below can never change or be removed. The hosted page MAY
+ * add new message types in the future; old wrappers silently ignore unknown
+ * types (the switch in index.ts must keep its no-op default), so additions
+ * are safe. Never rename a type, never remove or retype a field, and never
+ * add payload fields the wrapper is required to understand.
+ */
+export interface SolitonVerifyOptions {
+    /** Hosted verification URL from POST /api/v1/verifications. */
+    url: string;
+    /**
+     * Terminal state reached (pass OR final fail; deliberately not
+     * distinguished here). Carries only the verification id: confirm the
+     * verdict server-side via GET /api/v1/verifications/{id}.
+     */
+    onComplete: (e: {
+        verificationId: string;
+    }) => void;
+    /** Flow-level errors: link_expired, link_invalid, origin_not_allowed, storage_unavailable, internal. */
+    onError?: (e: {
+        code: string;
+        message: string;
+    }) => void;
+    /** User dismissed the flow before completion. */
+    onClose?: () => void;
+    /** Reserved; passed through to the hosted page as a query param. */
+    locale?: string;
+}
+export interface SolitonVerifyHandle {
+    close(): void;
+}
+/** Every hosted-page message is tagged with this protocol marker. */
+export declare const EMBED_PROTOCOL = "soliton-v1";
+export type EmbedMessage = {
+    protocol: typeof EMBED_PROTOCOL;
+    type: "soliton:ready";
+} | {
+    protocol: typeof EMBED_PROTOCOL;
+    type: "soliton:complete";
+    verificationId: string;
+} | {
+    protocol: typeof EMBED_PROTOCOL;
+    type: "soliton:error";
+    code: string;
+    message: string;
+} | {
+    protocol: typeof EMBED_PROTOCOL;
+    type: "soliton:close";
+};
+/**
+ * Parent -> child (the only message in that direction): the wrapper pings
+ * this at the hosted iframe so the hosted page can read the embedding origin
+ * from MessageEvent.origin, which the browser sets and nothing can spoof.
+ * Firefox has no location.ancestorOrigins, and Referrer-Policy: no-referrer
+ * on the customer page blanks the referrer fallback; without this ping such
+ * embeds would always fail the frame-origin gate. Added before the first npm
+ * publish, so it is part of the frozen soliton-v1 surface. Deliberately
+ * carries nothing beyond the protocol marker.
+ */
+export type ParentHelloMessage = {
+    protocol: typeof EMBED_PROTOCOL;
+    type: "soliton:hello";
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "//": "Publishable manifest for the npm Web SDK. No devDependencies and no own node_modules by design: every build runs from the next-app root with its existing toolchain (npm run build:sdk), so the lockfile never grows for packaging. dist/ is rebuilt automatically by the prepack hook and is not committed.",
+  "name": "@soliton-id/web-sdk",
+  "version": "1.0.0",
+  "description": "Soliton identity verification for the browser: opens the hosted verification flow in a full-viewport overlay iframe on your page and reports lifecycle events. Verdicts and portraits are fetched by your backend, never exposed in the browser.",
+  "license": "MIT",
+  "author": "Soliton",
+  "homepage": "https://soliton.id/docs/integration/sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/georgesabr/next-app.git",
+    "directory": "sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/georgesabr/next-app/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "prepack": "node build.mjs"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": [
+    "identity",
+    "verification",
+    "liveness",
+    "kyc",
+    "soliton"
+  ]
+}