@nauth-toolkit/core 0.1.0

package/src/storage/rate-limit-storage.service.spec.ts

@@ -0,0 +1,247 @@
+import { RateLimitStorageService } from './rate-limit-storage.service';
+import { StorageAdapter } from '../interfaces/storage-adapter.interface';
+
+/**
+ * Rate Limit Storage Service Unit Tests
+ *
+ * Tests rate limiting storage operations.
+ * Covers counter increment, window management, and expiration handling.
+ *
+ * Platform-agnostic: Uses direct instantiation, no NestJS dependencies.
+ */
+describe('RateLimitStorageService', () => {
+  let service: RateLimitStorageService;
+  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 RateLimitStorageService(mockStorageAdapter);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  // ============================================================================
+  // Service Initialization
+  // ============================================================================
+
+  it('should be defined', () => {
+    expect(service).toBeDefined();
+  });
+
+  // ============================================================================
+  // incrementRateLimit() Method
+  // ============================================================================
+
+  describe('incrementRateLimit', () => {
+    it('should increment counter and return count', async () => {
+      mockStorageAdapter.incr.mockResolvedValue(1);
+      mockStorageAdapter.expire.mockResolvedValue();
+
+      const result = await service.incrementRateLimit('user-123', '/api/login', 60000);
+
+      expect(result).toBe(1);
+      expect(mockStorageAdapter.incr).toHaveBeenCalledWith('nauth:ratelimit:user-123:/api/login');
+    });
+
+    it('should set expiry on first request in window', async () => {
+      mockStorageAdapter.incr.mockResolvedValue(1);
+      mockStorageAdapter.expire.mockResolvedValue();
+
+      await service.incrementRateLimit('user-123', '/api/login', 60000);
+
+      expect(mockStorageAdapter.expire).toHaveBeenCalledWith(
+        'nauth:ratelimit:user-123:/api/login',
+        60, // 60000ms = 60 seconds
+      );
+    });
+
+    it('should not set expiry on subsequent requests', async () => {
+      mockStorageAdapter.incr.mockResolvedValue(2);
+      mockStorageAdapter.expire.mockResolvedValue();
+
+      await service.incrementRateLimit('user-123', '/api/login', 60000);
+
+      expect(mockStorageAdapter.expire).not.toHaveBeenCalled();
+    });
+
+    it('should convert windowMs to seconds for TTL', async () => {
+      mockStorageAdapter.incr.mockResolvedValue(1);
+      mockStorageAdapter.expire.mockResolvedValue();
+
+      await service.incrementRateLimit('user-123', '/api/login', 120000); // 2 minutes
+
+      expect(mockStorageAdapter.expire).toHaveBeenCalledWith(
+        'nauth:ratelimit:user-123:/api/login',
+        120, // 120000ms = 120 seconds
+      );
+    });
+
+    it('should round up windowMs to seconds', async () => {
+      mockStorageAdapter.incr.mockResolvedValue(1);
+      mockStorageAdapter.expire.mockResolvedValue();
+
+      await service.incrementRateLimit('user-123', '/api/login', 1500); // 1.5 seconds
+
+      expect(mockStorageAdapter.expire).toHaveBeenCalledWith(
+        'nauth:ratelimit:user-123:/api/login',
+        2, // Math.ceil(1500 / 1000) = 2
+      );
+    });
+
+    it('should use correct key format', async () => {
+      mockStorageAdapter.incr.mockResolvedValue(1);
+      mockStorageAdapter.expire.mockResolvedValue();
+
+      await service.incrementRateLimit('ip-192.168.1.1', '/api/signup', 30000);
+
+      expect(mockStorageAdapter.incr).toHaveBeenCalledWith('nauth:ratelimit:ip-192.168.1.1:/api/signup');
+    });
+  });
+
+  // ============================================================================
+  // getRateLimit() Method
+  // ============================================================================
+
+  describe('getRateLimit', () => {
+    it('should return current rate limit count', async () => {
+      mockStorageAdapter.get.mockResolvedValue('5');
+
+      const result = await service.getRateLimit('user-123', '/api/login');
+
+      expect(result).toBe(5);
+      expect(mockStorageAdapter.get).toHaveBeenCalledWith('nauth:ratelimit:user-123:/api/login');
+    });
+
+    it('should return 0 when no limit recorded', async () => {
+      mockStorageAdapter.get.mockResolvedValue(null);
+
+      const result = await service.getRateLimit('user-123', '/api/login');
+
+      expect(result).toBe(0);
+    });
+
+    it('should parse string value to number', async () => {
+      mockStorageAdapter.get.mockResolvedValue('10');
+
+      const result = await service.getRateLimit('user-123', '/api/login');
+
+      expect(result).toBe(10);
+    });
+
+    it('should handle empty string', async () => {
+      mockStorageAdapter.get.mockResolvedValue('');
+
+      const result = await service.getRateLimit('user-123', '/api/login');
+
+      expect(result).toBe(0);
+    });
+
+    it('should use correct key format', async () => {
+      mockStorageAdapter.get.mockResolvedValue('3');
+
+      await service.getRateLimit('ip-10.0.0.1', '/api/reset-password');
+
+      expect(mockStorageAdapter.get).toHaveBeenCalledWith('nauth:ratelimit:ip-10.0.0.1:/api/reset-password');
+    });
+  });
+
+  // ============================================================================
+  // resetRateLimit() Method
+  // ============================================================================
+
+  describe('resetRateLimit', () => {
+    it('should delete rate limit counter', async () => {
+      mockStorageAdapter.del.mockResolvedValue();
+
+      await service.resetRateLimit('user-123', '/api/login');
+
+      expect(mockStorageAdapter.del).toHaveBeenCalledWith('nauth:ratelimit:user-123:/api/login');
+    });
+
+    it('should reset limit for correct identifier and endpoint', async () => {
+      mockStorageAdapter.del.mockResolvedValue();
+
+      await service.resetRateLimit('ip-192.168.1.1', '/api/signup');
+
+      expect(mockStorageAdapter.del).toHaveBeenCalledWith('nauth:ratelimit:ip-192.168.1.1:/api/signup');
+    });
+  });
+
+  // ============================================================================
+  // Integration Tests
+  // ============================================================================
+
+  describe('Integration', () => {
+    it('should track rate limit across multiple requests', async () => {
+      mockStorageAdapter.incr.mockResolvedValueOnce(1).mockResolvedValueOnce(2).mockResolvedValueOnce(3);
+      mockStorageAdapter.expire.mockResolvedValue();
+      mockStorageAdapter.get.mockResolvedValue('3');
+
+      // Make 3 requests
+      await service.incrementRateLimit('user-123', '/api/login', 60000);
+      await service.incrementRateLimit('user-123', '/api/login', 60000);
+      await service.incrementRateLimit('user-123', '/api/login', 60000);
+
+      const count = await service.getRateLimit('user-123', '/api/login');
+
+      expect(count).toBe(3);
+      expect(mockStorageAdapter.expire).toHaveBeenCalledTimes(1); // Only on first request
+    });
+
+    it('should reset rate limit correctly', async () => {
+      mockStorageAdapter.incr.mockResolvedValue(5);
+      mockStorageAdapter.expire.mockResolvedValue();
+      mockStorageAdapter.del.mockResolvedValue();
+      mockStorageAdapter.get.mockResolvedValue(null);
+
+      await service.incrementRateLimit('user-123', '/api/login', 60000);
+      await service.resetRateLimit('user-123', '/api/login');
+
+      const count = await service.getRateLimit('user-123', '/api/login');
+
+      expect(count).toBe(0);
+    });
+
+    it('should handle different endpoints independently', async () => {
+      mockStorageAdapter.incr.mockResolvedValueOnce(1).mockResolvedValueOnce(1);
+      mockStorageAdapter.expire.mockResolvedValue();
+      mockStorageAdapter.get.mockResolvedValueOnce('1').mockResolvedValueOnce('1');
+
+      await service.incrementRateLimit('user-123', '/api/login', 60000);
+      await service.incrementRateLimit('user-123', '/api/signup', 60000);
+
+      const loginCount = await service.getRateLimit('user-123', '/api/login');
+      const signupCount = await service.getRateLimit('user-123', '/api/signup');
+
+      expect(loginCount).toBe(1);
+      expect(signupCount).toBe(1);
+    });
+  });
+});

package/src/storage/rate-limit-storage.service.ts

@@ -0,0 +1,38 @@
+import { RateLimitStorage, StorageAdapter } from '../interfaces/storage-adapter.interface';
+
+/**
+ * Rate limit storage implementation using StorageAdapter (Platform-Agnostic)
+ */
+export class RateLimitStorageService implements RateLimitStorage {
+  private readonly keyPrefix = 'nauth:ratelimit:';
+
+  constructor(private readonly storageAdapter: StorageAdapter) {}
+
+  async incrementRateLimit(identifier: string, endpoint: string, windowMs: number): Promise<number> {
+    const key = this.getKey(identifier, endpoint);
+    const count = await this.storageAdapter.incr(key);
+
+    if (count === 1) {
+      // First request in this window, set expiry
+      const ttl = Math.ceil(windowMs / 1000);
+      await this.storageAdapter.expire(key, ttl);
+    }
+
+    return count;
+  }
+
+  async getRateLimit(identifier: string, endpoint: string): Promise<number> {
+    const key = this.getKey(identifier, endpoint);
+    const value = await this.storageAdapter.get(key);
+    return value ? parseInt(value, 10) : 0;
+  }
+
+  async resetRateLimit(identifier: string, endpoint: string): Promise<void> {
+    const key = this.getKey(identifier, endpoint);
+    await this.storageAdapter.del(key);
+  }
+
+  private getKey(identifier: string, endpoint: string): string {
+    return `${this.keyPrefix}${identifier}:${endpoint}`;
+  }
+}

package/src/templates/html-template.engine.spec.ts

@@ -0,0 +1,161 @@
+import { HtmlTemplateEngine } from './html-template.engine';
+import { TemplateType } from '../interfaces/template.interface';
+
+describe('HtmlTemplateEngine', () => {
+  let engine: HtmlTemplateEngine;
+
+  beforeEach(() => {
+    engine = new HtmlTemplateEngine();
+  });
+
+  it('should be defined', () => {
+    expect(engine).toBeDefined();
+  });
+
+  describe('render', () => {
+    it('should render verification email template', async () => {
+      const variables = {
+        appName: 'Test App',
+        userName: 'John Doe',
+        code: '123456',
+        link: 'https://example.com/verify',
+        expiryMinutes: 60,
+        companyName: 'Test Company',
+      };
+
+      const email = await engine.render(TemplateType.VERIFICATION, variables);
+
+      expect(email.subject).toContain('Test App');
+      expect(email.html).toContain('John Doe');
+      expect(email.html).toContain('123456');
+      expect(email.html).toContain('https://example.com/verify');
+      expect(email.text).toContain('123456');
+    });
+
+    it('should render password reset template', async () => {
+      const variables = {
+        appName: 'Test App',
+        userName: 'Jane Doe',
+        link: 'https://example.com/reset',
+        expiryMinutes: 30,
+        companyName: 'Test Company',
+      };
+
+      const email = await engine.render(TemplateType.PASSWORD_RESET, variables);
+
+      expect(email.subject).toContain('Reset'); // Capitalized in actual template
+      expect(email.html).toContain('Jane Doe');
+      expect(email.html).toContain('https://example.com/reset');
+    });
+
+    it('should render welcome email template', async () => {
+      const variables = {
+        appName: 'Test App',
+        userName: 'Bob Smith',
+        dashboardUrl: 'https://example.com/dashboard',
+        supportEmail: 'support@example.com',
+        companyName: 'Test Company',
+      };
+
+      const email = await engine.render(TemplateType.WELCOME, variables);
+
+      expect(email.subject).toContain('Welcome');
+      expect(email.html).toContain('Bob Smith');
+      expect(email.html).toContain('https://example.com/dashboard');
+    });
+
+    it('should render account lockout template', async () => {
+      const variables = {
+        appName: 'Test App',
+        userName: 'Alice Johnson',
+        reason: 'Too many failed login attempts',
+        durationMinutes: 15,
+        supportEmail: 'support@example.com',
+        companyName: 'Test Company',
+      };
+
+      const email = await engine.render(TemplateType.ACCOUNT_LOCKOUT, variables);
+
+      expect(email.subject).toContain('Account Locked');
+      expect(email.html).toContain('Alice Johnson');
+      expect(email.html).toContain('Too many failed login attempts');
+      expect(email.html).toContain('15');
+    });
+
+    it('should render new device login template', async () => {
+      const variables = {
+        appName: 'Test App',
+        userName: 'Charlie Brown',
+        deviceName: 'iPhone 13',
+        deviceType: 'mobile',
+        ipAddress: '192.168.1.100',
+        location: 'New York, US',
+        timestamp: '2025-10-22T12:00:00Z',
+        supportEmail: 'support@example.com',
+        companyName: 'Test Company',
+      };
+
+      const email = await engine.render(TemplateType.NEW_DEVICE, variables);
+
+      expect(email.subject).toContain('New Device Login');
+      expect(email.html).toContain('Charlie Brown');
+      expect(email.html).toContain('iPhone 13');
+      expect(email.html).toContain('192.168.1.100');
+    });
+
+    it('should throw error for unknown template type', async () => {
+      let error: Error | undefined;
+      try {
+        await engine.render('unknown' as any, {});
+      } catch (e) {
+        error = e as Error;
+      }
+      expect(error).toBeDefined();
+      expect(error?.message).toContain('Template "unknown" not found');
+    });
+
+    it('should handle missing variables gracefully', async () => {
+      const variables = {
+        appName: 'Test App',
+        // Missing other required variables
+      };
+
+      const email = await engine.render(TemplateType.VERIFICATION, variables);
+
+      expect(email.subject).toContain('Test App');
+      expect(email.html).toBeDefined();
+      expect(email.text).toBeDefined();
+    });
+
+    it('should replace all occurrences of a variable', async () => {
+      const variables = {
+        appName: 'Test App',
+        userName: 'Test User',
+        companyName: 'Test Company',
+      };
+
+      const email = await engine.render(TemplateType.WELCOME, variables);
+
+      // userName should appear in the greeting
+      expect(email.html).toContain('Test User');
+      expect(email.text).toContain('Test User');
+    });
+
+    it('should handle special characters in variables', async () => {
+      const variables = {
+        appName: 'Test & Company <Special>',
+        userName: 'John "Doe"',
+        code: '123456',
+        link: 'https://example.com/verify',
+        expiryMinutes: 60,
+        companyName: 'Test & Co.',
+      };
+
+      const email = await engine.render(TemplateType.VERIFICATION, variables);
+
+      // HTML escapes special characters in userName
+      expect(email.html).toContain('John &quot;Doe&quot;');
+      expect(email.text).toContain('John "Doe"');
+    });
+  });
+});