@vunexa/lixa 0.0.1-alpha.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] [@vunexa/lixa]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,240 @@
+# @vunexa/lixa
+
+> Package is in very early stage and can have frequent breaking changes. DO NOT USE it for production
+
+[![npm version](https://img.shields.io/npm/v/@vunexa/lixa.svg)](https://www.npmjs.com/package/@vunexa/lixa)
+[![npm downloads](https://img.shields.io/npm/dm/@vunexa/lixa.svg)](https://www.npmjs.com/package/@vunexa/lixa)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library for backend applications.  
+@vunexa/lixa simplifies multi-provider authentication flows (e.g., Google, GitHub), supports extensible session management, and enables custom provider registration.
+
+---
+
+## Features
+
+- Multi-provider OAuth/OIDC support with unified API
+- Built-in support for popular providers like Google and GitHub
+- Custom provider registration with extensible provider interface
+- Extensible session management via pluggable strategies
+- PKCE (Proof Key for Code Exchange) support
+- TypeScript-first with strong typing and async/await support
+- 100% test coverage with comprehensive error handling
+
+---
+
+## Installation
+
+```bash
+npm install @vunexa/lixa
+# or
+yarn add @vunexa/lixa
+```
+
+## Quick Start
+
+### 1. Configure lixa with multiple providers
+
+```typescript
+import { Lixa } from '@vunexa/lixa';
+
+const lixa = new Lixa({
+  providers: {
+    google: {
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+      redirectUri: 'https://yourapp.com/auth/google/callback',
+      scopes: ['openid', 'email', 'profile'],
+      extraConfig: {
+        prompt: 'consent',
+        access_type: 'offline',
+      },
+    },
+    github: {
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+      redirectUri: 'https://yourapp.com/auth/github/callback',
+      scopes: ['read:user', 'user:email'],
+      extraConfig: {},
+    },
+  },
+
+  // Optional: custom session strategy
+  sessionStrategy: {
+    createSession: async (tokenData) => {
+      // Custom session creation logic
+      return {
+        token: 'custom-session-token',
+        raw: tokenData
+      };
+    }
+  },
+});
+```
+
+### 2. Redirect users to the provider's authorization URL
+
+```typescript
+app.get("/login", (req, res) => {
+  const provider = req.query.provider as string; // 'google' or 'github'
+  const state = lixa.generateRandomState();
+  
+  // Store state in session for validation
+  req.session.oauthState = state;
+  
+  const authUrl = lixa.getAuthUrl(provider.toUpperCase(), state);
+  res.redirect(authUrl);
+});
+```
+
+### 3. Handle the provider callback and establish a session
+
+```typescript
+app.get("/auth/:provider/callback", async (req, res) => {
+  const { code, state } = req.query;
+  const provider = req.params.provider;
+
+  try {
+    // Validate state parameter
+    if (state !== req.session.oauthState) {
+      throw new Error('Invalid state parameter');
+    }
+
+    const session = await lixa.handleCallback({
+      provider,
+      code: code as string,
+      state: state as string,
+    });
+
+    // Session established
+    res.cookie("session_token", session.token, {
+      httpOnly: true,
+      secure: true,
+      sameSite: 'strict'
+    });
+    
+    res.redirect("/dashboard");
+  } catch (error) {
+    console.error("Authentication error:", error);
+    res.status(500).send("Authentication failed");
+  }
+});
+```
+
+## Advanced Usage
+
+### Custom Provider Registration
+
+You can register custom OAuth providers by implementing the `IProvider` interface:
+
+```typescript
+import { Lixa, IProvider } from '@vunexa/lixa';
+
+class CustomProvider implements IProvider {
+  authorizationEndpoint = 'https://custom-provider.com/oauth/authorize';
+  tokenEndpoint = 'https://custom-provider.com/oauth/token';
+  userInfoEndpoint = 'https://custom-provider.com/api/user';
+}
+
+// Register the custom provider
+Lixa.registerProvider({
+  custom: new CustomProvider()
+});
+
+// Use it in your configuration
+const lixa = new Lixa({
+  providers: {
+    custom: {
+      clientId: 'your-client-id',
+      clientSecret: 'your-client-secret',
+      redirectUri: 'https://yourapp.com/auth/custom/callback',
+      scopes: ['read:user'],
+    }
+  }
+});
+```
+
+### Check Provider Registration
+
+```typescript
+// Check if a provider is registered
+if (Lixa.isProviderRegistered('google')) {
+  console.log('Google provider is available');
+}
+```
+
+## API Reference
+
+### `Lixa` Class
+
+#### Constructor
+- `new Lixa(config: LixaConfig)` - Creates a new Lixa instance
+
+#### Static Methods
+- `Lixa.registerProvider(providerMap: { [key: string]: IProvider })` - Register custom providers
+- `Lixa.isProviderRegistered(provider: string): boolean` - Check if a provider is registered
+
+#### Instance Methods
+- `generateRandomState(): string` - Generate a random state parameter for OAuth flow
+- `getAuthUrl(provider: string, state: string): string` - Get authorization URL for a provider
+- `handleCallback({ provider, code, state }): Promise<Session>` - Handle OAuth callback and create session
+
+### Types
+
+```typescript
+interface ProviderConfig {
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+  scopes: string[];
+  extraConfig?: Record<string, any>;
+}
+
+interface LixaConfig {
+  providers: Record<string, ProviderConfig>;
+  sessionStrategy?: SessionStrategy;
+}
+
+interface SessionStrategy {
+  createSession(userInfo: any): Promise<Session>;
+}
+
+interface Session {
+  token: string;
+  raw: any;
+}
+
+interface IProvider {
+  authorizationEndpoint: string;
+  tokenEndpoint: string;
+  userInfoEndpoint: string;
+}
+```
+
+## Built-in Providers
+
+- **Google** - OAuth 2.0 and OpenID Connect
+- **GitHub** - OAuth 2.0
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Build the library
+npm run build
+
+# Lint code
+npm run lint
+```
+
+## License
+
+MIT

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

@@ -0,0 +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, type SafeLixaConfig, } from "./types";
+export { type IProvider } from "./providers";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"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,EACZ,KAAK,cAAc,GACpB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,160 @@
+import { type LixaConfig, type ProviderConfig, type Session } from "./types";
+import { IProvider } from "./providers";
+/**
+ * Type representing the keys of configured providers
+ */
+type ConfiguredProviderKey<T extends LixaConfig<any>> = keyof T['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
+ * 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
+ */
+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;
+}
+export { Lixa };
+//# sourceMappingURL=lixa.d.ts.map

package/dist/lixa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lixa.d.ts","sourceRoot":"","sources":["../src/lixa.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAUxC;;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,CAAU;IACxB,OAAO,CAAC,QAAQ,CAAW;IAE3B;;;;OAIG;gBACS,MAAM,EAAE,OAAO;IAe3B;;;;;;;;;;;;;;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,OAAO,CAAC;YAmDN,oBAAoB;IAsClC,OAAO,CAAC,kBAAkB;CAG3B;AAED,OAAO,EAAE,IAAI,EAAE,CAAC"}