@glideidentity/web-client-sdk 5.1.3 → 6.0.0-beta.2

package/dist/esm/client/logger.js

@@ -0,0 +1,131 @@
+/**
+ * Logger for Phone Authentication SDK.
+ *
+ * Provides a simple console-based logger with:
+ * - Debug mode toggle
+ * - PII sanitization
+ * - Configurable prefix
+ */
+// ============================================================================
+// PII SANITIZATION
+// ============================================================================
+/**
+ * Patterns to detect and sanitize PII.
+ */
+const PII_PATTERNS = {
+    // Phone numbers: +1234567890 or variations
+    phone: /(\+?[1-9]\d{6,14})/g,
+    // Email addresses
+    email: /([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})/g,
+    // JWT tokens (three base64 segments separated by dots)
+    jwt: /(eyJ[a-zA-Z0-9_-]*\.eyJ[a-zA-Z0-9_-]*\.[a-zA-Z0-9_-]*)/g,
+    // Session keys (long alphanumeric strings)
+    sessionKey: /session[_-]?key["']?\s*[:=]\s*["']?([a-zA-Z0-9_-]{20,})["']?/gi,
+};
+/**
+ * Sanitize data to remove PII before logging.
+ */
+function sanitize(data) {
+    if (data === null || data === undefined) {
+        return data;
+    }
+    if (typeof data === 'string') {
+        let sanitized = data;
+        // Mask phone numbers: +1234567890 -> +1***7890
+        sanitized = sanitized.replace(PII_PATTERNS.phone, (match) => {
+            if (match.length < 8)
+                return match; // Too short to be a phone
+            const visible = 4;
+            return match.slice(0, 2) + '***' + match.slice(-visible);
+        });
+        // Mask emails: user@example.com -> u***@example.com
+        sanitized = sanitized.replace(PII_PATTERNS.email, (match) => {
+            const [local, domain] = match.split('@');
+            return local.slice(0, 1) + '***@' + domain;
+        });
+        // Mask JWTs: eyJ... -> [JWT]
+        sanitized = sanitized.replace(PII_PATTERNS.jwt, '[JWT]');
+        // Mask session keys
+        sanitized = sanitized.replace(PII_PATTERNS.sessionKey, (match, key) => {
+            return match.replace(key, key.slice(0, 4) + '***' + key.slice(-4));
+        });
+        return sanitized;
+    }
+    if (Array.isArray(data)) {
+        return data.map(sanitize);
+    }
+    if (typeof data === 'object') {
+        const sanitized = {};
+        for (const [key, value] of Object.entries(data)) {
+            // Completely mask sensitive field values
+            const sensitiveFields = ['phone_number', 'phoneNumber', 'credential', 'token', 'password', 'secret'];
+            if (sensitiveFields.some(f => key.toLowerCase().includes(f.toLowerCase()))) {
+                sanitized[key] = typeof value === 'string' ? '[REDACTED]' : value;
+            }
+            else {
+                sanitized[key] = sanitize(value);
+            }
+        }
+        return sanitized;
+    }
+    return data;
+}
+// ============================================================================
+// LOGGER IMPLEMENTATION
+// ============================================================================
+/**
+ * Create a logger instance.
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ debug: true });
+ * logger.debug('Preparing request', { use_case: 'GetPhoneNumber' });
+ * logger.error('Request failed', { code: 'NETWORK_ERROR' });
+ * ```
+ */
+export function createLogger(config = {}) {
+    const { debug = false, prefix = '[PhoneAuth]' } = config;
+    /**
+     * Format a log message.
+     */
+    function format(message, data) {
+        const formattedMessage = `${prefix} ${message}`;
+        if (data !== undefined) {
+            const sanitizedData = sanitize(data);
+            return [formattedMessage, sanitizedData];
+        }
+        return [formattedMessage];
+    }
+    return {
+        debug(message, data) {
+            if (debug) {
+                const args = format(message, data);
+                console.debug(...args);
+            }
+        },
+        info(message, data) {
+            const args = format(message, data);
+            console.info(...args);
+        },
+        warn(message, data) {
+            const args = format(message, data);
+            console.warn(...args);
+        },
+        error(message, data) {
+            const args = format(message, data);
+            console.error(...args);
+        },
+    };
+}
+/**
+ * Create a no-op logger (silent).
+ * Useful for testing or when logging is not needed.
+ */
+export function createNoopLogger() {
+    return {
+        debug: () => { },
+        info: () => { },
+        warn: () => { },
+        error: () => { },
+    };
+}

package/dist/esm/client/phone-auth-client.js

@@ -0,0 +1,424 @@
+/**
+ * Phone Authentication Client
+ *
+ * Main SDK client for phone number authentication.
+ * Supports all strategies: TS43 (Android), Link (iOS), Desktop (QR).
+ *
+ * IMPORTANT: invokeSecurePrompt must be called from a user gesture (button click)
+ * because both iOS App Clips and Android Digital Credentials API require
+ * transient activation (user interaction) to open system UI.
+ */
+import { USE_CASE, AUTHENTICATION_STRATEGY, validatePhoneNumber, validatePlmn, } from '../core';
+import { createAuthError, ERROR_CODES, isAuthError } from '../core/errors';
+import { createHttpClient } from './http';
+import { createLogger, createNoopLogger } from './logger';
+import { createPollingHandler } from './strategies/polling';
+import { AuthModal, createQRCodeDataFromDesktop } from '../ui/modal';
+import { MobileDebugConsole } from '../ui/mobile-debug-console';
+export class PhoneAuthClient {
+    constructor(config = {}) {
+        // Build complete config with defaults
+        this.config = {
+            ...config,
+            endpoints: {
+                prepare: config.endpoints?.prepare || '/api/magic-auth/prepare',
+                process: config.endpoints?.process || '/api/magic-auth/process',
+                polling: config.endpoints?.polling,
+            },
+            timeout: config.timeout || 30000,
+            pollingInterval: config.pollingInterval || 2000,
+            maxPollingAttempts: config.maxPollingAttempts || 30,
+            debug: config.debug || false,
+        };
+        // Use custom or default HTTP client
+        this.http = config.httpClient || createHttpClient({
+            timeout: this.config.timeout,
+            headers: config.headers,
+            dynamicHeaders: config.dynamicHeaders,
+        });
+        // Use custom or default logger
+        this.logger = config.logger || (this.config.debug
+            ? createLogger({ debug: true })
+            : createNoopLogger());
+        this.logger.debug('PhoneAuthClient initialized', {
+            endpoints: this.config.endpoints,
+            timeout: this.config.timeout,
+        });
+        // Initialize mobile debug console if configured
+        if (config.devtools?.showMobileConsole && typeof window !== 'undefined') {
+            MobileDebugConsole.init();
+            this.logger.info('Mobile debug console enabled');
+        }
+    }
+    // ==========================================================================
+    // PUBLIC API - High-Level
+    // ==========================================================================
+    /**
+     * Complete authentication flow in one call.
+     *
+     * @example
+     * ```typescript
+     * // Get phone number
+     * const result = await client.authenticate({ use_case: 'GetPhoneNumber' });
+     * console.log(result.phone_number);
+     *
+     * // Verify phone number
+     * const result = await client.authenticate({
+     *   use_case: 'VerifyPhoneNumber',
+     *   phone_number: '+14155551234'
+     * });
+     * console.log(result.verified);
+     * ```
+     */
+    async authenticate(request, options) {
+        // Step 1: Prepare
+        const prepared = await this.prepare(request);
+        // Step 2: Invoke
+        const invokeResult = await this.invokeSecurePrompt(prepared, options);
+        // Step 3: Wait for credential and process
+        const credential = await invokeResult.credential;
+        // Determine use_case from (in priority order):
+        // 1. session.use_case (direct field)
+        // 2. session.metadata.use_case (server returns it in metadata)
+        // 3. request.use_case (fallback to original request)
+        const useCase = prepared.session.use_case
+            || prepared.session.metadata?.use_case
+            || request.use_case;
+        if (!useCase) {
+            throw createAuthError(ERROR_CODES.INVALID_RESPONSE, 'Could not determine use_case from session or request');
+        }
+        if (useCase === USE_CASE.VERIFY_PHONE_NUMBER) {
+            return this.verifyPhoneNumber(credential, prepared.session);
+        }
+        else {
+            return this.getPhoneNumber(credential, prepared.session);
+        }
+    }
+    // ==========================================================================
+    // PUBLIC API - Granular Steps
+    // ==========================================================================
+    /**
+     * Step 1: Prepare authentication request.
+     *
+     * Validates input and sends prepare request to backend.
+     */
+    async prepare(request) {
+        this.logger.debug('Preparing authentication', { use_case: request.use_case });
+        // Validate phone number if provided
+        if (request.phone_number) {
+            const phoneValidation = validatePhoneNumber(request.phone_number);
+            if (!phoneValidation.valid) {
+                throw createAuthError(ERROR_CODES.INVALID_PHONE_NUMBER, phoneValidation.error);
+            }
+        }
+        // Validate PLMN if provided (deprecated)
+        if (request.plmn) {
+            const plmnValidation = validatePlmn(request.plmn);
+            if (!plmnValidation.valid) {
+                throw createAuthError(ERROR_CODES.INVALID_PLMN, plmnValidation.error);
+            }
+        }
+        // Validate use_case is provided (unless parent_session_id is given)
+        if (!request.use_case && !request.options?.parent_session_id) {
+            throw createAuthError(ERROR_CODES.MISSING_PARAMETERS, 'use_case is required');
+        }
+        // Build request with client info
+        const requestBody = {
+            ...request,
+            id: request.id || this.generateRequestId(),
+            client_info: request.client_info || {
+                user_agent: navigator.userAgent,
+                platform: navigator.platform,
+            },
+        };
+        try {
+            const response = await this.http.post(this.config.endpoints.prepare, requestBody);
+            this.logger.debug('Prepare successful', {
+                strategy: response.authentication_strategy,
+                sessionKey: response.session.session_key,
+            });
+            return response;
+        }
+        catch (error) {
+            this.logger.error('Prepare failed', error);
+            throw error;
+        }
+    }
+    /**
+     * Step 2: Invoke secure prompt for authentication.
+     *
+     * IMPORTANT: Must be called from a user gesture (button click).
+     *
+     * Returns unified InvokeResult with:
+     * - credential: Promise that resolves to AuthCredential
+     * - cancel?: Function to cancel (Link/Desktop only)
+     * - strategy: The authentication strategy used
+     * - session: Session info
+     */
+    async invokeSecurePrompt(prepared, options) {
+        const { authentication_strategy: strategy, session, data } = prepared;
+        this.logger.debug('Invoking secure prompt', { strategy });
+        switch (strategy) {
+            case AUTHENTICATION_STRATEGY.TS43:
+                return this.handleTS43(data, session);
+            case AUTHENTICATION_STRATEGY.LINK:
+                return this.handleLink(data, session, options);
+            case AUTHENTICATION_STRATEGY.DESKTOP:
+                return this.handleDesktop(data, session, options);
+            default:
+                throw createAuthError(ERROR_CODES.UNSUPPORTED_STRATEGY, `Unknown strategy: ${strategy}`);
+        }
+    }
+    /**
+     * Step 3A: Get phone number from credential.
+     */
+    async getPhoneNumber(credential, session) {
+        this.logger.debug('Getting phone number');
+        const requestBody = {
+            session,
+            credential,
+            use_case: USE_CASE.GET_PHONE_NUMBER,
+        };
+        try {
+            const response = await this.http.post(this.config.endpoints.process, requestBody);
+            this.logger.info('Phone number retrieved');
+            return response;
+        }
+        catch (error) {
+            this.logger.error('Get phone number failed', error);
+            throw error;
+        }
+    }
+    /**
+     * Step 3B: Verify phone number with credential.
+     */
+    async verifyPhoneNumber(credential, session) {
+        this.logger.debug('Verifying phone number');
+        const requestBody = {
+            session,
+            credential,
+            use_case: USE_CASE.VERIFY_PHONE_NUMBER,
+        };
+        try {
+            const response = await this.http.post(this.config.endpoints.process, requestBody);
+            this.logger.info('Phone number verified', { verified: response.verified });
+            return response;
+        }
+        catch (error) {
+            this.logger.error('Verify phone number failed', error);
+            throw error;
+        }
+    }
+    // ==========================================================================
+    // PUBLIC API - Utilities
+    // ==========================================================================
+    /**
+     * Check if Digital Credentials API is supported.
+     */
+    isSupported() {
+        if (typeof window === 'undefined')
+            return false;
+        return 'DigitalCredential' in window;
+    }
+    /**
+     * Get browser support info for debugging.
+     */
+    getBrowserSupportInfo() {
+        if (typeof window === 'undefined') {
+            return { supported: false, browser: 'unknown', message: 'Not in browser' };
+        }
+        const userAgent = navigator.userAgent;
+        const isChrome = /Chrome/.test(userAgent) && /Google Inc/.test(navigator.vendor);
+        const isEdge = /Edg\//.test(userAgent);
+        const supported = this.isSupported();
+        if (supported) {
+            return {
+                supported: true,
+                browser: isChrome ? 'Chrome' : isEdge ? 'Edge' : 'Other',
+            };
+        }
+        return {
+            supported: false,
+            browser: isChrome ? 'Chrome' : isEdge ? 'Edge' : 'Other',
+            message: 'Enable chrome://flags/#web-identity-digital-credentials',
+        };
+    }
+    // ==========================================================================
+    // PRIVATE - Strategy Handlers
+    // ==========================================================================
+    /**
+     * Handle TS43 strategy (Android Digital Credentials API).
+     */
+    async handleTS43(data, session) {
+        // Check browser support
+        if (!this.isSupported()) {
+            throw createAuthError(ERROR_CODES.BROWSER_NOT_SUPPORTED, 'Digital Credentials API not available');
+        }
+        // Build credential request
+        const credentialRequest = {
+            digital: {
+                requests: [{
+                        protocol: data.protocol,
+                        data: data.data,
+                    }],
+            },
+        };
+        this.logger.debug('Invoking Digital Credentials API');
+        // Create credential promise - resolves to just the credential string
+        const credentialPromise = (async () => {
+            try {
+                const response = await navigator.credentials.get(credentialRequest);
+                const digitalResponse = response;
+                if (!digitalResponse?.data?.vp_token) {
+                    throw createAuthError(ERROR_CODES.INVALID_RESPONSE, 'No credential returned from Digital Credentials API');
+                }
+                // Extract credential from vp_token
+                const vpToken = digitalResponse.data.vp_token;
+                const credentialValue = typeof vpToken === 'string'
+                    ? vpToken
+                    : Object.values(vpToken)[0];
+                const credential = Array.isArray(credentialValue)
+                    ? credentialValue[0]
+                    : credentialValue;
+                // Validate credential is not empty/undefined
+                if (!credential || (typeof credential === 'string' && credential.trim() === '')) {
+                    throw createAuthError(ERROR_CODES.INVALID_RESPONSE, 'Empty credential returned from Digital Credentials API');
+                }
+                // Return just the credential string
+                return credential;
+            }
+            catch (error) {
+                // If it's already an AuthError, rethrow it directly
+                if (isAuthError(error)) {
+                    throw error;
+                }
+                // Map browser errors to SDK errors
+                const err = error;
+                if (err.name === 'NotAllowedError' ||
+                    (err.name === 'NetworkError' && err.code === 19)) {
+                    throw createAuthError(ERROR_CODES.USER_CANCELLED, 'User cancelled authentication');
+                }
+                if (err.name === 'NotSupportedError') {
+                    throw createAuthError(ERROR_CODES.BROWSER_NOT_SUPPORTED, 'Browser not supported');
+                }
+                throw createAuthError(ERROR_CODES.NETWORK_ERROR, err.message || 'Credential request failed');
+            }
+        })();
+        // TS43 returns immediately (no cancel needed)
+        return {
+            credential: credentialPromise,
+            cancel: undefined,
+            strategy: AUTHENTICATION_STRATEGY.TS43,
+            session,
+        };
+    }
+    /**
+     * Handle Link strategy (iOS App Clips).
+     * Uses window.location.href to navigate to the App Clip.
+     */
+    handleLink(data, session, options) {
+        if (!data.url) {
+            throw createAuthError(ERROR_CODES.INVALID_RESPONSE, 'Missing link URL');
+        }
+        this.logger.debug('Opening App Clip', { url: data.url });
+        // Navigate to App Clip URL (must be from user gesture)
+        // Using window.location.href for better iOS compatibility
+        window.location.href = data.url;
+        // Start polling for authentication status
+        const polling = createPollingHandler({
+            sessionKey: session.session_key,
+            interval: options?.pollingInterval || this.config.pollingInterval,
+            maxAttempts: options?.maxPollingAttempts || this.config.maxPollingAttempts,
+            pollingEndpoint: options?.pollingEndpoint || this.config.endpoints.polling,
+            statusUrl: data.status_url,
+            logger: this.logger,
+        });
+        // Create credential promise from polling - resolves to just the credential string
+        const credentialPromise = polling.start().then(result => {
+            if (result.status === 'completed' && result.credential) {
+                return result.credential;
+            }
+            throw createAuthError(ERROR_CODES.VERIFICATION_FAILED, result.message || 'Link authentication failed');
+        });
+        return {
+            credential: credentialPromise,
+            cancel: () => polling.cancel(),
+            strategy: AUTHENTICATION_STRATEGY.LINK,
+            session,
+        };
+    }
+    /**
+     * Handle Desktop strategy (QR code).
+     */
+    handleDesktop(data, session, options) {
+        // Extract session ID for polling
+        const sessionId = data.data?.session_id || session.session_key;
+        this.logger.debug('Starting desktop authentication', { sessionId });
+        // Start polling for authentication status
+        const polling = createPollingHandler({
+            sessionKey: sessionId,
+            interval: options?.pollingInterval || this.config.pollingInterval,
+            maxAttempts: options?.maxPollingAttempts || this.config.maxPollingAttempts,
+            pollingEndpoint: options?.pollingEndpoint || this.config.endpoints.polling,
+            statusUrl: data.data?.status_url,
+            logger: this.logger,
+        });
+        // Show modal UI if not prevented
+        let modal = null;
+        if (!options?.preventDefaultUI) {
+            try {
+                // Create QR code data from DesktopData
+                const qrData = createQRCodeDataFromDesktop(data);
+                // Create and show modal
+                modal = new AuthModal(options?.modalOptions);
+                modal.showQRCode(qrData, options?.modalOptions?.description || 'Scan with your phone camera');
+                // Set close callback to cancel polling
+                modal.setCloseCallback(() => {
+                    this.logger.debug('Modal closed by user, cancelling authentication');
+                    polling.cancel();
+                });
+                this.logger.debug('Desktop modal displayed');
+            }
+            catch (e) {
+                this.logger.warn('Failed to show modal, continuing with polling only', e);
+            }
+        }
+        // Create credential promise from polling - resolves to just the credential string
+        const credentialPromise = polling.start().then(result => {
+            // Close modal on success
+            if (modal) {
+                modal.close();
+            }
+            if (result.status === 'completed' && result.credential) {
+                return result.credential;
+            }
+            throw createAuthError(ERROR_CODES.VERIFICATION_FAILED, result.message || 'Desktop authentication failed');
+        }).catch(error => {
+            // Close modal on error
+            if (modal) {
+                modal.close();
+            }
+            throw error;
+        });
+        return {
+            credential: credentialPromise,
+            cancel: () => {
+                polling.cancel();
+                if (modal) {
+                    modal.close();
+                }
+            },
+            strategy: AUTHENTICATION_STRATEGY.DESKTOP,
+            session,
+        };
+    }
+    // ==========================================================================
+    // PRIVATE - Utilities
+    // ==========================================================================
+    /**
+     * Generate a unique request ID.
+     */
+    generateRequestId() {
+        return `web-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+    }
+}