Passport HTTP Basic & Digest Strategies

Common errors

• Error: Unknown authentication strategy "basic"

  cause The Passport BasicStrategy has not been properly configured or registered with `passport.use()` before `passport.authenticate('basic')` is called.
  fix Ensure `passport.use(new BasicStrategy(...))` is called and executed before any routes attempt to use the 'basic' strategy.

• TypeError: BasicStrategy is not a constructor

  cause This error typically occurs when attempting to call `BasicStrategy` as a function or if the import statement is incorrect (e.g., trying to default import a named export).
  fix Use `new BasicStrategy(...)` to instantiate the strategy. For CommonJS, ensure `const { BasicStrategy } = require('passport-http');` or `const BasicStrategy = require('passport-http').BasicStrategy;` is used. For ESM, `import { BasicStrategy } from 'passport-http';` is correct.

• ReferenceError: User is not defined

  cause The examples in the README use `User.findOne` and `user.verifyPassword` as placeholders, which assume you have a `User` model or equivalent logic defined to retrieve and validate user credentials.
  fix Replace `User.findOne` and `user.verifyPassword` with your actual user retrieval and password verification logic from your database or authentication system.

Warnings

• gotcha This package (v0.3.0) has not been updated in over nine years. While it may still function, it's not actively maintained, which can lead to compatibility issues with newer Node.js versions, updated Passport.js versions, or expose unpatched security vulnerabilities.
  Fix: Consider more modern authentication approaches (e.g., JWT, OAuth 2.0) or actively maintained Passport strategies, especially for new projects. If using, thoroughly test compatibility and review its source for potential security concerns.
• gotcha When using HTTP Basic or Digest authentication for APIs, sessions are typically not desired. Forgetting to set `session: false` in `passport.authenticate()` can lead to unexpected session creation or persistence behavior.
  Fix: Always include `{ session: false }` in `passport.authenticate('strategy', { session: false })` when using stateless HTTP authentication schemes.
• gotcha HTTP Basic Authentication sends credentials in plain text (Base64 encoded) and should *only* be used over HTTPS/TLS to prevent eavesdropping. HTTP Digest offers some protection but is considered less secure and more complex than modern token-based methods.
  Fix: Always deploy applications using Basic or Digest authentication with HTTPS/TLS enabled. For new applications, prefer token-based authentication (like JWT) over Digest for better security and flexibility.
• gotcha The `done` callback in strategy verification functions has a specific signature: `done(error, user, info)`. Incorrectly calling `done` (e.g., `done(user)`) can lead to authentication failures, server errors, or incorrect user context.
  Fix: Ensure `done` is called correctly: `done(null, user)` on success, `done(null, false)` for failed authentication (e.g., wrong password), and `done(error)` for server errors.

Install

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

Imports

• BasicStrategy
  wrong:

  const BasicStrategy = require('passport-http').Strategy;

  correct:

  import { BasicStrategy } from 'passport-http';

  BasicStrategy is a named export. Ensure you import the specific class.
• DigestStrategy
  wrong:

  const DigestStrategy = require('passport-http').DigestStrategy;

  correct:

  import { DigestStrategy } from 'passport-http';

  DigestStrategy is a named export. Use named import syntax.
• passport
  wrong:

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

  correct:

  import passport from 'passport';

  The `passport` object itself comes from the `passport` package, not `passport-http`.

Quickstart

This example demonstrates configuring and using both HTTP Basic and HTTP Digest authentication strategies with Passport.js and Express, showcasing how to protect routes without requiring session management.

import express from 'express';
import passport from 'passport';
import { BasicStrategy, DigestStrategy } from 'passport-http';

const app = express();
const PORT = process.env.PORT || 3000;

// A mock user database for demonstration
const users = [
  { id: 1, username: 'john', password: 'password', secret: 'shared-secret' },
  { id: 2, username: 'jane', password: 'secure', secret: 'another-secret' }
];

// Basic Strategy Configuration
passport.use(new BasicStrategy(
  function(userid, password, done) {
    const user = users.find(u => u.username === userid);
    if (!user) { return done(null, false); }
    if (user.password !== password) { return done(null, false); }
    return done(null, user);
  }
));

// Digest Strategy Configuration
passport.use(new DigestStrategy({ qop: 'auth' },
  function(username, done) {
    const user = users.find(u => u.username === username);
    if (!user) { return done(null, false); }
    // For Digest, 'done' needs to provide the user and the shared secret (password)
    return done(null, user, user.secret);
  },
  function(params, done) {
    // Optional: Validate nonce and other parameters to prevent replay attacks
    // For simplicity, we just accept for this example.
    done(null, true);
  }
));

app.use(passport.initialize());

// Routes for HTTP Basic Authentication
app.get('/basic-private', 
  passport.authenticate('basic', { session: false }),
  function(req, res) {
    res.json({ message: 'Welcome to the basic private area!', user: req.user.username });
  }
);

// Routes for HTTP Digest Authentication
app.get('/digest-private', 
  passport.authenticate('digest', { session: false }),
  function(req, res) {
    res.json({ message: 'Welcome to the digest private area!', user: req.user.username });
  }
);

app.get('/', (req, res) => {
  res.send('Hello! Try accessing /basic-private or /digest-private with auth.');
});

app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log('Test Basic Auth with: curl -u john:password http://localhost:3000/basic-private');
  console.log('Test Digest Auth with: curl --digest -u jane:another-secret http://localhost:3000/digest-private');
});