@vunexa/lixa 0.1.4 → 0.1.6-alpha.10

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

@@ -123,6 +123,41 @@ export declare enum AccountLinkingStrategy {
     ISOLATED = "ISOLATED"
 }
 
+/**
+ * Thrown when unlinking an account violates security constraints (e.g. unlinking the only login provider).
+ *
+ * @public
+ */
+export declare class AccountUnlinkError extends LixaError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+
+/**
+ * Generates an expired session cookie payload to clear the session on logout.
+ *
+ * @param options - Optional overrides for cookie name or attributes
+ *
+ * @example
+ * ```typescript
+ * const cookie = clearSessionCookie();
+ * res.setHeader("Set-Cookie", cookie.header);
+ * // or with Express:
+ * res.clearCookie(cookie.name, cookie.options);
+ * ```
+ *
+ * @public
+ */
+export declare function clearSessionCookie(options?: CookieOptions): CookiePayload;
+
+/**
+ * Generates an expired OAuth state cookie payload to clean up the state cookie after callback.
+ *
+ * @param options - Optional overrides for cookie attributes
+ *
+ * @public
+ */
+export declare function clearStateCookie(options?: CookieOptions): CookiePayload;
+
 /**
  * Type representing the keys of configured providers
  */
@@ -141,6 +176,8 @@ export declare interface ConnectedResource {
     accessToken: string;
     /** Optional refresh token for offline resource access */
     refreshToken?: string | undefined;
+    /** Unix timestamp in milliseconds when the resource access token expires */
+    expiresAt?: number | undefined;
     /** Resource scopes granted by the user */
     scopes: string[];
     /** Full raw token response from provider */
@@ -149,6 +186,91 @@ export declare interface ConnectedResource {
     connectedAt: number;
 }
 
+/**
+ * Sensible default cookie configuration options.
+ * Follows RFC 6265bis and OAuth 2.0 security best practices.
+ *
+ * @public
+ */
+export declare interface CookieOptions {
+    /**
+     * Cookie name.
+     * @default 'lixa_session'
+     */
+    name?: string | undefined;
+    /**
+     * Cookie path.
+     * @default '/'
+     */
+    path?: string | undefined;
+    /**
+     * Maximum age of the cookie in seconds.
+     */
+    maxAge?: number | undefined;
+    /**
+     * Prevents client-side scripts from accessing the cookie (XSS protection).
+     * @default true
+     */
+    httpOnly?: boolean | undefined;
+    /**
+     * Ensures the cookie is only transmitted over secure HTTPS connections.
+     * @default false in development, true in production
+     */
+    secure?: boolean | undefined;
+    /**
+     * Controls whether the cookie is sent with cross-site requests (CSRF protection).
+     * @default 'lax'
+     */
+    sameSite?: "lax" | "strict" | "none" | undefined;
+    /**
+     * Cookie domain.
+     */
+    domain?: string | undefined;
+}
+
+/**
+ * Cookie payload containing name, value, options, and formatted header.
+ *
+ * @public
+ */
+export declare interface CookiePayload {
+    name: string;
+    value: string;
+    options: CookieOptions;
+    /**
+     * Formatted `Set-Cookie` header value string.
+     */
+    header: string;
+}
+
+/**
+ * Generates a session cookie payload with secure default options.
+ *
+ * @param sessionId - The session identifier string
+ * @param options - Optional overrides for cookie attributes
+ *
+ * @example
+ * ```typescript
+ * const cookie = createSessionCookie(sessionId);
+ * res.setHeader("Set-Cookie", cookie.header);
+ * // or with Express:
+ * res.cookie(cookie.name, cookie.value, cookie.options);
+ * ```
+ *
+ * @public
+ */
+export declare function createSessionCookie(sessionId: string, options?: CookieOptions): CookiePayload;
+
+/**
+ * Generates an OAuth CSRF state cookie payload for in-flight authorization flows.
+ *
+ * @param state - The random state string
+ * @param options - Optional overrides for cookie attributes
+ *
+ * @public
+ */
+export declare function createStateCookie(state: string, options?: CookieOptions): CookiePayload;
+
 /**
  * Decode JWT ID token to extract user information
  *
@@ -156,6 +278,30 @@ export declare interface ConnectedResource {
  */
 export declare function decodeIdToken(idToken: string): UserInfo;
 
+/**
+ * Default session cookie name.
+ * @public
+ */
+export declare const DEFAULT_SESSION_COOKIE_NAME = "lixa_session";
+
+/**
+ * Default session max age in seconds (24 hours).
+ * @public
+ */
+export declare const DEFAULT_SESSION_MAX_AGE_SECONDS: number;
+
+/**
+ * Default OAuth state cookie name.
+ * @public
+ */
+export declare const DEFAULT_STATE_COOKIE_NAME = "lixa_oauth_state";
+
+/**
+ * Default OAuth state max age in seconds (5 minutes / 300 seconds).
+ * @public
+ */
+export declare const DEFAULT_STATE_MAX_AGE_SECONDS: number;
+
 /**
  * Determine OAuth provider from ID token issuer
  *
@@ -163,6 +309,15 @@ export declare function decodeIdToken(idToken: string): UserInfo;
  */
 export declare function determineProviderFromIssuer(userInfo: UserInfo): string | null;
 
+/**
+ * Thrown when account linking fails, e.g. when unverified email linking is rejected.
+ *
+ * @public
+ */
+export declare class EmailNotVerifiedError extends LixaError {
+    constructor(email?: string, details?: Record<string, unknown>);
+}
+
 /**
  * Extract user info from OAuth token data
  *
@@ -217,6 +372,33 @@ export declare function extractUserInfo(tokenData: OAuthTokenResponse, providerM
  */
 export declare function fetchUserInfo(accessToken: string, userInfoEndpoint: string): Promise<UserInfo>;
 
+/**
+ * Thrown when OAuth callback parameters (e.g. authorization code or state) are missing or malformed.
+ *
+ * @public
+ */
+export declare class InvalidOAuthCallbackError extends LixaError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+
+/**
+ * Thrown when a provider configuration is invalid or missing required credentials.
+ *
+ * @public
+ */
+export declare class InvalidProviderConfigError extends LixaError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+
+/**
+ * Thrown when an OAuth state parameter is invalid, missing, or has expired.
+ *
+ * @public
+ */
+export declare class InvalidStateError extends LixaError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+
 /**
  * Interface for OAuth 2.0 and OpenID Connect provider implementations.
  *
@@ -357,6 +539,12 @@ export declare interface IProvider {
     authScopes?: string[];
 }
 
+/**
+ * Checks if the runtime environment is production.
+ * @public
+ */
+export declare function isProductionEnvironment(): boolean;
+
 /**
  * Represents a linked provider account within a user's session.
  *
@@ -432,11 +620,15 @@ declare interface LinkedAccount {
 export 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 localStateHandler;
+    private localSessionHandler;
+    private localResourceHandler;
+    private userResourceStore;
+    private refreshMutexes;
     private config;
     private stateHandler;
     private sessionHandler;
+    private resourceHandler;
     private debug;
     /**
      * Creates a new Lixa instance with the provided configuration.
@@ -457,7 +649,7 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      *
      * @param name - The provider name
      * @param config - The provider configuration
-     * @throws Error when required fields are missing or invalid
+     * @throws InvalidProviderConfigError when required fields are missing or invalid
      */
     private validateProviderConfig;
     /**
@@ -465,20 +657,16 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      *
      * @param name - The provider name
      * @param provider - The provider implementation
-     * @throws Error when required properties are missing
+     * @throws InvalidProviderConfigError when required properties are missing
      */
     private validateProviderImplementation;
     /**
-     * Structured debug logging with standardized format.
+     * Structured logging with standardized format and custom logger support.
      *
-     * @param level - Log level (INFO, WARN, ERROR)
-     * @param context - Context of the log (Init, Auth, Token, Session, State)
+     * @param level - Log level (INFO, WARN, ERROR, DEBUG)
+     * @param context - Context of the log (Init, Auth, Token, Session, State, AccountLinking, Resource)
      * @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;
     /**
@@ -677,7 +865,7 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      */
     getAuthUrl(provider: ConfiguredProviderKey<TConfig> | string, state?: string): Promise<string>;
     /**
-     * Restricts primary authentication scopes strictly to AuthN identity scopes.
+     * Restricts primary authentication scopes strictly to AuthN identity scopes unless allowNonAuthScopes is true.
      */
     private resolveAuthNScopes;
     /**
@@ -743,11 +931,9 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
         prompt?: string;
         extraConfig?: Record<string, string>;
     }): Promise<string>;
+    private getUserKeyFromSession;
     /**
-     * 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]
+     * Handles the OAuth callback for a connected resource provider and stores resource tokens bound to user account.
      */
     handleResourceCallback(params: {
         sessionId: string;
@@ -757,20 +943,58 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
         scopes?: string[];
     }): Promise<Session>;
     /**
-     * Retrieves a connected resource provider token for an active session.
+     * Retrieves a connected resource for a specific User ID / Email directly (independent of session IDs).
+     * Automatically refreshes expired access tokens if a refresh token is present.
+     *
+     * @param userIdOrEmail - User identifier or email
+     * @param provider - Resource provider identifier (e.g. 'github', 'google')
+     */
+    getUserResource(userIdOrEmail: string, provider: string): Promise<ConnectedResource | null>;
+    /**
+     * Retrieves all connected resources for a specific User ID / Email.
+     */
+    getUserResources(userIdOrEmail: string): Promise<Record<string, ConnectedResource>>;
+    /**
+     * Retrieves a connected resource provider token for an active session, auto-refreshing expired tokens if possible.
      *
      * @param sessionId - Active session ID
-     * @param provider - Provider identifier (e.g. 'github')
+     * @param provider - Provider identifier (e.g. 'github', 'google')
      */
     getConnectedResource(sessionId: string, provider: string): Promise<ConnectedResource | null>;
     /**
-     * Disconnects a resource provider from an active session.
+     * Refreshes a user's resource access token using its refresh token.
+     * Deduplicates concurrent refresh requests via an in-flight promise mutex.
      *
-     * @param sessionId - Active session ID
-     * @param provider - Provider identifier to disconnect
+     * @param userIdOrEmail - User identifier or email
+     * @param provider - Provider identifier (e.g. 'google', 'github')
+     */
+    refreshUserResourceToken(userIdOrEmail: string, provider: string, existingResource?: ConnectedResource): Promise<ConnectedResource>;
+    /**
+     * Internal execution of refresh token exchange.
+     */
+    private executeRefreshUserResourceToken;
+    /**
+     * Refreshes a connected resource access token for an active session.
+     */
+    refreshResourceToken(sessionId: string, provider: string): Promise<ConnectedResource>;
+    /**
+     * Disconnects a resource provider for a specific User ID / Email.
+     */
+    disconnectUserResource(userIdOrEmail: string, provider: string): Promise<boolean>;
+    /**
+     * Disconnects a resource provider from an active session and user account.
      */
     disconnectResource(sessionId: string, provider: string): Promise<boolean>;
+    /**
+     * Retrieves active session details from session storage.
+     */
     fetchSessionInfo(sessionId: string): Promise<Session | null>;
+    /**
+     * Deletes a session from session storage (e.g. on logout).
+     *
+     * @param sessionId - Active session identifier
+     */
+    deleteSession(sessionId: string): Promise<void>;
     private exchangeCodeForToken;
     private findProviderByType;
 }
@@ -815,14 +1039,64 @@ export declare interface LixaConfig<TProviders extends Record<string, ProviderCo
      * @see {@link SessionHandler}
      */
     sessionHandler?: SessionHandler;
+    /**
+     * Optional custom resource handler.
+     * Handles storage and management of long-lived third-party resource provider tokens (AuthZ)
+     * bound directly to user accounts (User ID or Email), independent of transient session IDs.
+     *
+     * @see {@link ResourceHandler}
+     */
+    resourceHandler?: ResourceHandler;
     /**
      * Enable debug logging.
      * When enabled, outputs structured logs for initialization, auth flow, and errors.
      * Format: [Lixa] [timestamp] [level] [context] message
      */
     debug?: boolean;
+    /**
+     * Optional custom structured logger implementation.
+     * If provided, all Lixa logs will be routed through this logger.
+     */
+    logger?: LixaLogger;
 }
 
+/**
+ * Base error class for all Lixa authentication and authorization errors.
+ *
+ * @public
+ */
+export declare class LixaError extends Error {
+    /**
+     * Standard error code string.
+     */
+    readonly code: string;
+    /**
+     * Additional error context data.
+     */
+    readonly details: Record<string, unknown> | undefined;
+    constructor(message: string, code?: string, details?: Record<string, unknown>);
+}
+
+/**
+ * Custom logger interface for Lixa.
+ * @public
+ */
+export declare interface LixaLogger {
+    log(level: LogLevel, context: LogContext, message: string, data?: Record<string, unknown>): void;
+}
+
+/**
+ * Log context for Lixa structured logging.
+ * @public
+ */
+export declare type LogContext = "Init" | "Auth" | "Token" | "Session" | "State" | "AccountLinking" | "Resource";
+
+/**
+ * Log level for Lixa structured logging.
+ * @public
+ */
+export declare type LogLevel = "INFO" | "WARN" | "ERROR" | "DEBUG";
+
 /**
  * OAuth 2.0 token response structure.
  * Based on RFC 6749 Section 5.1 and OpenID Connect Core 1.0 Section 3.1.3.3
@@ -917,6 +1191,12 @@ export declare type ProviderConfig = {
     redirectUri: string;
     /** Array of OAuth scopes to request */
     scopes: string[];
+    /**
+     * Set to true to allow non-identity (resource) scopes during primary authentication flow.
+     * By default (false), Lixa restricts primary AuthN scopes to identity scopes to maintain
+     * clean AuthN vs AuthZ separation.
+     */
+    allowNonAuthScopes?: boolean;
     /** Additional provider-specific configuration parameters */
     extraConfig?: Record<string, string>;
 } & ({
@@ -945,6 +1225,73 @@ export declare interface ProviderMetadata {
     };
 }
 
+/**
+ * Thrown when attempting to use a provider that is not configured in the Lixa instance.
+ *
+ * @public
+ */
+export declare class ProviderNotConfiguredError extends LixaError {
+    constructor(provider: string, details?: Record<string, unknown>);
+}
+
+/**
+ * Thrown when a refresh token is missing or token refresh fails for a connected resource.
+ *
+ * @public
+ */
+export declare class RefreshTokenError extends LixaError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+
+/**
+ * Resource handler configuration.
+ *
+ * @public
+ */
+export declare interface ResourceHandler {
+    resourceStorage?: ResourceStorage;
+}
+
+/**
+ * Resource storage operations interface.
+ *
+ * @remarks
+ * Manages long-lived third-party resource provider tokens (AuthZ) bound to a user account
+ * (User ID or Email), independent of short-lived user sessions.
+ *
+ * @public
+ */
+export declare interface ResourceStorage {
+    /**
+     * Saves a connected resource token for a user.
+     *
+     * @param userId - Unique user identifier or email
+     * @param provider - Resource provider name (e.g. 'github', 'google')
+     * @param resource - Connected resource details including access & refresh tokens
+     */
+    saveResource(userId: string, provider: string, resource: ConnectedResource): Promise<void>;
+    /**
+     * Retrieves a connected resource token for a user.
+     *
+     * @param userId - Unique user identifier or email
+     * @param provider - Resource provider name
+     */
+    getResource(userId: string, provider: string): Promise<ConnectedResource | null>;
+    /**
+     * Retrieves all connected resources for a user.
+     *
+     * @param userId - Unique user identifier or email
+     */
+    getUserResources(userId: string): Promise<Record<string, ConnectedResource>>;
+    /**
+     * Deletes a connected resource token for a user.
+     *
+     * @param userId - Unique user identifier or email
+     * @param provider - Resource provider name
+     */
+    deleteResource(userId: string, provider: string): Promise<void>;
+}
+
 /**
  * Helper type to create a configuration with only registered providers.
  * Use this with Lixa.createConfig() for type safety.
@@ -958,6 +1305,18 @@ export declare type SafeLixaConfig<TProviders extends Record<string, ProviderCon
     providers: TProviders;
 };
 
+/**
+ * Serializes a cookie name, value, and options into a standard `Set-Cookie` header string.
+ *
+ * @param name - Cookie name
+ * @param value - Cookie value
+ * @param options - Cookie attributes
+ * @returns Formatted `Set-Cookie` string
+ *
+ * @public
+ */
+export declare function serializeCookie(name: string, value: string, options?: CookieOptions): string;
+
 /**
  * Represents a user session after successful OAuth authentication.
  *
@@ -976,25 +1335,29 @@ export declare interface Session<TRaw = OAuthTokenResponse> {
      */
     id?: string;
     /**
-     * The primary access token or session token identifier.
+     * Linked identity provider accounts (AuthN) keyed by provider name.
+     * Single source of truth for all authenticated user SSO identities.
      */
-    token: string;
+    accounts?: Record<string, LinkedAccount>;
+    /**
+     * Connected third-party resource provider tokens (AuthZ) keyed by provider name.
+     * Single source of truth for all post-login third-party API permissions.
+     */
+    resources?: Record<string, ConnectedResource>;
     /** Unique unified user ID across linked accounts */
     userId?: string;
     /** Primary user email */
     email?: string;
-    /** Current active auth provider for this session turn */
+    /**
+     * Optional primary access token or custom session token identifier.
+     */
+    token?: string;
+    /** Optional 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.).
+     * Optional raw session token response data from provider.
      */
-    raw: TRaw;
+    raw?: TRaw;
 }
 
 /**
@@ -1003,13 +1366,13 @@ export declare interface Session<TRaw = OAuthTokenResponse> {
  * @remarks
  * The SessionHandler manages session generation and storage after successful OAuth authentication.
  *
- * - GenerateSession: Optional. Customizes how OAuth tokens are converted into session data.
+ * - 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).
+ * - sessionStorage: 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 production, implement both generateSession (for user creation/lookup) and sessionStorage
  * (for persistent session storage with Redis, database, etc.).
  *
  * @example
@@ -1018,7 +1381,7 @@ export declare interface Session<TRaw = OAuthTokenResponse> {
  * import { SessionHandler, Session, OAuthTokenResponse, ProviderMetadata, extractUserInfo } from '@vunexa/lixa';
  *
  * const sessionHandler: SessionHandler = {
- *   GenerateSession: async (tokenData, providerMetadata) => {
+ *   generateSession: async (tokenData, providerMetadata) => {
  *     // Extract user info and create/retrieve user
  *     const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
  *     const user = await db.users.upsert({
@@ -1037,7 +1400,7 @@ export declare interface Session<TRaw = OAuthTokenResponse> {
  *     };
  *   },
  *
- *   storage: {
+ *   sessionStorage: {
  *     saveSession: async (sessionId, session, expiresInSeconds) => {
  *       const expiresAt = new Date(Date.now() + expiresInSeconds * 1000);
  *       await db.sessions.create({
@@ -1063,78 +1426,21 @@ export declare interface Session<TRaw = OAuthTokenResponse> {
  * };
  * ```
  *
- * @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
  */
 export declare interface SessionHandler {
     /**
-     * Generates session data from OAuth token data.
+     * Generates session data from OAuth token data (camelCase).
      *
      * @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>;
+    /**
+     * Generates session data from OAuth token data (PascalCase alias for backward compatibility).
+     */
+    GenerateSession?<T extends Session>(tokenData: OAuthTokenResponse, providerMetadata: ProviderMetadata): Promise<T>;
     /**
      * Session storage operations.
      *
@@ -1145,13 +1451,15 @@ export declare interface SessionHandler {
      * 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>;
+}
+
+/**
+ * Thrown when a user session is not found or has expired.
+ *
+ * @public
+ */
+export declare class SessionNotFoundError extends LixaError {
+    constructor(message?: string, details?: Record<string, unknown>);
 }
 
 /**
@@ -1168,7 +1476,7 @@ export declare interface SessionStorage {
      * Saves a session with expiration.
      *
      * @param sessionId - Unique session identifier
-     * @param session - Session data from GenerateSession()
+     * @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>;
@@ -1330,10 +1638,20 @@ export declare interface StateHandler {
      * }
      * ```
      */
+    /**
+     * Generates OAuth state parameter and associated data (camelCase).
+     */
     generateState?(provider: string): Promise<{
         state: string;
         data: StateData;
     }>;
+    /**
+     * Generates OAuth state parameter and associated data (PascalCase alias for backward compatibility).
+     */
+    GenerateState?(provider: string): Promise<{
+        state: string;
+        data: StateData;
+    }>;
     /**
      * State storage operations.
      *
@@ -1379,6 +1697,16 @@ export declare interface StateStorage {
     deleteState(state: string): Promise<void>;
 }
 
+/**
+ * Thrown when exchanging an authorization code for OAuth tokens fails at the provider endpoint.
+ *
+ * @public
+ */
+export declare class TokenExchangeError extends LixaError {
+    readonly status: number | undefined;
+    constructor(message: string, status?: number, details?: Record<string, unknown>);
+}
+
 /**
  * User information extracted from OAuth provider
  *