@l.x/sessions 1.0.3 → 1.0.5

package/src/session-initialization/createSessionInitializationService.ts

@@ -0,0 +1,184 @@
+import type { ChallengeSolverService } from '@l.x/sessions/src/challenge-solvers/types'
+import type { PerformanceTracker } from '@l.x/sessions/src/performance/types'
+import {
+  MaxChallengeRetriesError,
+  NoSolverAvailableError,
+} from '@l.x/sessions/src/session-initialization/sessionErrors'
+import type { SessionService } from '@l.x/sessions/src/session-service/types'
+import type { Logger } from 'utilities/src/logger/logger'
+
+interface SessionInitResult {
+  sessionId: string | null
+}
+
+/**
+ * Callbacks for session initialization lifecycle events.
+ * Each callback is optional and focused on one event.
+ */
+export interface SessionInitAnalytics {
+  /** Called when session initialization starts */
+  onInitStarted?: () => void
+  /** Called when session initialization completes (before challenge flow) */
+  onInitCompleted?: (data: { needChallenge: boolean; durationMs: number }) => void
+  /** Called when a challenge is received from the backend */
+  onChallengeReceived?: (data: { challengeType: string; challengeId: string }) => void
+  /** Called when session verification completes (success or retry) */
+  onVerifyCompleted?: (data: { success: boolean; attemptNumber: number; totalDurationMs: number }) => void
+}
+
+interface SessionInitOptions {
+  /**
+   * If provided, skips the initSession() RPC call and uses this value directly.
+   * Useful when the caller already knows the answer (e.g. from a prior init call).
+   */
+  needChallenge?: boolean
+}
+
+interface SessionInitializationService {
+  /**
+   * Orchestrates the complete session initialization flow:
+   * 1. Calls initSession (backend decides whether to create new or reuse existing)
+   * 2. Handles challenge solving if required
+   *
+   * Pass `options.needChallenge` to skip step 1 when the answer is already known.
+   *
+   * @throws Error if initialization fails
+   */
+  initialize(options?: SessionInitOptions): Promise<SessionInitResult>
+}
+
+function createSessionInitializationService(ctx: {
+  getSessionService: () => SessionService
+  challengeSolverService: ChallengeSolverService
+  /**
+   * Required: Performance tracker for timing measurements.
+   * Must be injected - no implicit dependency on globalThis.performance.
+   */
+  performanceTracker: PerformanceTracker
+  getIsSessionUpgradeAutoEnabled?: () => boolean
+  maxChallengeRetries?: number
+  getLogger?: () => Logger
+  /** Analytics callbacks for tracking session initialization lifecycle */
+  analytics?: SessionInitAnalytics
+}): SessionInitializationService {
+  const log = ctx.getLogger?.()
+
+  async function handleChallengeFlow(attemptCount = 0, flowStartTime?: number): Promise<void> {
+    const startTime = flowStartTime ?? ctx.performanceTracker.now()
+    const maxRetries = ctx.maxChallengeRetries ?? 3
+
+    const challenge = await ctx.getSessionService().requestChallenge()
+
+    log?.debug('createSessionInitializationService', 'handleChallengeFlow', 'Requesting challenge', {
+      challenge,
+    })
+
+    // Report challenge received (only on first attempt)
+    if (attemptCount === 0) {
+      const data = { challengeType: String(challenge.challengeType), challengeId: challenge.challengeId }
+      ctx.analytics?.onChallengeReceived?.(data)
+      log?.info('sessions', 'challengeReceived', 'Challenge received', data)
+    }
+
+    // get our solver for the challenge type
+    const solver = ctx.challengeSolverService.getSolver(challenge.challengeType)
+    if (!solver) {
+      throw new NoSolverAvailableError(challenge.challengeType)
+    }
+
+    // Solve the challenge — if the solver throws (e.g. Turnstile domain mismatch on
+    // Vercel previews), submit a placeholder solution so verifySession can reject it
+    // and the retry loop can request a different challenge type (typically Hashcash).
+    // Note: we use a non-empty placeholder because proto3 omits empty strings from the
+    // wire, which means the backend wouldn't see the solution field at all.
+    let solution: string
+    try {
+      solution = await solver.solve({
+        challengeId: challenge.challengeId,
+        challengeType: challenge.challengeType,
+        extra: challenge.extra,
+        challengeData: challenge.challengeData,
+      })
+    } catch (solverError) {
+      log?.warn(
+        'createSessionInitializationService',
+        'handleChallengeFlow',
+        'Solver failed, submitting placeholder solution to trigger fallback',
+        { error: solverError, challengeType: challenge.challengeType },
+      )
+      solution = 'solver-failed'
+    }
+
+    log?.debug('createSessionInitializationService', 'handleChallengeFlow', 'Solved challenge', { solution })
+
+    // Verify session with the solution
+    const result = await ctx.getSessionService().verifySession({
+      solution,
+      challengeId: challenge.challengeId,
+      challengeType: challenge.challengeType,
+    })
+
+    const verifyData = {
+      success: !result.retry,
+      attemptNumber: attemptCount + 1,
+      totalDurationMs: ctx.performanceTracker.now() - startTime,
+    }
+    ctx.analytics?.onVerifyCompleted?.(verifyData)
+    log?.info('sessions', 'verifyCompleted', 'Verify completed', verifyData)
+
+    if (!result.retry) {
+      return
+    }
+
+    // Handle server retry request
+    if (attemptCount >= maxRetries) {
+      throw new MaxChallengeRetriesError(maxRetries, attemptCount + 1)
+    }
+
+    await handleChallengeFlow(attemptCount + 1, startTime) // Recursive call with incremented count
+  }
+
+  async function initialize(options?: SessionInitOptions): Promise<SessionInitResult> {
+    const initStartTime = ctx.performanceTracker.now()
+
+    let needChallenge: boolean
+    let sessionId: string | undefined
+
+    if (options?.needChallenge !== undefined) {
+      // Caller already knows — skip the initSession() RPC
+      needChallenge = options.needChallenge
+      sessionId = undefined
+
+      const data = { needChallenge, durationMs: 0 }
+      ctx.analytics?.onInitCompleted?.(data)
+      log?.info('sessions', 'initCompleted', 'Session init completed', data)
+    } else {
+      // Discover from backend
+      ctx.analytics?.onInitStarted?.()
+      log?.info('sessions', 'initStarted', 'Session init started')
+
+      const initResponse = await ctx.getSessionService().initSession()
+      needChallenge = initResponse.needChallenge
+      sessionId = initResponse.sessionId
+
+      const data = { needChallenge, durationMs: ctx.performanceTracker.now() - initStartTime }
+      ctx.analytics?.onInitCompleted?.(data)
+      log?.info('sessions', 'initCompleted', 'Session init completed', data)
+    }
+
+    // Handle challenge if required and enabled
+    if (needChallenge && ctx.getIsSessionUpgradeAutoEnabled?.()) {
+      await handleChallengeFlow()
+    }
+
+    // sessionId is null for web (stored in cookie), real ID for non-web platforms
+    return {
+      sessionId: sessionId ?? null,
+    }
+  }
+
+  return { initialize }
+}
+
+export { createSessionInitializationService }
+export type { SessionInitializationService, SessionInitOptions, SessionInitResult }

package/src/session-initialization/sessionErrors.ts

@@ -0,0 +1,32 @@
+/**
+ * Base class for session-related errors that should not trigger retries at higher levels.
+ */
+export abstract class SessionError extends Error {
+  constructor(message: string, name: string) {
+    super(message)
+    this.name = name
+  }
+}
+
+/**
+ * Error thrown when maximum challenge retry attempts are exceeded.
+ * This error should not trigger additional retries at higher levels.
+ */
+export class MaxChallengeRetriesError extends SessionError {
+  constructor(maxRetries: number, actualAttempts: number) {
+    super(
+      `Maximum challenge retry attempts (${maxRetries}) exceeded after ${actualAttempts} attempts`,
+      'MaxChallengeRetriesError',
+    )
+  }
+}
+
+/**
+ * Error thrown when no solver is available for a challenge type.
+ * This error should not trigger additional retries at higher levels.
+ */
+export class NoSolverAvailableError extends SessionError {
+  constructor(challengeType: number) {
+    super(`No solver available for challenge type: ${challengeType}`, 'NoSolverAvailableError')
+  }
+}

package/src/session-repository/createSessionClient.ts

@@ -0,0 +1,10 @@
+import { createPromiseClient, type PromiseClient, type Transport } from '@connectrpc/connect'
+import { SessionService } from '@luxamm/client-platform-service/dist/lx/platformservice/v1/sessionService_connect'
+
+type SessionServiceClient = PromiseClient<typeof SessionService>
+
+function createSessionClient(ctx: { transport: Transport }): PromiseClient<typeof SessionService> {
+  return createPromiseClient(SessionService, ctx.transport)
+}
+
+export { type SessionServiceClient, createSessionClient }

package/src/session-repository/createSessionRepository.test.ts

@@ -0,0 +1,313 @@
+import type { PromiseClient } from '@connectrpc/connect'
+import type { SessionService } from '@luxamm/client-platform-service/dist/lx/platformservice/v1/sessionService_connect'
+import {
+  ChallengeFailure,
+  ChallengeFailure_Reason,
+  ChallengeResponse,
+  GetChallengeTypesResponse,
+  InitSessionResponse,
+  SignoutResponse,
+} from '@luxamm/client-platform-service/dist/lx/platformservice/v1/sessionService_pb'
+import { createSessionRepository } from '@l.x/sessions/src/session-repository/createSessionRepository'
+import { ChallengeRejectedError } from '@l.x/sessions/src/session-repository/errors'
+import { ChallengeType } from '@l.x/sessions/src/session-service/types'
+import { describe, expect, it, type MockedFunction, vi } from 'vitest'
+
+type MockedClient = {
+  [K in keyof PromiseClient<typeof SessionService>]: MockedFunction<PromiseClient<typeof SessionService>[K]>
+}
+
+describe('createSessionRepository', () => {
+  const createMockClient = (): MockedClient => ({
+    initSession: vi.fn().mockResolvedValue({
+      sessionId: 'test-session-123',
+      deviceId: 'test-device-123',
+      needChallenge: false,
+      extra: {},
+    }),
+    challenge: vi.fn().mockResolvedValue({
+      challengeId: 'challenge-123',
+      challengeType: 1,
+      extra: { sitekey: 'test-key' },
+      challengeData: { case: undefined },
+    }),
+    verify: vi.fn().mockResolvedValue({
+      retry: false,
+      outcome: { case: 'success' as const, value: {} },
+    }),
+    updateSession: vi.fn().mockResolvedValue({}),
+    deleteSession: vi.fn().mockResolvedValue({}),
+    introspectSession: vi.fn().mockResolvedValue({}), // Required by proto but not used
+    getChallengeTypes: vi.fn().mockResolvedValue(new GetChallengeTypesResponse({ challengeTypes: [] })),
+    signout: vi.fn().mockResolvedValue(new SignoutResponse({})),
+  })
+
+  describe('session initialization behaviors', () => {
+    it('initializes a session and returns session data', async () => {
+      const mockClient = createMockClient()
+      const repository = createSessionRepository({ client: mockClient as PromiseClient<typeof SessionService> })
+
+      const result = await repository.initSession()
+
+      expect(result).toEqual({
+        sessionId: 'test-session-123',
+        deviceId: 'test-device-123',
+        needChallenge: false,
+        extra: {},
+      })
+    })
+
+    it('handles web sessions without session ID', async () => {
+      const mockClient = createMockClient()
+      mockClient.initSession.mockResolvedValue(
+        new InitSessionResponse({
+          sessionId: undefined,
+          deviceId: undefined,
+          needChallenge: true,
+          extra: { sitekey: 'turnstile-key' },
+        }),
+      )
+
+      const repository = createSessionRepository({ client: mockClient })
+      const result = await repository.initSession()
+
+      // Web sessions don't return sessionId or deviceId (managed by cookies)
+      expect(result.sessionId).toBeUndefined()
+      expect(result.deviceId).toBeUndefined()
+      expect(result.needChallenge).toBe(true)
+      expect(result.extra).toEqual({ sitekey: 'turnstile-key' })
+    })
+
+    it('provides meaningful error when initialization fails', async () => {
+      const mockClient = createMockClient()
+      mockClient.initSession.mockRejectedValue(new Error('Network error'))
+
+      const repository = createSessionRepository({ client: mockClient })
+
+      await expect(repository.initSession()).rejects.toThrow('Failed to initialize session')
+    })
+  })
+
+  describe('bot detection behaviors', () => {
+    it('retrieves challenge information for bot detection', async () => {
+      const mockClient = createMockClient()
+      const repository = createSessionRepository({ client: mockClient as PromiseClient<typeof SessionService> })
+
+      const result = await repository.challenge({})
+
+      expect(result).toEqual({
+        challengeId: 'challenge-123',
+        challengeType: 1,
+        extra: { sitekey: 'test-key' },
+        challengeData: { case: undefined },
+        authorizeUrl: undefined,
+      })
+    })
+
+    it('throws ChallengeRejectedError when response has failure field', async () => {
+      const mockClient = createMockClient()
+      mockClient.challenge.mockResolvedValue(
+        new ChallengeResponse({
+          failure: new ChallengeFailure({ reason: ChallengeFailure_Reason.UNSPECIFIED }),
+        }),
+      )
+
+      const repository = createSessionRepository({ client: mockClient })
+
+      await expect(repository.challenge({})).rejects.toThrow(ChallengeRejectedError)
+      await expect(repository.challenge({})).rejects.toThrow('REASON_UNSPECIFIED')
+    })
+
+    it('throws ChallengeRejectedError with BOT_DETECTION_REQUIRED reason', async () => {
+      const mockClient = createMockClient()
+      mockClient.challenge.mockResolvedValue(
+        new ChallengeResponse({
+          failure: new ChallengeFailure({ reason: ChallengeFailure_Reason.BOT_DETECTION_REQUIRED }),
+        }),
+      )
+
+      const repository = createSessionRepository({ client: mockClient })
+
+      await expect(repository.challenge({})).rejects.toThrow(ChallengeRejectedError)
+      await expect(repository.challenge({})).rejects.toThrow('REASON_BOT_DETECTION_REQUIRED')
+    })
+
+    it('does NOT throw ChallengeRejectedError when no failure field is present', async () => {
+      const mockClient = createMockClient()
+      mockClient.challenge.mockResolvedValue(new ChallengeResponse({ challengeId: 'some-id', challengeType: 0 }))
+
+      const repository = createSessionRepository({ client: mockClient })
+      const result = await repository.challenge({})
+
+      expect(result.challengeId).toBe('some-id')
+    })
+
+    it('ChallengeRejectedError has typed reason and rawFailure fields', async () => {
+      const mockClient = createMockClient()
+      mockClient.challenge.mockResolvedValue(
+        new ChallengeResponse({
+          failure: new ChallengeFailure({ reason: ChallengeFailure_Reason.BOT_DETECTION_REQUIRED }),
+        }),
+      )
+
+      const repository = createSessionRepository({ client: mockClient })
+
+      try {
+        await repository.challenge({})
+        expect.fail('Should have thrown')
+      } catch (error) {
+        expect(error).toBeInstanceOf(ChallengeRejectedError)
+        const rejected = error as ChallengeRejectedError
+        expect(rejected.reason).toBe('REASON_BOT_DETECTION_REQUIRED')
+        expect(rejected.rawFailure).toBeDefined()
+        expect(rejected.name).toBe('ChallengeRejectedError')
+      }
+    })
+
+    it('provides meaningful error when challenge request fails', async () => {
+      const mockClient = createMockClient()
+      mockClient.challenge.mockRejectedValue(new Error('API error'))
+
+      const repository = createSessionRepository({ client: mockClient })
+
+      await expect(repository.challenge({})).rejects.toThrow('Failed to get challenge')
+    })
+  })
+
+  describe('session verify behaviors', () => {
+    it('submits bot detection solution', async () => {
+      const mockClient = createMockClient()
+      const repository = createSessionRepository({ client: mockClient as PromiseClient<typeof SessionService> })
+
+      const result = await repository.verifySession({
+        solution: 'solution-token',
+        challengeId: 'challenge-123',
+        challengeType: ChallengeType.TURNSTILE,
+      })
+
+      // Verify the client was called correctly (challengeType maps to 'type' in the backend API)
+      expect(mockClient.verify).toHaveBeenCalledWith({
+        solution: 'solution-token',
+        challengeId: 'challenge-123',
+        type: ChallengeType.TURNSTILE,
+      })
+
+      // Should return retry status
+      expect(result).toEqual({ retry: false })
+    })
+
+    it('handles verify with additional parameters', async () => {
+      const mockClient = createMockClient()
+      const repository = createSessionRepository({ client: mockClient as PromiseClient<typeof SessionService> })
+
+      const result = await repository.verifySession({
+        solution: 'solution-token',
+        challengeId: 'challenge-123',
+        challengeType: ChallengeType.TURNSTILE,
+      })
+
+      // Should succeed with required params
+      expect(result).toEqual({ retry: false })
+    })
+
+    it('treats undefined outcome with retry=false as success (proto3 dropped empty VerifySuccess)', async () => {
+      const mockClient = createMockClient()
+      mockClient.verify.mockResolvedValue({
+        retry: false,
+        outcome: { case: undefined, value: undefined },
+      })
+
+      const repository = createSessionRepository({ client: mockClient })
+
+      const result = await repository.verifySession({
+        solution: 'solution-token',
+        challengeId: 'challenge-123',
+        challengeType: ChallengeType.TURNSTILE,
+      })
+
+      // Proto3 drops empty VerifySuccess — retry: false signals success
+      expect(result.retry).toBe(false)
+    })
+
+    it('allows undefined outcome when retry is true (valid retry-only response)', async () => {
+      const mockClient = createMockClient()
+      mockClient.verify.mockResolvedValue({
+        retry: true,
+        outcome: { case: undefined, value: undefined },
+      })
+
+      const repository = createSessionRepository({ client: mockClient })
+
+      const result = await repository.verifySession({
+        solution: 'solution-token',
+        challengeId: 'challenge-123',
+        challengeType: ChallengeType.TURNSTILE,
+      })
+
+      expect(result.retry).toBe(true)
+    })
+
+    it('returns failure info from verify failure outcome', async () => {
+      const mockClient = createMockClient()
+      mockClient.verify.mockResolvedValue({
+        retry: true,
+        outcome: {
+          case: 'failure' as const,
+          value: {
+            reason: 1, // INVALID_SOLUTION
+            message: 'Bad code',
+            waitSeconds: 30,
+          },
+        },
+      })
+
+      const repository = createSessionRepository({ client: mockClient })
+
+      const result = await repository.verifySession({
+        solution: 'bad-code',
+        challengeId: 'challenge-123',
+        challengeType: ChallengeType.TURNSTILE,
+      })
+
+      expect(result.retry).toBe(true)
+      expect(result.failureReason).toBe('REASON_INVALID_SOLUTION')
+      expect(result.failureMessage).toBe('Bad code')
+      expect(result.waitSeconds).toBe(30)
+    })
+
+    it('provides meaningful error when verify fails', async () => {
+      const mockClient = createMockClient()
+      mockClient.verify.mockRejectedValue(new Error('Invalid solution'))
+
+      const repository = createSessionRepository({ client: mockClient })
+
+      await expect(
+        repository.verifySession({
+          solution: 'bad-token',
+          challengeId: 'challenge-123',
+          challengeType: ChallengeType.TURNSTILE,
+        }),
+      ).rejects.toThrow('Failed to verify session')
+    })
+  })
+
+  describe('session cleanup behaviors', () => {
+    it('deletes session successfully', async () => {
+      const mockClient = createMockClient()
+      const repository = createSessionRepository({ client: mockClient as PromiseClient<typeof SessionService> })
+
+      const result = await repository.deleteSession({})
+
+      expect(result).toEqual({})
+    })
+
+    it('provides meaningful error when deletion fails', async () => {
+      const mockClient = createMockClient()
+      mockClient.signout.mockRejectedValue(new Error('Server error'))
+
+      const repository = createSessionRepository({ client: mockClient })
+
+      await expect(repository.deleteSession({})).rejects.toThrow('Failed to delete session')
+    })
+  })
+})