Widget OpenWAF VerifyNuevo

OpenWAF Verify es un widget que insertas en un formulario. El navegador del visitante resuelve una prueba de trabajo breve y obtiene un token de un solo uso; tu servidor envía ese token a siteverify antes de aceptar el formulario. Usa el mismo motor que el reto de navegador.

Todo es de primera parte: el script, su worker y sus endpoints los sirve el borde de OpenWAF bajo /__waf/ en tu propio nombre con proxy. No hay iframe de terceros ni cookie de terceros, y el widget funciona con Content-Security-Policy: default-src 'self' (sin script ni estilo en línea, sin eval, sin blob:).

Demo en vivo: developers.openwaf.dev/demo/verify/ ejecuta este widget en este mismo sitio, detrás del borde de OpenWAF, con default-src 'self'.

El nombre que muestra el widget tiene que pasar por el proxy de OpenWAF.

#Cómo funciona

#Crear un widget

Un widget tiene un nombre (1–64 caracteres), un modo y de 1 a 10 nombres de la zona (el ápice o nombres bajo él, sin comodines) donde se puede mostrar. Una zona puede tener hasta 20 widgets.

openwaf-cloud ctl challenge widget-add example.com --name "Formulario de alta" --mode managed \
  --hostname example.com --hostname www.example.com --reason "Proteger el alta"

curl -s -X POST https://dash.openwaf.dev/v1/orgs/$ORG/zones/$ZONE/challenge/widgets \
  -H "Authorization: Bearer $OPENWAF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Formulario de alta", "mode": "managed", "hostnames": ["example.com", "www.example.com"], "reason": "Proteger el alta"}'

#Añadirlo a tu página

<script src="/__waf/challenge/v1/widget.js" async defer></script>

<form action="/signup" method="post">
  <input name="email" type="email" required>
  <div class="owaf-verify" data-sitekey="owk_TU_SITE_KEY" data-action="signup"></div>
  <button type="submit">Darme de alta</button>
</form>

El script busca todos los elementos .owaf-verify y muestra un widget en cada uno. Cuando el navegador ha resuelto el reto, el contenedor tiene <input type="hidden" name="owaf-verify-response" value="v1.…">, que el formulario envía con el resto de campos.

#API de JavaScript

Carga el script con ?render=explicit para mostrar tú los widgets, y con onload=<función> para que te avise cuando esté listo:

<script src="/__waf/challenge/v1/widget.js?render=explicit&onload=onVerifyReady" async defer></script>

function onVerifyReady() {
  const id = window.owafVerify.render("#verify", {
    sitekey: "owk_TU_SITE_KEY",
    action: "login",
    callback: (token) => console.log("listo"),
  });
}

#Modos

En esta versión la única señal que pide interacción es navigator.webdriver. Las señales de riesgo del lado del servidor llegarán en una versión posterior. La línea de estado es una región viva que leen los lectores de pantalla, y la caja se alcanza con el teclado.

#Tokens

• Un token empieza por v1., tiene como mucho 2048 caracteres y vale 300 segundos.
• Es de un solo uso: la primera llamada a siteverify lo gasta en todos los nodos de borde y en el plano de control; una segunda recibe timeout-or-duplicate.
• Va ligado a la red del visitante (/24 IPv4, /64 IPv6) y lleva el nombre del host, la acción y el cdata.

#Comprobar el token en tu servidor

Envía el token a siteverify desde tu servidor, nunca desde el navegador. Puedes llamarlo en tu propio host, a través del borde, o en el plano de control:

curl -s https://example.com/__waf/challenge/siteverify \
  -d secret="$OWAF_VERIFY_SECRET" \
  -d response="$TOKEN" \
  -d remoteip="203.0.113.7"

{"success": true, "challenge_ts": "2026-10-28T10:15:03Z", "hostname": "example.com",
 "action": "signup", "error-codes": [], "metadata": {"mode": "managed", "interactive": false, "risk": "low"}}

Comprueba success, después hostname y action. Los campos, los códigos de error, los límites y la idempotencia están en la referencia de siteverify.

#Ejemplos

export async function POST(req: Request) {
  const form = await req.formData();
  const res = await fetch("https://dash.openwaf.dev/v1/challenge/siteverify", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      secret: process.env.OWAF_VERIFY_SECRET,
      response: form.get("owaf-verify-response"),
      remoteip: req.headers.get("x-forwarded-for")?.split(",")[0]?.trim(),
    }),
  });
  const result = await res.json();
  if (!result.success || result.action !== "signup") {
    return Response.json({ error: "verification failed" }, { status: 403 });
  }
  // crear la cuenta
  return Response.json({ ok: true });
}

<?php
$ch = curl_init('https://dash.openwaf.dev/v1/challenge/siteverify');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'secret'   => getenv('OWAF_VERIFY_SECRET'),
        'response' => $_POST['owaf-verify-response'] ?? '',
        'remoteip' => $_SERVER['REMOTE_ADDR'],
    ]),
]);
$result = json_decode(curl_exec($ch), true);
if (empty($result['success']) || $result['action'] !== 'signup') {
    http_response_code(403);
    exit('Verificación fallida');
}
// crear la cuenta

curl -s https://dash.openwaf.dev/v1/challenge/siteverify \
  -H "Content-Type: application/json" \
  -d '{"secret": "ows_test_pass", "response": "v1.TEST.TOKEN"}'

Detrás del borde de OpenWAF, la dirección de cliente que tu origen ve en REMOTE_ADDR es la del borde; toma la del visitante de la cabecera en la que confía tu origen, o no envíes remoteip.

#Claves de prueba

Estas claves funcionan en cualquier host con OpenWAF Verify y en los dos endpoints de siteverify. Nunca gastan un contador ni producen un token real.

#Gestionar widgets

Leer necesita un token readonly; los cambios necesitan tech y un motivo. Los widgets no forman parte de la configuración versionada de la zona: los cambios quedan en el registro de auditoría de la organización (challenge.widget.create, update, delete, rotate_secret), nunca con el secreto, y revertir una versión de la zona no los toca. Toda escritura acepta ?dry_run=1.

#Rotar el secreto

Rotar devuelve un secreto nuevo una sola vez. El secreto anterior sigue valiendo 24 horas, para que despliegues el nuevo sin verificaciones fallidas. Tras una segunda rotación dentro de esas 24 horas, solo valen los dos secretos más recientes.

#Migrar desde Cloudflare Turnstile

Los campos de siteverify y la mayoría de códigos de error se llaman igual, así que migrar es sobre todo renombrar:

Después, quita challenges.cloudflare.com de tu Content Security Policy: no se carga nada de otro origen.

#Datos tratados

El widget está hecho para comprobar que un navegador hizo el trabajo, no para identificar a la persona:

• Prefijo de red. El borde usa la /24 IPv4 o la /64 IPv6 del visitante para ligar el reto y el token. Se mantiene en memoria y en el token solo entra un hash.
• navigator.webdriver. Si el navegador dice que está automatizado.
• Interacción. Si hubo interacción con la página antes de la comprobación: solo sí o no, nunca movimientos ni teclas.
• Sin huella digital. Sin canvas, WebGL, audio, fuentes, plugins ni client hints de alta entropía, y sin identificador persistente.
• Sin cookies. El widget no pone ninguna cookie ni hace peticiones a otro dominio.
• Dónde. Los retos y los tokens se emiten en nodos de borde de OpenWAF en la UE (Alemania y España).

Las respuestas de siteverify nunca incluyen estas señales. Los recuentos agregados (retos emitidos, resueltos, fallidos; resultados de siteverify) aparecen en la analítica de tu zona.