HTTP Basic Authentication for Node.js

Common errors

• TypeError: basicAuth is not a function

  cause The `require('basic-authentication')` statement was not immediately invoked with parentheses.
  fix Change `const basicAuth = require('basic-authentication');` to `const basicAuth = require('basic-authentication')();` (or pass options: `require('basic-authentication')(options)`).

• HTTP 401 Unauthorized

  cause Invalid username or password provided, or no credentials were sent. This could also be due to an incorrect `htpasswd` file path or hash configuration.
  fix Check the username and password in the client request. Verify the `user`, `password`, `file`, and `hash` options in your `basic-authentication` configuration. Ensure the `realm` is correctly set if using custom values.

• TypeError: Cannot read properties of undefined (reading 'user') // when using functions or legacy mode

  cause Attempting to access `user` or `password` properties on the return value of `basic-authentication` when not in `legacy` mode, or when authentication failed in `legacy` mode (which returns an empty object).
  fix If using `functions: true`, the return value is a Base64 string, not an object. If using `legacy: true`, ensure you check for an empty object `{}` before accessing properties, indicating authentication failure.

Warnings

• breaking Support for Node.js versions below 4 was removed in `basic-authentication@1.8.0`. Applications targeting older Node.js environments must use an earlier package version.
  Fix: Upgrade Node.js to version 4 or higher, or pin `basic-authentication` to a version prior to 1.8.0 if legacy Node.js support is essential.
• gotcha The module's behavior and return type are drastically altered by the `functions` and `legacy` options. Without these, it returns an Express middleware. With `functions: true`, it returns a function that takes `req` and returns a Base64 string (username). With `legacy: true`, it returns an object `{user, password}`.
  Fix: Carefully review the `options` documentation for `functions` and `legacy` flags and ensure your usage matches the expected return type and API surface. Always invoke `require('basic-authentication')(options)` with the correct configuration for your desired mode.
• breaking The license changed from GPL3 to Apache2 in version 1.9.0. This is a significant change in terms of legal implications for projects depending on this package.
  Fix: Review your project's licensing requirements and ensure compatibility with the Apache 2.0 license if upgrading to version 1.9.0 or later.
• gotcha When using the `file` option for htpasswd authentication, ensure the `hash` option correctly specifies the hashing algorithm (e.g., 'md5') used in your `.htpasswd` file. Incorrect hash types will lead to failed authentication.
  Fix: Verify the hash algorithm used when generating your `.htpasswd` file and set the `hash` option accordingly in your `basic-authentication` configuration.

Install

• npm install basic-authentication npm
• yarn add basic-authentication yarn
• pnpm add basic-authentication pnpm

Imports

• authenticationMiddleware
  wrong:

  import authenticationMiddleware from 'basic-authentication';

  correct:

  const authenticationMiddleware = require('basic-authentication')();

  The `require` call must be immediately invoked as a function to return the configured middleware instance. Direct ESM import is not supported.
• configuredAuthenticationFunction
  wrong:

  const authFunction = require('basic-authentication');
  // Then later trying authFunction({ functions: true });

  correct:

  const authFunction = require('basic-authentication')({ functions: true });

  To use the module as a direct authentication function (not Express middleware), the `functions: true` option must be passed during initialization. This changes the return type from a middleware to a function that takes `req` and returns user info.
• legacyAuthenticationObject
  wrong:

  const authObject = require('basic-authentication')({ functions: true }); // Expecting an object, getting a string

  correct:

  const authObject = require('basic-authentication')({ legacy: true });

  When using `legacy: true`, the module returns an object `{user, password}` if authentication succeeds, or an empty object on failure. Be careful not to confuse this with `functions: true` mode which returns a string.

Quickstart

Demonstrates `basic-authentication` as an Express middleware for a protected route and its functional mode for custom authentication logic, using environment variables for credentials.

const express = require('express');
const basicAuth = require('basic-authentication');

const app = express();

// Configure basic authentication with a custom user and password
const authMiddleware = basicAuth({
  user: process.env.AUTH_USER || 'myuser',
  password: process.env.AUTH_PASSWORD || 'mypassword',
  realm: 'Restricted Area'
});

// Apply the authentication middleware to a specific route
app.get('/protected', authMiddleware, (req, res) => {
  res.send('Welcome, authenticated user!');
});

// Or use it in a more functional way for advanced logic
const authChecker = basicAuth({ functions: true });
app.get('/admin', (req, res) => {
  const user = authChecker(req);
  if (user === (process.env.AUTH_USER || 'myuser')) {
    res.send(`Hello, admin ${user}!`);
  } else {
    res.status(401).send('Unauthorized: Invalid admin user.');
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log('Try accessing http://localhost:3000/protected with user:myuser and pass:mypassword');
});