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

52 @deprecated annotations and 4 deprecated arguments (count of 2026-09-13, after #732–#736).

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
• Jose\Experimental\Signature\ES256K, the shim kept since feat(signature): move ES256K from the experimental package to the library (RFC 8812) #736 moved the algorithm to the library, and its deprecated service in the bundle's signature_experimental.php
• decide the fate of EdDSA: RFC 9864 deprecates the polymorphic identifier and feat(signature): Ed25519 and Ed448 fully-specified algorithms, X448 for ECDH-ES (RFC 9864, RFC 8037) #734 deprecates signing with it, verification stays silent so the tokens in circulation keep working. Its docblock calls the removal "a candidate for 5.0.0" — either remove the class, or keep it verify-only and say so
• Jose\Experimental\Signature\ES256K, the alias kept once the algorithm moves to Jose\Component\Signature\Algorithm\ES256K (RFC 8812) — refactor(signature): move ES256K out of the experimental package (RFC 8812) #727
• Jose\Component\Signature\Algorithm\EdDSA, deprecated by RFC 9864 in favour of Ed25519 / Ed448 — feat(signature): Ed25519 and Ed448 fully-specified algorithms, EdDSA deprecated (RFC 9864); X448 for ECDH-ES (RFC 8037) #724 adds the replacements in 4.3; decide here whether the polymorphic identifier is removed or merely kept deprecated (interop: EdDSA is still what most issuers emit)

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
• final on the three classes left open only so their deprecated shim can extend them: Jose\Unsecured\Signature\None, Jose\Rsa15\KeyEncryption\RSA15 and Jose\Component\Signature\Algorithm\ES256K
• 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; since feat(signature): Ed25519 and Ed448 fully-specified algorithms, X448 for ECDH-ES (RFC 9864, RFC 8037) #734/feat(signature): move ES256K from the experimental package to the library (RFC 8812) #736, also DeprecatedES256KConsumer, the shim cases of ExperimentalAlgorithmsTest and ES256KSignatureTest, and the EdDSA cases of EdDSAAlgorithmsTest and OKPKeyAnalyzerTest
• 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.

---

2026-09-13 — #715 and #716 merged: the WrappedKey and TokenHeaders announcements of section 3 are in place. #732–#736 added two deprecations (the ES256K shim, EdDSA) and three classes left open for a shim: folded into sections 1, 2 and 4 above.