Basic HTTP Authentication Parser

2.0.8 · maintenance · verified Wed Apr 22

simple-auth-basic is a lightweight Node.js module designed for parsing HTTP Basic Authorization headers. It extracts the username and password from the 'Authorization' header in an incoming request or a raw header string, returning an object with `name` and `pass` properties. If the header is invalid or missing, it returns `undefined`. The current stable version is 2.0.8. As a focused utility for a well-established standard, its release cadence is generally slow, primarily for maintenance and compatibility updates rather than new features. Its key differentiator is its simplicity and singular focus on parsing the header, leaving credential validation to the application logic, often paired with a timing-safe string comparison library like `tsscmp` for security.

Common errors

```
TypeError: auth is not a function
```
cause Attempting to call `auth` directly on a string instead of a request object, or attempting to call `auth.parse` before `auth` is imported correctly.

fix Ensure `auth` is imported correctly as a default export (`import auth from 'simple-auth-basic'`) and that `auth` is called with a request object (`auth(req)`). For string parsing, use `auth.parse(headerString)`.
```
ReferenceError: require is not defined in ES module scope
```
cause Using CommonJS `require()` syntax in an ESM project (e.g., `"type": "module"` in package.json or `.mjs` files).

fix Replace `const auth = require('simple-auth-basic')` with `import auth from 'simple-auth-basic'`.

Warnings

gotcha This module only parses the Basic Authorization header. It does not perform any credential validation or database lookups. Developers must implement their own logic for checking usernames and passwords, preferably using timing-safe comparison methods to prevent timing attacks.
Fix: Always use a timing-safe string comparison library (e.g., `tsscmp`) when validating user-provided passwords against stored credentials to mitigate timing attacks.
gotcha The `auth(req)` function expects a standard Node.js HTTP request object. When parsing a header string from other sources (e.g., a custom proxy header or a non-Node.js environment), use `auth.parse(string)` instead.
Fix: For raw strings, use `auth.parse(headerString)`. For Node.js `IncomingMessage` objects, use `auth(req)`.

Install

npm install simple-auth-basic npm
yarn add simple-auth-basic yarn
pnpm add simple-auth-basic pnpm

Imports

auth
wrong:
```
const auth = require('simple-auth-basic')
```
correct:
```
import auth from 'simple-auth-basic'
```
While the README shows CJS `require()`, modern Node.js applications should prefer ESM `import`. This package should be compatible with both.
auth.parse
wrong:
```
import { parse } from 'simple-auth-basic'
```
correct:
```
import auth from 'simple-auth-basic'; auth.parse(headerString)
```
The `parse` function is a method on the default export, not a named export itself.

Quickstart

Demonstrates setting up a basic Node.js HTTP server that uses simple-auth-basic to parse Authorization headers and perform credential validation. It includes an example of using `tsscmp` for secure password comparison.

import http from 'http';
import auth from 'simple-auth-basic';
import compare from 'tsscmp'; // Often used for timing-safe comparisons

const server = http.createServer((req, res) => {
  const credentials = auth(req);

  // Basic function to validate credentials (against a user store in real apps)
  function check (name, pass) {
    let valid = true;
    // Using tsscmp to prevent timing attacks
    valid = compare(name, 'john') && valid;
    valid = compare(compare(pass, 'secret') && valid);
    return valid;
  }

  if (!credentials || !check(credentials.name, credentials.pass)) {
    res.statusCode = 401;
    res.setHeader('WWW-Authenticate', 'Basic realm="Secure Area"');
    res.end('Access denied');
  } else {
    res.end(`Welcome, ${credentials.name}! Access granted.`);
  }
});

const port = 3000;
server.listen(port, () => {
  console.log(`Server listening on http://localhost:${port}`);
  console.log('Try accessing with "john:secret" basic auth.');
});

view raw JSON →