feat: Socialite OIDC JWKS refresh

src/socialite/src/Two/OpenIdProvider.php

@@ -6,6 +6,7 @@
 
 use Firebase\JWT\JWK;
 use Firebase\JWT\JWT;
+use Firebase\JWT\SignatureInvalidException;
 use GuzzleHttp\RequestOptions;
 use Hypervel\Http\RedirectResponse;
 use Hypervel\Socialite\Two\Exceptions\ConfigurationFetchingException;
@@ -15,6 +16,7 @@
 use Hypervel\Socialite\Two\Exceptions\InvalidUserInfoUrlException;
 use Hypervel\Support\Str;
 use Throwable;
+use UnexpectedValueException;
 
 abstract class OpenIdProvider extends AbstractProvider
 {
@@ -34,6 +36,16 @@ abstract class OpenIdProvider extends AbstractProvider
      */
     protected ?array $jwks = null;
 
+    /**
+     * The timestamp of the last forced JWKS refresh attempt.
+     */
+    protected ?int $jwksRefreshAttemptedAt = null;
+
+    /**
+     * The minimum seconds between forced JWKS refreshes.
+     */
+    protected int $jwksRefreshCooldownSeconds = 10;
+
     /**
      * Get the base URL for the OIDC provider.
      */
@@ -101,9 +113,9 @@ protected function getUserInfoUrl(): ?string
     /**
      * Get the jwks URI for the provider.
      */
-    protected function getJwksUri(): string
+    protected function getJwksUri(bool $refresh = false): string
     {
-        return $this->getOpenIdConfig()['jwks_uri'];
+        return $this->getOpenIdConfig($refresh)['jwks_uri'];
     }
 
     /**
@@ -153,9 +165,9 @@ protected function getCurrentNonce(): ?string
     /**
      * @throws ConfigurationFetchingException
      */
-    protected function getOpenIdConfig(): array
+    protected function getOpenIdConfig(bool $refresh = false): array
     {
-        if ($this->openidConfig) {
+        if ($this->openidConfig && ! $refresh) {
             return $this->openidConfig;
         }
 
@@ -182,20 +194,38 @@ protected function getOpenIdConfigUrl(): string
     /**
      * Get the JSON Web Key Set (JWKS) for the provider.
      */
-    protected function getJwks(): array
+    protected function getJwks(bool $refresh = false): array
     {
-        if ($this->jwks) {
+        if ($this->jwks && ! $refresh) {
             return $this->jwks;
         }
 
+        if ($this->jwks && ! $this->canRefreshJwks($refresh)) {
+            return $this->jwks;
+        }
+
+        if ($refresh) {
+            $this->jwksRefreshAttemptedAt = time();
+        }
+
         $response = $this->getHttpClient()
-            ->get($this->getJwksUri());
+            ->get($this->getJwksUri($refresh));
 
         return $this->jwks = JWK::parseKeySet(
             json_decode((string) $response->getBody(), true)
         );
     }
 
+    /**
+     * Determine if the JWKS can be force-refreshed.
+     */
+    protected function canRefreshJwks(bool $refresh): bool
+    {
+        return ! $refresh
+            || $this->jwksRefreshAttemptedAt === null
+            || (time() - $this->jwksRefreshAttemptedAt) >= $this->jwksRefreshCooldownSeconds;
+    }
+
     /**
      * Receive data from auth/callback route
      * code, id_token, scope, state, session_state.
@@ -243,9 +273,20 @@ protected function isInvalidNonce(string $nonce): bool
      */
     protected function getUserByOIDCToken(string $token): ?array
     {
-        $this->validateOIDCPayload(
-            $data = (array) JWT::decode($token, $this->getJwks())
-        );
+        try {
+            $data = (array) JWT::decode($token, $this->getJwks());
+        } catch (SignatureInvalidException) {
+            // Some providers briefly replace key material under an existing kid.
+            $data = (array) JWT::decode($token, $this->getJwks(refresh: true));
+        } catch (UnexpectedValueException $e) {
+            if (! str_contains($e->getMessage(), '"kid" invalid')) {
+                throw $e;
+            }
+
+            $data = (array) JWT::decode($token, $this->getJwks(refresh: true));
+        }
+
+        $this->validateOIDCPayload($data);
 
         return $data;
     }

tests/Socialite/Fixtures/VerifyingOpenIdTestProviderStub.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Tests\Socialite\Fixtures;
+
+use GuzzleHttp\Client;
+use Hypervel\Socialite\Two\OpenIdProvider;
+use Hypervel\Socialite\Two\User;
+use Mockery as m;
+
+class VerifyingOpenIdTestProviderStub extends OpenIdProvider
+{
+    /**
+     * @var \GuzzleHttp\Client|\Mockery\MockInterface
+     */
+    public $http;
+
+    public function verifyToken(string $token): ?array
+    {
+        return $this->getUserByOIDCToken($token);
+    }
+
+    public function setJwksRefreshCooldownSeconds(int $seconds): void
+    {
+        $this->jwksRefreshCooldownSeconds = $seconds;
+    }
+
+    protected function getBaseUrl(): string
+    {
+        return 'http://base.url';
+    }
+
+    protected function getAuthUrl(?string $state, ?string $nonce = null): string
+    {
+        return $this->buildAuthUrlFromBase('http://auth.url', $state, $nonce);
+    }
+
+    protected function getTokenUrl(): string
+    {
+        return 'http://token.url';
+    }
+
+    protected function getUserByToken(string $token): array
+    {
+        return ['id' => 'foo'];
+    }
+
+    protected function mapUserToObject(array $user): User
+    {
+        return (new User)->map(['id' => $user['sub']]);
+    }
+
+    /**
+     * Get a fresh instance of the Guzzle HTTP client.
+     *
+     * @return \GuzzleHttp\Client|\Mockery\MockInterface
+     */
+    protected function getHttpClient(): Client
+    {
+        if ($this->http) {
+            return $this->http;
+        }
+
+        return $this->http = m::mock(Client::class);
+    }
+}