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

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

@@ -123,6 +123,61 @@ 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;
+
+/**
+ * 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.
+ *
+ * @param options - Optional overrides for cookie attributes
+ *
+ * @public
+ */
+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
  */
@@ -151,6 +206,112 @@ 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;
+}
+
+/**
+ * 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.
+ *
+ * @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
  *
@@ -158,6 +319,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
  *
@@ -165,6 +350,62 @@ 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>);
+}
+
+/**
+ * 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
  *
@@ -219,6 +460,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.
  *
@@ -359,6 +627,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.
  *
@@ -434,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;
@@ -460,7 +737,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;
     /**
@@ -468,20 +745,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;
     /**
@@ -680,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;
     /**
@@ -746,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.
@@ -786,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.
      */
@@ -803,7 +1073,16 @@ export declare class Lixa<TConfig extends LixaConfig<Record<string, ProviderConf
      * 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;
 }
@@ -862,8 +1141,50 @@ 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;
+}
+
+/**
+ * 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
@@ -958,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>;
 } & ({
@@ -986,6 +1313,24 @@ 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.
  *
@@ -1048,6 +1393,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.
  *
@@ -1097,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
@@ -1112,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({
@@ -1131,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({
@@ -1157,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.
      *
@@ -1239,13 +1539,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>);
 }
 
 /**
@@ -1262,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>;
@@ -1290,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.
  *
@@ -1424,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.
      *
@@ -1473,6 +1807,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
  *