@soliton-id/web-sdk 1.2.0 → 1.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +28 -0
- package/README.md +52 -2
- package/dist/core.d.ts +49 -0
- package/dist/hostedUrl.d.ts +7 -12
- package/dist/index.cjs +293 -69
- package/dist/index.d.ts +6 -0
- package/dist/index.mjs +293 -69
- package/dist/overlay.d.ts +18 -2
- package/dist/theme.d.ts +61 -0
- package/dist/types.d.ts +18 -2
- package/dist/urlCheck.d.ts +23 -0
- package/dist/white-label.cjs +541 -0
- package/dist/white-label.d.ts +80 -0
- package/dist/white-label.mjs +521 -0
- package/package.json +6 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,34 @@ All notable changes to `@soliton-id/web-sdk`. The `soliton-v1` postMessage
|
|
|
4
4
|
protocol is frozen: changes are additive only, so older SDK versions keep
|
|
5
5
|
working against the hosted flow.
|
|
6
6
|
|
|
7
|
+
## 1.4.0 — 2026-11-11
|
|
8
|
+
|
|
9
|
+
Additive only. Calls without the new option are unchanged, as are the
|
|
10
|
+
`soliton-v1` and `idv-v1` protocols.
|
|
11
|
+
|
|
12
|
+
- `open()` takes an optional `theme` on both the default and the
|
|
13
|
+
`/white-label` import: light and dark color palettes for the hosted
|
|
14
|
+
verification screens, the camera screen (`cameraBackground`, `oval`,
|
|
15
|
+
`ovalProgress`), the overlay backdrop and the close button
|
|
16
|
+
(`closeButton`), plus `colorScheme` (`auto`, `light` or `dark`). Colors are
|
|
17
|
+
opaque hex (`#rgb` or `#rrggbb`); anything else is ignored with one console
|
|
18
|
+
warning and never stops `open()`. Only the light flashes during the check
|
|
19
|
+
keep their own colors. Exports `VerificationTheme`, `ThemeColors` and
|
|
20
|
+
`ThemeColorKey`. Needs the matching hosted verification release.
|
|
21
|
+
|
|
22
|
+
## 1.3.0 — 2026-11-09
|
|
23
|
+
|
|
24
|
+
Additive only. The default import, its `open()` and the `soliton-v1`
|
|
25
|
+
protocol are unchanged, so existing integrations need no code change.
|
|
26
|
+
|
|
27
|
+
- Add `@soliton-id/web-sdk/white-label` (ESM/CJS + types) for a verification
|
|
28
|
+
page served on your own hostname: the same `open()`, callbacks and error
|
|
29
|
+
codes, with `verificationOrigin` required and no built-in hosts (the URL
|
|
30
|
+
must be on exactly that origin). Nothing it adds to your page names Soliton:
|
|
31
|
+
the iframe title is "Identity verification" (or the optional `title`), and
|
|
32
|
+
its DOM markers, spinner, error messages and messages to the verification
|
|
33
|
+
page use neutral names. Needs the matching hosted verification release.
|
|
34
|
+
|
|
7
35
|
## 1.2.0 — 2026-11-06
|
|
8
36
|
|
|
9
37
|
Additive only; existing calls are unchanged.
|
package/README.md
CHANGED
|
@@ -7,6 +7,47 @@ protocol, completion callbacks and server-side result/webhook contracts are
|
|
|
7
7
|
unchanged. See [the appliance guide](../docs/on-premise.md) for runtime origins,
|
|
8
8
|
local assets, packaging, iframe permissions and top-level mobile WebViews.
|
|
9
9
|
|
|
10
|
+
## White-label import
|
|
11
|
+
|
|
12
|
+
For a verification page served on your own hostname (for example
|
|
13
|
+
`https://verify.example.com`, set up for your account by Soliton), import the
|
|
14
|
+
white-label entry instead of the default one:
|
|
15
|
+
|
|
16
|
+
```ts
|
|
17
|
+
import { open } from "@soliton-id/web-sdk/white-label";
|
|
18
|
+
|
|
19
|
+
const handle = open({
|
|
20
|
+
url, // the hosted URL from your backend, on your verification hostname
|
|
21
|
+
verificationOrigin: "https://verify.example.com", // required
|
|
22
|
+
onComplete: ({ verificationId }) => {
|
|
23
|
+
// Fetch the result server-side, as with the default import.
|
|
24
|
+
},
|
|
25
|
+
onError: ({ code, message }) => {},
|
|
26
|
+
onClose: () => {},
|
|
27
|
+
// title: "Identity verification", // optional iframe title
|
|
28
|
+
});
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
It works like the default `open()`, with the same callbacks, error codes and
|
|
32
|
+
`handle.close()`, except:
|
|
33
|
+
|
|
34
|
+
- `verificationOrigin` is required: the exact HTTPS origin of your
|
|
35
|
+
verification hostname, taken from your configuration, never from browser
|
|
36
|
+
input. `open()` throws without it, and the URL must be on exactly that
|
|
37
|
+
origin; there are no built-in hosts. HTTP loopback (for example
|
|
38
|
+
`http://localhost:3000`) is accepted for development.
|
|
39
|
+
- Nothing it adds to your page names Soliton: the iframe title is
|
|
40
|
+
"Identity verification" (or your `title`), and its markup, styles, error
|
|
41
|
+
messages and messages to the verification page use neutral names.
|
|
42
|
+
|
|
43
|
+
Your page's `frame-src` and `Permissions-Policy` then name your verification
|
|
44
|
+
hostname instead of `https://soliton.id`. The default import is unchanged.
|
|
45
|
+
|
|
46
|
+
To keep the package name out of what you ship, build with your bundler's
|
|
47
|
+
production mode and do not publish source maps that include `node_modules`:
|
|
48
|
+
their file paths contain `@soliton-id/web-sdk`. Upload such maps privately to
|
|
49
|
+
your error tracker instead if you need them.
|
|
50
|
+
|
|
10
51
|
## Console API v2
|
|
11
52
|
|
|
12
53
|
The SDK opens `https://soliton.id/v/{token}` links from
|
|
@@ -150,7 +191,7 @@ const handle = open({
|
|
|
150
191
|
},
|
|
151
192
|
onError: ({ code, message }) => {
|
|
152
193
|
// link_expired | link_invalid | origin_not_allowed |
|
|
153
|
-
// storage_unavailable | internal | load_timeout
|
|
194
|
+
// storage_unavailable | link_already_used | capture_failed | internal | load_timeout
|
|
154
195
|
},
|
|
155
196
|
onClose: () => {
|
|
156
197
|
// The flow closed before completion (dismissal or initial load timeout).
|
|
@@ -320,7 +361,16 @@ attempt ended, not that verification passed; fetch the verdict server-to-server.
|
|
|
320
361
|
terminal state. It carries ONLY the verification id, never a verdict.
|
|
321
362
|
- `onError({ code, message })`: flow-level errors (`link_expired`,
|
|
322
363
|
`link_invalid`, `origin_not_allowed`, `storage_unavailable` when the user's
|
|
323
|
-
browser blocks the session storage the flow needs, `
|
|
364
|
+
browser blocks the session storage the flow needs, `link_already_used` when
|
|
365
|
+
the capture was already started from this link in another browser or on
|
|
366
|
+
another device, or the check had already finished when this browser came back
|
|
367
|
+
to it (a reload or a new tab in the same browser otherwise continues the
|
|
368
|
+
capture; start a new session for the user), `capture_failed` when the
|
|
369
|
+
capture could not be completed on this device (its last try never reached
|
|
370
|
+
Soliton, so there is no verdict; the check stays open and expires unfinished;
|
|
371
|
+
start a new session for the user), `internal`). Using up the tries
|
|
372
|
+
ends with `onComplete`, as after a final failed take, not with an error. The
|
|
373
|
+
overlay
|
|
324
374
|
stays open so the hosted page can show its own error card; call
|
|
325
375
|
`handle.close()` if you want it gone. If the frame has not become ready or
|
|
326
376
|
reported an error within 30 seconds, `load_timeout` is emitted instead and
|
package/dist/core.d.ts
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Overlay lifecycle shared by every SDK entry point: frame the hosted
|
|
3
|
+
* verification page in a full-viewport overlay and relay its lifecycle through
|
|
4
|
+
* callbacks. The capture engine runs on the verification origin inside the
|
|
5
|
+
* iframe, so its defenses update with each hosted release and the verdict
|
|
6
|
+
* never touches the customer page (only the verification id does).
|
|
7
|
+
*
|
|
8
|
+
* Each entry injects its own names (message protocol and types, DOM markers,
|
|
9
|
+
* error prefix) and its own URL rules. Nothing in this module names an entry,
|
|
10
|
+
* so a bundle carries only the names of the entry it imports.
|
|
11
|
+
*/
|
|
12
|
+
import type { OverlayNames } from "./overlay";
|
|
13
|
+
import type { ParsedHostedUrl } from "./urlCheck";
|
|
14
|
+
export interface EntryNames {
|
|
15
|
+
/** Protocol marker on every message, in both directions. */
|
|
16
|
+
protocol: string;
|
|
17
|
+
/** Parent -> child ping that lets the hosted page read our origin. */
|
|
18
|
+
hello: string;
|
|
19
|
+
/** Child -> parent lifecycle message types. */
|
|
20
|
+
ready: string;
|
|
21
|
+
complete: string;
|
|
22
|
+
error: string;
|
|
23
|
+
close: string;
|
|
24
|
+
/** Prefix of every error open() throws. */
|
|
25
|
+
errorPrefix: string;
|
|
26
|
+
overlay: OverlayNames;
|
|
27
|
+
/** Extra query parameters set on the iframe URL. */
|
|
28
|
+
params?: ReadonlyArray<readonly [string, string]>;
|
|
29
|
+
}
|
|
30
|
+
export interface OpenOptions {
|
|
31
|
+
url: string;
|
|
32
|
+
verificationOrigin?: string;
|
|
33
|
+
onComplete: (e: {
|
|
34
|
+
verificationId: string;
|
|
35
|
+
}) => void;
|
|
36
|
+
onError?: (e: {
|
|
37
|
+
code: string;
|
|
38
|
+
message: string;
|
|
39
|
+
}) => void;
|
|
40
|
+
onClose?: () => void;
|
|
41
|
+
locale?: string;
|
|
42
|
+
/** Untrusted input: pre-filtered by prepareTheme, never trusted as typed. */
|
|
43
|
+
theme?: unknown;
|
|
44
|
+
}
|
|
45
|
+
export interface OpenHandle {
|
|
46
|
+
close(): void;
|
|
47
|
+
}
|
|
48
|
+
export type UrlRules = (raw: string, verificationOrigin?: string) => ParsedHostedUrl;
|
|
49
|
+
export declare function openOverlay(options: OpenOptions, names: EntryNames, parseUrl: UrlRules): OpenHandle;
|
package/dist/hostedUrl.d.ts
CHANGED
|
@@ -1,17 +1,12 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Validation of the hosted verification URL handed to SolitonVerify.open().
|
|
3
3
|
*
|
|
4
|
-
* The
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
* attacker-chosen page in our overlay.
|
|
4
|
+
* The default entry frames URLs from an approved Soliton origin (http strictly
|
|
5
|
+
* for localhost dev) or, when the integrator configures one, exactly its
|
|
6
|
+
* verificationOrigin. The shared shape rules (bare /v/{32 hex} path, no
|
|
7
|
+
* credentials) live in urlCheck.ts; the Soliton allowlist lives only here, so
|
|
8
|
+
* the white-label entry, which never imports this module, cannot carry it.
|
|
10
9
|
*/
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
url: URL;
|
|
14
|
-
/** Origin the SDK will trust for postMessage events. */
|
|
15
|
-
hostedOrigin: string;
|
|
16
|
-
}
|
|
10
|
+
import type { ParsedHostedUrl } from "./urlCheck";
|
|
11
|
+
export type { ParsedHostedUrl };
|
|
17
12
|
export declare function parseHostedUrl(raw: string, verificationOrigin?: string): ParsedHostedUrl;
|