Registry / auth-security / basic-auth

basic-auth

JSON →
library0.0.2jsnpmunverified

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
npm install basic-auth
github ↗package ↗
INSTALL
IMPORT
SIG · BASIC-AUTH
B
basic-auth
auth-securityjavascriptv0.0.2
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
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.

auth
✓ const auth = require('basic-auth')
✗ import auth from 'basic-auth'
This package is a CommonJS module. Direct ESM import syntax is not supported without a transpiler or ESM wrapper.
auth(req)
✓ const credentials = auth(req); // req is a Node.js http.IncomingMessage object
✗ const credentials = auth(ctx); // `ctx` is not supported directly since v2.0.0, use `ctx.req`
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.
auth.parse(string)
✓ const credentials = auth.parse('Basic Zm9vOmJhcg==')
✗ import { parse } from 'basic-auth'
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.

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 issues
breakingThe `auth(ctx)` signature for Koa context objects was removed. Developers must now explicitly pass `ctx.req` instead of `ctx` directly.
fix
Change `auth(ctx)` to `auth(ctx.req)` when using with Koa or similar frameworks.
affects: >=2.0.0
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.
fix
Upgrade Node.js to a modern, supported version. The current LTS is recommended.
affects: >=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.
fix
Install `tsscmp` (`npm install tsscmp`) and integrate it into your credential checking logic as shown in the package's examples.
affects: >=0.0.1
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.
fix
For CommonJS environments, use `const auth = require('basic-auth')`. In pure ESM projects, consider a wrapper or use dynamic import `import('basic-auth')` if strictly necessary, but typically this package is used in CJS or transpiled contexts.
affects: >=0.0.1
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'name')
The `auth()` function returned `undefined` because the 'Authorization' header was missing, malformed, or not a Basic auth header.
fix
Always check if `credentials` is defined before attempting to access `credentials.name` or `credentials.pass`. Ensure the client is sending a valid 'Authorization: Basic ...' header.
TypeError: req.headers is undefined
The argument passed to `auth()` was not a valid Node.js `http.IncomingMessage` object or did not have a `headers` property. This can happen if a raw Koa `ctx` object is passed directly after v2.0.0.
fix
Ensure you are passing a valid request object, for instance, `http.IncomingMessage` in Node.js, or `ctx.req` if you are using Koa.
Upgrade
Version history
0.0.2latest on npm
Audit
Dependencies
safe-bufferrequiredUsed for improved Buffer API compatibility and security across Node.js versions, introduced in v2.0.0.
Agent activity
35 hits · last 30 days
node
32
OpenAI (training)
1
Resources
githubhttps://github.com/jshttp/basic-auth ↗
packagehttps://www.npmjs.com/package/basic-auth ↗
basic-auth — npm install basic-auth · libregistry