Bien démarrer

Dhal est un pare-feu applicatif web et une couche de sécurité des requêtes natifs pour Node.js. La version 1.1 prend en charge Express, Fastify, NestJS, Koa, Hono sur Node.js et les serveurs node:http.

Dhal complète les contrôles CDN, périphériques, réseau, d’authentification, d’autorisation et de validation. Il ne remplace pas la protection DDoS volumétrique ni la sécurité de l’infrastructure.

Prérequis

• Node.js 20 ou version ultérieure
• Un gestionnaire de paquets moderne compatible avec npm
• Redis ou Valkey pour les compteurs partagés lorsque plusieurs instances protègent les mêmes routes

Installation

npm install @rokadhq/dhal

Le paquet est @rokadhq/dhal, la commande CLI est dhal et le fichier de configuration par défaut est dhal.json.

Recommandé : intégration guidée

Exécutez dhal add depuis la racine de l’application :

npx dhal add

La commande par défaut est en lecture seule. Elle détecte le framework et le gestionnaire de paquets, prévisualise une configuration en mode surveillance, génère un module d’intégration révisable et affiche les instructions exactes d’enregistrement.

Après vérification du plan, créez les fichiers proposés :

npx dhal add --write

Dhal ne modifie pas automatiquement le code source existant. Les fichiers existants ne sont pas écrasés sans --force.

Pour une application node:http, sélectionnez explicitement le framework :

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

Configuration manuelle

Vous pouvez toujours créer la configuration générique :

npx dhal init

La configuration démarre en mode monitor et enregistre les décisions potentielles sans rejeter le trafic.

Points d’entrée des frameworks

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);

Installez Dhal après la création de l’application Nest et avant app.listen(). L’adaptateur détecte Express ou Fastify.

Koa

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

Enregistrez Dhal avant les routes et les middlewares qui ne doivent s’exécuter qu’après inspection.

Hono sur Node.js

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

L’adaptateur Hono utilise les objets Web Request et Response standard et est pris en charge sur le runtime Node.js.

node:http

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

Consultez le chapitre des intégrations pour les exemples complets de cycle de vie et d’identité.

Valider et réparer avant l’application

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

doctor --fix applique uniquement des réparations mécaniques prudentes. Il peut créer une configuration de surveillance manquante ou migrer une configuration compatible avec sauvegarde. Il n’active pas automatiquement le blocage, la confiance proxy, Redis, la télémétrie ou une réputation externe.

Un déploiement sûr consiste à :

1. Déployer globalement en mode monitor.
2. Rejouer du trafic connu et examiner les événements wouldBlock.
3. Activer block uniquement sur certaines routes à haut risque.
4. Valider la latence, les faux positifs et la disponibilité des dépendances.
5. Étendre progressivement l’application.

Modes de fonctionnement

Les profils de route peuvent remplacer le mode global pour permettre une application progressive.