Passport HTTP Header Token

Common errors

• TypeError: Strategy must be a function

  cause The `HTTPHeaderTokenStrategy` was not properly imported or instantiated as a class before being passed to `passport.use()`.
  fix Ensure you are requiring the `Strategy` property from the package and instantiating it with `new`: `const HTTPHeaderTokenStrategy = require('passport-http-header-token').Strategy; passport.use(new HTTPHeaderTokenStrategy(...));`

• Error: Unknown authentication strategy "http-header-token"

  cause The `passport-http-header-token` strategy has not been registered with Passport using `passport.use()` before `passport.authenticate()` is called.
  fix Verify that `passport.use(new HTTPHeaderTokenStrategy(...))` is executed before any routes or middleware that use `passport.authenticate('http-header-token', ...)`. Also check for typos in the strategy name.

• Authentication Failed (or similar log/response for incorrect token)

  cause The token provided by the client does not match any known user, or the `verify` callback returned `done(null, false)`.
  fix Check the token sent in the HTTP header by the client. Ensure your `verify` callback logic correctly retrieves and validates the token against your user data. Remember this strategy expects a raw token, not 'Bearer <token>' unless you parse it.

Warnings

• breaking This package is effectively abandoned, with the last publish date over 10 years ago (June 2016). It has not received any updates or security patches since. Using unmaintained software carries significant security risks and may not be compatible with modern Node.js versions or best practices.
  Fix: Consider migrating to actively maintained alternatives like `passport-http-bearer` (for standard bearer tokens) or `passport-jwt` (for JSON Web Tokens). If custom header token behavior is required, `passport-http-custom-bearer` is another option. Evaluate the security implications carefully if continued use is unavoidable.
• gotcha Unlike `passport-http-bearer`, this strategy expects the raw token value directly in the specified HTTP header (defaulting to 'Authorization'). It does not parse standard 'Bearer <token>' or other scheme-prefixed formats. Providing 'Bearer <token>' will pass 'Bearer <token>' as the token value to your verify callback.
  Fix: Ensure your client sends only the raw token value (e.g., `Authorization: mysecrettoken123`) or modify your `verify` callback to parse the incoming header string if it includes a scheme. For standard bearer token parsing (e.g., `Authorization: Bearer <token>`), use `passport-http-bearer` instead.
• gotcha This package is CommonJS-only and does not provide native ESM exports. Attempting to `import { Strategy } from 'passport-http-header-token'` in an ESM module will result in an error.
  Fix: Use CommonJS `require` syntax: `const HTTPHeaderTokenStrategy = require('passport-http-header-token').Strategy;` in your Node.js application.
• gotcha This package does not ship with TypeScript type definitions, nor are official types available on `@types/passport-http-header-token`. This necessitates manual type declarations or `@ts-ignore` usage in TypeScript projects.
  Fix: Create a `d.ts` declaration file (e.g., `passport-http-header-token.d.ts`) with basic types for the strategy. Example: `declare module 'passport-http-header-token' { class Strategy extends require('passport').Strategy { constructor(verify: (token: string, done: (err: any, user?: any, info?: any) => void) => void); } export { Strategy }; }`
• gotcha For API authentication using tokens, sessions are typically not needed and should be explicitly disabled to prevent unexpected behavior or session cookies being set. The default Passport behavior often involves sessions.
  Fix: When authenticating requests, always specify `{ session: false }` in the `passport.authenticate()` options: `passport.authenticate('http-header-token', { session: false, ... })`.

Install

• npm install passport-http-header-token npm
• yarn add passport-http-header-token yarn
• pnpm add passport-http-header-token pnpm

Imports

• Strategy
  wrong:

  import { Strategy } from 'passport-http-header-token';

  correct:

  const HTTPHeaderTokenStrategy = require('passport-http-header-token').Strategy;

  The package is CommonJS-only and does not provide an ESM export for `Strategy`.
• passport
  wrong:

  import passport from 'passport';

  correct:

  const passport = require('passport');

  Passport.js itself, like this strategy, is primarily CommonJS and typically imported via `require` in older Node.js projects.
• configure strategy
  wrong:

  passport.use('http-header-token', /* ... */);

  correct:

  passport.use(new HTTPHeaderTokenStrategy( /* ... */ ));

  The strategy is typically instantiated and passed directly to `passport.use()` or named explicitly (e.g., `'token'`) as the first argument.

Quickstart

Demonstrates how to set up and use `passport-http-header-token` in an Express application to authenticate requests using a token provided in the 'Authorization' header.

const express = require('express');
const passport = require('passport');
const HTTPHeaderTokenStrategy = require('passport-http-header-token').Strategy;

const app = express();

// Mock User database for demonstration
const users = [{
  id: 1,
  username: 'testuser',
  token: 'mysecrettoken123'
}];

passport.use(new HTTPHeaderTokenStrategy(
  function(token, done) {
    // In a real application, you would query your database here
    // for a user associated with the provided token.
    console.log(`Attempting to authenticate with token: ${token}`);
    const user = users.find(u => u.token === token);

    if (!user) {
      return done(null, false, { message: 'Incorrect token.' });
    }
    return done(null, user);
  }
));

app.use(passport.initialize());

app.get('/api/protected', 
  passport.authenticate('http-header-token', { session: false, failureMessage: true }),
  function(req, res) {
    res.json({ message: `Access granted, user: ${req.user.username}` });
  }
);

app.get('/', (req, res) => {
  res.send('Welcome! Try GET /api/protected with an Authorization header like: Authorization: mysecrettoken123');
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log('Test with: curl -H "Authorization: mysecrettoken123" http://localhost:3000/api/protected');
  console.log('Test failure with: curl -H "Authorization: wrongtoken" http://localhost:3000/api/protected');
});