@vunexa/lixa 0.0.1-alpha.26 → 0.0.1-alpha.28

package/README.md

@@ -545,6 +545,200 @@ const strategy: SessionStrategy = {
 };
 ```
 
+## User Info Utilities
+
+Lixa provides utilities to extract user information from OAuth tokens, making it easier to work with user data across different providers.
+
+### `extractUserInfo()`
+
+High-level function that automatically extracts user information from OAuth token data:
+
+```typescript
+import { extractUserInfo, type UserInfo } from "@vunexa/lixa";
+
+// In your session strategy
+const sessionStrategy = {
+  createSession: async (tokenData) => {
+    // Automatically extracts user info from ID token or fetches from API
+    const { userInfo, provider } = await extractUserInfo(
+      tokenData,
+      providerConfig.userInfoEndpoint,  // Optional: from IProvider
+      'google'  // Optional: provider name for error messages
+    );
+    
+    console.log(`User ${userInfo.email} authenticated via ${provider}`);
+    
+    // Create user in database
+    const user = await db.users.upsert({
+      email: userInfo.email,
+      name: userInfo.name,
+      givenName: userInfo.given_name,
+      familyName: userInfo.family_name,
+      picture: userInfo.picture,
+    });
+    
+    return {
+      token: generateSessionId(),
+      raw: { ...tokenData, userId: user.id }
+    };
+  }
+};
+```
+
+**Parameters:**
+- `tokenData` (OAuthTokenResponse) - OAuth token response from provider
+- `userInfoEndpoint` (string, optional) - Provider's userinfo endpoint URL (required if no ID token)
+- `providerName` (string, optional) - Provider name for error messages
+
+**Returns:**
+- `{ userInfo: UserInfo, provider: string }` - User information and detected provider name
+
+**Behavior:**
+1. If ID token present: Decodes JWT and extracts user info
+2. If only access token: Fetches from userinfo endpoint
+3. Provider detection: From ID token issuer, token data, or parameter
+4. Throws clear errors if provider cannot be determined
+
+### `decodeIdToken()`
+
+Decode JWT ID tokens to extract user information:
+
+```typescript
+import { decodeIdToken, type UserInfo } from "@vunexa/lixa";
+
+const userInfo: UserInfo = decodeIdToken(tokenData.id_token);
+console.log(userInfo.email, userInfo.name);
+```
+
+**Use case:** When you know the provider returns an ID token (OIDC providers like Google)
+
+### `fetchUserInfo()`
+
+Fetch user information from a provider's userinfo endpoint:
+
+```typescript
+import { fetchUserInfo, type UserInfo } from "@vunexa/lixa";
+
+const userInfo: UserInfo = await fetchUserInfo(
+  tokenData.access_token,
+  'https://www.googleapis.com/oauth2/v2/userinfo',
+  'google'  // Optional: for error messages
+);
+```
+
+**Use case:** When you need to fetch user info from the API (OAuth-only providers like GitHub, or when ID token is not available)
+
+### `determineProviderFromIssuer()`
+
+Detect OAuth provider from ID token issuer field:
+
+```typescript
+import { determineProviderFromIssuer, decodeIdToken } from "@vunexa/lixa";
+
+const userInfo = decodeIdToken(tokenData.id_token);
+const provider = determineProviderFromIssuer(userInfo);
+// Returns: 'google', 'github', or null if unknown
+```
+
+**Supported providers:**
+- Google: Detects `accounts.google.com` in issuer
+- GitHub: Detects `github` in issuer
+- Returns `null` for unknown issuers
+
+### `UserInfo` Type
+
+Standard user information structure across all providers:
+
+```typescript
+interface UserInfo {
+  email: string;                    // Required: User's email address
+  id?: string;                      // Optional: Provider-specific user ID
+  sub?: string;                     // Optional: Subject identifier (OIDC)
+  given_name?: string;              // Optional: First name
+  family_name?: string;             // Optional: Last name
+  name?: string;                    // Optional: Full name
+  picture?: string;                 // Optional: Profile picture URL
+  email_verified?: boolean;         // Optional: Email verification status
+  iss?: string;                     // Optional: Token issuer (OIDC)
+}
+```
+
+### Complete Example with User Info Utilities
+
+```typescript
+import { Lixa, extractUserInfo, type UserInfo } from "@vunexa/lixa";
+import { GoogleProvider, GithubProvider } from "@vunexa/lixa-providers";
+
+const lixa = new Lixa({
+  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"],
+    },
+    github: {
+      provider: new GithubProvider(),
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+      redirectUri: "https://yourapp.com/auth/github/callback",
+      scopes: ["user:email"],
+    }
+  },
+  
+  sessionStrategy: {
+    createSession: async (tokenData) => {
+      // Extract user info - works for both Google (ID token) and GitHub (API fetch)
+      const { userInfo, provider } = await extractUserInfo(tokenData);
+      
+      console.log(`User ${userInfo.email} authenticated via ${provider}`);
+      
+      // Create or update user in database
+      const user = await db.users.upsert({
+        email: userInfo.email,
+        name: userInfo.name || `${userInfo.given_name} ${userInfo.family_name}`.trim(),
+        givenName: userInfo.given_name,
+        familyName: userInfo.family_name,
+        picture: userInfo.picture,
+        emailVerified: userInfo.email_verified,
+      });
+      
+      // Create session
+      const sessionId = generateUniqueId();
+      await db.sessions.create({
+        id: sessionId,
+        userId: user.id,
+        provider,
+        accessToken: tokenData.access_token,
+        refreshToken: tokenData.refresh_token,
+        expiresAt: tokenData.expires_in 
+          ? new Date(Date.now() + tokenData.expires_in * 1000)
+          : null,
+      });
+      
+      return {
+        token: sessionId,
+        raw: {
+          ...tokenData,
+          userId: user.id,
+          provider,
+        }
+      };
+    }
+  }
+});
+```
+
+### Benefits of User Info Utilities
+
+✅ **Provider-agnostic** - Works with any OAuth provider  
+✅ **Automatic detection** - Determines provider from token data  
+✅ **Type-safe** - Full TypeScript support with UserInfo interface  
+✅ **Flexible** - Supports both ID token and API fetching  
+✅ **Error handling** - Clear error messages when provider cannot be determined  
+✅ **Uses IProvider** - Leverages userInfoEndpoint from provider configuration  
+
 ## API Reference
 
 ### `Lixa` Class

package/dist/export-types/index.d.ts

@@ -21,6 +21,13 @@
  */
 declare type ConfiguredProviderKey<T extends LixaConfig<Record<string, ProviderConfig>>> = keyof T['providers'];
 
+/**
+ * Decode JWT ID token to extract user information
+ *
+ * @public
+ */
+export declare function decodeIdToken(idToken: string): UserInfo;
+
 /**
  * Default session strategy that works with any OAuth provider.
  * Extracts common token information and creates a standardized session.
@@ -33,11 +40,80 @@ export declare class DefaultSessionStrategy implements SessionStrategy {
      * Handles common OAuth token formats and extracts the access token.
      *
      * @param tokenData - The token data received from the OAuth provider
+     * @param providerMetadata - Provider metadata (not used in default implementation)
      * @returns A Promise that resolves to a Session object
      */
-    createSession(tokenData: OAuthTokenResponse): Promise<Session>;
+    createSession(tokenData: OAuthTokenResponse, providerMetadata: ProviderMetadata): Promise<Session>;
 }
 
+/**
+ * Determine OAuth provider from ID token issuer
+ *
+ * @public
+ */
+export declare function determineProviderFromIssuer(userInfo: UserInfo): string | null;
+
+/**
+ * Extract user info from OAuth token data
+ *
+ * @param tokenData - OAuth token response from provider
+ * @param userInfoEndpoint - Optional userinfo endpoint URL (required if no ID token)
+ * @param providerName - Optional provider name for error messages
+ * @returns User info and detected provider name
+ *
+ * @remarks
+ * This function attempts to extract user information in the following order:
+ * 1. Decode ID token if present (preferred method)
+ * 2. Fetch from userinfo endpoint using access token (requires userInfoEndpoint parameter)
+ *
+ * Provider detection:
+ * - Primary: Extract from ID token issuer field
+ * - Fallback: Use provider field in token data (if present)
+ * - Fallback: Use providerName parameter
+ * - Throws error if provider cannot be determined
+ *
+ * @throws Error if no ID token or access token is available
+ * @throws Error if provider cannot be determined
+ * @throws Error if userInfoEndpoint is required but not provided
+ *
+ * @example
+ * With ID token (provider auto-detected):
+ * ```typescript
+ * const { userInfo, provider } = await extractUserInfo(tokenData);
+ * console.log(`User ${userInfo.email} authenticated via ${provider}`);
+ * ```
+ *
+ * @example
+ * Without ID token (requires userInfoEndpoint):
+ * ```typescript
+ * const { userInfo, provider } = await extractUserInfo(
+ *   tokenData,
+ *   'https://api.example.com/user',
+ *   'custom'
+ * );
+ * ```
+ *
+ * @public
+ */
+export declare function extractUserInfo(tokenData: OAuthTokenResponse, userInfoEndpoint?: string, providerName?: string): Promise<{
+    userInfo: UserInfo;
+    provider: string;
+}>;
+
+/**
+ * Fetch user info from OAuth provider's userinfo endpoint
+ *
+ * @param accessToken - OAuth access token
+ * @param userInfoEndpoint - The provider's userinfo endpoint URL
+ * @param providerName - Provider name for error messages (optional)
+ * @returns User information from the provider
+ *
+ * @throws Error if the request fails or response is invalid
+ *
+ * @public
+ */
+export declare function fetchUserInfo(accessToken: string, userInfoEndpoint: string, providerName?: string): Promise<UserInfo>;
+
 /**
  * Interface for OAuth 2.0 and OpenID Connect provider implementations.
  *
@@ -694,6 +770,26 @@ export declare type ProviderConfig = {
     provider: IProvider;
 });
 
+/**
+ * Provider metadata passed to session strategy.
+ * Contains provider name and endpoints for user info extraction.
+ *
+ * @public
+ */
+export declare interface ProviderMetadata {
+    /** The provider name (e.g., 'google', 'github') */
+    name: string;
+    /** Provider endpoints */
+    endpoints: {
+        /** Authorization endpoint URL */
+        authorization: string;
+        /** Token endpoint URL */
+        token: string;
+        /** UserInfo endpoint URL */
+        userInfo: string;
+    };
+}
+
 /**
  * Helper type to create a configuration with only registered providers.
  * Use this with Lixa.createConfig() for type safety.
@@ -867,24 +963,27 @@ export declare interface SessionDao {
  * @example
  * Custom session strategy with database integration:
  * ```typescript
- * interface CustomSessionData extends OAuthTokenResponse {
+ * interface CustomSessionData {
  *   userId: string;
  *   email: string;
+ *   provider: string;
+ *   accessToken: string;
+ *   refreshToken?: string;
+ *   expiresAt: number;
  * }
  *
  * class DatabaseSessionStrategy implements SessionStrategy {
  *   constructor(private db: Database) {}
  *
- *   async createSession(tokenData: OAuthTokenResponse): Promise<Session<CustomSessionData>> {
- *     // Decode ID token for OIDC providers
- *     const idToken = tokenData.id_token;
- *     const payload = decodeJwt(idToken);
+ *   async createSession(oauthContext: OAuthContext): Promise<Session<CustomSessionData>> {
+ *     // User info is already extracted by Lixa!
+ *     const { userInfo, provider, tokenData } = oauthContext;
  *
  *     // Create or update user in database
  *     const user = await this.db.users.upsert({
- *       email: payload.email,
- *       name: payload.name,
- *       picture: payload.picture
+ *       email: userInfo.email,
+ *       name: userInfo.name,
+ *       picture: userInfo.picture
  *     });
  *
  *     // Generate session ID
@@ -904,7 +1003,10 @@ export declare interface SessionDao {
  *       raw: {
  *         userId: user.id,
  *         email: user.email,
- *         ...tokenData
+ *         provider,
+ *         accessToken: tokenData.access_token,
+ *         refreshToken: tokenData.refresh_token,
+ *         expiresAt: Date.now() + (tokenData.expires_in || 3600) * 1000
  *       }
  *     };
  *   }
@@ -918,14 +1020,14 @@ export declare interface SessionStrategy {
      * Creates a session from OAuth token data.
      *
      * @param tokenData - The token data received from the OAuth provider's token endpoint
+     * @param providerMetadata - Provider metadata including name and endpoints
      * @returns A Promise that resolves to a Session object
      *
      * @remarks
      * This method is called after successfully exchanging the authorization code
-     * for tokens. The tokenData parameter contains the raw response from the
-     * provider's token endpoint.
+     * for tokens. You receive:
      *
-     * Common token data fields:
+     * Token Data:
      * - access_token: OAuth access token
      * - refresh_token: OAuth refresh token (optional)
      * - expires_in: Token expiration time in seconds
@@ -933,6 +1035,28 @@ export declare interface SessionStrategy {
      * - id_token: OpenID Connect ID token (for OIDC providers)
      * - scope: Granted scopes
      *
+     * Provider Metadata:
+     * - name: The provider name (e.g., 'google', 'github')
+     * - endpoints: Provider endpoints (authorization, token, userInfo)
+     *
+     * The providerMetadata.endpoints.userInfo can be used with extractUserInfo():
+     * ```typescript
+     * import { extractUserInfo } from '@vunexa/lixa';
+     *
+     * const { userInfo } = await extractUserInfo(
+     *   tokenData,
+     *   providerMetadata.endpoints.userInfo,
+     *   providerMetadata.name
+     * );
+     * ```
+     *
+     * Your session strategy should:
+     * 1. Extract user info (using extractUserInfo or decode ID token)
+     * 2. Create or lookup users in your database
+     * 3. Generate session identifiers
+     * 4. Store session data as needed
+     * 5. Return a Session object with token and raw data
+     *
      * @throws \{Error\} If session creation fails (e.g., database error, invalid token)
      *
      * @example
@@ -945,8 +1069,35 @@ export declare interface SessionStrategy {
      *   };
      * }
      * ```
+     *
+     * @example
+     * Database integration with user info extraction:
+     * ```typescript
+     * async createSession(
+     *   tokenData: OAuthTokenResponse,
+     *   providerMetadata: ProviderMetadata
+     * ): Promise<Session> {
+     *   // Extract user info from token or userinfo endpoint
+     *   const { userInfo } = await extractUserInfo(
+     *     tokenData,
+     *     providerMetadata.endpoints.userInfo,
+     *     providerMetadata.name
+     *   );
+     *
+     *   // Create or update user in database
+     *   const user = await db.users.upsert({
+     *     email: userInfo.email,
+     *     name: userInfo.name
+     *   });
+     *
+     *   return {
+     *     token: generateSessionId(),
+     *     raw: { userId: user.id, provider: providerMetadata.name, ...tokenData }
+     *   };
+     * }
+     * ```
      */
-    createSession(tokenData: OAuthTokenResponse): Promise<Session>;
+    createSession(tokenData: OAuthTokenResponse, providerMetadata: ProviderMetadata): Promise<Session>;
 }
 
 /**
@@ -1096,4 +1247,21 @@ export declare interface StateData {
     createdAt: number;
 }
 
+/**
+ * User information extracted from OAuth provider
+ *
+ * @public
+ */
+export declare interface UserInfo {
+    email: string;
+    id?: string | undefined;
+    sub?: string | undefined;
+    given_name?: string | undefined;
+    family_name?: string | undefined;
+    name?: string | undefined;
+    picture?: string | undefined;
+    email_verified?: boolean | undefined;
+    iss?: string | undefined;
+}
+
 export { }

package/dist/index.cjs

@@ -31,7 +31,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   DefaultSessionStrategy: () => DefaultSessionStrategy,
-  Lixa: () => Lixa
+  Lixa: () => Lixa,
+  decodeIdToken: () => decodeIdToken,
+  determineProviderFromIssuer: () => determineProviderFromIssuer,
+  extractUserInfo: () => extractUserInfo,
+  fetchUserInfo: () => fetchUserInfo
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -84,9 +88,10 @@ var DefaultSessionStrategy = class {
    * Handles common OAuth token formats and extracts the access token.
    *
    * @param tokenData - The token data received from the OAuth provider
+   * @param providerMetadata - Provider metadata (not used in default implementation)
    * @returns A Promise that resolves to a Session object
    */
-  async createSession(tokenData) {
+  async createSession(tokenData, providerMetadata) {
     if (!tokenData.access_token || typeof tokenData.access_token !== "string") {
       throw new Error("No valid access token found in OAuth response");
     }
@@ -545,7 +550,15 @@ var Lixa = class _Lixa {
     );
     this.log("INFO", "Token", "Token exchange successful");
     this.log("INFO", "Session", "Creating user session");
-    const session = await this.sessionStrategy.createSession(tokens);
+    const providerMetadata = {
+      name: providerType,
+      endpoints: {
+        authorization: providerImpl.authorizationEndpoint,
+        token: providerImpl.tokenEndpoint,
+        userInfo: providerImpl.userInfoEndpoint
+      }
+    };
+    const session = await this.sessionStrategy.createSession(tokens, providerMetadata);
     const sessionId = (0, import_crypto.randomBytes)(32).toString("hex");
     this.log("INFO", "Session", "Storing session", { sessionId });
     await this.sesionDao.saveSession(sessionId, session, 86400);
@@ -601,9 +614,108 @@ var Lixa = class _Lixa {
     return void 0;
   }
 };
+
+// src/utils/user-info.ts
+function decodeIdToken(idToken) {
+  const parts = idToken.split(".");
+  if (parts.length !== 3) {
+    throw new Error("Invalid ID token format: expected 3 parts separated by dots");
+  }
+  const base64Payload = parts[1];
+  if (!base64Payload) {
+    throw new Error("Invalid ID token: missing payload section");
+  }
+  const payload = Buffer.from(base64Payload, "base64").toString();
+  try {
+    return JSON.parse(payload);
+  } catch (error) {
+    throw new Error("Invalid ID token: failed to parse payload JSON");
+  }
+}
+function determineProviderFromIssuer(userInfo) {
+  if (!userInfo.iss) {
+    return null;
+  }
+  const issuer = userInfo.iss.toLowerCase();
+  if (issuer.includes("accounts.google.com")) {
+    return "google";
+  }
+  if (issuer.includes("github")) {
+    return "github";
+  }
+  return null;
+}
+async function fetchUserInfo(accessToken, userInfoEndpoint, providerName) {
+  const response = await fetch(userInfoEndpoint, {
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      Accept: "application/json"
+    }
+  });
+  if (!response.ok) {
+    const providerLabel = providerName ? ` from ${providerName}` : "";
+    throw new Error(`Failed to fetch user info${providerLabel}: ${response.status} ${response.statusText}`);
+  }
+  const data = await response.json();
+  if (!data || typeof data !== "object" || !("email" in data) || typeof data.email !== "string") {
+    const providerLabel = providerName ? ` from ${providerName}` : "";
+    throw new Error(`Invalid user info response${providerLabel}: missing or invalid email`);
+  }
+  return {
+    email: data.email,
+    id: "id" in data ? String(data.id) : void 0,
+    sub: "sub" in data ? String(data.sub) : void 0,
+    given_name: "given_name" in data ? String(data.given_name) : void 0,
+    family_name: "family_name" in data ? String(data.family_name) : void 0,
+    name: "name" in data ? String(data.name) : void 0,
+    picture: "picture" in data ? String(data.picture) : void 0,
+    email_verified: "email_verified" in data ? Boolean(data.email_verified) : void 0,
+    iss: "iss" in data ? String(data.iss) : void 0
+  };
+}
+async function extractUserInfo(tokenData, userInfoEndpoint, providerName) {
+  let userInfo;
+  let provider = null;
+  if (tokenData.id_token) {
+    userInfo = decodeIdToken(tokenData.id_token);
+    provider = determineProviderFromIssuer(userInfo);
+    if (!provider && providerName) {
+      provider = providerName;
+    }
+  } else if (tokenData.access_token) {
+    if ("provider" in tokenData && typeof tokenData.provider === "string") {
+      provider = tokenData.provider;
+    } else if (providerName) {
+      provider = providerName;
+    }
+    if (!provider) {
+      throw new Error(
+        "Cannot determine OAuth provider: No ID token with issuer information, no provider field in token data, and no providerName provided. Unable to fetch user info."
+      );
+    }
+    if (!userInfoEndpoint) {
+      throw new Error(
+        `Cannot fetch user info for provider '${provider}': No ID token available and no userInfoEndpoint provided. Either ensure the provider returns an ID token or provide the userInfoEndpoint parameter.`
+      );
+    }
+    userInfo = await fetchUserInfo(tokenData.access_token, userInfoEndpoint, provider);
+  } else {
+    throw new Error("No ID token or access token available to fetch user info");
+  }
+  if (!provider) {
+    throw new Error(
+      "Cannot determine OAuth provider: ID token issuer not recognized and no provider name provided."
+    );
+  }
+  return { userInfo, provider };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DefaultSessionStrategy,
-  Lixa
+  Lixa,
+  decodeIdToken,
+  determineProviderFromIssuer,
+  extractUserInfo,
+  fetchUserInfo
 });
 //# sourceMappingURL=index.cjs.map