@vunexa/lixa 0.0.1-alpha.19 → 0.0.1-alpha.21

package/dist/lixa.d.ts

@@ -10,18 +10,18 @@ type ConfiguredProviderKey<T extends LixaConfig<any>> = keyof T['providers'];
  *
  * @remarks
  * Lixa simplifies multi-provider authentication flows and supports extensible session management.
+ * Providers can be passed inline in the configuration, eliminating the need for pre-registration.
  *
  * @example
+ * Using built-in providers from @vunexa/lixa-providers:
  * ```typescript
  * import { Lixa } from '@vunexa/lixa';
- * import { GoogleProvider } from '@vunexa/lixa/providers';
+ * import { GoogleProvider } from '@vunexa/lixa-providers';
  *
- * // Register providers before using them
- * Lixa.registerProvider({ google: new GoogleProvider() });
- *
- * const config = Lixa.createConfig({
+ * const lixa = new Lixa({
  *   providers: {
  *     google: {
+ *       provider: new GoogleProvider(),
  *       clientId: 'your-client-id',
  *       clientSecret: 'your-client-secret',
  *       redirectUri: 'https://yourapp.com/auth/google/callback',
@@ -29,13 +29,36 @@ type ConfiguredProviderKey<T extends LixaConfig<any>> = keyof T['providers'];
  *     }
  *   }
  * });
+ * ```
  *
- * const lixa = new Lixa(config);
+ * @example
+ * Using custom inline providers:
+ * ```typescript
+ * import { Lixa, IProvider } from '@vunexa/lixa';
+ *
+ * const customProvider: IProvider = {
+ *   authorizationEndpoint: 'https://custom.com/oauth/authorize',
+ *   tokenEndpoint: 'https://custom.com/oauth/token',
+ *   userInfoEndpoint: 'https://custom.com/api/user'
+ * };
+ *
+ * const lixa = new Lixa({
+ *   providers: {
+ *     custom: {
+ *       provider: customProvider,
+ *       clientId: 'your-client-id',
+ *       clientSecret: 'your-client-secret',
+ *       redirectUri: 'https://yourapp.com/auth/custom/callback',
+ *       scopes: ['read:user']
+ *     }
+ *   }
+ * });
  * ```
  *
  * @public
  */
 declare class Lixa<TConfig extends LixaConfig<any> = LixaConfig> {
+    private static DEFAULT_PROVIDERS;
     private static CONFIGURED_PROVIDERS;
     private static LOCAL_STATE_CACHE;
     private static LOCAL_SESSION_CACHE;
@@ -48,17 +71,52 @@ declare class Lixa<TConfig extends LixaConfig<any> = LixaConfig> {
     /**
      * Creates a new Lixa instance with the provided configuration.
      *
+     * @remarks
+     * Providers can be passed inline in the configuration using the `provider` field.
+     * Provider resolution priority: inline custom provider > default providers > legacy registry.
+     *
      * @param config - The configuration object containing provider settings and optional session strategy
+     *
+     * @throws Error when provider configuration is missing required fields
+     * @throws Error when provider implementation is missing required properties
+     * @throws Error when provider is not available and no inline implementation is provided
      */
     constructor(config: TConfig);
+    /**
+     * Validates that a provider configuration has all required credentials.
+     *
+     * @param name - The provider name
+     * @param config - The provider configuration
+     * @throws Error when required fields are missing or invalid
+     */
+    private validateProviderConfig;
+    /**
+     * Validates that a provider implementation has all required properties.
+     *
+     * @param name - The provider name
+     * @param provider - The provider implementation
+     * @throws Error when required properties are missing
+     */
+    private validateProviderImplementation;
+    /**
+     * Structured debug logging with standardized format.
+     *
+     * @param level - Log level (INFO, WARN, ERROR)
+     * @param context - Context of the log (Init, Auth, Token, Session, State)
+     * @param message - Log message
+     * @param data - Optional data to log
+     *
+     * @remarks
+     * Format: [Lixa] [timestamp] [level] [context] message
+     * Only logs when debug mode is enabled.
+     */
     private log;
-    private logError;
     /**
-     * Checks if a provider is both registered and configured for this instance.
+     * Checks if a provider is configured for this instance.
      * This is a type guard that narrows the provider type for use with getAuthUrl.
      *
      * @param provider - The provider name to check (case-insensitive)
-     * @returns True if the provider is registered and configured, false otherwise
+     * @returns True if the provider is configured, false otherwise
      *
      * @example
      * ```typescript
@@ -69,12 +127,37 @@ declare class Lixa<TConfig extends LixaConfig<any> = LixaConfig> {
      * ```
      */
     isProviderConfigured<T extends string>(provider: T): provider is T & ConfiguredProviderKey<TConfig>;
+    /**
+     * Gets a provider implementation by name.
+     * Resolution priority: inline custom provider > default providers > legacy registry
+     *
+     * @param name - The provider name (case-insensitive)
+     * @param config - The provider configuration
+     * @returns The provider implementation
+     * @throws Error when provider is not found
+     */
+    private getProvider;
     /**
      * Registers custom OAuth providers for use with Lixa.
      *
+     * @deprecated This method is maintained for backward compatibility.
+     * The recommended approach is to pass providers inline in the configuration:
+     * ```typescript
+     * const lixa = new Lixa({
+     *   providers: {
+     *     custom: {
+     *       provider: new CustomProvider(),
+     *       clientId: '...',
+     *       // ...
+     *     }
+     *   }
+     * });
+     * ```
+     *
      * @param providerMap - A map of provider names to IProvider implementations
      *
      * @example
+     * Legacy usage (still supported):
      * ```typescript
      * class CustomProvider implements IProvider {
      *   authorizationEndpoint = 'https://custom.com/oauth/authorize';
@@ -93,14 +176,31 @@ declare class Lixa<TConfig extends LixaConfig<any> = LixaConfig> {
      */
     static getRegisteredProviders(): string[];
     /**
-     * Creates a type-safe configuration that only allows registered providers.
+     * Creates a type-safe configuration.
+     *
+     * @deprecated This method is maintained for backward compatibility.
+     * You can now pass configuration directly to the Lixa constructor without this helper.
+     *
+     * @param config - Configuration object with provider settings
+     * @returns The same configuration object with type safety
      *
-     * @param config - Configuration object with providers that must be registered
-     * @returns The same configuration object, but with type safety for registered providers
+     * @example
+     * New approach (recommended):
+     * ```typescript
+     * const lixa = new Lixa({
+     *   providers: {
+     *     google: {
+     *       provider: new GoogleProvider(),
+     *       clientId: '...',
+     *       // ...
+     *     }
+     *   }
+     * });
+     * ```
      */
-    static createConfig<T extends Record<string, ProviderConfig>>(config: LixaConfig<keyof T & string> & {
+    static createConfig<T extends Record<string, ProviderConfig>>(config: LixaConfig<T> & {
         providers: T;
-    }): LixaConfig<keyof T & string>;
+    }): LixaConfig<T>;
     /**
      * Generates a cryptographically secure random state parameter for OAuth flows.
      *
@@ -113,12 +213,81 @@ declare class Lixa<TConfig extends LixaConfig<any> = LixaConfig> {
     /**
      * Generates a cryptographically secure code verifier for PKCE flows.
      *
-     * @returns A 64-character hexadecimal string
+     * @returns A 64-character hexadecimal string (32 random bytes encoded as hex)
      *
      * @remarks
-     * The code verifier is used in PKCE (Proof Key for Code Exchange) to enhance security.
+     * This method implements the code verifier generation as specified in RFC 7636 (PKCE).
+     *
+     * **PKCE (Proof Key for Code Exchange)** is a security extension to OAuth 2.0 that
+     * prevents authorization code interception attacks. It's especially important for
+     * public clients (mobile apps, SPAs) but is recommended for all OAuth flows.
+     *
+     * **Generation methodology:**
+     * 1. Generate 32 cryptographically random bytes using Node.js crypto.randomBytes()
+     * 2. Encode the bytes as a hexadecimal string (64 characters)
+     * 3. The verifier is stored securely and used later in the token exchange
+     *
+     * **RFC 7636 Requirements:**
+     * - Minimum length: 43 characters
+     * - Maximum length: 128 characters
+     * - Character set: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
+     * - This implementation produces 64 hex characters, meeting the requirements
+     *
+     * The code verifier is:
+     * - Generated when creating the authorization URL
+     * - Stored in state cache with the state parameter
+     * - Retrieved during callback handling
+     * - Sent to the token endpoint to prove the client's identity
+     *
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7636 | RFC 7636 - PKCE}
+     * @see {@link buildCodeChallenge} for the corresponding challenge generation
+     *
+     * @internal
      */
     private static generateCodeVerifier;
+    /**
+     * Generates a code challenge from a code verifier for PKCE flows.
+     *
+     * @param codeVerifier - The code verifier string (64 hex characters)
+     * @returns A base64url-encoded SHA-256 hash of the code verifier
+     *
+     * @remarks
+     * This method implements the code challenge generation as specified in RFC 7636 (PKCE)
+     * using the S256 (SHA-256) transformation method.
+     *
+     * **Challenge generation methodology:**
+     * 1. Hash the code verifier using SHA-256
+     * 2. Encode the hash as base64
+     * 3. Convert to base64url format (RFC 4648):
+     *    - Replace '+' with '-'
+     *    - Replace '/' with '_'
+     *    - Remove trailing '=' padding
+     *
+     * **PKCE Flow:**
+     * 1. Client generates code_verifier (random string)
+     * 2. Client creates code_challenge = BASE64URL(SHA256(code_verifier))
+     * 3. Client sends code_challenge to authorization endpoint
+     * 4. Authorization server stores the code_challenge
+     * 5. Client sends code_verifier to token endpoint
+     * 6. Authorization server verifies: SHA256(code_verifier) == code_challenge
+     *
+     * **Security Benefits:**
+     * - Prevents authorization code interception attacks
+     * - Even if an attacker intercepts the authorization code, they cannot
+     *   exchange it for tokens without the original code_verifier
+     * - The challenge is sent in the authorization request (public)
+     * - The verifier is sent in the token request (should be kept secret)
+     *
+     * **RFC 7636 Transformation Methods:**
+     * - plain: code_challenge = code_verifier (not recommended)
+     * - S256: code_challenge = BASE64URL(SHA256(code_verifier)) (recommended, used here)
+     *
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc7636 | RFC 7636 - PKCE}
+     * @see {@link https://datatracker.ietf.org/doc/html/rfc4648#section-5 | RFC 4648 - Base64url Encoding}
+     * @see {@link generateCodeVerifier} for the verifier generation
+     *
+     * @internal
+     */
     private static buildCodeChallenge;
     /**
      * Generates the authorization URL for the specified provider.

package/dist/lixa.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lixa.d.ts","sourceRoot":"","sources":["../src/lixa.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAKxC,OAAO,EAAE,KAAK,OAAO,EAAgD,MAAM,kBAAkB,CAAC;AAO9F;;GAEG;AACH,KAAK,qBAAqB,CAAC,CAAC,SAAS,UAAU,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,CAAC,WAAW,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,cAAM,IAAI,CAAC,OAAO,SAAS,UAAU,CAAC,GAAG,CAAC,GAAG,UAAU;IACrD,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAqC;IACxE,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAyB;IACzD,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAA2B;IAC7D,OAAO,CAAC,MAAM,CAAC,wBAAwB,CAAgC;IACvE,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,KAAK,CAAU;IAEvB;;;;OAIG;gBACS,MAAM,EAAE,OAAO;IAkB3B,OAAO,CAAC,GAAG;IAMX,OAAO,CAAC,QAAQ;IAMhB;;;;;;;;;;;;;;OAcG;IACI,oBAAoB,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,QAAQ,IAAI,CAAC,GAAG,qBAAqB,CAAC,OAAO,CAAC;IAM1G;;;;;;;;;;;;;;;OAeG;WACW,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,WAAW,EAAE,CAAC,GAAG,IAAI;IAMzF;;;;OAIG;WACW,sBAAsB,IAAI,MAAM,EAAE;IAIhD;;;;;OAKG;WACW,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EACjE,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG;QAAE,SAAS,EAAE,CAAC,CAAA;KAAE,GACtD,UAAU,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IAc/B;;;;;;;OAOG;WACW,mBAAmB,IAAI,MAAM;IAI3C;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAInC,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAUjC;;;;;;;;;;;;;;;OAeG;IACI,UAAU,CAAC,QAAQ,EAAE,qBAAqB,CAAC,OAAO,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;IAsC3F;;;;;;;;;;;;;;;;;;OAkBG;IACU,cAAc,CAAC,EAC1B,QAAQ,EACR,IAAI,EACJ,KAAK,GACN,EAAE;QACD,QAAQ,EAAE,qBAAqB,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC;QAClD,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,MAAM,CAAC;IAgDZ,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;YAIrD,oBAAoB;IA2ClC,OAAO,CAAC,kBAAkB;CAG3B;AAED,OAAO,EAAE,IAAI,EAAE,CAAC"}
+{"version":3,"file":"lixa.d.ts","sourceRoot":"","sources":["../src/lixa.ts"],"names":[],"mappings":"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"}

package/dist/models/session.d.ts

@@ -1,27 +1,130 @@
 /**
  * Represents a user session after successful OAuth authentication.
  *
+ * @remarks
+ * The Session object is returned by SessionStrategy.createSession() and contains
+ * the session identifier and any additional data needed for your application.
+ *
+ * The structure is intentionally flexible to support various session management
+ * approaches (JWT tokens, session IDs, etc.).
+ *
  * @public
  */
 export interface Session {
-    /** The session token (typically the access token) */
+    /**
+     * The session token or identifier.
+     * This could be an access token, a session ID, a JWT, or any other identifier
+     * that your application uses to track authenticated users.
+     */
     token: string;
-    /** Raw token data from the OAuth provider */
+    /**
+     * Raw session data.
+     * Contains the complete OAuth token response and any additional data
+     * your SessionStrategy adds (user info, database IDs, etc.).
+     *
+     * Typical OAuth token data includes:
+     * - access_token: OAuth access token
+     * - refresh_token: OAuth refresh token (if requested)
+     * - expires_in: Token expiration time in seconds
+     * - token_type: Token type (usually "Bearer")
+     * - id_token: OpenID Connect ID token (if using OIDC)
+     * - scope: Granted scopes
+     */
     raw: any;
 }
 /**
  * Strategy interface for custom session creation.
  *
+ * @remarks
+ * Implement this interface to customize how OAuth tokens are converted into
+ * application sessions. This is where you typically:
+ * - Decode ID tokens (for OpenID Connect)
+ * - Look up or create users in your database
+ * - Generate session identifiers
+ * - Store session data
+ * - Add custom claims or metadata
+ *
+ * The default implementation (DefaultSessionStrategy) simply extracts the
+ * access token and returns it as the session token.
+ *
+ * @example
+ * Custom session strategy with database integration:
+ * ```typescript
+ * class DatabaseSessionStrategy implements SessionStrategy {
+ *   constructor(private db: Database) {}
+ *
+ *   async createSession(tokenData: any): Promise<Session> {
+ *     // Decode ID token for OIDC providers
+ *     const idToken = tokenData.id_token;
+ *     const payload = decodeJwt(idToken);
+ *
+ *     // Create or update user in database
+ *     const user = await this.db.users.upsert({
+ *       email: payload.email,
+ *       name: payload.name,
+ *       picture: payload.picture
+ *     });
+ *
+ *     // Generate session ID
+ *     const sessionId = generateSecureId();
+ *
+ *     // Store session with tokens
+ *     await this.db.sessions.create({
+ *       id: sessionId,
+ *       userId: user.id,
+ *       accessToken: tokenData.access_token,
+ *       refreshToken: tokenData.refresh_token,
+ *       expiresAt: new Date(Date.now() + tokenData.expires_in * 1000)
+ *     });
+ *
+ *     return {
+ *       token: sessionId,
+ *       raw: {
+ *         userId: user.id,
+ *         email: user.email,
+ *         ...tokenData
+ *       }
+ *     };
+ *   }
+ * }
+ * ```
+ *
  * @public
  */
 export interface SessionStrategy {
     /**
      * Creates a session from OAuth token data.
      *
-     * @param userInfo - The token data received from the OAuth provider
+     * @param tokenData - The token data received from the OAuth provider's token endpoint
      * @returns A Promise that resolves to a Session object
+     *
+     * @remarks
+     * This method is called after successfully exchanging the authorization code
+     * for tokens. The tokenData parameter contains the raw response from the
+     * provider's token endpoint.
+     *
+     * Common token data fields:
+     * - 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
+     *
+     * @throws \{Error\} If session creation fails (e.g., database error, invalid token)
+     *
+     * @example
+     * Simple implementation:
+     * ```typescript
+     * async createSession(tokenData: any): Promise<Session> {
+     *   return {
+     *     token: tokenData.access_token,
+     *     raw: tokenData
+     *   };
+     * }
+     * ```
      */
-    createSession(userInfo: any): Promise<Session>;
+    createSession(tokenData: any): Promise<Session>;
 }
 /**
  * Default session strategy that works with any OAuth provider.

package/dist/models/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/models/session.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,GAAG,EAAE,GAAG,CAAC;CACV;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,aAAa,CAAC,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAChD;AAED;;;;;GAKG;AACH,qBAAa,sBAAuB,YAAW,eAAe;IAC5D;;;;;;OAMG;IACG,aAAa,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC;CAgBtD"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/models/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,OAAO;IACtB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;;;;;;;OAYG;IACH,GAAG,EAAE,GAAG,CAAC;CACV;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,aAAa,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjD;AAED;;;;;GAKG;AACH,qBAAa,sBAAuB,YAAW,eAAe;IAC5D;;;;;;OAMG;IACG,aAAa,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC;CAgBtD"}

package/dist/providers/IProvider.d.ts

@@ -1,17 +1,134 @@
 /**
- * Interface for OAuth provider implementations.
+ * Interface for OAuth 2.0 and OpenID Connect provider implementations.
  *
  * @remarks
  * Implement this interface to add support for custom OAuth providers.
+ * Each provider defines the three core endpoints required for the OAuth 2.0
+ * authorization code flow with PKCE.
+ *
+ * Built-in providers (Google, GitHub) are available in the \@vunexa/lixa-providers package.
+ *
+ * All implementations must comply with:
+ * - RFC 6749 (OAuth 2.0)
+ * - RFC 7636 (PKCE)
+ * - OpenID Connect Core 1.0 (for OIDC providers)
+ *
+ * @example
+ * Custom provider implementation:
+ * ```typescript
+ * import { IProvider } from '@vunexa/lixa';
+ *
+ * class CustomProvider implements IProvider {
+ *   authorizationEndpoint = 'https://auth.example.com/oauth/authorize';
+ *   tokenEndpoint = 'https://auth.example.com/oauth/token';
+ *   userInfoEndpoint = 'https://api.example.com/user';
+ * }
+ *
+ * // Use in configuration
+ * const lixa = new Lixa({
+ *   providers: {
+ *     custom: {
+ *       provider: new CustomProvider(),
+ *       clientId: 'your-client-id',
+ *       clientSecret: 'your-client-secret',
+ *       redirectUri: 'https://app.com/callback',
+ *       scopes: ['read:user']
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * Object literal provider:
+ * ```typescript
+ * const customProvider: IProvider = {
+ *   authorizationEndpoint: 'https://auth.example.com/oauth/authorize',
+ *   tokenEndpoint: 'https://auth.example.com/oauth/token',
+ *   userInfoEndpoint: 'https://api.example.com/user'
+ * };
+ * ```
  *
  * @public
  */
 interface IProvider {
-    /** The OAuth authorization endpoint URL */
+    /**
+     * The OAuth 2.0 authorization endpoint URL.
+     *
+     * @remarks
+     * This is the URL where users are redirected to authenticate and authorize your application.
+     * The endpoint must support the OAuth 2.0 authorization code flow with PKCE.
+     *
+     * Standard query parameters sent to this endpoint:
+     * - client_id: Your application's client ID
+     * - redirect_uri: Where to redirect after authorization
+     * - response_type: Always "code" for authorization code flow
+     * - scope: Space-separated list of requested scopes
+     * - state: Random string for CSRF protection
+     * - code_challenge: PKCE code challenge (SHA-256 hash)
+     * - code_challenge_method: Always "S256" for SHA-256
+     *
+     * @example
+     * ```typescript
+     * authorizationEndpoint = 'https://accounts.google.com/o/oauth2/v2/auth'
+     * ```
+     */
     authorizationEndpoint: string;
-    /** The OAuth token exchange endpoint URL */
+    /**
+     * The OAuth 2.0 token endpoint URL.
+     *
+     * @remarks
+     * This is the URL where authorization codes are exchanged for access tokens.
+     * The endpoint must support the OAuth 2.0 token exchange with PKCE.
+     *
+     * Standard parameters sent to this endpoint (POST request):
+     * - grant_type: Always "authorization_code"
+     * - code: The authorization code from the callback
+     * - redirect_uri: Must match the authorization request
+     * - client_id: Your application's client ID
+     * - client_secret: Your application's client secret
+     * - code_verifier: PKCE code verifier (original random string)
+     *
+     * Expected response:
+     * - access_token: OAuth access token
+     * - token_type: Token type (usually "Bearer")
+     * - expires_in: Token expiration time in seconds
+     * - refresh_token: Refresh token (optional)
+     * - id_token: OpenID Connect ID token (for OIDC providers)
+     * - scope: Granted scopes
+     *
+     * @example
+     * ```typescript
+     * tokenEndpoint = 'https://oauth2.googleapis.com/token'
+     * ```
+     */
     tokenEndpoint: string;
-    /** The user information endpoint URL */
+    /**
+     * The user information endpoint URL.
+     *
+     * @remarks
+     * This is the URL where user profile information can be retrieved using the access token.
+     * For OpenID Connect providers, this is the UserInfo endpoint.
+     *
+     * The endpoint is called with the access token in the Authorization header:
+     * ```
+     * Authorization: Bearer <access_token>
+     * ```
+     *
+     * Common response fields:
+     * - sub: Subject identifier (user ID)
+     * - email: User's email address
+     * - name: User's full name
+     * - picture: User's profile picture URL
+     * - email_verified: Whether email is verified
+     *
+     * Note: This endpoint is not called automatically by Lixa. Your SessionStrategy
+     * can call it if needed to fetch user profile information.
+     *
+     * @example
+     * ```typescript
+     * userInfoEndpoint = 'https://www.googleapis.com/oauth2/v2/userinfo'
+     * ```
+     */
     userInfoEndpoint: string;
 }
 export { IProvider };

package/dist/providers/IProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IProvider.d.ts","sourceRoot":"","sources":["../../src/providers/IProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,UAAU,SAAS;IACjB,2CAA2C;IAC3C,qBAAqB,EAAE,MAAM,CAAC;IAC9B,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"IProvider.d.ts","sourceRoot":"","sources":["../../src/providers/IProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,UAAU,SAAS;IACjB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,qBAAqB,EAAE,MAAM,CAAC;IAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/providers/index.d.ts

@@ -1,4 +1,2 @@
 export { IProvider } from "./IProvider";
-export { GithubProvider } from "./github";
-export { GoogleProvider } from "./google";
 //# sourceMappingURL=index.d.ts.map

package/dist/providers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}