@l.x/sessions 1.0.3 → 1.0.4

package/src/challenge-solvers/createHashcashSolver.ts

@@ -0,0 +1,270 @@
+import { findProof, type HashcashChallenge } from '@l.x/sessions/src/challenge-solvers/hashcash/core'
+import type { HashcashWorkerChannelFactory } from '@l.x/sessions/src/challenge-solvers/hashcash/worker/types'
+import type { ChallengeData, ChallengeSolver } 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'
+import { z } from 'zod'
+
+/** Error type for analytics classification */
+type HashcashErrorType = 'validation' | 'no_proof' | 'worker_busy' | 'unknown'
+
+/** Base class for hashcash errors with typed errorType for reliable analytics classification */
+class HashcashError extends Error {
+  readonly errorType: HashcashErrorType
+
+  constructor(message: string, errorType: HashcashErrorType) {
+    super(message)
+    this.name = 'HashcashError'
+    this.errorType = errorType
+  }
+}
+
+/** Validation errors (parsing, missing data, invalid challenge format) */
+class HashcashValidationError extends HashcashError {
+  constructor(message: string) {
+    super(message, 'validation')
+    this.name = 'HashcashValidationError'
+  }
+}
+
+/** Proof not found within allowed iterations */
+class HashcashNoProofError extends HashcashError {
+  constructor(message: string) {
+    super(message, 'no_proof')
+    this.name = 'HashcashNoProofError'
+  }
+}
+
+/** Worker is busy processing another request */
+class HashcashWorkerBusyError extends HashcashError {
+  constructor(message: string) {
+    super(message, 'worker_busy')
+    this.name = 'HashcashWorkerBusyError'
+  }
+}
+
+/**
+ * Analytics data for Hashcash solve attempts.
+ * Reported via onSolveCompleted callback.
+ */
+interface HashcashSolveAnalytics {
+  durationMs: number
+  success: boolean
+  errorType?: 'validation' | 'no_proof' | 'worker_busy' | 'unknown'
+  errorMessage?: string
+  /** The difficulty level of the challenge (number of leading zero bytes) */
+  difficulty: number
+  /** Number of hash iterations to find proof (undefined on failure) */
+  iterationCount?: number
+  /** Whether the worker was used for proof computation */
+  usedWorker: boolean
+}
+
+/**
+ * Context for creating a hashcash solver.
+ */
+interface CreateHashcashSolverContext {
+  /**
+   * Required: Performance tracker for timing measurements.
+   * Must be injected - no implicit dependency on globalThis.performance.
+   */
+  performanceTracker: PerformanceTracker
+  /**
+   * Factory function to create a worker channel.
+   * If provided, proof-of-work runs in a Web Worker (non-blocking).
+   * If not provided, falls back to main-thread execution (blocking).
+   */
+  getWorkerChannel?: HashcashWorkerChannelFactory
+  /**
+   * Callback for analytics when solve completes (success or failure)
+   */
+  onSolveCompleted?: (data: HashcashSolveAnalytics) => void
+  /**
+   * Optional logger for operational observability (Datadog).
+   */
+  getLogger?: () => Logger
+}
+
+// Zod schema for hashcash challenge validation
+const HashcashChallengeSchema = z.object({
+  difficulty: z.number().int().nonnegative(),
+  subject: z.string().min(1),
+  algorithm: z.literal('sha256'),
+  nonce: z.string().min(1),
+  max_proof_length: z.number().int().positive().default(1000000),
+  verifier: z.string().optional(),
+})
+
+/**
+ * Parses and validates hashcash challenge data from the backend.
+ * @param challengeDataStr - JSON string containing challenge data
+ * @returns Parsed and validated HashcashChallenge
+ * @throws {Error} If challenge data is invalid or missing required fields
+ */
+function parseHashcashChallenge(challengeDataStr: string): HashcashChallenge {
+  let parsedData: unknown
+  try {
+    parsedData = JSON.parse(challengeDataStr)
+  } catch (error) {
+    throw new HashcashValidationError(`Failed to parse challenge JSON: ${error}`)
+  }
+
+  // Validate with Zod
+  const result = HashcashChallengeSchema.safeParse(parsedData)
+  if (!result.success) {
+    // Get unique field paths from errors
+    const fieldPaths = new Set(
+      result.error.issues.filter((issue) => issue.path.length > 0).map((issue) => issue.path[0]),
+    )
+    if (fieldPaths.size === 1) {
+      // Single field-specific error
+      const fieldName = String(Array.from(fieldPaths)[0])
+      throw new HashcashValidationError(`Invalid challenge data: ${fieldName}`)
+    }
+    // General validation error (multiple fields or form-level errors)
+    throw new HashcashValidationError('Invalid challenge data')
+  }
+
+  return result.data
+}
+
+/**
+ * Classifies error into analytics error type.
+ * Uses instanceof checks for typed errors (preferred), with string matching fallback for external errors.
+ */
+function classifyError(error: unknown): HashcashSolveAnalytics['errorType'] {
+  // Prefer typed error classification via instanceof
+  if (error instanceof HashcashError) {
+    return error.errorType
+  }
+
+  // Fallback to string matching for external or legacy errors
+  if (error instanceof Error) {
+    if (error.message.includes('parse') || error.message.includes('Invalid challenge')) {
+      return 'validation'
+    }
+    if (error.message.includes('Missing challengeData')) {
+      return 'validation'
+    }
+    if (error.message.includes('Failed to find valid proof')) {
+      return 'no_proof'
+    }
+    if (error.message.includes('busy')) {
+      return 'worker_busy'
+    }
+  }
+  return 'unknown'
+}
+
+/**
+ * Creates a real hashcash challenge solver that performs proof-of-work
+ * to solve hashcash challenges from the backend.
+ *
+ * @param ctx - Required context with performanceTracker and optional getWorkerChannel
+ */
+function createHashcashSolver(ctx: CreateHashcashSolverContext): ChallengeSolver {
+  const usedWorker = !!ctx.getWorkerChannel
+
+  async function solve(challengeData: ChallengeData): Promise<string> {
+    const startTime = ctx.performanceTracker.now()
+    let difficulty = 0 // Default, will be updated after parsing
+
+    try {
+      let challenge: HashcashChallenge
+
+      // Prefer typed challengeData over legacy extra field
+      if (challengeData.challengeData?.case === 'hashcash') {
+        const typed = challengeData.challengeData.value
+        challenge = {
+          difficulty: typed.difficulty,
+          subject: typed.subject,
+          algorithm: typed.algorithm as 'sha256',
+          nonce: typed.nonce,
+          max_proof_length: typed.maxProofLength,
+          verifier: typed.verifier,
+        }
+      } else {
+        // Fallback to legacy extra field
+        const challengeDataStr = challengeData.extra?.['challengeData']
+        if (!challengeDataStr) {
+          throw new HashcashValidationError('Missing challengeData in challenge extra field')
+        }
+        challenge = parseHashcashChallenge(challengeDataStr)
+      }
+
+      difficulty = challenge.difficulty
+
+      const findProofParams = {
+        challenge,
+        rangeStart: 0,
+        rangeSize: challenge.max_proof_length,
+      }
+
+      // Use worker if provided, otherwise fall back to main thread
+      let proof
+      if (ctx.getWorkerChannel) {
+        const workerChannel = ctx.getWorkerChannel()
+        try {
+          proof = await workerChannel.api.findProof(findProofParams)
+        } finally {
+          workerChannel.terminate()
+        }
+      } else {
+        // Fallback to main-thread execution (still async for Web Crypto)
+        proof = await findProof(findProofParams)
+      }
+
+      if (!proof) {
+        throw new HashcashNoProofError(
+          `Failed to find valid proof within allowed range (0-${challenge.max_proof_length}). ` +
+            'Challenge may have expired or difficulty may be too high.',
+        )
+      }
+
+      // Report success
+      const data: HashcashSolveAnalytics = {
+        durationMs: ctx.performanceTracker.now() - startTime,
+        success: true,
+        difficulty,
+        iterationCount: proof.attempts,
+        usedWorker,
+      }
+      ctx.onSolveCompleted?.(data)
+      ctx.getLogger?.().info('sessions', 'hashcashSolved', 'Hashcash solve completed', data)
+
+      // Return the solution in the format expected by backend: "${subject}:${nonce}:${counter}"
+      return `${challenge.subject}:${challenge.nonce}:${proof.counter}`
+    } catch (error) {
+      // Report failure
+      const data: HashcashSolveAnalytics = {
+        durationMs: ctx.performanceTracker.now() - startTime,
+        success: false,
+        errorType: classifyError(error),
+        errorMessage: error instanceof Error ? error.message : String(error),
+        difficulty,
+        usedWorker,
+      }
+      ctx.onSolveCompleted?.(data)
+      ctx.getLogger?.().warn('sessions', 'hashcashSolved', 'Hashcash solve failed', data)
+      ctx.getLogger?.().error(error, {
+        tags: {
+          file: 'createHashcashSolver.ts',
+          function: 'solve',
+        },
+      })
+      throw error
+    }
+  }
+
+  return { solve }
+}
+
+export {
+  createHashcashSolver,
+  parseHashcashChallenge,
+  HashcashError,
+  HashcashValidationError,
+  HashcashNoProofError,
+  HashcashWorkerBusyError,
+}
+export type { HashcashSolveAnalytics, CreateHashcashSolverContext }

package/src/challenge-solvers/createNoneMockSolver.ts

@@ -0,0 +1,11 @@
+import type { ChallengeData, ChallengeSolver } from '@l.x/sessions/src/challenge-solvers/types'
+
+function createNoneMockSolver(): ChallengeSolver {
+  async function solve(_challengeData: ChallengeData): Promise<string> {
+    return ''
+  }
+
+  return { solve }
+}
+
+export { createNoneMockSolver }

package/src/challenge-solvers/createTurnstileMockSolver.ts

@@ -0,0 +1,30 @@
+import type { ChallengeData, ChallengeSolver } from '@l.x/sessions/src/challenge-solvers/types'
+import { sleep } from 'utilities/src/time/timing'
+
+/**
+ * Creates a mock Turnstile challenge solver for development/testing
+ *
+ * In production, this would integrate with Cloudflare Turnstile:
+ * - Load Turnstile script
+ * - Render widget with sitekey from challengeData.extra
+ * - Return actual token from Turnstile API
+ */
+function createTurnstileMockSolver(): ChallengeSolver {
+  async function solve(challengeData: ChallengeData): Promise<string> {
+    // Simulate widget render delay
+    await sleep(300)
+
+    // Simulate challenge solving time (random between 200-500ms)
+    const solvingTime = 200 + Math.random() * 300
+    await sleep(solvingTime)
+
+    // Return mock Turnstile token
+    const timestamp = Date.now()
+    const challengeIdPrefix = challengeData.challengeId.slice(0, 8)
+    return `mock_turnstile_token_${timestamp}_${challengeIdPrefix}`
+  }
+
+  return { solve }
+}
+
+export { createTurnstileMockSolver }

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')
+}