feat(telemetry): one-time opt-out beacon + banner Settings deep-link (MCP-2482) (#684)

* feat(telemetry): one-time opt-out beacon + banner Settings deep-link (MCP-2482)

Part B — server-side opt-out beacon:
- Add internal/telemetry/optout.go: TelemetryDisableTransition (resolved-state
  compare, nil == enabled per MCP-2477), SendOptOutBeacon (reuses the existing
  /heartbeat ingest with event:"telemetry_disabled" + only the anonymous_id,
  no usage payload), and Service.NotifyConfigChanged.
- Detect the enabled->disabled flip on config write and fire EXACTLY ONE
  best-effort, fire-and-forget beacon; latch optedOut so no further heartbeats
  are emitted. Re-enable clears the latch (exactly once per flip).
- Wire NotifyConfigChanged into the daemon's REST apply path (runtime.ApplyConfig)
  and disk-reload path (ReloadConfiguration) so web UI + macOS app are covered,
  and into `mcpproxy telemetry disable` so the CLI path is covered (no fsnotify
  watcher means the daemon won't auto-reload the file). Send failure still
  disables; disabled->disabled / env-disabled emit nothing.

Part A — banner deep-link + disclosure:
- TelemetryBanner: add "Manage in Settings" link to /settings?focus=telemetry.enabled
  and a transparency note about the one-time opt-out signal.
- Settings.vue: focusField() resolves a field key to its tab, opens the
  enclosing accordion, scrolls to and highlights the row.
- Disclosure line added near the telemetry toggle (field help + confirm copy).

Docs: document the one-time opt-out signal in docs/features/telemetry.md.

Related #MCP-2482

* fix(telemetry): route opt-out beacon through service endpoint (fix CodeQL SSRF)

CodeQL go/request-forgery (CWE-918) flagged optout.go because the destination
URL flowed as a function parameter directly from the config source to the
http.Do sink. Make SendOptOutBeacon a *Service method that reads the resolved
s.endpoint/s.config — the same struct-field indirection the existing heartbeat
and feedback senders use (which CodeQL does not flag) — so the beacon can never
target an arbitrary caller-supplied URL. The CLI path now constructs a
telemetry.Service and calls the method instead of passing a raw URL.

No behavior change: still exactly one fire-and-forget beacon to /heartbeat on
the enabled->disabled flip.

Related #MCP-2482

* fix(telemetry): validate opt-out beacon URL (scheme/host) to clear CWE-918

Apply the repo's established request-forgery barrier (mirror validateRegistryURL):
parse the configured telemetry endpoint, constrain the scheme to http/https,
require a host, and issue the beacon against the re-serialized URL. Rejects
file://, gopher://, and schemeless/malformed endpoints before any request.

Related #MCP-2482

* fix(telemetry): pin opt-out beacon host to clear CWE-918 (host allowlist guard)

Scheme/host-presence validation alone did not satisfy CodeQL go/request-forgery;
the established repo barrier (validateRegistryURL) is a host equality guard. Pin
the beacon destination to the built-in telemetry host or a loopback address
(tests/local dev) and reject anything else before issuing the request. This both
clears the alert and genuinely hardens the path — the anonymous ID can only ever
reach the official endpoint or localhost, never an arbitrary host from a
malformed/hostile telemetry.endpoint value (documented as a testing override).

Related #MCP-2482

* fix(telemetry): inline opt-out beacon host guard (CWE-918 barrier shape)

Move the host allowlist check inline into validateTelemetryURL as an
'if !match { return err }' equality guard on the same control-flow path as the
request sink, mirroring validateRegistryURL (the repo's CodeQL-accepted
request-forgery barrier). The prior bool-returning helper put the guard across a
function boundary that CodeQL's barrier-guard analysis did not propagate.

Related #MCP-2482

* fix(telemetry): explicit-equality host guard for opt-out beacon (CWE-918)

Earlier barrier shapes (helper returning bool; EqualFold + net.ParseIP/IsLoopback)
did not satisfy CodeQL go/request-forgery. Switch to an inline exact-equality
allowlist (switch on the lower-cased host against the built-in telemetry host and
explicit loopback literals) — the canonical barrier shape the scanner recognizes,
on the same control-flow path as the request. Behaviour unchanged: prod host and
loopback (tests/local) allowed, everything else rejected.

Related #MCP-2482

* fix(telemetry): address Codex review — env-resolved gate, opt-out race, CLI guards (MCP-2482)

Codex REQUEST_CHANGES on PR #684:

1. [P1] Respect env-resolved disabled state. The transition gated only on
   Config.IsTelemetryEnabled() (MCPPROXY_TELEMETRY), so DO_NOT_TRACK=1 / CI=true
   could emit a beacon when telemetry was never enabled. Add
   EffectiveTelemetryEnabled() = IsTelemetryEnabled() && !IsDisabledByEnv(), and
   use it for the transition, the New() resolvedEnabled seed, and the CLI.

2. [P1] Heartbeat-after-opt-out race. sendHeartbeat checked optedOut only at
   entry; a heartbeat in flight when the latch flipped still shipped a full usage
   payload. Re-check the latch immediately before transmit so no usage data
   leaves after opt-out.

3. [P2] CLI disable path. Routed through a single guarded entry point
   (Service.EmitOptOutBeacon — applies semver/dev, env, and anon-id guards and
   owns the send) instead of calling SendOptOutBeacon directly (which bypassed
   the guards). The CLI now confirms "Telemetry disabled." before the best-effort
   beacon (non-blocking) with a short 3s timeout.

Tests: env-disabled emits nothing; mid-flight opt-out suppresses transmit;
EmitOptOutBeacon guard matrix (dev/env/no-anon-id skip, eligible sends). CLI
smoke: enabled=1 beacon, DO_NOT_TRACK/CI=0.

Related #MCP-2482

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Dumbris

cmd/mcpproxy/telemetry_cmd.go

@@ -11,6 +11,7 @@ import (
 
 	"github.com/spf13/cobra"
 	"go.etcd.io/bbolt"
+	"go.uber.org/zap"
 
 	clioutput "github.com/smart-mcp-proxy/mcpproxy-go/internal/cli/output"
 	"github.com/smart-mcp-proxy/mcpproxy-go/internal/cliclient"
@@ -267,6 +268,13 @@ func runTelemetryDisable(cmd *cobra.Command, _ []string) error {
 		return fmt.Errorf("failed to load config: %w", err)
 	}
 
+	// Capture the EFFECTIVE resolved state BEFORE mutating, so we only beacon on
+	// a genuine enabled->disabled transition (MCP-2482). Effective resolution
+	// includes env overrides (DO_NOT_TRACK / CI), so an install where telemetry
+	// was never actually enabled emits nothing. A second `disable` when already
+	// disabled also emits nothing (wasEnabled == false).
+	wasEnabled := telemetry.EffectiveTelemetryEnabled(cfg)
+
 	if cfg.Telemetry == nil {
 		cfg.Telemetry = &config.TelemetryConfig{}
 	}
@@ -278,7 +286,23 @@ func runTelemetryDisable(cmd *cobra.Command, _ []string) error {
 		return fmt.Errorf("failed to save config: %w", err)
 	}
 
+	// The disable is now persisted and effective — confirm immediately so the
+	// command never appears to hang on the (best-effort) beacon below.
 	fmt.Println("Telemetry disabled.")
+
+	// One-time opt-out beacon. When a daemon is running it does NOT auto-reload
+	// this file (there is no fsnotify watcher), so the CLI is responsible for the
+	// beacon in the CLI-driven path. Route it through the SAME guarded server-side
+	// entry point (EmitOptOutBeacon applies the dev-build/semver, env, and
+	// anon-id guards and owns the single send) rather than duplicating the send
+	// or bypassing a guard. A short timeout keeps this from blocking on a slow
+	// endpoint; the CLI is short-lived so the send must complete before exit.
+	if wasEnabled {
+		ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+		defer cancel()
+		beaconSvc := telemetry.New(cfg, "", version, Edition, zap.NewNop())
+		beaconSvc.EmitOptOutBeacon(ctx)
+	}
 	return nil
 }
 

docs/features/telemetry.md

@@ -44,6 +44,19 @@ The anonymous ID is a random UUID (v4) generated on first run. It has **no corre
 
 You can delete it by removing the `telemetry.anonymous_id` field from your config — a new random ID will be generated on next startup.
 
+## One-time opt-out signal
+
+When telemetry transitions from **enabled to disabled** (via the CLI, the config
+file, or the web UI / macOS app), MCPProxy sends **exactly one** final, anonymous
+beacon — an `event: "telemetry_disabled"` carrying **only your anonymous install
+ID** and **no usage data**. It lets us count how many installs opt out so we can
+gauge how the feature is received. The send is best-effort: if it fails,
+telemetry is still disabled. After it, **no further telemetry is emitted**.
+
+Disabling while already disabled (or reloading a config that is already
+disabled) sends nothing. Setting `MCPPROXY_TELEMETRY=false` is treated as
+"never enabled" and also sends nothing.
+
 ## How to disable
 
 There are three ways to disable telemetry:

frontend/src/components/TelemetryBanner.vue

@@ -1,5 +1,5 @@
 <template>
-  <div v-if="visible" class="alert alert-info">
+  <div v-if="visible" class="alert alert-info" data-test="telemetry-banner">
     <svg class="w-6 h-6 shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24">
       <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
     </svg>
@@ -11,17 +11,32 @@
         rel="noopener noreferrer"
         class="link link-hover underline"
       >Learn more</a>
+      <!-- Transparency note (MCP-2482): disclose the one-time opt-out signal. -->
+      <p class="text-xs opacity-80 mt-1" data-test="telemetry-banner-disclosure">
+        Disabling sends a single anonymous opt-out signal, then stops all telemetry.
+      </p>
+    </div>
+    <div class="flex items-center gap-2">
+      <RouterLink
+        to="/settings?focus=telemetry.enabled"
+        class="btn btn-sm btn-ghost"
+        data-test="telemetry-banner-settings-link"
+        @click="dismiss"
+      >
+        Manage in Settings
+      </RouterLink>
+      <button class="btn btn-sm btn-ghost btn-square" @click="dismiss" aria-label="Dismiss" data-test="telemetry-banner-dismiss">
+        <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
+        </svg>
+      </button>
     </div>
-    <button class="btn btn-sm btn-ghost" @click="dismiss" aria-label="Dismiss">
-      <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
-      </svg>
-    </button>
   </div>
 </template>
 
 <script setup lang="ts">
 import { ref, onMounted } from 'vue'
+import { RouterLink } from 'vue-router'
 
 const STORAGE_KEY = 'telemetry-banner-dismissed'
 const visible = ref(false)

frontend/src/views/Settings.vue

@@ -174,8 +174,8 @@
 </template>
 
 <script setup lang="ts">
-import { ref, reactive, computed, watch, onMounted, onUnmounted } from 'vue'
-import { RouterLink } from 'vue-router'
+import { ref, reactive, computed, watch, onMounted, onUnmounted, nextTick } from 'vue'
+import { RouterLink, useRoute } from 'vue-router'
 import { VueMonacoEditor } from '@guolao/vue-monaco-editor'
 import { useServersStore } from '@/stores/servers'
 import { useSystemStore } from '@/stores/system'
@@ -200,6 +200,7 @@ import api from '@/services/api'
 
 const serversStore = useServersStore()
 const systemStore = useSystemStore()
+const route = useRoute()
 
 const securityFields = SECURITY_FIELDS
 const generalFields = GENERAL_FIELDS
@@ -434,6 +435,41 @@ function handleConfigSaved() {
   loadConfig()
 }
 
+// Deep-link support (MCP-2482): the telemetry consent banner links to
+// /settings?focus=telemetry.enabled. Map any field key to the tab that renders
+// it, switch to that tab, open the enclosing accordion if it lives under
+// Advanced, then scroll to and briefly highlight the field row.
+function tabForFieldKey(key: string): string {
+  if (securityFields.some((f) => f.key === key)) return 'security'
+  if (generalFields.some((f) => f.key === key)) return 'general'
+  if (advancedAccordions.value.some((a) => a.fields.some((f) => f.key === key))) return 'advanced'
+  if (serverEditionFields.some((f) => f.key === key)) return 'teams'
+  return activeTab.value
+}
+
+async function focusField(key: string) {
+  // Clear any active search so the tabbed layout (not search results) renders.
+  search.value = ''
+  activeTab.value = tabForFieldKey(key)
+  await nextTick()
+
+  // Advanced settings live inside collapsed <details>; open the one holding it.
+  const acc = advancedAccordions.value.find((a) => a.fields.some((f) => f.key === key))
+  if (acc) {
+    const summary = document.querySelector(`[data-test="settings-accordion-${acc.id}"]`)
+    const det = summary?.closest('details') as HTMLDetailsElement | null
+    if (det) det.open = true
+    await nextTick()
+  }
+
+  const row = document.querySelector(`[data-test="setting-row-${key}"]`) as HTMLElement | null
+  if (!row) return
+  row.scrollIntoView({ behavior: 'smooth', block: 'center' })
+  const highlight = ['ring-2', 'ring-primary', 'ring-offset-2']
+  row.classList.add(...highlight)
+  setTimeout(() => row.classList.remove(...highlight), 2500)
+}
+
 // Fetch the resolved built-in MCP instructions default for the textarea
 // placeholder (MCP-2175). Non-fatal: a failure or an older core just leaves the
 // static catalogue placeholder in place.
@@ -456,10 +492,15 @@ watch(defaultInstructions, () => {
   maybePrefillInstructions()
 })
 
-onMounted(() => {
-  loadConfig()
+onMounted(async () => {
   loadDefaultInstructions()
   window.addEventListener('mcpproxy:config-saved', handleConfigSaved)
+  await loadConfig()
+  const focus = route.query.focus
+  if (typeof focus === 'string' && focus) {
+    await nextTick()
+    await focusField(focus)
+  }
 })
 onUnmounted(() => {
   window.removeEventListener('mcpproxy:config-saved', handleConfigSaved)

frontend/src/views/settings/fields.ts

@@ -251,13 +251,13 @@ export const GENERAL_FIELDS: SettingField[] = [
     key: 'telemetry.enabled',
     docs: '/features/telemetry',
     label: 'Anonymous usage telemetry',
-    help: 'Sends anonymous usage counts (never tool arguments, content, or identities). Opt-out at any time.',
+    help: 'Sends anonymous usage counts (never tool arguments, content, or identities). Opt-out at any time. Disabling sends a single anonymous opt-out signal, then stops all telemetry.',
     control: 'toggle',
     danger: {
       confirmValue: false,
       tone: 'info',
       message:
-        'Anonymous telemetry is how we see which features matter and catch problems — it never includes your tool arguments, content, or any identifying info. Turning it off removes that signal. Turn it off anyway?',
+        'Anonymous telemetry is how we see which features matter and catch problems — it never includes your tool arguments, content, or any identifying info. Turning it off removes that signal, and sends a single anonymous opt-out signal before all telemetry stops. Turn it off anyway?',
     },
   },
   { key: 'enable_prompts', label: 'Expose MCP prompts to clients', help: 'Advertises mcpproxy’s built-in guided prompts to connected AI clients: “setup-new-mcp-server” (add a server) and “troubleshoot-mcp-server” (diagnose connection issues).', control: 'toggle' },

internal/runtime/lifecycle.go

@@ -1029,6 +1029,14 @@ func (r *Runtime) ReloadConfiguration() error {
 		return fmt.Errorf("failed to reload servers: %w", err)
 	}
 
+	// MCP-2482: detect a telemetry enabled->disabled flip across the reload and
+	// fire the one-time opt-out beacon. This covers config changes that arrive
+	// via a disk reload (there is no fsnotify auto-watcher, so this is the
+	// manual/triggered-reload path). nil-safe + fire-and-forget.
+	if r.telemetryService != nil {
+		r.telemetryService.NotifyConfigChanged(newSnapshot.Config)
+	}
+
 	go r.postConfigReload()
 
 	r.logger.Info("Configuration reload completed",

internal/runtime/runtime.go

@@ -1304,6 +1304,14 @@ func (r *Runtime) ApplyConfig(newCfg *config.Config, cfgPath string) (*ConfigApp
 	// Event handlers may need to acquire locks on other resources
 	r.mu.Unlock()
 
+	// MCP-2482: drive the one-time telemetry opt-out beacon on an
+	// enabled->disabled flip. NotifyConfigChanged is fire-and-forget and
+	// nil-safe, so this never blocks the apply path. Covers web UI + macOS app,
+	// which both reach this via the REST /config apply pipeline.
+	if r.telemetryService != nil {
+		r.telemetryService.NotifyConfigChanged(newCfg)
+	}
+
 	// Update configSvc to notify subscribers (like supervisor)
 	// This must happen BEFORE LoadConfiguredServers to ensure supervisor reconciles
 	if err := r.configSvc.Update(&configCopy, configsvc.UpdateTypeModify, "api_apply_config"); err != nil {