@od-oneapp/storage 2026.1.1301

package/src/validation.ts

@@ -0,0 +1,827 @@
+/**
+ * @fileoverview Storage Validation and Error Handling
+ *
+ * Provides comprehensive validation utilities and error types for storage operations.
+ *
+ * Features:
+ * - File size validation
+ * - MIME type validation
+ * - Storage key validation
+ * - Error types and handling
+ * - SSRF protection
+ *
+ * @module @repo/storage/validation
+ */
+
+/**
+ * Storage error codes
+ */
+export enum StorageErrorCode {
+  // Validation errors
+  INVALID_KEY = 'INVALID_KEY',
+  INVALID_FILE_SIZE = 'INVALID_FILE_SIZE',
+  INVALID_MIME_TYPE = 'INVALID_MIME_TYPE',
+  INVALID_OPTIONS = 'INVALID_OPTIONS',
+
+  // Provider errors
+  PROVIDER_ERROR = 'PROVIDER_ERROR',
+  PROVIDER_UNAVAILABLE = 'PROVIDER_UNAVAILABLE',
+  PROVIDER_QUOTA_EXCEEDED = 'PROVIDER_QUOTA_EXCEEDED',
+
+  // Network errors
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  TIMEOUT = 'TIMEOUT',
+  CONNECTION_FAILED = 'CONNECTION_FAILED',
+
+  // Upload errors
+  UPLOAD_FAILED = 'UPLOAD_FAILED',
+  UPLOAD_CANCELLED = 'UPLOAD_CANCELLED',
+  UPLOAD_PARTIAL = 'UPLOAD_PARTIAL',
+
+  // Download errors
+  DOWNLOAD_FAILED = 'DOWNLOAD_FAILED',
+  FILE_NOT_FOUND = 'FILE_NOT_FOUND',
+  ACCESS_DENIED = 'ACCESS_DENIED',
+
+  // Configuration errors
+  CONFIG_ERROR = 'CONFIG_ERROR',
+  MISSING_CREDENTIALS = 'MISSING_CREDENTIALS',
+  INVALID_CONFIG = 'INVALID_CONFIG',
+}
+
+/**
+ * Base storage error class
+ */
+export class StorageError extends Error {
+  public readonly code: StorageErrorCode;
+  public readonly details?: Record<string, any>;
+  public readonly retryable: boolean;
+
+  constructor(
+    message: string,
+    code: StorageErrorCode,
+    details?: Record<string, any>,
+    retryable: boolean = false,
+  ) {
+    super(message);
+    this.name = 'StorageError';
+    this.code = code;
+    this.details = details;
+    this.retryable = retryable;
+  }
+}
+
+/**
+ * Validation error for invalid input
+ */
+export class ValidationError extends StorageError {
+  constructor(message: string, details?: Record<string, any>) {
+    super(message, StorageErrorCode.INVALID_OPTIONS, details, false);
+    this.name = 'ValidationError';
+  }
+}
+
+/**
+ * Provider-specific error
+ */
+export class ProviderError extends StorageError {
+  constructor(
+    message: string,
+    provider: string,
+    details?: Record<string, any>,
+    retryable: boolean = false,
+  ) {
+    super(message, StorageErrorCode.PROVIDER_ERROR, { ...details, provider }, retryable);
+    this.name = 'ProviderError';
+  }
+}
+
+/**
+ * Network-related error
+ */
+export class NetworkError extends StorageError {
+  constructor(message: string, details?: Record<string, any>, retryable: boolean = true) {
+    super(message, StorageErrorCode.NETWORK_ERROR, details, retryable);
+    this.name = 'NetworkError';
+  }
+}
+
+/**
+ * Upload-specific error
+ */
+export class UploadError extends StorageError {
+  constructor(message: string, details?: Record<string, any>, retryable: boolean = true) {
+    super(message, StorageErrorCode.UPLOAD_FAILED, details, retryable);
+    this.name = 'UploadError';
+  }
+}
+
+/**
+ * Download-specific error
+ */
+export class DownloadError extends StorageError {
+  constructor(message: string, details?: Record<string, any>, retryable: boolean = true) {
+    super(message, StorageErrorCode.DOWNLOAD_FAILED, details, retryable);
+    this.name = 'DownloadError';
+  }
+}
+
+/**
+ * Configuration error
+ */
+export class ConfigError extends StorageError {
+  constructor(message: string, details?: Record<string, any>) {
+    super(message, StorageErrorCode.CONFIG_ERROR, details, false);
+    this.name = 'ConfigError';
+  }
+}
+
+/**
+ * Validation options
+ */
+export interface ValidationOptions {
+  maxFileSize?: number;
+  allowedMimeTypes?: string[];
+  allowedExtensions?: string[];
+  maxKeyLength?: number;
+  forbiddenKeyPatterns?: RegExp[];
+  requireContentType?: boolean;
+}
+
+/**
+ * Quota information
+ */
+export interface QuotaInfo {
+  used: number;
+  limit: number;
+  remaining: number;
+  resetAt?: Date;
+  provider: string;
+}
+
+/**
+ * Validate file size
+ *
+ * @param size - File size in bytes
+ * @param maxSize - Maximum allowed size in bytes
+ * @returns Validation result
+ */
+export function validateFileSize(
+  size: number,
+  maxSize: number,
+): { valid: boolean; error?: string } {
+  if (size < 0) {
+    return { valid: false, error: 'File size cannot be negative' };
+  }
+
+  if (size > maxSize) {
+    return {
+      valid: false,
+      error: `File size ${size} bytes exceeds maximum ${maxSize} bytes`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Dangerous MIME types that should be blocked for security reasons
+ *
+ * These types can execute code or present security risks:
+ * - Executables (.exe, .dll, .app)
+ * - Scripts (.sh, .bat, .cmd, .js, .php, .py, .pl)
+ * - Archives with executables (.jar)
+ * - Windows system files (.com, .pif, .scr)
+ */
+const DANGEROUS_MIME_TYPES = [
+  // Executables
+  'application/x-msdownload', // .exe
+  'application/x-executable',
+  'application/x-dosexec',
+  'application/x-msdos-program',
+  'application/x-dll',
+  'application/x-app',
+
+  // Scripts
+  'application/x-sh', // Shell scripts
+  'text/x-sh',
+  'application/x-bat', // Batch files
+  'application/x-cmd',
+  'text/x-python', // Python scripts
+  'application/x-python-code',
+  'text/x-perl', // Perl scripts
+  'application/x-perl',
+  'application/javascript', // JavaScript (unless explicitly allowed)
+  'text/javascript',
+  'application/x-javascript',
+  'application/x-php', // PHP
+  'application/x-httpd-php',
+  'text/x-php',
+
+  // Windows system files
+  'application/x-com',
+  'application/x-pif',
+  'application/x-scr',
+  'application/x-vbs', // VBScript
+  'text/vbscript',
+
+  // Java
+  'application/java-archive', // .jar (can contain malicious code)
+  'application/x-java-applet',
+] as const;
+
+/**
+ * MIME type to file extension mappings for validation
+ *
+ * Maps common MIME types to their expected file extensions to prevent
+ * extension spoofing attacks (e.g., executable disguised as image)
+ */
+const MIME_TO_EXTENSIONS: Record<string, readonly string[]> = {
+  // Images
+  'image/jpeg': ['.jpg', '.jpeg'],
+  'image/png': ['.png'],
+  'image/gif': ['.gif'],
+  'image/webp': ['.webp'],
+  'image/svg+xml': ['.svg'],
+  'image/bmp': ['.bmp'],
+  'image/tiff': ['.tif', '.tiff'],
+  'image/avif': ['.avif'],
+
+  // Documents
+  'application/pdf': ['.pdf'],
+  'text/plain': ['.txt'],
+  'text/csv': ['.csv'],
+  'text/html': ['.html', '.htm'],
+  'text/xml': ['.xml'],
+  'application/json': ['.json'],
+
+  // Microsoft Office
+  'application/msword': ['.doc'],
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document': ['.docx'],
+  'application/vnd.ms-excel': ['.xls'],
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': ['.xlsx'],
+  'application/vnd.ms-powerpoint': ['.ppt'],
+  'application/vnd.openxmlformats-officedocument.presentationml.presentation': ['.pptx'],
+
+  // Archives (safe ones)
+  'application/zip': ['.zip'],
+  'application/x-gzip': ['.gz'],
+  'application/x-tar': ['.tar'],
+  'application/x-7z-compressed': ['.7z'],
+
+  // Audio
+  'audio/mpeg': ['.mp3'],
+  'audio/wav': ['.wav'],
+  'audio/ogg': ['.ogg'],
+  'audio/mp4': ['.m4a'],
+
+  // Video
+  'video/mp4': ['.mp4'],
+  'video/mpeg': ['.mpeg', '.mpg'],
+  'video/quicktime': ['.mov'],
+  'video/webm': ['.webm'],
+  'video/x-msvideo': ['.avi'],
+} as const;
+
+/**
+ * Validate MIME type against allowed types and dangerous content
+ *
+ * This function:
+ * 1. Blocks dangerous MIME types (executables, scripts) for security
+ * 2. Validates against allowed types list if provided
+ * 3. Supports wildcard patterns (e.g., image/*)
+ *
+ * @param mimeType - MIME type to validate
+ * @param allowedTypes - Array of allowed MIME types (optional)
+ * @returns Validation result with error message if invalid
+ *
+ * @example
+ * ```typescript
+ * // Block dangerous types
+ * validateMimeType('application/x-msdownload', ['image/*'])
+ * // => { valid: false, error: '...' }
+ *
+ * // Allow specific safe types
+ * validateMimeType('image/jpeg', ['image/*'])
+ * // => { valid: true }
+ * ```
+ */
+export function validateMimeType(
+  mimeType: string,
+  allowedTypes: string[] = [],
+): { valid: boolean; error?: string } {
+  if (!mimeType) {
+    return { valid: false, error: 'MIME type is required' };
+  }
+
+  const normalizedMimeType = mimeType.toLowerCase().trim();
+
+  // Block dangerous MIME types first (security check)
+  if (DANGEROUS_MIME_TYPES.includes(normalizedMimeType as (typeof DANGEROUS_MIME_TYPES)[number])) {
+    return {
+      valid: false,
+      error: `Content type '${mimeType}' is not allowed for security reasons (executable or script content)`,
+    };
+  }
+
+  // If no allowed types specified, allow all safe types
+  if (allowedTypes.length === 0) {
+    return { valid: true };
+  }
+
+  const normalizedAllowed = allowedTypes.map(t => t.toLowerCase().trim());
+
+  // Check exact match
+  if (normalizedAllowed.includes(normalizedMimeType)) {
+    return { valid: true };
+  }
+
+  // Check wildcard patterns (e.g., image/*)
+  const wildcardMatch = normalizedAllowed.some(allowed => {
+    if (allowed.endsWith('/*')) {
+      const prefix = allowed.slice(0, -2);
+      return normalizedMimeType.startsWith(prefix);
+    }
+    return false;
+  });
+
+  if (wildcardMatch) {
+    return { valid: true };
+  }
+
+  return {
+    valid: false,
+    error: `MIME type '${mimeType}' is not allowed. Allowed types: ${allowedTypes.join(', ')}`,
+  };
+}
+
+/**
+ * Validate file extension matches expected extension for MIME type
+ *
+ * Prevents extension spoofing attacks where malicious files are disguised
+ * with incorrect extensions (e.g., executable.exe renamed to image.jpg)
+ *
+ * @param filename - File name with extension
+ * @param contentType - MIME type of the file
+ * @returns Validation result with error message if mismatch detected
+ *
+ * @example
+ * ```typescript
+ * // Valid: JPEG file with .jpg extension
+ * validateFileExtension('photo.jpg', 'image/jpeg')
+ * // => { valid: true }
+ *
+ * // Invalid: JPEG MIME type with .exe extension (spoofing)
+ * validateFileExtension('photo.exe', 'image/jpeg')
+ * // => { valid: false, error: '...' }
+ *
+ * // Unknown MIME type: allowed with warning
+ * validateFileExtension('data.custom', 'application/x-custom')
+ * // => { valid: true } (with warning logged)
+ * ```
+ */
+export function validateFileExtension(
+  filename: string,
+  contentType: string,
+): { valid: boolean; error?: string } {
+  if (!filename || !contentType) {
+    return { valid: false, error: 'Filename and content type are required' };
+  }
+
+  // Extract file extension
+  const lastDotIndex = filename.lastIndexOf('.');
+  if (lastDotIndex === -1) {
+    return { valid: false, error: 'File must have an extension' };
+  }
+
+  const extension = filename.substring(lastDotIndex).toLowerCase();
+  const normalizedMimeType = contentType.toLowerCase().trim();
+
+  // Check if we have extension mapping for this MIME type
+  const allowedExtensions = MIME_TO_EXTENSIONS[normalizedMimeType];
+
+  if (!allowedExtensions) {
+    // Unknown MIME type - allow but this should be logged upstream
+    // Don't fail validation for unknown types (extensibility)
+    return { valid: true };
+  }
+
+  // Validate extension matches expected extensions for this MIME type
+  if (!allowedExtensions.includes(extension)) {
+    return {
+      valid: false,
+      error: `File extension '${extension}' does not match content type '${contentType}'. Expected: ${allowedExtensions.join(', ')}`,
+    };
+  }
+
+  return { valid: true };
+}
+
+// Import validateStorageKey for internal use in this file
+import { validateStorageKey } from '../keys';
+
+/**
+ * Validate storage key
+ *
+ * Re-exports from keys.ts for backwards compatibility.
+ * Use validateStorageKey from '../keys' for the canonical implementation.
+ *
+ * @param key - Storage key to validate
+ * @param options - Validation options
+ * @returns Validation result
+ */
+export { validateStorageKey };
+
+/**
+ * Validate upload options
+ *
+ * @param options - Upload options to validate
+ * @param validationOptions - Validation constraints
+ * @returns Validation result
+ */
+export function validateUploadOptions(
+  options: {
+    fileSize?: number;
+    contentType?: string;
+    key?: string;
+  },
+  validationOptions: ValidationOptions = {},
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  // Validate file size
+  if (options?.fileSize && validationOptions.maxFileSize) {
+    const sizeValidation = validateFileSize(options.fileSize, validationOptions.maxFileSize);
+    if (!sizeValidation.valid) {
+      if (sizeValidation.error) {
+        errors.push(sizeValidation.error);
+      }
+    }
+  }
+
+  // Validate MIME type
+  if (options?.contentType && validationOptions.allowedMimeTypes) {
+    const mimeValidation = validateMimeType(
+      options.contentType,
+      validationOptions.allowedMimeTypes,
+    );
+    if (!mimeValidation.valid) {
+      if (mimeValidation.error) {
+        errors.push(mimeValidation.error);
+      }
+    }
+  }
+
+  // Validate key
+  if (options?.key) {
+    const keyValidation = validateStorageKey(options.key, {
+      maxLength: validationOptions.maxKeyLength,
+      forbiddenPatterns: validationOptions.forbiddenKeyPatterns,
+    });
+    if (!keyValidation.valid && keyValidation.errors.length > 0) {
+      errors.push(...keyValidation.errors);
+    }
+  }
+
+  // Require content type
+  if (validationOptions.requireContentType && !options?.contentType) {
+    errors.push('Content type is required');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Determines if an error should be retried based on error type and message
+ *
+ * Checks for common transient failures that are safe to retry:
+ * - Network timeouts
+ * - Connection failures (ECONNRESET, ENOTFOUND, ETIMEDOUT)
+ * - Rate limiting (429, 503 status codes)
+ * - Server errors (500-599 status codes)
+ *
+ * @param error - Error instance to analyze (any type accepted)
+ * @returns `true` if the error indicates a transient failure that should be retried
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await storage.upload(key, data);
+ * } catch (error) {
+ *   if (isRetryableError(error)) {
+ *     // Retry the operation
+ *     await retryWithBackoff(() => storage.upload(key, data));
+ *   } else {
+ *     // Permanent failure - don't retry
+ *     throw error;
+ *   }
+ * }
+ * ```
+ */
+export function isRetryableError(error: unknown): boolean {
+  if (error instanceof StorageError) {
+    return error.retryable;
+  }
+
+  // Check for common retryable error patterns
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase();
+    return (
+      message.includes('timeout') ||
+      message.includes('network') ||
+      message.includes('connection') ||
+      message.includes('rate limit') ||
+      message.includes('temporary')
+    );
+  }
+
+  return false;
+}
+
+/**
+ * Extracts a standardized error code from any error type
+ *
+ * Maps common error messages to StorageErrorCode enum values:
+ * - "not found" → FILE_NOT_FOUND
+ * - "access denied" → ACCESS_DENIED
+ * - "timeout" → TIMEOUT
+ * - "network" → NETWORK_ERROR
+ * - Others → PROVIDER_ERROR
+ *
+ * @param error - Error of any type (StorageError, Error, string, unknown)
+ * @returns StorageErrorCode enum value for categorization
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await storage.delete(key);
+ * } catch (error) {
+ *   const code = getErrorCode(error);
+ *   if (code === StorageErrorCode.FILE_NOT_FOUND) {
+ *     // File already deleted - ignore
+ *     return { success: true };
+ *   }
+ *   throw error;
+ * }
+ * ```
+ */
+export function getErrorCode(error: unknown): StorageErrorCode {
+  if (error instanceof StorageError) {
+    return error.code;
+  }
+
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase();
+    if (message.includes('not found')) return StorageErrorCode.FILE_NOT_FOUND;
+    if (message.includes('access denied')) return StorageErrorCode.ACCESS_DENIED;
+    if (message.includes('timeout')) return StorageErrorCode.TIMEOUT;
+    if (message.includes('network')) return StorageErrorCode.NETWORK_ERROR;
+  }
+
+  return StorageErrorCode.PROVIDER_ERROR;
+}
+
+/**
+ * Wraps any error into a standardized StorageError with additional context
+ *
+ * Converts plain errors into structured StorageError instances with:
+ * - Proper error code classification
+ * - Operation context (upload, delete, etc.)
+ * - Provider information
+ * - Storage key reference
+ *
+ * @param error - Original error of any type
+ * @param context - Additional context to attach to the error
+ * @param context.operation - Storage operation being performed (e.g., "upload", "delete")
+ * @param context.provider - Storage provider name (e.g., "cloudflare-r2", "vercel-blob")
+ * @param context.key - Storage key being operated on
+ * @returns Standardized StorageError instance with full context
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await provider.upload(key, data);
+ * } catch (error) {
+ *   throw createStorageError(error, {
+ *     operation: 'upload',
+ *     provider: 'vercel-blob',
+ *     key,
+ *   });
+ * }
+ * ```
+ */
+export function createStorageError(
+  error: unknown,
+  context: {
+    operation?: string;
+    provider?: string;
+    key?: string;
+  } = {},
+): StorageError {
+  if (error instanceof StorageError) {
+    return error;
+  }
+
+  const message = error instanceof Error ? error.message : String(error);
+  const code = getErrorCode(error);
+  const retryable = isRetryableError(error);
+
+  return new StorageError(
+    message,
+    code,
+    {
+      originalError: error,
+      ...context,
+    },
+    retryable,
+  );
+}
+
+/**
+ * Check quota information
+ *
+ * @param used - Used quota in bytes
+ * @param limit - Quota limit in bytes
+ * @returns Quota information
+ */
+export function getQuotaInfo(used: number, limit: number, provider: string): QuotaInfo {
+  return {
+    used,
+    limit,
+    remaining: Math.max(0, limit - used),
+    provider,
+    resetAt: undefined, // Provider-specific
+  };
+}
+
+/**
+ * Check if quota is exceeded
+ *
+ * @param used - Used quota in bytes
+ * @param limit - Quota limit in bytes
+ * @returns True if quota is exceeded
+ */
+export function isQuotaExceeded(used: number, limit: number): boolean {
+  return used >= limit;
+}
+
+/**
+ * Format file size for display
+ *
+ * @param bytes - Size in bytes
+ * @returns Formatted size string
+ */
+export function formatFileSize(bytes: number): string {
+  if (bytes === 0) return '0 B';
+
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
+}
+
+/**
+ * Parse file size from string
+ *
+ * @param sizeString - Size string (e.g., "10MB", "1.5GB")
+ * @returns Size in bytes
+ */
+export function parseFileSize(sizeString: string): number {
+  // eslint-disable-next-line security/detect-unsafe-regex
+  const match = sizeString.match(/^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB|TB)$/i);
+  if (!match) {
+    throw new ValidationError(`Invalid file size format: ${sizeString}`);
+  }
+
+  const valueStr = match[1];
+  const unitStr = match[2];
+  if (!valueStr || !unitStr) {
+    throw new ValidationError(`Invalid file size format: ${sizeString}`);
+  }
+
+  const value = parseFloat(valueStr);
+  const unit = unitStr.toUpperCase();
+
+  const multipliers: Record<string, number> = {
+    B: 1,
+    KB: 1024,
+    MB: 1024 * 1024,
+    GB: 1024 * 1024 * 1024,
+    TB: 1024 * 1024 * 1024 * 1024,
+  };
+
+  const multiplier = multipliers[unit];
+  if (multiplier === undefined) {
+    throw new ValidationError(`Unknown unit: ${unit}`);
+  }
+
+  return value * multiplier;
+}
+
+/**
+ * Blocked hostname patterns for SSRF prevention
+ * Comprehensive list covering IPv4, IPv6, and special addresses
+ */
+const SSRF_BLOCKED_PATTERNS: RegExp[] = [
+  // IPv4 localhost and loopback
+  /^localhost$/i,
+  /^127\./,
+  /^0\./,
+
+  // IPv4 private ranges (RFC 1918)
+  /^10\./,
+  /^172\.(1[6-9]|2[0-9]|3[0-1])\./,
+  /^192\.168\./,
+
+  // Link-local IPv4 (includes cloud metadata endpoints)
+  /^169\.254\./,
+
+  // Carrier-grade NAT (RFC 6598)
+  /^100\.(6[4-9]|[7-9]\d|1[0-1]\d|12[0-7])\./,
+
+  // Class E reserved
+  /^240\./,
+
+  // IPv6 localhost
+  /^::1$/,
+  /^\[::1\]$/,
+
+  // IPv6 link-local
+  /^fe80:/i,
+  /^\[fe80:/i,
+
+  // IPv6 unique local (private)
+  /^fc00:/i,
+  /^fd00:/i,
+
+  // IPv4-mapped IPv6
+  /^::ffff:0:0:/i,
+
+  // IPv6 multicast
+  /^ff00:/i,
+
+  // Domain patterns
+  /\.local$/i,
+];
+
+/**
+ * Validates URL safety to prevent SSRF (Server-Side Request OneAppry) attacks
+ *
+ * This function blocks:
+ * - Non-HTTPS URLs (only HTTPS is allowed)
+ * - Localhost and loopback addresses (127.0.0.1, ::1, etc.)
+ * - Private IP ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
+ * - Cloud metadata endpoints (169.254.169.254)
+ * - Link-local addresses (169.254.0.0/16, fe80::/10)
+ * - Carrier-grade NAT ranges (100.64.0.0/10)
+ * - IPv6 private/special addresses (fc00::/7, ff00::/8)
+ * - .local domain suffix
+ *
+ * @param url - The URL to validate
+ * @returns Object with valid boolean and optional error message
+ *
+ * @example
+ * ```typescript
+ * const result = validateUrlForSSRF('https://example.com/image.jpg');
+ * if (!result.valid) {
+ *   throw new Error(result.error);
+ * }
+ * ```
+ */
+export function validateUrlForSSRF(url: string): {
+  valid: boolean;
+  error?: string;
+} {
+  try {
+    const parsed = new URL(url);
+
+    // Only allow HTTPS (not HTTP or other protocols)
+    if (parsed.protocol !== 'https:') {
+      return {
+        valid: false,
+        error: 'Only HTTPS URLs are allowed',
+      };
+    }
+
+    const hostname = parsed.hostname.toLowerCase();
+
+    // Check against all blocked patterns
+    if (SSRF_BLOCKED_PATTERNS.some(pattern => pattern.test(hostname))) {
+      return {
+        valid: false,
+        error: `URL hostname "${hostname}" is blocked for security reasons (private IP, localhost, or reserved address)`,
+      };
+    }
+
+    return { valid: true };
+  } catch {
+    return {
+      valid: false,
+      error: 'Invalid URL format',
+    };
+  }
+}