Basic Auth Middleware

Common errors

• ERR_REQUIRE_ESM: require() of ES Module ... not supported.

  cause Attempting to import this CommonJS-only package using ES Modules (`import`) syntax in a modern Node.js environment.
  fix Use CommonJS `require` syntax: `const Auth = require('basic-auth-middleware');`

• TypeError: auth is not a function

  cause Attempting to call the imported module directly as a middleware function instead of first instantiating it with credentials.
  fix Ensure you create an instance by calling `Auth` with username and password: `const auth = Auth('your-username', 'your-password');` before using `auth(req, res, ctx, done);`

Warnings

• breaking This package is considered abandoned, with the last update over 7 years ago (as of April 2026). It also carried an 'experimental' stability badge even at its 1.0.0 release. It is not recommended for new projects and should be replaced in existing ones due to potential security vulnerabilities and lack of maintenance.
  Fix: Migrate to a actively maintained basic authentication middleware for your specific framework (e.g., 'express-basic-auth' for Express) or implement a custom, modern solution.
• gotcha The middleware uses a callback-based API (`middleware(req, res, ctx, done)`) which is less common in modern async/await-centric Node.js development. This can lead to more complex error handling and control flow compared to promise-based alternatives.
  Fix: Wrap the middleware in a Promise or utilize an alternative package that provides a promise-based or async/await compatible API for easier integration with modern Node.js patterns.
• gotcha This package relies on the 'boom' library for error objects. 'boom' is also deprecated and largely unmaintained. Consumers of the `err` object will need to handle `boom`-specific properties (e.g., `err.output.statusCode`) rather than standard JavaScript `Error` properties.
  Fix: Inspect the `err` object in the callback for specific `boom` properties like `err.output` or `err.isBoom`. Consider migrating to a middleware that uses standard JavaScript `Error` objects or more modern error handling patterns.

Install

• npm install basic-auth-middleware npm
• yarn add basic-auth-middleware yarn
• pnpm add basic-auth-middleware pnpm

Imports

• Auth
  wrong:

  import Auth from 'basic-auth-middleware'

  correct:

  const Auth = require('basic-auth-middleware')

  This package only provides a CommonJS export. ES Modules (ESM) syntax like `import` is not supported. There are no TypeScript type declarations provided by the package.

Quickstart

Demonstrates setting up a basic HTTP server with basic authentication using environment variables for credentials. It shows successful and failed authentication scenarios.

const Auth = require('basic-auth-middleware');
const http = require('http');

const USERNAME = process.env.BASIC_AUTH_USERNAME || 'my-username';
const PASSWORD = process.env.BASIC_AUTH_PASSWORD || 'some-password';
const PORT = process.env.PORT || 3000;

const auth = Auth(USERNAME, PASSWORD);

const server = http.createServer(function (req, res) {
  const ctx = {}; // Context object, can be used for passing data
  auth(req, res, ctx, function (err) {
    if (err) {
      // boom errors typically have .output.statusCode
      res.statusCode = err.output ? err.output.statusCode : 401;
      res.setHeader('WWW-Authenticate', 'Basic realm="Authentication Required"');
      res.end('Not authenticated. Please provide valid credentials.');
      console.log('Authentication failed.');
      return;
    }
    res.end('Authentication successful! Welcome.');
    console.log('Authentication successful.');
  });
});

server.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log(`Try accessing with 'curl -u ${USERNAME}:${PASSWORD} http://localhost:${PORT}'`);
  console.log(`Or without credentials to fail: 'curl http://localhost:${PORT}'`);
});