src — auth

Module: src-auth Cohesion: 0.80 Members: 0

src — auth

The src/auth module provides comprehensive authentication and profile management capabilities, primarily focused on integrating with AI providers. It is divided into two main sub-modules: oauth for handling OAuth 2.0 flows and profile-manager.ts for a more generic, robust profile management system with advanced failure handling.

Module Overview

The src/auth module serves as the backbone for managing access to various AI services. It addresses several critical concerns:

  1. OAuth 2.0 Authentication: Securely handles authorization code grants with PKCE, token exchange, refresh, and user information retrieval for providers supporting OAuth.
  2. AI Model Profile Management (with Failover): Allows defining multiple profiles for AI providers (e.g., OpenAI, Anthropic, Grok), each with its own authentication method (API key or OAuth). It implements a circuit breaker pattern to automatically switch to backup providers upon failures, ensuring resilience.
  3. Generic Auth Profile Management (with Cooldowns & Persistence): A more generalized system for managing authentication profiles, featuring various rotation strategies (round-robin, priority, random), session stickiness, exponential backoff cooldowns for failed profiles (including special handling for billing-related failures), and persistent state storage.

Core Concepts

Before diving into the components, understanding a few core concepts will be helpful:

OAuth Module (src/auth/oauth)

This sub-module is dedicated to OAuth 2.0 authentication and managing AI provider profiles with failover.

types.ts

Defines all the essential types and interfaces used across the OAuth module:

OAuthManager

The OAuthManager class is responsible for orchestrating the entire OAuth 2.0 authentication process. It handles provider configuration, initiating authorization flows, exchanging codes for tokens, and managing token lifecycles.

Key Features:

Execution Flow (Authorization): 

graph TD
    A[User initiates Auth] --> B{OAuthManager.getAuthorizationUrl}
    B --> C{Generate PKCE & State}
    C --> D{Store State}
    D --> E[Return Auth URL]
    E --> F[User redirects to Provider]
    F --> G[User authorizes app]
    G --> H[Provider redirects to local server /callback]
    H --> I{OAuthManager.handleCallback}
    I --> J{Validate State}
    J --> K{OAuthManager.exchangeCode}
    K --> L{Request Tokens from Provider}
    L --> M{Parse Tokens & Fetch User Info}
    M --> N{Store Credential}
    N --> O{Schedule Refresh}
    O --> P[Emit auth:success]
    P --> Q[Local server responds & closes window]

ModelProfileManager

The ModelProfileManager class is designed to manage multiple AI provider profiles, enabling automatic failover and intelligent model selection. It integrates with OAuthManager for OAuth-based authentication.

Key Features:

Relationship between OAuthManager and ModelProfileManager: 

graph TD
    subgraph src/auth/oauth
        OAuthManager -- Manages OAuth Credentials --> StoredCredential[StoredCredential (in memory)]
        ModelProfileManager -- Retrieves Access Tokens --> OAuthManager
        ModelProfileManager -- Checks Token Expiry --> OAuthManager
        ModelProfileManager -- Stores OAuth Credential IDs --> ModelProfile[ModelProfile (in memory)]
    end

Auth Profile Manager (src/auth/profile-manager.ts)

The AuthProfileManager provides a more generic and robust system for managing authentication profiles, inspired by patterns like Native Engine. It focuses on intelligent profile rotation, advanced failure handling with exponential backoff, and persistent state.

Key Features:

Distinction from ModelProfileManager:

While both ModelProfileManager and AuthProfileManager manage "profiles," they serve different purposes and employ distinct mechanisms:

Singleton Access

Both OAuthManager and ModelProfileManager (and AuthProfileManager) are designed to be used as singletons within the application.

These singleton functions ensure that only one instance of each manager exists globally, simplifying state management and coordination across the application.