@soliton-id/web-sdk 1.1.2 → 1.3.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/dist/index.mjs CHANGED
@@ -1,57 +1,13 @@
1
1
  /* Soliton Web SDK v1. Built from sdk/src via `npm run build:sdk`; do not edit by hand. */
2
2
 
3
- // sdk/src/trustedOrigin.ts
4
- function trustedOrigin(value) {
5
- const url = new URL(value);
6
- const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
7
- if (url.origin !== value || url.username || url.password || value.includes("*") || url.protocol !== "https:" && !(url.protocol === "http:" && local)) {
8
- throw new Error("Use an exact HTTPS origin (HTTP loopback is allowed for development)");
9
- }
10
- return url.origin;
11
- }
12
-
13
- // sdk/src/hostedUrl.ts
14
- var HOSTED_PATH_RE = /^\/v\/[0-9a-f]{32}$/;
15
- var ALLOWED_HTTPS_ORIGINS = /* @__PURE__ */ new Set([
16
- "https://soliton.id",
17
- "https://staging.soliton.id"
18
- ]);
19
- function parseHostedUrl(raw, verificationOrigin) {
20
- const configuredOrigin = verificationOrigin === void 0 ? void 0 : trustedOrigin(verificationOrigin);
21
- let url;
22
- try {
23
- url = new URL(raw);
24
- } catch (e) {
25
- throw new Error(`SolitonVerify: "url" is not a valid absolute URL`);
26
- }
27
- const isLocalHttp = url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
28
- if (configuredOrigin !== void 0 && url.origin !== configuredOrigin) {
29
- throw new Error('SolitonVerify: "url" does not match the configured verificationOrigin');
30
- }
31
- if (configuredOrigin === void 0 && !ALLOWED_HTTPS_ORIGINS.has(url.origin) && !isLocalHttp) {
32
- throw new Error(
33
- 'SolitonVerify: "url" must be hosted on https://soliton.id or https://staging.soliton.id (http is allowed for localhost/127.0.0.1 development only)'
34
- );
35
- }
36
- if (url.username || url.password) {
37
- throw new Error('SolitonVerify: "url" must not embed credentials');
38
- }
39
- if (!HOSTED_PATH_RE.test(url.pathname)) {
40
- throw new Error(
41
- 'SolitonVerify: "url" does not look like a hosted verification URL (/v/{token})'
42
- );
43
- }
44
- return { url, hostedOrigin: url.origin };
45
- }
46
-
47
3
  // sdk/src/overlay.ts
48
4
  var MAX_Z_INDEX = "2147483647";
49
5
  var openOverlayCount = 0;
50
6
  var savedBodyOverflow = "";
51
- function createOverlay(iframeSrc, onCloseClick) {
7
+ function createOverlay(iframeSrc, onCloseClick, names) {
52
8
  const doc = document;
53
9
  const container = doc.createElement("div");
54
- container.setAttribute("data-soliton-sdk", "overlay");
10
+ container.setAttribute(names.marker, "overlay");
55
11
  container.style.cssText = [
56
12
  "position:fixed",
57
13
  "inset:0",
@@ -60,10 +16,10 @@ function createOverlay(iframeSrc, onCloseClick) {
60
16
  "display:block"
61
17
  ].join(";");
62
18
  const style = doc.createElement("style");
63
- style.textContent = "@keyframes soliton-sdk-spin{to{transform:rotate(360deg)}}";
19
+ style.textContent = `@keyframes ${names.animation}{to{transform:rotate(360deg)}}`;
64
20
  container.appendChild(style);
65
21
  const loading = doc.createElement("div");
66
- loading.setAttribute("data-soliton-sdk", "loading");
22
+ loading.setAttribute(names.marker, "loading");
67
23
  loading.style.cssText = [
68
24
  "position:absolute",
69
25
  "inset:0",
@@ -82,7 +38,7 @@ function createOverlay(iframeSrc, onCloseClick) {
82
38
  "border-radius:999px",
83
39
  "border:2px solid rgba(255,255,255,0.25)",
84
40
  "border-top-color:rgba(255,255,255,0.9)",
85
- "animation:soliton-sdk-spin 0.8s linear infinite"
41
+ `animation:${names.animation} 0.8s linear infinite`
86
42
  ].join(";");
87
43
  const loadingText = doc.createElement("div");
88
44
  loadingText.textContent = "Loading secure verification...";
@@ -91,7 +47,7 @@ function createOverlay(iframeSrc, onCloseClick) {
91
47
  container.appendChild(loading);
92
48
  const iframe = doc.createElement("iframe");
93
49
  iframe.setAttribute("allow", "camera; microphone; fullscreen; autoplay");
94
- iframe.setAttribute("title", "Soliton identity verification");
50
+ iframe.setAttribute("title", names.title);
95
51
  iframe.style.cssText = [
96
52
  "position:absolute",
97
53
  "inset:0",
@@ -146,43 +102,42 @@ function createOverlay(iframeSrc, onCloseClick) {
146
102
  };
147
103
  }
148
104
 
149
- // sdk/src/types.ts
150
- var EMBED_PROTOCOL = "soliton-v1";
151
-
152
- // sdk/src/index.ts
105
+ // sdk/src/core.ts
153
106
  var AUTO_CLOSE_DELAY_MS = 250;
154
107
  var HELLO_INTERVAL_MS = 250;
155
108
  var HELLO_MAX_PINGS = 40;
156
109
  var READY_TIMEOUT_MS = 3e4;
157
- function open(options) {
110
+ function openOverlay(options, names, parseUrl) {
111
+ var _a;
158
112
  if (!options || typeof options.url !== "string") {
159
- throw new Error('SolitonVerify: open() requires an options object with a "url"');
113
+ throw new Error(`${names.errorPrefix} open() requires an options object with a "url"`);
160
114
  }
161
115
  if (typeof options.onComplete !== "function") {
162
- throw new Error("SolitonVerify: open() requires an onComplete callback");
116
+ throw new Error(`${names.errorPrefix} open() requires an onComplete callback`);
163
117
  }
164
- const { url, hostedOrigin } = parseHostedUrl(options.url, options.verificationOrigin);
118
+ const { url, hostedOrigin } = parseUrl(options.url, options.verificationOrigin);
165
119
  const src = new URL(url.toString());
166
120
  src.searchParams.set("mode", "embed");
167
121
  src.searchParams.set("sdk", "1");
122
+ for (const [key, value] of (_a = names.params) != null ? _a : []) src.searchParams.set(key, value);
168
123
  if (options.locale) src.searchParams.set("locale", options.locale);
169
124
  let closed = false;
170
125
  let terminalDelivered = false;
171
126
  let loadTimedOut = false;
172
127
  let autoCloseTimer = null;
173
128
  let readyTimer = null;
174
- const overlay = createOverlay(src.toString(), () => close());
129
+ const overlay = createOverlay(src.toString(), () => close(), names.overlay);
175
130
  let helloPings = 0;
176
131
  const postHello = () => {
177
- var _a;
132
+ var _a2;
178
133
  helloPings += 1;
179
134
  if (helloPings > HELLO_MAX_PINGS) {
180
135
  stopHello();
181
136
  return;
182
137
  }
183
138
  try {
184
- (_a = overlay.iframe.contentWindow) == null ? void 0 : _a.postMessage(
185
- { protocol: EMBED_PROTOCOL, type: "soliton:hello" },
139
+ (_a2 = overlay.iframe.contentWindow) == null ? void 0 : _a2.postMessage(
140
+ { protocol: names.protocol, type: names.hello },
186
141
  hostedOrigin
187
142
  );
188
143
  } catch (e) {
@@ -200,23 +155,23 @@ function open(options) {
200
155
  readyTimer = null;
201
156
  }
202
157
  const onMessage = (event) => {
203
- var _a;
158
+ var _a2;
204
159
  if (closed || loadTimedOut || terminalDelivered) return;
205
160
  if (event.origin !== hostedOrigin) return;
206
161
  if (!overlay.iframe.contentWindow || event.source !== overlay.iframe.contentWindow) {
207
162
  return;
208
163
  }
209
164
  const data = event.data;
210
- if (!data || typeof data !== "object" || data.protocol !== EMBED_PROTOCOL) {
165
+ if (!data || typeof data !== "object" || data.protocol !== names.protocol) {
211
166
  return;
212
167
  }
213
168
  stopHello();
214
169
  switch (data.type) {
215
- case "soliton:ready":
170
+ case names.ready:
216
171
  stopReadyWait();
217
172
  overlay.markReady();
218
173
  break;
219
- case "soliton:complete": {
174
+ case names.complete: {
220
175
  if (terminalDelivered) break;
221
176
  stopReadyWait();
222
177
  terminalDelivered = true;
@@ -226,14 +181,14 @@ function open(options) {
226
181
  });
227
182
  break;
228
183
  }
229
- case "soliton:error":
184
+ case names.error:
230
185
  stopReadyWait();
231
- (_a = options.onError) == null ? void 0 : _a.call(options, {
186
+ (_a2 = options.onError) == null ? void 0 : _a2.call(options, {
232
187
  code: typeof data.code === "string" ? data.code : "internal",
233
188
  message: typeof data.message === "string" ? data.message : ""
234
189
  });
235
190
  break;
236
- case "soliton:close":
191
+ case names.close:
237
192
  close();
238
193
  break;
239
194
  default:
@@ -242,11 +197,11 @@ function open(options) {
242
197
  };
243
198
  window.addEventListener("message", onMessage);
244
199
  readyTimer = setTimeout(() => {
245
- var _a;
200
+ var _a2;
246
201
  if (readyTimer === null || closed || terminalDelivered) return;
247
202
  loadTimedOut = true;
248
203
  try {
249
- (_a = options.onError) == null ? void 0 : _a.call(options, {
204
+ (_a2 = options.onError) == null ? void 0 : _a2.call(options, {
250
205
  code: "load_timeout",
251
206
  message: "Verification did not load. Please try again."
252
207
  });
@@ -255,7 +210,7 @@ function open(options) {
255
210
  }
256
211
  }, READY_TIMEOUT_MS);
257
212
  function close() {
258
- var _a;
213
+ var _a2;
259
214
  if (closed) return;
260
215
  closed = true;
261
216
  if (autoCloseTimer !== null) clearTimeout(autoCloseTimer);
@@ -263,10 +218,89 @@ function open(options) {
263
218
  stopHello();
264
219
  window.removeEventListener("message", onMessage);
265
220
  overlay.destroy();
266
- if (!terminalDelivered) (_a = options.onClose) == null ? void 0 : _a.call(options);
221
+ if (!terminalDelivered) (_a2 = options.onClose) == null ? void 0 : _a2.call(options);
267
222
  }
268
223
  return { close };
269
224
  }
225
+
226
+ // sdk/src/trustedOrigin.ts
227
+ function trustedOrigin(value) {
228
+ const url = new URL(value);
229
+ const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
230
+ if (url.origin !== value || url.username || url.password || value.includes("*") || url.protocol !== "https:" && !(url.protocol === "http:" && local)) {
231
+ throw new Error("Use an exact HTTPS origin (HTTP loopback is allowed for development)");
232
+ }
233
+ return url.origin;
234
+ }
235
+
236
+ // sdk/src/urlCheck.ts
237
+ var HOSTED_PATH_RE = /^\/v\/[0-9a-f]{32}$/;
238
+ function checkHostedUrl(raw, prefix, configuredOrigin, checkUnconfigured) {
239
+ let url;
240
+ try {
241
+ url = new URL(raw);
242
+ } catch (e) {
243
+ throw new Error(`${prefix} "url" is not a valid absolute URL`);
244
+ }
245
+ if (configuredOrigin !== void 0) {
246
+ if (url.origin !== configuredOrigin) {
247
+ throw new Error(`${prefix} "url" does not match the configured verificationOrigin`);
248
+ }
249
+ } else if (checkUnconfigured) {
250
+ checkUnconfigured(url);
251
+ } else {
252
+ throw new Error(`${prefix} open() requires "verificationOrigin"`);
253
+ }
254
+ if (url.username || url.password) {
255
+ throw new Error(`${prefix} "url" must not embed credentials`);
256
+ }
257
+ if (!HOSTED_PATH_RE.test(url.pathname)) {
258
+ throw new Error(
259
+ `${prefix} "url" does not look like a hosted verification URL (/v/{token})`
260
+ );
261
+ }
262
+ return { url, hostedOrigin: url.origin };
263
+ }
264
+
265
+ // sdk/src/hostedUrl.ts
266
+ var ERROR_PREFIX = "SolitonVerify:";
267
+ var ALLOWED_HTTPS_ORIGINS = /* @__PURE__ */ new Set([
268
+ "https://soliton.id",
269
+ "https://staging.soliton.id"
270
+ ]);
271
+ function parseHostedUrl(raw, verificationOrigin) {
272
+ const configuredOrigin = verificationOrigin === void 0 ? void 0 : trustedOrigin(verificationOrigin);
273
+ return checkHostedUrl(raw, ERROR_PREFIX, configuredOrigin, (url) => {
274
+ const isLocalHttp = url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
275
+ if (!ALLOWED_HTTPS_ORIGINS.has(url.origin) && !isLocalHttp) {
276
+ throw new Error(
277
+ 'SolitonVerify: "url" must be hosted on https://soliton.id or https://staging.soliton.id (http is allowed for localhost/127.0.0.1 development only)'
278
+ );
279
+ }
280
+ });
281
+ }
282
+
283
+ // sdk/src/types.ts
284
+ var EMBED_PROTOCOL = "soliton-v1";
285
+
286
+ // sdk/src/index.ts
287
+ var SOLITON_NAMES = {
288
+ protocol: EMBED_PROTOCOL,
289
+ hello: "soliton:hello",
290
+ ready: "soliton:ready",
291
+ complete: "soliton:complete",
292
+ error: "soliton:error",
293
+ close: "soliton:close",
294
+ errorPrefix: "SolitonVerify:",
295
+ overlay: {
296
+ marker: "data-soliton-sdk",
297
+ animation: "soliton-sdk-spin",
298
+ title: "Soliton identity verification"
299
+ }
300
+ };
301
+ function open(options) {
302
+ return openOverlay(options, SOLITON_NAMES, parseHostedUrl);
303
+ }
270
304
  var SolitonVerify = { open };
271
305
  var index_default = SolitonVerify;
272
306
  export {
package/dist/overlay.d.ts CHANGED
@@ -7,11 +7,23 @@
7
7
  * styles so the SDK needs no stylesheet and cannot clash with host CSS
8
8
  * (spinner keyframes ride in a scoped <style> tag inside the overlay).
9
9
  */
10
+ /**
11
+ * Names the overlay puts in the host page's DOM. Each SDK entry injects its
12
+ * own, so an entry's bundle carries only the names it uses.
13
+ */
14
+ export interface OverlayNames {
15
+ /** Attribute marking the overlay's elements ("overlay", "loading"). */
16
+ marker: string;
17
+ /** Keyframes name of the loading spinner. */
18
+ animation: string;
19
+ /** Accessible title of the iframe. */
20
+ title: string;
21
+ }
10
22
  export interface Overlay {
11
23
  iframe: HTMLIFrameElement;
12
- /** Hide the loading state once the hosted page reports soliton:ready. */
24
+ /** Hide the loading state once the hosted page reports ready. */
13
25
  markReady(): void;
14
26
  /** Remove the overlay from the DOM and restore body scroll. Idempotent. */
15
27
  destroy(): void;
16
28
  }
17
- export declare function createOverlay(iframeSrc: string, onCloseClick: () => void): Overlay;
29
+ export declare function createOverlay(iframeSrc: string, onCloseClick: () => void, names: OverlayNames): Overlay;
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;
@@ -0,0 +1,23 @@
1
+ /**
2
+ * URL rules shared by every SDK entry point. The SDK only ever frames URLs
3
+ * shaped like the ones the verification APIs mint: an accepted origin and a
4
+ * bare /v/{32 hex} path. Everything else throws synchronously: a bad URL is
5
+ * an integration bug, not a runtime flow event, so it must fail loudly at the
6
+ * call site instead of rendering an attacker-chosen page in the overlay.
7
+ *
8
+ * Each entry supplies its own error prefix and, when it has one, its own rule
9
+ * for URLs opened without a configured origin, so no entry's bundle carries
10
+ * another entry's hosts or names.
11
+ */
12
+ export interface ParsedHostedUrl {
13
+ /** The validated URL, normalized by the URL parser. */
14
+ url: URL;
15
+ /** Origin the SDK will trust for postMessage events. */
16
+ hostedOrigin: string;
17
+ }
18
+ /**
19
+ * Validate `raw` against `configuredOrigin` (already checked by
20
+ * trustedOrigin) when there is one, else against `checkUnconfigured`. An entry
21
+ * without a rule for unconfigured URLs refuses them.
22
+ */
23
+ export declare function checkHostedUrl(raw: string, prefix: string, configuredOrigin: string | undefined, checkUnconfigured?: (url: URL) => void): ParsedHostedUrl;