Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

fix(settings): #5602 round-3 follow-ups — redacted-control baseline, Test Notification, stored-URL error (#6336)

LearningCircuit63bfaa4514d0
diff --git a/changelog.d/6336.security.md b/changelog.d/6336.security.md
new file mode 100644
index 0000000000..c117e322a4
--- /dev/null
+++ b/changelog.d/6336.security.md
@@ -0,0 +1,18 @@
+Follow-ups to the #5602 notification `service_url` redaction. Saving a
+sensitive setting now leaves its control in the state a fresh render would
+produce — blank, marked as redacted, and advertising the "press Enter while
+empty to clear" gesture — so a URL configured during that same session can
+still be cleared, and the save confirmation masks the value whether the save
+configured the secret or cleared it. An empty value reaches the server for
+such a control only through that explicit Enter-on-empty gesture, including
+while an earlier save for the same setting is still in flight — the window
+in which the control is blank because that save blanked it — and pressing
+Enter no longer queues a duplicate save of the value already on its way, so
+a stray blur in that window can no longer clear the stored URL. Test
+Notification works again for a configured URL whose field renders blank:
+the button enables and the stored URL is what gets tested. Testing the
+stored URL no longer echoes validator detail that can name the stored host;
+those failures return a generic message and the detail goes to the server
+log, while host-free operator instructions (outbound notifications
+disabled, the target-count cap, an unparsable URL list) are still returned
+inline.
diff --git a/src/local_deep_research/web/routers/settings.py b/src/local_deep_research/web/routers/settings.py
index e61004ee84..8b7fd2e060 100644
--- a/src/local_deep_research/web/routers/settings.py
+++ b/src/local_deep_research/web/routers/settings.py
@@ -1342,8 +1342,10 @@ def _is_secret_empty_noop(
The ``ui_element == "password"`` narrowing matters:
``notifications.service_url`` is a sensitive setting on a ``textarea``
- whose control renders its real value, so an empty write there is a
- deliberate "clear it" gesture and must reach the database (#5960).
+ that renders blank once redacted, but its blankness is advertised (the
+ placeholder names the explicit clear gesture) rather than a stand-in
+ for an unknown value, so an empty write there is a deliberate "clear
+ it" gesture and must reach the database (#5960).
A dict/list value goes through the container arm, delegated to
``_resolve_container_secret_write`` / ``_merge_redacted_container``:
@@ -4383,6 +4385,50 @@ def _caller_supplied_notification_url(request: Request) -> bool:
return submitted != DataSanitizer.REDACTION_TEXT
+# Error strings ``NotificationService.test_service`` can return that name
+# no destination: operator instructions and shape refusals whose text is
+# fixed, or parameterised only with counts. Kept as prefixes because two of
+# them continue with a count or a second sentence.
+_HOST_FREE_NOTIFICATION_TEST_ERRORS = (
+ # The outbound master switch is off; only an operator can change it.
+ "Outbound notifications are disabled.",
+ # The input does not partition into unambiguous entries.
+ "Notification service URL could not be parsed unambiguously",
+ # More entries than MAX_NOTIFICATION_TARGETS -- a count, not a host.
+ "Too many notification targets",
+ # Apprise declined to register the parsed entries.
+ "Failed to add service URL",
+ # The validator rejected the URL without a reason of its own.
+ "Invalid notification service URL.",
+ # Validation passed; delivery did not.
+ "Failed to send test notification",
+)
+
+
+def _is_host_free_notification_error(error_text: object) -> bool:
+ """True when a ``test_service`` error is safe to echo for a URL the
+ caller never named.
+
+ The stored-URL fallback tests a destination the caller does not have to
+ name and, once the setting is redacted, cannot read back. An error that
+ names it -- the validator's ``Blocked private/internal IP address:
+ <host>`` and ``Blocked cloud-metadata / link-local IP address: <host>``
+ -- would disclose the stored hostname/IP through the very endpoint that
+ exists to keep the URL hidden.
+
+ Matching an ALLOWLIST rather than denylisting those two prefixes keeps
+ the failure closed: an error string added to ``test_service`` later is
+ suppressed (the user loses detail, the log keeps it) instead of leaking
+ by default. Static operator instructions carry no host and must still
+ reach the UI -- "set LDR_NOTIFICATIONS_ALLOW_OUTBOUND=true" is useless
+ in a log the user cannot read, and ``docs/NOTIFICATIONS.md`` promises
+ it inline.
+ """
+ return isinstance(error_text, str) and error_text.startswith(
+ _HOST_FREE_NOTIFICATION_TEST_ERRORS
+ )
+
+
# Own bucket, not the shared "settings" one: this caps the stored-URL
# fallback without spending the quota a user needs for saving settings.
# Keyed per authenticated user (the branch convention for settings routes)
@@ -4431,6 +4477,9 @@ async def api_test_notification_url(
rather than raising).
"""
service_url = data.get("service_url")
+ # Captured before the stored-URL fallback replaces ``service_url``:
+ # the response shaping below branches on who chose the destination.
+ caller_supplied = _caller_supplied_notification_url(request)
if _is_blank_service_url(service_url) or (
service_url == DataSanitizer.REDACTION_TEXT
):
@@ -4478,11 +4527,43 @@ async def api_test_notification_url(
notification_service.test_service, service_url
)
- # Only return expected fields to prevent information leakage
+ # Only return expected fields to prevent information leakage. On
+ # the caller-supplied path the validator detail is safe to echo —
+ # the caller just typed that URL. The stored-URL fallback is
+ # different: an error that names the destination would reveal the
+ # stored hostname/IP, content the redacted API otherwise never
+ # returns. Those go to the server log and come back generic; the
+ # host-free operator instructions still come back inline, since
+ # they say what the user has to do next.
+ if caller_supplied:
+ return {
+ "success": result.get("success", False),
+ "message": result.get("message", ""),
+ "error": result.get("error", ""),
+ }
+ if result.get("success"):
+ return {
+ "success": result.get("success", False),
+ "message": result.get("message", ""),
+ "error": "",
+ }
+ error_text = result.get("error", "") or ""
+ logger.warning(
+ "Stored-URL notification test failed for user={!r}: {}",
+ username,
+ error_text or result.get("message", ""),
+ )
return {
- "success": result.get("success", False),
- "message": result.get("message", ""),
- "error": result.get("error", ""),
+ "success": False,
+ "message": "",
+ "error": (
+ error_text
+ if _is_host_free_notification_error(error_text)
+ else (
+ "Failed to test notification service. Check server "
+ "logs for details."
+ )
+ ),
}
except Exception:
diff --git a/src/local_deep_research/web/static/js/components/settings.js b/src/local_deep_research/web/static/js/components/settings.js
index df2c686f21..89ba19815f 100644
--- a/src/local_deep_research/web/static/js/components/settings.js
+++ b/src/local_deep_research/web/static/js/components/settings.js
@@ -27,9 +27,17 @@
// Keys whose value the settings API redacted on the current load. Used
// to mask values in save confirmations for sensitive settings that are
- // not password inputs (e.g. the notifications.service_url textarea).
+ // not password inputs (e.g. the notifications.service_url textarea),
+ // and, with the matching data-redacted attribute, to decide whether a
+ // blank control is a withheld secret (see isRedactedControl).
const redactedSettingKeys = new Set();
+ // The one setting with a dedicated test button; its control is looked
+ // up by several ids because the JS render and the Jinja macro name it
+ // differently.
+ const NOTIFICATION_SERVICE_URL_KEY = 'notifications.service_url';
+ let notificationTestInProgress = false;
+
/**
* True when the settings API redacted this value instead of returning it.
* @param {*} value - The value as delivered by /settings/api
@@ -51,6 +59,139 @@
return setting.ui_element === 'password' || isRedactedValue(setting.value);
}
+ // Placeholders the render templates put on a control that hides its
+ // stored value. Constants because syncRedactedControlState reapplies
+ // them after a save without re-rendering: two copies of the wording
+ // would let the post-save control and a re-rendered one disagree.
+ const SECRET_CLEARABLE_PLACEHOLDER =
+ 'Saved — type to replace, or press Enter while empty to clear';
+ const PASSWORD_CONFIGURED_PLACEHOLDER = '(saved — type to change)';
+ const PASSWORD_UNSET_PLACEHOLDER = '(not configured)';
+
+ /**
+ * The placeholder a control gets from its (possibly redacted) value.
+ * Used by the render templates and by the post-save re-sync, so both
+ * produce the same control for the same setting.
+ * @param {Object} setting - The setting object
+ * @returns {string}
+ */
+ function secrecyPlaceholder(setting) {
+ if (setting.ui_element === 'password') {
+ // The sentinel is a positive "is configured" signal: we know
+ // the value is set, we just don't know its plaintext.
+ const isConfigured =
+ isRedactedValue(setting.value) ||
+ (setting.value !== null && setting.value !== '');
+ return isConfigured
+ ? PASSWORD_CONFIGURED_PLACEHOLDER
+ : PASSWORD_UNSET_PLACEHOLDER;
+ }
+ return isRedactedValue(setting.value) ? SECRET_CLEARABLE_PLACEHOLDER : '';
+ }
+
+ /**
+ * True when this control is the blank-rendered face of a redacted
+ * secret, i.e. the field is empty because the value is withheld rather
+ * than because nothing is stored.
+ *
+ * Two pieces of state say so, and both are required: the module's
+ * redactedSettingKeys set (rebuilt by loadSettings, kept current by the
+ * post-save re-sync) and the control's own data-redacted attribute
+ * (written by the render templates and by the same re-sync). They are
+ * deliberately kept in agreement — see syncRedactedControlState — so
+ * requiring both means neither a stale attribute on a node that
+ * outlived its data nor a set entry for a control the render never
+ * marked (a password input) can drive the clear gesture or the Test
+ * Notification button on its own.
+ * @param {string} key - The setting key
+ * @param {HTMLElement|null} input - The control, if it exists
+ * @returns {boolean}
+ */
+ function isRedactedControl(key, input) {
+ return Boolean(input) &&
+ input.dataset.redacted === 'true' &&
+ redactedSettingKeys.has(key);
+ }
+
+ /**
+ * Re-apply a saved setting's redaction state to its live control.
+ *
+ * A save response carries a render's worth of new truth that never
+ * reaches the DOM: nothing re-renders after a save, so the node the
+ * user is looking at keeps whatever the last render gave it. Three
+ * pieces describe a secret control — the dirty-check baseline in
+ * originalSettings, membership of redactedSettingKeys, and the
+ * control's data-redacted attribute — and the clear gesture and the
+ * Test Notification button read combinations of them, so any two
+ * drifting apart produces a control that cannot be cleared or a button
+ * that is enabled for a setting that is no longer configured.
+ * Applying exactly what a render would have produced (blank body, the
+ * matching placeholder, the attribute) keeps all three in step until
+ * the next render, which derives from the allSettings entry updated by
+ * the same write-back.
+ * @param {string} key - The setting key
+ * @param {Object} setting - The setting as echoed by the save response
+ * @param {*} submittedValue - The value this save sent for the key
+ */
+ function syncRedactedControlState(key, setting, submittedValue) {
+ if (isRedactedValue(setting.value)) {
+ redactedSettingKeys.add(key);
+ } else {
+ redactedSettingKeys.delete(key);
+ }
+
+ const blankForSecrecy = rendersBlankForSecrecy(setting);
+ Array.from(document.getElementsByName(key)).forEach(control => {
+ if (control.tagName !== 'INPUT' && control.tagName !== 'TEXTAREA') return;
+ const wasRedacted = control.dataset.redacted === 'true';
+ // Only the controls a render marks get the attribute: a
+ // password input renders blank without it (its emptiness is
+ // unconditional, so an empty write there is a no-op the route
+ // handlers swallow rather than a clear gesture).
+ const markable = control.type !== 'password';
+ if (isRedactedValue(setting.value) && markable) {
+ control.dataset.redacted = 'true';
+ } else {
+ delete control.dataset.redacted;
+ }
+ // Only secrecy-blank controls have a placeholder this owns;
+ // an ordinary control (a dropdown's "Select a provider", say)
+ // keeps whatever its own render gave it.
+ if (blankForSecrecy || wasRedacted) {
+ control.placeholder = secrecyPlaceholder(setting);
+ }
+ // Blank it for the same reason the render does — and only if
+ // it still holds what this save submitted, so typing that
+ // started while the request was in flight is never discarded
+ // (that control is then legitimately dirty against the blank
+ // baseline and saves on its own).
+ if (blankForSecrecy && control.value === String(submittedValue)) {
+ control.value = '';
+ }
+ });
+ }
+
+ /**
+ * Enable/disable the Test Notification button from live DOM lookups.
+ *
+ * The notifications.service_url control is re-created whenever the
+ * settings list re-renders (the render replaces settingsContent's
+ * innerHTML wholesale), so a closure captured in setupRefreshButtons
+ * holds a detached node. Resolving both nodes on every call keeps the
+ * rule stable: the button is usable when the field has a value OR when
+ * it renders blank because the saved value is redacted — the stored
+ * URL is what gets tested then.
+ */
+ function updateTestNotificationButtonState() {
+ const btn = document.getElementById('test-notification-button');
+ const input = document.getElementById('notifications-service-url') ||
+ document.querySelector('input[name="notifications.service_url"], textarea[name="notifications.service_url"]');
+ if (!btn) return;
+ const hasValue = Boolean(input) && input.value.trim() !== '';
+ btn.disabled = notificationTestInProgress ||
+ !(hasValue || isRedactedControl(NOTIFICATION_SERVICE_URL_KEY, input));
+ }
+
// DOM elements and global variables
let settingsForm;
let settingsContent;
@@ -212,15 +353,11 @@
const serviceUrlInput = document.getElementById('notifications-service-url') ||
document.querySelector('input[name="notifications.service_url"], textarea[name="notifications.service_url"]');
if (serviceUrlInput) {
- const updateButtonState = () => {
- const hasValue = serviceUrlInput.value.trim() !== '';
- testNotificationBtn.disabled = !hasValue;
- };
-
- serviceUrlInput.addEventListener('input', updateButtonState);
- serviceUrlInput.addEventListener('change', updateButtonState);
- // Initial check
- updateButtonState();
+ serviceUrlInput.addEventListener('input', updateTestNotificationButtonState);
+ serviceUrlInput.addEventListener('change', updateTestNotificationButtonState);
+ // Initial check — the module helper re-resolves both nodes,
+ // so it also covers the redacted-blank (data-redacted) case.
+ updateTestNotificationButtonState();
}
}
@@ -540,14 +677,37 @@
// (notifications.service_url) would stop being clearable from the
// UI, which the route handlers deliberately allow.
const isExplicitClear =
- input.dataset.redacted === 'true' &&
+ isRedactedControl(key, input) &&
eventType === 'keydown' &&
e.key === 'Enter' &&
!e.shiftKey &&
value === '';
+ // The value this key already has on its way to the server. Saves
+ // for one key are serialized, so the latest queued intent is what
+ // the stored value ends up being: submitting that same value again
+ // is a pure duplicate. The Enter path used to queue exactly that —
+ // its programmatic input.blur() below re-enters this function with
+ // the value just submitted — and the duplicate kept the key
+ // "pending" across the first response's write-back, which is the
+ // window in which a stray blur could clear a secret.
+ const pendingSave = pendingSettingsSaveByKey.get(key);
+ const matchesPendingSave = Boolean(pendingSave) &&
+ Object.hasOwn(pendingSave.values, key) &&
+ areValuesEqual(value, pendingSave.values[key]);
+ // An empty redacted control carries no intent: it renders blank
+ // whether or not a secret is stored, and the post-save re-sync
+ // blanks it again. So nothing may turn it into an empty submit
+ // except the explicit clear gesture above — neither the
+ // dirty-check (blank value against blank baseline) nor the
+ // pending-save disjunct, which stays true for as long as any save
+ // for the key is queued or in flight.
+ const isBlankRedactedControl = isRedactedControl(key, input) && value === '';
// A reversal still needs saving if an earlier value can commit later.
- const hasChanged = pendingSettingsSaveByKey.has(key) ||
- !areValuesEqual(value, originalValue) || isExplicitClear;
+ const hasChanged = !matchesPendingSave && (
+ isBlankRedactedControl
+ ? isExplicitClear
+ : Boolean(pendingSave) || !areValuesEqual(value, originalValue)
+ );
if (hasChanged) {
// Mark parent item as modified
@@ -2386,9 +2546,7 @@
// gesture: the control renders blank, so deleting its
// contents is not a visible change and the dirty-check
// cannot see it (handleInputChange honours this).
- const textareaPlaceholder = isRedacted
- ? 'Saved — type to replace, or press Enter while empty to clear'
- : '';
+ const textareaPlaceholder = secrecyPlaceholder(setting);
inputElement = `
<textarea id="${settingId}" name="${setting.key}"
class="ldr-settings-textarea"
@@ -2605,15 +2763,10 @@
// would persist "[REDACTED]" as the API key.
// 3. The placeholder telegraphs configuration state
// without leaking the value or its length.
- // The "is configured" check accepts the redacted
- // sentinel as a positive signal — we know the value
- // is set, we just don't know its plaintext.
- const isConfigured =
- isRedactedValue(setting.value) ||
- (setting.value !== null && setting.value !== '');
- const placeholder = isConfigured
- ? '(saved — type to change)'
- : '(not configured)';
+ // secrecyPlaceholder's "is configured" check accepts
+ // the redacted sentinel as a positive signal — we know
+ // the value is set, we just don't know its plaintext.
+ const placeholder = secrecyPlaceholder(setting);
inputElement = `
<input type="password"
id="${settingId}" name="${setting.key}"
@@ -2635,7 +2788,7 @@
id="${settingId}" name="${setting.key}"
class="ldr-settings-input ldr-form-control"
value=""
- placeholder="${escapeHtml('Saved — type to replace, or press Enter while empty to clear')}"
+ placeholder="${escapeHtml(secrecyPlaceholder(setting))}"
data-redacted="true"
${!setting.editable ? 'disabled' : ''}
>
@@ -3058,6 +3211,23 @@
originalValues[key] = Object.hasOwn(originalSettings, key) ? originalSettings[key] : null;
});
+ // Whether each key is a secret as things stand BEFORE the save.
+ // The response write-back moves redactedSettingKeys to the NEW
+ // state, so reading that set alone describes only half of the
+ // transition: clearing a secret drops its key, and the save
+ // confirmation would then print values for a setting that was
+ // secret a moment ago. Masking on "secret before OR after" covers
+ // both directions — configuring one and clearing one.
+ const sensitiveBeforeSave = new Set(
+ savingKeys.filter(key => {
+ const setting = allSettings.find(s => s.key === key);
+ return Boolean(
+ (setting && setting.ui_element === 'password') ||
+ redactedSettingKeys.has(key)
+ );
+ })
+ );
+
// Track the latest request per setting key. Date.now() is not a
// safe request token: rapid submits can share a millisecond and let an
// older response overwrite newer state. Key ownership also covers a
@@ -3136,8 +3306,24 @@
} else {
allSettings[settingIndex] = processedSetting;
}
- originalSettings[key] = processedSetting.value;
+ // Mirror the load-time baseline rule (see
+ // loadSettings): the server echoes "[REDACTED]" for
+ // sensitive settings, but the control renders blank,
+ // so the baseline must be '' too — otherwise the next
+ // dirty-check sees an untouched blank field as dirty
+ // and a spurious submit can clear the stored value.
+ originalSettings[key] = rendersBlankForSecrecy(processedSetting)
+ ? ''
+ : processedSetting.value;
+ // The blank baseline above only holds if the control
+ // is blank too, and nothing re-renders after a save —
+ // so bring the live node, the redaction marker and the
+ // baseline to the same state in one place.
+ syncRedactedControlState(key, processedSetting, formData[key]);
});
+ // The service-url control may have just become (or stopped
+ // being) a configured-but-blank field.
+ updateTestNotificationButtonState();
}
const currentSavingKeys = getCurrentSavingKeys();
@@ -3189,7 +3375,8 @@
const setting = allSettings.find(s => s.key === key);
const isSensitive = Boolean(
(setting && setting.ui_element === 'password') ||
- redactedSettingKeys.has(key)
+ redactedSettingKeys.has(key) ||
+ sensitiveBeforeSave.has(key)
);
// Format the values for display - mask sensitive values
@@ -5078,6 +5265,7 @@
* Test notification functionality
*/
function testNotification() {
+ if (notificationTestInProgress) return;
const testBtn = document.getElementById('test-notification-button');
const resultDiv = document.getElementById('test-notification-result');
@@ -5086,11 +5274,13 @@
return;
}
- // Get the service URL from the input field - try multiple possible selectors
+ // Get the service URL from the input field - try multiple possible selectors.
+ // serviceUrlInput tracks the control the value came from (or the last
+ // existing candidate) so the redaction check below can inspect it.
let serviceUrl = '';
// Try the standard ID formats
- const serviceUrlInput = document.getElementById('notifications-service-url');
+ let serviceUrlInput = document.getElementById('notifications-service-url');
if (serviceUrlInput) {
serviceUrl = serviceUrlInput.value.trim();
}
@@ -5099,6 +5289,7 @@
if (!serviceUrl) {
const altInput = document.getElementById('notifications.service_url');
if (altInput) {
+ serviceUrlInput = altInput;
serviceUrl = altInput.value.trim();
}
}
@@ -5107,6 +5298,7 @@
if (!serviceUrl) {
const dynamicInput = document.getElementById('setting-notifications-service_url');
if (dynamicInput) {
+ serviceUrlInput = dynamicInput;
serviceUrl = dynamicInput.value.trim();
}
}
@@ -5115,16 +5307,24 @@
if (!serviceUrl) {
const nameInput = document.querySelector('input[name="notifications.service_url"], textarea[name="notifications.service_url"]');
if (nameInput) {
+ serviceUrlInput = nameInput;
serviceUrl = nameInput.value.trim();
}
}
- if (!serviceUrl) {
+ // A blank field whose stored value is redacted (data-redacted) still
+ // counts as configured: the endpoint treats an empty service_url as
+ // "test the stored URL" (routers/settings.py), so allow it through
+ // instead of erroring.
+ const emptyButConfigured = serviceUrl === '' &&
+ isRedactedControl(NOTIFICATION_SERVICE_URL_KEY, serviceUrlInput);
+ if (!serviceUrl && !emptyButConfigured) {
showTestResult('No notification service URL configured', 'error');
return;
}
- // Disable button and show loading state
+ // Keep saves and re-renders from enabling a duplicate test.
+ notificationTestInProgress = true;
testBtn.disabled = true;
const originalText = testBtn.innerHTML;
testBtn.innerHTML = '<i class="fas fa-spinner fa-spin"></i> Testing...';
@@ -5133,7 +5333,7 @@
window.api.fetchWithErrorHandling('/settings/api/notifications/test-url', {
method: 'POST',
body: JSON.stringify({
- service_url: serviceUrl
+ service_url: emptyButConfigured ? '' : serviceUrl
})
})
.then(data => {
@@ -5148,10 +5348,12 @@
showTestResult(`Test failed: ${error?.message || 'Unable to test notification'}`, 'error');
})
.finally(() => {
- // Re-enable button and restore original text
- testBtn.disabled = false;
+ notificationTestInProgress = false;
// eslint-disable-next-line no-unsanitized/property -- audited 2026-03-28: variable built from escaped/numeric values above
testBtn.innerHTML = originalText;
+ // The URL may have been cleared, or the controls replaced,
+ // while the request was pending. Re-read the current state.
+ updateTestNotificationButtonState();
});
}
diff --git a/tests/js/components/settings-redacted-baseline-sync.test.js b/tests/js/components/settings-redacted-baseline-sync.test.js
new file mode 100644
index 0000000000..31b08d142f
--- /dev/null
+++ b/tests/js/components/settings-redacted-baseline-sync.test.js
@@ -0,0 +1,542 @@
+/**
+ * A secret configured during THIS session must stay clearable.
+ *
+ * `notifications.service_url` ships unset (`value: ""`, `ui_element:
+ * "textarea"`), and an empty value is not redacted, so the control first
+ * renders as a plain textarea with no `data-redacted`. The moment the user
+ * saves a URL into it the server echoes `[REDACTED]`, which moves the
+ * dirty-check baseline to `''` (a redacted control renders blank, so its
+ * baseline has to be blank too). Nothing re-renders after a save, so the
+ * three pieces that describe the control — the baseline, the module's
+ * `redactedSettingKeys` set and the node's own `data-redacted` — have to be
+ * brought into line by the write-back itself. If only the baseline moves,
+ * the field still shows the URL but compares equal to `''` once emptied:
+ * clearing it submits nothing, the modified marker is dropped, and the
+ * webhook stays configured with no error shown.
+ *
+ * This drives the real module against a happy-dom settings page and pins
+ * the whole sequence: configure in-session, the post-save control state,
+ * that an untouched blur does NOT wipe the stored secret, that the
+ * advertised clear gesture DOES reach the server, and that the Test
+ * Notification button follows the same state in both directions (it tests
+ * the stored URL while one is configured, and goes back to disabled once
+ * the clear lands).
+ *
+ * That settled ordering is only half of it. A save keeps its key pending
+ * until the response lands, and the response blanks the control, so there
+ * is a window in which the field is blank AND a save for it is still in
+ * flight. The last two tests hold a save open across that window and pin
+ * what may be sent from inside it: an empty body only for the explicit
+ * Enter gesture, one request per Enter (the module blurs the field after
+ * an Enter save, and that re-entry must not queue a duplicate), and a
+ * genuinely different value still saved while an earlier one is pending.
+ */
+
+import '@js/config/urls.js';
+import '@js/services/api.js';
+import '@js/utils/alert-helpers.js';
+import '@js/utils/provider-options.js';
+import '@js/utils/value-helpers.js';
+
+const WEBHOOK_KEY = 'notifications.service_url';
+const NICKNAME_KEY = 'app.nickname';
+const SECRET_URL = 'discord://HOOKID_XYZ/TOKEN_SECRET_abcdefghijklmnop';
+const NEW_URL = 'discord://NEW/TOK';
+const OTHER_URL = 'discord://OTHER/TOK';
+const REDACTED = '[REDACTED]';
+
+const flushPromises = async (turns = 12) => {
+ for (let turn = 0; turn < turns; turn += 1) await Promise.resolve();
+};
+
+function jsonResponse(payload, status = 200) {
+ return new Response(JSON.stringify(payload), {
+ status,
+ headers: { 'Content-Type': 'application/json' },
+ });
+}
+
+function setting(overrides) {
+ return {
+ category: 'general',
+ description: '',
+ editable: true,
+ max_value: null,
+ min_value: null,
+ options: null,
+ step: null,
+ visible: true,
+ ...overrides,
+ };
+}
+
+beforeEach(() => {
+ vi.resetModules();
+});
+
+afterEach(() => {
+ vi.restoreAllMocks();
+ vi.unstubAllGlobals();
+ vi.useRealTimers();
+ delete window.ui;
+ delete window.matchMedia;
+ delete window.modelProvidersRequestInProgress;
+ delete window.searchEnginesRequestInProgress;
+ delete window.modelDropdownsInitialized;
+ delete window.searchEngineDropdownInitialized;
+ document.body.replaceChildren();
+});
+
+it('keeps baseline, redaction set and data-redacted together when a secret is configured in-session', async () => {
+ vi.useFakeTimers();
+ document.head.insertAdjacentHTML(
+ 'beforeend',
+ '<meta name="csrf-token" content="csrf-redacted-baseline">',
+ );
+ document.body.innerHTML = `
+ <form id="settings-form">
+ <input id="settings-search">
+ <button type="button" class="ldr-settings-tab active" data-tab="all">All</button>
+ <div id="settings-alert"></div>
+ <div id="settings-content"></div>
+ </form>
+ `;
+
+ // Fresh install: nothing configured, so the API returns the real
+ // (empty) value and the control renders WITHOUT data-redacted.
+ const settings = {
+ 'app.nickname': setting({
+ name: 'Nickname',
+ type: 'APP',
+ ui_element: 'text',
+ value: 'original',
+ }),
+ [WEBHOOK_KEY]: setting({
+ category: 'notifications',
+ name: 'Notification Service URL',
+ type: 'APP',
+ ui_element: 'textarea',
+ value: '',
+ }),
+ };
+
+ const saveBodies = [];
+ const testUrlBodies = [];
+ const fetchMock = vi.fn((url, options = {}) => {
+ if (url === URLS.SETTINGS_API.BASE) {
+ return Promise.resolve(jsonResponse({ status: 'success', settings }));
+ }
+ if (url === URLS.SETTINGS_API.AVAILABLE_MODELS) {
+ return Promise.resolve(jsonResponse({
+ providers: { ollama_models: [] },
+ provider_options: [],
+ }));
+ }
+ if (url === URLS.SETTINGS_API.AVAILABLE_SEARCH_ENGINES) {
+ return Promise.resolve(jsonResponse({ engine_options: [] }));
+ }
+ if (url === '/settings/api/data-location') {
+ return Promise.resolve(jsonResponse({
+ data_directory: '/ldr-data',
+ security_notice: { encrypted: false },
+ }));
+ }
+ if (url === URLS.SETTINGS_API.BACKUP_STATUS) {
+ return Promise.resolve(jsonResponse({ enabled: false, count: 0, backups: [] }));
+ }
+ if (url === '/settings/api/notifications/test-url') {
+ testUrlBodies.push(JSON.parse(options.body));
+ return Promise.resolve(jsonResponse({
+ success: true,
+ message: 'Test notification sent successfully',
+ error: '',
+ }));
+ }
+ if (url === URLS.SETTINGS_API.SAVE_ALL_SETTINGS) {
+ const body = JSON.parse(options.body);
+ saveBodies.push(body);
+ const responseSettings = {};
+ Object.entries(body).forEach(([key, value]) => {
+ settings[key] = { ...settings[key], value };
+ // The server redacts a sensitive setting's echo exactly
+ // when it is configured: an empty value stays readable
+ // (DataSanitizer.redact_value), which is what makes the
+ // configure/clear round trip flip data-redacted twice.
+ const echoed = key === WEBHOOK_KEY && value !== ''
+ ? REDACTED
+ : value;
+ responseSettings[key] = { ...settings[key], value: echoed };
+ });
+ return Promise.resolve(jsonResponse({
+ status: 'success',
+ settings: responseSettings,
+ }));
+ }
+ throw new Error(`Unexpected request: ${url}`);
+ });
+ vi.stubGlobal('fetch', fetchMock);
+ window.ui = { showMessage: vi.fn() };
+ window.matchMedia = vi.fn(() => ({ matches: false }));
+
+ await import('@js/components/settings.js');
+ if (document.readyState === 'loading') {
+ document.dispatchEvent(new Event('DOMContentLoaded'));
+ }
+ await flushPromises();
+ await vi.advanceTimersByTimeAsync(301);
+
+ // The Test Notification button is created by setupRefreshButtons,
+ // which only runs on a tab click.
+ document.querySelector('[data-tab="all"]').click();
+ await vi.advanceTimersByTimeAsync(101);
+ await flushPromises();
+
+ const field = () => document.getElementById('setting-notifications-service_url');
+ const testButton = () => document.getElementById('test-notification-button');
+
+ expect(field()).not.toBeNull();
+ expect(testButton()).not.toBeNull();
+ // Nothing configured: blank, unmarked, and nothing to test.
+ expect(field().value).toBe('');
+ expect(field().dataset.redacted).toBeUndefined();
+ expect(testButton().disabled).toBe(true);
+
+ // --- configure it in this session -------------------------------------
+ field().value = SECRET_URL;
+ field().dispatchEvent(new Event('blur'));
+ await flushPromises(40);
+
+ expect(saveBodies).toEqual([{ [WEBHOOK_KEY]: SECRET_URL }]);
+ // The save echo is the sentinel, so the control must now be exactly
+ // what a re-render would produce: blank, marked, and advertising the
+ // clear gesture — the same state its blank baseline assumes.
+ expect(field().value).toBe('');
+ expect(field().dataset.redacted).toBe('true');
+ expect(field().placeholder).toContain('press Enter while empty to clear');
+ // ...and the unrelated control is untouched by the re-sync.
+ expect(document.getElementById('setting-app-nickname').value).toBe('original');
+ // The confirmation masks a value that is a secret after this save.
+ expect(window.ui.showMessage).toHaveBeenLastCalledWith(
+ 'Service url updated', 'success', 6000,
+ );
+
+ // Configured-but-blank still counts as testable, and the empty body is
+ // what tells the endpoint to use the STORED url.
+ expect(testButton().disabled).toBe(false);
+ testButton().click();
+ await flushPromises(40);
+ expect(testUrlBodies).toEqual([{ service_url: '' }]);
+
+ // --- an untouched visit must not wipe the stored secret ---------------
+ field().dispatchEvent(new Event('blur'));
+ await flushPromises(40);
+ expect(saveBodies).toEqual([{ [WEBHOOK_KEY]: SECRET_URL }]);
+
+ // --- the advertised clear gesture must reach the server ---------------
+ field().dispatchEvent(new KeyboardEvent('keydown', {
+ key: 'Enter',
+ bubbles: true,
+ cancelable: true,
+ }));
+ await flushPromises(40);
+
+ expect(saveBodies).toEqual([
+ { [WEBHOOK_KEY]: SECRET_URL },
+ { [WEBHOOK_KEY]: '' },
+ ]);
+ // Cleared: the echo is readable again, so the mark comes off and the
+ // button stops offering to test a URL that no longer exists.
+ expect(field().dataset.redacted).toBeUndefined();
+ expect(field().placeholder).toBe('');
+ expect(testButton().disabled).toBe(true);
+
+ // ...and it masks one that was a secret *before* it: the write-back
+ // has already dropped the key from the redaction set by the time the
+ // confirmation is built, so reading only the new state here would
+ // start printing values for the setting that was secret a moment ago.
+ expect(window.ui.showMessage).toHaveBeenLastCalledWith(
+ 'Service url updated', 'success', 6000,
+ );
+
+ // The secret never reached a save confirmation.
+ expect(window.ui.showMessage.mock.calls.flat().join(' ')).not.toContain(SECRET_URL);
+ expect(window.ui.showMessage.mock.calls.flat().join(' ')).not.toContain(REDACTED);
+});
+
+/**
+ * Mount the dashboard with the webhook ALREADY configured (the server
+ * echoes the sentinel, so the control renders blank and marked), and keep
+ * every save response under the test's control: `pendingSaves` holds one
+ * resolver per issued request, so a save can be left in flight while the
+ * next gesture is made. Queued saves only reach fetch once the request
+ * they are blocked on settles, so `saveBodies` is read after settleSaves.
+ */
+async function mountConfigured() {
+ document.body.innerHTML = `
+ <form id="settings-form">
+ <input id="settings-search">
+ <button type="button" class="ldr-settings-tab active" data-tab="all">All</button>
+ <div id="settings-alert"></div>
+ <div id="settings-content"></div>
+ </form>
+ `;
+
+ const settings = {
+ [NICKNAME_KEY]: setting({
+ name: 'Nickname',
+ type: 'APP',
+ ui_element: 'text',
+ value: 'original',
+ }),
+ [WEBHOOK_KEY]: setting({
+ category: 'notifications',
+ name: 'Notification Service URL',
+ type: 'APP',
+ ui_element: 'textarea',
+ value: REDACTED,
+ }),
+ };
+
+ const saveBodies = [];
+ const pendingSaves = [];
+ const pendingNotificationTests = [];
+ const fetchMock = vi.fn((url, options = {}) => {
+ if (url === URLS.SETTINGS_API.BASE) {
+ return Promise.resolve(jsonResponse({ status: 'success', settings }));
+ }
+ if (url === URLS.SETTINGS_API.AVAILABLE_MODELS) {
+ return Promise.resolve(jsonResponse({
+ providers: { ollama_models: [] },
+ provider_options: [],
+ }));
+ }
+ if (url === URLS.SETTINGS_API.AVAILABLE_SEARCH_ENGINES) {
+ return Promise.resolve(jsonResponse({ engine_options: [] }));
+ }
+ if (url === '/settings/api/data-location') {
+ return Promise.resolve(jsonResponse({
+ data_directory: '/ldr-data',
+ security_notice: { encrypted: false },
+ }));
+ }
+ if (url === URLS.SETTINGS_API.BACKUP_STATUS) {
+ return Promise.resolve(jsonResponse({ enabled: false, count: 0, backups: [] }));
+ }
+ if (url === '/settings/api/notifications/test-url') {
+ return new Promise(resolveResponse => {
+ pendingNotificationTests.push(() => resolveResponse(jsonResponse({
+ success: true,
+ message: 'Test notification sent successfully',
+ error: '',
+ })));
+ });
+ }
+ if (url === URLS.SETTINGS_API.SAVE_ALL_SETTINGS) {
+ const body = JSON.parse(options.body);
+ saveBodies.push(body);
+ return new Promise(resolveResponse => {
+ pendingSaves.push(() => {
+ const responseSettings = {};
+ Object.entries(body).forEach(([key, value]) => {
+ settings[key] = { ...settings[key], value };
+ const echoed = key === WEBHOOK_KEY && value !== ''
+ ? REDACTED
+ : value;
+ responseSettings[key] = { ...settings[key], value: echoed };
+ });
+ resolveResponse(jsonResponse({
+ status: 'success',
+ settings: responseSettings,
+ }));
+ });
+ });
+ }
+ throw new Error(`Unexpected request: ${url}`);
+ });
+ vi.stubGlobal('fetch', fetchMock);
+ window.ui = { showMessage: vi.fn() };
+ window.matchMedia = vi.fn(() => ({ matches: false }));
+
+ // The module initialises on import unless the document is still
+ // loading, so this mount registers no DOMContentLoaded listener that a
+ // later mount in the same file could re-trigger.
+ vi.spyOn(document, 'readyState', 'get').mockReturnValue('complete');
+ await import('@js/components/settings.js');
+ await flushPromises();
+ await vi.advanceTimersByTimeAsync(301);
+ // Same settling sequence the first test uses to reach a rendered tab.
+ document.querySelector('[data-tab="all"]').click();
+ await vi.advanceTimersByTimeAsync(101);
+ await flushPromises();
+
+ // Answer everything outstanding, including saves that were queued
+ // behind another save and only issued once it settled.
+ const settleSaves = async (rounds = 6) => {
+ for (let round = 0; round < rounds; round += 1) {
+ pendingSaves.splice(0, pendingSaves.length).forEach(answer => answer());
+ await flushPromises(40);
+ }
+ };
+
+ return { settings, saveBodies, pendingSaves, pendingNotificationTests, settleSaves };
+}
+
+const pressEnter = element => element.dispatchEvent(new KeyboardEvent('keydown', {
+ key: 'Enter',
+ bubbles: true,
+ cancelable: true,
+}));
+
+it('sends an empty value for a redacted control only for the Enter gesture, in flight or not', async () => {
+ vi.useFakeTimers();
+ const { settings, saveBodies, pendingSaves, settleSaves } = await mountConfigured();
+ const field = () => document.getElementById('setting-notifications-service_url');
+
+ // Configured before this session: blank, marked, blank baseline.
+ expect(field().value).toBe('');
+ expect(field().dataset.redacted).toBe('true');
+
+ // --- replace the stored URL, and hold that save in flight -------------
+ field().focus();
+ // The module calls input.blur() after an Enter save; that only
+ // dispatches a blur for the focused node, and the blur listener
+ // re-entering handleInputChange is the sequence under test here.
+ expect(document.activeElement).toBe(field());
+ field().value = NEW_URL;
+ field().dispatchEvent(new Event('input'));
+ pressEnter(field());
+ await flushPromises(40);
+
+ expect(document.activeElement).not.toBe(field());
+ expect(saveBodies).toEqual([{ [WEBHOOK_KEY]: NEW_URL }]);
+ expect(pendingSaves).toHaveLength(1);
+
+ // --- the save is still in flight; the control is still marked ---------
+ // Emptying it and leaving is not the clear gesture: the field renders
+ // blank either way, so nothing here may be sent. The key stays pending
+ // for as long as the save is open, and that alone used to make this
+ // blur look like a change worth saving.
+ field().value = '';
+ field().dispatchEvent(new Event('input'));
+ field().dispatchEvent(new Event('blur'));
+ field().dispatchEvent(new Event('blur'));
+ await flushPromises(40);
+
+ // Settle first: a submit made from inside that window is queued behind
+ // the open save and only reaches fetch once it lands, so the strays
+ // are invisible until here.
+ await settleSaves();
+ expect(saveBodies.filter(body => body[WEBHOOK_KEY] === '')).toEqual([]);
+ expect(saveBodies).toEqual([{ [WEBHOOK_KEY]: NEW_URL }]);
+ // The response left the control in its redacted, blank state.
+ expect(field().value).toBe('');
+ expect(field().dataset.redacted).toBe('true');
+
+ // --- the gesture that IS a clear still reaches the server -------------
+ // Start another save and clear the field while that one is open, so
+ // the gesture is made from the same in-flight window the strays were.
+ field().focus();
+ field().value = OTHER_URL;
+ field().dispatchEvent(new Event('input'));
+ pressEnter(field());
+ await flushPromises(40);
+ expect(saveBodies).toHaveLength(2);
+ expect(pendingSaves).toHaveLength(1);
+
+ field().focus();
+ field().value = '';
+ field().dispatchEvent(new Event('input'));
+ pressEnter(field());
+ await flushPromises(40);
+ await settleSaves();
+
+ // One clear, made by the gesture; the strays above sent nothing.
+ expect(saveBodies).toEqual([
+ { [WEBHOOK_KEY]: NEW_URL },
+ { [WEBHOOK_KEY]: OTHER_URL },
+ { [WEBHOOK_KEY]: '' },
+ ]);
+ expect(settings[WEBHOOK_KEY].value).toBe('');
+ // Cleared: the echo is readable again, so the mark comes off.
+ expect(field().dataset.redacted).toBeUndefined();
+});
+
+it('queues one save per Enter and still saves a value changed while one is pending', async () => {
+ vi.useFakeTimers();
+ const { settings, saveBodies, settleSaves } = await mountConfigured();
+ const field = () => document.getElementById('setting-notifications-service_url');
+ const nickname = () => document.getElementById('setting-app-nickname');
+
+ field().focus();
+ field().value = NEW_URL;
+ field().dispatchEvent(new Event('input'));
+ pressEnter(field());
+ await flushPromises(40);
+ expect(document.activeElement).not.toBe(field());
+
+ // A different value typed while that save is open is a real intent:
+ // the earlier write may commit after it, so it still has to be sent.
+ field().value = OTHER_URL;
+ field().dispatchEvent(new Event('input'));
+ field().dispatchEvent(new Event('blur'));
+ await flushPromises(40);
+ await settleSaves();
+
+ // Two requests, not three: the programmatic blur after the Enter
+ // carried the value already in flight and added nothing.
+ expect(saveBodies).toEqual([
+ { [WEBHOOK_KEY]: NEW_URL },
+ { [WEBHOOK_KEY]: OTHER_URL },
+ ]);
+ expect(settings[WEBHOOK_KEY].value).toBe(OTHER_URL);
+
+ // ...and on a control that is not redacted at all, a reversal all the
+ // way back to the acknowledged value while a save is pending is still
+ // a write, because that older save can commit after it.
+ const beforeReversal = saveBodies.length;
+ nickname().value = 'changed';
+ nickname().dispatchEvent(new Event('blur'));
+ await flushPromises(40);
+ nickname().value = 'original';
+ nickname().dispatchEvent(new Event('blur'));
+ await flushPromises(40);
+ await settleSaves();
+
+ expect(saveBodies.slice(beforeReversal).map(body => body[NICKNAME_KEY]))
+ .toEqual(['changed', 'original']);
+ expect(settings[NICKNAME_KEY].value).toBe('original');
+});
+
+
+it('keeps an active notification test disabled across other saves and a clear', async () => {
+ vi.useFakeTimers();
+ const { pendingNotificationTests, settleSaves } = await mountConfigured();
+ const button = () => document.getElementById('test-notification-button');
+ const field = () => document.getElementById('setting-notifications-service_url');
+ const nickname = document.getElementById('setting-app-nickname');
+
+ button().click();
+ await flushPromises(40);
+ expect(pendingNotificationTests).toHaveLength(1);
+ expect(button().disabled).toBe(true);
+
+ // Saving another key must not discard the active request's busy state.
+ nickname.value = 'updated while testing';
+ nickname.dispatchEvent(new Event('blur'));
+ await settleSaves();
+ expect(button().disabled).toBe(true);
+ button().click();
+ await flushPromises(40);
+ expect(pendingNotificationTests).toHaveLength(1);
+
+ // Completing the earlier test must consult the newly cleared setting.
+ field().focus();
+ field().value = '';
+ pressEnter(field());
+ await settleSaves();
+ expect(field().dataset.redacted).toBeUndefined();
+ pendingNotificationTests[0]();
+ await flushPromises(40);
+ expect(button().disabled).toBe(true);
+ expect(button().textContent).not.toContain('Testing');
+});
diff --git a/tests/security/test_settings_secret_redaction_isolation.py b/tests/security/test_settings_secret_redaction_isolation.py
index 9e3ca157ba..40b53fa8be 100644
--- a/tests/security/test_settings_secret_redaction_isolation.py
+++ b/tests/security/test_settings_secret_redaction_isolation.py
@@ -1909,3 +1909,29 @@ def test_exact_sentinel_stays_a_noop_not_an_error(logged_in_client):
"/settings/save_all_settings", json={WEBHOOK_KEY: REDACTED}
)
assert save_all.status_code == 200
+
+
+def test_save_all_create_rejects_sentinel_for_plain_sensitive_leaf(
+ logged_in_client,
+):
+ """save-all CREATE of a sensitive leaf with no DB row yet (a plain
+ value, not a container) must reject the sentinel too: the update
+ path's exact-match no-op has nothing to keep, so an accepted write
+ would store "[REDACTED]" as the credential (#5947). The single-PUT
+ recreate path is pinned above (test_recreated_setting_rejects_
+ sentinel_entirely); this pins the save-all batch create path, whose
+ ui_element is not yet known so sensitivity is decided by the leaf
+ name alone."""
+ c = logged_in_client
+ key = "notifications.round3_create_guard.api_key"
+
+ response = c.post("/settings/save_all_settings", json={key: REDACTED})
+
+ assert response.status_code == 400, response.get_data(as_text=True)
+ payload = response.get_json()
+ assert payload["status"] == "error"
+ assert [e["key"] for e in payload["errors"]] == [key]
+ assert REDACTED in payload["errors"][0]["error"]
+
+ # Not persisted: no row was created, so the follow-up GET 404s.
+ assert c.get(f"/settings/api/{key}").status_code == 404
diff --git a/tests/web/routers/test_router_sibling_consistency.py b/tests/web/routers/test_router_sibling_consistency.py
index 214fca567e..6f84b529bd 100644
--- a/tests/web/routers/test_router_sibling_consistency.py
+++ b/tests/web/routers/test_router_sibling_consistency.py
@@ -501,9 +501,8 @@ def test_upload_endpoints_have_paired_rate_limits():
# Survey (routers/settings.py, every POST/PUT/DELETE that writes through
# SettingsManager.set_setting / equivalent onto the `settings` table):
# 7 of 9 siblings carry @settings_limit. The remaining 2 -- both read in
-# full -- are genuine gaps, not intentional exceptions (unlike
-# api_test_notification_url below, neither has any rate-limit rationale in
-# its docstring, and both do the exact same "look up current value, call
+# full -- are genuine gaps, not intentional exceptions (neither carries any
+# rate-limit rationale, and both do the exact same "look up current value, call
# settings_manager.set_setting, invalidate cache" shape as
# api_update_setting, which IS limited). Reported as a real finding; pinned
# here (not silently allowlisted as "fine") so a reader of this test sees
@@ -534,15 +533,25 @@ SETTINGS_VALUE_MUTATION_LIMITED = {
# than quietly allowlisting it as justified.
SETTINGS_VALUE_MUTATION_KNOWN_GAP = {}
+# (method, path) -> the rate-limit decorator the route must carry. For
+# routes in this family limited by their OWN bucket rather than the shared
+# @settings_limit, so the expectation names that handle instead of
+# assuming the family default.
+SETTINGS_VALUE_MUTATION_OWN_BUCKET_LIMITED = {
+ # Previously a justified exception, quoting a docstring that said
+ # "Rate limiting is not applied here because users need to test URLs
+ # when configuring notifications." That reasoning covers a caller who
+ # submits a URL, and that path is still exempt -- via
+ # notification_test_limit's exempt_when predicate. It does not cover
+ # the stored-URL fallback, a zero-argument send trigger whose
+ # destination the caller never has to name, so the route now carries
+ # its own "notification_test" scope: testing a notification must not
+ # spend the quota that saving settings needs.
+ ("POST", "/settings/api/notifications/test-url"): "notification_test_limit",
+}
+
# (method, path) -> justification. Verified by reading each route in full.
SETTINGS_VALUE_MUTATION_JUSTIFIED_EXCEPTIONS = {
- ("POST", "/settings/api/notifications/test-url"): (
- "api_test_notification_url's own docstring documents this as "
- "deliberate: 'Rate limiting is not applied here because users "
- "need to test URLs when configuring notifications. Abuse is "
- "mitigated by the @login_required decorator and the fact that "
- "users can only spam their own notification services.'"
- ),
("POST", "/settings/api/rate-limiting/engines/{engine_type}/reset"): (
"administrative: deletes the caller's own persisted "
"RateLimitEstimate rows, not a Setting value -- a different "
@@ -566,11 +575,12 @@ SETTINGS_VALUE_MUTATION_JUSTIFIED_EXCEPTIONS = {
def test_settings_value_mutation_rate_limit_coverage():
"""Pins the current, surveyed rate-limit landscape of settings.py's
value-mutation routes. Any route in this family not accounted for by
- one of the three registries above is new drift and fails here by
+ one of the four registries above is new drift and fails here by
name; the KNOWN_GAP entries specifically stay reported (not silently
justified) so this test doesn't quietly launder a real bug into "fine
by allowlist"."""
seen_limited = set()
+ seen_own_bucket = set()
unaccounted = []
for route in _mutating_routes():
if route.endpoint.__module__.rsplit(".", 1)[-1] != "settings":
@@ -580,6 +590,7 @@ def test_settings_value_mutation_rate_limit_coverage():
candidate = (m, route.path)
if (
candidate in SETTINGS_VALUE_MUTATION_LIMITED
+ or candidate in SETTINGS_VALUE_MUTATION_OWN_BUCKET_LIMITED
or candidate in SETTINGS_VALUE_MUTATION_KNOWN_GAP
or candidate in SETTINGS_VALUE_MUTATION_JUSTIFIED_EXCEPTIONS
):
@@ -599,6 +610,18 @@ def test_settings_value_mutation_rate_limit_coverage():
"this route needs moving to "
"SETTINGS_VALUE_MUTATION_KNOWN_GAP with a reason."
)
+ elif key in SETTINGS_VALUE_MUTATION_OWN_BUCKET_LIMITED:
+ seen_own_bucket.add(key)
+ expected = SETTINGS_VALUE_MUTATION_OWN_BUCKET_LIMITED[key]
+ if expected not in _decorator_names(route):
+ unaccounted.append(
+ f" {_route_label(route)} was surveyed as carrying "
+ f"@{expected}, its own rate-limit bucket, but no "
+ "longer does -- either the decorator was dropped "
+ "(regression: the stored-URL fallback is a "
+ "zero-argument send trigger) or the handle was "
+ "renamed and this registry needs updating."
+ )
elif key in SETTINGS_VALUE_MUTATION_KNOWN_GAP:
if has_settings_limit:
unaccounted.append(
@@ -617,6 +640,14 @@ def test_settings_value_mutation_rate_limit_coverage():
f"app: {sorted(missing_from_limited)} -- route renamed/removed? "
"Update this test's registries."
)
+ missing_from_own_bucket = (
+ set(SETTINGS_VALUE_MUTATION_OWN_BUCKET_LIMITED) - seen_own_bucket
+ )
+ assert not missing_from_own_bucket, (
+ "Surveyed own-bucket rate-limited route(s) no longer found in the "
+ f"live app: {sorted(missing_from_own_bucket)} -- route "
+ "renamed/removed? Update this test's registries."
+ )
assert not unaccounted, "\n".join(unaccounted)
diff --git a/tests/web/routes/test_settings_notification_test_error_shaping.py b/tests/web/routes/test_settings_notification_test_error_shaping.py
new file mode 100644
index 0000000000..04815a99d6
--- /dev/null
+++ b/tests/web/routes/test_settings_notification_test_error_shaping.py
@@ -0,0 +1,206 @@
+"""Error shaping for ``POST /settings/api/notifications/test-url``.
+
+The endpoint tests either the URL the caller sent or, for a blank/sentinel
+body, the caller's STORED ``notifications.service_url``. Those two paths
+must not report failures the same way:
+
+* caller-supplied -- the caller just typed the URL, so the validator's
+ reason (which can name the host) is theirs already and is echoed;
+* stored-URL -- the setting is redacted on every read path, so an error
+ naming its host would hand back through this endpoint exactly what the
+ redaction withholds. Those go to the server log and the caller gets a
+ generic failure.
+
+The narrowing that keeps the generic message from swallowing everything:
+a ``test_service`` failure that names no destination (the operator
+instruction for ``LDR_NOTIFICATIONS_ALLOW_OUTBOUND``, the target-count cap,
+the unambiguous-parse refusal, ...) is actionable and host-free, so it is
+still returned inline -- ``docs/NOTIFICATIONS.md`` promises exactly that,
+and a user who cannot read the server log has nothing else to go on.
+
+``NotificationService.test_service`` is patched throughout: these tests are
+about the response the router builds from its result, and each patched
+return value is a verbatim string from ``notifications/service.py`` /
+``security/notification_validator.py``. No network, no Apprise.
+"""
+
+import os
+
+# Rate limiting is read once at import time in
+# ``web/dependencies/rate_limit.py``; disable it before the app is imported
+# so a direct run of this file cannot flake on the shared settings bucket
+# (the PUT + POST pairs below).
+os.environ.setdefault("LDR_DISABLE_RATE_LIMITING", "true")
+
+import pytest # noqa: E402
+
+from local_deep_research.security.notification_validator import ( # noqa: E402
+ NotificationURLValidator,
+)
+
+WEBHOOK_KEY = "notifications.service_url"
+STORED_URL = "discord://HOOKID_XYZ/TOKEN_SECRET_abcdefghijklmnop"
+TEST_URL_ROUTE = "/settings/api/notifications/test-url"
+
+BLOCKED_HOST = "internal.corp.example"
+# Verbatim from NotificationURLValidator._validate_url_security: the
+# hostname is interpolated into the message the caller would receive.
+PRIVATE_IP_ERROR = (
+ f"{NotificationURLValidator.PRIVATE_IP_REJECTION_PREFIX} {BLOCKED_HOST}"
+)
+METADATA_ERROR = (
+ f"Blocked cloud-metadata / link-local IP address: {BLOCKED_HOST}"
+)
+# Verbatim from NotificationService.test_service: a static operator
+# instruction. It names no destination and only an operator can act on it.
+OUTBOUND_DISABLED_ERROR = (
+ "Outbound notifications are disabled. The server administrator must "
+ "set LDR_NOTIFICATIONS_ALLOW_OUTBOUND=true to enable notification "
+ "webhooks. See SECURITY.md 'Notification Webhook SSRF' for details."
+)
+GENERIC_ERROR = (
+ "Failed to test notification service. Check server logs for details."
+)
+
+
+def configured_client(authenticated_client):
+ """A logged-in client whose stored notification URL is set.
+
+ Stored through the real settings API so the endpoint's fallback
+ resolves it the way it does in production (the tests below assert
+ ``test_service`` was handed exactly this URL, which is what proves the
+ stored path -- not the caller-supplied one -- was taken).
+ """
+ response = authenticated_client.put(
+ f"/settings/api/{WEBHOOK_KEY}", json={"value": STORED_URL}
+ )
+ assert response.status_code == 200, response.text
+ return authenticated_client
+
+
+def failing_test_service(monkeypatch):
+ """Patch ``test_service`` to fail with a chosen error, recording the
+ URL it was asked to test."""
+ from local_deep_research.notifications.service import NotificationService
+
+ tested_urls = []
+
+ def install(error):
+ def fake_test_service(_service, url):
+ tested_urls.append(url)
+ return {"success": False, "error": error}
+
+ monkeypatch.setattr(
+ NotificationService, "test_service", fake_test_service
+ )
+ return tested_urls
+
+ return install
+
+
+ "host_bearing_error", [PRIVATE_IP_ERROR, METADATA_ERROR]
+)
+def test_stored_url_failure_never_names_the_stored_host(
+ configured_client, failing_test_service, host_bearing_error
+):
+ """The two validator messages that interpolate a hostname must not come
+ back to a caller who never named the destination."""
+ tested_urls = failing_test_service(host_bearing_error)
+
+ response = configured_client.post(TEST_URL_ROUTE, json={"service_url": ""})
+
+ assert response.status_code == 200, response.text
+ # The blank body really did take the stored-URL fallback.
+ assert tested_urls == [STORED_URL]
+ body = response.json()
+ assert body["success"] is False
+ assert body["error"] == GENERIC_ERROR
+ # Nothing host-derived anywhere in the response, not just in "error".
+ assert BLOCKED_HOST not in response.text
+ assert "Blocked" not in response.text
+
+
+def test_caller_supplied_failure_still_returns_the_validator_detail(
+ configured_client, failing_test_service
+):
+ """Positive control for the suppression above: a caller who names the
+ destination is told why it was refused. Without this the endpoint could
+ "pass" the test above by blanking every error it ever returns."""
+ tested_urls = failing_test_service(PRIVATE_IP_ERROR)
+ caller_url = f"http://{BLOCKED_HOST}/hook"
+
+ response = configured_client.post(
+ TEST_URL_ROUTE, json={"service_url": caller_url}
+ )
+
+ assert response.status_code == 200, response.text
+ assert tested_urls == [caller_url]
+ body = response.json()
+ assert body["success"] is False
+ assert body["error"] == PRIVATE_IP_ERROR
+ assert BLOCKED_HOST in body["error"]
+
+
+def test_stored_url_static_operator_instruction_is_returned_inline(
+ configured_client, failing_test_service
+):
+ """The stored path must not be a blanket "check the logs": a failure
+ that names no destination is the user's only actionable feedback, and
+ docs/NOTIFICATIONS.md promises this one inline."""
+ tested_urls = failing_test_service(OUTBOUND_DISABLED_ERROR)
+
+ response = configured_client.post(TEST_URL_ROUTE, json={"service_url": ""})
+
+ assert response.status_code == 200, response.text
+ assert tested_urls == [STORED_URL]
+ body = response.json()
+ assert body["success"] is False
+ assert body["error"] == OUTBOUND_DISABLED_ERROR
+
+
+def test_stored_url_unknown_failure_is_suppressed(
+ configured_client, failing_test_service
+):
+ """The allowlist fails closed: an error string this router does not
+ recognise is treated as possibly host-bearing. A message added to
+ ``test_service`` later costs a user some detail; it does not leak by
+ default."""
+ tested_urls = failing_test_service(
+ f"Some future refusal mentioning {BLOCKED_HOST}"
+ )
+
+ response = configured_client.post(TEST_URL_ROUTE, json={"service_url": ""})
+
+ assert response.status_code == 200, response.text
+ assert tested_urls == [STORED_URL]
+ assert response.json()["error"] == GENERIC_ERROR
+ assert BLOCKED_HOST not in response.text
+
+
+def test_stored_url_success_still_reports_the_success_message(
+ configured_client, monkeypatch
+):
+ """Only failures are reshaped: a successful stored-URL test keeps its
+ message (and carries no error)."""
+ from local_deep_research.notifications.service import NotificationService
+
+ monkeypatch.setattr(
+ NotificationService,
+ "test_service",
+ lambda _service, url: {
+ "success": True,
+ "message": "Test notification sent successfully",
+ },
+ )
+
+ response = configured_client.post(TEST_URL_ROUTE, json={"service_url": ""})
+
+ assert response.status_code == 200, response.text
+ assert response.json() == {
+ "success": True,
+ "message": "Test notification sent successfully",
+ "error": "",
+ }
diff --git a/tests/web/routes/test_settings_notification_test_rate_limit.py b/tests/web/routes/test_settings_notification_test_rate_limit.py
new file mode 100644
index 0000000000..cc3f30c695
--- /dev/null
+++ b/tests/web/routes/test_settings_notification_test_rate_limit.py
@@ -0,0 +1,123 @@
+"""Rate-limit scope tests for the notification test-url endpoint.
+
+``api_test_notification_url`` (web/routers/settings.py) carries
+``@notification_test_limit`` — a ``shared_limit`` with its own
+``notification_test`` bucket (per-user key), whose ``exempt_when`` is
+``_caller_supplied_notification_url``. The split that matters:
+
+* a caller who names a URL in the body is exempt (the case the endpoint
+ exists to serve — testing a URL while configuring notifications);
+* the STORED-URL fallback (blank/sentinel body) consumes the bucket —
+ that path is a zero-argument send trigger to the caller's own
+ configured webhook (#5958 follow-up).
+
+Like ``tests/web/routes/test_research_log_export_rate_limit.py`` (the
+idiom this file follows), enforcement is driven via
+``limiter._check_request_limit`` — the exact call slowapi's decorator
+wrapper makes per request — rather than a TestClient round trip: the
+limiter and its storage are process-global (other test modules import
+the app with ``LDR_DISABLE_RATE_LIMITING=true``), and the raw check
+needs none of the endpoint's DB plumbing. A uuid-unique username per
+test isolates each bucket, so no ``limiter.reset()`` is required.
+
+The payload is stashed on ``request.state`` by the real
+``_notification_test_body`` route dependency before slowapi evaluates
+``exempt_when``; the tests reproduce that stash directly.
+"""
+
+import uuid
+
+import pytest
+from slowapi.errors import RateLimitExceeded
+from starlette.requests import Request
+
+from local_deep_research.web.routers import settings as settings_mod
+
+_ENDPOINT = f"{settings_mod.__name__}.api_test_notification_url"
+
+
+def _request(username):
+ """Minimal Starlette ``Request`` from a raw ASGI scope (idiom from
+ ``test_research_log_export_rate_limit.py``). The session key makes
+ ``_user_key`` resolve to a per-user bucket, like a logged-in request.
+ """
+ scope = {
+ "type": "http",
+ "method": "POST",
+ "path": "/settings/api/notifications/test-url",
+ "query_string": b"",
+ "headers": [],
+ "client": ("10.204.5.2", 51234),
+ "session": {"username": username},
+ }
+ return Request(scope)
+
+
+def _route_limit():
+ """The endpoint's ``notification_test`` limit.
+
+ Selected by scope rather than unpacked as the route's only entry:
+ ``_route_limits`` holds one parsed ``Limit`` per limit string, and a
+ ``;``-joined multi-limit configuration -- the shape ``DEFAULT_RATE_LIMIT``
+ already uses -- would make a one-element unpack raise instead of testing
+ anything. With several, the smallest quota is the one a burst hits first,
+ so that is the one the enforcement test has to exhaust.
+ """
+ limits = [
+ limit
+ for limit in settings_mod.limiter._route_limits[_ENDPOINT]
+ if limit.scope == "notification_test"
+ ]
+ assert limits, (
+ f"no notification_test limit registered for {_ENDPOINT}; "
+ f"got {settings_mod.limiter._route_limits[_ENDPOINT]!r}"
+ )
+ return min(limits, key=lambda limit: limit.limit.amount)
+
+
+def test_stored_url_fallback_consumes_the_notification_test_bucket(
+ monkeypatch,
+):
+ monkeypatch.setattr(settings_mod.limiter, "enabled", True)
+ limit = _route_limit()
+ # Wiring: own scope (not the shared "settings" bucket) with the
+ # notification-specific exemption predicate.
+ assert limit.scope == "notification_test"
+ assert limit.exempt_when is settings_mod._caller_supplied_notification_url
+
+ quota = limit.limit.amount # 30 per minute via rate_limit_settings
+ username = f"notif-test-bucket-{uuid.uuid4().hex[:12]}"
+
+ def hit():
+ request = _request(username)
+ # Blank body: not caller-supplied, so the stored-URL fallback is
+ # what this request would take — it must consume the bucket.
+ request.state.notification_test_payload = {"service_url": ""}
+ settings_mod.limiter._check_request_limit(
+ request, settings_mod.api_test_notification_url, False
+ )
+
+ for _ in range(quota):
+ hit() # within the quota: must not raise
+
+ with pytest.raises(RateLimitExceeded):
+ hit() # one past the quota: the fallback path is cut off
+
+
+def test_caller_supplied_url_is_exempt_from_the_notification_test_bucket(
+ monkeypatch,
+):
+ monkeypatch.setattr(settings_mod.limiter, "enabled", True)
+ quota = _route_limit().limit.amount
+ username = f"notif-test-exempt-{uuid.uuid4().hex[:12]}"
+
+ # Well past the stored-URL quota: a caller who names their own
+ # destination must never be throttled by the fallback bucket.
+ for _ in range(quota + 10):
+ request = _request(username)
+ request.state.notification_test_payload = {
+ "service_url": "discord://HOOKID/TOKEN"
+ }
+ settings_mod.limiter._check_request_limit(
+ request, settings_mod.api_test_notification_url, False
+ )