@luxexchange/sessions 1.0.0

package/.depcheckrc

@@ -0,0 +1,20 @@
+ignores: [
+    # Dependencies that depcheck thinks are unused but are actually used
+    "openapi-typescript-codegen",
+    "typescript",
+    "@typescript/native-preview",
+    "depcheck",
+    "@vitest/coverage-v8",
+    "@types/react",
+    "ts-morph",
+
+    # Used but depcheck doesn't detect correctly
+    "@tanstack/react-query",
+    "@bufbuild/protobuf",
+
+    # Dependencies that depcheck thinks are missing but are actually present
+    ## Internal packages / workspaces
+    "@universe/sessions",
+    "tsconfig",
+    "utilities",
+  ]

package/.eslintrc.js

@@ -0,0 +1,21 @@
+module.exports = {
+  extends: ['@luxfi/eslint-config/lib'],
+  ignorePatterns: ['env.d.ts'],
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+  },
+  overrides: [
+    {
+      files: ['*.ts', '*.tsx'],
+      rules: {
+        'no-relative-import-paths/no-relative-import-paths': [
+          'error',
+          {
+            allowSameFolder: false,
+            prefix: '@luxfi/sessions',
+          },
+        ],
+      },
+    },
+  ],
+}

package/README.md

@@ -0,0 +1 @@
+# `@universe/sessions` Package

package/env.d.ts

@@ -0,0 +1,12 @@
+/** biome-ignore-all lint/style/noNamespace: required to define process.env type */
+
+declare global {
+  namespace NodeJS {
+    // All process.env values used by this package should be listed here
+    interface ProcessEnv {
+      NODE_ENV?: 'development' | 'production' | 'test'
+    }
+  }
+}
+
+export {}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@luxexchange/sessions",
+  "version": "1.0.0",
+  "scripts": {
+    "typecheck": "nx typecheck sessions",
+    "typecheck:tsgo": "nx typecheck:tsgo sessions",
+    "lint": "nx lint sessions",
+    "lint:fix": "nx lint:fix sessions",
+    "lint:biome": "nx lint:biome sessions",
+    "lint:biome:fix": "nx lint:biome:fix sessions",
+    "lint:eslint": "nx lint:eslint sessions",
+    "lint:eslint:fix": "nx lint:eslint:fix sessions",
+    "check:deps:usage": "nx check:deps:usage sessions",
+    "test": "nx test sessions",
+    "test:coverage": "nx test:coverage sessions",
+    "test:integration:backend": "nx test:integration:backend sessions"
+  },
+  "nx": {
+    "includedScripts": []
+  },
+  "dependencies": {
+    "@connectrpc/connect": "1.5.0",
+    "@connectrpc/connect-web": "1.5.0",
+    "@noble/hashes": "2.0.1",
+    "@scure/base": "2.0.0",
+    "@tanstack/react-query": "5.90.20",
+    "@uniswap/client-platform-service": "0.0.14",
+    "bidc": "0.0.3",
+    "@luxfi/utilities": "^1.0.0",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@edge-runtime/vm": "5.0.0",
+    "@types/chrome": "0.0.304",
+    "@types/node": "22.13.1",
+    "@types/react": "19.0.10",
+    "@typescript/native-preview": "7.0.0-dev.20260108.1",
+    "@luxfi/eslint-config": "^1.0.0",
+    "@vitest/coverage-v8": "3.2.1",
+    "depcheck": "1.4.7",
+    "eslint": "8.57.1",
+    "happy-dom": "20.0.10",
+    "ts-morph": "23.0.0",
+    "typescript": "5.8.3",
+    "vitest": "3.2.1"
+  },
+  "main": "src/index.ts",
+  "private": false,
+  "sideEffects": false
+}

package/project.json

@@ -0,0 +1,42 @@
+{
+  "name": "@luxfi/sessions",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "pkgs/sessions/src",
+  "projectType": "library",
+  "tags": ["scope:sessions", "type:lib"],
+  "targets": {
+    "typecheck": {},
+    "typecheck:tsgo": {},
+    "lint:biome": {},
+    "lint:biome:fix": {},
+    "lint:eslint": {},
+    "lint:eslint:fix": {},
+    "lint": {},
+    "lint:fix": {},
+    "check:deps:usage": {},
+    "test": {
+      "command": "vitest run",
+      "options": {
+        "cwd": "{projectRoot}"
+      }
+    },
+    "test:watch": {
+      "command": "vitest dev",
+      "options": {
+        "cwd": "{projectRoot}"
+      }
+    },
+    "test:coverage": {
+      "command": "vitest run --coverage",
+      "options": {
+        "cwd": "{projectRoot}"
+      }
+    },
+    "test:integration:backend": {
+      "command": "vitest run --config vitest.integration.config.ts",
+      "options": {
+        "cwd": "{projectRoot}"
+      }
+    }
+  }
+}

package/src/challenge-solvers/createChallengeSolverService.ts

@@ -0,0 +1,64 @@
+import { ChallengeType } from '@uniswap/client-platform-service/dist/uniswap/platformservice/v1/sessionService_pb'
+import { createHashcashMockSolver } from '@luxexchange/sessions/src/challenge-solvers/createHashcashMockSolver'
+import { createNoneMockSolver } from '@luxexchange/sessions/src/challenge-solvers/createNoneMockSolver'
+import { createTurnstileMockSolver } from '@luxexchange/sessions/src/challenge-solvers/createTurnstileMockSolver'
+import type { ChallengeSolver, ChallengeSolverService } from '@luxexchange/sessions/src/challenge-solvers/types'
+import type { Logger } from '@luxfi/utilities/src/logger/logger'
+
+interface CreateChallengeSolverServiceContext {
+  /**
+   * Optional custom solvers to override defaults
+   * Allows injection of real implementations or custom mocks
+   */
+  solvers?: Map<ChallengeType, ChallengeSolver>
+  /**
+   * Optional logger to use for debugging
+   */
+  getLogger?: () => Logger
+}
+
+function createChallengeSolverService(ctx: CreateChallengeSolverServiceContext = {}): ChallengeSolverService {
+  // Use injected solvers or fall back to default mocks
+  const solvers = ctx.solvers ?? createDefaultSolvers()
+
+  function getSolver(type: ChallengeType): ChallengeSolver | null {
+    // Handle UNSPECIFIED type explicitly
+    if (type === ChallengeType.UNSPECIFIED) {
+      return {
+        solve: async (): Promise<string> => {
+          throw new Error('No solver available for challenge type: UNSPECIFIED')
+        },
+      }
+    }
+
+    const value = solvers.get(type) ?? null
+
+    if (ctx.getLogger) {
+      ctx
+        .getLogger()
+        .debug(
+          'createChallengeSolverService',
+          'getSolver',
+          `Solver for challenge type ${type} is ${value ? 'available' : 'not available'}`,
+        )
+    }
+
+    return value
+  }
+
+  return { getSolver }
+}
+
+/**
+ * Creates the default set of mock solvers for development/testing
+ */
+function createDefaultSolvers(): Map<ChallengeType, ChallengeSolver> {
+  return new Map<ChallengeType, ChallengeSolver>([
+    [ChallengeType.UNSPECIFIED, createNoneMockSolver()],
+    [ChallengeType.TURNSTILE, createTurnstileMockSolver()],
+    [ChallengeType.HASHCASH, createHashcashMockSolver()],
+  ])
+}
+
+export { createChallengeSolverService }
+export type { CreateChallengeSolverServiceContext }

package/src/challenge-solvers/createHashcashMockSolver.ts

@@ -0,0 +1,39 @@
+import type { ChallengeData, ChallengeSolver } from '@luxfi/sessions/src/challenge-solvers/types'
+import { sleep } from '@luxfi/utilities/src/time/timing'
+
+/**
+ * Creates a mock Hashcash proof-of-work solver for development/testing
+ *
+ * In production, this would:
+ * - Extract difficulty/bits from challengeData.extra
+ * - Iterate through nonces to find hash with required leading zeros
+ * - Return actual proof-of-work solution
+ *
+ * Hashcash format: version:bits:date:resource::nonce:base64
+ */
+function createHashcashMockSolver(): ChallengeSolver {
+  async function solve(challengeData: ChallengeData): Promise<string> {
+    // Extract difficulty from extra data
+    const difficulty = challengeData.extra?.['bits'] || '20'
+
+    // Simulate proof-of-work computation time
+    // Real implementation would iterate through nonces
+    const iterations = parseInt(difficulty) / 4
+    for (let i = 0; i < iterations; i++) {
+      await sleep(100) // Simulate work
+    }
+
+    // Generate mock hashcash solution
+    const nonce = Math.random().toString(36).substring(2, 15)
+    const mockHash = btoa(`${challengeData.challengeId}${nonce}`).slice(0, 27)
+    const timestamp = new Date().toISOString().slice(2, 10).replace(/-/g, '')
+    const resource = challengeData.challengeId.slice(0, 16)
+
+    // Return in hashcash format
+    return `1:${difficulty}:${timestamp}:${resource}::${nonce}:${mockHash}`
+  }
+
+  return { solve }
+}
+
+export { createHashcashMockSolver }

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

@@ -0,0 +1,385 @@
+import { ChallengeType } from '@uniswap/client-platform-service/dist/uniswap/platformservice/v1/sessionService_pb'
+import { createHashcashSolver } from '@luxexchange/sessions/src/challenge-solvers/createHashcashSolver'
+import type { HashcashWorkerChannel } from '@luxexchange/sessions/src/challenge-solvers/hashcash/worker/types'
+import type { ChallengeData } from '@luxexchange/sessions/src/challenge-solvers/types'
+import type { PerformanceTracker } from '@luxexchange/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: 'Lux',
+    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(/^Lux:[A-Za-z0-9+/=]+:\d+$/)
+    expect(solution.startsWith('Lux:')).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('Lux')
+    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(`Lux:${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()
+    })
+  })
+})