@truly-you/trulyyou-web-sdk 0.1.0

package/src/sdk/TrulyYouSDK.ts

@@ -0,0 +1,1805 @@
+import { TrulyYouSDKConfig, FetchOptions, SigningResult, FetchResult } from '../types'
+import Pusher from 'pusher-js'
+
+export class TrulyYouSDK {
+  private config: TrulyYouSDKConfig
+  private frontendUrl: string
+  private apiUrl: string
+  private authAppId: string | undefined
+  private invisible: boolean
+  private targetElement: string | HTMLElement | undefined
+  private brandingCache: { primary?: string; background?: string; secondary?: string; textColor?: string; icon?: string; name?: string } | null = null
+  private realtimeUrl: string
+  private mockMobileDevice: boolean
+
+  constructor(config: TrulyYouSDKConfig) {
+    this.config = config
+    this.frontendUrl = config.frontendUrl || this.getDefaultFrontendUrl()
+    this.apiUrl = config.apiUrl || this.getDefaultApiUrl()
+    this.authAppId = config.authAppId
+    this.invisible = config.invisible || false
+    this.targetElement = config.targetElement
+    this.mockMobileDevice = config.mockMobileDevice || false
+    
+    // Determine realtime WebSocket URL
+    if (config.realtimeUrl) {
+      this.realtimeUrl = config.realtimeUrl
+      console.log('[SDK]: Using provided realtimeUrl:', this.realtimeUrl)
+    } else {
+      // Infer from frontendUrl - replace http/https with ws/wss
+      const url = new URL(this.frontendUrl)
+      const wsProtocol = url.protocol === 'https:' ? 'wss:' : 'ws:'
+      this.realtimeUrl = `${wsProtocol}//${url.host}`
+      console.log('[SDK]: No realtimeUrl provided, inferring from frontendUrl:', this.realtimeUrl)
+    }
+    
+    // Fetch branding on instantiation if authAppId is provided
+    if (this.authAppId) {
+      this.fetchBranding().catch(err => {
+        console.warn('[SDK]: Failed to fetch branding:', err)
+      })
+    }
+  }
+
+
+  /**
+   * Fetch app branding from SDK backend
+   */
+  private async fetchBranding(): Promise<void> {
+    if (!this.authAppId) return
+    
+    try {
+      // Call SDK backend API directly
+      const response = await fetch(`${this.apiUrl}/api/apps/${this.authAppId}`, {
+        method: 'GET',
+        headers: { 'Content-Type': 'application/json' }
+      })
+      if (response.ok) {
+        const data = await response.json()
+        // Handle both formats: { app: {...} } or direct app object
+        const app = data.app || data
+        if (app?.colors || app?.icon || app?.name) {
+          this.brandingCache = {
+            primary: app.colors?.primary,
+            background: app.colors?.background,
+            secondary: app.colors?.secondary,
+            textColor: app.colors?.textColor,
+            icon: app.icon,
+            name: app.name
+          }
+          console.log('[SDK]: Branding fetched and cached:', this.brandingCache)
+        }
+      }
+    } catch (error) {
+      console.warn('[SDK]: Error fetching branding:', error)
+    }
+  }
+
+  /**
+   * Generate QR code with app icon overlaid in center
+   */
+  private async generateQRCodeWithIcon(qrData: string, imgElement: HTMLImageElement): Promise<void> {
+    return new Promise((resolve, reject) => {
+      // Step 1: Generate base QR code
+      const qrCodeUrl = `https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=${encodeURIComponent(qrData)}`
+      const qrImg = new Image()
+      qrImg.crossOrigin = 'anonymous'
+      
+      qrImg.onload = () => {
+        // Step 2: Create canvas and draw QR code
+        const canvas = document.createElement('canvas')
+        canvas.width = 300
+        canvas.height = 300
+        const ctx = canvas.getContext('2d')
+        
+        if (!ctx) {
+          reject(new Error('Failed to get canvas context'))
+          return
+        }
+        
+        // Draw QR code
+        ctx.drawImage(qrImg, 0, 0, 300, 300)
+        
+        // Step 3: Overlay app icon if available
+        if (this.brandingCache?.icon) {
+          // Try to load icon via proxy first (avoids CORS issues)
+          // If proxy fails, try direct load, then fallback to QR without icon
+          const tryLoadIcon = async (iconUrl: string, useProxy: boolean) => {
+            try {
+              let imageUrl = iconUrl
+              
+              if (useProxy) {
+                // Fetch via proxy to avoid CORS
+                const proxyUrl = `${this.apiUrl}/api/proxy-icon?url=${encodeURIComponent(iconUrl)}`
+                const response = await fetch(proxyUrl)
+                if (!response.ok) {
+                  throw new Error('Proxy fetch failed')
+                }
+                const blob = await response.blob()
+                imageUrl = URL.createObjectURL(blob)
+              }
+              
+              const iconImg = new Image()
+              iconImg.crossOrigin = useProxy ? null : 'anonymous'
+              
+              await new Promise<void>((resolveIcon, rejectIcon) => {
+                iconImg.onload = () => resolveIcon()
+                iconImg.onerror = () => rejectIcon(new Error('Image load failed'))
+                iconImg.src = imageUrl
+              })
+              
+              // Calculate icon size (20% of QR code size)
+              const iconSize = 60
+              const iconX = (300 - iconSize) / 2
+              const iconY = (300 - iconSize) / 2
+              
+              // Draw white background circle for icon
+              ctx.fillStyle = '#ffffff'
+              ctx.beginPath()
+              ctx.arc(150, 150, iconSize / 2 + 4, 0, 2 * Math.PI)
+              ctx.fill()
+              
+              // Draw icon
+              ctx.drawImage(iconImg, iconX, iconY, iconSize, iconSize)
+              
+              // Clean up object URL if we created one
+              if (useProxy && imageUrl.startsWith('blob:')) {
+                URL.revokeObjectURL(imageUrl)
+              }
+              
+              // Convert canvas to data URL and set as image source
+              imgElement.src = canvas.toDataURL('image/png')
+              resolve()
+            } catch (error) {
+              throw error
+            }
+          }
+          
+          // Try proxy first, then direct, then fallback
+          const iconUrl = this.brandingCache.icon
+          tryLoadIcon(iconUrl, true).catch(() => {
+            // If proxy fails, try direct load
+            tryLoadIcon(iconUrl, false).catch(() => {
+              // If both fail, just use QR code without icon
+              imgElement.src = canvas.toDataURL('image/png')
+              resolve()
+            })
+          })
+        } else {
+          // No icon, just use QR code
+          imgElement.src = canvas.toDataURL('image/png')
+          resolve()
+        }
+      }
+      
+      qrImg.onerror = () => {
+        reject(new Error('Failed to load QR code'))
+      }
+      
+      qrImg.src = qrCodeUrl
+    })
+  }
+
+  private getDefaultFrontendUrl(): string {
+    if (typeof window !== 'undefined') {
+      const hostname = window.location.hostname
+      if (hostname === 'localhost' || hostname === '127.0.0.1') {
+        return 'http://localhost:3002'
+      }
+    }
+    return 'https://sdks.verification.local'
+  }
+
+  private getDefaultApiUrl(): string {
+    if (typeof window !== 'undefined') {
+      const hostname = window.location.hostname
+      if (hostname === 'localhost' || hostname === '127.0.0.1') {
+        return 'http://localhost:3003'
+      }
+    }
+    return 'https://api.verification.local'
+  }
+
+  /**
+   * Detect if running on iOS device
+   */
+  private isIOSDevice(): boolean {
+    if (typeof window === 'undefined') return false
+    return /iPad|iPhone|iPod/.test(navigator.userAgent) || 
+           (navigator.platform === 'MacIntel' && (navigator as any).maxTouchPoints > 1)
+  }
+
+  /**
+   * Detect if running on Safari browser
+   */
+  private isSafariBrowser(): boolean {
+    if (typeof window === 'undefined') return false
+    return /Safari/.test(navigator.userAgent) && !/Chrome/.test(navigator.userAgent)
+  }
+
+  /**
+   * Detect if running on desktop device (not just viewport-based)
+   * Returns false if mockMobileDevice is enabled (treats as mobile)
+   */
+  private isDesktopDevice(): boolean {
+    // If mock mobile device is enabled, always return false (treat as mobile)
+    if (this.mockMobileDevice === true) {
+      console.log('[SDK]: Mock mobile device mode enabled - treating device as mobile (no handoff)')
+      return false
+    }
+    
+    if (typeof window === 'undefined') return false
+    
+    const userAgent = navigator.userAgent || navigator.vendor || (window as any).opera
+    const isMobileUA = /android|webos|iphone|ipad|ipod|blackberry|iemobile|opera mini|mobile/i.test(userAgent.toLowerCase())
+    
+    // Additional checks for actual mobile devices
+    const hasTouchScreen = 'ontouchstart' in window || navigator.maxTouchPoints > 0
+    const isMobileOrientation = window.screen && 'orientation' in window.screen
+    
+    // Desktop if: not mobile UA pattern OR (mobile UA but no real touch/orientation support)
+    const isDesktop = !isMobileUA || (isMobileUA && !hasTouchScreen && !isMobileOrientation)
+    
+    return isDesktop
+  }
+
+  /**
+   * Resolve target element from string selector or HTMLElement
+   */
+  private resolveTargetElement(): HTMLElement | null {
+    if (!this.targetElement) return null
+    
+    if (typeof this.targetElement === 'string') {
+      return document.querySelector(this.targetElement)
+    }
+    
+    return this.targetElement
+  }
+
+  /**
+   * Probe iframe to check if key exists in iframe's localStorage
+   * Also checks backend to verify key exists and is active
+   */
+  private async probeIframeForKey(): Promise<string | null> {
+    return new Promise((resolve) => {
+      try {
+        const origin = window.location.origin
+        const iframe = document.createElement('iframe')
+        iframe.style.cssText = `position: fixed; top: -9999px; left: -9999px; width: 1px; height: 1px; border: none; opacity: 0; pointer-events: none;`
+        
+        // Create a probe endpoint URL - we'll use /sign endpoint with a probe flag
+        const probeUrl = new URL(`${this.frontendUrl}/sign`)
+        probeUrl.searchParams.set('probe', 'true')
+        probeUrl.searchParams.set('origin', origin)
+        iframe.src = probeUrl.toString()
+
+        let timeout: NodeJS.Timeout | undefined
+        let backendCheckPromise: Promise<boolean> | null = null
+
+        const cleanup = () => {
+          window.removeEventListener('message', handleMessage)
+          if (iframe.parentNode) {
+            iframe.parentNode.removeChild(iframe)
+          }
+          if (timeout) {
+            clearTimeout(timeout)
+          }
+        }
+
+        const handleMessage = async (event: MessageEvent) => {
+          try {
+            const frontendOrigin = new URL(this.frontendUrl).origin
+            if (event.origin !== frontendOrigin) return
+            
+          } catch (e) {
+            if (!event.origin.includes(window.location.hostname)) return
+          }
+
+          const data = event.data as any
+          if (data?.type === 'KEY_CHECK_RESULT') {
+            cleanup()
+            if (data.hasKey && data.keyId) {
+              // Key found in localStorage - verify it's active in backend
+              if (!backendCheckPromise) {
+                backendCheckPromise = this.checkKeyStatus(data.keyId)
+              }
+              
+              const isActive = await backendCheckPromise
+              if (isActive) {
+                resolve(data.keyId)
+              } else {
+                console.log('[SDK]: Key found in localStorage but not active in backend, ignoring')
+                resolve(null)
+              }
+            } else {
+              resolve(null)
+            }
+          } else if (data?.type === 'KEY_CHECK_FAILED') {
+            cleanup()
+            resolve(null)
+          }
+        }
+
+        window.addEventListener('message', handleMessage)
+        document.body.appendChild(iframe)
+
+        // Short timeout to keep UX snappy
+        timeout = setTimeout(() => {
+          cleanup()
+          resolve(null)
+        }, 1500)
+      } catch {
+        resolve(null)
+      }
+    })
+  }
+
+  /**
+   * Lightweight API call to check if key exists and is active in backend
+   * Calls SDK frontend which proxies to SDK backend
+   */
+  private async checkKeyStatus(keyId: string): Promise<boolean> {
+    try {
+      const response = await fetch(`${this.frontendUrl}/api/key/check/${encodeURIComponent(keyId)}`, {
+        method: 'GET',
+        headers: { 'Content-Type': 'application/json' }
+      })
+      
+      if (!response.ok) {
+        console.log('[SDK]: Key status check failed:', response.status)
+        return false
+      }
+      
+      const result = await response.json() as any
+      const isActive = result.success && result.exists && result.active === true
+      
+      if (!isActive) {
+        console.log('[SDK]: Key found but not active:', {
+          exists: result.exists,
+          active: result.active,
+          status: result.status
+        })
+      }
+      
+      return isActive
+    } catch (error) {
+      console.error('[SDK]: Error checking key status:', error)
+      // If backend check fails, treat as invalid (fail closed for security)
+      // This ensures we don't use keys if we can't verify their status
+      return false
+    }
+  }
+
+  /**
+   * Open enrollment popup and wait for completion
+   */
+  private async enrollWithPopup(): Promise<string> {
+    if (!this.authAppId) {
+      throw new Error('authAppId is required for enrollment. Please configure authAppId in SDK config.')
+    }
+
+    // Generate session first
+    const sessionResponse = await fetch(`${this.frontendUrl}/api/sessions/generate`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ authAppId: this.authAppId })
+    })
+
+    if (!sessionResponse.ok) {
+      const errorData = await sessionResponse.json()
+      throw new Error(errorData.error || 'Failed to generate enrollment session')
+    }
+
+    const sessionData = await sessionResponse.json()
+    const sessionId = sessionData.data.sessionId
+
+    // authAppId is guaranteed to exist here due to check above
+    const appId = this.authAppId!
+
+    return new Promise((resolve, reject) => {
+      const origin = window.location.origin
+      
+      // Build enrollment URL with branding colors from cache if available
+      const enrollUrlParams = new URLSearchParams({
+        authAppId: appId,
+        sessionId: sessionId,
+        returnTo: 'popup',
+        origin: origin
+      })
+      
+      // Add branding colors to URL params if cached
+      if (this.brandingCache?.primary) {
+        enrollUrlParams.set('primaryColor', this.brandingCache.primary)
+      }
+      if (this.brandingCache?.background) {
+        enrollUrlParams.set('backgroundColor', this.brandingCache.background)
+      }
+      if (this.brandingCache?.secondary) {
+        enrollUrlParams.set('secondaryColor', this.brandingCache.secondary)
+      }
+      if (this.brandingCache?.textColor) {
+        enrollUrlParams.set('textColor', this.brandingCache.textColor)
+      }
+      
+      const enrollUrl = `${this.frontendUrl}/enroll?${enrollUrlParams.toString()}`
+
+      console.log('[SDK]: Opening enrollment popup:', enrollUrl)
+
+      const popup = window.open(
+        enrollUrl,
+        'trulyyou-enroll',
+        'width=600,height=700,scrollbars=yes,resizable=yes'
+      )
+
+      if (!popup) {
+        reject(new Error('Failed to open enrollment popup. Please allow popups for this site.'))
+        return
+      }
+
+      let timeout: NodeJS.Timeout
+      let checkPopupClosed: NodeJS.Timeout
+      let successReceived = false
+
+      // Set up postMessage listener
+      const handleMessage = (event: MessageEvent) => {
+        console.log('[SDK]: Enrollment popup message received:', event.origin, event.data)
+
+        // Verify origin matches frontend URL
+        try {
+          const frontendOrigin = new URL(this.frontendUrl).origin
+          if (event.origin !== frontendOrigin) {
+            console.log('[SDK]: Origin mismatch, ignoring message')
+            return
+          }
+        } catch (e) {
+          // If frontendUrl is relative or invalid, check if it matches current origin
+          if (!event.origin.includes(window.location.hostname)) {
+            console.log('[SDK]: Origin mismatch, ignoring message')
+            return
+          }
+        }
+
+        if (event.data && event.data.type === 'ENROLLMENT_SUCCESS') {
+          successReceived = true
+          
+          // Clear timeouts
+          if (timeout) clearTimeout(timeout)
+          if (checkPopupClosed) clearInterval(checkPopupClosed)
+
+          // Remove listener
+          window.removeEventListener('message', handleMessage)
+
+          // Get keyId from message first (avoids race condition with localStorage)
+          // Fallback to localStorage if not in message
+          const keyIdFromMessage = event.data.keyId
+          const trulyYouKeyId = keyIdFromMessage || localStorage.getItem('trulyYouKeyId')
+          
+          if (trulyYouKeyId) {
+            console.log('[SDK]: Enrollment successful, keyId obtained:', trulyYouKeyId, keyIdFromMessage ? '(from message)' : '(from localStorage)')
+            // Also ensure it's in localStorage for future use
+            if (keyIdFromMessage && !localStorage.getItem('trulyYouKeyId')) {
+              localStorage.setItem('trulyYouKeyId', keyIdFromMessage)
+            }
+            resolve(trulyYouKeyId)
+          } else {
+            // Final fallback: wait a bit and check localStorage again (race condition mitigation)
+            setTimeout(() => {
+              const delayedKeyId = localStorage.getItem('trulyYouKeyId')
+              if (delayedKeyId) {
+                console.log('[SDK]: Enrollment successful, keyId obtained (delayed):', delayedKeyId)
+                resolve(delayedKeyId)
+              } else {
+                reject(new Error('Enrollment completed but no keyId found in message or localStorage'))
+              }
+            }, 500)
+          }
+        } else if (event.data && event.data.type === 'ENROLLMENT_ERROR') {
+          successReceived = true
+          if (timeout) clearTimeout(timeout)
+          if (checkPopupClosed) clearInterval(checkPopupClosed)
+          window.removeEventListener('message', handleMessage)
+          reject(new Error(event.data.error || 'Enrollment failed'))
+        }
+      }
+
+      window.addEventListener('message', handleMessage)
+
+      // Timeout after 10 minutes
+      timeout = setTimeout(() => {
+        if (!successReceived) {
+          window.removeEventListener('message', handleMessage)
+          if (checkPopupClosed) clearInterval(checkPopupClosed)
+          reject(new Error('Enrollment timeout'))
+        }
+      }, 10 * 60 * 1000)
+
+      // Check if popup was closed manually
+      checkPopupClosed = setInterval(() => {
+        if (popup.closed && !successReceived) {
+          clearInterval(checkPopupClosed)
+          clearTimeout(timeout)
+          window.removeEventListener('message', handleMessage)
+          reject(new Error('Enrollment popup was closed'))
+        }
+      }, 500)
+    })
+  }
+
+  /**
+   * Sign with iframe (mobile device)
+   */
+  private async signWithIframe(apiCallStructure: {
+    body: any
+    uri: string
+    method: string
+    headers?: any
+  }): Promise<SigningResult> {
+    return new Promise((resolve, reject) => {
+      try {
+        const signId = `sign_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`
+        const targetElement = this.resolveTargetElement()
+        
+        // Create signing loading overlay if we have a target element
+        const createSigningLoadingOverlay = () => {
+          if (!targetElement) return null
+          
+          const overlay = document.createElement('div')
+          overlay.id = `signing-overlay-${signId}`
+          overlay.style.cssText = `
+            position: absolute;
+            top: 0;
+            left: 0;
+            right: 0;
+            bottom: 0;
+            background-color: rgba(255, 255, 255, 0.9);
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: center;
+            z-index: 10000;
+            border-radius: 8px;
+          `
+          
+          const spinner = document.createElement('div')
+          spinner.style.cssText = `
+            width: 48px;
+            height: 48px;
+            border: 4px solid ${this.config.spinnerBgColor || '#e5e7eb'};
+            border-top-color: ${this.config.spinnerColor || '#2563eb'};
+            border-radius: 50%;
+            animation: spin 1s linear infinite;
+            margin-bottom: 16px;
+          `
+          
+          const text = document.createElement('div')
+          text.textContent = 'Authenticating...'
+          text.style.cssText = `
+            color: ${this.config.spinnerTextColor || '#6b7280'};
+            font-size: 14px;
+            font-weight: 500;
+          `
+          
+          // Add CSS animation
+          const style = document.createElement('style')
+          style.textContent = `
+            @keyframes spin {
+              0% { transform: rotate(0deg); }
+              100% { transform: rotate(360deg); }
+            }
+          `
+          document.head.appendChild(style)
+          
+          overlay.appendChild(spinner)
+          overlay.appendChild(text)
+          
+          return overlay
+        }
+
+        // Create iframe for signing
+        const iframe = document.createElement('iframe')
+        iframe.name = `trulyyou-sign-frame-${signId}`
+        iframe.scrolling = 'no'
+        iframe.setAttribute('scrolling', 'no')
+        // Allow WebAuthn in iframe (required for cross-origin iframes)
+        iframe.setAttribute('allow', 'publickey-credentials-get *; publickey-credentials-create *')
+        
+        // Encode payload
+        const sortObjectByKeys = (obj: any): any => {
+          if (obj === null || typeof obj !== 'object' || obj instanceof Array) {
+            return obj
+          }
+          const sorted: any = {}
+          Object.keys(obj).sort().forEach(key => {
+            sorted[key] = sortObjectByKeys(obj[key])
+          })
+          return sorted
+        }
+
+        const createPayloadBase64 = (data: any, uri: string, method: string, queryParams: any) => {
+          const dataToProcess = data === undefined || data === null ? {} : data
+          const queryParamsToProcess = queryParams === undefined || queryParams === null ? {} : queryParams
+          
+          const sortedData = sortObjectByKeys(dataToProcess)
+          const sortedQueryParams = sortObjectByKeys(queryParamsToProcess)
+          
+          const encodedBody = btoa(JSON.stringify(sortedData))
+          const encodedQueryParams = btoa(JSON.stringify(sortedQueryParams))
+          
+          const payloadData = {
+            method: method,
+            uriId: uri,
+            requestBody: encodedBody,
+            queryParams: encodedQueryParams,
+          }
+          
+          return {
+            fullbase64: btoa(JSON.stringify(payloadData)),
+            sortedData: sortedData,
+            sortedQueryParams: sortedQueryParams,
+            encodedBody: encodedBody,
+            encodedQueryParams: encodedQueryParams,
+          }
+        }
+
+        const base64EncodedResponse = createPayloadBase64(
+          apiCallStructure.body || {},
+          apiCallStructure.uri,
+          apiCallStructure.method,
+          {}
+        )
+        const encodedPayload = base64EncodedResponse.fullbase64
+        
+        // Prepare attestation data for iframe
+        const attestationDataForIframe = {
+          payload: encodedPayload,
+          apiCallStructure: apiCallStructure
+        }
+        
+        const encodedData = btoa(JSON.stringify(attestationDataForIframe))
+        
+        // Create form for POST submission to /sign/submit API route
+        const form = document.createElement('form')
+        form.method = 'POST'
+        form.action = `${this.frontendUrl}/sign/submit`
+        form.target = iframe.name
+        form.style.display = 'none'
+        
+        // Add form data as hidden inputs
+        const attestationDataInput = document.createElement('input')
+        attestationDataInput.type = 'hidden'
+        attestationDataInput.name = 'attestationData'
+        attestationDataInput.value = encodedData
+        form.appendChild(attestationDataInput)
+        
+        const signIdInput = document.createElement('input')
+        signIdInput.type = 'hidden'
+        signIdInput.name = 'signId'
+        signIdInput.value = signId
+        form.appendChild(signIdInput)
+        
+        const modeInput = document.createElement('input')
+        modeInput.type = 'hidden'
+        modeInput.name = 'mode'
+        modeInput.value = 'embedded'
+        form.appendChild(modeInput)
+        
+        // Determine if iframe will be visible (for mobile: not invisible, or iOS/Safari always visible)
+        const isIframeVisible = !this.invisible || this.isIOSDevice() || this.isSafariBrowser()
+        
+        // Add branding colors and visibility flag to form data
+        const brandingInput = document.createElement('input')
+        brandingInput.type = 'hidden'
+        brandingInput.name = 'branding'
+        brandingInput.value = JSON.stringify({
+          primary: this.brandingCache?.primary || this.config.spinnerColor || '#2563eb',
+          background: this.brandingCache?.background || '#ffffff',
+          secondary: this.brandingCache?.secondary || '#2563eb',
+          textColor: this.brandingCache?.textColor || this.config.spinnerTextColor || '#6b7280',
+          spinnerColor: this.config.spinnerColor || this.brandingCache?.primary || '#2563eb',
+          spinnerBgColor: this.config.spinnerBgColor || '#e5e7eb',
+          spinnerTextColor: this.config.spinnerTextColor || this.brandingCache?.textColor || '#6b7280',
+          visible: isIframeVisible
+        })
+        form.appendChild(brandingInput)
+        
+        // Mobile device logic (mock mobile OR actual mobile - both treated the same)
+        const isMobile = this.mockMobileDevice || !this.isDesktopDevice()
+        
+        if (isMobile) {
+          // Mobile: NEVER full screen
+          // iOS/Safari: ALWAYS use target element if provided (WebAuthn requires visible iframe)
+          if (this.isIOSDevice() || this.isSafariBrowser()) {
+            if (targetElement) {
+              // iOS/Safari: Use target element (required for WebAuthn)
+              const targetStyle = window.getComputedStyle(targetElement)
+              if (targetStyle.position === 'static') {
+                targetElement.style.position = 'relative'
+              }
+              const originalHeight = targetElement.style.height || targetStyle.height
+              if (!originalHeight || originalHeight === 'auto') {
+                const computedHeight = targetElement.offsetHeight
+                if (computedHeight > 0) {
+                  targetElement.style.height = `${computedHeight}px`
+                }
+              }
+              iframe.style.cssText = `position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none; z-index: 9999;`
+              targetElement.appendChild(iframe)
+              // No overlay needed - sign page is hidden when embedded
+            } else {
+              // iOS/Safari with no target element: must use invisible (can't use full screen on mobile)
+              console.warn('[SDK]: Mobile iOS/Safari with no target element - using invisible iframe (WebAuthn may fail)')
+              iframe.style.cssText = `position: fixed; top: -9999px; left: -9999px; width: 1px; height: 1px; border: none; opacity: 0; pointer-events: none;`
+            }
+          } else {
+            // Mobile non-iOS/Safari: invisible if invisible=true, target element if invisible=false
+            if (this.invisible) {
+              iframe.style.cssText = `position: fixed; top: -9999px; left: -9999px; width: 1px; height: 1px; border: none; opacity: 0; pointer-events: none;`
+            } else if (targetElement) {
+              // Visible iframe in target element
+              const targetStyle = window.getComputedStyle(targetElement)
+              if (targetStyle.position === 'static') {
+                targetElement.style.position = 'relative'
+              }
+              const originalHeight = targetElement.style.height || targetStyle.height
+              if (!originalHeight || originalHeight === 'auto') {
+                const computedHeight = targetElement.offsetHeight
+                if (computedHeight > 0) {
+                  targetElement.style.height = `${computedHeight}px`
+                }
+              }
+              iframe.style.cssText = `position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none; z-index: 9999;`
+              targetElement.appendChild(iframe)
+              // No overlay - sign page is hidden when embedded
+            } else {
+              // No target element - use invisible (can't use full screen on mobile)
+              console.warn('[SDK]: Mobile device with invisible=true but no target element - using invisible iframe')
+              iframe.style.cssText = `position: fixed; top: -9999px; left: -9999px; width: 1px; height: 1px; border: none; opacity: 0; pointer-events: none;`
+            }
+          }
+        } else {
+          // Desktop device: can use full screen (only when opened directly on Device B after handoff)
+          // But when called from SDK, prefer target element or invisible
+          if (this.invisible) {
+            iframe.style.cssText = `position: fixed; top: -9999px; left: -9999px; width: 1px; height: 1px; border: none; opacity: 0; pointer-events: none;`
+          } else if (targetElement) {
+            // Visible iframe in target element
+            const targetStyle = window.getComputedStyle(targetElement)
+            if (targetStyle.position === 'static') {
+              targetElement.style.position = 'relative'
+            }
+            const originalHeight = targetElement.style.height || targetStyle.height
+            if (!originalHeight || originalHeight === 'auto') {
+              const computedHeight = targetElement.offsetHeight
+              if (computedHeight > 0) {
+                targetElement.style.height = `${computedHeight}px`
+              }
+            }
+            iframe.style.cssText = `position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none; z-index: 9999;`
+            targetElement.appendChild(iframe)
+            const overlay = createSigningLoadingOverlay()
+            if (overlay) {
+              targetElement.appendChild(overlay)
+            }
+          } else {
+            // Desktop: full screen overlay (only when no target element - Device B after handoff)
+            iframe.style.cssText = `position: fixed; top: 0; left: 0; width: 100%; height: 100%; border: none; z-index: 9999; background: white;`
+          }
+        }
+        
+        // Append form to body
+        document.body.appendChild(form)
+        
+        // Append iframe - only to body if not already appended to target element above
+        // Check if iframe has a parent (was already appended to target element)
+        if (!iframe.parentNode) {
+          document.body.appendChild(iframe)
+        }
+        
+        let timeout: NodeJS.Timeout | undefined
+        let overlayElement: HTMLElement | null = null
+        
+        const cleanup = () => {
+          window.removeEventListener('message', handleMessage)
+          if (form.parentNode) {
+            form.parentNode.removeChild(form)
+          }
+          if (iframe.parentNode) {
+            iframe.parentNode.removeChild(iframe)
+          }
+          if (overlayElement && overlayElement.parentNode) {
+            overlayElement.parentNode.removeChild(overlayElement)
+          }
+          if (timeout) {
+            clearTimeout(timeout)
+          }
+          // Remove height constraint from target element
+          if (targetElement && !this.invisible) {
+            targetElement.style.height = ''
+          }
+        }
+        
+        const handleMessage = (event: MessageEvent) => {
+          try {
+            const frontendOrigin = new URL(this.frontendUrl).origin
+            if (event.origin !== frontendOrigin) return
+          } catch (e) {
+            if (!event.origin.includes(window.location.hostname)) return
+          }
+          
+          const data = event.data as any
+          // Handle both SIGNING_COMPLETE and SIGNATURE_COMPLETE (sign page sends SIGNATURE_COMPLETE)
+          if ((data?.type === 'SIGNING_COMPLETE' || data?.type === 'SIGNATURE_COMPLETE') && data?.signId === signId) {
+            console.log('[SDK]: Signature complete message received:', { type: data.type, hasSignature: !!data.signature || !!data.signatureBase64 })
+            cleanup()
+            if (data.error) {
+              reject(new Error(data.error))
+            } else {
+              // Sign page sends signatureBase64, but we expect signature - use either field
+              const signature = data.signature || data.signatureBase64
+              if (!signature) {
+                reject(new Error('No signature in response'))
+                return
+              }
+              resolve({
+                signature: signature,
+                keyId: data.keyId || ''
+              })
+            }
+          } else if (data?.type === 'SIGNING_ERROR' && data?.signId === signId) {
+            cleanup()
+            reject(new Error(data.error || 'Signing failed'))
+          }
+        }
+        
+        window.addEventListener('message', handleMessage)
+        
+        // Submit form to iframe
+        form.submit()
+        
+        // Remove form after submission
+        setTimeout(() => {
+          if (form.parentNode) {
+            form.parentNode.removeChild(form)
+          }
+        }, 100)
+        
+        // Store overlay reference for cleanup
+        if (targetElement && !this.invisible) {
+          overlayElement = targetElement.querySelector(`#signing-overlay-${signId}`) as HTMLElement
+        }
+        
+        // Timeout after 5 minutes
+        timeout = setTimeout(() => {
+          cleanup()
+          reject(new Error('Signing timeout'))
+        }, 5 * 60 * 1000)
+        
+      } catch (error: any) {
+        reject(error)
+      }
+    })
+  }
+
+  /**
+   * Sign with WebSocket handoff (desktop device)
+   */
+  private async signWithWebSocketHandoff(apiCallStructure: {
+    body: any
+    uri: string
+    method: string
+    headers?: any
+  }, signatureId: string): Promise<SigningResult> {
+    return new Promise((resolve, reject) => {
+      try {
+        console.log('[SDK]: Desktop device detected, using WebSocket handoff with signatureId:', signatureId)
+        
+        // Get primary color and app name from branding cache (already fetched on SDK instantiation)
+        const primaryColor = this.brandingCache?.primary || '#2563eb'
+        const authAppName = this.brandingCache?.name || 'TrulyYou'
+        
+        // Encode signatureId, primaryColor, and authAppName as base64 JSON for URL parameter
+        const encodedData = {
+          signatureId: signatureId,
+          primaryColor: primaryColor,
+          authAppName: authAppName
+        }
+        const encodedThing = btoa(JSON.stringify(encodedData))
+        
+        // Build sign URL with encoded parameter (no query params)
+        const signUrl = `${this.frontendUrl}/sign/${encodedThing}`
+        
+        // Encode payload
+        const sortObjectByKeys = (obj: any): any => {
+          if (obj === null || typeof obj !== 'object' || obj instanceof Array) {
+            return obj
+          }
+          const sorted: any = {}
+          Object.keys(obj).sort().forEach(key => {
+            sorted[key] = sortObjectByKeys(obj[key])
+          })
+          return sorted
+        }
+
+        const createPayloadBase64 = (data: any, uri: string, method: string, queryParams: any) => {
+          const dataToProcess = data === undefined || data === null ? {} : data
+          const queryParamsToProcess = queryParams === undefined || queryParams === null ? {} : queryParams
+          
+          const sortedData = sortObjectByKeys(dataToProcess)
+          const sortedQueryParams = sortObjectByKeys(queryParamsToProcess)
+          
+          const encodedBody = btoa(JSON.stringify(sortedData))
+          const encodedQueryParams = btoa(JSON.stringify(sortedQueryParams))
+          
+          const payloadData = {
+            method: method,
+            uriId: uri,
+            requestBody: encodedBody,
+            queryParams: encodedQueryParams,
+          }
+          
+          return {
+            fullbase64: btoa(JSON.stringify(payloadData)),
+            sortedData: sortedData,
+            sortedQueryParams: sortedQueryParams,
+            encodedBody: encodedBody,
+            encodedQueryParams: encodedQueryParams,
+          }
+        }
+
+        const base64EncodedResponse = createPayloadBase64(
+          apiCallStructure.body || {},
+          apiCallStructure.uri,
+          apiCallStructure.method,
+          {}
+        )
+        const encodedPayload = base64EncodedResponse.fullbase64
+
+        // Prepare attestation data for sending
+        const attestationData = {
+          payload: encodedPayload,
+          apiCallStructure: apiCallStructure
+        }
+
+        // Parse realtimeUrl to extract host/port for Pusher
+        let pusherHost: string | undefined
+        let pusherPort: number | undefined
+        let forceTLS = false
+        let encrypted = true
+        
+        try {
+          const realtimeUrlObj = new URL(this.realtimeUrl.startsWith('ws://') || this.realtimeUrl.startsWith('wss://') 
+            ? this.realtimeUrl 
+            : this.realtimeUrl.replace(/^http:/, 'ws:').replace(/^https:/, 'wss:'))
+          
+          pusherHost = realtimeUrlObj.hostname
+          pusherPort = realtimeUrlObj.port ? parseInt(realtimeUrlObj.port, 10) : (realtimeUrlObj.protocol === 'wss:' ? 443 : 80)
+          forceTLS = realtimeUrlObj.protocol === 'wss:'
+          encrypted = realtimeUrlObj.protocol === 'wss:'
+        } catch (e) {
+          console.warn('[SDK]: Error parsing realtimeUrl, using defaults:', e)
+          pusherHost = '127.0.0.1'
+          pusherPort = 6001
+        }
+        
+        // Get Pusher app key from config or use default
+        const pusherAppKey = this.config.pusherAppKey || 'app-key'
+        
+        // Merge custom Pusher config with parsed values
+        // When using custom wsHost/wsPort, we need to set cluster to empty string to disable default cluster behavior
+        const pusherOptions: any = {
+          wsHost: this.config.pusherConfig?.wsHost || pusherHost,
+          wsPort: this.config.pusherConfig?.wsPort || pusherPort,
+          cluster: this.config.pusherConfig?.cluster || '', // Required when using custom wsHost/wsPort
+          forceTLS: this.config.pusherConfig?.forceTLS ?? forceTLS,
+          encrypted: this.config.pusherConfig?.encrypted ?? encrypted,
+          disableStats: this.config.pusherConfig?.disableStats ?? true,
+          enabledTransports: this.config.pusherConfig?.enabledTransports || ['ws', 'wss'],
+        }
+        
+        console.log('[SDK]: Initializing Pusher with config:', pusherOptions)
+        const pusher = new Pusher(pusherAppKey, pusherOptions)
+        
+        // Use signatureId as the channel name (Soketi doesn't need 'public-' prefix)
+        const channel = pusher.subscribe(signatureId)
+        console.log('[SDK]: Attempting to subscribe to Pusher channel:', signatureId)
+        
+        // Log when channel subscription succeeds and bind events
+        channel.bind('pusher:subscription_succeeded', () => {
+          console.log('[SDK]: ✅ Successfully subscribed to channel:', signatureId)
+          
+          // Bind countdown events after subscription succeeds (backend uses client-* prefix)
+          channel.bind('countdown_update', (data: any) => {
+            console.log('[SDK]: 📊 Received countdown_update event:', data)
+          })
+          channel.bind('client-countdown_update', (data: any) => {
+            console.log('[SDK]: 📊 Received client-countdown_update event:', data)
+          })
+          
+          channel.bind('countdown_expired', () => {
+            console.log('[SDK]: ⏰ Received countdown_expired event')
+          })
+          channel.bind('client-countdown_expired', () => {
+            console.log('[SDK]: ⏰ Received client-countdown_expired event')
+          })
+        })
+        
+        // Store handlers in a variable that will be set later
+        let handleCountdownUpdate: ((data: any) => void) | null = null
+        let handleCountdownExpired: (() => void) | null = null
+        
+        // Bind events early - handlers will be assigned after QR setup
+        const earlyCountdownHandler = (data: any) => {
+          console.log('[SDK]: 📊 Received countdown_update event (early bind):', data)
+          if (handleCountdownUpdate) {
+            handleCountdownUpdate(data)
+          } else {
+            console.warn('[SDK]: Countdown handler not ready yet, storing event')
+            // Store event to process once handler is ready
+            setTimeout(() => {
+              if (handleCountdownUpdate) {
+                handleCountdownUpdate(data)
+              }
+            }, 100)
+          }
+        }
+        channel.bind('countdown_update', earlyCountdownHandler)
+        channel.bind('client-countdown_update', earlyCountdownHandler) // Backend sends as client event
+        
+        const earlyExpiredHandler = () => {
+          console.log('[SDK]: ⏰ Received countdown_expired event (early bind)')
+          if (handleCountdownExpired) {
+            handleCountdownExpired()
+          }
+        }
+        channel.bind('countdown_expired', earlyExpiredHandler)
+        channel.bind('client-countdown_expired', earlyExpiredHandler) // Backend sends as client event
+        
+        // Log connection errors
+        pusher.connection.bind('error', (err: any) => {
+          console.error('[SDK]: ❌ Pusher connection error:', err)
+        })
+        
+        // Log state changes
+        pusher.connection.bind('state_change', (states: any) => {
+          console.log('[SDK]: 🔄 Pusher state change:', states.previous, '->', states.current)
+        })
+        
+        let counterpartyConnected = false
+        let timeout: NodeJS.Timeout
+
+        // Wait for Pusher connection
+        pusher.connection.bind('connected', () => {
+          console.log('[SDK]: Pusher connected, waiting for counterparty...')
+          
+          // Notify server that desktop device connected (if QR is shown inline, already sent above)
+          if (!targetElement || !qrContainer) {
+            channel.trigger('client-device_connected', { type: 'device_connected', deviceType: 'desktop' })
+          }
+          
+          // Timeout after 5 minutes
+          timeout = setTimeout(() => {
+            cleanup()
+            pusher.disconnect()
+            reject(new Error('WebSocket handoff timeout - no counterparty connected'))
+          }, 5 * 60 * 1000)
+        })
+
+        // Listen for mobile device connection (client event from sign page)
+        // Device B now fetches payload from API, so we just mark as connected
+        channel.bind('client-device_connected', (data: any) => {
+          // Only react to mobile device connections (ignore our own desktop connection)
+          if (data.type === 'device_connected' && data.deviceType === 'mobile' && !counterpartyConnected) {
+            counterpartyConnected = true
+            console.log('[SDK]: Mobile device connected (payload will be fetched from API)')
+            // No longer sending payload via socket - Device B fetches from API
+          }
+        })
+
+        // Listen for signature result (client event from mobile)
+        channel.bind('client-signature_result', (data: any) => {
+          console.log('[SDK]: Signature result event received, raw data:', data)
+          console.log('[SDK]: Data keys:', Object.keys(data || {}))
+          console.log('[SDK]: counterpartyConnected:', counterpartyConnected)
+          
+          // Extract signature from data - handle both direct and wrapped formats
+          const signature = data?.signature || data?.data?.signature
+          const error = data?.error || data?.data?.error
+          const keyId = data?.keyId || data?.data?.keyId
+          
+          console.log('[SDK]: Extracted values - signature:', !!signature, 'error:', error, 'keyId:', keyId)
+          console.log('[SDK]: Full socket data received:', JSON.stringify(data, null, 2))
+          
+          // Prevent multiple processing
+          if (!counterpartyConnected) {
+            console.warn('[SDK]: Received signature result but counterparty not marked as connected yet. Waiting...')
+            // Don't return - might be a timing issue, try to process anyway
+          }
+          
+          clearTimeout(timeout)
+          
+          if (error) {
+            console.error('[SDK]: Signature error:', error)
+            cleanup()
+            pusher.disconnect()
+            reject(new Error(error))
+            return
+          } 
+          
+          if (signature) {
+            console.log('[SDK]: Signature received successfully, resolving promise...')
+            // Use keyId from Device B (not localStorage) - Device B sent this via socket
+            const deviceBKeyId = keyId || ''
+            if (!deviceBKeyId) {
+              console.warn('[SDK]: ⚠️ WARNING - No keyId received from Device B via socket! Data:', data)
+            }
+            console.log('[SDK]: ✅ Using keyId from Device B:', deviceBKeyId, '(extracted from socket)')
+            const result: SigningResult = {
+              signature: signature,
+              keyId: deviceBKeyId,
+              signatureId: signatureId
+            }
+            console.log('[SDK]: Resolving with SigningResult:', { 
+              signatureLength: result.signature?.length, 
+              keyId: result.keyId, 
+              signatureId: result.signatureId,
+              keyIdSource: deviceBKeyId ? 'Device B (socket)' : 'MISSING - will fallback to localStorage'
+            })
+            
+            cleanup()
+            pusher.disconnect()
+            resolve(result)
+            return
+          }
+          
+          console.error('[SDK]: Invalid signature result data - no signature or error:', JSON.stringify(data))
+          cleanup()
+          pusher.disconnect()
+          reject(new Error('Invalid signature result received'))
+        })
+
+        pusher.connection.bind('error', (error: any) => {
+          console.error('[SDK]: Pusher connection error:', error)
+          clearTimeout(timeout)
+          pusher.disconnect()
+          reject(new Error('Pusher connection error'))
+        })
+
+        pusher.connection.bind('disconnected', () => {
+          console.log('[SDK]: Pusher disconnected')
+          clearTimeout(timeout)
+        })
+
+        // Store signatureId and signUrl for enrollment page to use
+        // This will be handled by opening enrollment page with signatureId
+        // For now, we'll need to modify the enrollment flow to handle this
+        
+        // Actually, we need to open enrollment page instead of sign page
+        // The enrollment page will show QR code and handle WebSocket
+        // Let's modify the approach - we'll emit an event that the app can listen to
+        
+        // Store attestation data in sessionStorage for sign page to access
+        sessionStorage.setItem(`signHandoff_${signatureId}`, JSON.stringify(attestationData))
+        
+        // Show QR code inline in target element (Device A - desktop)
+        // Device B will scan QR code and open the sign page URL
+        const targetElement = this.resolveTargetElement()
+        let qrContainer: HTMLElement | null = null
+        let checkWindowClosed: NodeJS.Timeout | null = null
+        
+        if (targetElement) {
+          // Create QR code container
+          qrContainer = document.createElement('div')
+          qrContainer.id = `qr-handoff-${signatureId}`
+          qrContainer.style.cssText = `
+            position: absolute;
+            top: 0;
+            left: 0;
+            right: 0;
+            bottom: 0;
+            width: 100%;
+            height: 100%;
+            max-width: 100%;
+            max-height: 100%;
+            overflow: hidden;
+            background-color: rgba(255, 255, 255, 0.98);
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: center;
+            z-index: 10001;
+            padding: 0;
+            box-sizing: border-box;
+          `
+          
+          // Create QR code wrapper with countdown SVG overlay
+          const qrWrapper = document.createElement('div')
+          qrWrapper.style.cssText = `
+            position: relative;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            width: 100%;
+            height: 100%;
+            max-width: 100%;
+            max-height: 100%;
+          `
+          
+          // Create loading spinner (shown while QR loads)
+          const spinnerContainer = document.createElement('div')
+          spinnerContainer.style.cssText = `
+            position: absolute;
+            top: 50%;
+            left: 50%;
+            transform: translate(-50%, -50%);
+            width: 48px;
+            height: 48px;
+            z-index: 1;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+          `
+          
+          const spinner = document.createElement('div')
+          spinner.style.cssText = `
+            width: 48px;
+            height: 48px;
+            border: 4px solid ${this.brandingCache?.primary ? `${this.brandingCache.primary}20` : '#e5e7eb'};
+            border-top-color: ${this.brandingCache?.primary || '#2563eb'};
+            border-radius: 50%;
+            animation: spin 1s linear infinite;
+          `
+          
+          // Add spin animation
+          const style = document.createElement('style')
+          style.textContent = `
+            @keyframes spin {
+              to { transform: rotate(360deg); }
+            }
+          `
+          document.head.appendChild(style)
+          
+          spinnerContainer.appendChild(spinner)
+          
+          // Create QR code with app icon overlay in center
+          const qrImage = document.createElement('img')
+          qrImage.alt = 'QR Code for mobile signing (click to copy URL)'
+          qrImage.style.cssText = `
+            width: 100%;
+            height: 100%;
+            max-width: 100%;
+            max-height: 100%;
+            aspect-ratio: 1;
+            object-fit: contain;
+            cursor: pointer;
+            transition: opacity 0.2s;
+            position: relative;
+            z-index: 2;
+            display: none;
+            opacity: 0;
+          `
+          qrImage.title = 'Click to copy URL to clipboard'
+          
+          // Show spinner initially, hide when QR loads
+          qrImage.addEventListener('load', () => {
+            console.log('[SDK]: QR image loaded')
+            spinnerContainer.style.display = 'none'
+            qrImage.style.display = 'block'
+            qrImage.style.opacity = '1'
+            // Recalculate SVG position after QR is loaded and visible
+            setTimeout(() => {
+              if (setupCountdownRect) {
+                setupCountdownRect()
+              }
+            }, 50)
+          })
+          
+          qrImage.addEventListener('error', () => {
+            console.error('[SDK]: QR image failed to load')
+            spinnerContainer.style.display = 'none'
+            // Still try to show QR even if load failed
+            qrImage.style.display = 'block'
+            qrImage.style.opacity = '0.5'
+          })
+          
+          // Create countdown SVG overlay (positioned absolutely over QR image, matching exact size)
+          const countdownSvg = document.createElementNS('http://www.w3.org/2000/svg', 'svg')
+          countdownSvg.id = `countdown-svg-${signatureId}`
+          
+          // Wait for QR image to load and get actual rendered dimensions, then size SVG to match exactly
+          const setupCountdownRect = () => {
+            // Get actual rendered size and position of QR image (after object-fit: contain is applied)
+            const qrRect = qrImage.getBoundingClientRect()
+            const qrWrapperRect = qrWrapper.getBoundingClientRect()
+            
+            // QR image with object-fit: contain and aspect-ratio: 1 will be square
+            // and fit inside the wrapper. Get its actual rendered size.
+            const actualQRSize = Math.min(qrRect.width, qrRect.height)
+            
+            // Make SVG slightly bigger than QR to create border space (5% larger on each side = 10% total)
+            const borderPadding = actualQRSize * 0.05 // 5% padding on each side
+            const svgSize = actualQRSize + (borderPadding * 2) // Total SVG size with border space
+            
+            // Calculate position relative to wrapper (not viewport)
+            // Use getBoundingClientRect for accurate positioning (accounts for transforms and object-fit)
+            // For centered QR with flexbox, calculate offset from QR center to wrapper center
+            const qrCenterX = qrRect.left + qrRect.width / 2 - qrWrapperRect.left
+            const qrCenterY = qrRect.top + qrRect.height / 2 - qrWrapperRect.top
+            
+            // SVG should be centered over QR but slightly bigger - position from top-left
+            const offsetX = qrCenterX - svgSize / 2
+            const offsetY = qrCenterY - svgSize / 2
+            
+            // Use getBoundingClientRect values as they account for transforms and positioning
+            console.log('[SDK]: QR positioning - centered offset:', offsetX, offsetY, 'QR size:', actualQRSize, 'SVG size:', svgSize)
+            
+            // Position and size SVG to be slightly bigger than QR (with border space)
+            countdownSvg.style.cssText = `
+              position: absolute;
+              top: ${offsetY}px;
+              left: ${offsetX}px;
+              width: ${svgSize}px;
+              height: ${svgSize}px;
+              pointer-events: none;
+              z-index: 2;
+              transform: rotate(0deg);
+              transform-origin: center center;
+            `
+            countdownSvg.setAttribute('viewBox', `0 0 ${svgSize} ${svgSize}`)
+            countdownSvg.setAttribute('preserveAspectRatio', 'xMidYMid meet')
+            
+            // Rounded rectangle parameters - use percentages relative to viewBox
+            // The SVG is bigger than QR to create border space, but rect should fit within SVG bounds
+            const rectWidth = svgSize
+            const rectHeight = svgSize
+            const cornerRadius = svgSize * 0.04 // 4% of size for rounded corners (scales with QR)
+            const strokeWidth = svgSize * 0.06 // 6% of size for stroke (3x thicker - scales with QR)
+            
+            // Clear existing rects if any
+            while (countdownSvg.firstChild) {
+              countdownSvg.removeChild(countdownSvg.firstChild)
+            }
+            
+            // Position rect so stroke sits OUTSIDE the QR image
+            // QR is centered in SVG, so it goes from borderPadding to svgSize - borderPadding
+            // We want the stroke to sit outside this, so:
+            // - Rect inner edge should be at borderPadding (QR edge)
+            // - Stroke is centered on path, so x = borderPadding - strokeWidth/2 (so stroke extends outside)
+            // - Rect width should be actualQRSize + strokeWidth (to account for stroke extending outside)
+            const rectX = borderPadding - strokeWidth / 2
+            const rectY = borderPadding - strokeWidth / 2
+            const rectW = actualQRSize + strokeWidth
+            const rectH = actualQRSize + strokeWidth
+            
+            // Background rounded rectangle outline - positioned OUTSIDE QR bounds
+            const bgRect = document.createElementNS('http://www.w3.org/2000/svg', 'rect')
+            bgRect.setAttribute('x', rectX.toString())
+            bgRect.setAttribute('y', rectY.toString())
+            bgRect.setAttribute('width', rectW.toString())
+            bgRect.setAttribute('height', rectH.toString())
+            bgRect.setAttribute('rx', cornerRadius.toString())
+            bgRect.setAttribute('ry', cornerRadius.toString())
+            bgRect.setAttribute('fill', 'none')
+            bgRect.setAttribute('stroke', '#e5e7eb')
+            bgRect.setAttribute('stroke-width', strokeWidth.toString())
+            countdownSvg.appendChild(bgRect)
+            
+            // Progress rounded rectangle outline (animated) - same positioning, OUTSIDE QR bounds
+            const progressRect = document.createElementNS('http://www.w3.org/2000/svg', 'rect')
+            progressRect.id = `countdown-progress-${signatureId}`
+            progressRect.setAttribute('x', rectX.toString())
+            progressRect.setAttribute('y', rectY.toString())
+            progressRect.setAttribute('width', rectW.toString())
+            progressRect.setAttribute('height', rectH.toString())
+            progressRect.setAttribute('rx', cornerRadius.toString())
+            progressRect.setAttribute('ry', cornerRadius.toString())
+            progressRect.setAttribute('fill', 'none')
+            progressRect.setAttribute('stroke', this.brandingCache?.primary || '#2563eb')
+            progressRect.setAttribute('stroke-width', strokeWidth.toString())
+            progressRect.setAttribute('stroke-linecap', 'round')
+            progressRect.setAttribute('stroke-linejoin', 'round')
+            // Recalculate perimeter with new dimensions (rect is outside QR bounds)
+            const actualInnerWidth = rectW
+            const actualInnerHeight = rectH
+            const actualInnerRx = cornerRadius
+            const actualStraightEdges = 2 * (actualInnerWidth + actualInnerHeight - 2 * actualInnerRx)
+            const actualCornerArcs = 2 * Math.PI * actualInnerRx
+            const actualPerimeter = actualStraightEdges + actualCornerArcs
+            progressRect.setAttribute('stroke-dasharray', actualPerimeter.toString())
+            progressRect.setAttribute('stroke-dashoffset', actualPerimeter.toString())
+            progressRect.style.transition = 'stroke-dashoffset 0.3s linear, stroke 0.3s linear'
+            countdownSvg.appendChild(progressRect)
+            
+            // Return actual perimeter for use in countdown updates
+            return { perimeter: actualPerimeter }
+          }
+          
+          // Setup when image loads or immediately if already loaded
+          if (qrImage.complete && qrImage.naturalWidth > 0) {
+            setupCountdownRect()
+          } else {
+            qrImage.addEventListener('load', () => {
+              setupCountdownRect()
+            })
+            // Fallback setup with default values
+            setupCountdownRect()
+          }
+          
+          // Countdown state
+          let countdownState = { remaining: 30, total: 30 }
+          
+          // Listen for countdown updates (bound both early and in subscription_succeeded)
+          // Assign handler to the stored variable so early binds can access it
+          handleCountdownUpdate = (data: any) => {
+            console.log('[SDK]: 🎯 Processing countdown_update:', data)
+            if (data && (data.type === 'countdown_update' || data.timeRemaining !== undefined)) {
+              countdownState = { 
+                remaining: data.timeRemaining ?? countdownState.remaining, 
+                total: data.totalTime ?? countdownState.total 
+              }
+              console.log(`[SDK]: 📊 Updating countdown rectangle: ${countdownState.remaining}/${countdownState.total}`)
+              
+              // Calculate perimeter using actual SVG size from viewBox
+              const viewBoxAttr = countdownSvg.getAttribute('viewBox')
+              const svgSize = viewBoxAttr ? parseFloat(viewBoxAttr.split(' ')[2]) || 100 : 100
+              const cornerRadius = svgSize * 0.04
+              const strokeWidth = svgSize * 0.06 // 3x thicker
+              // Calculate border padding (5% of QR size, but we need to reverse-calculate from SVG size)
+              // SVG = QR + 2*borderPadding, so borderPadding = (SVG - QR) / 2
+              // We approximate QR as ~91% of SVG (since SVG = QR * 1.1, so QR ≈ SVG / 1.1)
+              const estimatedQRSize = svgSize / 1.1
+              const borderPadding = (svgSize - estimatedQRSize) / 2
+              // Rectangle is positioned OUTSIDE QR (at borderPadding - strokeWidth/2)
+              const rectW = estimatedQRSize + strokeWidth
+              const rectH = estimatedQRSize + strokeWidth
+              const actualInnerWidth = rectW
+              const actualInnerHeight = rectH
+              const actualInnerRx = cornerRadius
+              const straightEdges = 2 * (actualInnerWidth + actualInnerHeight - 2 * actualInnerRx)
+              const cornerArcs = 2 * Math.PI * actualInnerRx
+              const currentPerimeter = straightEdges + cornerArcs
+              
+              const percentage = countdownState.remaining / countdownState.total
+              const strokeDashoffset = currentPerimeter * (1 - percentage)
+              
+              // Update the progress rect if it exists
+              const progressRectElement = document.getElementById(`countdown-progress-${signatureId}`) as SVGElement | null
+              if (progressRectElement && progressRectElement instanceof SVGRectElement) {
+                progressRectElement.setAttribute('stroke-dashoffset', strokeDashoffset.toString())
+                console.log(`[SDK]: 📊 Set stroke-dashoffset to: ${strokeDashoffset} (percentage: ${percentage}, perimeter: ${currentPerimeter})`)
+                
+                // Change color when low
+                if (countdownState.remaining <= 5) {
+                  progressRectElement.setAttribute('stroke', '#ef4444')
+                } else if (countdownState.remaining <= 10) {
+                  progressRectElement.setAttribute('stroke', '#f59e0b')
+                } else {
+                  progressRectElement.setAttribute('stroke', this.brandingCache?.primary || '#2563eb')
+                }
+              }
+            } else {
+              console.warn('[SDK]: Invalid countdown_update data:', data)
+            }
+          }
+          
+          handleCountdownExpired = () => {
+            console.log('[SDK]: ⏰ Countdown expired - cleaning up and resetting state')
+            
+            // Clean up Pusher connection first
+            if (pusher && pusher.connection.state === 'connected') {
+              pusher.disconnect()
+            }
+            
+            // Remove QR container and all its children completely
+            if (qrContainer) {
+              // Remove all child elements
+              while (qrContainer.firstChild) {
+                qrContainer.removeChild(qrContainer.firstChild)
+              }
+              // Remove container from DOM
+              if (qrContainer.parentNode) {
+                qrContainer.parentNode.removeChild(qrContainer)
+              }
+              qrContainer = null
+            }
+            
+            // Reset countdown SVG reference
+            const countdownSvgElement = document.getElementById(`countdown-svg-${signatureId}`)
+            if (countdownSvgElement && countdownSvgElement.parentNode) {
+              countdownSvgElement.parentNode.removeChild(countdownSvgElement)
+            }
+            
+            // Clean up any other references
+            cleanup()
+            
+            // Silently reject - don't show alert, just reset state
+            reject(new Error('Countdown expired'))
+          }
+          
+          channel.bind('countdown_update', handleCountdownUpdate)
+          channel.bind('client-countdown_update', handleCountdownUpdate) // Backend sends as client event
+          channel.bind('countdown_expired', handleCountdownExpired)
+          channel.bind('client-countdown_expired', handleCountdownExpired) // Backend sends as client event
+          
+          qrWrapper.appendChild(spinnerContainer)
+          qrWrapper.appendChild(qrImage)
+          qrWrapper.appendChild(countdownSvg)
+          
+          // Add click handler to copy URL to clipboard
+          qrImage.addEventListener('click', async () => {
+            try {
+              await navigator.clipboard.writeText(signUrl)
+              console.log('[SDK]: URL copied to clipboard:', signUrl)
+              
+              // Visual feedback - temporarily change opacity
+              const originalOpacity = qrImage.style.opacity || '1'
+              qrImage.style.opacity = '0.7'
+              setTimeout(() => {
+                qrImage.style.opacity = originalOpacity
+              }, 200)
+            } catch (err) {
+              console.error('[SDK]: Failed to copy URL to clipboard:', err)
+              // Fallback for older browsers
+              const textArea = document.createElement('textarea')
+              textArea.value = signUrl
+              textArea.style.position = 'fixed'
+              textArea.style.opacity = '0'
+              document.body.appendChild(textArea)
+              textArea.select()
+              try {
+                document.execCommand('copy')
+                console.log('[SDK]: URL copied to clipboard (fallback method)')
+              } catch (fallbackErr) {
+                console.error('[SDK]: Fallback copy failed:', fallbackErr)
+              }
+              document.body.removeChild(textArea)
+            }
+          })
+          
+          // Generate QR code with icon overlay
+          this.generateQRCodeWithIcon(signUrl, qrImage).catch((err: any) => {
+            console.warn('[SDK]: Error generating QR code with icon, using fallback:', err)
+            // Fallback to simple QR code without icon
+            const qrCodeUrl = `https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=${encodeURIComponent(signUrl)}`
+            qrImage.src = qrCodeUrl
+          })
+          
+          qrContainer.appendChild(qrWrapper)
+          
+          // Make target element position relative if needed and add overflow constraints
+          const targetStyle = window.getComputedStyle(targetElement)
+          if (targetStyle.position === 'static') {
+            targetElement.style.position = 'relative'
+          }
+          // Ensure target element contains the overlay
+          if (targetStyle.overflow === 'visible') {
+            targetElement.style.overflow = 'hidden'
+          }
+          
+          targetElement.appendChild(qrContainer)
+        } else {
+          // No target element - fallback to opening in new window
+          console.warn('[SDK]: No target element available, opening sign page in new window')
+          const signWindow = window.open(signUrl, '_blank', 'width=600,height=700')
+          
+          if (!signWindow) {
+            pusher.disconnect()
+            reject(new Error('Failed to open sign page. Please allow popups for this site.'))
+            return
+          }
+
+          // Monitor sign window for closure
+          checkWindowClosed = setInterval(() => {
+            if (signWindow.closed) {
+              if (checkWindowClosed) clearInterval(checkWindowClosed)
+              clearTimeout(timeout)
+              pusher.disconnect()
+              reject(new Error('Sign window was closed'))
+            }
+          }, 500)
+        }
+
+        // Store pusher reference for cleanup
+        let pusherInstance: Pusher | null = pusher
+        
+        // Cleanup on completion
+        const cleanup = () => {
+          if (qrContainer && qrContainer.parentNode) {
+            qrContainer.parentNode.removeChild(qrContainer)
+          }
+          if (checkWindowClosed) {
+            clearInterval(checkWindowClosed)
+          }
+          clearTimeout(timeout)
+          if (pusherInstance) {
+            pusherInstance.disconnect()
+            pusherInstance = null
+          }
+          sessionStorage.removeItem(`signHandoff_${signatureId}`)
+        }
+
+      } catch (error: any) {
+        reject(error)
+      }
+    })
+  }
+
+  /**
+   * Sign a payload with WebAuthn without a server-generated challenge
+   * Encodes the payload directly as the challenge
+   * Uses iframe to extract key from iframe's localStorage, not host
+   */
+  async signPayload(apiCallStructure: {
+    body: any
+    uri: string
+    method: string
+    headers?: any
+  }, signatureId?: string): Promise<SigningResult> {
+    try {
+      // Step 1: Check if desktop device first - desktop uses WebSocket handoff (no key probe needed)
+      if (this.isDesktopDevice()) {
+        console.log('[SDK]: Desktop device detected, using WebSocket handoff (skipping key probe)')
+        if (!signatureId) {
+          throw new Error('signatureId is required for desktop handoff')
+        }
+        return await this.signWithWebSocketHandoff(apiCallStructure, signatureId)
+      }
+      
+      // Step 2: Mobile device - probe iframe to check if key exists in iframe's localStorage and is active in backend
+      console.log('[SDK]: Mobile device detected, probing iframe for existing key...')
+      let keyId = await this.probeIframeForKey()
+      
+      if (!keyId) {
+        // Step 3: No valid active key found (missing, invalid, revoked, or expired) - open enrollment popup
+        console.log('[SDK]: No valid active key found (missing, invalid, revoked, or expired), opening enrollment popup...')
+        await this.enrollWithPopup()
+        
+        // Step 4: After enrollment, probe again to verify new key is active
+        keyId = await this.probeIframeForKey()
+        
+        if (!keyId) {
+          throw new Error('Enrollment completed but no valid active key found')
+        }
+      }
+      
+      console.log('[SDK]: Valid active key found, signing with keyId:', keyId)
+      
+      // Step 5: Sign using iframe (key is extracted from iframe's localStorage)
+      console.log('[SDK]: Using iframe signing for mobile device')
+      return await this.signWithIframe(apiCallStructure)
+
+    } catch (error: any) {
+      console.error('[SDK]: Signing error:', error)
+      throw error
+    }
+  }
+
+  /**
+   * Fetch with automatic payload signing
+   */
+  async fetchWithSignature(
+    url: string,
+    options: FetchOptions = {}
+  ): Promise<FetchResult> {
+    // Declare signatureId at function scope so it's accessible in catch block
+    let signatureId: string | undefined = undefined
+    try {
+      console.log('[SDK]: fetchWithSignature called for:', url)
+
+      // Parse URL to get path and base URL
+      const urlObj = new URL(url)
+      const uriPath = urlObj.pathname + urlObj.search
+      const baseUrl = `${urlObj.protocol}//${urlObj.host}`
+
+      // Prepare API call structure
+      const apiCallStructure = {
+        body: options.body ? JSON.parse(options.body as string) : {},
+        uri: uriPath,
+        method: (options.method || 'GET').toUpperCase(),
+        headers: options.headers || {}
+      }
+
+      console.log('[SDK]: API call structure:', apiCallStructure)
+
+      // Check if domain + signature template match (if authAppId is configured)
+      if (this.authAppId) {
+        try {
+          // Generate signatureId first (for desktop handoff, we need it before signing)
+          // Generate a long, unique signatureId
+          signatureId = `sig_${Date.now()}_${Math.random().toString(36).substring(2, 15)}${Math.random().toString(36).substring(2, 15)}${Math.random().toString(36).substring(2, 15)}${Math.random().toString(36).substring(2, 15)}`
+          
+          // Get keyId and userId from localStorage
+          const keyId = localStorage.getItem('trulyYouKeyId')
+          const userIdStr = localStorage.getItem('trulyYouUserId')
+          let userId: string | undefined
+          if (userIdStr) {
+            try {
+              userId = userIdStr
+            } catch (e) {
+              console.warn('[SDK]: Failed to parse userId from localStorage:', e)
+            }
+          }
+
+          // Check if this will be a handoff flow (desktop device)
+          const isHandoff = this.isDesktopDevice()
+
+          // Create signature document BEFORE signing (this also validates domain and template and starts countdown for handoff)
+          const createResponse = await fetch(`${this.apiUrl}/api/signatures/create`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              appId: this.authAppId,
+              baseUrl,
+              endpoint: uriPath,
+              method: apiCallStructure.method,
+              keyId: keyId || '',
+              userId: userId,
+              apiCallStructure,
+              signatureId,
+              isHandoff // Flag to indicate handoff flow
+            })
+          })
+
+          if (createResponse.ok) {
+            const createData = await createResponse.json()
+            if (createData.success && createData.data?.signatureId) {
+              console.log('[SDK]: Signature document created with signatureId:', createData.data.signatureId)
+            } else {
+              throw new Error('Failed to create signature document: ' + (createData.error || 'No signatureId returned'))
+            }
+          } else {
+            const errorData = await createResponse.json().catch(() => ({}))
+            throw new Error('Failed to create signature: ' + (errorData.error || 'Creation request failed'))
+          }
+
+          // Now sign the payload (pass signatureId for desktop handoff)
+          const signingResult = await this.signPayload(apiCallStructure, signatureId)
+
+          // Make the actual API call with signature and signatureId in header
+          // Use keyId from signingResult (Device B's keyId for handoff, or localStorage keyId for mobile)
+          console.log('[SDK]: 🔍 KeyId debug - signingResult.keyId:', signingResult.keyId, 'localStorage keyId:', keyId, 'keyId type:', typeof signingResult.keyId, 'empty?:', signingResult.keyId === '')
+          const keyIdForAuth = signingResult.keyId || keyId || ''
+          console.log('[SDK]: ✅ Final keyId for auth header:', keyIdForAuth, '(from', signingResult.keyId && signingResult.keyId !== '' ? 'Device B' : 'localStorage fallback', ')')
+          const authHeaderValue = btoa(JSON.stringify({ signature: signingResult.signature, keyId: keyIdForAuth, signatureId }))
+
+          const response = await fetch(url, {
+            ...options,
+            headers: {
+              ...options.headers,
+              'x-truly-auth': authHeaderValue
+            }
+          })
+
+          console.log('[SDK]: Request complete, status:', response.status)
+
+          return {
+            response,
+            signature: signingResult.signature,
+            signatureId
+          }
+        } catch (error: any) {
+          console.error('[SDK]: Signature creation error:', error)
+          // Silently fail for countdown expiry - don't throw error
+          if (error.message && error.message.includes('Countdown expired')) {
+            // Return empty result to indicate silent failure
+            return { response: null as any, signature: '', signatureId: signatureId || '' }
+          }
+          throw new Error('Signature creation failed: ' + (error.message || 'Unknown error'))
+        }
+      } else {
+        throw new Error('authAppId is required for signature validation. Please configure authAppId in SDK initialization.')
+      }
+
+    } catch (error: any) {
+      console.error('[SDK]: fetchWithSignature error:', error)
+      // Silently fail for countdown expiry - just reset state
+      if (error.message && error.message.includes('Countdown expired')) {
+        // Don't throw error, just silently reset - return empty result
+        // signatureId is in scope from fetchWithSignature function
+        const expiredSignatureId = signatureId || ''
+        return { response: null as any, signature: '', signatureId: expiredSignatureId }
+      }
+      throw error
+    }
+  }
+}
+