Fiber jwtware: should expired JWTs return a distinct 401 for refresh, and what are the limits of built-in expiry handling?

Answer to the core question

Yes – return a distinct 401 response when the token is expired so the client can call a refresh endpoint. Fiber’s jwtware will reject any token that fails signature or time‑claim validation before it reaches your handler. The ErrorHandler hook is the only place you can differentiate expired from other failures and send a machine‑readable code such as token_expired. This pattern is safe; the exp claim is already public, so distinguishing it does not leak useful information to an attacker. Keep the HTTP status the same (401) for all failures to avoid giving scanners a side‑channel on the type of error.

Why this matters

• Access tokens should be short‑lived (e.g., 5–15 min) and never grant refresh capability directly.
• Refresh logic must be separate, usually via a secure, opaque token stored server‑side or in a dedicated store.
• Fiber’s session middleware is lazy‑expiry (checked on read) and independent of JWT exp; do not treat session presence as proof of a valid token.
• jwtware’s built‑in validation only covers signature and the standard time claims; it has no sliding window, automatic refresh, or additional leeway beyond what you configure in the underlying JWT library.

How to implement the pattern

1. Pin the JWT library version. jwtware uses github.com/golang-jwt/jwt/v5 (or v4 in older releases). Verify go.mod and note the error types.

   go list -m github.com/golang-jwt/jwt
   

2. Set up jwtware with a custom ErrorHandler.

   app.Use(jwtware.New(jwtware.Config{
       SigningKey: []byte("secret"),
       ErrorHandler: func(c *fiber.Ctx, err error) error {
           if errors.Is(err, jwt.ErrTokenExpired) { // v5
               return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{
                   "code": "token_expired",
                   "msg":  "access token expired",
               })
           }
           // For v4 you would use:
           // if ve, ok := err.(*jwt.ValidationError); ok && ve.Errors&jwt.ValidationErrorExpired != 0 { … }
           return c.Status(fiber.StatusUnauthorized).JSON(fiber.Map{
               "code": "invalid_token",
               "msg":  "token validation failed",
           })
       },
   }))
   

3. Protect routes with jwtware only where you need authentication. Public routes should not mount the middleware.
4. Implement a refresh endpoint. Accept the refresh token (stored server‑side or in a secure cookie), issue a new access token, and optionally rotate the refresh token.
5. Do not rely on Fiber sessions for token validity. Keep sessions for other state (e.g., CSRF tokens) or use them only after the access token has been validated.

Limits of built‑in expiry handling

• jwtware calls the underlying JWT library’s ParseWithClaims which checks exp, nbf, and iat against the current time. No automatic sliding or refresh is performed.
• Leeway (clock skew tolerance) can be set via the library’s jwt.WithLeeway option; it applies to all time claims equally.
• There is no per‑route or per‑claim expiration logic beyond the standard exp claim.
• If you need fine‑grained revocation or per‑scope expiry, you must implement that yourself (e.g., blacklist, short‑lived refresh tokens, or claim‑based checks).

Verification checklist

• Issue a token with exp in the past and confirm the server returns a 401 with code":"token_expired".
• Issue a token with an invalid signature and confirm the server returns 401 with code":"invalid_token".
• Test the full flow: expired token → refresh endpoint → new access token → protected route.
• Run the same tests against the exact JWT library version in go.mod to ensure error discrimination works.

Missing diagnostic detail

If you are currently using a legacy Fiber jwtware build that pulls github.com/dgrijalva/jwt-go (v3) or an older v4 release, the error types differ. Please confirm the exact module version you are compiling against so the ErrorHandler can be written to match the correct error type.