@soliton-id/web-sdk 1.0.1 → 1.1.1

package/CHANGELOG.md

@@ -4,6 +4,48 @@ 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.1.1 — 2026-10-29
+
+Package metadata only; no code or API changes. The repository and issue links
+point to `georges-soliton/soliton-front-end`.
+
+## 1.1.0 — 2026-10-29
+
+Additive only. `open()` and the `soliton-v1` protocol are unchanged, so
+existing integrations need no code change.
+
+- Add the isolated `/server` export and downloadable `soliton-server.mjs` for
+  Node.js 18+: combined v2 session creation and link issuance, with a pre-link
+  persistence callback, bounded requests, explicit link recovery and
+  structured partial-failure errors.
+- Add the optional `verificationOrigin` option for customer-hosted deployments.
+- Bound initial iframe readiness to 30 seconds; report `load_timeout` and clean
+  up stalled overlays without emitting a verification result. A frame that
+  stays blank until then usually means the embedding page's origin is not
+  registered for the link's environment.
+- Document the v2 session flow: completion callbacks keep the UUID
+  `verificationId`, and results are read server-side from the saved session.
+- Document server-side `liveness_tier` selection for Standard, Medium and High
+  in sandbox and production; the returned URL selects the capture.
+- Document that registered embedding origins apply on the next page load, with
+  no Soliton deployment.
+
+## 1.0.2 — 2026-08-06
+
+Documentation only. No runtime, API, or bundle changes; `soliton-v1` is
+unchanged and `1.0.0`/`1.0.1` remain fully compatible.
+
+- Reframed `sk_test_` as the **sandbox environment** rather than a
+  fixtures-only mode. A sandbox credential now runs real captures; the
+  deterministic `pass` / `fail` / `partial` fixtures remain available and
+  remain sandbox-only. `sk_live_` still cannot request a fixture.
+- Documented that redirect domains, iframe origins, and webhook endpoints are
+  registered per environment, so a staging origin can embed sandbox links
+  without being able to embed production ones, and each environment's webhook
+  has its own signing secret.
+- Documented the additive `environment` field on the create response, every
+  status read, and every webhook payload.
+
 ## 1.0.1 — 2026-08-02
 
 Documentation only. No runtime, API, or bundle changes; `soliton-v1` is

package/README.md

@@ -1,3 +1,87 @@
+## Customer-hosted appliances
+
+Set `verificationOrigin` to your trusted customer-hosted HTTPS origin when calling
+`open({ url, verificationOrigin, onComplete })`. The issued URL must match that
+origin exactly. Omit the option for the existing cloud allowlist. The iframe
+protocol, completion callbacks and server-side result/webhook contracts are
+unchanged. See [the appliance guide](../docs/on-premise.md) for runtime origins,
+local assets, packaging, iframe permissions and top-level mobile WebViews.
+
+## Console API v2
+
+The SDK opens `https://soliton.id/v/{token}` links from
+`POST /api/v2/sessions/{id}/link`. Create the session first with your console
+API key using `POST /api/v2/sessions`; resolve `browser_path` against the
+verification origin and pass only the resulting URL to `open()`.
+Both redirect and embedded methods use the same API key and v2 endpoints.
+Register exact embedding origins per account/environment; they apply on the next
+page load with no frontend deploy. There is no wildcard or implicit
+same-company-domain grant.
+
+`onComplete({ verificationId })` is unchanged: it carries the browser UUID alias,
+not a verdict. Your backend must fetch `GET /api/v2/sessions/{savedSessionId}`
+using the `ses_…` ID bound to the authenticated user at creation. Never trust the
+callback ID as the authority for a lookup. The `/sdk/v1/` path and `soliton-v1`
+message marker are the SDK protocol, independent of REST API version.
+
+## Optional v2 server helper (Node.js 18+)
+
+The helper keeps v2 intact while combining session creation and link issuance
+into one server-side function. Download `/sdk/v1/soliton-server.mjs` from your
+Soliton deployment into your backend project, review it, and commit the file.
+Do not use a browser script tag or dynamically download it on every request.
+The source package also exports `@soliton-id/web-sdk/server` (ESM/CJS + types);
+use the downloaded module until a package containing that export is published.
+
+```js
+import { createVerificationClient, VerificationStartError } from './soliton-server.mjs';
+const soliton = createVerificationClient({
+  apiOrigin: process.env.API_ORIGIN,
+  verificationOrigin: process.env.VERIFICATION_ORIGIN,
+  apiKey: process.env.API_KEY,
+  timeoutMs: 20000, // Per request, including its response body.
+});
+// user/attempt come from your authenticated server endpoint.
+// saveSession/saveLink are your application database operations.
+const { sessionId, url } = await soliton.startVerification({
+  userReference: user.id,
+  tier: 'high',
+  idempotencyKey: attempt.id,
+  onSessionCreated: async id => { await saveSession(user.id, attempt.id, id); },
+});
+await saveLink(attempt.id, url);
+// Return only { url } to the browser. Keep sessionId on your server.
+```
+
+This still makes two HTTP requests, with no automatic retries. Only session
+creation is idempotent; the combined helper is **not** end-to-end idempotent.
+Persist a stable key for each logical attempt, serialize duplicate requests,
+and return a securely stored URL for an attempt that already succeeded.
+Neither successful URLs nor service credentials belong in logs.
+
+`VerificationStartError` includes `stage` (`create`, `persist`, `link`),
+`sessionId` when known, `status` when a response was available, and `retryAfter`
+(the raw HTTP Retry-After value, if supplied). It omits arbitrary response bodies
+and transport errors so secrets cannot leak through its message.
+
+- `create`: resolve the failure and retry with the same idempotency key and body;
+  a lost response may conceal a successful creation. Respect 429/Retry-After;
+  fix authentication or conflicting inputs rather than retrying unchanged.
+- `persist`: your `onSessionCreated` callback failed. No link was requested.
+  Save the known session ID before proceeding.
+- `link`: the session exists; retain the ID. A timeout or malformed response may
+  conceal successful issuance. Make an explicit recovery decision, then call
+  `soliton.issueVerificationLink(savedSessionId)` to get `{ sessionId, url }`.
+  This replaces the previous link; do not rotate a link already in use.
+
+Origins must be HTTPS (HTTP only for loopback development), without credentials,
+paths, queries or fragments. Never derive them from browser input. The helper
+refuses API redirects, validates returned hosted paths and rejects browser use.
+It does not store state, authenticate your user, or make access decisions.
+
+See `/docs/integration/sdk` for the full v2 SDK guide and `/docs/integration/api`
+for raw requests. Existing v1 instructions below remain compatible.
+
 # @soliton-id/web-sdk
 
 Soliton identity verification for the browser. `open()` overlays the Soliton
@@ -35,9 +119,19 @@ 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:
+Your backend chooses the liveness tier and creates a verification with your
+secret API key (never do this from the browser):
+
+```bash
+# Use sk_live_... for production; sk_test_... for sandbox.
+curl -X POST https://api.soliton.id/api/v1/verifications \
+  -H "Authorization: Bearer sk_test_..." \
+  -H "Content-Type: application/json" \
+  -d '{"liveness_tier":"standard","client_reference_id":"user-8412"}'
+```
+
+Store the returned `verification_id`, requested tier and `environment` against
+your authenticated user on your backend. Hand the returned `url` to your page:
 
 ```ts
 import { open } from "@soliton-id/web-sdk";
@@ -56,30 +150,82 @@ const handle = open({
   },
   onError: ({ code, message }) => {
     // link_expired | link_invalid | origin_not_allowed |
-    // storage_unavailable | internal
+    // storage_unavailable | internal | load_timeout
   },
   onClose: () => {
-    // The user dismissed the flow before completion.
+    // The flow closed before completion (dismissal or initial load timeout).
   },
 });
 
 // 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.
+The overlay is always full-viewport for every tier. High uses the whole screen
+for its light challenge; Standard and Medium keep that layout without flashes.
+Do not clip the overlay into a widget.
+
+## Choose liveness (sandbox and production)
+
+| Server-side `liveness_tier` | Capture | Browser permissions |
+| --- | --- | --- |
+| `standard` | Camera only, no sound or flashes | Camera |
+| `medium` | Camera and sound, no flashes | Camera and microphone |
+| `high` (default) | Camera, sound and light | Camera and microphone |
+
+All three use the same `POST /api/v1/verifications` endpoint and work with both
+`sk_test_` and `sk_live_` keys. Omitting the field preserves High for existing
+integrations. Choose the tier using your server's policy; do not let untrusted
+browser input override that policy.
+
+The URL binds the chosen tier for capture and every retake. Pass it unchanged
+to `open()` or use it as a redirect: **there is no tier option in `open()` and
+no tier query parameter to add**. Existing SDK versions already support every
+tier; no package upgrade or separate bundle is needed. To change tiers, create
+a new verification.
+
+On completion, require the authenticated status response's `liveness_tier`
+and `environment` to match the values stored for your user before accepting
+the verdict. The callback still carries only `verificationId`.
 
 ## Callback semantics
 
+An integration that provides its own completion screen can opt out of the
+hosted result summary by adding `completion=parent` to the hosted URL:
+
+```ts
+const embeddedUrl = new URL(url);
+embeddedUrl.searchParams.set("completion", "parent");
+const handle = open({
+  url: embeddedUrl.toString(),
+  onComplete: () => {
+    handle.close();
+    // Show your own final screen and have your backend fetch the saved result.
+  },
+});
+```
+
+The preference is honored only inside an iframe after its parent origin passes
+the usual registration check. It hands control back immediately at a terminal
+state, without the default three-second result summary. Retryable failures and
+errors remain in the hosted flow. Top-level redirects and embeds without this
+opt-in retain their existing behavior. Existing SDK bundles preserve this URL
+parameter; the hosted frontend must support it. The callback still means the
+attempt ended, not that verification passed; fetch the verdict server-to-server.
+
 - `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`.
+  `handle.close()` if you want it gone. If the frame has not become ready or
+  reported an error within 30 seconds, `load_timeout` is emitted instead and
+  the overlay closes automatically, followed by `onClose`. This is a loading
+  failure, never a biometric verdict. A frame that stayed blank before it
+  almost always means your page's exact origin is not registered for the
+  link's environment: the browser console shows a `frame-ancestors` error. Once ready, there is no SDK capture deadline.
+- `onClose()`: the flow closed before completion (the X button, hosted Cancel,
+  `handle.close()`, or initial load timeout). Not fired after `onComplete`.
 
 ## Getting the result (server-to-server only)
 
@@ -87,12 +233,12 @@ that needs the whole screen, so it cannot be clipped into a widget.
 BACKEND with your API key:
 
 1. `GET /api/v1/verifications/{id}`: the verdict (`verified`,
-   `partial_verification`, plus `portrait_available`).
+   `partial_verification`, `liveness_tier`, 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`
+   briefly read `false` while extraction finishes; once status is `completed`
    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
@@ -118,26 +264,32 @@ 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:
+Embedding is off by default. One origin list per environment controls two checks:
 
 1. Your Soliton account must have the exact origin of each page that runs the
    SDK and directly contains its Soliton iframe registered (scheme + host +
-   port, e.g. `https://app.example.com`). This direct-parent page does not
-   have to be the browser's top-level page.
-2. The direct-parent origin must also be present in the soliton.id deploy-time
-   `frame-ancestors` allowlist. If the SDK page is itself framed, every origin
-   above it in the frame chain must be present there too (we manage this
-   allowlist).
-
-A verification link opened inside an iframe with any other direct-parent
-origin refuses to start and reports `origin_not_allowed`.
-
-During the invite-only pilot, Soliton manually manages both layers. Send your
+   port, e.g. `https://app.example.com`), **for the environment that will open
+   the link**. This direct-parent page does not have to be the browser's
+   top-level page. A link is checked against the origins registered for the
+   environment of the key that created it, so `https://dev.example.com` can be
+   a sandbox embedder without becoming a production one.
+2. The same list feeds the hosted page's `frame-ancestors` policy, read on
+   every page load, so a registered origin applies with no deployment. If the
+   SDK page is itself framed, every origin above it in the frame chain must be
+   registered for the same environment too, because the browser checks
+   `frame-ancestors` against the whole chain.
+
+Opened inside an iframe on any other origin, the browser blocks the frame: it
+stays blank and the SDK reports `load_timeout` after 30 seconds.
+`origin_not_allowed` means the hosted page loaded but this particular link may
+not be embedded there, for example a console test link.
+
+During the invite-only pilot, Soliton registers your origins. Send your
 Soliton contact every exact production and local direct-parent origin before
 testing. Include a staging origin only when Soliton has supplied a working
 staging flow URL. For a nested integration, also send every other ancestor
-origin. Wildcards are not accepted, and adding or changing an origin can
-require a Soliton deployment.
+origin. Wildcards are not accepted. A registered origin applies on the next
+page load; no Soliton deployment is involved.
 
 Register the direct-parent page's origin, not a URL path. For example,
 `https://app.example.com` and `https://app.example.com:8443` are different
@@ -174,8 +326,9 @@ Permissions-Policy: camera=(self "https://soliton.id"), microphone=(self "https:
   bundles the npm package.
 - If any document above the Soliton iframe explicitly restricts camera or
   microphone with `Permissions-Policy`, every level in a nested frame chain
-  must allow and delegate both features through each intervening iframe; an
-  upstream denial cannot be overridden lower in the chain. The SDK already
+  must allow and delegate the features used by the selected tier: camera for
+  Standard; camera and microphone for Medium and High. The examples allow all
+  tiers. An upstream denial cannot be overridden lower in the chain. The SDK already
   sets the matching `allow="camera; microphone"` attribute on the iframe it
   creates.
 
@@ -190,38 +343,57 @@ soliton.id. Do not add Soliton to your page's `frame-ancestors`: that directive
 controls who may frame your page, while `frame-src` controls what your page may
 frame.
 
-## Test mode
+## Sandbox
+
+Your account has two environments and the API key prefix selects one:
+`sk_live_` is **production**, `sk_test_` is **sandbox**. Each has its own
+credentials, verifications, redirect domains, iframe origins, and webhook
+endpoint with its own signing secret.
 
-`sk_test_` credentials produce deterministic synthetic fixtures, so you can
-build and regression-test the embed without capturing a person. Your server
-names the outcome when it creates the verification:
+A sandbox verification opens in the overlay exactly like a production one and
+runs the same real capture — but it is checked against the iframe origins
+registered for **sandbox**, so your staging page can embed sandbox links
+without being able to embed production ones. Register each origin for the
+environment that will use it.
+
+Sandbox is additionally the only place that can request a fixed outcome, which
+is the practical way to exercise your `partial` branch:
 
 ```jsonc
 // POST /api/v1/verifications with an sk_test_ key
-{ "client_reference_id": "user-8412", "test_fixture_scenario": "partial" }
+{ "liveness_tier": "medium", "client_reference_id": "user-8412", "test_fixture_scenario": "partial" }
 ```
 
-| `test_fixture_scenario` | `verified` | `partial_verification` |
-| ----------------------- | ---------- | ---------------------- |
-| `pass`                  | `true`     | `false`                |
-| `partial`               | `true`     | `true`                 |
-| `fail`                  | `false`    | `false`                |
-
-The resulting URL opens in the overlay exactly like a real one and fires
-`onComplete` the same way, but never requests camera permission and never
-records anything. The hosted page marks itself as synthetic on screen. This is
-the practical way to exercise your `partial` branch, which is awkward to
-trigger with a real capture.
-
-Test mode does not exercise liveness, anti-spoof, or anti-deepfake logic, and
-simulates no errors or timeouts — only the three terminal verdicts. Verify the
-production path with an `sk_live_` key.
-
-The two modes are strictly isolated: a live key cannot create or read a
-fixture, and a test key cannot read a real verification, even within one
-account. Every status read and webhook carries `result_source`
-(`biometric` or `synthetic_test_fixture`) — assert it is `biometric` anywhere
-a real verdict matters.
+| `test_fixture_scenario` | `verified` | Standard `partial_verification` | Medium / High `partial_verification` |
+| --- | --- | --- | --- |
+| `pass` | `true` | `false` | `false` |
+| `partial` | `true` | `false` | `true` |
+| `fail` | `false` | `false` | `false` |
+
+A fixture's URL opens in the overlay and fires `onComplete` the same way, but
+never requests camera permission and never records anything. The hosted page
+marks itself as synthetic on screen.
+
+Fixtures do not exercise liveness, anti-spoof, or anti-deepfake logic, and
+simulate no errors or timeouts — only the three terminal verdicts. Real
+sandbox captures do run the full pipeline; a production `sk_live_` key cannot
+request fixtures at all.
+
+The two environments are strictly isolated: neither credential can read the
+other's verifications, even within one account. Every create response, status
+read, and webhook carries `environment` (`sandbox` or `production`) and
+`result_source` (`biometric` or `synthetic_test_fixture`) — assert both
+anywhere a real production verdict matters.
+
+Keep the same explicit `liveness_tier` when moving from sandbox to production;
+switch keys and use origins registered for production. The completed status
+response and signed webhook include `liveness_tier`: require it to match your
+stored choice, and reject missing or mismatched tiers. Fetch the verdict using
+the verification id bound to your user's session, as in the quickstart above.
+
+Standard has only verified and not-verified outcomes: completed results always
+set `partial_verification: false`. Medium and High can still return partial
+verification. A Standard `partial` test fixture resolves to a verified result.
 
 ## Completion webhooks
 
@@ -233,6 +405,12 @@ deduplicate on `X-Soliton-Event-Id`, and respond `2xx` within 5 seconds. Full
 setup, the signature recipe, and retry semantics are in the
 [integration guide](https://soliton.id/docs/integration).
 
+Webhooks are configured per environment: one endpoint for sandbox and one for
+production, each with its own signing secret. A sandbox completion is only ever
+delivered to the sandbox endpoint, so a staging receiver cannot validate — or
+forge — a production event. The payload's `environment` field tells you which
+is which if you point both at one URL.
+
 ## How it works
 
 `open()` accepts hosted URLs from `https://soliton.id`. When Soliton has

package/dist/hostedUrl.d.ts

@@ -2,7 +2,7 @@
  * 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
+ * the v1 verification API or v2 session link API: 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
@@ -14,4 +14,4 @@ export interface ParsedHostedUrl {
     /** Origin the SDK will trust for postMessage events. */
     hostedOrigin: string;
 }
-export declare function parseHostedUrl(raw: string): ParsedHostedUrl;
+export declare function parseHostedUrl(raw: string, verificationOrigin?: string): ParsedHostedUrl;

package/dist/index.cjs

@@ -27,13 +27,24 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// sdk/src/trustedOrigin.ts
+function trustedOrigin(value) {
+  const url = new URL(value);
+  const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (url.origin !== value || url.username || url.password || value.includes("*") || url.protocol !== "https:" && !(url.protocol === "http:" && local)) {
+    throw new Error("Use an exact HTTPS origin (HTTP loopback is allowed for development)");
+  }
+  return url.origin;
+}
+
 // 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) {
+function parseHostedUrl(raw, verificationOrigin) {
+  const configuredOrigin = verificationOrigin === void 0 ? void 0 : trustedOrigin(verificationOrigin);
   let url;
   try {
     url = new URL(raw);
@@ -41,7 +52,10 @@ function parseHostedUrl(raw) {
     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) {
+  if (configuredOrigin !== void 0 && url.origin !== configuredOrigin) {
+    throw new Error('SolitonVerify: "url" does not match the configured verificationOrigin');
+  }
+  if (configuredOrigin === void 0 && !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)'
     );
@@ -166,6 +180,7 @@ var EMBED_PROTOCOL = "soliton-v1";
 var AUTO_CLOSE_DELAY_MS = 250;
 var HELLO_INTERVAL_MS = 250;
 var HELLO_MAX_PINGS = 40;
+var READY_TIMEOUT_MS = 3e4;
 function open(options) {
   if (!options || typeof options.url !== "string") {
     throw new Error('SolitonVerify: open() requires an options object with a "url"');
@@ -173,14 +188,16 @@ function open(options) {
   if (typeof options.onComplete !== "function") {
     throw new Error("SolitonVerify: open() requires an onComplete callback");
   }
-  const { url, hostedOrigin } = parseHostedUrl(options.url);
+  const { url, hostedOrigin } = parseHostedUrl(options.url, options.verificationOrigin);
   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 loadTimedOut = false;
   let autoCloseTimer = null;
+  let readyTimer = null;
   const overlay = createOverlay(src.toString(), () => close());
   let helloPings = 0;
   const postHello = () => {
@@ -205,8 +222,13 @@ function open(options) {
     clearInterval(helloTimer);
     overlay.iframe.removeEventListener("load", onIframeLoad);
   }
+  function stopReadyWait() {
+    if (readyTimer !== null) clearTimeout(readyTimer);
+    readyTimer = null;
+  }
   const onMessage = (event) => {
     var _a;
+    if (closed || loadTimedOut || terminalDelivered) return;
     if (event.origin !== hostedOrigin) return;
     if (!overlay.iframe.contentWindow || event.source !== overlay.iframe.contentWindow) {
       return;
@@ -218,10 +240,12 @@ function open(options) {
     stopHello();
     switch (data.type) {
       case "soliton:ready":
+        stopReadyWait();
         overlay.markReady();
         break;
       case "soliton:complete": {
         if (terminalDelivered) break;
+        stopReadyWait();
         terminalDelivered = true;
         autoCloseTimer = setTimeout(() => close(), AUTO_CLOSE_DELAY_MS);
         options.onComplete({
@@ -230,6 +254,7 @@ function open(options) {
         break;
       }
       case "soliton:error":
+        stopReadyWait();
         (_a = options.onError) == null ? void 0 : _a.call(options, {
           code: typeof data.code === "string" ? data.code : "internal",
           message: typeof data.message === "string" ? data.message : ""
@@ -243,11 +268,25 @@ function open(options) {
     }
   };
   window.addEventListener("message", onMessage);
+  readyTimer = setTimeout(() => {
+    var _a;
+    if (readyTimer === null || closed || terminalDelivered) return;
+    loadTimedOut = true;
+    try {
+      (_a = options.onError) == null ? void 0 : _a.call(options, {
+        code: "load_timeout",
+        message: "Verification did not load. Please try again."
+      });
+    } finally {
+      close();
+    }
+  }, READY_TIMEOUT_MS);
   function close() {
     var _a;
     if (closed) return;
     closed = true;
     if (autoCloseTimer !== null) clearTimeout(autoCloseTimer);
+    stopReadyWait();
     stopHello();
     window.removeEventListener("message", onMessage);
     overlay.destroy();

package/dist/index.d.ts

@@ -2,8 +2,8 @@
  * 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
+ * callbacks; the capture engine runs on the trusted verification origin inside
+ * the iframe, so anti-injection defenses update with each frontend release and the
  * verdict never touches the customer page (only the verification id does).
  *
  * Built artifacts (npm run build:sdk):

package/dist/index.mjs

@@ -1,12 +1,23 @@
 /* Soliton Web SDK v1. Built from sdk/src via `npm run build:sdk`; do not edit by hand. */
 
+// sdk/src/trustedOrigin.ts
+function trustedOrigin(value) {
+  const url = new URL(value);
+  const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (url.origin !== value || url.username || url.password || value.includes("*") || url.protocol !== "https:" && !(url.protocol === "http:" && local)) {
+    throw new Error("Use an exact HTTPS origin (HTTP loopback is allowed for development)");
+  }
+  return url.origin;
+}
+
 // 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) {
+function parseHostedUrl(raw, verificationOrigin) {
+  const configuredOrigin = verificationOrigin === void 0 ? void 0 : trustedOrigin(verificationOrigin);
   let url;
   try {
     url = new URL(raw);
@@ -14,7 +25,10 @@ function parseHostedUrl(raw) {
     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) {
+  if (configuredOrigin !== void 0 && url.origin !== configuredOrigin) {
+    throw new Error('SolitonVerify: "url" does not match the configured verificationOrigin');
+  }
+  if (configuredOrigin === void 0 && !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)'
     );
@@ -139,6 +153,7 @@ var EMBED_PROTOCOL = "soliton-v1";
 var AUTO_CLOSE_DELAY_MS = 250;
 var HELLO_INTERVAL_MS = 250;
 var HELLO_MAX_PINGS = 40;
+var READY_TIMEOUT_MS = 3e4;
 function open(options) {
   if (!options || typeof options.url !== "string") {
     throw new Error('SolitonVerify: open() requires an options object with a "url"');
@@ -146,14 +161,16 @@ function open(options) {
   if (typeof options.onComplete !== "function") {
     throw new Error("SolitonVerify: open() requires an onComplete callback");
   }
-  const { url, hostedOrigin } = parseHostedUrl(options.url);
+  const { url, hostedOrigin } = parseHostedUrl(options.url, options.verificationOrigin);
   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 loadTimedOut = false;
   let autoCloseTimer = null;
+  let readyTimer = null;
   const overlay = createOverlay(src.toString(), () => close());
   let helloPings = 0;
   const postHello = () => {
@@ -178,8 +195,13 @@ function open(options) {
     clearInterval(helloTimer);
     overlay.iframe.removeEventListener("load", onIframeLoad);
   }
+  function stopReadyWait() {
+    if (readyTimer !== null) clearTimeout(readyTimer);
+    readyTimer = null;
+  }
   const onMessage = (event) => {
     var _a;
+    if (closed || loadTimedOut || terminalDelivered) return;
     if (event.origin !== hostedOrigin) return;
     if (!overlay.iframe.contentWindow || event.source !== overlay.iframe.contentWindow) {
       return;
@@ -191,10 +213,12 @@ function open(options) {
     stopHello();
     switch (data.type) {
       case "soliton:ready":
+        stopReadyWait();
         overlay.markReady();
         break;
       case "soliton:complete": {
         if (terminalDelivered) break;
+        stopReadyWait();
         terminalDelivered = true;
         autoCloseTimer = setTimeout(() => close(), AUTO_CLOSE_DELAY_MS);
         options.onComplete({
@@ -203,6 +227,7 @@ function open(options) {
         break;
       }
       case "soliton:error":
+        stopReadyWait();
         (_a = options.onError) == null ? void 0 : _a.call(options, {
           code: typeof data.code === "string" ? data.code : "internal",
           message: typeof data.message === "string" ? data.message : ""
@@ -216,11 +241,25 @@ function open(options) {
     }
   };
   window.addEventListener("message", onMessage);
+  readyTimer = setTimeout(() => {
+    var _a;
+    if (readyTimer === null || closed || terminalDelivered) return;
+    loadTimedOut = true;
+    try {
+      (_a = options.onError) == null ? void 0 : _a.call(options, {
+        code: "load_timeout",
+        message: "Verification did not load. Please try again."
+      });
+    } finally {
+      close();
+    }
+  }, READY_TIMEOUT_MS);
   function close() {
     var _a;
     if (closed) return;
     closed = true;
     if (autoCloseTimer !== null) clearTimeout(autoCloseTimer);
+    stopReadyWait();
     stopHello();
     window.removeEventListener("message", onMessage);
     overlay.destroy();

package/dist/server.cjs

@@ -0,0 +1,119 @@
+/* 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/server.ts
+var server_exports = {};
+__export(server_exports, {
+  VerificationStartError: () => VerificationStartError,
+  createVerificationClient: () => createVerificationClient
+});
+module.exports = __toCommonJS(server_exports);
+var VerificationStartError = class extends Error {
+  constructor(stage, sessionId, status, retryAfter) {
+    super(`Verification ${stage} failed${status ? ` (HTTP ${status})` : ""}. No automatic retry was attempted.`);
+    this.stage = stage;
+    this.sessionId = sessionId;
+    this.status = status;
+    this.retryAfter = retryAfter;
+    this.name = "VerificationStartError";
+  }
+};
+function origin(value) {
+  const url = new URL(value);
+  const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (url.protocol !== "https:" && !(local && url.protocol === "http:") || url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+    throw new TypeError("Use an HTTPS origin without credentials, path, query or fragment; HTTP is allowed only on localhost.");
+  }
+  return url.origin;
+}
+function validSessionId(value) {
+  return typeof value === "string" && /^ses_[a-zA-Z0-9]+$/.test(value);
+}
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function createVerificationClient(options) {
+  if (typeof window !== "undefined") throw new Error("The verification client is server-only. Keep API keys on your server.");
+  const apiOrigin = origin(options.apiOrigin);
+  const verificationOrigin = origin(options.verificationOrigin);
+  if (!options.apiKey || /[\s\x00-\x1f\x7f]/.test(options.apiKey)) throw new TypeError("A server API key is required.");
+  const apiKey = options.apiKey;
+  const timeoutMs = options.timeoutMs ?? 2e4;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 12e4) throw new TypeError("timeoutMs must be between 1 and 120000.");
+  async function post(path, stage, sessionId, body, idempotencyKey) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let status;
+    try {
+      const response = await fetch(apiOrigin + path, {
+        method: "POST",
+        redirect: "error",
+        // Never forward a secret to an API redirect target.
+        signal: controller.signal,
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          ...body ? { "Content-Type": "application/json" } : {},
+          ...idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}
+        },
+        ...body ? { body: JSON.stringify(body) } : {}
+      });
+      status = response.status;
+      if (!response.ok) throw new VerificationStartError(stage, sessionId, status, response.headers.get("Retry-After") ?? void 0);
+      return record(await response.json());
+    } catch (error) {
+      if (error instanceof VerificationStartError) throw error;
+      throw new VerificationStartError(stage, sessionId, status);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async function issueVerificationLink(sessionId) {
+    if (!validSessionId(sessionId)) throw new TypeError("A saved ses_ session ID is required.");
+    const issued = await post(`/api/v2/sessions/${sessionId}/link`, "link", sessionId);
+    if (typeof issued.browser_path !== "string" || !/^\/v\/[a-f0-9]{32}$/.test(issued.browser_path)) {
+      throw new VerificationStartError("link", sessionId);
+    }
+    return { sessionId, url: new URL(issued.browser_path, verificationOrigin).href };
+  }
+  async function startVerification(input) {
+    if (!["standard", "medium", "high"].includes(input.tier)) throw new TypeError("Choose standard, medium or high.");
+    if (typeof input.userReference !== "string" || !input.userReference.trim()) throw new TypeError("An authenticated user reference is required.");
+    if (typeof input.idempotencyKey !== "string" || !/^[\x21-\x7e]{1,196}$/.test(input.idempotencyKey)) {
+      throw new TypeError("Use a stable 1\u2013196 character idempotency key for this attempt.");
+    }
+    const session = await post("/api/v2/sessions", "create", void 0, {
+      client_reference_id: input.userReference,
+      checks: [{ type: "presence", configuration: { liveness_tier: input.tier } }]
+    }, input.idempotencyKey);
+    if (!validSessionId(session.id)) throw new VerificationStartError("create");
+    try {
+      await input.onSessionCreated?.(session.id);
+    } catch {
+      throw new VerificationStartError("persist", session.id);
+    }
+    return issueVerificationLink(session.id);
+  }
+  return { startVerification, issueVerificationLink };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  VerificationStartError,
+  createVerificationClient
+});

package/dist/server.d.ts

@@ -0,0 +1,34 @@
+/** Server-only v2 convenience API. Never import this module into a browser bundle. */
+export type VerificationTier = "standard" | "medium" | "high";
+export type VerificationStage = "create" | "persist" | "link";
+export declare class VerificationStartError extends Error {
+    readonly stage: VerificationStage;
+    readonly sessionId?: string | undefined;
+    readonly status?: number | undefined;
+    readonly retryAfter?: string | undefined;
+    constructor(stage: VerificationStage, sessionId?: string | undefined, status?: number | undefined, retryAfter?: string | undefined);
+}
+export interface VerificationClientOptions {
+    apiOrigin: string;
+    verificationOrigin: string;
+    apiKey: string;
+    /** Per-request timeout, including response body consumption. Default 20 seconds. */
+    timeoutMs?: number;
+}
+export interface StartVerificationOptions {
+    userReference: string;
+    tier: VerificationTier;
+    /** Persist this per logical attempt; reuse only with the identical request. */
+    idempotencyKey: string;
+    /** Awaited before link issuance. Persist the ID against the authenticated user here. */
+    onSessionCreated?: (sessionId: string) => void | Promise<void>;
+}
+export interface StartedVerification {
+    sessionId: string;
+    url: string;
+}
+/** Node 18+ (native fetch). No retries or in-memory caching; persistence belongs to your backend. */
+export declare function createVerificationClient(options: VerificationClientOptions): {
+    startVerification: (input: StartVerificationOptions) => Promise<StartedVerification>;
+    issueVerificationLink: (sessionId: string) => Promise<StartedVerification>;
+};

package/dist/server.mjs

@@ -0,0 +1,94 @@
+/* Soliton Web SDK v1. Built from sdk/src via `npm run build:sdk`; do not edit by hand. */
+
+// sdk/src/server.ts
+var VerificationStartError = class extends Error {
+  constructor(stage, sessionId, status, retryAfter) {
+    super(`Verification ${stage} failed${status ? ` (HTTP ${status})` : ""}. No automatic retry was attempted.`);
+    this.stage = stage;
+    this.sessionId = sessionId;
+    this.status = status;
+    this.retryAfter = retryAfter;
+    this.name = "VerificationStartError";
+  }
+};
+function origin(value) {
+  const url = new URL(value);
+  const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (url.protocol !== "https:" && !(local && url.protocol === "http:") || url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+    throw new TypeError("Use an HTTPS origin without credentials, path, query or fragment; HTTP is allowed only on localhost.");
+  }
+  return url.origin;
+}
+function validSessionId(value) {
+  return typeof value === "string" && /^ses_[a-zA-Z0-9]+$/.test(value);
+}
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function createVerificationClient(options) {
+  if (typeof window !== "undefined") throw new Error("The verification client is server-only. Keep API keys on your server.");
+  const apiOrigin = origin(options.apiOrigin);
+  const verificationOrigin = origin(options.verificationOrigin);
+  if (!options.apiKey || /[\s\x00-\x1f\x7f]/.test(options.apiKey)) throw new TypeError("A server API key is required.");
+  const apiKey = options.apiKey;
+  const timeoutMs = options.timeoutMs ?? 2e4;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 12e4) throw new TypeError("timeoutMs must be between 1 and 120000.");
+  async function post(path, stage, sessionId, body, idempotencyKey) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let status;
+    try {
+      const response = await fetch(apiOrigin + path, {
+        method: "POST",
+        redirect: "error",
+        // Never forward a secret to an API redirect target.
+        signal: controller.signal,
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          ...body ? { "Content-Type": "application/json" } : {},
+          ...idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}
+        },
+        ...body ? { body: JSON.stringify(body) } : {}
+      });
+      status = response.status;
+      if (!response.ok) throw new VerificationStartError(stage, sessionId, status, response.headers.get("Retry-After") ?? void 0);
+      return record(await response.json());
+    } catch (error) {
+      if (error instanceof VerificationStartError) throw error;
+      throw new VerificationStartError(stage, sessionId, status);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async function issueVerificationLink(sessionId) {
+    if (!validSessionId(sessionId)) throw new TypeError("A saved ses_ session ID is required.");
+    const issued = await post(`/api/v2/sessions/${sessionId}/link`, "link", sessionId);
+    if (typeof issued.browser_path !== "string" || !/^\/v\/[a-f0-9]{32}$/.test(issued.browser_path)) {
+      throw new VerificationStartError("link", sessionId);
+    }
+    return { sessionId, url: new URL(issued.browser_path, verificationOrigin).href };
+  }
+  async function startVerification(input) {
+    if (!["standard", "medium", "high"].includes(input.tier)) throw new TypeError("Choose standard, medium or high.");
+    if (typeof input.userReference !== "string" || !input.userReference.trim()) throw new TypeError("An authenticated user reference is required.");
+    if (typeof input.idempotencyKey !== "string" || !/^[\x21-\x7e]{1,196}$/.test(input.idempotencyKey)) {
+      throw new TypeError("Use a stable 1\u2013196 character idempotency key for this attempt.");
+    }
+    const session = await post("/api/v2/sessions", "create", void 0, {
+      client_reference_id: input.userReference,
+      checks: [{ type: "presence", configuration: { liveness_tier: input.tier } }]
+    }, input.idempotencyKey);
+    if (!validSessionId(session.id)) throw new VerificationStartError("create");
+    try {
+      await input.onSessionCreated?.(session.id);
+    } catch {
+      throw new VerificationStartError("persist", session.id);
+    }
+    return issueVerificationLink(session.id);
+  }
+  return { startVerification, issueVerificationLink };
+}
+export {
+  VerificationStartError,
+  createVerificationClient
+};

package/dist/trustedOrigin.d.ts

@@ -0,0 +1,2 @@
+/** Exact origin configuration, never derived from the URL being opened. */
+export declare function trustedOrigin(value: string): string;

package/dist/types.d.ts

@@ -12,22 +12,38 @@
  * add payload fields the wrapper is required to understand.
  */
 export interface SolitonVerifyOptions {
-    /** Hosted verification URL from POST /api/v1/verifications. */
+    /**
+     * Hosted URL from the v1 verification API or v2 session link API. Choose
+     * liveness_tier (standard, medium, high) in that server-side request;
+     * the URL binds the tier in both sandbox and production. open() does not
+     * select or override it, and existing SDK versions support every tier.
+     */
     url: string;
+    /**
+     * Explicit trusted origin for a customer-hosted deployment. Exact HTTPS origin
+     * (HTTP loopback for development); must come from your integration configuration,
+     * never from an untrusted link. When set, only this origin is accepted.
+     * Omit to retain the existing Soliton cloud origin allowlist.
+     */
+    verificationOrigin?: 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}.
+     * verdict server-side using the ID saved at creation. For v2, fetch
+     * GET /api/v2/sessions/{savedSessionId}; verificationId remains the
+     * browser UUID alias for compatibility, not the prefixed ses_ ID.
      */
     onComplete: (e: {
         verificationId: string;
     }) => void;
-    /** Flow-level errors: link_expired, link_invalid, origin_not_allowed, storage_unavailable, internal. */
+    /** Flow-level errors: link_expired, link_invalid, origin_not_allowed,
+     * storage_unavailable, internal, load_timeout. A load_timeout closes the
+     * overlay after this callback and invokes onClose, never onComplete. */
     onError?: (e: {
         code: string;
         message: string;
     }) => void;
-    /** User dismissed the flow before completion. */
+    /** Flow closed before completion, including an initial load timeout. */
     onClose?: () => void;
     /** Reserved; passed through to the hosted page as a query param. */
     locale?: string;

package/package.json

@@ -1,18 +1,18 @@
 {
-  "//": "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.",
+  "//": "Publishable manifest for the npm Web SDK. No devDependencies and no own node_modules by design: every build runs from the front-end repository 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.1",
+  "version": "1.1.1",
   "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",
+    "url": "git+https://github.com/georges-soliton/soliton-front-end.git",
     "directory": "sdk"
   },
   "bugs": {
-    "url": "https://github.com/georgesabr/next-app/issues"
+    "url": "https://github.com/georges-soliton/soliton-front-end/issues"
   },
   "publishConfig": {
     "access": "public",
@@ -27,6 +27,12 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "browser": null,
+      "import": "./dist/server.mjs",
+      "require": "./dist/server.cjs"
     }
   },
   "files": [