karlitschek · Oct 20, 2026
@@ -12,6 +12,7 @@
 use OC\NavigationManager;
 use OC\Profiler\BuiltInProfiler;
 use OC\Security\CSP\ContentSecurityPolicyNonceManager;
+use OC\Security\Guard\RequestGuardManager;
 use OC\Share20\GroupDeletedListener;
 use OC\Share20\Hooks;
 use OC\Share20\UserDeletedListener;
@@ -420,6 +421,26 @@ private static function getProductName(): string {
 		return $productName;
 	}
 
+	/**
+	 * Lets apps refuse a request before the session is started,
+	 * e.g. one from a banned address.
+	 */
+	private static function checkRequestGuards(): void {
+		$decision = Server::get(RequestGuardManager::class)->check(Server::get(IRequest::class));
+		if ($decision === null) {
+			return;
+		}
+
+		http_response_code(403);
+		header('Retry-After: ' . $decision->getRetryAfter());
+		header('Content-Type: text/plain; charset=utf-8');
+		echo Server::get(\OCP\L10N\IFactory::class)->get('lib')->t(
+			'Access from your network is temporarily blocked. If you think this is a mistake, contact your administrator and give them this reference: %s',
+			[$decision->getReference()]
+		);
+		exit();
+	}
+
 	public static function initSession(): void {
 		$request = Server::get(IRequest::class);
 
@@ -833,6 +854,10 @@ public static function initForRequest(): void {
 		$bootstrapCoordinator = Server::get(\OC\AppFramework\Bootstrap\Coordinator::class);
 		$bootstrapCoordinator->runInitialRegistration();
 
+		if (!self::$CLI) {
+			self::checkRequestGuards();
+		}
+
 		$eventLogger->start('init_session', 'Initialize session');
 
 		$systemConfig = Server::get(\OC\SystemConfig::class);

@@ -885,6 +885,8 @@
     'OCP\\Security\\Events\\GenerateSecurePasswordEvent' => $baseDir . '/lib/public/Security/Events/GenerateSecurePasswordEvent.php',
     'OCP\\Security\\Events\\ValidatePasswordPolicyEvent' => $baseDir . '/lib/public/Security/Events/ValidatePasswordPolicyEvent.php',
     'OCP\\Security\\FeaturePolicy\\AddFeaturePolicyEvent' => $baseDir . '/lib/public/Security/FeaturePolicy/AddFeaturePolicyEvent.php',
+    'OCP\\Security\\Guard\\GuardDecision' => $baseDir . '/lib/public/Security/Guard/GuardDecision.php',
+    'OCP\\Security\\Guard\\IRequestGuard' => $baseDir . '/lib/public/Security/Guard/IRequestGuard.php',
     'OCP\\Security\\IContentSecurityPolicyManager' => $baseDir . '/lib/public/Security/IContentSecurityPolicyManager.php',
     'OCP\\Security\\ICredentialsManager' => $baseDir . '/lib/public/Security/ICredentialsManager.php',
     'OCP\\Security\\ICrypto' => $baseDir . '/lib/public/Security/ICrypto.php',
@@ -2319,6 +2321,7 @@
     'OC\\Security\\Crypto' => $baseDir . '/lib/private/Security/Crypto.php',
     'OC\\Security\\FeaturePolicy\\FeaturePolicy' => $baseDir . '/lib/private/Security/FeaturePolicy/FeaturePolicy.php',
     'OC\\Security\\FeaturePolicy\\FeaturePolicyManager' => $baseDir . '/lib/private/Security/FeaturePolicy/FeaturePolicyManager.php',
+    'OC\\Security\\Guard\\RequestGuardManager' => $baseDir . '/lib/private/Security/Guard/RequestGuardManager.php',
     'OC\\Security\\Hasher' => $baseDir . '/lib/private/Security/Hasher.php',
     'OC\\Security\\IdentityProof\\Key' => $baseDir . '/lib/private/Security/IdentityProof/Key.php',
     'OC\\Security\\IdentityProof\\Manager' => $baseDir . '/lib/private/Security/IdentityProof/Manager.php',

@@ -926,6 +926,8 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OCP\\Security\\Events\\GenerateSecurePasswordEvent' => __DIR__ . '/../../..' . '/lib/public/Security/Events/GenerateSecurePasswordEvent.php',
         'OCP\\Security\\Events\\ValidatePasswordPolicyEvent' => __DIR__ . '/../../..' . '/lib/public/Security/Events/ValidatePasswordPolicyEvent.php',
         'OCP\\Security\\FeaturePolicy\\AddFeaturePolicyEvent' => __DIR__ . '/../../..' . '/lib/public/Security/FeaturePolicy/AddFeaturePolicyEvent.php',
+        'OCP\\Security\\Guard\\GuardDecision' => __DIR__ . '/../../..' . '/lib/public/Security/Guard/GuardDecision.php',
+        'OCP\\Security\\Guard\\IRequestGuard' => __DIR__ . '/../../..' . '/lib/public/Security/Guard/IRequestGuard.php',
         'OCP\\Security\\IContentSecurityPolicyManager' => __DIR__ . '/../../..' . '/lib/public/Security/IContentSecurityPolicyManager.php',
         'OCP\\Security\\ICredentialsManager' => __DIR__ . '/../../..' . '/lib/public/Security/ICredentialsManager.php',
         'OCP\\Security\\ICrypto' => __DIR__ . '/../../..' . '/lib/public/Security/ICrypto.php',
@@ -2360,6 +2362,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OC\\Security\\Crypto' => __DIR__ . '/../../..' . '/lib/private/Security/Crypto.php',
         'OC\\Security\\FeaturePolicy\\FeaturePolicy' => __DIR__ . '/../../..' . '/lib/private/Security/FeaturePolicy/FeaturePolicy.php',
         'OC\\Security\\FeaturePolicy\\FeaturePolicyManager' => __DIR__ . '/../../..' . '/lib/private/Security/FeaturePolicy/FeaturePolicyManager.php',
+        'OC\\Security\\Guard\\RequestGuardManager' => __DIR__ . '/../../..' . '/lib/private/Security/Guard/RequestGuardManager.php',
         'OC\\Security\\Hasher' => __DIR__ . '/../../..' . '/lib/private/Security/Hasher.php',
         'OC\\Security\\IdentityProof\\Key' => __DIR__ . '/../../..' . '/lib/private/Security/IdentityProof/Key.php',
         'OC\\Security\\IdentityProof\\Manager' => __DIR__ . '/../../..' . '/lib/private/Security/IdentityProof/Manager.php',

@@ -36,6 +36,7 @@
 use OCP\Notification\INotifier;
 use OCP\Profile\ILinkAction;
 use OCP\Search\IProvider;
+use OCP\Security\Guard\IRequestGuard;
 use OCP\Server;
 use OCP\Settings\IDeclarativeSettingsForm;
 use OCP\SetupCheck\ISetupCheck;
@@ -151,6 +152,9 @@ class RegistrationContext {
 	/** @var ServiceRegistration<ISystemReportSection>[] */
 	private array $systemReportSections = [];
 
+	/** @var ServiceRegistration<IRequestGuard>[] */
+	private array $requestGuards = [];
+
 	/** @var PreviewProviderRegistration[] */
 	private array $previewProviders = [];
 
@@ -471,6 +475,14 @@ public function registerSystemReportSection(string $sectionClass): void {
 				);
 			}
 
+			#[\Override]
+			public function registerRequestGuard(string $guardClass): void {
+				$this->context->registerRequestGuard(
+					$this->appId,
+					$guardClass
+				);
+			}
+
 			#[\Override]
 			public function registerDeclarativeSettings(string $declarativeSettingsClass): void {
 				$this->context->registerDeclarativeSettings(
@@ -712,6 +724,13 @@ public function registerSystemReportSection(string $appId, string $sectionClass)
 		$this->systemReportSections[] = new ServiceRegistration($appId, $sectionClass);
 	}
 
+	/**
+	 * @psalm-param class-string<IRequestGuard> $guardClass
+	 */
+	public function registerRequestGuard(string $appId, string $guardClass): void {
+		$this->requestGuards[] = new ServiceRegistration($appId, $guardClass);
+	}
+
 	/**
 	 * @psalm-param class-string<IDeclarativeSettingsForm> $declarativeSettingsClass
 	 */
@@ -1110,6 +1129,13 @@ public function getSystemReportSections(): array {
 		return $this->systemReportSections;
 	}
 
+	/**
+	 * @return ServiceRegistration<IRequestGuard>[]
+	 */
+	public function getRequestGuards(): array {
+		return $this->requestGuards;
+	}
+
 	/**
 	 * @return ServiceRegistration<ITeamResourceProvider>[]
 	 */

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OC\Security\Guard;
+
+use OC\AppFramework\Bootstrap\Coordinator;
+use OCP\IRequest;
+use OCP\Security\Guard\GuardDecision;
+use OCP\Security\Guard\IRequestGuard;
+use Psr\Container\ContainerInterface;
+use Psr\Log\LoggerInterface;
+
+final readonly class RequestGuardManager {
+	public function __construct(
+		private Coordinator $coordinator,
+		private ContainerInterface $container,
+		private LoggerInterface $logger,
+	) {
+	}
+
+	/**
+	 * Asks the registered guards in order and returns the first refusal.
+	 */
+	public function check(IRequest $request): ?GuardDecision {
+		$registrations = $this->coordinator->getRegistrationContext()?->getRequestGuards() ?? [];
+		foreach ($registrations as $registration) {
+			$class = $registration->getService();
+			try {
+				/** @var IRequestGuard $guard */
+				$guard = $this->container->get($class);
+				$decision = $guard->check($request);
+			} catch (\Throwable $t) {
+				$this->logger->error('Exception in request guard ' . $class . ': ' . $t->getMessage(), [
+					'app' => $registration->getAppId(),
+					'exception' => $t,
+				]);
+				continue;
+			}
+
+			if ($decision !== null) {
+				return $decision;
+			}
+		}
+
+		return null;
+	}
+}
@@ -413,6 +413,15 @@ public function registerSetupCheck(string $setupCheckClass): void;
 	 */
 	public function registerSystemReportSection(string $sectionClass): void;
 
+	/**
+	 * Register an implementation of \OCP\Security\Guard\IRequestGuard that
+	 * may refuse web requests before the session is started
+	 *
+	 * @param class-string<\OCP\Security\Guard\IRequestGuard> $guardClass
+	 * @since 36.0.0
+	 */
+	public function registerRequestGuard(string $guardClass): void;
+
 	/**
 	 * Register an implementation of \OCP\Settings\IDeclarativeSettings that
 	 * will handle the implementation of declarative settings

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Security\Guard;
+
+/**
+ * A request guard's decision to refuse a request.
+ *
+ * @since 36.0.0
+ */
+final class GuardDecision {
+	private function __construct(
+		private readonly int $retryAfter,
+		private readonly string $reference,
+	) {
+	}
+
+	/**
+	 * @param int $retryAfter seconds after which the client may try again
+	 * @param string $reference short id shown to the client, so an administrator can look the block up
+	 * @since 36.0.0
+	 */
+	public static function deny(int $retryAfter, string $reference): self {
+		return new self(max(0, $retryAfter), $reference);
+	}
+
+	/**
+	 * @since 36.0.0
+	 */
+	public function getRetryAfter(): int {
+		return $this->retryAfter;
+	}
+
+	/**
+	 * @since 36.0.0
+	 */
+	public function getReference(): string {
+		return $this->reference;
+	}
+}
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Security\Guard;
+
+use OCP\IRequest;
+
+/**
+ * Decides early whether a web request may proceed, e.g. to refuse requests
+ * from a banned address on every entry point.
+ *
+ * Guards run for every web request after the apps were registered and before
+ * the session is started, so they must be cheap and must not use the session.
+ * A guard that throws is logged and ignored.
+ *
+ * @since 36.0.0
+ */
+interface IRequestGuard {
+	/**
+	 * @return GuardDecision|null a decision to refuse the request, or null to let it proceed
+	 * @since 36.0.0
+	 */
+	public function check(IRequest $request): ?GuardDecision;
+}