@soliton-id/web-sdk 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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.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

@@ -92,7 +92,7 @@ BACKEND with your API key:
    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
@@ -122,12 +122,16 @@ Embedding is off by default and gated on BOTH layers:
 
 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.
+   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 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).
+   allowlist). This layer is one list for the whole deployment and is not per
+   environment; the per-environment precision comes from layer 1.
 
 A verification link opened inside an iframe with any other direct-parent
 origin refuses to start and reports `origin_not_allowed`.
@@ -190,11 +194,21 @@ 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
 
-`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:
+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.
+
+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
@@ -207,21 +221,20 @@ names the outcome when it creates the verification:
 | `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.
+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.
 
-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.
+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 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.
+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.
 
 ## Completion webhooks
 
@@ -233,6 +246,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/package.json

@@ -1,7 +1,7 @@
 {
   "//": "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.1",
+  "version": "1.0.2",
   "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",