Host Validation Middleware

0.1.4 · active · verified Wed Apr 22

host-validation-middleware is an npm package providing Connect/Express-compatible middleware designed to protect against DNS rebinding attacks by validating the `Host` header in incoming HTTP requests. The current stable version is 0.1.4, indicating it's still in an early development phase but receives maintenance patches. It differentiates itself by offering flexible host matching, including subdomain wildcard support (e.g., `.mydomain.com`), and automatically allowing `localhost` and IP addresses which are not susceptible to DNS rebinding. While crucial for HTTP development environments, the package explicitly notes that its utility is significantly reduced for HTTPS production sites, as DNS rebinding attacks are generally ineffective against encrypted connections. Its core logic is inspired by the `allowedHosts` option found in `webpack-dev-server`.

Common errors

```
TypeError: (0 , host_validation_middleware_1.hostValidationMiddleware) is not a function
```
cause Attempting to use CommonJS `require()` syntax to import `hostValidationMiddleware` from an ES Module package.

fix Update your import statement to use ES Module syntax: `import { hostValidationMiddleware } from 'host-validation-middleware';` and ensure your Node.js environment supports ES Modules.
```
403 Forbidden (HTTP response)
```
cause The `Host` header of the incoming HTTP request does not match any of the allowed patterns configured in `allowedHosts`.

fix Review the `allowedHosts` array in your `hostValidationMiddleware` configuration. Verify that the requested host (e.g., `mydomain.com`, `sub.mydomain.com`) is correctly listed or covered by a wildcard entry (e.g., `.mydomain.com`). Also, check for typos in the host header being sent by the client.
```
ERR_UNSUPPORTED_DIR_IMPORT
```
cause A CommonJS file is trying to import an ES Module package, and Node.js cannot resolve the module graph correctly due to the mismatch.

fix Either convert the importing file to an ES Module (by adding `"type": "module"` to your `package.json` or changing the file extension to `.mjs`) or refactor to use dynamic `import()` within the CommonJS context if absolutely necessary, though direct ESM conversion is preferred for modern Node.js applications.

Warnings

gotcha DNS rebinding attacks are generally ineffective against HTTPS sites. This middleware's utility is significantly reduced, and often unnecessary, for production environments where HTTPS is universally used.
Fix: Consider if this middleware is truly needed in your production HTTPS setup. It's primarily beneficial for HTTP development servers.
breaking This package is an ES Module and provides only ES Module exports. Direct `require()` calls in CommonJS environments will fail with module resolution errors (e.g., 'ERR_UNSUPPORTED_DIR_IMPORT' or 'is not a function').
Fix: Ensure your project is configured for ES Modules by using `import` statements and setting `"type": "module"` in `package.json`, or by using `.mjs` file extensions.
gotcha The `allowedHosts` option requires careful configuration. A value like `example.com` only matches the exact domain, while `.example.com` allows `example.com` and all its subdomains. Misunderstanding this can lead to legitimate requests being blocked.
Fix: Thoroughly test your `allowedHosts` configuration. Use the `.` prefix for subdomains as intended (e.g., `['.yourdomain.com']`). Remember that `localhost` and IP addresses are always allowed automatically.

Install

npm install host-validation-middleware npm
yarn add host-validation-middleware yarn
pnpm add host-validation-middleware pnpm

Imports

hostValidationMiddleware

wrong:

const { hostValidationMiddleware } = require('host-validation-middleware')

correct:

import { hostValidationMiddleware } from 'host-validation-middleware'

This package is an ES Module; CommonJS `require()` is not supported directly and will lead to errors.

isHostAllowed
wrong:
```
const { isHostAllowed } = require('host-validation-middleware')
```
correct:
```
import { isHostAllowed } from 'host-validation-middleware'
```
The `isHostAllowed` utility function is also exported as an ES Module, requiring `import` syntax.

Quickstart

Demonstrates setting up host validation with Connect, allowing specified domains and subdomains, and customizing error responses.

import connect from 'connect';
import { hostValidationMiddleware } from 'host-validation-middleware';

const app = connect();

app.use(
  hostValidationMiddleware({
    allowedHosts: Object.freeze(['example.com', '.mydomain.com', 'localhost:3000']),
    generateErrorMessage: (hostname) => `Access denied for host: ${hostname}`,
    errorResponseContentType: 'text/plain'
  })
);

app.use((req, res) => {
  res.end('Hello, world!');
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

view raw JSON →