@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 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 what happens
205
- (camera, plus microphone for Medium and High) and collect any consent you
206
- need before opening the flow. For Medium and High, ask users to turn their
207
- speaker volume up, which the instructions screen does. For sandbox links,
208
- include Soliton's
209
- [testing data policy](https://soliton.id/testing-data), which the
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, internal, load_timeout. A load_timeout closes the
41
- * overlay after this callback and invokes onClose, never onComplete. */
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.1.2",
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",