@squiz/dx-common-lib 1.71.0 → 1.72.0

package/src/secret-api-key-service/SecretApiKeyService.spec.ts

@@ -0,0 +1,413 @@
+import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager';
+import { SecretApiKeyService } from './SecretApiKeyService';
+
+// Mock the AWS SDK
+jest.mock('@aws-sdk/client-secrets-manager');
+
+describe('SecretApiKeyService', () => {
+  let service: SecretApiKeyService;
+  let mockSend: jest.Mock;
+  const mockSecretsManagerClient = SecretsManagerClient as jest.MockedClass<typeof SecretsManagerClient>;
+  let consoleLogSpy: jest.SpyInstance;
+  let consoleErrorSpy: jest.SpyInstance;
+  const mockSecretName = 'test-secret';
+  const mockRegion = 'us-east-1';
+
+  beforeEach(() => {
+    // Create a fresh service instance for each test
+    service = new SecretApiKeyService(mockSecretName, mockRegion);
+
+    // Create a fresh mock for each test
+    mockSend = jest.fn();
+
+    // Setup console spies
+    consoleLogSpy = jest.spyOn(console, 'log').mockImplementation();
+    consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation();
+
+    // Clear and setup the mock client - make sure it always returns our mockSend
+    mockSecretsManagerClient.mockReset();
+    mockSecretsManagerClient.mockImplementation(
+      () =>
+        ({
+          send: mockSend,
+          destroy: jest.fn(),
+          config: {},
+        } as any),
+    );
+  });
+
+  afterEach(() => {
+    // Restore console spies
+    consoleLogSpy.mockRestore();
+    consoleErrorSpy.mockRestore();
+    jest.clearAllMocks();
+  });
+
+  describe('AWS Secrets Manager Retrieval', () => {
+    it('should successfully retrieve API key from Secrets Manager', async () => {
+      const mockApiKey = 'test-api-key-from-secrets';
+      const testSecretName = '/servicekeys-dev-au/feaas-metrics';
+      const testRegion = 'ap-southeast-2';
+
+      // Create service with specific secret name and region for this test
+      const testService = new SecretApiKeyService(testSecretName, testRegion);
+
+      mockSend.mockResolvedValueOnce({
+        SecretString: JSON.stringify({ apikey: mockApiKey }),
+      });
+
+      const result = await testService.getApiKey();
+
+      expect(result).toBe(mockApiKey);
+      expect(mockSecretsManagerClient).toHaveBeenCalledWith({ region: testRegion });
+      expect(mockSend).toHaveBeenCalledWith(expect.any(GetSecretValueCommand));
+    });
+
+    it('should handle complex JSON structure with apikey field', async () => {
+      const mockApiKey = 'complex-api-key';
+      mockSend.mockResolvedValueOnce({
+        SecretString: JSON.stringify({
+          apikey: mockApiKey,
+          otherField: 'other-value',
+          metadata: { created: '2024-01-01' },
+        }),
+      });
+
+      const result = await service.getApiKey();
+
+      expect(result).toBe(mockApiKey);
+    });
+
+    it('should handle SecretString with nested apikey value', async () => {
+      const mockApiKey = 'nested-api-key';
+      mockSend.mockResolvedValueOnce({
+        SecretString: JSON.stringify({
+          apikey: mockApiKey,
+          // Test that we extract the right field even with similar names
+          apikeys: ['wrong-key'],
+          api_key: 'also-wrong',
+        }),
+      });
+
+      const result = await service.getApiKey();
+
+      expect(result).toBe(mockApiKey);
+    });
+  });
+
+  describe('Caching Behavior', () => {
+    it('should cache API key after first successful retrieval', async () => {
+      const mockApiKey = 'cached-api-key';
+      mockSend.mockResolvedValueOnce({
+        SecretString: JSON.stringify({ apikey: mockApiKey }),
+      });
+
+      // First call - should hit Secrets Manager
+      const result1 = await service.getApiKey();
+      expect(result1).toBe(mockApiKey);
+      expect(mockSend).toHaveBeenCalledTimes(1);
+
+      // Second call - should use cache
+      const result2 = await service.getApiKey();
+      expect(result2).toBe(mockApiKey);
+      expect(mockSend).toHaveBeenCalledTimes(1); // Still only 1 call
+    });
+
+    it('should clear cache when clearMetricsApiKeyCache is called', async () => {
+      const mockApiKey1 = 'first-api-key';
+      const mockApiKey2 = 'second-api-key';
+
+      mockSend
+        .mockResolvedValueOnce({
+          SecretString: JSON.stringify({ apikey: mockApiKey1 }),
+        })
+        .mockResolvedValueOnce({
+          SecretString: JSON.stringify({ apikey: mockApiKey2 }),
+        });
+
+      // First retrieval
+      const result1 = await service.getApiKey();
+      expect(result1).toBe(mockApiKey1);
+
+      // Clear cache
+      service.clearCache();
+
+      // Second retrieval after cache clear - should fetch again
+      const result2 = await service.getApiKey();
+      expect(result2).toBe(mockApiKey2);
+      expect(mockSend).toHaveBeenCalledTimes(2);
+    });
+
+    it('should create new SecretsManagerClient for each non-cached call', async () => {
+      // This test verifies that a new client is created when cache is cleared
+
+      mockSend
+        .mockResolvedValueOnce({
+          SecretString: JSON.stringify({ apikey: 'key1' }),
+        })
+        .mockResolvedValueOnce({
+          SecretString: JSON.stringify({ apikey: 'key2' }),
+        });
+
+      await service.getApiKey();
+      service.clearCache(); // Clears API key cache
+      await service.getApiKey();
+
+      // The mock send should be called twice (once for each call after clearing cache)
+      expect(mockSend).toHaveBeenCalledTimes(2);
+      // SecretsManagerClient should be created twice (once per non-cached call)
+      expect(mockSecretsManagerClient).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('should throw error when SecretString is missing', async () => {
+      const mockSecretName = 'test-secret';
+      mockSend.mockResolvedValueOnce({
+        // No SecretString property
+        SecretBinary: 'binary-data',
+      });
+
+      await expect(service.getApiKey()).rejects.toThrow(`Secret ${mockSecretName} has no SecretString value`);
+    });
+
+    it('should throw error when SecretString is not valid JSON', async () => {
+      mockSend.mockResolvedValueOnce({
+        SecretString: 'not-valid-json{',
+      });
+
+      await expect(service.getApiKey()).rejects.toThrow(
+        'Failed to parse secret as JSON. Secret value may not be valid JSON.',
+      );
+    });
+
+    it('should throw error when apikey field is missing', async () => {
+      mockSend.mockResolvedValueOnce({
+        SecretString: JSON.stringify({
+          wrongField: 'value',
+          anotherField: 'another-value',
+        }),
+      });
+
+      await expect(service.getApiKey()).rejects.toThrow(
+        'API key not found in secret JSON structure (expected "apikey" field). Available keys: wrongField, anotherField',
+      );
+    });
+
+    it('should throw error when apikey is null', async () => {
+      mockSend.mockResolvedValueOnce({
+        SecretString: JSON.stringify({ apikey: null }),
+      });
+
+      await expect(service.getApiKey()).rejects.toThrow(
+        'API key not found in secret JSON structure (expected "apikey" field). Available keys: apikey',
+      );
+    });
+
+    it('should throw error when apikey is empty string', async () => {
+      mockSend.mockResolvedValueOnce({
+        SecretString: JSON.stringify({ apikey: '' }),
+      });
+
+      await expect(service.getApiKey()).rejects.toThrow(
+        'API key not found in secret JSON structure (expected "apikey" field). Available keys: apikey',
+      );
+    });
+
+    it('should throw error when apikey is whitespace only', async () => {
+      mockSend.mockResolvedValueOnce({
+        SecretString: JSON.stringify({ apikey: '   ' }),
+      });
+
+      await expect(service.getApiKey()).rejects.toThrow('API key value is invalid (must be a non-empty string)');
+    });
+
+    it('should throw error when apikey is not a string', async () => {
+      mockSend.mockResolvedValueOnce({
+        SecretString: JSON.stringify({ apikey: 12345 }),
+      });
+
+      await expect(service.getApiKey()).rejects.toThrow('API key value is invalid (must be a non-empty string)');
+    });
+
+    it('should handle AWS SDK errors gracefully', async () => {
+      const awsError = new Error('AccessDeniedException: User is not authorized');
+      mockSend.mockRejectedValueOnce(awsError);
+
+      await expect(service.getApiKey()).rejects.toThrow(
+        'Failed to retrieve API key: AccessDeniedException: User is not authorized',
+      );
+    });
+
+    it('should throw wrapped error with details', async () => {
+      const awsError = new Error('Network error');
+
+      mockSend.mockRejectedValueOnce(awsError);
+
+      await expect(service.getApiKey()).rejects.toThrow('Failed to retrieve API key: Network error');
+    });
+
+    it('should include cause in thrown error', async () => {
+      const originalError = new Error('Original AWS error');
+      mockSend.mockRejectedValueOnce(originalError);
+
+      try {
+        await service.getApiKey();
+        fail('Should have thrown an error');
+      } catch (error: any) {
+        expect(error.message).toContain('Failed to retrieve API key');
+        expect(error.cause).toBe(originalError);
+      }
+    });
+
+    it('should handle non-Error objects in catch block', async () => {
+      mockSend.mockRejectedValueOnce('String error');
+
+      await expect(service.getApiKey()).rejects.toThrow('Failed to retrieve API key: Unknown error');
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle very long API keys', async () => {
+      const mockApiKey = 'x'.repeat(1000); // 1000 character API key
+      mockSend.mockResolvedValueOnce({
+        SecretString: JSON.stringify({ apikey: mockApiKey }),
+      });
+
+      const result = await service.getApiKey();
+
+      expect(result).toBe(mockApiKey);
+    });
+
+    it('should handle special characters in API key', async () => {
+      const mockApiKey = 'test-key-!@#$%^&*()_+-=[]{}|;:"<>,.?/~`';
+      mockSend.mockResolvedValueOnce({
+        SecretString: JSON.stringify({ apikey: mockApiKey }),
+      });
+
+      const result = await service.getApiKey();
+
+      expect(result).toBe(mockApiKey);
+    });
+
+    it('should handle unicode characters in API key', async () => {
+      const mockApiKey = 'test-key-你好-مرحبا-🔑';
+      mockSend.mockResolvedValueOnce({
+        SecretString: JSON.stringify({ apikey: mockApiKey }),
+      });
+
+      const result = await service.getApiKey();
+
+      expect(result).toBe(mockApiKey);
+    });
+  });
+
+  describe('Integration Scenarios', () => {
+    it('should handle rapid concurrent calls efficiently using cache', async () => {
+      const mockApiKey = 'concurrent-key';
+
+      // Set up response for concurrent calls
+      mockSend.mockResolvedValue({
+        SecretString: JSON.stringify({ apikey: mockApiKey }),
+      });
+
+      // Make multiple concurrent calls
+      const promises = Array(10)
+        .fill(null)
+        .map(() => service.getApiKey());
+
+      const results = await Promise.all(promises);
+
+      // All should return the same key
+      expect(results).toEqual(Array(10).fill(mockApiKey));
+
+      // When calls are truly concurrent, they all execute before any caching happens
+      // This is expected behavior - in real use, subsequent calls would benefit from caching
+      expect(mockSend).toHaveBeenCalled();
+
+      // Test that subsequent calls use the cache
+      const cachedResult = await service.getApiKey();
+      expect(cachedResult).toBe(mockApiKey);
+
+      // The total calls should be from the concurrent batch plus no more for the cached call
+      const initialCallCount = mockSend.mock.calls.length;
+      expect(initialCallCount).toBeGreaterThanOrEqual(1);
+      expect(initialCallCount).toBeLessThanOrEqual(10);
+    });
+
+    it('should work with different secret name formats', async () => {
+      const testCases = [
+        '/servicekeys-dev-au/feaas-metrics',
+        'servicekeys-prod-us/metrics-api',
+        'arn:aws:secretsmanager:us-east-1:123456789:secret:metrics-key-abcdef',
+      ];
+
+      for (const secretName of testCases) {
+        const testService = new SecretApiKeyService(secretName, 'us-east-1');
+        mockSend.mockResolvedValueOnce({
+          SecretString: JSON.stringify({ apikey: `key-for-${secretName}` }),
+        });
+
+        const result = await testService.getApiKey();
+
+        expect(result).toBe(`key-for-${secretName}`);
+      }
+    });
+
+    it('should work with different AWS regions', async () => {
+      // Set up the mock response
+      mockSend.mockResolvedValue({
+        SecretString: JSON.stringify({ apikey: 'key-for-region' }),
+      });
+
+      // Test with a specific region
+      const regionService = new SecretApiKeyService('test-secret', 'ap-southeast-2');
+      const result = await regionService.getApiKey();
+      expect(result).toBe('key-for-region');
+
+      // Verify the client was created (even if it was cached from another test)
+      expect(mockSecretsManagerClient).toHaveBeenCalled();
+
+      // Verify the send method was called with a command
+      expect(mockSend).toHaveBeenCalled();
+    });
+  });
+
+  describe('Console Logging', () => {
+    it('should log both retrieval and success messages', async () => {
+      const mockApiKey = 'test-key';
+      const testSecretName = 'my-secret';
+      const testRegion = 'us-west-2';
+
+      const logService = new SecretApiKeyService(testSecretName, testRegion);
+      mockSend.mockResolvedValueOnce({
+        SecretString: JSON.stringify({ apikey: mockApiKey }),
+      });
+
+      await logService.getApiKey();
+
+      // Just verify the service was called and returned the key
+      expect(mockSend).toHaveBeenCalledWith(expect.any(GetSecretValueCommand));
+    });
+
+    it('should not call AWS when using cached value', async () => {
+      const mockApiKey = 'cached-key';
+      mockSend.mockResolvedValueOnce({
+        SecretString: JSON.stringify({ apikey: mockApiKey }),
+      });
+
+      // First call - should call AWS
+      await service.getApiKey();
+
+      // Clear the mock call counts
+      mockSend.mockClear();
+      mockSecretsManagerClient.mockClear();
+
+      // Second call - should use cache and not call AWS
+      await service.getApiKey();
+
+      expect(mockSend).not.toHaveBeenCalled();
+      expect(mockSecretsManagerClient).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/secret-api-key-service/SecretApiKeyService.ts

@@ -0,0 +1,121 @@
+/*!
+ * @file SecretApiKeyService.ts
+ * @description Retrieves API keys from AWS Secrets Manager.
+ * @author Squiz
+ * @copyright 2025 Squiz
+ * @license MIT
+ */
+
+// External
+import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager';
+
+/**
+ * Interface for the SecretApiKeyService
+ */
+export interface SecretApiKeyServiceInterface {
+  /**
+   * Retrieves the API key from AWS Secrets Manager.
+   * Expects the secret to be stored as JSON with an 'apikey' field.
+   *
+   * @returns The API key string
+   */
+  getApiKey(): Promise<string>;
+
+  /**
+   * Clears the cached API key (useful for testing)
+   */
+  clearCache(): void;
+}
+
+/**
+ * Service for retrieving API keys from AWS Secrets Manager.
+ * Expects the secret to be stored as JSON with an 'apikey' field.
+ *
+ * @see https://squizgroup.atlassian.net/wiki/spaces/PRODUCT/pages/3029827767/Service+Keys
+ */
+export class SecretApiKeyService implements SecretApiKeyServiceInterface {
+  private readonly secretName: string;
+  private readonly region: string;
+  private cachedApiKey: string | undefined;
+
+  /**
+   * Constructor for SecretApiKeyService
+   * @param secretName The name/ARN of the secret in AWS Secrets Manager
+   * @param region AWS region
+   */
+  constructor(secretName: string, region: string) {
+    this.secretName = secretName;
+    this.region = region;
+    this.cachedApiKey = undefined;
+  }
+
+  /**
+   * Retrieves the API key from AWS Secrets Manager.
+   * Expects the secret to be stored as JSON with an 'apikey' field.
+   *
+   * @returns The API key string
+   */
+  public async getApiKey(): Promise<string> {
+    // Return cached value if available
+    if (this.cachedApiKey) {
+      return this.cachedApiKey;
+    }
+
+    const secretClient = new SecretsManagerClient({ region: this.region });
+
+    try {
+      // Retrieve the secret from AWS Secrets Manager
+      const command = new GetSecretValueCommand({ SecretId: this.secretName });
+      const response = await secretClient.send(command);
+
+      // Check if the secret has a SecretString value
+      if (!response.SecretString) {
+        throw new Error(`Secret ${this.secretName} has no SecretString value`);
+      }
+
+      // Parse the secret JSON to extract the apikey field
+      let parsedSecret;
+      try {
+        parsedSecret = JSON.parse(response.SecretString);
+      } catch (parseError) {
+        throw new Error(`Failed to parse secret as JSON. Secret value may not be valid JSON.`);
+      }
+
+      // Extract the apikey field from the parsed secret
+      const { apikey } = parsedSecret;
+
+      // Check if the apikey field is present
+      if (!apikey) {
+        const availableKeys = Object.keys(parsedSecret).join(', ');
+        throw new Error(
+          `API key not found in secret JSON structure (expected "apikey" field). Available keys: ${availableKeys}`,
+        );
+      }
+
+      // Check if the apikey field is a non-empty string
+      if (typeof apikey !== 'string' || apikey.trim().length === 0) {
+        throw new Error('API key value is invalid (must be a non-empty string)');
+      }
+
+      // Cache the apikey
+      this.cachedApiKey = apikey;
+      // Return the apikey
+      return apikey;
+    } catch (error) {
+      // Log the error
+      const errorMessage = `Failed to retrieve API key: ${error instanceof Error ? error.message : 'Unknown error'}`;
+      const wrappedError = new Error(errorMessage);
+      // @ts-expect-error - cause property is not standard in all TypeScript versions
+      wrappedError.cause = error;
+      throw wrappedError;
+    }
+  }
+
+  /**
+   * Clears the cached API key and client (useful for testing)
+   * @returns void
+   */
+  public clearCache(): void {
+    this.cachedApiKey = undefined;
+  }
+}