@safepassage/sdk 3.0.3 → 3.0.4

package/dist/tests/SafePassageSDK.test.js

@@ -0,0 +1,130 @@
+/**
+ * Tests for SafePassage SDK
+ */
+import { SafePassage } from '../core/SafePassageSDK';
+describe('SafePassage SDK', () => {
+    let mockLocation;
+    let mockWindow;
+    beforeEach(() => {
+        // Mock window.location
+        mockLocation = {
+            href: 'https://merchant.com',
+            hostname: 'merchant.com',
+            origin: 'https://merchant.com'
+        };
+        // Mock window
+        mockWindow = {
+            location: mockLocation,
+            open: jest.fn(),
+            addEventListener: jest.fn(),
+            removeEventListener: jest.fn()
+        };
+        // Replace global window
+        global.window = mockWindow;
+    });
+    describe('constructor', () => {
+        it('should initialize with valid config', () => {
+            const config = {
+                apiKey: 'sk_test_123',
+                returnUrl: 'https://merchant.com/verified',
+                cancelUrl: 'https://merchant.com/cancelled'
+            };
+            const sp = new SafePassage(config);
+            expect(sp).toBeDefined();
+        });
+        it('should throw error for missing apiKey', () => {
+            const config = {
+                returnUrl: 'https://merchant.com/verified',
+                cancelUrl: 'https://merchant.com/cancelled'
+            };
+            expect(() => new SafePassage(config)).toThrow('apiKey is required');
+        });
+        it('should throw error for invalid apiKey format', () => {
+            const config = {
+                apiKey: 'invalid_key',
+                returnUrl: 'https://merchant.com/verified',
+                cancelUrl: 'https://merchant.com/cancelled'
+            };
+            expect(() => new SafePassage(config)).toThrow('Invalid apiKey format');
+        });
+        it('should throw error for missing returnUrl', () => {
+            const config = {
+                apiKey: 'sk_test_123',
+                cancelUrl: 'https://merchant.com/cancelled'
+            };
+            expect(() => new SafePassage(config)).toThrow('returnUrl is required');
+        });
+        it('should auto-detect development environment for localhost', () => {
+            mockLocation.hostname = 'localhost';
+            const config = {
+                apiKey: 'sk_test_123',
+                returnUrl: 'http://localhost:3000/verified',
+                cancelUrl: 'http://localhost:3000/cancelled'
+            };
+            const sp = new SafePassage(config);
+            expect(sp).toBeDefined();
+        });
+        it('should enforce minimum age of 25', () => {
+            const config = {
+                apiKey: 'sk_test_123',
+                returnUrl: 'https://merchant.com/verified',
+                cancelUrl: 'https://merchant.com/cancelled',
+                defaultChallengeAge: 21
+            };
+            expect(() => new SafePassage(config)).toThrow('defaultChallengeAge must be at least 25');
+        });
+    });
+    describe('verify', () => {
+        let sp;
+        beforeEach(() => {
+            const config = {
+                apiKey: 'sk_test_123',
+                returnUrl: 'https://merchant.com/verified',
+                cancelUrl: 'https://merchant.com/cancelled'
+            };
+            sp = new SafePassage(config);
+        });
+        it('should throw error for missing sessionId', () => {
+            expect(() => sp.verify({})).toThrow('sessionId is required');
+        });
+        it('should redirect in same-tab mode', () => {
+            const sessionId = '550e8400-e29b-41d4-a716-446655440000';
+            sp.verify({ sessionId });
+            expect(mockWindow.location.href).toContain('verify.safepassageapp.com');
+            expect(mockWindow.location.href).toContain(`sessionId=${sessionId}`);
+        });
+        it('should open new tab in new-tab mode', () => {
+            const config = {
+                apiKey: 'sk_test_123',
+                returnUrl: 'https://merchant.com/verified',
+                cancelUrl: 'https://merchant.com/cancelled',
+                mode: 'new-tab'
+            };
+            const sp = new SafePassage(config);
+            const sessionId = '550e8400-e29b-41d4-a716-446655440000';
+            sp.verify({ sessionId });
+            expect(mockWindow.open).toHaveBeenCalledWith(expect.stringContaining('verify.safepassageapp.com'), 'safepassage-verify', 'width=600,height=700');
+        });
+    });
+    describe('URL building', () => {
+        it('should build correct URL with all parameters', () => {
+            const config = {
+                apiKey: 'sk_test_123',
+                returnUrl: 'https://merchant.com/verified',
+                cancelUrl: 'https://merchant.com/cancelled',
+                environment: 'staging'
+            };
+            const sp = new SafePassage(config);
+            // Access private method for testing
+            const buildUrl = sp.buildVerificationUrl.bind(sp);
+            const url = buildUrl({
+                sessionId: '550e8400-e29b-41d4-a716-446655440000',
+                challengeAge: 30,
+                verificationMode: 'L2'
+            });
+            expect(url).toContain('verify-staging.safepassageapp.com');
+            expect(url).toContain('sessionId=550e8400-e29b-41d4-a716-446655440000');
+            expect(url).toContain('state=');
+        });
+    });
+});

package/dist/types/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * SafePassage SDK Type Definitions
+ */
+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';
+    /**
+     * External user identifier from merchant system
+     * Optional parameter that will be returned with verification results
+     * Useful for correlating SafePassage sessions with merchant user records
+     */
+    externalUserId?: string;
+}
+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';
+    /**
+     * External user identifier if provided during verification
+     */
+    externalUserId?: string;
+}
+export interface StatePayload {
+    merchantId: string;
+    sessionId: string;
+    returnUrl: string;
+    cancelUrl: string;
+    challengeAge?: number;
+    verificationMode?: 'L1' | 'L2';
+    hasOverrides?: boolean;
+    externalUserId?: string;
+    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;
+    externalUserId?: string;
+}

package/dist/types/index.js

@@ -0,0 +1,4 @@
+/**
+ * SafePassage SDK Type Definitions
+ */
+export {};

package/dist/utils/crypto.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Crypto utilities for SafePassage SDK - Browser compatible
+ */
+/**
+ * Generate HMAC-SHA256 signature using Web Crypto API
+ * Note: This is client-side HMAC, the secret is known to the client.
+ * For true security, verification should still happen server-side.
+ */
+export declare function generateHMAC(data: string, secret: string): Promise<string>;
+/**
+ * Verify HMAC-SHA256 signature using Web Crypto API
+ */
+export declare function verifyHMAC(data: string, signature: string, secret: string): Promise<boolean>;
+/**
+ * Generate a secure random token for client-side use
+ */
+export declare function generateSecureToken(length?: number): string;
+/**
+ * Environment-specific secret derivation
+ * In a real implementation, this would derive from environment variables
+ * For client-side use, this provides basic tamper resistance
+ */
+export declare function getSigningSecret(environment: 'production' | 'staging' | 'development'): string;
+/**
+ * Create signed state parameter with timestamp and integrity protection
+ */
+export declare function createSignedState(payload: any, environment: 'production' | 'staging' | 'development'): Promise<string>;
+/**
+ * Verify and parse signed state parameter
+ */
+export declare function parseSignedState(signedState: string, environment: 'production' | 'staging' | 'development', maxAge?: number): Promise<any | null>;

package/dist/utils/crypto.js

@@ -0,0 +1,128 @@
+/**
+ * Crypto utilities for SafePassage SDK - Browser compatible
+ */
+import { STATE_EXPIRY_MS } from './validation';
+/**
+ * Generate HMAC-SHA256 signature using Web Crypto API
+ * Note: This is client-side HMAC, the secret is known to the client.
+ * For true security, verification should still happen server-side.
+ */
+export async function generateHMAC(data, secret) {
+    // Encode the secret and data as Uint8Array
+    const encoder = new TextEncoder();
+    const keyData = encoder.encode(secret);
+    const dataBuffer = encoder.encode(data);
+    // Import the secret as a key
+    const key = await crypto.subtle.importKey('raw', keyData, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    // Generate the signature
+    const signature = await crypto.subtle.sign('HMAC', key, dataBuffer);
+    // Convert to hex string
+    return Array.from(new Uint8Array(signature))
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+/**
+ * Verify HMAC-SHA256 signature using Web Crypto API
+ */
+export async function verifyHMAC(data, signature, secret) {
+    try {
+        const expectedSignature = await generateHMAC(data, secret);
+        return constantTimeCompare(signature, expectedSignature);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Constant-time string comparison to prevent timing attacks
+ */
+function constantTimeCompare(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return result === 0;
+}
+/**
+ * Generate a secure random token for client-side use
+ */
+export function generateSecureToken(length = 32) {
+    const array = new Uint8Array(length);
+    crypto.getRandomValues(array);
+    return Array.from(array, b => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Environment-specific secret derivation
+ * In a real implementation, this would derive from environment variables
+ * For client-side use, this provides basic tamper resistance
+ */
+export function getSigningSecret(environment) {
+    // WARNING: Client-side secrets are NOT secure against determined attackers
+    // This is defense-in-depth only. Real security comes from server-side validation.
+    const baseSecrets = {
+        production: 'safepassage-prod-hmac-2025',
+        staging: 'safepassage-stage-hmac-2025',
+        development: 'safepassage-dev-hmac-2025'
+    };
+    return baseSecrets[environment];
+}
+/**
+ * Create signed state parameter with timestamp and integrity protection
+ */
+export async function createSignedState(payload, environment) {
+    // Add timestamp for freshness
+    const timestampedPayload = {
+        ...payload,
+        timestamp: Date.now(),
+        nonce: generateSecureToken(16) // Add nonce to prevent replay attacks
+    };
+    const dataString = JSON.stringify(timestampedPayload);
+    const secret = getSigningSecret(environment);
+    const signature = await generateHMAC(dataString, secret);
+    // Combine data and signature
+    const signedPayload = {
+        data: timestampedPayload,
+        signature
+    };
+    return btoa(JSON.stringify(signedPayload));
+}
+/**
+ * Verify and parse signed state parameter
+ */
+export async function parseSignedState(signedState, environment, maxAge = STATE_EXPIRY_MS) {
+    try {
+        const json = atob(signedState);
+        const signedPayload = JSON.parse(json);
+        if (!signedPayload.data || !signedPayload.signature) {
+            console.warn('SafePassage: Invalid signed state format');
+            return null;
+        }
+        const { data, signature } = signedPayload;
+        const dataString = JSON.stringify(data);
+        const secret = getSigningSecret(environment);
+        // Verify signature
+        const isValid = await verifyHMAC(dataString, signature, secret);
+        if (!isValid) {
+            console.warn('SafePassage: State signature verification failed');
+            return null;
+        }
+        // Check timestamp freshness
+        if (data.timestamp) {
+            const age = Date.now() - data.timestamp;
+            if (age > maxAge) {
+                console.warn('SafePassage: State parameter expired', { age, maxAge });
+                return null;
+            }
+        }
+        // Remove internal fields before returning
+        const { timestamp, nonce, ...payload } = data;
+        return payload;
+    }
+    catch (error) {
+        console.warn('SafePassage: Failed to parse signed state', error);
+        return null;
+    }
+}

package/dist/utils/environment.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Environment utilities for SafePassage SDK with security enforcement
+ */
+export declare function getEnvironmentUrl(environment: 'production' | 'staging' | 'development'): string;
+export declare function getApiUrl(environment: 'production' | 'staging' | 'development'): string;
+/**
+ * Detect environment with security warnings
+ */
+export declare function detectEnvironment(): 'production' | 'staging' | 'development';
+/**
+ * Validate environment configuration on startup
+ */
+export declare function validateEnvironmentSecurity(environment: 'production' | 'staging' | 'development'): void;

package/dist/utils/environment.js

@@ -0,0 +1,88 @@
+/**
+ * Environment utilities for SafePassage SDK with security enforcement
+ */
+const ENVIRONMENT_URLS = {
+    production: 'https://verify.safepassageapp.com',
+    staging: 'https://verify-staging.safepassageapp.com',
+    development: 'http://localhost:5173'
+};
+export function getEnvironmentUrl(environment) {
+    const url = ENVIRONMENT_URLS[environment];
+    // Security check: Ensure production/staging always use HTTPS
+    if ((environment === 'production' || environment === 'staging') && !url.startsWith('https://')) {
+        throw new Error(`HTTPS required for ${environment} environment`);
+    }
+    return url;
+}
+export function getApiUrl(environment) {
+    const apiUrls = {
+        production: 'https://api.safepassageapp.com',
+        staging: 'https://api-staging.safepassageapp.com',
+        development: 'http://localhost:3001'
+    };
+    const url = apiUrls[environment];
+    // Security check: Ensure production/staging always use HTTPS
+    if ((environment === 'production' || environment === 'staging') && !url.startsWith('https://')) {
+        throw new Error(`HTTPS required for API URLs in ${environment} environment`);
+    }
+    return url;
+}
+/**
+ * Detect environment with security warnings
+ */
+export function detectEnvironment() {
+    const hostname = window.location.hostname;
+    if (hostname === 'localhost' || hostname === '127.0.0.1' || hostname.includes('.local')) {
+        // Warn if using HTTP in development with non-localhost domains
+        if (window.location.protocol === 'http:' && !hostname.match(/^(localhost|127\.0\.0\.1)$/)) {
+            console.warn('SafePassage Security Warning: Using HTTP with non-localhost domain in development');
+        }
+        return 'development';
+    }
+    if (hostname.includes('staging') || hostname.includes('stage')) {
+        // Enforce HTTPS in staging
+        if (window.location.protocol !== 'https:') {
+            console.error('SafePassage Security Error: HTTPS required in staging environment');
+        }
+        return 'staging';
+    }
+    // Production environment - strict HTTPS enforcement
+    if (window.location.protocol !== 'https:') {
+        console.error('SafePassage Security Error: HTTPS required in production environment');
+    }
+    return 'production';
+}
+/**
+ * Validate environment configuration on startup
+ */
+export function validateEnvironmentSecurity(environment) {
+    // Check current page protocol
+    const isSecure = window.location.protocol === 'https:';
+    const hostname = window.location.hostname;
+    switch (environment) {
+        case 'production':
+            if (!isSecure) {
+                throw new Error('SafePassage requires HTTPS in production environment');
+            }
+            break;
+        case 'staging':
+            if (!isSecure) {
+                console.warn('SafePassage Warning: HTTPS strongly recommended in staging environment');
+            }
+            break;
+        case 'development':
+            const isLocalhost = hostname === 'localhost' || hostname === '127.0.0.1' || hostname.includes('.local');
+            if (!isSecure && !isLocalhost) {
+                console.warn('SafePassage Warning: HTTPS recommended for non-localhost development');
+            }
+            break;
+    }
+    // Validate environment URLs
+    try {
+        getEnvironmentUrl(environment);
+        getApiUrl(environment);
+    }
+    catch (error) {
+        throw new Error(`Environment configuration validation failed: ${error}`);
+    }
+}

package/dist/utils/polyfills.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Polyfills for browser compatibility
+ */
+/**
+ * Polyfill for crypto.randomUUID (not supported in older browsers)
+ * Generates a UUID v4 using crypto.getRandomValues
+ */
+export declare function setupPolyfills(): void;
+/**
+ * Check browser compatibility and warn about unsupported features
+ */
+export declare function checkBrowserCompatibility(): void;

package/dist/utils/polyfills.js

@@ -0,0 +1,66 @@
+/**
+ * Polyfills for browser compatibility
+ */
+/**
+ * Polyfill for crypto.randomUUID (not supported in older browsers)
+ * Generates a UUID v4 using crypto.getRandomValues
+ */
+export function setupPolyfills() {
+    // Polyfill crypto.randomUUID if not available
+    if (!crypto.randomUUID) {
+        crypto.randomUUID = function () {
+            // Generate 16 random bytes
+            const array = new Uint8Array(16);
+            crypto.getRandomValues(array);
+            // Set version (4) and variant bits
+            array[6] = (array[6] & 0x0f) | 0x40; // Version 4
+            array[8] = (array[8] & 0x3f) | 0x80; // Variant 10
+            // Convert to hex string with dashes
+            const hex = Array.from(array).map(b => b.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, 32)
+            ].join('-');
+        };
+    }
+    // Note: URLSearchParams is widely supported (IE 11 doesn't support it, but we're not targeting IE 11)
+    // If needed, a polyfill can be added here
+}
+/**
+ * Check browser compatibility and warn about unsupported features
+ */
+export function checkBrowserCompatibility() {
+    const warnings = [];
+    // Check for required features
+    if (!window.crypto || !window.crypto.getRandomValues) {
+        throw new Error('SafePassage SDK requires Web Crypto API support');
+    }
+    if (!window.crypto.subtle) {
+        throw new Error('SafePassage SDK requires Web Crypto subtle API for HMAC operations');
+    }
+    // Check for features that we can polyfill
+    if (!crypto.randomUUID) {
+        warnings.push('crypto.randomUUID not supported, using polyfill');
+    }
+    if (!window.URLSearchParams) {
+        warnings.push('URLSearchParams not supported, consider adding a polyfill for IE 11 support');
+    }
+    // Check for modern JavaScript features
+    try {
+        // Test optional chaining
+        const test = { a: { b: 1 } };
+        const result = test?.a?.b;
+        if (result !== 1)
+            throw new Error();
+    }
+    catch {
+        warnings.push('Optional chaining (?.) not supported, ensure transpilation for older browsers');
+    }
+    // Log warnings if any
+    if (warnings.length > 0) {
+        console.warn('SafePassage SDK Browser Compatibility:', warnings.join('; '));
+    }
+}

package/dist/utils/security.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Security utilities for SafePassage SDK
+ * Enhanced origin validation and security enforcement
+ */
+/**
+ * Validate if an origin is trusted for the given environment
+ */
+export declare function isOriginTrusted(origin: string, environment: 'production' | 'staging' | 'development'): boolean;
+/**
+ * Enhanced origin validation with logging and strict allowlist
+ */
+export declare function validatePostMessageOrigin(event: MessageEvent, environment: 'production' | 'staging' | 'development', allowedCustomOrigins?: string[]): boolean;
+/**
+ * Validate SafePassage message format and content
+ */
+export declare function validateSafePassageMessage(event: MessageEvent, expectedSessionId: string): {
+    isValid: boolean;
+    error?: string;
+};
+/**
+ * Enforce HTTPS in production environment
+ */
+export declare function enforceHTTPS(environment: 'production' | 'staging' | 'development'): void;
+/**
+ * Validate URL security for return/cancel URLs
+ */
+export declare function validateReturnUrl(url: string, environment: 'production' | 'staging' | 'development'): {
+    isValid: boolean;
+    error?: string;
+};
+/**
+ * Generate secure session ID with entropy validation
+ */
+export declare function generateSecureSessionId(): string;
+/**
+ * Rate limiting for verification attempts
+ */
+declare class VerificationRateLimit {
+    private attempts;
+    private readonly maxAttempts;
+    private readonly timeWindow;
+    isAllowed(identifier: string): boolean;
+    reset(identifier: string): void;
+}
+export declare const verificationRateLimit: VerificationRateLimit;
+/**
+ * Security event logging for monitoring
+ */
+export declare function logSecurityEvent(event: string, details: any): void;
+export {};