@l.x/sessions 1.0.3 → 1.0.5

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

@@ -0,0 +1,35 @@
+/**
+ * Base stub for hashcash core functions.
+ * Platform-specific implementations override this file.
+ *
+ * - Web: core.web.ts (Web Crypto + batching)
+ * - Native: core.native.ts (mobile uses Nitro modules)
+ *
+ * Shared types and platform-agnostic functions live in shared.ts.
+ */
+
+import { PlatformSplitStubError } from 'utilities/src/errors'
+
+export type { HashcashChallenge, ProofResult } from '@l.x/sessions/src/challenge-solvers/hashcash/shared'
+// Re-export everything from shared — types, checkDifficulty, formatHashcashString
+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 PlatformSplitStubError('computeHash')
+}
+
+export async function findProof(_params: {
+  challenge: HashcashChallenge
+  rangeStart?: number
+  rangeSize?: number
+  shouldStop?: () => boolean
+  batchSize?: number
+}): Promise<ProofResult | null> {
+  throw new PlatformSplitStubError('findProof')
+}
+
+export async function verifyProof(_challenge: HashcashChallenge, _proofCounter: string): Promise<boolean> {
+  throw new PlatformSplitStubError('verifyProof')
+}

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

@@ -0,0 +1,123 @@
+/**
+ * Web-optimized hashcash core implementation.
+ *
+ * Uses Web Crypto API via @noble/hashes/webcrypto.js for hardware-accelerated
+ * SHA-256 hashing. Includes batching to amortize async overhead.
+ *
+ * This is the web platform implementation - mobile uses native Nitro modules.
+ */
+import { sha256 } from '@noble/hashes/webcrypto.js'
+
+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'
+import { checkDifficulty } from '@l.x/sessions/src/challenge-solvers/hashcash/shared'
+
+// Pre-allocated TextEncoder for memory efficiency (avoids creating new instance per hash)
+const encoder = new TextEncoder()
+
+// Default batch size for async hashing
+// Tuned to balance async overhead vs responsiveness to cancellation
+const DEFAULT_BATCH_SIZE = 256
+
+/**
+ * Compute SHA-256 hash using Web Crypto API.
+ * Async for hardware acceleration.
+ */
+export async function computeHash(params: { subject: string; nonce: string; counter: number }): Promise<Uint8Array> {
+  const { subject, nonce, counter } = params
+
+  // Backend expects: "${subject}:${nonce}:${counter}"
+  const solutionString = `${subject}:${nonce}:${counter}`
+
+  // Hash using Web Crypto (hardware-accelerated)
+  const inputBytes = encoder.encode(solutionString)
+  return sha256(inputBytes)
+}
+
+/**
+ * Find a proof-of-work solution using batched Web Crypto hashing.
+ *
+ * Processes hashes in batches to amortize async overhead while remaining
+ * responsive to cancellation requests.
+ */
+export async function findProof(params: {
+  challenge: HashcashChallenge
+  rangeStart?: number
+  rangeSize?: number
+  shouldStop?: () => boolean
+  batchSize?: number
+}): Promise<ProofResult | null> {
+  const {
+    challenge,
+    rangeStart = 0,
+    rangeSize = challenge.max_proof_length || 1_000_000,
+    shouldStop,
+    batchSize = DEFAULT_BATCH_SIZE,
+  } = params
+
+  const startTime = Date.now()
+  const rangeEnd = rangeStart + rangeSize
+  const { subject, nonce, difficulty } = challenge
+
+  for (let batchStart = rangeStart; batchStart < rangeEnd; batchStart += batchSize) {
+    // Check for cancellation at batch boundaries
+    if (shouldStop?.()) {
+      return null
+    }
+
+    // Determine actual batch end (don't exceed range)
+    const batchEnd = Math.min(batchStart + batchSize, rangeEnd)
+    const currentBatchSize = batchEnd - batchStart
+
+    // Generate counter values for this batch
+    const counters: number[] = new Array(currentBatchSize)
+    for (let i = 0; i < currentBatchSize; i++) {
+      counters[i] = batchStart + i
+    }
+
+    // Hash all counters in this batch in parallel
+    const hashes = await Promise.all(counters.map((counter) => computeHash({ subject, nonce, counter })))
+
+    // Check each hash for valid proof
+    for (let i = 0; i < hashes.length; i++) {
+      const hash = hashes[i]
+      const counter = counters[i]
+      // Safety check (shouldn't happen since arrays are same size)
+      if (!hash || counter === undefined) {
+        continue
+      }
+      if (checkDifficulty(hash, difficulty)) {
+        return {
+          counter: counter.toString(),
+          hash,
+          attempts: counter - rangeStart + 1,
+          timeMs: Date.now() - startTime,
+        }
+      }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Verify a proof solution.
+ * Async because it uses Web Crypto.
+ */
+export async function verifyProof(challenge: HashcashChallenge, proofCounter: string): Promise<boolean> {
+  const counter = parseInt(proofCounter)
+
+  if (isNaN(counter)) {
+    return false
+  }
+
+  const hash = await computeHash({
+    subject: challenge.subject,
+    nonce: challenge.nonce,
+    counter,
+  })
+  return checkDifficulty(hash, challenge.difficulty)
+}

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

@@ -0,0 +1,195 @@
+import { ChallengeType } from '@luxamm/client-platform-service/dist/lx/platformservice/v1/sessionService_pb'
+import { createWorkerHashcashSolver } from '@l.x/sessions/src/challenge-solvers/hashcash/createWorkerHashcashSolver'
+import type { HashcashWorkerChannelFactory } from '@l.x/sessions/src/challenge-solvers/hashcash/worker/types'
+import type { ChallengeData } from '@l.x/sessions/src/challenge-solvers/types'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+describe('createWorkerHashcashSolver', () => {
+  // Real backend example data
+  const backendExample = {
+    difficulty: 1,
+    subject: 'Lx',
+    algorithm: 'sha256' as const,
+    nonce: 'Qlquffem7d8RrL6fmveE68XK0KxcoczdiVpFrV1qeUk=',
+    max_proof_length: 10000,
+  }
+
+  // Mock channel factory for testing
+  function createMockChannelFactory(
+    findProofResult: { counter: string; hash: Uint8Array; attempts: number; timeMs: number } | null = {
+      counter: '123',
+      hash: new Uint8Array([0, 0, 1, 2, 3]),
+      attempts: 124,
+      timeMs: 50,
+    },
+  ): {
+    factory: HashcashWorkerChannelFactory
+    mocks: {
+      findProof: ReturnType<typeof vi.fn>
+      cancel: ReturnType<typeof vi.fn>
+      terminate: ReturnType<typeof vi.fn>
+    }
+  } {
+    const findProof = vi.fn().mockResolvedValue(findProofResult)
+    const cancel = vi.fn().mockResolvedValue(undefined)
+    const terminate = vi.fn()
+
+    const factory: HashcashWorkerChannelFactory = () => ({
+      api: { findProof, cancel },
+      terminate,
+    })
+
+    return { factory, mocks: { findProof, cancel, terminate } }
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('successfully solves a valid challenge using worker', async () => {
+    const { factory, mocks } = createMockChannelFactory()
+    const solver = createWorkerHashcashSolver({ createChannel: factory })
+
+    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).toBe(`Lx:${backendExample.nonce}:123`)
+
+    // Verify worker was called correctly
+    expect(mocks.findProof).toHaveBeenCalledOnce()
+    expect(mocks.findProof).toHaveBeenCalledWith({
+      challenge: expect.objectContaining({
+        subject: 'Lx',
+        difficulty: 1,
+        nonce: backendExample.nonce,
+      }),
+      rangeStart: 0,
+      rangeSize: 10000,
+    })
+
+    // Verify channel was terminated
+    expect(mocks.terminate).toHaveBeenCalledOnce()
+  })
+
+  it('throws error when challengeData is missing', async () => {
+    const { factory } = createMockChannelFactory()
+    const solver = createWorkerHashcashSolver({ createChannel: factory })
+
+    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 no proof is found', async () => {
+    const { factory } = createMockChannelFactory(null)
+    const solver = createWorkerHashcashSolver({ createChannel: factory })
+
+    const challengeData: ChallengeData = {
+      challengeId: 'test-challenge-123',
+      challengeType: ChallengeType.HASHCASH,
+      extra: {
+        challengeData: JSON.stringify(backendExample),
+      },
+    }
+
+    await expect(solver.solve(challengeData)).rejects.toThrow('Failed to find valid proof within allowed range')
+  })
+
+  it('terminates channel even when error occurs', async () => {
+    const findProof = vi.fn().mockRejectedValue(new Error('Worker error'))
+    const terminate = vi.fn()
+
+    const factory: HashcashWorkerChannelFactory = () => ({
+      api: { findProof, cancel: vi.fn() },
+      terminate,
+    })
+
+    const solver = createWorkerHashcashSolver({ createChannel: factory })
+
+    const challengeData: ChallengeData = {
+      challengeId: 'test-challenge-123',
+      challengeType: ChallengeType.HASHCASH,
+      extra: {
+        challengeData: JSON.stringify(backendExample),
+      },
+    }
+
+    await expect(solver.solve(challengeData)).rejects.toThrow('Worker error')
+
+    // Channel should still be terminated
+    expect(terminate).toHaveBeenCalledOnce()
+  })
+
+  describe('cancellation', () => {
+    it('cancels solving when AbortSignal is triggered', async () => {
+      const controller = new AbortController()
+      const { factory, mocks } = createMockChannelFactory()
+
+      // Make findProof take a while and check abort during it
+      mocks.findProof.mockImplementation(async () => {
+        // Simulate work, then check if cancelled
+        await new Promise((resolve) => setTimeout(resolve, 50))
+        return null // Simulates cancelled result
+      })
+
+      const solver = createWorkerHashcashSolver({
+        createChannel: factory,
+        signal: controller.signal,
+      })
+
+      const challengeData: ChallengeData = {
+        challengeId: 'test-challenge-123',
+        challengeType: ChallengeType.HASHCASH,
+        extra: {
+          challengeData: JSON.stringify(backendExample),
+        },
+      }
+
+      // Start solving and cancel after a short delay
+      const solvePromise = solver.solve(challengeData)
+      controller.abort()
+
+      await expect(solvePromise).rejects.toThrow('Challenge solving was cancelled')
+
+      // Verify cancel was called on the worker
+      expect(mocks.cancel).toHaveBeenCalled()
+    })
+
+    it('throws immediately if already aborted', async () => {
+      const controller = new AbortController()
+      controller.abort() // Abort before starting
+
+      const { factory, mocks } = createMockChannelFactory()
+
+      const solver = createWorkerHashcashSolver({
+        createChannel: factory,
+        signal: controller.signal,
+      })
+
+      const challengeData: ChallengeData = {
+        challengeId: 'test-challenge-123',
+        challengeType: ChallengeType.HASHCASH,
+        extra: {
+          challengeData: JSON.stringify(backendExample),
+        },
+      }
+
+      await expect(solver.solve(challengeData)).rejects.toThrow('Challenge solving was cancelled')
+
+      // Worker should not be called if already aborted
+      expect(mocks.findProof).not.toHaveBeenCalled()
+    })
+  })
+})

package/src/challenge-solvers/hashcash/createWorkerHashcashSolver.ts

@@ -0,0 +1,120 @@
+/**
+ * Worker-backed hashcash solver.
+ *
+ * Offloads proof-of-work computation to a Web Worker to avoid
+ * blocking the main thread.
+ */
+import { parseHashcashChallenge } from '@l.x/sessions/src/challenge-solvers/createHashcashSolver'
+import 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'
+
+interface CreateWorkerHashcashSolverContext {
+  /**
+   * Factory function to create a worker channel.
+   * Platform-specific (web, extension, native) implementations
+   * are injected here.
+   */
+  createChannel: HashcashWorkerChannelFactory
+
+  /**
+   * Optional AbortSignal for external cancellation.
+   * When aborted, cancels the in-progress proof search.
+   */
+  signal?: AbortSignal
+}
+
+/**
+ * Creates a hashcash solver that runs proof-of-work in a worker.
+ *
+ * @example
+ * ```ts
+ * import { createHashcashWorkerChannel } from './worker/createHashcashWorkerChannel.web'
+ *
+ * const getWorker = () => new Worker(new URL('./hashcash.worker.ts', import.meta.url), { type: 'module' })
+ *
+ * const solver = createWorkerHashcashSolver({
+ *   createChannel: () => createHashcashWorkerChannel({ getWorker })
+ * })
+ *
+ * const solution = await solver.solve(challengeData)
+ * ```
+ */
+function createWorkerHashcashSolver(ctx: CreateWorkerHashcashSolverContext): ChallengeSolver {
+  async function solve(challengeData: ChallengeData): Promise<string> {
+    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 {
+      const challengeDataStr = challengeData.extra?.['challengeData']
+      if (!challengeDataStr) {
+        throw new Error('Missing challengeData in challenge extra field')
+      }
+      challenge = parseHashcashChallenge(challengeDataStr)
+    }
+
+    // Create worker channel
+    const channel = ctx.createChannel()
+
+    // Handle external cancellation
+    const abortHandler = (): void => {
+      channel.api.cancel().catch(() => {
+        // Ignore cancellation errors
+      })
+    }
+
+    if (ctx.signal) {
+      ctx.signal.addEventListener('abort', abortHandler)
+    }
+
+    try {
+      // Check if already aborted
+      if (ctx.signal?.aborted) {
+        throw new Error('Challenge solving was cancelled')
+      }
+
+      // Find proof-of-work solution in worker
+      const proof = await channel.api.findProof({
+        challenge,
+        rangeStart: 0,
+        rangeSize: challenge.max_proof_length,
+      })
+
+      if (!proof) {
+        // Could be cancelled or no solution found
+        if (ctx.signal?.aborted) {
+          throw new Error('Challenge solving was cancelled')
+        }
+
+        throw new Error(
+          `Failed to find valid proof within allowed range (0-${challenge.max_proof_length}). ` +
+            'Challenge may have expired or difficulty may be too high.',
+        )
+      }
+
+      // Return the solution in the format expected by backend: "${subject}:${nonce}:${counter}"
+      return `${challenge.subject}:${challenge.nonce}:${proof.counter}`
+    } finally {
+      // Clean up
+      if (ctx.signal) {
+        ctx.signal.removeEventListener('abort', abortHandler)
+      }
+      channel.terminate()
+    }
+  }
+
+  return { solve }
+}
+
+export { createWorkerHashcashSolver }
+export type { CreateWorkerHashcashSolverContext }

package/src/challenge-solvers/hashcash/shared.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared types and platform-agnostic utilities for hashcash.
+ *
+ * This file contains code that has zero platform dependencies and is
+ * imported by all platform variants (core.ts, core.web.ts, core.native.ts).
+ *
+ * NOTE: This file intentionally does NOT follow the platform-split naming
+ * convention (no .web.ts/.native.ts variants) so it can be safely imported
+ * from platform-specific files without circular resolution.
+ */
+
+import { base64 } from '@scure/base'
+
+export interface HashcashChallenge {
+  difficulty: number
+  subject: string
+  algorithm: 'sha256'
+  nonce: string
+  max_proof_length: number
+  verifier?: string
+}
+
+export interface ProofResult {
+  counter: string
+  hash: Uint8Array
+  attempts: number
+  timeMs: number
+}
+
+/**
+ * Check if a hash meets the required difficulty.
+ * Difficulty is the number of leading zero bytes required.
+ */
+export function checkDifficulty(hash: Uint8Array, difficulty: number): boolean {
+  // Backend uses difficulty as number of zero BYTES, not bits
+  // difficulty=1 means first byte must be 0
+  // difficulty=2 means first two bytes must be 0, etc.
+
+  // Check if hash has enough bytes
+  if (hash.length < difficulty) {
+    return false
+  }
+
+  // Check that the first 'difficulty' bytes are all zero
+  for (let i = 0; i < difficulty; i++) {
+    if (hash[i] !== 0) {
+      return false
+    }
+  }
+
+  return true
+}
+
+/**
+ * Format a proof into hashcash string format for submission.
+ * Format: version:bits:date:resource:extension:counter:hash
+ */
+export function formatHashcashString(challenge: HashcashChallenge, proof: ProofResult): string {
+  const version = '1'
+  const bits = challenge.difficulty.toString()
+  const date = new Date().toISOString().slice(2, 10).replace(/-/g, '')
+  const resource = challenge.subject.slice(0, 16)
+  const extension = ''
+  const counter = proof.counter
+
+  // Encode the proof hash as base64 (truncated)
+  const hashB64 = base64.encode(proof.hash).slice(0, 27)
+
+  return `${version}:${bits}:${date}:${resource}:${extension}:${counter}:${hashB64}`
+}

package/src/challenge-solvers/hashcash/worker/createHashcashMultiWorkerChannel.native.ts

@@ -0,0 +1,22 @@
+/**
+ * Native stub for multi-worker hashcash channel factory.
+ * Web Workers are not available in React Native.
+ */
+
+import type { HashcashWorkerChannel } from '@l.x/sessions/src/challenge-solvers/hashcash/worker/types'
+import { NotImplementedError } from 'utilities/src/errors'
+
+/**
+ * Configuration for multi-worker hashcash channel.
+ */
+interface MultiWorkerConfig {
+  workerCount?: number
+  getWorker: () => Worker
+}
+
+function createHashcashMultiWorkerChannel(_config: MultiWorkerConfig): HashcashWorkerChannel {
+  throw new NotImplementedError('createHashcashMultiWorkerChannel')
+}
+
+export { createHashcashMultiWorkerChannel }
+export type { MultiWorkerConfig }

package/src/challenge-solvers/hashcash/worker/createHashcashMultiWorkerChannel.ts

@@ -0,0 +1,22 @@
+/**
+ * Base stub for multi-worker hashcash channel factory.
+ * Platform-specific implementations override this file.
+ */
+
+import type { HashcashWorkerChannel } from '@l.x/sessions/src/challenge-solvers/hashcash/worker/types'
+import { PlatformSplitStubError } from 'utilities/src/errors'
+
+/**
+ * Configuration for multi-worker hashcash channel.
+ */
+interface MultiWorkerConfig {
+  workerCount?: number
+  getWorker: () => Worker
+}
+
+function createHashcashMultiWorkerChannel(_config: MultiWorkerConfig): HashcashWorkerChannel {
+  throw new PlatformSplitStubError('createHashcashMultiWorkerChannel')
+}
+
+export { createHashcashMultiWorkerChannel }
+export type { MultiWorkerConfig }