Registry / auth-security / basic-auth

basic-auth

JSON →
library2.0.1jsnpmunverified

basic-auth is a focused Node.js module designed for parsing the 'Authorization' header field specifically for Basic HTTP Authentication. It efficiently extracts the username and password from the header string, returning them as an object with `name` and `pass` properties. The current stable version is 2.0.1, indicating a mature and stable package that receives updates primarily for dependency maintenance and minor internal improvements. It operates with a low-cadence release cycle. A key differentiator is its simplicity and direct utility, offering a lightweight solution for a common HTTP parsing task without imposing additional framework or middleware dependencies. This makes it highly versatile for integration into various Node.js HTTP servers, custom middleware, or application logic, handling edge cases such as empty usernames or passwords correctly.

auth-securityhttp-networking
github ↗package ↗
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

This package is a CommonJS module. Direct ESM import syntax is not supported without a transpiler or ESM wrapper.

const auth = require('basic-auth')

The primary function accepts a Node.js `http.IncomingMessage` object. Passing a raw Koa context (`ctx`) directly was deprecated in v2.0.0; use `ctx.req` instead.

const credentials = auth(req); // req is a Node.js http.IncomingMessage object

The `parse` method is exposed as a property of the main `auth` export, designed for parsing raw `Authorization` header strings. It's not a named export for direct destructuring.

const credentials = auth.parse('Basic Zm9vOmJhcg==')

Demonstrates a basic Node.js HTTP server using `basic-auth` to parse incoming 'Authorization' headers and implement credential validation with `tsscmp` for security.

const http = require('http'); const auth = require('basic-auth'); const compare = require('tsscmp'); // For timing-safe comparison (install separately) // Create server const server = http.createServer(function (req, res) { const credentials = auth(req); // Basic function to validate credentials for example function check (name, pass) { let valid = true; // Simple method to prevent short-circuiting and use timing-safe compare valid = compare(name, 'john') && valid; valid = compare(pass, 'secret') && valid; return valid; } // Check credentials // The 'check' function will typically be against your user store if (!credentials || !check(credentials.name, credentials.pass)) { res.statusCode = 401; res.setHeader('WWW-Authenticate', 'Basic realm="example"'); res.end('Access denied'); } else { res.end(`Access granted to ${credentials.name}`); } }); // Listen server.listen(3000, () => { console.log('Server listening on http://localhost:3000'); console.log('Try accessing with "john:secret" or other credentials.'); });
Debug
Known footguns
breakingThe `auth(ctx)` signature for Koa context objects was removed. Developers must now explicitly pass `ctx.req` instead of `ctx` directly.
breakingSupport for Node.js versions below 0.8 was dropped. While unlikely to affect modern applications, very old Node.js environments will not be compatible with versions >=2.0.0.
gotchaWhen validating credentials, always use a timing-safe comparison function (e.g., `tsscmp`) to prevent timing attacks. Directly comparing strings with `===` or `!==` can leak information about the correct password length through execution time differences.
gotchaThis package is a CommonJS module. Attempting to use `import` statements directly in an ESM context will require a bundler or specific Node.js configuration to handle CJS interoperability, or Node.js's own CJS interop for default exports.
Upgrade
Version history

Breaking-change detection hasn't run for this library yet.

Audit
Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity
17 hits · last 30 days
gptbot
4
ahrefsbot
4
bytedance
4
script
1
Resources
githubhttps://github.com/jshttp/basic-auth ↗
packagehttps://www.npmjs.com/package/basic-auth ↗