fix(dashboard): correct the four guard-flag descriptions to the audited semantics

changelog.d/fixes/flag-descriptions-setup-claims.md

@@ -0,0 +1 @@
+- **fix(dashboard):** The feature-flag cards for `OUTBOUND_SSRF_GUARD_ENABLED`, `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`, `OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` and `RERANK_REMOTE_PROVIDER_NODES` still described the pre-correction guard semantics (local URLs blocked by default, metadata hosts never routed to). The dashboard renders the raw English `description` from `featureFlagDefinitions.ts`, so the four descriptions now carry the same corrected semantics as `docs/reference/FEATURE_FLAGS.md` (PR #15616), pinned by unit tests — thanks @woodsonl

src/shared/constants/featureFlagDefinitions.ts

@@ -85,7 +85,8 @@ export const FEATURE_FLAG_DEFINITIONS: FeatureFlagDefinition[] = [
   {
     key: "OUTBOUND_SSRF_GUARD_ENABLED",
     label: "SSRF Guard",
-    description: "Block outbound requests to private/internal IP ranges",
+    description:
+      "Legacy alias: a value saved on this flag's dashboard toggle is read before the environment; false, 0, no, or off in either turns the outbound URL guard's host checks off like OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS",
     descriptionI18nKey: "featureFlagOutboundSsrfGuardEnabledDescription",
     category: "security",
     defaultValue: "true",
@@ -159,7 +160,7 @@ export const FEATURE_FLAG_DEFINITIONS: FeatureFlagDefinition[] = [
     key: "RERANK_REMOTE_PROVIDER_NODES",
     label: "Remote Rerank Provider Nodes",
     description:
-      "Allow POST /v1/rerank (and the memory engine's rerank step, which calls it over loopback) to use OpenAI-compatible provider nodes hosted outside localhost — a LAN box or Tailscale peer running TEI, Infinity, vLLM, etc. Off by default — routing to a remote host changes egress identity and must be an explicit operator decision. Loopback nodes are always allowed and unaffected. Remote nodes must also pass the provider outbound URL policy (cloud-metadata hosts are never routed to).",
+      "Allow POST /v1/rerank (and the memory engine's rerank step, which calls it over loopback) to use OpenAI-compatible provider nodes hosted outside localhost — a LAN box or Tailscale peer running TEI, Infinity, vLLM, etc. Off by default — routing to a remote host changes egress identity and must be an explicit operator decision. Loopback nodes are always allowed and unaffected. Remote nodes must also pass the provider outbound URL policy.",
     descriptionI18nKey: "settings.featureFlags.rerankRemoteProviderNodes",
     category: "network",
     defaultValue: "false",
@@ -361,7 +362,8 @@ export const FEATURE_FLAG_DEFINITIONS: FeatureFlagDefinition[] = [
   {
     key: "OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS",
     label: "Allow Private Provider URLs",
-    description: "Allow provider URLs pointing to private/internal networks",
+    description:
+      "Turns off the outbound URL guard's host checks, cloud-metadata block included, on provider URL validation, model discovery, provider-node base URLs, and the proxy-fallback test, and allows private webhook targets. Local and LAN URLs already pass on the validation, discovery, and provider-node paths by default; the proxy-fallback test and webhook targets check only this flag",
     descriptionI18nKey: "featureFlagOmnirouteAllowPrivateProviderUrlsDescription",
     category: "network",
     defaultValue: "false",
@@ -373,7 +375,7 @@ export const FEATURE_FLAG_DEFINITIONS: FeatureFlagDefinition[] = [
     key: "OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS",
     label: "Allow Local Provider URLs",
     description:
-      "Allow adding and validating providers on local/private addresses (127.0.0.1, localhost, LAN, private IP ranges) — needed for local OpenAI-compatible models. Enabled by default (OmniRoute is local-first); turn it OFF to enforce strict public-only blocking if you only use public providers. Cloud-metadata endpoints (e.g. 169.254.169.254) stay blocked either way.",
+      "Allow provider URLs on local/private addresses (127.0.0.1, localhost, LAN). On by default (OmniRoute is local-first): the guard then blocks cloud-metadata endpoints (all of 169.254.0.0/16 plus the known metadata hostnames). Disable for strict public-only blocking: private and loopback hosts are blocked too",
     descriptionI18nKey: "featureFlagOmnirouteAllowLocalProviderUrlsDescription",
     category: "network",
     defaultValue: "true",

tests/unit/feature-flag-descriptions-claims.test.ts

@@ -0,0 +1,49 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { FEATURE_FLAG_DEFINITIONS } from "../../src/shared/constants/featureFlagDefinitions";
+
+const byKey = (key: string) => {
+  const entry = FEATURE_FLAG_DEFINITIONS.find((f) => f.key === key);
+  assert.ok(entry, `feature flag ${key} must be defined`);
+  return entry.description;
+};
+
+// The dashboard renders these raw English descriptions (descriptionI18nKey has no
+// en.json message), so they must state the same guard semantics as
+// docs/reference/FEATURE_FLAGS.md. PR #15616 corrected the docs; these pins keep the
+// dashboard text from drifting back to the old claims.
+test("SSRF Guard dashboard description states the legacy-alias semantics", () => {
+  const d = byKey("OUTBOUND_SSRF_GUARD_ENABLED");
+  assert.match(d, /Legacy alias/);
+  assert.match(d, /dashboard toggle is read before the environment/);
+  assert.match(d, /false, 0, no, or off/);
+  assert.doesNotMatch(d, /^Block outbound requests/);
+});
+
+test("Allow Private dashboard description states what the flag turns off", () => {
+  const d = byKey("OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS");
+  assert.match(d, /cloud-metadata block included/);
+  assert.match(d, /provider URL validation, model discovery, provider-node base URLs/);
+  assert.match(d, /private webhook targets/);
+  // The proxy-fallback test and webhooks consult only this flag — the local-first
+  // default does not open them.
+  assert.match(d, /check only this flag/);
+  assert.doesNotMatch(d, /REQUIRED for self-hosted/);
+});
+
+test("Allow Local dashboard description states the local-first default and the metadata block", () => {
+  const d = byKey("OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS");
+  assert.match(d, /by default \(OmniRoute is local-first\)|On by default \(local-first\)/);
+  assert.match(d, /all of 169\.254\.0\.0\/16/);
+  assert.match(d, /private and loopback hosts are blocked too/);
+  assert.doesNotMatch(d, /needed for local OpenAI-compatible models/);
+});
+
+test("Remote Rerank dashboard description does not claim metadata hosts are never routed to", () => {
+  const d = byKey("RERANK_REMOTE_PROVIDER_NODES");
+  assert.match(d, /must also pass the provider outbound URL policy/);
+  // Under guard mode "none" (private opt-in) the node check does not block metadata,
+  // so the absolute claim was removed with the docs correction.
+  assert.doesNotMatch(d, /never routed to/);
+});