feat(AppFramework): Add missing NoSameSiteCookieRequired attribute

CarlSchwan · CarlSchwan · commit 6408ed0b5153 · 2026-01-28T21:48:16.000+01:00
Allow to replace the old annotation.

Signed-off-by: Carl Schwan &lt;carl.schwan@nextcloud.com&gt;
diff --git a/apps/files_sharing/lib/Controller/PublicPreviewController.php b/apps/files_sharing/lib/Controller/PublicPreviewController.php
@@ -8,6 +8,7 @@
 
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
+use OCP\AppFramework\Http\Attribute\NoSameSiteCookieRequired;
 use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Attribute\PublicPage;
 use OCP\AppFramework\Http\DataResponse;
@@ -144,8 +145,6 @@ public function getPreview(
 	}
 
 	/**
-	 * @NoSameSiteCookieRequired
-	 *
 	 * Get a direct link preview for a shared file
 	 *
 	 * @param string $token Token of the share
@@ -159,6 +158,7 @@ public function getPreview(
 	#[PublicPage]
 	#[NoCSRFRequired]
 	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT)]
+	#[NoSameSiteCookieRequired]
 	public function directLink(string $token) {
 		// No token no image
 		if ($token === '') {
diff --git a/apps/files_sharing/lib/Controller/ShareController.php b/apps/files_sharing/lib/Controller/ShareController.php
@@ -15,12 +15,12 @@
 use OCP\Accounts\IAccountManager;
 use OCP\AppFramework\AuthPublicShareController;
 use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
+use OCP\AppFramework\Http\Attribute\NoSameSiteCookieRequired;
 use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Attribute\PublicPage;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\Http\NotFoundResponse;
 use OCP\AppFramework\Http\RedirectResponse;
-use OCP\AppFramework\Http\Response;
 use OCP\AppFramework\Http\TemplateResponse;
 use OCP\Constants;
 use OCP\Defaults;
@@ -343,18 +343,13 @@ public function showShare($path = ''): TemplateResponse {
 	}
 
 	/**
-	 * @NoSameSiteCookieRequired
-	 *
-	 * @param string $token
-	 * @param string|null $files
-	 * @param string $path
-	 * @return void|Response
 	 * @throws NotFoundException
 	 * @deprecated 31.0.0 Users are encouraged to use the DAV endpoint
 	 */
 	#[PublicPage]
 	#[NoCSRFRequired]
-	public function downloadShare($token, $files = null, $path = '') {
+	#[NoSameSiteCookieRequired]
+	public function downloadShare(string $token, ?string $files = null, string $path = ''): NotFoundResponse|RedirectResponse|DataResponse {
 		\OC_User::setIncognitoMode(true);
 
 		$share = $this->shareManager->getShareByToken($token);
diff --git a/apps/theming/lib/Controller/ThemingController.php b/apps/theming/lib/Controller/ThemingController.php
@@ -17,6 +17,7 @@
 use OCP\AppFramework\Http\Attribute\AuthorizedAdminSetting;
 use OCP\AppFramework\Http\Attribute\BruteForceProtection;
 use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
+use OCP\AppFramework\Http\Attribute\NoSameSiteCookieRequired;
 use OCP\AppFramework\Http\Attribute\NoTwoFactorRequired;
 use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Attribute\PublicPage;
@@ -377,8 +378,6 @@ public function getImage(string $key, bool $useSvg = true) {
 	}
 
 	/**
-	 * @NoSameSiteCookieRequired
-	 *
 	 * Get the CSS stylesheet for a theme
 	 *
 	 * @param string $themeId ID of the theme
@@ -393,6 +392,7 @@ public function getImage(string $key, bool $useSvg = true) {
 	#[NoCSRFRequired]
 	#[NoTwoFactorRequired]
 	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT)]
+	#[NoSameSiteCookieRequired]
 	public function getThemeStylesheet(string $themeId, bool $plain = false, bool $withCustomCss = false) {
 		$themes = $this->themesService->getThemes();
 		if (!in_array($themeId, array_keys($themes))) {
diff --git a/core/Controller/AvatarController.php b/core/Controller/AvatarController.php
@@ -13,6 +13,7 @@
 use OCP\AppFramework\Http\Attribute\FrontpageRoute;
 use OCP\AppFramework\Http\Attribute\NoAdminRequired;
 use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
+use OCP\AppFramework\Http\Attribute\NoSameSiteCookieRequired;
 use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Attribute\PublicPage;
 use OCP\AppFramework\Http\FileDisplayResponse;
@@ -50,8 +51,6 @@ public function __construct(
 	}
 
 	/**
-	 * @NoSameSiteCookieRequired
-	 *
 	 * Get the dark avatar
 	 *
 	 * @param string $userId ID of the user
@@ -67,6 +66,7 @@ public function __construct(
 	#[PublicPage]
 	#[FrontpageRoute(verb: 'GET', url: '/avatar/{userId}/{size}/dark')]
 	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT)]
+	#[NoSameSiteCookieRequired]
 	public function getAvatarDark(string $userId, int $size, bool $guestFallback = false) {
 		if ($size <= 64) {
 			if ($size !== 64) {
@@ -102,8 +102,6 @@ public function getAvatarDark(string $userId, int $size, bool $guestFallback = f
 
 
 	/**
-	 * @NoSameSiteCookieRequired
-	 *
 	 * Get the avatar
 	 *
 	 * @param string $userId ID of the user
@@ -119,6 +117,7 @@ public function getAvatarDark(string $userId, int $size, bool $guestFallback = f
 	#[PublicPage]
 	#[FrontpageRoute(verb: 'GET', url: '/avatar/{userId}/{size}')]
 	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT)]
+	#[NoSameSiteCookieRequired]
 	public function getAvatar(string $userId, int $size, bool $guestFallback = false) {
 		if ($size <= 64) {
 			if ($size !== 64) {
diff --git a/core/Controller/ClientFlowLoginController.php b/core/Controller/ClientFlowLoginController.php
@@ -17,6 +17,7 @@
 use OCP\AppFramework\Http\Attribute\FrontpageRoute;
 use OCP\AppFramework\Http\Attribute\NoAdminRequired;
 use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
+use OCP\AppFramework\Http\Attribute\NoSameSiteCookieRequired;
 use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Attribute\PasswordConfirmationRequired;
 use OCP\AppFramework\Http\Attribute\PublicPage;
@@ -171,13 +172,11 @@ public function showAuthPickerPage(string $clientIdentifier = '', string $user =
 		return $response;
 	}
 
-	/**
-	 * @NoSameSiteCookieRequired
-	 */
 	#[NoAdminRequired]
 	#[NoCSRFRequired]
 	#[UseSession]
 	#[FrontpageRoute(verb: 'GET', url: '/login/flow/grant')]
+	#[NoSameSiteCookieRequired]
 	public function grantPage(
 		string $stateToken = '',
 		string $clientIdentifier = '',
diff --git a/core/Controller/ClientFlowLoginV2Controller.php b/core/Controller/ClientFlowLoginV2Controller.php
@@ -18,6 +18,7 @@
 use OCP\AppFramework\Http\Attribute\FrontpageRoute;
 use OCP\AppFramework\Http\Attribute\NoAdminRequired;
 use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
+use OCP\AppFramework\Http\Attribute\NoSameSiteCookieRequired;
 use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Attribute\PasswordConfirmationRequired;
 use OCP\AppFramework\Http\Attribute\PublicPage;
@@ -142,14 +143,12 @@ public function showAuthPickerPage(string $user = '', int $direct = 0): Standalo
 		);
 	}
 
-	/**
-	 * @NoSameSiteCookieRequired
-	 */
 	#[NoAdminRequired]
 	#[NoCSRFRequired]
 	#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 	#[UseSession]
 	#[FrontpageRoute(verb: 'GET', url: '/login/v2/grant')]
+	#[NoSameSiteCookieRequired]
 	public function grantPage(?string $stateToken, int $direct = 0): StandaloneTemplateResponse {
 		if ($stateToken === null) {
 			return $this->stateTokenMissingResponse();
diff --git a/core/Controller/CssController.php b/core/Controller/CssController.php
@@ -13,11 +13,11 @@
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\Attribute\FrontpageRoute;
 use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
+use OCP\AppFramework\Http\Attribute\NoSameSiteCookieRequired;
 use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Attribute\PublicPage;
 use OCP\AppFramework\Http\FileDisplayResponse;
 use OCP\AppFramework\Http\NotFoundResponse;
-use OCP\AppFramework\Http\Response;
 use OCP\AppFramework\Utility\ITimeFactory;
 use OCP\Files\IAppData;
 use OCP\Files\NotFoundException;
@@ -41,21 +41,19 @@ public function __construct(
 	}
 
 	/**
-	 * @NoSameSiteCookieRequired
-	 *
 	 * @param string $fileName css filename with extension
 	 * @param string $appName css folder name
-	 * @return FileDisplayResponse|NotFoundResponse
 	 */
 	#[PublicPage]
 	#[NoCSRFRequired]
 	#[FrontpageRoute(verb: 'GET', url: '/css/{appName}/{fileName}')]
-	public function getCss(string $fileName, string $appName): Response {
+	#[NoSameSiteCookieRequired]
+	public function getCss(string $fileName, string $appName): FileDisplayResponse|NotFoundResponse {
 		try {
 			$folder = $this->appData->getFolder($appName);
 			$gzip = false;
 			$file = $this->getFile($folder, $fileName, $gzip);
-		} catch (NotFoundException $e) {
+		} catch (NotFoundException) {
 			return new NotFoundResponse();
 		}
 
diff --git a/core/Controller/JsController.php b/core/Controller/JsController.php
@@ -13,12 +13,12 @@
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\Attribute\FrontpageRoute;
 use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
+use OCP\AppFramework\Http\Attribute\NoSameSiteCookieRequired;
 use OCP\AppFramework\Http\Attribute\NoTwoFactorRequired;
 use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Attribute\PublicPage;
 use OCP\AppFramework\Http\FileDisplayResponse;
 use OCP\AppFramework\Http\NotFoundResponse;
-use OCP\AppFramework\Http\Response;
 use OCP\AppFramework\Utility\ITimeFactory;
 use OCP\Files\IAppData;
 use OCP\Files\NotFoundException;
@@ -42,15 +42,14 @@ public function __construct(
 	}
 
 	/**
-	 * @NoSameSiteCookieRequired
-	 *
 	 * @param string $fileName js filename with extension
 	 * @param string $appName js folder name
 	 */
 	#[PublicPage]
 	#[NoCSRFRequired]
 	#[FrontpageRoute(verb: 'GET', url: '/js/{appName}/{fileName}')]
 	#[NoTwoFactorRequired]
+	#[NoSameSiteCookieRequired]
 	public function getJs(string $fileName, string $appName): FileDisplayResponse|NotFoundResponse {
 		try {
 			$folder = $this->appData->getFolder($appName);
diff --git a/lib/composer/composer/autoload_classmap.php b/lib/composer/composer/autoload_classmap.php
@@ -93,6 +93,7 @@
     'OCP\\AppFramework\\Http\\Attribute\\IgnoreOpenAPI' => $baseDir . '/lib/public/AppFramework/Http/Attribute/IgnoreOpenAPI.php',
     'OCP\\AppFramework\\Http\\Attribute\\NoAdminRequired' => $baseDir . '/lib/public/AppFramework/Http/Attribute/NoAdminRequired.php',
     'OCP\\AppFramework\\Http\\Attribute\\NoCSRFRequired' => $baseDir . '/lib/public/AppFramework/Http/Attribute/NoCSRFRequired.php',
+    'OCP\\AppFramework\\Http\\Attribute\\NoSameSiteCookieRequired' => $baseDir . '/lib/public/AppFramework/Http/Attribute/NoSameSiteCookieRequired.php',
     'OCP\\AppFramework\\Http\\Attribute\\NoTwoFactorRequired' => $baseDir . '/lib/public/AppFramework/Http/Attribute/NoTwoFactorRequired.php',
     'OCP\\AppFramework\\Http\\Attribute\\OpenAPI' => $baseDir . '/lib/public/AppFramework/Http/Attribute/OpenAPI.php',
     'OCP\\AppFramework\\Http\\Attribute\\PasswordConfirmationRequired' => $baseDir . '/lib/public/AppFramework/Http/Attribute/PasswordConfirmationRequired.php',
diff --git a/lib/composer/composer/autoload_static.php b/lib/composer/composer/autoload_static.php
@@ -134,6 +134,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OCP\\AppFramework\\Http\\Attribute\\IgnoreOpenAPI' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/IgnoreOpenAPI.php',
         'OCP\\AppFramework\\Http\\Attribute\\NoAdminRequired' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/NoAdminRequired.php',
         'OCP\\AppFramework\\Http\\Attribute\\NoCSRFRequired' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/NoCSRFRequired.php',
+        'OCP\\AppFramework\\Http\\Attribute\\NoSameSiteCookieRequired' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/NoSameSiteCookieRequired.php',
         'OCP\\AppFramework\\Http\\Attribute\\NoTwoFactorRequired' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/NoTwoFactorRequired.php',
         'OCP\\AppFramework\\Http\\Attribute\\OpenAPI' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/OpenAPI.php',
         'OCP\\AppFramework\\Http\\Attribute\\PasswordConfirmationRequired' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/PasswordConfirmationRequired.php',
diff --git a/lib/private/AppFramework/Http/Attributes/TwoFactorSetUpDoneRequired.php b/lib/private/AppFramework/Http/Attributes/TwoFactorSetUpDoneRequired.php
@@ -12,7 +12,7 @@
 
 use Attribute;
 
-#[Attribute]
+#[Attribute(Attribute::TARGET_METHOD)]
 class TwoFactorSetUpDoneRequired {
 
 }
diff --git a/lib/private/AppFramework/Middleware/Security/SameSiteCookieMiddleware.php b/lib/private/AppFramework/Middleware/Security/SameSiteCookieMiddleware.php
@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 /**
  * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors
  * SPDX-License-Identifier: AGPL-3.0-or-later
@@ -10,13 +12,17 @@
 use OC\AppFramework\Middleware\Security\Exceptions\LaxSameSiteCookieFailedException;
 use OC\AppFramework\Utility\ControllerMethodReflector;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\NoSameSiteCookieRequired;
 use OCP\AppFramework\Http\Response;
 use OCP\AppFramework\Middleware;
+use Psr\Log\LoggerInterface;
+use ReflectionMethod;
 
 class SameSiteCookieMiddleware extends Middleware {
 	public function __construct(
-		private Request $request,
-		private ControllerMethodReflector $reflector,
+		private readonly Request $request,
+		private readonly ControllerMethodReflector $reflector,
+		private readonly LoggerInterface $logger,
 	) {
 	}
 
@@ -29,7 +35,8 @@ public function beforeController($controller, $methodName) {
 			return;
 		}
 
-		$noSSC = $this->reflector->hasAnnotation('NoSameSiteCookieRequired');
+		$reflectionMethod = new ReflectionMethod($controller, $methodName);
+		$noSSC = $this->hasAnnotationOrAttribute($reflectionMethod, 'NoSameSiteCookieRequired', NoSameSiteCookieRequired::class);
 		if ($noSSC) {
 			return;
 		}
@@ -80,4 +87,25 @@ protected function setSameSiteCookie(): void {
 			);
 		}
 	}
+
+	/**
+	 * @template T
+	 *
+	 * @param ReflectionMethod $reflectionMethod
+	 * @param ?string $annotationName
+	 * @param class-string<T> $attributeClass
+	 * @return boolean
+	 */
+	protected function hasAnnotationOrAttribute(ReflectionMethod $reflectionMethod, ?string $annotationName, string $attributeClass): bool {
+		if (!empty($reflectionMethod->getAttributes($attributeClass))) {
+			return true;
+		}
+
+		if ($annotationName && $this->reflector->hasAnnotation($annotationName)) {
+			$this->logger->debug($reflectionMethod->getDeclaringClass()->getName() . '::' . $reflectionMethod->getName() . ' uses the @' . $annotationName . ' annotation and should use the #[' . $attributeClass . '] attribute instead');
+			return true;
+		}
+
+		return false;
+	}
 }
diff --git a/lib/public/AppFramework/Http/Attribute/NoSameSiteCookieRequired.php b/lib/public/AppFramework/Http/Attribute/NoSameSiteCookieRequired.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH
+ * SPDX-FileContributor: Carl Schwan
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\AppFramework\Http\Attribute;
+
+use Attribute;
+use OCP\AppFramework\Attribute\Consumable;
+
+/**
+ * Attribute for controller methods that want to disable the same site cookies
+ * requirements.
+ *
+ * @since 33.0.0
+ */
+#[Attribute(Attribute::TARGET_METHOD)]
+#[Consumable(since: '33.0.0')]
+class NoSameSiteCookieRequired {
+}
diff --git a/lib/public/AppFramework/Http/Attribute/NoTwoFactorRequired.php b/lib/public/AppFramework/Http/Attribute/NoTwoFactorRequired.php
@@ -11,15 +11,20 @@
 namespace OCP\AppFramework\Http\Attribute;
 
 use Attribute;
+use OCP\AppFramework\Attribute\Consumable;
 
 /**
+ * Attribute for controller methods that want to disable the two factor
+ * authentification requirements.
+ *
  * A user can access the page before the two-factor challenge has been passed
  * (use this wisely and only in two-factor auth apps, e.g. to allow setup during
  * login).
  *
  * @since 33.0.0
  */
-#[Attribute]
+#[Attribute(Attribute::TARGET_METHOD)]
+#[Consumable(since: '33.0.0')]
 class NoTwoFactorRequired {
 
 }
diff --git a/tests/lib/AppFramework/Middleware/Security/SameSiteCookieMiddlewareTest.php b/tests/lib/AppFramework/Middleware/Security/SameSiteCookieMiddlewareTest.php
