@od-oneapp/storage 2026.1.1301

package/src/validation.test.ts

@@ -0,0 +1,312 @@
+/**
+ * @fileoverview validation.test.ts
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  ConfigError,
+  DownloadError,
+  NetworkError,
+  ProviderError,
+  StorageError,
+  StorageErrorCode,
+  UploadError,
+  ValidationError,
+  createStorageError,
+  formatFileSize,
+  getErrorCode,
+  getQuotaInfo,
+  isQuotaExceeded,
+  isRetryableError,
+  parseFileSize,
+  validateFileExtension,
+  validateFileSize,
+  validateMimeType,
+  validateStorageKey,
+  validateUploadOptions,
+  validateUrlForSSRF,
+} from './validation';
+
+describe('validation utilities', () => {
+  it('validates file size boundaries', () => {
+    expect(validateFileSize(512, 1024)).toStrictEqual({ valid: true });
+    expect(validateFileSize(-1, 1024)).toStrictEqual({
+      valid: false,
+      error: 'File size cannot be negative',
+    });
+    expect(validateFileSize(2048, 1024)).toStrictEqual({
+      valid: false,
+      error: 'File size 2048 bytes exceeds maximum 1024 bytes',
+    });
+  });
+
+  it('validates mime types with wildcards and dangerous types', () => {
+    expect(validateMimeType('image/png', ['image/png', 'image/jpeg']).valid).toBe(true);
+    expect(validateMimeType('image/webp', ['image/*']).valid).toBe(true);
+    expect(validateMimeType('text/plain', ['image/*'])).toStrictEqual({
+      valid: false,
+      error: "MIME type 'text/plain' is not allowed. Allowed types: image/*",
+    });
+
+    // Required check
+    expect(validateMimeType('')).toStrictEqual({
+      valid: false,
+      error: 'MIME type is required',
+    });
+
+    // Dangerous types
+    expect(validateMimeType('application/x-msdownload')).toStrictEqual({
+      valid: false,
+      error:
+        "Content type 'application/x-msdownload' is not allowed for security reasons (executable or script content)",
+    });
+
+    // Empty allowed list (defaults to allowing safe types)
+    expect(validateMimeType('image/png', [])).toStrictEqual({ valid: true });
+  });
+
+  it('validates file extensions against content type', () => {
+    expect(validateFileExtension('image.jpg', 'image/jpeg')).toStrictEqual({ valid: true });
+    expect(validateFileExtension('image.png', 'image/png')).toStrictEqual({ valid: true });
+
+    // Missing requirements
+    expect(validateFileExtension('', 'image/jpeg').valid).toBe(false);
+    expect(validateFileExtension('image.jpg', '').valid).toBe(false);
+
+    // Missing extension
+    expect(validateFileExtension('no-extension', 'image/jpeg')).toStrictEqual({
+      valid: false,
+      error: 'File must have an extension',
+    });
+
+    // Mismatch
+    expect(validateFileExtension('virus.exe', 'image/jpeg')).toStrictEqual({
+      valid: false,
+      error:
+        "File extension '.exe' does not match content type 'image/jpeg'. Expected: .jpg, .jpeg",
+    });
+
+    // Unknown MIME type (allowed)
+    expect(validateFileExtension('file.custom', 'application/x-custom')).toStrictEqual({
+      valid: true,
+    });
+  });
+
+  it('validates storage keys with optional rules', () => {
+    // Valid key returns { valid: true, errors: [] }
+    const validResult = validateStorageKey('folder/file.txt');
+    expect(validResult.valid).toBe(true);
+    expect(validResult.errors).toHaveLength(0);
+
+    // Key exceeds max length
+    const tooLong = validateStorageKey('folder/file.txt', { maxLength: 5 });
+    expect(tooLong.valid).toBe(false);
+    expect(tooLong.errors).toContain('Key exceeds maximum length of 5 characters');
+
+    // Forbidden pattern match
+    const forbidden = validateStorageKey('secret/file.txt', {
+      forbiddenPatterns: [/secret/],
+    });
+    expect(forbidden.valid).toBe(false);
+    expect(forbidden.errors.some(e => e.includes('forbidden pattern'))).toBe(true);
+
+    // Empty key with allowEmpty: true
+    const emptyAllowed = validateStorageKey('', { allowEmpty: true });
+    expect(emptyAllowed.valid).toBe(true);
+
+    // Empty key with allowEmpty: false
+    const emptyNotAllowed = validateStorageKey('', { allowEmpty: false });
+    expect(emptyNotAllowed.valid).toBe(false);
+    expect(emptyNotAllowed.errors.some(e => e.includes('empty'))).toBe(true);
+
+    // Invalid characters
+    const badChars = validateStorageKey('bad|name');
+    expect(badChars.valid).toBe(false);
+    expect(badChars.errors.some(e => e.includes('invalid characters'))).toBe(true);
+
+    // Double slashes
+    const doubleSlash = validateStorageKey('double//slash');
+    expect(doubleSlash.valid).toBe(false);
+    expect(doubleSlash.errors.some(e => e.includes('double slashes'))).toBe(true);
+
+    // Relative path traversal
+    const traversal = validateStorageKey('../relative/path');
+    expect(traversal.valid).toBe(false);
+    expect(traversal.errors.some(e => e.includes('relative path'))).toBe(true);
+  });
+
+  it('validates upload options for multiple rules', () => {
+    const result = validateUploadOptions(
+      {
+        fileSize: 2048,
+        contentType: 'image/png',
+        key: 'safe/path.png',
+      },
+      {
+        maxFileSize: 1024,
+        allowedMimeTypes: ['image/*'],
+        maxKeyLength: 100,
+        forbiddenKeyPatterns: [/safe\/path/],
+        requireContentType: true,
+      },
+    );
+
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('File size 2048 bytes exceeds maximum 1024 bytes');
+    expect(result.errors).toContain('Key matches forbidden pattern: safe\\/path');
+    expect(result.errors.some(error => error.includes('MIME type'))).toBe(false);
+
+    const missingType = validateUploadOptions({ key: 'file.txt' }, { requireContentType: true });
+    expect(missingType).toStrictEqual({ valid: false, errors: ['Content type is required'] });
+  });
+
+  it('detects retryable errors', () => {
+    const retryable = new NetworkError('temporary network issue');
+    const nonRetryable = new ConfigError('invalid configuration');
+
+    expect(isRetryableError(retryable)).toBe(true);
+    expect(isRetryableError(nonRetryable)).toBe(false);
+    expect(isRetryableError(new Error('permanent failure'))).toBe(false);
+    expect(isRetryableError(new Error('connection timeout'))).toBe(true);
+    expect(isRetryableError(new Error('rate limit reached'))).toBe(true);
+    expect(isRetryableError('not an error object')).toBe(false);
+  });
+
+  it('extracts error codes from various error shapes', () => {
+    const custom = new ProviderError('provider down', 'vercel', undefined, false);
+    const timeout = new Error('Request timeout occurred');
+    const notFound = new Error('resource not found on server');
+    const accessDenied = new Error('access denied to resource');
+    const network = new Error('network failure');
+
+    expect(getErrorCode(custom)).toBe(StorageErrorCode.PROVIDER_ERROR);
+    expect(getErrorCode(timeout)).toBe(StorageErrorCode.TIMEOUT);
+    expect(getErrorCode(notFound)).toBe(StorageErrorCode.FILE_NOT_FOUND);
+    expect(getErrorCode(accessDenied)).toBe(StorageErrorCode.ACCESS_DENIED);
+    expect(getErrorCode(network)).toBe(StorageErrorCode.NETWORK_ERROR);
+    expect(getErrorCode({})).toBe(StorageErrorCode.PROVIDER_ERROR);
+  });
+
+  it('creates consistent storage errors', () => {
+    const underlying = new UploadError('upload failed', { key: 'file.txt' }, true);
+    const wrapped = createStorageError(underlying, { operation: 'upload', provider: 'mock' });
+    expect(wrapped).toBe(underlying);
+
+    const genericError = new Error('Something went wrong');
+    const standardized = createStorageError(genericError, { key: 'file.txt' });
+
+    expect(standardized).toBeInstanceOf(StorageError);
+    expect(standardized.code).toBe(StorageErrorCode.PROVIDER_ERROR);
+    expect(standardized.details).toMatchObject({ key: 'file.txt', originalError: genericError });
+    expect(standardized.retryable).toBe(false);
+
+    const stringError = createStorageError('error string');
+    expect(stringError.message).toBe('error string');
+  });
+
+  it('provides quota helper utilities', () => {
+    expect(isQuotaExceeded(100, 100)).toBe(true);
+    expect(isQuotaExceeded(101, 100)).toBe(true);
+    expect(isQuotaExceeded(50, 100)).toBe(false);
+
+    const quota = getQuotaInfo(25, 100, 'mock');
+    expect(quota).toStrictEqual({
+      used: 25,
+      limit: 100,
+      remaining: 75,
+      provider: 'mock',
+      resetAt: undefined,
+    });
+  });
+
+  it('formats and parses file sizes', () => {
+    expect(formatFileSize(0)).toBe('0 B');
+    expect(formatFileSize(1536)).toBe('1.5 KB');
+    expect(formatFileSize(5 * 1024 * 1024)).toBe('5 MB');
+
+    expect(parseFileSize('10 MB')).toBe(10 * 1024 * 1024);
+    expect(parseFileSize('1.5GB')).toBeCloseTo(1.5 * 1024 * 1024 * 1024);
+    expect(() => parseFileSize('unknown')).toThrowError(ValidationError);
+    expect(() => parseFileSize('100')).toThrowError(ValidationError);
+    expect(() => parseFileSize('10 ZZ')).toThrowError(ValidationError);
+  });
+
+  it('validates URLs for SSRF protection', () => {
+    // Valid
+    expect(validateUrlForSSRF('https://example.com/image.jpg')).toStrictEqual({ valid: true });
+
+    // Non-HTTPS
+    expect(validateUrlForSSRF('http://example.com')).toStrictEqual({
+      valid: false,
+      error: 'Only HTTPS URLs are allowed',
+    });
+
+    // Localhost / Loopback
+    expect(validateUrlForSSRF('https://localhost/admin')).toStrictEqual({
+      valid: false,
+      error:
+        'URL hostname "localhost" is blocked for security reasons (private IP, localhost, or reserved address)',
+    });
+    expect(validateUrlForSSRF('https://127.0.0.1')).toStrictEqual({
+      valid: false,
+      error:
+        'URL hostname "127.0.0.1" is blocked for security reasons (private IP, localhost, or reserved address)',
+    });
+
+    // Private Ranges
+    expect(validateUrlForSSRF('https://10.0.0.1')).toStrictEqual({
+      valid: false,
+      error:
+        'URL hostname "10.0.0.1" is blocked for security reasons (private IP, localhost, or reserved address)',
+    });
+    expect(validateUrlForSSRF('https://192.168.1.1')).toStrictEqual({
+      valid: false,
+      error:
+        'URL hostname "192.168.1.1" is blocked for security reasons (private IP, localhost, or reserved address)',
+    });
+
+    // Cloud Metadata
+    expect(validateUrlForSSRF('https://169.254.169.254')).toStrictEqual({
+      valid: false,
+      error:
+        'URL hostname "169.254.169.254" is blocked for security reasons (private IP, localhost, or reserved address)',
+    });
+
+    // IPv6 Loopback
+    expect(validateUrlForSSRF('https://[::1]')).toStrictEqual({
+      valid: false,
+      error:
+        'URL hostname "[::1]" is blocked for security reasons (private IP, localhost, or reserved address)',
+    });
+
+    // Local domains
+    expect(validateUrlForSSRF('https://internal.local')).toStrictEqual({
+      valid: false,
+      error:
+        'URL hostname "internal.local" is blocked for security reasons (private IP, localhost, or reserved address)',
+    });
+
+    // Invalid format
+    expect(validateUrlForSSRF('not-a-url')).toStrictEqual({
+      valid: false,
+      error: 'Invalid URL format',
+    });
+  });
+
+  it('exposes concrete error subclasses for completeness', () => {
+    const storageError = new StorageError('base', StorageErrorCode.CONFIG_ERROR);
+    const providerError = new ProviderError('provider', 'mock');
+    const networkError = new NetworkError('network');
+    const uploadError = new UploadError('upload');
+    const downloadError = new DownloadError('download');
+    const configError = new ConfigError('config');
+
+    expect(storageError).toBeInstanceOf(StorageError);
+    expect(providerError.details?.provider).toBe('mock');
+    expect(networkError.retryable).toBe(true);
+    expect(uploadError.code).toBe(StorageErrorCode.UPLOAD_FAILED);
+    expect(downloadError.code).toBe(StorageErrorCode.DOWNLOAD_FAILED);
+    expect(configError.retryable).toBe(false);
+  });
+});