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

package/dist/index.d.cts

@@ -314,10 +314,20 @@ 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.
      *
@@ -343,7 +353,7 @@ 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>;
@@ -423,13 +433,13 @@ 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
@@ -438,7 +448,7 @@ 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({
@@ -457,7 +467,7 @@ interface ResourceHandler {
  *     };
  *   },
  *
- *   storage: {
+ *   sessionStorage: {
  *     saveSession: async (sessionId, session, expiresInSeconds) => {
  *       const expiresAt = new Date(Date.now() + expiresInSeconds * 1000);
  *       await db.sessions.create({
@@ -483,78 +493,21 @@ 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
  */
 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.
      *
@@ -565,13 +518,6 @@ 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>;
 }
 
 /**
@@ -759,6 +705,12 @@ 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>;
 } & ({
@@ -924,6 +876,28 @@ interface LixaConfig<TProviders extends Record<string, ProviderConfig> = Record<
      * 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;
+}
+/**
+ * Log level for Lixa structured logging.
+ * @public
+ */
+type LogLevel = "INFO" | "WARN" | "ERROR" | "DEBUG";
+/**
+ * Log context for Lixa structured logging.
+ * @public
+ */
+type LogContext = "Init" | "Auth" | "Token" | "Session" | "State" | "AccountLinking" | "Resource";
+/**
+ * Custom logger interface for Lixa.
+ * @public
+ */
+interface LixaLogger {
+    log(level: LogLevel, context: LogContext, message: string, data?: Record<string, unknown>): void;
 }
 /**
  * Helper type to create a configuration with only registered providers.
@@ -997,8 +971,11 @@ type ConfiguredProviderKey<T extends LixaConfig<Record<string, ProviderConfig>>>
 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;
@@ -1035,16 +1012,12 @@ declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> =
      */
     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;
     /**
@@ -1243,7 +1216,7 @@ declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> =
      */
     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;
     /**
@@ -1309,14 +1282,6 @@ declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> =
         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.
@@ -1349,11 +1314,16 @@ declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConfig>> =
     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.
      */
@@ -1622,7 +1592,7 @@ declare const DEFAULT_STATE_COOKIE_NAME = "lixa_oauth_state";
  */
 declare const DEFAULT_SESSION_MAX_AGE_SECONDS: number;
 /**
- * Default OAuth state max age in seconds (10 minutes).
+ * Default OAuth state max age in seconds (5 minutes / 300 seconds).
  * @public
  */
 declare const DEFAULT_STATE_MAX_AGE_SECONDS: number;
@@ -1693,4 +1663,105 @@ declare function createStateCookie(state: string, options?: CookieOptions): Cook
  */
 declare function clearStateCookie(options?: CookieOptions): CookiePayload;
 
-export { type AccountLinkingConfig, type AccountLinkingMode, AccountLinkingStrategy, AccountUnlinkError, type ConnectedResource, type CookieOptions, type CookiePayload, DEFAULT_SESSION_COOKIE_NAME, DEFAULT_SESSION_MAX_AGE_SECONDS, DEFAULT_STATE_COOKIE_NAME, DEFAULT_STATE_MAX_AGE_SECONDS, EmailNotVerifiedError, type IProvider, InvalidOAuthCallbackError, InvalidProviderConfigError, InvalidStateError, Lixa, type LixaConfig, LixaError, type OAuthTokenResponse, type ProviderConfig, type ProviderMetadata, ProviderNotConfiguredError, RefreshTokenError, type ResourceHandler, type ResourceStorage, type SafeLixaConfig, type Session, type SessionHandler, SessionNotFoundError, type SessionStorage, type StateData, type StateHandler, type StateStorage, TokenExchangeError, type UserInfo, clearSessionCookie, clearStateCookie, createSessionCookie, createStateCookie, decodeIdToken, determineProviderFromIssuer, extractUserInfo, fetchUserInfo, isProductionEnvironment, serializeCookie };
+/**
+ * Duck-typed Express request interface for framework-agnostic typing.
+ * @public
+ */
+interface ExpressLikeRequest {
+    cookies?: Record<string, string>;
+    sessionInfo?: any;
+    sessionId?: string;
+    [key: string]: any;
+}
+/**
+ * Duck-typed Express response interface for framework-agnostic typing.
+ * @public
+ */
+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;
+}
+/**
+ * Express-compatible NextFunction type.
+ * @public
+ */
+type ExpressLikeNextFunction = (err?: any) => void;
+/**
+ * Express-compatible RequestHandler type.
+ * @public
+ */
+type ExpressLikeRequestHandler = (req: ExpressLikeRequest, res: ExpressLikeResponse, next: ExpressLikeNextFunction) => any;
+/**
+ * Options for Express authentication helpers.
+ * @public
+ */
+interface ExpressAuthHelperOptions {
+    sessionCookieName?: string;
+    sessionCookieOptions?: CookieOptions;
+    stateCookieOptions?: CookieOptions;
+    successRedirectUrl?: string;
+    errorRedirectUrl?: string;
+}
+/**
+ * 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
+ */
+declare function setSessionCookieOnResponse(res: ExpressLikeResponse, sessionId: string, options?: CookieOptions): void;
+/**
+ * Clears the session cookie on an Express response.
+ *
+ * @param res - Express response object
+ * @param options - Optional cookie attribute overrides
+ *
+ * @public
+ */
+declare function clearSessionCookieOnResponse(res: ExpressLikeResponse, 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
+ */
+declare function setStateCookieOnResponse(res: ExpressLikeResponse, state: string, options?: CookieOptions): void;
+/**
+ * Clears the OAuth CSRF state cookie on an Express response.
+ *
+ * @param res - Express response object
+ * @param options - Optional cookie attribute overrides
+ *
+ * @public
+ */
+declare function clearStateCookieOnResponse(res: ExpressLikeResponse, options?: CookieOptions): void;
+/**
+ * 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
+ */
+declare function createRequireAuthMiddleware(lixa: Lixa<any>, options?: {
+    sessionCookieName?: string;
+    unauthorizedHandler?: (req: ExpressLikeRequest, res: ExpressLikeResponse) => void;
+}): ExpressLikeRequestHandler;
+
+export { type AccountLinkingConfig, type AccountLinkingMode, AccountLinkingStrategy, AccountUnlinkError, type ConnectedResource, type CookieOptions, type CookiePayload, DEFAULT_SESSION_COOKIE_NAME, DEFAULT_SESSION_MAX_AGE_SECONDS, DEFAULT_STATE_COOKIE_NAME, DEFAULT_STATE_MAX_AGE_SECONDS, EmailNotVerifiedError, type ExpressAuthHelperOptions, type IProvider, InvalidOAuthCallbackError, InvalidProviderConfigError, InvalidStateError, Lixa, type LixaConfig, LixaError, type LixaLogger, type LogContext, type LogLevel, type OAuthTokenResponse, type ProviderConfig, type ProviderMetadata, ProviderNotConfiguredError, RefreshTokenError, type ResourceHandler, type ResourceStorage, type SafeLixaConfig, type Session, type SessionHandler, SessionNotFoundError, type SessionStorage, type StateData, type StateHandler, type StateStorage, TokenExchangeError, type UserInfo, clearSessionCookie, clearSessionCookieOnResponse, clearStateCookie, clearStateCookieOnResponse, createRequireAuthMiddleware, createSessionCookie, createStateCookie, decodeIdToken, determineProviderFromIssuer, extractUserInfo, fetchUserInfo, isProductionEnvironment, serializeCookie, setSessionCookieOnResponse, setStateCookieOnResponse };

package/dist/index.d.ts

@@ -16,8 +16,9 @@
  * @packageDocumentation
  */
 export { Lixa } from "./lixa";
-export { type ProviderConfig, type LixaConfig, type SafeLixaConfig, type IProvider, type Session, type ConnectedResource, type ProviderMetadata, type OAuthTokenResponse, type StateHandler, type StateStorage, type SessionHandler, type SessionStorage, type ResourceHandler, type ResourceStorage, type StateData, AccountLinkingStrategy, type AccountLinkingMode, type AccountLinkingConfig, } from "./types";
+export { type ProviderConfig, type LixaConfig, type SafeLixaConfig, type IProvider, type Session, type ConnectedResource, type ProviderMetadata, type OAuthTokenResponse, type StateHandler, type StateStorage, type SessionHandler, type SessionStorage, type ResourceHandler, type ResourceStorage, type StateData, AccountLinkingStrategy, type AccountLinkingMode, type AccountLinkingConfig, type LogLevel, type LogContext, type LixaLogger, } from "./types";
 export { type UserInfo, extractUserInfo, decodeIdToken, fetchUserInfo, determineProviderFromIssuer, } from "./utils/user-info";
 export { LixaError, InvalidStateError, ProviderNotConfiguredError, InvalidProviderConfigError, InvalidOAuthCallbackError, TokenExchangeError, SessionNotFoundError, EmailNotVerifiedError, AccountUnlinkError, RefreshTokenError, } from "./errors";
 export { type CookieOptions, type CookiePayload, DEFAULT_SESSION_COOKIE_NAME, DEFAULT_STATE_COOKIE_NAME, DEFAULT_SESSION_MAX_AGE_SECONDS, DEFAULT_STATE_MAX_AGE_SECONDS, isProductionEnvironment, serializeCookie, createSessionCookie, clearSessionCookie, createStateCookie, clearStateCookie, } from "./utils/cookies";
+export { type ExpressAuthHelperOptions, setSessionCookieOnResponse, clearSessionCookieOnResponse, setStateCookieOnResponse, clearStateCookieOnResponse, createRequireAuthMiddleware, } from "./express";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,sBAAsB,EACtB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,GAC1B,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,QAAQ,EACb,eAAe,EACf,aAAa,EACb,aAAa,EACb,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,0BAA0B,EAC1B,0BAA0B,EAC1B,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,2BAA2B,EAC3B,yBAAyB,EACzB,+BAA+B,EAC/B,6BAA6B,EAC7B,uBAAuB,EACvB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,sBAAsB,EACtB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,UAAU,GAChB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,QAAQ,EACb,eAAe,EACf,aAAa,EACb,aAAa,EACb,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,0BAA0B,EAC1B,0BAA0B,EAC1B,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,2BAA2B,EAC3B,yBAAyB,EACzB,+BAA+B,EAC/B,6BAA6B,EAC7B,uBAAuB,EACvB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,wBAAwB,EAC7B,0BAA0B,EAC1B,4BAA4B,EAC5B,wBAAwB,EACxB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,WAAW,CAAC"}