Getting started

Dhal is an app-native web application firewall and request-security layer for Node.js. Version 1.1 supports Express, Fastify, NestJS, Koa, Hono on Node.js, and raw node:http servers.

Dhal complements CDN, edge, network, authentication, authorization, and input-validation controls. It does not replace volumetric DDoS protection or infrastructure security.

Requirements

• Node.js 20 or newer
• A modern npm-compatible package manager
• Redis or Valkey for shared counters when multiple application instances protect the same routes

Install

npm install @rokadhq/dhal

The npm package is @rokadhq/dhal, the CLI command is dhal, and the default configuration file is dhal.json.

Recommended: guided onboarding

Run dhal add from the application root:

npx dhal add

The default command is read-only. It detects the framework and package manager, previews a monitor-mode configuration, generates a reviewable framework integration module, and prints exact registration instructions.

After reviewing the plan, create the proposed files:

npx dhal add --write

Dhal does not patch existing application source automatically. Existing output files are not overwritten unless --force is supplied.

Raw node:http applications can be selected explicitly:

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

Manual configuration

You can still create the generic starter configuration directly:

npx dhal init

The generated configuration starts in monitor mode. Dhal evaluates requests and records what it would block without rejecting traffic.

Framework entrypoints

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

Install Dhal after creating the Nest application and before app.listen(). The adapter detects whether Nest uses Express or Fastify.

Koa

import { dhalKoa } from "@rokadhq/dhal/koa";

app.use(dhalKoa({ configPath: "dhal.json" }));

Register Dhal before application routes and middleware that should only execute after inspection.

Hono on Node.js

import { dhalHono } from "@rokadhq/dhal/hono";

app.use("*", dhalHono({ configPath: "dhal.json" }));

The Hono adapter consumes standard Web Request and Response objects and is supported on the Node.js runtime.

Raw node:http

import { createNodeHttpDhal } from "@rokadhq/dhal/node-http";

const protection = createNodeHttpDhal({ configPath: "dhal.json" });

See the framework integrations chapter for complete lifecycle and identity examples.

Validate and repair before enforcement

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

doctor --fix applies only conservative mechanical repairs. It can create a missing monitor-mode starter file or migrate a compatible configuration with backup support. It does not enable blocking, proxy trust, Redis, telemetry, or external reputation services automatically.

A safe rollout is:

1. Deploy globally in monitor mode.
2. Replay known-good traffic and review wouldBlock events.
3. Enable block only on selected high-risk routes.
4. Validate latency, false positives, and backend availability.
5. Expand enforcement gradually.

Operating modes

Route profiles can override the global mode, allowing gradual enforcement without changing the whole application at once.