Errores de codificación de URL: prueba las entradas de la API del agente antes de las llamadas

Una URL no es una cadena inofensiva. Es una instrucción estructurada cuyos delimitadores determinan el host, la ruta, los nombres de los parámetros y sus valores. Si un agente combina texto proporcionado por el usuario con una URL de forma incorrecta, puede llamar a un endpoint distinto del que revisó el desarrollador.

He visto equipos aprobar una solicitud que en la transcripción de la herramienta parecía GET /records/alice y pasar después una tarde entera descubriendo que el servidor había recibido una ruta con una barra adicional, un parámetro de consulta duplicado o una secuencia de recorrido descodificada. El agente no necesitó un exploit exótico. Bastó texto corriente como a+b, %2F, &admin=true o un nombre escrito en un alfabeto no ASCII.

Los errores de codificación de URL se suelen minimizar porque un cliente HTTP a menudo «gestiona la codificación». En realidad gestiona parte de la serialización según su propia API y sus valores predeterminados. No puede decidir si un valor del usuario pertenece a un segmento de ruta, a un valor de consulta, al cuerpo de un formulario o a ningún sitio. Esa decisión debe estar en la definición de la acción y en sus pruebas.

El destino de la solicitud, no la cadena visible, decide la llamada

Una solicitud puede cambiar de significado cada vez que el software analiza o reconstruye la URL. La secuencia que produce el agente es solo el principio. La biblioteca cliente puede normalizarla, un proxy inverso puede reescribirla y el framework de la aplicación puede descodificarla antes de buscar la ruta o vincular los parámetros.

RFC 3986 divide una URI en componentes: esquema, autoridad, ruta, consulta y fragmento. Dentro de una ruta, / es un delimitador. Dentro de una consulta, & y = adquieren significado en las convenciones habituales, aunque RFC 3986 no define una gramática universal para las consultas. Esa diferencia explica la mayoría de los fallos que se suelen llamar, sin precisión, «problemas de codificación».

Imagina una acción destinada a obtener un proyecto:

GET https://api.example.test/projects/{project_id}

Si project_id es north/ops, estos destinos no son equivalentes:

/projects/north/ops
/projects/north%2Fops

El primero tiene dos segmentos después de projects. El segundo intenta transportar una barra literal dentro de un solo segmento. Que el segundo caso sobreviva depende de todo el recorrido entre el cliente y la aplicación. Algunas pilas descodifican %2F antes de buscar la ruta y lo convierten en la primera forma. Otras lo rechazan. Una prueba que solo afirma «la URL estaba codificada» demuestra muy poco.

La misma trampa aparece en las consultas. Una acción que busca una frase literal no debería construir esto sustituyendo USER_TEXT por texto sin procesar:

/search?q=USER_TEXT

Con red&limit=500, el destino final puede convertirse en:

/search?q=red&limit=500

La aplicación ve entonces dos parámetros de consulta. Si el código crea un objeto de consulta y proporciona red&limit=500 como valor de q, debería producir:

/search?q=red%26limit%3D500

Ese es el límite concreto que hay que probar: entra un campo semántico, sale un destino exacto y en el destino se recupera el mismo campo semántico.

No pruebes solo con letras y números. Esos valores ocultan precisamente los errores que exponen los agentes. Un agente recibe tickets de soporte, títulos de incidencias, nombres de ramas, rutas de archivos, URL copiadas y texto libre. Los datos reales contienen delimitadores.

Un parámetro de ruta es un segmento, no una URL a medio construir

Trata un parámetro de ruta como un único segmento, salvo que el contrato de la API indique expresamente que acepta una ruta. Esta regla elimina una cantidad sorprendente de ambigüedad.

Los desarrolladores suelen concatenar rutas porque el resultado se lee bien:

const target = base + "/projects/" + projectId + "/builds";

Ese código no asigna un significado específico de componente a projectId. Si el valor contiene /, ?, # o %, el resultado dependerá de lo que haga el código posterior. También invita a otro error: alguien ve un valor codificado en un registro, vuelve a aplicar encodeURIComponent «por seguridad» y produce otro identificador.

Construye los segmentos como datos, codifica cada uno una sola vez y une únicamente los separadores que pertenecen a la ruta. En JavaScript, este pequeño helper hace visible el contrato:

function pathSegment(value) {
  if (typeof value !== "string" || value.length === 0) {
    throw new Error("project id must be a nonempty string");
  }
  return encodeURIComponent(value);
}

const path = "/projects/" + pathSegment(projectId) + "/builds";

encodeURIComponent es apropiado aquí porque codifica /, ?, #, & y = que de otro modo modificarían la ruta o iniciarían una consulta o un fragmento. Deja sin escapar un pequeño conjunto definido por RFC 3986, incluidos los apóstrofos y los paréntesis. Normalmente eso no cambia la estructura de la ruta, pero un contrato estricto puede exigir un codificador más restrictivo. Decide según la especificación de la API, no por costumbre.

No uses encodeURI para un solo segmento. Conserva los delimitadores URI porque espera una URI completa. Si le pasas north/ops, la barra permanece y la ruta cambia. Es una recomendación popular porque el nombre de la función parece adecuado, pero su ámbito es otro.

Una ruta puede contener legítimamente varios segmentos, por ejemplo cuando una API define /{owner}/{repository}. Modela eso como dos campos, no como una cadena libre resourcePath. Si el endpoint necesita realmente un identificador opaco que pueda contener barras, considera colocarlo en un parámetro de consulta o en el cuerpo JSON. Las API que obligan a pasar texto opaco por las capas de enrutamiento hacen que todos tengan que adivinar qué ocurre con las barras codificadas.

Hay además una decisión de enrutamiento que la codificación del cliente no puede corregir. Muchos proxies y frameworks normalizan segmentos como . y .., agrupan barras repetidas o rechazan separadores codificados. Pregunta al responsable del endpoint si la búsqueda de la ruta ocurre antes o después de descodificar los porcentajes. Después prueba la ruta desplegada, incluido el proxy. La documentación de un framework ejecutado de forma aislada en el equipo del desarrollador no responde a esa pregunta.

Las cadenas de consulta necesitan una gramática declarada

Una cadena de consulta no es un bloque único que se escapa. Es una colección de campos cuya gramática pertenece a la API. Antes de que un agente pueda llamar al endpoint con seguridad, debes decidir cómo se tratan los nombres repetidos, los valores vacíos, las matrices, los booleanos, los espacios y los duplicados.

El estándar WHATWG URL y las API orientadas al navegador usan la serialización de consultas de estilo formulario para URLSearchParams. En esa convención, un espacio suele convertirse en + y un signo más literal en %2B. Muchos analizadores de servidores usan la misma convención. RFC 3986 no dice que + signifique un espacio en una URI genérica. Ambos hechos importan cuando un componente usa un analizador genérico y otro uno de formularios.

Usa un constructor de consultas en lugar de plantillas de cadenas:

const query = new URLSearchParams();
query.set("q", userText);
query.set("include_archived", "false");
for (const label of labels) query.append("label", label);

const url = "https://api.example.test/search?" + query.toString();

Para userText = "C++ & systems", la escritura exacta puede ser q=C%2B%2B+%26+systems. Un servidor que aplique descodificación de formularios debería recuperar C++ & systems. La prueba de regresión debe esperar el valor semántico de la API, no exigir que todas las bibliotecas usen %20 para los espacios. En las convenciones de consulta habituales, %20 y + pueden representar un espacio, pero un signo más literal debe seguir siendo un signo más después del análisis.

Los campos repetidos requieren una decisión explícita. Estos contratos son distintos:

?label=bug&label=security
?label=bug,security
?label=["bug","security"]

El primero usa un nombre repetido. El segundo es un valor que contiene una coma, salvo que la API indique lo contrario. El tercero es una cadena con aspecto de JSON, no JSON, a menos que el servidor la analice deliberadamente. No digas al agente «pasa las etiquetas en la URL» y dejes implícito el formato. Dale un argumento de tipo matriz y haz que la acción lo serialice de la única forma que acepta el endpoint.

Los parámetros escalares duplicados son otro fallo silencioso. Una solicitud con ?role=user&role=admin puede devolver el primer valor, el último, una matriz o un error según el framework. Si una comprobación de seguridad lee el primero y un servicio posterior lee el último, se produce una decisión dividida. Rechaza los duplicados de los campos que solo deben aparecer una vez, en el primer componente que controles.

Los fragmentos también merecen atención porque confunden la depuración. Normalmente #section nunca sale del cliente como parte de una solicitud HTTP. Si una entrada sin procesar añade #, puede eliminar todo lo que viene después de un objeto URL antes de enviar la solicitud. Codifícalo dentro de un valor de ruta o de consulta cuando sea un dato. No confíes en un registro de la cadena original para saber qué llegó al servidor.

Los signos de porcentaje y el orden de descodificación crean identificadores distintos

Descodifica los escapes de porcentaje una sola vez y en un límite definido. Si dos componentes descodifican la misma entrada, un valor que parecía inofensivo puede convertirse en un delimitador después de superar la primera comprobación.

Toma el texto %252F. Una descodificación produce %2F. Una segunda produce /. Esto importa cuando la validación ocurre entre ambas operaciones. Un gateway puede rechazar / sin procesar y permitir %252F, mientras una aplicación posterior descodifica de nuevo y divide la ruta. Lo mismo ocurre con %252e, que se convierte en %2e y después en ..

Distingue estos tres valores tanto en el diseño como en las pruebas:

1. La escritura recibida por la red, como %252F.
2. El valor después de una descodificación, como %2F.
3. El valor de la aplicación después de todos los analizadores y reescrituras, como /.

Los equipos suelen llamar «la URL» a los tres. Ese lenguaje confuso provoca revisiones defectuosas porque se comparan etapas distintas sin advertirlo.

RFC 3986 recomienda que los productores de URI no codifiquen ni descodifiquen la misma cadena más de una vez. Es un buen principio, pero no un plan de implementación. Define que el serializador de la acción recibe cadenas de aplicación descodificadas y que el servidor recibe bytes brutos de la solicitud. Todo lo que haya entre esos límites debe conservar el escape o rechazar las formas que no pueda preservar.

No aceptes entradas ya codificadas por comodidad. Un prompt que diga «proporciona un ID de proyecto codificado» obliga al modelo a adivinar si %2F es un dato o una instrucción. La siguiente capa no sabrá si debe conservar el signo de porcentaje o convertirlo en %25. Acepta campos de texto sin codificar, codifícalos una vez en la capa de acciones y rechaza escapes de porcentaje mal formados solo donde se acepten URL sin procesar de forma intencionada.

Unicode añade otro límite. Normalmente un cliente URL convierte el texto en bytes UTF-8 y codifica los bytes que no pueden aparecer directamente en el componente elegido. Los frameworks del servidor pueden normalizar Unicode de forma distinta antes de buscar un usuario o un recurso. Mantén los identificadores en una forma canónica en la capa de aplicación si el dominio lo exige. La codificación de URL transporta bytes, pero no decide si dos cadenas visualmente parecidas nombran la misma cuenta.

Prueba todo el recorrido con entradas adversarias, pero normales

Una prueba útil de codificación observa dos cosas: el destino de solicitud emitido por el cliente y los valores analizados por el receptor. Si solo compruebas un lado, una reescritura del proxy o un descodificador del framework puede cambiar el significado en medio.

Empieza con un handler de eco controlado en tu entorno de pruebas. Debe registrar el destino bruto cuando el runtime del servidor lo exponga y devolver después la ruta y los campos de consulta analizados. No incluyas credenciales en este endpoint. Su función es mostrar la serialización, no autenticar a nadie.

Este pequeño handler de Node muestra la forma de la respuesta:

import http from "node:http";

http.createServer((req, res) => {
  const url = new URL(req.url, "http://local.test");
  const pairs = [...url.searchParams.entries()];
  res.setHeader("content-type", "application/json");
  res.end(JSON.stringify({
    requestTarget: req.url,
    pathname: url.pathname,
    queryPairs: pairs
  }, null, 2));
}).listen(8787);

Envíale casos conocidos y conserva la salida esperada. Por ejemplo, un constructor de consultas que reciba C++ & systems debe producir un resultado con un único par q cuyo valor analizado sea exactamente C++ & systems. Una consulta construida a mano suele revelarse al devolver dos pares o al cambiar los signos más por espacios.

{
  "requestTarget": "/search?q=C%2B%2B+%26+systems",
  "pathname": "/search",
  "queryPairs": [["q", "C++ & systems"]]
}

La suite debe cubrir una matriz compacta, no docenas de cadenas aleatorias:

• Espacio, signo más literal, signo de porcentaje, ampersand, signo igual, interrogación y almohadilla.
• Barra y barra codificada dentro de un identificador pensado como un solo segmento.
• Cadenas vacías, campos opcionales ausentes y nombres de consulta repetidos.
• Un valor Unicode y otro cuyos escapes de porcentaje parezcan una segunda pasada de descodificación.
• Una URL completa pegada en un campo que espera un identificador.

Usa pruebas basadas en propiedades si tu equipo ya trabaja así, pero no escondas los casos importantes entre ejemplos generados. Esos casos documentan por qué existe el límite. Cuando aparezca una regresión, encoded slash stays inside project_id resulta mucho más útil que un número de semilla.

Ejecuta las mismas pruebas de integración a través del recorrido que usa el tráfico de producción. Una prueba directa contra el proceso de la aplicación no indicará si el proxy rechaza %2F, reescribe barras duplicadas o elige otro valor de una consulta repetida. Si el borde de producción no puede incluirse en las pruebas locales, usa una ruta de staging con la misma configuración y conviértela en una comprobación de cada lanzamiento.

Da a los agentes argumentos estructurados, no libertad para construir URL

Un agente debe elegir una acción y proporcionar argumentos tipados. La implementación de la acción debe elegir el método HTTP, el origen permitido, la plantilla de ruta, la gramática de consulta, los encabezados y la codificación. Permitir que el agente entregue una URL completa concentra todos esos controles en una cadena ambigua.

Un contrato de acción limitado podría ser:

{
  "name": "get_project_builds",
  "input": {
    "project_id": "north/ops",
    "branch": "release+candidate",
    "limit": 25
  }
}

El código de la acción debe validar project_id como identificador, codificarlo como un segmento de ruta, poner branch en un constructor de consultas, validar limit como un entero dentro del rango permitido y construir la URL a partir de un origen fijo. El modelo no necesita ver un token bearer ni decidir dónde va un ampersand.

Esta separación también evita confusiones de origen. Una cadena que empieza por https://other.example no pertenece a un campo de identificador. Si una acción realmente obtiene una URL proporcionada por el usuario, conviértela en una acción independiente con una lista de permitidos, reglas claras para DNS y redirecciones y una razón documentada. No introduzcas una capacidad de obtención arbitraria mediante un campo llamado callback o file.

Sé prudente con las API que aceptan lenguajes de filtros en parámetros de consulta. Un campo como filter=status:open AND owner:me tiene dos gramáticas: la serialización de la consulta URL y el propio lenguaje de filtros. La codificación de URL mantiene el filtro dentro de un valor de consulta, pero no hace seguro el filtro. Analiza o limita por separado ese lenguaje interno, u ofrece campos de filtro tipados.

Evita poner secretos en las URL. Las cadenas de consulta pueden acabar en registros de acceso, historial del navegador, telemetría e informes de errores. Las credenciales deben ir en el mecanismo de autorización que espera la API. Codificar un token API no hace segura su presencia en una consulta.

La aprobación es útil, pero no puede reparar una solicitud mal formada

La autorización humana y la serialización correcta resuelven problemas distintos. Una aprobación puede confirmar que un proceso reconocido puede usar una credencial. No puede revelar si una secuencia de porcentaje se convertirá en una barra en un router posterior o si un parámetro duplicado cambiará los privilegios después del análisis.

Pon comprobaciones deterministas antes de que la llamada llegue a una superficie de aprobación:

• Acepta campos estructurados en lugar de un destino de solicitud ya ensamblado.
• Fija el origen, el método y la plantilla de ruta en la definición de la acción.
• Serializa cada segmento de ruta y cada valor de consulta una sola vez.
• Rechaza campos duplicados o mal formados que el endpoint no defina.
• Prueba el destino final a través del recorrido desplegado.

Sallyport puede mantener las credenciales fuera de un agente compatible con MCP y exigir autorización para un proceso de agente o para cada uso de una credencial seleccionada. Ese control humano funciona mejor cuando la capa de acciones ya produce una solicitud inequívoca.

Los registros también necesitan ambos niveles de detalle. Registra la acción aprobada y sus argumentos seguros, y conserva una representación redactada del destino real y del resultado HTTP. Si un servicio tiene un campo de consulta sensible, redacta su valor, pero conserva el nombre del parámetro y suficiente estructura para diagnosticar duplicaciones accidentales. Nunca registres los encabezados de autorización solo porque una solicitud haya fallado.

La normalización de rutas puede neutralizar a un cliente correcto

Una solicitud perfectamente serializada puede cambiar en los límites de la infraestructura. Los proxies, balanceadores, firewalls de aplicaciones y servidores tienen sus propias reglas para barras duplicadas, segmentos de puntos, separadores codificados y escapes inválidos. Necesitas un contrato de ruta para toda la cadena.

Supón que el cliente envía esta ruta:

/files/reports%2F2025%2Fnotes

Si la API espera un único ID de archivo opaco, el parámetro deseado es reports/2025/notes. Pero un proxy que descodifica antes de reenviar puede enviar /files/reports/2025/notes. Un router configurado para /files/:id puede rechazarlo. Otro puede coincidir con /files/:folder/:year/:name y llamar a un handler distinto. Ningún resultado demuestra por sí solo que el codificador del cliente fallara.

Toma una decisión para cada ruta sensible. Puedes rechazar las barras codificadas en el borde y documentar que los ID no pueden contener barras. Puedes conservarlas hasta el handler y probar esa propiedad. También puedes rediseñar el endpoint para que los datos opacos vivan fuera de la ruta. Lo que no debes hacer es dejar el comportamiento en manos de valores predeterminados dependientes de la versión y tratarlo como un límite de seguridad.

Vigila también las redirecciones. Los clientes HTTP pueden seguirlas automáticamente, y una URL redirigida puede llevar una ruta o una consulta normalizada de otra manera. En acciones con credenciales, define si se permiten redirecciones, si el origen de destino debe coincidir y si los encabezados de autorización se eliminan al cambiar de origen.

Si operas varios servicios, prueba deliberadamente sus desacuerdos. Envía la misma ruta codificada a través del borde y directamente a la aplicación en un entorno no productivo. Si los valores de ruta analizados difieren, corrígelo antes de dar acceso al agente. Un analizador dividido es un problema operativo incluso si ningún atacante lo aprovecha.

Una suite de regresión debe conservar el significado que pretendías

El objetivo de las pruebas de URL no es imponer una escritura de escape concreta. Es conservar la relación entre los argumentos de la acción y el significado que el servidor da a la solicitud mientras cambian las bibliotecas y la infraestructura.

Escribe aserciones en tres capas. Las pruebas unitarias deben verificar que el codificador convierte a/b en un único segmento codificado y que la serialización conserva & dentro de un valor. Las pruebas de acción deben capturar el método, el origen, la ruta y los pares de consulta exactos enviados a un handler de eco. Las pruebas de integración deben pasar por un borde parecido al de producción y comprobar que el handler recibe la ruta y los parámetros esperados.

Cuando el contrato de una API sea impreciso, escribe la ambigüedad y elimínala. «Admite texto de búsqueda en la URL» no es un contrato. Indica si se acepta un q vacío, si q=a+b significa un signo más o un espacio, si se permiten valores tag repetidos y si %2F está permitido en los ID. Esos detalles dejan de ser incidentales cuando un agente puede generar llamadas a partir de texto humano arbitrario.

No tapes una prueba fallida descodificando la entrada antes. La descodificación temprana suele hacer que el caso parezca normal mientras desplaza la ambigüedad a una capa menos visible. Conserva el texto bruto del usuario como datos hasta que el serializador específico del componente lo gestione. Después inspecciona lo que el receptor analizó realmente.

El diario Activity de Sallyport facilita comparar la llamada aprobada de un agente con el resultado que devolvió, y su cadena de auditoría puede verificarse sin conexión con sp audit verify. Usa ese rastro para investigar una discrepancia, no como sustituto de decidir qué acepta tu endpoint.

La primera prueba que añadiría es muy corriente: un identificador que contenga /, un valor de consulta con + y &, y un signo de porcentaje que deba seguir siendo literal. Si tu acción no puede indicar exactamente qué recibe el servidor para esas entradas, todavía no está lista para aceptar texto proporcionado por usuarios a través de un agente.