Basic Auth

Basic Auth provides HTTP Basic Authentication header parsing for Node.js applications. It implements the RFC 7617 Basic Authentication scheme with two primary functions: parsing Authorization headers from HTTP request objects and parsing basic auth strings directly.

Package Information

• Package Name: basic-auth
• Package Type: npm
• Language: JavaScript
• Installation: npm install basic-auth

Core Imports

var auth = require('basic-auth');

For ES modules:

import auth from 'basic-auth';

Basic Usage

var auth = require('basic-auth');
var http = require('http');

// Parse from HTTP request
var server = http.createServer(function (req, res) {
  var credentials = auth(req);
  
  if (!credentials) {
    res.statusCode = 401;
    res.setHeader('WWW-Authenticate', 'Basic realm="example"');
    res.end('Access denied');
    return;
  }
  
  console.log('User:', credentials.name);
  console.log('Pass:', credentials.pass);
  res.end('Access granted');
});

// Parse from header string directly
var headerString = 'Basic Zm9vOmJhcg=='; // "foo:bar" encoded
var user = auth.parse(headerString);
console.log(user); // { name: 'foo', pass: 'bar' }

Capabilities

Request Parsing

Parses the Authorization header field from HTTP request objects, supporting both Node.js HTTP requests and Koa context objects.

/**
 * Parse the Authorization header field of a request.
 * @param {object} req - HTTP request object or Koa context object
 * @returns {object|undefined} Object with .name and .pass properties, or undefined if parsing fails
 * @throws {TypeError} When req is missing, not an object, or lacks headers property
 */
function auth(req);

The function accepts:

• Node.js HTTP request objects (with headers.authorization)
• Koa context objects (with req.headers.authorization)

Returns an object with:

• name (string): Username from basic auth credentials
• pass (string): Password from basic auth credentials

Returns undefined for:

• Missing Authorization header
• Malformed Authorization header
• Invalid basic auth scheme
• Malformed base64 credentials

Throws TypeError for:

• Missing req argument
• Non-object req argument
• Missing or invalid req.headers property

String Parsing

Parses basic auth authorization header strings directly, useful for custom header processing or non-standard authorization sources.

/**
 * Parse basic auth authorization header string.
 * @param {string} string - Authorization header string (e.g., "Basic Zm9vOmJhcg==")
 * @returns {object|undefined} Object with .name and .pass properties, or undefined if string is invalid
 */
auth.parse = function parse(string);

The function accepts authorization header strings in the format:

• "Basic <base64-encoded-credentials>"
• Case-insensitive "Basic" scheme
• Base64-encoded username:password credentials

Returns the same credential object format as the main auth() function, or undefined for invalid inputs.

Types

/**
 * Credentials object returned by both auth() and auth.parse()
 */
interface Credentials {
  /** Username from basic auth credentials */
  name: string;
  /** Password from basic auth credentials */  
  pass: string;
}

Error Handling

The library follows these error handling patterns:

• Input validation errors: Throws TypeError with descriptive messages
• Parsing failures: Returns undefined (never throws for malformed headers)
• Missing headers: Returns undefined (normal case, not an error)

Common error messages:

• "argument req is required" - Missing req parameter
• "argument req is required to be an object" - Invalid req type
• "argument req is required to have headers property" - Missing/invalid headers

Compatibility

• Node.js: >= 0.6
• Environment: Server-side only (uses Node.js Buffer API)
• Frameworks: Compatible with Express, Koa, vanilla HTTP servers, and custom frameworks