jsonwebtoken

Postconditions — what we check

• verify · verify-token-expired

  error
  Whentoken's exp claim is before current time
  ThrowsTokenExpiredError: jwt expired
  Required handlingCaller MUST wrap jwt.verify() in try-catch block or use callback error-first pattern. TokenExpiredError indicates legitimate expiration - handle gracefully with 401 response and prompt user to refresh token or re-authenticate.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1]
• verify · verify-token-not-active

  error
  Whentoken's nbf claim is after current time
  ThrowsNotBeforeError: jwt not active
  Required handlingCaller MUST handle NotBeforeError. Token is valid but not yet active. Either reject with 401 or retry after specified date.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1]
• verify · verify-invalid-signature

  error
  Whentoken signature does not match expected value
  ThrowsJsonWebTokenError: invalid signature
  Required handlingCaller MUST handle JsonWebTokenError for invalid signatures. This indicates tampering or wrong secret/key. CRITICAL security event - log and reject with 403. Never expose error details to client.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1]
• verify · verify-malformed-token

  error
  Whentoken structure is invalid (not 3 parts, invalid base64, etc.)
  ThrowsJsonWebTokenError: jwt malformed
  Required handlingCaller MUST handle JsonWebTokenError for malformed tokens. Invalid structure indicates corrupted token or attack. Reject with 400 or 403.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[1]
• verify · verify-invalid-algorithm

  error
  Whentoken algorithm not in options.algorithms whitelist
  ThrowsJsonWebTokenError: invalid algorithm
  Required handlingCaller MUST handle algorithm mismatch errors. This prevents CVE-2015-9235 algorithm confusion attack. Always specify algorithms option in verify().
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[2]
• verify · verify-audience-mismatch

  error
  Whentoken aud claim does not match options.audience
  ThrowsJsonWebTokenError: jwt audience invalid. expected: [expected]
  Required handlingCaller MUST handle audience validation errors when using options.audience. Audience mismatch indicates token intended for different service.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[3]
• verify · verify-issuer-mismatch

  error
  Whentoken iss claim does not match options.issuer
  ThrowsJsonWebTokenError: jwt issuer invalid. expected: [expected]
  Required handlingCaller MUST handle issuer validation errors when using options.issuer. Issuer mismatch indicates token from untrusted source.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[3]
• verify · verify-missing-secret

  error
  WhensecretOrPublicKey parameter is undefined or empty
  ThrowsJsonWebTokenError: secret or public key must be provided
  Required handlingCaller MUST handle missing secret errors. This typically indicates configuration error (missing environment variable). Fatal error - should fail fast on application startup, not at runtime.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[4]
• sign · sign-invalid-payload

  warning
  Whenpayload is not a plain object, string, or buffer
  ThrowsError: Expected 'payload' to be a plain object, Buffer, or string
  Required handlingCaller SHOULD validate payload type before calling jwt.sign() or wrap in try-catch. Common when payload is null, undefined, or Promise object (forgot await on database query).
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[5]
• sign · sign-missing-secret

  warning
  WhensecretOrPrivateKey is undefined, null, or empty
  ThrowsError: secretOrPrivateKey must have a value
  Required handlingCaller SHOULD ensure secret exists before calling jwt.sign(). Missing secret indicates configuration error. Should fail fast on startup, not at runtime during login.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[5]
• sign · sign-invalid-options

  warning
  Whenoptions.algorithm is invalid or unsupported
  ThrowsError: 'algorithm' must be a valid string enum value
  Required handlingCaller SHOULD validate algorithm option. Common mistake: typo in algorithm name (e.g., 'HS-256' instead of 'HS256').
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[5]
• sign · sign-invalid-expiresin

  warning
  Whenoptions.expiresIn is invalid format
  ThrowsError: invalid expiresIn option
  Required handlingCaller SHOULD validate expiresIn format. Accepts seconds (number) or time span string ('1h', '2d', '30s'). Invalid format throws.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[6]
• sign · sign-claim-conflict

  warning
  Whenoptions.expiresIn provided but payload already has exp property
  ThrowsError: Bad 'options.expiresIn' option the payload already has an 'exp' property
  Required handlingCaller SHOULD NOT set exp in both payload and options. Choose one method: either payload.exp or options.expiresIn, not both.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[6]
• decode · decode-used-for-authentication

  error
  Whenjwt.decode() return value is used to make authentication or authorization decisions (e.g., checking role claims, user ID, or admin status) without subsequently calling jwt.verify() with the same token.
  ReturnsJwtPayload | null | string
  Required handlingMUST use jwt.verify() for all authentication and authorization decisions. jwt.decode() is only safe for: (1) inspecting the header to select a verification key from a JWKS, (2) extracting non-security metadata after verification has already succeeded, (3) debugging and logging. Never use decode() result to make access control decisions.
  costcriticalin prodimmediate exceptionusers seesecurity breachvisibilitysilent
  Sources[7][8][9]
• decode · decode-null-return-not-checked

  warning
  Whenjwt.decode() return value is used without checking for null, on input that may be untrusted, undefined, or malformed.
  Returnsnull | JwtPayload | string
  Required handlingAlways check the return value before accessing properties: const payload = jwt.decode(token); if (!payload) { return res.status(400).json({ error: 'Invalid token' }); }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]

Sources

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

1. [1]github.com/auth0/node-jsonwebtokenhttps://github.com/auth0/node-jsonwebtoken#errors--codes
2. [2]nvd.nist.gov/vuln/detailhttps://nvd.nist.gov/vuln/detail/CVE-2015-9235
3. [3]github.com/auth0/node-jsonwebtokenhttps://github.com/auth0/node-jsonwebtoken#jwtverifytoken-secretorpublickey-options-callback
4. [4]github.com/auth0/node-jsonwebtokenhttps://github.com/auth0/node-jsonwebtoken
5. [5]github.com/auth0/node-jsonwebtokenhttps://github.com/auth0/node-jsonwebtoken#jwtsignpayload-secretorprivatekey-options-callback
6. [6]github.com/auth0/node-jsonwebtokenhttps://github.com/auth0/node-jsonwebtoken#token-expiration-exp-claim
7. [7]github.com/auth0/node-jsonwebtokenhttps://github.com/auth0/node-jsonwebtoken/blob/master/README.md
8. [8]owasp.org/www-project-web-security-testing-guide/latesthttps://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/06-Session_Management_Testing/10-Testing_JSON_Web_Tokens
9. [9]invicti.com/blog/web-securityhttps://www.invicti.com/blog/web-security/json-web-token-jwt-attacks-vulnerabilities/