@l.x/sessions 1.0.3 → 1.0.5

package/src/challenge-solvers/turnstileScriptLoader.ts

@@ -0,0 +1,325 @@
+import { TurnstileScriptLoadError } from '@l.x/sessions/src/challenge-solvers/turnstileErrors'
+import type { TurnstileScriptOptions } from '@l.x/sessions/src/challenge-solvers/types'
+
+type TurnstileState = 'unloaded' | 'loading' | 'ready'
+
+interface TurnstileLoadPromise {
+  resolve: (value?: void | PromiseLike<void>) => void
+  reject: (reason?: unknown) => void
+}
+
+/**
+ * Global state machine for Turnstile script loading
+ * Singleton pattern ensures shared state across solver instances
+ */
+class TurnstileScriptState {
+  private state: TurnstileState = 'unloaded'
+  private loadPromise: Promise<void>
+  private loadResolvers: TurnstileLoadPromise | null = null
+
+  constructor() {
+    this.loadPromise = new Promise((resolve, reject) => {
+      this.loadResolvers = { resolve, reject }
+      // If already ready, resolve immediately
+      if (this.state === 'ready' && window.turnstile) {
+        resolve(undefined)
+      }
+    })
+  }
+
+  getState(): TurnstileState {
+    return this.state
+  }
+
+  setState(newState: TurnstileState): void {
+    this.state = newState
+  }
+
+  getLoadPromise(): Promise<void> {
+    return this.loadPromise
+  }
+
+  resolveLoad(): void {
+    if (this.loadResolvers) {
+      this.loadResolvers.resolve(undefined)
+      this.loadResolvers = null
+    }
+  }
+
+  rejectLoad(reason: unknown): void {
+    if (this.loadResolvers) {
+      this.loadResolvers.reject(reason)
+      this.loadResolvers = null
+    }
+  }
+
+  /**
+   * Reset state for testing purposes
+   */
+  reset(): void {
+    this.state = 'unloaded'
+    this.loadPromise = new Promise((resolve, reject) => {
+      this.loadResolvers = { resolve, reject }
+    })
+  }
+}
+
+// Singleton instance
+const turnstileState = new TurnstileScriptState()
+
+const DEFAULT_SCRIPT_ID = 'cf-turnstile-script'
+const DEFAULT_ONLOAD_NAME = 'onloadTurnstileCallback'
+const TURNSTILE_SCRIPT_URL = 'https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit'
+
+/**
+ * Observes script loading using MutationObserver
+ * More reliable than polling for detecting when script is loaded
+ */
+function observeScriptLoad(scriptId: string, timeoutMs = 10000): Promise<void> {
+  return new Promise((resolve, reject) => {
+    // Check if script already exists and is loaded
+    const existingScript = document.getElementById(scriptId) as HTMLScriptElement | null
+    if (existingScript && window.turnstile) {
+      resolve(undefined)
+      return
+    }
+
+    // If script exists but not loaded yet, set up load listener
+    if (existingScript && !window.turnstile) {
+      // Track intervals so we can clean them up from any code path
+      let loadCheckIntervalId: ReturnType<typeof setInterval> | null = null
+      let raceCheckIntervalId: ReturnType<typeof setInterval> | null = null
+
+      const cleanup = (): void => {
+        if (loadCheckIntervalId) {
+          clearInterval(loadCheckIntervalId)
+        }
+        if (raceCheckIntervalId) {
+          clearInterval(raceCheckIntervalId)
+        }
+        existingScript.removeEventListener('load', onScriptLoad)
+        existingScript.removeEventListener('error', onScriptError)
+      }
+
+      const onScriptLoad = (): void => {
+        // Wait a bit for turnstile to initialize
+        loadCheckIntervalId = setInterval(() => {
+          if (window.turnstile) {
+            cleanup()
+            resolve(undefined)
+          }
+        }, 50)
+
+        // Timeout if turnstile doesn't initialize
+        setTimeout(() => {
+          cleanup()
+          if (!window.turnstile) {
+            reject(new TurnstileScriptLoadError('Turnstile did not initialize after script load'))
+          } else {
+            resolve(undefined)
+          }
+        }, timeoutMs)
+      }
+
+      const onScriptError = (): void => {
+        cleanup()
+        reject(new TurnstileScriptLoadError('Failed to load Turnstile script'))
+      }
+
+      // Script exists but not loaded yet, listen for load event
+      // For scripts with defer/async, the load event will fire when ready
+      existingScript.addEventListener('load', onScriptLoad)
+      existingScript.addEventListener('error', onScriptError)
+
+      // Also check periodically in case the script loaded before we attached listeners
+      // (race condition with defer/async scripts)
+      raceCheckIntervalId = setInterval(() => {
+        if (window.turnstile) {
+          cleanup()
+          resolve(undefined)
+        }
+      }, 50)
+
+      // Timeout fallback
+      setTimeout(() => {
+        cleanup()
+        if (!window.turnstile) {
+          reject(new TurnstileScriptLoadError('Turnstile script loaded but API not available'))
+        } else {
+          resolve(undefined)
+        }
+      }, timeoutMs)
+      return
+    }
+
+    let resolved = false
+    const timeoutId = setTimeout(() => {
+      if (!resolved) {
+        resolved = true
+        reject(new TurnstileScriptLoadError(`Script observation timeout after ${timeoutMs}ms`))
+      }
+    }, timeoutMs)
+
+    const observer = new MutationObserver(() => {
+      const script = document.getElementById(scriptId) as HTMLScriptElement | null
+      if (script && window.turnstile) {
+        if (!resolved) {
+          resolved = true
+          clearTimeout(timeoutId)
+          observer.disconnect()
+          resolve(undefined)
+        }
+      }
+    })
+
+    // Start observing
+    observer.observe(document.head, {
+      childList: true,
+      subtree: true,
+    })
+
+    // Also check immediately in case script was added synchronously
+    const scriptCheck = document.getElementById(scriptId) as HTMLScriptElement | null
+    if (scriptCheck && window.turnstile) {
+      resolved = true
+      clearTimeout(timeoutId)
+      observer.disconnect()
+      resolve(undefined)
+      return
+    }
+  })
+}
+
+/**
+ * Injects Turnstile script with CSP-compliant options
+ */
+function injectTurnstileScript(options: TurnstileScriptOptions = {}): void {
+  const scriptId = options.id || DEFAULT_SCRIPT_ID
+  const onLoadCallbackName = options.onLoadCallbackName || DEFAULT_ONLOAD_NAME
+
+  // Check if script already exists
+  if (document.getElementById(scriptId)) {
+    return
+  }
+
+  // Set up global onload callback
+  // Use unknown first to avoid type errors
+  const windowWithCallback = window as unknown as Record<string, unknown>
+  windowWithCallback[onLoadCallbackName] = (): void => {
+    turnstileState.setState('ready')
+    turnstileState.resolveLoad()
+    // Clean up callback
+    delete windowWithCallback[onLoadCallbackName]
+  }
+
+  // Create script element
+  const script = document.createElement('script')
+  script.id = scriptId
+  script.src = TURNSTILE_SCRIPT_URL
+
+  // Apply CSP-compliant options
+  if (options.nonce) {
+    script.nonce = options.nonce
+  }
+  if (options.defer !== undefined) {
+    script.defer = options.defer
+  }
+  if (options.async !== undefined) {
+    script.async = options.async
+  }
+  if (options.crossOrigin) {
+    script.crossOrigin = options.crossOrigin
+  }
+
+  // Track interval so it can be cleaned up from timeout
+  let checkIntervalId: ReturnType<typeof setInterval> | null = null
+
+  // Set onload callback via script attribute for CSP compliance
+  script.onload = (): void => {
+    // Wait for turnstile to actually be available
+    // The global callback will handle state transition
+    checkIntervalId = setInterval(() => {
+      if (window.turnstile) {
+        if (checkIntervalId) {
+          clearInterval(checkIntervalId)
+        }
+        // If global callback hasn't fired, resolve manually
+        if (turnstileState.getState() !== 'ready') {
+          turnstileState.setState('ready')
+          turnstileState.resolveLoad()
+        }
+      }
+    }, 50)
+
+    // Fallback timeout
+    setTimeout(() => {
+      if (checkIntervalId) {
+        clearInterval(checkIntervalId)
+      }
+      // Only reject if BOTH conditions are true: state isn't ready AND turnstile doesn't exist.
+      // If turnstile exists but state isn't ready, the interval will handle it.
+      // If state is ready, the global callback already resolved.
+      if (turnstileState.getState() !== 'ready' && !window.turnstile) {
+        turnstileState.rejectLoad(new TurnstileScriptLoadError('Turnstile did not initialize after script load'))
+      }
+    }, 5000)
+  }
+
+  script.onerror = (): void => {
+    turnstileState.setState('unloaded')
+    turnstileState.rejectLoad(new TurnstileScriptLoadError('Failed to load Turnstile script'))
+  }
+
+  // Inject script
+  document.head.appendChild(script)
+  turnstileState.setState('loading')
+}
+
+/**
+ * Ensures Turnstile script is loaded, using state machine for coordination
+ */
+async function ensureTurnstileScript(scriptOptions: TurnstileScriptOptions = {}): Promise<void> {
+  // If already ready, return immediately
+  if (turnstileState.getState() === 'ready' && window.turnstile) {
+    return Promise.resolve()
+  }
+
+  // Check if script exists in DOM (including preloaded scripts)
+  const scriptId = scriptOptions.id || DEFAULT_SCRIPT_ID
+  const existingScript = document.getElementById(scriptId) as HTMLScriptElement | null
+
+  if (existingScript) {
+    // Script exists in DOM - check if it's already loaded
+    if (window.turnstile) {
+      turnstileState.setState('ready')
+      turnstileState.resolveLoad()
+      return Promise.resolve()
+    }
+
+    // Script exists but not loaded yet - observe for loading
+    // This handles preloaded scripts with defer/async
+    turnstileState.setState('loading')
+    return observeScriptLoad(scriptId).then(() => {
+      turnstileState.setState('ready')
+      turnstileState.resolveLoad()
+    })
+  }
+
+  // If already loading (from a previous call), wait for existing promise
+  if (turnstileState.getState() === 'loading') {
+    return turnstileState.getLoadPromise()
+  }
+
+  // Script doesn't exist - inject it
+  injectTurnstileScript(scriptOptions)
+  return turnstileState.getLoadPromise()
+}
+
+/**
+ * Reset turnstile state for testing purposes
+ */
+function resetTurnstileState(): void {
+  turnstileState.reset()
+}
+
+export { ensureTurnstileScript, observeScriptLoad, turnstileState, resetTurnstileState }

package/src/challenge-solvers/turnstileSolver.integration.test.ts

@@ -0,0 +1,331 @@
+/// @vitest-environment happy-dom
+import { ChallengeType } from '@luxamm/client-platform-service/dist/lx/platformservice/v1/sessionService_pb'
+import { createTurnstileSolver } from '@l.x/sessions/src/challenge-solvers/createTurnstileSolver'
+import { resetTurnstileState } from '@l.x/sessions/src/challenge-solvers/turnstileScriptLoader'
+import type { PerformanceTracker } from '@l.x/sessions/src/performance/types'
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// Mock performance tracker for testing
+function createMockPerformanceTracker(): PerformanceTracker {
+  let time = 0
+  return {
+    now: (): number => {
+      time += 100
+      return time
+    },
+  }
+}
+
+// Mock window.turnstile API
+const mockTurnstileAPI = {
+  render: vi.fn(),
+  remove: vi.fn(),
+  reset: vi.fn(),
+  getResponse: vi.fn(),
+  ready: vi.fn(),
+}
+
+// Setup DOM mocks
+beforeAll(() => {
+  const originalCreateElement = document.createElement.bind(document)
+  vi.spyOn(document, 'createElement').mockImplementation((tagName: string) => {
+    const element = originalCreateElement(tagName)
+    if (tagName === 'div') {
+      // Track created divs for assertions
+      // eslint-disable-next-line no-extra-semi
+      ;(element as any)._testCreated = true
+    }
+    return element
+  })
+
+  vi.spyOn(document.head, 'appendChild').mockImplementation((node) => {
+    if (node instanceof HTMLScriptElement && node.src.includes('challenges.cloudflare.com')) {
+      // Simulate script load immediately
+      setTimeout(() => {
+        // Set up the mock turnstile API
+        // eslint-disable-next-line no-extra-semi
+        ;(window as any).turnstile = mockTurnstileAPI
+        if (node.onload) {
+          node.onload({} as Event)
+        }
+      }, 0)
+    }
+    return node
+  })
+
+  const originalBodyAppendChild = document.body.appendChild.bind(document.body)
+  vi.spyOn(document.body, 'appendChild').mockImplementation((node) => {
+    // eslint-disable-next-line no-extra-semi
+    ;(node as any)._testAppended = true
+    // Actually append to the DOM so we can query it later
+    return originalBodyAppendChild(node)
+  })
+
+  vi.spyOn(Element.prototype, 'removeChild').mockImplementation(function (this: Element, child: Node) {
+    // eslint-disable-next-line no-extra-semi
+    ;(child as any)._testRemoved = true
+    return child
+  })
+})
+
+afterAll(() => {
+  vi.restoreAllMocks()
+})
+
+describe('Turnstile Solver Integration Tests', () => {
+  beforeEach(() => {
+    // Configure mock Turnstile API behavior
+    mockTurnstileAPI.ready.mockImplementation((callback: () => void) => {
+      // Call the callback immediately
+      callback()
+    })
+
+    mockTurnstileAPI.render.mockImplementation((container: string | HTMLElement, options: any) => {
+      // Simulate successful render and call the callback with a test token
+      if (options.callback) {
+        setTimeout(() => {
+          options.callback('test-turnstile-solution-token')
+        }, 10) // Small delay to simulate async behavior
+      }
+      return 'widget-123' // Return a mock widget ID
+    })
+  })
+
+  afterEach(() => {
+    // Clean up DOM
+    document.querySelectorAll('div[id^="turnstile-"]').forEach((el) => el.remove())
+
+    // Reset mocks to default successful behavior
+    vi.clearAllMocks()
+    ;(window as any).turnstile = undefined
+
+    // Reset turnstile script loader state for next test
+    resetTurnstileState()
+  })
+
+  it('verifies Turnstile solver basic functionality', async () => {
+    // Create a challenge solver directly to test
+    const turnstileSolver = createTurnstileSolver({ performanceTracker: createMockPerformanceTracker() })
+
+    // Create challenge data with proper structure
+    const challengeData = {
+      challengeId: 'dom-test-challenge-123',
+      challengeType: ChallengeType.TURNSTILE,
+      extra: {
+        challengeData: JSON.stringify({
+          siteKey: '0x4AAAAAABiAHneWOWZHzZtO',
+          action: 'session_verification',
+        }),
+      },
+    }
+
+    // Execute the solver and wait for solution
+    const solution = await turnstileSolver.solve(challengeData)
+
+    // Verify solution was returned
+    expect(solution).toBe('test-turnstile-solution-token')
+
+    // Verify script injection was attempted
+    expect(document.head.appendChild).toHaveBeenCalledWith(
+      expect.objectContaining({
+        src: 'https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit',
+      }),
+    )
+  })
+
+  it('handles Turnstile solver errors properly', async () => {
+    // Configure mock to simulate an error with proper timing
+    mockTurnstileAPI.render.mockImplementation(async (container: string | HTMLElement, options: any) => {
+      if (options['error-callback']) {
+        // Use microtask to ensure promise handlers are set up
+        await Promise.resolve().then(() => {
+          options['error-callback']('NETWORK_ERROR')
+        })
+      }
+      return 'widget-error-123'
+    })
+
+    const turnstileSolver = createTurnstileSolver({ performanceTracker: createMockPerformanceTracker() })
+    const challengeData = {
+      challengeId: 'error-test-123',
+      challengeType: ChallengeType.TURNSTILE,
+      extra: {
+        challengeData: JSON.stringify({
+          siteKey: 'test-site-key',
+          action: 'test-action',
+        }),
+      },
+    }
+
+    // Should reject with Turnstile error
+    await expect(turnstileSolver.solve(challengeData)).rejects.toThrow('Turnstile error: NETWORK_ERROR')
+  })
+
+  it('handles expired tokens', async () => {
+    // Configure mock to simulate token expiration
+    mockTurnstileAPI.render.mockImplementation(async (container: string | HTMLElement, options: any) => {
+      if (options['expired-callback']) {
+        // Use microtask to ensure promise handlers are set up
+        await Promise.resolve().then(() => {
+          options['expired-callback']()
+        })
+      }
+      return 'widget-expired-123'
+    })
+
+    const turnstileSolver = createTurnstileSolver({ performanceTracker: createMockPerformanceTracker() })
+    const challengeData = {
+      challengeId: 'expired-test-123',
+      challengeType: ChallengeType.TURNSTILE,
+      extra: {
+        challengeData: JSON.stringify({
+          siteKey: 'test-site-key',
+          action: 'test-action',
+        }),
+      },
+    }
+
+    // Should reject with expiration error
+    await expect(turnstileSolver.solve(challengeData)).rejects.toThrow('Turnstile token expired')
+  })
+
+  it('handles timeout scenarios', async () => {
+    // Configure mock to never call any callbacks
+    mockTurnstileAPI.render.mockImplementation(() => {
+      // Don't call any callbacks - simulate timeout
+      return 'widget-timeout-123'
+    })
+
+    // Use a short timeout for testing (100ms instead of 30s)
+    const turnstileSolver = createTurnstileSolver({
+      performanceTracker: createMockPerformanceTracker(),
+      timeoutMs: 100,
+    })
+    const challengeData = {
+      challengeId: 'timeout-test-123',
+      challengeType: ChallengeType.TURNSTILE,
+      extra: {
+        challengeData: JSON.stringify({
+          siteKey: 'test-site-key',
+          action: 'test-action',
+        }),
+      },
+    }
+
+    // Should reject with timeout error after 100ms
+    await expect(turnstileSolver.solve(challengeData)).rejects.toThrow('Turnstile challenge timed out after')
+  })
+
+  it('handles missing challenge data', async () => {
+    const turnstileSolver = createTurnstileSolver({ performanceTracker: createMockPerformanceTracker() })
+    const challengeData = {
+      challengeId: 'missing-data-123',
+      challengeType: ChallengeType.TURNSTILE,
+      extra: {}, // Missing challengeData
+    }
+
+    // Should reject with missing data error
+    await expect(turnstileSolver.solve(challengeData)).rejects.toThrow('Missing challengeData in challenge extra')
+  })
+
+  it('handles invalid challenge data JSON', async () => {
+    const turnstileSolver = createTurnstileSolver({ performanceTracker: createMockPerformanceTracker() })
+    const challengeData = {
+      challengeId: 'invalid-json-123',
+      challengeType: ChallengeType.TURNSTILE,
+      extra: {
+        challengeData: 'invalid-json-{',
+      },
+    }
+
+    // Should reject with JSON parse error
+    await expect(turnstileSolver.solve(challengeData)).rejects.toThrow('Failed to parse challengeData')
+  })
+
+  it('handles missing siteKey in challenge data', async () => {
+    const turnstileSolver = createTurnstileSolver({ performanceTracker: createMockPerformanceTracker() })
+    const challengeData = {
+      challengeId: 'missing-sitekey-123',
+      challengeType: ChallengeType.TURNSTILE,
+      extra: {
+        challengeData: JSON.stringify({
+          action: 'test-action',
+          // Missing siteKey
+        }),
+      },
+    }
+
+    // Should reject with missing siteKey error
+    await expect(turnstileSolver.solve(challengeData)).rejects.toThrow('Missing siteKey in challengeData')
+  })
+
+  it('handles script loading failures', async () => {
+    // Mock script loading failure
+    vi.spyOn(document.head, 'appendChild').mockImplementationOnce((node) => {
+      if (node instanceof HTMLScriptElement && node.src.includes('challenges.cloudflare.com')) {
+        setTimeout(() => {
+          if (node.onerror) {
+            node.onerror({} as Event)
+          }
+        }, 0)
+      }
+      return node
+    })
+
+    const turnstileSolver = createTurnstileSolver({ performanceTracker: createMockPerformanceTracker() })
+    const challengeData = {
+      challengeId: 'script-fail-123',
+      challengeType: ChallengeType.TURNSTILE,
+      extra: {
+        challengeData: JSON.stringify({
+          siteKey: 'test-site-key',
+          action: 'test-action',
+        }),
+      },
+    }
+
+    // Should reject with script loading error
+    await expect(turnstileSolver.solve(challengeData)).rejects.toThrow('Failed to load Turnstile script')
+  })
+
+  it('handles multiple concurrent solve requests', async () => {
+    const turnstileSolver = createTurnstileSolver({ performanceTracker: createMockPerformanceTracker() })
+
+    // Create multiple challenge data objects
+    const challenges = Array.from({ length: 3 }, (_, i) => ({
+      challengeId: `concurrent-test-${i}`,
+      challengeType: ChallengeType.TURNSTILE,
+      extra: {
+        challengeData: JSON.stringify({
+          siteKey: `test-site-key-${i}`,
+          action: 'test-action',
+        }),
+      },
+    }))
+
+    // Configure mock to return different tokens for each widget
+    let widgetCounter = 0
+    mockTurnstileAPI.render.mockImplementation((container: string | HTMLElement, options: any) => {
+      const widgetId = `widget-${widgetCounter++}`
+      if (options.callback) {
+        setTimeout(() => {
+          options.callback(`solution-for-${widgetId}`)
+        }, 10)
+      }
+      return widgetId
+    })
+
+    // Execute all solvers concurrently
+    const solutionPromises = challenges.map((challenge) => turnstileSolver.solve(challenge))
+
+    // Wait for all solutions
+    const solutions = await Promise.all(solutionPromises)
+
+    // Verify all solutions are unique
+    expect(solutions).toHaveLength(3)
+    expect(new Set(solutions).size).toBe(3)
+    solutions.forEach((solution) => {
+      expect(solution).toMatch(/^solution-for-widget-\d+$/)
+    })
+  })
+})

package/src/challenge-solvers/types.ts

@@ -0,0 +1,55 @@
+import type { TypedChallengeData } from '@l.x/sessions/src/session-repository/types'
+import type { ChallengeType } from '@l.x/sessions/src/session-service/types'
+
+interface ChallengeData {
+  challengeId: string
+  challengeType: ChallengeType
+  /** @deprecated Use challengeData instead */
+  extra?: Record<string, string>
+  /** Type-safe challenge-specific data (replaces extra) */
+  challengeData?: TypedChallengeData
+}
+
+interface ChallengeSolver {
+  solve(challengeData: ChallengeData): Promise<string>
+}
+
+interface ChallengeSolverService {
+  getSolver(type: ChallengeType): ChallengeSolver | null
+}
+
+/**
+ * Script injection options for CSP compliance and customization
+ */
+interface TurnstileScriptOptions {
+  /**
+   * Custom nonce for the injected script (for CSP compliance)
+   */
+  nonce?: string
+  /**
+   * Whether to set the script as defer
+   * @default false (Turnstile requires synchronous loading for ready())
+   */
+  defer?: boolean
+  /**
+   * Whether to set the script as async
+   * @default false (Turnstile requires synchronous loading for ready())
+   */
+  async?: boolean
+  /**
+   * Custom crossOrigin for the injected script
+   */
+  crossOrigin?: string
+  /**
+   * Custom ID for the injected script
+   * @default "cf-turnstile-script"
+   */
+  id?: string
+  /**
+   * Custom name for the onload callback
+   * @default "onloadTurnstileCallback"
+   */
+  onLoadCallbackName?: string
+}
+
+export type { ChallengeData, ChallengeSolver, ChallengeSolverService, TurnstileScriptOptions }