Configuración

Documentación de dhal

Página 2 de 9

Dhal v1 utiliza schemaVersion: "1". El archivo predeterminado es dhal.json, aunque los adaptadores y createDhal() aceptan otro configPath.

Precedencia

La configuración efectiva se construye en este orden:

valores predeterminados incorporados;
archivo indicado por configPath;
sobrescritura config pasada al motor o adaptador.

Los objetos se combinan recursivamente y los arrays se sustituyen.

import { createDhal } from "@rokadhq/dhal";

const protection = createDhal({
  configPath: "dhal.json",
  config: {
    mode: "monitor",
    response: { message: "Solicitud rechazada" }
  }
});

Configuración mínima

json

{
  "schemaVersion": "1",
  "mode": "monitor",
  "trustProxy": false,
  "runtime": {
    "onInternalError": "allow",
    "internalErrorStatusCode": 500,
    "maxInspectionMs": 25,
    "bypass": {
      "enabled": true,
      "paths": ["/health", "/ready"],
      "methods": ["OPTIONS"]
    }
  },
  "rateLimit": {
    "enabled": true,
    "store": "memory",
    "keyBy": ["ip", "route"],
    "default": { "windowSeconds": 60, "max": 120 },
    "routes": {}
  }
}

Secciones principales

Campo	Función
`mode`	Comportamiento global `off`, `monitor`, `block` o `strict`.
`trustProxy`	Confía en cabeceras de reenvío para resolver la IP.
`runtime`	Errores internos, presupuesto de inspección y bypass.
`identity`	Cabeceras de usuario, tenant y clave API.
`ip`	Listas permitidas/bloqueadas y reputación.
`rateLimit`	Límites globales y por ruta.
`rules`	Firmas, bots, payload, API, cabeceras y credenciales.
`routes`	Sobrescrituras por ruta.
`policy`	Severidad, supresiones, muestreo y requisitos CI.
`observability`	Redacción, eventos, OTel y webhooks.
`response`	Estado y mensaje de bloqueo.

Seguridad de ejecución

Usa onInternalError: "allow" durante la adopción inicial cuando la disponibilidad sea prioritaria. Usa comportamiento fail-closed solo después de validar dependencias y fallos.

Mantén los bypass limitados a endpoints que no procesen entrada no confiable.

Activa trustProxy únicamente cuando un proxy confiable sobrescriba las cabeceras de reenvío y el acceso directo a la aplicación esté bloqueado. Una configuración incorrecta permite falsificar la IP usada por límites, reputación y auditoría.

Secretos

Los campos como apiKeyEnv y secretEnv contienen nombres de variables de entorno, no secretos. Guarda las credenciales en variables de entorno o un gestor de secretos.

Validación

bash

npx dhal test-config
npx dhal migrate --check

El esquema JSON también está disponible como @rokadhq/dhal/dhal.schema.json y mediante getDhalConfigJsonSchema().