feat: add key object v5

[bshaffer]

Modifications to POC PR #352

• allow for Firebase\JWT\Key objects instead of using an array of $allowed_args. This is more secure because it ties a key to an algorithm
• fully backwards compatible
• updates documentation to only use recommended way

use Firebase\JWT\JWT;
use Firebase\JWT\Key;

// old
JWT::decode($jwt, $publicKey, ['RS256']);

// new
JWT::decode($jwt, new Key($publicKey, 'RS256'));

This prevents a certain kind of attack described in #351.
Releasing this as an optional feature in v5 will allow libraries to require 5.5^|6^ in composer when we make using the Key objects required in v6, and that will allow a smoother upgrade for everyone.

cc @paragonie-security

[paragonie-security]

@googlebot I consent.

[swiffer]

Providing algorithms as 3rd parameter is marked deprecated but still needs to be used when working with JWKs? Is this still true?

[bshaffer]

@swiffer no, it's not REQUIRED, it is possible to loop through the returned keys and create Key objects from them. This is the recommended way and i should probably update the docs with an example.

[swiffer]

@bshaffer as the keys array from the jwks is containing the alg for every key provided isn't it safe to rely on these and change the return value of parseKeySet to return Key objects directly?

[bshaffer]

@swiffer we can't change the return value without tagging a new major release, so the library won't be able to make that change until the next major version, which is the plan.

[swiffer]

Yes, have just figured that out this moment checking the pr for 6.0 - thanks a lot. Looking forward for the release!