@vunexa/lixa 0.0.1-alpha.8 → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1361 @@
+/**
+ * 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
+ */
+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]: string | number | boolean | undefined;
+}
+/**
+ * Represents a linked provider account within a user's session.
+ *
+ * @public
+ */
+interface LinkedAccount {
+    /** The provider identifier (e.g. 'github', 'google') */
+    provider: string;
+    /** Provider user ID if available */
+    providerUserId?: string | undefined;
+    /** User email for this provider */
+    email?: string | undefined;
+    /** OAuth access token for this provider */
+    accessToken: string;
+    /** Full raw token response from provider */
+    raw: OAuthTokenResponse;
+    /** Unix timestamp in milliseconds when account was linked */
+    linkedAt: number;
+}
+/**
+ * Represents a connected resource provider token (e.g. GitHub Repo access, Google Drive)
+ * obtained post-authentication via Lixa's Resource Connection API.
+ *
+ * @public
+ */
+interface ConnectedResource {
+    /** The provider identifier (e.g. 'github', 'google', 'slack') */
+    provider: string;
+    /** Resource access token */
+    accessToken: string;
+    /** Optional refresh token for offline resource access */
+    refreshToken?: string | undefined;
+    /** Resource scopes granted by the user */
+    scopes: string[];
+    /** Full raw token response from provider */
+    raw: OAuthTokenResponse;
+    /** Unix timestamp in milliseconds when resource was connected */
+    connectedAt: number;
+}
+/**
+ * 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, multi-SSO account linking, connected resources, etc.).
+ *
+ * @public
+ */
+interface Session<TRaw = OAuthTokenResponse> {
+    /**
+     * Unique session ID generated by Lixa upon authentication.
+     */
+    id?: string;
+    /**
+     * The primary access token or session token identifier.
+     */
+    token: string;
+    /** Unique unified user ID across linked accounts */
+    userId?: string;
+    /** Primary user email */
+    email?: string;
+    /** Current active auth provider for this session turn */
+    provider?: string;
+    /** Linked SSO provider accounts keyed by provider name */
+    accounts?: Record<string, LinkedAccount>;
+    /** Connected third-party resource provider tokens keyed by provider name */
+    resources?: Record<string, ConnectedResource>;
+    /**
+     * Raw session data.
+     * Contains the complete OAuth token response and any additional data
+     * your SessionStrategy adds (user info, database IDs, etc.).
+     */
+    raw: TRaw;
+}
+/**
+ * Provider metadata passed to session strategy.
+ * Contains provider name and endpoints for user info extraction.
+ *
+ * @public
+ */
+interface ProviderMetadata {
+    /** The provider name (e.g., 'google', 'github') */
+    name: string;
+    /** Provider endpoints */
+    endpoints: {
+        /** Authorization endpoint URL */
+        authorization: string;
+        /** Token endpoint URL */
+        token: string;
+        /** UserInfo endpoint URL */
+        userInfo: string;
+    };
+}
+
+/**
+ * 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
+ */
+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;
+}
+/**
+ * State storage operations interface.
+ *
+ * @remarks
+ * Groups all state storage operations together. All methods must be implemented
+ * if this interface is provided.
+ *
+ * @public
+ */
+interface StateStorage {
+    /**
+     * 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)
+     */
+    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
+     */
+    getState(state: string): Promise<StateData | null>;
+    /**
+     * Deletes OAuth state (called after successful validation).
+     *
+     * @param state - The state parameter value
+     */
+    deleteState(state: string): Promise<void>;
+}
+/**
+ * State handler for OAuth authorization flow.
+ *
+ * @remarks
+ * The StateHandler manages state generation and storage during the OAuth authorization flow.
+ *
+ * - GenerateState: Optional. Customizes how state parameters and PKCE verifiers are generated.
+ *   If not provided, uses default implementation (cryptographically secure random strings).
+ *
+ * - storage: Optional. Provides custom state storage (save/get/delete operations).
+ *   If not provided, uses in-memory cache (not suitable for production).
+ *
+ * For production, implement storage with Redis, database, or other distributed cache.
+ *
+ * @example
+ * Full implementation with Redis:
+ * ```typescript
+ * import { StateHandler, StateData } from '@vunexa/lixa';
+ *
+ * const stateHandler: StateHandler = {
+ *   GenerateState: async (provider) => {
+ *     const state = generateSecureRandomString(32);
+ *     const codeVerifier = generateSecureRandomString(64);
+ *     return {
+ *       state,
+ *       data: {
+ *         provider,
+ *         codeVerifier,
+ *         createdAt: Date.now()
+ *       }
+ *     };
+ *   },
+ *
+ *   storage: {
+ *     saveState: async (state, data, expiresInSeconds) => {
+ *       await redis.setex(`oauth:state:${state}`, expiresInSeconds, JSON.stringify(data));
+ *     },
+ *     getState: async (state) => {
+ *       const data = await redis.get(`oauth:state:${state}`);
+ *       return data ? JSON.parse(data) : null;
+ *     },
+ *     deleteState: async (state) => {
+ *       await redis.del(`oauth:state:${state}`);
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * Minimal implementation (uses defaults):
+ * ```typescript
+ * const stateHandler: StateHandler = {
+ *   storage: {
+ *     saveState: async (state, data, expiresInSeconds) => {
+ *       await redis.setex(state, expiresInSeconds, JSON.stringify(data));
+ *     },
+ *     getState: async (state) => {
+ *       const data = await redis.get(state);
+ *       return data ? JSON.parse(data) : null;
+ *     },
+ *     deleteState: async (state) => {
+ *       await redis.del(state);
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ */
+interface StateHandler {
+    /**
+     * Generates OAuth state parameter and associated data.
+     *
+     * @param provider - The provider name for callback routing
+     * @returns A Promise that resolves to state string and state data
+     *
+     * @remarks
+     * This method generates:
+     * - state: A cryptographically secure random string for CSRF protection
+     * - codeVerifier: A PKCE code verifier for secure token exchange
+     * - createdAt: Timestamp for debugging
+     *
+     * If not provided, defaults to generating 32-byte hex strings for state
+     * and 64-byte hex strings for code verifier.
+     *
+     * @example
+     * ```typescript
+     * GenerateState: async (provider) => {
+     *   const state = crypto.randomBytes(16).toString('hex');
+     *   const codeVerifier = crypto.randomBytes(32).toString('hex');
+     *   return {
+     *     state,
+     *     data: {
+     *       provider,
+     *       codeVerifier,
+     *       createdAt: Date.now()
+     *     }
+     *   };
+     * }
+     * ```
+     */
+    generateState?(provider: string): Promise<{
+        state: string;
+        data: StateData;
+    }>;
+    /**
+     * State storage operations.
+     *
+     * @remarks
+     * Provides methods for saving, retrieving, and deleting OAuth state.
+     * All three methods must be implemented together.
+     *
+     * If not provided, uses in-memory cache (not suitable for production).
+     */
+    stateStorage?: StateStorage;
+}
+/**
+ * Session storage operations interface.
+ *
+ * @remarks
+ * Groups all session storage operations together. All methods must be implemented
+ * if this interface is provided.
+ *
+ * @public
+ */
+interface SessionStorage {
+    /**
+     * Saves a session with expiration.
+     *
+     * @param sessionId - Unique session identifier
+     * @param session - Session data from GenerateSession()
+     * @param expiresInSeconds - TTL in seconds (typically 86400 for 24 hours)
+     */
+    saveSession<T extends Session>(sessionId: string, session: 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
+     */
+    getSession<T extends Session>(sessionId: string): Promise<T | null>;
+    /**
+     * Deletes a session (e.g., on logout).
+     *
+     * @param sessionId - Unique session identifier
+     */
+    deleteSession(sessionId: string): Promise<void>;
+    /**
+     * Optional helper to retrieve an active session by user email for account linking.
+     *
+     * @param email - Primary user email
+     */
+    getSessionByEmail?<T extends Session>(email: string): Promise<{
+        sessionId: string;
+        session: T;
+    } | null>;
+}
+/**
+ * Session handler for OAuth authentication.
+ *
+ * @remarks
+ * The SessionHandler manages session generation and storage after successful OAuth authentication.
+ *
+ * - GenerateSession: Optional. Customizes how OAuth tokens are converted into session data.
+ *   If not provided, uses default implementation (access token as session token).
+ *
+ * - storage: Optional. Provides custom session storage (save/get/delete operations).
+ *   If not provided, uses in-memory cache (not suitable for production).
+ *
+ * For production, implement both GenerateSession (for user creation/lookup) and storage
+ * (for persistent session storage with Redis, database, etc.).
+ *
+ * @example
+ * Full implementation with database:
+ * ```typescript
+ * import { SessionHandler, Session, OAuthTokenResponse, ProviderMetadata, extractUserInfo } from '@vunexa/lixa';
+ *
+ * const sessionHandler: SessionHandler = {
+ *   GenerateSession: async (tokenData, providerMetadata) => {
+ *     // Extract user info and create/retrieve user
+ *     const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+ *     const user = await db.users.upsert({
+ *       email: userInfo.email,
+ *       name: userInfo.name
+ *     });
+ *
+ *     // Return session data (not stored yet)
+ *     return {
+ *       token: tokenData.access_token,
+ *       raw: {
+ *         ...tokenData,
+ *         userId: user.id,
+ *         provider: providerMetadata.name
+ *       }
+ *     };
+ *   },
+ *
+ *   storage: {
+ *     saveSession: async (sessionId, session, expiresInSeconds) => {
+ *       const expiresAt = new Date(Date.now() + expiresInSeconds * 1000);
+ *       await db.sessions.create({
+ *         id: sessionId,
+ *         token: session.token,
+ *         data: session.raw,
+ *         expiresAt
+ *       });
+ *     },
+ *
+ *     getSession: async (sessionId) => {
+ *       const record = await db.sessions.findOne({
+ *         id: sessionId,
+ *         expiresAt: { $gt: new Date() }
+ *       });
+ *       return record ? { token: record.token, raw: record.data } : null;
+ *     },
+ *
+ *     deleteSession: async (sessionId) => {
+ *       await db.sessions.delete({ id: sessionId });
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * Minimal implementation (uses defaults):
+ * ```typescript
+ * const sessionHandler: SessionHandler = {
+ *   storage: {
+ *     saveSession: async (sessionId, session, expiresInSeconds) => {
+ *       await redis.setex(sessionId, expiresInSeconds, JSON.stringify(session));
+ *     },
+ *     getSession: async (sessionId) => {
+ *       const data = await redis.get(sessionId);
+ *       return data ? JSON.parse(data) : null;
+ *     },
+ *     deleteSession: async (sessionId) => {
+ *       await redis.del(sessionId);
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ */
+interface SessionHandler {
+    /**
+     * Generates session data from OAuth token data.
+     *
+     * @param tokenData - The token data received from the OAuth provider's token endpoint
+     * @param providerMetadata - Provider metadata including name and endpoints
+     * @returns A Promise that resolves to session data
+     *
+     * @remarks
+     * This method is responsible for creating session data from OAuth tokens.
+     * It is called after successfully exchanging the authorization code for tokens.
+     *
+     * Token Data:
+     * - 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
+     *
+     * Provider Metadata:
+     * - name: The provider name (e.g., 'google', 'github')
+     * - endpoints: Provider endpoints (authorization, token, userInfo)
+     *
+     * Your implementation should:
+     * 1. Extract user info (using extractUserInfo or decode ID token)
+     * 2. Create or lookup users in your database
+     * 3. Build and return session data with any custom fields
+     *
+     * Note: This method should NOT store the session. Storage is handled by the storage object.
+     *
+     * If not provided, defaults to using the access token as the session token.
+     *
+     * @example
+     * ```typescript
+     * GenerateSession: async (tokenData, providerMetadata) => {
+     *   const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+     *   const user = await db.users.upsert({ email: userInfo.email });
+     *
+     *   return {
+     *     token: tokenData.access_token,
+     *     raw: {
+     *       ...tokenData,
+     *       userId: user.id,
+     *       provider: providerMetadata.name
+     *     }
+     *   };
+     * }
+     * ```
+     */
+    generateSession?<T extends Session>(tokenData: OAuthTokenResponse, providerMetadata: ProviderMetadata): Promise<T>;
+    /**
+     * Session storage operations.
+     *
+     * @remarks
+     * Provides methods for saving, retrieving, and deleting sessions.
+     * All three methods must be implemented together.
+     *
+     * If not provided, uses in-memory cache (not suitable for production).
+     */
+    sessionStorage?: SessionStorage;
+    /**
+     * Optional method to generate session data from OAuth tokens.
+     *
+     * @remarks
+     * If not provided, uses default implementation from LocalSessionHandler.
+     */
+    generateSession?<T extends Session>(tokenData: OAuthTokenResponse, providerMetadata: ProviderMetadata): Promise<T>;
+}
+
+/**
+ * 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
+ */
+interface IProvider {
+    /**
+     * 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 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.
+     *
+     * @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;
+    /**
+     * Minimal authentication scopes required for identity verification (AuthN).
+     *
+     * @example ['openid', 'email', 'profile'] or ['read:user', 'user:email']
+     */
+    authScopes?: string[];
+}
+
+/**
+ * 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
+ */
+type ProviderConfig = {
+    /** The OAuth client ID provided by the provider */
+    clientId: string;
+    /** The OAuth client secret provided by the provider */
+    clientSecret: string;
+    /** The redirect URI registered with the provider */
+    redirectUri: string;
+    /** Array of OAuth scopes to request */
+    scopes: string[];
+    /** Additional provider-specific configuration parameters */
+    extraConfig?: Record<string, string>;
+} & ({
+    provider?: never;
+} | {
+    provider: IProvider;
+});
+/**
+ * Main configuration object for Lixa.
+ * 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 handlers:
+ * ```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']
+ *     }
+ *   },
+ *   stateHandler: {
+ *     storage: {
+ *       saveState: async (state, data, ttl) => await redis.setex(state, ttl, JSON.stringify(data)),
+ *       getState: async (state) => JSON.parse(await redis.get(state) || 'null'),
+ *       deleteState: async (state) => await redis.del(state)
+ *     }
+ *   },
+ *   sessionHandler: {
+ *     GenerateSession: async (tokenData, providerMetadata) => {
+ *       const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+ *       const user = await db.users.upsert({ email: userInfo.email });
+ *       return { token: tokenData.access_token, raw: { ...tokenData, userId: user.id } };
+ *     },
+ *     storage: {
+ *       saveSession: async (id, session, ttl) => await db.sessions.create({ id, session, ttl }),
+ *       getSession: async (id) => await db.sessions.findOne({ id }),
+ *       deleteSession: async (id) => await db.sessions.delete({ id })
+ *     }
+ *   },
+ *   debug: true
+ * });
+ * ```
+ *
+/**
+ * Strategy mode for multi-SSO identity account linking.
+ *
+ * @public
+ */
+declare enum AccountLinkingStrategy {
+    /** Automatically merge identities matching the same verified primary email address */
+    AUTO_LINK_BY_VERIFIED_EMAIL = "AUTO_LINK_BY_VERIFIED_EMAIL",
+    /** Keep identity profiles isolated per provider (no automatic account merging) */
+    ISOLATED = "ISOLATED"
+}
+/**
+ * Supported mode values for account linking configuration.
+ *
+ * @public
+ */
+type AccountLinkingMode = AccountLinkingStrategy | "AUTO_LINK_BY_VERIFIED_EMAIL" | "ISOLATED" | "linkByEmail" | "separate";
+/**
+ * Account linking settings for Lixa.
+ *
+ * @public
+ */
+interface AccountLinkingConfig {
+    /**
+     * Account linking mode strategy:
+     * - AccountLinkingStrategy.AUTO_LINK_BY_VERIFIED_EMAIL ("AUTO_LINK_BY_VERIFIED_EMAIL" / "linkByEmail"): Auto-link accounts sharing same verified email.
+     * - AccountLinkingStrategy.ISOLATED ("ISOLATED" / "separate"): Keep provider accounts isolated (default).
+     *
+     * @default AccountLinkingStrategy.ISOLATED
+     */
+    mode?: AccountLinkingMode;
+    /**
+     * Whether to require that the email address is verified by the provider before linking.
+     *
+     * @default true
+     */
+    requireVerifiedEmail?: boolean;
+}
+/**
+ * Main configuration object for Lixa.
+ * Provides type-safe provider name inference.
+ *
+ * @public
+ */
+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;
+    /**
+     * Account linking configuration for multi-SSO user linking.
+     */
+    accountLinking?: AccountLinkingConfig;
+    /**
+     * Optional custom state handler.
+     * Handles state generation and storage during OAuth authorization flow.
+     *
+     * - GenerateState: Customizes how state parameters and PKCE verifiers are generated
+     * - storage: Provides persistent state storage (save/get/delete operations)
+     *
+     * Defaults to in-memory cache if not provided (not suitable for production).
+     *
+     * @see {@link StateHandler}
+     */
+    stateHandler?: StateHandler;
+    /**
+     * Optional custom session handler.
+     * Handles session generation and storage after authentication.
+     *
+     * - GenerateSession: Customizes how OAuth tokens are converted into session data
+     * - storage: Provides persistent session storage (save/get/delete operations)
+     *
+     * Defaults to in-memory cache if not provided (not suitable for production).
+     *
+     * @see {@link SessionHandler}
+     */
+    sessionHandler?: SessionHandler;
+    /**
+     * Enable debug logging.
+     * When enabled, outputs structured logs for initialization, auth flow, and errors.
+     * Format: [Lixa] [timestamp] [level] [context] message
+     */
+    debug?: boolean;
+}
+/**
+ * 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
+ */
+type SafeLixaConfig<TProviders extends Record<string, ProviderConfig>> = LixaConfig<TProviders> & {
+    providers: TProviders;
+};
+
+/**
+ * Type representing the keys of configured providers
+ */
+type ConfiguredProviderKey<T extends LixaConfig<Record<string, ProviderConfig>>> = keyof T['providers'];
+/**
+ * A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library.
+ *
+ * @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';
+ *
+ * const lixa = new Lixa({
+ *   providers: {
+ *     google: {
+ *       provider: new GoogleProvider(),
+ *       clientId: 'your-client-id',
+ *       clientSecret: 'your-client-secret',
+ *       redirectUri: 'https://yourapp.com/auth/google/callback',
+ *       scopes: ['openid', 'email', 'profile']
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @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({
+ *   providers: {
+ *     custom: {
+ *       provider: customProvider,
+ *       clientId: 'your-client-id',
+ *       clientSecret: 'your-client-secret',
+ *       redirectUri: 'https://yourapp.com/auth/custom/callback',
+ *       scopes: ['read:user']
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> = LixaConfig> {
+    private static DEFAULT_PROVIDERS;
+    private static CONFIGURED_PROVIDERS;
+    private static LOCAL_STATE_HANDLER;
+    private static LOCAL_SESSION_HANDLER;
+    private config;
+    private stateHandler;
+    private sessionHandler;
+    private debug;
+    /**
+     * 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;
+    /**
+     * 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 configured, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (lixa.isProviderConfigured(provider)) {
+     *   // TypeScript now knows provider is a valid ConfiguredProviderKey
+     *   const authUrl = lixa.getAuthUrl(provider, state);
+     * }
+     * ```
+     */
+    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';
+     *   tokenEndpoint = 'https://custom.com/oauth/token';
+     *   userInfoEndpoint = 'https://custom.com/api/user';
+     * }
+     *
+     * Lixa.registerProvider({ custom: new CustomProvider() });
+     * ```
+     */
+    static registerProvider<T extends Record<string, IProvider>>(providerMap: T): void;
+    /**
+     * Gets the list of registered provider names.
+     *
+     * @returns Array of registered provider names
+     */
+    static getRegisteredProviders(): string[];
+    /**
+     * 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 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<T> & {
+        providers: T;
+    }): LixaConfig<T>;
+    /**
+     * Generates a cryptographically secure random state parameter for OAuth flows.
+     *
+     * @returns A 32-character hexadecimal string
+     *
+     * @remarks
+     * The state parameter is used to prevent CSRF attacks in OAuth flows.
+     */
+    static generateRandomState(): string;
+    /**
+     * Generates a cryptographically secure code verifier for PKCE flows.
+     *
+     * @returns A 64-character hexadecimal string (32 random bytes encoded as hex)
+     *
+     * @remarks
+     * 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.
+     *
+     * @param provider - The provider name (must be a configured provider key)
+     * @param state - The state parameter for CSRF protection
+     * @returns The complete authorization URL to redirect users to
+     *
+     * @throws Error when the provider is not configured
+     *
+     * @example
+     * ```typescript
+     * const state = Lixa.generateRandomState();
+     * const authUrl = lixa.getAuthUrl('google', state);
+     * res.redirect(authUrl);
+     * ```
+     */
+    getAuthUrl(provider: ConfiguredProviderKey<TConfig> | string, state?: string): Promise<string>;
+    /**
+     * Restricts primary authentication scopes strictly to AuthN identity scopes.
+     */
+    private resolveAuthNScopes;
+    /**
+     * Handles the OAuth callback and creates a user session.
+     *
+     * @param provider - The provider name (must be a configured provider key)
+     * @param code - The authorization code from the provider
+     * @param state - The state parameter for validation
+     * @returns A Promise that resolves to the session ID
+     *
+     * @throws Error when code or state is missing/invalid, or provider is not configured
+     *
+     * @example
+     * ```typescript
+     * const sessionId = await lixa.handleCallback({
+     *   provider: 'google',
+     *   code: req.query.code,
+     *   state: req.query.state
+     * });
+     * ```
+     */
+    handleCallback({ provider, code, state, }: {
+        provider: ConfiguredProviderKey<TConfig> | string;
+        code: string;
+        state?: string;
+    }): Promise<string>;
+    /**
+     * Explicitly link a new OAuth provider account to an active session.
+     *
+     * @param params - Object containing sessionId, provider, code, and optional state
+     * @returns The active session ID with the newly linked provider
+     */
+    linkAccount(params: {
+        sessionId: string;
+        provider: ConfiguredProviderKey<TConfig> | string;
+        code: string;
+        state?: string;
+    }): Promise<string>;
+    /**
+     * Unlinks an OAuth provider account from an active session.
+     *
+     * @param sessionId - Active session ID
+     * @param providerToUnlink - Provider name to unlink (e.g. 'github')
+     * @returns Promise resolving to true on successful unlink
+     */
+    unlinkAccount(sessionId: string, providerToUnlink: string): Promise<boolean>;
+    /**
+     * Generates an authorization URL for connecting a resource provider (AuthZ) post-login.
+     *
+     * @remarks
+     * Resource authorization is kept strictly separate from primary authentication (AuthN).
+     * Call this method after a user is authenticated to request permissions for external API access
+     * (e.g. GitHub repositories, Google Drive, Slack, etc.).
+     *
+     * @param params - Object containing sessionId, provider, requested resource scopes, and optional state
+     * @returns The authorization URL for resource consent
+     */
+    getResourceAuthUrl(params: {
+        sessionId: string;
+        provider: ConfiguredProviderKey<TConfig> | string;
+        scopes: string[];
+        state?: string;
+    }): Promise<string>;
+    /**
+     * Handles the OAuth callback for a connected resource provider and stores resource tokens on the session.
+     *
+     * @param params - Object containing sessionId, provider, code, state, and requested scopes
+     * @returns Updated Session containing stored resource tokens under session.resources[provider]
+     */
+    handleResourceCallback(params: {
+        sessionId: string;
+        provider: ConfiguredProviderKey<TConfig> | string;
+        code: string;
+        state?: string;
+        scopes?: string[];
+    }): Promise<Session>;
+    /**
+     * Retrieves a connected resource provider token for an active session.
+     *
+     * @param sessionId - Active session ID
+     * @param provider - Provider identifier (e.g. 'github')
+     */
+    getConnectedResource(sessionId: string, provider: string): Promise<ConnectedResource | null>;
+    /**
+     * Disconnects a resource provider from an active session.
+     *
+     * @param sessionId - Active session ID
+     * @param provider - Provider identifier to disconnect
+     */
+    disconnectResource(sessionId: string, provider: string): Promise<boolean>;
+    fetchSessionInfo(sessionId: string): Promise<Session | null>;
+    private exchangeCodeForToken;
+    private findProviderByType;
+}
+
+/**
+ * User information extracted from OAuth provider
+ *
+ * @public
+ */
+interface UserInfo {
+    email: string;
+    id?: string | undefined;
+    sub?: string | undefined;
+    given_name?: string | undefined;
+    family_name?: string | undefined;
+    name?: string | undefined;
+    picture?: string | undefined;
+    email_verified?: boolean | undefined;
+    iss?: string | undefined;
+}
+/**
+ * Decode JWT ID token to extract user information
+ *
+ * @public
+ */
+declare function decodeIdToken(idToken: string): UserInfo;
+/**
+ * Determine OAuth provider from ID token issuer
+ *
+ * @public
+ */
+declare function determineProviderFromIssuer(userInfo: UserInfo): string | null;
+/**
+ * Fetch user info from OAuth provider's userinfo endpoint
+ *
+ * @param accessToken - OAuth access token
+ * @param userInfoEndpoint - The provider's userinfo endpoint URL
+ * @param providerName - Provider name for error messages (optional)
+ * @returns User information from the provider
+ *
+ * @throws Error if the request fails or response is invalid
+ *
+ * @public
+ */
+declare function fetchUserInfo(accessToken: string, userInfoEndpoint: string): Promise<UserInfo>;
+/**
+ * Extract user info from OAuth token data
+ *
+ * @param tokenData - OAuth token response from provider
+ * @param providerMetadata - Provider metadata containing endpoints configuration
+ * @returns User info extracted from token or fetched from provider
+ *
+ * @remarks
+ * This function attempts to extract user information in the following order:
+ * 1. Decode ID token if present (preferred method for OIDC providers)
+ * 2. Fetch from userinfo endpoint using access token (uses providerMetadata.endpoints.userInfo)
+ *
+ * The function automatically determines the best method based on available token data.
+ * For OIDC providers (like Google), it decodes the JWT ID token.
+ * For OAuth-only providers (like GitHub), it fetches from the userinfo endpoint.
+ *
+ * @throws Error if no ID token or access token is available
+ * @throws Error if userinfo endpoint is required but not provided in providerMetadata
+ *
+ * @example
+ * With ID token (OIDC provider like Google):
+ * ```typescript
+ * const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+ * console.log(`User ${userInfo.email} authenticated`);
+ * ```
+ *
+ * @example
+ * Without ID token (OAuth provider like GitHub):
+ * ```typescript
+ * const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+ * // Automatically fetches from providerMetadata.endpoints.userInfo
+ * console.log(`User ${userInfo.email} authenticated`);
+ * ```
+ *
+ * @public
+ */
+declare function extractUserInfo(tokenData: OAuthTokenResponse, providerMetadata: ProviderMetadata): Promise<{
+    userInfo: UserInfo;
+}>;
+
+export { type AccountLinkingConfig, type AccountLinkingMode, AccountLinkingStrategy, type ConnectedResource, type IProvider, Lixa, type LixaConfig, type OAuthTokenResponse, type ProviderConfig, type ProviderMetadata, type SafeLixaConfig, type Session, type SessionHandler, type SessionStorage, type StateData, type StateHandler, type StateStorage, type UserInfo, decodeIdToken, determineProviderFromIssuer, extractUserInfo, fetchUserInfo };