or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-authentication.mdindex.mdsession-management.mdstrategy-development.md
tile.json

tessl/npm-passport

Simple, unobtrusive authentication for Node.js

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

To install, run

npx @tessl/cli install tessl/npm-passport@0.7.0

index.mddocs/

Passport

Passport is a comprehensive Express-compatible authentication middleware for Node.js that provides a complete authentication framework through an ecosystem of 480+ strategies. It serves as a lightweight, unobtrusive authentication layer that handles request authentication without imposing database schema constraints or mounting routes, giving developers maximum flexibility in application architecture.

Package Information

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

Core Imports

const passport = require("passport");

For ES modules:

import passport from "passport";

Access to constructors and strategies:

const { Passport, Strategy } = require("passport");
// or
import { Passport, Strategy } from "passport";

Basic Usage

const express = require("express");
const session = require("express-session");
const passport = require("passport");
const LocalStrategy = require("passport-local").Strategy;

const app = express();

// Configure express-session middleware
app.use(session({
  secret: "keyboard cat",
  resave: false,
  saveUninitialized: false
}));

// Initialize Passport
app.use(passport.initialize());
app.use(passport.session());

// Configure user serialization
passport.serializeUser((user, done) => {
  done(null, user.id);
});

passport.deserializeUser((id, done) => {
  // Load user from database
  User.findById(id, (err, user) => {
    done(err, user);
  });
});

// Register authentication strategy
passport.use(new LocalStrategy(
  (username, password, done) => {
    // Verify credentials
    User.findOne({ username }, (err, user) => {
      if (err) return done(err);
      if (!user || !user.validatePassword(password)) {
        return done(null, false, { message: "Invalid credentials" });
      }
      return done(null, user);
    });
  }
));

// Protected route
app.post("/login",
  passport.authenticate("local", {
    successRedirect: "/dashboard",
    failureRedirect: "/login"
  })
);

Architecture

Passport is built around several key components:

  • Authenticator: Core class managing strategies, serialization, and middleware generation
  • Strategies: Pluggable authentication mechanisms (local, OAuth, etc.)
  • Session Management: User serialization/deserialization for persistent login sessions
  • Middleware System: Express/Connect compatible middleware for authentication flow
  • Request Extensions: Helper methods added to HTTP request objects

Capabilities

Core Authentication

Main authentication functionality including strategy management, middleware creation, and request processing. This is the primary interface for integrating Passport into applications.

// Default singleton instance
const passport = require("passport");

// Strategy management
passport.use(name, strategy);
passport.use(strategy);
passport.unuse(name);

// Middleware generation
passport.initialize(options);
passport.authenticate(strategy, options, callback);
passport.authorize(strategy, options, callback);
passport.session(options);

Core Authentication

Session Management

User session handling including login/logout operations and user serialization/deserialization for persistent authentication state across requests.

// User serialization/deserialization
passport.serializeUser(fn);
passport.deserializeUser(fn);

// Request methods (added by Passport)
req.logIn(user, options, callback);
req.logOut(options, callback);
req.isAuthenticated();
req.isUnauthenticated();

Session Management

Strategy Development

Framework for creating custom authentication strategies and understanding the strategy interface for advanced authentication scenarios.

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

class CustomStrategy extends Strategy {
  constructor(options, verify) {
    super();
    this.name = "custom";
    // Strategy implementation
  }
  
  authenticate(req, options) {
    // Authentication logic
    this.success(user, info);
    this.fail(challenge, status);
    this.redirect(url, status);
    this.pass();
    this.error(err);
  }
}

Strategy Development

Types

interface AuthenticateOptions {
  session?: boolean;
  keepSessionInfo?: boolean;
  successRedirect?: string;
  failureRedirect?: string;
  successFlash?: boolean | string | { type: string; message: string };
  failureFlash?: boolean | string | { type: string; message: string };
  successMessage?: boolean | string;
  failureMessage?: boolean | string;
  failWithError?: boolean;
  assignProperty?: string;
  authInfo?: boolean;
  successReturnToOrRedirect?: string;
}

interface InitializeOptions {
  userProperty?: string;
  compat?: boolean;
}

interface SerializationCallback {
  (err: Error | null, user?: any): void;
}

interface DeserializationCallback {
  (err: Error | null, user?: any): void;
}

interface VerifyCallback {
  (err: Error | null, user?: any, info?: any): void;
}

class AuthenticationError extends Error {
  constructor(message: string, status?: number);
  name: "AuthenticationError";
  message: string;
  status: number;
}

interface SessionManagerOptions {
  key?: string;
  keepSessionInfo?: boolean;
}

interface LogInOptions {
  session?: boolean;
  keepSessionInfo?: boolean;
}

interface LogOutOptions {
  keepSessionInfo?: boolean;
}

interface TransformAuthInfoCallback {
  // Synchronous (arity 1)
  (info: any): any;
  // Asynchronous (arity 2)  
  (info: any, done: (err: Error | null, transformedInfo?: any) => void): void;
  // With request access (arity 3)
  (req: any, info: any, done: (err: Error | null, transformedInfo?: any) => void): void;
}

interface FrameworkAdapter {
  initialize(passport: any, options?: any): Function;
  authenticate(passport: any, name?: string | string[], options?: any, callback?: Function): Function;
}

// External dependencies (not part of Passport core)
interface UtilsMerge {
  (dest: any, src: any): any;
}

interface PauseStream {
  (stream: any): any;
}

interface PassportStrategy {
  name: string;
  authenticate(req: any, options?: any): void;
}