[SDK-2741] Improvements to session/transient cookie storage (#542)

* feat: Improvements to cookie handling

* tests: Update tests for new cookie handling

* tests: Testing improvements

* tests: Testing improvements

* Apply feedback: remove join() instances

* Fix merge conflicts

* Fix merge conflicts

* fix: Don't unnecessarily bas64_encode the cookie payload

* tests: Fix for static analysis warning

* tests: Fix for static analysis warning

* tests: Fix merge conflicts

* tests: Fix code styling warnings from merge

* Implement review feedback from @jimmyjames

Author: evansims

composer.json

@@ -29,18 +29,18 @@
   ],
   "require": {
     "php": "^7.4 || ^8.0",
-    "ext-json": "*",
-    "ext-openssl": "*",
     "ext-filter": "*",
+    "ext-json": "*",
     "ext-mbstring": "*",
+    "ext-openssl": "*",
     "php-http/discovery": "^1.0",
     "php-http/httplug": "^2.2",
     "php-http/multipart-stream-builder": "^1.1",
     "psr/cache": "^1.0 || ^2.0 || ^3.0",
     "psr/event-dispatcher": "^1.0",
     "psr/http-client-implementation": "^1.0",
-    "psr/http-message-implementation": "^1.0",
-    "psr/http-factory-implementation": "^1.0"
+    "psr/http-factory-implementation": "^1.0",
+    "psr/http-message-implementation": "^1.0"
   },
   "require-dev": {
     "symfony/cache": "^4.4 || ^5.2",

phpinsights.php

@@ -46,9 +46,12 @@
         ],
         \SlevomatCodingStandard\Sniffs\Functions\UnusedParameterSniff::class => [
             'exclude' => [
+                'src/API/Management.php',
                 'src/Configuration/SdkConfiguration.php',
                 'src/Configuration/SdkState.php',
-                'src/API/Management.php',
+                'src/Store/SessionStore.php',
+                'src/Store/InMemoryStorage.php',
+                'src/Store/Psr6Store.php',
             ],
         ],
         \SlevomatCodingStandard\Sniffs\Classes\ModernClassNameReferenceSniff::class => [

phpstan.neon.dist

@@ -43,6 +43,8 @@ parameters:
         - '#Cannot call method get\(\) on Auth0\\SDK\\Contract\\StoreInterface\|null.#'
         - '#Cannot call method set\(\) on Auth0\\SDK\\Contract\\StoreInterface\|null.#'
         - '#Cannot call method delete\(\) on Auth0\\SDK\\Contract\\StoreInterface\|null.#'
+        - '#Cannot call method defer\(\) on Auth0\\SDK\\Contract\\StoreInterface\|null.#'
+        - '#Cannot call method purge\(\) on Auth0\\SDK\\Contract\\StoreInterface\|null.#'
         - '#Instanceof between Auth0\\SDK\\Configuration\\SdkConfiguration and Auth0\\SDK\\Configuration\\SdkConfiguration will always evaluate to true.#'
         - '#caught "Throwable" must be rethrown.#'
         - '#Class OpenSSLAsymmetricKey not found.#'

src/Auth0.php

@@ -176,17 +176,20 @@ public function logout(
      */
     public function clear(): self
     {
-        $sessionStorage = $this->configuration()->getSessionStorage();
-        $transientStorage = $this->configuration()->getTransientStorage();
-
-        if ($sessionStorage !== null) {
-            $sessionStorage->deleteAll();
+        // Delete all data in the session storage medium.
+        if ($this->configuration()->hasSessionStorage()) {
+            $this->configuration->getSessionStorage()->purge();
         }
 
-        if ($transientStorage !== null) {
-            $transientStorage->deleteAll();
+        // Delete all data in the transient storage medium.
+        if ($this->configuration()->hasTransientStorage()) {
+            $this->configuration->getTransientStorage()->purge();
         }
 
+        // If state saving had been deferred, disable it and force a update to persistent storage.
+        $this->deferStateSaving(false);
+
+        // Reset the internal state.
         $this->getState()->reset();
 
         return $this;
@@ -259,6 +262,8 @@ public function decode(
     public function exchange(
         ?string $redirectUri = null
     ): bool {
+        $this->deferStateSaving();
+
         $code = $this->getRequestParameter('code');
         $state = $this->getRequestParameter('state');
         $codeVerifier = null;
@@ -277,6 +282,7 @@ public function exchange(
             $codeVerifier = $this->getTransientStore()->getOnce('code_verifier');
 
             if ($codeVerifier === null) {
+                $this->clear();
                 throw \Auth0\SDK\Exception\StateException::missingCodeVerifier();
             }
         }
@@ -333,6 +339,8 @@ public function exchange(
         }
 
         $this->setUser($user ?? []);
+        $this->deferStateSaving(false);
+
         return true;
     }
 
@@ -352,16 +360,19 @@ public function exchange(
     public function renew(
         ?array $params = null
     ): self {
+        $this->deferStateSaving();
         $refreshToken = $this->getState()->getRefreshToken();
 
         if ($refreshToken === null) {
+            $this->clear();
             throw \Auth0\SDK\Exception\StateException::failedRenewTokenMissingRefreshToken();
         }
 
         $response = $this->authentication()->refreshToken($refreshToken, $params);
         $response = HttpResponse::decodeContent($response);
 
         if (! isset($response['access_token']) || ! $response['access_token']) {
+            $this->clear();
             throw \Auth0\SDK\Exception\StateException::failedRenewTokenMissingAccessToken();
         }
 
@@ -371,6 +382,8 @@ public function renew(
             $this->setIdToken($response['id_token']);
         }
 
+        $this->deferStateSaving(false);
+
         return $this;
     }
 
@@ -709,4 +722,24 @@ private function getState(): SdkState
 
         return $this->state;
     }
+
+    /**
+     * Defer saving transient or session states to destination medium.
+     * Improves performance during large blocks of changes.
+     *
+     * @param bool $deferring Whether to defer persisting the storage state.
+     */
+    private function deferStateSaving(
+        bool $deferring = true
+    ): self {
+        if ($this->configuration()->hasSessionStorage()) {
+            $this->configuration()->getSessionStorage()->defer($deferring);
+        }
+
+        if ($this->configuration()->hasTransientStorage()) {
+            $this->configuration()->getTransientStorage()->defer($deferring);
+        }
+
+        return $this;
+    }
 }

src/Configuration/SdkConfiguration.php

@@ -52,6 +52,7 @@
  * @method SdkConfiguration setResponseType(string $responseType = 'code')
  * @method SdkConfiguration setScope(?array $scope = null)
  * @method SdkConfiguration setSessionStorage(?StoreInterface $sessionStorage = null)
+ * @method SdkConfiguration setSessionStorageId(string $sessionStorageId = 'auth0_session')
  * @method SdkConfiguration setStrategy(string $strategy = 'webapp')
  * @method SdkConfiguration setTokenAlgorithm(string $tokenAlgorithm = 'RS256')
  * @method SdkConfiguration setTokenCache(?CacheItemPoolInterface $cache = null)
@@ -60,6 +61,7 @@
  * @method SdkConfiguration setTokenLeeway(int $tokenLeeway = 60)
  * @method SdkConfiguration setTokenMaxAge(?int $tokenMaxAge = null)
  * @method SdkConfiguration setTransientStorage(?StoreInterface $transientStorage = null)
+ * @method SdkConfiguration setTransientStorageId(string $transientStorageId = 'auth0_transient')
  * @method SdkConfiguration setUsePkce(bool $usePkce)
  *
  * @method array<string>|null getAudience(?\Throwable $exceptionIfNull = null)
@@ -91,6 +93,7 @@
  * @method string getResponseType()
  * @method array<string> getScope()
  * @method StoreInterface|null getSessionStorage(?\Throwable $exceptionIfNull = null)
+ * @method string getSessionStorageId()
  * @method string getStrategy()
  * @method string getTokenAlgorithm()
  * @method CacheItemPoolInterface|null getTokenCache(?\Throwable $exceptionIfNull = null)
@@ -99,6 +102,7 @@
  * @method int|null getTokenLeeway(?\Throwable $exceptionIfNull = null)
  * @method int|null getTokenMaxAge(?\Throwable $exceptionIfNull = null)
  * @method StoreInterface|null getTransientStorage(?\Throwable $exceptionIfNull = null)
+ * @method string getTransientStorageId()
  * @method bool getUsePkce()
  *
  * @method bool hasAudience()
@@ -130,13 +134,15 @@
  * @method bool hasResponseType()
  * @method bool hasScope()
  * @method bool hasSessionStorage()
+ * @method bool hasSessionStorageId()
  * @method bool hasStrategy()
  * @method bool hasTokenAlgorithm()
  * @method bool hasTokenCache()
  * @method bool hasTokenCacheTtl()
  * @method bool hasTokenLeeway()
  * @method bool hasTokenMaxAge()
  * @method bool hasTransientStorage()
+ * @method bool hasTransientStorageId()
  * @method bool hasUsePkce()
  *
  * @method bool pushScope($scope)
@@ -180,6 +186,7 @@ final class SdkConfiguration implements ConfigurableContract
      * @param StreamFactoryInterface|null    $httpStreamFactory     A PSR-17 compatible stream factory to create request body streams.
      * @param bool                           $httpTelemetry         Defaults to true. If true, API requests will include telemetry about the SDK and PHP runtime version to help us improve our services.
      * @param StoreInterface|null            $sessionStorage        Defaults to use cookies. A StoreInterface-compatible class for storing Token state.
+     * @param string                         $sessionStorageId      Defaults to 'auth0_session'. The namespace to prefix session items under.
      * @param string|null                    $cookieSecret          The secret used to derive an encryption key for the user identity in a session cookie and to sign the transient cookies used by the login callback.
      * @param string|null                    $cookieDomain          Defaults to value of HTTP_HOST server environment information. Cookie domain, for example 'www.example.com', for use with PHP sessions and SDK cookies. To make cookies visible on all subdomains then the domain must be prefixed with a dot like '.example.com'.
      * @param int                            $cookieExpires         Defaults to 0. How long, in seconds, before cookies expire. If set to 0 the cookie will expire at the end of the session (when the browser closes).
@@ -190,6 +197,7 @@ final class SdkConfiguration implements ConfigurableContract
      * @param bool                           $persistAccessToken    Defaults to true. If true, the Access Token will persist in session storage.
      * @param bool                           $persistRefreshToken   Defaults to true. If true, the Refresh Token will persist in session storage.
      * @param StoreInterface|null            $transientStorage      Defaults to use cookies. A StoreInterface-compatible class for storing ephemeral state data, such as nonces.
+     * @param string                         $transientStorageId    Defaults to 'auth0_transient'. The namespace to prefix transient items under.
      * @param bool                           $queryUserInfo         Defaults to false. If true, query the /userinfo endpoint during an authorization code exchange.
      * @param string|null                    $managementToken       An Access Token to use for Management API calls. If there isn't one specified, the SDK will attempt to get one for you using your $clientSecret.
      * @param CacheItemPoolInterface|null    $managementTokenCache  A PSR-6 compatible cache adapter for storing generated management access tokens.
@@ -223,6 +231,7 @@ public function __construct(
         ?StreamFactoryInterface $httpStreamFactory = null,
         bool $httpTelemetry = true,
         ?StoreInterface $sessionStorage = null,
+        string $sessionStorageId = 'auth0_session',
         ?string $cookieSecret = null,
         ?string $cookieDomain = null,
         int $cookieExpires = 0,
@@ -233,6 +242,7 @@ public function __construct(
         bool $persistAccessToken = true,
         bool $persistRefreshToken = true,
         ?StoreInterface $transientStorage = null,
+        string $transientStorageId = 'auth0_transient',
         bool $queryUserInfo = false,
         ?string $managementToken = null,
         ?CacheItemPoolInterface $managementTokenCache = null,
@@ -389,11 +399,11 @@ private function setupStateFactories(): void
     private function setupStateStorage(): void
     {
         if (! $this->getSessionStorage() instanceof StoreInterface) {
-            $this->setSessionStorage(new CookieStore($this, 'auth0_session'));
+            $this->setSessionStorage(new CookieStore($this, $this->getSessionStorageId()));
         }
 
         if (! $this->getTransientStorage() instanceof StoreInterface) {
-            $this->setTransientStorage(new CookieStore($this, 'auth0_transient'));
+            $this->setTransientStorage(new CookieStore($this, $this->getTransientStorageId()));
         }
     }
 

src/Contract/StoreInterface.php

@@ -23,14 +23,14 @@ public function set(
     /**
      * Get a value from the store by a given key.
      *
-     * @param string      $key     Key to get.
-     * @param string|null $default Return value if key not found.
+     * @param string $key     Key to get.
+     * @param mixed  $default Return value if key not found.
      *
      * @return mixed
      */
     public function get(
         string $key,
-        ?string $default = null
+        $default = null
     );
 
     /**
@@ -45,5 +45,12 @@ public function delete(
     /**
      * Remove all stored values
      */
-    public function deleteAll(): void;
+    public function purge(): void;
+
+    /**
+     * Defer saving state changes to destination to improve performance during blocks of changes.
+     */
+    public function defer(
+        bool $deferring
+    ): void;
 }