@vunexa/lixa 0.1.6-alpha.8 → 0.1.6-alpha.9

package/dist/dao/session-cache.d.ts

@@ -5,7 +5,8 @@ declare class LocalSessionHandler implements SessionHandler {
     private emailToSessionMap;
     sessionStorage: SessionStorage;
     constructor(defaultTtlSeconds?: number);
-    GenerateSession<T extends Session>(tokenData: OAuthTokenResponse, providerMetadata: ProviderMetadata): Promise<T>;
+    generateSession<T extends Session>(tokenData: OAuthTokenResponse, _providerMetadata?: ProviderMetadata): Promise<T>;
+    GenerateSession<T extends Session>(tokenData: OAuthTokenResponse, providerMetadata?: ProviderMetadata): Promise<T>;
 }
 export { LocalSessionHandler };
 //# sourceMappingURL=session-cache.d.ts.map

package/dist/dao/session-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-cache.d.ts","sourceRoot":"","sources":["../../src/dao/session-cache.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEvF,cAAM,mBAAoB,YAAW,cAAc;IACjD,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,iBAAiB,CAAkC;IACpD,cAAc,EAAE,cAAc,CAAC;gBAE1B,iBAAiB,GAAE,MAAY;IAuCrC,eAAe,CAAC,CAAC,SAAS,OAAO,EACrC,SAAS,EAAE,kBAAkB,EAC7B,gBAAgB,EAAE,gBAAgB,GACjC,OAAO,CAAC,CAAC,CAAC;CAad;AAED,OAAO,EAAE,mBAAmB,EAAE,CAAC"}
+{"version":3,"file":"session-cache.d.ts","sourceRoot":"","sources":["../../src/dao/session-cache.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEvF,cAAM,mBAAoB,YAAW,cAAc;IACjD,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,iBAAiB,CAAkC;IACpD,cAAc,EAAE,cAAc,CAAC;gBAE1B,iBAAiB,GAAE,MAAY;IAwDrC,eAAe,CAAC,CAAC,SAAS,OAAO,EACrC,SAAS,EAAE,kBAAkB,EAC7B,iBAAiB,CAAC,EAAE,gBAAgB,GACnC,OAAO,CAAC,CAAC,CAAC;IAcP,eAAe,CAAC,CAAC,SAAS,OAAO,EACrC,SAAS,EAAE,kBAAkB,EAC7B,gBAAgB,CAAC,EAAE,gBAAgB,GAClC,OAAO,CAAC,CAAC,CAAC;CAGd;AAED,OAAO,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/dao/state-cache.d.ts

@@ -7,6 +7,10 @@ declare class LocalStateHandler implements StateHandler {
         state: string;
         data: StateData;
     }>;
+    GenerateState(provider: string): Promise<{
+        state: string;
+        data: StateData;
+    }>;
 }
 export { LocalStateHandler };
 //# sourceMappingURL=state-cache.d.ts.map

package/dist/dao/state-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-cache.d.ts","sourceRoot":"","sources":["../../src/dao/state-cache.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEhE,cAAM,iBAAkB,YAAW,YAAY;IAC7C,OAAO,CAAC,KAAK,CAAY;IAClB,YAAY,EAAE,YAAY,CAAC;gBAEtB,iBAAiB,GAAE,MAAY;IAoBrC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,CAAA;KAAE,CAAC;CAanF;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAC"}
+{"version":3,"file":"state-cache.d.ts","sourceRoot":"","sources":["../../src/dao/state-cache.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEhE,cAAM,iBAAkB,YAAW,YAAY;IAC7C,OAAO,CAAC,KAAK,CAAY;IAClB,YAAY,EAAE,YAAY,CAAC;gBAEtB,iBAAiB,GAAE,MAAY;IAoBrC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,CAAA;KAAE,CAAC;IAe5E,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,CAAA;KAAE,CAAC;CAGnF;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/dao/types.d.ts

@@ -164,10 +164,20 @@ export 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.
      *
@@ -193,7 +203,7 @@ export 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>;
@@ -273,13 +283,13 @@ export interface ResourceHandler {
  * @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
@@ -288,7 +298,7 @@ export interface ResourceHandler {
  * 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({
@@ -307,7 +317,7 @@ export interface ResourceHandler {
  *     };
  *   },
  *
- *   storage: {
+ *   sessionStorage: {
  *     saveSession: async (sessionId, session, expiresInSeconds) => {
  *       const expiresAt = new Date(Date.now() + expiresInSeconds * 1000);
  *       await db.sessions.create({
@@ -333,78 +343,21 @@ export interface ResourceHandler {
  * };
  * ```
  *
- * @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 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: import('../models/session').OAuthTokenResponse, providerMetadata: import('../models/session').ProviderMetadata): Promise<T>;
+    /**
+     * Generates session data from OAuth token data (PascalCase alias for backward compatibility).
+     */
+    GenerateSession?<T extends Session>(tokenData: import('../models/session').OAuthTokenResponse, providerMetadata: import('../models/session').ProviderMetadata): Promise<T>;
     /**
      * Session storage operations.
      *
@@ -415,12 +368,5 @@ export 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: import('../models/session').OAuthTokenResponse, providerMetadata: import('../models/session').ProviderMetadata): Promise<T>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/dao/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/dao/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/dao/types.ts"],"names":[],"mappings":"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"}

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

@@ -149,6 +149,16 @@ export declare class AccountUnlinkError extends LixaError {
  */
 export declare function clearSessionCookie(options?: CookieOptions): CookiePayload;
 
+/**
+ * Clears the session cookie on an Express response.
+ *
+ * @param res - Express response object
+ * @param options - Optional cookie attribute overrides
+ *
+ * @public
+ */
+export declare function clearSessionCookieOnResponse(res: ExpressLikeResponse, options?: CookieOptions): void;
+
 /**
  * Generates an expired OAuth state cookie payload to clean up the state cookie after callback.
  *
@@ -158,6 +168,16 @@ export declare function clearSessionCookie(options?: CookieOptions): CookiePaylo
  */
 export declare function clearStateCookie(options?: CookieOptions): CookiePayload;
 
+/**
+ * Clears the OAuth CSRF state cookie on an Express response.
+ *
+ * @param res - Express response object
+ * @param options - Optional cookie attribute overrides
+ *
+ * @public
+ */
+export declare function clearStateCookieOnResponse(res: ExpressLikeResponse, options?: CookieOptions): void;
+
 /**
  * Type representing the keys of configured providers
  */
@@ -243,6 +263,27 @@ export declare interface CookiePayload {
     header: string;
 }
 
+/**
+ * Creates an Express authentication middleware that verifies the session cookie and populates req.sessionInfo.
+ *
+ * @param lixa - Lixa instance
+ * @param options - Optional session cookie name and custom unauthorized handler
+ *
+ * @example
+ * ```typescript
+ * const requireAuth = createRequireAuthMiddleware(lixa);
+ * app.get('/protected', requireAuth, (req, res) => {
+ *   res.json({ user: req.sessionInfo });
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function createRequireAuthMiddleware(lixa: Lixa<any>, options?: {
+    sessionCookieName?: string;
+    unauthorizedHandler?: (req: ExpressLikeRequest, res: ExpressLikeResponse) => void;
+}): ExpressLikeRequestHandler;
+
 /**
  * Generates a session cookie payload with secure default options.
  *
@@ -297,7 +338,7 @@ export declare const DEFAULT_SESSION_MAX_AGE_SECONDS: number;
 export declare const DEFAULT_STATE_COOKIE_NAME = "lixa_oauth_state";
 
 /**
- * Default OAuth state max age in seconds (10 minutes).
+ * Default OAuth state max age in seconds (5 minutes / 300 seconds).
  * @public
  */
 export declare const DEFAULT_STATE_MAX_AGE_SECONDS: number;
@@ -318,6 +359,53 @@ export declare class EmailNotVerifiedError extends LixaError {
     constructor(email?: string, details?: Record<string, unknown>);
 }
 
+/**
+ * Options for Express authentication helpers.
+ * @public
+ */
+export declare interface ExpressAuthHelperOptions {
+    sessionCookieName?: string;
+    sessionCookieOptions?: CookieOptions;
+    stateCookieOptions?: CookieOptions;
+    successRedirectUrl?: string;
+    errorRedirectUrl?: string;
+}
+
+/**
+ * Express-compatible NextFunction type.
+ * @public
+ */
+declare type ExpressLikeNextFunction = (err?: any) => void;
+
+/**
+ * Duck-typed Express request interface for framework-agnostic typing.
+ * @public
+ */
+declare interface ExpressLikeRequest {
+    cookies?: Record<string, string>;
+    sessionInfo?: any;
+    sessionId?: string;
+    [key: string]: any;
+}
+
+/**
+ * Express-compatible RequestHandler type.
+ * @public
+ */
+declare type ExpressLikeRequestHandler = (req: ExpressLikeRequest, res: ExpressLikeResponse, next: ExpressLikeNextFunction) => any;
+
+/**
+ * Duck-typed Express response interface for framework-agnostic typing.
+ * @public
+ */
+declare interface ExpressLikeResponse {
+    cookie(name: string, value: string, options?: any): any;
+    status(code: number): this;
+    json(body: any): any;
+    redirect?(url: string): any;
+    [key: string]: any;
+}
+
 /**
  * Extract user info from OAuth token data
  *
@@ -620,8 +708,11 @@ 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;
@@ -658,16 +749,12 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      */
     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;
     /**
@@ -866,7 +953,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;
     /**
@@ -932,14 +1019,6 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
         prompt?: string;
         extraConfig?: Record<string, 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]
-     */
-    private static userResourceStore;
-    static LOCAL_RESOURCE_HANDLER: ResourceHandler;
     private getUserKeyFromSession;
     /**
      * Handles the OAuth callback for a connected resource provider and stores resource tokens bound to user account.
@@ -972,11 +1051,16 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
     getConnectedResource(sessionId: string, provider: string): Promise<ConnectedResource | null>;
     /**
      * Refreshes a user's resource access token using its refresh token.
+     * Deduplicates concurrent refresh requests via an in-flight promise mutex.
      *
      * @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.
      */
@@ -1057,6 +1141,11 @@ export declare interface LixaConfig<TProviders extends Record<string, ProviderCo
      * 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;
 }
 
 /**
@@ -1076,6 +1165,26 @@ export declare class LixaError extends Error {
     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
@@ -1170,6 +1279,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>;
 } & ({
@@ -1339,13 +1454,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
@@ -1354,7 +1469,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({
@@ -1373,7 +1488,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({
@@ -1399,78 +1514,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.
      *
@@ -1481,13 +1539,6 @@ 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>;
 }
 
 /**
@@ -1513,7 +1564,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>;
@@ -1541,6 +1592,28 @@ export declare interface SessionStorage {
     } | null>;
 }
 
+/**
+ * Sets an RFC 6265bis compliant session cookie on an Express response.
+ *
+ * @param res - Express response object
+ * @param sessionId - Unique session ID
+ * @param options - Optional cookie attribute overrides
+ *
+ * @public
+ */
+export declare function setSessionCookieOnResponse(res: ExpressLikeResponse, sessionId: string, options?: CookieOptions): void;
+
+/**
+ * Sets an OAuth CSRF state cookie on an Express response.
+ *
+ * @param res - Express response object
+ * @param state - OAuth state parameter
+ * @param options - Optional cookie attribute overrides
+ *
+ * @public
+ */
+export declare function setStateCookieOnResponse(res: ExpressLikeResponse, state: string, options?: CookieOptions): void;
+
 /**
  * OAuth state data structure.
  *
@@ -1675,10 +1748,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.
      *