5.0.0: remove what 4.3 deprecated, seal what it announced

[Spomky]

4.3 spends its whole cycle preparing 5.0: every removal the major makes is deprecated there, every class it seals is annotated, and every contract it changes carries a BC NOTE. This issue is the inventory of what 5.0 has to do with that preparation, so that the 5.0.x branch can start the day 4.3.0 is tagged.

It is an umbrella: #653 tracks the RSA1_5 CEK size on its own.

1. Remove the deprecated API

50 @deprecated annotations and 4 deprecated arguments.

Output parameters, replaced by the result objects of 4.3

• JWSLoader::loadAndVerifyWithKey() and loadAndVerifyWithKeySet() → loadAndVerify()
• JWSVerifier::verifyWithKeySet() → verify()
• JWEDecrypter::decryptUsingKey() and decryptUsingKeySet() → decrypt()
• JWELoader::loadAndDecryptWithKey() and loadAndDecryptWithKeySet() → loadAndDecrypt()
• the same seven methods on EventDispatchingJWSLoader, EventDispatchingJWSVerifier, EventDispatchingJWEDecrypter and EventDispatchingJWELoader, which survive the removal of the deprecated subclasses below
• the $signature argument of NestedTokenLoader::load() and of EventDispatchingNestedTokenLoader::load()
• the $name argument of JWSSerializerManager::unserialize() and JWESerializerManager::unserialize()

Immutability

• JWSBuilder::create() and JWEBuilder::create()
• AlgorithmManager::add()
• JWSSerializerManagerFactory::names() and JWESerializerManagerFactory::names() → aliases()

Key management

• the 16 static methods of JWKFactory → JWKFactoryInterface
• the UrlKeySetFactory class and UrlKeySetFactoryTrait::enabledCache() (deprecated since 4.1)

Core

• JWKSet::sortKeys()

Bundle

• the 10 deprecated Services\* subclasses: JWSBuilder, JWSVerifier, JWSLoader, JWEBuilder, JWEDecrypter, JWELoader, NestedTokenBuilder, NestedTokenLoader, ClaimCheckerManager, HeaderCheckerManager
• the 10 matching factories still build those subclasses today, since returning the EventDispatching* decorators would have changed their return type in a minor: rewire them, and widen create() to the interfaces

Algorithms

• Jose\Component\Signature\Algorithm\None and Jose\Component\Encryption\Algorithm\KeyEncryption\RSA15, the two shims kept for the migration to web-token/jwt-unsecured and web-token/jwt-rsa15
• drop the require on those two packages from web-token/jwt-library: it exists only so the shims can extend their replacement

Deprecation plumbing

• Core\Util\InheritanceChecker (13 call sites) and Core\Util\InternalCallChecker (2 call sites)

2. Seal what 4.3 announced

• final on the 11 services carrying @final: JWSBuilder, JWSVerifier, JWSLoader, JWEBuilder, JWEDecrypter, JWELoader, NestedTokenBuilder, NestedTokenLoader, JWKFactory (also readonly), Checker\ClaimCheckerManager and Checker\HeaderCheckerManager
• final readonly on JWK, JWKSet, JWS, JWE and Signature, with the state given to the constructor. This removes JWS::addSignature() and JWE::withPayload(), the two mutators sealed in 4.3, so the builders and the serializers have to assemble the object in one go
• Signature: throw instead of deprecating when a protected header is passed without its encoded form
• JWE::getIV() and getTag(): narrow to string and drop the two return.unusedType entries added to the PHPStan baseline in feat(core): announce the 5.0.0 breaks that were still silent #715

3. Change the contracts

• WrappedKey as the return type of KeyEncryption::encryptKey(), KeyWrapping::wrapKey(), KeyAgreement::getAgreementKey() and KeyAgreementWithKeyWrapping::wrapAgreementKey() (announced for the fourth one in feat(core): announce the 5.0.0 breaks that were still silent #715), dropping the array &$additionalHeader output parameter
• EncryptedContent as the return type of ContentEncryptionAlgorithm::encryptContent(), dropping ?string &$tag
• TokenHeaders as the return type of TokenTypeSupport::retrieveTokenHeaders() (feat(checker): announce the object replacing the token type support headers #716), dropping its two array &$header
• declare and require the expected CEK size on KeyEncryption::decryptKey() and KeyWrapping::unwrapKey(), delete CEK_LENGTHS from Jose\Rsa15\KeyEncryption\RSA15 and drop the two @phpstan-ignore arguments.count of JWEDecrypter — RSA1_5: pass the expected CEK size as a parameter instead of the hardcoded CEK_LENGTHS table #653
• EncryptionAlgorithmManagers: reject the algorithms that are neither key encryption nor content encryption instead of ignoring them, and give the builder and the decrypter the two managers
• merge MissingPayloadRuntimeException and MissingPayloadLogicException into a single class

4. Housekeeping

• open the 5.0.x branch
• raise the PHP floor (>=8.2 today) and the Symfony one (^7.0|^8.0), prune brick/math: ^0.12|…|^0.19
• keep symfony/deprecation-contracts: 5.x will deprecate again
• tests: the 3 assertions on deprecation messages (AlgorithmManagerTest, JWSBuilderImmutabilityTest, JWEBuilderImmutabilityTest), the 2 tests documenting the algorithm shims (NoneSignatureTest, RSAKeyEncryptionTest), and the inheritance cases of ServiceInterfacesTest and SealedValueObjectsTest
• write migration/from-v4.3-to-v5.0.md in the documentation

Done when

On 5.0.x, each of these greps returns nothing in src/:

@deprecated
trigger_deprecation
func_num_args|func_get_arg
@final
BC NOTE
5\.0

The func_num_args() one is the useful cross-check: every remaining crutch belongs either to a deprecated method removed in section 1, or to the CEK size argument declared in section 3.