@luxexchange/sessions 1.0.0

package/src/sessionLifecycle.integration.test.ts

@@ -0,0 +1,264 @@
+import {
+  ChallengeResponse,
+  ChallengeType,
+  DeleteSessionResponse,
+  GetChallengeTypesResponse,
+  InitSessionResponse,
+  IntrospectSessionResponse,
+  SignoutResponse,
+  UpdateSessionResponse,
+  VerifyResponse,
+} from '@luxdex/client-platform-service/dist/uniswap/platformservice/v1/sessionService_pb'
+import { createSessionRepository } from '@luxfi/sessions/src/session-repository/createSessionRepository'
+import { createSessionService } from '@luxfi/sessions/src/session-service/createSessionService'
+import type { SessionService } from '@luxfi/sessions/src/session-service/types'
+import {
+  createMockSessionClient,
+  InMemoryDeviceIdService,
+  InMemorySessionStorage,
+  InMemoryLuxIdentifierService,
+  type MockEndpoints,
+} from '@luxfi/sessions/src/test-utils'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+describe('Session Lifecycle Integration Tests', () => {
+  let sessionStorage: InMemorySessionStorage
+  let deviceIdService: InMemoryDeviceIdService
+  let luxIdentifierService: InMemoryLuxIdentifierService
+  let sessionService: SessionService
+  let mockEndpoints: MockEndpoints
+
+  beforeEach(() => {
+    // Initialize in-memory storage
+    sessionStorage = new InMemorySessionStorage()
+    deviceIdService = new InMemoryDeviceIdService()
+    luxIdentifierService = new InMemoryLuxIdentifierService()
+
+    // Set up mock endpoints with default responses
+    mockEndpoints = {
+      '/lux.platformservice.v1.SessionService/InitSession': async (): Promise<InitSessionResponse> => {
+        return new InitSessionResponse({
+          sessionId: 'test-session-123',
+          needChallenge: false,
+          extra: {},
+        })
+      },
+      '/lux.platformservice.v1.SessionService/Challenge': async (): Promise<ChallengeResponse> => {
+        return new ChallengeResponse({
+          challengeId: 'challenge-123',
+          challengeType: ChallengeType.TURNSTILE,
+          extra: { sitekey: 'test-key' },
+        })
+      },
+      '/lux.platformservice.v1.SessionService/Verify': async (): Promise<VerifyResponse> => {
+        return new VerifyResponse({
+          retry: false,
+        })
+      },
+      '/lux.platformservice.v1.SessionService/DeleteSession': async (): Promise<DeleteSessionResponse> => {
+        return new DeleteSessionResponse({})
+      },
+      '/lux.platformservice.v1.SessionService/IntrospectSession': async (): Promise<IntrospectSessionResponse> => {
+        return new IntrospectSessionResponse({})
+      },
+      '/lux.platformservice.v1.SessionService/UpdateSession': async (): Promise<UpdateSessionResponse> => {
+        return new UpdateSessionResponse({})
+      },
+      '/lux.platformservice.v1.SessionService/GetChallengeTypes': async (): Promise<GetChallengeTypesResponse> => {
+        return new GetChallengeTypesResponse({ challengeTypes: [] })
+      },
+      '/lux.platformservice.v1.SessionService/Signout': async (): Promise<SignoutResponse> => {
+        return new SignoutResponse({})
+      },
+    }
+
+    // Create session client with test transport
+    const sessionClient = createMockSessionClient(mockEndpoints, sessionStorage, deviceIdService)
+
+    // Create repository
+    const sessionRepository = createSessionRepository({
+      client: sessionClient as any,
+    })
+
+    // Create session service
+    sessionService = createSessionService({
+      sessionStorage,
+      deviceIdService,
+      luxIdentifierService,
+      sessionRepository,
+    })
+  })
+
+  afterEach(async () => {
+    // Clean up any stored data
+    await sessionStorage.clear()
+    await deviceIdService.removeDeviceId()
+  })
+
+  it('initializes and stores a session', async () => {
+    const response = await sessionService.initSession()
+
+    expect(response).toEqual({
+      sessionId: 'test-session-123',
+      needChallenge: false,
+      extra: {},
+    })
+
+    // Verify session was stored
+    const storedSession = await sessionStorage.get()
+    expect(storedSession?.sessionId).toBe('test-session-123')
+  })
+
+  it('handles session initialization without challenge requirement', async () => {
+    // Override default to return needChallenge: false
+    mockEndpoints['/lux.platformservice.v1.SessionService/InitSession'] =
+      async (): Promise<InitSessionResponse> => {
+        return new InitSessionResponse({
+          sessionId: 'simple-session-123',
+          needChallenge: false,
+          extra: {},
+        })
+      }
+
+    await deviceIdService.setDeviceId('simple-device-123')
+
+    // Initialize
+    const response = await sessionService.initSession()
+
+    // Verify response
+    expect(response.sessionId).toBe('simple-session-123')
+    expect(response.needChallenge).toBe(false)
+
+    // Session should be stored
+    const storedSession = await sessionStorage.get()
+    expect(storedSession?.sessionId).toBe('simple-session-123')
+  })
+
+  it('properly clears session on deletion', async () => {
+    // Initialize a session first
+    await sessionService.initSession()
+
+    // Verify session exists
+    let storedSession = await sessionStorage.get()
+    expect(storedSession?.sessionId).toBe('test-session-123')
+
+    // Delete session
+    await sessionService.removeSession()
+
+    // Verify session is cleared
+    storedSession = await sessionStorage.get()
+    expect(storedSession).toBeNull()
+  })
+
+  it('stores session ID when provided (mobile/extension behavior)', async () => {
+    mockEndpoints['/lux.platformservice.v1.SessionService/InitSession'] =
+      async (): Promise<InitSessionResponse> => {
+        return new InitSessionResponse({
+          sessionId: 'mobile-session-123',
+          needChallenge: false,
+          extra: {},
+        })
+      }
+
+    const response = await sessionService.initSession()
+
+    expect(response.sessionId).toBe('mobile-session-123')
+
+    // Session should be stored
+    const storedSession = await sessionStorage.get()
+    expect(storedSession?.sessionId).toBe('mobile-session-123')
+  })
+
+  it('handles web sessions without storing session ID when undefined', async () => {
+    mockEndpoints['/lux.platformservice.v1.SessionService/InitSession'] =
+      async (): Promise<InitSessionResponse> => {
+        return new InitSessionResponse({
+          sessionId: undefined,
+          needChallenge: true,
+          extra: { sitekey: 'turnstile-key' },
+        })
+      }
+
+    const response = await sessionService.initSession()
+
+    expect(response.sessionId).toBeUndefined()
+    expect(response.needChallenge).toBe(true)
+
+    // Session should not be stored
+    const storedSession = await sessionStorage.get()
+    expect(storedSession).toBeNull()
+  })
+
+  it('retrieves existing session state', async () => {
+    // Initialize a session
+    await sessionService.initSession()
+
+    // Get session state
+    const sessionState = await sessionService.getSessionState()
+
+    expect(sessionState).toEqual({
+      sessionId: 'test-session-123',
+    })
+  })
+
+  it('returns null when no session exists', async () => {
+    // Don't initialize any session
+    const sessionState = await sessionService.getSessionState()
+
+    expect(sessionState).toBeNull()
+  })
+
+  it('handles multiple initialization attempts', async () => {
+    // First initialization
+    await sessionService.initSession()
+
+    const firstSession = await sessionStorage.get()
+    expect(firstSession?.sessionId).toBe('test-session-123')
+
+    // Update mock to return different session
+    mockEndpoints['/lux.platformservice.v1.SessionService/InitSession'] =
+      async (): Promise<InitSessionResponse> => {
+        return new InitSessionResponse({
+          sessionId: 'new-session-789',
+          needChallenge: false,
+          extra: {},
+        })
+      }
+
+    // Second initialization should replace the first
+    await sessionService.initSession()
+
+    const secondSession = await sessionStorage.get()
+    expect(secondSession?.sessionId).toBe('new-session-789')
+  })
+
+  it('sets and retrieves device ID through init response', async () => {
+    mockEndpoints['/lux.platformservice.v1.SessionService/InitSession'] =
+      async (): Promise<InitSessionResponse> => {
+        return new InitSessionResponse({
+          sessionId: 'device-test-session',
+          deviceId: 'new-device-123',
+          needChallenge: false,
+          extra: {},
+        })
+      }
+
+    await sessionService.initSession()
+
+    // Device ID should be stored
+    const deviceId = await deviceIdService.getDeviceId()
+    expect(deviceId).toBe('new-device-123')
+  })
+
+  it('preserves existing device ID when not provided in response', async () => {
+    // Set device ID first
+    await deviceIdService.setDeviceId('existing-device-456')
+
+    // Init without device_id in response
+    await sessionService.initSession()
+
+    // Device ID should remain unchanged
+    const deviceId = await deviceIdService.getDeviceId()
+    expect(deviceId).toBe('existing-device-456')
+  })
+})

package/src/test-utils/createLocalCookieTransport.ts

@@ -0,0 +1,52 @@
+import type { Transport } from '@connectrpc/connect'
+import { createConnectTransport } from '@connectrpc/connect-web'
+
+/**
+ * Creates a test transport that simulates browser cookie behavior
+ * for integration testing with real backends.
+ */
+export function createLocalCookieTransport(options: { baseUrl: string; cookieJar: Map<string, string> }): Transport {
+  const { baseUrl, cookieJar } = options
+
+  return createConnectTransport({
+    baseUrl,
+    credentials: 'include', // Tell backend we want cookies
+    interceptors: [
+      (next) => async (request) => {
+        // Add required headers that backend expects
+        request.header.set('x-request-source', 'lux-web')
+
+        // Simulate browser cookie behavior: add stored cookies to request
+        if (cookieJar.size > 0) {
+          const cookieHeader = Array.from(cookieJar.entries())
+            .map(([name, value]) => `${name}=${value}`)
+            .join('; ')
+          request.header.set('cookie', cookieHeader)
+        }
+
+        // Make the request
+        const response = await next(request)
+
+        // Simulate browser cookie behavior: store cookies from response
+        for (const cookie of response.header.getSetCookie()) {
+          const [nameValue] = cookie.split(';')
+          if (nameValue) {
+            const [name, value] = nameValue.split('=')
+            if (name && value) {
+              cookieJar.set(name.trim(), value.trim())
+            }
+          }
+        }
+
+        return response
+      },
+    ],
+  })
+}
+
+/**
+ * Creates a cookie jar for managing cookies in tests
+ */
+export function createCookieJar(): Map<string, string> {
+  return new Map<string, string>()
+}

package/src/test-utils/createLocalHeaderTransport.ts

@@ -0,0 +1,45 @@
+import type { Transport } from '@connectrpc/connect'
+import { createConnectTransport } from '@connectrpc/connect-web'
+
+interface CreateLocalHeaderTransportOptions {
+  baseUrl: string
+  requestSource: 'lux-ios' | 'lux-android' | 'lux-extension'
+  getSessionId: () => Promise<string | null>
+  getDeviceId: () => Promise<string | null>
+}
+
+/**
+ * Creates a test transport that simulates native app behavior
+ * for integration testing with real backends.
+ *
+ * Unlike web which uses cookies, native platforms send session
+ * and device IDs via headers on every request.
+ */
+export function createLocalHeaderTransport(options: CreateLocalHeaderTransportOptions): Transport {
+  const { baseUrl, requestSource, getSessionId, getDeviceId } = options
+
+  return createConnectTransport({
+    baseUrl,
+    // NO credentials: 'include' - native platforms don't use cookies
+    interceptors: [
+      (next) => async (request) => {
+        // Add platform-specific request source header
+        request.header.set('x-request-source', requestSource)
+
+        // Add session ID header if available
+        const sessionId = await getSessionId()
+        if (sessionId) {
+          request.header.set('X-Session-ID', sessionId)
+        }
+
+        // Add device ID header if available
+        const deviceId = await getDeviceId()
+        if (deviceId) {
+          request.header.set('X-Device-ID', deviceId)
+        }
+
+        return next(request)
+      },
+    ],
+  })
+}

package/src/test-utils/mocks.ts

@@ -0,0 +1,122 @@
+import type { ChallengeSolver, ChallengeSolverService } from '@luxfi/sessions/src/challenge-solvers/types'
+import type { SessionService } from '@luxfi/sessions/src/session-service/types'
+import { ChallengeType } from '@luxfi/sessions/src/session-service/types'
+import { vi } from 'vitest'
+
+/**
+ * Creates a mock SessionService with sensible defaults
+ * All methods are vi.fn() mocks that can be overridden
+ */
+export function createMockSessionService(overrides: Partial<SessionService> = {}): SessionService {
+  return {
+    getSessionState: vi.fn().mockResolvedValue(null),
+    initSession: vi.fn().mockResolvedValue({
+      sessionId: 'mock-session-123',
+      needChallenge: false,
+      extra: {},
+    }),
+    requestChallenge: vi.fn().mockResolvedValue({
+      challengeId: 'mock-challenge-456',
+      challengeType: ChallengeType.TURNSTILE,
+      extra: {},
+      challengeData: { case: 'turnstile', value: { siteKey: 'mock-sitekey', action: 'verify' } },
+    }),
+    verifySession: vi.fn().mockResolvedValue({
+      retry: false,
+    }),
+    removeSession: vi.fn().mockResolvedValue(undefined),
+    ...overrides,
+  }
+}
+
+/**
+ * Creates a mock ChallengeSolver
+ */
+export function createMockChallengeSolver(
+  solveFn: () => Promise<string> = async (): Promise<string> => 'mock-solution',
+): ChallengeSolver {
+  return {
+    solve: vi.fn().mockImplementation(solveFn),
+  }
+}
+
+/**
+ * Creates a mock ChallengeSolverService
+ */
+export function createMockChallengeSolverService(
+  solvers: Map<ChallengeType, ChallengeSolver> = new Map(),
+): ChallengeSolverService {
+  // Default solvers if not provided
+  if (solvers.size === 0) {
+    solvers.set(
+      ChallengeType.TURNSTILE,
+      createMockChallengeSolver(async () => 'mock-turnstile-token'),
+    )
+    solvers.set(
+      ChallengeType.HASHCASH,
+      createMockChallengeSolver(async () => 'mock-hashcash-proof'),
+    )
+  }
+
+  return {
+    getSolver: vi.fn().mockImplementation((type: ChallengeType) => solvers.get(type) || null),
+  }
+}
+
+/**
+ * Test scenario helpers for common setups
+ */
+export const TestScenarios = {
+  /**
+   * Setup for when a session already exists
+   */
+  withExistingSession(service: SessionService, sessionId = 'existing-session-789'): void {
+    vi.mocked(service.getSessionState).mockResolvedValue({ sessionId })
+  },
+
+  /**
+   * Setup for when initialization requires no challenge
+   */
+  withNoChallenge(service: SessionService): void {
+    vi.mocked(service.getSessionState).mockResolvedValue(null)
+    vi.mocked(service.initSession).mockResolvedValue({
+      sessionId: 'new-session-111',
+      needChallenge: false,
+      extra: {},
+    })
+  },
+
+  /**
+   * Setup for when initialization requires a challenge
+   */
+  withChallengeRequired(service: SessionService, challengeType = ChallengeType.TURNSTILE): void {
+    vi.mocked(service.getSessionState).mockResolvedValue(null)
+    vi.mocked(service.initSession).mockResolvedValue({
+      sessionId: 'new-session-222',
+      needChallenge: true,
+      extra: {},
+    })
+    vi.mocked(service.requestChallenge).mockResolvedValue({
+      challengeId: 'challenge-333',
+      challengeType,
+      extra: {},
+      challengeData: { case: 'turnstile', value: { siteKey: 'test-sitekey', action: 'verify' } },
+    })
+    vi.mocked(service.verifySession).mockResolvedValue({
+      retry: false,
+    })
+  },
+
+  /**
+   * Setup for when server requests challenge retry
+   */
+  withServerRetry(service: SessionService, retriesBeforeSuccess = 1): void {
+    let attemptCount = 0
+    vi.mocked(service.verifySession).mockImplementation(async () => {
+      attemptCount++
+      return {
+        retry: attemptCount <= retriesBeforeSuccess,
+      }
+    })
+  },
+}

package/src/test-utils.ts

@@ -0,0 +1,200 @@
+/** biome-ignore-all lint/suspicious/noExplicitAny: mock handlers */
+import type { PartialMessage } from '@bufbuild/protobuf'
+import type { CallOptions } from '@connectrpc/connect'
+import { createConnectTransport } from '@connectrpc/connect-web'
+import {
+  type ChallengeRequest,
+  type ChallengeResponse,
+  type GetChallengeTypesRequest,
+  type GetChallengeTypesResponse,
+  type InitSessionRequest,
+  type InitSessionResponse,
+  type IntrospectSessionRequest,
+  type IntrospectSessionResponse,
+  type SignoutRequest,
+  type SignoutResponse,
+  type UpdateSessionRequest,
+  type UpdateSessionResponse,
+  type VerifyRequest,
+  type VerifyResponse,
+} from '@luxdex/client-platform-service/dist/uniswap/platformservice/v1/sessionService_pb'
+import type { DeviceIdService } from '@luxfi/sessions/src/device-id/types'
+import type { SessionServiceClient } from '@luxfi/sessions/src/session-repository/createSessionClient'
+import type { SessionState, SessionStorage } from '@luxfi/sessions/src/session-storage/types'
+import type { LuxIdentifierService } from '@luxfi/sessions/src/lux-identifier/types'
+// Types for our test transport
+export interface MockEndpointHandler {
+  (request: any, headers: Record<string, string>): Promise<any>
+}
+
+export interface MockEndpoints {
+  '/lux.platformservice.v1.SessionService/InitSession': MockEndpointHandler
+  '/lux.platformservice.v1.SessionService/Challenge': MockEndpointHandler
+  '/lux.platformservice.v1.SessionService/Verify': MockEndpointHandler
+  '/lux.platformservice.v1.SessionService/IntrospectSession': MockEndpointHandler
+  '/lux.platformservice.v1.SessionService/UpdateSession': MockEndpointHandler
+  '/lux.platformservice.v1.SessionService/GetChallengeTypes': MockEndpointHandler
+  '/lux.platformservice.v1.SessionService/Signout': MockEndpointHandler
+}
+
+// Test transport that intercepts requests and returns mock responses
+export function createTestTransport(mockEndpoints: MockEndpoints): ReturnType<typeof createConnectTransport> {
+  return createConnectTransport({
+    baseUrl: 'https://test.api.lux.org',
+    interceptors: [
+      (_next) => async (request) => {
+        const url = request.url
+        const path = new URL(url).pathname
+        const handler = mockEndpoints[path as keyof MockEndpoints]
+
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (!handler) {
+          throw new Error(`No mock handler for ${path}`)
+        }
+
+        // Extract headers
+        const headers: Record<string, string> = {}
+        request.header.forEach((value, key) => {
+          headers[key] = value
+        })
+
+        const requestData = request.message
+
+        const responseData = await handler(requestData, headers)
+
+        // Return properly typed response
+        return {
+          stream: false as const,
+          service: request.service,
+          method: request.method,
+          header: new Headers(),
+          message: responseData,
+          trailer: new Headers(),
+        }
+      },
+    ],
+  })
+}
+
+// In-memory storage implementations
+export class InMemorySessionStorage implements SessionStorage {
+  private state: SessionState | null = null
+
+  async get(): Promise<SessionState | null> {
+    return this.state
+  }
+
+  async set(session: SessionState): Promise<void> {
+    this.state = session
+  }
+
+  async clear(): Promise<void> {
+    this.state = null
+  }
+}
+
+export class InMemoryDeviceIdService implements DeviceIdService {
+  private deviceId: string | null = null
+
+  async getDeviceId(): Promise<string | null> {
+    return this.deviceId
+  }
+
+  async setDeviceId(id: string): Promise<void> {
+    this.deviceId = id
+  }
+
+  async removeDeviceId(): Promise<void> {
+    this.deviceId = null
+  }
+}
+
+export class InMemoryLuxIdentifierService implements LuxIdentifierService {
+  private identifier: string | null = null
+
+  async getLuxIdentifier(): Promise<string | null> {
+    return this.identifier
+  }
+
+  async setLuxIdentifier(id: string): Promise<void> {
+    this.identifier = id
+  }
+
+  async removeLuxIdentifier(): Promise<void> {
+    this.identifier = null
+  }
+}
+
+// Create a mock session client for testing
+// eslint-disable-next-line max-params
+export function createMockSessionClient(
+  mockEndpoints: MockEndpoints,
+  sessionStorage: SessionStorage,
+  deviceIdService: DeviceIdService,
+): SessionServiceClient {
+  return {
+    initSession: async (
+      request: PartialMessage<InitSessionRequest>,
+      _options?: CallOptions,
+    ): Promise<InitSessionResponse> => {
+      const response = await mockEndpoints['/lux.platformservice.v1.SessionService/InitSession'](request, {})
+      return response as InitSessionResponse
+    },
+    challenge: async (
+      request: PartialMessage<ChallengeRequest>,
+      _options?: CallOptions,
+    ): Promise<ChallengeResponse> => {
+      const sessionId = await sessionStorage.get()
+      const deviceId = await deviceIdService.getDeviceId()
+      const headers: Record<string, string> = {}
+      if (sessionId?.sessionId) {
+        headers['X-Session-ID'] = sessionId.sessionId
+      }
+      if (deviceId) {
+        headers['X-Device-ID'] = deviceId
+      }
+
+      const response = await mockEndpoints['/lux.platformservice.v1.SessionService/Challenge'](request, headers)
+      return response as ChallengeResponse
+    },
+    verify: async (request: PartialMessage<VerifyRequest>, _options?: CallOptions): Promise<VerifyResponse> => {
+      const sessionId = await sessionStorage.get()
+      const deviceId = await deviceIdService.getDeviceId()
+      const headers: Record<string, string> = {}
+      if (sessionId?.sessionId) {
+        headers['X-Session-ID'] = sessionId.sessionId
+      }
+      if (deviceId) {
+        headers['X-Device-ID'] = deviceId
+      }
+
+      const response = await mockEndpoints['/lux.platformservice.v1.SessionService/Verify'](request, headers)
+      return response as VerifyResponse
+    },
+    introspectSession: async (
+      request: PartialMessage<IntrospectSessionRequest>,
+      _options?: CallOptions,
+    ): Promise<IntrospectSessionResponse> => {
+      const response = await mockEndpoints['/lux.platformservice.v1.SessionService/IntrospectSession'](request, {})
+      return response as IntrospectSessionResponse
+    },
+    updateSession: async (
+      request: PartialMessage<UpdateSessionRequest>,
+      _options?: CallOptions,
+    ): Promise<UpdateSessionResponse> => {
+      const response = await mockEndpoints['/lux.platformservice.v1.SessionService/UpdateSession'](request, {})
+      return response as UpdateSessionResponse
+    },
+    getChallengeTypes: async (
+      request: PartialMessage<GetChallengeTypesRequest>,
+      _options?: CallOptions,
+    ): Promise<GetChallengeTypesResponse> => {
+      const response = await mockEndpoints['/lux.platformservice.v1.SessionService/GetChallengeTypes'](request, {})
+      return response as GetChallengeTypesResponse
+    },
+    signout: async (request: PartialMessage<SignoutRequest>, _options?: CallOptions): Promise<SignoutResponse> => {
+      const response = await mockEndpoints['/lux.platformservice.v1.SessionService/Signout'](request, {})
+      return response as SignoutResponse
+    },
+  }
+}