@vunexa/lixa 0.0.1-alpha.9 → 0.1.0

package/dist/dao/types.d.ts

@@ -1,6 +1,379 @@
-export interface StateDao {
-    saveState(state: string, data: any, expiresInSeconds: number): Promise<void>;
-    getState(state: string): Promise<any | null>;
+import type { Session } from "../models/session";
+/**
+ * OAuth state data structure.
+ *
+ * @remarks
+ * This structure is used internally by Lixa to store OAuth flow state
+ * during the authorization process. It contains the information needed
+ * to complete the PKCE flow and route callbacks to the correct provider.
+ *
+ * @public
+ */
+export interface StateData {
+    /**
+     * Provider name for callback routing.
+     * Used to identify which provider configuration to use when handling the callback.
+     *
+     * @example 'google', 'github', 'custom'
+     */
+    provider: string;
+    /**
+     * PKCE code verifier for secure token exchange.
+     * A cryptographically random string (64 hex characters) used in the PKCE flow
+     * to prevent authorization code interception attacks.
+     *
+     * @see RFC 7636 - Proof Key for Code Exchange
+     */
+    codeVerifier: string;
+    /**
+     * Unix timestamp in milliseconds when the state was created.
+     * Used for debugging and validation purposes.
+     */
+    createdAt: number;
+}
+/**
+ * State storage operations interface.
+ *
+ * @remarks
+ * Groups all state storage operations together. All methods must be implemented
+ * if this interface is provided.
+ *
+ * @public
+ */
+export interface StateStorage {
+    /**
+     * Saves OAuth state with expiration.
+     *
+     * @param state - The state parameter value (random string for CSRF protection)
+     * @param data - State data including provider name and PKCE code verifier
+     * @param expiresInSeconds - TTL in seconds (typically 300 for 5 minutes)
+     */
+    saveState(state: string, data: StateData, expiresInSeconds: number): Promise<void>;
+    /**
+     * Retrieves OAuth state data.
+     *
+     * @param state - The state parameter value
+     * @returns State data or null if not found or expired
+     */
+    getState(state: string): Promise<StateData | null>;
+    /**
+     * Deletes OAuth state (called after successful validation).
+     *
+     * @param state - The state parameter value
+     */
     deleteState(state: string): Promise<void>;
 }
+/**
+ * State handler for OAuth authorization flow.
+ *
+ * @remarks
+ * The StateHandler manages state generation and storage during the OAuth authorization flow.
+ *
+ * - GenerateState: Optional. Customizes how state parameters and PKCE verifiers are generated.
+ *   If not provided, uses default implementation (cryptographically secure random strings).
+ *
+ * - storage: Optional. Provides custom state storage (save/get/delete operations).
+ *   If not provided, uses in-memory cache (not suitable for production).
+ *
+ * For production, implement storage with Redis, database, or other distributed cache.
+ *
+ * @example
+ * Full implementation with Redis:
+ * ```typescript
+ * import { StateHandler, StateData } from '@vunexa/lixa';
+ *
+ * const stateHandler: StateHandler = {
+ *   GenerateState: async (provider) => {
+ *     const state = generateSecureRandomString(32);
+ *     const codeVerifier = generateSecureRandomString(64);
+ *     return {
+ *       state,
+ *       data: {
+ *         provider,
+ *         codeVerifier,
+ *         createdAt: Date.now()
+ *       }
+ *     };
+ *   },
+ *
+ *   storage: {
+ *     saveState: async (state, data, expiresInSeconds) => {
+ *       await redis.setex(`oauth:state:${state}`, expiresInSeconds, JSON.stringify(data));
+ *     },
+ *     getState: async (state) => {
+ *       const data = await redis.get(`oauth:state:${state}`);
+ *       return data ? JSON.parse(data) : null;
+ *     },
+ *     deleteState: async (state) => {
+ *       await redis.del(`oauth:state:${state}`);
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * Minimal implementation (uses defaults):
+ * ```typescript
+ * const stateHandler: StateHandler = {
+ *   storage: {
+ *     saveState: async (state, data, expiresInSeconds) => {
+ *       await redis.setex(state, expiresInSeconds, JSON.stringify(data));
+ *     },
+ *     getState: async (state) => {
+ *       const data = await redis.get(state);
+ *       return data ? JSON.parse(data) : null;
+ *     },
+ *     deleteState: async (state) => {
+ *       await redis.del(state);
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ */
+export interface StateHandler {
+    /**
+     * Generates OAuth state parameter and associated data.
+     *
+     * @param provider - The provider name for callback routing
+     * @returns A Promise that resolves to state string and state data
+     *
+     * @remarks
+     * This method generates:
+     * - state: A cryptographically secure random string for CSRF protection
+     * - codeVerifier: A PKCE code verifier for secure token exchange
+     * - createdAt: Timestamp for debugging
+     *
+     * If not provided, defaults to generating 32-byte hex strings for state
+     * and 64-byte hex strings for code verifier.
+     *
+     * @example
+     * ```typescript
+     * GenerateState: async (provider) => {
+     *   const state = crypto.randomBytes(16).toString('hex');
+     *   const codeVerifier = crypto.randomBytes(32).toString('hex');
+     *   return {
+     *     state,
+     *     data: {
+     *       provider,
+     *       codeVerifier,
+     *       createdAt: Date.now()
+     *     }
+     *   };
+     * }
+     * ```
+     */
+    generateState?(provider: string): Promise<{
+        state: string;
+        data: StateData;
+    }>;
+    /**
+     * State storage operations.
+     *
+     * @remarks
+     * Provides methods for saving, retrieving, and deleting OAuth state.
+     * All three methods must be implemented together.
+     *
+     * If not provided, uses in-memory cache (not suitable for production).
+     */
+    stateStorage?: StateStorage;
+}
+/**
+ * Session storage operations interface.
+ *
+ * @remarks
+ * Groups all session storage operations together. All methods must be implemented
+ * if this interface is provided.
+ *
+ * @public
+ */
+export interface SessionStorage {
+    /**
+     * Saves a session with expiration.
+     *
+     * @param sessionId - Unique session identifier
+     * @param session - Session data from GenerateSession()
+     * @param expiresInSeconds - TTL in seconds (typically 86400 for 24 hours)
+     */
+    saveSession<T extends Session>(sessionId: string, session: T, expiresInSeconds: number): Promise<void>;
+    /**
+     * Retrieves a session by ID.
+     *
+     * @param sessionId - Unique session identifier
+     * @returns Session data or null if not found or expired
+     */
+    getSession<T extends Session>(sessionId: string): Promise<T | null>;
+    /**
+     * Deletes a session (e.g., on logout).
+     *
+     * @param sessionId - Unique session identifier
+     */
+    deleteSession(sessionId: string): Promise<void>;
+    /**
+     * Optional helper to retrieve an active session by user email for account linking.
+     *
+     * @param email - Primary user email
+     */
+    getSessionByEmail?<T extends Session>(email: string): Promise<{
+        sessionId: string;
+        session: T;
+    } | null>;
+}
+/**
+ * Session handler for OAuth authentication.
+ *
+ * @remarks
+ * The SessionHandler manages session generation and storage after successful OAuth authentication.
+ *
+ * - GenerateSession: Optional. Customizes how OAuth tokens are converted into session data.
+ *   If not provided, uses default implementation (access token as session token).
+ *
+ * - storage: Optional. Provides custom session storage (save/get/delete operations).
+ *   If not provided, uses in-memory cache (not suitable for production).
+ *
+ * For production, implement both GenerateSession (for user creation/lookup) and storage
+ * (for persistent session storage with Redis, database, etc.).
+ *
+ * @example
+ * Full implementation with database:
+ * ```typescript
+ * import { SessionHandler, Session, OAuthTokenResponse, ProviderMetadata, extractUserInfo } from '@vunexa/lixa';
+ *
+ * const sessionHandler: SessionHandler = {
+ *   GenerateSession: async (tokenData, providerMetadata) => {
+ *     // Extract user info and create/retrieve user
+ *     const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+ *     const user = await db.users.upsert({
+ *       email: userInfo.email,
+ *       name: userInfo.name
+ *     });
+ *
+ *     // Return session data (not stored yet)
+ *     return {
+ *       token: tokenData.access_token,
+ *       raw: {
+ *         ...tokenData,
+ *         userId: user.id,
+ *         provider: providerMetadata.name
+ *       }
+ *     };
+ *   },
+ *
+ *   storage: {
+ *     saveSession: async (sessionId, session, expiresInSeconds) => {
+ *       const expiresAt = new Date(Date.now() + expiresInSeconds * 1000);
+ *       await db.sessions.create({
+ *         id: sessionId,
+ *         token: session.token,
+ *         data: session.raw,
+ *         expiresAt
+ *       });
+ *     },
+ *
+ *     getSession: async (sessionId) => {
+ *       const record = await db.sessions.findOne({
+ *         id: sessionId,
+ *         expiresAt: { $gt: new Date() }
+ *       });
+ *       return record ? { token: record.token, raw: record.data } : null;
+ *     },
+ *
+ *     deleteSession: async (sessionId) => {
+ *       await db.sessions.delete({ id: sessionId });
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * Minimal implementation (uses defaults):
+ * ```typescript
+ * const sessionHandler: SessionHandler = {
+ *   storage: {
+ *     saveSession: async (sessionId, session, expiresInSeconds) => {
+ *       await redis.setex(sessionId, expiresInSeconds, JSON.stringify(session));
+ *     },
+ *     getSession: async (sessionId) => {
+ *       const data = await redis.get(sessionId);
+ *       return data ? JSON.parse(data) : null;
+ *     },
+ *     deleteSession: async (sessionId) => {
+ *       await redis.del(sessionId);
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ */
+export interface SessionHandler {
+    /**
+     * Generates session data 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 session data
+     *
+     * @remarks
+     * This method is responsible for creating session data from OAuth tokens.
+     * It is called after successfully exchanging the authorization code for tokens.
+     *
+     * 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)
+     *
+     * Your implementation should:
+     * 1. Extract user info (using extractUserInfo or decode ID token)
+     * 2. Create or lookup users in your database
+     * 3. Build and return session data with any custom fields
+     *
+     * Note: This method should NOT store the session. Storage is handled by the storage object.
+     *
+     * If not provided, defaults to using the access token as the session token.
+     *
+     * @example
+     * ```typescript
+     * GenerateSession: async (tokenData, providerMetadata) => {
+     *   const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+     *   const user = await db.users.upsert({ email: userInfo.email });
+     *
+     *   return {
+     *     token: tokenData.access_token,
+     *     raw: {
+     *       ...tokenData,
+     *       userId: user.id,
+     *       provider: providerMetadata.name
+     *     }
+     *   };
+     * }
+     * ```
+     */
+    generateSession?<T extends Session>(tokenData: import('../models/session').OAuthTokenResponse, providerMetadata: import('../models/session').ProviderMetadata): Promise<T>;
+    /**
+     * Session storage operations.
+     *
+     * @remarks
+     * Provides methods for saving, retrieving, and deleting sessions.
+     * All three methods must be implemented together.
+     *
+     * If not provided, uses in-memory cache (not suitable for production).
+     */
+    sessionStorage?: SessionStorage;
+    /**
+     * Optional method to generate session data from OAuth tokens.
+     *
+     * @remarks
+     * If not provided, uses default implementation from LocalSessionHandler.
+     */
+    generateSession?<T extends Session>(tokenData: import('../models/session').OAuthTokenResponse, providerMetadata: import('../models/session').ProviderMetadata): Promise<T>;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/dao/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/dao/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;IAC7C,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/dao/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnF;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAEnD;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,aAAa,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC;IAE9E;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,WAAW,CAAC,CAAC,SAAS,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvG;;;;;OAKG;IACH,UAAU,CAAC,CAAC,SAAS,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEpE;;;;OAIG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhD;;;;OAIG;IACH,iBAAiB,CAAC,CAAC,CAAC,SAAS,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CACzG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACH,eAAe,CAAC,CAAC,CAAC,SAAS,OAAO,EAChC,SAAS,EAAE,OAAO,mBAAmB,EAAE,kBAAkB,EACzD,gBAAgB,EAAE,OAAO,mBAAmB,EAAE,gBAAgB,GAC7D,OAAO,CAAC,CAAC,CAAC,CAAC;IAEd;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;;;OAKG;IACH,eAAe,CAAC,CAAC,CAAC,SAAS,OAAO,EAChC,SAAS,EAAE,OAAO,mBAAmB,EAAE,kBAAkB,EACzD,gBAAgB,EAAE,OAAO,mBAAmB,EAAE,gBAAgB,GAC7D,OAAO,CAAC,CAAC,CAAC,CAAC;CACf"}