Connect HTTP Authentication Middleware

Common errors

• Error: Cannot find module 'http-auth'

  cause `http-auth` is a peer dependency that `http-auth-connect` wraps but does not automatically install.
  fix Install the core `http-auth` package: `npm install http-auth`.

• HTTP 401 Unauthorized (in browser) or 'Basic realm="Secure Area"' header missing (in console)

  cause The `file` path for your `.htpasswd` file is incorrect, the file is malformed, or the specified `realm` in `auth.basic` configuration does not match what the browser expects or the server is sending.
  fix Double-check the `file` path for your `.htpasswd` to ensure it's absolute and points to a valid file. Verify the `.htpasswd` file format is correct. Ensure the `realm` option in `auth.basic` configuration is set as intended.

• TypeError: Cannot read properties of undefined (reading 'split') or similar errors related to authentication credentials

  cause Typically indicates a malformed or incorrect entry in the `.htpasswd` file, or issues with the `http-auth` module parsing the provided credentials.
  fix Inspect your `.htpasswd` file for correct username:hashedpassword format. Ensure no extra newlines or invalid characters are present. Use a tool to generate valid Apache-compatible `.htpasswd` entries.

Warnings

• gotcha This package is an adapter for `http-auth`. It requires `http-auth` to be installed as a separate dependency (`npm install http-auth`) and configured independently. Misconfigurations in the `http-auth` module (e.g., incorrect `realm`, invalid user file paths, or weak credentials) will directly impact the security and functionality of your application.
  Fix: Ensure `http-auth` is installed (`npm install http-auth`) and correctly configured according to its documentation before passing its `auth` instance to `http-auth-connect`.
• gotcha The example and typical usage of `http-auth-connect` relies on file-based user storage (`.htpasswd` files). While convenient for development, this method is generally not scalable or secure for production environments with many users. Consider integrating `http-auth` with a more robust and dynamic user management system (e.g., database, LDAP, OAuth) for production deployments.
  Fix: For production, configure `http-auth` to use a custom `verify` function or integrate with a proper user management system. Refer to the `http-auth` documentation for advanced authentication strategies.
• gotcha `http-auth-connect` is designed for Connect/Express-style middleware. Attempting to use it directly with Node.js's native `http` module or other non-Connect compatible frameworks will result in errors or unexpected behavior, as it expects a middleware signature (`req`, `res`, `next`).
  Fix: Ensure your application uses a Connect-compatible framework (like Express or Connect itself) to integrate this middleware. For other frameworks, a custom adapter might be necessary.

Install

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

Imports

• authConnect

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

  This package is primarily CommonJS. Use `require` for Node.js environments.
• authConnect
  wrong:

  import { authConnect } from 'http-auth-connect';

  correct:

  import authConnect from 'http-auth-connect';

  While CommonJS modules can often be imported with `import defaultExport from 'module'`, named imports like `{ authConnect }` will not work as it does not have a named export of 'authConnect'.
• auth

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

  The core `http-auth` module, which `http-auth-connect` integrates, must be imported separately to configure authentication schemes.

Quickstart

This quickstart demonstrates how to set up HTTP Basic Authentication using `http-auth-connect` with Express, protecting a simple route. It includes creating a temporary .htpasswd file for user credentials.

const express = require('express');
const auth = require('http-auth');
const authConnect = require('http-auth-connect');
const path = require('path');
const fs = require('fs');

// Create a dummy htpasswd file for demonstration
const htpasswdPath = path.join(__dirname, 'users.htpasswd');
fs.writeFileSync(htpasswdPath, 'gevorg:$apr1$D9ByKj6f$d2yF/X7zN4L9P.hR/oE3w1\nSarah:$apr1$uL9P.hR/oE3w1$D9ByKj6f$d2yF/X7zN4L9P.hR/oE3w1\n');

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

const app = express();

// Apply the authentication middleware
app.use(authConnect(basic));

// Setup a protected route
app.get('/', (req, res) => {
  res.send(`Hello from express - ${req.user}! You are authenticated.`);
});

// Start server
const PORT = process.env.PORT || 1337;
app.listen(PORT, () => {
  console.log(`Server running at http://127.0.0.1:${PORT}/`);
  console.log('Try accessing with user "gevorg" and password "gpass", or "Sarah" and "testpass".');
});

// Clean up dummy file on exit (for proper demonstration)
process.on('exit', () => {
    if (fs.existsSync(htpasswdPath)) {
        fs.unlinkSync(htpasswdPath);
    }
});