@vunexa/lixa 0.0.1-alpha.8 → 0.1.0

package/dist/models/session.d.ts

@@ -0,0 +1,316 @@
+/**
+ * OAuth 2.0 token response structure.
+ * Based on RFC 6749 Section 5.1 and OpenID Connect Core 1.0 Section 3.1.3.3
+ *
+ * @remarks
+ * This interface represents the standard OAuth 2.0 token response with
+ * optional OpenID Connect extensions. All OAuth providers should return
+ * at minimum the required fields (access_token, token_type).
+ *
+ * @public
+ */
+export interface OAuthTokenResponse {
+    /**
+     * OAuth 2.0 access token (required).
+     * Used to access protected resources on behalf of the user.
+     */
+    access_token: string;
+    /**
+     * Token type (required).
+     * Typically "Bearer" for OAuth 2.0.
+     */
+    token_type: string;
+    /**
+     * Token expiration time in seconds (optional).
+     * Time until the access token expires.
+     */
+    expires_in?: number;
+    /**
+     * OAuth 2.0 refresh token (optional).
+     * Used to obtain new access tokens without re-authentication.
+     */
+    refresh_token?: string;
+    /**
+     * Granted OAuth scopes (optional).
+     * Space-separated list of scopes that were granted.
+     */
+    scope?: string;
+    /**
+     * OpenID Connect ID token (optional).
+     * JWT containing user identity claims (only present for OIDC providers).
+     */
+    id_token?: string;
+    /**
+     * Additional provider-specific fields.
+     * Some providers may include extra fields like user_id, account_id, etc.
+     */
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Represents a linked provider account within a user's session.
+ *
+ * @public
+ */
+export interface LinkedAccount {
+    /** The provider identifier (e.g. 'github', 'google') */
+    provider: string;
+    /** Provider user ID if available */
+    providerUserId?: string | undefined;
+    /** User email for this provider */
+    email?: string | undefined;
+    /** OAuth access token for this provider */
+    accessToken: string;
+    /** Full raw token response from provider */
+    raw: OAuthTokenResponse;
+    /** Unix timestamp in milliseconds when account was linked */
+    linkedAt: number;
+}
+/**
+ * Represents a connected resource provider token (e.g. GitHub Repo access, Google Drive)
+ * obtained post-authentication via Lixa's Resource Connection API.
+ *
+ * @public
+ */
+export interface ConnectedResource {
+    /** The provider identifier (e.g. 'github', 'google', 'slack') */
+    provider: string;
+    /** Resource access token */
+    accessToken: string;
+    /** Optional refresh token for offline resource access */
+    refreshToken?: string | undefined;
+    /** Resource scopes granted by the user */
+    scopes: string[];
+    /** Full raw token response from provider */
+    raw: OAuthTokenResponse;
+    /** Unix timestamp in milliseconds when resource was connected */
+    connectedAt: number;
+}
+/**
+ * Represents a user session after successful OAuth authentication.
+ *
+ * @remarks
+ * The Session object is returned by SessionStrategy.createSession() and contains
+ * the session identifier and any additional data needed for your application.
+ *
+ * The structure is intentionally flexible to support various session management
+ * approaches (JWT tokens, session IDs, multi-SSO account linking, connected resources, etc.).
+ *
+ * @public
+ */
+export interface Session<TRaw = OAuthTokenResponse> {
+    /**
+     * Unique session ID generated by Lixa upon authentication.
+     */
+    id?: string;
+    /**
+     * The primary access token or session token identifier.
+     */
+    token: string;
+    /** Unique unified user ID across linked accounts */
+    userId?: string;
+    /** Primary user email */
+    email?: string;
+    /** Current active auth provider for this session turn */
+    provider?: string;
+    /** Linked SSO provider accounts keyed by provider name */
+    accounts?: Record<string, LinkedAccount>;
+    /** Connected third-party resource provider tokens keyed by provider name */
+    resources?: Record<string, ConnectedResource>;
+    /**
+     * Raw session data.
+     * Contains the complete OAuth token response and any additional data
+     * your SessionStrategy adds (user info, database IDs, etc.).
+     */
+    raw: TRaw;
+}
+/**
+ * Provider metadata passed to session strategy.
+ * Contains provider name and endpoints for user info extraction.
+ *
+ * @public
+ */
+export 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;
+    };
+}
+/**
+ * Strategy interface for custom session creation.
+ *
+ * @remarks
+ * Implement this interface to customize how OAuth tokens are converted into
+ * application sessions. This is where you typically:
+ * - Decode ID tokens (for OpenID Connect)
+ * - Look up or create users in your database
+ * - Generate session identifiers
+ * - Store session data
+ * - Add custom claims or metadata
+ *
+ * The default implementation (DefaultSessionStrategy) simply extracts the
+ * access token and returns it as the session token.
+ *
+ * @example
+ * Custom session strategy with database integration:
+ * ```typescript
+ * interface CustomSessionData {
+ *   userId: string;
+ *   email: string;
+ *   provider: string;
+ *   accessToken: string;
+ *   refreshToken?: string;
+ *   expiresAt: number;
+ * }
+ *
+ * class DatabaseSessionStrategy implements SessionStrategy {
+ *   constructor(private db: Database) {}
+ *
+ *   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: userInfo.email,
+ *       name: userInfo.name,
+ *       picture: userInfo.picture
+ *     });
+ *
+ *     // Generate session ID
+ *     const sessionId = generateSecureId();
+ *
+ *     // Store session with tokens
+ *     await this.db.sessions.create({
+ *       id: sessionId,
+ *       userId: user.id,
+ *       accessToken: tokenData.access_token,
+ *       refreshToken: tokenData.refresh_token,
+ *       expiresAt: new Date(Date.now() + (tokenData.expires_in || 3600) * 1000)
+ *     });
+ *
+ *     return {
+ *       token: sessionId,
+ *       raw: {
+ *         userId: user.id,
+ *         email: user.email,
+ *         provider,
+ *         accessToken: tokenData.access_token,
+ *         refreshToken: tokenData.refresh_token,
+ *         expiresAt: Date.now() + (tokenData.expires_in || 3600) * 1000
+ *       }
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export 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. You receive:
+     *
+     * Token Data:
+     * - access_token: OAuth access token
+     * - refresh_token: OAuth refresh token (optional)
+     * - expires_in: Token expiration time in seconds
+     * - token_type: Token type (usually "Bearer")
+     * - 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
+     * Simple implementation:
+     * ```typescript
+     * async createSession(tokenData: OAuthTokenResponse): Promise<Session> {
+     *   return {
+     *     token: tokenData.access_token,
+     *     raw: tokenData
+     *   };
+     * }
+     * ```
+     *
+     * @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, providerMetadata: ProviderMetadata): Promise<Session>;
+}
+/**
+ * Default session strategy that works with any OAuth provider.
+ * Extracts common token information and creates a standardized session.
+ *
+ * @public
+ */
+export declare class DefaultSessionStrategy implements SessionStrategy {
+    /**
+     * Creates a session from OAuth token data.
+     * 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, providerMetadata: ProviderMetadata): Promise<Session>;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/models/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/models/session.ts"],"names":[],"mappings":"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"}

package/dist/providers/IProvider.d.ts

@@ -1,18 +1,141 @@
 /**
- * Interface for OAuth provider implementations.
+ * Interface for OAuth 2.0 and OpenID Connect provider implementations.
  *
  * @remarks
  * Implement this interface to add support for custom OAuth providers.
+ * Each provider defines the three core endpoints required for the OAuth 2.0
+ * authorization code flow with PKCE.
+ *
+ * Built-in providers (Google, GitHub) are available in the \@vunexa/lixa-providers package.
+ *
+ * All implementations must comply with:
+ * - RFC 6749 (OAuth 2.0)
+ * - RFC 7636 (PKCE)
+ * - OpenID Connect Core 1.0 (for OIDC providers)
+ *
+ * @example
+ * Custom provider implementation:
+ * ```typescript
+ * import { IProvider } from '@vunexa/lixa';
+ *
+ * class CustomProvider implements IProvider {
+ *   authorizationEndpoint = 'https://auth.example.com/oauth/authorize';
+ *   tokenEndpoint = 'https://auth.example.com/oauth/token';
+ *   userInfoEndpoint = 'https://api.example.com/user';
+ * }
+ *
+ * // Use in configuration
+ * const lixa = new Lixa({
+ *   providers: {
+ *     custom: {
+ *       provider: new CustomProvider(),
+ *       clientId: 'your-client-id',
+ *       clientSecret: 'your-client-secret',
+ *       redirectUri: 'https://app.com/callback',
+ *       scopes: ['read:user']
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * Object literal provider:
+ * ```typescript
+ * const customProvider: IProvider = {
+ *   authorizationEndpoint: 'https://auth.example.com/oauth/authorize',
+ *   tokenEndpoint: 'https://auth.example.com/oauth/token',
+ *   userInfoEndpoint: 'https://api.example.com/user'
+ * };
+ * ```
  *
  * @public
  */
 interface IProvider {
-    /** The OAuth authorization endpoint URL */
+    /**
+     * The OAuth 2.0 authorization endpoint URL.
+     *
+     * @remarks
+     * This is the URL where users are redirected to authenticate and authorize your application.
+     * The endpoint must support the OAuth 2.0 authorization code flow with PKCE.
+     *
+     * Standard query parameters sent to this endpoint:
+     * - client_id: Your application's client ID
+     * - redirect_uri: Where to redirect after authorization
+     * - response_type: Always "code" for authorization code flow
+     * - scope: Space-separated list of requested scopes
+     * - state: Random string for CSRF protection
+     * - code_challenge: PKCE code challenge (SHA-256 hash)
+     * - code_challenge_method: Always "S256" for SHA-256
+     *
+     * @example
+     * ```typescript
+     * authorizationEndpoint = 'https://accounts.google.com/o/oauth2/v2/auth'
+     * ```
+     */
     authorizationEndpoint: string;
-    /** The OAuth token exchange endpoint URL */
+    /**
+     * The OAuth 2.0 token endpoint URL.
+     *
+     * @remarks
+     * This is the URL where authorization codes are exchanged for access tokens.
+     * The endpoint must support the OAuth 2.0 token exchange with PKCE.
+     *
+     * Standard parameters sent to this endpoint (POST request):
+     * - grant_type: Always "authorization_code"
+     * - code: The authorization code from the callback
+     * - redirect_uri: Must match the authorization request
+     * - client_id: Your application's client ID
+     * - client_secret: Your application's client secret
+     * - code_verifier: PKCE code verifier (original random string)
+     *
+     * Expected response:
+     * - access_token: OAuth access token
+     * - token_type: Token type (usually "Bearer")
+     * - expires_in: Token expiration time in seconds
+     * - refresh_token: Refresh token (optional)
+     * - id_token: OpenID Connect ID token (for OIDC providers)
+     * - scope: Granted scopes
+     *
+     * @example
+     * ```typescript
+     * tokenEndpoint = 'https://oauth2.googleapis.com/token'
+     * ```
+     */
     tokenEndpoint: string;
-    /** The user information endpoint URL */
+    /**
+     * The user information endpoint URL.
+     *
+     * @remarks
+     * This is the URL where user profile information can be retrieved using the access token.
+     * For OpenID Connect providers, this is the UserInfo endpoint.
+     *
+     * The endpoint is called with the access token in the Authorization header:
+     * ```
+     * Authorization: Bearer <access_token>
+     * ```
+     *
+     * Common response fields:
+     * - sub: Subject identifier (user ID)
+     * - email: User's email address
+     * - name: User's full name
+     * - picture: User's profile picture URL
+     * - email_verified: Whether email is verified
+     *
+     * Note: This endpoint is not called automatically by Lixa. Your SessionStrategy
+     * can call it if needed to fetch user profile information.
+     *
+     * @example
+     * ```typescript
+     * userInfoEndpoint = 'https://www.googleapis.com/oauth2/v2/userinfo'
+     * ```
+     */
     userInfoEndpoint: string;
+    /**
+     * Minimal authentication scopes required for identity verification (AuthN).
+     *
+     * @example ['openid', 'email', 'profile'] or ['read:user', 'user:email']
+     */
+    authScopes?: string[];
 }
 export { IProvider };
 //# sourceMappingURL=IProvider.d.ts.map

package/dist/providers/IProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IProvider.d.ts","sourceRoot":"","sources":["../../src/providers/IProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,UAAU,SAAS;IACjB,2CAA2C;IAC3C,qBAAqB,EAAE,MAAM,CAAC;IAC9B,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"IProvider.d.ts","sourceRoot":"","sources":["../../src/providers/IProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,UAAU,SAAS;IACjB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,qBAAqB,EAAE,MAAM,CAAC;IAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/providers/index.d.ts

@@ -1,4 +1,2 @@
 export { IProvider } from "./IProvider";
-export { GithubProvider } from "./github";
-export { GoogleProvider } from "./google";
 //# sourceMappingURL=index.d.ts.map

package/dist/providers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}