@soliton-id/web-sdk 1.1.2 → 1.2.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 +20 -0
- package/README.md +33 -7
- package/dist/server.cjs +19 -1
- package/dist/server.d.ts +13 -0
- package/dist/server.mjs +19 -1
- package/dist/types.d.ts +5 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,26 @@ 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.2.0 — 2026-11-06
|
|
8
|
+
|
|
9
|
+
Additive only; existing calls are unchanged.
|
|
10
|
+
|
|
11
|
+
- `startVerification()` takes an optional `consent: { givenAt, noticeVersion }`.
|
|
12
|
+
Send it only if you skip the instructions screen (`intro=skip`) and collect
|
|
13
|
+
biometric consent on your own screen. That consent and its record remain
|
|
14
|
+
your responsibility; sending a copy is optional. It goes to Soliton as
|
|
15
|
+
`consent` on session creation, and Soliton then also keeps it for at least
|
|
16
|
+
5 years. `givenAt` is a `Date` or an RFC 3339 string with `Z` or an offset
|
|
17
|
+
(a string without one is refused rather than read as local time), at most
|
|
18
|
+
5 minutes in the future; `noticeVersion` is 1–64 printable characters.
|
|
19
|
+
- `onError` can report `consent_required`: your account requires consent, you
|
|
20
|
+
skipped the instructions screen and sent none, and the account is set to
|
|
21
|
+
refuse such checks. (Set to show the consent screen instead, the flow simply
|
|
22
|
+
shows it.)
|
|
23
|
+
- The README's `intro=skip` section matches the integration guide: link the
|
|
24
|
+
biometric privacy notice (live keys) or the testing data policy (sandbox
|
|
25
|
+
keys), and keep or send a record of each consent.
|
|
26
|
+
|
|
7
27
|
## 1.1.2 — 2026-10-29
|
|
8
28
|
|
|
9
29
|
Documentation only; no code or API changes. The README explains `intro=skip`,
|
package/README.md
CHANGED
|
@@ -201,13 +201,39 @@ const handle = open({ url: directUrl.toString(), onComplete });
|
|
|
201
201
|
|
|
202
202
|
If you skip the instructions screen, you must:
|
|
203
203
|
|
|
204
|
-
1. **Explain the check and collect consent first.** Tell the user
|
|
205
|
-
(camera, plus microphone for Medium and High) and
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
[testing data policy](https://soliton.id/testing-data)
|
|
210
|
-
instructions screen would otherwise show.
|
|
204
|
+
1. **Explain the check and collect biometric consent first.** Tell the user
|
|
205
|
+
what happens (camera, plus microphone for Medium and High) and get their
|
|
206
|
+
express consent to the collection and use of their facial biometric data
|
|
207
|
+
before opening the flow. Link Soliton's
|
|
208
|
+
[biometric privacy notice](https://soliton.id/biometric-notice) (live keys)
|
|
209
|
+
or [testing data policy](https://soliton.id/testing-data) (sandbox keys),
|
|
210
|
+
which the instructions screen would otherwise show. Keep a record of each
|
|
211
|
+
consent: the time, the text shown and the user. When you skip the screen,
|
|
212
|
+
you collect this consent, and you are responsible for it and for keeping its
|
|
213
|
+
record on your own systems. Sending Soliton a copy when you create the
|
|
214
|
+
session is optional; Soliton then also keeps it for at least 5 years:
|
|
215
|
+
|
|
216
|
+
```js
|
|
217
|
+
await soliton.startVerification({
|
|
218
|
+
userReference: user.id,
|
|
219
|
+
tier: 'high',
|
|
220
|
+
idempotencyKey: attempt.id,
|
|
221
|
+
// When the person agreed, and which version of your consent text they saw.
|
|
222
|
+
consent: { givenAt: attempt.consentGivenAt, noticeVersion: 'your-consent-v3' },
|
|
223
|
+
onSessionCreated: async id => { await saveSession(user.id, attempt.id, id); },
|
|
224
|
+
});
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
Without the helper, add
|
|
228
|
+
`"consent": {"given_at": "2026-11-06T18:02:11Z", "notice_version": "your-consent-v3"}`
|
|
229
|
+
to the `POST /api/v2/sessions` body. If Soliton has set your account to
|
|
230
|
+
require consent (everywhere, or where the person is in places agreed with
|
|
231
|
+
you, judged from their IP address; an unknown location counts) and you skip
|
|
232
|
+
the screen without sending it, the person sees Soliton's
|
|
233
|
+
consent screen instead, or the check cannot start and `onError` reports
|
|
234
|
+
`consent_required`, depending on your account's setting. For Medium and
|
|
235
|
+
High, ask users to turn their speaker volume up, which the instructions
|
|
236
|
+
screen does.
|
|
211
237
|
2. **Let every iframe pass on camera, microphone and autoplay.** Each iframe
|
|
212
238
|
between the browser window and the hosted page, including yours, needs
|
|
213
239
|
`allow="camera; microphone; autoplay; fullscreen"`. The SDK's own iframe
|
package/dist/server.cjs
CHANGED
|
@@ -49,6 +49,22 @@ function validSessionId(value) {
|
|
|
49
49
|
function record(value) {
|
|
50
50
|
return value && typeof value === "object" && !Array.isArray(value) ? value : {};
|
|
51
51
|
}
|
|
52
|
+
var RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]([01]\d|2[0-3]):[0-5]\d)$/;
|
|
53
|
+
var MAX_FUTURE_MS = 5 * 6e4;
|
|
54
|
+
function consentBody(consent) {
|
|
55
|
+
const raw = consent.givenAt;
|
|
56
|
+
const givenAt = raw instanceof Date ? raw : typeof raw === "string" && RFC3339.test(raw) ? new Date(raw) : void 0;
|
|
57
|
+
if (!givenAt || Number.isNaN(givenAt.getTime()) || givenAt.getUTCFullYear() < 2e3) {
|
|
58
|
+
throw new TypeError("consent.givenAt must be a Date or an RFC 3339 time with Z or an offset, such as 2026-11-06T18:02:11Z.");
|
|
59
|
+
}
|
|
60
|
+
if (givenAt.getTime() > Date.now() + MAX_FUTURE_MS) throw new TypeError("consent.givenAt cannot be more than 5 minutes in the future.");
|
|
61
|
+
const label = consent.noticeVersion;
|
|
62
|
+
const characters = typeof label === "string" ? Array.from(label).length : 0;
|
|
63
|
+
if (typeof label !== "string" || characters < 1 || characters > 64 || !label.trim() || new RegExp("\\p{Cc}", "u").test(label)) {
|
|
64
|
+
throw new TypeError("consent.noticeVersion must be 1\u201364 printable characters.");
|
|
65
|
+
}
|
|
66
|
+
return { given_at: givenAt.toISOString(), notice_version: label };
|
|
67
|
+
}
|
|
52
68
|
function createVerificationClient(options) {
|
|
53
69
|
if (typeof window !== "undefined") throw new Error("The verification client is server-only. Keep API keys on your server.");
|
|
54
70
|
const apiOrigin = origin(options.apiOrigin);
|
|
@@ -98,9 +114,11 @@ function createVerificationClient(options) {
|
|
|
98
114
|
if (typeof input.idempotencyKey !== "string" || !/^[\x21-\x7e]{1,196}$/.test(input.idempotencyKey)) {
|
|
99
115
|
throw new TypeError("Use a stable 1\u2013196 character idempotency key for this attempt.");
|
|
100
116
|
}
|
|
117
|
+
const consent = input.consent == null ? void 0 : consentBody(input.consent);
|
|
101
118
|
const session = await post("/api/v2/sessions", "create", void 0, {
|
|
102
119
|
client_reference_id: input.userReference,
|
|
103
|
-
checks: [{ type: "presence", configuration: { liveness_tier: input.tier } }]
|
|
120
|
+
checks: [{ type: "presence", configuration: { liveness_tier: input.tier } }],
|
|
121
|
+
...consent ? { consent } : {}
|
|
104
122
|
}, input.idempotencyKey);
|
|
105
123
|
if (!validSessionId(session.id)) throw new VerificationStartError("create");
|
|
106
124
|
try {
|
package/dist/server.d.ts
CHANGED
|
@@ -22,6 +22,19 @@ export interface StartVerificationOptions {
|
|
|
22
22
|
idempotencyKey: string;
|
|
23
23
|
/** Awaited before link issuance. Persist the ID against the authenticated user here. */
|
|
24
24
|
onSessionCreated?: (sessionId: string) => void | Promise<void>;
|
|
25
|
+
/**
|
|
26
|
+
* Optional. Only when you skip Soliton's instructions screen (`intro=skip`) and
|
|
27
|
+
* collected biometric consent on your own screen. That consent and its record stay
|
|
28
|
+
* your responsibility; sending a copy is optional, and Soliton then also keeps it for
|
|
29
|
+
* at least 5 years. Store it with the attempt so a retry sends the identical request.
|
|
30
|
+
*/
|
|
31
|
+
consent?: CustomerConsent | null;
|
|
32
|
+
}
|
|
33
|
+
export interface CustomerConsent {
|
|
34
|
+
/** When the person agreed on your screen: a Date, or an RFC 3339 string with Z or an offset. */
|
|
35
|
+
givenAt: Date | string;
|
|
36
|
+
/** Which version of your consent text they saw, 1–64 printable characters. */
|
|
37
|
+
noticeVersion: string;
|
|
25
38
|
}
|
|
26
39
|
export interface StartedVerification {
|
|
27
40
|
sessionId: string;
|
package/dist/server.mjs
CHANGED
|
@@ -25,6 +25,22 @@ function validSessionId(value) {
|
|
|
25
25
|
function record(value) {
|
|
26
26
|
return value && typeof value === "object" && !Array.isArray(value) ? value : {};
|
|
27
27
|
}
|
|
28
|
+
var RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]([01]\d|2[0-3]):[0-5]\d)$/;
|
|
29
|
+
var MAX_FUTURE_MS = 5 * 6e4;
|
|
30
|
+
function consentBody(consent) {
|
|
31
|
+
const raw = consent.givenAt;
|
|
32
|
+
const givenAt = raw instanceof Date ? raw : typeof raw === "string" && RFC3339.test(raw) ? new Date(raw) : void 0;
|
|
33
|
+
if (!givenAt || Number.isNaN(givenAt.getTime()) || givenAt.getUTCFullYear() < 2e3) {
|
|
34
|
+
throw new TypeError("consent.givenAt must be a Date or an RFC 3339 time with Z or an offset, such as 2026-11-06T18:02:11Z.");
|
|
35
|
+
}
|
|
36
|
+
if (givenAt.getTime() > Date.now() + MAX_FUTURE_MS) throw new TypeError("consent.givenAt cannot be more than 5 minutes in the future.");
|
|
37
|
+
const label = consent.noticeVersion;
|
|
38
|
+
const characters = typeof label === "string" ? Array.from(label).length : 0;
|
|
39
|
+
if (typeof label !== "string" || characters < 1 || characters > 64 || !label.trim() || new RegExp("\\p{Cc}", "u").test(label)) {
|
|
40
|
+
throw new TypeError("consent.noticeVersion must be 1\u201364 printable characters.");
|
|
41
|
+
}
|
|
42
|
+
return { given_at: givenAt.toISOString(), notice_version: label };
|
|
43
|
+
}
|
|
28
44
|
function createVerificationClient(options) {
|
|
29
45
|
if (typeof window !== "undefined") throw new Error("The verification client is server-only. Keep API keys on your server.");
|
|
30
46
|
const apiOrigin = origin(options.apiOrigin);
|
|
@@ -74,9 +90,11 @@ function createVerificationClient(options) {
|
|
|
74
90
|
if (typeof input.idempotencyKey !== "string" || !/^[\x21-\x7e]{1,196}$/.test(input.idempotencyKey)) {
|
|
75
91
|
throw new TypeError("Use a stable 1\u2013196 character idempotency key for this attempt.");
|
|
76
92
|
}
|
|
93
|
+
const consent = input.consent == null ? void 0 : consentBody(input.consent);
|
|
77
94
|
const session = await post("/api/v2/sessions", "create", void 0, {
|
|
78
95
|
client_reference_id: input.userReference,
|
|
79
|
-
checks: [{ type: "presence", configuration: { liveness_tier: input.tier } }]
|
|
96
|
+
checks: [{ type: "presence", configuration: { liveness_tier: input.tier } }],
|
|
97
|
+
...consent ? { consent } : {}
|
|
80
98
|
}, input.idempotencyKey);
|
|
81
99
|
if (!validSessionId(session.id)) throw new VerificationStartError("create");
|
|
82
100
|
try {
|
package/dist/types.d.ts
CHANGED
|
@@ -37,8 +37,11 @@ export interface SolitonVerifyOptions {
|
|
|
37
37
|
verificationId: string;
|
|
38
38
|
}) => void;
|
|
39
39
|
/** Flow-level errors: link_expired, link_invalid, origin_not_allowed,
|
|
40
|
-
* storage_unavailable,
|
|
41
|
-
*
|
|
40
|
+
* storage_unavailable, link_unavailable, consent_required, internal,
|
|
41
|
+
* load_timeout. consent_required means your account requires consent, you
|
|
42
|
+
* skipped the instructions screen (intro=skip) and sent none, and the account
|
|
43
|
+
* is set to refuse such checks. A load_timeout closes the overlay after this
|
|
44
|
+
* callback and invokes onClose, never onComplete. */
|
|
42
45
|
onError?: (e: {
|
|
43
46
|
code: string;
|
|
44
47
|
message: string;
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"//": "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.",
|
|
3
3
|
"name": "@soliton-id/web-sdk",
|
|
4
|
-
"version": "1.
|
|
4
|
+
"version": "1.2.0",
|
|
5
5
|
"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.",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"author": "Soliton",
|