Introducing Dhal

Abstract

Modern API systems are not protected by a single boundary. A production SaaS product may sit behind a CDN, a reverse proxy, an API gateway, an authentication layer, application middleware, database policy, observability pipelines, and incident-response systems. Each layer sees part of the truth. The edge sees traffic volume and network origin. The authentication layer sees identity. The application sees routes, request bodies, tenants, API keys, response outcomes, business flow, and failure patterns.

Dhal was built for the part of security that only the application can see.

Dhal is an open-source, application-native web application firewall and request-security middleware for Node.js. It runs inside the request path and provides deterministic, route-aware controls for Express, Fastify, NestJS, Koa, Hono on Node.js, and raw node:http applications. It complements CDN, edge, network, authentication, authorization, validation, and infrastructure controls. It does not replace volumetric DDoS protection, application-specific authorization, secure coding, or operational monitoring.

This journal explains why we built Dhal, the gaps it fills, the research assumptions behind its design, and the future we have in mind for application-native request protection.

Why we built Dhal

Rokad works on production software systems where the security problem is rarely isolated to one obvious vulnerability. The recurring pattern is more practical: a team has reasonable infrastructure, uses a major framework, has authentication, deploys behind a CDN or proxy, and still lacks a clear way to express request-layer policy inside the application.

That gap becomes visible during routine engineering questions:

• Should the login route have a different rate limit from the public content route?
• Should repeated authentication failures change how future requests are evaluated?
• Should a suspicious user agent be blocked globally, only on internal routes, or merely recorded?
• Should a JSON API reject unexpected content types and payload shapes before route logic runs?
• Should a policy change start in monitor mode and become blocking only after replay testing?
• Should route-specific decisions produce structured telemetry without exposing sensitive fields?
• Should horizontally scaled instances share rate-limit counters and security signals?
• Should security configuration be reviewable in Git, testable in CI, and explainable to operators?

These are not exotic enterprise-only problems. They appear in small SaaS applications, internal dashboards, public APIs, AI products, marketplace systems, developer platforms, and agency-built client software. The application layer often knows enough to make a better decision, but the decision is scattered across ad hoc middleware, route handlers, reverse-proxy snippets, copied rate-limit helpers, framework-specific plugins, and incident-driven patches.

Dhal began as a response to that fragmentation.

We did not want a package that only adds a few attack signatures. We wanted a request-security layer that treats configuration as a production artifact: explicit, versioned, observable, replayable, and safe to roll out gradually. The result is a package that starts in monitor mode, supports route profiles, exposes diagnostics, integrates with distributed stores, emits structured events, and defines a stable v1 contract for applications that need predictable behavior.

The core thesis: the edge cannot see everything

Edge controls are essential. A CDN, reverse proxy, cloud WAF, network firewall, rate-limit gateway, and DDoS provider can filter enormous amounts of unwanted traffic before the application spends CPU cycles. They are the correct place for many network-scale controls.

But edge systems usually do not have full application semantics. They may not know whether /api/login is a password endpoint, whether /api/invoices/:id belongs to a tenant, whether a request failed authentication five times in the last minute, whether a user is anonymous or internal, whether a payload has already been parsed by framework middleware, or whether a route has deliberately chosen a stricter mode than the rest of the application.

The distinction matters because API abuse is frequently contextual. OWASP's API Security Top 10 includes risks such as broken authentication, unrestricted resource consumption, unrestricted access to sensitive business flows, server-side request forgery, and security misconfiguration. These risks do not map cleanly to a single IP-address rule or a static signature list. OWASP's Automated Threats project also classifies abuse patterns such as credential stuffing, vulnerability scanning, scraping, token cracking, carding, scalping, and denial of inventory as automated misuse of web application functionality rather than only exploitation of one implementation bug.

Dhal's thesis is straightforward: keep edge security, but add an application-native layer that can use application context.

That is why Dhal runs where routes, identities, request bodies, response outcomes, and deployment context are available. This placement allows a Node.js application to express policies that are closer to the shape of the actual system.

The gap Dhal fills

Dhal is not trying to replace every security product. It fills a specific gap between infrastructure controls and application code.

1. Route-aware policy

Many API security decisions are route-specific. A public marketing endpoint, a login endpoint, a webhook receiver, a file upload route, an internal admin API, and a GraphQL endpoint do not carry the same risk. Treating them with one global policy either becomes too weak for high-risk routes or too noisy for normal traffic.

Dhal introduces route profiles: modes, limits, rules, responses, tags, suppressions, and positive-security controls can be configured per route. The same application can run globally in monitor mode while selected authentication routes run in block mode after review.

2. Monitor-first rollout

Security controls fail when they are enabled with too much confidence and too little evidence. False positives are not only inconvenient; they can become availability incidents. For this reason, Dhal's rollout model begins with observation.

In monitor mode, Dhal records what it would block while allowing the request to proceed. Teams can review wouldBlock events, replay known-good and malicious traffic, tune suppressions, and then enable blocking route by route. This mirrors how production teams actually reduce risk: measure first, enforce after review.

3. Distributed state for real deployments

In a single-process demo, memory counters may be enough. In a real deployment, several Node.js instances often serve the same API. Rate limits, credential-stuffing signals, and reputation outcomes become weak if each instance sees only a fragment of the request stream.

Dhal supports Redis or Valkey for shared counters and security signals. It also refuses to start an enforcing deployment that declares Redis-backed rate limiting without receiving a distributed rate-limit store. That refusal is intentional. A security package should not silently degrade into a misleading posture.

4. Behavior-aware request protection

Signature checks are useful, but modern abuse is often behavioral. Credential stuffing is not detected by one suspicious payload. It appears through repeated authentication outcomes. Bot activity is not always a single user-agent string; it may require scoring, multiple signals, and explicit false-positive controls.

Dhal combines rule categories such as SQL injection, XSS, path traversal, SSRF, RCE, SSTI, GraphQL probes, bot scoring, honeypots, credential-stuffing detection, content-type validation, header checks, payload-size limits, and route-level policy. The aim is not to claim perfect attack detection. The aim is to provide a coherent decision surface that a production team can reason about.

5. Observable, privacy-conscious decisions

A security decision is incomplete if operators cannot explain it. But security telemetry can also create privacy risk if it captures too much. Dhal therefore includes structured events, OpenTelemetry support, signed webhooks, and redaction controls for fields such as IP address, identity, and user agent.

The intended output is not a noisy dump of sensitive request data. The intended output is an operational record: what decision was made, why it was made, which rule contributed, what route was affected, and how the team can reproduce or tune the behavior.

6. Reviewable automation

Dhal includes guided onboarding through commands such as dhal add, diagnostics through dhal doctor, readiness scoring through dhal readiness --production, and OpenAPI inspection and policy generation. The design constraint is that generated security configuration should remain reviewable.

Generated route policies remain in monitor mode. Existing owner-managed route profiles are preserved. Dhal does not patch application source automatically without explicit write commands. This keeps automation useful without turning it into invisible enforcement.

Research assumptions behind the design

Dhal's design rests on several assumptions about production systems.

First, security policy needs locality. The closer a policy is to the behavior it protects, the easier it is to test, review, and maintain. Route-aware configuration belongs near the application because the application owns route semantics.

Second, production safety is a security property. A request-security layer that regularly breaks valid users will be bypassed or removed. Monitor mode, replay, suppressions, health bypasses, internal-error behavior, and bounded telemetry are not convenience features; they are mechanisms for keeping security deployable.

Third, security tools should be explicit about their boundary. Dhal runs inside the Node.js process. It cannot stop bandwidth exhaustion, TLS-handshake exhaustion, kernel/socket exhaustion, or traffic that never reaches the application. Its role is application-layer request evaluation, not infrastructure survival.

Fourth, open-source security infrastructure must be inspectable. The policy format, CLI behavior, release artifacts, compatibility matrix, and v1 contract should be visible. Dhal's stable package, CLI, schema version, framework adapters, stores, telemetry integrations, and compatibility inventory are part of that inspectability.

Fifth, security configuration is engineering code. It should be stored, diffed, migrated, tested, explained, and reviewed. A dhal.json file is not just a settings file; it is a policy artifact.

What Dhal includes today

Dhal v1.1.0 provides a stable app-native WAF for Node.js with route-aware protection, distributed controls, runtime safety, production diagnostics, and a frozen v1 contract.

The current surface includes:

• framework adapters for Express, Fastify, NestJS, Koa, Hono on Node.js, and raw node:http;
• IP allowlists, blocklists, IPv4 and IPv6 CIDR matching, and optional reputation checks;
• Redis and Valkey support for distributed rate limiting and shared security signals;
• built-in rule coverage for common injection probes, traversal attempts, SSRF, RCE, SSTI, GraphQL probes, automation, bot scoring, honeypots, and credential-stuffing behavior;
• JSON API positive-security controls for content type, headers, payload size, and route-specific expectations;
• route-level modes, limits, rule configuration, responses, tags, and suppressions;
• OpenTelemetry, structured events, signed webhook telemetry, and privacy-aware redaction;
• guided onboarding, conservative configuration repair, framework presets, and OpenAPI policy generation;
• CLI workflows for initialization, config testing, diagnostics, migration checks, readiness, compatibility, stability, replay, simulation, reports, and release checks;
• stable ESM, CommonJS, TypeScript, CLI, and dhal.json schema contracts.

This combination is important. The value is not only in any single rule. The value is in the policy lifecycle: generate carefully, start in monitor mode, observe, replay, tune, enforce narrowly, expand gradually, and keep the system explainable.

What Dhal deliberately does not do

A serious security tool should state its non-goals.

Dhal does not replace authentication. It can use trusted identity values to improve rate limiting, signals, telemetry, suppressions, and route policy, but it does not decide whether a user is allowed to access a specific business object.

Dhal does not replace authorization. Broken object-level authorization and broken function-level authorization must be addressed in application logic, domain policy, or a dedicated authorization layer.

Dhal does not replace validation. Application schemas, type checks, input constraints, and domain validation remain necessary.

Dhal does not replace DDoS protection. Because it runs after traffic reaches the Node.js process, it cannot absorb volumetric attacks before application execution.

Dhal does not replace secure development practice. It helps inspect, score, limit, observe, and block requests, but it cannot make unsafe code safe by itself.

This boundary is not a weakness. It is the condition for correct use.

The future we have in mind

Dhal's long-term direction is application-native security infrastructure for modern JavaScript and TypeScript systems. That means broadening coverage while preserving a small number of commitments: deterministic behavior, monitor-first rollout, explicit boundaries, privacy-aware telemetry, and reviewable policy.

Broader runtime and framework coverage

The Node.js ecosystem is no longer only Express and Fastify. Production applications increasingly use meta-frameworks, server functions, fetch-style handlers, file-based routing, edge-adjacent runtimes, and mixed deployment targets. Dhal's future framework work will focus on making request protection easier to adopt across those surfaces without losing clarity about runtime support.

The important principle is not to chase every framework name. The important principle is to make the protection boundary explicit: where does Dhal inspect, what request object does it receive, what response outcome can it observe, what state can it share, and what modes are safe in that runtime?

Better policy generation from application descriptions

OpenAPI policy generation is an early step toward a larger idea: security configuration should be derived from real application structure, but never blindly enforced. Future work should improve route classification, schema-aware positive security, generated suppressions, owner-managed overrides, and confidence annotations.

The goal is not one-click magic. The goal is to reduce the blank-page problem while leaving the final policy reviewable by engineers.

Deception and abuse-resistance patterns

Application-native security can do more than block obvious probes. It can create low-risk signals that help identify automation. Honeypot headers, routes, parameters, and deceptive paths are early examples. Future versions can expand this into more structured deception controls for bots, scanners, credential attacks, token enumeration, and suspicious business-flow automation.

These controls must remain conservative. Deception is useful only when it improves signal quality without harming legitimate users or making the system unpredictable.

Form and business-flow protection

Many damaging attacks are not classic injection attacks. They target forms, login flows, signup flows, reset flows, checkout flows, referral flows, voucher flows, waitlists, and inventory flows. OWASP's automated-threat taxonomy is useful here because it describes misuse of valid functionality, not only technical exploit strings.

A future Dhal should make it easier to protect high-abuse flows while keeping business logic in the application. That may include form shields, token controls, attempt sequencing, flow-level rate limits, and route groups that model a user journey rather than a single endpoint.

Operational intelligence without hidden telemetry

Dhal should continue to avoid hidden package telemetry. Security tools require trust. But production teams still need better local and owner-controlled intelligence: richer reports, safer redaction, deployment posture scoring, replay analysis, false-positive summaries, and policy-drift detection.

The future direction is owner-controlled insight, not silent data extraction.

Commercial support without weakening open source

Dhal is open source. Its usefulness should not depend on a sales conversation. At the same time, production security work often needs careful implementation: route analysis, Redis or Valkey deployment, observability setup, CI integration, replay fixtures, policy tuning, and gradual block-mode rollout.

Rokad can support teams that want help deploying Dhal or improving Node.js API security more broadly. That support should amplify the open-source project rather than restrict it.

Conclusion

Dhal exists because modern APIs need a security layer that understands more than IP addresses and static signatures. The application has context that the edge usually lacks: routes, identities, bodies, response outcomes, tenants, API keys, deployment assumptions, and business-flow semantics. That context should be usable without burying security logic across scattered middleware and incident-driven patches.

The correct model is not edge security or application-native security. It is both.

Dhal's role is to make application-layer request protection explicit, observable, testable, and safe to deploy. Its first stable releases focus on Node.js because the ecosystem is large, diverse, and operationally fragmented. The future is broader: more frameworks, better policy generation, safer business-flow protection, stronger diagnostics, and an open-source foundation that production teams can inspect and extend.

Dhal is therefore more than a package release. It is Rokad's position on how request security should be built: close to the application, honest about its boundary, conservative in rollout, and accountable in production.

References

• Dhal repository: https://github.com/rokadhq/dhal
• Dhal npm package: https://www.npmjs.com/package/@rokadhq/dhal
• Dhal documentation: https://rokad.co/en/docs/dhal
• Dhal product page: https://rokad.co/en/open-source/dhal
• OWASP API Security Top 10 2023: https://owasp.org/API-Security/editions/2023/en/0x00-header/
• OWASP Automated Threats to Web Applications: https://owasp.org/www-project-automated-threats-to-web-applications/
• NIST SP 800-53 Rev. 5: https://csrc.nist.gov/pubs/sp/800/53/r5/upd1/final