podverse-helpers 5.1.26-alpha.0 → 5.1.28-alpha.0

package/dist/lib/validation/startupValidation.js

@@ -0,0 +1,497 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateRequired = validateRequired;
+exports.validateOptional = validateOptional;
+exports.validateConditionalOptional = validateConditionalOptional;
+exports.getAllAvailableOrListMessage = getAllAvailableOrListMessage;
+exports.displayValidationResultsSilent = displayValidationResultsSilent;
+exports.validateLocale = validateLocale;
+exports.validateSupportedLocalesList = validateSupportedLocalesList;
+exports.validateOptionalNonEmpty = validateOptionalNonEmpty;
+exports.validateBoolean = validateBoolean;
+exports.validateWebProtocol = validateWebProtocol;
+exports.validateLogLevel = validateLogLevel;
+exports.validatePositiveNumber = validatePositiveNumber;
+const locales_1 = require("../constants/locales");
+/**
+ * Validates a required environment variable
+ * @param varName - The name of the environment variable to validate
+ * @param category - The category/group this variable belongs to (for display purposes)
+ * @returns ValidationResult indicating whether the variable is set and valid
+ */
+function validateRequired(varName, category) {
+    const value = process.env[varName];
+    const isSet = value !== undefined && value !== null && typeof value === 'string' && value.trim() !== '';
+    // Additional validation for numeric values
+    if (isSet && (varName.includes('PORT') || varName.includes('EXPIRATION') || varName.includes('CACHE_TTL'))) {
+        const numValue = Number(value);
+        if (isNaN(numValue) || numValue <= 0) {
+            return {
+                name: varName,
+                isSet: true,
+                isValid: false,
+                isRequired: true,
+                message: `Invalid number: "${value}"`,
+                category
+            };
+        }
+    }
+    // Additional validation for API_ALLOWED_CORS_ORIGINS (should not be empty)
+    if (varName === 'API_ALLOWED_CORS_ORIGINS' && isSet) {
+        const origins = value.split(',').map(origin => origin.trim()).filter(origin => origin !== '');
+        if (origins.length === 0) {
+            return {
+                name: varName,
+                isSet: true,
+                isValid: false,
+                isRequired: true,
+                message: 'Empty - must contain at least one origin',
+                category
+            };
+        }
+    }
+    return {
+        name: varName,
+        isSet,
+        isValid: isSet,
+        isRequired: true,
+        message: isSet ? 'Set' : 'Missing or empty',
+        category
+    };
+}
+/**
+ * Validates an optional environment variable
+ * @param varName - The name of the environment variable to validate
+ * @param category - The category/group this variable belongs to (for display purposes)
+ * @param defaultMessage - Optional message to display when variable is not set (defaults to "Skipped")
+ * @returns ValidationResult indicating whether the variable is set and valid (optional vars are always valid even if not set)
+ */
+function validateOptional(varName, category, defaultMessage = 'Skipped') {
+    const value = process.env[varName] || '';
+    const isSet = value !== '';
+    // Additional validation for numeric values if set
+    if (isSet && (varName.includes('PORT') || varName.includes('EXPIRATION') || varName.includes('CACHE_TTL'))) {
+        const numValue = Number(value);
+        if (isNaN(numValue) || numValue <= 0) {
+            return {
+                name: varName,
+                isSet: true,
+                isValid: false,
+                isRequired: false,
+                message: `Invalid number: "${value}"`,
+                category
+            };
+        }
+    }
+    return {
+        name: varName,
+        isSet,
+        isValid: true, // Optional vars are always valid (even if not set)
+        isRequired: false,
+        message: isSet ? 'Set' : defaultMessage,
+        category
+    };
+}
+/**
+ * Validates a conditionally optional environment variable (only logs if set but not needed)
+ * Returns null if variable is not set (so it won't be included in results)
+ * @param varName - The name of the environment variable to validate
+ * @param category - The category/group this variable belongs to (for display purposes)
+ * @returns ValidationResult if variable is set, null otherwise
+ */
+function validateConditionalOptional(varName, category) {
+    const value = process.env[varName] || '';
+    const isSet = value !== '';
+    // Only validate if the variable is set (if not set, don't include in results)
+    if (!isSet) {
+        return null;
+    }
+    // Additional validation for numeric values if set
+    if (varName.includes('PORT') || varName.includes('EXPIRATION') || varName.includes('CACHE_TTL')) {
+        const numValue = Number(value);
+        if (isNaN(numValue) || numValue <= 0) {
+            return {
+                name: varName,
+                isSet: true,
+                isValid: false,
+                isRequired: false,
+                message: `Invalid number: "${value}"`,
+                category
+            };
+        }
+    }
+    return {
+        name: varName,
+        isSet: true,
+        isValid: true,
+        isRequired: false,
+        message: 'Set (not needed when signup mode is disabled)',
+        category
+    };
+}
+/**
+ * Generates a validation error message for variables that accept "all-available" or comma-delimited list
+ * @param validValues - Array of valid values that can be used in the comma-delimited list
+ * @returns Error message string
+ */
+function getAllAvailableOrListMessage(validValues) {
+    return `must be "all-available" or comma-delimited list (valid values: ${validValues.join(', ')})`;
+}
+/**
+ * Displays validation results silently - only logs failures.
+ * This is intended for modules (not apps) that should not show validation output unless there are errors.
+ * @param summary - The validation summary to display
+ */
+function displayValidationResultsSilent(summary) {
+    // Only log if there are failures
+    if (summary.failed === 0 && summary.requiredMissing === 0) {
+        return;
+    }
+    // Group results by category
+    const byCategory = summary.results.reduce((acc, result) => {
+        if (!acc[result.category]) {
+            acc[result.category] = [];
+        }
+        acc[result.category].push(result);
+        return acc;
+    }, {});
+    // Display failures by category
+    const categories = Object.keys(byCategory).sort();
+    for (const category of categories) {
+        const failures = byCategory[category].filter(r => !r.isValid);
+        if (failures.length > 0) {
+            console.error(`[${category}]`);
+            for (const result of failures) {
+                const requiredText = result.isRequired ? ' (required)' : ' (optional)';
+                console.error(`  ✗ ${result.name}${requiredText} - ${result.message}`);
+            }
+        }
+    }
+    // Display summary of failures
+    if (summary.failed > 0) {
+        console.error('\n=== Validation Failures ===');
+        console.error(`Failed: ${summary.failed}`);
+        console.error(`Required Missing: ${summary.requiredMissing}`);
+        if (summary.requiredMissing > 0) {
+            console.error('\nThe following required environment variables are missing or invalid:');
+            summary.results
+                .filter(r => r.isRequired && !r.isValid)
+                .forEach(r => {
+                console.error(`  - ${r.name}: ${r.message}`);
+            });
+        }
+    }
+}
+/**
+ * Validates a single locale value against supported locales
+ * @param varName - The name of the environment variable to validate
+ * @param category - The category/group this variable belongs to (for display purposes)
+ * @param isRequired - Whether the variable is required (default: true)
+ * @returns ValidationResult indicating whether the locale is valid
+ */
+function validateLocale(varName, category, isRequired = true) {
+    const value = process.env[varName] || '';
+    const isSet = value !== '';
+    if (!isSet) {
+        return {
+            name: varName,
+            isSet: false,
+            isValid: !isRequired,
+            isRequired,
+            message: isRequired
+                ? `Missing - must be one of: ${locales_1.SUPPORTED_LOCALES.join(', ')}`
+                : 'Skipped',
+            category
+        };
+    }
+    const trimmedValue = value.trim();
+    if (!locales_1.SUPPORTED_LOCALES.includes(trimmedValue)) {
+        return {
+            name: varName,
+            isSet: true,
+            isValid: false,
+            isRequired,
+            message: `Invalid locale: "${value}". Valid locales: ${locales_1.SUPPORTED_LOCALES.join(', ')}`,
+            category
+        };
+    }
+    return {
+        name: varName,
+        isSet: true,
+        isValid: true,
+        isRequired,
+        message: `Valid locale: ${trimmedValue}`,
+        category
+    };
+}
+/**
+ * Validates NEXT_PUBLIC_FEATURES_SUPPORTED_LOCALES
+ * Must be "all-available" or comma-delimited list of valid locales
+ * @param varName - The name of the environment variable to validate (defaults to 'NEXT_PUBLIC_FEATURES_SUPPORTED_LOCALES')
+ * @param category - The category/group this variable belongs to (for display purposes)
+ * @returns ValidationResult indicating whether the supported locales list is valid
+ */
+function validateSupportedLocalesList(varName = 'NEXT_PUBLIC_FEATURES_SUPPORTED_LOCALES', category) {
+    const value = process.env[varName] || '';
+    const isSet = value !== '';
+    if (!isSet || value.trim() === '') {
+        return {
+            name: varName,
+            isSet: false,
+            isValid: false,
+            isRequired: true,
+            message: `Missing - ${getAllAvailableOrListMessage(locales_1.SUPPORTED_LOCALES)}`,
+            category
+        };
+    }
+    const trimmedValue = value.trim();
+    // Allow "all-available" as a special value
+    if (trimmedValue === 'all-available') {
+        return {
+            name: varName,
+            isSet: true,
+            isValid: true,
+            isRequired: true,
+            message: 'Set to "all-available"',
+            category
+        };
+    }
+    // Validate comma-delimited list of locales
+    const locales = trimmedValue.split(',').map(l => l.trim()).filter(Boolean);
+    if (locales.length === 0) {
+        return {
+            name: varName,
+            isSet: true,
+            isValid: false,
+            isRequired: true,
+            message: `Empty after parsing - ${getAllAvailableOrListMessage(locales_1.SUPPORTED_LOCALES)}`,
+            category
+        };
+    }
+    // Check that all locales are valid
+    const invalidLocales = locales.filter(locale => !locales_1.SUPPORTED_LOCALES.includes(locale));
+    if (invalidLocales.length > 0) {
+        return {
+            name: varName,
+            isSet: true,
+            isValid: false,
+            isRequired: true,
+            message: `Invalid locale(s): ${invalidLocales.join(', ')}. Valid locales: ${locales_1.SUPPORTED_LOCALES.join(', ')}`,
+            category
+        };
+    }
+    return {
+        name: varName,
+        isSet: true,
+        isValid: true,
+        isRequired: true,
+        message: `Valid locales: ${locales.join(', ')}`,
+        category
+    };
+}
+/**
+ * Validates an optional environment variable - if set, must not be empty
+ * @param varName - The name of the environment variable to validate
+ * @param category - The category/group this variable belongs to (for display purposes)
+ * @returns ValidationResult indicating whether the variable is valid (optional, but if set must not be empty)
+ */
+function validateOptionalNonEmpty(varName, category) {
+    const value = process.env[varName];
+    // If not set at all (undefined), it's valid (optional)
+    if (value === undefined || value === null) {
+        return {
+            name: varName,
+            isSet: false,
+            isValid: true,
+            isRequired: false,
+            message: 'Skipped',
+            category
+        };
+    }
+    // If set but empty or only whitespace, it's invalid
+    if (typeof value === 'string' && value.trim() === '') {
+        return {
+            name: varName,
+            isSet: true,
+            isValid: false,
+            isRequired: false,
+            message: 'Empty - if set, must not be empty',
+            category
+        };
+    }
+    // If set and has a value, it's valid
+    return {
+        name: varName,
+        isSet: true,
+        isValid: true,
+        isRequired: false,
+        message: 'Set',
+        category
+    };
+}
+/**
+ * Validates a boolean environment variable - must be "true" or "false" if set
+ * @param varName - The name of the environment variable to validate
+ * @param category - The category/group this variable belongs to (for display purposes)
+ * @param isRequired - Whether the variable is required (default: false)
+ * @param defaultValue - Optional default value message if not set (e.g., "Use Default (false)")
+ * @returns ValidationResult indicating whether the boolean value is valid
+ */
+function validateBoolean(varName, category, isRequired = false, defaultValue) {
+    const value = process.env[varName];
+    const isSet = value !== undefined && value !== null && typeof value === 'string' && value.trim() !== '';
+    if (!isSet) {
+        return {
+            name: varName,
+            isSet: false,
+            isValid: !isRequired,
+            isRequired,
+            message: defaultValue || (isRequired ? 'Missing - must be "true" or "false"' : 'Skipped'),
+            category
+        };
+    }
+    const lowerValue = value.toLowerCase().trim();
+    if (lowerValue !== 'true' && lowerValue !== 'false') {
+        return {
+            name: varName,
+            isSet: true,
+            isValid: false,
+            isRequired,
+            message: `Invalid value: "${value}" - must be "true" or "false"`,
+            category
+        };
+    }
+    return {
+        name: varName,
+        isSet: true,
+        isValid: true,
+        isRequired,
+        message: `Set to ${lowerValue}`,
+        category
+    };
+}
+/**
+ * Validates WEB_PROTOCOL - must be "http" or "https" if set
+ * @param varName - The name of the environment variable to validate (defaults to 'WEB_PROTOCOL')
+ * @param category - The category/group this variable belongs to (for display purposes)
+ * @param isRequired - Whether the variable is required (default: false)
+ * @returns ValidationResult indicating whether the protocol is valid
+ */
+function validateWebProtocol(varName = 'WEB_PROTOCOL', category, isRequired = false) {
+    const value = process.env[varName];
+    const isSet = value !== undefined && value !== null && typeof value === 'string' && value.trim() !== '';
+    if (!isSet) {
+        return {
+            name: varName,
+            isSet: false,
+            isValid: !isRequired,
+            isRequired,
+            message: isRequired ? 'Missing - must be "http" or "https"' : 'Skipped',
+            category
+        };
+    }
+    const lowerValue = value.toLowerCase().trim();
+    if (lowerValue !== 'http' && lowerValue !== 'https') {
+        return {
+            name: varName,
+            isSet: true,
+            isValid: false,
+            isRequired,
+            message: `Invalid protocol: "${value}" - must be "http" or "https"`,
+            category
+        };
+    }
+    return {
+        name: varName,
+        isSet: true,
+        isValid: true,
+        isRequired,
+        message: `Set to ${lowerValue}`,
+        category
+    };
+}
+/**
+ * Validates LOG_LEVEL - must be a valid winston log level
+ * @param varName - The name of the environment variable to validate (defaults to 'LOG_LEVEL')
+ * @param category - The category/group this variable belongs to (for display purposes)
+ * @param isRequired - Whether the variable is required (default: true)
+ * @param validLevels - Optional array of valid log levels (defaults to winston levels)
+ * @returns ValidationResult indicating whether the log level is valid
+ */
+function validateLogLevel(varName = 'LOG_LEVEL', category, isRequired = true, validLevels = ['error', 'warn', 'info', 'debug', 'verbose', 'silly', 'silent']) {
+    const value = process.env[varName];
+    const isSet = value !== undefined && value !== null && typeof value === 'string' && value.trim() !== '';
+    if (!isSet) {
+        return {
+            name: varName,
+            isSet: false,
+            isValid: !isRequired,
+            isRequired,
+            message: isRequired ? `Missing or empty - must be a valid log level (${validLevels.join(', ')})` : 'Skipped',
+            category
+        };
+    }
+    const lowerValue = value.toLowerCase().trim();
+    if (!validLevels.includes(lowerValue)) {
+        return {
+            name: varName,
+            isSet: true,
+            isValid: false,
+            isRequired,
+            message: `Invalid log level: "${value}" - must be one of: ${validLevels.join(', ')}`,
+            category
+        };
+    }
+    return {
+        name: varName,
+        isSet: true,
+        isValid: true,
+        isRequired,
+        message: `Valid log level: ${lowerValue}`,
+        category
+    };
+}
+/**
+ * Validates a positive number environment variable
+ * @param varName - The name of the environment variable to validate
+ * @param category - The category/group this variable belongs to (for display purposes)
+ * @param isRequired - Whether the variable is required (default: false)
+ * @param min - Optional minimum value (default: 1)
+ * @param max - Optional maximum value (no limit if not specified)
+ * @returns ValidationResult indicating whether the number is valid
+ */
+function validatePositiveNumber(varName, category, isRequired = false, min = 1, max) {
+    const value = process.env[varName];
+    const isSet = value !== undefined && value !== null && typeof value === 'string' && value.trim() !== '';
+    if (!isSet) {
+        return {
+            name: varName,
+            isSet: false,
+            isValid: !isRequired,
+            isRequired,
+            message: isRequired ? `Missing - must be a positive number${min > 1 ? ` (min: ${min})` : ''}${max ? ` (max: ${max})` : ''}` : 'Skipped',
+            category
+        };
+    }
+    const numValue = Number(value);
+    if (isNaN(numValue) || numValue < min || (max !== undefined && numValue > max)) {
+        const rangeMsg = max !== undefined ? ` between ${min} and ${max}` : ` >= ${min}`;
+        return {
+            name: varName,
+            isSet: true,
+            isValid: false,
+            isRequired,
+            message: `Invalid number: "${value}" - must be a positive number${rangeMsg}`,
+            category
+        };
+    }
+    const rangeMsg = max !== undefined ? ` (${min}-${max})` : ` (min: ${min})`;
+    return {
+        name: varName,
+        isSet: true,
+        isValid: true,
+        isRequired,
+        message: `Valid number: ${numValue}${rangeMsg}`,
+        category
+    };
+}

package/dist/lib/validation/url.d.ts

@@ -15,4 +15,40 @@ export declare function validateHttpOrHttpsUrl(url?: string | null): {
     isValid: boolean;
     error?: string;
 };
+/**
+ * Checks if an IP address is in a private IP range.
+ * Useful for SSRF protection in any application.
+ *
+ * @param ip - The IP address to check (IPv4 format)
+ * @returns true if the IP is in a private range, false otherwise
+ */
+export declare function isPrivateIP(ip: string): boolean;
+/**
+ * Checks if a hostname is a localhost variant.
+ * Useful for SSRF protection in any application.
+ *
+ * @param hostname - The hostname to check
+ * @returns true if the hostname is a localhost variant, false otherwise
+ */
+export declare function isLocalhost(hostname: string): boolean;
+/**
+ * Validates a URL for SSRF (Server-Side Request Forgery) vulnerabilities.
+ * Checks for private IPs, localhost, and dangerous protocols.
+ * Useful for any application that needs to validate external URLs.
+ *
+ * @param url - The URL to validate
+ * @param options - Optional configuration
+ * @param options.allowPrivateIPs - If true, allows private IP addresses (default: false)
+ * @param options.allowLocalhost - If true, allows localhost URLs (default: false)
+ * @param options.allowedProtocols - Array of allowed protocols (default: ['http:', 'https:'])
+ * @returns Object with isValid boolean and optional error message
+ */
+export declare function validateUrlForSSRF(url: string | null, options?: {
+    allowPrivateIPs?: boolean;
+    allowLocalhost?: boolean;
+    allowedProtocols?: string[];
+}): {
+    isValid: boolean;
+    error?: string;
+};
 //# sourceMappingURL=url.d.ts.map

package/dist/lib/validation/url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../../src/lib/validation/url.ts"],"names":[],"mappings":"AAAA,wBAAgB,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAM/D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAyB1F;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAsBhG"}
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../../src/lib/validation/url.ts"],"names":[],"mappings":"AAAA,wBAAgB,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAM/D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAyB1F;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAsBhG;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CA4B/C;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAarD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,OAAO,GAAE;IACP,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB,GACL;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CA2DtC"}

package/dist/lib/validation/url.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isValidHttpUrl = isValidHttpUrl;
 exports.validateHttpsUrl = validateHttpsUrl;
 exports.validateHttpOrHttpsUrl = validateHttpOrHttpsUrl;
+exports.isPrivateIP = isPrivateIP;
+exports.isLocalhost = isLocalhost;
+exports.validateUrlForSSRF = validateUrlForSSRF;
 function isValidHttpUrl(url) {
     if (!url) {
         return null;
@@ -59,3 +62,113 @@ function validateHttpOrHttpsUrl(url) {
         return { isValid: false, error: 'Invalid URL format' };
     }
 }
+/**
+ * Checks if an IP address is in a private IP range.
+ * Useful for SSRF protection in any application.
+ *
+ * @param ip - The IP address to check (IPv4 format)
+ * @returns true if the IP is in a private range, false otherwise
+ */
+function isPrivateIP(ip) {
+    // IPv4 private ranges
+    // 10.0.0.0/8
+    if (/^10\./.test(ip)) {
+        return true;
+    }
+    // 172.16.0.0/12 (172.16.0.0 - 172.31.255.255)
+    if (/^172\.(1[6-9]|2[0-9]|3[0-1])\./.test(ip)) {
+        return true;
+    }
+    // 192.168.0.0/16
+    if (/^192\.168\./.test(ip)) {
+        return true;
+    }
+    // 127.0.0.0/8 (localhost)
+    if (/^127\./.test(ip)) {
+        return true;
+    }
+    // 169.254.0.0/16 (link-local)
+    if (/^169\.254\./.test(ip)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Checks if a hostname is a localhost variant.
+ * Useful for SSRF protection in any application.
+ *
+ * @param hostname - The hostname to check
+ * @returns true if the hostname is a localhost variant, false otherwise
+ */
+function isLocalhost(hostname) {
+    const lower = hostname.toLowerCase();
+    return (lower === 'localhost' ||
+        lower === '127.0.0.1' ||
+        lower === '::1' ||
+        lower.startsWith('127.') ||
+        lower.startsWith('0.0.0.0') ||
+        lower === '[::1]' ||
+        lower.startsWith('[::1]') ||
+        lower.startsWith('fe80:') ||
+        lower.startsWith('[fe80:'));
+}
+/**
+ * Validates a URL for SSRF (Server-Side Request Forgery) vulnerabilities.
+ * Checks for private IPs, localhost, and dangerous protocols.
+ * Useful for any application that needs to validate external URLs.
+ *
+ * @param url - The URL to validate
+ * @param options - Optional configuration
+ * @param options.allowPrivateIPs - If true, allows private IP addresses (default: false)
+ * @param options.allowLocalhost - If true, allows localhost URLs (default: false)
+ * @param options.allowedProtocols - Array of allowed protocols (default: ['http:', 'https:'])
+ * @returns Object with isValid boolean and optional error message
+ */
+function validateUrlForSSRF(url, options = {}) {
+    if (!url) {
+        return { isValid: false, error: 'URL is required' };
+    }
+    const { allowPrivateIPs = false, allowLocalhost = false, allowedProtocols = ['http:', 'https:'], } = options;
+    try {
+        const parsedUrl = new URL(url);
+        // Check protocol
+        if (!allowedProtocols.includes(parsedUrl.protocol)) {
+            return { isValid: false, error: `Protocol ${parsedUrl.protocol} is not allowed` };
+        }
+        // Block file:// and data: protocols by default
+        if (parsedUrl.protocol === 'file:' || parsedUrl.protocol === 'data:') {
+            return { isValid: false, error: 'Invalid protocol' };
+        }
+        // Check for localhost variants
+        if (!allowLocalhost && isLocalhost(parsedUrl.hostname)) {
+            return { isValid: false, error: 'Localhost URLs are not allowed' };
+        }
+        // Check for private IP addresses
+        if (!allowPrivateIPs) {
+            // Check if hostname is an IP address
+            const ipRegex = /^(\d{1,3}\.){3}\d{1,3}$/;
+            if (ipRegex.test(parsedUrl.hostname)) {
+                if (isPrivateIP(parsedUrl.hostname)) {
+                    return { isValid: false, error: 'Private IP addresses are not allowed' };
+                }
+            }
+            // Also check hostname string directly (in case it's not a valid IP format but still private)
+            if (isPrivateIP(parsedUrl.hostname)) {
+                return { isValid: false, error: 'Private IP addresses are not allowed' };
+            }
+            // Check for IPv6 localhost addresses
+            if (parsedUrl.hostname.includes(':')) {
+                if (parsedUrl.hostname.startsWith('::1') ||
+                    parsedUrl.hostname.startsWith('[::1]') ||
+                    parsedUrl.hostname.startsWith('fe80:') ||
+                    parsedUrl.hostname.startsWith('[fe80:')) {
+                    return { isValid: false, error: 'Localhost IPv6 addresses are not allowed' };
+                }
+            }
+        }
+        return { isValid: true };
+    }
+    catch (_a) {
+        return { isValid: false, error: 'Invalid URL format' };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "podverse-helpers",
-  "version": "5.1.26-alpha.0",
+  "version": "5.1.28-alpha.0",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -37,8 +37,5 @@
     "ts-node": "^10.9.2",
     "typescript": "^5.9.2",
     "typescript-eslint": "^8.44.0"
-  },
-  "overrides": {
-    "diff": "^8.0.3"
   }
 }