Passport.js Strategy for HTTP Basic/Digest Authentication via http-auth

Common errors

• TypeError: auth.basic is not a function

  cause The `http-auth` module was either not installed, installed incorrectly, or an incompatible version is in use that does not expose the `basic` method directly on its default export.
  fix Ensure `http-auth` is correctly installed via `npm install http-auth`. Verify your import statement is `const auth = require('http-auth');`. If the issue persists, check `http-auth`'s documentation for any breaking changes in its API.

• Error: Unknown authentication strategy "http"

  cause The `http-auth-passport` strategy, which is identified as 'http', was not successfully registered with the Passport.js middleware before being used in a route.
  fix Confirm that `passport.use(authPassport(basic));` is executed prior to any route that calls `passport.authenticate('http', ...)`. Ensure `authPassport` is correctly imported from `http-auth-passport` and that the `basic` instance is properly configured.

• 401 Unauthorized Response

  cause The server responded with 401 Unauthorized, indicating that the provided credentials (or lack thereof) were insufficient or incorrect for the protected resource.
  fix Check the username and password being sent in the `Authorization` header. Verify that the `.htpasswd` file's content or the custom credential callback's logic matches the expected values. Ensure the client (e.g., browser or API tool) is correctly sending the HTTP Basic Authorization header with each request.

Warnings

• breaking This package is primarily a CommonJS module. Direct usage in a purely ESM Node.js environment (`"type": "module"` in package.json) might lead to `require is not defined` errors or require specific interoperability configurations or bundler setups.
  Fix: For ESM projects, consider dynamic `import()` or transpiling your code. Alternatively, ensure your project supports CommonJS modules via Node.js's default interoperability or a bundler.
• gotcha The package `http-auth-passport` has not seen significant feature development or updates since its last release in 2021. It might not be fully compatible with major version updates of `passport` (e.g., v0.6.0+ which introduced asynchronous `req.login()`/`req.logout()` and changes in middleware extending request objects) without explicit testing.
  Fix: Carefully test compatibility with your specific `passport` version. Consult `passport`'s changelog for breaking changes affecting strategy integration. For active development, consider alternative, more actively maintained Passport strategies like `passport-http` if the unique features of `http-auth` are not strictly necessary.
• gotcha The example and typical use case for `http-auth-passport` explicitly disable sessions using `session: false` in `passport.authenticate()`. This is appropriate for stateless API authentication but will prevent session-based persistent logins for web applications.
  Fix: If session support is needed, ensure `express-session` and `passport.session()` middleware are correctly configured and placed before `passport.authenticate()` in your middleware stack. Then, remove the `session: false` option from the `authenticate` call.
• gotcha HTTP Basic authentication transmits credentials (username and password) in Base64-encoded plain text over the network. Without HTTPS, these credentials can be easily intercepted and compromised by attackers.
  Fix: Always deploy applications utilizing HTTP Basic authentication with HTTPS enabled to encrypt traffic. For enhanced security, consider more robust authentication mechanisms such as token-based (e.g., JWT with OAuth 2.0 Bearer tokens) or Digest authentication.
• deprecated The underlying `http-auth` module, which `http-auth-passport` integrates with, has been reported with an 'Inactive' maintenance status by security tools like Snyk, despite some recent NPM publishes. This indicates potentially slow responses to new feature requests, bug reports, or security vulnerabilities in the core authentication logic.
  Fix: Regularly monitor the `http-auth` project for security advisories. Evaluate if migrating to a more actively maintained direct Passport strategy like `passport-http` for Basic/Digest authentication would be a more sustainable long-term solution, if `http-auth` specific functionalities are not critical.
• gotcha When configuring `auth.basic()` or `auth.digest()`, providing a correct and accessible path to the `.htpasswd` or `.htdigest` file, or ensuring the callback returns credentials in the expected format, is crucial. Incorrect paths or malformed files/callbacks will result in authentication failures.
  Fix: Verify that the `file` property in your `auth.basic()` configuration uses an absolute path (`path.join(__dirname, 'yourfile.htpasswd')` is recommended) and that the file is readable by the Node.js process. Confirm the file content adheres to the `http-auth` module's specified format.

Install

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

Imports

• authPassport
  wrong:

  import { authPassport } from 'http-auth-passport';

  correct:

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

  This package is primarily CommonJS. While Node.js allows some interoperability, direct named ESM imports for a default CJS export are incorrect without specific bundling or transpilation.
• auth
  wrong:

  import { auth } from 'http-auth';

  correct:

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

  The `http-auth` module is a CommonJS package. Named ESM imports for its default export will not work directly.
• passport
  wrong:

  import { passport } from 'passport';

  correct:

  const passport = require('passport');

  The `passport` module is typically imported as a default export, making named ESM imports incorrect without explicit `default` specifiers or specific configurations.

Quickstart

This quickstart sets up an Express server that utilizes `http-auth-passport` to protect a route with HTTP Basic Authentication. It demonstrates defining a basic authentication realm using a `.htpasswd` file, integrating this realm as a Passport strategy, and securing an endpoint without maintaining user sessions. The example includes the creation of a temporary `.htpasswd` file for immediate testing.

const express = require('express');
const auth = require('http-auth');
const authPassport = require('http-auth-passport');
const passport = require('passport');
const fs = require('fs');

// Create a dummy .htpasswd file for demonstration
const htpasswdContent = 'testuser:testpass\nadmin:securepass';
const htpasswdPath = `${__dirname}/users.htpasswd`;
fs.writeFileSync(htpasswdPath, htpasswdContent);

const basic = auth.basic({
  realm: 'Secure Area',
  file: htpasswdPath // Path to your .htpasswd file
});

passport.use(authPassport(basic));

const app = express();

app.get('/', passport.authenticate('http', { session: false }), (req, res) => {
  res.end(`Welcome, ${req.user}! You are authenticated with HTTP Basic.`);
});

app.listen(1337, () => {
  console.log('Server running at http://127.0.0.1:1337/');
  console.log('Try accessing http://127.0.0.1:1337/ with username: testuser, password: testpass');
  console.log('Or with username: admin, password: securepass');
});