@sorisdk/web-audio 0.6.2 → 0.6.4

package/README.md

@@ -13,7 +13,96 @@ Public integration guide: https://docs.soriapi.com/ko/integration/web
 - An ephemeral key issued by your server
 - Microphone permission granted by the user
 
-## Installation
+## Standalone CDN
+
+For a browser application that does not use npm or a bundler, import the
+versioned standalone module directly. No package installation, Vite/webpack
+configuration, or Node-based asset server is required:
+
+```html
+<script type="module">
+  import { AudioRecognizer } from
+    "https://cdn.iplateia.com/web/sorisdk/v0.6.4/sori-web-audio.mjs";
+
+  const recognizer = new AudioRecognizer({
+    appId: "YOUR_APP_ID",
+    ephemeralKey: async () => {
+      const response = await fetch("/api/ephemeral-key", {
+        method: "POST"
+      });
+
+      if (!response.ok) {
+        throw new Error(`Ephemeral key request failed: HTTP ${response.status}`);
+      }
+
+      const { ephemeral_key } = await response.json();
+      return ephemeral_key;
+    }
+  });
+
+  recognizer.on("campaign", (event) => {
+    console.log(event.campaign);
+  });
+
+  await recognizer.start();
+</script>
+```
+
+Static URL imports are valid inside `<script type="module">`. Dynamic
+`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.
+The module loads its versioned WASM assets and the shared
+`https://cdn.iplateia.com/web/sorisdk/model.pack` automatically.
+
+The standalone module removes the frontend build/server requirement, but it
+does not remove the trusted server requirement for ephemeral credentials.
+Provide a backend or serverless endpoint for the `ephemeralKey` callback, and
+never place a long-lived application secret in browser code.
+
+The application operator is responsible for protecting that endpoint with the
+authentication or anonymous-user verification appropriate to the product,
+plus per-user/IP/session rate limits, issuance quotas, and abuse monitoring. A
+public endpoint that returns a reusable key to every POST request can let an
+anonymous caller consume recognition quota. CORS is required when the endpoint
+is on a different origin, but CORS is not authentication and does not stop
+scripts, bots, or non-browser clients from calling the endpoint.
+
+Production billing and abuse protection must also rely on server-enforced key
+expiry, app/session scope, revocation, and usage quotas. Do not treat the word
+“ephemeral” or secrecy of a browser-visible key as the security boundary.
+
+For a strict Content Security Policy, allow WebAssembly compilation with
+`'wasm-unsafe-eval'`, allow `https://cdn.iplateia.com` in `script-src` and
+`connect-src`, and add the SORI API plus ephemeral-key endpoint origins to
+`connect-src`. For example:
+
+```text
+script-src 'self' 'wasm-unsafe-eval' https://cdn.iplateia.com;
+connect-src 'self' https://cdn.iplateia.com https://console.soriapi.com;
+```
+
+If the module script is inline as in the example above, authorize that script
+with a nonce or hash (or move it into an allowed external script) instead of
+adding `'unsafe-inline'`.
+
+An import map can give the standalone URL the npm package name:
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "@sorisdk/web-audio": "https://cdn.iplateia.com/web/sorisdk/v0.6.4/sori-web-audio.mjs"
+  }
+}
+</script>
+<script type="module">
+  import { AudioRecognizer } from "@sorisdk/web-audio";
+</script>
+```
+
+## npm installation
 
 ```bash
 npm install @sorisdk/web-audio
@@ -70,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.2",
+  "version": "0.6.4",
   "description": "Web SDK for browser-based audio recognition with SORI API",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,17 +34,19 @@
   "license": "SEE LICENSE IN LICENSE.md",
   "homepage": "https://docs.soriapi.com/ko/integration/web",
   "dependencies": {
-    "@sorisdk/matcher": "0.6.2",
-    "@sorisdk/afpgen": "0.6.2"
+    "@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",
     "build": "tsup src/index.ts --format esm --dts && pnpm run build:wasm && node ../../scripts/write-default-loader.mjs packages/web-audio ./generated/window.js",
+    "build:standalone": "pnpm --dir ../afpgen build && pnpm --dir ../matcher build && pnpm run build && vite build --config vite.standalone.config.ts && node ../../scripts/write-standalone-manifest.mjs && node ../../scripts/check-standalone-distribution.mjs",
+    "check:standalone": "node ../../scripts/check-standalone-distribution.mjs",
     "test": "vitest run",
     "test:watch": "vitest"
   }