@vunexa/lixa 0.0.1-alpha.20 → 0.0.1-alpha.22

package/dist/export-types/index.d.ts

@@ -4,13 +4,22 @@
  * @remarks
  * This package simplifies multi-provider authentication flows (e.g., Google, GitHub), supports extensible session management, and enables custom provider registration.
  *
+ * Key features:
+ * - OAuth 2.0 authorization code flow with PKCE (RFC 6749, RFC 7636)
+ * - OpenID Connect support
+ * - Built-in providers available in \@vunexa/lixa-providers
+ * - Custom provider support via IProvider interface
+ * - Extensible session management via SessionStrategy
+ * - Pluggable state and session storage via StateDao and SessionDao
+ * - TypeScript-first with comprehensive type safety
+ *
  * @packageDocumentation
  */
 
 /**
  * Type representing the keys of configured providers
  */
-declare type ConfiguredProviderKey<T extends LixaConfig<any>> = keyof T['providers'];
+declare type ConfiguredProviderKey<T extends LixaConfig<Record<string, ProviderConfig>>> = keyof T['providers'];
 
 /**
  * Default session strategy that works with any OAuth provider.
@@ -26,23 +35,140 @@ export declare class DefaultSessionStrategy implements SessionStrategy {
      * @param tokenData - The token data received from the OAuth provider
      * @returns A Promise that resolves to a Session object
      */
-    createSession(tokenData: any): Promise<Session>;
+    createSession(tokenData: OAuthTokenResponse): Promise<Session>;
 }
 
 /**
- * Interface for OAuth provider implementations.
+ * Interface for OAuth 2.0 and OpenID Connect provider implementations.
  *
  * @remarks
  * Implement this interface to add support for custom OAuth providers.
+ * Each provider defines the three core endpoints required for the OAuth 2.0
+ * authorization code flow with PKCE.
+ *
+ * Built-in providers (Google, GitHub) are available in the \@vunexa/lixa-providers package.
+ *
+ * All implementations must comply with:
+ * - RFC 6749 (OAuth 2.0)
+ * - RFC 7636 (PKCE)
+ * - OpenID Connect Core 1.0 (for OIDC providers)
+ *
+ * @example
+ * Custom provider implementation:
+ * ```typescript
+ * import { IProvider } from '@vunexa/lixa';
+ *
+ * class CustomProvider implements IProvider {
+ *   authorizationEndpoint = 'https://auth.example.com/oauth/authorize';
+ *   tokenEndpoint = 'https://auth.example.com/oauth/token';
+ *   userInfoEndpoint = 'https://api.example.com/user';
+ * }
+ *
+ * // Use in configuration
+ * const lixa = new Lixa({
+ *   providers: {
+ *     custom: {
+ *       provider: new CustomProvider(),
+ *       clientId: 'your-client-id',
+ *       clientSecret: 'your-client-secret',
+ *       redirectUri: 'https://app.com/callback',
+ *       scopes: ['read:user']
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * Object literal provider:
+ * ```typescript
+ * const customProvider: IProvider = {
+ *   authorizationEndpoint: 'https://auth.example.com/oauth/authorize',
+ *   tokenEndpoint: 'https://auth.example.com/oauth/token',
+ *   userInfoEndpoint: 'https://api.example.com/user'
+ * };
+ * ```
  *
  * @public
  */
 export declare interface IProvider {
-    /** The OAuth authorization endpoint URL */
+    /**
+     * The OAuth 2.0 authorization endpoint URL.
+     *
+     * @remarks
+     * This is the URL where users are redirected to authenticate and authorize your application.
+     * The endpoint must support the OAuth 2.0 authorization code flow with PKCE.
+     *
+     * Standard query parameters sent to this endpoint:
+     * - client_id: Your application's client ID
+     * - redirect_uri: Where to redirect after authorization
+     * - response_type: Always "code" for authorization code flow
+     * - scope: Space-separated list of requested scopes
+     * - state: Random string for CSRF protection
+     * - code_challenge: PKCE code challenge (SHA-256 hash)
+     * - code_challenge_method: Always "S256" for SHA-256
+     *
+     * @example
+     * ```typescript
+     * authorizationEndpoint = 'https://accounts.google.com/o/oauth2/v2/auth'
+     * ```
+     */
     authorizationEndpoint: string;
-    /** The OAuth token exchange endpoint URL */
+    /**
+     * The OAuth 2.0 token endpoint URL.
+     *
+     * @remarks
+     * This is the URL where authorization codes are exchanged for access tokens.
+     * The endpoint must support the OAuth 2.0 token exchange with PKCE.
+     *
+     * Standard parameters sent to this endpoint (POST request):
+     * - grant_type: Always "authorization_code"
+     * - code: The authorization code from the callback
+     * - redirect_uri: Must match the authorization request
+     * - client_id: Your application's client ID
+     * - client_secret: Your application's client secret
+     * - code_verifier: PKCE code verifier (original random string)
+     *
+     * Expected response:
+     * - access_token: OAuth access token
+     * - token_type: Token type (usually "Bearer")
+     * - expires_in: Token expiration time in seconds
+     * - refresh_token: Refresh token (optional)
+     * - id_token: OpenID Connect ID token (for OIDC providers)
+     * - scope: Granted scopes
+     *
+     * @example
+     * ```typescript
+     * tokenEndpoint = 'https://oauth2.googleapis.com/token'
+     * ```
+     */
     tokenEndpoint: string;
-    /** The user information endpoint URL */
+    /**
+     * The user information endpoint URL.
+     *
+     * @remarks
+     * This is the URL where user profile information can be retrieved using the access token.
+     * For OpenID Connect providers, this is the UserInfo endpoint.
+     *
+     * The endpoint is called with the access token in the Authorization header:
+     * ```
+     * Authorization: Bearer <access_token>
+     * ```
+     *
+     * Common response fields:
+     * - sub: Subject identifier (user ID)
+     * - email: User's email address
+     * - name: User's full name
+     * - picture: User's profile picture URL
+     * - email_verified: Whether email is verified
+     *
+     * Note: This endpoint is not called automatically by Lixa. Your SessionStrategy
+     * can call it if needed to fetch user profile information.
+     *
+     * @example
+     * ```typescript
+     * userInfoEndpoint = 'https://www.googleapis.com/oauth2/v2/userinfo'
+     * ```
+     */
     userInfoEndpoint: string;
 }
 
@@ -51,18 +177,18 @@ export declare interface IProvider {
  *
  * @remarks
  * Lixa simplifies multi-provider authentication flows and supports extensible session management.
+ * Providers can be passed inline in the configuration, eliminating the need for pre-registration.
  *
  * @example
+ * Using built-in providers from \@vunexa/lixa-providers:
  * ```typescript
  * import { Lixa } from '@vunexa/lixa';
- * import { GoogleProvider } from '@vunexa/lixa/providers';
- *
- * // Register providers before using them
- * Lixa.registerProvider({ google: new GoogleProvider() });
+ * import { GoogleProvider } from '@vunexa/lixa-providers';
  *
- * const config = Lixa.createConfig({
+ * const lixa = new Lixa({
  *   providers: {
  *     google: {
+ *       provider: new GoogleProvider(),
  *       clientId: 'your-client-id',
  *       clientSecret: 'your-client-secret',
  *       redirectUri: 'https://yourapp.com/auth/google/callback',
@@ -70,13 +196,36 @@ export declare interface IProvider {
  *     }
  *   }
  * });
+ * ```
+ *
+ * @example
+ * Using custom inline providers:
+ * ```typescript
+ * import { Lixa, IProvider } from '@vunexa/lixa';
+ *
+ * const customProvider: IProvider = {
+ *   authorizationEndpoint: 'https://custom.com/oauth/authorize',
+ *   tokenEndpoint: 'https://custom.com/oauth/token',
+ *   userInfoEndpoint: 'https://custom.com/api/user'
+ * };
  *
- * const lixa = new Lixa(config);
+ * const lixa = new Lixa({
+ *   providers: {
+ *     custom: {
+ *       provider: customProvider,
+ *       clientId: 'your-client-id',
+ *       clientSecret: 'your-client-secret',
+ *       redirectUri: 'https://yourapp.com/auth/custom/callback',
+ *       scopes: ['read:user']
+ *     }
+ *   }
+ * });
  * ```
  *
  * @public
  */
-export declare class Lixa<TConfig extends LixaConfig<any> = LixaConfig> {
+export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> = LixaConfig> {
+    private static DEFAULT_PROVIDERS;
     private static CONFIGURED_PROVIDERS;
     private static LOCAL_STATE_CACHE;
     private static LOCAL_SESSION_CACHE;
@@ -89,17 +238,52 @@ export declare class Lixa<TConfig extends LixaConfig<any> = LixaConfig> {
     /**
      * Creates a new Lixa instance with the provided configuration.
      *
+     * @remarks
+     * Providers can be passed inline in the configuration using the `provider` field.
+     * Provider resolution priority: inline custom provider \> default providers \> legacy registry.
+     *
      * @param config - The configuration object containing provider settings and optional session strategy
+     *
+     * @throws Error when provider configuration is missing required fields
+     * @throws Error when provider implementation is missing required properties
+     * @throws Error when provider is not available and no inline implementation is provided
      */
     constructor(config: TConfig);
+    /**
+     * Validates that a provider configuration has all required credentials.
+     *
+     * @param name - The provider name
+     * @param config - The provider configuration
+     * @throws Error when required fields are missing or invalid
+     */
+    private validateProviderConfig;
+    /**
+     * Validates that a provider implementation has all required properties.
+     *
+     * @param name - The provider name
+     * @param provider - The provider implementation
+     * @throws Error when required properties are missing
+     */
+    private validateProviderImplementation;
+    /**
+     * Structured debug logging with standardized format.
+     *
+     * @param level - Log level (INFO, WARN, ERROR)
+     * @param context - Context of the log (Init, Auth, Token, Session, State)
+     * @param message - Log message
+     * @param data - Optional data to log
+     *
+     * @remarks
+     * Format: [Lixa] [timestamp] [level] [context] message
+     * Only logs when debug mode is enabled.
+     */
     private log;
-    private logError;
     /**
-     * Checks if a provider is both registered and configured for this instance.
+     * Checks if a provider is configured for this instance.
      * This is a type guard that narrows the provider type for use with getAuthUrl.
      *
      * @param provider - The provider name to check (case-insensitive)
-     * @returns True if the provider is registered and configured, false otherwise
+     * @returns True if the provider is configured, false otherwise
      *
      * @example
      * ```typescript
@@ -110,12 +294,37 @@ export declare class Lixa<TConfig extends LixaConfig<any> = LixaConfig> {
      * ```
      */
     isProviderConfigured<T extends string>(provider: T): provider is T & ConfiguredProviderKey<TConfig>;
+    /**
+     * Gets a provider implementation by name.
+     * Resolution priority: inline custom provider \> default providers \> legacy registry
+     *
+     * @param name - The provider name (case-insensitive)
+     * @param config - The provider configuration
+     * @returns The provider implementation
+     * @throws Error when provider is not found
+     */
+    private getProvider;
     /**
      * Registers custom OAuth providers for use with Lixa.
      *
+     * @deprecated This method is maintained for backward compatibility.
+     * The recommended approach is to pass providers inline in the configuration:
+     * ```typescript
+     * const lixa = new Lixa({
+     *   providers: {
+     *     custom: {
+     *       provider: new CustomProvider(),
+     *       clientId: '...',
+     *       // ...
+     *     }
+     *   }
+     * });
+     * ```
+     *
      * @param providerMap - A map of provider names to IProvider implementations
      *
      * @example
+     * Legacy usage (still supported):
      * ```typescript
      * class CustomProvider implements IProvider {
      *   authorizationEndpoint = 'https://custom.com/oauth/authorize';
@@ -134,14 +343,31 @@ export declare class Lixa<TConfig extends LixaConfig<any> = LixaConfig> {
      */
     static getRegisteredProviders(): string[];
     /**
-     * Creates a type-safe configuration that only allows registered providers.
+     * Creates a type-safe configuration.
+     *
+     * @deprecated This method is maintained for backward compatibility.
+     * You can now pass configuration directly to the Lixa constructor without this helper.
      *
-     * @param config - Configuration object with providers that must be registered
-     * @returns The same configuration object, but with type safety for registered providers
+     * @param config - Configuration object with provider settings
+     * @returns The same configuration object with type safety
+     *
+     * @example
+     * New approach (recommended):
+     * ```typescript
+     * const lixa = new Lixa({
+     *   providers: {
+     *     google: {
+     *       provider: new GoogleProvider(),
+     *       clientId: '...',
+     *       // ...
+     *     }
+     *   }
+     * });
+     * ```
      */
-    static createConfig<T extends Record<string, ProviderConfig>>(config: LixaConfig<keyof T & string> & {
+    static createConfig<T extends Record<string, ProviderConfig>>(config: LixaConfig<T> & {
         providers: T;
-    }): LixaConfig<keyof T & string>;
+    }): LixaConfig<T>;
     /**
      * Generates a cryptographically secure random state parameter for OAuth flows.
      *
@@ -154,12 +380,81 @@ export declare class Lixa<TConfig extends LixaConfig<any> = LixaConfig> {
     /**
      * Generates a cryptographically secure code verifier for PKCE flows.
      *
-     * @returns A 64-character hexadecimal string
+     * @returns A 64-character hexadecimal string (32 random bytes encoded as hex)
      *
      * @remarks
-     * The code verifier is used in PKCE (Proof Key for Code Exchange) to enhance security.
+     * This method implements the code verifier generation as specified in RFC 7636 (PKCE).
+     *
+     * **PKCE (Proof Key for Code Exchange)** is a security extension to OAuth 2.0 that
+     * prevents authorization code interception attacks. It's especially important for
+     * public clients (mobile apps, SPAs) but is recommended for all OAuth flows.
+     *
+     * **Generation methodology:**
+     * 1. Generate 32 cryptographically random bytes using Node.js crypto.randomBytes()
+     * 2. Encode the bytes as a hexadecimal string (64 characters)
+     * 3. The verifier is stored securely and used later in the token exchange
+     *
+     * **RFC 7636 Requirements:**
+     * - Minimum length: 43 characters
+     * - Maximum length: 128 characters
+     * - Character set: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
+     * - This implementation produces 64 hex characters, meeting the requirements
+     *
+     * The code verifier is:
+     * - Generated when creating the authorization URL
+     * - Stored in state cache with the state parameter
+     * - Retrieved during callback handling
+     * - Sent to the token endpoint to prove the client's identity
+     *
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7636 | RFC 7636 - PKCE}
+     * @see buildCodeChallenge for the corresponding challenge generation
+     *
+     * @internal
      */
     private static generateCodeVerifier;
+    /**
+     * Generates a code challenge from a code verifier for PKCE flows.
+     *
+     * @param codeVerifier - The code verifier string (64 hex characters)
+     * @returns A base64url-encoded SHA-256 hash of the code verifier
+     *
+     * @remarks
+     * This method implements the code challenge generation as specified in RFC 7636 (PKCE)
+     * using the S256 (SHA-256) transformation method.
+     *
+     * **Challenge generation methodology:**
+     * 1. Hash the code verifier using SHA-256
+     * 2. Encode the hash as base64
+     * 3. Convert to base64url format (RFC 4648):
+     *    - Replace '+' with '-'
+     *    - Replace '/' with '_'
+     *    - Remove trailing '=' padding
+     *
+     * **PKCE Flow:**
+     * 1. Client generates code_verifier (random string)
+     * 2. Client creates code_challenge = BASE64URL(SHA256(code_verifier))
+     * 3. Client sends code_challenge to authorization endpoint
+     * 4. Authorization server stores the code_challenge
+     * 5. Client sends code_verifier to token endpoint
+     * 6. Authorization server verifies: SHA256(code_verifier) == code_challenge
+     *
+     * **Security Benefits:**
+     * - Prevents authorization code interception attacks
+     * - Even if an attacker intercepts the authorization code, they cannot
+     *   exchange it for tokens without the original code_verifier
+     * - The challenge is sent in the authorization request (public)
+     * - The verifier is sent in the token request (should be kept secret)
+     *
+     * **RFC 7636 Transformation Methods:**
+     * - plain: code_challenge = code_verifier (not recommended)
+     * - S256: code_challenge = BASE64URL(SHA256(code_verifier)) (recommended, used here)
+     *
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7636 | RFC 7636 - PKCE}
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-5 | RFC 4648 - Base64url Encoding}
+     * @see generateCodeVerifier for the verifier generation
+     *
+     * @internal
+     */
     private static buildCodeChallenge;
     /**
      * Generates the authorization URL for the specified provider.
@@ -209,29 +504,180 @@ export declare class Lixa<TConfig extends LixaConfig<any> = LixaConfig> {
 
 /**
  * Main configuration object for Lixa.
- * Only allows providers that have been registered through registerProvider.
+ * Provides type-safe provider name inference.
+ *
+ * @remarks
+ * The generic type parameter TProviders enables TypeScript to infer provider names
+ * from the configuration object, providing autocomplete and type checking for
+ * provider names in methods like getAuthUrl() and handleCallback().
+ *
+ * @typeParam TProviders - The provider configuration map type, defaults to a generic record
+ *
+ * @example
+ * Basic configuration with built-in providers:
+ * ```typescript
+ * import { Lixa } from '@vunexa/lixa';
+ * import { GoogleProvider } from '@vunexa/lixa-providers';
+ *
+ * const lixa = new Lixa({
+ *   providers: {
+ *     google: {
+ *       provider: new GoogleProvider(),
+ *       clientId: process.env.GOOGLE_CLIENT_ID!,
+ *       clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+ *       redirectUri: 'https://app.com/auth/google/callback',
+ *       scopes: ['openid', 'email', 'profile']
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * Configuration with custom session and state storage:
+ * ```typescript
+ * const lixa = new Lixa({
+ *   providers: {
+ *     google: {
+ *       provider: new GoogleProvider(),
+ *       clientId: process.env.GOOGLE_CLIENT_ID!,
+ *       clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+ *       redirectUri: 'https://app.com/auth/google/callback',
+ *       scopes: ['openid', 'email', 'profile']
+ *     }
+ *   },
+ *   sessionStrategy: new CustomSessionStrategy(),
+ *   stateDao: new RedisStateDao(),
+ *   sessionDao: new DatabaseSessionDao(),
+ *   debug: true
+ * });
+ * ```
  *
  * @public
  */
-export declare interface LixaConfig<TRegisteredProviders extends string = string> {
-    /** Map of registered provider names to their configurations */
-    providers: Record<TRegisteredProviders, ProviderConfig>;
-    /** Optional custom session creation strategy */
+export declare interface LixaConfig<TProviders extends Record<string, ProviderConfig> = Record<string, ProviderConfig>> {
+    /**
+     * Map of provider names to their configurations.
+     * Provider names will be available for autocomplete in getAuthUrl() and handleCallback().
+     */
+    providers: TProviders;
+    /**
+     * Optional custom session creation strategy.
+     * Defines how OAuth tokens are converted into application sessions.
+     * Defaults to DefaultSessionStrategy if not provided.
+     *
+     * @see {@link SessionStrategy}
+     */
     sessionStrategy?: SessionStrategy;
-    /** Optional custom state storage implementation */
+    /**
+     * Optional custom state storage implementation.
+     * Used for CSRF protection and PKCE code verifier storage during OAuth flow.
+     * Defaults to in-memory cache if not provided (not suitable for production).
+     *
+     * @see {@link StateDao}
+     */
     stateDao?: StateDao;
-    /** Optiona: custom session storage implementation */
+    /**
+     * Optional custom session storage implementation.
+     * Used for persistent user session storage after authentication.
+     * Defaults to in-memory cache if not provided (not suitable for production).
+     *
+     * @see {@link SessionDao}
+     */
     sessionDao?: SessionDao;
-    /** Enable debug logging */
+    /**
+     * Enable debug logging.
+     * When enabled, outputs structured logs for initialization, auth flow, and errors.
+     * Format: [Lixa] [timestamp] [level] [context] message
+     */
     debug?: boolean;
 }
 
 /**
- * Configuration for an OAuth provider.
+ * OAuth 2.0 token response structure.
+ * Based on RFC 6749 Section 5.1 and OpenID Connect Core 1.0 Section 3.1.3.3
+ *
+ * @remarks
+ * This interface represents the standard OAuth 2.0 token response with
+ * optional OpenID Connect extensions. All OAuth providers should return
+ * at minimum the required fields (access_token, token_type).
  *
  * @public
  */
-export declare interface ProviderConfig {
+declare interface OAuthTokenResponse {
+    /**
+     * OAuth 2.0 access token (required).
+     * Used to access protected resources on behalf of the user.
+     */
+    access_token: string;
+    /**
+     * Token type (required).
+     * Typically "Bearer" for OAuth 2.0.
+     */
+    token_type: string;
+    /**
+     * Token expiration time in seconds (optional).
+     * Time until the access token expires.
+     */
+    expires_in?: number;
+    /**
+     * OAuth 2.0 refresh token (optional).
+     * Used to obtain new access tokens without re-authentication.
+     */
+    refresh_token?: string;
+    /**
+     * Granted OAuth scopes (optional).
+     * Space-separated list of scopes that were granted.
+     */
+    scope?: string;
+    /**
+     * OpenID Connect ID token (optional).
+     * JWT containing user identity claims (only present for OIDC providers).
+     */
+    id_token?: string;
+    /**
+     * Additional provider-specific fields.
+     * Some providers may include extra fields like user_id, account_id, etc.
+     */
+    [key: string]: unknown;
+}
+
+/**
+ * Configuration for an OAuth provider instance.
+ *
+ * @remarks
+ * For built-in providers (google, github), just provide credentials.
+ * For custom providers, include the provider implementation.
+ *
+ * The provider field uses a discriminated union to ensure type safety:
+ * - When omitted or undefined: assumes a built-in provider
+ * - When provided: must be a valid IProvider implementation
+ *
+ * @example
+ * Built-in provider configuration:
+ * ```typescript
+ * {
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   redirectUri: 'https://app.com/callback',
+ *   scopes: ['openid', 'email']
+ * }
+ * ```
+ *
+ * @example
+ * Custom provider configuration:
+ * ```typescript
+ * {
+ *   provider: new CustomProvider(),
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   redirectUri: 'https://app.com/callback',
+ *   scopes: ['read:user']
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare type ProviderConfig = {
     /** The OAuth client ID provided by the provider */
     clientId: string;
     /** The OAuth client secret provided by the provider */
@@ -241,56 +687,413 @@ export declare interface ProviderConfig {
     /** Array of OAuth scopes to request */
     scopes: string[];
     /** Additional provider-specific configuration parameters */
-    extraConfig?: Record<string, any>;
-}
+    extraConfig?: Record<string, string>;
+} & ({
+    provider?: never;
+} | {
+    provider: IProvider;
+});
 
 /**
  * Helper type to create a configuration with only registered providers.
  * Use this with Lixa.createConfig() for type safety.
  *
+ * @deprecated This type is maintained for backward compatibility.
+ * The new inline provider configuration pattern makes this unnecessary.
+ *
  * @public
  */
-export declare type SafeLixaConfig<TProviders extends Record<string, ProviderConfig>> = LixaConfig<keyof TProviders & string> & {
+export declare type SafeLixaConfig<TProviders extends Record<string, ProviderConfig>> = LixaConfig<TProviders> & {
     providers: TProviders;
 };
 
 /**
  * Represents a user session after successful OAuth authentication.
  *
+ * @remarks
+ * The Session object is returned by SessionStrategy.createSession() and contains
+ * the session identifier and any additional data needed for your application.
+ *
+ * The structure is intentionally flexible to support various session management
+ * approaches (JWT tokens, session IDs, etc.).
+ *
  * @public
  */
-export declare interface Session {
-    /** The session token (typically the access token) */
+export declare interface Session<TRaw = OAuthTokenResponse> {
+    /**
+     * The session token or identifier.
+     * This could be an access token, a session ID, a JWT, or any other identifier
+     * that your application uses to track authenticated users.
+     */
     token: string;
-    /** Raw token data from the OAuth provider */
-    raw: any;
+    /**
+     * Raw session data.
+     * Contains the complete OAuth token response and any additional data
+     * your SessionStrategy adds (user info, database IDs, etc.).
+     *
+     * Typical OAuth token data includes:
+     * - access_token: OAuth access token
+     * - refresh_token: OAuth refresh token (if requested)
+     * - expires_in: Token expiration time in seconds
+     * - token_type: Token type (usually "Bearer")
+     * - id_token: OpenID Connect ID token (if using OIDC)
+     * - scope: Granted scopes
+     */
+    raw: TRaw;
 }
 
-declare interface SessionDao {
-    saveSession(session: string, data: any, expiresInSeconds: number): Promise<void>;
-    getSession(session: string): Promise<any | null>;
-    deleteSession(session: string): Promise<void>;
+/**
+ * Data access object for session storage.
+ *
+ * @remarks
+ * Session storage is used to persist user sessions after successful OAuth authentication.
+ * Sessions must persist across HTTP requests and support TTL (time-to-live).
+ *
+ * The default implementation uses in-memory cache, which is not suitable for production
+ * environments with multiple server instances or server restarts.
+ *
+ * For production, implement this interface with a distributed cache like Redis,
+ * a database, or a session store like express-session.
+ *
+ * @example
+ * Database implementation:
+ * ```typescript
+ * import { Session } from '../models/session';
+ *
+ * class DatabaseSessionDao implements SessionDao {
+ *   constructor(private db: Database) {}
+ *
+ *   async saveSession(sessionId: string, session: Session, expiresInSeconds: number): Promise<void> {
+ *     const expiresAt = new Date(Date.now() + expiresInSeconds * 1000);
+ *     await this.db.sessions.create({
+ *       id: sessionId,
+ *       token: session.token,
+ *       data: session.raw,
+ *       expiresAt
+ *     });
+ *   }
+ *
+ *   async getSession(sessionId: string): Promise<Session | null> {
+ *     const record = await this.db.sessions.findOne({
+ *       id: sessionId,
+ *       expiresAt: { $gt: new Date() }
+ *     });
+ *     return record ? { token: record.token, raw: record.data } : null;
+ *   }
+ *
+ *   async deleteSession(sessionId: string): Promise<void> {
+ *     await this.db.sessions.delete({ id: sessionId });
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare interface SessionDao {
+    /**
+     * Saves a session with expiration.
+     *
+     * @param sessionId - Unique session identifier
+     * @param data - Session data from SessionStrategy.createSession()
+     * @param expiresInSeconds - TTL in seconds (typically 86400 for 24 hours)
+     *
+     * @remarks
+     * The session data structure is defined by your SessionStrategy implementation.
+     * The default strategy returns a Session object with token and raw OAuth token response.
+     *
+     * @example
+     * ```typescript
+     * await sessionDao.saveSession('session-123', \{
+     *   token: 'access-token',
+     *   raw: \{
+     *     access_token: 'token',
+     *     token_type: 'Bearer',
+     *     expires_in: 3600
+     *   \}
+     * \}, 86400);
+     * ```
+     */
+    saveSession<T = unknown>(sessionId: string, data: T, expiresInSeconds: number): Promise<void>;
+    /**
+     * Retrieves a session by ID.
+     *
+     * @param sessionId - Unique session identifier
+     * @returns Session data or null if not found or expired
+     *
+     * @remarks
+     * This method is called to retrieve user session data for authenticated requests.
+     * The returned data should match the structure saved by saveSession.
+     *
+     * @example
+     * ```typescript
+     * const session = await sessionDao.getSession('session-123');
+     * if (!session) {
+     *   throw new Error('Session not found or expired');
+     * }
+     * ```
+     */
+    getSession<T = unknown>(sessionId: string): Promise<T | null>;
+    /**
+     * Deletes a session (e.g., on logout).
+     *
+     * @param sessionId - Unique session identifier
+     *
+     * @remarks
+     * This method should be called when a user logs out to invalidate their session.
+     *
+     * @example
+     * ```typescript
+     * await sessionDao.deleteSession('session-123');
+     * ```
+     */
+    deleteSession(sessionId: string): Promise<void>;
 }
 
 /**
  * Strategy interface for custom session creation.
  *
+ * @remarks
+ * Implement this interface to customize how OAuth tokens are converted into
+ * application sessions. This is where you typically:
+ * - Decode ID tokens (for OpenID Connect)
+ * - Look up or create users in your database
+ * - Generate session identifiers
+ * - Store session data
+ * - Add custom claims or metadata
+ *
+ * The default implementation (DefaultSessionStrategy) simply extracts the
+ * access token and returns it as the session token.
+ *
+ * @example
+ * Custom session strategy with database integration:
+ * ```typescript
+ * interface CustomSessionData extends OAuthTokenResponse {
+ *   userId: string;
+ *   email: string;
+ * }
+ *
+ * class DatabaseSessionStrategy implements SessionStrategy {
+ *   constructor(private db: Database) {}
+ *
+ *   async createSession(tokenData: OAuthTokenResponse): Promise<Session<CustomSessionData>> {
+ *     // Decode ID token for OIDC providers
+ *     const idToken = tokenData.id_token;
+ *     const payload = decodeJwt(idToken);
+ *
+ *     // Create or update user in database
+ *     const user = await this.db.users.upsert({
+ *       email: payload.email,
+ *       name: payload.name,
+ *       picture: payload.picture
+ *     });
+ *
+ *     // Generate session ID
+ *     const sessionId = generateSecureId();
+ *
+ *     // Store session with tokens
+ *     await this.db.sessions.create({
+ *       id: sessionId,
+ *       userId: user.id,
+ *       accessToken: tokenData.access_token,
+ *       refreshToken: tokenData.refresh_token,
+ *       expiresAt: new Date(Date.now() + (tokenData.expires_in || 3600) * 1000)
+ *     });
+ *
+ *     return {
+ *       token: sessionId,
+ *       raw: {
+ *         userId: user.id,
+ *         email: user.email,
+ *         ...tokenData
+ *       }
+ *     };
+ *   }
+ * }
+ * ```
+ *
  * @public
  */
 export declare interface SessionStrategy {
     /**
      * Creates a session from OAuth token data.
      *
-     * @param userInfo - The token data received from the OAuth provider
+     * @param tokenData - The token data received from the OAuth provider's token endpoint
      * @returns A Promise that resolves to a Session object
+     *
+     * @remarks
+     * This method is called after successfully exchanging the authorization code
+     * for tokens. The tokenData parameter contains the raw response from the
+     * provider's token endpoint.
+     *
+     * Common token data fields:
+     * - access_token: OAuth access token
+     * - refresh_token: OAuth refresh token (optional)
+     * - expires_in: Token expiration time in seconds
+     * - token_type: Token type (usually "Bearer")
+     * - id_token: OpenID Connect ID token (for OIDC providers)
+     * - scope: Granted scopes
+     *
+     * @throws \{Error\} If session creation fails (e.g., database error, invalid token)
+     *
+     * @example
+     * Simple implementation:
+     * ```typescript
+     * async createSession(tokenData: OAuthTokenResponse): Promise<Session> {
+     *   return {
+     *     token: tokenData.access_token,
+     *     raw: tokenData
+     *   };
+     * }
+     * ```
      */
-    createSession(userInfo: any): Promise<Session>;
+    createSession(tokenData: OAuthTokenResponse): Promise<Session>;
 }
 
-declare interface StateDao {
-    saveState(state: string, data: any, expiresInSeconds: number): Promise<void>;
-    getState(state: string): Promise<any | null>;
+/**
+ * Data access object for OAuth state storage.
+ *
+ * @remarks
+ * State storage is used during the OAuth authorization flow to:
+ * - Prevent CSRF attacks by validating the state parameter
+ * - Store PKCE code verifiers for secure token exchange
+ * - Maintain OAuth flow context across HTTP requests
+ *
+ * State data must persist across HTTP requests and support TTL (time-to-live).
+ * The default implementation uses in-memory cache, which is not suitable for production
+ * environments with multiple server instances or server restarts.
+ *
+ * For production, implement this interface with a distributed cache like Redis,
+ * or a database with TTL support.
+ *
+ * @example
+ * Redis implementation:
+ * ```typescript
+ * class RedisStateDao implements StateDao {
+ *   constructor(private redis: RedisClient) {}
+ *
+ *   async saveState(state: string, data: StateData, expiresInSeconds: number): Promise<void> {
+ *     await this.redis.setex(`oauth:state:${state}`, expiresInSeconds, JSON.stringify(data));
+ *   }
+ *
+ *   async getState(state: string): Promise<StateData | null> {
+ *     const data = await this.redis.get(`oauth:state:${state}`);
+ *     return data ? JSON.parse(data) : null;
+ *   }
+ *
+ *   async deleteState(state: string): Promise<void> {
+ *     await this.redis.del(`oauth:state:${state}`);
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare interface StateDao {
+    /**
+     * Saves OAuth state with expiration.
+     *
+     * @param state - The state parameter value (random string for CSRF protection)
+     * @param data - State data including provider name and PKCE code verifier
+     * @param expiresInSeconds - TTL in seconds (typically 300 for 5 minutes)
+     *
+     * @remarks
+     * The data object MUST include the following required fields:
+     * - **provider** (string): Provider name for callback routing (e.g., 'google', 'github')
+     * - **codeVerifier** (string): PKCE code verifier for secure token exchange (64 hex characters)
+     * - **createdAt** (number): Unix timestamp in milliseconds for debugging and validation
+     *
+     * These fields are automatically populated by Lixa during the authorization flow.
+     * The state is stored when generating the authorization URL and retrieved during
+     * the OAuth callback to complete the PKCE flow.
+     *
+     * @see {@link StateData} for the complete state data structure
+     *
+     * @example
+     * ```typescript
+     * await stateDao.saveState('random-state-123', {
+     *   provider: 'google',
+     *   codeVerifier: 'abc123...',
+     *   createdAt: Date.now()
+     * }, 300);
+     * ```
+     */
+    saveState(state: string, data: StateData, expiresInSeconds: number): Promise<void>;
+    /**
+     * Retrieves OAuth state data.
+     *
+     * @param state - The state parameter value
+     * @returns State data or null if not found or expired
+     *
+     * @remarks
+     * This method is called during the OAuth callback to validate the state
+     * parameter and retrieve the PKCE code verifier for token exchange.
+     *
+     * The returned data will include:
+     * - provider: Provider name for routing
+     * - codeVerifier: PKCE code verifier for token exchange
+     * - createdAt: Timestamp when state was created
+     *
+     * @see {@link StateData} for the complete state data structure
+     *
+     * @example
+     * ```typescript
+     * const stateData = await stateDao.getState('random-state-123');
+     * if (!stateData) {
+     *   throw new Error('Invalid or expired state');
+     * }
+     * console.log(stateData.provider); // 'google'
+     * console.log(stateData.codeVerifier); // 'abc123...'
+     * ```
+     */
+    getState(state: string): Promise<StateData | null>;
+    /**
+     * Deletes OAuth state (called after successful validation).
+     *
+     * @param state - The state parameter value
+     *
+     * @remarks
+     * This method should be called after successfully validating the state
+     * to prevent replay attacks. State should only be usable once.
+     *
+     * @example
+     * ```typescript
+     * await stateDao.deleteState('random-state-123');
+     * ```
+     */
     deleteState(state: string): Promise<void>;
 }
 
+/**
+ * OAuth state data structure.
+ *
+ * @remarks
+ * This structure is used internally by Lixa to store OAuth flow state
+ * during the authorization process. It contains the information needed
+ * to complete the PKCE flow and route callbacks to the correct provider.
+ *
+ * @public
+ */
+export declare interface StateData {
+    /**
+     * Provider name for callback routing.
+     * Used to identify which provider configuration to use when handling the callback.
+     *
+     * @example 'google', 'github', 'custom'
+     */
+    provider: string;
+    /**
+     * PKCE code verifier for secure token exchange.
+     * A cryptographically random string (64 hex characters) used in the PKCE flow
+     * to prevent authorization code interception attacks.
+     *
+     * @see RFC 7636 - Proof Key for Code Exchange
+     */
+    codeVerifier: string;
+    /**
+     * Unix timestamp in milliseconds when the state was created.
+     * Used for debugging and validation purposes.
+     */
+    createdAt: number;
+}
+
 export { }