passport-jwt

Postconditions — what we check

• Strategy · missing-secret-throws

  error
  WhensecretOrKey and secretOrKeyProvider are both absent from options
  ThrowsTypeError: JwtStrategy requires a secret or key
  Required handlingCaller MUST provide either secretOrKey or secretOrKeyProvider in options. This error is thrown synchronously during strategy instantiation. Wrap new Strategy() in try-catch during application initialization if using dynamic configuration.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2]
• Strategy · both-secret-and-provider-throws

  error
  WhenBoth secretOrKey and secretOrKeyProvider are provided in options. Only one of these is allowed. Providing both indicates a configuration mistake — the strategy cannot determine which key source to use.
  ThrowsTypeError: JwtStrategy has been given both a secretOrKey and a secretOrKeyProvider
  Required handlingUse EITHER secretOrKey (for static secrets) OR secretOrKeyProvider (for dynamic key lookup, e.g., multi-tenant or JWKS endpoint). Never both at the same time. // Correct: static secret only new Strategy({ secretOrKey: process.env.JWT_SECRET, jwtFromRequest: ... }, verify); // Correct: dynamic provider only new Strategy({ secretOrKeyProvider: myProvider, jwtFromRequest: ... }, verify); // WRONG: both provided — throws TypeError at startup new Strategy({ secretOrKey: 'secret', secretOrKeyProvider: myProvider, jwtFromRequest: ... }, verify); This error is thrown synchronously at application startup, so it will crash the server process during initialization if not caught.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3][1]
• Strategy · missing-verify-callback-throws

  error
  WhenThe verify callback (second argument to new Strategy()) is not provided or is undefined/null. The verify callback is required to validate the decoded JWT payload and call done() with the authenticated user (or false on failure).
  ThrowsTypeError: JwtStrategy requires a verify callback
  Required handlingAlways provide a verify callback as the second argument: passport.use(new Strategy(options, function(jwt_payload, done) { User.findById(jwt_payload.sub, function(err, user) { if (err) return done(err, false); if (user) return done(null, user); return done(null, false); }); })); The verify callback signature is: (jwt_payload, done) — when passReqToCallback is false (default) (req, jwt_payload, done) — when passReqToCallback is true
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4][1]
• Strategy · missing-jwt-from-request-throws

  error
  Whenoptions.jwtFromRequest is not provided. This function tells the strategy where to find the JWT in each incoming request. Without it, the strategy cannot extract the token from any request and throws synchronously at construction.
  ThrowsTypeError: JwtStrategy requires a function to retrieve jwt from requests (see option jwtFromRequest)
  Required handlingAlways include jwtFromRequest in options. Use one of the built-in extractors: const { ExtractJwt } = require('passport-jwt'); // Most common: Bearer token in Authorization header opts.jwtFromRequest = ExtractJwt.fromAuthHeaderAsBearerToken(); // From custom header opts.jwtFromRequest = ExtractJwt.fromHeader('x-access-token'); // From request body opts.jwtFromRequest = ExtractJwt.fromBodyField('access_token'); // Combine multiple extractors (tries each in order) opts.jwtFromRequest = ExtractJwt.fromExtractors([ ExtractJwt.fromAuthHeaderAsBearerToken(), ExtractJwt.fromUrlQueryParameter('token'), ]);
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][1]
• Strategy · verify-callback-db-error

  error
  WhenThe verify callback encounters a database or service error during user lookup
  ThrowsError passed to done(err) callback in the verify function
  Required handlingThe verify callback MUST call done(err) when encountering errors during user lookup. Calling done(err) with a non-null first argument causes passport to return a 500 error. Pattern: if (err) { return done(err, false); }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• Strategy · token-invalid-or-expired

  error
  WhenJWT token signature is invalid, token is expired, or token is malformed
  ThrowsAuthentication failure passed to done(null, false, info)
  Required handlingWhen token validation fails, passport calls the verify function with null payload. The verify callback MUST call done(null, false) to deny authentication. Callers using passport.authenticate('jwt') MUST handle 401 responses appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• Strategy · token-extraction-fails

  error
  WhenjwtFromRequest extractor returns null (no token found in request)
  ThrowsAuthentication fails with 401 Unauthorized before verify callback is called
  Required handlingCaller MUST handle 401 responses from protected routes when no token is present. The verify callback is NOT invoked when extraction fails.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• ExtractJwt.fromExtractors · from-extractors-non-array-throws

  error
  WhenExtractJwt.fromExtractors() is called with a non-array argument. Common mistakes: - Passing a single extractor function directly instead of wrapping in an array - Passing undefined (e.g., a variable that was not initialized) - Passing null or a string
  ThrowsTypeError: extractors.fromExtractors expects an array
  Required handlingAlways wrap extractor functions in an array: // WRONG — passes function directly, throws TypeError opts.jwtFromRequest = ExtractJwt.fromExtractors( ExtractJwt.fromAuthHeaderAsBearerToken() ); // CORRECT — array of extractor functions opts.jwtFromRequest = ExtractJwt.fromExtractors([ ExtractJwt.fromAuthHeaderAsBearerToken(), ExtractJwt.fromUrlQueryParameter('token'), ]); This error is thrown synchronously during application initialization (when the Strategy is configured), before any requests are processed. It will crash the server startup if uncaught.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][1]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]passportjs.org/packages/passport-jwthttps://www.passportjs.org/packages/passport-jwt/
2. [2]github.com/mikenicholson/passport-jwthttps://github.com/mikenicholson/passport-jwt/issues/206
3. [3]github.com/mikenicholson/passport-jwthttps://github.com/mikenicholson/passport-jwt/blob/master/lib/strategy.js#L37
4. [4]github.com/mikenicholson/passport-jwthttps://github.com/mikenicholson/passport-jwt/blob/master/lib/strategy.js#L50
5. [5]github.com/mikenicholson/passport-jwthttps://github.com/mikenicholson/passport-jwt/blob/master/lib/strategy.js#L55
6. [6]github.com/mikenicholson/passport-jwthttps://github.com/mikenicholson/passport-jwt/blob/master/lib/extract_jwt.js#L77