added SameSite enum; setCookie() and Session accept it, IResponse::SameSite* constants deprecated

Author: dg

src/Bridges/HttpDI/SessionExtension.php

@@ -8,7 +8,7 @@
 namespace Nette\Bridges\HttpDI;
 
 use Nette;
-use Nette\Http\IResponse;
+use Nette\Http\SameSite;
 use Nette\Schema\Expect;
 
 
@@ -42,7 +42,7 @@ public function getConfigSchema(): Nette\Schema\Schema
 			'expiration' => Expect::string()->dynamic(),
 			'handler' => Expect::string()->dynamic(),
 			'readAndClose' => Expect::bool(),
-			'cookieSamesite' => Expect::anyOf(IResponse::SameSiteLax, IResponse::SameSiteStrict, IResponse::SameSiteNone)
+			'cookieSamesite' => Expect::anyOf(SameSite::Lax->value, SameSite::Strict->value, SameSite::None->value)
 				->firstIsDefault(),
 		])->otherItems();
 	}

src/Http/Helpers.php

@@ -119,7 +119,7 @@ public static function ipMatch(string $ip, string $mask): bool
 	public static function initCookie(IRequest $request, IResponse $response): void
 	{
 		if ($request->getHeader('Sec-Fetch-Site') === null) {
-			$response->setCookie(self::StrictCookieName, '1', null, '/', sameSite: IResponse::SameSiteStrict);
+			$response->setCookie(self::StrictCookieName, '1', null, '/', sameSite: SameSite::Strict);
 		}
 	}
 }

src/Http/IResponse.php

@@ -138,7 +138,7 @@ interface IResponse
 		511 => 'Network Authentication Required',
 	];
 
-	/** SameSite cookie */
+	/** @deprecated use Nette\Http\SameSite enum */
 	public const
 		SameSiteLax = 'Lax',
 		SameSiteStrict = 'Strict',

src/Http/Response.php

@@ -225,7 +225,7 @@ public function getHeaders(): array
 
 	/**
 	 * Sends a cookie.
-	 * @param self::SameSite*|null  $sameSite
+	 * @param SameSite|self::SameSite*|null  $sameSite
 	 * @throws Nette\InvalidStateException  if HTTP headers have been sent
 	 */
 	public function setCookie(
@@ -236,11 +236,12 @@ public function setCookie(
 		?string $domain = null,
 		?bool $secure = null,
 		?bool $httpOnly = null,
-		?string $sameSite = null,
+		SameSite|string|null $sameSite = null,
 		bool $partitioned = false,
 	): static
 	{
 		self::checkHeaders();
+		$sameSite = $sameSite instanceof SameSite ? $sameSite->value : $sameSite;
 		[$path, $domain] = [ // resolve the defaults first, so the final values (incl. those from cookiePath/cookieDomain) are validated
 			$path ?? ($domain ? '/' : $this->cookiePath),
 			$domain ?? ($path ? '' : $this->cookieDomain),
@@ -258,9 +259,9 @@ public function setCookie(
 		}
 
 		$seconds = Helpers::expirationToSeconds($expire);
-		$sameSite ??= self::SameSiteLax;
+		$sameSite ??= SameSite::Lax->value;
 		// both SameSite=None and Partitioned are rejected by the browser without the Secure attribute
-		$secure = $sameSite === self::SameSiteNone || $partitioned
+		$secure = $sameSite === SameSite::None->value || $partitioned
 			? true
 			: $secure ?? $this->cookieSecure;
 		// the value is raw-url-encoded the same way PHP reads it back from $_COOKIE;

src/Http/Session.php

@@ -40,7 +40,7 @@ class Session
 
 	/** @var array<string, mixed> default configuration */
 	private array $options = [
-		'cookie_samesite' => IResponse::SameSiteLax,
+		'cookie_samesite' => SameSite::Lax->value,
 		'cookie_lifetime' => 0,   // session cookie - kept by the browser per its own policy
 		'gc_maxlifetime' => self::DefaultFileLifetime, // server-side idle timeout, independent of the cookie lifetime above
 	];
@@ -509,14 +509,14 @@ public function setCookieParameters(
 		string $path,
 		?string $domain = null,
 		?bool $secure = null,
-		?string $sameSite = null,
+		SameSite|string|null $sameSite = null,
 	): static
 	{
 		return $this->setOptions([
 			'cookie_path' => $path,
 			'cookie_domain' => $domain,
 			'cookie_secure' => $secure,
-			'cookie_samesite' => $sameSite,
+			'cookie_samesite' => $sameSite instanceof SameSite ? $sameSite->value : $sameSite,
 		]);
 	}
 

src/Http/enums.php

@@ -60,3 +60,20 @@ enum FetchDest: string
 	case Worker = 'worker';
 	case Xslt = 'xslt';
 }
+
+
+/**
+ * Values of the SameSite cookie attribute, controlling whether the cookie is sent with
+ * cross-site requests (a protection against CSRF).
+ */
+enum SameSite: string
+{
+	/** sent with same-site requests and top-level cross-site navigation (the safe default) */
+	case Lax = 'Lax';
+
+	/** sent only with same-site requests, never when coming from a foreign site */
+	case Strict = 'Strict';
+
+	/** sent with all requests, including cross-site; requires the Secure attribute */
+	case None = 'None';
+}

tests/Http/Response.setCookie.phpt

@@ -138,19 +138,31 @@ Assert::exception(
 // SameSite=None forces the Secure attribute (otherwise the browser rejects the cookie)
 $response = new Http\Response;
 $old = headers_list();
-$response->setCookie('test', 'value', null, sameSite: Http\IResponse::SameSiteNone);
+$response->setCookie('test', 'value', null, sameSite: Http\SameSite::None);
 $headers = array_values(array_diff(headers_list(), $old, ['Set-Cookie:']));
 Assert::same(['Set-Cookie: test=value; path=/; secure; HttpOnly; SameSite=None'], $headers);
 
 
 // Partitioned (CHIPS) adds the attribute and forces Secure
 $response = new Http\Response;
 $old = headers_list();
-$response->setCookie('test', 'value', null, sameSite: Http\IResponse::SameSiteNone, partitioned: true);
+$response->setCookie('test', 'value', null, sameSite: Http\SameSite::None, partitioned: true);
 $headers = array_values(array_diff(headers_list(), $old, ['Set-Cookie:']));
 Assert::same(['Set-Cookie: test=value; path=/; secure; HttpOnly; SameSite=None; Partitioned'], $headers);
 
 
+// the SameSite enum and the equivalent string produce the same header
+$response = new Http\Response;
+$old = headers_list();
+$response->setCookie('test', 'a', null, sameSite: Http\SameSite::Strict);
+$response->setCookie('test', 'b', null, sameSite: 'Strict');
+$headers = array_values(array_diff(headers_list(), $old, ['Set-Cookie:']));
+Assert::same([
+	'Set-Cookie: test=a; path=/; HttpOnly; SameSite=Strict',
+	'Set-Cookie: test=b; path=/; HttpOnly; SameSite=Strict',
+], $headers);
+
+
 // integer 0 is deprecated, but kept as a session cookie for BC
 $response = new Http\Response;
 $old = headers_list();