@sparkvault/sdk 1.21.9 → 1.21.11

package/README.md

@@ -16,7 +16,7 @@ The official SparkVault JavaScript SDK for browser applications. Add passwordles
 - [Error Handling](#error-handling)
 - [TypeScript Support](#typescript-support)
 - [Browser Support](#browser-support)
-- [Development](#development)
+- [Build & Release](#build--release)
 - [License](#license)
 
 ## Installation
@@ -717,7 +717,7 @@ The SDK supports all modern browsers:
 
 **Note:** Passkey authentication requires WebAuthn support. On unsupported browsers, passkey will not appear as an option — other methods will still work.
 
-## Development
+## Build & Release
 
 ### Setup
 

package/dist/identity/renderer.d.ts

@@ -96,6 +96,11 @@ export declare class IdentityRenderer {
      * Open a WebSocket connection and return the connectionId.
      * The server echoes back the connectionId on init; this is used to route
      * the SparkLink verification result back to this SDK instance.
+     *
+     * Returns:
+     * - { connectionId: string } on success
+     * - { error: 'csp' } if blocked by Content Security Policy
+     * - { error: 'connection' } for other connection failures
      */
     private openSparkLinkWebSocket;
     /**

package/dist/identity/utils.d.ts

@@ -10,7 +10,7 @@ export { arrayBufferToBase64url, base64urlToArrayBuffer, base64urlToString, } fr
 /**
  * Extract the root (registrable) domain from a hostname for cross-subdomain cookies.
  * Returns the domain prefixed with a dot (e.g., ".client.com") or null when
- * the domain attribute should not be set (localhost, IP addresses).
+ * the domain attribute should not be set (loopback hosts, IP addresses).
  *
  * @param hostname - The hostname to extract the root domain from
  * @returns Root domain with leading dot, or null

package/dist/sparkvault.cjs.js

@@ -565,13 +565,13 @@ const MULTI_PART_TLDS = new Set([
 /**
  * Extract the root (registrable) domain from a hostname for cross-subdomain cookies.
  * Returns the domain prefixed with a dot (e.g., ".client.com") or null when
- * the domain attribute should not be set (localhost, IP addresses).
+ * the domain attribute should not be set (loopback hosts, IP addresses).
  *
  * @param hostname - The hostname to extract the root domain from
  * @returns Root domain with leading dot, or null
  */
 function getRootDomain(hostname) {
-    // Localhost — browsers reject domain attribute for localhost
+    // Loopback host — browsers reject domain attribute for localhost
     if (hostname === 'localhost' || hostname === '127.0.0.1')
         return null;
     // IPv4 addresses
@@ -1422,10 +1422,6 @@ class PasskeyHandler {
             if (hostname === 'sparkvault.com' || hostname.endsWith('.sparkvault.com')) {
                 return true;
             }
-            // Allow localhost for development
-            if (hostname === 'localhost') {
-                return true;
-            }
             return false;
         }
         catch {
@@ -4794,17 +4790,27 @@ class IdentityRenderer {
                 case 'sparklink': {
                     this.setState({ view: 'loading' });
                     // Open WebSocket and get connectionId before sending
-                    const connectionId = await this.openSparkLinkWebSocket();
-                    if (!connectionId) {
+                    const wsResult = await this.openSparkLinkWebSocket();
+                    if ('error' in wsResult) {
                         this.cleanupSparkLink();
-                        this.setState({
-                            view: 'error',
-                            message: 'Failed to establish connection',
-                            code: 'sparklink_ws_failed',
-                        });
+                        if (wsResult.error === 'csp') {
+                            // CSP blocking WebSocket - provide developer-friendly error
+                            this.setState({
+                                view: 'error',
+                                message: 'Connection blocked by security policy. Please contact the site administrator to add wss://*.sparkvault.com to the Content-Security-Policy connect-src directive.',
+                                code: 'sparklink_csp_blocked',
+                            });
+                        }
+                        else {
+                            this.setState({
+                                view: 'error',
+                                message: 'Failed to establish connection',
+                                code: 'sparklink_ws_failed',
+                            });
+                        }
                         return;
                     }
-                    const result = await this.sparkLinkHandler.send(connectionId);
+                    const result = await this.sparkLinkHandler.send(wsResult.connectionId);
                     if (!result.success) {
                         this.cleanupSparkLink();
                         this.setState({
@@ -5107,6 +5113,11 @@ class IdentityRenderer {
      * Open a WebSocket connection and return the connectionId.
      * The server echoes back the connectionId on init; this is used to route
      * the SparkLink verification result back to this SDK instance.
+     *
+     * Returns:
+     * - { connectionId: string } on success
+     * - { error: 'csp' } if blocked by Content Security Policy
+     * - { error: 'connection' } for other connection failures
      */
     openSparkLinkWebSocket() {
         this.cleanupSparkLink();
@@ -5114,13 +5125,27 @@ class IdentityRenderer {
         const wsUrl = `wss://${wsDomain}`;
         return new Promise((resolve) => {
             let resolved = false;
+            let cspViolationDetected = false;
+            // Listen for CSP violations to provide a more helpful error message
+            const cspHandler = (event) => {
+                // Check if this CSP violation is for our WebSocket connection
+                if (event.violatedDirective === 'connect-src' &&
+                    event.blockedURI.includes(wsDomain)) {
+                    cspViolationDetected = true;
+                }
+            };
+            document.addEventListener('securitypolicyviolation', cspHandler);
+            const cleanup = () => {
+                document.removeEventListener('securitypolicyviolation', cspHandler);
+            };
             const ws = new WebSocket(wsUrl);
             this.sparkLinkWs = ws;
             const timeout = setTimeout(() => {
                 if (!resolved) {
                     resolved = true;
+                    cleanup();
                     ws.close();
-                    resolve(null);
+                    resolve({ error: cspViolationDetected ? 'csp' : 'connection' });
                 }
             }, 10000);
             ws.onopen = () => {
@@ -5130,8 +5155,9 @@ class IdentityRenderer {
                 catch {
                     if (!resolved) {
                         resolved = true;
+                        cleanup();
                         clearTimeout(timeout);
-                        resolve(null);
+                        resolve({ error: 'connection' });
                     }
                 }
             };
@@ -5145,24 +5171,27 @@ class IdentityRenderer {
                 }
                 if (!resolved && data.type === 'connection' && typeof data.connectionId === 'string') {
                     resolved = true;
+                    cleanup();
                     clearTimeout(timeout);
                     this.setupSparkLinkWsHandler(ws);
-                    resolve(data.connectionId);
+                    resolve({ connectionId: data.connectionId });
                     return;
                 }
             };
             ws.onerror = () => {
                 if (!resolved) {
                     resolved = true;
+                    cleanup();
                     clearTimeout(timeout);
-                    resolve(null);
+                    resolve({ error: cspViolationDetected ? 'csp' : 'connection' });
                 }
             };
             ws.onclose = () => {
                 if (!resolved) {
                     resolved = true;
+                    cleanup();
                     clearTimeout(timeout);
-                    resolve(null);
+                    resolve({ error: cspViolationDetected ? 'csp' : 'connection' });
                 }
             };
         });
@@ -5252,17 +5281,26 @@ class IdentityRenderer {
      */
     async handleSparkLinkResend() {
         // Open new WebSocket for the resend
-        const connectionId = await this.openSparkLinkWebSocket();
-        if (!connectionId) {
+        const wsResult = await this.openSparkLinkWebSocket();
+        if ('error' in wsResult) {
             this.cleanupSparkLink();
-            this.setState({
-                view: 'error',
-                message: 'Unable to establish a secure connection. Please try again or choose a different method.',
-                code: 'sparklink_ws_failed',
-            });
+            if (wsResult.error === 'csp') {
+                this.setState({
+                    view: 'error',
+                    message: 'Connection blocked by security policy. Please contact the site administrator to add wss://*.sparkvault.com to the Content-Security-Policy connect-src directive.',
+                    code: 'sparklink_csp_blocked',
+                });
+            }
+            else {
+                this.setState({
+                    view: 'error',
+                    message: 'Unable to establish a secure connection. Please try again or choose a different method.',
+                    code: 'sparklink_ws_failed',
+                });
+            }
             return;
         }
-        const result = await this.sparkLinkHandler.send(connectionId);
+        const result = await this.sparkLinkHandler.send(wsResult.connectionId);
         if (result.success) {
             this.setState({
                 view: 'sparklink-waiting',
@@ -9221,7 +9259,6 @@ if (typeof window !== 'undefined') {
     // Auto-initialize from script tag data-account-id attribute
     const instance = autoInit(SparkVault);
     // Expose instance (if auto-init succeeded) or class (for manual init)
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     window.SparkVault = instance ?? SparkVault;
 }