@nauth-toolkit/core 0.1.0

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

@@ -0,0 +1,339 @@
+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

@@ -0,0 +1,310 @@
+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);
+    });
+  });
+});