or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-passport-local

Local username and password authentication strategy for Passport.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/passport-local@1.0.x

To install, run

npx @tessl/cli install tessl/npm-passport-local@1.0.0

index.mddocs/

Passport Local

Passport Local provides a local username and password authentication strategy for the Passport authentication middleware. It enables traditional credential-based authentication in Node.js applications using Connect-style middleware frameworks like Express.

Package Information

  • Package Name: passport-local
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install passport-local

Core Imports

const LocalStrategy = require('passport-local').Strategy;

Or using the default export:

const LocalStrategy = require('passport-local');

Basic Usage

const passport = require('passport');
const LocalStrategy = require('passport-local').Strategy;

passport.use(new LocalStrategy(
  function(username, password, done) {
    User.findOne({ username: username }, function (err, user) {
      if (err) { return done(err); }
      if (!user) { return done(null, false); }
      if (!user.verifyPassword(password)) { return done(null, false); }
      return done(null, user);
    });
  }
));

// Authenticate requests
app.post('/login', 
  passport.authenticate('local', { failureRedirect: '/login' }),
  function(req, res) {
    res.redirect('/');
  });

Capabilities

Strategy Constructor

Creates a new local authentication strategy instance.

/**
 * Local authentication strategy constructor
 * @param {Object} options - Configuration options (optional)
 * @param {Function} verify - Callback function that verifies username/password
 */
function Strategy(options, verify);

// Constructor overload - when options is omitted
function Strategy(verify);

Options

interface StrategyOptions {
  /** Field name where the username is found, defaults to 'username' */
  usernameField?: string;
  /** Field name where the password is found, defaults to 'password' */
  passwordField?: string;
  /** When true, req is the first argument to the verify callback (default: false) */
  passReqToCallback?: boolean;
}

Verify Callback

/**
 * Verify callback function for authenticating credentials
 * @param {string} username - Username from request
 * @param {string} password - Password from request
 * @param {Function} done - Callback to complete authentication
 */
function verifyCallback(username, password, done);

/**
 * Verify callback function with request object (when passReqToCallback is true)
 * @param {Object} req - HTTP request object
 * @param {string} username - Username from request
 * @param {string} password - Password from request
 * @param {Function} done - Callback to complete authentication
 */
function verifyCallbackWithReq(req, username, password, done);

Done Callback

/**
 * Authentication completion callback
 * @param {Error|null} err - Error if authentication failed due to error
 * @param {Object|false} user - User object if authentication succeeded, false if failed
 * @param {Object} info - Additional info object (optional)
 */
function doneCallback(err, user, info);

Strategy Properties

class Strategy {
  /** Strategy name, always 'local' */
  name: string;
}

Authentication Method

The authenticate method is called internally by Passport and should not be called directly.

/**
 * Authenticate request based on form submission contents
 * @param {Object} req - HTTP request object
 * @param {Object} options - Authentication options
 */
Strategy.prototype.authenticate(req, options);

Authentication Options

interface AuthenticateOptions {
  /** Custom message for missing credentials (default: 'Missing credentials') */
  badRequestMessage?: string;
}

Error Handling

The strategy handles the following error scenarios:

  • Missing verify callback: Throws TypeError if verify callback is not provided to constructor
  • Missing credentials: Returns 400 Bad Request with configurable message when username or password is missing
  • Authentication failure: Calls this.fail() when verify callback returns false for user
  • Runtime errors: Calls this.error() when verify callback throws an exception

Integration with Passport

// Register the strategy
passport.use(new LocalStrategy(verifyCallback));

// Use in routes
app.post('/login', passport.authenticate('local', options));

The strategy integrates with Passport's standard authentication flow:

  1. Extracts username/password from request body or query parameters
  2. Calls the provided verify callback with credentials
  3. Handles the authentication result via Passport's success/fail/error methods

Field Extraction

Credentials are extracted from the request in the following order:

  1. From req.body using the configured field names
  2. From req.query using the configured field names (fallback)

The field extraction supports nested field paths using bracket notation (e.g., user[name]).