@soliton-id/web-sdk 1.0.0 → 1.0.1

package/CHANGELOG.md

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

@@ -120,29 +120,51 @@ 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`). 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
-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 +172,77 @@ 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.
+
+## Test mode
+
+`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:
+
+```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`                |
+
+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.
+
+## 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).
 
 ## 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.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",