@plyaz/auth 1.0.0

package/src/tokens/refresh-token-manager.ts

@@ -0,0 +1,448 @@
+/* eslint-disable no-unused-vars */
+/* eslint-disable no-magic-numbers */
+/**
+ * @fileoverview Refresh token manager for @plyaz/auth
+ * @module @plyaz/auth/tokens/refresh-token-manager
+ * 
+ * @description
+ * Manages refresh token lifecycle including generation, validation, rotation,
+ * and revocation. Implements security best practices like token rotation
+ * and family tracking to prevent token theft and replay attacks.
+ * 
+ * @example
+ * ```typescript
+ * import { RefreshTokenManager } from '@plyaz/auth';
+ * 
+ * const manager = new RefreshTokenManager({
+ *   secretKey: 'your-secret-key',
+ *   tokenTTL: 604800, // 7 days
+ *   enableRotation: true
+ * });
+ * 
+ * const tokens = await manager.generateTokenPair(userId, sessionId);
+ * ```
+ */
+
+import { sign, verify } from 'jsonwebtoken';
+import { randomBytes } from 'crypto';
+import { TokenBlacklist } from '../core/blacklist/token.blacklist';
+import { AuthenticationError } from '@plyaz/errors';
+
+
+/**
+ * Refresh token manager configuration
+ */
+export interface RefreshTokenManagerConfig {
+  /** Secret key for signing tokens */
+  secretKey: string;
+  /** Refresh token TTL in seconds */
+  tokenTTL: number;
+  /** Access token TTL in seconds */
+  accessTokenTTL: number;
+  /** Token issuer */
+  issuer: string;
+  /** Token audience */
+  audience: string;
+  /** Enable token rotation */
+  enableRotation: boolean;
+  /** Enable token family tracking */
+  enableFamilyTracking: boolean;
+  /** Maximum token family size */
+  maxFamilySize: number;
+}
+
+/**
+ * Token pair (access + refresh)
+ */
+export interface TokenPair {
+  /** Access token */
+  accessToken: string;
+  /** Refresh token */
+  refreshToken: string;
+  /** Access token expiration */
+  accessTokenExpiresAt: Date;
+  /** Refresh token expiration */
+  refreshTokenExpiresAt: Date;
+}
+
+/**
+ * Refresh token payload
+ */
+export interface RefreshTokenPayload {
+  /** User ID */
+  sub: string;
+  /** Session ID */
+  sessionId: string;
+  /** Token family ID (for rotation tracking) */
+  family?: string;
+  /** Token generation number */
+  generation?: number;
+  /** Token type */
+  type: 'refresh';
+  /** Issued at */
+  iat: number;
+  /** Expires at */
+  exp: number;
+  /** Issuer */
+  iss: string;
+  /** Audience */
+  aud: string;
+}
+
+/**
+ * Access token payload
+ */
+export interface AccessTokenPayload {
+  /** User ID */
+  sub: string;
+  /** Session ID */
+  sessionId: string;
+  /** User roles */
+  roles?: string[];
+  /** User permissions */
+  permissions?: string[];
+  /** Token type */
+  type: 'access';
+  /** Issued at */
+  iat: number;
+  /** Expires at */
+  exp: number;
+  /** Issuer */
+  iss: string;
+  /** Audience */
+  aud: string;
+}
+
+/**
+ * Token family for rotation tracking
+ */
+interface TokenFamily {
+  /** Family ID */
+  id: string;
+  /** User ID */
+  userId: string;
+  /** Session ID */
+  sessionId: string;
+  /** Current generation */
+  generation: number;
+  /** Created at */
+  createdAt: Date;
+  /** Last used at */
+  lastUsedAt: Date;
+}
+
+/**
+ * Refresh token manager implementation
+ * Handles refresh token lifecycle with security features
+ */
+export class RefreshTokenManager {
+  private readonly config: RefreshTokenManagerConfig;
+  private readonly blacklist: TokenBlacklist;
+  private readonly tokenFamilies = new Map<string, TokenFamily>();
+
+  constructor(config: RefreshTokenManagerConfig) {
+    this.config = config;
+    this.blacklist = new TokenBlacklist({ keyPrefix: 'token:', defaultTTL: 3600 });
+  }
+
+  /**
+   * Generate new token pair (access + refresh)
+   * @param userId - User identifier
+   * @param sessionId - Session identifier
+   * @param userRoles - User roles for access token
+   * @param userPermissions - User permissions for access token
+   * @returns Token pair
+   */
+  async generateTokenPair(
+    userId: string,
+    sessionId: string,
+    userRoles?: string[],
+    userPermissions?: string[]
+  ): Promise<TokenPair> {
+    const now = Math.floor(Date.now() / 1000);
+    const accessTokenExp = now + this.config.accessTokenTTL;
+    const refreshTokenExp = now + this.config.tokenTTL;
+
+    // Generate token family if rotation is enabled
+    let family: string | undefined;
+    let generation = 1;
+
+    if (this.config.enableFamilyTracking) {
+      family = this.generateFamilyId();
+      this.tokenFamilies.set(family, {
+        id: family,
+        userId,
+        sessionId,
+        generation,
+        createdAt: new Date(),
+        lastUsedAt: new Date()
+      });
+    }
+
+    // Create access token payload
+    const accessPayload: AccessTokenPayload = {
+      sub: userId,
+      sessionId,
+      roles: userRoles,
+      permissions: userPermissions,
+      type: 'access',
+      iat: now,
+      exp: accessTokenExp,
+      iss: this.config.issuer,
+      aud: this.config.audience
+    };
+
+    // Create refresh token payload
+    const refreshPayload: RefreshTokenPayload = {
+      sub: userId,
+      sessionId,
+      family,
+      generation,
+      type: 'refresh',
+      iat: now,
+      exp: refreshTokenExp,
+      iss: this.config.issuer,
+      aud: this.config.audience
+    };
+
+    // Sign tokens
+    const accessToken = sign(accessPayload, this.config.secretKey, { algorithm: 'HS256' });
+    const refreshToken = sign(refreshPayload, this.config.secretKey, { algorithm: 'HS256' });
+
+    return {
+      accessToken,
+      refreshToken,
+      accessTokenExpiresAt: new Date(accessTokenExp * 1000),
+      refreshTokenExpiresAt: new Date(refreshTokenExp * 1000)
+    };
+  }
+
+  /**
+   * Refresh token pair using refresh token
+   * @param refreshToken - Current refresh token
+   * @param userRoles - Updated user roles
+   * @param userPermissions - Updated user permissions
+   * @returns New token pair
+   */
+  async refreshTokenPair(
+    refreshToken: string,
+    userRoles?: string[],
+    userPermissions?: string[]
+  ): Promise<TokenPair> {
+    // Validate refresh token
+    const payload = await this.validateRefreshToken(refreshToken);
+
+    // Check token family if rotation is enabled
+    if (this.config.enableFamilyTracking && payload.family) {
+      await this.validateTokenFamily(payload);
+    }
+
+    // Revoke old refresh token if rotation is enabled
+    if (this.config.enableRotation) {
+      await this.blacklist.add(refreshToken, payload.exp);
+    }
+
+    // Generate new token pair
+    const newTokenPair = await this.generateTokenPair(
+      payload.sub,
+      payload.sessionId,
+      userRoles,
+      userPermissions
+    );
+
+    // Update token family
+    if (this.config.enableFamilyTracking && payload.family) {
+      const family = this.tokenFamilies.get(payload.family);
+      if (family) {
+        family.generation++;
+        family.lastUsedAt = new Date();
+        
+        // Enforce family size limit
+        if (family.generation > this.config.maxFamilySize) {
+          await this.revokeTokenFamily(payload.family);
+          throw new AuthenticationError('AUTH_TOKEN_INVALID');
+        }
+      }
+    }
+
+    return newTokenPair;
+  }
+
+  /**
+   * Validate refresh token
+   * @param refreshToken - Refresh token to validate
+   * @returns Decoded payload
+   */
+  async validateRefreshToken(refreshToken: string): Promise<RefreshTokenPayload> {
+    try {
+      // Check if token is blacklisted
+      if (await this.blacklist.isBlacklisted(refreshToken)) {
+        throw new AuthenticationError('AUTH_TOKEN_REVOKED');
+      }
+
+      // Verify token
+      const payload = verify(refreshToken, this.config.secretKey, {
+        issuer: this.config.issuer,
+        audience: this.config.audience,
+        algorithms: ['HS256']
+      }) as RefreshTokenPayload;
+
+      // Validate token type
+      if (payload.type !== 'refresh') {
+        throw new AuthenticationError('AUTH_TOKEN_INVALID');
+      }
+
+      return payload;
+
+    } catch (error) {
+  if (error instanceof Error) {
+    if (error.name === 'TokenExpiredError') {
+      throw new AuthenticationError('AUTH_TOKEN_EXPIRED');
+    }
+
+    if (error.name === 'JsonWebTokenError') {
+      throw new AuthenticationError('AUTH_TOKEN_INVALID');
+    }
+  }
+
+  throw error;
+}
+
+  }
+
+  /**
+   * Revoke refresh token
+   * @param refreshToken - Refresh token to revoke
+   */
+  async revokeRefreshToken(refreshToken: string): Promise<void> {
+    try {
+      const payload = await this.validateRefreshToken(refreshToken);
+      
+      // Add to blacklist
+      await this.blacklist.add(refreshToken, payload.exp);
+
+      // Revoke entire token family if enabled
+      if (this.config.enableFamilyTracking && payload.family) {
+        await this.revokeTokenFamily(payload.family);
+      }
+
+    } catch (error) {
+      // Token might already be invalid, but still try to blacklist
+      await this.blacklist.add(refreshToken, Math.floor(Date.now() / 1000) + 3600);
+    }
+  }
+
+  /**
+   * Revoke all refresh tokens for a user
+   * @param userId - User identifier
+   */
+  async revokeAllUserTokens(userId: string): Promise<void> {
+    // Revoke all token families for user
+    for (const [familyId, family] of this.tokenFamilies.entries()) {
+      if (family.userId === userId) {
+        await this.revokeTokenFamily(familyId);
+      }
+    }
+  }
+
+  /**
+   * Revoke all refresh tokens for a session
+   * @param sessionId - Session identifier
+   */
+  async revokeSessionTokens(sessionId: string): Promise<void> {
+    // Revoke all token families for session
+    for (const [familyId, family] of this.tokenFamilies.entries()) {
+      if (family.sessionId === sessionId) {
+        await this.revokeTokenFamily(familyId);
+      }
+    }
+  }
+
+  /**
+   * Get token family information
+   * @param familyId - Token family identifier
+   * @returns Token family or null
+   */
+  getTokenFamily(familyId: string): TokenFamily | null {
+    return this.tokenFamilies.get(familyId) ?? null;
+  }
+
+  /**
+   * Clean up expired token families
+   * @returns Number of cleaned families
+   */
+  async cleanupExpiredFamilies(): Promise<number> {
+    let cleanedCount = 0;
+    const now = new Date();
+    const expiredFamilies: string[] = [];
+
+    for (const [familyId, family] of this.tokenFamilies.entries()) {
+      // Consider family expired if not used for longer than token TTL
+      const expiredTime = new Date(family.lastUsedAt.getTime() + this.config.tokenTTL * 1000);
+      if (expiredTime < now) {
+        expiredFamilies.push(familyId);
+      }
+    }
+
+    for (const familyId of expiredFamilies) {
+      this.tokenFamilies.delete(familyId);
+      cleanedCount++;
+    }
+
+    return cleanedCount;
+  }
+
+  /**
+   * Validate token family for rotation security
+   * @param payload - Refresh token payload
+   * @private
+   */
+  private async validateTokenFamily(payload: RefreshTokenPayload): Promise<void> {
+    if (!payload.family) {
+      return;
+    }
+
+    const family = this.tokenFamilies.get(payload.family);
+    
+    if (!family) {
+      throw new AuthenticationError('AUTH_TOKEN_INVALID');
+    }
+
+    // Check if token generation is valid
+    if (payload.generation !== family.generation) {
+      // Potential token theft - revoke entire family
+      await this.revokeTokenFamily(payload.family);
+      throw new AuthenticationError('AUTH_TOKEN_REVOKED');
+    }
+
+    // Check if user and session match
+    if (family.userId !== payload.sub || family.sessionId !== payload.sessionId) {
+      await this.revokeTokenFamily(payload.family);
+      throw new AuthenticationError('AUTH_TOKEN_REVOKED');
+    }
+  }
+
+  /**
+   * Revoke entire token family
+   * @param familyId - Token family identifier
+   * @private
+   */
+  private async revokeTokenFamily(familyId: string): Promise<void> {
+    const family = this.tokenFamilies.get(familyId);
+    
+    if (family) {
+      // In a real implementation, this would blacklist all tokens in the family
+      // For now, we just remove the family tracking
+      this.tokenFamilies.delete(familyId);
+    }
+  }
+
+  /**
+   * Generate unique family ID
+   * @returns Family identifier
+   * @private
+   */
+  private generateFamilyId(): string {
+    return randomBytes(16).toString('hex');
+  }
+}