@safepassage/sdk 3.0.3 → 3.0.5

package/dist/core/SafePassageSDK.js

@@ -0,0 +1,587 @@
+/**
+ * SafePassage SDK - Redirect-based age verification
+ *
+ * Lightweight SDK for integrating SafePassage age verification using redirect flow.
+ * Provides a secure, easy-to-implement solution for age verification with comprehensive
+ * security features and flexible integration options.
+ *
+ * Key Features:
+ * - Redirect and new-tab verification modes
+ * - Automatic session management for public API keys
+ * - HMAC-signed state parameters for security
+ * - Rate limiting and race condition protection
+ * - Comprehensive security validation and logging
+ * - PostMessage communication for new-tab mode
+ * - Automatic cleanup and resource management
+ * - Environment-specific configuration
+ *
+ * Security Features:
+ * - Origin validation for PostMessage communication
+ * - HTTPS enforcement in production
+ * - Rate limiting per API key and origin
+ * - State parameter signing with timestamps and nonces
+ * - Comprehensive security event logging
+ * - Protection against race conditions and replay attacks
+ *
+ * @author SafePassage Engineering
+ * @version 2.0.0
+ * @since 1.0.0
+ */
+import { generateState, validateConfig } from '../utils/validation';
+import { getEnvironmentUrl, validateEnvironmentSecurity, } from '../utils/environment';
+import { validatePostMessageOrigin, validateSafePassageMessage, enforceHTTPS, verificationRateLimit, logSecurityEvent, } from '../utils/security';
+/**
+ * SafePassage SDK Main Class
+ *
+ * Primary SDK class that manages age verification sessions with comprehensive
+ * security and error handling. Supports both redirect and new-tab modes with
+ * automatic session management and PostMessage communication.
+ *
+ * The class implements multiple security layers including origin validation,
+ * rate limiting, state signing, and comprehensive event logging to ensure
+ * secure verification flows.
+ */
+export class SafePassage {
+    /**
+     * Initialize SafePassage SDK
+     *
+     * Validates configuration, sets up security measures, and prepares the SDK
+     * for verification operations. Performs comprehensive environment validation
+     * and security initialization.
+     *
+     * @param {SafePassageConfig} config - SDK configuration object
+     * @throws {Error} If configuration validation fails
+     */
+    constructor(config) {
+        this.popupWindow = null;
+        this.messageListener = null;
+        this.popupMonitorInterval = null;
+        this.unloadListener = null;
+        this.isVerificationInProgress = false;
+        this.currentSessionId = null;
+        validateConfig(config);
+        this.config = {
+            ...config,
+            environment: config.environment || this.detectEnvironment(),
+            mode: config.mode || 'redirect',
+        };
+        // Comprehensive environment security validation
+        validateEnvironmentSecurity(this.config.environment);
+        // Enforce HTTPS in production (additional layer)
+        enforceHTTPS(this.config.environment);
+        // Log initialization for security monitoring
+        logSecurityEvent('SDK_INITIALIZED', {
+            environment: this.config.environment,
+            mode: this.config.mode,
+            origin: window.location.origin,
+            protocol: window.location.protocol,
+            hostname: window.location.hostname,
+        });
+        // Set up automatic cleanup on page unload
+        this.setupAutoCleanup();
+    }
+    /**
+     * Initiate age verification with race condition protection
+     *
+     * Main verification method that handles session creation, security validation,
+     * and verification flow initiation. Includes race condition protection and
+     * comprehensive error handling.
+     *
+     * For public keys (pk_*), automatically creates sessions via the portal API.
+     * For private keys (sk_*), requires a pre-created sessionId.
+     *
+     * @param {VerificationOptions} [options={}] - Verification options
+     * @param {string} [options.sessionId] - Session ID (required for private keys)
+     * @param {number} [options.challengeAge] - Age challenge override
+     * @param {string} [options.verificationMode] - Verification mode override
+     * @param {string} [options.externalUserId] - External user identifier
+     * @returns {Promise<void>} Promise that resolves when verification is initiated
+     * @throws {Error} If verification cannot be started or is already in progress
+     */
+    async verify(options = {}) {
+        const isPublicKey = this.isPublicKey();
+        let sessionId = options.sessionId;
+        // For public keys, generate session internally if not provided
+        if (isPublicKey && !sessionId) {
+            sessionId = await this.createInternalSession(options);
+        }
+        // For private keys, sessionId is required
+        if (!isPublicKey && !sessionId) {
+            throw new Error('sessionId is required for private API keys - must be a merchant-generated UUID v4');
+        }
+        if (!sessionId) {
+            throw new Error('Failed to create or obtain sessionId');
+        }
+        // Race condition check - prevent multiple simultaneous verifications
+        if (this.isVerificationInProgress) {
+            const error = new Error(`Verification already in progress for session ${this.currentSessionId?.substring(0, 8)}...`);
+            logSecurityEvent('RACE_CONDITION_PREVENTED', {
+                currentSession: this.currentSessionId?.substring(0, 8) + '...',
+                attemptedSession: options.sessionId
+                    ? options.sessionId.substring(0, 8) + '...'
+                    : 'undefined',
+                origin: window.location.origin,
+            });
+            this.config.onError?.(error);
+            throw error;
+        }
+        // Lock verification process
+        this.isVerificationInProgress = true;
+        this.currentSessionId = sessionId;
+        try {
+            // Rate limiting check
+            const rateLimitKey = `${this.config.apiKey}:${window.location.origin}`;
+            if (!verificationRateLimit.isAllowed(rateLimitKey)) {
+                const error = new Error('Too many verification attempts. Please wait before trying again.');
+                logSecurityEvent('RATE_LIMIT_EXCEEDED', {
+                    apiKey: this.config.apiKey.substring(0, 8) + '...',
+                    origin: window.location.origin,
+                    sessionId: sessionId
+                        ? sessionId.substring(0, 8) + '...'
+                        : 'undefined',
+                });
+                this.config.onError?.(error);
+                throw error;
+            }
+            const verificationUrl = await this.buildVerificationUrl({
+                ...options,
+                sessionId,
+            });
+            // Log verification attempt
+            logSecurityEvent('VERIFICATION_INITIATED', {
+                environment: this.config.environment,
+                mode: this.config.mode,
+                sessionId: sessionId ? sessionId.substring(0, 8) + '...' : 'undefined',
+                origin: window.location.origin,
+            });
+            if (this.config.mode === 'new-tab') {
+                this.openNewTab(verificationUrl, sessionId);
+            }
+            else {
+                // For redirect mode, unlock immediately since we're leaving the page
+                this.unlockVerification();
+                this.redirect(verificationUrl);
+            }
+        }
+        catch (error) {
+            // Always unlock on error
+            this.unlockVerification();
+            throw error;
+        }
+    }
+    /**
+     * Build verification URL with HMAC-signed state
+     *
+     * Constructs the verification URL with signed state parameter containing
+     * all necessary configuration and security information. The state parameter
+     * includes HMAC signature for integrity protection.
+     *
+     * @param {VerificationOptions} options - Verification options
+     * @returns {Promise<string>} Complete verification URL
+     * @private
+     */
+    async buildVerificationUrl(options) {
+        const baseUrl = getEnvironmentUrl(this.config.environment);
+        // Determine if we have explicit overrides
+        const hasExplicitChallengeAge = options.challengeAge !== undefined;
+        const hasExplicitVerificationMode = options.verificationMode !== undefined;
+        const hasOverrides = hasExplicitChallengeAge || hasExplicitVerificationMode;
+        const state = await generateState({
+            merchantId: this.config.apiKey,
+            sessionId: options.sessionId,
+            returnUrl: this.config.returnUrl,
+            cancelUrl: this.config.cancelUrl,
+            challengeAge: options.challengeAge || this.config.defaultChallengeAge,
+            verificationMode: options.verificationMode || this.config.defaultVerificationMode,
+            hasOverrides: hasOverrides, // Flag to indicate explicit overrides
+            externalUserId: options.externalUserId,
+            timestamp: Date.now(),
+            // Phase 2: Include config for self-contained verify-ui
+            apiUrl: this.getPortalApiUrl(),
+            engineUrl: this.getEngineUrl(),
+            wsUrl: this.getWebSocketUrl(),
+            environment: this.config.environment,
+            features: {
+                captureMode: 'enhanced_verification',
+                testMode: false,
+                warmupPeriodMs: 2000,
+                qualityThreshold: 0.6,
+            },
+        }, this.config.environment);
+        const params = new URLSearchParams({
+            state,
+            sessionId: options.sessionId,
+            mode: this.config.mode,
+        });
+        return `${baseUrl}/?${params.toString()}`;
+    }
+    /**
+     * Redirect in same tab
+     *
+     * Performs a full page redirect to the verification URL.
+     * Used for redirect mode verification.
+     *
+     * @param {string} url - Verification URL to redirect to
+     * @private
+     */
+    redirect(url) {
+        window.location.href = url;
+    }
+    /**
+     * Open in new tab with PostMessage communication and proper cleanup
+     *
+     * Opens verification URL in a new tab/window and sets up secure PostMessage
+     * communication for receiving verification results. Includes comprehensive
+     * security validation and automatic cleanup.
+     *
+     * @param {string} url - Verification URL to open
+     * @param {string} sessionId - Session ID for result correlation
+     * @private
+     */
+    openNewTab(url, sessionId) {
+        // Clean up any existing resources
+        this.cleanup();
+        // Clear any existing popup monitor interval
+        if (this.popupMonitorInterval) {
+            clearInterval(this.popupMonitorInterval);
+            this.popupMonitorInterval = null;
+        }
+        // Open new tab
+        this.popupWindow = window.open(url, 'safepassage-verify', 'width=600,height=700');
+        if (!this.popupWindow) {
+            this.config.onError?.(new Error('Failed to open verification window. Please check popup blocker settings.'));
+            return;
+        }
+        // Set up PostMessage listener with enhanced security
+        this.messageListener = (event) => {
+            // Enhanced origin validation with strict allowlist
+            if (!validatePostMessageOrigin(event, this.config.environment)) {
+                logSecurityEvent('POSTMESSAGE_ORIGIN_BLOCKED', {
+                    origin: event.origin,
+                    environment: this.config.environment,
+                    expectedOrigins: `SafePassage trusted origins for ${this.config.environment}`,
+                    messageType: event.data?.type,
+                });
+                return;
+            }
+            // Enhanced message validation
+            const messageValidation = validateSafePassageMessage(event, sessionId);
+            if (!messageValidation.isValid) {
+                logSecurityEvent('POSTMESSAGE_VALIDATION_FAILED', {
+                    error: messageValidation.error,
+                    origin: event.origin,
+                    sessionId: sessionId.substring(0, 8) + '...',
+                    messageType: event.data?.type,
+                });
+                return;
+            }
+            const result = {
+                sessionId: event.data.sessionId,
+                status: event.data.status,
+            };
+            // Log successful verification completion
+            logSecurityEvent('VERIFICATION_COMPLETED', {
+                status: result.status,
+                sessionId: sessionId.substring(0, 8) + '...',
+                origin: event.origin,
+            });
+            // Clean up resources
+            this.cleanup();
+            // Unlock verification after successful completion
+            this.unlockVerification();
+            // Clear monitoring interval
+            if (this.popupMonitorInterval) {
+                clearInterval(this.popupMonitorInterval);
+                this.popupMonitorInterval = null;
+            }
+            // Trigger appropriate callback
+            if (result.status === 'verified') {
+                this.config.onComplete?.(result);
+            }
+            else if (result.status === 'cancelled') {
+                this.config.onCancel?.();
+            }
+            else {
+                this.config.onError?.(new Error(`Verification failed: ${result.status}`));
+            }
+        };
+        window.addEventListener('message', this.messageListener);
+        // Monitor popup window with proper cleanup
+        this.popupMonitorInterval = setInterval(() => {
+            if (this.popupWindow && this.popupWindow.closed) {
+                // Log popup closed event
+                logSecurityEvent('POPUP_CLOSED_BY_USER', {
+                    sessionId: sessionId.substring(0, 8) + '...',
+                    environment: this.config.environment,
+                });
+                // Clean up and trigger cancel callback
+                this.cleanup();
+                // Unlock verification after popup closed
+                this.unlockVerification();
+                this.config.onCancel?.();
+            }
+        }, 500);
+    }
+    /**
+     * Set up automatic cleanup on page unload to prevent memory leaks
+     *
+     * Registers event listeners for page unload events to ensure proper
+     * cleanup of resources and verification state. Handles both traditional
+     * page navigation and single-page application route changes.
+     *
+     * @private
+     */
+    setupAutoCleanup() {
+        this.unloadListener = () => {
+            // Log automatic cleanup
+            logSecurityEvent('SDK_AUTO_CLEANUP', {
+                environment: this.config.environment,
+                trigger: 'page_unload',
+            });
+            // Clean up all resources and unlock verification
+            this.cleanup();
+            this.unlockVerification();
+        };
+        // Listen for page unload events
+        window.addEventListener('beforeunload', this.unloadListener);
+        window.addEventListener('pagehide', this.unloadListener);
+        // For single-page applications, also listen for route changes
+        if (window.history && window.history.pushState) {
+            const originalPushState = window.history.pushState;
+            window.history.pushState = (...args) => {
+                this.cleanup();
+                this.unlockVerification();
+                return originalPushState.apply(window.history, args);
+            };
+        }
+    }
+    /**
+     * Auto-detect environment based on current URL
+     *
+     * Analyzes the current hostname to determine the appropriate environment
+     * configuration. Used when environment is not explicitly specified.
+     *
+     * @returns {'production' | 'staging' | 'development'} Detected environment
+     * @private
+     */
+    detectEnvironment() {
+        const hostname = window.location.hostname;
+        if (hostname === 'localhost' ||
+            hostname === '127.0.0.1' ||
+            hostname.includes('.local')) {
+            return 'development';
+        }
+        if (hostname.includes('staging') || hostname.includes('stage')) {
+            return 'staging';
+        }
+        return 'production';
+    }
+    /**
+     * Unlock verification process to allow new verifications
+     *
+     * Resets the verification lock state to allow new verification attempts.
+     * Called after successful completion, errors, or cleanup.
+     *
+     * @private
+     */
+    unlockVerification() {
+        this.isVerificationInProgress = false;
+        this.currentSessionId = null;
+        logSecurityEvent('VERIFICATION_UNLOCKED', {
+            environment: this.config.environment,
+            origin: window.location.origin,
+        });
+    }
+    /**
+     * Internal cleanup method to prevent memory leaks
+     *
+     * Cleans up popup windows, event listeners, and intervals.
+     * Does not unlock verification state - that's handled by specific callers.
+     *
+     * @private
+     */
+    cleanup() {
+        // Close popup window
+        if (this.popupWindow && !this.popupWindow.closed) {
+            this.popupWindow.close();
+        }
+        this.popupWindow = null;
+        // Remove message listener
+        if (this.messageListener) {
+            window.removeEventListener('message', this.messageListener);
+            this.messageListener = null;
+        }
+        // Clear monitoring interval
+        if (this.popupMonitorInterval) {
+            clearInterval(this.popupMonitorInterval);
+            this.popupMonitorInterval = null;
+        }
+        // Note: Verification unlocking is handled by specific callers
+    }
+    /**
+     * Remove auto-cleanup listeners
+     *
+     * Removes page unload event listeners that were set up for automatic cleanup.
+     *
+     * @private
+     */
+    removeAutoCleanupListeners() {
+        if (this.unloadListener) {
+            window.removeEventListener('beforeunload', this.unloadListener);
+            window.removeEventListener('pagehide', this.unloadListener);
+            this.unloadListener = null;
+        }
+    }
+    /**
+     * Public cleanup method for manual resource management
+     *
+     * Completely destroys the SDK instance, cleaning up all resources and
+     * removing all event listeners. Should be called when the SDK is no longer needed.
+     *
+     * @public
+     */
+    destroy() {
+        // Log destruction for security monitoring
+        logSecurityEvent('SDK_DESTROYED', {
+            environment: this.config.environment,
+            origin: window.location.origin,
+        });
+        // Clean up all resources
+        this.cleanup();
+        // Unlock verification
+        this.unlockVerification();
+        // Remove auto-cleanup listeners
+        this.removeAutoCleanupListeners();
+    }
+    /**
+     * Get Portal API URL based on environment
+     *
+     * Returns the appropriate portal-api URL for the current environment.
+     *
+     * @returns {string} Portal API URL
+     * @private
+     */
+    getPortalApiUrl() {
+        switch (this.config.environment) {
+            case 'development':
+                return 'http://localhost:3001';
+            case 'staging':
+            case 'production':
+                return 'https://api.safepassageapp.com';
+            default:
+                return 'https://api.safepassageapp.com';
+        }
+    }
+    /**
+     * Get Engine URL based on environment
+     *
+     * Returns the appropriate verify-engine URL for the current environment.
+     * In production, engine access is proxied through portal-api.
+     *
+     * @returns {string} Engine URL
+     * @private
+     */
+    getEngineUrl() {
+        switch (this.config.environment) {
+            case 'development':
+                return 'http://localhost:8000';
+            case 'staging':
+            case 'production':
+                // Direct access to verify-engine
+                return 'https://engine.safepassageapp.com';
+            default:
+                return 'https://engine.safepassageapp.com';
+        }
+    }
+    /**
+     * Get WebSocket URL based on environment
+     *
+     * Returns the appropriate WebSocket URL for the current environment.
+     * In production, WebSocket connections are proxied through portal-api.
+     *
+     * @returns {string} WebSocket URL
+     * @private
+     */
+    getWebSocketUrl() {
+        switch (this.config.environment) {
+            case 'development':
+                return 'ws://localhost:8000/safe-passage-llm/api/v1/websocket/stream';
+            case 'staging':
+            case 'production':
+                // Direct WebSocket connection to verify-engine
+                return 'wss://engine.safepassageapp.com/safe-passage-llm/api/v1/websocket/stream';
+            default:
+                return 'wss://engine.safepassageapp.com/safe-passage-llm/api/v1/websocket/stream';
+        }
+    }
+    /**
+     * Detect if this is a public key (pk_ prefix) vs private key (sk_ prefix)
+     *
+     * Determines API key type based on prefix to handle different authentication flows.
+     *
+     * @returns {boolean} True if public key, false if private key
+     * @private
+     */
+    isPublicKey() {
+        return this.config.apiKey.startsWith('pk_');
+    }
+    /**
+     * Create session internally for public keys
+     *
+     * Creates a verification session via the portal API for public key authentication.
+     * Generates a UUID session ID and submits session creation request with
+     * verification parameters.
+     *
+     * @param {VerificationOptions} options - Verification options
+     * @returns {Promise<string>} Created session ID
+     * @throws {Error} If session creation fails
+     * @private
+     */
+    async createInternalSession(options) {
+        const sessionId = crypto.randomUUID();
+        try {
+            const portalApiUrl = this.getPortalApiUrl();
+            const response = await fetch(`${portalApiUrl}/api/v1/sessions/create`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                },
+                body: JSON.stringify({
+                    merchantId: this.config.apiKey, // API expects merchantId even though it uses auth header
+                    sessionId,
+                    returnUrl: this.config.returnUrl,
+                    cancelUrl: this.config.cancelUrl,
+                    challengeAge: options.challengeAge,
+                    verificationMode: options.verificationMode,
+                    merchantName: document.title || window.location.hostname,
+                    externalUserId: options.externalUserId,
+                }),
+            });
+            if (!response.ok) {
+                const errorData = await response.json().catch(() => ({}));
+                throw new Error(`Failed to create session: ${response.status} ${response.statusText}. ${errorData.message || ''}`);
+            }
+            await response.json();
+            // Log successful session creation
+            logSecurityEvent('INTERNAL_SESSION_CREATED', {
+                sessionId: sessionId.substring(0, 8) + '...',
+                environment: this.config.environment,
+                apiKeyType: 'public',
+            });
+            return sessionId;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logSecurityEvent('INTERNAL_SESSION_FAILED', {
+                error: errorMessage,
+                environment: this.config.environment,
+                apiKeyType: 'public',
+            });
+            this.config.onError?.(error);
+            throw new Error(`Failed to create verification session: ${errorMessage}`);
+        }
+    }
+}
+// For backwards compatibility
+export default SafePassage;