@vunexa/lixa 0.0.1-alpha.19 → 0.0.1-alpha.21

package/dist/dao/types.d.ts

@@ -1,11 +1,245 @@
+/**
+ * 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;
+}
+/**
+ * Data access object for OAuth state storage.
+ *
+ * @remarks
+ * State storage is used during the OAuth authorization flow to:
+ * - Prevent CSRF attacks by validating the state parameter
+ * - Store PKCE code verifiers for secure token exchange
+ * - Maintain OAuth flow context across HTTP requests
+ *
+ * State data must persist across HTTP requests and support TTL (time-to-live).
+ * The default implementation uses in-memory cache, which is not suitable for production
+ * environments with multiple server instances or server restarts.
+ *
+ * For production, implement this interface with a distributed cache like Redis,
+ * or a database with TTL support.
+ *
+ * @example
+ * Redis implementation:
+ * ```typescript
+ * class RedisStateDao implements StateDao {
+ *   constructor(private redis: RedisClient) {}
+ *
+ *   async saveState(state: string, data: any, expiresInSeconds: number): Promise<void> {
+ *     await this.redis.setex(`oauth:state:${state}`, expiresInSeconds, JSON.stringify(data));
+ *   }
+ *
+ *   async getState(state: string): Promise<any | null> {
+ *     const data = await this.redis.get(`oauth:state:${state}`);
+ *     return data ? JSON.parse(data) : null;
+ *   }
+ *
+ *   async deleteState(state: string): Promise<void> {
+ *     await this.redis.del(`oauth:state:${state}`);
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface StateDao {
-    saveState(state: string, data: any, expiresInSeconds: number): Promise<void>;
-    getState(state: string): Promise<any | null>;
+    /**
+     * 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)
+     *
+     * @remarks
+     * The data object MUST include the following required fields:
+     * - **provider** (string): Provider name for callback routing (e.g., 'google', 'github')
+     * - **codeVerifier** (string): PKCE code verifier for secure token exchange (64 hex characters)
+     * - **createdAt** (number): Unix timestamp in milliseconds for debugging and validation
+     *
+     * These fields are automatically populated by Lixa during the authorization flow.
+     * The state is stored when generating the authorization URL and retrieved during
+     * the OAuth callback to complete the PKCE flow.
+     *
+     * @see {@link StateData} for the complete state data structure
+     *
+     * @example
+     * ```typescript
+     * await stateDao.saveState('random-state-123', {
+     *   provider: 'google',
+     *   codeVerifier: 'abc123...',
+     *   createdAt: Date.now()
+     * }, 300);
+     * ```
+     */
+    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
+     *
+     * @remarks
+     * This method is called during the OAuth callback to validate the state
+     * parameter and retrieve the PKCE code verifier for token exchange.
+     *
+     * The returned data will include:
+     * - provider: Provider name for routing
+     * - codeVerifier: PKCE code verifier for token exchange
+     * - createdAt: Timestamp when state was created
+     *
+     * @see {@link StateData} for the complete state data structure
+     *
+     * @example
+     * ```typescript
+     * const stateData = await stateDao.getState('random-state-123');
+     * if (!stateData) {
+     *   throw new Error('Invalid or expired state');
+     * }
+     * console.log(stateData.provider); // 'google'
+     * console.log(stateData.codeVerifier); // 'abc123...'
+     * ```
+     */
+    getState(state: string): Promise<StateData | null>;
+    /**
+     * Deletes OAuth state (called after successful validation).
+     *
+     * @param state - The state parameter value
+     *
+     * @remarks
+     * This method should be called after successfully validating the state
+     * to prevent replay attacks. State should only be usable once.
+     *
+     * @example
+     * ```typescript
+     * await stateDao.deleteState('random-state-123');
+     * ```
+     */
     deleteState(state: string): Promise<void>;
 }
+/**
+ * Data access object for session storage.
+ *
+ * @remarks
+ * Session storage is used to persist user sessions after successful OAuth authentication.
+ * Sessions must persist across HTTP requests and support TTL (time-to-live).
+ *
+ * The default implementation uses in-memory cache, which is not suitable for production
+ * environments with multiple server instances or server restarts.
+ *
+ * For production, implement this interface with a distributed cache like Redis,
+ * a database, or a session store like express-session.
+ *
+ * @example
+ * Database implementation:
+ * ```typescript
+ * class DatabaseSessionDao implements SessionDao {
+ *   constructor(private db: Database) {}
+ *
+ *   async saveSession(sessionId: string, session: Session, expiresInSeconds: number): Promise<void> {
+ *     const expiresAt = new Date(Date.now() + expiresInSeconds * 1000);
+ *     await this.db.sessions.create({
+ *       id: sessionId,
+ *       token: session.token,
+ *       data: session.raw,
+ *       expiresAt
+ *     });
+ *   }
+ *
+ *   async getSession(sessionId: string): Promise<Session | null> {
+ *     const record = await this.db.sessions.findOne({
+ *       id: sessionId,
+ *       expiresAt: { $gt: new Date() }
+ *     });
+ *     return record ? { token: record.token, raw: record.data } : null;
+ *   }
+ *
+ *   async deleteSession(sessionId: string): Promise<void> {
+ *     await this.db.sessions.delete({ id: sessionId });
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface SessionDao {
-    saveSession(session: string, data: any, expiresInSeconds: number): Promise<void>;
-    getSession(session: string): Promise<any | null>;
-    deleteSession(session: string): Promise<void>;
+    /**
+     * Saves a session with expiration.
+     *
+     * @param sessionId - Unique session identifier
+     * @param data - Session data from SessionStrategy.createSession()
+     * @param expiresInSeconds - TTL in seconds (typically 86400 for 24 hours)
+     *
+     * @remarks
+     * The session data structure is defined by your SessionStrategy implementation.
+     * The default strategy returns \{ token: string, raw: any \}.
+     *
+     * @example
+     * ```typescript
+     * await sessionDao.saveSession('session-123', \{
+     *   token: 'access-token',
+     *   raw: \{ userId: '456', email: 'user\@example.com' \}
+     * \}, 86400);
+     * ```
+     */
+    saveSession(sessionId: string, data: any, expiresInSeconds: number): Promise<void>;
+    /**
+     * Retrieves a session by ID.
+     *
+     * @param sessionId - Unique session identifier
+     * @returns Session data or null if not found or expired
+     *
+     * @remarks
+     * This method is called to retrieve user session data for authenticated requests.
+     *
+     * @example
+     * ```typescript
+     * const session = await sessionDao.getSession('session-123');
+     * if (!session) {
+     *   throw new Error('Session not found or expired');
+     * }
+     * ```
+     */
+    getSession(sessionId: string): Promise<any | null>;
+    /**
+     * Deletes a session (e.g., on logout).
+     *
+     * @param sessionId - Unique session identifier
+     *
+     * @remarks
+     * This method should be called when a user logs out to invalidate their session.
+     *
+     * @example
+     * ```typescript
+     * await sessionDao.deleteSession('session-123');
+     * ```
+     */
+    deleteSession(sessionId: string): Promise<void>;
 }
 //# 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;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjF,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;IACjD,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/dao/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnF;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAEnD;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnF;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;IAEnD;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD"}