@vunexa/lixa 0.0.1-alpha.8 → 0.1.0

package/README.md

@@ -1,240 +1,360 @@
 # @vunexa/lixa
 
-> Package is in very early stage and can have frequent breaking changes. DO NOT USE it for production
+> Package is in active development.
 
 [![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.
+`@vunexa/lixa` simplifies multi-provider authentication (e.g. Google, GitHub, Microsoft), enforces strict **AuthN/AuthZ separation**, enables **multi-SSO account linking**, and provides a dedicated post-login **Resource Connection API**.
 
 ---
 
 ## 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
+- **Strict AuthN / AuthZ Separation**: Primary login is automatically restricted to minimal identity scopes (`openid`, `email`, `profile`). Resource scopes are isolated to post-login connection.
+- **Multi-SSO Account Linking**: Seamlessly merge accounts sharing the same verified email address under a single unified user session.
+- **Post-Login Resource Connection API**: Connect third-party API providers (GitHub Repositories, Google Drive, Slack) post-authentication and manage resource tokens on the user session.
+- **Multi-provider OAuth/OIDC support** with unified API.
+- **Built-in providers** for Google, GitHub, and more via `@vunexa/lixa-providers`.
+- **Custom provider support** with extensible provider interface.
+- **Unified session management** via `SessionHandler` (generation + storage).
+- **Unified state management** via `StateHandler` (PKCE + CSRF protection).
+- **Automatic PKCE** (Proof Key for Code Exchange) for all OAuth flows.
+- **TypeScript-first** with full type safety (zero `any` types).
+
+---
+
+## Architecture Overview
+
+```mermaid
+graph TD
+    User([User Client / Browser])
+    
+    subgraph Lixa ["Lixa Core Engine"]
+        AuthNGuard["Primary AuthN Guard<br/>(Minimal Identity Scopes Only)"]
+        SessionMgr["Session Handler & Unified Session"]
+        AccountLinker["Account Linker<br/>(AUTO_LINK_BY_VERIFIED_EMAIL)"]
+        ResourceConn["Resource Connection API<br/>(Post-Login AuthZ)"]
+    end
+
+    subgraph IdentityProviders ["Identity Providers (AuthN)"]
+        GoogleAuth["Google / OIDC"]
+        GitHubAuth["GitHub OAuth"]
+    end
+
+    subgraph ResourceProviders ["Resource APIs (AuthZ)"]
+        GitHubAPI["GitHub API (repos, orgs)"]
+        GoogleDriveAPI["Google Drive API"]
+    end
+
+    User -->|"1. Primary Login / Link Account"| AuthNGuard
+    AuthNGuard -->|"Request Identity"| IdentityProviders
+    IdentityProviders -->|"Tokens + UserInfo"| AccountLinker
+    AccountLinker -->|"Unified Session (session.accounts)"| SessionMgr
+    
+    User -->|"2. Connect Resource API (Post-Login)"| ResourceConn
+    ResourceConn -->|"Request Permissions (repo, drive)"| ResourceProviders
+    ResourceProviders -->|"Resource Access Tokens"| SessionMgr
+```
 
 ---
 
 ## Installation
 
 ```bash
-npm install @vunexa/lixa
+npm install @vunexa/lixa @vunexa/lixa-providers
 # or
-yarn add @vunexa/lixa
+yarn add @vunexa/lixa @vunexa/lixa-providers
 ```
 
+---
+
 ## Quick Start
 
-### 1. Configure lixa with multiple providers
+### 1. Configure Lixa with Account Linking & Providers
 
 ```typescript
-import { Lixa } from '@vunexa/lixa';
-
-const lixa = new Lixa({
+import { Lixa, AccountLinkingStrategy } from "@vunexa/lixa";
+import { GoogleProvider, GithubProvider } from "@vunexa/lixa-providers";
+
+export const lixa = new Lixa({
+  // Configure Multi-SSO Account Linking Strategy
+  accountLinking: {
+    mode: AccountLinkingStrategy.AUTO_LINK_BY_VERIFIED_EMAIL,
+    requireVerifiedEmail: true,
+  },
   providers: {
     google: {
+      provider: new GoogleProvider(),
       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',
-      },
+      redirectUri: "http://localhost:3000/auth/google/callback",
+      scopes: ["openid", "email", "profile"],
     },
     github: {
+      provider: new GithubProvider(),
       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: {},
+      redirectUri: "http://localhost:3000/auth/github/callback",
+      scopes: ["read:user", "user:email"],
     },
   },
-
-  // 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
+### 2. Primary Authentication & Callback
 
 ```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);
+// 1. Redirect to provider authorization URL
+app.get("/auth/:provider", async (req, res) => {
+  const authUrl = await lixa.getAuthUrl(req.params.provider);
   res.redirect(authUrl);
 });
-```
 
-### 3. Handle the provider callback and establish a session
-
-```typescript
+// 2. Handle provider callback
 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({
+    const sessionId = 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");
+    res.cookie("session_id", sessionId, { httpOnly: true, secure: true });
+    res.redirect("/profile");
   } catch (error) {
-    console.error("Authentication error:", error);
-    res.status(500).send("Authentication failed");
+    res.status(401).send("Authentication failed");
   }
 });
 ```
 
-## Advanced Usage
+---
 
-### Custom Provider Registration
+## Multi-SSO Account Linking
+
+Lixa supports automatic identity merging for users signing in with different SSO providers (e.g. Google and GitHub) that share the same verified email address.
+
+### Account Linking Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant App as Express Backend
+    participant Lixa as Lixa Engine
+    participant SessionStore as SessionStorage
+    participant Google as Google Identity
+    participant GitHub as GitHub Identity
+
+    Note over User, GitHub: 1. Primary Login with Google
+    User->>App: GET /auth/google
+    App->>Lixa: getAuthUrl('google')
+    Lixa-->>App: Redirect URL (openid, email, profile)
+    App-->>User: 302 Redirect to Google Consent
+    User->>Google: Grant Identity Consent
+    Google-->>App: GET /auth/google/callback?code=xxx
+    App->>Lixa: handleCallback({ provider: 'google', code })
+    Lixa->>Google: Exchange code for tokens
+    Lixa->>Lixa: extractUserInfo() -> alex@example.com (verified)
+    Lixa->>SessionStore: Save session (sessionId: 0x123...)
+    Lixa-->>App: Returns sessionId: 0x123...
+    App-->>User: Set Cookie session_id=0x123...
+
+    Note over User, GitHub: 2. Subsequent Login with GitHub (Same Email)
+    User->>App: GET /auth/github
+    App->>Lixa: getAuthUrl('github')
+    Lixa-->>App: Redirect URL (read:user, user:email)
+    App-->>User: 302 Redirect to GitHub Consent
+    User->>GitHub: Grant Identity Consent
+    GitHub-->>App: GET /auth/github/callback?code=yyy
+    App->>Lixa: handleCallback({ provider: 'github', code })
+    Lixa->>GitHub: Exchange code for tokens
+    Lixa->>Lixa: extractUserInfo() -> alex@example.com (verified)
+    Lixa->>SessionStore: getSessionByEmail("alex@example.com")
+    SessionStore-->>Lixa: Existing Session (sessionId: 0x123...)
+    Lixa->>Lixa: Merge github into session.accounts['github']
+    Lixa->>SessionStore: Save updated session (sessionId: 0x123...)
+    Lixa-->>App: Returns SAME sessionId: 0x123...
+```
 
-You can register custom OAuth providers by implementing the `IProvider` interface:
+### Account Linking Configuration Modes
 
 ```typescript
-import { Lixa, IProvider } from '@vunexa/lixa';
+import { AccountLinkingStrategy } 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';
+// Mode 1: Auto-link by verified email (Recommended)
+accountLinking: {
+  mode: AccountLinkingStrategy.AUTO_LINK_BY_VERIFIED_EMAIL,
+  requireVerifiedEmail: true,
 }
 
-// Register the custom provider
-Lixa.registerProvider({
-  custom: new CustomProvider()
-});
+// Mode 2: Treat provider logins as separate accounts
+accountLinking: {
+  mode: AccountLinkingStrategy.ISOLATED,
+}
+```
 
-// 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'],
-    }
-  }
+### Explicit Account Linking & Unlinking APIs
+
+```typescript
+// Explicitly link a new provider while authenticated
+await lixa.linkAccount({
+  sessionId: req.cookies.session_id,
+  provider: "github",
+  code: req.query.code as string,
+  state: req.query.state as string,
 });
+
+// Unlink a provider account
+await lixa.unlinkAccount(req.cookies.session_id, "github");
 ```
 
-### Check Provider Registration
+---
 
-```typescript
-// Check if a provider is registered
-if (Lixa.isProviderRegistered('google')) {
-  console.log('Google provider is available');
-}
+## Post-Login Resource Connection API (AuthZ)
+
+Primary authentication is strictly limited to identity scopes. To request third-party API permissions (such as GitHub Repositories or Google Drive), use Lixa's post-login **Resource Connection API**.
+
+### Resource Connection Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant App as Express Backend
+    participant Lixa as Lixa Engine
+    participant SessionStore as SessionStorage
+    participant ResourceAPI as GitHub OAuth (Resource Scopes)
+
+    Note over User, ResourceAPI: Connect Resource API Post-Login
+    User->>App: POST /connect/github (Cookie: session_id=0x123...)
+    App->>Lixa: getResourceAuthUrl({ sessionId: '0x123...', provider: 'github', scopes: ['repo', 'read:org'] })
+    Lixa->>SessionStore: Validate active session
+    Lixa-->>App: Resource Authorization URL (scopes: repo read:org)
+    App-->>User: 302 Redirect to Resource Consent
+    User->>ResourceAPI: Grant Resource Consent (Repo Access)
+    ResourceAPI-->>App: GET /connect/github/callback?code=zzz&state=...
+    App->>Lixa: handleResourceCallback({ sessionId: '0x123...', provider: 'github', code })
+    Lixa->>ResourceAPI: Exchange code for Resource Access Token
+    Lixa->>SessionStore: Store under session.resources['github']
+    Lixa-->>App: Updated Session
+    App-->>User: Render Dashboard (Repo Access Granted)
 ```
 
-## API Reference
+### Resource Connection Usage Example
 
-### `Lixa` Class
+```typescript
+// 1. Generate Resource Authorization URL (Requires Active Session)
+app.get("/connect/github", async (req, res) => {
+  const sessionId = req.cookies.session_id;
 
-#### Constructor
-- `new Lixa(config: LixaConfig)` - Creates a new Lixa instance
+  const resourceAuthUrl = await lixa.getResourceAuthUrl({
+    sessionId,
+    provider: "github",
+    scopes: ["repo", "read:org"], // Resource permissions requested post-login
+  });
 
-#### Static Methods
-- `Lixa.registerProvider(providerMap: { [key: string]: IProvider })` - Register custom providers
-- `Lixa.isProviderRegistered(provider: string): boolean` - Check if a provider is registered
+  res.redirect(resourceAuthUrl);
+});
 
-#### 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
+// 2. Handle Resource Callback
+app.get("/connect/github/callback", async (req, res) => {
+  const sessionId = req.cookies.session_id;
 
-### Types
+  const updatedSession = await lixa.handleResourceCallback({
+    sessionId,
+    provider: "github",
+    code: req.query.code as string,
+    state: req.query.state as string,
+    scopes: ["repo", "read:org"],
+  });
 
-```typescript
-interface ProviderConfig {
-  clientId: string;
-  clientSecret: string;
-  redirectUri: string;
-  scopes: string[];
-  extraConfig?: Record<string, any>;
-}
+  res.redirect("/dashboard");
+});
 
-interface LixaConfig {
-  providers: Record<string, ProviderConfig>;
-  sessionStrategy?: SessionStrategy;
-}
+// 3. Query Connected Resource Access Token
+app.get("/api/github/repos", async (req, res) => {
+  const resource = await lixa.getConnectedResource(req.cookies.session_id, "github");
 
-interface SessionStrategy {
-  createSession(userInfo: any): Promise<Session>;
-}
+  if (!resource) {
+    return res.status(403).json({ error: "GitHub resource not connected" });
+  }
+
+  // Call GitHub API with resource access token
+  const response = await fetch("https://api.github.com/user/repos", {
+    headers: { Authorization: `Bearer ${resource.accessToken}` },
+  });
+
+  const repos = await response.json();
+  res.json(repos);
+});
+
+// 4. Disconnect Resource Provider
+app.delete("/connect/github", async (req, res) => {
+  await lixa.disconnectResource(req.cookies.session_id, "github");
+  res.json({ success: true });
+});
+```
+
+---
 
-interface Session {
+## Session Interface Structure
+
+```typescript
+export interface Session<TRaw = OAuthTokenResponse> {
+  /** Unique session ID generated by Lixa */
+  id?: string;
+
+  /** Primary access token or session token */
   token: string;
-  raw: any;
-}
 
-interface IProvider {
-  authorizationEndpoint: string;
-  tokenEndpoint: string;
-  userInfoEndpoint: string;
+  /** Unified user ID across linked accounts */
+  userId?: string;
+
+  /** Primary user email */
+  email?: string;
+
+  /** Current active auth provider */
+  provider?: string;
+
+  /** Linked SSO provider accounts (AuthN) */
+  accounts?: Record<string, LinkedAccount>;
+
+  /** Connected third-party resource provider tokens (AuthZ) */
+  resources?: Record<string, ConnectedResource>;
+
+  /** Full raw token response from provider */
+  raw: TRaw;
 }
 ```
 
-## Built-in Providers
-
-- **Google** - OAuth 2.0 and OpenID Connect
-- **GitHub** - OAuth 2.0
+### `LinkedAccount` vs `ConnectedResource`
 
-## Development
+| Concept | Purpose | Scopes Allowed | Stored Location |
+| :--- | :--- | :--- | :--- |
+| **`LinkedAccount`** | Identity verification & multi-SSO merging (**AuthN**) | Minimal identity scopes (`openid`, `email`, `read:user`) | `session.accounts[provider]` |
+| **`ConnectedResource`** | External API resource access (**AuthZ**) | Resource permissions (`repo`, `drive.readonly`) | `session.resources[provider]` |
 
-```bash
-# Install dependencies
-npm install
+---
 
-# Run tests
-npm test
+## User Info Utilities
 
-# Run tests with coverage
-npm run test:coverage
+Lixa provides utilities to extract user information from OAuth tokens:
 
-# Build the library
-npm run build
+```typescript
+import { extractUserInfo, type UserInfo } from "@vunexa/lixa";
 
-# Lint code
-npm run lint
+const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+console.log(userInfo.email, userInfo.name);
 ```
 
+---
+
 ## License
 
-MIT
+[MIT](LICENSE)

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

@@ -0,0 +1,11 @@
+import { SessionHandler, SessionStorage } from "./types";
+import type { Session, OAuthTokenResponse, ProviderMetadata } from "../models/session";
+declare class LocalSessionHandler implements SessionHandler {
+    private cache;
+    private emailToSessionMap;
+    sessionStorage: SessionStorage;
+    constructor(defaultTtlSeconds?: number);
+    GenerateSession<T extends Session>(tokenData: OAuthTokenResponse, providerMetadata: ProviderMetadata): Promise<T>;
+}
+export { LocalSessionHandler };
+//# sourceMappingURL=session-cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-cache.d.ts","sourceRoot":"","sources":["../../src/dao/session-cache.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEvF,cAAM,mBAAoB,YAAW,cAAc;IACjD,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,iBAAiB,CAAkC;IACpD,cAAc,EAAE,cAAc,CAAC;gBAE1B,iBAAiB,GAAE,MAAY;IAuCrC,eAAe,CAAC,CAAC,SAAS,OAAO,EACrC,SAAS,EAAE,kBAAkB,EAC7B,gBAAgB,EAAE,gBAAgB,GACjC,OAAO,CAAC,CAAC,CAAC;CAad;AAED,OAAO,EAAE,mBAAmB,EAAE,CAAC"}

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

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

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

@@ -1 +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"}
+{"version":3,"file":"state-cache.d.ts","sourceRoot":"","sources":["../../src/dao/state-cache.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEhE,cAAM,iBAAkB,YAAW,YAAY;IAC7C,OAAO,CAAC,KAAK,CAAY;IAClB,YAAY,EAAE,YAAY,CAAC;gBAEtB,iBAAiB,GAAE,MAAY;IAoBrC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,CAAA;KAAE,CAAC;CAanF;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAC"}