@luxexchange/sessions 1.0.0

package/src/session-repository/createSessionRepository.ts

@@ -0,0 +1,242 @@
+import {
+  ChallengeFailure_Reason,
+  VerifyFailure_Reason,
+} from '@uniswap/client-platform-service/dist/uniswap/platformservice/v1/sessionService_pb'
+import type { SessionServiceClient } from '@luxexchange/sessions/src/session-repository/createSessionClient'
+import { ChallengeRejectedError } from '@luxexchange/sessions/src/session-repository/errors'
+import type { SessionRepository, TypedChallengeData } from '@luxexchange/sessions/src/session-repository/types'
+import { ChallengeFailureReason, VerifyFailureReason } from '@luxexchange/sessions/src/session-repository/types'
+import type { Logger } from '@luxfi/utilities/src/logger/logger'
+
+/**
+ * Creates a session repository that handles communication with the session service.
+ * This is the layer that makes actual API calls to the backend.
+ *
+ * TODO(proto): `VerifyResponse` in `@uniswap/client-platform-service` still has a proto3
+ * issue where an empty `VerifySuccess` message gets silently dropped, leaving
+ * `outcome.case === undefined`. The `verifySession()` method works around this by using
+ * the `retry` flag as a discriminator.
+ *
+ * The `ChallengeResponse` failure case was fixed in v0.0.14 — the proto now includes a
+ * proper `failure?: ChallengeFailure` field with typed `ChallengeFailure_Reason`.
+ */
+function createSessionRepository(ctx: { client: SessionServiceClient; getLogger?: () => Logger }): SessionRepository {
+  const initSession: SessionRepository['initSession'] = async () => {
+    try {
+      const response = await ctx.client['initSession']({})
+
+      return {
+        sessionId: response.sessionId,
+        deviceId: response.deviceId,
+        needChallenge: response.needChallenge || false,
+        extra: response.extra,
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error)
+      throw new Error(`Failed to initialize session: ${errorMessage}`, { cause: error })
+    }
+  }
+
+  const challenge: SessionRepository['challenge'] = async (request) => {
+    try {
+      const response = await ctx.client['challenge']({
+        challengeType: request.challengeType,
+        identifier: request.identifier,
+      })
+
+      const logger = ctx.getLogger?.()
+
+      logger?.debug('createSessionRepository', 'challenge', 'Raw challenge response', {
+        challengeId: response.challengeId,
+        challengeType: response.challengeType,
+        extraKeys: Object.keys(response.extra),
+        extra: response.extra,
+        challengeDataCase: (response as unknown as { challengeData?: TypedChallengeData }).challengeData?.case,
+        challengeDataValue: (response as unknown as { challengeData?: TypedChallengeData }).challengeData?.value,
+      })
+
+      // Check for explicit challenge failure from the backend (e.g., bot detection required)
+      if (response.failure) {
+        const reasonEnum = response.failure.reason
+        const reason = `REASON_${ChallengeFailure_Reason[reasonEnum]}` as ChallengeFailureReason
+        throw new ChallengeRejectedError(reason, { failure: response.failure, extra: response.extra })
+      }
+
+      // Map proto oneof challengeData to our typed interface
+      let challengeData: TypedChallengeData = { case: undefined }
+      let authorizeUrl: string | undefined
+      const protoChallengeData = (response as unknown as { challengeData?: TypedChallengeData }).challengeData
+
+      if (protoChallengeData && protoChallengeData.case === 'turnstile') {
+        challengeData = {
+          case: 'turnstile',
+          value: {
+            siteKey: protoChallengeData.value.siteKey,
+            action: protoChallengeData.value.action,
+          },
+        }
+      } else if (protoChallengeData && protoChallengeData.case === 'hashcash') {
+        challengeData = {
+          case: 'hashcash',
+          value: {
+            difficulty: protoChallengeData.value.difficulty,
+            subject: protoChallengeData.value.subject,
+            algorithm: protoChallengeData.value.algorithm,
+            nonce: protoChallengeData.value.nonce,
+            maxProofLength: protoChallengeData.value.maxProofLength,
+            verifier: protoChallengeData.value.verifier,
+          },
+        }
+      } else if (protoChallengeData && protoChallengeData.case === 'github') {
+        challengeData = {
+          case: 'github',
+          value: {
+            authorizeUrl: protoChallengeData.value.authorizeUrl,
+          },
+        }
+        authorizeUrl = protoChallengeData.value.authorizeUrl
+      } else {
+        // Fallback to legacy extra field for authorize URL
+        const legacyChallengeData = response.extra['challengeData']
+        // Legacy format is JSON: {"authorizeUrl":"https://..."} or a raw URL
+        if (legacyChallengeData?.startsWith('http')) {
+          authorizeUrl = legacyChallengeData
+        } else if (legacyChallengeData) {
+          try {
+            const parsed = JSON.parse(legacyChallengeData) as { authorizeUrl?: string }
+            authorizeUrl = parsed.authorizeUrl
+          } catch {
+            // Not JSON, not a URL — skip
+          }
+        }
+
+        logger?.debug('createSessionRepository', 'challenge', 'No typed challengeData, falling back to extra', {
+          legacyChallengeData,
+          resolvedAuthorizeUrl: authorizeUrl,
+        })
+      }
+
+      logger?.debug('createSessionRepository', 'challenge', 'Mapped challenge response', {
+        challengeDataCase: challengeData.case,
+        authorizeUrl,
+      })
+
+      return {
+        challengeId: response.challengeId || '',
+        challengeType: response.challengeType || 0,
+        extra: response.extra,
+        challengeData,
+        authorizeUrl,
+      }
+    } catch (error) {
+      // Don't wrap typed session errors — they carry structured data for callers
+      if (error instanceof ChallengeRejectedError) {
+        throw error
+      }
+      const errorMessage = error instanceof Error ? error.message : String(error)
+      throw new Error(`Failed to get challenge: ${errorMessage}`, { cause: error })
+    }
+  }
+
+  const verifySession: SessionRepository['verifySession'] = async (request) => {
+    try {
+      const response = await ctx.client['verify']({
+        solution: request.solution,
+        challengeId: request.challengeId,
+        type: request.challengeType,
+      })
+
+      const logger = ctx.getLogger?.()
+      logger?.debug('createSessionRepository', 'verifySession', 'Raw verify response', {
+        retry: response.retry,
+        retryType: typeof response.retry,
+        outcomeCase: response.outcome.case,
+        outcomeValue: JSON.stringify(response.outcome.value),
+        newSessionId: response.newSessionId,
+        responseKeys: Object.keys(response),
+      })
+
+      // Proto3 validation: When outcome.case is undefined, proto3 silently dropped the oneof.
+      // This happens for BOTH success and failure outcomes with empty/default values.
+      // Use `retry` as the discriminator: `retry: false` means the backend accepted the
+      // solution (proto3 dropped an empty VerifySuccess); `retry: true` means try again.
+      if (response.outcome.case === undefined) {
+        if (response.retry) {
+          // Backend wants a retry — outcome was likely a dropped failure. This is fine,
+          // the caller handles retries via the `retry` flag.
+          logger?.debug('createSessionRepository', 'verifySession', 'Empty outcome with retry=true, treating as retry')
+        } else {
+          // Backend accepted the solution — proto3 dropped the empty VerifySuccess message.
+          logger?.debug(
+            'createSessionRepository',
+            'verifySession',
+            'Empty outcome with retry=false, treating as success (proto3 likely dropped empty VerifySuccess)',
+          )
+        }
+      }
+
+      // Extract userInfo from success outcome, waitSeconds from failure outcome
+      const userInfo =
+        response.outcome.case === 'success'
+          ? response.outcome.value.userInfo
+            ? { name: response.outcome.value.userInfo.name, email: response.outcome.value.userInfo.email }
+            : undefined
+          : undefined
+
+      const waitSeconds = response.outcome.case === 'failure' ? response.outcome.value.waitSeconds : undefined
+
+      // Extract failure info — cast the constructed string to the typed VerifyFailureReason union
+      const failureReasonEnum = response.outcome.case === 'failure' ? response.outcome.value.reason : undefined
+      const failureReason =
+        failureReasonEnum !== undefined
+          ? (`REASON_${VerifyFailure_Reason[failureReasonEnum]}` as VerifyFailureReason)
+          : undefined
+      const failureMessage = response.outcome.case === 'failure' ? response.outcome.value.message : undefined
+
+      return {
+        retry: response.retry,
+        waitSeconds,
+        userInfo,
+        failureReason,
+        failureMessage,
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error)
+      throw new Error(`Failed to verify session: ${errorMessage}`, { cause: error })
+    }
+  }
+
+  const deleteSession: SessionRepository['deleteSession'] = async () => {
+    try {
+      // Proto renamed deleteSession to signout
+      await ctx.client['signout']({})
+      return {}
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error)
+      throw new Error(`Failed to delete session: ${errorMessage}`, { cause: error })
+    }
+  }
+
+  const getChallengeTypes: SessionRepository['getChallengeTypes'] = async () => {
+    try {
+      const response = await ctx.client['getChallengeTypes']({})
+      return response.challengeTypeConfig.map((cfg: { type: number; config: Record<string, string> }) => ({
+        type: cfg.type,
+        config: cfg.config,
+      }))
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error)
+      throw new Error(`Failed to get challenge types: ${errorMessage}`, { cause: error })
+    }
+  }
+
+  return {
+    initSession,
+    challenge,
+    verifySession,
+    deleteSession,
+    getChallengeTypes,
+  }
+}
+
+export { createSessionRepository }

package/src/session-repository/errors.ts

@@ -0,0 +1,22 @@
+import { SessionError } from '@luxexchange/sessions/src/session-initialization/sessionErrors'
+
+/**
+ * Error thrown when the Entry Gateway rejects a challenge request.
+ *
+ * Since v0.0.14, the proto `ChallengeResponse` includes a typed `failure?: ChallengeFailure`
+ * field with `ChallengeFailure_Reason` (e.g., `BOT_DETECTION_REQUIRED`). This error is
+ * thrown when that field is present, carrying the typed reason for callers to handle.
+ */
+export class ChallengeRejectedError extends SessionError {
+  /** The failure reason string (may not be in our proto types yet) */
+  readonly reason: string
+
+  /** The full raw failure object for debugging */
+  readonly rawFailure: unknown
+
+  constructor(reason: string, rawFailure?: unknown) {
+    super(`Challenge rejected by Entry Gateway: ${reason}`, 'ChallengeRejectedError')
+    this.reason = reason
+    this.rawFailure = rawFailure
+  }
+}

package/src/session-repository/types.ts

@@ -0,0 +1,289 @@
+import { ChallengeType } from '@luxdex/client-platform-service/dist/uniswap/platformservice/v1/sessionService_pb'
+
+/**
+ * Typed challenge data for Turnstile bot detection
+ */
+interface TurnstileChallengeData {
+  siteKey: string
+  action: string
+}
+
+/**
+ * Typed challenge data for HashCash proof-of-work
+ */
+interface HashCashChallengeData {
+  difficulty: number
+  subject: string
+  algorithm: string
+  nonce: string
+  maxProofLength: number
+  verifier: string
+}
+
+/**
+ * Typed challenge data for GitHub OAuth
+ */
+interface GitHubChallengeData {
+  authorizeUrl: string
+}
+
+/**
+ * Type-safe challenge data union (mirrors proto oneof ChallengeResponse.challenge_data)
+ */
+type TypedChallengeData =
+  | { case: 'turnstile'; value: TurnstileChallengeData }
+  | { case: 'hashcash'; value: HashCashChallengeData }
+  | { case: 'github'; value: GitHubChallengeData }
+  | { case: undefined; value?: undefined }
+
+/**
+ * Response from session initialization
+ */
+interface InitSessionResponse {
+  /**
+   * Session ID
+   * - Web: undefined (in Set-Cookie header)
+   * - Mobile/Extension: actual session ID string
+   */
+  sessionId?: string // optional string session_id
+  deviceId?: string // string device_id
+
+  /** Whether bot detection challenge is required */
+  needChallenge: boolean // bool need_challenge
+
+  /** @deprecated Extra information for bot detection (JSON data) — kept for backwards compatibility */
+  extra: Record<string, string> // map<string, string> extra
+}
+
+/**
+ * Request for a challenge
+ * For bot detection: empty (server decides challenge type)
+ * For OAuth: specify challengeType
+ */
+interface ChallengeRequest {
+  /** Challenge type to request (optional - server decides if not specified) */
+  challengeType?: ChallengeType
+  /** Email or other identifier (required for email OTP challenges) */
+  identifier?: string
+}
+
+/**
+ * Challenge response
+ * For bot detection: typed challenge data in challengeData
+ * For OAuth: authorizeUrl in challengeData (GitHub) or extra (legacy)
+ */
+interface ChallengeResponse {
+  /** Unique challenge identifier (used as OAuth state parameter) */
+  challengeId: string // string challenge_id = 1
+
+  /** Type of challenge */
+  challengeType: ChallengeType // ChallengeType challenge_type = 2
+
+  /** @deprecated Use challengeData instead. Kept for backwards compatibility. */
+  extra: Record<string, string> // map<string, string> extra = 3 [deprecated]
+
+  /** Type-safe challenge-specific data (replaces extra) */
+  challengeData?: TypedChallengeData
+
+  /** OAuth authorization URL extracted from challengeData or extra */
+  authorizeUrl?: string
+}
+
+/**
+ * Request to verify session with bot detection solution
+ */
+interface VerifySessionRequest {
+  /** Solution token (Turnstile token or HashCash proof) */
+  solution: string
+
+  /** Challenge ID being solved */
+  challengeId: string
+
+  /** Type of challenge being solved */
+  challengeType: ChallengeType
+}
+
+/**
+ * User information from OAuth provider
+ */
+interface UserInfo {
+  name?: string
+  email?: string
+}
+
+/**
+ * Typed failure reasons from the SessionService/Verify proto.
+ * Values match the wire format: `REASON_${VerifyFailure_Reason[enum]}`.
+ *
+ * Use for exhaustive case matching in strategies and services:
+ * ```ts
+ * switch (result.failureReason) {
+ *   case VerifyFailureReason.INVALID_CHALLENGE:
+ *     return { action: 'error', message: result.failureMessage }
+ * }
+ * ```
+ */
+const VerifyFailureReason = {
+  /** Default/unknown failure */
+  UNSPECIFIED: 'REASON_UNSPECIFIED',
+  /** Bad OTP code or bot detection solution */
+  INVALID_SOLUTION: 'REASON_INVALID_SOLUTION',
+  /** OAuth provider email needs verification */
+  EMAIL_NOT_VERIFIED: 'REASON_EMAIL_NOT_VERIFIED',
+  /** Challenge ID is invalid or expired — re-initiate a challenge */
+  INVALID_CHALLENGE: 'REASON_IVALID_CHALLENGE', // backend proto typo preserved
+  /** Email is linked to a different auth provider */
+  PROVIDER_MISMATCH: 'REASON_PROVIDER_MISMATCH',
+} as const
+
+type VerifyFailureReason = (typeof VerifyFailureReason)[keyof typeof VerifyFailureReason]
+
+/**
+ * Response from session verification
+ */
+interface VerifySessionResponse {
+  /** Whether to retry the challenge */
+  retry: boolean // bool retry = 1
+
+  /** Seconds to wait before retry (for rate limiting, e.g., email OTP) */
+  waitSeconds?: number // from VerifyFailure.wait_seconds
+
+  /** User information from successful OAuth verification */
+  userInfo?: UserInfo // from VerifySuccess.user_info
+
+  /** Typed failure reason code — use VerifyFailureReason for matching */
+  failureReason?: VerifyFailureReason
+
+  /** Human-readable failure message from the backend */
+  failureMessage?: string
+}
+
+/**
+ * Request to delete a session
+ * Empty - session identified via cookie or header
+ */
+
+// biome-ignore lint/complexity/noBannedTypes: Empty per proto
+type DeleteSessionRequest = {}
+
+/**
+ * Response from session deletion
+ */
+
+// biome-ignore lint/complexity/noBannedTypes: Empty per proto
+type DeleteSessionResponse = {}
+
+/**
+ * Introspect request - Entry Gateway only
+ * Frontend doesn't use this
+ */
+interface IntrospectRequest {
+  /** Session ID to introspect */
+  sessionId: string // string session_id = 1
+}
+
+/**
+ * Introspect response - Entry Gateway only
+ * Frontend doesn't use this
+ */
+interface IntrospectResponse {
+  /** Wrapped/hashed session ID */
+  wrappedId: string // string wrapped_id = 1
+
+  /** Validation result */
+  result: boolean // bool result = 2
+
+  /** Trust score */
+  score: number // int32 score = 4
+
+  /** Persona identifier */
+  personaId: string // string persona_id = 5
+}
+
+/**
+ * Configuration for a challenge type (OAuth provider or bot detection)
+ * Returned by getChallengeTypes to provide client-side SDK configuration
+ */
+interface ChallengeTypeConfig {
+  /** Challenge type (e.g., GOOGLE, GITHUB, EMAIL, TURNSTILE) */
+  type: ChallengeType
+
+  /** Provider-specific configuration (e.g., clientId, scope for OAuth) */
+  config: Record<string, string>
+}
+
+/**
+ * Session Service API client interface
+ * Wraps the protobuf-generated client
+ */
+interface SessionRepository {
+  /**
+   * Initialize a new session
+   * - Headers: X-Device-ID (mobile/extension only)
+   * - Response: session_id in body (mobile/ext) or Set-Cookie (web)
+   * TODO: this is pretty implicit: when on web, we exclude the device ID header,
+   * so then it implicitly returns a session ID via the Set-Cookie header
+   *
+   */
+  initSession(): Promise<InitSessionResponse>
+
+  /**
+   * Request a bot detection challenge
+   * - Headers: X-Session-ID (mobile/ext) or Cookie (web)
+   */
+  challenge(request: ChallengeRequest): Promise<ChallengeResponse>
+
+  /**
+   * Submit bot detection solution to verify session
+   * - Headers: X-Session-ID (mobile/ext) or Cookie (web)
+   */
+  verifySession(request: VerifySessionRequest): Promise<VerifySessionResponse>
+
+  /**
+   * Delete the current session
+   * - Headers: X-Session-ID (mobile/ext) or Cookie (web)
+   */
+  deleteSession(request: DeleteSessionRequest): Promise<DeleteSessionResponse>
+
+  /**
+   * Introspect session validity (Entry Gateway only)
+   * Frontend should NOT use this - EGW internal only
+   */
+  introspect?(request: IntrospectRequest): Promise<IntrospectResponse>
+
+  /**
+   * Get available challenge types and their configuration
+   * Returns OAuth provider configs (e.g., Google client ID) and bot detection configs
+   */
+  getChallengeTypes(): Promise<ChallengeTypeConfig[]>
+}
+
+/**
+ * Typed failure reasons from the SessionService/Challenge proto.
+ * Values match the wire format: `REASON_${ChallengeFailure_Reason[enum]}`.
+ */
+const ChallengeFailureReason = {
+  /** Default/unknown failure */
+  UNSPECIFIED: 'REASON_UNSPECIFIED',
+  /** Session must pass bot detection first (score < 60) */
+  BOT_DETECTION_REQUIRED: 'REASON_BOT_DETECTION_REQUIRED',
+} as const
+
+type ChallengeFailureReason = (typeof ChallengeFailureReason)[keyof typeof ChallengeFailureReason]
+
+export { ChallengeFailureReason, VerifyFailureReason }
+
+export type {
+  SessionRepository,
+  ChallengeRequest,
+  ChallengeResponse,
+  ChallengeTypeConfig,
+  VerifySessionRequest,
+  VerifySessionResponse,
+  InitSessionResponse,
+  UserInfo,
+  TypedChallengeData,
+  TurnstileChallengeData,
+  HashCashChallengeData,
+  GitHubChallengeData,
+}

package/src/session-service/createNoopSessionService.ts

@@ -0,0 +1,24 @@
+import { ChallengeType } from '@luxdex/client-platform-service/dist/uniswap/platformservice/v1/sessionService_pb'
+import type { SessionService } from '@luxfi/sessions/src/session-service/types'
+
+function createNoopSessionService(): SessionService {
+  const initSession: SessionService['initSession'] = async () => ({ needChallenge: false, extra: {} })
+  const removeSession: SessionService['removeSession'] = async () => {}
+  const getSessionState: SessionService['getSessionState'] = async () => null
+  const requestChallenge: SessionService['requestChallenge'] = async () => ({
+    challengeId: 'noop-challenge-123',
+    challengeType: ChallengeType.UNSPECIFIED,
+    extra: {},
+  })
+  const verifySession: SessionService['verifySession'] = async () => ({ retry: false })
+
+  return {
+    initSession,
+    requestChallenge,
+    verifySession,
+    removeSession,
+    getSessionState,
+  }
+}
+
+export { createNoopSessionService }