feat(net): trusted-proxy depth so real client IPs survive a proxy — #2453

Fixes the defect the operator spotted in #370 immediately after it shipped:
auth.ClientIP ignored X-Forwarded-For whenever RemoteAddr was public, so a
proxy on a public address — a separate host, or a CDN, i.e. anyone running
this publicly, since public means TLS means a proxy — recorded the PROXY for
every session. created_ip and last_ip were then always equal and the
"Address changed" signal could never fire. The feature looked like it worked
and reported nothing.

Replaced with the standard trusted-hop model (Rails, Caddy, Traefik, nginx).
XFF grows left-to-right as each proxy appends the peer it received from, so
for client -> CDN -> own-proxy -> app the app sees [client, CDN] with
RemoteAddr = own-proxy, and the client sits at XFF[len - hops]:

  0  RemoteAddr, XFF ignored — no proxy
  1  the address your own proxy observed
  2  through a CDN in front of your proxy

Default 1, per the operator: publicly reachable means a TLS terminator in
front.

The cost is real and stated rather than hidden. hops >= 1 DECLARES that a
proxy exists; set it with no proxy, or deeper than the actual chain, and the
index reaches attacker-supplied entries, letting a visitor choose which
address their own session shows — defeating exactly the detection #370 is
for. That's inherent to the model, which is why 0 is a first-class value and
the admin card says "count your proxies, don't guess high" instead of just
exposing a number. Both mis-set shapes are pinned by tests so they stay known
consequences rather than surprises.

Migration 0053 + internal/netsettings, cached under an RWMutex. That's not an
optimisation: ClientIP runs in RequireUser for every authenticated request, so
a per-request query would put the database on the critical path of the whole
API. New() always returns a usable service so a boot-time DB hiccup degrades
to the default instead of breaking that path (rule #131), and Hops() is
nil-safe because test routers construct middleware without it.

RequireUser now takes a func() int rather than an int — the value is
operator-editable at runtime while the middleware is built once at boot, and
reading it per request is what makes a save take effect with no restart
(rule #25).

The admin card is verifiable, not just configurable: it reports the address
the CURRENT setting resolves THIS request to, the raw forwarded chain, and the
socket peer — so you set the number, save, and confirm the address matches the
machine you're on. It also counts the arriving chain and says how many proxies
that implies. GET/PUT both return that payload, PUT recomputed under the new
value, so the effect is visible without a reload.

Also fixes styling in the #370 card that CI could not catch: text-destructive
and bg-destructive don't exist in this Tailwind config — the palette is
colors.action.destructive — so the "Address changed" warning and the
sign-out-others button were rendering unstyled. Both now use
text-action-destructive / bg-action-destructive / text-action-fg.

Not done here: requestlog.go still logs raw RemoteAddr and will disagree with
the sessions UI about who connected. Left for its own change.

web/src/lib/api/admin.ts

@@ -644,3 +644,28 @@ export function createDiagnosticDevicesQuery(userId?: string) {
     staleTime: 15_000
   });
 }
+
+// Trusted-proxy depth (#2453) ---------------------------------------------
+
+// detected_client_ip / forwarded_chain / remote_addr describe THIS request
+// under the current setting, so the admin card can be verified rather than
+// reasoned about: change the number, see what address you resolve to.
+export type NetworkSettings = {
+  trusted_proxy_hops: number;
+  max_hops: number;
+  detected_client_ip: string;
+  forwarded_chain: string;
+  remote_addr: string;
+};
+
+export async function getNetworkSettings(): Promise<NetworkSettings> {
+  return api.get<NetworkSettings>('/api/admin/network-settings');
+}
+
+// Returns the payload recomputed under the new value, so the card can show
+// the effect immediately instead of requiring a reload.
+export async function updateNetworkSettings(hops: number): Promise<NetworkSettings> {
+  return api.put<NetworkSettings>('/api/admin/network-settings', {
+    trusted_proxy_hops: hops
+  });
+}

web/src/lib/components/ActiveSessions.svelte

@@ -127,7 +127,7 @@
   </p>
 
   {#if loadError}
-    <p class="text-sm text-destructive">
+    <p class="text-sm text-action-destructive">
       Couldn't load your sessions.
       <button type="button" class="underline hover:no-underline" onclick={load}>Try again</button>
     </p>
@@ -156,7 +156,7 @@
               {/if}
               {#if hasMoved(s)}
                 <span
-                  class="inline-flex items-center gap-1 rounded px-1.5 py-0.5 text-xs text-destructive"
+                  class="inline-flex items-center gap-1 rounded px-1.5 py-0.5 text-xs text-action-destructive"
                 >
                   <TriangleAlert size={12} aria-hidden="true" />
                   Address changed
@@ -195,7 +195,7 @@
           </span>
           <button
             type="button"
-            class="rounded bg-destructive px-3 py-1 text-sm text-white
+            class="rounded bg-action-destructive px-3 py-1 text-sm text-action-fg
                    focus-visible:ring-2 focus-visible:ring-accent disabled:opacity-50"
             disabled={busy}
             onclick={onLogoutOthers}

web/src/lib/components/NetworkSettingsCard.svelte

@@ -0,0 +1,135 @@
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import { Save, TriangleAlert } from 'lucide-svelte';
+  import {
+    getNetworkSettings,
+    updateNetworkSettings,
+    type NetworkSettings
+  } from '$lib/api/admin';
+  import { pushToast } from '$lib/stores/toast.svelte';
+
+  let settings = $state<NetworkSettings | null>(null);
+  let hops = $state(1);
+  let saving = $state(false);
+  let loadError = $state(false);
+
+  const dirty = $derived(!!settings && hops !== settings.trusted_proxy_hops);
+  const chain = $derived(
+    (settings?.forwarded_chain ?? '')
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean)
+  );
+  // The operator can count their proxies from what actually arrived rather
+  // than guessing — one XFF entry per proxy in front of us.
+  const suggested = $derived(chain.length);
+
+  async function load() {
+    try {
+      settings = await getNetworkSettings();
+      hops = settings.trusted_proxy_hops;
+      loadError = false;
+    } catch {
+      loadError = true;
+    }
+  }
+
+  onMount(load);
+
+  async function save() {
+    saving = true;
+    try {
+      settings = await updateNetworkSettings(hops);
+      hops = settings.trusted_proxy_hops;
+      pushToast('Proxy depth saved.');
+    } catch {
+      pushToast("Couldn't save proxy depth.", 'error');
+    } finally {
+      saving = false;
+    }
+  }
+</script>
+
+<section class="space-y-4 rounded-xl border border-border bg-surface p-5">
+  <div>
+    <h3 class="font-display text-lg font-medium text-text-primary">Client IP detection</h3>
+    <p class="mt-1 text-sm text-text-secondary">
+      How many reverse proxies sit in front of Minstrel. This decides which address is
+      recorded for each sign-in on the <span class="whitespace-nowrap">Active sessions</span> card,
+      so getting it right is what makes an unfamiliar login visible.
+    </p>
+  </div>
+
+  {#if loadError}
+    <p class="text-sm text-action-destructive">
+      Couldn't load network settings.
+      <button type="button" class="underline hover:no-underline" onclick={load}>Try again</button>
+    </p>
+  {:else if settings === null}
+    <p class="text-sm text-text-secondary">Loading…</p>
+  {:else}
+    <div class="flex flex-wrap items-end gap-3">
+      <label class="flex flex-col gap-1">
+        <span class="text-sm text-text-secondary">Trusted proxies</span>
+        <input
+          type="number"
+          min="0"
+          max={settings.max_hops}
+          bind:value={hops}
+          class="w-24 rounded border border-border bg-background px-2 py-1
+                 focus-visible:outline focus-visible:outline-2 focus-visible:outline-accent"
+        />
+      </label>
+      <button
+        type="button"
+        class="inline-flex items-center gap-1.5 rounded-md border border-border px-3 py-1.5
+               text-sm hover:bg-surface-hover focus-visible:ring-2 focus-visible:ring-accent
+               disabled:opacity-50"
+        disabled={saving || !dirty}
+        onclick={save}
+      >
+        <Save size={14} aria-hidden="true" />
+        {saving ? 'Saving…' : 'Save'}
+      </button>
+    </div>
+
+    <!-- Verification, not decoration: the number is abstract, but "the address
+         Minstrel currently sees for YOU" is checkable against the machine
+         you're sitting at. -->
+    <dl class="grid gap-x-4 gap-y-1 text-sm sm:grid-cols-[auto_1fr]">
+      <dt class="text-text-secondary">Your address right now</dt>
+      <dd class="font-mono">{settings.detected_client_ip || 'unknown'}</dd>
+      <dt class="text-text-secondary">Direct connection from</dt>
+      <dd class="font-mono">{settings.remote_addr || 'unknown'}</dd>
+      <dt class="text-text-secondary">Forwarded chain</dt>
+      <dd class="font-mono break-all">{settings.forwarded_chain || '(none)'}</dd>
+    </dl>
+
+    {#if suggested > 0 && settings.trusted_proxy_hops !== suggested}
+      <p class="text-sm text-text-secondary">
+        This request arrived with {suggested}
+        {suggested === 1 ? 'forwarded address' : 'forwarded addresses'}, which usually means
+        {suggested}
+        {suggested === 1 ? 'proxy' : 'proxies'} in front of Minstrel.
+      </p>
+    {/if}
+
+    <div class="space-y-2 rounded border border-border bg-background p-3 text-sm">
+      <p class="flex items-start gap-2 text-text-secondary">
+        <TriangleAlert size={14} class="mt-0.5 flex-shrink-0 text-action-destructive" aria-hidden="true" />
+        <span>
+          Count your proxies — don't guess high. This number tells Minstrel how much of the
+          <span class="font-mono">X-Forwarded-For</span> header to believe, and that header is
+          written by whoever connects. Set it higher than your real chain, or above 0 with no
+          proxy at all, and a visitor can choose which address their own session shows — which
+          defeats the point of the sessions list.
+        </span>
+      </p>
+      <ul class="ml-6 list-disc space-y-1 text-text-secondary">
+        <li><strong>0</strong> — no proxy; Minstrel is reached directly.</li>
+        <li><strong>1</strong> — one reverse proxy, e.g. nginx, Caddy or Traefik terminating TLS.</li>
+        <li><strong>2</strong> — a CDN in front of your own proxy, e.g. Cloudflare → nginx.</li>
+      </ul>
+    </div>
+  {/if}
+</section>

web/src/lib/components/NetworkSettingsCard.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, test, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/svelte';
+import NetworkSettingsCard from './NetworkSettingsCard.svelte';
+
+const getNetworkSettings = vi.fn();
+const updateNetworkSettings = vi.fn();
+
+vi.mock('$lib/api/admin', () => ({
+  getNetworkSettings: () => getNetworkSettings(),
+  updateNetworkSettings: (hops: number) => updateNetworkSettings(hops)
+}));
+
+vi.mock('$lib/stores/toast.svelte', () => ({ pushToast: vi.fn() }));
+
+function settings(over: Record<string, unknown> = {}) {
+  return {
+    trusted_proxy_hops: 1,
+    max_hops: 10,
+    detected_client_ip: '198.51.100.7',
+    forwarded_chain: '198.51.100.7',
+    remote_addr: '172.18.0.1:40000',
+    ...over
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('NetworkSettingsCard', () => {
+  // The detected address is the card's verification affordance — the number
+  // is abstract, this is checkable against the machine you're sitting at.
+  test('shows the address the current setting resolves to', async () => {
+    getNetworkSettings.mockResolvedValue(settings());
+    render(NetworkSettingsCard);
+
+    expect(await screen.findByText('198.51.100.7')).toBeTruthy();
+    expect(screen.getByText('172.18.0.1:40000')).toBeTruthy();
+  });
+
+  test('save is inert until the value actually changes', async () => {
+    getNetworkSettings.mockResolvedValue(settings({ trusted_proxy_hops: 1 }));
+    render(NetworkSettingsCard);
+
+    const save = await screen.findByRole('button', { name: /Save/ });
+    expect(save).toBeDisabled();
+
+    const input = screen.getByRole('spinbutton');
+    await fireEvent.input(input, { target: { value: '2' } });
+    await waitFor(() => expect(save).not.toBeDisabled());
+  });
+
+  test('saving sends the new depth and adopts the echoed value', async () => {
+    getNetworkSettings.mockResolvedValue(settings({ trusted_proxy_hops: 1 }));
+    updateNetworkSettings.mockResolvedValue(
+      settings({ trusted_proxy_hops: 2, detected_client_ip: '203.0.113.9' })
+    );
+    render(NetworkSettingsCard);
+
+    const input = await screen.findByRole('spinbutton');
+    await fireEvent.input(input, { target: { value: '2' } });
+    await fireEvent.click(screen.getByRole('button', { name: /Save/ }));
+
+    await waitFor(() => expect(updateNetworkSettings).toHaveBeenCalledWith(2));
+    // The recomputed address proves the change took effect on this request.
+    expect(await screen.findByText('203.0.113.9')).toBeTruthy();
+  });
+
+  // Counting proxies is the operator's job and the hint is how they do it
+  // without guessing.
+  test('hints the likely depth when it disagrees with the arriving chain', async () => {
+    getNetworkSettings.mockResolvedValue(
+      settings({ trusted_proxy_hops: 1, forwarded_chain: '198.51.100.7, 203.0.113.50' })
+    );
+    render(NetworkSettingsCard);
+
+    expect(await screen.findByText(/arrived with 2 forwarded addresses/)).toBeTruthy();
+  });
+
+  test('no hint when the setting already matches the chain length', async () => {
+    getNetworkSettings.mockResolvedValue(
+      settings({ trusted_proxy_hops: 1, forwarded_chain: '198.51.100.7' })
+    );
+    render(NetworkSettingsCard);
+
+    await screen.findByText('198.51.100.7');
+    expect(screen.queryByText(/arrived with/)).toBeNull();
+  });
+
+  test('states the mis-set risk rather than only exposing a number', async () => {
+    getNetworkSettings.mockResolvedValue(settings());
+    render(NetworkSettingsCard);
+
+    expect(await screen.findByText(/Count your proxies/)).toBeTruthy();
+  });
+
+  test('offers a retry when loading fails', async () => {
+    getNetworkSettings.mockRejectedValue(new Error('boom'));
+    render(NetworkSettingsCard);
+
+    const retry = await screen.findByRole('button', { name: 'Try again' });
+    getNetworkSettings.mockResolvedValue(settings());
+    await fireEvent.click(retry);
+    await screen.findByText('198.51.100.7');
+  });
+});

web/src/routes/admin/integrations/+page.svelte

@@ -27,6 +27,7 @@
   import { errCode } from '$lib/api/errors';
   import { pushToast } from '$lib/stores/toast.svelte';
   import Modal from '$lib/components/Modal.svelte';
+  import NetworkSettingsCard from '$lib/components/NetworkSettingsCard.svelte';
   import type { LidarrConfig, LidarrTestResult } from '$lib/api/types';
 
   // Lidarr connection panel. The "saved api key" is masked as "***" on GET —
@@ -820,6 +821,12 @@
       </button>
     </div>
   </section>
+
+  <!-- Client IP detection. Belongs here rather than in user Settings: it
+       describes how Minstrel sits behind other infrastructure, same as every
+       other card on this page, and it's an operator-wide setting rather than
+       a per-user preference. -->
+  <NetworkSettingsCard />
 </div>
 
 <Modal