Por qué abrimos el código cliente de OpenWAF Verify y qué sigue cerrado

Por qué abrirlo

Un widget de reto es código que se ejecuta dentro de tu página, en los dispositivos de tus visitantes y sobre ellos. Se te pide que confíes en que no saca huellas, no llama a terceros y no ralentiza la página. Pedirlo con código minificado y sin explicar es un mal trato, y las revisiones de privacidad hacen bien en señalarlo.

Verify ya es de primera parte: el edge sirve el script desde el dominio del sitio protegido, bajo /__waf/, y todas sus peticiones vuelven a él. Publicar el código es el paso siguiente. Si el navegador ejecuta algo sobre ti, deberías poder leerlo.

Hay además un motivo práctico: casi todos los fallos están en la integración. Un formulario que se envía antes de que llegue el token, una aplicación de una sola página que pinta el widget dos veces, un backend que nunca comprueba el hostname. Bibliotecas que resuelven eso, con pruebas que cualquiera puede ejecutar, valen más a la vista.

Qué hay en el repositorio

El repositorio es github.com/openwaf-dev/verify:

• El código del navegador. El widget, el worker que resuelve la prueba de trabajo y la página intersticial que el edge muestra en las navegaciones.
• La especificación del protocolo. El formato externo del token, la petición de resolución y sus campos, la petición y la respuesta de siteverify y todos los códigos de error.
• Clientes de siteverify. Go (paquete siteverify), Node y TypeScript (@openwaf/verify) y PHP (openwaf/verify). Se comportan igual: no llaman al servidor con un token vacío o demasiado largo, dan errores tipados si falla el transporte, pueden comprobar el hostname y la acción esperados y nunca dejan el secreto en un error ni en un log.
• Componentes. React (@openwaf/verify-react) y Vue 3 (@openwaf/verify-vue), que cargan el script en modo de renderizado explícito y limpian al desmontarse.
• Ejemplos e integración continua. Aplicaciones pequeñas por lenguaje y pruebas en cada pull request, con llamadas reales usando las claves de prueba.

Qué sigue cerrado y por qué

Hay dos cosas que no están en el repositorio.

La primera es la puntuación de riesgo, en el servidor: cómo pondera el edge lo que sabe de una petición para decidir si un reto lleva una prueba de trabajo más dura, un clic o nada. Ya hemos descrito las grandes clases de información que usa, como la reputación de la red, la coherencia de la petición o el comportamiento en muchas peticiones; no publicamos cómo se ponderan ni se combinan.

La segunda es un módulo de extensión que se ejecuta en la página. Sus comprobaciones contestan sí o no, y el módulo añade un único entero opaco a la petición de resolución; los valores que hay detrás no salen de la página. El widget que sirve el edge es el código abierto más ese módulo: si compilas el repositorio obtienes un widget que funciona, pero no los mismos bytes que servimos. Preferimos decirlo a que alguien lo descubra con un diff.

El motivo es sencillo: una detección publicada es una detección parcheada. Una comprobación con la lógica en GitHub deja de funcionar pronto. El código que hace funcionar el widget o verifica un token no pierde nada por ser público; decidir quién parece automatizado, sí.

La separación también acota lo que puede hacer la parte cerrada: se ejecuta dentro del widget abierto, solo aporta ese entero y este viaja en una petición que puedes inspeccionar. No puede añadir llamadas de red, cookies ni almacenamiento sin que tu navegador lo muestre.

Cómo comprobarlo tú

No hace falta creernos. En cualquier página con el widget:

• Panel de red. Abre las herramientas de desarrollo, filtra por dominio y recarga. Todas las peticiones del widget van al origen de la página, bajo /__waf/; ningún dominio de terceros.
• Almacenamiento. El widget no pone cookies ni usa el almacenamiento local. El token va en un campo oculto del formulario, dentro del contenedor.
• Política de seguridad de contenido. Funciona con default-src 'self', sin scripts en línea ni orígenes externos que permitir.
• La petición de resolución. Compara su cuerpo con la especificación: cada campo está descrito ahí, y el único que no envía el código abierto es el entero de la extensión.
• El código. Lee el widget y el worker, o compílalos y compara su comportamiento con lo que sirve el edge.

La página de código abierto de la documentación detalla estos pasos.

Empezar en cinco minutos

Las claves de prueba funcionan en cualquier dominio con Verify y no gastan nada. La sitekey owk_test_pass siempre genera un token y el secreto ows_test_pass acepta cualquier respuesta no vacía. En la página:

<form method="post" action="/alta">
  <div class="owaf-verify" data-sitekey="owk_test_pass"></div>
  <button>Darme de alta</button>
</form>
<script src="/__waf/challenge/v1/widget.js" async defer></script>

El formulario recibe un campo llamado owaf-verify-response. En el servidor se envía a siteverify una vez. De momento las bibliotecas se instalan desde GitHub; los paquetes de npm y Packagist llegarán pronto. En Node:

npm install https://github.com/openwaf-dev/verify/releases/download/v0.1.0/openwaf-verify-0.1.0.tgz

import { SiteverifyClient } from "@openwaf/verify";
const client = new SiteverifyClient({ secret: process.env.OPENWAF_VERIFY_SECRET });
const result = await client.verify(token, { remoteIp, expectedAction: "signup" });
if (!result.success) return reject(result.errorCodes);

En los demás lenguajes la forma es la misma:

• Go: go get github.com/openwaf-dev/verify/siteverify@v0.1.0
• PHP: añade el repositorio con composer config repositories.openwaf-verify vcs https://github.com/openwaf-dev/verify y después composer require openwaf/verify:^0.1
• React: instala openwaf-verify-react-0.1.0.tgz de la versión v0.1.0 del mismo modo y después usa <Verify siteKey="owk_test_pass" /> con un callback onSuccess que recibe el token

Los tokens son de un solo uso y valen 300 segundos. Si una llamada a siteverify agota el tiempo de espera, repítela con la misma clave de idempotencia: el servidor devuelve la primera respuesta en vez de dar el token por gastado. Antes de producción, cambia las claves de prueba por las tuyas desde el panel. La referencia del widget y la de siteverify explican cada opción y cada código de error.

Por qué Apache-2.0

Todo el repositorio es Apache-2.0. Las bibliotecas acaban en productos ajenos, a menudo comerciales, y una licencia permisiva acorta la revisión legal. Apache-2.0 incluye además una concesión explícita de patentes, algo que importa en código que está en el camino de las peticiones de un negocio, y casi todos los equipos legales ya la tienen aprobada. Puedes hacer un fork, también para apuntar el widget a tu propio verificador.

Contribuir y avisar de vulnerabilidades

Las issues y las pull requests son bienvenidas en GitHub: fallos, integraciones con otros frameworks, accesibilidad, traducciones del widget. Las pruebas corren sin cuenta y las reales solo usan las claves de prueba. Los cambios de protocolo pasan antes por la especificación.

Por favor, no publiques vulnerabilidades en issues abiertas. Escribe a support@openwaf.dev con los detalles; la política de seguridad del repositorio explica qué incluir y qué esperar. Vale también para el servicio y sus partes cerradas.

Abrir el cliente no hace que Verify sea más difícil de saltar, ni lo pretende. Hace que lo que se ejecuta en los dispositivos de tus visitantes se pueda leer, probar y arreglar, y deja la parte que decide quién parece automatizado donde sigue funcionando.

Preguntas frecuentes

Fuentes

• OpenWAF Verify: source code OpenWAF
• Verify open source OpenWAF, 29 oct 2026
• Verify widget OpenWAF
• Siteverify OpenWAF
• Apache License, Version 2.0 The Apache Software Foundation
• Content Security Policy Level 3 W3C