Architecture Note: Using Passport.js Local Strategy in a Node.js REST API

Requirements

The Local Strategy authenticates by verifying a username and password against a trusted user store and then relies on server‑side sessions to maintain state. Therefore the application must:

• Enable express-session with secure cookie options (HttpOnly, SameSite, Secure in production).
• Validate credentials against a trusted source (e.g., bcrypt‑hashed passwords in a database).
• Ensure the Node.js process can access the chosen session store (memory for dev, Redis or similar for prod).

Smallest Suitable Design

A minimal implementation consists of four steps:

1. Initialize Passport and session middleware:

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

const app = express();
app.use(session({
  secret: process.env.SESSION_SECRET || 'dev-secret',
  resave: false,
  saveUninitialized: false,
  cookie: { httpOnly: true, secure: process.env.NODE_ENV === 'production', sameSite: 'lax' }
}));
app.use(passport.initialize());
app.use(passport.session());

1. Define the LocalStrategy verify function:

passport.use(new LocalStrategy(async (username, password, done) => {
  try {
    // Replace with actual user lookup
    const user = await getUserByUsername(username);
    if (!user) { return done(null, false); }
    const match = await bcrypt.compare(password, user.passwordHash);
    if (!match) { return done(null, false); }
    return done(null, { id: user.id, username: user.username });
  } catch (err) {
    return done(err);
  }
}));

1. Serialize and deserialize only a non‑sensitive identifier:

passport.serializeUser((user, done) => done(null, user.id));
passport.deserializeUser(async (id, done) => {
  try {
    const user = await getUserById(id);
    done(null, user ? { id: user.id, username: user.username } : false);
  } catch (err) {
    done(err);
  }
});

1. Protect routes with ensureAuthenticated middleware:

function ensureAuthenticated(req, res, next) {
  if (req.isAuthenticated()) { return next(); }
  res.status(401).json({ error: 'Unauthorized' });
}

app.post('/login', passport.authenticate('local', { failureRedirect: '/login-failure' }), (req, res) => {
  res.json({ message: 'Logged in' });
});

app.get('/profile', ensureAuthenticated, (req, res) => {
  res.json({ user: req.user });
});

Trust/Data Boundaries

The verify function receives raw username and password from the request body; treat them as untrusted input. Sanitize or validate length and character set before passing them to the user‑lookup query to avoid injection attacks. Only the minimal user object (ID and username) should be passed to done(null, user). Storing passwords, tokens, or other sensitive data in the serialized user expands the impact of a compromised session store. The session cookie is the trust boundary between client and server. In production it must carry the attributes HttpOnly, Secure, and SameSite=Lax (or Strict) to prevent client‑side script access and mitigate CSRF.

Operational Checks and Failure Modes

• Failed authentication: The verify function calls done(null, false); Passport responds with a 401 (or redirects to /login-failure).
• Session store loss: If Redis disconnects, existing sessions become invalid, forcing users to log in again. Implement a health check on the store and alert on disconnect.
• Replay attacks: Mitigate by rotating the session ID after login (req.session.regenerate) and limiting concurrent sessions per user.
• DoS via login endpoint: Apply rate‑limiting (e.g., express-rate-limit) to the /login route.

Conditions That Would Change the Design

• If the API must serve stateless clients (mobile apps, SPAs without cookie support), replace the Local Strategy with a token‑based approach (JWT or opaque tokens) and remove session middleware.
• When regulatory requirements forbid server‑side storage of session data, move to encrypted signed cookies or short‑lived tokens.
• If the user store evolves to federated identity (OAuth, SAML), replace the Local Strategy with the appropriate Strategy while keeping the serialize/deserialize pattern.

Practical Verification Steps

1. Install dependencies: npm install passport passport-local express-session bcrypt (run in the project directory).
2. Set environment variables: SESSION_SECRET, NODE_ENV=production for secure cookie flags.
3. Start the server: node server.js (requires permission to bind to the chosen port, e.g., 3000).
4. Using curl from a terminal, test login:

   curl -X POST http://localhost:3000/login \
     -H "Content-Type: application/json" \
     -d '{"username":"alice","password":"secret"}' \
     -v
   

   Expect a Set-Cookie header containing HttpOnly, Secure (if NODE_ENV=production), and SameSite. A successful login returns JSON with a success message.
5. Request a protected route with the cookie:

   curl http://localhost:3000/profile -b "connect.sid=" -v
   

   Expect a 200 response and the user JSON.
6. Clear the cookie or call a logout endpoint (req.logout()) and repeat the protected request; you should receive 401.
7. To simulate a session‑store failure, stop the Redis instance (if used) and verify that existing sessions no longer authenticate, prompting a re‑login.

Limitations

The Local Strategy is tightly coupled to server‑side sessions, which adds infrastructure complexity (session store, replication, backup). It does not suit purely token‑based APIs or environments where cookies cannot be used (e.g., certain CORS‑restricted cross‑domain calls). Scaling horizontally requires a shared, fault‑tolerant session store; otherwise, authentication state is lost on node restarts.