@vunexa/lixa 0.0.1-alpha.9 → 0.1.1

package/README.md

@@ -1,240 +1,270 @@
 # @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
+
+![Architecture Overview](./docs/images/architecture.svg)
 
 ---
 
 ## 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
+---
+
+## 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.
 
-### Custom Provider Registration
+### Account Linking Sequence Diagram
 
-You can register custom OAuth providers by implementing the `IProvider` interface:
+![Account Linking Sequence](./docs/images/account-linking.svg)
+
+### 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()
-});
-
-// 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'],
-    }
-  }
-});
+// Mode 2: Treat provider logins as separate accounts
+accountLinking: {
+  mode: AccountLinkingStrategy.ISOLATED,
+}
 ```
 
-### Check Provider Registration
+### Explicit Account Linking & Unlinking APIs
 
 ```typescript
-// Check if a provider is registered
-if (Lixa.isProviderRegistered('google')) {
-  console.log('Google provider is available');
-}
+// 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");
 ```
 
-## API Reference
+---
 
-### `Lixa` Class
+## Post-Login Resource Connection API (AuthZ)
 
-#### Constructor
-- `new Lixa(config: LixaConfig)` - Creates a new Lixa instance
+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**.
 
-#### Static Methods
-- `Lixa.registerProvider(providerMap: { [key: string]: IProvider })` - Register custom providers
-- `Lixa.isProviderRegistered(provider: string): boolean` - Check if a provider is registered
+### Resource Connection Sequence Diagram
 
-#### 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
+![Resource Connection Sequence](./docs/images/resource-connection.svg)
 
-### Types
+### Resource Connection Usage Example
 
 ```typescript
-interface ProviderConfig {
-  clientId: string;
-  clientSecret: string;
-  redirectUri: string;
-  scopes: string[];
-  extraConfig?: Record<string, any>;
-}
+// 1. Generate Resource Authorization URL (Requires Active Session)
+app.get("/connect/github", async (req, res) => {
+  const sessionId = req.cookies.session_id;
 
-interface LixaConfig {
-  providers: Record<string, ProviderConfig>;
-  sessionStrategy?: SessionStrategy;
-}
+  const resourceAuthUrl = await lixa.getResourceAuthUrl({
+    sessionId,
+    provider: "github",
+    scopes: ["repo", "read:org"], // Resource permissions requested post-login
+  });
 
-interface SessionStrategy {
-  createSession(userInfo: any): Promise<Session>;
-}
+  res.redirect(resourceAuthUrl);
+});
+
+// 2. Handle Resource Callback
+app.get("/connect/github/callback", async (req, res) => {
+  const sessionId = req.cookies.session_id;
+
+  const updatedSession = await lixa.handleResourceCallback({
+    sessionId,
+    provider: "github",
+    code: req.query.code as string,
+    state: req.query.state as string,
+    scopes: ["repo", "read:org"],
+  });
+
+  res.redirect("/dashboard");
+});
+
+// 3. Query Connected Resource Access Token
+app.get("/api/github/repos", async (req, res) => {
+  const resource = await lixa.getConnectedResource(req.cookies.session_id, "github");
+
+  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)