feat(lexicon): validate value on set

ArtificialOwl · ArtificialOwl · commit a9488d7d6bdf · 2026-01-26T18:58:05.000-01:00
Signed-off-by: Maxence Lange &lt;maxence@artificial-owl.com&gt;
diff --git a/lib/composer/composer/autoload_classmap.php b/lib/composer/composer/autoload_classmap.php
@@ -286,6 +286,7 @@
     'OCP\\Config\\BeforePreferenceSetEvent' => $baseDir . '/lib/public/Config/BeforePreferenceSetEvent.php',
     'OCP\\Config\\Exceptions\\IncorrectTypeException' => $baseDir . '/lib/public/Config/Exceptions/IncorrectTypeException.php',
     'OCP\\Config\\Exceptions\\TypeConflictException' => $baseDir . '/lib/public/Config/Exceptions/TypeConflictException.php',
+    'OCP\\Config\\Exceptions\\UnacceptableValueException' => $baseDir . '/lib/public/Config/Exceptions/UnacceptableValueException.php',
     'OCP\\Config\\Exceptions\\UnknownKeyException' => $baseDir . '/lib/public/Config/Exceptions/UnknownKeyException.php',
     'OCP\\Config\\IUserConfig' => $baseDir . '/lib/public/Config/IUserConfig.php',
     'OCP\\Config\\Lexicon\\Entry' => $baseDir . '/lib/public/Config/Lexicon/Entry.php',
diff --git a/lib/composer/composer/autoload_static.php b/lib/composer/composer/autoload_static.php
@@ -327,6 +327,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OCP\\Config\\BeforePreferenceSetEvent' => __DIR__ . '/../../..' . '/lib/public/Config/BeforePreferenceSetEvent.php',
         'OCP\\Config\\Exceptions\\IncorrectTypeException' => __DIR__ . '/../../..' . '/lib/public/Config/Exceptions/IncorrectTypeException.php',
         'OCP\\Config\\Exceptions\\TypeConflictException' => __DIR__ . '/../../..' . '/lib/public/Config/Exceptions/TypeConflictException.php',
+        'OCP\\Config\\Exceptions\\UnacceptableValueException' => __DIR__ . '/../../..' . '/lib/public/Config/Exceptions/UnacceptableValueException.php',
         'OCP\\Config\\Exceptions\\UnknownKeyException' => __DIR__ . '/../../..' . '/lib/public/Config/Exceptions/UnknownKeyException.php',
         'OCP\\Config\\IUserConfig' => __DIR__ . '/../../..' . '/lib/public/Config/IUserConfig.php',
         'OCP\\Config\\Lexicon\\Entry' => __DIR__ . '/../../..' . '/lib/public/Config/Lexicon/Entry.php',
diff --git a/lib/private/AppConfig.php b/lib/private/AppConfig.php
@@ -15,6 +15,7 @@
 use OC\Config\ConfigManager;
 use OC\Config\PresetManager;
 use OC\Memcache\Factory as CacheFactory;
+use OCP\Config\Exceptions\UnacceptableValueException;
 use OCP\Config\Lexicon\Entry;
 use OCP\Config\Lexicon\Strictness;
 use OCP\Config\ValueType;
@@ -784,6 +785,7 @@ public function setValueArray(
 	 * @param int $type value type {@see VALUE_STRING} {@see VALUE_INT} {@see VALUE_FLOAT} {@see VALUE_BOOL} {@see VALUE_ARRAY}
 	 *
 	 * @return bool TRUE if value was updated in database
+	 * @throws UnacceptableValueException if lexicon does not validate value
 	 * @throws AppConfigTypeConflictException if type from database is not VALUE_MIXED and different from the requested one
 	 * @see IAppConfig for explanation about lazy loading
 	 */
@@ -795,11 +797,18 @@ private function setTypedValue(
 		int $type,
 	): bool {
 		$this->assertParams($app, $key);
-		if (!$this->matchAndApplyLexiconDefinition($app, $key, $lazy, $type)) {
+		/** @var ?Entry $lexiconEntry */
+		$lexiconEntry = null;
+		if (!$this->matchAndApplyLexiconDefinition($app, $key, $lazy, $type, lexiconEntry: $lexiconEntry)) {
 			return false; // returns false as database is not updated
 		}
 		$this->loadConfig(null, $lazy ?? true);
 
+		// lexicon entry might have requested a check on the value
+		if ($lexiconEntry?->onSetConfirmation() !== null && !$lexiconEntry->onSetConfirmation()($value)) {
+			return false;
+		}
+
 		$sensitive = $this->isTyped(self::VALUE_SENSITIVE, $type);
 		$inserted = $refreshCache = false;
 
diff --git a/lib/private/Config/UserConfig.php b/lib/private/Config/UserConfig.php
@@ -14,6 +14,7 @@
 use OC\AppFramework\Bootstrap\Coordinator;
 use OCP\Config\Exceptions\IncorrectTypeException;
 use OCP\Config\Exceptions\TypeConflictException;
+use OCP\Config\Exceptions\UnacceptableValueException;
 use OCP\Config\Exceptions\UnknownKeyException;
 use OCP\Config\IUserConfig;
 use OCP\Config\Lexicon\Entry;
@@ -1082,6 +1083,7 @@ public function setValueArray(
 	 * @param ValueType $type value type
 	 *
 	 * @return bool TRUE if value was updated in database
+	 * @throws UnacceptableValueException if lexicon does not validate value
 	 * @throws TypeConflictException if type from database is not VALUE_MIXED and different from the requested one
 	 * @see IUserConfig for explanation about lazy loading
 	 */
@@ -1100,12 +1102,19 @@ private function setTypedValue(
 		}
 
 		$this->assertParams($userId, $app, $key);
-		if (!$this->matchAndApplyLexiconDefinition($userId, $app, $key, $lazy, $type, $flags)) {
+		/** @var ?Entry $lexiconEntry */
+		$lexiconEntry = null;
+		if (!$this->matchAndApplyLexiconDefinition($userId, $app, $key, $lazy, $type, $flags, lexiconEntry: $lexiconEntry)) {
 			// returns false as database is not updated
 			return false;
 		}
 		$this->loadConfig($userId, $lazy);
 
+		// lexicon entry might have requested a check on the value
+		if ($lexiconEntry?->onSetConfirmation() !== null && !$lexiconEntry->onSetConfirmation()($value)) {
+			return false;
+		}
+
 		$inserted = $refreshCache = false;
 		$origValue = $value;
 		$sensitive = $this->isFlagged(self::FLAG_SENSITIVE, $flags);
@@ -1937,6 +1946,7 @@ private function matchAndApplyLexiconDefinition(
 		ValueType &$type = ValueType::MIXED,
 		int &$flags = 0,
 		?string &$default = null,
+		?Entry &$lexiconEntry = null,
 	): bool {
 		$configDetails = $this->getConfigDetailsFromLexicon($app);
 		if (array_key_exists($key, $configDetails['aliases']) && !$this->ignoreLexiconAliases) {
@@ -1953,18 +1963,18 @@ private function matchAndApplyLexiconDefinition(
 			return true;
 		}
 
-		/** @var Entry $configValue */
-		$configValue = $configDetails['entries'][$key];
+		/** @var Entry $lexiconEntry */
+		$lexiconEntry = $configDetails['entries'][$key];
 		if ($type === ValueType::MIXED) {
 			// we overwrite if value was requested as mixed
-			$type = $configValue->getValueType();
-		} elseif ($configValue->getValueType() !== $type) {
+			$type = $lexiconEntry->getValueType();
+		} elseif ($lexiconEntry->getValueType() !== $type) {
 			throw new TypeConflictException('The user config key ' . $app . '/' . $key . ' is typed incorrectly in relation to the config lexicon');
 		}
 
-		$lazy = $configValue->isLazy();
-		$flags = $configValue->getFlags();
-		if ($configValue->isDeprecated()) {
+		$lazy = $lexiconEntry->isLazy();
+		$flags = $lexiconEntry->getFlags();
+		if ($lexiconEntry->isDeprecated()) {
 			$this->logger->notice('User config key ' . $app . '/' . $key . ' is set as deprecated.');
 		}
 
@@ -1976,7 +1986,7 @@ private function matchAndApplyLexiconDefinition(
 
 		// only look for default if needed, default from Lexicon got priority if not overwritten by admin
 		if ($default !== null) {
-			$default = $this->getSystemDefault($app, $configValue) ?? $configValue->getDefault($this->presetManager->getLexiconPreset()) ?? $default;
+			$default = $this->getSystemDefault($app, $lexiconEntry) ?? $lexiconEntry->getDefault($this->presetManager->getLexiconPreset()) ?? $default;
 		}
 
 		// returning false will make get() returning $default and set() not changing value in database
diff --git a/lib/public/Config/Exceptions/UnacceptableValueException.php b/lib/public/Config/Exceptions/UnacceptableValueException.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Config\Exceptions;
+
+use Exception;
+use OCP\AppFramework\Attribute\Throwable;
+
+#[Throwable(since: '33.0.0')]
+class UnacceptableValueException extends Exception {
+}
diff --git a/lib/public/Config/Lexicon/Entry.php b/lib/public/Config/Lexicon/Entry.php
@@ -10,6 +10,7 @@
 
 use Closure;
 use OCP\AppFramework\Attribute\Consumable;
+use OCP\Config\Exceptions\UnacceptableValueException;
 use OCP\Config\ValueType;
 
 /**
@@ -35,8 +36,10 @@ class Entry {
 	 * @param string|null $rename source in case of a rename of a config key.
 	 * @param int $options additional bitflag options {@see self::RENAME_INVERT_BOOLEAN}
 	 * @param string $note additional note and warning related to the use of the config key.
+	 * @param Closure|null $onSetConfirm callback to be called when a config value is set.
 	 *
 	 * @since 32.0.0
+	 * @since 33.0.0 added $onSetConfirm
 	 * @psalm-suppress PossiblyInvalidCast
 	 * @psalm-suppress RiskyCast
 	 */
@@ -51,6 +54,7 @@ public function __construct(
 		private readonly ?string $rename = null,
 		private readonly int $options = 0,
 		private readonly string $note = '',
+		private readonly ?Closure $onSetConfirm = null,
 	) {
 		// key can only contain alphanumeric chars and underscore "_"
 		if (preg_match('/[^[:alnum:]_]/', $key)) {
@@ -195,6 +199,21 @@ public function getNote(): string {
 		return $this->note;
 	}
 
+	/**
+	 * Returns an optional callback to be called when a config value is set.
+	 * If not null, the callback will be called before the config value is set.
+	 * Callable must accept a typed (as defined using {@see ValueType}) parameter
+	 * containing the new value.
+	 * Callback must return a boolean indicating if the set operation should be allowed.
+	 * Callback should throw {@see UnacceptableValueException} to indicate a specific error message.
+	 *
+	 * @return Closure|null
+	 * @since 33.0.0
+	 */
+	public function onSetConfirmation(): ?Closure {
+		return $this->onSetConfirm;
+	}
+
 	/**
 	 * returns if config key is set as lazy
 	 *
