feat: add validateDecoded option for JWT payload validation

[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

• Closes Add 'validate' option to allow token claim validation #316

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

[jsumners]

I'm not sure this is a good idea. The issuance of a JWT should be done after the client has been authenticated and authorized. This seems to be adding authorization functionality into the JWT validation process. I think that is probably a bad practice.

If this change is warranted, I think the naming of the option is not clear enough. And this is definitely missing required documentation.