Primeros pasos

Dhal es un firewall de aplicaciones web y una capa de seguridad de solicitudes nativos para Node.js. La versión 1.1 admite Express, Fastify, NestJS, Koa, Hono sobre Node.js y servidores node:http.

Dhal complementa los controles de CDN, perímetro, red, autenticación, autorización y validación. No sustituye la protección DDoS volumétrica ni la seguridad de infraestructura.

Requisitos

• Node.js 20 o posterior
• Un gestor de paquetes moderno compatible con npm
• Redis o Valkey para contadores compartidos cuando varias instancias protegen las mismas rutas

Instalación

npm install @rokadhq/dhal

El paquete es @rokadhq/dhal, el comando de CLI es dhal y el archivo de configuración predeterminado es dhal.json.

Recomendado: incorporación guiada

Ejecuta dhal add desde la raíz de la aplicación:

npx dhal add

El comando predeterminado es de solo lectura. Detecta el framework y el gestor de paquetes, muestra una configuración en modo de supervisión, genera un módulo de integración revisable e indica los pasos exactos de registro.

Después de revisar el plan, crea los archivos propuestos:

npx dhal add --write

Dhal no modifica automáticamente el código fuente existente. Los archivos existentes no se sobrescriben salvo que se indique --force.

Para aplicaciones node:http, selecciona el framework de forma explícita:

npx dhal add --framework node-http --write

Configuración manual

También puedes crear la configuración inicial genérica:

npx dhal init

La configuración comienza en modo monitor, por lo que Dhal registra lo que bloquearía sin rechazar tráfico.

Puntos de entrada por framework

Express

import { dhal } from "@rokadhq/dhal/express";
app.use(express.json({ limit: "1mb" }));
app.use(dhal({ configPath: "dhal.json" }));

Fastify

import { dhalFastify } from "@rokadhq/dhal/fastify";
await app.register(dhalFastify({ configPath: "dhal.json" }));

NestJS

import { installDhalNest } from "@rokadhq/dhal/nest";
const app = await NestFactory.create(AppModule);
await installDhalNest(app, { configPath: "dhal.json" });
await app.listen(3000);

Instala Dhal después de crear la aplicación Nest y antes de app.listen(). El adaptador detecta Express o Fastify.

Koa

import { dhalKoa } from "@rokadhq/dhal/koa";
app.use(dhalKoa({ configPath: "dhal.json" }));

Registra Dhal antes de las rutas y del middleware que solo deba ejecutarse después de la inspección.

Hono sobre Node.js

import { dhalHono } from "@rokadhq/dhal/hono";
app.use("*", dhalHono({ configPath: "dhal.json" }));

El adaptador Hono usa objetos Web Request y Response estándar y está soportado en el runtime de Node.js.

node:http

import { createNodeHttpDhal } from "@rokadhq/dhal/node-http";
const protection = createNodeHttpDhal({ configPath: "dhal.json" });

Consulta el capítulo de integraciones para ejemplos completos de ciclo de vida e identidad.

Validar y reparar antes de aplicar bloqueo

npx dhal test-config
npx dhal migrate --check
npx dhal doctor
npx dhal doctor --fix --dry-run
npx dhal readiness --production

doctor --fix solo aplica reparaciones mecánicas conservadoras. Puede crear una configuración de supervisión ausente o migrar una configuración compatible con copia de seguridad. No activa automáticamente bloqueo, confianza de proxy, Redis, telemetría ni reputación externa.

Un despliegue seguro consiste en:

1. Desplegar globalmente en modo monitor.
2. Reproducir tráfico conocido y revisar eventos wouldBlock.
3. Activar block solo en rutas seleccionadas de alto riesgo.
4. Validar latencia, falsos positivos y disponibilidad de dependencias.
5. Ampliar la aplicación gradualmente.

Modos de funcionamiento

Los perfiles de ruta pueden sustituir el modo global para habilitar la aplicación gradual.