feat(lexicon): validate value on set

Signed-off-by: Maxence Lange <[email protected]>

Author: ArtificialOwl

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,17 @@ private function setTypedValue(
 		int $type,
 	): bool {
 		$this->assertParams($app, $key);
-		if (!$this->matchAndApplyLexiconDefinition($app, $key, $lazy, $type)) {
+		$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?->onSetConfirm() !== null && !$lexiconEntry->onSetConfirm()($value)) {
+			return false;
+		}
+
 		$sensitive = $this->isTyped(self::VALUE_SENSITIVE, $type);
 		$inserted = $refreshCache = false;
 

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,18 @@ private function setTypedValue(
 		}
 
 		$this->assertParams($userId, $app, $key);
-		if (!$this->matchAndApplyLexiconDefinition($userId, $app, $key, $lazy, $type, $flags)) {
+		$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?->onSetConfirm() !== null && !$lexiconEntry->onSetConfirm()($value)) {
+			return false;
+		}
+
 		$inserted = $refreshCache = false;
 		$origValue = $value;
 		$sensitive = $this->isFlagged(self::FLAG_SENSITIVE, $flags);
@@ -1937,6 +1945,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 +1962,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 +1985,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

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 {
+}

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,22 @@ 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 Callable|null
+	 * @throws UnacceptableValueException
+	 * @since 33.0.0
+	 */
+	public function onSetConfirmation(): ?Callable {
+		return $this->onSetConfirm;
+	}
+
 	/**
 	 * returns if config key is set as lazy
 	 *