@l.x/sessions 1.0.3 → 1.0.5

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 '@l.x/sessions/src/challenge-solvers/hashcash/core'
+import type {
+  FindProofParams,
+  HashcashWorkerAPI,
+  HashcashWorkerChannel,
+} from '@l.x/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 '@l.x/sessions/src/challenge-solvers/hashcash/worker/types'
+import { NotImplementedError } from '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 '@l.x/sessions/src/challenge-solvers/hashcash/worker/types'
+import { PlatformSplitStubError } from '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 '@l.x/sessions/src/challenge-solvers/hashcash/core'
+import type {
+  CreateHashcashWorkerChannelContext,
+  FindProofParams,
+  HashcashWorkerAPI,
+  HashcashWorkerChannel,
+} from '@l.x/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 '@l.x/sessions/src/challenge-solvers/hashcash/core'
+import { findProof } from '@l.x/sessions/src/challenge-solvers/hashcash/core'
+import type { FindProofParams } from '@l.x/sessions/src/challenge-solvers/hashcash/worker/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>)

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

@@ -0,0 +1,69 @@
+import type { HashcashChallenge, ProofResult } from '@l.x/sessions/src/challenge-solvers/hashcash/core'
+
+/**
+ * Parameters for finding a hashcash proof
+ */
+interface FindProofParams {
+  challenge: HashcashChallenge
+  rangeStart?: number
+  rangeSize?: number
+}
+
+/**
+ * Context for creating a hashcash worker channel.
+ * Apps inject the Worker instance getter to control Worker instantiation.
+ */
+interface CreateHashcashWorkerChannelContext {
+  /**
+   * Returns a Worker instance for hashcash proof-of-work.
+   * Called once on first channel creation (singleton pattern).
+   */
+  getWorker: () => Worker
+}
+
+/**
+ * The API exposed by the hashcash worker.
+ * This is the contract between main thread and worker.
+ */
+interface HashcashWorkerAPI {
+  /**
+   * Find a proof-of-work solution for the given challenge.
+   * Returns null if no solution found within range or if cancelled.
+   */
+  findProof(params: FindProofParams): Promise<ProofResult | null>
+
+  /**
+   * Cancel any in-progress proof search.
+   */
+  cancel(): Promise<void>
+}
+
+/**
+ * A channel to communicate with a hashcash worker.
+ * Platform-specific implementations create these.
+ */
+interface HashcashWorkerChannel {
+  /**
+   * The worker API - call methods to execute on worker thread
+   */
+  api: HashcashWorkerAPI
+
+  /**
+   * Terminate the worker and clean up resources
+   */
+  terminate(): void
+}
+
+/**
+ * Factory function that creates a HashcashWorkerChannel.
+ * Injected into the solver to enable platform-specific implementations.
+ */
+type HashcashWorkerChannelFactory = () => HashcashWorkerChannel
+
+export type {
+  CreateHashcashWorkerChannelContext,
+  FindProofParams,
+  HashcashWorkerAPI,
+  HashcashWorkerChannel,
+  HashcashWorkerChannelFactory,
+}

package/src/challenge-solvers/turnstileErrors.ts

@@ -0,0 +1,49 @@
+import { SessionError } from '@l.x/sessions/src/session-initialization/sessionErrors'
+
+/**
+ * Error thrown when Turnstile script fails to load
+ */
+export class TurnstileScriptLoadError extends SessionError {
+  constructor(message: string, cause?: unknown) {
+    super(`Turnstile script load error: ${message}`, 'TurnstileScriptLoadError')
+    if (cause) {
+      this.cause = cause
+    }
+  }
+}
+
+/**
+ * Error thrown when Turnstile API is not available
+ */
+export class TurnstileApiNotAvailableError extends SessionError {
+  constructor() {
+    super('Turnstile API not available', 'TurnstileApiNotAvailableError')
+  }
+}
+
+/**
+ * Error thrown when Turnstile challenge times out
+ */
+export class TurnstileTimeoutError extends SessionError {
+  constructor(timeoutMs: number) {
+    super(`Turnstile challenge timed out after ${timeoutMs}ms`, 'TurnstileTimeoutError')
+  }
+}
+
+/**
+ * Error thrown when Turnstile returns an error
+ */
+export class TurnstileError extends SessionError {
+  constructor(errorCode: string) {
+    super(`Turnstile error: ${errorCode}`, 'TurnstileError')
+  }
+}
+
+/**
+ * Error thrown when Turnstile token expires
+ */
+export class TurnstileTokenExpiredError extends SessionError {
+  constructor() {
+    super('Turnstile token expired', 'TurnstileTokenExpiredError')
+  }
+}