@sorisdk/web-audio 0.6.3 → 0.6.4

package/README.md

@@ -22,7 +22,7 @@ configuration, or Node-based asset server is required:
 ```html
 <script type="module">
   import { AudioRecognizer } from
-    "https://cdn.iplateia.com/web/sorisdk/v0.6.3/sori-web-audio.mjs";
+    "https://cdn.iplateia.com/web/sorisdk/v0.6.4/sori-web-audio.mjs";
 
   const recognizer = new AudioRecognizer({
     appId: "YOUR_APP_ID",
@@ -49,7 +49,7 @@ configuration, or Node-based asset server is required:
 ```
 
 Static URL imports are valid inside `<script type="module">`. Dynamic
-`await import("https://cdn.iplateia.com/web/sorisdk/v0.6.3/sori-web-audio.mjs")`
+`await import("https://cdn.iplateia.com/web/sorisdk/v0.6.4/sori-web-audio.mjs")`
 is an optional alternative when the SDK should be loaded conditionally.
 
 Pin an exact version in production. Do not construct a mutable `latest` URL.
@@ -93,7 +93,7 @@ An import map can give the standalone URL the npm package name:
 <script type="importmap">
 {
   "imports": {
-    "@sorisdk/web-audio": "https://cdn.iplateia.com/web/sorisdk/v0.6.3/sori-web-audio.mjs"
+    "@sorisdk/web-audio": "https://cdn.iplateia.com/web/sorisdk/v0.6.4/sori-web-audio.mjs"
   }
 }
 </script>
@@ -159,6 +159,67 @@ await recognizer.stop();
 await recognizer.destroy();
 ```
 
+## Session identifiers
+
+`AudioRecognizer` creates one pseudonymous session identifier per application
+and stores it in `localStorage` under
+`sorisdk:web-audio:session:<appId>`. The value persists until the origin's
+storage is cleared or the session manager's `clear()` method is called. An
+upgrade does not rotate an existing non-empty value, including identifiers
+created by older SDK versions.
+
+New identifiers use `crypto.randomUUID()`. Browsers without `randomUUID()` use
+`crypto.getRandomValues()` to create an RFC 4122 UUID v4. If neither secure API
+is available, session creation fails instead of falling back to predictable
+randomness. A host for such an environment must provide a cryptographically
+secure generator explicitly:
+
+```ts
+import {
+  AudioRecognizer,
+  createLocalStorageSessionManager
+} from "@sorisdk/web-audio";
+
+const sessionManager = createLocalStorageSessionManager({
+  key: "sorisdk:web-audio:session:YOUR_APP_ID",
+  generateSessionId: () => secureSessionIdFromYourRuntime()
+});
+
+const recognizer = new AudioRecognizer({
+  appId: "YOUR_APP_ID",
+  ephemeralKey: fetchEphemeralKeyFromYourServer,
+  sessionManager
+});
+
+// Stop recognition before intentionally rotating the identifier.
+await recognizer.destroy();
+await sessionManager.clear?.();
+```
+
+Treat the identifier as persistent pseudonymous data: do not include personal
+information in a custom value, and do not log or expose it unnecessarily.
+Clearing it breaks device and activity continuity; the next authentication
+creates a new server-side device identity.
+
+### SORI service contract
+
+The current SORI service uses the identifier at these boundaries:
+
+| Boundary | Use of `sessionId` | Security contract |
+| --- | --- | --- |
+| Authentication request | Debounces repeated requests and upserts an account-scoped device record | A valid application ID plus secret or ephemeral key is still required |
+| Session token | Stored as the signed device claim | Possession of the raw identifier does not create or validate a token |
+| Recognition activity | Attributes impressions, clicks, campaign links, and campaign webhooks to a device | Authorization comes from the signed token, not the identifier |
+| Monitoring | Binds stored health and transition data to the token's device claim | A submitted device ID must match the signed claim |
+| Authentication webhook | Populates the webhook `device_id` | The value is correlation data, not a webhook credential |
+| Quota and throttling | Selects the authentication debounce bucket only | It is not a standalone billing or usage quota key |
+| AudioPack caching | Not used as a cache partition | The browser cache remains application-scoped |
+| Replay protection | No use | The stable identifier provides neither freshness nor replay protection |
+
+Authorization, quota enforcement, cache isolation, and replay controls must
+remain bound to authenticated server-side state rather than possession or
+unpredictability of `sessionId`.
+
 ## Advanced wasm loading overrides
 
 If you need to pin explicit generated modules, use the nested `wasm` options:

package/dist/index.js

@@ -201,6 +201,7 @@ var WrappedFingerprintMatchWindow = class {
   constructor(inner) {
     this.inner = inner;
   }
+  inner;
   appendFingerprint(bytes) {
     const fn = getCallable(this.inner, ["appendFingerprint", "append_fingerprint"]);
     if (!fn) {
@@ -1025,11 +1026,31 @@ function resolveStorage2(storage) {
   }
   return globalThis.localStorage;
 }
+function formatUuidV4(bytes) {
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20)
+  ].join("-");
+}
 function defaultGenerateSessionId() {
-  if (typeof globalThis.crypto !== "undefined" && typeof globalThis.crypto.randomUUID === "function") {
-    return globalThis.crypto.randomUUID();
+  const crypto = globalThis.crypto;
+  if (typeof crypto !== "undefined") {
+    if (typeof crypto.randomUUID === "function") {
+      return crypto.randomUUID();
+    }
+    if (typeof crypto.getRandomValues === "function") {
+      return formatUuidV4(crypto.getRandomValues(new Uint8Array(16)));
+    }
   }
-  return `session-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+  throw new Error(
+    "Secure random number generation is unavailable; provide a cryptographically secure `generateSessionId`"
+  );
 }
 function createLocalStorageSessionManager(options) {
   const storage = resolveStorage2(options.storage);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sorisdk/web-audio",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Web SDK for browser-based audio recognition with SORI API",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,13 +34,13 @@
   "license": "SEE LICENSE IN LICENSE.md",
   "homepage": "https://docs.soriapi.com/ko/integration/web",
   "dependencies": {
-    "@sorisdk/matcher": "0.6.3",
-    "@sorisdk/afpgen": "0.6.3"
+    "@sorisdk/matcher": "0.6.4",
+    "@sorisdk/afpgen": "0.6.4"
   },
   "devDependencies": {
     "tsup": "^8.5.1",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.6"
   },
   "scripts": {
     "build:wasm": "node ../../scripts/build-wasm-package.mjs web-audio",