@stryke/url 0.3.39 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 # Changelog for Stryke - URL
 
+## [0.3.39](https://github.com/storm-software/stryke/releases/tag/url%400.3.39) (03/02/2026)
+
+### Updated Dependencies
+
+- Updated **type-checks** to **v0.5.28**
+- Updated **json** to **v0.11.0**
+- Updated **path** to **v0.26.9**
+
 ## [0.3.38](https://github.com/storm-software/stryke/releases/tag/url%400.3.38) (03/02/2026)
 
 ### Updated Dependencies

package/dist/index.cjs

@@ -1,5 +1,16 @@
+const require_helpers = require('./helpers.cjs');
 const require_storm_url = require('./storm-url.cjs');
 const require_types = require('./types.cjs');
+const require_validate = require('./validate.cjs');
 
+exports.BLOCKED_IPV4_RANGES = require_validate.BLOCKED_IPV4_RANGES;
 exports.PROTOCOL_RELATIVE_SYMBOL = require_types.PROTOCOL_RELATIVE_SYMBOL;
-exports.StormURL = require_storm_url.StormURL;
+exports.StormURL = require_storm_url.StormURL;
+exports.formatLocalePath = require_helpers.formatLocalePath;
+exports.ipv4ToInt = require_validate.ipv4ToInt;
+exports.isBlockedHostname = require_validate.isBlockedHostname;
+exports.isBlockedIPAddress = require_validate.isBlockedIPAddress;
+exports.isBlockedIPv4 = require_validate.isBlockedIPv4;
+exports.isValidURL = require_helpers.isValidURL;
+exports.validateUrl = require_validate.validateUrl;
+exports.validateUrlForPreview = require_validate.validateUrlForPreview;

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import { formatLocalePath, isValidURL } from "./helpers.cjs";
 import { PROTOCOL_RELATIVE_SYMBOL, StormURLInterface, StormURLOptions } from "./types.cjs";
 import { StormURL } from "./storm-url.cjs";
-export { PROTOCOL_RELATIVE_SYMBOL, StormURL, StormURLInterface, StormURLOptions };
+import { BLOCKED_IPV4_RANGES, URLValidationResult, ipv4ToInt, isBlockedHostname, isBlockedIPAddress, isBlockedIPv4, validateUrl, validateUrlForPreview } from "./validate.cjs";
+export { BLOCKED_IPV4_RANGES, PROTOCOL_RELATIVE_SYMBOL, StormURL, StormURLInterface, StormURLOptions, URLValidationResult, formatLocalePath, ipv4ToInt, isBlockedHostname, isBlockedIPAddress, isBlockedIPv4, isValidURL, validateUrl, validateUrlForPreview };

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+import { formatLocalePath, isValidURL } from "./helpers.mjs";
 import { PROTOCOL_RELATIVE_SYMBOL, StormURLInterface, StormURLOptions } from "./types.mjs";
 import { StormURL } from "./storm-url.mjs";
-export { PROTOCOL_RELATIVE_SYMBOL, StormURL, StormURLInterface, StormURLOptions };
+import { BLOCKED_IPV4_RANGES, URLValidationResult, ipv4ToInt, isBlockedHostname, isBlockedIPAddress, isBlockedIPv4, validateUrl, validateUrlForPreview } from "./validate.mjs";
+export { BLOCKED_IPV4_RANGES, PROTOCOL_RELATIVE_SYMBOL, StormURL, StormURLInterface, StormURLOptions, URLValidationResult, formatLocalePath, ipv4ToInt, isBlockedHostname, isBlockedIPAddress, isBlockedIPv4, isValidURL, validateUrl, validateUrlForPreview };

package/dist/index.mjs

@@ -1,4 +1,6 @@
+import { formatLocalePath, isValidURL } from "./helpers.mjs";
 import { StormURL } from "./storm-url.mjs";
 import { PROTOCOL_RELATIVE_SYMBOL } from "./types.mjs";
+import { BLOCKED_IPV4_RANGES, ipv4ToInt, isBlockedHostname, isBlockedIPAddress, isBlockedIPv4, validateUrl, validateUrlForPreview } from "./validate.mjs";
 
-export { PROTOCOL_RELATIVE_SYMBOL, StormURL };
+export { BLOCKED_IPV4_RANGES, PROTOCOL_RELATIVE_SYMBOL, StormURL, formatLocalePath, ipv4ToInt, isBlockedHostname, isBlockedIPAddress, isBlockedIPv4, isValidURL, validateUrl, validateUrlForPreview };

package/dist/validate.cjs

@@ -0,0 +1,210 @@
+
+//#region src/validate.ts
+/**
+* List of blocked IPv4 ranges for Server-Side Request Forgery (SSRF) protection
+*/
+const BLOCKED_IPV4_RANGES = [
+	{
+		start: "127.0.0.0",
+		end: "127.255.255.255"
+	},
+	{
+		start: "10.0.0.0",
+		end: "10.255.255.255"
+	},
+	{
+		start: "172.16.0.0",
+		end: "172.31.255.255"
+	},
+	{
+		start: "192.168.0.0",
+		end: "192.168.255.255"
+	},
+	{
+		start: "169.254.0.0",
+		end: "169.254.255.255"
+	},
+	{
+		start: "169.254.169.254",
+		end: "169.254.169.254"
+	},
+	{
+		start: "255.255.255.255",
+		end: "255.255.255.255"
+	},
+	{
+		start: "0.0.0.0",
+		end: "0.255.255.255"
+	}
+];
+/**
+* List of blocked hostnames for Server-Side Request Forgery (SSRF) protection
+*
+* @remarks
+* This includes common internal hostnames and patterns that should not be accessed
+*/
+const BLOCKED_HOSTNAMES = [
+	"localhost",
+	"localhost.localdomain",
+	"ip6-localhost",
+	"ip6-loopback",
+	"kubernetes.default",
+	"kubernetes.default.svc",
+	"kubernetes.default.svc.cluster.local",
+	"internal",
+	"metadata",
+	"metadata.google.internal"
+];
+/**
+* Convert an IPv4 address to a 32-bit integer for range comparison
+*
+* @param ip - The IPv4 address as a string
+* @returns The 32-bit integer representation of the IPv4 address, or -1 if invalid
+*/
+function ipv4ToInt(ip) {
+	const parts = ip.split(".").map(Number);
+	if (parts.length !== 4 || parts.some((p) => Number.isNaN(p) || p < 0 || p > 255) || !parts[0] || !parts[1] || !parts[2] || !parts[3]) return -1;
+	return (parts[0] << 24 | parts[1] << 16 | parts[2] << 8 | parts[3]) >>> 0;
+}
+/**
+* Check if an IPv4 address is in a blocked range for Server-Side Request Forgery (SSRF) protection
+*
+* @param ip - The IPv4 address as a string
+* @returns True if the IP is in a blocked range, false otherwise
+*/
+function isBlockedIPv4(ip) {
+	const ipInt = ipv4ToInt(ip);
+	if (ipInt === -1) return false;
+	for (const range of BLOCKED_IPV4_RANGES) {
+		const startInt = ipv4ToInt(range.start);
+		const endInt = ipv4ToInt(range.end);
+		if (ipInt >= startInt && ipInt <= endInt) return true;
+	}
+	return false;
+}
+/**
+* Check if an IPv6 address is a blocked address for Server-Side Request Forgery (SSRF) protection
+*
+* @param ip - The IPv6 address as a string
+* @returns True if the IP is blocked, false otherwise
+*/
+function isBlockedIPv6(ip) {
+	const normalized = ip.toLowerCase();
+	if (normalized === "::1" || normalized === "0:0:0:0:0:0:0:1") return true;
+	if (normalized === "::" || normalized === "0:0:0:0:0:0:0:0") return true;
+	const ipv4Mapped = normalized.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+	if (ipv4Mapped && ipv4Mapped[1]) return isBlockedIPv4(ipv4Mapped[1]);
+	if (normalized.startsWith("fe8") || normalized.startsWith("fe9") || normalized.startsWith("fea") || normalized.startsWith("feb")) return true;
+	if (normalized.startsWith("fc") || normalized.startsWith("fd")) return true;
+	return false;
+}
+/**
+* Check if a hostname is blocked for Server-Side Request Forgery (SSRF) protection by comparing against a list of blocked hostnames and patterns. This includes exact matches, subdomain checks, and common internal domain patterns.
+*
+* @param hostname - The hostname to check
+* @returns True if the hostname is blocked, false otherwise
+*/
+function isBlockedHostname(hostname) {
+	const lower = hostname.toLowerCase();
+	if (BLOCKED_HOSTNAMES.includes(lower)) return true;
+	for (const blocked of BLOCKED_HOSTNAMES) if (lower.endsWith(`.${blocked}`)) return true;
+	if (lower.endsWith(".local")) return true;
+	if (lower.endsWith(".internal")) return true;
+	return false;
+}
+/**
+* Check if a hostname appears to be an IP address and if so, whether it's blocked for Server-Side Request Forgery (SSRF) protection
+*
+* @param hostname - The hostname to check
+* @returns True if the hostname is a blocked IP address, false otherwise
+*/
+function isBlockedIPAddress(hostname) {
+	if (/^\d+\.\d+\.\d+\.\d+$/.test(hostname)) return isBlockedIPv4(hostname);
+	const ipv6 = hostname.replace(/^\[|\]$/g, "");
+	if (ipv6.includes(":")) return isBlockedIPv6(ipv6);
+	return false;
+}
+/**
+* Validate a URL for use in general contexts (e.g. fetching data, making API calls) with Server-Side Request Forgery (SSRF) protection. This function checks if the URL is well-formed, uses allowed protocols (http/https), and ensures that the hostname does not resolve to internal IP addresses or hostnames. It also checks for non-standard ports that might indicate internal services.
+*
+* @param url - The URL to validate
+* @returns A URLValidationResult object indicating whether the URL is valid, any error message if invalid, and a sanitized version of the URL if valid
+*/
+function validateUrl(url) {
+	try {
+		const parsed = new URL(url);
+		if (!["http:", "https:"].includes(parsed.protocol)) return {
+			valid: false,
+			error: "Only HTTP and HTTPS protocols are allowed"
+		};
+		const hostname = parsed.hostname.toLowerCase();
+		if (isBlockedHostname(hostname)) return {
+			valid: false,
+			error: "Access to internal hostnames is not allowed"
+		};
+		if (isBlockedIPAddress(hostname)) return {
+			valid: false,
+			error: "Access to internal IP addresses is not allowed"
+		};
+		const port = parsed.port ? Number.parseInt(parsed.port, 10) : parsed.protocol === "https:" ? 443 : 80;
+		if ([
+			22,
+			23,
+			25,
+			53,
+			135,
+			139,
+			445,
+			1433,
+			1521,
+			3306,
+			3389,
+			5432,
+			5900,
+			6379,
+			9200,
+			27017
+		].includes(port)) return {
+			valid: false,
+			error: `Access to port ${port} is not allowed`
+		};
+		return {
+			valid: true,
+			sanitizedUrl: parsed.toString()
+		};
+	} catch {
+		return {
+			valid: false,
+			error: "Invalid URL format"
+		};
+	}
+}
+/**
+* Validate a URL for use in URL preview.
+*
+* @remarks
+* These validations are more restrictive than general URL validations. For URL previews, we want to be extra cautious to prevent any potential SSRF vulnerabilities, so we enforce stricter rules on allowed ports and ensure that the URL is well-formed and does not point to internal resources. This function builds upon the general `validateUrl` function and adds additional checks specific to URL previews, such as blocking non-standard HTTP ports that are commonly used for internal services. By using this function for URL previews, we can help ensure that the URLs being previewed are safe and do not pose a security risk to the application or its users.
+*
+* @param url - The URL to validate for preview
+* @returns A URLValidationResult object indicating whether the URL is valid for preview, any error message if invalid, and a sanitized version of the URL if valid
+*/
+function validateUrlForPreview(url) {
+	const result = validateUrl(url);
+	if (!result.valid) return result;
+	const parsed = new URL(url);
+	const port = parsed.port ? Number.parseInt(parsed.port, 10) : parsed.protocol === "https:" ? 443 : 80;
+	if (port !== 80 && port !== 443 && port !== 8080 && port !== 8443) return {
+		valid: false,
+		error: "Only standard HTTP ports (80, 443, 8080, 8443) are allowed for URL preview"
+	};
+	return result;
+}
+
+//#endregion
+exports.BLOCKED_IPV4_RANGES = BLOCKED_IPV4_RANGES;
+exports.ipv4ToInt = ipv4ToInt;
+exports.isBlockedHostname = isBlockedHostname;
+exports.isBlockedIPAddress = isBlockedIPAddress;
+exports.isBlockedIPv4 = isBlockedIPv4;
+exports.validateUrl = validateUrl;
+exports.validateUrlForPreview = validateUrlForPreview;

package/dist/validate.d.cts

@@ -0,0 +1,67 @@
+//#region src/validate.d.ts
+/**
+ * List of blocked IPv4 ranges for Server-Side Request Forgery (SSRF) protection
+ */
+declare const BLOCKED_IPV4_RANGES: {
+  start: string;
+  end: string;
+}[];
+/**
+ * Convert an IPv4 address to a 32-bit integer for range comparison
+ *
+ * @param ip - The IPv4 address as a string
+ * @returns The 32-bit integer representation of the IPv4 address, or -1 if invalid
+ */
+declare function ipv4ToInt(ip: string): number;
+/**
+ * Check if an IPv4 address is in a blocked range for Server-Side Request Forgery (SSRF) protection
+ *
+ * @param ip - The IPv4 address as a string
+ * @returns True if the IP is in a blocked range, false otherwise
+ */
+declare function isBlockedIPv4(ip: string): boolean;
+/**
+ * Check if a hostname is blocked for Server-Side Request Forgery (SSRF) protection by comparing against a list of blocked hostnames and patterns. This includes exact matches, subdomain checks, and common internal domain patterns.
+ *
+ * @param hostname - The hostname to check
+ * @returns True if the hostname is blocked, false otherwise
+ */
+declare function isBlockedHostname(hostname: string): boolean;
+/**
+ * Check if a hostname appears to be an IP address and if so, whether it's blocked for Server-Side Request Forgery (SSRF) protection
+ *
+ * @param hostname - The hostname to check
+ * @returns True if the hostname is a blocked IP address, false otherwise
+ */
+declare function isBlockedIPAddress(hostname: string): boolean;
+/**
+ * A result object for URL validation, indicating whether the URL is valid, any error message if invalid, and a sanitized version of the URL if valid. This structure allows for clear communication of validation results and can be easily extended in the future if needed.
+ *
+ * @remarks
+ * The `valid` property indicates if the URL passed validation. The `error` property provides a message explaining why the URL is invalid, if applicable. The `sanitizedUrl` property contains a cleaned-up version of the URL that can be safely used if the original URL is valid.
+ */
+interface URLValidationResult {
+  valid: boolean;
+  error?: string;
+  sanitizedUrl?: string;
+}
+/**
+ * Validate a URL for use in general contexts (e.g. fetching data, making API calls) with Server-Side Request Forgery (SSRF) protection. This function checks if the URL is well-formed, uses allowed protocols (http/https), and ensures that the hostname does not resolve to internal IP addresses or hostnames. It also checks for non-standard ports that might indicate internal services.
+ *
+ * @param url - The URL to validate
+ * @returns A URLValidationResult object indicating whether the URL is valid, any error message if invalid, and a sanitized version of the URL if valid
+ */
+declare function validateUrl(url: string): URLValidationResult;
+/**
+ * Validate a URL for use in URL preview.
+ *
+ * @remarks
+ * These validations are more restrictive than general URL validations. For URL previews, we want to be extra cautious to prevent any potential SSRF vulnerabilities, so we enforce stricter rules on allowed ports and ensure that the URL is well-formed and does not point to internal resources. This function builds upon the general `validateUrl` function and adds additional checks specific to URL previews, such as blocking non-standard HTTP ports that are commonly used for internal services. By using this function for URL previews, we can help ensure that the URLs being previewed are safe and do not pose a security risk to the application or its users.
+ *
+ * @param url - The URL to validate for preview
+ * @returns A URLValidationResult object indicating whether the URL is valid for preview, any error message if invalid, and a sanitized version of the URL if valid
+ */
+declare function validateUrlForPreview(url: string): URLValidationResult;
+//#endregion
+export { BLOCKED_IPV4_RANGES, URLValidationResult, ipv4ToInt, isBlockedHostname, isBlockedIPAddress, isBlockedIPv4, validateUrl, validateUrlForPreview };
+//# sourceMappingURL=validate.d.cts.map

package/dist/validate.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.cts","names":[],"sources":["../src/validate.ts"],"sourcesContent":[],"mappings":";;AAqBA;AA4CA;AAuBgB,cAnEH,mBAmEgB,EAAA;EAiEb,KAAA,EAAA,MAAA;EAkCA,GAAA,EAAA,MAAA;AAqBhB,CAAA,EAAA;AAYA;AA4EA;;;;;iBAvOgB,SAAA;;;;;;;iBAuBA,aAAA;;;;;;;iBAiEA,iBAAA;;;;;;;iBAkCA,kBAAA;;;;;;;UAqBC,mBAAA;;;;;;;;;;;iBAYD,WAAA,eAA0B;;;;;;;;;;iBA4E1B,qBAAA,eAAoC"}

package/dist/validate.d.mts

@@ -0,0 +1,67 @@
+//#region src/validate.d.ts
+/**
+ * List of blocked IPv4 ranges for Server-Side Request Forgery (SSRF) protection
+ */
+declare const BLOCKED_IPV4_RANGES: {
+  start: string;
+  end: string;
+}[];
+/**
+ * Convert an IPv4 address to a 32-bit integer for range comparison
+ *
+ * @param ip - The IPv4 address as a string
+ * @returns The 32-bit integer representation of the IPv4 address, or -1 if invalid
+ */
+declare function ipv4ToInt(ip: string): number;
+/**
+ * Check if an IPv4 address is in a blocked range for Server-Side Request Forgery (SSRF) protection
+ *
+ * @param ip - The IPv4 address as a string
+ * @returns True if the IP is in a blocked range, false otherwise
+ */
+declare function isBlockedIPv4(ip: string): boolean;
+/**
+ * Check if a hostname is blocked for Server-Side Request Forgery (SSRF) protection by comparing against a list of blocked hostnames and patterns. This includes exact matches, subdomain checks, and common internal domain patterns.
+ *
+ * @param hostname - The hostname to check
+ * @returns True if the hostname is blocked, false otherwise
+ */
+declare function isBlockedHostname(hostname: string): boolean;
+/**
+ * Check if a hostname appears to be an IP address and if so, whether it's blocked for Server-Side Request Forgery (SSRF) protection
+ *
+ * @param hostname - The hostname to check
+ * @returns True if the hostname is a blocked IP address, false otherwise
+ */
+declare function isBlockedIPAddress(hostname: string): boolean;
+/**
+ * A result object for URL validation, indicating whether the URL is valid, any error message if invalid, and a sanitized version of the URL if valid. This structure allows for clear communication of validation results and can be easily extended in the future if needed.
+ *
+ * @remarks
+ * The `valid` property indicates if the URL passed validation. The `error` property provides a message explaining why the URL is invalid, if applicable. The `sanitizedUrl` property contains a cleaned-up version of the URL that can be safely used if the original URL is valid.
+ */
+interface URLValidationResult {
+  valid: boolean;
+  error?: string;
+  sanitizedUrl?: string;
+}
+/**
+ * Validate a URL for use in general contexts (e.g. fetching data, making API calls) with Server-Side Request Forgery (SSRF) protection. This function checks if the URL is well-formed, uses allowed protocols (http/https), and ensures that the hostname does not resolve to internal IP addresses or hostnames. It also checks for non-standard ports that might indicate internal services.
+ *
+ * @param url - The URL to validate
+ * @returns A URLValidationResult object indicating whether the URL is valid, any error message if invalid, and a sanitized version of the URL if valid
+ */
+declare function validateUrl(url: string): URLValidationResult;
+/**
+ * Validate a URL for use in URL preview.
+ *
+ * @remarks
+ * These validations are more restrictive than general URL validations. For URL previews, we want to be extra cautious to prevent any potential SSRF vulnerabilities, so we enforce stricter rules on allowed ports and ensure that the URL is well-formed and does not point to internal resources. This function builds upon the general `validateUrl` function and adds additional checks specific to URL previews, such as blocking non-standard HTTP ports that are commonly used for internal services. By using this function for URL previews, we can help ensure that the URLs being previewed are safe and do not pose a security risk to the application or its users.
+ *
+ * @param url - The URL to validate for preview
+ * @returns A URLValidationResult object indicating whether the URL is valid for preview, any error message if invalid, and a sanitized version of the URL if valid
+ */
+declare function validateUrlForPreview(url: string): URLValidationResult;
+//#endregion
+export { BLOCKED_IPV4_RANGES, URLValidationResult, ipv4ToInt, isBlockedHostname, isBlockedIPAddress, isBlockedIPv4, validateUrl, validateUrlForPreview };
+//# sourceMappingURL=validate.d.mts.map

package/dist/validate.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.mts","names":[],"sources":["../src/validate.ts"],"sourcesContent":[],"mappings":";;AAqBA;AA4CA;AAuBgB,cAnEH,mBAmEgB,EAAA;EAiEb,KAAA,EAAA,MAAA;EAkCA,GAAA,EAAA,MAAA;AAqBhB,CAAA,EAAA;AAYA;AA4EA;;;;;iBAvOgB,SAAA;;;;;;;iBAuBA,aAAA;;;;;;;iBAiEA,iBAAA;;;;;;;iBAkCA,kBAAA;;;;;;;UAqBC,mBAAA;;;;;;;;;;;iBAYD,WAAA,eAA0B;;;;;;;;;;iBA4E1B,qBAAA,eAAoC"}

package/dist/validate.mjs

@@ -0,0 +1,204 @@
+//#region src/validate.ts
+/**
+* List of blocked IPv4 ranges for Server-Side Request Forgery (SSRF) protection
+*/
+const BLOCKED_IPV4_RANGES = [
+	{
+		start: "127.0.0.0",
+		end: "127.255.255.255"
+	},
+	{
+		start: "10.0.0.0",
+		end: "10.255.255.255"
+	},
+	{
+		start: "172.16.0.0",
+		end: "172.31.255.255"
+	},
+	{
+		start: "192.168.0.0",
+		end: "192.168.255.255"
+	},
+	{
+		start: "169.254.0.0",
+		end: "169.254.255.255"
+	},
+	{
+		start: "169.254.169.254",
+		end: "169.254.169.254"
+	},
+	{
+		start: "255.255.255.255",
+		end: "255.255.255.255"
+	},
+	{
+		start: "0.0.0.0",
+		end: "0.255.255.255"
+	}
+];
+/**
+* List of blocked hostnames for Server-Side Request Forgery (SSRF) protection
+*
+* @remarks
+* This includes common internal hostnames and patterns that should not be accessed
+*/
+const BLOCKED_HOSTNAMES = [
+	"localhost",
+	"localhost.localdomain",
+	"ip6-localhost",
+	"ip6-loopback",
+	"kubernetes.default",
+	"kubernetes.default.svc",
+	"kubernetes.default.svc.cluster.local",
+	"internal",
+	"metadata",
+	"metadata.google.internal"
+];
+/**
+* Convert an IPv4 address to a 32-bit integer for range comparison
+*
+* @param ip - The IPv4 address as a string
+* @returns The 32-bit integer representation of the IPv4 address, or -1 if invalid
+*/
+function ipv4ToInt(ip) {
+	const parts = ip.split(".").map(Number);
+	if (parts.length !== 4 || parts.some((p) => Number.isNaN(p) || p < 0 || p > 255) || !parts[0] || !parts[1] || !parts[2] || !parts[3]) return -1;
+	return (parts[0] << 24 | parts[1] << 16 | parts[2] << 8 | parts[3]) >>> 0;
+}
+/**
+* Check if an IPv4 address is in a blocked range for Server-Side Request Forgery (SSRF) protection
+*
+* @param ip - The IPv4 address as a string
+* @returns True if the IP is in a blocked range, false otherwise
+*/
+function isBlockedIPv4(ip) {
+	const ipInt = ipv4ToInt(ip);
+	if (ipInt === -1) return false;
+	for (const range of BLOCKED_IPV4_RANGES) {
+		const startInt = ipv4ToInt(range.start);
+		const endInt = ipv4ToInt(range.end);
+		if (ipInt >= startInt && ipInt <= endInt) return true;
+	}
+	return false;
+}
+/**
+* Check if an IPv6 address is a blocked address for Server-Side Request Forgery (SSRF) protection
+*
+* @param ip - The IPv6 address as a string
+* @returns True if the IP is blocked, false otherwise
+*/
+function isBlockedIPv6(ip) {
+	const normalized = ip.toLowerCase();
+	if (normalized === "::1" || normalized === "0:0:0:0:0:0:0:1") return true;
+	if (normalized === "::" || normalized === "0:0:0:0:0:0:0:0") return true;
+	const ipv4Mapped = normalized.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+	if (ipv4Mapped && ipv4Mapped[1]) return isBlockedIPv4(ipv4Mapped[1]);
+	if (normalized.startsWith("fe8") || normalized.startsWith("fe9") || normalized.startsWith("fea") || normalized.startsWith("feb")) return true;
+	if (normalized.startsWith("fc") || normalized.startsWith("fd")) return true;
+	return false;
+}
+/**
+* Check if a hostname is blocked for Server-Side Request Forgery (SSRF) protection by comparing against a list of blocked hostnames and patterns. This includes exact matches, subdomain checks, and common internal domain patterns.
+*
+* @param hostname - The hostname to check
+* @returns True if the hostname is blocked, false otherwise
+*/
+function isBlockedHostname(hostname) {
+	const lower = hostname.toLowerCase();
+	if (BLOCKED_HOSTNAMES.includes(lower)) return true;
+	for (const blocked of BLOCKED_HOSTNAMES) if (lower.endsWith(`.${blocked}`)) return true;
+	if (lower.endsWith(".local")) return true;
+	if (lower.endsWith(".internal")) return true;
+	return false;
+}
+/**
+* Check if a hostname appears to be an IP address and if so, whether it's blocked for Server-Side Request Forgery (SSRF) protection
+*
+* @param hostname - The hostname to check
+* @returns True if the hostname is a blocked IP address, false otherwise
+*/
+function isBlockedIPAddress(hostname) {
+	if (/^\d+\.\d+\.\d+\.\d+$/.test(hostname)) return isBlockedIPv4(hostname);
+	const ipv6 = hostname.replace(/^\[|\]$/g, "");
+	if (ipv6.includes(":")) return isBlockedIPv6(ipv6);
+	return false;
+}
+/**
+* Validate a URL for use in general contexts (e.g. fetching data, making API calls) with Server-Side Request Forgery (SSRF) protection. This function checks if the URL is well-formed, uses allowed protocols (http/https), and ensures that the hostname does not resolve to internal IP addresses or hostnames. It also checks for non-standard ports that might indicate internal services.
+*
+* @param url - The URL to validate
+* @returns A URLValidationResult object indicating whether the URL is valid, any error message if invalid, and a sanitized version of the URL if valid
+*/
+function validateUrl(url) {
+	try {
+		const parsed = new URL(url);
+		if (!["http:", "https:"].includes(parsed.protocol)) return {
+			valid: false,
+			error: "Only HTTP and HTTPS protocols are allowed"
+		};
+		const hostname = parsed.hostname.toLowerCase();
+		if (isBlockedHostname(hostname)) return {
+			valid: false,
+			error: "Access to internal hostnames is not allowed"
+		};
+		if (isBlockedIPAddress(hostname)) return {
+			valid: false,
+			error: "Access to internal IP addresses is not allowed"
+		};
+		const port = parsed.port ? Number.parseInt(parsed.port, 10) : parsed.protocol === "https:" ? 443 : 80;
+		if ([
+			22,
+			23,
+			25,
+			53,
+			135,
+			139,
+			445,
+			1433,
+			1521,
+			3306,
+			3389,
+			5432,
+			5900,
+			6379,
+			9200,
+			27017
+		].includes(port)) return {
+			valid: false,
+			error: `Access to port ${port} is not allowed`
+		};
+		return {
+			valid: true,
+			sanitizedUrl: parsed.toString()
+		};
+	} catch {
+		return {
+			valid: false,
+			error: "Invalid URL format"
+		};
+	}
+}
+/**
+* Validate a URL for use in URL preview.
+*
+* @remarks
+* These validations are more restrictive than general URL validations. For URL previews, we want to be extra cautious to prevent any potential SSRF vulnerabilities, so we enforce stricter rules on allowed ports and ensure that the URL is well-formed and does not point to internal resources. This function builds upon the general `validateUrl` function and adds additional checks specific to URL previews, such as blocking non-standard HTTP ports that are commonly used for internal services. By using this function for URL previews, we can help ensure that the URLs being previewed are safe and do not pose a security risk to the application or its users.
+*
+* @param url - The URL to validate for preview
+* @returns A URLValidationResult object indicating whether the URL is valid for preview, any error message if invalid, and a sanitized version of the URL if valid
+*/
+function validateUrlForPreview(url) {
+	const result = validateUrl(url);
+	if (!result.valid) return result;
+	const parsed = new URL(url);
+	const port = parsed.port ? Number.parseInt(parsed.port, 10) : parsed.protocol === "https:" ? 443 : 80;
+	if (port !== 80 && port !== 443 && port !== 8080 && port !== 8443) return {
+		valid: false,
+		error: "Only standard HTTP ports (80, 443, 8080, 8443) are allowed for URL preview"
+	};
+	return result;
+}
+
+//#endregion
+export { BLOCKED_IPV4_RANGES, ipv4ToInt, isBlockedHostname, isBlockedIPAddress, isBlockedIPv4, validateUrl, validateUrlForPreview };
+//# sourceMappingURL=validate.mjs.map

package/dist/validate.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.mjs","names":[],"sources":["../src/validate.ts"],"sourcesContent":["/* -------------------------------------------------------------------\n\n                       ⚡ Storm Software - Stryke\n\n This code was released as part of the Stryke project. Stryke\n is maintained by Storm Software under the Apache-2.0 license, and is\n free for commercial and private use. For more information, please visit\n our licensing page at https://stormsoftware.com/licenses/projects/stryke.\n\n Website:                  https://stormsoftware.com\n Repository:               https://github.com/storm-software/stryke\n Documentation:            https://docs.stormsoftware.com/projects/stryke\n Contact:                  https://stormsoftware.com/contact\n\n SPDX-License-Identifier:  Apache-2.0\n\n ------------------------------------------------------------------- */\n\n/**\n * List of blocked IPv4 ranges for Server-Side Request Forgery (SSRF) protection\n */\nexport const BLOCKED_IPV4_RANGES = [\n  // Loopback\n  { start: \"127.0.0.0\", end: \"127.255.255.255\" },\n  // Private networks (RFC 1918)\n  { start: \"10.0.0.0\", end: \"10.255.255.255\" },\n  { start: \"172.16.0.0\", end: \"172.31.255.255\" },\n  { start: \"192.168.0.0\", end: \"192.168.255.255\" },\n  // Link-local\n  { start: \"169.254.0.0\", end: \"169.254.255.255\" },\n  // AWS metadata service\n  { start: \"169.254.169.254\", end: \"169.254.169.254\" },\n  // Broadcast\n  { start: \"255.255.255.255\", end: \"255.255.255.255\" },\n  // Current network\n  { start: \"0.0.0.0\", end: \"0.255.255.255\" }\n];\n\n/**\n * List of blocked hostnames for Server-Side Request Forgery (SSRF) protection\n *\n * @remarks\n * This includes common internal hostnames and patterns that should not be accessed\n */\nconst BLOCKED_HOSTNAMES = [\n  \"localhost\",\n  \"localhost.localdomain\",\n  \"ip6-localhost\",\n  \"ip6-loopback\",\n  // Kubernetes internal\n  \"kubernetes.default\",\n  \"kubernetes.default.svc\",\n  \"kubernetes.default.svc.cluster.local\",\n  // Common internal service names\n  \"internal\",\n  \"metadata\",\n  \"metadata.google.internal\"\n];\n\n/**\n * Convert an IPv4 address to a 32-bit integer for range comparison\n *\n * @param ip - The IPv4 address as a string\n * @returns The 32-bit integer representation of the IPv4 address, or -1 if invalid\n */\nexport function ipv4ToInt(ip: string): number {\n  const parts = ip.split(\".\").map(Number);\n  if (\n    parts.length !== 4 ||\n    parts.some(p => Number.isNaN(p) || p < 0 || p > 255) ||\n    !parts[0] ||\n    !parts[1] ||\n    !parts[2] ||\n    !parts[3]\n  ) {\n    return -1;\n  }\n  return (\n    ((parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]) >>> 0\n  );\n}\n\n/**\n * Check if an IPv4 address is in a blocked range for Server-Side Request Forgery (SSRF) protection\n *\n * @param ip - The IPv4 address as a string\n * @returns True if the IP is in a blocked range, false otherwise\n */\nexport function isBlockedIPv4(ip: string): boolean {\n  const ipInt = ipv4ToInt(ip);\n  if (ipInt === -1) return false;\n\n  for (const range of BLOCKED_IPV4_RANGES) {\n    const startInt = ipv4ToInt(range.start);\n    const endInt = ipv4ToInt(range.end);\n    if (ipInt >= startInt && ipInt <= endInt) {\n      return true;\n    }\n  }\n\n  return false;\n}\n\n/**\n * Check if an IPv6 address is a blocked address for Server-Side Request Forgery (SSRF) protection\n *\n * @param ip - The IPv6 address as a string\n * @returns True if the IP is blocked, false otherwise\n */\nfunction isBlockedIPv6(ip: string): boolean {\n  // Normalize the address\n  const normalized = ip.toLowerCase();\n\n  // Loopback\n  if (normalized === \"::1\" || normalized === \"0:0:0:0:0:0:0:1\") {\n    return true;\n  }\n\n  // Unspecified\n  if (normalized === \"::\" || normalized === \"0:0:0:0:0:0:0:0\") {\n    return true;\n  }\n\n  // IPv4-mapped IPv6 addresses (::ffff:x.x.x.x)\n  const ipv4Mapped = normalized.match(/^::ffff:(\\d+\\.\\d+\\.\\d+\\.\\d+)$/);\n  if (ipv4Mapped && ipv4Mapped[1]) {\n    return isBlockedIPv4(ipv4Mapped[1]);\n  }\n\n  // Link-local (fe80::/10)\n  if (\n    normalized.startsWith(\"fe8\") ||\n    normalized.startsWith(\"fe9\") ||\n    normalized.startsWith(\"fea\") ||\n    normalized.startsWith(\"feb\")\n  ) {\n    return true;\n  }\n\n  // Unique local (fc00::/7)\n  if (normalized.startsWith(\"fc\") || normalized.startsWith(\"fd\")) {\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Check if a hostname is blocked for Server-Side Request Forgery (SSRF) protection by comparing against a list of blocked hostnames and patterns. This includes exact matches, subdomain checks, and common internal domain patterns.\n *\n * @param hostname - The hostname to check\n * @returns True if the hostname is blocked, false otherwise\n */\nexport function isBlockedHostname(hostname: string): boolean {\n  const lower = hostname.toLowerCase();\n\n  // Check exact matches\n  if (BLOCKED_HOSTNAMES.includes(lower)) {\n    return true;\n  }\n\n  // Check if it's a subdomain of a blocked hostname\n  for (const blocked of BLOCKED_HOSTNAMES) {\n    if (lower.endsWith(`.${blocked}`)) {\n      return true;\n    }\n  }\n\n  // Check for .local TLD (mDNS)\n  if (lower.endsWith(\".local\")) {\n    return true;\n  }\n\n  // Check for .internal domains\n  if (lower.endsWith(\".internal\")) {\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Check if a hostname appears to be an IP address and if so, whether it's blocked for Server-Side Request Forgery (SSRF) protection\n *\n * @param hostname - The hostname to check\n * @returns True if the hostname is a blocked IP address, false otherwise\n */\nexport function isBlockedIPAddress(hostname: string): boolean {\n  // IPv4 check\n  if (/^\\d+\\.\\d+\\.\\d+\\.\\d+$/.test(hostname)) {\n    return isBlockedIPv4(hostname);\n  }\n\n  // IPv6 check (with brackets removed if present)\n  const ipv6 = hostname.replace(/^\\[|\\]$/g, \"\");\n  if (ipv6.includes(\":\")) {\n    return isBlockedIPv6(ipv6);\n  }\n\n  return false;\n}\n\n/**\n * A result object for URL validation, indicating whether the URL is valid, any error message if invalid, and a sanitized version of the URL if valid. This structure allows for clear communication of validation results and can be easily extended in the future if needed.\n *\n * @remarks\n * The `valid` property indicates if the URL passed validation. The `error` property provides a message explaining why the URL is invalid, if applicable. The `sanitizedUrl` property contains a cleaned-up version of the URL that can be safely used if the original URL is valid.\n */\nexport interface URLValidationResult {\n  valid: boolean;\n  error?: string;\n  sanitizedUrl?: string;\n}\n\n/**\n * Validate a URL for use in general contexts (e.g. fetching data, making API calls) with Server-Side Request Forgery (SSRF) protection. This function checks if the URL is well-formed, uses allowed protocols (http/https), and ensures that the hostname does not resolve to internal IP addresses or hostnames. It also checks for non-standard ports that might indicate internal services.\n *\n * @param url - The URL to validate\n * @returns A URLValidationResult object indicating whether the URL is valid, any error message if invalid, and a sanitized version of the URL if valid\n */\nexport function validateUrl(url: string): URLValidationResult {\n  try {\n    const parsed = new URL(url);\n\n    // Only allow http and https\n    if (![\"http:\", \"https:\"].includes(parsed.protocol)) {\n      return {\n        valid: false,\n        error: \"Only HTTP and HTTPS protocols are allowed\"\n      };\n    }\n\n    const hostname = parsed.hostname.toLowerCase();\n\n    // Check for blocked hostnames\n    if (isBlockedHostname(hostname)) {\n      return {\n        valid: false,\n        error: \"Access to internal hostnames is not allowed\"\n      };\n    }\n\n    // Check for blocked IP addresses\n    if (isBlockedIPAddress(hostname)) {\n      return {\n        valid: false,\n        error: \"Access to internal IP addresses is not allowed\"\n      };\n    }\n\n    // Check for non-standard ports that might indicate internal services\n    const port = parsed.port\n      ? Number.parseInt(parsed.port, 10)\n      : parsed.protocol === \"https:\"\n        ? 443\n        : 80;\n\n    // Block common internal service ports\n    const blockedPorts = [\n      22, // SSH\n      23, // Telnet\n      25, // SMTP\n      53, // DNS\n      135, // RPC\n      139, // NetBIOS\n      445, // SMB\n      1433, // MSSQL\n      1521, // Oracle\n      3306, // MySQL\n      3389, // RDP\n      5432, // PostgreSQL\n      5900, // VNC\n      6379, // Redis\n      9200, // Elasticsearch\n      27017 // MongoDB\n    ];\n\n    if (blockedPorts.includes(port)) {\n      return { valid: false, error: `Access to port ${port} is not allowed` };\n    }\n\n    return { valid: true, sanitizedUrl: parsed.toString() };\n  } catch {\n    return { valid: false, error: \"Invalid URL format\" };\n  }\n}\n\n/**\n * Validate a URL for use in URL preview.\n *\n * @remarks\n * These validations are more restrictive than general URL validations. For URL previews, we want to be extra cautious to prevent any potential SSRF vulnerabilities, so we enforce stricter rules on allowed ports and ensure that the URL is well-formed and does not point to internal resources. This function builds upon the general `validateUrl` function and adds additional checks specific to URL previews, such as blocking non-standard HTTP ports that are commonly used for internal services. By using this function for URL previews, we can help ensure that the URLs being previewed are safe and do not pose a security risk to the application or its users.\n *\n * @param url - The URL to validate for preview\n * @returns A URLValidationResult object indicating whether the URL is valid for preview, any error message if invalid, and a sanitized version of the URL if valid\n */\nexport function validateUrlForPreview(url: string): URLValidationResult {\n  const result = validateUrl(url);\n  if (!result.valid) {\n    return result;\n  }\n\n  const parsed = new URL(url);\n\n  // For previews, only allow standard HTTP ports\n  const port = parsed.port\n    ? Number.parseInt(parsed.port, 10)\n    : parsed.protocol === \"https:\"\n      ? 443\n      : 80;\n  if (port !== 80 && port !== 443 && port !== 8080 && port !== 8443) {\n    return {\n      valid: false,\n      error:\n        \"Only standard HTTP ports (80, 443, 8080, 8443) are allowed for URL preview\"\n    };\n  }\n\n  return result;\n}\n"],"mappings":";;;;AAqBA,MAAa,sBAAsB;CAEjC;EAAE,OAAO;EAAa,KAAK;EAAmB;CAE9C;EAAE,OAAO;EAAY,KAAK;EAAkB;CAC5C;EAAE,OAAO;EAAc,KAAK;EAAkB;CAC9C;EAAE,OAAO;EAAe,KAAK;EAAmB;CAEhD;EAAE,OAAO;EAAe,KAAK;EAAmB;CAEhD;EAAE,OAAO;EAAmB,KAAK;EAAmB;CAEpD;EAAE,OAAO;EAAmB,KAAK;EAAmB;CAEpD;EAAE,OAAO;EAAW,KAAK;EAAiB;CAC3C;;;;;;;AAQD,MAAM,oBAAoB;CACxB;CACA;CACA;CACA;CAEA;CACA;CACA;CAEA;CACA;CACA;CACD;;;;;;;AAQD,SAAgB,UAAU,IAAoB;CAC5C,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,OAAO;AACvC,KACE,MAAM,WAAW,KACjB,MAAM,MAAK,MAAK,OAAO,MAAM,EAAE,IAAI,IAAI,KAAK,IAAI,IAAI,IACpD,CAAC,MAAM,MACP,CAAC,MAAM,MACP,CAAC,MAAM,MACP,CAAC,MAAM,GAEP,QAAO;AAET,SACI,MAAM,MAAM,KAAO,MAAM,MAAM,KAAO,MAAM,MAAM,IAAK,MAAM,QAAQ;;;;;;;;AAU3E,SAAgB,cAAc,IAAqB;CACjD,MAAM,QAAQ,UAAU,GAAG;AAC3B,KAAI,UAAU,GAAI,QAAO;AAEzB,MAAK,MAAM,SAAS,qBAAqB;EACvC,MAAM,WAAW,UAAU,MAAM,MAAM;EACvC,MAAM,SAAS,UAAU,MAAM,IAAI;AACnC,MAAI,SAAS,YAAY,SAAS,OAChC,QAAO;;AAIX,QAAO;;;;;;;;AAST,SAAS,cAAc,IAAqB;CAE1C,MAAM,aAAa,GAAG,aAAa;AAGnC,KAAI,eAAe,SAAS,eAAe,kBACzC,QAAO;AAIT,KAAI,eAAe,QAAQ,eAAe,kBACxC,QAAO;CAIT,MAAM,aAAa,WAAW,MAAM,gCAAgC;AACpE,KAAI,cAAc,WAAW,GAC3B,QAAO,cAAc,WAAW,GAAG;AAIrC,KACE,WAAW,WAAW,MAAM,IAC5B,WAAW,WAAW,MAAM,IAC5B,WAAW,WAAW,MAAM,IAC5B,WAAW,WAAW,MAAM,CAE5B,QAAO;AAIT,KAAI,WAAW,WAAW,KAAK,IAAI,WAAW,WAAW,KAAK,CAC5D,QAAO;AAGT,QAAO;;;;;;;;AAST,SAAgB,kBAAkB,UAA2B;CAC3D,MAAM,QAAQ,SAAS,aAAa;AAGpC,KAAI,kBAAkB,SAAS,MAAM,CACnC,QAAO;AAIT,MAAK,MAAM,WAAW,kBACpB,KAAI,MAAM,SAAS,IAAI,UAAU,CAC/B,QAAO;AAKX,KAAI,MAAM,SAAS,SAAS,CAC1B,QAAO;AAIT,KAAI,MAAM,SAAS,YAAY,CAC7B,QAAO;AAGT,QAAO;;;;;;;;AAST,SAAgB,mBAAmB,UAA2B;AAE5D,KAAI,uBAAuB,KAAK,SAAS,CACvC,QAAO,cAAc,SAAS;CAIhC,MAAM,OAAO,SAAS,QAAQ,YAAY,GAAG;AAC7C,KAAI,KAAK,SAAS,IAAI,CACpB,QAAO,cAAc,KAAK;AAG5B,QAAO;;;;;;;;AAqBT,SAAgB,YAAY,KAAkC;AAC5D,KAAI;EACF,MAAM,SAAS,IAAI,IAAI,IAAI;AAG3B,MAAI,CAAC,CAAC,SAAS,SAAS,CAAC,SAAS,OAAO,SAAS,CAChD,QAAO;GACL,OAAO;GACP,OAAO;GACR;EAGH,MAAM,WAAW,OAAO,SAAS,aAAa;AAG9C,MAAI,kBAAkB,SAAS,CAC7B,QAAO;GACL,OAAO;GACP,OAAO;GACR;AAIH,MAAI,mBAAmB,SAAS,CAC9B,QAAO;GACL,OAAO;GACP,OAAO;GACR;EAIH,MAAM,OAAO,OAAO,OAChB,OAAO,SAAS,OAAO,MAAM,GAAG,GAChC,OAAO,aAAa,WAClB,MACA;AAsBN,MAnBqB;GACnB;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACD,CAEgB,SAAS,KAAK,CAC7B,QAAO;GAAE,OAAO;GAAO,OAAO,kBAAkB,KAAK;GAAkB;AAGzE,SAAO;GAAE,OAAO;GAAM,cAAc,OAAO,UAAU;GAAE;SACjD;AACN,SAAO;GAAE,OAAO;GAAO,OAAO;GAAsB;;;;;;;;;;;;AAaxD,SAAgB,sBAAsB,KAAkC;CACtE,MAAM,SAAS,YAAY,IAAI;AAC/B,KAAI,CAAC,OAAO,MACV,QAAO;CAGT,MAAM,SAAS,IAAI,IAAI,IAAI;CAG3B,MAAM,OAAO,OAAO,OAChB,OAAO,SAAS,OAAO,MAAM,GAAG,GAChC,OAAO,aAAa,WAClB,MACA;AACN,KAAI,SAAS,MAAM,SAAS,OAAO,SAAS,QAAQ,SAAS,KAC3D,QAAO;EACL,OAAO;EACP,OACE;EACH;AAGH,QAAO"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stryke/url",
-  "version": "0.3.39",
+  "version": "0.4.0",
   "type": "module",
   "description": "A package containing the `StormURL` class, which is used to parse and manipulate URLs.",
   "repository": {
@@ -22,11 +22,15 @@
       "import": "./dist/storm-url.mjs"
     },
     "./types": { "require": "./dist/types.cjs", "import": "./dist/types.mjs" },
+    "./validate": {
+      "require": "./dist/validate.cjs",
+      "import": "./dist/validate.mjs"
+    },
     "./*": "./*"
   },
   "types": "./dist/index.d.cts",
   "dependencies": { "ufo": "^1.6.3" },
   "devDependencies": { "@types/node": "^24.11.0", "tsdown": "^0.17.2" },
   "publishConfig": { "access": "public" },
-  "gitHead": "c19d9de45cecf6e0cc805e04358c9dc9d9e4eb6a"
+  "gitHead": "b8125bf046febc1991df62777827d0481c2c89c0"
 }