@vunexa/lixa 0.1.0 → 0.1.1

package/README.md

@@ -28,36 +28,7 @@ A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library
 
 ## 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
-```
+![Architecture Overview](./docs/images/architecture.svg)
 
 ---
 
@@ -141,46 +112,7 @@ Lixa supports automatic identity merging for users signing in with different SSO
 
 ### 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...
-```
+![Account Linking Sequence](./docs/images/account-linking.svg)
 
 ### Account Linking Configuration Modes
 
@@ -222,29 +154,7 @@ Primary authentication is strictly limited to identity scopes. To request third-
 
 ### 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)
-```
+![Resource Connection Sequence](./docs/images/resource-connection.svg)
 
 ### Resource Connection Usage Example
 

package/README.template.md

@@ -0,0 +1,360 @@
+# @vunexa/lixa
+
+> 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 (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
+
+- **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 @vunexa/lixa-providers
+# or
+yarn add @vunexa/lixa @vunexa/lixa-providers
+```
+
+---
+
+## Quick Start
+
+### 1. Configure Lixa with Account Linking & Providers
+
+```typescript
+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: "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: "http://localhost:3000/auth/github/callback",
+      scopes: ["read:user", "user:email"],
+    },
+  },
+});
+```
+
+### 2. Primary Authentication & Callback
+
+```typescript
+// 1. Redirect to provider authorization URL
+app.get("/auth/:provider", async (req, res) => {
+  const authUrl = await lixa.getAuthUrl(req.params.provider);
+  res.redirect(authUrl);
+});
+
+// 2. Handle provider callback
+app.get("/auth/:provider/callback", async (req, res) => {
+  const { code, state } = req.query;
+  const provider = req.params.provider;
+
+  try {
+    const sessionId = await lixa.handleCallback({
+      provider,
+      code: code as string,
+      state: state as string,
+    });
+
+    res.cookie("session_id", sessionId, { httpOnly: true, secure: true });
+    res.redirect("/profile");
+  } catch (error) {
+    res.status(401).send("Authentication failed");
+  }
+});
+```
+
+---
+
+## 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...
+```
+
+### Account Linking Configuration Modes
+
+```typescript
+import { AccountLinkingStrategy } from "@vunexa/lixa";
+
+// Mode 1: Auto-link by verified email (Recommended)
+accountLinking: {
+  mode: AccountLinkingStrategy.AUTO_LINK_BY_VERIFIED_EMAIL,
+  requireVerifiedEmail: true,
+}
+
+// Mode 2: Treat provider logins as separate accounts
+accountLinking: {
+  mode: AccountLinkingStrategy.ISOLATED,
+}
+```
+
+### 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");
+```
+
+---
+
+## 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)
+```
+
+### Resource Connection Usage Example
+
+```typescript
+// 1. Generate Resource Authorization URL (Requires Active Session)
+app.get("/connect/github", async (req, res) => {
+  const sessionId = req.cookies.session_id;
+
+  const resourceAuthUrl = await lixa.getResourceAuthUrl({
+    sessionId,
+    provider: "github",
+    scopes: ["repo", "read:org"], // Resource permissions requested post-login
+  });
+
+  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 });
+});
+```
+
+---
+
+## 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;
+
+  /** 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;
+}
+```
+
+### `LinkedAccount` vs `ConnectedResource`
+
+| 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]` |
+
+---
+
+## User Info Utilities
+
+Lixa provides utilities to extract user information from OAuth tokens:
+
+```typescript
+import { extractUserInfo, type UserInfo } from "@vunexa/lixa";
+
+const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+console.log(userInfo.email, userInfo.name);
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

package/docs/api/index.md

@@ -0,0 +1,32 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md)
+
+## API Reference
+
+## Packages
+
+<table><thead><tr><th>
+
+Package
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[@vunexa/lixa](./lixa.md)
+
+
+</td><td>
+
+A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library for backend applications.
+
+
+</td></tr>
+</tbody></table>
+

package/docs/api/lixa.iprovider.authorizationendpoint.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@vunexa/lixa](./lixa.md) &gt; [IProvider](./lixa.iprovider.md) &gt; [authorizationEndpoint](./lixa.iprovider.authorizationendpoint.md)
+
+## IProvider.authorizationEndpoint property
+
+The OAuth authorization endpoint URL
+
+**Signature:**
+
+```typescript
+authorizationEndpoint: string;
+```

package/docs/api/lixa.iprovider.md

@@ -0,0 +1,100 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@vunexa/lixa](./lixa.md) &gt; [IProvider](./lixa.iprovider.md)
+
+## IProvider interface
+
+Interface for OAuth provider implementations.
+
+**Signature:**
+
+```typescript
+interface IProvider 
+```
+
+## Remarks
+
+Implement this interface to add support for custom OAuth providers.
+
+## Properties
+
+<table><thead><tr><th>
+
+Property
+
+
+</th><th>
+
+Modifiers
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[authorizationEndpoint](./lixa.iprovider.authorizationendpoint.md)
+
+
+</td><td>
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+The OAuth authorization endpoint URL
+
+
+</td></tr>
+<tr><td>
+
+[tokenEndpoint](./lixa.iprovider.tokenendpoint.md)
+
+
+</td><td>
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+The OAuth token exchange endpoint URL
+
+
+</td></tr>
+<tr><td>
+
+[userInfoEndpoint](./lixa.iprovider.userinfoendpoint.md)
+
+
+</td><td>
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+The user information endpoint URL
+
+
+</td></tr>
+</tbody></table>
+

package/docs/api/lixa.iprovider.tokenendpoint.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@vunexa/lixa](./lixa.md) &gt; [IProvider](./lixa.iprovider.md) &gt; [tokenEndpoint](./lixa.iprovider.tokenendpoint.md)
+
+## IProvider.tokenEndpoint property
+
+The OAuth token exchange endpoint URL
+
+**Signature:**
+
+```typescript
+tokenEndpoint: string;
+```

package/docs/api/lixa.iprovider.userinfoendpoint.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@vunexa/lixa](./lixa.md) &gt; [IProvider](./lixa.iprovider.md) &gt; [userInfoEndpoint](./lixa.iprovider.userinfoendpoint.md)
+
+## IProvider.userInfoEndpoint property
+
+The user information endpoint URL
+
+**Signature:**
+
+```typescript
+userInfoEndpoint: string;
+```

package/docs/api/lixa.lixa._constructor_.md

@@ -0,0 +1,50 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@vunexa/lixa](./lixa.md) &gt; [Lixa](./lixa.lixa.md) &gt; [(constructor)](./lixa.lixa._constructor_.md)
+
+## Lixa.(constructor)
+
+Creates a new Lixa instance with the provided configuration.
+
+**Signature:**
+
+```typescript
+constructor(config: LixaConfig);
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+config
+
+
+</td><td>
+
+[LixaConfig](./lixa.lixaconfig.md)
+
+
+</td><td>
+
+The configuration object containing provider settings and optional session strategy
+
+
+</td></tr>
+</tbody></table>
+