@safepassage/sdk 3.0.4 → 3.0.5

package/dist/core/SafePassageSDK.js

@@ -1,11 +1,57 @@
 /**
  * SafePassage SDK - Redirect-based age verification
- * Lightweight SDK for integrating SafePassage age verification using redirect flow
+ *
+ * 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';
+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;
@@ -17,7 +63,7 @@ export class SafePassage {
         this.config = {
             ...config,
             environment: config.environment || this.detectEnvironment(),
-            mode: config.mode || 'redirect'
+            mode: config.mode || 'redirect',
         };
         // Comprehensive environment security validation
         validateEnvironmentSecurity(this.config.environment);
@@ -29,13 +75,28 @@ export class SafePassage {
             mode: this.config.mode,
             origin: window.location.origin,
             protocol: window.location.protocol,
-            hostname: window.location.hostname
+            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();
@@ -56,8 +117,10 @@ export class SafePassage {
             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
+                attemptedSession: options.sessionId
+                    ? options.sessionId.substring(0, 8) + '...'
+                    : 'undefined',
+                origin: window.location.origin,
             });
             this.config.onError?.(error);
             throw error;
@@ -73,18 +136,23 @@ export class SafePassage {
                 logSecurityEvent('RATE_LIMIT_EXCEEDED', {
                     apiKey: this.config.apiKey.substring(0, 8) + '...',
                     origin: window.location.origin,
-                    sessionId: sessionId ? sessionId.substring(0, 8) + '...' : 'undefined'
+                    sessionId: sessionId
+                        ? sessionId.substring(0, 8) + '...'
+                        : 'undefined',
                 });
                 this.config.onError?.(error);
                 throw error;
             }
-            const verificationUrl = await this.buildVerificationUrl({ ...options, sessionId });
+            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
+                origin: window.location.origin,
             });
             if (this.config.mode === 'new-tab') {
                 this.openNewTab(verificationUrl, sessionId);
@@ -103,6 +171,14 @@ export class SafePassage {
     }
     /**
      * 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);
@@ -119,23 +195,48 @@ export class SafePassage {
             verificationMode: options.verificationMode || this.config.defaultVerificationMode,
             hasOverrides: hasOverrides, // Flag to indicate explicit overrides
             externalUserId: options.externalUserId,
-            timestamp: Date.now()
+            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
+            mode: this.config.mode,
         });
-        return `${baseUrl}/verify?${params.toString()}`;
+        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
@@ -159,7 +260,7 @@ export class SafePassage {
                     origin: event.origin,
                     environment: this.config.environment,
                     expectedOrigins: `SafePassage trusted origins for ${this.config.environment}`,
-                    messageType: event.data?.type
+                    messageType: event.data?.type,
                 });
                 return;
             }
@@ -170,19 +271,19 @@ export class SafePassage {
                     error: messageValidation.error,
                     origin: event.origin,
                     sessionId: sessionId.substring(0, 8) + '...',
-                    messageType: event.data?.type
+                    messageType: event.data?.type,
                 });
                 return;
             }
             const result = {
                 sessionId: event.data.sessionId,
-                status: event.data.status
+                status: event.data.status,
             };
             // Log successful verification completion
             logSecurityEvent('VERIFICATION_COMPLETED', {
                 status: result.status,
                 sessionId: sessionId.substring(0, 8) + '...',
-                origin: event.origin
+                origin: event.origin,
             });
             // Clean up resources
             this.cleanup();
@@ -211,7 +312,7 @@ export class SafePassage {
                 // Log popup closed event
                 logSecurityEvent('POPUP_CLOSED_BY_USER', {
                     sessionId: sessionId.substring(0, 8) + '...',
-                    environment: this.config.environment
+                    environment: this.config.environment,
                 });
                 // Clean up and trigger cancel callback
                 this.cleanup();
@@ -223,13 +324,19 @@ export class SafePassage {
     }
     /**
      * 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'
+                trigger: 'page_unload',
             });
             // Clean up all resources and unlock verification
             this.cleanup();
@@ -250,10 +357,18 @@ export class SafePassage {
     }
     /**
      * 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')) {
+        if (hostname === 'localhost' ||
+            hostname === '127.0.0.1' ||
+            hostname.includes('.local')) {
             return 'development';
         }
         if (hostname.includes('staging') || hostname.includes('stage')) {
@@ -263,17 +378,27 @@ export class SafePassage {
     }
     /**
      * 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
+            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
@@ -295,6 +420,10 @@ export class SafePassage {
     }
     /**
      * Remove auto-cleanup listeners
+     *
+     * Removes page unload event listeners that were set up for automatic cleanup.
+     *
+     * @private
      */
     removeAutoCleanupListeners() {
         if (this.unloadListener) {
@@ -305,12 +434,17 @@ export class SafePassage {
     }
     /**
      * 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
+            origin: window.location.origin,
         });
         // Clean up all resources
         this.cleanup();
@@ -319,14 +453,89 @@ export class SafePassage {
         // 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();
@@ -336,7 +545,7 @@ export class SafePassage {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',
-                    'Authorization': `Bearer ${this.config.apiKey}`
+                    Authorization: `Bearer ${this.config.apiKey}`,
                 },
                 body: JSON.stringify({
                     merchantId: this.config.apiKey, // API expects merchantId even though it uses auth header
@@ -346,19 +555,19 @@ export class SafePassage {
                     challengeAge: options.challengeAge,
                     verificationMode: options.verificationMode,
                     merchantName: document.title || window.location.hostname,
-                    externalUserId: options.externalUserId
-                })
+                    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 || ''}`);
             }
-            const sessionData = await response.json();
+            await response.json();
             // Log successful session creation
             logSecurityEvent('INTERNAL_SESSION_CREATED', {
                 sessionId: sessionId.substring(0, 8) + '...',
                 environment: this.config.environment,
-                apiKeyType: 'public'
+                apiKeyType: 'public',
             });
             return sessionId;
         }
@@ -367,26 +576,12 @@ export class SafePassage {
             logSecurityEvent('INTERNAL_SESSION_FAILED', {
                 error: errorMessage,
                 environment: this.config.environment,
-                apiKeyType: 'public'
+                apiKeyType: 'public',
             });
             this.config.onError?.(error);
             throw new Error(`Failed to create verification session: ${errorMessage}`);
         }
     }
-    /**
-     * Get portal API URL based on environment
-     */
-    getPortalApiUrl() {
-        switch (this.config.environment) {
-            case 'production':
-                return 'https://api.safepassageapp.com';
-            case 'staging':
-                return 'https://api-staging.safepassageapp.com';
-            case 'development':
-            default:
-                return 'http://localhost:3001';
-        }
-    }
 }
 // For backwards compatibility
 export default SafePassage;

package/dist/index.d.ts

@@ -1,117 +1,21 @@
 /**
- * SafePassage SDK Type Definitions
+ * SafePassage SDK - Redirect-based age verification
+ *
+ * @example
+ * ```javascript
+ * // Initialize SDK
+ * const sp = new SafePassage({
+ *   apiKey: 'pk_live_xxxxx',
+ *   returnUrl: 'https://merchant.com/verified',
+ *   cancelUrl: 'https://merchant.com/cancelled'
+ * });
+ *
+ * // Trigger verification
+ * sp.verify({
+ *   sessionId: generateUUID() // Merchant-generated UUID v4
+ * });
+ * ```
  */
-export interface SafePassageConfig {
-    /**
-     * Public API key (starts with pk_live_ or pk_test_)
-     */
-    apiKey: string;
-    /**
-     * URL to redirect to after successful verification
-     * Must be pre-registered in dashboard
-     */
-    returnUrl: string;
-    /**
-     * URL to redirect to if user cancels verification
-     * Must be pre-registered in dashboard
-     */
-    cancelUrl: string;
-    /**
-     * Environment to use
-     * @default Auto-detected based on hostname
-     */
-    environment?: 'production' | 'staging' | 'development';
-    /**
-     * Verification mode
-     * @default 'redirect'
-     */
-    mode?: 'redirect' | 'new-tab';
-    /**
-     * Default challenge age (minimum 25)
-     * Can be overridden per verification
-     */
-    defaultChallengeAge?: number;
-    /**
-     * Default verification mode
-     * Can be overridden per verification
-     */
-    defaultVerificationMode?: 'L1' | 'L2';
-    /**
-     * Callback when verification completes (new-tab mode only)
-     */
-    onComplete?: (result: VerificationResult) => void;
-    /**
-     * Callback when user cancels (new-tab mode only)
-     */
-    onCancel?: () => void;
-    /**
-     * Callback for errors
-     */
-    onError?: (error: Error) => void;
-}
-export interface VerificationOptions {
-    /**
-     * Merchant-generated UUID v4 for this verification session
-     * Required for private keys (sk_), optional for public keys (pk_)
-     * For public keys: SDK will generate session internally
-     */
-    sessionId?: string;
-    /**
-     * Minimum age to verify (minimum 25)
-     * @default Uses merchant dashboard configuration
-     */
-    challengeAge?: number;
-    /**
-     * Verification mode
-     * L1: Age estimation allowed if user appears older
-     * L2: Full ID verification required
-     * @default Uses merchant dashboard configuration
-     */
-    verificationMode?: 'L1' | 'L2';
-}
-export interface VerificationResult {
-    /**
-     * The session ID that was verified
-     */
-    sessionId: string;
-    /**
-     * Binary result: 'verified' or 'failed'
-     * Full details available via server-side API
-     */
-    status: 'verified' | 'failed' | 'cancelled';
-}
-export interface StatePayload {
-    merchantId: string;
-    sessionId: string;
-    returnUrl: string;
-    cancelUrl: string;
-    challengeAge?: number;
-    verificationMode?: 'L1' | 'L2';
-    hasOverrides?: boolean;
-    timestamp: number;
-}
-export interface SessionValidationResponse {
-    sessionId: string;
-    merchantId: string;
-    status: 'verified' | 'failed';
-    verified: boolean;
-    estimatedAge?: number;
-    challengeAge: number;
-    verificationMode: 'L1' | 'L2';
-    verificationMethod?: 'facial' | 'document' | 'combined';
-    timestamp: string;
-    expiresAt: string;
-}
-export interface SessionCreationResponse {
-    sessionToken: string;
-    verifyUrl: string;
-    expiresAt: string;
-}
-export interface CreateSessionRequest {
-    sessionId: string;
-    returnUrl: string;
-    cancelUrl?: string;
-    challengeAge?: number;
-    verificationMode?: 'L1' | 'L2';
-    merchantName?: string;
-}
+export { SafePassage, SafePassage as default } from './core/SafePassageSDK';
+export type { SafePassageConfig, VerificationOptions, VerificationResult, SessionValidationResponse, } from './types';
+export declare const VERSION = "3.0.4";

package/dist/index.js

@@ -28,7 +28,13 @@ export { SafePassage, SafePassage as default } from './core/SafePassageSDK';
 export const VERSION = '3.0.4';
 // For UMD builds
 if (typeof window !== 'undefined' && window) {
+    // Dynamic import for UMD builds
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
     const { SafePassage } = require('./core/SafePassageSDK');
-    window.SafePassage = SafePassage;
-    window.SafePassage.VERSION = VERSION;
+    // Attach to window object for global access
+    const globalWindow = window;
+    globalWindow.SafePassage = SafePassage;
+    if (globalWindow.SafePassage) {
+        globalWindow.SafePassage.VERSION = VERSION;
+    }
 }