bearerparse

Zero-dependency HTTP Authorization and WWW-Authenticate header parser and builder for Node.js

"No more substring(7) hacks — parse Bearer, Basic, Digest, and custom auth schemes with a single function call."

Quick Start

npm install bearerparse

const { parseAuthHeader, parseBearerToken, parseWwwAuthenticate, buildWwwAuthenticate, extractBearerPayload } = require('bearerparse');

// Parse any Authorization header
const auth = parseAuthHeader('Bearer eyJhbG...MjN9.sig');
// → { scheme: 'bearer', token: 'eyJhbG...MjN9.sig' }

// Extract just the Bearer token (handles = padding correctly)
const token = parseBearerToken('Bearer eyJhbG...sig=');
// → 'eyJhbG...sig='  (naive split('=') would break here)

// Parse WWW-Authenticate challenge
const challenge = parseWwwAuthenticate('Bearer realm="api", error="invalid_token"');
// → { scheme: 'bearer', params: { realm: 'api', error: 'invalid_token' } }

// Build a WWW-Authenticate header
const header = buildWwwAuthenticate('bearer', { realm: 'api', scope: 'read:users' });
// → 'Bearer realm="api", scope="read:users"'

// Decode JWT payload (no signature verification)
const payload = extractBearerPayload('Bearer eyJzdWIiOiIxMjMifQ.sig');
// → { sub: '123' }

⚡ Performance & Benchmarks

bearerparse is a zero-dependency pure-JavaScript library. No native bindings, no bundler magic — just fast, readable code.

For HTTP server middleware and API clients, header parsing is a hot path. bearerparse is designed for O(n) single-pass parsing with no backtracking.

Why bearerparse?

Node.js stdlib has no built-in HTTP Authorization header parser. Developers resort to:

• substring(7) or split(' ') — breaks on tokens with = padding characters (JWTs, base64url)
• Third-party auth middleware with 5–10 transitive dependencies
• Manual substring workarounds per StackOverflow answer — inconsistent, untested

bearerparse fixes these by providing a standards-compliant, zero-dependency library that handles every edge case the spec calls out:

| Edge case | bearerparse | naive split(' ') | |---|---|---| | Bearer token= (trailing =) | ✅ keeps = in token | ❌ splits on = | | Bearer token=abc= | ✅ full token | ❌ truncates | | bearer token (extra spaces) | ✅ trimmed | ❌ broken | | Bearer header.payload.sig (JWT) | ✅ full token with dots | ❌ splits on . | | BEARER TOKEN (mixed case) | ✅ normalized | ❌ broken |

Key Features

• 5 public functions: parseAuthHeader, parseBearerToken, parseWwwAuthenticate, buildWwwAuthenticate, extractBearerPayload
• Zero dependencies — no package-lock risk, no supply-chain attack surface
• Handles all common auth schemes: Bearer, Basic, Digest, HOBA, Negotiate
• RFC 6750 compliant — Bearer scheme is case-insensitive, tokens preserve = padding
• Proper WWW-Authenticate parser — quoted-string aware (handles commas inside quoted values)
• JWT payload extraction — decode without verification (verification is out of scope)
• ESM + CJS — import or require() both work
• TypeScript definitions — index.d.ts with all public types included
• Strict mode safe — no global mutation, no eval, no new Function

API Reference

parseAuthHeader(header: string): AuthResult | null

Parses any Authorization header value and returns a typed result. Returns null for empty or unparseable headers.

parseAuthHeader('Bearer abc123')
// → { scheme: 'bearer', token: 'abc123' }

parseAuthHeader('Basic dXNlcjpwYXNz')
// → { scheme: 'basic', username: 'user', password: 'pass' }

parseAuthHeader('Negotiate YGZlZGY=')
// → { scheme: 'negotiate', raw: 'YGZlZGY=' }

parseAuthHeader('')       // → null
parseAuthHeader('nope')   // → null

parseBearerToken(header: string): string | null

Extracts just the Bearer token — the fastest path for Bearer-only use cases. Handles = padding and extra whitespace correctly.

parseBearerToken('Bearer eyJhbGciOiJIUzI1NiJ9.test=sig=')
// → 'eyJhbGciOiJIUzI1NiJ9.test=sig='

parseBearerToken('bearer  token123  ')
// → 'token123'

parseWwwAuthenticate(header: string): WwwAuthenticateResult | null

Parses a WWW-Authenticate challenge header with proper quoted-string handling.

parseWwwAuthenticate('Bearer realm="api", error="invalid_token"')
// → { scheme: 'bearer', params: { realm: 'api', error: 'invalid_token' } }

parseWwwAuthenticate('Bearer realm="api, internal"')
// → { scheme: 'bearer', params: { realm: 'api, internal' } }

buildWwwAuthenticate(scheme: string, params: Object): string

Builds a WWW-Authenticate header string. Handles escaping of " and \ in param values.

buildWwwAuthenticate('bearer', { realm: 'api' })
// → 'Bearer realm="api"'

buildWwwAuthenticate('bearer', { realm: 'api', scope: 'read' })
// → 'Bearer realm="api", scope="read"'

extractBearerPayload(header: string): Object | null

Extracts and decodes the payload segment of a Bearer token (JWT or base64url). Does not verify the token signature.

// JWT: header.payload.signature
extractBearerPayload('Bearer eyJzdWIiOiIxMjMiLCJpYXQiOjE2OTk5OTk5OX0.sig')
// → { sub: '123', iat: 1699999999 }

// Non-JWT base64url token
extractBearerPayload('Bearer c29tZXRva2Vu')
// → { __raw: 'sometoken' }

CLI

npx bearerparse <header>

Parses any Authorization header from stdin or argument and prints the parsed result as JSON.

Install

npm install bearerparse

Or from source:

git clone https://github.com/prasadaabhishek/bearerparse.git
cd bearerparse
npm install
npm test

Limitations

• extractBearerPayload decodes but does not verify JWT signatures (by design — verification requires a secret/public key and is out of scope)
• Only HTTP Authorization and WWW-Authenticate headers are supported; other auth headers (e.g. Proxy-Authenticate) are not currently parsed
• TypeScript types are provided but no @types/* wrapper package is published — the .d.ts file is included in the package

Non-goals

• Token verification (JWT signature checking)
• OAuth 2.0 token endpoint logic
• Digest authentication (MD5/session challenge-response)
• Authorization logic (what to do with a valid token)
• Node.js built-in module dependencies (no crypto, no buffer required)

License

MIT © 2026