Importante

Esta documentación solo es válida para el caso de usar tecnología de bordes, ya sea "Evento Único" o "Protección Automática".

En el caso del modo "Legacy" la seguridad queda delegada al cliente. Recomendamos el uso de sessions, o en caso de cookies, que no puedan ser facilmente manipuladas por los usuarios, y/o compartidas en redes sociales reforzandolas con firmas digitales.

Seguridad y control de acceso

Virtual Queue aplica el control de acceso en el borde de la red mediante workers que interceptan cada request al dominio del cliente antes de que llegue a su servidor de origen. Esto significa que ningún visitante puede saltarse la fila modificando variables en su navegador: la decisión de permitir o redirigir se toma siempre del lado servidor, con datos firmados criptográficamente.

Variables que controlan el acceso a la fila

User ID y sesión persistente

Cuando un usuario ingresa por primera vez a Virtual Queue, el sistema genera un identificador único de sesión y lo guarda en el navegador como cookie. Esto permite que, si el usuario cierra el navegador y lo vuelve a abrir, su posición en la fila se mantenga sin tener que volver a hacer la cola desde cero.

La cookie está marcada con los flags HttpOnly, SameSite=Lax y Secure (sobre HTTPS), lo que impide su lectura desde JavaScript del lado cliente y mitiga ataques de XSS y CSRF.

User status (actividad)

El sistema detecta en todo momento si el usuario sigue conectado o se desconectó, especialmente en el momento crítico en que termina la fila y pasa a la página de compra. Si el usuario deja de estar activo, su turno tiene un período de gracia configurable hasta caducar. Si ese valor se configura en cero, el turno caduca de forma inmediata cuando el usuario abandona la sesión.

Token de un solo uso

Cada posición en la fila está identificada con un token único e irrepetible. Cuando el usuario completa la espera y es habilitado para acceder al sitio, el worker del edge verifica este token contra la API de Virtual Queue (/api/v1/queue/verify).

Características de seguridad del token:

• Un solo uso: una vez consumido, queda invalidado del lado servidor. Si un usuario compartiera la URL con su token (vía chat, email, redes), cualquier otro visitante recibiría una denegación y sería enviado nuevamente a la fila.
• Verificación centralizada: la validación se realiza siempre contra la API; el edge nunca confía en el valor del token sin contrastarlo.
• Binding a cliente: tras la verificación exitosa, el edge emite una cookie firmada (queue_verified) ligada al User-Agent del navegador que originó la solicitud. Si se copia la cookie a otro dispositivo o navegador, el binding falla y el acceso es rechazado.

Cookie firmada (queue_verified)

Una vez verificado el token, el worker emite una cookie firmada con HMAC-SHA256 usando un secreto que solo conoce la infraestructura del edge (JWT_SECRET). El payload contiene:

Campo	Descripción
t	Token original validado
exp	Timestamp de expiración (10 minutos por defecto)
dom	Dominio para el que se emitió la cookie
ck	Client key (User-Agent) al que queda ligada

En cada request posterior, el edge:

1. Recalcula la firma HMAC y la compara con la enviada.
2. Verifica que la cookie no esté expirada.
3. Comprueba que dom coincida con el dominio actual.
4. Comprueba que ck coincida con el User-Agent del request.

Cualquier alteración del payload invalida la firma y el usuario es enviado a la fila.

Intento de modificación de variables del lado cliente

Las variables operativas de la aplicación —posición en la fila, recorrido individual, cantidad total de usuarios, token de habilitación, identificador de sesión y estado del evento— se almacenan y se evalúan exclusivamente del lado servidor. El navegador del usuario sólo recibe cookies firmadas que no contienen información sensible ni modificable: cualquier intento de editarlas, copiarlas a otro equipo o reproducirlas fuera de su contexto original es detectado por la verificación HMAC en el edge.

Enforcement en el edge (Cloudflare Workers)

El control de acceso se ejecuta como una capa transparente delante del sitio del cliente. Esto aporta varias propiedades de seguridad:

• Imposible de saltear desde el cliente: el worker se interpone físicamente entre el visitante y el origen. No existe un endpoint alternativo al que ir.
• ACLs evaluadas por prioridad: las reglas se aplican ordenadas por prioridad descendente y la primera que matchea decide la acción (bypass o redirect_to_queue). Soporta patrones prefix, exact, contains y glob.
• Aislamiento por dominio: cada dominio cliente tiene su propio conjunto de reglas, identificado por el header CF-Original-Host (compatible con Cloudflare for SaaS).
• Autenticación worker → API: el worker se autentica contra la API de Virtual Queue con un Bearer token (EDGE_INGRESS_TOKEN) provisto vía Wrangler secrets, nunca embebido en el código.
• Bypass selectivo seguro: assets estáticos (CSS, JS, imágenes, fuentes), rutas /api/, endpoints de framework y conexiones WebSocket pasan sin overhead, pero todas las rutas navegables son evaluadas.

Rate limiting y activación dinámica (sólo edge_forwarder)

La versión completa del edge incorpora un Durable Object (RateLimiter) que mide el tráfico real mediante un promedio móvil exponencial (EMA) con bandas de histéresis del 10 %. Esto evita activaciones y desactivaciones oscilantes de la fila ante picos cortos.

• La activación de la fila requiere permiso explícito de la API (traffic_light endpoint). El edge no puede unilateralmente decidir abrir o cerrar el portal.
• La desactivación sigue el mismo principio: aunque el tráfico esté por debajo del umbral, el edge consulta a la API antes de dejar pasar tráfico sin restricción.
• El estado del evento (active / inactive) persiste en el Durable Object, lo que garantiza una vista consistente del estado del evento entre todos los requests, incluso bajo carga.
• En caso de fallo de comunicación con la API, el edge aplica una política fail-closed para desactivación (mantiene la fila activa por defecto), priorizando la integridad del control sobre la disponibilidad.

Resumen del modelo de confianza

Componente	Quién confía en quién
Navegador del usuario	No se confía en nada de lo que envía salvo cookies con firma HMAC válida
Edge Worker → API VQueue	Autenticación con Bearer token vía secret de Wrangler
Cookie queue_verified	Firmada con HMAC-SHA256; ligada a dominio + User-Agent + expiración
Token de fila	Validado contra API en cada emisión; un solo uso
Estado del evento	Único origen de verdad: API + Durable Object, nunca el cliente