[ENHANCEMENT] RFC-9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)

[codemasher]

Describe the feature

The feature is documented in RFC-9449.

Right now I don't see the need to implement abstract support for this, as there are currently no major services out in the wild that support it (as it is a relatively new proposal).
Further, the underlying protocol has a lot of dependencies (RFCs 7515, 7516, 7517, 7518, 7519, 7520, 7521, 7523) that translate into one or more additional libraries, such as firebase/php-jwt or web-token/jwt-framework for example, which is not justifiable at this point.
Bluesky's upcoming OAuth2 support might be the first implementation that makes use of it, and once it is rolled out, I'll figure out implementation details and whether to depend on external libraries or just roll a minimum JWT implementation for this specific provider.

Code sample (if applicable)

DPoP introduces the concept of a DPoP proof, which is a JWT created by the client and sent with an HTTP request using the DPoP header field. Each HTTP request requires a unique DPoP proof.

The DPoP proof is sent with the access token request, hence it should be created once the authorization code is received, so in OAuth2Provider::getAccessToken(). Ideal is probably OAuth2Provider::sendAccessTokenRequest() which is called in the aforementioned method and which has direct access to the PSR-7 RequestInterface instance:

	protected function sendAccessTokenRequest(string $url, array $body):ResponseInterface{

		$request = $this->requestFactory
			->createRequest('POST', $url)
			->withHeader('Accept', 'application/json')
			->withHeader('Accept-Encoding', 'identity')
			->withHeader('Content-Type', 'application/x-www-form-urlencoded')
			->withBody($this->streamFactory->createStream(QueryUtil::build($body, PHP_QUERY_RFC1738)))
		;

		foreach($this::HEADERS_AUTH as $header => $value){
			$request = $request->withHeader($header, $value);
		}

		if($this::USES_BASIC_AUTH_IN_ACCESS_TOKEN_REQUEST){
			$request = $this->addBasicAuthHeader($request);
		}

		// as with all additional features, an interface will be added
		if($this instanceof DPoP){
			$dpopProof = $this->createDpopProof(/* ... */);

			$request = $request->withHeader('DPoP', $dpopProof);
		}

		return $this->http->sendRequest($request);
	}

During creation of the proof, the generated private key should be saved for the current user, which requires additional methods in the storage interface as the key is required for subsequent proofs:

• OAuthStorageInterface::storeDpopPrivateKey(string $key, string $provider):static
• [get, has, clear, clearAll...]

No changes are required to the token response parser or the AccessToken class as the only difference here is that the access token is a JWT that contains data instead of a random string.

The request authorization boils down to:

	public function getRequestAuthorization(RequestInterface $request, AccessToken|null $token = null):RequestInterface{
		$token ??= $this->storage->getAccessToken($this->name);

		if($token->isExpired()){

			if(!$this instanceof TokenRefresh || $this->options->tokenAutoRefresh !== true){
				throw new InvalidAccessTokenException;
			}

			$token = $this->refreshAccessToken($token);
		}

		return $request
			// the "Bearer" changes to "DPoP" as per spec (or whatever the service doc says)
			->withHeader('Authorization', 'DPoP '.$token->accessToken)
			// additionally, a DPoP proof is attached
			->withHeader('DPoP', $this->createDpopProof(/* ... */))
		;
	}

Are you (the requester) willing to submit a pull request for that feature?

[YES] (I guess I'll have to!?)