Http: Review OAuth 2.0 classes

- Rename `OAuth2GrantType` to `HasGrantType`; access its constants
  (now with `GRANT_` prefixes) via its implementations; add missing
  grants, incl. `device_code` for planned device flow support
- Remove redundant `OAuth2Flow` (grants and flows are equivalent)
- Add `HasResponseType` for values passed to the authorization endpoint,
  incl. for OpenID Connect flows

Author: lkrms

phpstan-baseline-7.4.neon

@@ -40,6 +40,7 @@ parameters:
 			paths:
 				- src/Toolkit/Core/Facade/*
 				- tests/unit/Toolkit/Core/Facade/*
+				- tests/fixtures/Toolkit/Http/OAuth2/OAuth2Client/OAuth2TestClient.php
 		-
 			identifier: salient.needless.coalesce
 			paths:

phpstan-baseline-8.3.neon

@@ -0,0 +1,47 @@
+<?php declare(strict_types=1);
+
+namespace Salient\Http\OAuth2;
+
+/**
+ * @api
+ */
+interface HasGrantType
+{
+    /**
+     * Authorization code
+     *
+     * - \[RFC6749] Section 4.1 ("Authorization Code Grant")
+     * - \[OpenID.Core] Section 3.1 ("Authentication using the Authorization
+     *   Code Flow")
+     * - \[OpenID.Core] Section 3.3 ("Authentication using the Hybrid Flow")
+     */
+    public const GRANT_AUTHORIZATION_CODE = 'authorization_code';
+
+    /**
+     * Resource owner password
+     *
+     * - \[RFC6749] Section 4.3 ("Resource Owner Password Credentials Grant")
+     */
+    public const GRANT_PASSWORD = 'password';
+
+    /**
+     * Client credentials
+     *
+     * - \[RFC6749] Section 4.4 ("Client Credentials Grant")
+     */
+    public const GRANT_CLIENT_CREDENTIALS = 'client_credentials';
+
+    /**
+     * Device code
+     *
+     * - \[RFC8628] ("OAuth 2.0 Device Authorization Grant")
+     */
+    public const GRANT_DEVICE_CODE = 'urn:ietf:params:oauth:grant-type:device_code';
+
+    /**
+     * Refresh token
+     *
+     * - \[RFC6749] Section 6 ("Refreshing an Access Token")
+     */
+    public const GRANT_REFRESH_TOKEN = 'refresh_token';
+}

phpstan.neon.dist

@@ -0,0 +1,60 @@
+<?php declare(strict_types=1);
+
+namespace Salient\Http\OAuth2;
+
+/**
+ * @api
+ */
+interface HasResponseType
+{
+    /**
+     * Authorization code
+     *
+     * - \[RFC6749] Section 4.1 ("Authorization Code Grant")
+     * - \[OpenID.Core] Section 3.1 ("Authentication using the Authorization
+     *   Code Flow")
+     */
+    public const RESPONSE_CODE = 'code';
+
+    /**
+     * Token
+     *
+     * - \[RFC6749] Section 4.2 ("Implicit Grant")
+     */
+    public const RESPONSE_TOKEN = 'token';
+
+    /**
+     * ID token
+     *
+     * - \[OpenID.Core] Section 3.2 ("Authentication using the Implicit Flow")
+     */
+    public const RESPONSE_ID_TOKEN = 'id_token';
+
+    /**
+     * ID token + token
+     *
+     * - \[OpenID.Core] Section 3.2 ("Authentication using the Implicit Flow")
+     */
+    public const RESPONSE_ID_TOKEN_TOKEN = 'id_token token';
+
+    /**
+     * Authorization code + ID token
+     *
+     * - \[OpenID.Core] Section 3.3 ("Authentication using the Hybrid Flow")
+     */
+    public const RESPONSE_CODE_ID_TOKEN = 'code id_token';
+
+    /**
+     * Authorization code + token
+     *
+     * - \[OpenID.Core] Section 3.3 ("Authentication using the Hybrid Flow")
+     */
+    public const RESPONSE_CODE_TOKEN = 'code token';
+
+    /**
+     * Authorization code + ID token + token
+     *
+     * - \[OpenID.Core] Section 3.3 ("Authentication using the Hybrid Flow")
+     */
+    public const RESPONSE_CODE_ID_TOKEN_TOKEN = 'code id_token token';
+}

src/Toolkit/Http/OAuth2/HasGrantType.php

@@ -10,7 +10,6 @@
 use Salient\Core\Facade\Cache;
 use Salient\Core\Facade\Console;
 use Salient\Curler\Curler;
-use Salient\Http\Message\Response;
 use Salient\Http\Server\Server;
 use Salient\Http\Server\ServerResponse;
 use Salient\Utility\Arr;
@@ -21,98 +20,34 @@
 use Throwable;
 use UnexpectedValueException;
 
-/**
- * A headless OAuth 2.0 client that acquires and validates tokens required for
- * access to protected resources
- */
-abstract class OAuth2Client
+abstract class OAuth2Client implements HasGrantType, HasResponseType
 {
     private ?Server $Listener;
     private AbstractProvider $Provider;
-    /** @var OAuth2Flow::* */
-    private int $Flow;
+    /** @var self::GRANT_* */
+    private string $Flow;
     private string $TokenKey;
 
     /**
-     * Return an HTTP listener to receive OAuth 2.0 redirects from the provider,
-     * or null to disable flows that require it
-     *
-     * Reference implementation:
-     *
-     * ```php
-     * <?php
-     * class OAuth2TestClient extends OAuth2Client
-     * {
-     *     protected function getListener(): ?Server
-     *     {
-     *         $listener = new Server(
-     *             Env::get('app_host', 'localhost'),
-     *             Env::getInt('app_port', 27755),
-     *         );
-     *
-     *         $proxyHost = Env::getNullable('app_proxy_host', null);
-     *         $proxyPort = Env::getNullableInt('app_proxy_port', null);
-     *
-     *         if ($proxyHost !== null && $proxyPort !== null) {
-     *             return $listener->withProxy(
-     *                 $proxyHost,
-     *                 $proxyPort,
-     *                 Env::getNullableBool('app_proxy_tls', null),
-     *                 Env::get('app_proxy_base_path', ''),
-     *             );
-     *         }
-     *
-     *         return $listener;
-     *     }
-     * }
-     * ```
+     * Get an in-process HTTP server to receive OAuth 2.0 redirects from the
+     * provider to the client, or null if flows that require it are disabled
      */
     abstract protected function getListener(): ?Server;
 
     /**
-     * Return an OAuth 2.0 provider to request and validate tokens that
-     * authorize access to the resource server
-     *
-     * Example:
-     *
-     * The following provider could be used to authorize access to the Microsoft
-     * Graph API on behalf of a user or application. `redirectUri` can be
-     * omitted if support for the Authorization Code flow is not required.
-     *
-     * > The only scope required for access to the Microsoft Graph API is
-     * > `https://graph.microsoft.com/.default`
-     *
-     * ```php
-     * <?php
-     * class OAuth2TestClient extends OAuth2Client
-     * {
-     *     protected function getProvider(): GenericProvider
-     *     {
-     *         return new GenericProvider([
-     *             'clientId' => $this->AppId,
-     *             'clientSecret' => $this->Secret,
-     *             'redirectUri' => $this->getRedirectUri(),
-     *             'urlAuthorize' => sprintf('https://login.microsoftonline.com/%s/oauth2/authorize', $this->TenantId),
-     *             'urlAccessToken' => sprintf('https://login.microsoftonline.com/%s/oauth2/v2.0/token', $this->TenantId),
-     *             'urlResourceOwnerDetails' => sprintf('https://login.microsoftonline.com/%s/openid/userinfo', $this->TenantId),
-     *             'scopes' => ['openid', 'profile', 'email', 'offline_access', 'https://graph.microsoft.com/.default'],
-     *             'scopeSeparator' => ' ',
-     *         ]);
-     *     }
-     * }
-     * ```
+     * Get an OAuth 2.0 provider for the client
      */
     abstract protected function getProvider(): AbstractProvider;
 
     /**
-     * Return the OAuth 2.0 flow to use
+     * Get the client's OAuth 2.0 flow
      *
-     * @return OAuth2Flow::*
+     * @return OAuth2Client::GRANT_*
      */
-    abstract protected function getFlow(): int;
+    abstract protected function getFlow(): string;
 
     /**
-     * Return the URL of the OAuth 2.0 provider's JSON Web Key Set, or null to
+     * Get the URL of the OAuth 2.0 provider's JSON Web Key Set, or null to
      * disable JWT signature validation and decoding
      *
      * Required for token signature validation. Check the provider's
@@ -124,9 +59,13 @@ abstract protected function getJsonWebKeySetUrl(): ?string;
      * Called when an access token is received from the OAuth 2.0 provider
      *
      * @param array<string,mixed>|null $idToken
-     * @param OAuth2GrantType::* $grantType
+     * @param OAuth2Client::GRANT_* $grantType
      */
-    abstract protected function receiveToken(OAuth2AccessToken $token, ?array $idToken, string $grantType): void;
+    abstract protected function receiveToken(
+        OAuth2AccessToken $token,
+        ?array $idToken,
+        string $grantType
+    ): void;
 
     public function __construct()
     {
@@ -215,7 +154,7 @@ final protected function refreshAccessToken(): ?OAuth2AccessToken
         return $refreshToken === null
             ? null
             : $this->requestAccessToken(
-                OAuth2GrantType::REFRESH_TOKEN,
+                self::GRANT_REFRESH_TOKEN,
                 ['refresh_token' => $refreshToken]
             );
     }
@@ -251,14 +190,14 @@ final protected function authorize(array $options = []): OAuth2AccessToken
         $this->flushTokens();
 
         switch ($this->Flow) {
-            case OAuth2Flow::CLIENT_CREDENTIALS:
+            case self::GRANT_CLIENT_CREDENTIALS:
                 return $this->authorizeWithClientCredentials($options);
 
-            case OAuth2Flow::AUTHORIZATION_CODE:
+            case self::GRANT_AUTHORIZATION_CODE:
                 return $this->authorizeWithAuthorizationCode($options);
 
             default:
-                throw new LogicException(sprintf('Invalid OAuth2Flow: %d', $this->Flow));
+                throw new LogicException(sprintf('Invalid flow: %s', $this->Flow));
         }
     }
 
@@ -282,7 +221,7 @@ private function authorizeWithClientCredentials(array $options = []): OAuth2Acce
         }
 
         return $this->requestAccessToken(
-            OAuth2GrantType::CLIENT_CREDENTIALS,
+            self::GRANT_CLIENT_CREDENTIALS,
             $options
         );
     }
@@ -327,7 +266,7 @@ private function authorizeWithAuthorizationCode(array $options = []): OAuth2Acce
         }
 
         return $this->requestAccessToken(
-            OAuth2GrantType::AUTHORIZATION_CODE,
+            self::GRANT_AUTHORIZATION_CODE,
             ['code' => $code],
             $options['scope'] ?? null
         );
@@ -372,7 +311,7 @@ private function receiveAuthorizationCode(ServerRequestInterface $request): Serv
      * Request an access token from the OAuth 2.0 provider, then validate, cache
      * and return it
      *
-     * @param string&OAuth2GrantType::* $grantType
+     * @param self::GRANT_* $grantType
      * @param array<string,mixed> $options
      * @param mixed $scope
      */
@@ -418,7 +357,7 @@ private function requestAccessToken(
             ?? $options['scope']
             ?? $scope);
 
-        if (!$scopes && $grantType === OAuth2GrantType::REFRESH_TOKEN) {
+        if (!$scopes && $grantType === self::GRANT_REFRESH_TOKEN) {
             $lastToken = Cache::getInstance()->getInstanceOf($this->TokenKey, OAuth2AccessToken::class);
             if ($lastToken) {
                 $scopes = $lastToken->getScopes();