@vunexa/lixa 0.0.1-alpha.3 → 0.0.1-alpha.5

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

@@ -0,0 +1,10 @@
+import { StateDao } from "./types";
+declare class LocalStateCache implements StateDao {
+    private cache;
+    constructor(defaultTtlSeconds?: number);
+    saveState(state: string, data: any, expiresInSeconds: number): Promise<void>;
+    getState(state: string): Promise<any | null>;
+    deleteState(state: string): Promise<void>;
+}
+export { LocalStateCache };
+//# sourceMappingURL=state-cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state-cache.d.ts","sourceRoot":"","sources":["../../src/dao/state-cache.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,cAAM,eAAgB,YAAW,QAAQ;IACvC,OAAO,CAAC,KAAK,CAAY;gBAEb,iBAAiB,GAAE,MAAY;IAIrC,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAI5C,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGhD;AAED,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/dao/state-cache.js

@@ -0,0 +1,18 @@
+import NodeCache from 'node-cache';
+class LocalStateCache {
+    cache;
+    constructor(defaultTtlSeconds = 600) {
+        this.cache = new NodeCache({ stdTTL: defaultTtlSeconds });
+    }
+    async saveState(state, data, expiresInSeconds) {
+        this.cache.set(state, data, expiresInSeconds);
+    }
+    async getState(state) {
+        return this.cache.get(state) || null;
+    }
+    async deleteState(state) {
+        this.cache.del(state);
+    }
+}
+export { LocalStateCache };
+//# sourceMappingURL=state-cache.js.map

package/dist/dao/state-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-cache.js","sourceRoot":"","sources":["../../src/dao/state-cache.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AAGnC,MAAM,eAAe;IACX,KAAK,CAAY;IAEzB,YAAY,oBAA4B,GAAG;QACzC,IAAI,CAAC,KAAK,GAAG,IAAI,SAAS,CAAC,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,KAAa,EAAE,IAAS,EAAE,gBAAwB;QAChE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,gBAAgB,CAAC,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;IACvC,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,KAAa;QAC7B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACxB,CAAC;CACF;AAED,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/dao/types.d.ts

@@ -0,0 +1,6 @@
+export interface StateDao {
+    saveState(state: string, data: any, expiresInSeconds: number): Promise<void>;
+    getState(state: string): Promise<any | null>;
+    deleteState(state: string): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/dao/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;IAC7C,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C"}

package/dist/dao/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/dao/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/dao/types.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -1,3 +1,12 @@
+/**
+ * A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library for backend applications.
+ *
+ * @remarks
+ * This package simplifies multi-provider authentication flows (e.g., Google, GitHub), supports extensible session management, and enables custom provider registration.
+ *
+ * @packageDocumentation
+ */
 export { Lixa } from "./lixa";
 export { type ProviderConfig, type LixaConfig, type SessionStrategy, type Session, } from "./types";
+export { type IProvider } from "./providers";
 //# 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,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,OAAO,GACb,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,OAAO,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,2 +1,10 @@
+/**
+ * A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library for backend applications.
+ *
+ * @remarks
+ * This package simplifies multi-provider authentication flows (e.g., Google, GitHub), supports extensible session management, and enables custom provider registration.
+ *
+ * @packageDocumentation
+ */
 export { Lixa } from "./lixa";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC"}

package/dist/lixa.d.ts

@@ -1,18 +1,116 @@
 import { type LixaConfig, type Session } from "./types";
 import { IProvider } from "./providers";
 /**
+ * A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library.
+ *
+ * @remarks
+ * Lixa simplifies multi-provider authentication flows and supports extensible session management.
+ *
+ * @example
+ * ```typescript
+ * const lixa = new Lixa({
+ *   providers: {
+ *     google: {
+ *       clientId: 'your-client-id',
+ *       clientSecret: 'your-client-secret',
+ *       redirectUri: 'https://yourapp.com/auth/google/callback',
+ *       scopes: ['openid', 'email', 'profile']
+ *     }
+ *   }
+ * });
+ * ```
+ *
  * @public
  */
 declare class Lixa {
     private static CONFIGURED_PROVIDERS;
+    private static LOCAL_STATE_CACHE;
     private config;
+    private stateDao;
+    /**
+     * Creates a new Lixa instance with the provided configuration.
+     *
+     * @param config - The configuration object containing provider settings and optional session strategy
+     */
     constructor(config: LixaConfig);
+    /**
+     * Checks if a provider is registered and available for use.
+     *
+     * @param provider - The provider name to check (case-insensitive)
+     * @returns True if the provider is registered, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (Lixa.isProviderRegistered('google')) {
+     *   console.log('Google provider is available');
+     * }
+     * ```
+     */
     static isProviderRegistered(provider: string): boolean;
+    /**
+     * Registers custom OAuth providers for use with Lixa.
+     *
+     * @param providerMap - A map of provider names to IProvider implementations
+     *
+     * @example
+     * ```typescript
+     * class CustomProvider implements IProvider {
+     *   authorizationEndpoint = 'https://custom.com/oauth/authorize';
+     *   tokenEndpoint = 'https://custom.com/oauth/token';
+     *   userInfoEndpoint = 'https://custom.com/api/user';
+     * }
+     *
+     * Lixa.registerProvider({ custom: new CustomProvider() });
+     * ```
+     */
     static registerProvider(providerMap: {
         [key: string]: IProvider;
     }): void;
-    generateRandomState(): string;
+    /**
+     * Generates a cryptographically secure random state parameter for OAuth flows.
+     *
+     * @returns A 32-character hexadecimal string
+     *
+     * @remarks
+     * The state parameter is used to prevent CSRF attacks in OAuth flows.
+     */
+    static generateRandomState(): string;
+    /**
+     * Generates the authorization URL for the specified provider.
+     *
+     * @param provider - The provider name (case-insensitive)
+     * @param state - The state parameter for CSRF protection
+     * @returns The complete authorization URL to redirect users to
+     *
+     * @throws Error when the provider is not configured
+     *
+     * @example
+     * ```typescript
+     * const state = Lixa.generateRandomState();
+     * const authUrl = lixa.getAuthUrl('google', state);
+     * res.redirect(authUrl);
+     * ```
+     */
     getAuthUrl(provider: string, state: string): string;
+    /**
+     * Handles the OAuth callback and creates a user session.
+     *
+     * @param provider - The provider name
+     * @param code - The authorization code from the provider
+     * @param state - The state parameter for validation
+     * @returns A Promise that resolves to a Session object
+     *
+     * @throws Error when code or state is missing/invalid, or provider is not configured
+     *
+     * @example
+     * ```typescript
+     * const session = await lixa.handleCallback({
+     *   provider: 'google',
+     *   code: req.query.code,
+     *   state: req.query.state
+     * });
+     * ```
+     */
     handleCallback({ provider, code, state, }: {
         provider: string;
         code: string;

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,EAAuB,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAkC,MAAM,aAAa,CAAC;AAGxE;;GAEG;AACH,cAAM,IAAI;IACR,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAqC;IACxE,OAAO,CAAC,MAAM,CAAa;gBAEf,MAAM,EAAE,UAAU;WAUhB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;WAI/C,gBAAgB,CAAC,WAAW,EAAE;QAC1C,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;KAC1B,GAAG,IAAI;IAQD,mBAAmB,IAAI,MAAM;IAI7B,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;IAqB7C,cAAc,CAAC,EAC1B,QAAQ,EACR,IAAI,EACJ,KAAK,GACN,EAAE;QACD,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,OAAO,CAAC;YAuCN,oBAAoB;IAsClC,OAAO,CAAC,kBAAkB;CAG3B;AAED,OAAO,EAAE,IAAI,EAAE,CAAC"}
+{"version":3,"file":"lixa.d.ts","sourceRoot":"","sources":["../src/lixa.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,UAAU,EAAuB,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAkC,MAAM,aAAa,CAAC;AAKxE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,cAAM,IAAI;IACR,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAqC;IACxE,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAyB;IACzD,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,QAAQ,CAAW;IAE3B;;;;OAIG;gBACS,MAAM,EAAE,UAAU;IAW9B;;;;;;;;;;;;OAYG;WACW,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAI7D;;;;;;;;;;;;;;;OAeG;WACW,gBAAgB,CAAC,WAAW,EAAE;QAC1C,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;KAC1B,GAAG,IAAI;IAQR;;;;;;;OAOG;WACW,mBAAmB,IAAI,MAAM;IAI3C;;;;;;;;;;;;;;;OAeG;IACI,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;IA6B1D;;;;;;;;;;;;;;;;;;OAkBG;IACU,cAAc,CAAC,EAC1B,QAAQ,EACR,IAAI,EACJ,KAAK,GACN,EAAE;QACD,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,OAAO,CAAC;YA+CN,oBAAoB;IAsClC,OAAO,CAAC,kBAAkB;CAG3B;AAED,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/dist/lixa.js

@@ -1,14 +1,42 @@
 import { randomBytes } from "crypto";
 import { GithubProvider, GoogleProvider } from "./providers";
 import { GITHUB, GOOGLE } from "./utils/constants";
+import { LocalStateCache } from "./dao/state-cache";
 /**
+ * A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library.
+ *
+ * @remarks
+ * Lixa simplifies multi-provider authentication flows and supports extensible session management.
+ *
+ * @example
+ * ```typescript
+ * const lixa = new Lixa({
+ *   providers: {
+ *     google: {
+ *       clientId: 'your-client-id',
+ *       clientSecret: 'your-client-secret',
+ *       redirectUri: 'https://yourapp.com/auth/google/callback',
+ *       scopes: ['openid', 'email', 'profile']
+ *     }
+ *   }
+ * });
+ * ```
+ *
  * @public
  */
 class Lixa {
     static CONFIGURED_PROVIDERS = new Map();
+    static LOCAL_STATE_CACHE = new LocalStateCache();
     config;
+    stateDao;
+    /**
+     * Creates a new Lixa instance with the provided configuration.
+     *
+     * @param config - The configuration object containing provider settings and optional session strategy
+     */
     constructor(config) {
         this.config = config;
+        this.stateDao = config.stateDao || Lixa.LOCAL_STATE_CACHE;
         if (!Lixa.CONFIGURED_PROVIDERS.has(GITHUB)) {
             Lixa.CONFIGURED_PROVIDERS.set(GITHUB, new GithubProvider());
         }
@@ -16,9 +44,38 @@ class Lixa {
             Lixa.CONFIGURED_PROVIDERS.set(GOOGLE, new GoogleProvider());
         }
     }
+    /**
+     * Checks if a provider is registered and available for use.
+     *
+     * @param provider - The provider name to check (case-insensitive)
+     * @returns True if the provider is registered, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (Lixa.isProviderRegistered('google')) {
+     *   console.log('Google provider is available');
+     * }
+     * ```
+     */
     static isProviderRegistered(provider) {
         return Lixa.CONFIGURED_PROVIDERS.has(provider.toLowerCase());
     }
+    /**
+     * Registers custom OAuth providers for use with Lixa.
+     *
+     * @param providerMap - A map of provider names to IProvider implementations
+     *
+     * @example
+     * ```typescript
+     * class CustomProvider implements IProvider {
+     *   authorizationEndpoint = 'https://custom.com/oauth/authorize';
+     *   tokenEndpoint = 'https://custom.com/oauth/token';
+     *   userInfoEndpoint = 'https://custom.com/api/user';
+     * }
+     *
+     * Lixa.registerProvider({ custom: new CustomProvider() });
+     * ```
+     */
     static registerProvider(providerMap) {
         // This is a static method, so we can't access instance properties.
         // Instead, we can modify the prototype to add the new provider.
@@ -26,9 +83,33 @@ class Lixa {
             Lixa.CONFIGURED_PROVIDERS.set(key, providerImpl);
         });
     }
-    generateRandomState() {
+    /**
+     * Generates a cryptographically secure random state parameter for OAuth flows.
+     *
+     * @returns A 32-character hexadecimal string
+     *
+     * @remarks
+     * The state parameter is used to prevent CSRF attacks in OAuth flows.
+     */
+    static generateRandomState() {
         return randomBytes(16).toString("hex");
     }
+    /**
+     * Generates the authorization URL for the specified provider.
+     *
+     * @param provider - The provider name (case-insensitive)
+     * @param state - The state parameter for CSRF protection
+     * @returns The complete authorization URL to redirect users to
+     *
+     * @throws Error when the provider is not configured
+     *
+     * @example
+     * ```typescript
+     * const state = Lixa.generateRandomState();
+     * const authUrl = lixa.getAuthUrl('google', state);
+     * res.redirect(authUrl);
+     * ```
+     */
     getAuthUrl(provider, state) {
         const providerType = provider.toLowerCase();
         const providerConfig = this.findProviderByType(providerType);
@@ -36,6 +117,10 @@ class Lixa {
         if (!providerConfig || !providerImpl) {
             throw new Error(`Provider ${providerType} not configured`);
         }
+        // Cache the state paramaeter with TTL of 5 minutes (300 seconds)
+        // We dont care about value. we are onl interested in key existence
+        this.stateDao.saveState(state, state, 300 // 5 minutes in seconds
+        );
         const params = new URLSearchParams({
             client_id: providerConfig.clientId,
             redirect_uri: providerConfig.redirectUri,
@@ -46,6 +131,25 @@ class Lixa {
         });
         return `${providerImpl.authorizationEndpoint}?${params.toString()}`;
     }
+    /**
+     * Handles the OAuth callback and creates a user session.
+     *
+     * @param provider - The provider name
+     * @param code - The authorization code from the provider
+     * @param state - The state parameter for validation
+     * @returns A Promise that resolves to a Session object
+     *
+     * @throws Error when code or state is missing/invalid, or provider is not configured
+     *
+     * @example
+     * ```typescript
+     * const session = await lixa.handleCallback({
+     *   provider: 'google',
+     *   code: req.query.code,
+     *   state: req.query.state
+     * });
+     * ```
+     */
     async handleCallback({ provider, code, state, }) {
         if (!code || code.trim() === "") {
             throw new Error("Invalid or missing code in callback");
@@ -53,9 +157,16 @@ class Lixa {
         if (!state || state.trim() === "") {
             throw new Error("Invalid or missing state in callback");
         }
-        //TODO: Validate state here
-        const providerConfig = this.findProviderByType(provider.toLowerCase());
-        const providerImpl = Lixa.CONFIGURED_PROVIDERS.get(provider);
+        //Validate state here
+        const cachedState = await this.stateDao.getState(state);
+        if (!cachedState) {
+            throw new Error("Invalid or expired state");
+        }
+        // State is valid, remove it from cache to prevent reuse
+        await this.stateDao.deleteState(state);
+        const providerType = provider.toLowerCase();
+        const providerConfig = this.findProviderByType(providerType);
+        const providerImpl = Lixa.CONFIGURED_PROVIDERS.get(providerType);
         if (!providerConfig || !providerImpl) {
             throw new Error(`Provider ${provider} not configured`);
         }

package/dist/lixa.js.map

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

package/dist/providers/IProvider.d.ts

@@ -1,6 +1,17 @@
+/**
+ * Interface for OAuth provider implementations.
+ *
+ * @remarks
+ * Implement this interface to add support for custom OAuth providers.
+ *
+ * @public
+ */
 interface IProvider {
+    /** The OAuth authorization endpoint URL */
     authorizationEndpoint: string;
+    /** The OAuth token exchange endpoint URL */
     tokenEndpoint: string;
+    /** The user information endpoint URL */
     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":"AAEA,UAAU,SAAS;IACjB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,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;;;;;;;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"}

package/dist/providers/IProvider.js

@@ -1,3 +1,2 @@
-// Implement an extandable interface for authentication providers
 export {};
 //# sourceMappingURL=IProvider.js.map

package/dist/providers/IProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"IProvider.js","sourceRoot":"","sources":["../../src/providers/IProvider.ts"],"names":[],"mappings":"AAAA,iEAAiE"}
+{"version":3,"file":"IProvider.js","sourceRoot":"","sources":["../../src/providers/IProvider.ts"],"names":[],"mappings":""}

package/dist/types.d.ts

@@ -1,31 +1,57 @@
+import { StateDao } from "./dao/types";
 /**
+ * Configuration for an OAuth provider.
+ *
  * @public
  */
 export interface ProviderConfig {
+    /** The OAuth client ID provided by the provider */
     clientId: string;
+    /** The OAuth client secret provided by the provider */
     clientSecret: string;
+    /** The redirect URI registered with the provider */
     redirectUri: string;
+    /** Array of OAuth scopes to request */
     scopes: string[];
+    /** Additional provider-specific configuration parameters */
     extraConfig?: Record<string, any>;
 }
 /**
+ * Main configuration object for Lixa.
+ *
  * @public
  */
 export interface LixaConfig {
+    /** Map of provider names to their configurations */
     providers: Record<string, ProviderConfig>;
+    /** Optional custom session creation strategy */
     sessionStrategy?: SessionStrategy;
+    /** Optional custom state storage implementation */
+    stateDao?: StateDao;
 }
 /**
+ * Strategy interface for custom session creation.
+ *
  * @public
  */
 export interface SessionStrategy {
+    /**
+     * Creates a session from OAuth token data.
+     *
+     * @param userInfo - The token data received from the OAuth provider
+     * @returns A Promise that resolves to a Session object
+     */
     createSession(userInfo: any): Promise<Session>;
 }
 /**
+ * Represents a user session after successful OAuth authentication.
+ *
  * @public
  */
 export interface Session {
+    /** The session token (typically the access token) */
     token: string;
+    /** Raw token data from the OAuth provider */
     raw: any;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,aAAa,CAAC,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAChD;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,GAAG,CAAC;CACV"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C,gDAAgD;IAChD,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,mDAAmD;IACnD,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,aAAa,CAAC,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAChD;AAED;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,GAAG,EAAE,GAAG,CAAC;CACV"}

package/index.d.ts

@@ -1,22 +1,140 @@
-declare interface IProvider {
+/**
+ * A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library for backend applications.
+ *
+ * @remarks
+ * This package simplifies multi-provider authentication flows (e.g., Google, GitHub), supports extensible session management, and enables custom provider registration.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Interface for OAuth provider implementations.
+ *
+ * @remarks
+ * Implement this interface to add support for custom OAuth providers.
+ *
+ * @public
+ */
+export declare interface IProvider {
+    /** The OAuth authorization endpoint URL */
     authorizationEndpoint: string;
+    /** The OAuth token exchange endpoint URL */
     tokenEndpoint: string;
+    /** The user information endpoint URL */
     userInfoEndpoint: string;
 }
 
 /**
+ * A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library.
+ *
+ * @remarks
+ * Lixa simplifies multi-provider authentication flows and supports extensible session management.
+ *
+ * @example
+ * ```typescript
+ * const lixa = new Lixa({
+ *   providers: {
+ *     google: {
+ *       clientId: 'your-client-id',
+ *       clientSecret: 'your-client-secret',
+ *       redirectUri: 'https://yourapp.com/auth/google/callback',
+ *       scopes: ['openid', 'email', 'profile']
+ *     }
+ *   }
+ * });
+ * ```
+ *
  * @public
  */
 export declare class Lixa {
     private static CONFIGURED_PROVIDERS;
+    private static LOCAL_STATE_CACHE;
     private config;
+    private stateDao;
+    /**
+     * Creates a new Lixa instance with the provided configuration.
+     *
+     * @param config - The configuration object containing provider settings and optional session strategy
+     */
     constructor(config: LixaConfig);
+    /**
+     * Checks if a provider is registered and available for use.
+     *
+     * @param provider - The provider name to check (case-insensitive)
+     * @returns True if the provider is registered, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (Lixa.isProviderRegistered('google')) {
+     *   console.log('Google provider is available');
+     * }
+     * ```
+     */
     static isProviderRegistered(provider: string): boolean;
+    /**
+     * Registers custom OAuth providers for use with Lixa.
+     *
+     * @param providerMap - A map of provider names to IProvider implementations
+     *
+     * @example
+     * ```typescript
+     * class CustomProvider implements IProvider {
+     *   authorizationEndpoint = 'https://custom.com/oauth/authorize';
+     *   tokenEndpoint = 'https://custom.com/oauth/token';
+     *   userInfoEndpoint = 'https://custom.com/api/user';
+     * }
+     *
+     * Lixa.registerProvider({ custom: new CustomProvider() });
+     * ```
+     */
     static registerProvider(providerMap: {
         [key: string]: IProvider;
     }): void;
-    generateRandomState(): string;
+    /**
+     * Generates a cryptographically secure random state parameter for OAuth flows.
+     *
+     * @returns A 32-character hexadecimal string
+     *
+     * @remarks
+     * The state parameter is used to prevent CSRF attacks in OAuth flows.
+     */
+    static generateRandomState(): string;
+    /**
+     * Generates the authorization URL for the specified provider.
+     *
+     * @param provider - The provider name (case-insensitive)
+     * @param state - The state parameter for CSRF protection
+     * @returns The complete authorization URL to redirect users to
+     *
+     * @throws Error when the provider is not configured
+     *
+     * @example
+     * ```typescript
+     * const state = Lixa.generateRandomState();
+     * const authUrl = lixa.getAuthUrl('google', state);
+     * res.redirect(authUrl);
+     * ```
+     */
     getAuthUrl(provider: string, state: string): string;
+    /**
+     * Handles the OAuth callback and creates a user session.
+     *
+     * @param provider - The provider name
+     * @param code - The authorization code from the provider
+     * @param state - The state parameter for validation
+     * @returns A Promise that resolves to a Session object
+     *
+     * @throws Error when code or state is missing/invalid, or provider is not configured
+     *
+     * @example
+     * ```typescript
+     * const session = await lixa.handleCallback({
+     *   provider: 'google',
+     *   code: req.query.code,
+     *   state: req.query.state
+     * });
+     * ```
+     */
     handleCallback({ provider, code, state, }: {
         provider: string;
         code: string;
@@ -27,37 +145,68 @@ export declare class Lixa {
 }
 
 /**
+ * Main configuration object for Lixa.
+ *
  * @public
  */
 export declare interface LixaConfig {
+    /** Map of provider names to their configurations */
     providers: Record<string, ProviderConfig>;
+    /** Optional custom session creation strategy */
     sessionStrategy?: SessionStrategy;
+    /** Optional custom state storage implementation */
+    stateDao?: StateDao;
 }
 
 /**
+ * Configuration for an OAuth provider.
+ *
  * @public
  */
 export declare interface ProviderConfig {
+    /** The OAuth client ID provided by the provider */
     clientId: string;
+    /** The OAuth client secret provided by the provider */
     clientSecret: string;
+    /** The redirect URI registered with the provider */
     redirectUri: string;
+    /** Array of OAuth scopes to request */
     scopes: string[];
+    /** Additional provider-specific configuration parameters */
     extraConfig?: Record<string, any>;
 }
 
 /**
+ * Represents a user session after successful OAuth authentication.
+ *
  * @public
  */
 export declare interface Session {
+    /** The session token (typically the access token) */
     token: string;
+    /** Raw token data from the OAuth provider */
     raw: any;
 }
 
 /**
+ * Strategy interface for custom session creation.
+ *
  * @public
  */
 export declare interface SessionStrategy {
+    /**
+     * Creates a session from OAuth token data.
+     *
+     * @param userInfo - The token data received from the OAuth provider
+     * @returns A Promise that resolves to a Session object
+     */
     createSession(userInfo: any): Promise<Session>;
 }
 
+declare interface StateDao {
+    saveState(state: string, data: any, expiresInSeconds: number): Promise<void>;
+    getState(state: string): Promise<any | null>;
+    deleteState(state: string): Promise<void>;
+}
+
 export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vunexa/lixa",
-  "version": "0.0.1-alpha.3",
+  "version": "0.0.1-alpha.5",
   "description": "Lixa is a flexible, provider-agnostic OAuth and OpenID Connect (OIDC) client library that simplifies multi-provider authentication flows. It supports seamless integration with providers like Google and GitHub, offers extensible session management, and enables dynamic provider resolution based on callback URLs.",
   "keywords": [
     "oauth",
@@ -27,6 +27,7 @@
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
     "api-extractor": "api-extractor run --local --verbose",
+    "docs:api": "npm run build && api-documenter markdown --input temp --output docs/api",
     "publish:alpha": "npm run build && npm version prerelease --preid=alpha && npm publish --tag alpha",
     "publish:beta": "npm run build && npm version prerelease --preid=beta && npm publish --tag beta",
     "publish:stable": "npm run build && npm version patch && npm publish --tag latest"
@@ -42,6 +43,7 @@
     "@microsoft/api-extractor": "^7.52.11",
     "@types/jest": "^29.5.12",
     "@types/node": "^24.3.1",
+    "@types/node-cache": "^4.1.3",
     "@typescript-eslint/eslint-plugin": "^8.42.0",
     "@typescript-eslint/parser": "^8.42.0",
     "eslint": "^9.35.0",
@@ -49,5 +51,8 @@
     "jest": "^29.7.0",
     "ts-jest": "^29.1.2",
     "typescript": "^5.9.2"
+  },
+  "dependencies": {
+    "node-cache": "^5.1.2"
   }
 }