HTTP Basic and Digest Authentication for Node.js

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require()` in a Node.js project configured as an ES Module (`"type": "module"` in `package.json`).
  fix Change your project's `package.json` to `"type": "commonjs"` or rename your script file to have a `.cjs` extension. If you must use ESM, consider using a dynamic import: `const auth = await import('http-auth').then(m => m.default || m);` (though this package exports directly, not a default).

• TypeError: auth.basic is not a function

  cause The `auth` object was not correctly imported or is undefined when attempting to call `auth.basic()`.
  fix Ensure that `const auth = require("http-auth");` is present and executed correctly before you try to call `auth.basic` or `auth.digest`. This often happens if the `require` statement is conditional or placed incorrectly.

• Error: ENOENT: no such file or directory, open '/path/to/users.htpasswd'

  cause The file specified in the `file` option for basic or digest authentication does not exist at the given path or the Node.js process lacks read permissions for it.
  fix Verify the `file` path is correct and absolute. Use `path.join(__dirname, 'data', 'users.htpasswd')` for relative paths within your project. Ensure the Node.js process has read permissions for the file.

Warnings

• breaking The package is strictly CommonJS. Attempting to use `import` statements directly in a pure ESM Node.js project will result in a `TypeError: require is not defined` or similar errors. It is not designed for direct ESM consumption.
  Fix: Ensure your project is configured for CommonJS, or use a build tool like Webpack/Rollup that can transpile CommonJS modules for ESM environments. If using Node.js ESM, you must use `createRequire` or a dynamic import (`await import()`) if absolutely necessary, but it's generally recommended for CJS-only packages to stick to `require()` environments.
• breaking Older versions of `http-auth` (prior to 4.1.3) contained unspecified security vulnerabilities. Users on these versions are at risk and should upgrade immediately.
  Fix: Upgrade to `http-auth` version 4.1.3 or newer to patch known security issues: `npm install http-auth@latest`.
• gotcha The `http-auth` package does not ship with official TypeScript declaration files (`.d.ts`). Developers using TypeScript will need to either create their own declaration files or use `@ts-ignore` directives, leading to a less type-safe development experience.
  Fix: Consider contributing `d.ts` files to the project, providing a `types/http-auth/index.d.ts` file in your project, or looking for community-maintained types (e.g., `@types/http-auth`, though none exist currently).
• gotcha Using file-based authentication (e.g., `.htpasswd` files) for storing user credentials, especially with plaintext or basic hashes, is generally not recommended for production applications due to security risks. Without strong file system permissions and hashing algorithms, credentials can be easily compromised.
  Fix: For production, integrate with more secure authentication backends such as databases with strong hashing (e.g., bcrypt), external identity providers, or OAuth/OIDC systems. If file-based is unavoidable, ensure robust file system permissions and use strong hashing algorithms provided by utilities like `htpasswd` or `htdigest` with modern secure options.

Install

• npm install http-auth npm
• yarn add http-auth yarn
• pnpm add http-auth pnpm

Imports

• auth
  wrong:

  import auth from 'http-auth';

  correct:

  const auth = require('http-auth');

  This package is CommonJS-only. Direct ESM imports will fail without a transpilation step or a CommonJS wrapper.
• basic
  wrong:

  import { basic } from 'http-auth';

  correct:

  const basic = auth.basic({...});

  The `basic` authentication strategy is a method on the `auth` object, not a direct export.
• digest
  wrong:

  import { digest } from 'http-auth';

  correct:

  const digest = auth.digest({...});

  The `digest` authentication strategy is a method on the `auth` object, not a direct export.

Quickstart

This quickstart sets up a basic HTTP server with HTTP Basic Authentication, reading user credentials from a temporary `.htpasswd` file. It demonstrates how to initialize the `basic` authentication middleware and integrate it into a standard Node.js `http.createServer` callback.

const http = require("http");
const auth = require("http-auth");
const path = require('path');
const fs = require('fs');

// Create a dummy .htpasswd file for the example
const htpasswdPath = path.join(__dirname, "users.htpasswd");
fs.writeFileSync(htpasswdPath, "gevorg:gpass\nSarah:testpass");

const basicAuth = auth.basic({
  realm: "Protected Area.",
  file: htpasswdPath // gevorg:gpass, Sarah:testpass
});

http.createServer(
  basicAuth.check((req, res) => {
    res.end(`Welcome to the private area - ${req.user} (${req.method} ${req.url})!`);
  })
)
.listen(1337, () => {
  console.log("Server running at http://127.0.0.1:1337/");
  console.log("Try accessing with 'gevorg' and 'gpass' or 'Sarah' and 'testpass'.");
  console.log("To stop the server, press Ctrl+C. The users.htpasswd file will be removed.");
});

// Clean up the dummy file on exit
process.on('exit', () => {
  if (fs.existsSync(htpasswdPath)) {
    fs.unlinkSync(htpasswdPath);
    console.log("Cleaned up users.htpasswd");
  }
});