@luxexchange/sessions 1.0.0

package/src/index.ts

@@ -0,0 +1,137 @@
+/** biome-ignore-all assist/source/organizeImports: we want to manually group exports by category */
+
+/**
+ * @luxexchange/sessions
+ *
+ * This is the ONLY public entry point for the Sessions package.
+ * All exports must be explicitly listed here.
+ * Deep imports are forbidden and will be blocked by ESLint.
+ */
+
+// Device ID
+export { createDeviceIdService } from '@luxexchange/sessions/src/device-id/createDeviceIdService'
+export type { DeviceIdService } from '@luxexchange/sessions/src/device-id/types'
+// Lux Identifier
+export { createLuxIdentifierService } from '@luxexchange/sessions/src/lux-identifier/createLuxIdentifierService'
+export { luxIdentifierQuery } from '@luxexchange/sessions/src/lux-identifier/luxIdentifierQuery'
+export type { LuxIdentifierService } from '@luxexchange/sessions/src/lux-identifier/types'
+// Session Repository
+export { createSessionRepository } from '@luxexchange/sessions/src/session-repository/createSessionRepository'
+export { ChallengeRejectedError } from '@luxexchange/sessions/src/session-repository/errors'
+export { ChallengeFailureReason, VerifyFailureReason } from '@luxexchange/sessions/src/session-repository/types'
+export type {
+  SessionRepository,
+  ChallengeTypeConfig,
+  TypedChallengeData,
+  TurnstileChallengeData,
+  HashCashChallengeData,
+  GitHubChallengeData,
+} from '@luxexchange/sessions/src/session-repository/types'
+
+// Session Service
+export { createNoopSessionService } from '@luxexchange/sessions/src/session-service/createNoopSessionService'
+export { createSessionService } from '@luxexchange/sessions/src/session-service/createSessionService'
+export type {
+  SessionService,
+  InitSessionResponse,
+  ChallengeRequest,
+  ChallengeResponse,
+  VerifySessionRequest,
+  VerifySessionResponse,
+} from '@luxexchange/sessions/src/session-service/types'
+
+// Session Storage
+export { createSessionStorage } from '@luxexchange/sessions/src/session-storage/createSessionStorage'
+export type { SessionStorage, SessionState } from '@luxexchange/sessions/src/session-storage/types'
+
+// Session Client
+export { createSessionClient } from '@luxexchange/sessions/src/session-repository/createSessionClient'
+export type { SessionServiceClient } from '@luxexchange/sessions/src/session-repository/createSessionClient'
+
+// Session Initialization
+export { createSessionInitializationService } from '@luxexchange/sessions/src/session-initialization/createSessionInitializationService'
+export {
+  SessionError,
+  MaxChallengeRetriesError,
+  NoSolverAvailableError,
+} from '@luxexchange/sessions/src/session-initialization/sessionErrors'
+export type {
+  SessionInitializationService,
+  SessionInitOptions,
+  SessionInitResult,
+  SessionInitAnalytics,
+} from '@luxexchange/sessions/src/session-initialization/createSessionInitializationService'
+
+// Challenge Solvers
+export { createChallengeSolverService } from '@luxexchange/sessions/src/challenge-solvers/createChallengeSolverService'
+export { createTurnstileMockSolver } from '@luxexchange/sessions/src/challenge-solvers/createTurnstileMockSolver'
+export { createHashcashMockSolver } from '@luxexchange/sessions/src/challenge-solvers/createHashcashMockSolver'
+export { createNoneMockSolver } from '@luxexchange/sessions/src/challenge-solvers/createNoneMockSolver'
+export { createTurnstileSolver } from '@luxexchange/sessions/src/challenge-solvers/createTurnstileSolver'
+export { createHashcashSolver } from '@luxexchange/sessions/src/challenge-solvers/createHashcashSolver'
+export { createWorkerHashcashSolver } from '@luxexchange/sessions/src/challenge-solvers/hashcash/createWorkerHashcashSolver'
+export {
+  TurnstileScriptLoadError,
+  TurnstileApiNotAvailableError,
+  TurnstileTimeoutError,
+  TurnstileError,
+  TurnstileTokenExpiredError,
+} from '@luxexchange/sessions/src/challenge-solvers/turnstileErrors'
+export type {
+  ChallengeSolver,
+  ChallengeSolverService,
+  ChallengeData,
+  TurnstileScriptOptions,
+} from '@luxexchange/sessions/src/challenge-solvers/types'
+export type {
+  CreateTurnstileSolverContext,
+  TurnstileSolveAnalytics,
+} from '@luxexchange/sessions/src/challenge-solvers/createTurnstileSolver'
+export type {
+  CreateHashcashWorkerChannelContext,
+  HashcashWorkerChannel,
+  HashcashWorkerChannelFactory,
+} from '@luxexchange/sessions/src/challenge-solvers/hashcash/worker/types'
+export { createHashcashWorkerChannel } from '@luxexchange/sessions/src/challenge-solvers/hashcash/worker/createHashcashWorkerChannel'
+export { createHashcashMultiWorkerChannel } from '@luxexchange/sessions/src/challenge-solvers/hashcash/worker/createHashcashMultiWorkerChannel'
+export type { MultiWorkerConfig } from '@luxexchange/sessions/src/challenge-solvers/hashcash/worker/createHashcashMultiWorkerChannel'
+export type { CreateWorkerHashcashSolverContext } from '@luxexchange/sessions/src/challenge-solvers/hashcash/createWorkerHashcashSolver'
+export type {
+  CreateHashcashSolverContext,
+  HashcashSolveAnalytics,
+} from '@luxexchange/sessions/src/challenge-solvers/createHashcashSolver'
+
+export { ChallengeType } from '@luxexchange/sessions/src/session-service/types'
+
+// OAuth Service
+export { createOAuthService } from '@luxexchange/sessions/src/oauth-service/createOAuthService'
+export type { CreateOAuthServiceContext } from '@luxexchange/sessions/src/oauth-service/createOAuthService'
+export type {
+  OAuthService,
+  OAuthInitiationResult,
+  OAuthCallbackParams,
+  OAuthVerificationResult,
+  OAuthInitiateParams,
+  OAuthVerifyParams,
+  OAuthUserInfo,
+} from '@luxexchange/sessions/src/oauth-service/types'
+
+// Performance Tracking
+export type { PerformanceTracker } from '@luxexchange/sessions/src/performance/types'
+export {
+  createPerformanceTracker,
+  PERFORMANCE_TRACKING_DISABLED,
+} from '@luxexchange/sessions/src/performance/createPerformanceTracker'
+export type { CreatePerformanceTrackerContext } from '@luxexchange/sessions/src/performance/createPerformanceTracker'
+export { createNoopPerformanceTracker } from '@luxexchange/sessions/src/performance/createNoopPerformanceTracker'
+
+// Test utilities (for integration testing)
+export {
+  InMemorySessionStorage,
+  InMemoryDeviceIdService,
+  InMemoryLuxIdentifierService,
+} from '@luxexchange/sessions/src/test-utils'
+export {
+  createCookieJar,
+  createLocalCookieTransport,
+} from '@luxexchange/sessions/src/test-utils/createLocalCookieTransport'

package/src/lux-identifier/createLuxIdentifierService.ts

@@ -0,0 +1,19 @@
+import type { LuxIdentifierService } from '@luxfi/sessions/src/lux-identifier/types'
+
+function createLuxIdentifierService(ctx: {
+  getLuxIdentifier: () => Promise<string | null>
+  setLuxIdentifier: (identifier: string) => Promise<void>
+  removeLuxIdentifier: () => Promise<void>
+}): LuxIdentifierService {
+  const getLuxIdentifier = ctx.getLuxIdentifier
+  const setLuxIdentifier = ctx.setLuxIdentifier
+  const removeLuxIdentifier = ctx.removeLuxIdentifier
+
+  return {
+    getLuxIdentifier,
+    setLuxIdentifier,
+    removeLuxIdentifier,
+  }
+}
+
+export { createLuxIdentifierService }

package/src/lux-identifier/luxIdentifierQuery.ts

@@ -0,0 +1,20 @@
+import { queryOptions } from '@tanstack/react-query'
+import type { LuxIdentifierService } from '@luxexchange/sessions/src/lux-identifier/types'
+import { ReactQueryCacheKey } from '@luxfi/utilities/src/reactQuery/cache'
+import type { QueryOptionsResult } from '@luxfi/utilities/src/reactQuery/queryOptions'
+
+type LuxIdentifierQueryOptions = QueryOptionsResult<
+  string | null,
+  Error,
+  string | null,
+  [ReactQueryCacheKey.LuxIdentifier]
+>
+
+export function luxIdentifierQuery(getService: () => LuxIdentifierService): LuxIdentifierQueryOptions {
+  return queryOptions({
+    queryKey: [ReactQueryCacheKey.LuxIdentifier],
+    queryFn: async () => getService().getLuxIdentifier(),
+    staleTime: Infinity,
+    gcTime: Infinity,
+  })
+}

package/src/lux-identifier/types.ts

@@ -0,0 +1,11 @@
+/**
+ * Lux Identifier provider interface
+ * Platform-specific implementations handle lux identifier persistence
+ */
+interface LuxIdentifierService {
+  getLuxIdentifier(): Promise<string | null>
+  setLuxIdentifier(identifier: string): Promise<void>
+  removeLuxIdentifier(): Promise<void>
+}
+
+export type { LuxIdentifierService }

package/src/oauth-service/createOAuthService.ts

@@ -0,0 +1,125 @@
+import type {
+  OAuthCallbackParams,
+  OAuthInitiateParams,
+  OAuthInitiationResult,
+  OAuthService,
+  OAuthVerificationResult,
+  OAuthVerifyParams,
+} from '@luxexchange/sessions/src/oauth-service/types'
+import type { SessionRepository } from '@luxexchange/sessions/src/session-repository/types'
+
+/**
+ * Context (dependencies) for creating an OAuthService
+ */
+export interface CreateOAuthServiceContext {
+  /** Session repository for backend communication */
+  sessionRepository: SessionRepository
+}
+
+/**
+ * Creates an OAuth Service instance.
+ *
+ * Handles OAuth redirect-based authentication flows by wrapping
+ * the session repository's challenge/verify methods.
+ *
+ * Unlike ChallengeSolver (synchronous solve), OAuth requires:
+ * - External redirect to OAuth provider
+ * - User action (authorization)
+ * - Callback with authorization code
+ *
+ * @example
+ * ```typescript
+ * const oauthService = createOAuthService({ sessionRepository })
+ *
+ * // 1. Initiate - get URL and redirect user
+ * const { authorizeUrl } = await oauthService.initiate({
+ *   challengeType: ChallengeType.GITHUB,
+ *   callbackUrl: 'https://app.com/auth/callback/github',
+ * })
+ * redirect(authorizeUrl)
+ *
+ * // 2. In callback route - parse and verify
+ * const params = oauthService.parseCallback(new URL(request.url))
+ * const result = await oauthService.verify({
+ *   ...params,
+ *   challengeType: ChallengeType.GITHUB,
+ * })
+ * // result.userInfo contains { name?, email? } from OAuth provider
+ * redirect('/')
+ * ```
+ */
+export function createOAuthService(ctx: CreateOAuthServiceContext): OAuthService {
+  /**
+   * Initiate OAuth flow by requesting authorization URL
+   * Note: Callback URL is now configured server-side per OAuth provider
+   */
+  async function initiate(params: OAuthInitiateParams): Promise<OAuthInitiationResult> {
+    const response = await ctx.sessionRepository.challenge({
+      challengeType: params.challengeType,
+      // Note: callbackUrl is no longer sent to backend - configured server-side
+    })
+
+    if (!response.authorizeUrl) {
+      throw new Error('No authorization URL returned from challenge')
+    }
+
+    return {
+      authorizeUrl: response.authorizeUrl,
+      state: response.challengeId,
+    }
+  }
+
+  /**
+   * Parse OAuth callback URL to extract parameters
+   */
+  function parseCallback(url: URL): OAuthCallbackParams {
+    return {
+      code: url.searchParams.get('code'),
+      state: url.searchParams.get('state'),
+      error: url.searchParams.get('error'),
+      errorDescription: url.searchParams.get('error_description'),
+    }
+  }
+
+  /**
+   * Verify OAuth callback by submitting authorization code
+   */
+  async function verify(params: OAuthVerifyParams): Promise<OAuthVerificationResult> {
+    // Handle OAuth error from provider
+    if (params.error) {
+      return {
+        success: false,
+        retry: false,
+      }
+    }
+
+    // Validate required params
+    if (!params.code || !params.state) {
+      return {
+        success: false,
+        retry: false,
+      }
+    }
+
+    const result = await ctx.sessionRepository.verifySession({
+      solution: params.code,
+      challengeId: params.state,
+      challengeType: params.challengeType,
+    })
+
+    return {
+      success: !result.retry && !result.failureReason,
+      retry: result.retry,
+      waitSeconds: result.waitSeconds,
+      userInfo: result.userInfo,
+      failureReason: result.failureReason,
+      failureMessage: result.failureMessage,
+    }
+  }
+
+  return {
+    initiate,
+    parseCallback,
+    verify,
+  }
+}

package/src/oauth-service/types.ts

@@ -0,0 +1,104 @@
+import { ChallengeType } from '@uniswap/client-platform-service/dist/uniswap/platformservice/v1/sessionService_pb'
+
+/**
+ * Result from initiating an OAuth flow
+ */
+export interface OAuthInitiationResult {
+  /** URL to redirect user to for OAuth provider authorization */
+  authorizeUrl: string
+  /** Challenge ID used as OAuth state parameter for CSRF protection */
+  state: string
+}
+
+/**
+ * Parameters extracted from OAuth callback URL
+ */
+export interface OAuthCallbackParams {
+  /** Authorization code from OAuth provider */
+  code: string | null
+  /** State parameter (challenge ID) for CSRF validation */
+  state: string | null
+  /** OAuth error code if authorization failed */
+  error: string | null
+  /** Human-readable error description */
+  errorDescription: string | null
+}
+
+/**
+ * User information from OAuth provider
+ */
+export interface OAuthUserInfo {
+  name?: string
+  email?: string
+}
+
+/**
+ * Result from verifying OAuth callback
+ */
+export interface OAuthVerificationResult {
+  /** Whether verification succeeded */
+  success: boolean
+  /** Whether to retry the flow */
+  retry: boolean
+  /** Seconds to wait before retry (for rate limiting) */
+  waitSeconds?: number
+  /** User information from OAuth provider */
+  userInfo?: OAuthUserInfo
+  /** Failure reason from backend (e.g., 'REASON_PROVIDER_MISMATCH') */
+  failureReason?: string
+  /** Failure message with details (e.g., contains 'CHALLENGE_TYPE_GOOGLE') */
+  failureMessage?: string
+}
+
+/**
+ * OAuth initiation parameters
+ */
+export interface OAuthInitiateParams {
+  /** Type of OAuth challenge (GITHUB, GOOGLE, SLACK, etc.) */
+  challengeType: ChallengeType
+  /** URL where OAuth provider should redirect after authorization */
+  callbackUrl: string
+}
+
+/**
+ * OAuth verification parameters
+ */
+export interface OAuthVerifyParams extends OAuthCallbackParams {
+  /** Type of OAuth challenge being verified */
+  challengeType: ChallengeType
+}
+
+/**
+ * OAuth Service interface
+ *
+ * Handles OAuth redirect-based authentication flows.
+ * Unlike ChallengeSolver (which solves challenges synchronously),
+ * OAuth requires external user action and callback handling.
+ *
+ * Flow:
+ * 1. initiate() - Get authorization URL and redirect user
+ * 2. parseCallback() - Extract params from callback URL
+ * 3. verify() - Submit authorization code to backend
+ */
+export interface OAuthService {
+  /**
+   * Initiate OAuth flow by requesting authorization URL from backend
+   * @param params - Challenge type and callback URL
+   * @returns Authorization URL to redirect user to
+   */
+  initiate(params: OAuthInitiateParams): Promise<OAuthInitiationResult>
+
+  /**
+   * Parse OAuth callback URL to extract parameters
+   * @param url - Callback URL with query params from OAuth provider
+   * @returns Extracted callback parameters
+   */
+  parseCallback(url: URL): OAuthCallbackParams
+
+  /**
+   * Verify OAuth callback by submitting authorization code to backend
+   * @param params - Callback params plus challenge type
+   * @returns Verification result
+   */
+  verify(params: OAuthVerifyParams): Promise<OAuthVerificationResult>
+}

package/src/performance/createNoopPerformanceTracker.ts

@@ -0,0 +1,12 @@
+import { PERFORMANCE_TRACKING_DISABLED } from '@luxexchange/sessions/src/performance/createPerformanceTracker'
+import type { PerformanceTracker } from '@luxexchange/sessions/src/performance/types'
+
+/**
+ * Creates a noop performance tracker that always returns the disabled sentinel.
+ * Use this when performance tracking is not needed (e.g., extension, mobile, tests).
+ */
+function createNoopPerformanceTracker(): PerformanceTracker {
+  return { now: () => PERFORMANCE_TRACKING_DISABLED }
+}
+
+export { createNoopPerformanceTracker }

package/src/performance/createPerformanceTracker.ts

@@ -0,0 +1,43 @@
+import type { PerformanceTracker } from '@luxexchange/sessions/src/performance/types'
+
+/** Sentinel value indicating performance tracking is disabled */
+export const PERFORMANCE_TRACKING_DISABLED = -1
+
+interface CreatePerformanceTrackerContext {
+  /** Feature flag to enable/disable performance tracking. Required. */
+  getIsPerformanceTrackingEnabled: () => boolean
+  /**
+   * Injected timing function. This is the actual performance API.
+   * Allows the caller to pass performance.now, Date.now, or a mock.
+   * Required - no implicit dependency on globalThis.performance.
+   */
+  getNow: () => number
+}
+
+/**
+ * Creates a performance tracker with feature flag control.
+ *
+ * Behavior:
+ * - If tracking is disabled (feature flag returns false), returns -1 (sentinel)
+ * - Otherwise calls the injected getNow() function
+ *
+ * The sentinel value (-1) allows analytics consumers to distinguish
+ * between "0ms duration" and "tracking was disabled".
+ *
+ * Note: All dependencies are explicitly passed in - no implicit globals.
+ */
+function createPerformanceTracker(ctx: CreatePerformanceTrackerContext): PerformanceTracker {
+  function now(): number {
+    // If disabled via feature flag, return sentinel (-1)
+    if (!ctx.getIsPerformanceTrackingEnabled()) {
+      return PERFORMANCE_TRACKING_DISABLED
+    }
+
+    return ctx.getNow()
+  }
+
+  return { now }
+}
+
+export { createPerformanceTracker }
+export type { CreatePerformanceTrackerContext }

package/src/performance/index.ts

@@ -0,0 +1,7 @@
+/* eslint-disable check-file/no-index */
+export type { CreatePerformanceTrackerContext } from '@luxexchange/sessions/src/performance/createPerformanceTracker'
+export {
+  createPerformanceTracker,
+  PERFORMANCE_TRACKING_DISABLED,
+} from '@luxexchange/sessions/src/performance/createPerformanceTracker'
+export type { PerformanceTracker } from '@luxexchange/sessions/src/performance/types'

package/src/performance/types.ts

@@ -0,0 +1,11 @@
+/**
+ * Contract for performance timing.
+ * Abstraction over performance.now() that can be:
+ * - Injected for testing
+ * - Disabled via feature flag
+ * - Platform-specific (browser vs React Native vs Node)
+ */
+export interface PerformanceTracker {
+  /** Returns current high-resolution timestamp in milliseconds */
+  now(): number
+}