@vunexa/lixa 0.0.1-alpha.10

package/index.d.ts

@@ -0,0 +1,261 @@
+/**
+ * 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
+ */
+
+/**
+ * Type representing the keys of configured providers
+ */
+declare type ConfiguredProviderKey<T extends LixaConfig<any>> = keyof T['providers'];
+
+/**
+ * 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
+ * import { Lixa } from '@vunexa/lixa';
+ * import { GoogleProvider } from '@vunexa/lixa/providers';
+ *
+ * // Register providers before using them
+ * Lixa.registerProvider({ google: new GoogleProvider() });
+ *
+ * const config = Lixa.createConfig({
+ *   providers: {
+ *     google: {
+ *       clientId: 'your-client-id',
+ *       clientSecret: 'your-client-secret',
+ *       redirectUri: 'https://yourapp.com/auth/google/callback',
+ *       scopes: ['openid', 'email', 'profile']
+ *     }
+ *   }
+ * });
+ *
+ * const lixa = new Lixa(config);
+ * ```
+ *
+ * @public
+ */
+export declare class Lixa<TConfig extends LixaConfig<any> = LixaConfig> {
+    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: TConfig);
+    /**
+     * Checks if a provider is both registered and 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
+     *
+     * @example
+     * ```typescript
+     * if (lixa.isProviderConfigured(provider)) {
+     *   // TypeScript now knows provider is a valid ConfiguredProviderKey
+     *   const authUrl = lixa.getAuthUrl(provider, state);
+     * }
+     * ```
+     */
+    isProviderConfigured<T extends string>(provider: T): provider is T & ConfiguredProviderKey<TConfig>;
+    /**
+     * 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<T extends Record<string, IProvider>>(providerMap: T): void;
+    /**
+     * Gets the list of registered provider names.
+     *
+     * @returns Array of registered provider names
+     */
+    static getRegisteredProviders(): string[];
+    /**
+     * Creates a type-safe configuration that only allows registered providers.
+     *
+     * @param config - Configuration object with providers that must be registered
+     * @returns The same configuration object, but with type safety for registered providers
+     */
+    static createConfig<T extends Record<string, ProviderConfig>>(config: LixaConfig<keyof T & string> & {
+        providers: T;
+    }): LixaConfig<keyof T & 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 a cryptographically secure code verifier for PKCE flows.
+     *
+     * @returns A 64-character hexadecimal string
+     *
+     * @remarks
+     * The code verifier is used in PKCE (Proof Key for Code Exchange) to enhance security.
+     */
+    private static generateCodeVerifier;
+    private static buildCodeChallenge;
+    /**
+     * Generates the authorization URL for the specified provider.
+     *
+     * @param provider - The provider name (must be a configured provider key)
+     * @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: ConfiguredProviderKey<TConfig> | string, state: string): string;
+    /**
+     * Handles the OAuth callback and creates a user session.
+     *
+     * @param provider - The provider name (must be a configured provider key)
+     * @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: ConfiguredProviderKey<TConfig> | string;
+        code: string;
+        state?: string;
+    }): Promise<Session>;
+    private exchangeCodeForToken;
+    private findProviderByType;
+}
+
+/**
+ * Main configuration object for Lixa.
+ * Only allows providers that have been registered through registerProvider.
+ *
+ * @public
+ */
+export declare interface LixaConfig<TRegisteredProviders extends string = string> {
+    /** Map of registered provider names to their configurations */
+    providers: Record<TRegisteredProviders, 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>;
+}
+
+/**
+ * Helper type to create a configuration with only registered providers.
+ * Use this with Lixa.createConfig() for type safety.
+ *
+ * @public
+ */
+export declare type SafeLixaConfig<TProviders extends Record<string, ProviderConfig>> = LixaConfig<keyof TProviders & string> & {
+    providers: TProviders;
+};
+
+/**
+ * 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

@@ -0,0 +1,63 @@
+{
+  "name": "@vunexa/lixa",
+  "version": "0.0.1-alpha.10",
+  "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",
+    "oidc"
+  ],
+  "license": "MIT",
+  "author": "vamsi",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./providers": {
+      "types": "./providers.d.ts",
+      "import": "./dist/providers.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc && npm run test && api-extractor run --local",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "test": "jest",
+    "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"
+  },
+  "files": [
+    "dist",
+    "index.d.ts",
+    "providers.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@eslint/js": "^9.35.0",
+    "@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",
+    "globals": "^16.3.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.9.2"
+  },
+  "dependencies": {
+    "node-cache": "^5.1.2"
+  }
+}