@luxexchange/sessions 1.0.0

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 '@luxexchange/sessions/src/challenge-solvers/createHashcashSolver'
+import type { HashcashChallenge } from '@luxexchange/sessions/src/challenge-solvers/hashcash/core'
+import type { HashcashWorkerChannelFactory } from '@luxexchange/sessions/src/challenge-solvers/hashcash/worker/types'
+import type { ChallengeData, ChallengeSolver } from '@luxexchange/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 '@luxexchange/sessions/src/challenge-solvers/hashcash/worker/types'
+import { NotImplementedError } from '@luxfi/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 '@luxexchange/sessions/src/challenge-solvers/hashcash/worker/types'
+import { PlatformSplitStubError } from '@luxfi/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 }

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

@@ -0,0 +1,212 @@
+/**
+ * Multi-worker channel factory for parallel hashcash proof-of-work.
+ *
+ * Spawns multiple Web Workers to search different counter ranges in parallel.
+ * Uses Promise.race() - first worker to find a valid proof wins.
+ *
+ * This provides significant speedup on multi-core systems:
+ * - 4 workers ~= 4x speedup
+ * - 8 workers ~= 8x speedup (diminishing returns beyond core count)
+ */
+
+import type { ProofResult } from '@luxexchange/sessions/src/challenge-solvers/hashcash/core'
+import type {
+  FindProofParams,
+  HashcashWorkerAPI,
+  HashcashWorkerChannel,
+} from '@luxexchange/sessions/src/challenge-solvers/hashcash/worker/types'
+import { createChannel } from 'bidc'
+
+/**
+ * Configuration for multi-worker hashcash channel.
+ */
+interface MultiWorkerConfig {
+  /**
+   * Number of workers to spawn.
+   * Defaults to navigator.hardwareConcurrency or 4.
+   */
+  workerCount?: number
+
+  /**
+   * Factory function to create a Worker instance.
+   */
+  getWorker: () => Worker
+}
+
+/**
+ * Internal worker state for tracking individual workers.
+ */
+interface WorkerState {
+  worker: Worker
+  channel: ReturnType<typeof createChannel>
+  cancelled: boolean
+}
+
+/**
+ * Creates a multi-worker channel for parallel hashcash proof-of-work.
+ *
+ * @example
+ * ```ts
+ * const channel = createHashcashMultiWorkerChannel({
+ *   workerCount: 4,
+ *   getWorker: () => new Worker(
+ *     new URL('./hashcash.worker.ts', import.meta.url),
+ *     { type: 'module' }
+ *   ),
+ * })
+ *
+ * const proof = await channel.api.findProof({ challenge })
+ * channel.terminate()
+ * ```
+ */
+function createHashcashMultiWorkerChannel(config: MultiWorkerConfig): HashcashWorkerChannel {
+  const workerCount = config.workerCount ?? (typeof navigator !== 'undefined' ? navigator.hardwareConcurrency : 4)
+  const workers: WorkerState[] = []
+
+  // Track if we've been terminated
+  let terminated = false
+
+  // Initialize workers lazily on first findProof call
+  const initWorkers = (): void => {
+    if (workers.length > 0 || terminated) {
+      return
+    }
+
+    for (let i = 0; i < workerCount; i++) {
+      const worker = config.getWorker()
+      const channel = createChannel(worker)
+      workers.push({ worker, channel, cancelled: false })
+    }
+  }
+
+  const api: HashcashWorkerAPI = {
+    async findProof(params: FindProofParams): Promise<ProofResult | null> {
+      if (terminated) {
+        throw new Error('Multi-worker channel has been terminated')
+      }
+
+      initWorkers()
+
+      // Reset cancelled state for all workers at start of new search
+      workers.forEach((state) => {
+        state.cancelled = false
+      })
+
+      const { challenge, rangeStart = 0, rangeSize = challenge.max_proof_length } = params
+      const rangeEnd = rangeStart + rangeSize
+
+      // Divide range across workers
+      const rangePerWorker = Math.ceil(rangeSize / workerCount)
+
+      // Track completion state
+      let foundResult: ProofResult | null = null
+      let completedCount = 0
+
+      // Pre-calculate expected worker count before starting any workers.
+      // This avoids a subtle dependency on JS event loop microtask ordering:
+      // if we counted inline, a fast-completing worker's .then() could
+      // theoretically race with the loop incrementing the started count.
+      let expectedCount = 0
+      workers.forEach((state, index) => {
+        if (state.cancelled || terminated) {
+          return
+        }
+        const workerRangeStart = rangeStart + index * rangePerWorker
+        const workerRangeEnd = Math.min(workerRangeStart + rangePerWorker, rangeEnd)
+        if (workerRangeEnd - workerRangeStart > 0) {
+          expectedCount++
+        }
+      })
+
+      if (expectedCount === 0) {
+        return null
+      }
+
+      return new Promise((resolve) => {
+        // Start all workers in parallel
+        workers.forEach((state, index) => {
+          if (terminated) {
+            return
+          }
+
+          const workerRangeStart = rangeStart + index * rangePerWorker
+          const workerRangeEnd = Math.min(workerRangeStart + rangePerWorker, rangeEnd)
+          const workerRangeSize = workerRangeEnd - workerRangeStart
+
+          if (workerRangeSize <= 0) {
+            return
+          }
+
+          // Start worker search (don't await - let them race)
+          state.channel
+            .send({
+              type: 'findProof',
+              params: {
+                challenge,
+                rangeStart: workerRangeStart,
+                rangeSize: workerRangeSize,
+              },
+            })
+            .then((result: unknown) => {
+              // Check if worker returned busy response
+              if (result && typeof result === 'object' && 'busy' in result) {
+                return null
+              }
+              return result as ProofResult | null
+            })
+            .then((result) => {
+              completedCount++
+
+              // First worker to find a valid proof wins
+              if (result && !foundResult && !terminated) {
+                foundResult = result
+                // Cancel all other workers immediately
+                api.cancel().catch(() => {})
+                resolve(result)
+              } else if (completedCount === expectedCount && !foundResult) {
+                // All expected workers done, no result found
+                resolve(null)
+              }
+            })
+            .catch(() => {
+              completedCount++
+              if (completedCount === expectedCount && !foundResult) {
+                resolve(null)
+              }
+            })
+        })
+      })
+    },
+
+    async cancel(): Promise<void> {
+      // Cancel all workers - fire and forget for speed
+      workers.forEach((state) => {
+        if (!state.cancelled) {
+          state.cancelled = true
+          state.channel.send({ type: 'cancel' }).catch(() => {
+            // Ignore cancel errors
+          })
+        }
+      })
+    },
+  }
+
+  return {
+    api,
+    terminate(): void {
+      terminated = true
+
+      // Terminate all workers
+      for (const state of workers) {
+        state.cancelled = true
+        state.channel.cleanup()
+        state.worker.terminate()
+      }
+
+      workers.length = 0
+    },
+  }
+}
+
+export { createHashcashMultiWorkerChannel }
+export type { MultiWorkerConfig }

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

@@ -0,0 +1,16 @@
+/**
+ * Native implementation of hashcash worker channel factory.
+ * Web Workers are not available in React Native.
+ */
+
+import type {
+  CreateHashcashWorkerChannelContext,
+  HashcashWorkerChannel,
+} from '@luxexchange/sessions/src/challenge-solvers/hashcash/worker/types'
+import { NotImplementedError } from '@luxfi/utilities/src/errors'
+
+function createHashcashWorkerChannel(_ctx: CreateHashcashWorkerChannelContext): HashcashWorkerChannel {
+  throw new NotImplementedError('createHashcashWorkerChannel')
+}
+
+export { createHashcashWorkerChannel }

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

@@ -0,0 +1,16 @@
+/**
+ * Base stub for hashcash worker channel factory.
+ * Platform-specific implementations override this file.
+ */
+
+import type {
+  CreateHashcashWorkerChannelContext,
+  HashcashWorkerChannel,
+} from '@luxexchange/sessions/src/challenge-solvers/hashcash/worker/types'
+import { PlatformSplitStubError } from '@luxfi/utilities/src/errors'
+
+function createHashcashWorkerChannel(_ctx: CreateHashcashWorkerChannelContext): HashcashWorkerChannel {
+  throw new PlatformSplitStubError('createHashcashWorkerChannel')
+}
+
+export { createHashcashWorkerChannel }

package/src/challenge-solvers/hashcash/worker/createHashcashWorkerChannel.web.ts

@@ -0,0 +1,97 @@
+/**
+ * Web Worker channel factory for hashcash proof-of-work.
+ *
+ * Creates a Web Worker and establishes a BIDC channel for
+ * bidirectional async communication.
+ *
+ * This is the web platform implementation used by both web app and extension.
+ */
+
+import type { ProofResult } from '@luxexchange/sessions/src/challenge-solvers/hashcash/core'
+import type {
+  CreateHashcashWorkerChannelContext,
+  FindProofParams,
+  HashcashWorkerAPI,
+  HashcashWorkerChannel,
+} from '@luxexchange/sessions/src/challenge-solvers/hashcash/worker/types'
+import { createChannel } from 'bidc'
+
+// Singleton worker instance for reuse
+let sharedWorker: Worker | null = null
+let sharedChannel: ReturnType<typeof createChannel> | null = null
+let referenceCount = 0
+// Track pending operations to reject on terminate
+const pendingOperations = new Set<(err: Error) => void>()
+
+/**
+ * Creates (or reuses) a channel to the hashcash worker.
+ *
+ * Uses a shared worker instance to avoid creation overhead.
+ * The worker is only terminated when all channels are closed.
+ *
+ * @param ctx - Context containing getWorker function to create the Worker instance
+ */
+function createHashcashWorkerChannel(ctx: CreateHashcashWorkerChannelContext): HashcashWorkerChannel {
+  // Create worker on first use
+  if (!sharedWorker) {
+    sharedWorker = ctx.getWorker()
+    sharedChannel = createChannel(sharedWorker)
+  }
+
+  referenceCount++
+
+  const channel = sharedChannel
+  if (!channel) {
+    throw new Error('Worker channel not initialized')
+  }
+  const { send } = channel
+
+  const api: HashcashWorkerAPI = {
+    findProof(params: FindProofParams): Promise<ProofResult | null> {
+      return new Promise((resolve, reject) => {
+        pendingOperations.add(reject)
+
+        send({ type: 'findProof', params })
+          .then((result: unknown) => {
+            // Check if worker returned busy response
+            // Worker returns { busy: true } when another operation is in progress
+            if (result && typeof result === 'object' && 'busy' in result) {
+              reject(new Error('Worker is busy - another findProof operation is in progress'))
+            } else {
+              resolve(result as ProofResult | null)
+            }
+          })
+          .catch(reject)
+          .finally(() => pendingOperations.delete(reject))
+      })
+    },
+
+    async cancel(): Promise<void> {
+      await send({ type: 'cancel' })
+    },
+  }
+
+  return {
+    api,
+    terminate(): void {
+      referenceCount--
+
+      // Only terminate when no more references
+      if (referenceCount <= 0 && sharedWorker) {
+        // Reject any pending operations before terminating
+        const error = new Error('Worker terminated while operation in progress')
+        for (const reject of pendingOperations) {
+          reject(error)
+        }
+        pendingOperations.clear()
+
+        sharedWorker.terminate()
+        sharedWorker = null
+        sharedChannel = null
+        referenceCount = 0
+      }
+    },
+  }
+}
+
+export { createHashcashWorkerChannel }

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

@@ -0,0 +1,91 @@
+/**
+ * Hashcash Web Worker
+ *
+ * Runs proof-of-work computation off the main thread using Web Crypto.
+ * Uses BIDC for bidirectional async communication.
+ */
+
+import type { ProofResult } from '../core'
+import { findProof } from '../core'
+import type { FindProofParams } from './types'
+import type { SerializableValue } from 'bidc'
+import { createChannel } from 'bidc'
+
+/**
+ * Message types sent from main thread to worker
+ * These are plain objects at runtime, compatible with SerializableValue
+ */
+type WorkerMessage = { type: 'findProof'; params: FindProofParams } | { type: 'cancel' }
+
+/**
+ * Response type returned from worker to main thread.
+ * Matches ProofResult structure but explicitly typed for serialization.
+ */
+type WorkerResponse = ProofResult | null
+
+/**
+ * Operation state for single-operation-at-a-time enforcement.
+ *
+ * This worker is designed for single-operation-at-a-time usage. Concurrent findProof
+ * calls will be rejected with an error. This ensures clean cancellation semantics
+ * where cancel() only affects the one in-progress operation.
+ */
+let operationInProgress = false
+let cancelled = false
+
+// Create BIDC channel - in worker context, connects to parent
+const { receive } = createChannel()
+
+/**
+ * Response type for busy state - signals to caller that worker is occupied.
+ * The channel layer converts this to an appropriate error.
+ */
+type WorkerBusyResponse = { busy: true }
+
+/**
+ * Async message handler for incoming requests from main thread.
+ * BIDC supports async handlers - it awaits the Promise before sending response.
+ */
+const messageHandler = async (data: WorkerMessage): Promise<WorkerResponse | WorkerBusyResponse> => {
+  switch (data.type) {
+    case 'findProof': {
+      // Enforce single-operation-at-a-time
+      if (operationInProgress) {
+        return { busy: true }
+      }
+
+      operationInProgress = true
+      // Reset cancellation flag for new search
+      cancelled = false
+
+      try {
+        // findProof is now async (uses Web Crypto)
+        const result = await findProof({
+          challenge: data.params.challenge,
+          rangeStart: data.params.rangeStart,
+          rangeSize: data.params.rangeSize,
+          // Check cancellation flag during iteration
+          shouldStop: () => cancelled,
+        })
+
+        // Return ProofResult directly - BIDC handles serialization of Uint8Array
+        return result
+      } finally {
+        operationInProgress = false
+      }
+    }
+
+    case 'cancel': {
+      cancelled = true
+      return null
+    }
+
+    default:
+      return null
+  }
+}
+
+// Register async message handler with BIDC
+// BIDC supports async handlers - the response Promise is awaited before sending
+// eslint-disable-next-line @typescript-eslint/no-floating-promises
+receive(messageHandler as (data: SerializableValue) => Promise<SerializableValue>)