Passport HTTP Bearer Strategy (SuperLogin Fork)

Common errors

• TypeError: HTTPBearerStrategy requires a verify callback

  cause The `BearerStrategy` constructor was called without providing the essential `verify` callback function.
  fix Pass a function as the second argument (or first, if no options object) to the `BearerStrategy` constructor: `new BearerStrategy(function(token, done) { /* ... */ })`.

• ReferenceError: BearerStrategy is not defined

  cause The `BearerStrategy` class was used without being correctly imported or required from the package.
  fix For CommonJS, use `const { Strategy: BearerStrategy } = require('passport-http-bearer-sl');`. For ESM (if transpiled), use `import { Strategy as BearerStrategy } from 'passport-http-bearer-sl';`.

• Unauthorized / 401 response when providing `access_token` in URL query

  cause This fork expects `bearer_token` in the query string or `Authorization` header, not `access_token`, due to its specific modification for SuperLogin.
  fix Send the token via the `Authorization: Bearer <token>` header or use the `bearer_token` query/body parameter instead of `access_token`.

Warnings

• breaking This fork changes the expected query parameter for the bearer token from `access_token` (used by the original `passport-http-bearer`) to `bearer_token` to avoid conflicts with OAuth providers. Code expecting `access_token` in query parameters will break.
  Fix: Ensure clients send the bearer token in the `Authorization` header as `Bearer <token>` or as a `bearer_token` query/body parameter, not `access_token`.
• gotcha The package is effectively abandoned with no recent updates or maintenance since 2017. This implies potential compatibility issues with newer Node.js versions or security vulnerabilities that will not be patched.
  Fix: For new projects, consider using the original `passport-http-bearer` (which is actively maintained) or a more recent alternative. If you must use this package, thoroughly audit its code and dependencies for security flaws.
• gotcha Like all Passport strategies, `passport-http-bearer-sl` requires a `verify` callback function. Failing to provide this callback will result in a `TypeError` during strategy initialization.
  Fix: Always provide a `verify` callback function to the `BearerStrategy` constructor that handles token validation and calls the `done` callback.
• gotcha Passport's core `session` vulnerability (CVE-2022-25896) affects Passport versions prior to 0.6.0. While this package is a strategy, its usage with an outdated Passport core could expose applications to session fixation attacks.
  Fix: Ensure your core `passport` package dependency is updated to version `0.6.0` or later to mitigate session fixation vulnerabilities. Even with `session: false` this is good practice.

Install

• npm install passport-http-bearer-sl npm
• yarn add passport-http-bearer-sl yarn
• pnpm add passport-http-bearer-sl pnpm

Imports

• BearerStrategy
  wrong:

  import BearerStrategy from 'passport-http-bearer-sl';
  // or:
  const BearerStrategy = require('passport-http-bearer-sl');

  correct:

  import { Strategy as BearerStrategy } from 'passport-http-bearer-sl';
  // or for CommonJS:
  const BearerStrategy = require('passport-http-bearer-sl').Strategy;

  The package exports a named `Strategy` class. For clarity, it's common practice to rename it to `BearerStrategy`. Primarily designed for CommonJS due to its age.
• passport.authenticate
  wrong:

  app.get('/api/resource', passport.authenticate('bearer'), (req, res) => { /* ... */ });

  correct:

  app.get('/api/resource', passport.authenticate('bearer', { session: false }), (req, res) => { /* ... */ });

  When using bearer tokens for APIs, sessions are typically not required, so `session: false` should be explicitly set for stateless authentication.
• passport.use
  wrong:

  passport.use('bearer-sl', new BearerStrategy(function(token, done) { /* ... */ }));

  correct:

  passport.use(new BearerStrategy(function(token, done) { /* ... */ }));

  While you can name the strategy, 'bearer' is the conventional name for HTTP Bearer strategies, allowing `passport.authenticate('bearer')` to work without specifying the custom name.

Quickstart

This quickstart demonstrates how to configure and use `passport-http-bearer-sl` with Express.js to protect an API endpoint using a bearer token, showing token verification and access to user data.

const express = require('express');
const passport = require('passport');
const { Strategy: BearerStrategy } = require('passport-http-bearer-sl');

const app = express();
app.use(passport.initialize());

// Simulate a User database
const users = [{
  id: 1,
  username: 'testuser',
  token: 'supersecrettoken123',
  scope: ['read', 'write']
}];

passport.use(new BearerStrategy(
  function(token, done) {
    // In a real application, you would fetch the user from a database
    // based on the provided bearer token.
    const user = users.find(u => u.token === token);
    if (!user) { return done(null, false); }
    // Optional info can be passed, typically including associated scope
    return done(null, user, { scope: user.scope });
  }
));

app.get('/profile', 
  passport.authenticate('bearer', { session: false }),
  function(req, res) {
    // req.user contains the authenticated user
    // req.authInfo contains the optional info from the strategy (e.g., scope)
    res.json({
      message: `Welcome, ${req.user.username}!`, 
      user: req.user,
      authInfo: req.authInfo
    });
  }
);

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
  console.log('Test with: curl -H "Authorization: Bearer supersecrettoken123" http://localhost:3000/profile');
  console.log('Test with invalid token: curl -H "Authorization: Bearer wrongtoken" http://localhost:3000/profile');
});