bearer-token-parser

bearer-token-parser

Zero-dependency Bearer token parser & validator middleware for Express. Extracts and validates tokens from headers, query strings, and request bodies with full async support.

Features

• 3 token sources — Authorization header, query string, request body
• Async-ready — tokenCheckCallback and requestParameterCheck support both sync and async functions
• RFC 6750 compliant — automatic WWW-Authenticate error responses
• Zero dependencies — only Express as a peer dependency
• TypeScript included — ships with type definitions out of the box
• ESM & CJS — works with import and require
• Express 4 & 5 — compatible with both major versions

Installation

npm i bearer-token-parser

// ESM
import {BearerParser, BearerValidator} from 'bearer-token-parser';

// CommonJS
const {BearerParser, BearerValidator} = require('bearer-token-parser');

Quick Start

Protect any Express route with Bearer token authentication in just a few lines. Pass BearerValidator.validation() as route middleware — it extracts the token, runs your check, and rejects invalid requests with proper WWW-Authenticate headers automatically.

import express from 'express';
import {BearerParser, BearerValidator} from 'bearer-token-parser';

const app = express();

app.get('/api/protected', [
  BearerValidator.validation({
    realm: 'my-api',
    tokenCheckCallback: async (token) => {
      // Verify token against your database, JWT, etc.
      // Return true if valid, false otherwise.
      const user = await db.findUserByToken(token);
      return user != null;
    },
  })
], (req, res) => {
  // Token is valid — extract it if needed.
  const token = BearerParser.parseBearerToken(req);
  res.json({authenticated: true, token});
});

How It Works

This library provides two classes:

BearerValidator creates Express middleware that validates Bearer tokens and automatically responds with RFC 6750-compliant WWW-Authenticate headers on failure.

BearerParser extracts Bearer tokens from requests. Used internally by BearerValidator, but also available for standalone use — it only needs a plain request object with headers, query, or body.

Validation Flow

When all checks pass, the middleware calls next() and your route handler receives the request as normal.

Error Responses

On failure, the middleware responds via BearerValidator.resWithWwwAuthenticate() with a WWW-Authenticate header following RFC 6750:

HTTP Status	WWW-Authenticate	When
401	Bearer realm="…", error="token_required"	Token source is missing (no header / no query param / no body param)
401	Bearer realm="…", error="invalid_token", error_description="Token format error"	Token is empty or has an invalid format
401	Bearer realm="…", error="invalid_token", error_description="Token cannot be authenticated"	tokenCheckCallback returned false
400	Bearer realm="…", error="invalid_request"	requestParameterCheck returned false

Usage Examples

Token from Authorization Header (default)

import express from 'express';
import {BearerValidator} from 'bearer-token-parser';

const app = express();

app.get('/api/resource', [
  // Validate the Bearer token from the Authorization header.
  BearerValidator.validation({
    realm: 'my-api',
    // Check if the token matches the expected value.
    tokenCheckCallback: token => token === process.env.API_TOKEN,
  })
], (req, res) => {
  // Only reached when the token is valid.
  res.json({ok: true});
});

curl -H "Authorization: Bearer <token>" http://localhost:3000/api/resource

Token from Query Parameter

import express from 'express';
import {BearerValidator} from 'bearer-token-parser';

const app = express();

app.get('/api/resource', [
  // Validate the token from the query string (?api_key=...).
  BearerValidator.validation({
    tokenLocation: 'query',
    tokenParameter: 'api_key',
    realm: 'my-api',
    tokenCheckCallback: token => token === process.env.API_TOKEN,
  })
], (req, res) => {
  res.json({ok: true});
});

curl http://localhost:3000/api/resource?api_key=<token>

Token from Request Body

import express from 'express';
import {BearerValidator} from 'bearer-token-parser';

const app = express();

app.post('/api/resource', [
  // Validate the token from the JSON body ({ "access_token": "..." }).
  BearerValidator.validation({
    tokenLocation: 'body',
    tokenParameter: 'access_token',
    realm: 'my-api',
    tokenCheckCallback: token => token === process.env.API_TOKEN,
  })
], (req, res) => {
  res.json({ok: true});
});

curl -X POST -H "Content-Type: application/json" \
  -d '{"access_token":"<token>"}' \
  http://localhost:3000/api/resource

With Request Parameter Validation

You can add a second validation layer using requestParameterCheck to validate request body fields after the token is verified:

import express from 'express';
import {BearerValidator} from 'bearer-token-parser';
import {body, validationResult} from 'express-validator';

const app = express();

app.post('/api/users', [
  body('email').isEmail(),
  body('name').isLength({min: 1, max: 50}),

  BearerValidator.validation({
    realm: 'my-api',
    // Verify the token (async supported).
    tokenCheckCallback: async (token) => {
      const user = await db.findUserByToken(token);
      return user != null;
    },
    // Validate request params after token passes.
    // Return false to respond with 400 invalid_request.
    requestParameterCheck: (req) => {
      return validationResult(req).isEmpty();
    },
  })
], async (req, res) => {
  res.json({created: true});
});

Standalone Token Parsing (without validation)

BearerParser can be used on its own — it only needs a request object with headers, query, or body:

import {BearerParser} from 'bearer-token-parser';

// Extract from the Authorization header ("Bearer <token>").
const headerToken = BearerParser.parseBearerTokenHeader(req);

// Extract from a query parameter (?access_token=...).
const queryToken = BearerParser.parseBearerTokenQuery(req, 'access_token');

// Extract from the request body ({ "access_token": "..." }).
const bodyToken = BearerParser.parseBearerTokenBody(req, 'access_token');

// Each returns the token string, or undefined if not found / invalid format.

API Reference

BearerParser

Utility class for extracting Bearer tokens from HTTP requests.

BearerParser.parseBearerToken(req)

Alias for parseBearerTokenHeader.

BearerParser.parseBearerTokenHeader(req)

Extracts a Bearer token from the Authorization request header. Parses the header value matching the pattern Bearer <token> and returns the token portion.

Parameter	Type	Description
req	Request | {headers: {authorization?: string}}	The request object

Returns: string | undefined — The extracted token, or undefined if the header is missing or the format is invalid.

BearerParser.parseBearerTokenQuery(req, tokenParameter?)

Extracts a Bearer token from a query string parameter.

Parameter	Type	Default	Description
req	Request | {query: {[key: string]: any}}		The request object
tokenParameter	string	'access_token'	The query parameter name

Returns: string | undefined

BearerParser.parseBearerTokenBody(req, tokenParameter?)

Extracts a Bearer token from the request body.

Parameter	Type	Default	Description
req	Request | {body: {[key: string]: any}}		The request object
tokenParameter	string	'access_token'	The body parameter name

Returns: string | undefined

BearerValidator

Express middleware for Bearer token authentication.

BearerValidator.validation(options)

Creates an Express middleware that validates Bearer tokens. Extracts a token from the configured location, validates it, and either calls next() on success or responds with a 401/400 status and WWW-Authenticate header on failure.

Option	Type	Default	Description
tokenLocation	'header' | 'query' | 'body'	'header'	Where to extract the token from
tokenParameter	string	'access_token'	Parameter name for query/body tokens. Required when tokenLocation is 'query' or 'body'.
realm	string	''	Realm name included in the WWW-Authenticate response header
tokenCheckCallback	(token: string) => boolean | Promise<boolean>	—	Validates the extracted token. Supports sync and async functions.
requestParameterCheck	(req: Request) => boolean | Promise<boolean>	—	Validates request parameters after token verification. Supports sync and async functions.

Returns: Express middleware function (req, res, next) => Promise<void>

Throws: TypeError if tokenLocation is 'query' or 'body' and tokenParameter is empty.

BearerValidator.resWithWwwAuthenticate(res, statusCode, realm, error?, errorDescription?)

Sends an HTTP response with a WWW-Authenticate header following RFC 6750. Can be used directly for custom error responses.

Parameter	Type	Description
res	Response	The Express response object
statusCode	number	HTTP status code (e.g., 401, 400)
realm	string	Realm name for the WWW-Authenticate header
error	string?	Error code (e.g., 'invalid_token')
errorDescription	string?	Human-readable error description

// Custom error response example
BearerValidator.resWithWwwAuthenticate(res, 401, 'my-api', 'invalid_token', 'The token has expired');
// => WWW-Authenticate: Bearer realm="my-api", error="invalid_token", error_description="The token has expired"

BearerValidatorOptions

TypeScript interface for the validation() options. Available as a named export for type-safe configuration:

import {BearerValidator, BearerValidatorOptions} from 'bearer-token-parser';

const options: BearerValidatorOptions = {
  tokenLocation: 'header',
  realm: 'my-api',
  tokenCheckCallback: async (token) => {
    // Your validation logic.
    return token === process.env.API_TOKEN;
  },
};

app.use('/api', BearerValidator.validation(options));

Changelog

See CHANGELOG.md.

Author

shumatsumonobu

• github/shumatsumonobu
• X/shumatsumonobu

License

MIT