feat: add CSRF token randomization

app/Config/Security.php

@@ -17,6 +17,17 @@ class Security extends BaseConfig
      */
     public $csrfProtection = 'cookie';
 
+    /**
+     * --------------------------------------------------------------------------
+     * CSRF Token Randomization
+     * --------------------------------------------------------------------------
+     *
+     * Randomize the CSRF Token for added security.
+     *
+     * @var bool
+     */
+    public $tokenRandomize = false;
+
     /**
      * --------------------------------------------------------------------------
      * CSRF Token Name

env

@@ -111,6 +111,7 @@
 #--------------------------------------------------------------------
 
 # security.csrfProtection = 'cookie'
+# security.tokenRandomize = false
 # security.tokenName = 'csrf_token_name'
 # security.headerName = 'X-CSRF-TOKEN'
 # security.cookieName = 'csrf_cookie_name'

system/Security/Security.php

@@ -19,6 +19,7 @@
 use Config\Cookie as CookieConfig;
 use Config\Security as SecurityConfig;
 use Config\Services;
+use LogicException;
 
 /**
  * Class Security
@@ -30,6 +31,7 @@ class Security implements SecurityInterface
 {
     public const CSRF_PROTECTION_COOKIE  = 'cookie';
     public const CSRF_PROTECTION_SESSION = 'session';
+    protected const CSRF_HASH_BYTES      = 16;
 
     /**
      * CSRF Protection Method
@@ -40,6 +42,13 @@ class Security implements SecurityInterface
      */
     protected $csrfProtection = self::CSRF_PROTECTION_COOKIE;
 
+    /**
+     * CSRF Token Randomization
+     *
+     * @var bool
+     */
+    protected $tokenRandomize = false;
+
     /**
      * CSRF Hash
      *
@@ -167,6 +176,7 @@ public function __construct(App $config)
             $this->regenerate     = $security->regenerate ?? $this->regenerate;
             $this->rawCookieName  = $security->cookieName ?? $this->rawCookieName;
             $this->expires        = $security->expires ?? $this->expires;
+            $this->tokenRandomize = $security->tokenRandomize ?? $this->tokenRandomize;
         } else {
             // `Config/Security.php` is absence
             $this->tokenName     = $config->CSRFTokenName ?? $this->tokenName;
@@ -270,7 +280,8 @@ public function verify(RequestInterface $request)
             return $this;
         }
 
-        $token = $this->getPostedToken($request);
+        $token = $this->tokenRandomize ? $this->derandomize($this->getPostedToken($request))
+            : $this->getPostedToken($request);
 
         // Do the tokens match?
         if (! isset($token, $this->hash) || ! hash_equals($this->hash, $token)) {
@@ -329,7 +340,33 @@ private function getPostedToken(RequestInterface $request): ?string
      */
     public function getHash(): ?string
     {
-        return $this->hash;
+        return $this->tokenRandomize ? $this->randomize($this->hash) : $this->hash;
+    }
+
+    /**
+     * Randomize hash to avoid BREACH attacks.
+     */
+    protected function randomize(string $hash): string
+    {
+        $keyBinary  = random_bytes(static::CSRF_HASH_BYTES);
+        $hashBinary = hex2bin($hash);
+
+        if ($hashBinary === false) {
+            throw new LogicException('$hash is invalid: ' . $hash);
+        }
+
+        return bin2hex(($hashBinary ^ $keyBinary) . $keyBinary);
+    }
+
+    /**
+     * Derandomize the token.
+     */
+    protected function derandomize(string $token): string
+    {
+        $key   = substr($token, -static::CSRF_HASH_BYTES * 2);
+        $value = substr($token, 0, static::CSRF_HASH_BYTES * 2);
+
+        return bin2hex(hex2bin($value) ^ hex2bin($key));
     }
 
     /**
@@ -461,7 +498,7 @@ protected function generateHash(): string
                 return $this->hash = $this->session->get($this->tokenName);
             }
 
-            $this->hash = bin2hex(random_bytes(16));
+            $this->hash = bin2hex(random_bytes(static::CSRF_HASH_BYTES));
 
             if ($this->isCSRFCookie()) {
                 $this->saveHashInCookie();

system/Test/Mock/MockSecurity.php

@@ -19,4 +19,12 @@ protected function doSendCookie(): void
     {
         $_COOKIE['csrf_cookie_name'] = $this->hash;
     }
+
+    protected function randomize(string $hash): string
+    {
+        $keyBinary  = hex2bin('005513c290126d34d41bf41c5265e0f1');
+        $hashBinary = hex2bin($hash);
+
+        return bin2hex(($hashBinary ^ $keyBinary) . $keyBinary);
+    }
 }