davidgin/web-bot-auth

Verificación de autenticación para bots web (Web Bot Auth)

Esta skill añade verificación de tráfico firmado de agentes a un servicio existente. La parte difícil no es la criptografía; son los pequeños detalles que hacen que una firma signifique menos de lo que aparenta: componentes sin firmar, un nonce reutilizado, una cabecera que desencadena una petición, una URL reconstruida de manera diferente a como la firmó el cliente. El código de referencia y las pruebas aquí codifican esos detalles. Tu trabajo es integrarlos en la pila del usuario sin debilitarlos.

Estado de la especificación: apunta a draft-meunier-web-bot-auth-architecture-05 (un borrador de Internet de IETF, no un estándar) y acepta la Signature-Agent antigua entrecomillada (quoted-string) que muchos agentes desplegados aún envían. Indica al usuario que es un borrador y que puede cambiar.

Flujo de trabajo

1. Encuentra el punto de entrada de la solicitud. Identifica el framework y dónde entran las solicitudes (middleware, manejador de borde, hook de proxy inverso). Observa si el servicio está detrás de un proxy o CDN, porque eso determina cómo reconstruir la URL (consulta references/adapters.md).

2. Decide las decisiones de política con el usuario. Lee references/policy-decisions.md y pregunta sobre cualquier aspecto que no se haya decidido en la conversación: qué operadores incluir en la lista blanca, si exigir vinculación de solicitud y nonces, el almacén de nonces, y qué debe hacer cada resultado. No elijas silenciosamente ajustes estrictos: los ajustes estrictos por defecto rechazan a la mayoría de los agentes desplegados hoy. Tampoco elijas silenciosamente ajustes laxos: di qué dejan abierto.

3. Añade el verificador.

   • Python: copia scripts/web_bot_auth.py en el proyecto sin cambios (mantén su cabecera de licencia), añade cryptography a las dependencias y escribe un adaptador pequeño que construya un Request.
   • Otros lenguajes: transpila scripts/web_bot_auth.py, usando la biblioteca Ed25519 establecida del lenguaje (nunca una hecha a mano), y un analizador de campos estructurados RFC 8941 mantenido si existe. La transpilación no está completa hasta que pase todos los casos en assets/test-vectors.json.

4. Escribe el adaptador con cuidado. Es donde fallan la mayoría de las integraciones. El Request debe llevar el método tal como se envió, la URL absoluta tal como la solicitó el cliente, cada aparición de cabecera y los bytes del cuerpo sin procesar antes del análisis o descompresión. Consulta references/adapters.md para notas específicas de cada framework.

5. Elige el almacén de nonces. Solo en memoria para un solo proceso. Cualquier configuración con más de un worker o nodo necesita un almacén compartido y fuertemente consistente. Consulta references/nonce-stores.md.

6. Asigna los resultados a acciones. Usa la tabla a continuación a menos que el usuario haya decidido otra cosa.

7. Prueba la integración de extremo a extremo. Escribe pruebas a través del framework real (su cliente de pruebas) usando sign_request para producir solicitudes firmadas: una solicitud válida, un cuerpo manipulado, una repetición y una solicitud caducada. Ejecuta también scripts/test_web_bot_auth.py si se copió el archivo.

8. Recomienda un despliegue solo en modo log. Registra outcome, reason, operator, keyid, binds_request y replay_protected para cada solicitud durante un período antes de aplicar ninguna medida.

Resultados

Resultado	Significado	Acción por defecto
unsigned	Sin firma web-bot-auth	Gestión de bots existente / puntuación de riesgo
verified	Firma válida, operador en lista blanca	Admitir como ese agente; aún aplicar autenticación de usuario y límites de velocidad
signed_untrusted	Firma válida, operador conocido pero no en lista blanca	Tratar como sin firmar, opcionalmente con menor riesgo
unknown_operator	Bien formado, pero no hay clave disponible	Tratar como sin firmar; opcionalmente encolar una búsqueda de directorio en segundo plano
invalid	Presente y erróneo	Bloquear. Los clientes legítimos no envían firmas rotas
expired	Fuera de su ventana de tiempo	Bloquear
replay	Nonce ya usado	Bloquear

Result.hostile es true para los últimos tres. Para verified, también verifica dos banderas. Si binds_request es false, la firma no cubre el método, la ruta, la consulta ni el cuerpo. Si replay_protected es false, no había nonce o el almacén no estaba disponible. Un valor predeterminado sensato es admitir solicitudes verificadas con cualquiera de las dos banderas en false solo para métodos seguros (GET, HEAD).

Reglas que son fáciles de romper

Estas reglas existen porque cada una tiene un ataque concreto detrás. Si las restricciones del usuario parecen requerir romper una, explica el riesgo y deja que decida.

• Nunca hagas fetch de un directorio de claves en línea para un operador que no esté en la lista blanca. Signature-Agent está controlado por el atacante, por lo que hacer fetch de lo que nombre es SSRF y permite que cualquiera detenga tu ruta de solicitudes. Haz fetch de operadores desconocidos en un trabajo en segundo plano con safe_fetch_directory, o no lo hagas en absoluto.
• Verifica Content-Digest contra el cuerpo siempre que esté cubierto. Firmar la cabecera no sirve de nada si nadie comprueba que coincida con los bytes recibidos.
• Registra el nonce solo después de que la firma se verifique. De lo contrario, cualquiera puede llenar el almacén o quemar los nonces de un agente legítimo por adelantado.
• Usa un almacén de nonces compartido y atómico entre instancias. Un caché por proceso permite que una repetición caiga en un worker diferente.
• Limita la frescura por created, no solo por expires. Los agentes pueden firmar con expiraciones largas; Policy.max_age mantiene pequeña la ventana de replay y el caché de nonces independientemente.
• Reconstruye la URL que el cliente realmente solicitó. Detrás de un proxy, usa el esquema y el host reenviados solo de proxies en los que confíes. Si te equivocas, las firmas válidas no se verificarán, o una cabecera Host falsificada será confiable.
• Una firma verificada identifica al operador, no al usuario. Mantén la autenticación normal y la autorización por usuario y los límites de velocidad detrás de ella. Nunca permitas que una firma sustituya al consentimiento del usuario en acciones sensibles.
• No apliques comprobaciones de comportamiento humano a agentes verificados. Son automatización por diseño.

Archivos

• scripts/web_bot_auth.py: el verificador, resolvedores de claves, almacenes de nonces y sign_request. Archivo único; depende solo de cryptography.
• scripts/test_web_bot_auth.py: pruebas de casos de ataque más el vector de conformidad del Apéndice B.2.6 de RFC 9421. Ejecutar con python -m unittest -v test_web_bot_auth desde scripts/.
• scripts/generate_vectors.py: regenera assets/test-vectors.json.
• assets/test-vectors.json: vectores neutrales al lenguaje para transpilaciones (solo claves de prueba).
• references/policy-decisions.md: las decisiones a tomar con el usuario, con compensaciones. Leer en el paso 2.
• references/adapters.md: cómo construir Request correctamente en frameworks comunes y detrás de proxies. Leer en el paso 4.
• references/nonce-stores.md: qué almacenes son seguros y cómo dimensionarlos. Leer en el paso 5.