@l.x/sessions 1.0.3 → 1.0.5

package/src/challenge-solvers/createHashcashSolver.test.ts

@@ -0,0 +1,385 @@
+import { ChallengeType } from '@luxamm/client-platform-service/dist/lx/platformservice/v1/sessionService_pb'
+import { createHashcashSolver } from '@l.x/sessions/src/challenge-solvers/createHashcashSolver'
+import type { HashcashWorkerChannel } from '@l.x/sessions/src/challenge-solvers/hashcash/worker/types'
+import type { ChallengeData } from '@l.x/sessions/src/challenge-solvers/types'
+import type { PerformanceTracker } from '@l.x/sessions/src/performance/types'
+import { describe, expect, it, vi } from 'vitest'
+
+// Mock performance tracker for testing
+function createMockPerformanceTracker(): PerformanceTracker {
+  let time = 0
+  return {
+    now: (): number => {
+      time += 100
+      return time
+    },
+  }
+}
+
+describe('createHashcashSolver', () => {
+  const mockPerformanceTracker = createMockPerformanceTracker()
+  const solver = createHashcashSolver({ performanceTracker: mockPerformanceTracker })
+
+  // Real backend example data
+  const backendExample = {
+    difficulty: 1,
+    subject: 'Lx',
+    algorithm: 'sha256' as const,
+    nonce: 'Qlquffem7d8RrL6fmveE68XK0KxcoczdiVpFrV1qeUk=',
+    max_proof_length: 10000,
+  }
+
+  it('successfully solves a valid challenge', async () => {
+    const challengeData: ChallengeData = {
+      challengeId: 'test-challenge-123',
+      challengeType: ChallengeType.HASHCASH,
+      extra: {
+        challengeData: JSON.stringify(backendExample),
+      },
+    }
+
+    const solution = await solver.solve(challengeData)
+
+    // Check format: "${subject}:${nonce}:${counter}"
+    expect(solution).toMatch(/^Lx:[A-Za-z0-9+/=]+:\d+$/)
+    expect(solution.startsWith('Lx:')).toBe(true)
+    expect(solution).toContain(backendExample.nonce) // Should contain the base64 nonce
+
+    // Verify the solution has all three parts
+    const parts = solution.split(':')
+    expect(parts.length).toBe(3)
+    expect(parts[0]).toBe('Lx')
+    expect(parts[1]).toBe(backendExample.nonce)
+    expect(Number.parseInt(parts[2], 10)).toBeGreaterThanOrEqual(0)
+  })
+
+  it('throws error when challengeData is missing', async () => {
+    const challengeData: ChallengeData = {
+      challengeId: 'test-challenge-123',
+      challengeType: ChallengeType.HASHCASH,
+      extra: {}, // Missing challengeData
+    }
+
+    await expect(solver.solve(challengeData)).rejects.toThrow('Missing challengeData in challenge extra field')
+  })
+
+  it('throws error when challengeData is not valid JSON', async () => {
+    const challengeData: ChallengeData = {
+      challengeId: 'test-challenge-123',
+      challengeType: ChallengeType.HASHCASH,
+      extra: {
+        challengeData: 'not-valid-json{',
+      },
+    }
+
+    await expect(solver.solve(challengeData)).rejects.toThrow('Failed to parse challenge JSON')
+  })
+
+  it('throws error when required fields are missing', async () => {
+    const invalidChallenge = {
+      difficulty: 1,
+      // Missing: nonce, subject, algorithm
+    }
+
+    const challengeData: ChallengeData = {
+      challengeId: 'test-challenge-123',
+      challengeType: ChallengeType.HASHCASH,
+      extra: {
+        challengeData: JSON.stringify(invalidChallenge),
+      },
+    }
+
+    // Zod will report all missing fields at once
+    await expect(solver.solve(challengeData)).rejects.toThrow('Invalid challenge data')
+  })
+
+  it('throws error when algorithm is not sha256', async () => {
+    const invalidChallenge = {
+      ...backendExample,
+      algorithm: 'sha512' as any, // Wrong algorithm
+    }
+
+    const challengeData: ChallengeData = {
+      challengeId: 'test-challenge-123',
+      challengeType: ChallengeType.HASHCASH,
+      extra: {
+        challengeData: JSON.stringify(invalidChallenge),
+      },
+    }
+
+    // Zod will report the literal mismatch
+    await expect(solver.solve(challengeData)).rejects.toThrow('Invalid challenge data: algorithm')
+  })
+
+  it('handles high difficulty that cannot be solved', async () => {
+    const impossibleChallenge = {
+      ...backendExample,
+      difficulty: 30, // Very high difficulty
+      max_proof_length: 10, // Very small search space
+    }
+
+    const challengeData: ChallengeData = {
+      challengeId: 'test-challenge-123',
+      challengeType: ChallengeType.HASHCASH,
+      extra: {
+        challengeData: JSON.stringify(impossibleChallenge),
+      },
+    }
+
+    await expect(solver.solve(challengeData)).rejects.toThrow('Failed to find valid proof within allowed range')
+  })
+
+  it('handles missing extra field gracefully', async () => {
+    const challengeData: ChallengeData = {
+      challengeId: 'test-challenge-123',
+      challengeType: ChallengeType.HASHCASH,
+      // No extra field at all
+    }
+
+    await expect(solver.solve(challengeData)).rejects.toThrow('Missing challengeData in challenge extra field')
+  })
+
+  describe('analytics callback', () => {
+    it('reports success with difficulty and iteration count', async () => {
+      const onSolveCompleted = vi.fn()
+      const solverWithAnalytics = createHashcashSolver({
+        performanceTracker: createMockPerformanceTracker(),
+        onSolveCompleted,
+      })
+
+      const challengeData: ChallengeData = {
+        challengeId: 'test-challenge-123',
+        challengeType: ChallengeType.HASHCASH,
+        extra: {
+          challengeData: JSON.stringify(backendExample),
+        },
+      }
+
+      await solverWithAnalytics.solve(challengeData)
+
+      expect(onSolveCompleted).toHaveBeenCalledWith(
+        expect.objectContaining({
+          success: true,
+          difficulty: 1,
+          usedWorker: false,
+        }),
+      )
+      expect(onSolveCompleted.mock.calls[0][0].iterationCount).toBeGreaterThan(0)
+      expect(onSolveCompleted.mock.calls[0][0].durationMs).toBeGreaterThanOrEqual(0)
+    })
+
+    it('reports failure with validation error type', async () => {
+      const onSolveCompleted = vi.fn()
+      const solverWithAnalytics = createHashcashSolver({
+        performanceTracker: createMockPerformanceTracker(),
+        onSolveCompleted,
+      })
+
+      const challengeData: ChallengeData = {
+        challengeId: 'test-challenge-123',
+        challengeType: ChallengeType.HASHCASH,
+        extra: {}, // Missing challengeData
+      }
+
+      await expect(solverWithAnalytics.solve(challengeData)).rejects.toThrow()
+
+      expect(onSolveCompleted).toHaveBeenCalledWith(
+        expect.objectContaining({
+          success: false,
+          errorType: 'validation',
+          usedWorker: false,
+        }),
+      )
+    })
+
+    it('reports failure when proof cannot be found', async () => {
+      const onSolveCompleted = vi.fn()
+      const solverWithAnalytics = createHashcashSolver({
+        performanceTracker: createMockPerformanceTracker(),
+        onSolveCompleted,
+      })
+
+      const impossibleChallenge = {
+        ...backendExample,
+        difficulty: 30,
+        max_proof_length: 10,
+      }
+
+      const challengeData: ChallengeData = {
+        challengeId: 'test-challenge-123',
+        challengeType: ChallengeType.HASHCASH,
+        extra: {
+          challengeData: JSON.stringify(impossibleChallenge),
+        },
+      }
+
+      await expect(solverWithAnalytics.solve(challengeData)).rejects.toThrow()
+
+      expect(onSolveCompleted).toHaveBeenCalledWith(
+        expect.objectContaining({
+          success: false,
+          errorType: 'no_proof',
+          difficulty: 30,
+        }),
+      )
+    })
+
+    it('reports usedWorker: true when worker is provided', async () => {
+      const onSolveCompleted = vi.fn()
+      const mockWorkerChannel: HashcashWorkerChannel = {
+        api: {
+          findProof: vi.fn().mockResolvedValue({ counter: 42, hash: new Uint8Array([0]), attempts: 100 }),
+          cancel: vi.fn(),
+        },
+        terminate: vi.fn(),
+      }
+
+      const solverWithWorker = createHashcashSolver({
+        performanceTracker: createMockPerformanceTracker(),
+        getWorkerChannel: () => mockWorkerChannel,
+        onSolveCompleted,
+      })
+
+      const challengeData: ChallengeData = {
+        challengeId: 'test-challenge-123',
+        challengeType: ChallengeType.HASHCASH,
+        extra: {
+          challengeData: JSON.stringify(backendExample),
+        },
+      }
+
+      await solverWithWorker.solve(challengeData)
+
+      expect(onSolveCompleted).toHaveBeenCalledWith(
+        expect.objectContaining({
+          success: true,
+          usedWorker: true,
+        }),
+      )
+    })
+  })
+
+  describe('with worker channel', () => {
+    it('uses worker channel when provided', async () => {
+      const mockFindProof = vi.fn().mockResolvedValue({ counter: 42, hash: new Uint8Array([0]) })
+      const mockTerminate = vi.fn()
+
+      const mockWorkerChannel: HashcashWorkerChannel = {
+        api: {
+          findProof: mockFindProof,
+          cancel: vi.fn(),
+        },
+        terminate: mockTerminate,
+      }
+
+      const solverWithWorker = createHashcashSolver({
+        performanceTracker: createMockPerformanceTracker(),
+        getWorkerChannel: () => mockWorkerChannel,
+      })
+
+      const challengeData: ChallengeData = {
+        challengeId: 'test-challenge-123',
+        challengeType: ChallengeType.HASHCASH,
+        extra: {
+          challengeData: JSON.stringify(backendExample),
+        },
+      }
+
+      const solution = await solverWithWorker.solve(challengeData)
+
+      expect(mockFindProof).toHaveBeenCalledWith({
+        challenge: backendExample,
+        rangeStart: 0,
+        rangeSize: backendExample.max_proof_length,
+      })
+      expect(mockTerminate).toHaveBeenCalled()
+      expect(solution).toBe(`Lx:${backendExample.nonce}:42`)
+    })
+
+    it('terminates worker channel even on error', async () => {
+      const mockTerminate = vi.fn()
+
+      const mockWorkerChannel: HashcashWorkerChannel = {
+        api: {
+          findProof: vi.fn().mockRejectedValue(new Error('Worker error')),
+          cancel: vi.fn(),
+        },
+        terminate: mockTerminate,
+      }
+
+      const solverWithWorker = createHashcashSolver({
+        performanceTracker: createMockPerformanceTracker(),
+        getWorkerChannel: () => mockWorkerChannel,
+      })
+
+      const challengeData: ChallengeData = {
+        challengeId: 'test-challenge-123',
+        challengeType: ChallengeType.HASHCASH,
+        extra: {
+          challengeData: JSON.stringify(backendExample),
+        },
+      }
+
+      await expect(solverWithWorker.solve(challengeData)).rejects.toThrow('Worker error')
+      expect(mockTerminate).toHaveBeenCalled()
+    })
+
+    it('throws error when worker returns null', async () => {
+      const mockTerminate = vi.fn()
+
+      const mockWorkerChannel: HashcashWorkerChannel = {
+        api: {
+          findProof: vi.fn().mockResolvedValue(null),
+          cancel: vi.fn(),
+        },
+        terminate: mockTerminate,
+      }
+
+      const solverWithWorker = createHashcashSolver({
+        performanceTracker: createMockPerformanceTracker(),
+        getWorkerChannel: () => mockWorkerChannel,
+      })
+
+      const challengeData: ChallengeData = {
+        challengeId: 'test-challenge-123',
+        challengeType: ChallengeType.HASHCASH,
+        extra: {
+          challengeData: JSON.stringify(backendExample),
+        },
+      }
+
+      await expect(solverWithWorker.solve(challengeData)).rejects.toThrow('Failed to find valid proof')
+      expect(mockTerminate).toHaveBeenCalled()
+    })
+
+    it('throws error when worker is busy with another operation', async () => {
+      const mockTerminate = vi.fn()
+
+      const mockWorkerChannel: HashcashWorkerChannel = {
+        api: {
+          findProof: vi
+            .fn()
+            .mockRejectedValue(new Error('Worker is busy - another findProof operation is in progress')),
+          cancel: vi.fn(),
+        },
+        terminate: mockTerminate,
+      }
+
+      const solverWithWorker = createHashcashSolver({
+        performanceTracker: createMockPerformanceTracker(),
+        getWorkerChannel: () => mockWorkerChannel,
+      })
+
+      const challengeData: ChallengeData = {
+        challengeId: 'test-challenge-123',
+        challengeType: ChallengeType.HASHCASH,
+        extra: {
+          challengeData: JSON.stringify(backendExample),
+        },
+      }
+
+      await expect(solverWithWorker.solve(challengeData)).rejects.toThrow('Worker is busy')
+      expect(mockTerminate).toHaveBeenCalled()
+    })
+  })
+})

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 }