Passport.js serializeUser/deserializeUser lacks built‑in schema‑version guard

Direct answer

Embed a tiny version object in the value returned by serializeUser (e.g. {id: user.id, v: '1.2.0'}). In deserializeUser parse that payload, compare the stored version with the current schema version, and either reject the session (forcing re‑login) or run a legacy mapper for backward‑compatible fields. A lightweight middleware can cache the result of that comparison per session so the version check runs only once per login.

Confirmed facts

• Passport stores exactly what serializeUser returns; the session store treats it as opaque JSON.
• No core hook exists for schema versioning, migration, or automatic purge.
• Changing the payload shape breaks existing sessions unless the new deserializeUser can still parse the old format.

Likely explanation (best‑practice pattern)

1. Serialize with version:

   passport.serializeUser((user, done) =>
     done(null, { id: user.id, v: CURRENT_SCHEMA_VERSION }));
   

2. Deserialize with guard:

   passport.deserializeUser(async (payload, done) => {
     if (!payload || typeof payload !== 'object') return done(null, false);
     if (payload.v !== CURRENT_SCHEMA_VERSION) {
       // Option A: reject → force login
       return done(null, false);
       // Option B: migrate via legacy mapper (see note)
     }
     const user = await User.findById(payload.id);
     done(null, user);
   });
   

3. Optional middleware to avoid per‑request overhead:

   app.use((req, res, next) => {
     if (req.user && !req.session._schemaValid) {
       req.session._schemaValid = true; // first request after login
     }
     next();
   });
   

4. Control exposure with TTL: set a short rolling TTL (e.g. 15 min) on the session store so stale sessions expire quickly during a migration window.

Trade‑offs

Assumptions & uncertainty

• Assumes you control CURRENT_SCHEMA_VERSION (e.g. a constant or value from package.json).
• Assumes the session store serializes the payload as JSON (default for express-session).
• Legacy mapper strategy is marked for review because it depends on how often your user model changes.

Verification steps

1. Log in, inspect the session store (Redis, MemoryStore, etc.) and confirm the payload contains v.
2. Bump CURRENT_SCHEMA_VERSION, restart the app, and make a request; the session should be rejected or migrated per your choice.
3. Revert the version, log in again, and verify successful deserialization.
4. Measure request latency before and after adding the guard to quantify overhead.
5. Set a very short TTL (e.g. 30 s) and observe automatic expiry of stale sessions.

One missing diagnostic detail

What session store and TTL are you currently using? The recommendation for short rolling TTL vs. explicit invalidation changes based on that answer.