@l.x/sessions 1.0.3 → 1.0.5

package/src/challenge-solvers/createTurnstileSolver.ts

@@ -0,0 +1,357 @@
+import {
+  TurnstileApiNotAvailableError,
+  TurnstileError,
+  TurnstileScriptLoadError,
+  TurnstileTimeoutError,
+  TurnstileTokenExpiredError,
+} from '@l.x/sessions/src/challenge-solvers/turnstileErrors'
+import { ensureTurnstileScript } from '@l.x/sessions/src/challenge-solvers/turnstileScriptLoader'
+import type {
+  ChallengeData,
+  ChallengeSolver,
+  TurnstileScriptOptions,
+} from '@l.x/sessions/src/challenge-solvers/types'
+import type { PerformanceTracker } from '@l.x/sessions/src/performance/types'
+import type { Logger } from 'utilities/src/logger/logger'
+
+/**
+ * Analytics data for Turnstile solve attempts.
+ * Reported via onSolveCompleted callback.
+ */
+interface TurnstileSolveAnalytics {
+  durationMs: number
+  success: boolean
+  errorType?: 'timeout' | 'script_load' | 'network' | 'validation' | 'unknown'
+  errorMessage?: string
+}
+
+// Declare Turnstile types inline to avoid import issues
+interface TurnstileWidget {
+  render: (container: string | HTMLElement, options: TurnstileOptions) => string
+  remove: (widgetId: string) => void
+  reset: (widgetId: string) => void
+  getResponse: (widgetId: string) => string | undefined
+  ready: (callback: () => void) => void
+}
+
+interface TurnstileOptions {
+  sitekey: string
+  action?: string
+  theme?: 'light' | 'dark' | 'auto'
+  size?: 'normal' | 'compact' | 'flexible'
+  callback?: (token: string) => void
+  'error-callback'?: (error: string) => void
+  'expired-callback'?: () => void
+}
+
+// Extend the Window interface to include turnstile
+declare global {
+  interface Window {
+    turnstile?: TurnstileWidget
+  }
+}
+
+interface CreateTurnstileSolverContext {
+  /**
+   * Required: Performance tracker for timing measurements.
+   * Must be injected - no implicit dependency on globalThis.performance.
+   */
+  performanceTracker: PerformanceTracker
+  /**
+   * Optional logger for debugging
+   */
+  getLogger?: () => Logger
+  /**
+   * Optional script injection options for CSP compliance
+   */
+  scriptOptions?: TurnstileScriptOptions
+  /**
+   * Widget rendering timeout in milliseconds
+   * @default 30000
+   */
+  timeoutMs?: number
+  /**
+   * Callback for analytics when solve completes (success or failure)
+   */
+  onSolveCompleted?: (data: TurnstileSolveAnalytics) => void
+}
+
+/**
+ * Classifies error into analytics error type
+ */
+function classifyError(error: unknown): TurnstileSolveAnalytics['errorType'] {
+  if (error instanceof TurnstileTimeoutError || error instanceof TurnstileTokenExpiredError) {
+    return 'timeout'
+  }
+  if (error instanceof TurnstileScriptLoadError || error instanceof TurnstileApiNotAvailableError) {
+    return 'script_load'
+  }
+  if (error instanceof TurnstileError) {
+    return 'network'
+  }
+  if (error instanceof Error && error.message.includes('parse')) {
+    return 'validation'
+  }
+  if (error instanceof Error && error.message.includes('Missing')) {
+    return 'validation'
+  }
+  return 'unknown'
+}
+
+/**
+ * Creates a Turnstile challenge solver.
+ *
+ * This integrates with Cloudflare Turnstile using explicit rendering:
+ * - Dynamically loads Turnstile script if not present (with state management)
+ * - Creates a temporary DOM container
+ * - Renders widget with sitekey and action from challengeData.extra
+ * - Returns the verification token from Turnstile API
+ *
+ * Features:
+ * - Separation of concerns: Script loading separated from widget rendering
+ * - Dependency injection: Logger and script options injected via context
+ * - Contract-based design: Implements ChallengeSolver interface
+ * - Factory pattern: Returns solver instance, not component
+ */
+function createTurnstileSolver(ctx: CreateTurnstileSolverContext): ChallengeSolver {
+  async function solve(challengeData: ChallengeData): Promise<string> {
+    const startTime = ctx.performanceTracker.now()
+
+    ctx.getLogger?.().debug('createTurnstileSolver', 'solve', 'Solving Turnstile challenge', { challengeData })
+
+    // Extract challenge data — prefer typed challengeData over legacy extra field
+    let siteKey: string
+    let action: string | undefined
+
+    if (challengeData.challengeData?.case === 'turnstile') {
+      siteKey = challengeData.challengeData.value.siteKey
+      action = challengeData.challengeData.value.action
+    } else {
+      // Fallback to legacy extra field
+      const challengeDataStr = challengeData.extra?.['challengeData']
+      if (!challengeDataStr) {
+        const error = new Error('Missing challengeData in challenge extra')
+        ctx.onSolveCompleted?.({
+          durationMs: ctx.performanceTracker.now() - startTime,
+          success: false,
+          errorType: 'validation',
+          errorMessage: error.message,
+        })
+        throw error
+      }
+
+      let parsedData: { siteKey: string; action: string }
+      try {
+        parsedData = JSON.parse(challengeDataStr)
+      } catch (error) {
+        const parseError = new Error('Failed to parse challengeData', { cause: error })
+        ctx.onSolveCompleted?.({
+          durationMs: ctx.performanceTracker.now() - startTime,
+          success: false,
+          errorType: 'validation',
+          errorMessage: parseError.message,
+        })
+        throw parseError
+      }
+
+      siteKey = parsedData.siteKey
+      action = parsedData.action
+    }
+
+    if (!siteKey) {
+      const error = new Error('Missing siteKey in challengeData')
+      ctx.onSolveCompleted?.({
+        durationMs: ctx.performanceTracker.now() - startTime,
+        success: false,
+        errorType: 'validation',
+        errorMessage: error.message,
+      })
+      throw error
+    }
+
+    ctx.getLogger?.().debug('createTurnstileSolver', 'solve', 'Parsed challengeData', { siteKey, action })
+
+    await ensureTurnstileScript(ctx.scriptOptions)
+
+    ctx.getLogger?.().debug('createTurnstileSolver', 'solve', 'Turnstile script loaded')
+
+    // Verify Turnstile API is available
+    if (!window.turnstile) {
+      const error = new TurnstileApiNotAvailableError()
+      ctx.onSolveCompleted?.({
+        durationMs: ctx.performanceTracker.now() - startTime,
+        success: false,
+        errorType: 'script_load',
+        errorMessage: error.message,
+      })
+      throw error
+    }
+
+    // Create temporary container for the widget
+    const containerId = `turnstile-${challengeData.challengeId}`
+    const container = document.createElement('div')
+    container.id = containerId
+    container.style.position = 'fixed'
+    container.style.top = '-9999px' // Hide off-screen
+    container.style.left = '-9999px'
+    container.setAttribute('aria-hidden', 'true') // Accessibility
+    document.body.appendChild(container)
+
+    const timeoutMs = ctx.timeoutMs ?? 30000
+    const cleanupState = {
+      timeoutId: null as ReturnType<typeof setTimeout> | null,
+      widgetId: null as string | null,
+    }
+
+    try {
+      // Wait for Turnstile to be ready and render widget
+      const token = await new Promise<string>((resolve, reject) => {
+        // Set up timeout with proper cleanup
+        cleanupState.timeoutId = setTimeout(() => {
+          if (cleanupState.widgetId && window.turnstile) {
+            try {
+              window.turnstile.remove(cleanupState.widgetId)
+            } catch {
+              // Ignore cleanup errors
+            }
+          }
+          reject(new TurnstileTimeoutError(timeoutMs))
+        }, timeoutMs)
+
+        // Helper function to render the widget
+        const renderWidget = (): void => {
+          if (!window.turnstile) {
+            reject(new TurnstileApiNotAvailableError())
+            return
+          }
+
+          try {
+            cleanupState.widgetId = window.turnstile.render(container, {
+              sitekey: siteKey,
+              action,
+              theme: 'light',
+              size: 'normal',
+              callback: (tokenValue: string) => {
+                if (cleanupState.timeoutId) {
+                  clearTimeout(cleanupState.timeoutId)
+                  cleanupState.timeoutId = null
+                }
+                ctx.getLogger?.().debug('createTurnstileSolver', 'solve', 'Turnstile token resolved', {
+                  tokenValue,
+                })
+                resolve(tokenValue)
+              },
+              'error-callback': (error: string) => {
+                if (cleanupState.timeoutId) {
+                  clearTimeout(cleanupState.timeoutId)
+                  cleanupState.timeoutId = null
+                }
+                ctx.getLogger?.().debug('createTurnstileSolver', 'solve', 'Turnstile error', { error })
+                reject(new TurnstileError(error))
+              },
+              'expired-callback': () => {
+                if (cleanupState.timeoutId) {
+                  clearTimeout(cleanupState.timeoutId)
+                  cleanupState.timeoutId = null
+                }
+                ctx.getLogger?.().debug('createTurnstileSolver', 'solve', 'Turnstile token expired')
+                reject(new TurnstileTokenExpiredError())
+              },
+            })
+
+            ctx.getLogger?.().debug('createTurnstileSolver', 'solve', 'Turnstile widget rendered', {
+              widgetId: cleanupState.widgetId,
+            })
+          } catch (error) {
+            if (cleanupState.timeoutId) {
+              clearTimeout(cleanupState.timeoutId)
+              cleanupState.timeoutId = null
+            }
+            ctx.getLogger?.().error(error, {
+              tags: {
+                file: 'createTurnstileSolver.ts',
+                function: 'solve',
+              },
+            })
+            reject(
+              new TurnstileError(`Failed to render widget: ${error instanceof Error ? error.message : String(error)}`),
+            )
+          }
+        }
+
+        if (!window.turnstile) {
+          reject(new TurnstileApiNotAvailableError())
+          return
+        }
+
+        try {
+          window.turnstile.ready(() => {
+            renderWidget()
+          })
+        } catch (error) {
+          // Fallback: render directly if ready() throws
+          ctx.getLogger?.().debug('createTurnstileSolver', 'solve', 'turnstile.ready() failed, rendering directly', {
+            error: error instanceof Error ? error.message : String(error),
+          })
+          renderWidget()
+        }
+      })
+
+      // Report success
+      const data: TurnstileSolveAnalytics = {
+        durationMs: ctx.performanceTracker.now() - startTime,
+        success: true,
+      }
+      ctx.onSolveCompleted?.(data)
+      ctx.getLogger?.().info('sessions', 'turnstileSolved', 'Turnstile solve completed', data)
+
+      return token
+    } catch (error) {
+      // Report failure
+      const data: TurnstileSolveAnalytics = {
+        durationMs: ctx.performanceTracker.now() - startTime,
+        success: false,
+        errorType: classifyError(error),
+        errorMessage: error instanceof Error ? error.message : String(error),
+      }
+      ctx.onSolveCompleted?.(data)
+      ctx.getLogger?.().warn('sessions', 'turnstileSolved', 'Turnstile solve failed', data)
+
+      ctx.getLogger?.().error(error, {
+        tags: {
+          file: 'createTurnstileSolver.ts',
+          function: 'solve',
+        },
+      })
+      throw error
+    } finally {
+      // Clean up timeout
+      if (cleanupState.timeoutId) {
+        clearTimeout(cleanupState.timeoutId)
+      }
+
+      // Clean up widget if it was created
+      // widgetId only exists if turnstile was successfully loaded and rendered
+      if (cleanupState.widgetId) {
+        try {
+          // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+          if (window.turnstile) {
+            window.turnstile.remove(cleanupState.widgetId)
+          }
+        } catch {
+          // Ignore cleanup errors
+        }
+      }
+
+      // Clean up container
+      if (container.parentNode) {
+        container.parentNode.removeChild(container)
+      }
+    }
+  }
+
+  return { solve }
+}
+
+export { createTurnstileSolver }
+export type { CreateTurnstileSolverContext, TurnstileSolveAnalytics }

package/src/challenge-solvers/hashcash/core.native.ts

@@ -0,0 +1,34 @@
+/**
+ * Native stub for hashcash core functions.
+ *
+ * Mobile does not use this file - it uses native Nitro modules
+ * (hashcash-native package) which bypass the JS hashcash implementation entirely.
+ *
+ * @see packages/hashcash-native for the native implementation
+ */
+
+import { NotImplementedError } from 'utilities/src/errors'
+
+export type { HashcashChallenge, ProofResult } from '@l.x/sessions/src/challenge-solvers/hashcash/shared'
+// Re-export shared types and platform-agnostic functions
+export { checkDifficulty, formatHashcashString } from '@l.x/sessions/src/challenge-solvers/hashcash/shared'
+
+import type { HashcashChallenge, ProofResult } from '@l.x/sessions/src/challenge-solvers/hashcash/shared'
+
+export async function computeHash(_params: { subject: string; nonce: string; counter: number }): Promise<Uint8Array> {
+  throw new NotImplementedError('computeHash - mobile uses native Nitro modules')
+}
+
+export async function findProof(_params: {
+  challenge: HashcashChallenge
+  rangeStart?: number
+  rangeSize?: number
+  shouldStop?: () => boolean
+  batchSize?: number
+}): Promise<ProofResult | null> {
+  throw new NotImplementedError('findProof - mobile uses native Nitro modules')
+}
+
+export async function verifyProof(_challenge: HashcashChallenge, _proofCounter: string): Promise<boolean> {
+  throw new NotImplementedError('verifyProof - mobile uses native Nitro modules')
+}

package/src/challenge-solvers/hashcash/core.test.ts

@@ -0,0 +1,314 @@
+import {
+  checkDifficulty,
+  computeHash,
+  findProof,
+  formatHashcashString,
+  type HashcashChallenge,
+  verifyProof,
+} from '@l.x/sessions/src/challenge-solvers/hashcash/core'
+import { describe, expect, it } from 'vitest'
+
+describe('hashcash core', () => {
+  // Backend example data for testing
+  const backendExample: HashcashChallenge = {
+    difficulty: 1,
+    subject: 'Lx',
+    algorithm: 'sha256',
+    nonce: 'Qlquffem7d8RrL6fmveE68XK0KxcoczdiVpFrV1qeUk=',
+    max_proof_length: 1000,
+  }
+
+  // Basic smoke test
+  it('exports all required functions', () => {
+    expect(checkDifficulty).toBeDefined()
+    expect(computeHash).toBeDefined()
+    expect(findProof).toBeDefined()
+    expect(verifyProof).toBeDefined()
+    expect(formatHashcashString).toBeDefined()
+  })
+
+  describe('checkDifficulty', () => {
+    it('validates difficulty 1 (1 full zero byte)', () => {
+      // Backend treats difficulty as number of zero BYTES
+      // difficulty=1 means first byte must be 0
+      const validHash = new Uint8Array([0, 255, 255, 255])
+      expect(checkDifficulty(validHash, 1)).toBe(true)
+
+      const invalidHash = new Uint8Array([1, 255, 255, 255])
+      expect(checkDifficulty(invalidHash, 1)).toBe(false)
+
+      const invalidHash2 = new Uint8Array([0b00000001, 255, 255, 255]) // Even 1 bit set fails
+      expect(checkDifficulty(invalidHash2, 1)).toBe(false)
+    })
+
+    it('validates difficulty 2 (2 full zero bytes)', () => {
+      // First two bytes must be all zeros
+      const validHash = new Uint8Array([0, 0, 255, 255])
+      expect(checkDifficulty(validHash, 2)).toBe(true)
+
+      const invalidHash = new Uint8Array([0, 1, 255, 255]) // Second byte not zero
+      expect(checkDifficulty(invalidHash, 2)).toBe(false)
+    })
+
+    it('validates difficulty 0 (no requirement)', () => {
+      const anyHash = new Uint8Array([255, 255, 255, 255])
+      expect(checkDifficulty(anyHash, 0)).toBe(true)
+    })
+  })
+
+  describe('computeHash', () => {
+    it('produces consistent SHA-256 hashes', async () => {
+      const params = {
+        subject: 'test',
+        nonce: 'AQIDBA==', // Base64 string
+        counter: 42,
+      }
+
+      const hash1 = await computeHash(params)
+      const hash2 = await computeHash(params)
+
+      expect(hash1).toEqual(hash2)
+      expect(hash1.length).toBe(32) // SHA-256 is 32 bytes
+    })
+
+    it('works with real backend nonce', async () => {
+      const hash = await computeHash({
+        subject: backendExample.subject,
+        nonce: backendExample.nonce, // Use nonce string directly
+        counter: 0,
+      })
+
+      expect(hash).toBeDefined()
+      expect(hash.length).toBe(32)
+    })
+
+    it('hashes colon-separated string format like backend', async () => {
+      // Test that we're using the backend's expected format: "${subject}:${nonce}:${counter}"
+      const nonceString = 'AQIDBA=='
+
+      const hash = await computeHash({
+        subject: 'Lx',
+        nonce: nonceString,
+        counter: 123,
+      })
+
+      // The hash should be of the string "Lx:AQIDBA==:123"
+      expect(hash).toBeDefined()
+      expect(hash.length).toBe(32)
+
+      // Verify the expected string format
+      const expectedString = `Lx:${nonceString}:123`
+      expect(expectedString).toBe('Lx:AQIDBA==:123')
+    })
+
+    it('matches known SHA-256 test vector', async () => {
+      // computeHash("Lx:AQIDBA==:123") verified against @noble/hashes/webcrypto SHA-256
+      const hash = await computeHash({
+        subject: 'Lx',
+        nonce: 'AQIDBA==',
+        counter: 123,
+      })
+
+      const expectedHex = '222c2db479a1ff907a329fc3ff8e99b1f19f0695d938b74ccd95323b9c853510'
+      const actualHex = Array.from(hash)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('')
+
+      expect(actualHex).toBe(expectedHex)
+    })
+  })
+
+  describe('findProof', () => {
+    it('finds a valid proof for difficulty 1', async () => {
+      const challenge: HashcashChallenge = {
+        ...backendExample,
+        difficulty: 1,
+        max_proof_length: 10000, // Increase range for testing
+      }
+
+      const proof = await findProof({ challenge })
+
+      expect(proof).not.toBeNull()
+      if (proof) {
+        expect(proof.counter).toBeDefined()
+        expect(proof.hash).toBeDefined()
+        expect(proof.attempts).toBeGreaterThan(0)
+        expect(checkDifficulty(proof.hash, 1)).toBe(true)
+      }
+    })
+
+    it('respects max_proof_length limit', async () => {
+      const challenge: HashcashChallenge = {
+        ...backendExample,
+        difficulty: 20, // High difficulty unlikely to be found
+        max_proof_length: 100,
+      }
+
+      const proof = await findProof({
+        challenge,
+        rangeSize: challenge.max_proof_length,
+      })
+
+      // Should return null since difficulty 20 (20 zero bytes) is impossible in 100 attempts
+      expect(proof).toBeNull()
+    })
+
+    it('returns null when shouldStop signals cancellation', async () => {
+      let calls = 0
+      const shouldStop = (): boolean => {
+        calls++
+        // Stop after the first batch boundary check
+        return calls >= 2
+      }
+
+      const challenge: HashcashChallenge = {
+        ...backendExample,
+        difficulty: 20, // High difficulty so it won't find a proof naturally
+        max_proof_length: 100_000,
+      }
+
+      const proof = await findProof({
+        challenge,
+        shouldStop,
+        batchSize: 64,
+      })
+
+      expect(proof).toBeNull()
+      // shouldStop was called at least twice (once to pass, once to cancel)
+      expect(calls).toBeGreaterThanOrEqual(2)
+    })
+
+    it('finds proof with custom rangeStart', async () => {
+      // First, find a valid proof starting from 0
+      const challenge: HashcashChallenge = {
+        ...backendExample,
+        difficulty: 1,
+        max_proof_length: 10000,
+      }
+
+      const baseProof = await findProof({ challenge })
+      expect(baseProof).not.toBeNull()
+
+      if (baseProof) {
+        const knownCounter = parseInt(baseProof.counter)
+
+        // Now search again starting from that known counter
+        const proof = await findProof({
+          challenge,
+          rangeStart: knownCounter,
+          rangeSize: 1, // Only check the one counter
+        })
+
+        expect(proof).not.toBeNull()
+        expect(proof!.counter).toBe(knownCounter.toString())
+      }
+    })
+  })
+
+  describe('verifyProof', () => {
+    it('verifies a valid proof', async () => {
+      const challenge: HashcashChallenge = {
+        ...backendExample,
+        difficulty: 1,
+        max_proof_length: 10000,
+      }
+
+      // First find a proof
+      const proof = await findProof({ challenge })
+      expect(proof).not.toBeNull()
+
+      if (proof) {
+        // Then verify it
+        const isValid = await verifyProof(challenge, proof.counter)
+        expect(isValid).toBe(true)
+      }
+    })
+
+    it('rejects an invalid proof', async () => {
+      // Test with non-numeric counter (always invalid)
+      expect(await verifyProof(backendExample, 'not-a-number')).toBe(false)
+
+      // Test with higher difficulty where most counters are invalid
+      const higherDifficultyChallenge = {
+        ...backendExample,
+        difficulty: 16, // 2 full zero bytes required
+      }
+
+      // This counter is very unlikely to produce 2 zero bytes
+      const isValid = await verifyProof(higherDifficultyChallenge, '12345')
+      expect(isValid).toBe(false)
+    })
+  })
+
+  describe('formatHashcashString', () => {
+    it('formats hashcash string correctly', () => {
+      const proof = {
+        counter: '123',
+        hash: new Uint8Array(32).fill(0),
+        attempts: 123,
+        timeMs: 10,
+      }
+
+      const formatted = formatHashcashString(backendExample, proof)
+
+      // Check format: version:bits:date:resource:extension:counter:hash
+      const parts = formatted.split(':')
+
+      expect(parts.length).toBe(7)
+      expect(parts[0]).toBe('1') // Version
+      expect(parts[1]).toBe('1') // Difficulty
+      expect(parts[2]).toMatch(/^\d{6}$/) // Date format YYMMDD (always 6 digits)
+      expect(parts[3]).toBe('Lx') // Resource
+      expect(parts[4]).toBe('') // Extension (empty)
+      expect(parts[5]).toBe('123') // Counter
+      expect(parts[6]).toMatch(/^[A-Za-z0-9+/=]+$/) // Base64 hash
+    })
+  })
+
+  describe('integration with backend example', () => {
+    it('completes full hashcash flow with real backend data', async () => {
+      const challenge: HashcashChallenge = {
+        ...backendExample,
+        max_proof_length: 10000, // Give enough range to find solution
+      }
+
+      // Step 1: Find proof
+      const proof = await findProof({ challenge })
+      expect(proof).not.toBeNull()
+
+      if (proof) {
+        // Step 2: Verify the proof is valid
+        const isValid = await verifyProof(challenge, proof.counter)
+        expect(isValid).toBe(true)
+
+        // Step 3: Check the hash meets difficulty requirement
+        expect(checkDifficulty(proof.hash, challenge.difficulty)).toBe(true)
+
+        // Step 4: Format for submission
+        const hashcashString = formatHashcashString(challenge, proof)
+        expect(hashcashString).toBeTruthy()
+
+        // Verify format includes our subject
+        expect(hashcashString).toContain('Lx')
+      }
+    })
+
+    it('handles backend difficulty vs verifier discrepancy', async () => {
+      // The backend example shows difficulty: 1
+      // But the verifier checks: hash.slice(0,1).every(x => x === 0)
+      // which actually requires the first byte to be 0 (difficulty 8)
+
+      const challenge = backendExample
+      const proof = await findProof({
+        challenge,
+        rangeSize: 10000,
+      })
+
+      if (proof) {
+        // Check our difficulty 1 validation
+        const meetsSpecifiedDifficulty = checkDifficulty(proof.hash, 1)
+        expect(meetsSpecifiedDifficulty).toBe(true)
+      }
+    })
+  })
+})