Passport Strategy Base Class

Common errors

• TypeError: Strategy is not a constructor

  cause Attempting to use `new Strategy()` after incorrectly importing it as a named export in CommonJS, or a general incorrect import path.
  fix In CommonJS, ensure you use `const Strategy = require('passport-strategy');`. In ESM/TypeScript, ensure your transpilation handles `module.exports` correctly, often `import Strategy from 'passport-strategy';` is needed, or potentially `import { Strategy } from 'passport-strategy';` if tooling assumes named export behavior.

• TypeError: Strategy#authenticate must be overridden by subclass

  cause You are attempting to use the abstract `Strategy` class directly without extending it and implementing your own `authenticate` method.
  fix Create a subclass that extends `Strategy` and provides its own `authenticate(req, options)` method with your authentication logic. `class MyStrategy extends Strategy { authenticate(req, options) { /* ... */ } }`

• TypeError: Cannot read properties of undefined (reading 'user') on req.user after authentication

  cause This typically indicates that `passport.initialize()` and/or `passport.session()` middleware are not correctly configured, or `passport.serializeUser`/`deserializeUser` are missing or misconfigured, preventing the authenticated user from being attached to the request.
  fix Verify that `app.use(passport.initialize());` and `app.use(passport.session());` (if using sessions) are correctly placed before any routes that require authentication. Also, ensure `passport.serializeUser` and `passport.deserializeUser` are implemented to manage user sessions.

Warnings

• breaking The `passport-strategy` package (v1.0.0) is very old, last published in 2013, and has not received updates in over a decade. While still functional as a base class, developers should be aware that it might not align with the latest Node.js features, security best practices, or modern JavaScript syntax (e.g., pure ESM).
  Fix: Consider using newer alternatives or explicitly reviewing the base `Strategy` implementation within the currently maintained `passport` package itself or derived strategies. For new projects, ensure compatibility with the `passport` version you are using. There is also `@passport-next/passport-strategy` (v1.1.0, published 2018) which offers a slightly newer base.
• gotcha `passport-strategy` exports the `Strategy` constructor directly as `module.exports`, not as a named export. Attempting `const { Strategy } = require('passport-strategy');` in CommonJS environments will result in `undefined` for `Strategy`.
  Fix: For CommonJS, use `const Strategy = require('passport-strategy');` to correctly import the constructor. For ESM/TypeScript, `import Strategy from 'passport-strategy';` or `import { Strategy } from 'passport-strategy';` might be transpiled to work, but direct CommonJS interoperability should use the default import pattern.
• gotcha The `Strategy` class is abstract and *must* be subclassed. Instantiating `new Strategy()` directly and calling `authenticate()` without overriding it will result in an error or unexpected behavior, as the abstract `authenticate` method is not implemented in the base class.
  Fix: Always extend `Strategy` and provide your own `authenticate` method in the subclass. For example: `class CustomStrategy extends Strategy { authenticate(req, options) { /* ... */ } }` or `util.inherits(CustomStrategy, Strategy); CustomStrategy.prototype.authenticate = function(...) { /* ... */ };`.
• gotcha This package only provides the base class. To use custom strategies within an application, you must also install and configure the main `passport` package, including its middleware (`passport.initialize()` and `passport.session()`) and `serializeUser`/`deserializeUser` functions for session management.
  Fix: Ensure `passport` and `express-session` (if using sessions) are installed and correctly configured in your application. Register your custom strategy using `passport.use(new MyStrategy());` and set up session serialization/deserialization.

Install

• npm install passport-strategy npm
• yarn add passport-strategy yarn
• pnpm add passport-strategy pnpm

Imports

• Strategy
  wrong:

  const Strategy = require('passport-strategy').Strategy;

  correct:

  import { Strategy } from 'passport-strategy';

  While the package is primarily CommonJS, modern TypeScript/ESM projects often use `import` syntax, with bundlers handling the interop. The constructor is the default export.
• Strategy (CommonJS)
  wrong:

  const { Strategy } = require('passport-strategy');

  correct:

  const Strategy = require('passport-strategy');

  In CommonJS, the `Strategy` constructor is the direct module.exports, not a named export. Many examples mistakenly try to destructure it.

Quickstart

This quickstart demonstrates how to define a custom authentication strategy by subclassing the `Strategy` abstract class, overriding its `authenticate` method, and registering it with Passport.js. It shows a simplified 'always success' scenario and how the base class's success method is called.

const util = require('util');
const Strategy = require('passport-strategy');

/**
 * A simple custom strategy extending passport-strategy.
 * This example demonstrates a basic 'always success' strategy.
 */
function CustomAlwaysSuccessStrategy(options) {
  Strategy.call(this);
  this.name = 'custom-always-success';
  this._options = options || {};
}

util.inherits(CustomAlwaysSuccessStrategy, Strategy);

/**
 * The authenticate method must be overridden by subclasses.
 * It performs the actual authentication logic.
 */
CustomAlwaysSuccessStrategy.prototype.authenticate = function(req, options) {
  // In a real strategy, you would parse credentials from req,
  // interact with a database, call an external API, etc.
  // For this example, we simply succeed immediately with a dummy user.
  const user = { id: '123', name: 'Test User' };
  const info = { message: 'Authentication successful with custom strategy.' };

  // Call one of the action functions provided by the base Strategy class.
  // This indicates the outcome of the authentication attempt.
  this.success(user, info);

  // Other possible outcomes:
  // this.fail({ message: 'Invalid credentials' }, 401);
  // this.redirect('/login', 302);
  // this.pass(); // defer to next strategy
  // this.error(new Error('Something went wrong'));
};

// Example usage with Passport.js (requires 'passport' package)
const passport = require('passport');
passport.use(new CustomAlwaysSuccessStrategy());

// To test, imagine an Express route:
// app.get('/auth/custom', passport.authenticate('custom-always-success', { session: false }), (req, res) => {
//   res.json({ message: 'Logged in!', user: req.user });
// });

// For demonstration, let's manually 'authenticate' (without Express context)
// In a real app, this would be handled by Passport middleware.
const dummyReq = {}; // Simulate an Express request object
const strategyInstance = new CustomAlwaysSuccessStrategy();
strategyInstance.authenticate(dummyReq, {}, (err, user, info) => {
  if (user) {
    console.log('Authentication successful:', user, info);
  } else {
    console.error('Authentication failed:', err || info);
  }
});