@sparkvault/sdk 1.11.3 → 1.21.5

package/README.md

@@ -681,6 +681,21 @@ const result: VerifyResult = await sparkvault.identity.pop(options);
 // result.identityType: 'email' | 'phone'
 ```
 
+## Content Security Policy (CSP)
+
+If your site uses a Content Security Policy, you must allow the SparkVault domains:
+
+```
+connect-src https://api.sparkvault.com wss://ws.sparkvault.com;
+script-src https://cdn.sparkvault.com;
+```
+
+| Directive | Domain | Reason |
+|-----------|--------|--------|
+| `connect-src` | `https://api.sparkvault.com` | API requests (identity verification, config) |
+| `connect-src` | `wss://ws.sparkvault.com` | WebSocket for SparkLink push notifications |
+| `script-src` | `https://cdn.sparkvault.com` | SDK script (if using CDN installation) |
+
 ## Best Practices
 
 1. **Initialize Once** — Create the SparkVault instance once when your app loads, not on every login attempt. The SDK preloads configuration for instant modal opening.

package/dist/identity/api.d.ts

@@ -5,7 +5,7 @@
  * Single responsibility: API calls only.
  */
 import type { ResolvedConfig } from '../config';
-import type { SdkConfig, TotpSendResponse, TotpVerifyResponse, PasskeyChallengeResponse, PasskeyVerifyResponse, SparkLinkSendResponse, SparkLinkStatusResponse, AuthContext } from './types';
+import type { SdkConfig, TotpSendResponse, TotpVerifyResponse, PasskeyChallengeResponse, PasskeyVerifyResponse, SparkLinkSendResponse, AuthContext } from './types';
 export declare class IdentityApi {
     private readonly config;
     private readonly timeoutMs;
@@ -102,13 +102,9 @@ export declare class IdentityApi {
     getSocialAuthUrl(provider: string, redirectUri: string, state: string): string;
     /**
      * Send SparkLink email for identity verification.
-     * Includes openerOrigin for postMessage-based completion notification.
+     * Includes connectionId for WebSocket push notification of verification result.
      */
-    sendSparkLink(email: string, authContext?: AuthContext): Promise<SparkLinkSendResponse>;
-    /**
-     * Check SparkLink verification status (polling endpoint)
-     */
-    checkSparkLinkStatus(sparkId: string, _authContext?: AuthContext): Promise<SparkLinkStatusResponse>;
+    sendSparkLink(email: string, connectionId: string, authContext?: AuthContext): Promise<SparkLinkSendResponse>;
 }
 export declare class IdentityApiError extends Error {
     readonly code: string;

package/dist/identity/handlers/index.d.ts

@@ -6,4 +6,4 @@
  */
 export { PasskeyHandler, type PasskeyResult, type PasskeyCheckResult } from './passkey-handler';
 export { TotpHandler, type TotpSendResult, type TotpVerifyResult } from './totp-handler';
-export { SparkLinkHandler, type SparkLinkSendResult, type SparkLinkStatusResult } from './sparklink-handler';
+export { SparkLinkHandler, type SparkLinkSendResult } from './sparklink-handler';

package/dist/identity/handlers/sparklink-handler.d.ts

@@ -1,8 +1,8 @@
 /**
  * SparkLink Handler
  *
- * Single responsibility: SparkLink sending and status polling.
- * Extracts SparkLink logic from IdentityRenderer for better separation of concerns.
+ * Single responsibility: SparkLink sending.
+ * Verification is handled via WebSocket push (no polling, no iframe).
  */
 import type { IdentityApi } from '../api';
 import type { VerificationState } from '../state';
@@ -16,18 +16,7 @@ export interface SparkLinkSendResult {
     error?: string;
 }
 /**
- * Result of SparkLink status check
- */
-export interface SparkLinkStatusResult {
-    verified: boolean;
-    token?: string;
-    identity?: string;
-    identityType?: string;
-    /** Redirect URL for OIDC/simple mode flows */
-    redirect?: string;
-}
-/**
- * Handles SparkLink sending and verification polling
+ * Handles SparkLink sending
  */
 export declare class SparkLinkHandler {
     private readonly api;
@@ -35,11 +24,7 @@ export declare class SparkLinkHandler {
     constructor(api: IdentityApi, state: VerificationState);
     /**
      * Send SparkLink to the user's email
+     * @param connectionId - WebSocket connectionId for push notification
      */
-    send(): Promise<SparkLinkSendResult>;
-    /**
-     * Check SparkLink verification status
-     * Called periodically by the renderer to poll for completion
-     */
-    checkStatus(sparkId: string): Promise<SparkLinkStatusResult>;
+    send(connectionId: string): Promise<SparkLinkSendResult>;
 }

package/dist/identity/renderer.d.ts

@@ -23,8 +23,7 @@ export declare class IdentityRenderer {
     private readonly sparkLinkHandler;
     private currentView;
     private focusTimeoutId;
-    private pollingInterval;
-    private messageListener;
+    private sparkLinkWs;
     constructor(container: Container, api: IdentityApi, options: VerifyOptions, callbacks: RendererCallbacks);
     private get recipient();
     private get identityType();
@@ -88,19 +87,24 @@ export declare class IdentityRenderer {
      */
     private handlePasskeyPromptSkip;
     /**
-     * Start listening for SparkLink verification completion.
-     * Uses postMessage as primary mechanism (instant notification from ceremony page),
-     * with polling as fallback for edge cases where postMessage might fail.
+     * 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.
      */
-    private startSparkLinkPolling;
+    private openSparkLinkWebSocket;
     /**
-     * Handle successful SparkLink verification (from either postMessage or polling).
+     * Set up WebSocket message handler for SparkLink verification results.
+     * Handles: sparklink_verified, sparklink_failed, sparklink_resent.
+     */
+    private setupSparkLinkWsHandler;
+    /**
+     * Handle successful SparkLink verification via WebSocket push.
      */
     private handleSparkLinkVerified;
     /**
-     * Stop SparkLink polling and message listener.
+     * Clean up SparkLink WebSocket connection.
      */
-    private stopSparkLinkPolling;
+    private cleanupSparkLink;
     /**
      * Handle resending SparkLink.
      */

package/dist/identity/types.d.ts

@@ -113,6 +113,8 @@ export interface SdkConfig {
     allowedIdentityTypes?: ('email' | 'phone')[];
     /** Enabled method IDs */
     methods: MethodId[];
+    /** WebSocket domain for SparkLink push notifications (e.g., 'ws.sparkvault.com') */
+    wsDomain?: string;
 }
 /** Method metadata for SDK rendering (static lookup) */
 export interface MethodMetadata {
@@ -173,14 +175,6 @@ export interface SparkLinkSendResponse {
     sparkId: string;
     expiresAt: number;
 }
-export interface SparkLinkStatusResponse {
-    verified: boolean;
-    token?: string;
-    identity?: string;
-    identityType?: string;
-    /** Redirect URL for OIDC/simple mode flows */
-    redirect?: string;
-}
 export type IdentityViewState = {
     view: 'loading';
 } | {
@@ -210,7 +204,6 @@ export type IdentityViewState = {
 } | {
     view: 'sparklink-waiting';
     email: string;
-    sparkId: string;
     expiresAt: number;
 } | {
     view: 'oauth-pending';

package/dist/sparkvault.cjs.js

@@ -833,26 +833,16 @@ class IdentityApi {
     }
     /**
      * Send SparkLink email for identity verification.
-     * Includes openerOrigin for postMessage-based completion notification.
+     * Includes connectionId for WebSocket push notification of verification result.
      */
-    async sendSparkLink(email, authContext) {
+    async sendSparkLink(email, connectionId, authContext) {
         return this.request('POST', '/sparklink/send', {
             email,
             type: 'verify_identity',
-            // Send opener origin for postMessage on verification completion
-            // This allows the ceremony page to notify the SDK directly instead of polling
-            openerOrigin: typeof window !== 'undefined' ? window.location.origin : undefined,
+            connection_id: connectionId,
             ...this.buildAuthContextParams(authContext),
         });
     }
-    /**
-     * Check SparkLink verification status (polling endpoint)
-     */
-    async checkSparkLinkStatus(sparkId, _authContext) {
-        // For GET requests with auth context, we'd need query params, but the status endpoint
-        // doesn't need auth context - it's already stored in the sparklink record
-        return this.request('GET', `/sparklink/status/${sparkId}`);
-    }
 }
 class IdentityApiError extends Error {
     constructor(message, code, statusCode) {
@@ -1494,7 +1484,7 @@ class TotpHandler {
                 success: false,
                 newKindling: response.kindling,
                 retryAfter: response.retry_after,
-                backoffExpires: response.expires_at,
+                backoffExpires: response.retry_after, // When backoff ends (not code expiry)
                 error: 'Invalid code. Please try again.',
             };
         }
@@ -1511,11 +1501,11 @@ class TotpHandler {
 /**
  * SparkLink Handler
  *
- * Single responsibility: SparkLink sending and status polling.
- * Extracts SparkLink logic from IdentityRenderer for better separation of concerns.
+ * Single responsibility: SparkLink sending.
+ * Verification is handled via WebSocket push (no polling, no iframe).
  */
 /**
- * Handles SparkLink sending and verification polling
+ * Handles SparkLink sending
  */
 class SparkLinkHandler {
     constructor(api, state) {
@@ -1524,10 +1514,11 @@ class SparkLinkHandler {
     }
     /**
      * Send SparkLink to the user's email
+     * @param connectionId - WebSocket connectionId for push notification
      */
-    async send() {
+    async send(connectionId) {
         try {
-            const result = await this.api.sendSparkLink(this.state.recipient, this.state.authContext);
+            const result = await this.api.sendSparkLink(this.state.recipient, connectionId, this.state.authContext);
             return {
                 success: true,
                 sparkId: result.sparkId,
@@ -1542,26 +1533,6 @@ class SparkLinkHandler {
             };
         }
     }
-    /**
-     * Check SparkLink verification status
-     * Called periodically by the renderer to poll for completion
-     */
-    async checkStatus(sparkId) {
-        try {
-            const result = await this.api.checkSparkLinkStatus(sparkId);
-            return {
-                verified: result.verified,
-                token: result.token,
-                identity: result.identity,
-                identityType: result.identityType,
-                redirect: result.redirect,
-            };
-        }
-        catch {
-            // On error, return not verified (polling will continue)
-            return { verified: false };
-        }
-    }
 }
 
 /**
@@ -4234,7 +4205,7 @@ class SparkLinkWaitingView {
      * Switch to expired state - static icon, no animation, helpful message
      */
     showExpiredState() {
-        // Notify renderer to stop polling
+        // Notify renderer to clean up WebSocket connection
         this.props.onExpired();
         // Update waiting section: replace spinner with expired icon
         if (this.waitingSection) {
@@ -4381,9 +4352,8 @@ class IdentityRenderer {
         // View management
         this.currentView = null;
         this.focusTimeoutId = null;
-        // SparkLink polling and postMessage listener
-        this.pollingInterval = null;
-        this.messageListener = null;
+        // SparkLink WebSocket
+        this.sparkLinkWs = null;
         this.container = container;
         this.api = api;
         this.options = options;
@@ -4482,7 +4452,7 @@ class IdentityRenderer {
             clearTimeout(this.focusTimeoutId);
             this.focusTimeoutId = null;
         }
-        this.stopSparkLinkPolling();
+        this.cleanupSparkLink();
         this.destroyCurrentView();
         this.container.destroy();
     }
@@ -4587,7 +4557,7 @@ class IdentityRenderer {
                     onResend: () => this.handleSparkLinkResend(),
                     onFallback: () => this.handleSparkLinkFallback(),
                     onBack: () => this.showMethodSelect(),
-                    onExpired: () => this.stopSparkLinkPolling(),
+                    onExpired: () => this.cleanupSparkLink(),
                 });
             case 'oauth-pending':
                 return new LoadingView({ message: `Connecting to ${state.provider}...` });
@@ -4717,8 +4687,20 @@ class IdentityRenderer {
                 }
                 case 'sparklink': {
                     this.setState({ view: 'loading' });
-                    const result = await this.sparkLinkHandler.send();
+                    // Open WebSocket and get connectionId before sending
+                    const connectionId = await this.openSparkLinkWebSocket();
+                    if (!connectionId) {
+                        this.cleanupSparkLink();
+                        this.setState({
+                            view: 'error',
+                            message: 'Failed to establish connection',
+                            code: 'sparklink_ws_failed',
+                        });
+                        return;
+                    }
+                    const result = await this.sparkLinkHandler.send(connectionId);
                     if (!result.success) {
+                        this.cleanupSparkLink();
                         this.setState({
                             view: 'error',
                             message: result.error ?? 'Failed to send SparkLink',
@@ -4729,10 +4711,8 @@ class IdentityRenderer {
                     this.setState({
                         view: 'sparklink-waiting',
                         email: this.recipient,
-                        sparkId: result.sparkId,
                         expiresAt: result.expiresAt,
                     });
-                    this.startSparkLinkPolling(result.sparkId);
                     break;
                 }
                 case 'social': {
@@ -5018,51 +4998,119 @@ class IdentityRenderer {
         this.callbacks.onSuccess(pendingResult);
     }
     /**
-     * Start listening for SparkLink verification completion.
-     * Uses postMessage as primary mechanism (instant notification from ceremony page),
-     * with polling as fallback for edge cases where postMessage might fail.
+     * 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.
      */
-    startSparkLinkPolling(sparkId) {
-        this.stopSparkLinkPolling();
-        // Primary: Listen for postMessage from ceremony page
-        // This is faster and more reliable than polling
-        this.messageListener = (event) => {
-            // Validate message structure and type
-            if (!event.data || typeof event.data !== 'object')
-                return;
-            if (event.data.type !== 'sparklink_verified')
-                return;
-            const { token, identity, identityType, redirect } = event.data;
-            // Validate required fields
-            if (!token || !identity)
+    openSparkLinkWebSocket() {
+        this.cleanupSparkLink();
+        const wsDomain = this.sdkConfig?.wsDomain || 'ws.sparkvault.com';
+        const wsUrl = `wss://${wsDomain}`;
+        return new Promise((resolve) => {
+            let resolved = false;
+            const ws = new WebSocket(wsUrl);
+            this.sparkLinkWs = ws;
+            const timeout = setTimeout(() => {
+                if (!resolved) {
+                    resolved = true;
+                    ws.close();
+                    resolve(null);
+                }
+            }, 10000);
+            ws.onopen = () => {
+                try {
+                    ws.send(JSON.stringify({ action: 'init' }));
+                }
+                catch {
+                    if (!resolved) {
+                        resolved = true;
+                        clearTimeout(timeout);
+                        resolve(null);
+                    }
+                }
+            };
+            ws.onmessage = (event) => {
+                let data;
+                try {
+                    data = JSON.parse(event.data);
+                }
+                catch {
+                    return;
+                }
+                if (!resolved && data.type === 'connection' && typeof data.connectionId === 'string') {
+                    resolved = true;
+                    clearTimeout(timeout);
+                    this.setupSparkLinkWsHandler(ws);
+                    resolve(data.connectionId);
+                    return;
+                }
+            };
+            ws.onerror = () => {
+                if (!resolved) {
+                    resolved = true;
+                    clearTimeout(timeout);
+                    resolve(null);
+                }
+            };
+            ws.onclose = () => {
+                if (!resolved) {
+                    resolved = true;
+                    clearTimeout(timeout);
+                    resolve(null);
+                }
+            };
+        });
+    }
+    /**
+     * Set up WebSocket message handler for SparkLink verification results.
+     * Handles: sparklink_verified, sparklink_failed, sparklink_resent.
+     */
+    setupSparkLinkWsHandler(ws) {
+        ws.onmessage = (event) => {
+            let data;
+            try {
+                data = JSON.parse(event.data);
+            }
+            catch {
                 return;
-            this.handleSparkLinkVerified({
-                token,
-                identity,
-                identityType: identityType || 'email',
-                redirect,
-            });
-        };
-        window.addEventListener('message', this.messageListener);
-        // Fallback: Poll status endpoint every 2 seconds
-        // This catches cases where postMessage might not work (popup blockers, etc)
-        this.pollingInterval = setInterval(async () => {
-            const status = await this.sparkLinkHandler.checkStatus(sparkId);
-            if (status.verified && status.token && status.identity) {
-                this.handleSparkLinkVerified({
-                    token: status.token,
-                    identity: status.identity,
-                    identityType: status.identityType || 'email',
-                    redirect: status.redirect,
-                });
             }
-        }, 2000);
+            switch (data.type) {
+                case 'sparklink_verified':
+                    this.handleSparkLinkVerified({
+                        token: data.token,
+                        identity: data.identity,
+                        identityType: data.identityType || 'email',
+                    });
+                    break;
+                case 'sparklink_failed':
+                    this.cleanupSparkLink();
+                    this.setState({
+                        view: 'error',
+                        message: 'Verification failed. Please try again or choose a different method.',
+                        code: 'sparklink_failed',
+                    });
+                    break;
+                case 'sparklink_resent':
+                    // Server auto-resent a new link — update countdown timer
+                    if (typeof data.expiresAt === 'number') {
+                        this.setState({
+                            view: 'sparklink-waiting',
+                            email: this.recipient,
+                            expiresAt: data.expiresAt,
+                        });
+                    }
+                    break;
+            }
+        };
+        ws.onclose = () => {
+            this.sparkLinkWs = null;
+        };
     }
     /**
-     * Handle successful SparkLink verification (from either postMessage or polling).
+     * Handle successful SparkLink verification via WebSocket push.
      */
     async handleSparkLinkVerified(result) {
-        this.stopSparkLinkPolling();
+        this.cleanupSparkLink();
         // Handle redirect for OIDC/simple mode flows
         if (result.redirect) {
             this.close();
@@ -5082,39 +5130,54 @@ class IdentityRenderer {
         this.callbacks.onSuccess(result);
     }
     /**
-     * Stop SparkLink polling and message listener.
+     * Clean up SparkLink WebSocket connection.
      */
-    stopSparkLinkPolling() {
-        if (this.pollingInterval) {
-            clearInterval(this.pollingInterval);
-            this.pollingInterval = null;
-        }
-        if (this.messageListener) {
-            window.removeEventListener('message', this.messageListener);
-            this.messageListener = null;
+    cleanupSparkLink() {
+        if (this.sparkLinkWs) {
+            this.sparkLinkWs.onmessage = null;
+            this.sparkLinkWs.onclose = null;
+            this.sparkLinkWs.onerror = null;
+            this.sparkLinkWs.close();
+            this.sparkLinkWs = null;
         }
     }
     /**
      * Handle resending SparkLink.
      */
     async handleSparkLinkResend() {
-        const result = await this.sparkLinkHandler.send();
-        if (result.success && result.sparkId) {
-            this.stopSparkLinkPolling();
+        // Open new WebSocket for the resend
+        const connectionId = await this.openSparkLinkWebSocket();
+        if (!connectionId) {
+            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',
+            });
+            return;
+        }
+        const result = await this.sparkLinkHandler.send(connectionId);
+        if (result.success) {
             this.setState({
                 view: 'sparklink-waiting',
                 email: this.recipient,
-                sparkId: result.sparkId,
                 expiresAt: result.expiresAt,
             });
-            this.startSparkLinkPolling(result.sparkId);
+        }
+        else {
+            this.cleanupSparkLink();
+            this.setState({
+                view: 'error',
+                message: result.error ?? 'Failed to resend verification link. Please try again.',
+                code: 'sparklink_resend_failed',
+            });
         }
     }
     /**
      * Handle fallback from SparkLink to TOTP verification code.
      */
     async handleSparkLinkFallback() {
-        this.stopSparkLinkPolling();
+        this.cleanupSparkLink();
         this.setState({ view: 'loading' });
         const result = await this.totpHandler.send('email');
         if (!result.success) {