Por qué validar una URL es más difícil de lo que parece
Casi toda aplicación web acepta direcciones en algún punto: un campo de perfil con el sitio personal, un webhook que el usuario configura, un enlace que se guarda en base de datos o una imagen remota que se descarga. En todos esos casos alguien escribe una cadena y el programa debe decidir si es una URL usable. La pregunta parece trivial hasta que aparecen los casos reales: direcciones sin protocolo, espacios al final, puertos extraños, caracteres no latinos, direcciones IP en formato decimal o esquemas como javascript: y file: que nadie quería permitir.
Existen tres enfoques habituales: usar el objeto URL que ya incluye el lenguaje, apoyarse en paquetes de npm o escribir una expresión regular. Cada uno resuelve un problema distinto y conviene saber cuándo usar cada uno. En este tutorial construiremos un módulo de validación completo, desde la comprobación básica hasta las defensas que exige un servidor que hace peticiones a direcciones proporcionadas por terceros, y lo cubriremos con pruebas automáticas.
Trabajaremos con JavaScript moderno en módulos ES. Todo el código funciona en Node.js en su línea LTS actual (la 24, con la 22 todavía en mantenimiento) y en los navegadores vigentes. La pieza central es la API estándar URL, que sigue la especificación WHATWG y se comporta igual en ambos entornos. Para las pruebas usaremos el ejecutor integrado node:test, de modo que no necesitaremos instalar nada.
Lo que aprenderás a lo largo del texto:
- Qué significa realmente que una cadena sea una URL válida.
- Cómo validar con
new URL()y con el método estáticoURL.canParse(). - Cómo limitar los protocolos permitidos y normalizar la entrada.
- Qué papel juegan los paquetes externos y las expresiones regulares.
- Cómo tratar dominios internacionalizados, puertos y credenciales incrustadas.
- Qué riesgos de seguridad aparecen en el servidor, en especial el SSRF.
- Cómo probar el validador y qué errores evitar.
Qué entendemos por una URL válida
Antes de escribir código hay que fijar una definición, porque «válida» puede significar tres cosas bastante distintas. La primera es la validez sintáctica: la cadena puede analizarse según las reglas de la especificación y produce componentes coherentes (esquema, host, ruta, consulta y fragmento). La segunda es la validez de política: además de analizarse, cumple las reglas de tu aplicación, por ejemplo que solo se admitan http: y https:. La tercera es la validez práctica: la dirección existe, responde y devuelve lo que se espera.
Un analizador sintáctico solo responde a la primera pregunta. Para la segunda necesitas reglas propias encima del resultado del análisis. Para la tercera necesitas una petición de red, y eso introduce latencia, fallos intermitentes y riesgos de seguridad que veremos más adelante. Mezclar los tres niveles en una sola función es el origen de muchos errores, así que en este tutorial los mantendremos separados.
Conviene recordar también que la especificación es muy permisiva. La cadena https:example.com se interpreta como una URL especial con host example.com, y los espacios en los extremos se recortan sin avisar. Que el analizador acepte algo no significa que sea lo que tu formulario quería recibir. Por eso la política propia es imprescindible.
El constructor URL y la captura del error
La herramienta más directa es el constructor URL. Recibe una cadena y devuelve un objeto con los componentes ya separados. Si la cadena no se puede interpretar como una dirección absoluta, lanza un TypeError. Esa excepción es la señal de invalidez.
function esUrlAnalizable(texto) {
try {
new URL(texto);
return true;
} catch {
return false;
}
}
console.log(esUrlAnalizable("https://ejemplo.dev/docs?pagina=2"));
console.log(esUrlAnalizable("ejemplo.dev/docs"));
console.log(esUrlAnalizable("mailto:[email protected]"));
console.log(esUrlAnalizable(""));
true
false
true
false
El resultado enseña dos cosas. Primero, una cadena sin esquema como ejemplo.dev/docs falla porque el constructor exige una URL absoluta cuando no recibe una base. Segundo, mailto: se acepta sin problema: es una URL perfectamente válida, solo que no es una dirección web. Aquí se ve la diferencia entre validez sintáctica y de política.
El constructor devuelve un objeto con propiedades muy útiles para decidir. Veamos qué obtenemos de una dirección completa.
const direccion = new URL(
"https://usuario:[email protected]:8443/v2/pedidos?estado=abierto#resumen"
);
console.log(direccion.protocol);
console.log(direccion.username);
console.log(direccion.hostname);
console.log(direccion.port);
console.log(direccion.pathname);
console.log(direccion.search);
console.log(direccion.hash);
console.log(direccion.origin);
https:
usuario
api.ejemplo.dev
8443
/v2/pedidos
?estado=abierto
#resumen
https://api.ejemplo.dev:8443
Observa que protocol incluye los dos puntos finales y que hostname no incluye el puerto, a diferencia de host. Esos detalles producen fallos sutiles cuando se comparan con cadenas escritas a mano.
URL.canParse como comprobación sin excepciones
Durante años el patrón del bloque try/catch fue la única opción nativa. Hoy existe un método estático pensado exactamente para esto: URL.canParse(). Devuelve un booleano sin lanzar excepciones y sin que tengas que conservar el objeto resultante. Está disponible en Node.js desde las versiones 18.17 y 19.9, y en todos los navegadores actuales.
console.log(URL.canParse("https://ejemplo.dev"));
console.log(URL.canParse("//ejemplo.dev"));
console.log(URL.canParse("/ruta/relativa"));
console.log(URL.canParse("/ruta/relativa", "https://ejemplo.dev"));
true
false
false
true
El segundo argumento opcional es una URL base. Con ella, una ruta relativa se resuelve contra ese origen, lo cual resulta práctico cuando se aceptan enlaces internos. Sin base, las rutas relativas no son analizables.
Una ventaja secundaria es la limpieza del código: una función de una línea sustituye al bloque de captura. Una desventaja es que, si después necesitas inspeccionar los componentes, tendrás que analizar la cadena otra vez con el constructor. En ese caso lo más sensato es seguir usando try/catch una sola vez y reutilizar el objeto. Existe además URL.parse(), que devuelve el objeto o null, y que está disponible en las versiones recientes de Node.js y de los navegadores; si tu entorno de ejecución lo soporta, evita tanto la excepción como el doble análisis.
const resultado = URL.parse("https://ejemplo.dev/blog");
if (resultado) {
console.log(resultado.hostname);
} else {
console.log("La cadena no es una URL");
}
ejemplo.dev
Si necesitas compatibilidad con entornos antiguos, comprueba antes si el método existe o conserva el envoltorio con try/catch como alternativa. En un proyecto nuevo basado en Node.js 22 o posterior, URL.canParse() y URL.parse() están disponibles sin problema.
Restringir los protocolos permitidos
El primer endurecimiento obligatorio es limitar los esquemas. Si tu aplicación guarda enlaces para mostrarlos como hipervínculos, un valor como javascript:alert(1) es analizable y, si se inserta en un atributo href, ejecuta código al hacer clic. Esto es un vector clásico de XSS y la comprobación sintáctica no lo detecta.
La solución consiste en una lista de permitidos, nunca en una lista de prohibidos. Los esquemas peligrosos son muchos (javascript:, data:, vbscript:, file:, blob:), y siempre puede aparecer otro. Una lista cerrada con los esquemas que de verdad aceptas es más segura y más simple.
const PROTOCOLOS_WEB = new Set(["http:", "https:"]);
export function analizarUrlWeb(entrada) {
if (typeof entrada !== "string") return null;
const texto = entrada.trim();
if (texto.length === 0 || texto.length > 2048) return null;
const url = URL.parse(texto);
if (!url) return null;
return PROTOCOLOS_WEB.has(url.protocol) ? url : null;
}
Esta función hace varias cosas pequeñas pero importantes. Rechaza valores que no sean cadenas, recorta espacios, limita la longitud máxima y delega el análisis en la API estándar. El límite de 2048 caracteres es una convención razonable: muchos servidores y proxies rechazan líneas de petición más largas, y una cadena enorme es una forma barata de consumir recursos.
Para exigir solo conexiones cifradas, basta con reducir el conjunto a https:. En aplicaciones modernas suele ser la opción correcta, con una excepción: durante el desarrollo local es habitual necesitar localhost sin cifrado, y ahí conviene un parámetro de configuración en lugar de relajar la regla para todos.
export function analizarUrlSegura(entrada, { permitirLocal = false } = {}) {
const url = analizarUrlWeb(entrada);
if (!url) return null;
if (url.protocol === "https:") return url;
if (permitirLocal && url.hostname === "localhost") return url;
return null;
}
Cuando una dirección admite un campo sin protocolo, como alguien que escribe ejemplo.dev en un formulario, no hay que cambiar la validación. Lo correcto es decidir una política explícita de normalización: si no hay esquema, anteponer el esquema seguro y volver a analizar. Es mejor hacerlo de forma visible y no con una expresión regular que haga opcional el prefijo, porque así controlas exactamente qué se acepta.
export function normalizarEntradaUsuario(entrada) {
const texto = String(entrada).trim();
if (!texto) return null;
const conEsquema = /^[a-z][a-z0-9+.-]*:/i.test(texto)
? texto
: `https://${texto}`;
return analizarUrlWeb(conEsquema);
}
Hay un matiz: una entrada como localhost:3000 parece tener esquema (localhost:) según esa expresión. Si necesitas admitir ese formato, añade un caso previo. Estos bordes son la razón por la que conviene tener pruebas, un asunto que cubriremos más abajo.
Expresiones regulares: cuándo sí y cuándo no
Es tentador resolver todo con una expresión regular, porque ofrece control total y no depende de nada. Un patrón típico comprueba el esquema, el nombre de dominio o la IP, el puerto opcional, la ruta, la consulta y el fragmento. Para casos de uso muy acotados funciona, pero tiene límites serios.
Una versión razonable para direcciones web con esquema obligatorio podría ser la siguiente.
const PATRON_WEB =
/^https?:\/\/(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}(?::\d{1,5})?(?:\/[^\s?#]*)?(?:\?[^\s#]*)?(?:#\S*)?$/i;
console.log(PATRON_WEB.test("https://ejemplo.dev/ruta?x=1#a"));
console.log(PATRON_WEB.test("https://ejemplo"));
console.log(PATRON_WEB.test("ftp://ejemplo.dev"));
console.log(PATRON_WEB.test("https://ejemplo.dev/con espacio"));
true
false
false
false
Funciona para esos ejemplos, y aun así ya se aprecian los inconvenientes. No admite nombres internacionalizados como mañana.es, ni localhost, ni direcciones IPv6 entre corchetes, ni dominios con punto final. Tampoco distingue un puerto válido de uno fuera de rango: :99999 pasa el filtro aunque el máximo es 65535. Y cada ampliación hace el patrón más largo y más difícil de mantener.
Hay además un riesgo de rendimiento. Los patrones con cuantificadores anidados pueden sufrir retroceso catastrófico (ReDoS) ante entradas diseñadas a propósito, y eso bloquea el bucle de eventos de Node.js. Un validador expuesto a internet no debería depender de una expresión compleja sin límites de longitud previos.
Mi recomendación práctica es usar la expresión regular solo como filtro de formato muy simple, o en validaciones del lado del cliente donde el objetivo es ayudar al usuario y no garantizar seguridad. Cuando necesites buscar fragmentos dentro de un texto más largo, por ejemplo extraer enlaces de un párrafo, las expresiones regulares sí son la herramienta adecuada; si quieres repasar cómo trabajar con coincidencias y alternativas, te sirve esta guía sobre buscar subcadenas en JavaScript con includes, indexOf y regex. Una vez extraído cada candidato, pásalo por el analizador estándar.
const CANDIDATAS = /\bhttps?:\/\/[^\s<>"']+/gi;
export function extraerEnlaces(texto) {
const encontradas = texto.match(CANDIDATAS) ?? [];
return encontradas
.map((c) => analizarUrlWeb(c.replace(/[.,;:!?)]+$/, "")))
.filter(Boolean)
.map((u) => u.href);
}
console.log(
extraerEnlaces("Docs en https://ejemplo.dev/guia, y soporte en https://ayuda.ejemplo.dev.")
);
[ 'https://ejemplo.dev/guia', 'https://ayuda.ejemplo.dev/' ]
Fíjate en la división de responsabilidades: la expresión regular encuentra candidatas con tolerancia y el analizador estándar decide si son válidas. Esa combinación es mucho más robusta que intentar que un solo patrón haga ambas cosas.
Paquetes de npm: ayudas y su coste
Existen paquetes pequeños dedicados a esta tarea. Uno general, is-url, comprueba el formato pero acepta cualquier protocolo, de modo que mailto: también pasaría. Otro, is-url-http, limita la comprobación a direcciones HTTP y HTTPS. Son cómodos, aunque conviene preguntarse si hacen falta.
Con la API nativa, la función que hemos escrito antes cubre lo mismo en pocas líneas, sin dependencias, sin riesgo de cadena de suministro y con el comportamiento exacto del estándar que usan los navegadores. Cada dependencia añade superficie de ataque, tamaño de instalación y una versión más que vigilar. Para algo que se resuelve con diez líneas, el coste rara vez compensa.
Hay situaciones donde una librería sí aporta. Si necesitas una lista actualizada de sufijos públicos para distinguir ejemplo.co.uk de un subdominio, un paquete basado en esa lista es la forma correcta. Lo mismo ocurre si necesitas validar tipos concretos de URL, como enlaces de vídeo de plataformas conocidas, o si trabajas en un entorno sin la API URL. Antes de instalar nada, revisa la fecha del último mantenimiento, el número de dependencias transitivas y si el comportamiento coincide con la especificación actual.
Si decides usar una de estas librerías, mantén tu propia función como envoltorio. Así, el resto de la aplicación depende de analizarUrlWeb y no de un paquete concreto, y podrás sustituirlo sin tocar cien archivos.
Dominios, IDN y puntos delicados del anfitrión
El nombre de host es la parte más rica en casos extremos. El analizador estándar convierte automáticamente los nombres internacionalizados a su forma Punycode, que es la que viaja por la red.
const u = new URL("https://mañana.es/café?q=ñandú");
console.log(u.hostname);
console.log(u.pathname);
console.log(u.search);
xn--maana-pta.es
/caf%C3%A9
?q=%C3%B1and%C3%BA
El host se transforma a xn--maana-pta.es, mientras que la ruta y la consulta se codifican con porcentajes. Si te interesa entender por qué cada parte se codifica de forma distinta y qué función usar en cada caso, tienes el detalle en este artículo sobre encodeURI frente a encodeURIComponent para codificar URLs en JavaScript.
Esta conversión tiene una consecuencia de seguridad: los ataques de homógrafos. Un dominio que mezcla letras latinas y cirílicas puede parecer idéntico al legítimo a simple vista. Si tu aplicación muestra enlaces a otros usuarios, considera mostrar el hostname en Punycode cuando contenga caracteres de varios alfabetos, o directamente rechazarlo.
export function tieneHostMixto(url) {
const host = url.hostname;
return host.split(".").some((etiqueta) => etiqueta.startsWith("xn--"));
}
Otros detalles del anfitrión que merece la pena controlar:
- Un punto final tras el dominio es válido y distinto del mismo nombre sin él para comparaciones de cadenas.
- Las mayúsculas se normalizan a minúsculas en el host, no en la ruta.
- Los puertos por defecto (80 para HTTP y 443 para HTTPS) desaparecen de
porty dehref. - Las direcciones IPv4 en formato octal, hexadecimal o decimal único se convierten a la notación con puntos.
Este último punto es especialmente relevante. El analizador estándar interpreta un número decimal único o una forma hexadecimal abreviada como la dirección de bucle local.
console.log(new URL("http://2130706433").hostname);
console.log(new URL("http://0x7f.1").hostname);
console.log(new URL("http://[::1]:8080").hostname);
127.0.0.1
127.0.0.1
[::1]
Quien intente burlar un filtro de texto que busque la cadena «127.0.0.1» tiene a su disposición muchas representaciones equivalentes. Por eso, las decisiones de seguridad nunca deben tomarse comparando la cadena original, sino el hostname ya normalizado por el analizador.
Credenciales incrustadas y otras rarezas
Una URL puede contener usuario y contraseña delante del host: https://usuario:[email protected]. En una aplicación normal casi nunca hay motivo para aceptarlo, y sí hay motivos para rechazarlo. Guardar una contraseña dentro de una cadena que luego se registra en logs o se muestra en pantalla es una fuga de secretos, y además el formato se ha usado para engañar: si delante de la arroba aparece un dominio conocido, el host real es lo que viene después.
export function sinCredenciales(url) {
return url.username === "" && url.password === "";
}
const sospechosa = new URL("https://[email protected]/entrar");
console.log(sospechosa.hostname);
console.log(sinCredenciales(sospechosa));
sitio-malicioso.dev
false
Integra esta comprobación en la política común. También puedes limitar el puerto a un conjunto conocido si tu caso lo permite, y rechazar rutas que contengan secuencias de recorrido cuando la URL vaya a mapearse a un recurso local. Recuerda que el analizador normaliza /a/../b a /b, de modo que las secuencias de puntos simples se resuelven antes de que tu código las vea.
Ensamblemos ahora una función de política única que combine todas las reglas vistas hasta aquí.
const PROTOCOLOS = new Set(["http:", "https:"]);
const LONGITUD_MAXIMA = 2048;
export function validarUrl(entrada, opciones = {}) {
const { soloHttps = false, permitirCredenciales = false } = opciones;
if (typeof entrada !== "string") {
return { valida: false, motivo: "no es texto" };
}
const texto = entrada.trim();
if (!texto) return { valida: false, motivo: "vacía" };
if (texto.length > LONGITUD_MAXIMA) {
return { valida: false, motivo: "demasiado larga" };
}
const url = URL.parse(texto);
if (!url) return { valida: false, motivo: "no analizable" };
if (!PROTOCOLOS.has(url.protocol)) {
return { valida: false, motivo: "protocolo no permitido" };
}
if (soloHttps && url.protocol !== "https:") {
return { valida: false, motivo: "se exige https" };
}
if (!permitirCredenciales && (url.username || url.password)) {
return { valida: false, motivo: "credenciales incrustadas" };
}
if (url.hostname === "") {
return { valida: false, motivo: "sin host" };
}
return { valida: true, url };
}
Devolver un objeto con el motivo en lugar de un simple booleano cuesta muy poco y mejora la experiencia: puedes mostrar mensajes útiles al usuario y registrar las causas de rechazo para detectar abusos o fallos de usabilidad.
SSRF: cuando el servidor sigue la URL
Todo lo anterior protege la entrada. Pero hay un escenario más peligroso: aceptar una URL que el propio servidor va a visitar, ya sea para generar una vista previa, descargar una imagen, llamar a un webhook o importar un archivo. Si no se controla, un atacante puede apuntar tu servidor hacia recursos internos. Es lo que se conoce como falsificación de peticiones del lado del servidor, o SSRF, y figura entre las vulnerabilidades más graves en entornos de nube.
El objetivo clásico es el servicio de metadatos de la instancia, accesible desde dentro de la red del proveedor mediante una dirección local de enlace. Con una sola petición, el atacante puede obtener credenciales temporales. Otros objetivos son paneles de administración en localhost, bases de datos sin autenticar en la red privada o servicios internos que confían en el origen de la petición.
Una defensa seria requiere resolver el nombre de host antes de conectar y comprobar la dirección IP real contra rangos prohibidos. Validar solo el texto no basta, porque un nombre público puede resolver a una dirección privada.
import { lookup } from "node:dns/promises";
import { isIP } from "node:net";
function esIpv4Privada(ip) {
const [a, b] = ip.split(".").map(Number);
return (
a === 10 ||
a === 127 ||
a === 0 ||
(a === 169 && b === 254) ||
(a === 172 && b >= 16 && b <= 31) ||
(a === 192 && b === 168) ||
(a === 100 && b >= 64 && b <= 127)
);
}
function esIpv6Privada(ip) {
const minuscula = ip.toLowerCase();
return (
minuscula === "::1" ||
minuscula === "::" ||
minuscula.startsWith("fc") ||
minuscula.startsWith("fd") ||
minuscula.startsWith("fe80") ||
minuscula.startsWith("::ffff:")
);
}
export async function hostEsPublico(hostname) {
const limpio = hostname.replace(/^\[|\]$/g, "");
const direcciones = isIP(limpio)
? [{ address: limpio, family: isIP(limpio) }]
: await lookup(limpio, { all: true });
if (direcciones.length === 0) return false;
return direcciones.every(({ address, family }) =>
family === 4 ? !esIpv4Privada(address) : !esIpv6Privada(address)
);
}
Esta función cubre los rangos más habituales: bucle local, redes privadas, enlace local y el rango de traducción compartida. Es una base útil, no una solución completa. La lista de bloques reservados es más larga y puede cambiar, así que en producción conviene apoyarse en una librería mantenida que clasifique direcciones, o en la configuración de red del propio entorno.
Existe además un problema de fondo llamado reenlace de DNS: el nombre se resuelve una primera vez durante tu comprobación y una segunda al conectar, y el atacante controla el servidor DNS, de modo que la segunda respuesta puede apuntar a una IP interna. La mitigación sólida es conectar directamente a la dirección ya verificada, fijando la resolución en el agente de la petición, y enviar la cabecera Host original.
Estas son las medidas que debería llevar cualquier función que descargue contenido de una URL externa:
- Aplicar la política de protocolos y rechazar credenciales incrustadas.
- Resolver el host y comprobar todas las direcciones devueltas.
- Fijar la conexión a la IP verificada, o validar en el momento de conectar.
- Desactivar o controlar las redirecciones, y revalidar cada destino.
- Poner un tiempo máximo y un tamaño máximo de respuesta.
- Ejecutar el servicio en una red con salida restringida mediante reglas de cortafuegos.
Las redirecciones merecen atención aparte: un servidor público puede responder con un 302 hacia la dirección del servicio de metadatos. Si el cliente HTTP las sigue en automático, la validación inicial no sirve de nada. Una opción sencilla es seguirlas a mano, con un límite de saltos, aplicando la validación completa a cada nueva ubicación.
export async function descargarSeguro(entrada, saltosMaximos = 3) {
let actual = entrada;
for (let salto = 0; salto <= saltosMaximos; salto++) {
const { valida, url, motivo } = validarUrl(actual, { soloHttps: true });
if (!valida) throw new Error(`URL rechazada: ${motivo}`);
if (!(await hostEsPublico(url.hostname))) {
throw new Error("El host resuelve a una dirección no pública");
}
const respuesta = await fetch(url, {
redirect: "manual",
signal: AbortSignal.timeout(5000),
});
if (respuesta.status >= 300 && respuesta.status < 400) {
const destino = respuesta.headers.get("location");
if (!destino) throw new Error("Redirección sin destino");
actual = new URL(destino, url).href;
continue;
}
return respuesta;
}
throw new Error("Demasiadas redirecciones");
}
Este ejemplo todavía tiene el hueco del reenlace de DNS descrito antes, que se cierra fijando la resolución del agente; sirve para ilustrar la estructura: validar, comprobar, pedir sin seguir automáticamente y repetir. Fíjate también en el uso de AbortSignal.timeout, que evita que una conexión lenta mantenga recursos ocupados indefinidamente.
Pruebas con node:test
Un validador de URLs es un candidato perfecto para pruebas automáticas, porque su comportamiento se describe con tablas de entradas y salidas. El ejecutor integrado node:test es estable desde Node.js 20 y no requiere dependencias. Guardemos el validador en un módulo y escribamos pruebas con casos válidos, inválidos y adversariales.
validador-url/
├── package.json
├── src/
│ └── validar-url.js
└── test/
└── validar-url.test.js
El archivo de configuración mínimo declara el tipo de módulo para poder usar import.
{
"name": "validador-url",
"version": "1.0.0",
"type": "module",
"scripts": {
"test": "node --test"
}
}
Ahora las pruebas. Agrupamos los casos con describe y generamos una prueba por cada fila de una tabla, lo que mantiene el archivo corto y legible.
import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { validarUrl } from "../src/validar-url.js";
describe("validarUrl", () => {
const aceptadas = [
"https://ejemplo.dev",
"http://ejemplo.dev:8080/ruta?a=1#parte",
"https://mañana.es/café",
"https://[2001:db8::1]/",
" https://ejemplo.dev ",
];
for (const entrada of aceptadas) {
it(`acepta ${JSON.stringify(entrada)}`, () => {
assert.equal(validarUrl(entrada).valida, true);
});
}
const rechazadas = [
["", "vacía"],
["ejemplo.dev", "no analizable"],
["javascript:alert(1)", "protocolo no permitido"],
["ftp://ejemplo.dev", "protocolo no permitido"],
["file:///etc/passwd", "protocolo no permitido"],
["https://usuario:[email protected]", "credenciales incrustadas"],
["https://" + "a".repeat(3000) + ".dev", "demasiado larga"],
];
for (const [entrada, motivo] of rechazadas) {
it(`rechaza por ${motivo}`, () => {
const resultado = validarUrl(entrada);
assert.equal(resultado.valida, false);
assert.equal(resultado.motivo, motivo);
});
}
it("rechaza valores que no son texto", () => {
assert.equal(validarUrl(null).valida, false);
assert.equal(validarUrl(42).valida, false);
assert.equal(validarUrl(undefined).valida, false);
});
it("exige https cuando se pide", () => {
const resultado = validarUrl("http://ejemplo.dev", { soloHttps: true });
assert.equal(resultado.valida, false);
assert.equal(resultado.motivo, "se exige https");
});
});
Para ejecutar el conjunto, basta con lanzar el script. La salida resume cada caso con una marca y un resumen final.
npm test
▶ validarUrl
✔ acepta "https://ejemplo.dev"
✔ acepta "http://ejemplo.dev:8080/ruta?a=1#parte"
✔ acepta "https://mañana.es/café"
✔ acepta "https://[2001:db8::1]/"
✔ acepta " https://ejemplo.dev "
✔ rechaza por vacía
✔ rechaza por no analizable
✔ rechaza por protocolo no permitido
✔ rechaza por protocolo no permitido
✔ rechaza por protocolo no permitido
✔ rechaza por credenciales incrustadas
✔ rechaza por demasiado larga
✔ rechaza valores que no son texto
✔ exige https cuando se pide
✔ validarUrl
ℹ tests 14
ℹ pass 14
ℹ fail 0
Cuando descubras un fallo en producción, el procedimiento sano es añadir primero la entrada problemática a la tabla, comprobar que la prueba falla y después corregir la función. Así el conjunto crece con cada incidencia y evita regresiones. Para el código de red, como hostEsPublico, sustituye lookup por una función simulada con el sistema de dobles de node:test, de modo que las pruebas no dependan de internet.
import { describe, it, mock } from "node:test";
import assert from "node:assert/strict";
describe("clasificación de direcciones", () => {
it("detecta redes privadas", () => {
const privadas = ["10.0.0.5", "172.20.1.1", "192.168.1.10", "169.254.169.254"];
for (const ip of privadas) {
assert.equal(esIpv4Privada(ip), true, ip);
}
});
it("deja pasar direcciones públicas", () => {
assert.equal(esIpv4Privada("93.184.216.34"), false);
});
it("usa una función simulada", () => {
const resolver = mock.fn(() => [{ address: "10.0.0.1", family: 4 }]);
assert.equal(resolver.mock.callCount(), 0);
resolver();
assert.equal(resolver.mock.callCount(), 1);
});
});
Recuerda exportar esIpv4Privada si quieres probarla de forma directa, o probarla a través de la función pública. Y no olvides los casos de las representaciones raras del anfitrión: el número decimal 2130706433 o la forma con ceros iniciales deben terminar clasificados como bucle local una vez normalizados.
Errores comunes que conviene evitar
Tras ver el panorama completo, recopilo los fallos más frecuentes que aparecen en revisiones de código.
El primero es validar con una expresión regular y fiarse de ella para decisiones de seguridad. Una expresión es un filtro de formato, no una barrera. El segundo es usar startsWith("https://") o includes("ejemplo.dev") sobre la cadena sin analizarla. Una cadena como https://ejemplo.dev.atacante.net o https://atacante.net/?ref=ejemplo.dev pasa esas comprobaciones sin ser tu dominio.
const mala = "https://ejemplo.dev.atacante.net/login";
console.log(mala.includes("ejemplo.dev"));
console.log(new URL(mala).hostname === "ejemplo.dev");
console.log(new URL(mala).hostname.endsWith(".ejemplo.dev"));
true
false
false
La comparación correcta se hace sobre el hostname ya analizado y, para subdominios, con el punto delante para no aceptar sufijos parecidos como malejemplo.dev. El tercer error es confiar en URL.canParse() como si fuera una política: es solo sintaxis y deja pasar file: y data:. El cuarto es olvidar la longitud y el tipo de entrada, lo que provoca excepciones inesperadas cuando llega undefined o un objeto en lugar de una cadena.
Otros fallos habituales:
- Comparar URLs como cadenas en lugar de normalizarlas:
https://ejemplo.devyhttps://ejemplo.dev/son equivalentes, y tambiénHTTPS://EJEMPLO.DEV. - Construir enlaces concatenando texto en lugar de usar
URLSearchParamspara la consulta, lo que rompe los caracteres especiales. - Confundir
hostconhostname, y por tanto comparar con el puerto incluido. - Aceptar redirecciones sin límite ni revalidación.
- Validar solo en el cliente. El navegador es del usuario, y cualquier regla debe repetirse en el servidor.
- Mostrar la URL original en lugar de la normalizada, con lo que se pierde la protección frente a homógrafos.
Para construir URLs de forma segura, la API nativa también ayuda. En vez de pegar fragmentos, usa el constructor con base y los parámetros de consulta como objeto.
const base = new URL("https://api.ejemplo.dev/v2/");
const consulta = new URL("buscar", base);
consulta.searchParams.set("termino", "café & té");
consulta.searchParams.set("pagina", "2");
console.log(consulta.href);
https://api.ejemplo.dev/v2/buscar?termino=caf%C3%A9+%26+t%C3%A9&pagina=2
Así el escape se aplica de forma correcta y consistente, sin trucos manuales.
Rendimiento y buenas prácticas de diseño
La mayoría de las aplicaciones validan pocas URLs por petición, y el coste del analizador nativo es despreciable. Aun así, hay tres puntos que cuentan cuando se procesan lotes grandes, como al importar miles de enlaces desde un archivo.
El primero: URL.canParse() y URL.parse() evitan el coste de crear y capturar excepciones, que es notablemente mayor que el de un retorno normal. En bucles con muchas entradas inválidas, la diferencia se nota. El segundo: ejecuta las comprobaciones más baratas primero, como el tipo, la longitud y la cadena vacía, antes de analizar. El tercero: si resuelves nombres de host, hazlo en paralelo con un límite de concurrencia y guarda resultados en una caché con caducidad corta, porque las consultas DNS dominan con mucha diferencia el tiempo total.
import { performance } from "node:perf_hooks";
const entradas = Array.from({ length: 200_000 }, (_, i) =>
i % 2 === 0 ? `https://sitio${i}.ejemplo.dev/ruta` : `no-es-url-${i}`
);
function conExcepcion(texto) {
try {
new URL(texto);
return true;
} catch {
return false;
}
}
let t = performance.now();
entradas.forEach(conExcepcion);
console.log("try/catch:", Math.round(performance.now() - t), "ms");
t = performance.now();
entradas.forEach((e) => URL.canParse(e));
console.log("canParse:", Math.round(performance.now() - t), "ms");
Los números exactos dependen de tu máquina y de la versión del motor, así que mídelos en tu propio entorno en lugar de fiarte de cifras ajenas. Lo habitual es que la segunda variante gane con holgura cuando hay muchas entradas inválidas.
Como resumen de diseño, estas prácticas dan buen resultado en proyectos reales:
- Centraliza la validación en un único módulo con una función de política y devuélvela tipada o con motivo de rechazo.
- Analiza una vez y reutiliza el objeto
URLen el resto del flujo, en lugar de volver a analizar la cadena. - Guarda siempre la forma normalizada (
href) y no la original. - Usa listas de permitidos para esquemas y, cuando proceda, para dominios.
- Registra los rechazos con su motivo para detectar patrones de abuso.
- Repite la validación en el servidor aunque ya exista en el cliente.
- Escribe una prueba por cada incidencia real que encuentres.
Un ejemplo completo en un formulario del navegador
Para cerrar el recorrido práctico, veamos el uso en el lado del cliente. La validación en el navegador no sustituye a la del servidor, pero mejora la experiencia al dar respuesta inmediata. Podemos aprovechar el propio HTML con un campo de tipo url y reforzarlo con nuestra función, mostrando el mensaje de error con setCustomValidity.
const campo = document.querySelector("#sitio-web");
const mensaje = document.querySelector("#mensaje-error");
const MOTIVOS = {
"vacía": "Escribe una dirección.",
"no analizable": "La dirección no tiene un formato válido.",
"protocolo no permitido": "Solo se admiten direcciones web.",
"se exige https": "La dirección debe empezar por https.",
"credenciales incrustadas": "No incluyas usuario ni contraseña.",
"demasiado larga": "La dirección es demasiado larga.",
};
campo.addEventListener("input", () => {
const resultado = validarUrl(campo.value, { soloHttps: true });
if (resultado.valida) {
campo.setCustomValidity("");
mensaje.textContent = "";
} else {
const texto = MOTIVOS[resultado.motivo] ?? "Dirección no válida.";
campo.setCustomValidity(texto);
mensaje.textContent = texto;
}
});
campo.addEventListener("blur", () => {
const resultado = validarUrl(campo.value, { soloHttps: true });
if (resultado.valida) campo.value = resultado.url.href;
});
Al perder el foco, el campo se reescribe con la forma normalizada, de modo que el usuario ve exactamente lo que se enviará. La asignación del mensaje se hace con textContent y no con innerHTML, para no introducir una nueva vía de inyección. Y si más adelante pintas esa dirección como un enlace, asigna el valor normalizado al atributo href solo después de pasar la política de protocolos.
function crearEnlaceSeguro(entrada, etiqueta) {
const { valida, url } = validarUrl(entrada);
if (!valida) return document.createTextNode(etiqueta);
const a = document.createElement("a");
a.href = url.href;
a.textContent = etiqueta;
a.rel = "noopener noreferrer nofollow";
a.target = "_blank";
return a;
}
El uso de rel evita que la página destino obtenga acceso a la ventana de origen y limita la transmisión de la referencia. Si la dirección no pasa la política, se muestra el texto sin enlace, que es el comportamiento más seguro por defecto.
Conclusiones
Validar una URL en JavaScript no consiste en encontrar la expresión regular perfecta, sino en separar con claridad tres capas: análisis sintáctico, política de la aplicación y comprobaciones de red. El objeto URL y los métodos URL.canParse() y URL.parse() resuelven la primera capa con el comportamiento exacto del estándar, sin dependencias y con muy buen rendimiento.
Sobre esa base, la política debe ser explícita: lista cerrada de protocolos, rechazo de credenciales incrustadas, límites de longitud y comparaciones hechas sobre el host normalizado y no sobre la cadena original. Si tu servidor visita las direcciones que recibe, añade la defensa frente a SSRF: resolución del host, bloqueo de rangos no públicos, control estricto de redirecciones, tiempos máximos y, de forma ideal, restricciones de red en la infraestructura.
Por último, convierte todo ello en pruebas con node:test. Una tabla de casos válidos, inválidos y adversariales cuesta pocos minutos y detecta regresiones durante años. Con un módulo único, bien probado y con motivos de rechazo claros, tendrás un validador sencillo de mantener, seguro por defecto y reutilizable tanto en el servidor como en el navegador.
