@nauth-toolkit/core 0.1.0 → 0.1.5

package/src/services/trusted-device.service.ts

@@ -1,339 +0,0 @@
-import { Repository } from 'typeorm';
-import { NAuthConfig } from '../interfaces/config.interface';
-import { NAuthLogger } from '../utils/nauth-logger';
-import { createHash } from 'crypto';
-import { BaseTrustedDevice } from '../entities/trusted-device.entity';
-
-/**
- * Trusted Device Service
- *
- * Manages device trust for "remember device" feature.
- * Devices can be trusted after successful MFA verification, allowing
- * users to skip MFA for a configured period (rememberDeviceDays).
- *
- * Security:
- * - Device tokens are server-generated UUIDs
- * - Only hash stored in database (SHA-256)
- * - Tokens persist across logouts and session expiry
- * - Independent of refresh token lifecycle
- *
- * @example
- * ```typescript
- * // Mark device as trusted after MFA
- * const deviceToken = await trustedDeviceService.createTrustedDevice(
- *   userId,
- *   deviceName,
- *   deviceType,
- *   ipAddress,
- *   userAgent,
- *   platform,
- *   browser
- * );
- *
- * // Check if device is trusted
- * const isTrusted = await trustedDeviceService.isDeviceTrusted(
- *   deviceToken,
- *   userId
- * );
- * ```
- */
-export class TrustedDeviceService {
-  constructor(
-    private readonly config: NAuthConfig,
-    private readonly logger: NAuthLogger,
-    private readonly trustedDeviceRepository?: Repository<BaseTrustedDevice>,
-  ) {}
-
-  /**
-   * Create trusted device record
-   *
-   * Generates a secure device token, stores its hash in database,
-   * and returns the plain token for client storage.
-   *
-   * @param userId - Internal user ID
-   * @param deviceName - Optional device name
-   * @param deviceType - Optional device type (mobile/desktop/tablet)
-   * @param ipAddress - IP address when device was trusted
-   * @param userAgent - User agent string
-   * @param platform - Platform from user agent
-   * @param browser - Browser from user agent
-   * @returns Device token (UUID) to be stored by client
-   *
-   * @throws {Error} If rememberDevice is not enabled or repository not available
-   */
-  async createTrustedDevice(
-    userId: number,
-    deviceName?: string | null,
-    deviceType?: string | null,
-    ipAddress?: string | null,
-    userAgent?: string | null,
-    platform?: string | null,
-    browser?: string | null,
-  ): Promise<string> {
-    if (!this.config.mfa?.rememberDevices || this.config.mfa.rememberDevices === 'never') {
-      throw new Error('rememberDevices is not enabled in configuration');
-    }
-
-    if (!this.trustedDeviceRepository) {
-      this.logger?.warn?.('TrustedDeviceRepository not available - trusted device feature disabled');
-      throw new Error('TrustedDeviceRepository not available');
-    }
-
-    // Generate secure device token (UUID v4)
-    const crypto = await import('crypto');
-    const deviceToken = crypto.randomUUID();
-
-    // Hash token for storage (SHA-256)
-    const deviceTokenHash = this.hashDeviceToken(deviceToken);
-
-    // Calculate expiry (now + rememberDeviceDays)
-    // Only applicable if rememberDevices is not 'never'
-    const rememberDeviceDays = this.config.mfa.rememberDeviceDays || 30;
-    const trustedUntil = new Date();
-    trustedUntil.setDate(trustedUntil.getDate() + rememberDeviceDays);
-
-    // Check if device already trusted (by hash)
-    const existing = await this.trustedDeviceRepository.findOne({
-      where: {
-        userId,
-        deviceTokenHash,
-      },
-    });
-
-    if (existing) {
-      // Update existing record
-      await this.trustedDeviceRepository.update(
-        { userId, deviceTokenHash },
-        {
-          trustedUntil,
-          lastUsedAt: new Date(),
-          deviceName: deviceName || null,
-          deviceType: deviceType || null,
-          ipAddress: ipAddress || null,
-          userAgent: userAgent || null,
-          platform: platform || null,
-          browser: browser || null,
-        },
-      );
-      this.logger?.debug?.(`Updated trusted device for user ${userId}`);
-      return deviceToken;
-    }
-
-    // Create new trusted device record
-    const trustedDevice = this.trustedDeviceRepository.create({
-      userId,
-      deviceTokenHash,
-      deviceId: null, // Not used, kept for backward compatibility
-      deviceName: deviceName || null,
-      deviceType: deviceType || null,
-      ipAddress: ipAddress || null,
-      userAgent: userAgent || null,
-      platform: platform || null,
-      browser: browser || null,
-      trustedUntil,
-      lastUsedAt: new Date(),
-    });
-
-    await this.trustedDeviceRepository.save(trustedDevice);
-    this.logger?.debug?.(`Created trusted device for user ${userId}, expires ${trustedUntil.toISOString()}`);
-
-    return deviceToken;
-  }
-
-  /**
-   * Check if device is trusted
-   *
-   * Validates device token against trusted devices table.
-   * Updates lastUsedAt if device is found and valid.
-   *
-   * Security:
-   * - Returns false for invalid/tampered tokens (silent - MFA required)
-   * - Detection of tampered tokens should be handled by caller for audit logging
-   *
-   * @param deviceToken - Device token from client (plain UUID)
-   * @param userId - Internal user ID
-   * @returns True if device is trusted and not expired
-   */
-  async isDeviceTrusted(deviceToken: string | null | undefined, userId: number): Promise<boolean> {
-    if (!deviceToken || !this.trustedDeviceRepository) {
-      return false;
-    }
-
-    if (!this.config.mfa?.rememberDevices || this.config.mfa.rememberDevices === 'never') {
-      return false;
-    }
-
-    // Hash token for lookup
-    const deviceTokenHash = this.hashDeviceToken(deviceToken);
-
-    // Find trusted device
-    const trustedDevice = await this.trustedDeviceRepository.findOne({
-      where: {
-        userId,
-        deviceTokenHash,
-      },
-    });
-
-    if (!trustedDevice) {
-      // Device token not found - could be tampered/fake
-      // Caller should check if token was provided and audit suspicious activity
-      return false;
-    }
-
-    // Check if trust has expired
-    const trustedUntil = trustedDevice.trustedUntil;
-    if (new Date() > new Date(trustedUntil)) {
-      // Trust expired - delete record
-      await this.trustedDeviceRepository.delete({
-        userId,
-        deviceTokenHash,
-      });
-      this.logger?.debug?.(`Trusted device expired for user ${userId}`);
-      return false;
-    }
-
-    // Update lastUsedAt with throttling to reduce write load
-    const lastUsedAt = trustedDevice.lastUsedAt;
-    const now = new Date();
-    const fifteenMinutesMs = 15 * 60 * 1000;
-    if (!lastUsedAt || now.getTime() - new Date(lastUsedAt).getTime() > fifteenMinutesMs) {
-      await this.trustedDeviceRepository.update({ userId, deviceTokenHash }, { lastUsedAt: now });
-    }
-
-    return true;
-  }
-
-  /**
-   * Validate device token and detect tampering attempts
-   *
-   * Checks if device token is valid and returns validation result.
-   * Used to detect suspicious tampered/fake token attempts for audit logging.
-   *
-   * @param deviceToken - Device token from client (can be null/undefined)
-   * @param userId - Internal user ID
-   * @returns Validation result with suspicious flag
-   */
-  async validateDeviceToken(
-    deviceToken: string | null | undefined,
-    userId: number,
-  ): Promise<{ isValid: boolean; isSuspicious: boolean }> {
-    // No token provided - not suspicious (user just doesn't have trusted device)
-    if (!deviceToken) {
-      return { isValid: false, isSuspicious: false };
-    }
-
-    // Check if trusted
-    const isTrusted = await this.isDeviceTrusted(deviceToken, userId);
-
-    // If token was provided but not trusted, it's suspicious (tampered/fake)
-    const isSuspicious = !isTrusted && deviceToken !== null && deviceToken !== undefined;
-
-    return { isValid: isTrusted, isSuspicious };
-  }
-
-  /**
-   * Revoke trusted device
-   *
-   * Removes device from trusted devices table.
-   * Used when user explicitly untrusts a device.
-   *
-   * @param deviceToken - Device token to revoke
-   * @param userId - Internal user ID
-   */
-  async revokeTrustedDevice(deviceToken: string, userId: number): Promise<void> {
-    if (!this.trustedDeviceRepository) {
-      return;
-    }
-
-    const deviceTokenHash = this.hashDeviceToken(deviceToken);
-    await this.trustedDeviceRepository.delete({
-      userId,
-      deviceTokenHash,
-    });
-
-    this.logger?.debug?.(`Revoked trusted device for user ${userId}`);
-  }
-
-  /**
-   * Get user's trusted devices
-   *
-   * Returns list of trusted devices for management UI.
-   *
-   * @param userId - Internal user ID
-   * @returns Array of trusted device records (without tokens)
-   */
-  async getUserTrustedDevices(userId: number): Promise<Omit<BaseTrustedDevice, 'deviceTokenHash'>[]> {
-    if (!this.trustedDeviceRepository) {
-      return [];
-    }
-
-    const devices = await this.trustedDeviceRepository.find({
-      where: { userId },
-      order: { lastUsedAt: 'DESC' },
-    });
-
-    // Filter expired devices
-    const now = new Date();
-    const validDevices = devices.filter((d) => new Date(d.trustedUntil) > now);
-
-    // Return without sensitive data
-    return validDevices.map((d) => {
-      const { deviceTokenHash, ...rest } = d;
-      return rest;
-    });
-  }
-
-  /**
-   * Revoke all trusted devices for a user
-   *
-   * Removes all trusted devices for the user.
-   * Used when user performs global logout with forgetDevices flag.
-   *
-   * @param userId - Internal user ID
-   * @returns Object containing count and device information before deletion
-   */
-  async revokeAllTrustedDevices(userId: number): Promise<{
-    revokedCount: number;
-    devices: Array<{
-      id: number | string;
-      deviceName: string | null;
-      lastUsedAt: Date | null;
-      trustedUntil: Date | null;
-    }>;
-  }> {
-    if (!this.trustedDeviceRepository) {
-      return { revokedCount: 0, devices: [] };
-    }
-
-    // Get devices before deletion for audit logging
-    const devices = await this.trustedDeviceRepository.find({
-      where: { userId },
-      order: { lastUsedAt: 'DESC' },
-    });
-
-    // Extract device information (without sensitive token hash)
-    // Note: ipAddress, browser, platform, deviceType are automatically captured by audit service via client info
-    // Only include unique identifiers and historical timestamps
-    const deviceInfo = devices.map((d) => ({
-      id: d.id,
-      deviceName: d.deviceName ?? null, // User-given name (may differ from current device name)
-      lastUsedAt: d.lastUsedAt ?? null, // Historical timestamp
-      trustedUntil: d.trustedUntil ?? null, // Expiry date
-    }));
-
-    // Delete all devices
-    const result = await this.trustedDeviceRepository.delete({ userId });
-    const deletedCount = typeof result.affected === 'number' ? result.affected : 0;
-    this.logger?.debug?.(`Revoked ${deletedCount} trusted device(s) for user ${userId}`);
-    return { revokedCount: deletedCount, devices: deviceInfo };
-  }
-
-  /**
-   * Hash device token (SHA-256)
-   *
-   * @private
-   */
-  private hashDeviceToken(token: string): string {
-    return createHash('sha256').update(token).digest('hex');
-  }
-}

package/src/storage/account-lockout-storage.service.spec.ts

@@ -1,310 +0,0 @@
-import { AccountLockoutStorageService } from './account-lockout-storage.service';
-import { StorageAdapter } from '../interfaces/storage-adapter.interface';
-
-/**
- * Account Lockout Storage Service Unit Tests
- *
- * Tests IP-based account lockout storage operations.
- * Covers failed attempt tracking, lock/unlock operations, and expiration handling.
- *
- * Platform-agnostic: Uses direct instantiation, no NestJS dependencies.
- */
-describe('AccountLockoutStorageService', () => {
-  let service: AccountLockoutStorageService;
-  let mockStorageAdapter: jest.Mocked<StorageAdapter>;
-
-  beforeEach(() => {
-    // Create mock storage adapter
-    mockStorageAdapter = {
-      initialize: jest.fn(),
-      isHealthy: jest.fn(),
-      get: jest.fn(),
-      set: jest.fn(),
-      del: jest.fn(),
-      exists: jest.fn(),
-      incr: jest.fn(),
-      decr: jest.fn(),
-      expire: jest.fn(),
-      ttl: jest.fn(),
-      hget: jest.fn(),
-      hset: jest.fn(),
-      hgetall: jest.fn(),
-      hdel: jest.fn(),
-      lpush: jest.fn(),
-      lrange: jest.fn(),
-      llen: jest.fn(),
-      keys: jest.fn(),
-      scan: jest.fn(),
-      cleanup: jest.fn(),
-      disconnect: jest.fn(),
-    } as any;
-
-    // Instantiate service directly
-    service = new AccountLockoutStorageService(mockStorageAdapter);
-  });
-
-  afterEach(() => {
-    jest.clearAllMocks();
-  });
-
-  // ============================================================================
-  // Service Initialization
-  // ============================================================================
-
-  it('should be defined', () => {
-    expect(service).toBeDefined();
-  });
-
-  // ============================================================================
-  // recordFailedAttempt() Method
-  // ============================================================================
-
-  describe('recordFailedAttempt', () => {
-    it('should increment failed attempts counter', async () => {
-      mockStorageAdapter.incr.mockResolvedValue(1);
-
-      const result = await service.recordFailedAttempt('192.168.1.1');
-
-      expect(result).toBe(1);
-      expect(mockStorageAdapter.incr).toHaveBeenCalledWith('nauth:lockout:ip:192.168.1.1');
-    });
-
-    it('should return incremented count', async () => {
-      mockStorageAdapter.incr.mockResolvedValue(5);
-
-      const result = await service.recordFailedAttempt('192.168.1.1');
-
-      expect(result).toBe(5);
-    });
-
-    it('should use correct key prefix', async () => {
-      mockStorageAdapter.incr.mockResolvedValue(1);
-
-      await service.recordFailedAttempt('10.0.0.1');
-
-      expect(mockStorageAdapter.incr).toHaveBeenCalledWith('nauth:lockout:ip:10.0.0.1');
-    });
-  });
-
-  // ============================================================================
-  // getFailedAttempts() Method
-  // ============================================================================
-
-  describe('getFailedAttempts', () => {
-    it('should return failed attempts count', async () => {
-      mockStorageAdapter.get.mockResolvedValue('3');
-
-      const result = await service.getFailedAttempts('192.168.1.1');
-
-      expect(result).toBe(3);
-      expect(mockStorageAdapter.get).toHaveBeenCalledWith('nauth:lockout:ip:192.168.1.1');
-    });
-
-    it('should return 0 when no attempts recorded', async () => {
-      mockStorageAdapter.get.mockResolvedValue(null);
-
-      const result = await service.getFailedAttempts('192.168.1.1');
-
-      expect(result).toBe(0);
-    });
-
-    it('should parse string value to number', async () => {
-      mockStorageAdapter.get.mockResolvedValue('10');
-
-      const result = await service.getFailedAttempts('192.168.1.1');
-
-      expect(result).toBe(10);
-    });
-
-    it('should handle empty string', async () => {
-      mockStorageAdapter.get.mockResolvedValue('');
-
-      const result = await service.getFailedAttempts('192.168.1.1');
-
-      expect(result).toBe(0);
-    });
-  });
-
-  // ============================================================================
-  // isAccountLocked() Method
-  // ============================================================================
-
-  describe('isAccountLocked', () => {
-    it('should return true when account is locked', async () => {
-      mockStorageAdapter.exists.mockResolvedValue(true);
-
-      const result = await service.isAccountLocked('192.168.1.1');
-
-      expect(result).toBe(true);
-      expect(mockStorageAdapter.exists).toHaveBeenCalledWith('nauth:locked:ip:192.168.1.1');
-    });
-
-    it('should return false when account is not locked', async () => {
-      mockStorageAdapter.exists.mockResolvedValue(false);
-
-      const result = await service.isAccountLocked('192.168.1.1');
-
-      expect(result).toBe(false);
-    });
-
-    it('should use correct lock key prefix', async () => {
-      mockStorageAdapter.exists.mockResolvedValue(false);
-
-      await service.isAccountLocked('10.0.0.1');
-
-      expect(mockStorageAdapter.exists).toHaveBeenCalledWith('nauth:locked:ip:10.0.0.1');
-    });
-  });
-
-  // ============================================================================
-  // lockAccount() Method
-  // ============================================================================
-
-  describe('lockAccount', () => {
-    it('should lock account with correct data', async () => {
-      mockStorageAdapter.set.mockResolvedValue();
-
-      await service.lockAccount('192.168.1.1', 300, 'too_many_failed_attempts');
-
-      expect(mockStorageAdapter.set).toHaveBeenCalledWith(
-        'nauth:locked:ip:192.168.1.1',
-        (expect as any).stringContaining('too_many_failed_attempts'),
-        300,
-      );
-    });
-
-    it('should include lockedAt timestamp', async () => {
-      const beforeLock = new Date();
-      mockStorageAdapter.set.mockResolvedValue();
-
-      await service.lockAccount('192.168.1.1', 300, 'test_reason');
-
-      const afterLock = new Date();
-      const callArgs = mockStorageAdapter.set.mock.calls[0];
-      const lockData = JSON.parse(callArgs[1] as string);
-
-      expect(lockData.reason).toBe('test_reason');
-      expect(new Date(lockData.lockedAt).getTime()).toBeGreaterThanOrEqual(beforeLock.getTime());
-      expect(new Date(lockData.lockedAt).getTime()).toBeLessThanOrEqual(afterLock.getTime());
-    });
-
-    it('should calculate lockedUntil correctly', async () => {
-      const duration = 600; // 10 minutes
-      mockStorageAdapter.set.mockResolvedValue();
-
-      await service.lockAccount('192.168.1.1', duration, 'test_reason');
-
-      const callArgs = mockStorageAdapter.set.mock.calls[0];
-      const lockData = JSON.parse(callArgs[1] as string);
-      const lockedUntil = new Date(lockData.lockedUntil);
-      const expectedTime = Date.now() + duration * 1000;
-
-      expect(lockedUntil.getTime()).toBeCloseTo(expectedTime, -2); // Within 1 second
-    });
-
-    it('should set TTL equal to duration', async () => {
-      const duration = 300;
-      mockStorageAdapter.set.mockResolvedValue();
-
-      await service.lockAccount('192.168.1.1', duration, 'test_reason');
-
-      expect(mockStorageAdapter.set).toHaveBeenCalledWith(
-        'nauth:locked:ip:192.168.1.1',
-        (expect as any).anything(),
-        duration,
-      );
-    });
-  });
-
-  // ============================================================================
-  // unlockAccount() Method
-  // ============================================================================
-
-  describe('unlockAccount', () => {
-    it('should delete lock key and reset failed attempts', async () => {
-      mockStorageAdapter.del.mockResolvedValue();
-
-      await service.unlockAccount('192.168.1.1');
-
-      expect(mockStorageAdapter.del).toHaveBeenCalledWith('nauth:locked:ip:192.168.1.1');
-      expect(mockStorageAdapter.del).toHaveBeenCalledWith('nauth:lockout:ip:192.168.1.1');
-      expect(mockStorageAdapter.del).toHaveBeenCalledTimes(2);
-    });
-
-    it('should unlock account and reset counter', async () => {
-      mockStorageAdapter.del.mockResolvedValue();
-
-      await service.unlockAccount('10.0.0.1');
-
-      // Should delete both lock key and attempt counter
-      expect(mockStorageAdapter.del).toHaveBeenCalledWith('nauth:locked:ip:10.0.0.1');
-      expect(mockStorageAdapter.del).toHaveBeenCalledWith('nauth:lockout:ip:10.0.0.1');
-      expect(mockStorageAdapter.del).toHaveBeenCalledTimes(2);
-    });
-  });
-
-  // ============================================================================
-  // resetFailedAttempts() Method
-  // ============================================================================
-
-  describe('resetFailedAttempts', () => {
-    it('should delete failed attempts counter', async () => {
-      mockStorageAdapter.del.mockResolvedValue();
-
-      await service.resetFailedAttempts('192.168.1.1');
-
-      expect(mockStorageAdapter.del).toHaveBeenCalledWith('nauth:lockout:ip:192.168.1.1');
-    });
-
-    it('should reset counter for correct IP', async () => {
-      mockStorageAdapter.del.mockResolvedValue();
-
-      await service.resetFailedAttempts('10.0.0.1');
-
-      expect(mockStorageAdapter.del).toHaveBeenCalledWith('nauth:lockout:ip:10.0.0.1');
-    });
-  });
-
-  // ============================================================================
-  // Integration Tests
-  // ============================================================================
-
-  describe('Integration', () => {
-    it('should track failed attempts and lock account', async () => {
-      mockStorageAdapter.incr
-        .mockResolvedValueOnce(1)
-        .mockResolvedValueOnce(2)
-        .mockResolvedValueOnce(3)
-        .mockResolvedValueOnce(4)
-        .mockResolvedValueOnce(5);
-      mockStorageAdapter.set.mockResolvedValue();
-      mockStorageAdapter.exists.mockResolvedValue(false).mockResolvedValue(true);
-
-      // Record 5 failed attempts
-      for (let i = 0; i < 5; i++) {
-        await service.recordFailedAttempt('192.168.1.1');
-      }
-
-      // Lock account
-      await service.lockAccount('192.168.1.1', 300, 'max_attempts_exceeded');
-
-      // Verify locked
-      const isLocked = await service.isAccountLocked('192.168.1.1');
-      expect(isLocked).toBe(true);
-    });
-
-    it('should unlock and reset attempts', async () => {
-      mockStorageAdapter.del.mockResolvedValue();
-      mockStorageAdapter.exists.mockResolvedValue(false);
-      mockStorageAdapter.get.mockResolvedValue(null);
-
-      await service.unlockAccount('192.168.1.1');
-
-      const isLocked = await service.isAccountLocked('192.168.1.1');
-      const attempts = await service.getFailedAttempts('192.168.1.1');
-
-      expect(isLocked).toBe(false);
-      expect(attempts).toBe(0);
-    });
-  });
-});