@soliton-id/web-sdk 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -4,6 +4,37 @@ 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
+unchanged and `1.0.0` remains fully compatible. Published because npm's
+`1.0.0` README is immutable and described test keys incorrectly.
+
+- Rewrote the test-key section: `sk_test_` credentials now produce
+  deterministic synthetic fixtures (`pass` / `fail` / `partial`) that never
+  open the camera, rather than running the same real capture pipeline as
+  `sk_live_`. Documented the scenario/verdict mapping and the strict
+  live/test read isolation.
+- Documented completion webhooks as a polling alternative, and corrected the
+  iframe-origin, CSP, and `Permissions-Policy` guidance to describe the
+  iframe's direct-parent origin and nested frame chains.
+
 ## 1.0.0 — 2026-08-01
 
 First public release.

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
@@ -120,29 +120,55 @@ creation and check it on every status read to make this auditable.
 
 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`.
+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`), **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). 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`.
 
 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
+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.
 
+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
+origins; `/verify`, a query string, and a trailing slash are not part of the
+value you send us. Redirect-domain registration and iframe-origin registration
+are separate: enabling one does not enable the other.
+
 ## 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):
+Content Security Policy (CSP) is the browser response header that controls
+which sources a page may load. If the page that runs the SDK sends restrictive
+security headers, merge the Soliton sources into its existing policies; do not
+replace the rest of your policy with these minimal examples.
+
+When you bundle the npm package:
+
+```text
+Content-Security-Policy: frame-src https://soliton.id
+Permissions-Policy: camera=(self "https://soliton.id"), microphone=(self "https://soliton.id")
+```
+
+When you load the classic CDN script or hosted ESM build, the remote script
+also needs to be allowed:
 
 ```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")
+Content-Security-Policy: frame-src https://soliton.id; script-src https://soliton.id
+Permissions-Policy: camera=(self "https://soliton.id"), microphone=(self "https://soliton.id")
 ```
 
 - `frame-src` must include the Soliton origin you use because the capture flow
@@ -150,31 +176,92 @@ Permissions-Policy: camera=(self "https://soliton.id" "https://staging.soliton.i
 - `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
+- 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
+  sets the matching `allow="camera; microphone"` attribute on the iframe it
+  creates.
+
+These examples use production. Add a staging origin to these directives only
+when Soliton has supplied its exact, working staging URL; include both origins
+only if the same page can open both environments.
+
+For local customer-page testing, send us the exact origin, including its port
+(for example `http://localhost:3000`), for registration. It does not belong in
+`frame-src` or `script-src` while the iframe and hosted SDK still load from
+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.
+
+## 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.
+
+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" }
+```
 
-`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.
+| `test_fixture_scenario` | `verified` | `partial_verification` |
+| ----------------------- | ---------- | ---------------------- |
+| `pass`                  | `true`     | `false`                |
+| `partial`               | `true`     | `true`                 |
+| `fail`                  | `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.
+
+## Completion webhooks
+
+Instead of polling, your server can receive a signed `verification.completed`
+POST the moment a verification reaches its final verdict. Like `onComplete`, it
+is a "check now" signal rather than the verdict itself — fetch the verification
+server-to-server before acting on it. Verify the `X-Soliton-Signature` HMAC,
+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 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.
+`open()` accepts hosted URLs from `https://soliton.id`. When Soliton has
+supplied a working staging flow URL, it also accepts
+`https://staging.soliton.id`; HTTP localhost/127.0.0.1 URLs are accepted for
+development. Every URL must use a `/v/{token}` path; query parameters are
+preserved. The SDK 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/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.0",
+  "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",