feat: add validateDecoded option to validate JWT payload

[williamfds]

This PR introduces a new validateDecoded option to the @fastify/jwt plugin.

It allows developers to define custom validation logic that runs after the JWT is decoded and verified, but before assigning request.user.
This enables scenarios where claims alone are insufficient, such as:

• Checking flags (e.g., isVerified)

• Validating roles or permissions

• Applying business rules or JSON Schema validation

• Performing async checks (e.g., database lookups)

Example: synchronous usage

fastify.register(jwt, {
  secret: 'supersecret',
  validateDecoded: (payload) => {
    if (!payload.admin) {
      throw new Error('Not authorized')
    }
  }
})

Example: asynchronous usage

fastify.register(jwt, {
 secret: 'supersecret',
 validateDecoded: async (payload) => {
   const isAllowed = await someCheck(payload.userId)
   if (!isAllowed) {
     throw new Error('Blocked by validation')
   }
 }
})

Implementation notes

This change includes the following:

• Adds validateDecoded(payload) support to plugin options

• Executed after token verification in request.jwtVerify()

• If validation fails, responds with 400 Bad Request

• Includes test coverage for both sync and async cases

• Type definitions updated (types/jwt.d.ts)

• Documentation updated in README.md

Related

Checklist

• run npm run test and npm run benchmark
• tests and/or benchmarks are included
• documentation is changed or added
• commit message and code follows the Developer's Certification of Origin
  and the Code of conduct

[williamfds]

Hello again @jsumners

Following up on your feedback in #377, I’ve created this new PR after renaming the branch;

This new PR:

• Implements the validation as validateDecoded, not validate
• Returns 400 Bad Request on validation failure, as suggested
• Respects decode.complete = false by maintaining correct flow
• Includes documentation and TypeScript support
• Covers sync and async usage
• Addresses all points from Add 'validate' option to allow token claim validation #316

Thanks again for your previous review! Would love your input here to move this forward 🙏

[jsumners]

Please don't open new PRs for the same work. The context of the conversation around the work gets lost. Update the original PR.

[WilliamFdaSilva]

Please don't open new PRs for the same work. The context of the conversation around the work gets lost. Update the original PR.

Hi!
Apologies for the confusion — I had to create a new PR to align the branch name with the naming conventions, changing it from validate to validateDecoded. As a result, the original PR was closed.

This won't happen again. Thanks for your understanding!

[jsumners]

The source branch name is really inconsequential. Please keep the work in the original PR.

[williamfds]

The source branch name is really inconsequential. Please keep the work in the original PR.

All changes from this PR have been consolidated into PR #377, which now includes the validateDecoded functionality.
Closing this one in favor of #377.

[jsumners]

Thank you.