@safepassage/sdk 3.0.3 → 3.0.4

package/dist/utils/security.js

@@ -0,0 +1,208 @@
+/**
+ * Security utilities for SafePassage SDK
+ * Enhanced origin validation and security enforcement
+ */
+/**
+ * Trusted SafePassage origins for different environments
+ * These are the only origins allowed to send PostMessage events
+ */
+const TRUSTED_ORIGINS = {
+    production: [
+        'https://verify.safepassageapp.com',
+        'https://portal.safepassageapp.com',
+        'https://api.safepassageapp.com'
+    ],
+    staging: [
+        'https://verify-staging.safepassageapp.com',
+        'https://portal-staging.safepassageapp.com',
+        'https://api-staging.safepassageapp.com'
+    ],
+    development: [
+        'http://localhost:5173',
+        'http://localhost:3000',
+        'http://localhost:3001',
+        'http://localhost:3002',
+        'http://127.0.0.1:5173',
+        'http://127.0.0.1:3000',
+        'http://127.0.0.1:3001',
+        'http://127.0.0.1:3002'
+    ]
+};
+/**
+ * Validate if an origin is trusted for the given environment
+ */
+export function isOriginTrusted(origin, environment) {
+    const trustedOrigins = TRUSTED_ORIGINS[environment];
+    return trustedOrigins.includes(origin);
+}
+/**
+ * Enhanced origin validation with logging and strict allowlist
+ */
+export function validatePostMessageOrigin(event, environment, allowedCustomOrigins = []) {
+    const { origin } = event;
+    // Check against trusted SafePassage origins
+    if (isOriginTrusted(origin, environment)) {
+        return true;
+    }
+    // Check against custom allowed origins (for merchant websites)
+    if (allowedCustomOrigins.length > 0) {
+        const isCustomOriginAllowed = allowedCustomOrigins.some(allowedOrigin => {
+            // Support wildcard subdomains (e.g., "*.example.com")
+            if (allowedOrigin.startsWith('*.')) {
+                const domain = allowedOrigin.slice(2);
+                return origin.endsWith(`.${domain}`) || origin === `https://${domain}` || origin === `http://${domain}`;
+            }
+            return origin === allowedOrigin;
+        });
+        if (isCustomOriginAllowed) {
+            return true;
+        }
+    }
+    // Log security violation for debugging
+    console.warn(`SafePassage Security: Blocked PostMessage from untrusted origin: ${origin}`, {
+        environment,
+        trustedOrigins: TRUSTED_ORIGINS[environment],
+        allowedCustomOrigins,
+        eventType: event.data?.type
+    });
+    return false;
+}
+/**
+ * Validate SafePassage message format and content
+ */
+export function validateSafePassageMessage(event, expectedSessionId) {
+    const { data } = event;
+    // Check message format
+    if (!data || typeof data !== 'object') {
+        return { isValid: false, error: 'Invalid message format' };
+    }
+    // Check message type
+    if (data.type !== 'safepassage:verification:complete') {
+        return { isValid: false, error: 'Invalid message type' };
+    }
+    // Check session ID
+    if (!data.sessionId || data.sessionId !== expectedSessionId) {
+        return { isValid: false, error: 'Session ID mismatch' };
+    }
+    // Check status field
+    if (!data.status || !['verified', 'failed', 'cancelled'].includes(data.status)) {
+        return { isValid: false, error: 'Invalid status value' };
+    }
+    return { isValid: true };
+}
+/**
+ * Enforce HTTPS in production environment
+ */
+export function enforceHTTPS(environment) {
+    if (environment === 'production' && window.location.protocol !== 'https:') {
+        const httpsUrl = window.location.href.replace('http:', 'https:');
+        console.error('SafePassage Security: HTTPS required in production. Redirecting...', {
+            current: window.location.href,
+            redirect: httpsUrl
+        });
+        window.location.replace(httpsUrl);
+    }
+}
+/**
+ * Validate URL security for return/cancel URLs
+ */
+export function validateReturnUrl(url, environment) {
+    try {
+        const parsed = new URL(url);
+        // Production must use HTTPS
+        if (environment === 'production' && parsed.protocol !== 'https:') {
+            return { isValid: false, error: 'HTTPS required for return URLs in production' };
+        }
+        // Development allows HTTP localhost
+        if (environment === 'development') {
+            const isLocalhost = parsed.hostname === 'localhost' ||
+                parsed.hostname === '127.0.0.1' ||
+                parsed.hostname.endsWith('.local');
+            if (!isLocalhost && parsed.protocol !== 'https:') {
+                return { isValid: false, error: 'Non-localhost URLs must use HTTPS' };
+            }
+        }
+        // Staging should use HTTPS
+        if (environment === 'staging' && parsed.protocol !== 'https:') {
+            return { isValid: false, error: 'HTTPS required for return URLs in staging' };
+        }
+        // Block suspicious URLs
+        const suspiciousPatterns = [
+            /data:/i,
+            /javascript:/i,
+            /vbscript:/i,
+            /file:/i,
+            /ftp:/i
+        ];
+        for (const pattern of suspiciousPatterns) {
+            if (pattern.test(url)) {
+                return { isValid: false, error: 'Blocked suspicious URL scheme' };
+            }
+        }
+        return { isValid: true };
+    }
+    catch (error) {
+        return { isValid: false, error: 'Invalid URL format' };
+    }
+}
+/**
+ * Generate secure session ID with entropy validation
+ */
+export function generateSecureSessionId() {
+    // Use crypto.randomUUID if available (modern browsers)
+    if (crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    // Fallback to secure random generation
+    const array = new Uint8Array(16);
+    crypto.getRandomValues(array);
+    // Convert to UUID v4 format
+    const hex = Array.from(array).map(b => b.toString(16).padStart(2, '0')).join('');
+    return [
+        hex.slice(0, 8),
+        hex.slice(8, 12),
+        '4' + hex.slice(13, 16), // Version 4
+        ((parseInt(hex.slice(16, 17), 16) & 0x3) | 0x8).toString(16) + hex.slice(17, 20), // Variant
+        hex.slice(20, 32)
+    ].join('-');
+}
+/**
+ * Rate limiting for verification attempts
+ */
+class VerificationRateLimit {
+    constructor() {
+        this.attempts = new Map();
+        this.maxAttempts = 5;
+        this.timeWindow = 60000; // 1 minute
+    }
+    isAllowed(identifier) {
+        const now = Date.now();
+        const attempts = this.attempts.get(identifier) || [];
+        // Filter out old attempts
+        const recentAttempts = attempts.filter(time => now - time < this.timeWindow);
+        if (recentAttempts.length >= this.maxAttempts) {
+            console.warn(`SafePassage Security: Rate limit exceeded for ${identifier}`);
+            return false;
+        }
+        // Add current attempt
+        recentAttempts.push(now);
+        this.attempts.set(identifier, recentAttempts);
+        return true;
+    }
+    reset(identifier) {
+        this.attempts.delete(identifier);
+    }
+}
+export const verificationRateLimit = new VerificationRateLimit();
+/**
+ * Security event logging for monitoring
+ */
+export function logSecurityEvent(event, details) {
+    console.warn(`SafePassage Security Event: ${event}`, {
+        timestamp: new Date().toISOString(),
+        userAgent: navigator.userAgent,
+        url: window.location.href,
+        ...details
+    });
+    // In production, this could send events to a security monitoring service
+}

package/dist/utils/validation.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Validation utilities for SafePassage SDK
+ */
+import type { SafePassageConfig, StatePayload } from '../types';
+export declare const MINIMUM_AGE = 25;
+export declare const MAXIMUM_AGE = 150;
+export declare const MAX_URL_LENGTH = 2048;
+export declare const MAX_API_KEY_LENGTH = 128;
+export declare const STATE_EXPIRY_MS = 600000;
+export declare function validateConfig(config: SafePassageConfig): void;
+export declare function validateSessionId(sessionId: string): void;
+export declare function validateChallengeAge(age?: number): void;
+/**
+ * Generate signed state parameter with HMAC protection
+ * Uses client-side HMAC for tamper resistance and server-side verification
+ */
+export declare function generateState(payload: StatePayload, environment: 'production' | 'staging' | 'development'): Promise<string>;
+/**
+ * Parse and validate signed state parameter
+ */
+export declare function parseState(state: string, environment: 'production' | 'staging' | 'development'): Promise<StatePayload | null>;

package/dist/utils/validation.js

@@ -0,0 +1,147 @@
+/**
+ * Validation utilities for SafePassage SDK
+ */
+import { validateReturnUrl } from './security';
+export const MINIMUM_AGE = 25;
+export const MAXIMUM_AGE = 150;
+export const MAX_URL_LENGTH = 2048;
+export const MAX_API_KEY_LENGTH = 128;
+export const STATE_EXPIRY_MS = 600000; // 10 minutes
+// SafePassage supports both public (pk_) and private (sk_) API keys
+const API_KEY_PATTERN = /^(pk_|sk_)[a-zA-Z0-9]+$/;
+const UUID_V4_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export function validateConfig(config) {
+    if (!config.apiKey) {
+        throw new Error('apiKey is required');
+    }
+    if (config.apiKey.length > MAX_API_KEY_LENGTH) {
+        throw new Error(`apiKey exceeds maximum length of ${MAX_API_KEY_LENGTH} characters`);
+    }
+    if (!API_KEY_PATTERN.test(config.apiKey)) {
+        throw new Error('Invalid apiKey format. Expected pk_xxx (public) or sk_xxx (private)');
+    }
+    // Prevent Secret Keys from being used in browser code
+    if (typeof window !== 'undefined' && config.apiKey.startsWith('sk_')) {
+        throw new Error('Secret keys (sk_) should never be used in browser code for security reasons. ' +
+            'Secret keys expose your account to unauthorized access if used client-side. ' +
+            'Please use your public key (pk_) instead. ' +
+            'If you need to use features that require a secret key (like custom challenge age), ' +
+            'create the session server-side and pass the sessionId to startVerificationWithSession(). ' +
+            'See: https://docs.safepassageapp.com/server-side-sessions');
+    }
+    if (!config.returnUrl) {
+        throw new Error('returnUrl is required');
+    }
+    if (config.returnUrl.length > MAX_URL_LENGTH) {
+        throw new Error(`returnUrl exceeds maximum length of ${MAX_URL_LENGTH} characters`);
+    }
+    if (!config.cancelUrl) {
+        throw new Error('cancelUrl is required');
+    }
+    if (config.cancelUrl.length > MAX_URL_LENGTH) {
+        throw new Error(`cancelUrl exceeds maximum length of ${MAX_URL_LENGTH} characters`);
+    }
+    // Enhanced URL validation with security checks
+    const environment = detectEnvironment();
+    const returnUrlValidation = validateReturnUrl(config.returnUrl, environment);
+    if (!returnUrlValidation.isValid) {
+        throw new Error(`returnUrl validation failed: ${returnUrlValidation.error}`);
+    }
+    const cancelUrlValidation = validateReturnUrl(config.cancelUrl, environment);
+    if (!cancelUrlValidation.isValid) {
+        throw new Error(`cancelUrl validation failed: ${cancelUrlValidation.error}`);
+    }
+    if (config.defaultChallengeAge !== undefined) {
+        if (config.defaultChallengeAge < MINIMUM_AGE) {
+            throw new Error(`defaultChallengeAge must be at least ${MINIMUM_AGE}`);
+        }
+        if (config.defaultChallengeAge > MAXIMUM_AGE) {
+            throw new Error(`defaultChallengeAge cannot exceed ${MAXIMUM_AGE}`);
+        }
+    }
+    if (config.defaultVerificationMode && !['L1', 'L2'].includes(config.defaultVerificationMode)) {
+        throw new Error('defaultVerificationMode must be L1 or L2');
+    }
+    if (config.mode && !['redirect', 'new-tab'].includes(config.mode)) {
+        throw new Error('mode must be redirect or new-tab');
+    }
+}
+/**
+ * Detect environment based on current URL
+ */
+function 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';
+}
+export function validateSessionId(sessionId) {
+    if (!sessionId) {
+        throw new Error('sessionId is required');
+    }
+    if (!UUID_V4_PATTERN.test(sessionId)) {
+        throw new Error('sessionId must be a valid UUID v4');
+    }
+}
+export function validateChallengeAge(age) {
+    if (age !== undefined) {
+        if (age < MINIMUM_AGE) {
+            throw new Error(`challengeAge must be at least ${MINIMUM_AGE}`);
+        }
+        if (age > MAXIMUM_AGE) {
+            throw new Error(`challengeAge cannot exceed ${MAXIMUM_AGE}`);
+        }
+    }
+}
+// URL validation now handled by security.ts validateReturnUrl function
+/**
+ * Generate signed state parameter with HMAC protection
+ * Uses client-side HMAC for tamper resistance and server-side verification
+ */
+export async function generateState(payload, environment) {
+    // Import crypto utilities
+    const { createSignedState } = await import('./crypto');
+    return createSignedState(payload, environment);
+}
+/**
+ * Parse and validate signed state parameter
+ */
+export async function parseState(state, environment) {
+    try {
+        // Import crypto utilities
+        const { parseSignedState } = await import('./crypto');
+        // Try parsing as signed state first (new format)
+        const signedPayload = await parseSignedState(state, environment);
+        if (signedPayload) {
+            // Validate payload structure
+            if (!signedPayload.merchantId || !signedPayload.sessionId ||
+                !signedPayload.returnUrl || !signedPayload.cancelUrl) {
+                return null;
+            }
+            return signedPayload;
+        }
+        // Fallback to legacy base64 format for backwards compatibility
+        console.warn('SafePassage: Falling back to legacy state format - update your SDK');
+        const json = atob(state);
+        const payload = JSON.parse(json);
+        // Validate payload structure
+        if (!payload.merchantId || !payload.sessionId || !payload.returnUrl || !payload.cancelUrl) {
+            return null;
+        }
+        // Check timestamp expiration
+        const age = Date.now() - payload.timestamp;
+        if (age > STATE_EXPIRY_MS) {
+            console.warn('SafePassage: State parameter expired', { age, maxAge: STATE_EXPIRY_MS });
+            return null;
+        }
+        return payload;
+    }
+    catch (error) {
+        console.warn('SafePassage: Failed to parse state parameter', error);
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@safepassage/sdk",
-  "version": "3.0.3",
+  "version": "3.0.4",
   "description": "SafePassage SDK - Lightweight redirect-based age verification",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/dist/components/SafePassageVerification.d.ts

@@ -1,4 +0,0 @@
-import React from 'react';
-import type { SafePassageOptions } from '../types';
-declare const SafePassageVerification: React.FC<SafePassageOptions>;
-export default SafePassageVerification;

package/dist/components/SafePassageVerification.js

@@ -1,196 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useSafePassage } from '../hooks/useSafePassage';
-const SafePassageVerification = ({ wsUrl, mode = 'enhanced_verification', maxReconnectAttempts = 5, reconnectDelay = 3000, frameRate = 10, imageQuality = 0.8, config_overrides, onSuccess, onFailure, onStateChange, customMessages, className = '', style = {} }) => {
-    const { error, feedback, processingStep, zoneTransition, qualityScore, videoRef, canvasRef, isSessionStarted } = useSafePassage({
-        wsUrl,
-        mode,
-        maxReconnectAttempts,
-        reconnectDelay,
-        frameRate,
-        imageQuality,
-        config_overrides
-    }, {
-        onSuccess,
-        onFailure,
-        onStateChange
-    }, customMessages);
-    const getDisplayMessage = () => {
-        if (zoneTransition) {
-            return zoneTransition.message;
-        }
-        if (feedback && !processingStep) {
-            return feedback;
-        }
-        if (processingStep) {
-            return processingStep;
-        }
-        if (!isSessionStarted) {
-            return 'Starting camera...';
-        }
-        return 'Position your face in the camera and look forward';
-    };
-    const getMessageClass = () => {
-        if (zoneTransition)
-            return 'safepassage-instruction-zone-transition';
-        if (feedback && !processingStep)
-            return 'safepassage-instruction-feedback';
-        if (processingStep)
-            return 'safepassage-instruction-processing';
-        return 'safepassage-instruction-default';
-    };
-    // Calculate glow intensity based on quality score and feedback
-    const getGlowIntensity = () => {
-        // Base glow on quality score (0-1)
-        let intensity = qualityScore;
-        // Boost intensity for positive feedback (both generic and zone-specific)
-        if (feedback === 'good_position' ||
-            feedback === 'good_wide_position' ||
-            feedback === 'good_close_position') {
-            intensity = Math.max(intensity, 0.9);
-        }
-        // Medium intensity for zone positioning messages
-        if (feedback === 'position_at_comfortable_distance' ||
-            feedback === 'move_closer_to_camera') {
-            intensity = Math.max(intensity, 0.6);
-        }
-        // Reduce intensity for negative feedback
-        if (feedback === 'no_face_detected' ||
-            feedback === 'move_closer' ||
-            feedback === 'move_further' ||
-            feedback === 'center_face' ||
-            feedback === 'improve_lighting') {
-            intensity = Math.min(intensity, 0.3);
-        }
-        // Special handling for zone transitions - pulse effect
-        if (zoneTransition) {
-            intensity = Math.max(intensity, 0.7);
-        }
-        // Clamp between 0 and 1
-        return Math.max(0, Math.min(1, intensity));
-    };
-    const glowIntensity = getGlowIntensity();
-    return (_jsxs("div", { className: `safepassage-verification-container ${className}`, style: style, children: [_jsxs("div", { className: "safepassage-video-container", children: [_jsx("video", { ref: videoRef, autoPlay: true, playsInline: true, className: "safepassage-verification-video" }), _jsx("div", { className: "safepassage-video-overlay", children: _jsx("div", { className: "safepassage-oval-frame", style: {
-                                '--glow-intensity': glowIntensity,
-                                '--glow-opacity': glowIntensity > 0.1 ? glowIntensity : 0
-                            } }) })] }), _jsx("div", { className: "safepassage-instructions-area", children: _jsx("div", { className: `safepassage-instruction-text ${getMessageClass()}`, children: getDisplayMessage() }) }), _jsx("canvas", { ref: canvasRef, style: { display: 'none' } }), error && (_jsx("div", { className: "safepassage-error-message", children: error })), _jsx("style", { children: `
-        .safepassage-verification-container {
-          display: flex;
-          flex-direction: column;
-          align-items: center;
-          justify-content: center;
-          width: 100%;
-          min-height: 100vh;
-          margin: 0;
-          padding: 40px 20px;
-          text-align: center;
-          background-color: #2a2a2a;
-          position: fixed;
-          top: 0;
-          left: 0;
-          right: 0;
-          bottom: 0;
-        }
-        
-        .safepassage-video-container {
-          position: relative;
-          width: 320px;
-          height: 320px;
-          margin-bottom: 40px;
-        }
-        
-        .safepassage-verification-video {
-          width: 100%;
-          height: 100%;
-          object-fit: cover;
-          border-radius: 50%;
-          background-color: #000;
-        }
-        
-        .safepassage-video-overlay {
-          position: absolute;
-          top: 0;
-          left: 0;
-          width: 100%;
-          height: 100%;
-          pointer-events: none;
-        }
-        
-        .safepassage-oval-frame {
-          width: 100%;
-          height: 100%;
-          border: 3px solid #ffffff;
-          border-radius: 50%;
-          box-shadow: 
-            0 0 20px rgba(255, 255, 255, 0.3),
-            0 0 calc(30px * var(--glow-intensity, 0)) rgba(34, 197, 94, calc(var(--glow-opacity, 0) * 0.8)),
-            0 0 calc(50px * var(--glow-intensity, 0)) rgba(34, 197, 94, calc(var(--glow-opacity, 0) * 0.4)),
-            0 0 calc(80px * var(--glow-intensity, 0)) rgba(34, 197, 94, calc(var(--glow-opacity, 0) * 0.2));
-          transition: box-shadow 0.3s ease-out;
-        }
-        
-        .safepassage-instructions-area {
-          width: 100%;
-          max-width: 400px;
-        }
-        
-        .safepassage-instruction-text {
-          font-size: 18px;
-          font-weight: 500;
-          color: #ffffff;
-          text-align: center;
-          line-height: 1.4;
-          min-height: 50px;
-          display: flex;
-          align-items: center;
-          justify-content: center;
-        }
-        
-        .safepassage-instruction-zone-transition {
-          color: #4fc3f7;
-          font-weight: 600;
-          animation: safepassage-pulse 0.5s ease-in-out;
-        }
-        
-        .safepassage-instruction-feedback {
-          color: #ffffff;
-        }
-        
-        .safepassage-instruction-processing {
-          color: #81c784;
-        }
-        
-        .safepassage-instruction-default {
-          color: #ffffff;
-          opacity: 0.9;
-        }
-        
-        .safepassage-error-message {
-          color: #e53e3e;
-          margin-top: 10px;
-        }
-        
-        @keyframes safepassage-pulse {
-          0% { opacity: 0.7; transform: scale(1); }
-          50% { opacity: 1; transform: scale(1.02); }
-          100% { opacity: 0.9; transform: scale(1); }
-        }
-        
-        @media (max-width: 480px) {
-          .safepassage-verification-container {
-            padding: 20px 15px;
-          }
-          
-          .safepassage-video-container {
-            width: 280px;
-            height: 280px;
-            margin-bottom: 30px;
-          }
-          
-          .safepassage-instruction-text {
-            font-size: 16px;
-            min-height: 45px;
-          }
-        }
-      ` })] }));
-};
-export default SafePassageVerification;