fix(net): validate hop range before checking availability — #2453

TestSetHops_RejectsOutOfRange caught a real ordering bug in code I wrote in
the same commit: the nil-pool guard sat ahead of the range check, so
SetHops(-1) on a service with no pool returned "network settings unavailable"
instead of ErrHopsOutOfRange.

Range first is correct, and the distinction is user-visible rather than
cosmetic: the argument is invalid regardless of whether the database is
reachable, and admin_network.go maps ErrHopsOutOfRange to 400 while anything
else becomes 500. The old order blamed the server for the caller's input.

Note this is the first failure in this sequence that wasn't a missed call
site — vet and golangci-lint both passed, and a test asserting a specific
sentinel error found it. Worth the extra assertion; `err != nil` would have
passed happily.

README.md

@@ -11,10 +11,22 @@ A self-hosted music server that thinks for you. Smart shuffle, contextual likes,
 - **OpenSubsonic-compatible.** Existing Subsonic clients (DSub, Symfonium, play:Sub, etc.) connect with no special configuration.
 - **Server-side smart shuffle.** Track-similarity vectors, dual-like model (general + contextual), and session memory keep mixes coherent across devices.
 - **ListenBrainz radio.** Session-aware "more like this" pulls from ListenBrainz similarity data, not a static genre tag.
-- **Lidarr integration.** Triggered scans, request-driven album imports, and a quarantine flow when something doesn't fit.
+- **Lidarr integration.** Triggered scans, request-driven album imports, and a quarantine flow when something doesn't fit — against a Lidarr instance *you* run and configure. Optional, and off until you supply a URL and API key.
 - **Built-in web SPA.** Full-feature library, search, queue, playlists, and admin — no separate frontend container to deploy.
 - **Native Android client, shipped with the server.** The signed APK is bundled into every image and attached to each [release](https://git.fabledsword.com/bvandeusen/minstrel/releases) — sideload it once, then the app self-updates straight from your own server (no app store, no separate download to track).
 
+## Scope and responsible use
+
+**Minstrel serves music you already have.** It is a library server: it indexes files on disk you point it at, and streams them to your own clients. It does not source, search for, or acquire content, and it has no opinion about where your files came from.
+
+Concretely, Minstrel ships **no** indexers, **no** trackers, **no** torrent / Usenet / NZB client, and **no** DRM circumvention of any kind. There is nothing to point at a content source because Minstrel has no such subsystem.
+
+The **Lidarr integration is optional and inert until you configure it.** You supply the URL and API key of a Lidarr instance you are already running; Minstrel then calls that instance's API to trigger scans, submit album requests, and reconcile imports. Minstrel neither bundles nor installs Lidarr, and configures no indexers on your behalf — Lidarr ships with none either, and any it uses are ones you added yourself.
+
+**What you put in your library, and what sources you configure in your own Lidarr, are your responsibility.** Copyright law applies to your collection the same way it applies to any other software that plays a file. Please respect it, and respect the terms of any service you connect.
+
+Minstrel is not affiliated with or endorsed by Lidarr, ListenBrainz, MusicBrainz, or Subsonic.
+
 ## Quickstart
 
 ```yaml

android/app/src/main/AndroidManifest.xml

@@ -8,7 +8,16 @@
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
     <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <!-- In-app self-update. REQUEST_INSTALL_PACKAGES lets us hand an APK to the
+         platform installer at all; UPDATE_PACKAGES_WITHOUT_USER_ACTION (API 31+)
+         is what lets that install happen with NO confirm dialog. The platform
+         grants the silent path only when the installer opts in via
+         SessionParams.setRequireUserAction(USER_ACTION_NOT_REQUIRED), the
+         installed app targets API 29+, the installer holds this permission, and
+         the target is the installer itself — all true here, since Minstrel is
+         updating Minstrel. See update/data/SelfUpdateSession.kt. -->
     <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
+    <uses-permission android:name="android.permission.UPDATE_PACKAGES_WITHOUT_USER_ACTION" />
     <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
     <uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
 
@@ -19,9 +28,9 @@
         android:fullBackupContent="@xml/backup_rules"
         android:icon="@mipmap/ic_launcher"
         android:label="@string/app_name"
+        android:networkSecurityConfig="@xml/network_security_config"
         android:supportsRtl="true"
         android:theme="@style/Theme.Minstrel"
-        android:usesCleartextTraffic="true"
         tools:targetApi="34">
 
         <!-- Portrait-locked until a tablet/landscape layout exists.
@@ -48,15 +57,11 @@
             </intent-filter>
         </service>
 
-        <provider
-            android:name="androidx.core.content.FileProvider"
-            android:authorities="${applicationId}.fileprovider"
-            android:exported="false"
-            android:grantUriPermissions="true">
-            <meta-data
-                android:name="android.support.FILE_PROVIDER_PATHS"
-                android:resource="@xml/file_paths" />
-        </provider>
+        <!-- The FileProvider that used to live here existed solely to expose the
+             downloaded update APK as a content:// URI for the old ACTION_VIEW
+             install intent. A PackageInstaller session takes a stream instead,
+             so both the provider and res/xml/file_paths.xml are gone — nothing
+             else in the app ever used that authority. -->
 
         <!-- On-demand WorkManager initialization: MinstrelApplication
              implements Configuration.Provider and supplies the

android/app/src/main/java/com/fabledsword/minstrel/player/ui/QueueRow.kt

@@ -0,0 +1,348 @@
+package com.fabledsword.minstrel.player.ui
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.gestures.detectDragGesturesAfterLongPress
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.Icon
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.SwipeToDismissBox
+import androidx.compose.material3.SwipeToDismissBoxValue
+import androidx.compose.material3.Text
+import androidx.compose.material3.rememberSwipeToDismissBoxState
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableFloatStateOf
+import androidx.compose.runtime.mutableIntStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.composed
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.graphicsLayer
+import androidx.compose.ui.input.pointer.pointerInput
+import androidx.compose.ui.layout.onSizeChanged
+import androidx.compose.ui.semantics.CustomAccessibilityAction
+import androidx.compose.ui.semantics.customActions
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.zIndex
+import com.composables.icons.lucide.Lucide
+import com.composables.icons.lucide.Music
+import com.composables.icons.lucide.Trash2
+import com.composables.icons.lucide.Volume2
+import com.fabledsword.minstrel.models.TrackRef
+import com.fabledsword.minstrel.shared.formatDuration
+import com.fabledsword.minstrel.shared.widgets.LikeButton
+import com.fabledsword.minstrel.shared.widgets.ServerImage
+import com.fabledsword.minstrel.theme.LocalActionColors
+import kotlin.math.roundToInt
+
+/*
+ * A single queue row, split out of QueueScreen.kt when swipe-to-remove (#2435)
+ * pushed that file past detekt's TooManyFunctions limit. The seam is real and
+ * not just a way to satisfy the analyzer: the row now carries two gestures, a
+ * swipe background, and its own accessibility surface, which is more behaviour
+ * than the screen that lists it. `internal` rather than `private` only because
+ * QueueList (still in QueueScreen.kt) is the caller.
+ */
+
+@Suppress("LongParameterList") // Compose row wiring — layout + queue callbacks, not logic.
+@Composable
+internal fun QueueRow(
+    track: TrackRef,
+    index: Int,
+    queueSize: Int,
+    isCurrent: Boolean,
+    liked: Boolean,
+    onClick: () -> Unit,
+    onToggleLike: () -> Unit,
+    onRemove: () -> Unit,
+    onMove: (Int, Int) -> Unit,
+) {
+    var dragOffsetY by remember { mutableFloatStateOf(0f) }
+    var rowHeightPx by remember { mutableIntStateOf(0) }
+    val highlight = if (isCurrent) {
+        MaterialTheme.colorScheme.primary.copy(alpha = HIGHLIGHT_ALPHA)
+    } else {
+        Color.Transparent
+    }
+    // Swipe left to remove, replacing the X button (#2395 follow-up). Only
+    // end-to-start is enabled: a right-swipe has no meaning here, and leaving it
+    // live would delete tracks on a mis-aimed gesture in either direction.
+    val dismissState = rememberSwipeToDismissBoxState(
+        confirmValueChange = { value ->
+            if (value == SwipeToDismissBoxValue.EndToStart) {
+                onRemove()
+                true
+            } else {
+                false
+            }
+        },
+    )
+    SwipeToDismissBox(
+        state = dismissState,
+        enableDismissFromStartToEnd = false,
+        backgroundContent = { RemoveSwipeBackground() },
+        // The reorder lift lives out here so a row being dragged vertically
+        // carries its swipe container with it rather than sliding out of one.
+        modifier = Modifier
+            .onSizeChanged { rowHeightPx = it.height }
+            .zIndex(if (dragOffsetY != 0f) 1f else 0f)
+            .graphicsLayer { translationY = dragOffsetY },
+    ) {
+        QueueRowContent(
+            track = track,
+            index = index,
+            queueSize = queueSize,
+            isCurrent = isCurrent,
+            liked = liked,
+            highlight = highlight,
+            rowHeightPx = rowHeightPx,
+            onClick = onClick,
+            onToggleLike = onToggleLike,
+            onRemove = onRemove,
+            onMove = onMove,
+            onDragOffset = { dragOffsetY = it },
+        )
+    }
+}
+
+@Suppress("LongParameterList") // Compose row wiring — layout + queue callbacks, not logic.
+@Composable
+private fun QueueRowContent(
+    track: TrackRef,
+    index: Int,
+    queueSize: Int,
+    isCurrent: Boolean,
+    liked: Boolean,
+    highlight: Color,
+    rowHeightPx: Int,
+    onClick: () -> Unit,
+    onToggleLike: () -> Unit,
+    onRemove: () -> Unit,
+    onMove: (Int, Int) -> Unit,
+    onDragOffset: (Float) -> Unit,
+) {
+    Row(
+        modifier = Modifier
+            .fillMaxWidth()
+            // Opaque: this sits ON TOP of the red remove background, so a
+            // transparent row would show the fill through it at rest.
+            .background(MaterialTheme.colorScheme.surface)
+            .background(highlight)
+            .clickable(onClick = onClick)
+            .queueReorderActions(
+                index = index,
+                queueSize = queueSize,
+                onMove = onMove,
+                onRemove = onRemove,
+            )
+            .padding(horizontal = 16.dp, vertical = 12.dp),
+        verticalAlignment = Alignment.CenterVertically,
+        horizontalArrangement = Arrangement.spacedBy(12.dp),
+    ) {
+        // The album art IS the grab surface (#2395). The grip icon it replaces
+        // cost ~36dp of every row's width — icon plus its 12dp gap — on the
+        // narrowest surface in the app, competing with the title for space.
+        QueueRowThumbnail(
+            track = track,
+            dragModifier = Modifier.queueReorderDrag(
+                index = index,
+                queueSize = queueSize,
+                rowHeightPx = rowHeightPx,
+                onOffsetChange = onDragOffset,
+                onMove = onMove,
+            ),
+        )
+        if (isCurrent) {
+            Icon(
+                Lucide.Volume2,
+                contentDescription = "Now playing",
+                tint = MaterialTheme.colorScheme.primary,
+            )
+        }
+        QueueRowText(track = track, isCurrent = isCurrent, modifier = Modifier.weight(1f))
+        if (track.durationSec > 0) {
+            Text(
+                text = formatDuration(track.durationSec),
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+        }
+        LikeButton(liked = liked, onToggle = onToggleLike)
+    }
+}
+
+/**
+ * What the row slides off to reveal: the destructive colour with a trash glyph,
+ * pinned to the trailing edge because that is the edge the swipe uncovers.
+ *
+ * Oxblood (LocalActionColors.destructive), NOT colorScheme.error. The design
+ * system keeps those apart deliberately — an error is a failure that already
+ * happened, a destructive action is one about to happen — and using the error
+ * colour here would dress an intentional gesture as a fault report.
+ */
+@Composable
+private fun RemoveSwipeBackground() {
+    val actions = LocalActionColors.current
+    Box(
+        modifier = Modifier
+            .fillMaxSize()
+            .background(actions.destructive)
+            .padding(horizontal = 24.dp),
+        contentAlignment = Alignment.CenterEnd,
+    ) {
+        Row(
+            verticalAlignment = Alignment.CenterVertically,
+            horizontalArrangement = Arrangement.spacedBy(8.dp),
+        ) {
+            Icon(Lucide.Trash2, contentDescription = null, tint = actions.onAction)
+            Text(
+                text = "Remove",
+                style = MaterialTheme.typography.labelLarge,
+                color = actions.onAction,
+            )
+        }
+    }
+}
+
+/**
+ * Screen-reader reordering and removal for a queue row.
+ *
+ * Both gestures this row now relies on — long-press-drag to reorder, swipe to
+ * remove — are touch-only and unavailable under TalkBack, and each replaced a
+ * control that a screen reader COULD find (the grip's "Reorder track", the X's
+ * "Remove from queue"). Without these actions the row would have lost both
+ * capabilities for anyone not using touch. They're the Android counterpart to
+ * the web row's ArrowUp/ArrowDown keys and its still-present X button.
+ */
+private fun Modifier.queueReorderActions(
+    index: Int,
+    queueSize: Int,
+    onMove: (Int, Int) -> Unit,
+    onRemove: () -> Unit,
+): Modifier = semantics {
+    customActions = listOf(
+        CustomAccessibilityAction("Move up") {
+            if (index > 0) { onMove(index, index - 1); true } else false
+        },
+        CustomAccessibilityAction("Move down") {
+            if (index < queueSize - 1) { onMove(index, index + 1); true } else false
+        },
+        CustomAccessibilityAction("Remove from queue") { onRemove(); true },
+    )
+}
+
+/**
+ * Reorder-drag behaviour for a queue row, applied to whatever element is the
+ * grab surface — the album art, since #2395 removed the grip icon.
+ *
+ * Uses **detectDragGesturesAfterLongPress**, not detectDragGestures, and that
+ * is the load-bearing detail. The grip was a small target, so a plain drag
+ * gesture on it never competed with anything. A 48dp thumbnail is a large
+ * chunk of every row, and with a plain drag detector any vertical pan starting
+ * on artwork would be swallowed as a row-reorder instead of scrolling the
+ * queue — the list would feel broken precisely where it's easiest to touch.
+ * Long-press-then-drag separates the two: pan scrolls, long-press reorders,
+ * tap still plays (the detector doesn't consume a plain tap, so it falls
+ * through to the row's clickable).
+ */
+private fun Modifier.queueReorderDrag(
+    index: Int,
+    queueSize: Int,
+    rowHeightPx: Int,
+    onOffsetChange: (Float) -> Unit,
+    onMove: (Int, Int) -> Unit,
+): Modifier = composed {
+    // Mirrors the web queue: the row follows the finger during a drag, then on
+    // release we translate the accumulated offset into a row delta and reorder.
+    var offset by remember { mutableFloatStateOf(0f) }
+    pointerInput(index, queueSize, rowHeightPx) {
+        detectDragGesturesAfterLongPress(
+            onDrag = { change, dragAmount ->
+                change.consume()
+                offset += dragAmount.y
+                onOffsetChange(offset)
+            },
+            onDragEnd = {
+                val delta = if (rowHeightPx > 0) (offset / rowHeightPx).roundToInt() else 0
+                val target = (index + delta).coerceIn(0, queueSize - 1)
+                if (target != index) onMove(index, target)
+                offset = 0f
+                onOffsetChange(0f)
+            },
+            onDragCancel = {
+                offset = 0f
+                onOffsetChange(0f)
+            },
+        )
+    }
+}
+
+@Composable
+private fun QueueRowThumbnail(track: TrackRef, dragModifier: Modifier = Modifier) {
+    Box(
+        modifier = Modifier
+            .size(48.dp)
+            .clip(RoundedCornerShape(4.dp))
+            .background(MaterialTheme.colorScheme.surfaceVariant)
+            .then(dragModifier),
+        contentAlignment = Alignment.Center,
+    ) {
+        ServerImage(
+            url = track.coverUrl,
+            contentDescription = null,
+            modifier = Modifier.size(48.dp),
+        ) {
+            Icon(
+                Lucide.Music,
+                contentDescription = null,
+                tint = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+        }
+    }
+}
+
+@Composable
+private fun QueueRowText(track: TrackRef, isCurrent: Boolean, modifier: Modifier = Modifier) {
+    Column(modifier = modifier) {
+        Text(
+            text = track.title,
+            style = MaterialTheme.typography.bodyLarge,
+            color = MaterialTheme.colorScheme.onSurface,
+            fontWeight = if (isCurrent) FontWeight.Medium else FontWeight.Normal,
+            maxLines = 1,
+            overflow = TextOverflow.Ellipsis,
+        )
+        val subtitle = queueSubtitle(track)
+        if (subtitle.isNotEmpty()) {
+            Text(
+                text = subtitle,
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                maxLines = 1,
+                overflow = TextOverflow.Ellipsis,
+            )
+        }
+    }
+}
+
+/** "Artist · Album" — collapses gracefully when either is missing. */
+private fun queueSubtitle(track: TrackRef): String = listOf(track.artistName, track.albumTitle)
+    .filter { it.isNotEmpty() }
+    .joinToString(" · ")
+
+private const val HIGHLIGHT_ALPHA = 0.12f

android/app/src/main/java/com/fabledsword/minstrel/player/ui/QueueScreen.kt

@@ -1,23 +1,16 @@
 package com.fabledsword.minstrel.player.ui
 
 import androidx.compose.animation.AnimatedVisibility
-import androidx.compose.foundation.background
-import androidx.compose.foundation.clickable
-import androidx.compose.foundation.gestures.detectDragGestures
-import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.Column
-import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.Spacer
 import androidx.compose.foundation.layout.fillMaxSize
-import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.size
 import androidx.compose.foundation.layout.width
 import androidx.compose.foundation.lazy.LazyColumn
 import androidx.compose.foundation.lazy.itemsIndexed
 import androidx.compose.foundation.lazy.rememberLazyListState
-import androidx.compose.foundation.shape.RoundedCornerShape
 import androidx.compose.material3.ExperimentalMaterial3Api
 import androidx.compose.material3.FilledTonalButton
 import androidx.compose.material3.HorizontalDivider
@@ -31,39 +24,20 @@ import androidx.compose.runtime.Composable
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.derivedStateOf
 import androidx.compose.runtime.getValue
-import androidx.compose.runtime.mutableFloatStateOf
-import androidx.compose.runtime.mutableIntStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.rememberCoroutineScope
-import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
-import androidx.compose.ui.draw.clip
-import androidx.compose.ui.graphics.Color
-import androidx.compose.ui.graphics.graphicsLayer
-import androidx.compose.ui.input.pointer.pointerInput
-import androidx.compose.ui.layout.onSizeChanged
-import androidx.compose.ui.text.font.FontWeight
-import androidx.compose.ui.text.style.TextOverflow
 import androidx.compose.ui.unit.dp
-import androidx.compose.ui.zIndex
 import androidx.hilt.navigation.compose.hiltViewModel
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import androidx.navigation.NavHostController
 import com.composables.icons.lucide.ArrowDown
 import com.composables.icons.lucide.ArrowLeft
-import com.composables.icons.lucide.GripVertical
 import com.composables.icons.lucide.Lucide
-import com.composables.icons.lucide.Music
 import com.composables.icons.lucide.Trash2
-import com.composables.icons.lucide.Volume2
-import com.composables.icons.lucide.X
 import com.fabledsword.minstrel.models.TrackRef
-import com.fabledsword.minstrel.shared.formatDuration
 import com.fabledsword.minstrel.shared.widgets.EmptyState
-import com.fabledsword.minstrel.shared.widgets.LikeButton
-import com.fabledsword.minstrel.shared.widgets.ServerImage
-import kotlin.math.roundToInt
 import kotlinx.coroutines.launch
 
 @OptIn(ExperimentalMaterial3Api::class)
@@ -203,157 +177,6 @@ private fun JumpToCurrentPill(
     }
 }
 
-@Suppress("LongParameterList") // Compose row wiring — layout + queue callbacks, not logic.
-@Composable
-private fun QueueRow(
-    track: TrackRef,
-    index: Int,
-    queueSize: Int,
-    isCurrent: Boolean,
-    liked: Boolean,
-    onClick: () -> Unit,
-    onToggleLike: () -> Unit,
-    onRemove: () -> Unit,
-    onMove: (Int, Int) -> Unit,
-) {
-    var dragOffsetY by remember { mutableFloatStateOf(0f) }
-    var rowHeightPx by remember { mutableIntStateOf(0) }
-    val highlight = if (isCurrent) {
-        MaterialTheme.colorScheme.primary.copy(alpha = HIGHLIGHT_ALPHA)
-    } else {
-        Color.Transparent
-    }
-    Row(
-        modifier = Modifier
-            .fillMaxWidth()
-            .onSizeChanged { rowHeightPx = it.height }
-            .zIndex(if (dragOffsetY != 0f) 1f else 0f)
-            .graphicsLayer { translationY = dragOffsetY }
-            .background(highlight)
-            .clickable(onClick = onClick)
-            .padding(horizontal = 16.dp, vertical = 12.dp),
-        verticalAlignment = Alignment.CenterVertically,
-        horizontalArrangement = Arrangement.spacedBy(12.dp),
-    ) {
-        DragHandle(
-            index = index,
-            queueSize = queueSize,
-            rowHeightPx = rowHeightPx,
-            onOffsetChange = { dragOffsetY = it },
-            onMove = onMove,
-        )
-        QueueRowThumbnail(track = track)
-        if (isCurrent) {
-            Icon(
-                Lucide.Volume2,
-                contentDescription = "Now playing",
-                tint = MaterialTheme.colorScheme.primary,
-            )
-        }
-        QueueRowText(track = track, isCurrent = isCurrent, modifier = Modifier.weight(1f))
-        if (track.durationSec > 0) {
-            Text(
-                text = formatDuration(track.durationSec),
-                style = MaterialTheme.typography.bodySmall,
-                color = MaterialTheme.colorScheme.onSurfaceVariant,
-            )
-        }
-        LikeButton(liked = liked, onToggle = onToggleLike)
-        IconButton(onClick = onRemove) {
-            Icon(Lucide.X, contentDescription = "Remove from queue")
-        }
-    }
-}
-
-@Composable
-private fun DragHandle(
-    index: Int,
-    queueSize: Int,
-    rowHeightPx: Int,
-    onOffsetChange: (Float) -> Unit,
-    onMove: (Int, Int) -> Unit,
-) {
-    // Mirrors the web queue: the row follows the finger during a drag, then on
-    // release we translate the accumulated offset into a row delta and reorder.
-    var offset by remember { mutableFloatStateOf(0f) }
-    Icon(
-        Lucide.GripVertical,
-        contentDescription = "Reorder track",
-        tint = MaterialTheme.colorScheme.onSurfaceVariant,
-        modifier = Modifier.pointerInput(index, queueSize, rowHeightPx) {
-            detectDragGestures(
-                onDrag = { change, dragAmount ->
-                    change.consume()
-                    offset += dragAmount.y
-                    onOffsetChange(offset)
-                },
-                onDragEnd = {
-                    val delta = if (rowHeightPx > 0) (offset / rowHeightPx).roundToInt() else 0
-                    val target = (index + delta).coerceIn(0, queueSize - 1)
-                    if (target != index) onMove(index, target)
-                    offset = 0f
-                    onOffsetChange(0f)
-                },
-                onDragCancel = {
-                    offset = 0f
-                    onOffsetChange(0f)
-                },
-            )
-        },
-    )
-}
-
-@Composable
-private fun QueueRowThumbnail(track: TrackRef) {
-    Box(
-        modifier = Modifier
-            .size(48.dp)
-            .clip(RoundedCornerShape(4.dp))
-            .background(MaterialTheme.colorScheme.surfaceVariant),
-        contentAlignment = Alignment.Center,
-    ) {
-        ServerImage(
-            url = track.coverUrl,
-            contentDescription = null,
-            modifier = Modifier.size(48.dp),
-        ) {
-            Icon(
-                Lucide.Music,
-                contentDescription = null,
-                tint = MaterialTheme.colorScheme.onSurfaceVariant,
-            )
-        }
-    }
-}
-
-@Composable
-private fun QueueRowText(track: TrackRef, isCurrent: Boolean, modifier: Modifier = Modifier) {
-    Column(modifier = modifier) {
-        Text(
-            text = track.title,
-            style = MaterialTheme.typography.bodyLarge,
-            color = MaterialTheme.colorScheme.onSurface,
-            fontWeight = if (isCurrent) FontWeight.Medium else FontWeight.Normal,
-            maxLines = 1,
-            overflow = TextOverflow.Ellipsis,
-        )
-        val subtitle = queueSubtitle(track)
-        if (subtitle.isNotEmpty()) {
-            Text(
-                text = subtitle,
-                style = MaterialTheme.typography.bodySmall,
-                color = MaterialTheme.colorScheme.onSurfaceVariant,
-                maxLines = 1,
-                overflow = TextOverflow.Ellipsis,
-            )
-        }
-    }
-}
-
-/** "Artist · Album" — collapses gracefully when either is missing. */
-private fun queueSubtitle(track: TrackRef): String = listOf(track.artistName, track.albumTitle)
-    .filter { it.isNotEmpty() }
-    .joinToString(" · ")
 
 /** "N tracks · 12 min" header summary. */
 private fun queueSummary(tracks: List<TrackRef>): String {
@@ -367,6 +190,5 @@ private fun queueSummary(tracks: List<TrackRef>): String {
     return "${tracks.size} $noun · $length"
 }
 
-private const val HIGHLIGHT_ALPHA = 0.12f
 private const val SECONDS_PER_MINUTE = 60
 private const val MINUTES_PER_HOUR = 60

android/app/src/main/java/com/fabledsword/minstrel/settings/ui/AboutCardViewModel.kt

@@ -6,22 +6,27 @@ import com.fabledsword.minstrel.BuildConfig
 import com.fabledsword.minstrel.api.ErrorCopy
 import com.fabledsword.minstrel.models.UpdateInfo
 import com.fabledsword.minstrel.update.data.ApkInstaller
+import com.fabledsword.minstrel.update.data.InstallStage
 import com.fabledsword.minstrel.update.data.UpdateRepository
+import com.fabledsword.minstrel.update.data.isBusy
 import com.fabledsword.minstrel.update.data.isVersionNewer
+import com.fabledsword.minstrel.update.data.message
+import com.fabledsword.minstrel.update.data.stage
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.flow.update
 import kotlinx.coroutines.launch
+import java.io.File
 import javax.inject.Inject
 
 /**
  * One of three terminal states the Check-for-updates button surfaces.
  * `Idle` is the pre-check state; `Latest` means the installed build
  * matches or exceeds the server's bundled APK; `UpdateAvailable`
- * surfaces an "Install vX.Y.Z" button that downloads + launches the
- * system installer via [ApkInstaller].
+ * surfaces an "Install vX.Y.Z" button that downloads the APK and
+ * installs it via [ApkInstaller].
  */
 sealed interface UpdateCheckResult {
     data object Idle : UpdateCheckResult
@@ -33,7 +38,7 @@ sealed interface UpdateCheckResult {
 data class AboutUiState(
     val installedVersion: String = BuildConfig.VERSION_NAME,
     val isChecking: Boolean = false,
-    val isInstalling: Boolean = false,
+    val installStage: InstallStage = InstallStage.IDLE,
     val installMessage: String? = null,
     val result: UpdateCheckResult = UpdateCheckResult.Idle,
 )
@@ -43,9 +48,9 @@ data class AboutUiState(
  * [UpdateRepository.getLatest], compares versus the build's
  * VERSION_NAME via [isVersionNewer], and reports the terminal state.
  * When an update is available, [install] downloads the APK via
- * [ApkInstaller] and hands it to the system installer — routing the
- * user to the "install unknown apps" settings page first when that
- * permission hasn't been granted.
+ * [ApkInstaller] and installs it — routing the user to the "install
+ * unknown apps" settings page first when that permission hasn't been
+ * granted.
  */
 @HiltViewModel
 class AboutCardViewModel @Inject constructor(
@@ -75,7 +80,7 @@ class AboutCardViewModel @Inject constructor(
     }
 
     fun install(info: UpdateInfo) {
-        if (internal.value.isInstalling) return
+        if (internal.value.installStage.isBusy()) return
         if (!installer.canInstall()) {
             installer.requestInstallPermission()
             internal.update {
@@ -84,21 +89,32 @@ class AboutCardViewModel @Inject constructor(
             return
         }
         viewModelScope.launch {
-            internal.update { it.copy(isInstalling = true, installMessage = null) }
-            runCatching { installer.downloadApk(info.apkUrl) }
-                .onSuccess { apk ->
-                    installer.launchInstall(apk)
-                    internal.update { it.copy(isInstalling = false) }
-                }
-                .onFailure { e ->
-                    val why = ErrorCopy.fromThrowable(e)
-                    internal.update {
-                        it.copy(
-                            isInstalling = false,
-                            installMessage = "Couldn't download update: $why",
-                        )
-                    }
+            internal.update {
+                it.copy(installStage = InstallStage.DOWNLOADING, installMessage = null)
+            }
+            val apk = download(info.apkUrl)
+            if (apk != null) {
+                // The install half now suspends on the platform's verdict, so it
+                // gets its own stage — reporting "Downloading…" through it would
+                // be a lie once a confirm dialog is on screen.
+                internal.update { it.copy(installStage = InstallStage.INSTALLING) }
+                val outcome = installer.install(apk)
+                internal.update {
+                    it.copy(installStage = outcome.stage(), installMessage = outcome.message())
                 }
+            }
         }
     }
+
+    private suspend fun download(apkUrl: String): File? =
+        runCatching { installer.downloadApk(apkUrl) }
+            .onFailure { e ->
+                internal.update {
+                    it.copy(
+                        installStage = InstallStage.ERROR,
+                        installMessage = "Couldn't download update: ${ErrorCopy.fromThrowable(e)}",
+                    )
+                }
+            }
+            .getOrNull()
 }

android/app/src/main/java/com/fabledsword/minstrel/settings/ui/SettingsScreen.kt

@@ -58,6 +58,8 @@ import com.fabledsword.minstrel.nav.ServerUrl
 import com.fabledsword.minstrel.shared.widgets.MinstrelTopAppBar
 import com.fabledsword.minstrel.theme.ThemeMode
 import com.fabledsword.minstrel.theme.ThemePreferenceViewModel
+import com.fabledsword.minstrel.update.data.InstallStage
+import com.fabledsword.minstrel.update.data.isBusy
 
 @Composable
 fun SettingsScreen(
@@ -381,7 +383,7 @@ private fun UpdateControls(state: AboutUiState, viewModel: AboutCardViewModel) {
     UpdateCheckLine(result = state.result)
     Button(
         onClick = viewModel::checkForUpdates,
-        enabled = !state.isChecking && !state.isInstalling,
+        enabled = !state.isChecking && !state.installStage.isBusy(),
         modifier = Modifier.fillMaxWidth(),
     ) {
         if (state.isChecking) {
@@ -393,7 +395,7 @@ private fun UpdateControls(state: AboutUiState, viewModel: AboutCardViewModel) {
     if (available != null) {
         InstallButton(
             version = available.info.version,
-            isInstalling = state.isInstalling,
+            stage = state.installStage,
             onClick = { viewModel.install(available.info) },
         )
     }
@@ -407,16 +409,22 @@ private fun UpdateControls(state: AboutUiState, viewModel: AboutCardViewModel) {
 }
 
 @Composable
-private fun InstallButton(version: String, isInstalling: Boolean, onClick: () -> Unit) {
+private fun InstallButton(version: String, stage: InstallStage, onClick: () -> Unit) {
     Button(
         onClick = onClick,
-        enabled = !isInstalling,
+        enabled = !stage.isBusy(),
         modifier = Modifier.fillMaxWidth(),
     ) {
-        if (isInstalling) {
+        if (stage.isBusy()) {
             ButtonSpinner()
         }
-        Text(if (isInstalling) "Downloading…" else "Install $version")
+        Text(
+            when (stage) {
+                InstallStage.DOWNLOADING -> "Downloading…"
+                InstallStage.INSTALLING -> "Installing…"
+                else -> "Install $version"
+            },
+        )
     }
 }
 

android/app/src/main/java/com/fabledsword/minstrel/update/data/ApkInstaller.kt

@@ -5,7 +5,6 @@ import android.content.Intent
 import android.net.Uri
 import android.os.Build
 import android.provider.Settings
-import androidx.core.content.FileProvider
 import dagger.hilt.android.qualifiers.ApplicationContext
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
@@ -17,27 +16,26 @@ import javax.inject.Inject
 import javax.inject.Singleton
 
 private const val APK_FILENAME = "minstrel-update.apk"
-private const val APK_MIME = "application/vnd.android.package-archive"
 
 /**
- * Downloads the server-bundled APK and hands it to Android's package
- * installer. Mirrors Flutter's `update/installer.dart` — the native
- * side that the Flutter MethodChannel delegated to.
+ * Downloads the server-bundled APK and installs it over ourselves.
  *
  * The download goes through the shared [OkHttpClient] so it inherits
  * the auth cookie + the BaseUrlInterceptor host rewrite (apkUrl is
  * server-relative, e.g. `/api/client/apk`). The APK lands in the
- * cache dir, exposed to the system installer via the app's
- * FileProvider content:// URI.
+ * cache dir; [SelfUpdateSession] streams it from there into a
+ * [android.content.pm.PackageInstaller] session.
  *
  * On Android O+ the user must have granted "install unknown apps"
  * for Minstrel; [canInstall] reports it and [requestInstallPermission]
- * opens the relevant settings screen.
+ * opens the relevant settings screen. That grant is still required with
+ * the session API — silent *updates* don't imply silent *permission*.
  */
 @Singleton
 class ApkInstaller @Inject constructor(
     @ApplicationContext private val context: Context,
     private val okHttpClient: OkHttpClient,
+    private val session: SelfUpdateSession,
 ) {
     suspend fun downloadApk(apkUrl: String): File = withContext(Dispatchers.IO) {
         val request = Request.Builder()
@@ -61,19 +59,13 @@ class ApkInstaller @Inject constructor(
         Build.VERSION.SDK_INT < Build.VERSION_CODES.O ||
             context.packageManager.canRequestPackageInstalls()
 
-    /** Hand the downloaded APK to the system installer's confirm dialog. */
-    fun launchInstall(apk: File) {
-        val uri: Uri = FileProvider.getUriForFile(
-            context,
-            "${context.packageName}.fileprovider",
-            apk,
-        )
-        val intent = Intent(Intent.ACTION_VIEW).apply {
-            setDataAndType(uri, APK_MIME)
-            addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION or Intent.FLAG_ACTIVITY_NEW_TASK)
-        }
-        context.startActivity(intent)
-    }
+    /**
+     * Install [apk] over ourselves, suspending until the platform decides.
+     *
+     * Note for callers: on a successful silent install this never returns —
+     * the process is replaced. Don't treat the absence of a verdict as failure.
+     */
+    suspend fun install(apk: File): InstallOutcome = session.run(apk)
 
     /** Open the "install unknown apps" settings page for Minstrel. */
     fun requestInstallPermission() {

android/app/src/main/java/com/fabledsword/minstrel/update/data/InstallOutcome.kt

@@ -0,0 +1,68 @@
+package com.fabledsword.minstrel.update.data
+
+/**
+ * Terminal verdict from the platform on a self-update install (#2438).
+ *
+ * The old `ACTION_VIEW` handoff had no verdict at all — we fired an intent and
+ * assumed. A [PackageInstaller][android.content.pm.PackageInstaller] session
+ * reports back, so "declined" and "failed" stop looking identical.
+ */
+sealed interface InstallOutcome {
+    /**
+     * The platform completed the install.
+     *
+     * Rarely observed on a self-update: our process is replaced the moment the
+     * new APK lands, so the coroutine awaiting this usually dies before it
+     * resumes. Modelled anyway — silently relying on being killed would make
+     * the success path invisible to anyone reading this.
+     */
+    data object Installed : InstallOutcome
+
+    /** The user declined the platform's confirm dialog. Not an error. */
+    data object Cancelled : InstallOutcome
+
+    /** The platform refused. [reason] is its own message, where it gave one. */
+    data class Failed(val reason: String?) : InstallOutcome
+}
+
+/**
+ * Where an install has got to, for the two surfaces that show it: the shell's
+ * [UpdateBanner][com.fabledsword.minstrel.update.ui.UpdateBanner] and the
+ * Settings About card.
+ *
+ * DOWNLOADING and INSTALLING are deliberately distinct. They used to be one
+ * state because the install half was fire-and-forget and took no time from our
+ * side; now that we await the platform's verdict, collapsing them would leave
+ * the UI claiming "Downloading…" through an install that can sit on a confirm
+ * dialog indefinitely.
+ */
+enum class InstallStage { IDLE, DOWNLOADING, INSTALLING, ERROR }
+
+/** True while an install is underway and a second tap should do nothing. */
+fun InstallStage.isBusy(): Boolean =
+    this == InstallStage.DOWNLOADING || this == InstallStage.INSTALLING
+
+/**
+ * The stage an outcome lands the UI in. A cancelled install returns to IDLE
+ * rather than ERROR — the user chose it, so presenting it as a failure would
+ * be a lie with a red tint.
+ */
+fun InstallOutcome.stage(): InstallStage = when (this) {
+    InstallOutcome.Installed, InstallOutcome.Cancelled -> InstallStage.IDLE
+    is InstallOutcome.Failed -> InstallStage.ERROR
+}
+
+/**
+ * User-facing copy for an outcome; null when there is nothing worth saying.
+ *
+ * Lives beside the outcome rather than in either UI package because two
+ * separate screens surface the same verdicts and must not drift — the same
+ * reasoning that puts [ErrorCopy][com.fabledsword.minstrel.api.ErrorCopy]
+ * outside the UI layer.
+ */
+fun InstallOutcome.message(): String? = when (this) {
+    InstallOutcome.Installed -> null
+    InstallOutcome.Cancelled -> "Update cancelled."
+    is InstallOutcome.Failed -> reason?.let { "Couldn't install update: $it" }
+        ?: "Couldn't install update."
+}

android/app/src/main/java/com/fabledsword/minstrel/update/data/SelfUpdateSession.kt

@@ -0,0 +1,220 @@
+package com.fabledsword.minstrel.update.data
+
+import android.app.PendingIntent
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.content.IntentSender
+import android.content.pm.ApplicationInfo
+import android.content.pm.PackageInstaller
+import android.content.pm.PackageManager
+import android.os.Build
+import androidx.core.content.ContextCompat
+import androidx.core.content.IntentCompat
+import dagger.hilt.android.qualifiers.ApplicationContext
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.suspendCancellableCoroutine
+import kotlinx.coroutines.withContext
+import java.io.File
+import javax.inject.Inject
+import javax.inject.Singleton
+import kotlin.coroutines.resume
+
+private const val STAGED_APK_NAME = "minstrel-update"
+
+/** Whole-file write: openWrite takes a Long offset, and Kotlin won't widen 0. */
+private const val WRITE_FROM_START = 0L
+
+/** Our own broadcast, delivered by the platform via the session's IntentSender. */
+private const val RESULT_ACTION = "com.fabledsword.minstrel.INSTALL_RESULT"
+
+/**
+ * Installs an APK over ourselves through a [PackageInstaller] session (#2438).
+ *
+ * Split from [ApkInstaller] because the two halves are different work — one
+ * speaks HTTP, the other speaks to the package manager — and the session half
+ * carries a receiver, a PendingIntent and version-gated params that would
+ * crowd the downloader out of its own file.
+ *
+ * ## Why a session, rather than the ACTION_VIEW intent this replaced
+ *
+ * Two reasons, and the second is the one that matters to users.
+ *
+ * The old path fired `ACTION_VIEW` at an `application/vnd.android.package-archive`
+ * URI and hoped. It could not report an outcome, so a failed install and a
+ * user who declined looked identical — see [InstallOutcome].
+ *
+ * More importantly, a session is where the platform lets a self-updater say it
+ * is one. [PackageInstaller.SessionParams.setRequireUserAction] with
+ * `USER_ACTION_NOT_REQUIRED`, paired with the `UPDATE_PACKAGES_WITHOUT_USER_ACTION`
+ * manifest permission, is the sanctioned way to update with **no dialog at
+ * all**. The platform grants that when all of: the installer opts in (here),
+ * the installed app targets API 29+ (we're on 36), the installer holds the
+ * permission (we do), and the target is the installer itself or something it
+ * first installed (we are updating ourselves). All four hold.
+ *
+ * ## What is deliberately absent
+ *
+ * No `setRequestUpdateOwnership(true)`. It reads like the right declaration for
+ * a self-updater and it is not: ownership can only be claimed on **initial**
+ * installation — setting it on an update is documented as a no-op — and it also
+ * wants the privileged `ENFORCE_UPDATE_OWNERSHIP` permission. It exists for app
+ * stores claiming the apps they install, not for an app updating itself.
+ */
+@Singleton
+class SelfUpdateSession @Inject constructor(
+    @ApplicationContext private val context: Context,
+) {
+    /**
+     * Stage [apk] and hand it to the platform, suspending until a terminal
+     * verdict arrives.
+     *
+     * Never returns on the happy path when the install is silent: the platform
+     * replaces this process the moment the new APK lands, so the coroutine dies
+     * rather than resuming. Callers must treat that as success, not a hang.
+     */
+    suspend fun run(apk: File): InstallOutcome {
+        val staged = withContext(Dispatchers.IO) { runCatching { stage(apk) } }
+        return staged.fold(
+            onSuccess = { sessionId -> awaitCommit(sessionId) },
+            onFailure = { InstallOutcome.Failed(it.message) },
+        )
+    }
+
+    /** Open a session, stream the APK in, return the session id. */
+    private fun stage(apk: File): Int {
+        val installer = context.packageManager.packageInstaller
+        val sessionId = installer.createSession(newParams())
+        installer.openSession(sessionId).use { session ->
+            session.openWrite(STAGED_APK_NAME, WRITE_FROM_START, apk.length()).use { sink ->
+                apk.inputStream().use { source -> source.copyTo(sink) }
+                // fsync before the session closes: the platform validates the
+                // staged bytes at commit, and buffered tail bytes read as a
+                // truncated APK.
+                session.fsync(sink)
+            }
+        }
+        return sessionId
+    }
+
+    // Explicit `params.` receivers rather than an apply {} block: lintVitalRelease
+    // runs on assembleRelease, and NewApi is easier for it to reason about when
+    // the guarded call has a named receiver instead of an implicit one.
+    private fun newParams(): PackageInstaller.SessionParams {
+        val params = PackageInstaller.SessionParams(
+            PackageInstaller.SessionParams.MODE_FULL_INSTALL,
+        )
+        params.setAppPackageName(context.packageName)
+        params.setInstallReason(PackageManager.INSTALL_REASON_USER)
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            // The whole point of this class. Pre-S there is no such API, so the
+            // confirm dialog is unavoidable there — degrade, don't fail.
+            params.setRequireUserAction(PackageInstaller.SessionParams.USER_ACTION_NOT_REQUIRED)
+        }
+        return params
+    }
+
+    /**
+     * Commit the session and wait for the platform to report back.
+     *
+     * A pending-user-action status is *not* terminal — the platform is asking us
+     * to show its dialog, and the real verdict arrives in a second broadcast
+     * once the user decides. So the receiver stays registered across it.
+     */
+    private suspend fun awaitCommit(sessionId: Int): InstallOutcome =
+        suspendCancellableCoroutine { continuation ->
+            val installer = context.packageManager.packageInstaller
+            val receiver = object : BroadcastReceiver() {
+                override fun onReceive(unused: Context, intent: Intent) {
+                    val status = intent.getIntExtra(
+                        PackageInstaller.EXTRA_STATUS,
+                        PackageInstaller.STATUS_FAILURE,
+                    )
+                    if (status == PackageInstaller.STATUS_PENDING_USER_ACTION) {
+                        confirmWithUser(intent)
+                    } else {
+                        context.unregisterReceiver(this)
+                        val why = intent.getStringExtra(PackageInstaller.EXTRA_STATUS_MESSAGE)
+                        if (continuation.isActive) continuation.resume(outcomeOf(status, why))
+                    }
+                }
+            }
+            ContextCompat.registerReceiver(
+                context,
+                receiver,
+                IntentFilter(RESULT_ACTION),
+                ContextCompat.RECEIVER_NOT_EXPORTED,
+            )
+            continuation.invokeOnCancellation {
+                // Stop listening, but deliberately do NOT abandon the session.
+                // Cancellation here means our caller's scope died — the user
+                // navigated away, or the VM cleared — and by this point the
+                // session is already committed. The user asked for this install;
+                // killing it because nobody is watching the banner any more
+                // would be the wrong reading of their intent.
+                runCatching { context.unregisterReceiver(receiver) }
+            }
+            runCatching {
+                installer.openSession(sessionId).use { it.commit(resultSender(sessionId)) }
+            }.onFailure { error ->
+                // Resuming normally means invokeOnCancellation never fires, so
+                // clean up the staged session here or it sits until it expires.
+                runCatching { context.unregisterReceiver(receiver) }
+                runCatching { installer.abandonSession(sessionId) }
+                if (continuation.isActive) {
+                    continuation.resume(InstallOutcome.Failed(error.message))
+                }
+            }
+        }
+
+    private fun resultSender(sessionId: Int): IntentSender {
+        // Scoped to our own package so the broadcast can't be answered elsewhere.
+        val intent = Intent(RESULT_ACTION).setPackage(context.packageName)
+        var flags = PendingIntent.FLAG_UPDATE_CURRENT
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            // The platform writes its status extras into this intent, so it has
+            // to stay mutable — FLAG_IMMUTABLE would arrive with none of them.
+            flags = flags or PendingIntent.FLAG_MUTABLE
+        }
+        // Session id as the request code keeps concurrent sessions from
+        // colliding on FLAG_UPDATE_CURRENT.
+        return PendingIntent.getBroadcast(context, sessionId, intent, flags).intentSender
+    }
+
+    /**
+     * Show the platform's own confirm dialog, which arrives as an extra.
+     *
+     * The system-app check is not ceremony. Below API 34 a dynamically
+     * registered receiver cannot declare itself unexported, so another app on
+     * the device can broadcast [RESULT_ACTION] at us — and calling
+     * `startActivity` on an attacker-supplied extra would hand it whatever we
+     * can reach. The genuine confirm activity belongs to the platform
+     * installer, so demanding a system component costs the real path nothing.
+     */
+    private fun confirmWithUser(result: Intent) {
+        val pending = IntentCompat.getParcelableExtra(
+            result,
+            Intent.EXTRA_INTENT,
+            Intent::class.java,
+        ) ?: return
+        if (isPlatformActivity(pending)) {
+            context.startActivity(pending.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
+        }
+    }
+
+    private fun isPlatformActivity(intent: Intent): Boolean {
+        val flags = intent.resolveActivityInfo(context.packageManager, 0)
+            ?.applicationInfo
+            ?.flags
+            ?: 0
+        val systemFlags = ApplicationInfo.FLAG_SYSTEM or ApplicationInfo.FLAG_UPDATED_SYSTEM_APP
+        return (flags and systemFlags) != 0
+    }
+
+    private fun outcomeOf(status: Int, message: String?): InstallOutcome = when (status) {
+        PackageInstaller.STATUS_SUCCESS -> InstallOutcome.Installed
+        PackageInstaller.STATUS_FAILURE_ABORTED -> InstallOutcome.Cancelled
+        else -> InstallOutcome.Failed(message)
+    }
+}

android/app/src/main/java/com/fabledsword/minstrel/update/ui/UpdateBanner.kt

@@ -28,6 +28,8 @@ import com.composables.icons.lucide.Download
 import com.composables.icons.lucide.Lucide
 import com.composables.icons.lucide.X
 import com.fabledsword.minstrel.models.UpdateInfo
+import com.fabledsword.minstrel.update.data.InstallStage
+import com.fabledsword.minstrel.update.data.isBusy
 
 /**
  * Shell-level soft banner that nudges an available update. Renders
@@ -79,7 +81,7 @@ private fun BannerBody(
             .padding(start = 16.dp, top = 8.dp, end = 4.dp, bottom = 8.dp),
     ) {
         BannerRow(info = info, stage = stage, onInstall = onInstall, onDismiss = onDismiss)
-        if (stage == InstallStage.DOWNLOADING) {
+        if (stage.isBusy()) {
             LinearProgressIndicator(
                 modifier = Modifier
                     .fillMaxWidth()
@@ -124,8 +126,17 @@ private fun BannerRow(
             color = MaterialTheme.colorScheme.onSurfaceVariant,
             modifier = Modifier.weight(1f),
         )
-        TextButton(onClick = onInstall, enabled = stage != InstallStage.DOWNLOADING) {
-            Text(if (stage == InstallStage.DOWNLOADING) "Installing…" else "Install")
+        TextButton(onClick = onInstall, enabled = !stage.isBusy()) {
+            // Downloading and installing are separate words because they're now
+            // separate waits — the install half suspends on the platform, which
+            // may be sitting on a confirm dialog.
+            Text(
+                when (stage) {
+                    InstallStage.DOWNLOADING -> "Downloading…"
+                    InstallStage.INSTALLING -> "Installing…"
+                    else -> "Install"
+                },
+            )
         }
         IconButton(onClick = onDismiss) {
             Icon(

android/app/src/main/java/com/fabledsword/minstrel/update/ui/UpdateBannerViewModel.kt

@@ -5,7 +5,11 @@ import androidx.lifecycle.viewModelScope
 import com.fabledsword.minstrel.api.ErrorCopy
 import com.fabledsword.minstrel.models.UpdateInfo
 import com.fabledsword.minstrel.update.data.ApkInstaller
+import com.fabledsword.minstrel.update.data.InstallStage
 import com.fabledsword.minstrel.update.data.UpdateBannerController
+import com.fabledsword.minstrel.update.data.isBusy
+import com.fabledsword.minstrel.update.data.message
+import com.fabledsword.minstrel.update.data.stage
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.SharingStarted
@@ -13,13 +17,11 @@ import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.combine
 import kotlinx.coroutines.flow.stateIn
 import kotlinx.coroutines.launch
+import java.io.File
 import javax.inject.Inject
 
 private const val SHARE_STOP_TIMEOUT_MS = 5_000L
 
-/** Install lifecycle for the banner's Install button. */
-enum class InstallStage { IDLE, DOWNLOADING, ERROR }
-
 data class UpdateBannerUiState(
     val info: UpdateInfo? = null,
     val stage: InstallStage = InstallStage.IDLE,
@@ -28,9 +30,9 @@ data class UpdateBannerUiState(
 
 /**
  * Thin VM over [UpdateBannerController]. Surfaces the available update
- * and runs the download → system-install handoff via [ApkInstaller],
- * mirroring the About card's flow (route to "install unknown apps"
- * settings first when the permission is missing).
+ * and runs the download → install handoff via [ApkInstaller], mirroring
+ * the About card's flow (route to "install unknown apps" settings first
+ * when the permission is missing).
  */
 @HiltViewModel
 class UpdateBannerViewModel @Inject constructor(
@@ -38,7 +40,7 @@ class UpdateBannerViewModel @Inject constructor(
     private val installer: ApkInstaller,
 ) : ViewModel() {
 
-    private val installState = MutableStateFlow(IdleInstall)
+    private val installState = MutableStateFlow(InstallSnapshot(InstallStage.IDLE, null))
 
     val uiState: StateFlow<UpdateBannerUiState> =
         combine(controller.available, installState) { info, install ->
@@ -52,7 +54,7 @@ class UpdateBannerViewModel @Inject constructor(
     fun dismiss(version: String) = controller.dismiss(version)
 
     fun install(info: UpdateInfo) {
-        if (installState.value.stage == InstallStage.DOWNLOADING) return
+        if (installState.value.stage.isBusy()) return
         if (!installer.canInstall()) {
             installer.requestInstallPermission()
             installState.value = InstallSnapshot(
@@ -63,21 +65,28 @@ class UpdateBannerViewModel @Inject constructor(
         }
         viewModelScope.launch {
             installState.value = InstallSnapshot(InstallStage.DOWNLOADING, null)
-            runCatching { installer.downloadApk(info.apkUrl) }
-                .onSuccess { apk ->
-                    installer.launchInstall(apk)
-                    installState.value = IdleInstall
-                }
-                .onFailure { e ->
-                    installState.value = InstallSnapshot(
-                        InstallStage.ERROR,
-                        "Couldn't download update: ${ErrorCopy.fromThrowable(e)}",
-                    )
-                }
+            val apk = download(info.apkUrl)
+            if (apk != null) {
+                // Await the platform's verdict rather than firing an intent and
+                // assuming it worked. On a silent install this suspends until
+                // the process is replaced, so the line below is only reached
+                // when the install did NOT simply succeed.
+                installState.value = InstallSnapshot(InstallStage.INSTALLING, null)
+                val outcome = installer.install(apk)
+                installState.value = InstallSnapshot(outcome.stage(), outcome.message())
+            }
         }
     }
+
+    private suspend fun download(apkUrl: String): File? =
+        runCatching { installer.downloadApk(apkUrl) }
+            .onFailure { e ->
+                installState.value = InstallSnapshot(
+                    InstallStage.ERROR,
+                    "Couldn't download update: ${ErrorCopy.fromThrowable(e)}",
+                )
+            }
+            .getOrNull()
 }
 
 private data class InstallSnapshot(val stage: InstallStage, val message: String?)
-
-private val IdleInstall = InstallSnapshot(InstallStage.IDLE, null)

android/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Adaptive icon (API 26+). Before this the app shipped legacy bitmaps only,
+     so modern launchers letterboxed the square instead of masking it to the
+     device's icon shape. The foreground PNGs are drawn on a 108dp canvas with
+     the mark inside the 66dp safe zone, so no mask can clip it. -->
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@color/ic_launcher_background"/>
+    <foreground android:drawable="@mipmap/ic_launcher_foreground"/>
+    <monochrome android:drawable="@mipmap/ic_launcher_foreground"/>
+</adaptive-icon>

android/app/src/main/res/values/colors.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <!-- Obsidian. The adaptive icon's plate; chosen over the raised-surface
+         iron because the accent note only clears the 3:1 graphics contrast
+         threshold against this darker value (3.04:1 vs 2.70:1). -->
+    <color name="ic_launcher_background">#14171A</color>
+</resources>

android/app/src/main/res/xml/file_paths.xml

@@ -1,9 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<paths>
-    <!-- The downloaded update APK lives in the app cache dir; the
-         FileProvider exposes just that directory to the system
-         installer via a content:// URI. -->
-    <cache-path
-        name="updates"
-        path="." />
-</paths>

android/app/src/main/res/xml/network_security_config.xml

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Replaces a bare android:usesCleartextTraffic="true" on <application> (#2439).
+
+  Cleartext is still permitted app-wide, and it has to be. Two independent
+  reasons, neither of which can be narrowed to a domain list:
+
+    1. The Minstrel server's host is entered by the user at runtime. Plenty of
+       self-hosters run it over plain HTTP on a LAN; refusing that would break
+       real installs rather than secure anyone.
+
+    2. UPnP / DLNA / Sonos. Device-description and SOAP control URLs arrive in
+       SSDP responses at runtime and are plain HTTP essentially without
+       exception — see player/output/upnp/{UpnpDiscoveryController,SoapClient}.
+
+  A <domain-config> would be the way to scope this, but it matches literal
+  hostnames rather than CIDR ranges, and both sets of hosts above are unknowable
+  until runtime. So a permissive base-config is an honest description of our
+  situation — the gain over the manifest attribute is that the reasoning now
+  lives somewhere, and there is one place to tighten if a future settings screen
+  can distinguish a LAN server from a WAN one.
+
+  Worth stating because it looks worse than it is: this is NOT a tamper risk for
+  the in-app updater. An APK altered in transit and re-signed is rejected by the
+  platform as a signature mismatch on update, so the boundary there is enforced
+  regardless of transport.
+
+  Trust anchors are deliberately left at the platform default (system CAs only).
+  Adding <certificates src="user" /> would let self-hosters use HTTPS with their
+  own private CA — attractive for this product, and what Mihon does — but it
+  also makes the app trust every CA on the device, including a corporate MITM
+  proxy. That's an operator decision, not a default worth assuming.
+-->
+<network-security-config xmlns:tools="http://schemas.android.com/tools">
+    <base-config
+        cleartextTrafficPermitted="true"
+        tools:ignore="InsecureBaseConfiguration" />
+</network-security-config>

internal/api/admin_network.go

@@ -0,0 +1,65 @@
+package api
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/apierror"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/auth"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/netsettings"
+)
+
+type networkSettingsResp struct {
+	TrustedProxyHops int `json:"trusted_proxy_hops"`
+	MaxHops          int `json:"max_hops"`
+	// DetectedClientIP is what the CURRENT setting resolves this very request
+	// to. It's the difference between a number the operator has to reason
+	// about and one they can verify: set the value, reload, and check the
+	// address matches the machine you're sitting at.
+	DetectedClientIP string `json:"detected_client_ip"`
+	// ForwardedChain is the raw X-Forwarded-For as received, so an operator
+	// whose detected address looks wrong can see how many hops actually
+	// arrived and count them rather than guess.
+	ForwardedChain string `json:"forwarded_chain"`
+	RemoteAddr     string `json:"remote_addr"`
+}
+
+type updateNetworkSettingsReq struct {
+	TrustedProxyHops int `json:"trusted_proxy_hops"`
+}
+
+func (h *handlers) handleGetNetworkSettings(w http.ResponseWriter, r *http.Request) {
+	writeJSON(w, http.StatusOK, h.networkSettingsPayload(r))
+}
+
+func (h *handlers) handleUpdateNetworkSettings(w http.ResponseWriter, r *http.Request) {
+	var req updateNetworkSettingsReq
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeErr(w, apierror.BadRequest("invalid_body", "malformed JSON"))
+		return
+	}
+	if err := h.netSettings.SetHops(r.Context(), req.TrustedProxyHops); err != nil {
+		if errors.Is(err, netsettings.ErrHopsOutOfRange) {
+			writeErr(w, apierror.BadRequest("invalid_hops", err.Error()))
+			return
+		}
+		writeErrWithLog(w, h.logger, "admin network: update failed", apierror.Internal(err))
+		return
+	}
+	// Echo the payload recomputed under the NEW value, so the card can show
+	// immediately what the change did to this request's own address rather
+	// than making the operator reload to find out.
+	writeJSON(w, http.StatusOK, h.networkSettingsPayload(r))
+}
+
+func (h *handlers) networkSettingsPayload(r *http.Request) networkSettingsResp {
+	hops := h.netSettings.Hops()
+	return networkSettingsResp{
+		TrustedProxyHops: hops,
+		MaxHops:          netsettings.MaxTrustedProxyHops,
+		DetectedClientIP: auth.ClientIP(r, hops),
+		ForwardedChain:   r.Header.Get("X-Forwarded-For"),
+		RemoteAddr:       r.RemoteAddr,
+	}
+}

internal/api/api.go

@@ -20,6 +20,7 @@ import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/lidarrquarantine"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/lidarrrequests"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/mailer"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/netsettings"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/playevents"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/playlists"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/recsettings"
@@ -30,7 +31,7 @@ import (
 // Mount attaches /api/* handlers to r. Public endpoints (login) are outside
 // RequireUser; everything else is gated by the middleware. The events writer
 // is shared with the Subsonic mount so /rest/scrobble feeds the same store.
-func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playevents.Writer, recCfg config.RecommendationConfig, recSettings *recsettings.Service, lidarrCfg *lidarrconfig.Service, lidarrReqs *lidarrrequests.Service, lidarrQuar *lidarrquarantine.Service, tracksSvc *tracks.Service, playlistsSvc *playlists.Service, coverEnricher *coverart.Enricher, coverSettings *coverart.SettingsService, tagSettings *tags.SettingsService, scanner *library.Scanner, scanCfg library.RunScanConfig, dataDir string, sender mailer.Sender, bus *eventbus.Bus, playlistScheduler *playlists.Scheduler, streamSecret []byte) {
+func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playevents.Writer, recCfg config.RecommendationConfig, recSettings *recsettings.Service, lidarrCfg *lidarrconfig.Service, lidarrReqs *lidarrrequests.Service, lidarrQuar *lidarrquarantine.Service, tracksSvc *tracks.Service, playlistsSvc *playlists.Service, coverEnricher *coverart.Enricher, coverSettings *coverart.SettingsService, tagSettings *tags.SettingsService, scanner *library.Scanner, scanCfg library.RunScanConfig, dataDir string, sender mailer.Sender, bus *eventbus.Bus, playlistScheduler *playlists.Scheduler, streamSecret []byte, netSettings *netsettings.Service) {
 	rng := rand.New(rand.NewSource(rand.Int63()))
 	h := &handlers{
 		pool: pool, logger: logger, events: events, recCfg: recCfg,
@@ -51,6 +52,7 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 		eventbus:          bus,
 		playlistScheduler: playlistScheduler,
 		streamSecret:      streamSecret,
+		netSettings:       netSettings,
 	}
 
 	r.Route("/api", func(api chi.Router) {
@@ -74,7 +76,7 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 		api.With(auth.OptionalUser(pool, logger)).Get("/tracks/{id}/stream.{ext}", h.handleGetStream)
 
 		api.Group(func(authed chi.Router) {
-			authed.Use(auth.RequireUser(pool))
+			authed.Use(auth.RequireUser(pool, netSettings.Hops))
 			authed.Post("/auth/logout", h.handleLogout)
 			authed.Get("/me", h.handleGetMe)
 			authed.Get("/me/system-playlists-status", h.handleGetSystemPlaylistsStatus)
@@ -87,6 +89,9 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 			authed.Put("/me/timezone", h.handlePutTimezone)
 			authed.Get("/me/api-token", h.handleGetMyAPIToken)
 			authed.Post("/me/api-token", h.handleRegenerateMyAPIToken)
+			authed.Get("/me/sessions", h.handleListMySessions)
+			authed.Delete("/me/sessions/{id}", h.handleRevokeMySession)
+			authed.Post("/me/sessions/logout-others", h.handleRevokeMyOtherSessions)
 
 			authed.Get("/artists", h.handleListArtists)
 			authed.Get("/artists/{id}", h.handleGetArtist)
@@ -182,6 +187,9 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 				admin.Post("/albums/{id}/cover/refetch", h.handleAdminAlbumRefetchCover)
 				admin.Post("/covers/refetch-missing", h.handleAdminBulkRefetchCovers)
 
+				admin.Get("/network-settings", h.handleGetNetworkSettings)
+				admin.Put("/network-settings", h.handleUpdateNetworkSettings)
+
 				admin.Get("/scan/status", h.handleGetScanStatus)
 				admin.Post("/scan/run", h.handleTriggerScan)
 
@@ -261,6 +269,9 @@ type handlers struct {
 	mailer            mailer.Sender
 	eventbus          *eventbus.Bus
 	playlistScheduler *playlists.Scheduler
+	// netSettings caches the trusted reverse-proxy depth read by the auth
+	// middleware on every request and edited from the admin network card.
+	netSettings *netsettings.Service
 	// streamSecret is the HMAC key used by SignStreamToken /
 	// VerifyStreamToken to authenticate the UPnP-speaker stream path
 	// (see internal/api/stream_token.go and the design at

internal/api/auth.go

@@ -96,6 +96,11 @@ func (h *handlers) handleLogin(w http.ResponseWriter, r *http.Request) {
 		UserID:    user.ID,
 		TokenHash: auth.HashSessionToken(token),
 		UserAgent: r.UserAgent(),
+		// Origin address, frozen at issue time. Compared against last_ip in
+		// the active-sessions surface: a session that was born somewhere the
+		// user recognises but is being used from somewhere they don't is the
+		// case this whole surface exists to surface.
+		Ip: auth.ClientIP(r, h.netSettings.Hops()),
 	}); err != nil {
 		h.logger.Error("api: insert session failed", "err", err)
 		writeErr(w, apierror.InternalMsg("insert failed", err))

internal/api/auth_register.go

@@ -175,6 +175,7 @@ func (h *handlers) handleRegister(w http.ResponseWriter, r *http.Request) {
 		UserID:    user.ID,
 		TokenHash: auth.HashSessionToken(sessionToken),
 		UserAgent: r.UserAgent(),
+		Ip:        auth.ClientIP(r, h.netSettings.Hops()),
 	}); err != nil {
 		h.logger.Error("register: insert session failed", "err", err)
 		writeErr(w, apierror.Internal(err))

internal/api/library_test.go

@@ -465,7 +465,7 @@ func TestRoutesRegisteredInMount(t *testing.T) {
 	r := chi.NewRouter()
 	w := playevents.NewWriter(h.pool, slog.New(slog.NewTextHandler(io.Discard, nil)),
 		30*time.Minute, 0.5, 30000)
-	Mount(r, h.pool, h.logger, w, config.RecommendationConfig{RadioSize: 50, RadioSizeMax: 200, RecentlyPlayedHours: 1}, h.recSettings, h.lidarrCfg, h.lidarrRequests, h.lidarrQuarantine, h.tracks, h.playlists, h.coverart, h.coverSettings, h.tagSettings, h.scanner, h.scanCfg, h.dataDir, nil, eventbus.New(), nil, nil)
+	Mount(r, h.pool, h.logger, w, config.RecommendationConfig{RadioSize: 50, RadioSizeMax: 200, RecentlyPlayedHours: 1}, h.recSettings, h.lidarrCfg, h.lidarrRequests, h.lidarrQuarantine, h.tracks, h.playlists, h.coverart, h.coverSettings, h.tagSettings, h.scanner, h.scanCfg, h.dataDir, nil, eventbus.New(), nil, nil, h.netSettings)
 
 	paths := []string{
 		"/api/artists",

internal/api/me_sessions.go

@@ -0,0 +1,136 @@
+package api
+
+import (
+	"errors"
+	"net/http"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/apierror"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/audit"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/auth"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+)
+
+// errNoCurrentSession means the request authenticated but the middleware
+// didn't record which session did it — which should be impossible on a route
+// behind RequireUser. It matters because "log out everywhere else" is defined
+// by exclusion: without knowing which session is ours, the safe-looking
+// action would sign the caller out too.
+var errNoCurrentSession = errors.New("no session id in request context")
+
+// sessionResp is one row of the active-sessions list.
+//
+// token_hash is absent, and that is the point of storing only a hash: it
+// never leaves the database, so this surface can list sessions without
+// handing out anything that could be replayed.
+type sessionResp struct {
+	ID        string `json:"id"`
+	UserAgent string `json:"user_agent"`
+	// CreatedIP is frozen at issue time; LastIP moves with the session. The
+	// pair is what makes a stolen token legible — same device string, but an
+	// address the user doesn't recognise.
+	CreatedIP  string    `json:"created_ip"`
+	LastIP     string    `json:"last_ip"`
+	CreatedAt  time.Time `json:"created_at"`
+	LastSeenAt time.Time `json:"last_seen_at"`
+	// Current marks the session making this request so the UI can label it
+	// and not offer a "log out" that signs the user out of the page they're
+	// standing on.
+	Current bool `json:"current"`
+}
+
+type revokedResp struct {
+	Revoked int `json:"revoked"`
+}
+
+// handleListMySessions implements GET /api/me/sessions.
+func (h *handlers) handleListMySessions(w http.ResponseWriter, r *http.Request) {
+	user, ok := requireUser(w, r)
+	if !ok {
+		return
+	}
+	// Absent id is tolerated here (unlike logout-others): the list still
+	// renders, it just won't flag a current row.
+	currentID, _ := auth.SessionIDFromContext(r.Context())
+
+	rows, err := dbq.New(h.pool).ListSessionsForUser(r.Context(), user.ID)
+	if err != nil {
+		h.logger.Error("list sessions: query failed", "err", err)
+		writeErr(w, apierror.Internal(err))
+		return
+	}
+	out := make([]sessionResp, 0, len(rows))
+	for _, s := range rows {
+		out = append(out, sessionResp{
+			ID:         uuidToString(s.ID),
+			UserAgent:  s.UserAgent,
+			CreatedIP:  s.CreatedIp,
+			LastIP:     s.LastIp,
+			CreatedAt:  s.CreatedAt.Time,
+			LastSeenAt: s.LastSeenAt.Time,
+			Current:    s.ID == currentID,
+		})
+	}
+	writeJSON(w, http.StatusOK, out)
+}
+
+// handleRevokeMySession implements DELETE /api/me/sessions/{id}.
+func (h *handlers) handleRevokeMySession(w http.ResponseWriter, r *http.Request) {
+	user, ok := requireUser(w, r)
+	if !ok {
+		return
+	}
+	id, ok := parseUUID(chi.URLParam(r, "id"))
+	if !ok {
+		// Malformed and belongs-to-someone-else collapse to one answer on
+		// purpose: a distinguishable response would let a caller probe
+		// whether another user's session id exists.
+		writeErr(w, apierror.NotFound("session"))
+		return
+	}
+	n, err := dbq.New(h.pool).DeleteSessionForUser(r.Context(), dbq.DeleteSessionForUserParams{
+		ID:     id,
+		UserID: user.ID,
+	})
+	if err != nil {
+		h.logger.Error("revoke session: delete failed", "err", err)
+		writeErr(w, apierror.Internal(err))
+		return
+	}
+	if n == 0 {
+		writeErr(w, apierror.NotFound("session"))
+		return
+	}
+	audit.WriteOrLog(r.Context(), h.pool, h.logger, user.ID, user.ID, audit.ActionSessionRevoke, nil)
+	w.WriteHeader(http.StatusNoContent)
+}
+
+// handleRevokeMyOtherSessions implements POST /api/me/sessions/logout-others.
+func (h *handlers) handleRevokeMyOtherSessions(w http.ResponseWriter, r *http.Request) {
+	user, ok := requireUser(w, r)
+	if !ok {
+		return
+	}
+	currentID, ok := auth.SessionIDFromContext(r.Context())
+	if !ok {
+		// Refuse rather than guess: deleting "all but unknown" is deleting
+		// all, which would log the caller out of the page they invoked this
+		// from and look exactly like the attack they were defending against.
+		h.logger.Error("revoke other sessions: no session id in context")
+		writeErr(w, apierror.Internal(errNoCurrentSession))
+		return
+	}
+	n, err := dbq.New(h.pool).DeleteOtherSessionsForUser(r.Context(), dbq.DeleteOtherSessionsForUserParams{
+		UserID: user.ID,
+		ID:     currentID,
+	})
+	if err != nil {
+		h.logger.Error("revoke other sessions: delete failed", "err", err)
+		writeErr(w, apierror.Internal(err))
+		return
+	}
+	audit.WriteOrLog(r.Context(), h.pool, h.logger, user.ID, user.ID, audit.ActionSessionRevokeOthers, nil)
+	writeJSON(w, http.StatusOK, revokedResp{Revoked: int(n)})
+}

internal/api/me_sessions_test.go

@@ -0,0 +1,226 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/jackc/pgx/v5/pgtype"
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/auth"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+)
+
+// seedSession inserts a session for userID and returns its id.
+func seedSession(t *testing.T, pool *pgxpool.Pool, userID pgtype.UUID, ip string) pgtype.UUID {
+	t.Helper()
+	token, err := auth.MintSessionToken()
+	if err != nil {
+		t.Fatalf("mint: %v", err)
+	}
+	sess, err := dbq.New(pool).InsertSession(context.Background(), dbq.InsertSessionParams{
+		UserID:    userID,
+		TokenHash: auth.HashSessionToken(token),
+		UserAgent: "test-agent",
+		Ip:        ip,
+	})
+	if err != nil {
+		t.Fatalf("insert session: %v", err)
+	}
+	return sess.ID
+}
+
+// withSession attaches the user and current-session id the handlers expect
+// from RequireUser.
+func withSession(r *http.Request, user dbq.User, sessionID pgtype.UUID) *http.Request {
+	ctx := context.WithValue(r.Context(), userCtxKeyForTest(), user)
+	ctx = context.WithValue(ctx, auth.SessionIDCtxKeyForTest(), sessionID)
+	return r.WithContext(ctx)
+}
+
+// withURLParam wires a chi route param, which handlers read via chi.URLParam.
+func withURLParam(r *http.Request, key, value string) *http.Request {
+	rctx := chi.NewRouteContext()
+	rctx.URLParams.Add(key, value)
+	return r.WithContext(context.WithValue(r.Context(), chi.RouteCtxKey, rctx))
+}
+
+// The rule #47 assertion. A delete keyed only on session id would let any
+// household member revoke any other member's session by id — this pins that
+// the user scope is actually in the WHERE clause and not just intended.
+func TestRevokeMySession_CannotRevokeAnotherUsersSession(t *testing.T) {
+	h, pool := testHandlers(t)
+	alice := seedUser(t, pool, "alice", "hunter2", false)
+	bob := seedUser(t, pool, "bob", "hunter2", false)
+
+	bobSession := seedSession(t, pool, bob.ID, "203.0.113.9")
+	aliceSession := seedSession(t, pool, alice.ID, "203.0.113.1")
+
+	target := uuidToString(bobSession)
+	req := httptest.NewRequest(http.MethodDelete, "/api/me/sessions/"+target, nil)
+	req = withURLParam(req, "id", target)
+	req = withSession(req, alice, aliceSession)
+	w := httptest.NewRecorder()
+	h.handleRevokeMySession(w, req)
+
+	if w.Code != http.StatusNotFound {
+		t.Errorf("status = %d, want 404 (not another user's to revoke)", w.Code)
+	}
+
+	// The 404 must mean "didn't happen", not merely "wasn't reported".
+	var stillThere bool
+	if err := pool.QueryRow(context.Background(),
+		`SELECT EXISTS (SELECT 1 FROM sessions WHERE id = $1)`, bobSession,
+	).Scan(&stillThere); err != nil {
+		t.Fatalf("exists check: %v", err)
+	}
+	if !stillThere {
+		t.Error("bob's session was deleted by alice's request")
+	}
+}
+
+func TestRevokeMySession_DeletesOwnSession(t *testing.T) {
+	h, pool := testHandlers(t)
+	alice := seedUser(t, pool, "alice", "hunter2", false)
+	current := seedSession(t, pool, alice.ID, "203.0.113.1")
+	other := seedSession(t, pool, alice.ID, "198.51.100.7")
+
+	target := uuidToString(other)
+	req := httptest.NewRequest(http.MethodDelete, "/api/me/sessions/"+target, nil)
+	req = withURLParam(req, "id", target)
+	req = withSession(req, alice, current)
+	w := httptest.NewRecorder()
+	h.handleRevokeMySession(w, req)
+
+	if w.Code != http.StatusNoContent {
+		t.Fatalf("status = %d, want 204", w.Code)
+	}
+	var gone bool
+	if err := pool.QueryRow(context.Background(),
+		`SELECT NOT EXISTS (SELECT 1 FROM sessions WHERE id = $1)`, other,
+	).Scan(&gone); err != nil {
+		t.Fatalf("exists check: %v", err)
+	}
+	if !gone {
+		t.Error("session survived its own owner's revoke")
+	}
+}
+
+// "Log out everywhere else" must spare the caller — otherwise the button
+// signs you out of the page you pressed it on, which is indistinguishable
+// from the compromise it's meant to remedy.
+func TestRevokeMyOtherSessions_SparesCurrentAndOtherUsers(t *testing.T) {
+	h, pool := testHandlers(t)
+	alice := seedUser(t, pool, "alice", "hunter2", false)
+	bob := seedUser(t, pool, "bob", "hunter2", false)
+
+	current := seedSession(t, pool, alice.ID, "203.0.113.1")
+	seedSession(t, pool, alice.ID, "198.51.100.7")
+	seedSession(t, pool, alice.ID, "198.51.100.8")
+	bobSession := seedSession(t, pool, bob.ID, "203.0.113.9")
+
+	req := httptest.NewRequest(http.MethodPost, "/api/me/sessions/logout-others", nil)
+	req = withSession(req, alice, current)
+	w := httptest.NewRecorder()
+	h.handleRevokeMyOtherSessions(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", w.Code)
+	}
+	var body revokedResp
+	if err := json.NewDecoder(w.Body).Decode(&body); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if body.Revoked != 2 {
+		t.Errorf("revoked = %d, want 2 (alice's other two, not bob's)", body.Revoked)
+	}
+
+	var aliceRemaining, bobRemaining int
+	if err := pool.QueryRow(context.Background(),
+		`SELECT count(*) FROM sessions WHERE user_id = $1`, alice.ID,
+	).Scan(&aliceRemaining); err != nil {
+		t.Fatalf("count alice: %v", err)
+	}
+	if aliceRemaining != 1 {
+		t.Errorf("alice sessions = %d, want 1 (the current one)", aliceRemaining)
+	}
+	if err := pool.QueryRow(context.Background(),
+		`SELECT count(*) FROM sessions WHERE id = $1`, bobSession,
+	).Scan(&bobRemaining); err != nil {
+		t.Fatalf("count bob: %v", err)
+	}
+	if bobRemaining != 1 {
+		t.Error("bob's session was caught in alice's logout-others")
+	}
+}
+
+// Without a current-session id the exclusion has nothing to exclude, so the
+// handler must refuse rather than delete everything.
+func TestRevokeMyOtherSessions_RefusesWithoutCurrentSession(t *testing.T) {
+	h, pool := testHandlers(t)
+	alice := seedUser(t, pool, "alice", "hunter2", false)
+	seedSession(t, pool, alice.ID, "203.0.113.1")
+
+	req := httptest.NewRequest(http.MethodPost, "/api/me/sessions/logout-others", nil)
+	req = req.WithContext(context.WithValue(req.Context(), userCtxKeyForTest(), alice))
+	w := httptest.NewRecorder()
+	h.handleRevokeMyOtherSessions(w, req)
+
+	if w.Code != http.StatusInternalServerError {
+		t.Errorf("status = %d, want 500", w.Code)
+	}
+	var remaining int
+	if err := pool.QueryRow(context.Background(),
+		`SELECT count(*) FROM sessions WHERE user_id = $1`, alice.ID,
+	).Scan(&remaining); err != nil {
+		t.Fatalf("count: %v", err)
+	}
+	if remaining != 1 {
+		t.Errorf("sessions = %d, want 1 — refusing must not delete", remaining)
+	}
+}
+
+func TestListMySessions_FlagsCurrentAndScopesToUser(t *testing.T) {
+	h, pool := testHandlers(t)
+	alice := seedUser(t, pool, "alice", "hunter2", false)
+	bob := seedUser(t, pool, "bob", "hunter2", false)
+
+	current := seedSession(t, pool, alice.ID, "203.0.113.1")
+	seedSession(t, pool, alice.ID, "198.51.100.7")
+	seedSession(t, pool, bob.ID, "203.0.113.9")
+
+	req := httptest.NewRequest(http.MethodGet, "/api/me/sessions", nil)
+	req = withSession(req, alice, current)
+	w := httptest.NewRecorder()
+	h.handleListMySessions(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", w.Code)
+	}
+	var got []sessionResp
+	if err := json.NewDecoder(w.Body).Decode(&got); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if len(got) != 2 {
+		t.Fatalf("sessions = %d, want 2 (bob's must not appear)", len(got))
+	}
+	currentCount := 0
+	for _, s := range got {
+		if s.Current {
+			currentCount++
+			if s.ID != uuidToString(current) {
+				t.Errorf("current flagged on %s, want %s", s.ID, uuidToString(current))
+			}
+		}
+		if s.CreatedIP == "" {
+			t.Error("created_ip empty — the whole point of the surface")
+		}
+	}
+	if currentCount != 1 {
+		t.Errorf("current-flagged rows = %d, want exactly 1", currentCount)
+	}
+}

internal/audit/audit.go

@@ -48,6 +48,13 @@ const (
 	ActionTokenRegenerate      Action = "token_regenerate"
 	ActionForgotPasswordInit   Action = "forgot_password_initiated"
 	ActionPasswordResetByEmail Action = "password_reset_via_email"
+
+	// Active-sessions surface (#370). Worth auditing rather than silent:
+	// revoking sessions is what a user does when they think an account is
+	// compromised, so the audit trail is most useful precisely when it's
+	// exercised.
+	ActionSessionRevoke       Action = "session_revoke"
+	ActionSessionRevokeOthers Action = "session_revoke_others"
 )
 
 // Write inserts one audit_log row. metadata is marshaled as JSON;

internal/auth/clientip.go

@@ -0,0 +1,111 @@
+package auth
+
+import (
+	"net"
+	"net/http"
+	"strings"
+)
+
+// ClientIP returns the caller's address, reading through trustedProxyHops
+// reverse proxies (#2453).
+//
+// X-Forwarded-For grows left-to-right: every proxy APPENDS the peer it
+// received the request from. For client -> CDN -> own-proxy -> Minstrel the
+// app sees XFF = [client, CDN] and RemoteAddr = own-proxy. Each trusted proxy
+// therefore accounts for one entry counting from the right, and the first
+// address we were NOT told to trust is the client:
+//
+//	hops 0  -> RemoteAddr; XFF ignored entirely
+//	hops 1  -> XFF[1] = CDN — trusting only our own proxy, the most we can
+//	           honestly claim is the address it told us about
+//	hops 2  -> XFF[0] = client
+//
+// This replaces an earlier heuristic that ignored XFF whenever RemoteAddr was
+// public. That was safe but useless in the deployment that matters: a proxy
+// on a public address (separate host, or a CDN) meant every session recorded
+// the proxy, so the active-sessions surface could never show an address
+// change (#370).
+//
+// # What the operator is asserting
+//
+// hops >= 1 is a DECLARATION that a proxy sits in front. Two ways to get it
+// wrong, both worth understanding rather than papering over:
+//
+//   - Set to 1+ with NO proxy: any client can forge X-Forwarded-For and pick
+//     what its own session row shows, defeating the compromise detection.
+//   - Set HIGHER than the real chain: the index runs past the proxy-written
+//     entries into attacker-supplied ones, same result.
+//
+// Both are inherent to the trusted-hop model — Rails, Caddy, Traefik and
+// nginx all behave this way — which is why 0 is a first-class value and the
+// admin card tells the operator to count their proxies.
+func ClientIP(r *http.Request, trustedProxyHops int) string {
+	remote := hostOf(r.RemoteAddr)
+	if trustedProxyHops <= 0 {
+		return remote
+	}
+	chain := forwardedChain(r)
+	if len(chain) == 0 {
+		// No forwarding header: either there's genuinely no proxy, or one is
+		// misconfigured. The socket peer is the only thing we actually know.
+		return remote
+	}
+	// Clamp rather than reject: a chain shorter than the configured depth
+	// means the operator over-counted, and the leftmost entry is the closest
+	// thing to a client on offer. The caveat above covers the risk.
+	idx := len(chain) - trustedProxyHops
+	if idx < 0 {
+		idx = 0
+	}
+	if ip := net.ParseIP(chain[idx]); ip != nil {
+		return ip.String()
+	}
+	// A proxy wrote something that isn't an address. Positional meaning is
+	// lost, so fall back to what we can verify ourselves.
+	return remote
+}
+
+// forwardedChain returns the X-Forwarded-For entries in wire order, or the
+// single X-Real-IP value when XFF is absent.
+//
+// Entries are kept verbatim, including unparseable ones: their POSITION is
+// what carries meaning here, so silently dropping a malformed hop would
+// shift every index and could hand back an attacker-supplied entry.
+func forwardedChain(r *http.Request) []string {
+	raw := r.Header.Get("X-Forwarded-For")
+	if strings.TrimSpace(raw) == "" {
+		// Some proxies set only X-Real-IP, which by construction is a single
+		// hop — the address that proxy saw.
+		if real := strings.TrimSpace(r.Header.Get("X-Real-IP")); real != "" {
+			return []string{real}
+		}
+		return nil
+	}
+	parts := strings.Split(raw, ",")
+	out := make([]string, 0, len(parts))
+	for _, p := range parts {
+		if p = strings.TrimSpace(p); p != "" {
+			out = append(out, p)
+		}
+	}
+	return out
+}
+
+// hopsOf reads a trusted-depth accessor, treating a nil one as "trust
+// nothing". Test contexts and any future caller that hasn't wired the
+// settings service get the safe reading rather than a panic.
+func hopsOf(fn func() int) int {
+	if fn == nil {
+		return 0
+	}
+	return fn()
+}
+
+// hostOf strips the port from a RemoteAddr, tolerating values that have none.
+func hostOf(remoteAddr string) string {
+	host, _, err := net.SplitHostPort(remoteAddr)
+	if err != nil {
+		return strings.TrimSpace(remoteAddr)
+	}
+	return host
+}

internal/auth/clientip_test.go

@@ -0,0 +1,170 @@
+package auth
+
+import (
+	"net/http"
+	"testing"
+)
+
+// The hop arithmetic is the whole feature, so the table is written as
+// deployment topologies rather than abstract inputs.
+func TestClientIP(t *testing.T) {
+	tests := []struct {
+		name       string
+		hops       int
+		remoteAddr string
+		forwarded  string
+		realIP     string
+		want       string
+	}{
+		{
+			name:       "no proxy configured, socket peer wins",
+			hops:       0,
+			remoteAddr: "203.0.113.5:51234",
+			want:       "203.0.113.5",
+		},
+		{
+			// hops 0 is the setting for a directly-exposed instance, and it
+			// must make forged headers inert.
+			name:       "hops 0 ignores a forged forwarded header",
+			hops:       0,
+			remoteAddr: "203.0.113.5:51234",
+			forwarded:  "198.51.100.99",
+			want:       "203.0.113.5",
+		},
+		{
+			// The common case: one TLS-terminating proxy. Note RemoteAddr is
+			// PUBLIC here — a proxy on its own host — which the previous
+			// private-range heuristic got wrong.
+			name:       "one proxy on a public address yields the client",
+			hops:       1,
+			remoteAddr: "203.0.113.200:40000",
+			forwarded:  "198.51.100.7",
+			want:       "198.51.100.7",
+		},
+		{
+			name:       "one proxy on a private address yields the client",
+			hops:       1,
+			remoteAddr: "172.18.0.1:40000",
+			forwarded:  "198.51.100.7",
+			want:       "198.51.100.7",
+		},
+		{
+			// client -> Cloudflare -> own proxy -> app.
+			// Trusting only our own proxy, the honest answer is Cloudflare:
+			// that's the address our proxy actually observed.
+			name:       "cdn chain with hops 1 stops at the cdn",
+			hops:       1,
+			remoteAddr: "172.18.0.1:40000",
+			forwarded:  "198.51.100.7, 203.0.113.50",
+			want:       "203.0.113.50",
+		},
+		{
+			// Same chain, both hops trusted — now we reach the real client.
+			name:       "cdn chain with hops 2 reaches the client",
+			hops:       2,
+			remoteAddr: "172.18.0.1:40000",
+			forwarded:  "198.51.100.7, 203.0.113.50",
+			want:       "198.51.100.7",
+		},
+		{
+			// A client prepending a lie is only reachable if the operator
+			// over-counts their proxies; at the correct depth it's skipped.
+			name:       "forged prefix is not reached at the correct depth",
+			hops:       1,
+			remoteAddr: "172.18.0.1:40000",
+			forwarded:  "1.2.3.4, 198.51.100.7",
+			want:       "198.51.100.7",
+		},
+		{
+			// The documented mis-set failure, pinned so it stays a KNOWN
+			// consequence rather than a surprise: depth deeper than the real
+			// chain reads attacker-supplied input.
+			name:       "hops set deeper than the chain clamps to the leftmost entry",
+			hops:       5,
+			remoteAddr: "172.18.0.1:40000",
+			forwarded:  "1.2.3.4, 198.51.100.7",
+			want:       "1.2.3.4",
+		},
+		{
+			name:       "no forwarding header falls back to the socket peer",
+			hops:       1,
+			remoteAddr: "203.0.113.5:51234",
+			want:       "203.0.113.5",
+		},
+		{
+			name:       "x-real-ip used when forwarded-for is absent",
+			hops:       1,
+			remoteAddr: "172.18.0.1:40000",
+			realIP:     "198.51.100.7",
+			want:       "198.51.100.7",
+		},
+		{
+			name:       "forwarded-for wins over x-real-ip when both present",
+			hops:       1,
+			remoteAddr: "172.18.0.1:40000",
+			forwarded:  "198.51.100.7",
+			realIP:     "1.2.3.4",
+			want:       "198.51.100.7",
+		},
+		{
+			// Positions are preserved, so a garbage hop can be selected —
+			// in which case we fall back rather than return nonsense.
+			name:       "unparseable selected entry falls back to the socket peer",
+			hops:       1,
+			remoteAddr: "172.18.0.1:40000",
+			forwarded:  "198.51.100.7, not-an-ip",
+			want:       "172.18.0.1",
+		},
+		{
+			name:       "ipv6 client through one proxy",
+			hops:       1,
+			remoteAddr: "[fd00::1]:40000",
+			forwarded:  "2001:db8::5",
+			want:       "2001:db8::5",
+		},
+		{
+			name:       "ipv6 socket peer without proxy",
+			hops:       0,
+			remoteAddr: "[2001:db8::1]:51234",
+			want:       "2001:db8::1",
+		},
+		{
+			name:       "remote addr without a port is tolerated",
+			hops:       0,
+			remoteAddr: "203.0.113.5",
+			want:       "203.0.113.5",
+		},
+		{
+			name:       "empty remote addr yields empty",
+			hops:       1,
+			remoteAddr: "",
+			want:       "",
+		},
+		{
+			name:       "whitespace-only forwarded header is treated as absent",
+			hops:       1,
+			remoteAddr: "172.18.0.1:40000",
+			forwarded:  "   ",
+			want:       "172.18.0.1",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			r, err := http.NewRequest(http.MethodGet, "/api/me/sessions", nil)
+			if err != nil {
+				t.Fatalf("NewRequest: %v", err)
+			}
+			r.RemoteAddr = tc.remoteAddr
+			if tc.forwarded != "" {
+				r.Header.Set("X-Forwarded-For", tc.forwarded)
+			}
+			if tc.realIP != "" {
+				r.Header.Set("X-Real-IP", tc.realIP)
+			}
+			if got := ClientIP(r, tc.hops); got != tc.want {
+				t.Errorf("ClientIP(hops=%d) = %q, want %q", tc.hops, got, tc.want)
+			}
+		})
+	}
+}

internal/auth/middleware.go

@@ -3,12 +3,17 @@ package auth
 import (
 	"context"
 
+	"github.com/jackc/pgx/v5/pgtype"
+
 	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
 )
 
 type ctxKey int
 
-const userCtxKey ctxKey = 1
+const (
+	userCtxKey      ctxKey = 1
+	sessionIDCtxKey ctxKey = 2
+)
 
 // UserFromContext returns the authenticated user placed in context by
 // RequireUser. Returns false when RequireUser has not run (e.g. in tests that
@@ -17,3 +22,13 @@ func UserFromContext(ctx context.Context) (dbq.User, bool) {
 	u, ok := ctx.Value(userCtxKey).(dbq.User)
 	return u, ok
 }
+
+// SessionIDFromContext returns the id of the session that authenticated this
+// request. The active-sessions surface needs it for the two things it can't
+// do from the user alone: mark which row is "this device", and exclude that
+// row from "log out everywhere else" so the action doesn't sign the caller
+// out of the page they invoked it from.
+func SessionIDFromContext(ctx context.Context) (pgtype.UUID, bool) {
+	id, ok := ctx.Value(sessionIDCtxKey).(pgtype.UUID)
+	return id, ok
+}

internal/auth/session.go

@@ -56,7 +56,13 @@ const SessionCookieName = "minstrel_session"
 // bearer header and puts the dbq.User in request context via userCtxKey.
 // Requests without a valid session return 401 with no body so callers don't
 // leak whether the username existed (matches the /rest/* auth posture).
-func RequireUser(pool *pgxpool.Pool) func(http.Handler) http.Handler {
+//
+// trustedHops supplies the reverse-proxy depth used to record the session's
+// current address (#2453). It's a func rather than an int because the value
+// is operator-editable at runtime and this middleware is constructed once at
+// boot — reading it per request is what makes an admin change take effect
+// without a restart. Passing nil means "trust nothing", i.e. the socket peer.
+func RequireUser(pool *pgxpool.Pool, trustedHops func() int) func(http.Handler) http.Handler {
 	return func(next http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 			token := sessionTokenFromRequest(r)
@@ -98,10 +104,17 @@ func RequireUser(pool *pgxpool.Pool) func(http.Handler) http.Handler {
 			}
 			// Best-effort last-seen update. A failure here shouldn't fail the
 			// request; the session is still valid and this is observability.
-			if err := q.TouchSessionLastSeen(r.Context(), sess.ID); err != nil {
+			// last_ip rides the same UPDATE — a session whose address has
+			// moved since it was issued is the signal the active-sessions
+			// surface exists to show, and it costs nothing extra here.
+			if err := q.TouchSessionLastSeen(r.Context(), dbq.TouchSessionLastSeenParams{
+				ID:     sess.ID,
+				LastIp: ClientIP(r, hopsOf(trustedHops)),
+			}); err != nil {
 				slog.Warn("api: touch session last_seen failed", "err", err)
 			}
 			ctx := context.WithValue(r.Context(), userCtxKey, user)
+			ctx = context.WithValue(ctx, sessionIDCtxKey, sess.ID)
 			next.ServeHTTP(w, r.WithContext(ctx))
 		})
 	}
@@ -112,6 +125,12 @@ func RequireUser(pool *pgxpool.Pool) func(http.Handler) http.Handler {
 // middleware. Do not use this outside _test.go files.
 func UserCtxKeyForTest() any { return userCtxKey }
 
+// SessionIDCtxKeyForTest is the sibling of UserCtxKeyForTest for the session
+// id, so handler tests can exercise the current-session logic (which row is
+// "this device", which one logout-others must spare) without standing up the
+// middleware. Do not use this outside _test.go files.
+func SessionIDCtxKeyForTest() any { return sessionIDCtxKey }
+
 // OptionalUser is RequireUser's permissive sibling: it resolves the caller
 // from the session cookie or bearer header and attaches the user to context
 // when present + valid, but does NOT 401 on absence. The downstream handler
@@ -153,6 +172,7 @@ func OptionalUser(pool *pgxpool.Pool, logger *slog.Logger) func(http.Handler) ht
 				return
 			}
 			ctx := context.WithValue(r.Context(), userCtxKey, user)
+			ctx = context.WithValue(ctx, sessionIDCtxKey, sess.ID)
 			next.ServeHTTP(w, r.WithContext(ctx))
 		})
 	}

internal/auth/session_test.go

@@ -57,7 +57,7 @@ func TestRequireUser_RejectsWhenNoCookieOrBearer(t *testing.T) {
 	next := http.HandlerFunc(func(_ http.ResponseWriter, _ *http.Request) {
 		t.Fatal("handler must not be called")
 	})
-	h := RequireUser(nil)(next)
+	h := RequireUser(nil, nil)(next)
 
 	req := httptest.NewRequest(http.MethodGet, "/api/me", nil)
 	w := httptest.NewRecorder()

internal/db/dbq/models.go

@@ -381,6 +381,11 @@ type LidarrRequest struct {
 	LidarrAddConfirmedAt pgtype.Timestamptz
 }
 
+type NetworkSetting struct {
+	ID               bool
+	TrustedProxyHops int32
+}
+
 type PasswordReset struct {
 	Token     string
 	UserID    pgtype.UUID
@@ -514,6 +519,8 @@ type Session struct {
 	UserAgent  string
 	CreatedAt  pgtype.Timestamptz
 	LastSeenAt pgtype.Timestamptz
+	CreatedIp  string
+	LastIp     string
 }
 
 type SkipEvent struct {

internal/db/dbq/network_settings.sql.go

@@ -0,0 +1,32 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: network_settings.sql
+
+package dbq
+
+import (
+	"context"
+)
+
+const getNetworkSettings = `-- name: GetNetworkSettings :one
+SELECT id, trusted_proxy_hops FROM network_settings WHERE id = true
+`
+
+func (q *Queries) GetNetworkSettings(ctx context.Context) (NetworkSetting, error) {
+	row := q.db.QueryRow(ctx, getNetworkSettings)
+	var i NetworkSetting
+	err := row.Scan(&i.ID, &i.TrustedProxyHops)
+	return i, err
+}
+
+const updateTrustedProxyHops = `-- name: UpdateTrustedProxyHops :one
+UPDATE network_settings SET trusted_proxy_hops = $1 WHERE id = true RETURNING id, trusted_proxy_hops
+`
+
+func (q *Queries) UpdateTrustedProxyHops(ctx context.Context, trustedProxyHops int32) (NetworkSetting, error) {
+	row := q.db.QueryRow(ctx, updateTrustedProxyHops, trustedProxyHops)
+	var i NetworkSetting
+	err := row.Scan(&i.ID, &i.TrustedProxyHops)
+	return i, err
+}

internal/db/dbq/sessions.sql.go

@@ -11,6 +11,25 @@ import (
 	"github.com/jackc/pgx/v5/pgtype"
 )
 
+const deleteOtherSessionsForUser = `-- name: DeleteOtherSessionsForUser :execrows
+DELETE FROM sessions WHERE user_id = $1 AND id <> $2
+`
+
+type DeleteOtherSessionsForUserParams struct {
+	UserID pgtype.UUID
+	ID     pgtype.UUID
+}
+
+// "Log out everywhere else." Excludes the caller's own session so the action
+// doesn't log them out of the page they just used to invoke it.
+func (q *Queries) DeleteOtherSessionsForUser(ctx context.Context, arg DeleteOtherSessionsForUserParams) (int64, error) {
+	result, err := q.db.Exec(ctx, deleteOtherSessionsForUser, arg.UserID, arg.ID)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected(), nil
+}
+
 const deleteSession = `-- name: DeleteSession :exec
 DELETE FROM sessions WHERE id = $1
 `
@@ -29,8 +48,29 @@ func (q *Queries) DeleteSessionByTokenHash(ctx context.Context, tokenHash []byte
 	return err
 }
 
+const deleteSessionForUser = `-- name: DeleteSessionForUser :execrows
+DELETE FROM sessions WHERE id = $1 AND user_id = $2
+`
+
+type DeleteSessionForUserParams struct {
+	ID     pgtype.UUID
+	UserID pgtype.UUID
+}
+
+// Scoped by user_id, not just id (rule #47). Keyed on the id alone, any
+// household member could revoke another member's session by guessing a uuid.
+// execrows lets the handler answer 404 rather than a false 204 when the row
+// isn't theirs.
+func (q *Queries) DeleteSessionForUser(ctx context.Context, arg DeleteSessionForUserParams) (int64, error) {
+	result, err := q.db.Exec(ctx, deleteSessionForUser, arg.ID, arg.UserID)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected(), nil
+}
+
 const getSessionByTokenHash = `-- name: GetSessionByTokenHash :one
-SELECT id, user_id, token_hash, user_agent, created_at, last_seen_at FROM sessions WHERE token_hash = $1
+SELECT id, user_id, token_hash, user_agent, created_at, last_seen_at, created_ip, last_ip FROM sessions WHERE token_hash = $1
 `
 
 func (q *Queries) GetSessionByTokenHash(ctx context.Context, tokenHash []byte) (Session, error) {
@@ -43,24 +83,35 @@ func (q *Queries) GetSessionByTokenHash(ctx context.Context, tokenHash []byte) (
 		&i.UserAgent,
 		&i.CreatedAt,
 		&i.LastSeenAt,
+		&i.CreatedIp,
+		&i.LastIp,
 	)
 	return i, err
 }
 
 const insertSession = `-- name: InsertSession :one
-INSERT INTO sessions (user_id, token_hash, user_agent)
-VALUES ($1, $2, $3)
-RETURNING id, user_id, token_hash, user_agent, created_at, last_seen_at
+INSERT INTO sessions (user_id, token_hash, user_agent, created_ip, last_ip)
+VALUES ($1, $2, $3, $4, $4)
+RETURNING id, user_id, token_hash, user_agent, created_at, last_seen_at, created_ip, last_ip
 `
 
 type InsertSessionParams struct {
 	UserID    pgtype.UUID
 	TokenHash []byte
 	UserAgent string
+	Ip        string
 }
 
+// created_ip and last_ip start equal: at issue time the origin IS the current
+// location. They diverge as the session is used from elsewhere, which is what
+// makes a stolen token visible in the active-sessions surface.
 func (q *Queries) InsertSession(ctx context.Context, arg InsertSessionParams) (Session, error) {
-	row := q.db.QueryRow(ctx, insertSession, arg.UserID, arg.TokenHash, arg.UserAgent)
+	row := q.db.QueryRow(ctx, insertSession,
+		arg.UserID,
+		arg.TokenHash,
+		arg.UserAgent,
+		arg.Ip,
+	)
 	var i Session
 	err := row.Scan(
 		&i.ID,
@@ -69,15 +120,57 @@ func (q *Queries) InsertSession(ctx context.Context, arg InsertSessionParams) (S
 		&i.UserAgent,
 		&i.CreatedAt,
 		&i.LastSeenAt,
+		&i.CreatedIp,
+		&i.LastIp,
 	)
 	return i, err
 }
 
-const touchSessionLastSeen = `-- name: TouchSessionLastSeen :exec
-UPDATE sessions SET last_seen_at = now() WHERE id = $1
+const listSessionsForUser = `-- name: ListSessionsForUser :many
+SELECT id, user_id, token_hash, user_agent, created_at, last_seen_at, created_ip, last_ip FROM sessions WHERE user_id = $1 ORDER BY last_seen_at DESC
 `
 
-func (q *Queries) TouchSessionLastSeen(ctx context.Context, id pgtype.UUID) error {
-	_, err := q.db.Exec(ctx, touchSessionLastSeen, id)
+// Most-recently-active first: the row a user is most likely to act on is the
+// one that moved last, and an unfamiliar entry at the top is the alarm.
+func (q *Queries) ListSessionsForUser(ctx context.Context, userID pgtype.UUID) ([]Session, error) {
+	rows, err := q.db.Query(ctx, listSessionsForUser, userID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []Session
+	for rows.Next() {
+		var i Session
+		if err := rows.Scan(
+			&i.ID,
+			&i.UserID,
+			&i.TokenHash,
+			&i.UserAgent,
+			&i.CreatedAt,
+			&i.LastSeenAt,
+			&i.CreatedIp,
+			&i.LastIp,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const touchSessionLastSeen = `-- name: TouchSessionLastSeen :exec
+UPDATE sessions SET last_seen_at = now(), last_ip = $2 WHERE id = $1
+`
+
+type TouchSessionLastSeenParams struct {
+	ID     pgtype.UUID
+	LastIp string
+}
+
+func (q *Queries) TouchSessionLastSeen(ctx context.Context, arg TouchSessionLastSeenParams) error {
+	_, err := q.db.Exec(ctx, touchSessionLastSeen, arg.ID, arg.LastIp)
 	return err
 }

internal/db/migrations/0052_session_ips.down.sql

@@ -0,0 +1,3 @@
+ALTER TABLE sessions
+    DROP COLUMN created_ip,
+    DROP COLUMN last_ip;

internal/db/migrations/0052_session_ips.up.sql

@@ -0,0 +1,19 @@
+-- Session provenance for the active-sessions surface (#370).
+--
+-- TWO addresses, not one, and the pair is the point: a session created at
+-- home and now being used from somewhere else is the shape of a stolen
+-- token. A single "current IP" column can't express that, and a single
+-- "origin IP" column goes stale the moment the token moves.
+--
+-- text rather than inet, matching user_agent directly above: these are
+-- stored to be displayed, never queried by subnet, and inet round-trips
+-- through pgx/sqlc as a netip.Prefix that renders as "1.2.3.4/32" and would
+-- need unwrapping at every display site.
+--
+-- DEFAULT '' rather than NULL so existing rows — and any future insert that
+-- genuinely can't determine an address — stay renderable without a null
+-- check at every call site. The UI reads empty as "unknown" rather than
+-- inventing a value.
+ALTER TABLE sessions
+    ADD COLUMN created_ip text NOT NULL DEFAULT '',
+    ADD COLUMN last_ip    text NOT NULL DEFAULT '';

internal/db/migrations/0053_network_settings.down.sql

@@ -0,0 +1 @@
+DROP TABLE network_settings;

internal/db/migrations/0053_network_settings.up.sql

@@ -0,0 +1,33 @@
+-- Trusted reverse-proxy depth for client-IP extraction (#2453).
+--
+-- X-Forwarded-For grows left-to-right: each proxy APPENDS the peer it
+-- received the request from. For client -> CDN -> own-proxy -> Minstrel the
+-- app sees XFF = [client, CDN] with RemoteAddr = own-proxy. So the real
+-- client sits at XFF[len - hops], where hops counts the proxies you trust:
+--
+--   0  no proxy in front — use the socket peer, ignore XFF entirely
+--   1  one reverse proxy (nginx / Caddy / Traefik terminating TLS)
+--   2  a CDN in front of your own proxy (Cloudflare -> nginx -> Minstrel)
+--
+-- Default 1: a publicly reachable Minstrel needs a TLS terminator in front of
+-- it, and recording that terminator's own address for every session makes the
+-- active-sessions surface (#370) useless — created_ip and last_ip would both
+-- be the proxy, so the "address changed" signal could never fire.
+--
+-- The cost, stated on the admin card rather than buried: hops >= 1 DECLARES
+-- that a proxy exists. If one doesn't, a client can forge X-Forwarded-For and
+-- choose what its own session row shows, which defeats exactly the compromise
+-- detection #370 exists for. That is inherent to the trusted-hop model, which
+-- is why 0 is a first-class setting and not a hidden escape hatch.
+--
+-- Upper bound 10 guards a typo turning into "trust the whole header"; no real
+-- deployment chains ten proxies.
+CREATE TABLE network_settings (
+    id                 boolean PRIMARY KEY DEFAULT true,
+    trusted_proxy_hops int NOT NULL DEFAULT 1,
+    CONSTRAINT network_settings_singleton CHECK (id = true),
+    CONSTRAINT network_settings_hops_range
+        CHECK (trusted_proxy_hops >= 0 AND trusted_proxy_hops <= 10)
+);
+
+INSERT INTO network_settings (id) VALUES (true) ON CONFLICT (id) DO NOTHING;

internal/db/queries/network_settings.sql

@@ -0,0 +1,5 @@
+-- name: GetNetworkSettings :one
+SELECT * FROM network_settings WHERE id = true;
+
+-- name: UpdateTrustedProxyHops :one
+UPDATE network_settings SET trusted_proxy_hops = $1 WHERE id = true RETURNING *;

internal/db/queries/sessions.sql

@@ -1,16 +1,36 @@
 -- name: InsertSession :one
-INSERT INTO sessions (user_id, token_hash, user_agent)
-VALUES ($1, $2, $3)
+-- created_ip and last_ip start equal: at issue time the origin IS the current
+-- location. They diverge as the session is used from elsewhere, which is what
+-- makes a stolen token visible in the active-sessions surface.
+INSERT INTO sessions (user_id, token_hash, user_agent, created_ip, last_ip)
+VALUES ($1, $2, $3, sqlc.arg(ip), sqlc.arg(ip))
 RETURNING *;
 
 -- name: GetSessionByTokenHash :one
 SELECT * FROM sessions WHERE token_hash = $1;
 
 -- name: TouchSessionLastSeen :exec
-UPDATE sessions SET last_seen_at = now() WHERE id = $1;
+UPDATE sessions SET last_seen_at = now(), last_ip = $2 WHERE id = $1;
+
+-- name: ListSessionsForUser :many
+-- Most-recently-active first: the row a user is most likely to act on is the
+-- one that moved last, and an unfamiliar entry at the top is the alarm.
+SELECT * FROM sessions WHERE user_id = $1 ORDER BY last_seen_at DESC;
 
 -- name: DeleteSession :exec
 DELETE FROM sessions WHERE id = $1;
 
 -- name: DeleteSessionByTokenHash :exec
 DELETE FROM sessions WHERE token_hash = $1;
+
+-- name: DeleteSessionForUser :execrows
+-- Scoped by user_id, not just id (rule #47). Keyed on the id alone, any
+-- household member could revoke another member's session by guessing a uuid.
+-- execrows lets the handler answer 404 rather than a false 204 when the row
+-- isn't theirs.
+DELETE FROM sessions WHERE id = $1 AND user_id = $2;
+
+-- name: DeleteOtherSessionsForUser :execrows
+-- "Log out everywhere else." Excludes the caller's own session so the action
+-- doesn't log them out of the page they just used to invoke it.
+DELETE FROM sessions WHERE user_id = $1 AND id <> $2;

internal/netsettings/service.go

@@ -0,0 +1,108 @@
+// Package netsettings holds the DB-backed network settings the request path
+// needs. Today that's the trusted reverse-proxy depth used to pull a real
+// client address out of X-Forwarded-For (#2453).
+//
+// Values are cached under an RWMutex and refreshed on write. That isn't an
+// optimisation: auth.ClientIP runs in the RequireUser middleware for every
+// authenticated request, so a per-request query here would put the database
+// on the critical path of the entire API.
+package netsettings
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"sync"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+)
+
+const (
+	// DefaultTrustedProxyHops mirrors migration 0053's column default. One
+	// proxy, because anything publicly reachable needs a TLS terminator in
+	// front of it.
+	DefaultTrustedProxyHops = 1
+	// MaxTrustedProxyHops mirrors the CHECK in migration 0053.
+	MaxTrustedProxyHops = 10
+)
+
+// ErrHopsOutOfRange is returned by SetHops for values the CHECK would reject,
+// so the API layer can answer 400 instead of surfacing a constraint violation.
+var ErrHopsOutOfRange = errors.New("trusted proxy hops must be between 0 and 10")
+
+// Service caches the network settings and owns their persistence.
+type Service struct {
+	pool   *pgxpool.Pool
+	logger *slog.Logger
+
+	mu   sync.RWMutex
+	hops int
+}
+
+// New loads the settings once and caches them.
+//
+// It ALWAYS returns a usable Service, even alongside a non-nil error. The
+// value it holds sits on the authenticated request path, so a boot-time
+// database hiccup must degrade to the default rather than take every request
+// down with it (rule #131). The error is returned so the caller can log that
+// the cache holds a default rather than stored state.
+func New(ctx context.Context, pool *pgxpool.Pool, logger *slog.Logger) (*Service, error) {
+	s := &Service{pool: pool, logger: logger, hops: DefaultTrustedProxyHops}
+	if pool == nil {
+		return s, nil
+	}
+	row, err := dbq.New(pool).GetNetworkSettings(ctx)
+	if err != nil {
+		return s, err
+	}
+	s.hops = int(row.TrustedProxyHops)
+	return s, nil
+}
+
+// Hops returns the cached trusted-proxy depth.
+//
+// Nil-safe: test contexts construct routers without this service, and a
+// missing setting should mean "trust nothing" rather than a panic in
+// middleware.
+func (s *Service) Hops() int {
+	if s == nil {
+		return 0
+	}
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.hops
+}
+
+// SetHops persists a new depth and refreshes the cache, so an admin change
+// takes effect on the next request with no restart (rule #25).
+func (s *Service) SetHops(ctx context.Context, hops int) error {
+	// Range first, availability second. The argument is wrong regardless of
+	// whether the database is reachable, and the distinction is user-visible:
+	// this ordering answers 400 for a bad value, where the reverse would
+	// report 500 and blame the server for the caller's input.
+	if hops < 0 || hops > MaxTrustedProxyHops {
+		return ErrHopsOutOfRange
+	}
+	if s == nil || s.pool == nil {
+		// Mirrors Hops()'s nil-tolerance: handlers can be constructed without
+		// this service in tests, and a write attempt there should be an error
+		// rather than a panic in an HTTP handler.
+		return errors.New("network settings unavailable")
+	}
+	row, err := dbq.New(s.pool).UpdateTrustedProxyHops(ctx, int32(hops))
+	if err != nil {
+		return err
+	}
+	s.mu.Lock()
+	s.hops = int(row.TrustedProxyHops)
+	s.mu.Unlock()
+	// Worth a line in the log: this changes how much of a client-supplied
+	// header the server believes, so an operator debugging odd addresses in
+	// the sessions list wants to see when it last moved.
+	if s.logger != nil {
+		s.logger.Info("netsettings: trusted proxy hops updated", "hops", hops)
+	}
+	return nil
+}

internal/netsettings/service_test.go

@@ -0,0 +1,55 @@
+package netsettings
+
+import (
+	"context"
+	"errors"
+	"testing"
+)
+
+// A nil service reaches middleware in test routers and anywhere the settings
+// aren't wired. It must read as "trust nothing" rather than panic — the
+// alternative is a nil dereference inside RequireUser, on every request.
+func TestHops_NilServiceTrustsNothing(t *testing.T) {
+	var s *Service
+	if got := s.Hops(); got != 0 {
+		t.Errorf("(*Service)(nil).Hops() = %d, want 0", got)
+	}
+}
+
+func TestNew_NilPoolYieldsDefault(t *testing.T) {
+	s, err := New(context.Background(), nil, nil)
+	if err != nil {
+		t.Fatalf("New with nil pool: %v", err)
+	}
+	if s == nil {
+		t.Fatal("New returned nil service")
+	}
+	if got := s.Hops(); got != DefaultTrustedProxyHops {
+		t.Errorf("Hops() = %d, want %d", got, DefaultTrustedProxyHops)
+	}
+}
+
+// Range is rejected before the query so the API answers 400 rather than
+// surfacing a CHECK violation as a 500.
+func TestSetHops_RejectsOutOfRange(t *testing.T) {
+	s, _ := New(context.Background(), nil, nil)
+	for _, hops := range []int{-1, MaxTrustedProxyHops + 1, 999} {
+		if err := s.SetHops(context.Background(), hops); !errors.Is(err, ErrHopsOutOfRange) {
+			t.Errorf("SetHops(%d) error = %v, want ErrHopsOutOfRange", hops, err)
+		}
+	}
+}
+
+// In-range values with no pool must still fail, and must not mutate the
+// cache — a write that didn't persist reporting success would leave the
+// running process disagreeing with the database.
+func TestSetHops_NoPoolFailsWithoutMutatingCache(t *testing.T) {
+	s, _ := New(context.Background(), nil, nil)
+	before := s.Hops()
+	if err := s.SetHops(context.Background(), 2); err == nil {
+		t.Error("SetHops with nil pool returned nil error")
+	}
+	if after := s.Hops(); after != before {
+		t.Errorf("cache changed from %d to %d despite a failed write", before, after)
+	}
+}

internal/server/server.go

@@ -25,6 +25,7 @@ import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/lidarrquarantine"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/lidarrrequests"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/mailer"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/netsettings"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/playevents"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/playlists"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/recsettings"
@@ -164,13 +165,21 @@ func (s *Server) Router() http.Handler {
 				s.Logger.Error("server: recsettings boot failed", "err", err)
 			}
 		}
-		api.Mount(r, s.Pool, s.Logger, writer, s.RecommendationCfg, recSettings, lidarrCfg, lidarrReqs, lidarrQuar, tracksSvc, playlistsSvc, s.CoverEnricher, s.CoverSettings, s.TagSettings, s.LibraryScanner, s.ScanCfg, s.DataDir, smtpSender, bus, s.PlaylistScheduler, s.StreamSecret)
+		// Cached trusted-proxy depth (#2453). Constructed here rather than in
+		// main.go because nothing else needs it at boot, and New always hands
+		// back a usable service — a DB hiccup degrades to the default rather
+		// than breaking the authenticated request path that reads it.
+		netSettings, err := netsettings.New(context.Background(), s.Pool, s.Logger)
+		if err != nil {
+			s.Logger.Error("server: netsettings boot failed, using default hops", "err", err)
+		}
+		api.Mount(r, s.Pool, s.Logger, writer, s.RecommendationCfg, recSettings, lidarrCfg, lidarrReqs, lidarrQuar, tracksSvc, playlistsSvc, s.CoverEnricher, s.CoverSettings, s.TagSettings, s.LibraryScanner, s.ScanCfg, s.DataDir, smtpSender, bus, s.PlaylistScheduler, s.StreamSecret, netSettings)
 		// /api/admin/scan is the only admin route owned by the server package
 		// (it needs the Scanner). Register it as a single inline-middleware
 		// route — using r.Route("/api/admin", ...) here would create a second
 		// subtree that shadows every admin route registered by api.Mount.
 		if s.Scanner != nil {
-			r.With(auth.RequireUser(s.Pool), auth.RequireAdmin()).
+			r.With(auth.RequireUser(s.Pool, netSettings.Hops), auth.RequireAdmin()).
 				Post("/api/admin/scan", s.handleAdminScan)
 		}
 		subsonic.Mount(r, s.Pool, s.Logger, s.SubsonicCfg, writer)

web/src/app.html

@@ -2,7 +2,19 @@
 <html lang="en">
   <head>
     <meta charset="utf-8" />
-    <link rel="icon" href="%sveltekit.assets%/favicon.png" />
+    <!--
+      SVG first: it flips the M with the viewer's colour scheme, which the PNG
+      can't. The PNG is the fallback for browsers without SVG-favicon support
+      and is plated for the same reason apple-touch-icon is — see brand/.
+      Ordering matters: browsers take the last icon they understand, so the
+      PNG must come FIRST or it wins over the SVG in Chrome.
+    -->
+    <link rel="icon" href="%sveltekit.assets%/favicon.png" sizes="32x32" />
+    <link rel="icon" href="%sveltekit.assets%/brand/favicon.svg" type="image/svg+xml" />
+    <link rel="apple-touch-icon" href="%sveltekit.assets%/apple-touch-icon.png" />
+    <!-- Obsidian: matches --fs-surface-page so mobile browser chrome doesn't
+         seam against the app's own background. -->
+    <meta name="theme-color" content="#14171A" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>Minstrel</title>
     <script>

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/api/me.ts

@@ -62,3 +62,33 @@ export async function regenerateAPIToken(): Promise<APITokenResponse> {
 export async function putMyTimezone(timezone: string): Promise<void> {
   await api.put<void>('/api/me/timezone', { timezone });
 }
+
+// Active sessions (#370) ---------------------------------------------------
+
+// created_ip is frozen at issue time; last_ip moves with the session. The
+// pair is the signal — the same device string arriving from an address you
+// don't recognise is what a stolen token looks like from the inside.
+export type ActiveSession = {
+  id: string;
+  user_agent: string;
+  created_ip: string;
+  last_ip: string;
+  created_at: string;
+  last_seen_at: string;
+  current: boolean;
+};
+
+export async function listSessions(): Promise<ActiveSession[]> {
+  return api.get<ActiveSession[]>('/api/me/sessions');
+}
+
+export async function revokeSession(id: string): Promise<void> {
+  await api.del(`/api/me/sessions/${id}`);
+}
+
+// Returns how many were ended. The server excludes the caller's own session,
+// so this never signs you out of the page you pressed it on.
+export async function revokeOtherSessions(): Promise<number> {
+  const body = await api.post<{ revoked: number }>('/api/me/sessions/logout-others', {});
+  return body.revoked;
+}

web/src/lib/components/ActiveSessions.svelte

@@ -0,0 +1,227 @@
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import { MonitorSmartphone, TriangleAlert } from 'lucide-svelte';
+  import {
+    listSessions,
+    revokeSession,
+    revokeOtherSessions,
+    type ActiveSession
+  } from '$lib/api/me';
+  import { errCode } from '$lib/api/errors';
+  import { pushToast } from '$lib/stores/toast.svelte';
+
+  // Self-contained: nothing else in the app reads this data, so it holds its
+  // own state and reloads explicitly rather than joining the query cache.
+
+  let sessions = $state<ActiveSession[] | null>(null);
+  let loadError = $state(false);
+  let busy = $state(false);
+  let confirmingLogoutOthers = $state(false);
+
+  const others = $derived((sessions ?? []).filter((s) => !s.current).length);
+
+  async function load() {
+    try {
+      sessions = await listSessions();
+      loadError = false;
+    } catch {
+      loadError = true;
+    }
+  }
+
+  onMount(load);
+
+  async function onRevoke(s: ActiveSession) {
+    busy = true;
+    try {
+      await revokeSession(s.id);
+      pushToast('Signed that device out.');
+      await load();
+    } catch (e: unknown) {
+      // Already gone — revoked from another device, or expired. Reloading
+      // shows the truth, so it isn't worth an error. The code is
+      // `session_not_found`: apierror.NotFound("session") prefixes it.
+      if (errCode(e) === 'session_not_found') {
+        await load();
+      } else {
+        pushToast("Couldn't sign that device out.", 'error');
+      }
+    } finally {
+      busy = false;
+    }
+  }
+
+  async function onLogoutOthers() {
+    busy = true;
+    try {
+      const n = await revokeOtherSessions();
+      pushToast(n === 1 ? 'Signed out 1 other device.' : `Signed out ${n} other devices.`);
+      confirmingLogoutOthers = false;
+      await load();
+    } catch {
+      pushToast("Couldn't sign the other devices out.", 'error');
+    } finally {
+      busy = false;
+    }
+  }
+
+  // Deliberately coarse. A full UA parser would be a dependency and a
+  // maintenance burden for a string whose only job is "do you recognise
+  // this?" — the IP columns carry the actual signal.
+  function describeAgent(ua: string): string {
+    if (!ua) return 'Unknown device';
+    if (/Minstrel/i.test(ua)) return 'Minstrel for Android';
+    if (/Android/i.test(ua)) return 'Android browser';
+    if (/iPhone|iPad|iOS/i.test(ua)) return 'iOS browser';
+    const browser = /Edg\//.test(ua)
+      ? 'Edge'
+      : /Firefox\//.test(ua)
+        ? 'Firefox'
+        : /Chrome\//.test(ua)
+          ? 'Chrome'
+          : /Safari\//.test(ua)
+            ? 'Safari'
+            : '';
+    const os = /Windows/.test(ua)
+      ? 'Windows'
+      : /Mac OS X/.test(ua)
+        ? 'macOS'
+        : /Linux/.test(ua)
+          ? 'Linux'
+          : '';
+    if (browser && os) return `${browser} on ${os}`;
+    if (browser) return browser;
+    return ua.length > 40 ? `${ua.slice(0, 40)}…` : ua;
+  }
+
+  function when(iso: string): string {
+    const then = new Date(iso).getTime();
+    if (Number.isNaN(then)) return 'unknown';
+    const mins = Math.round((Date.now() - then) / 60000);
+    if (mins < 1) return 'just now';
+    if (mins < 60) return `${mins} min ago`;
+    const hours = Math.round(mins / 60);
+    if (hours < 24) return hours === 1 ? '1 hour ago' : `${hours} hours ago`;
+    const days = Math.round(hours / 24);
+    if (days < 30) return days === 1 ? 'yesterday' : `${days} days ago`;
+    return new Date(iso).toLocaleDateString();
+  }
+
+  // The reason IP is stored at all. Rather than making someone eyeball two
+  // addresses per row, say plainly when a session is being used from
+  // somewhere other than where it was created.
+  function hasMoved(s: ActiveSession): boolean {
+    return !!s.created_ip && !!s.last_ip && s.created_ip !== s.last_ip;
+  }
+
+  function addr(ip: string): string {
+    return ip || 'unknown';
+  }
+</script>
+
+<section class="space-y-3 rounded border border-border bg-surface p-4">
+  <h2 class="text-lg font-semibold">Active sessions</h2>
+  <p class="text-sm text-text-secondary">
+    Every device signed in to your account. If you see one you don't recognise — especially
+    one marked as having moved — sign it out and change your password.
+  </p>
+
+  {#if loadError}
+    <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>
+  {:else if sessions === null}
+    <p class="text-sm text-text-secondary">Loading…</p>
+  {:else if sessions.length === 0}
+    <!-- Practically unreachable: listing requires an authenticated request,
+         which means at least one session exists. Handled rather than assumed. -->
+    <p class="text-sm text-text-secondary">No active sessions.</p>
+  {:else}
+    <ul class="divide-y divide-border">
+      {#each sessions as s (s.id)}
+        <li class="flex items-start gap-3 py-3">
+          <MonitorSmartphone
+            size={18}
+            class="mt-0.5 flex-shrink-0 text-text-secondary"
+            aria-hidden="true"
+          />
+          <div class="min-w-0 flex-1">
+            <div class="flex flex-wrap items-center gap-2">
+              <span class="font-medium text-text-primary">{describeAgent(s.user_agent)}</span>
+              {#if s.current}
+                <span class="rounded bg-surface-hover px-1.5 py-0.5 text-xs text-text-secondary">
+                  This device
+                </span>
+              {/if}
+              {#if hasMoved(s)}
+                <span
+                  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
+                </span>
+              {/if}
+            </div>
+            <div class="text-xs text-text-secondary">
+              Last seen {when(s.last_seen_at)} from <span class="font-mono">{addr(s.last_ip)}</span>
+            </div>
+            <div class="text-xs text-text-secondary">
+              Signed in {when(s.created_at)} from <span class="font-mono">{addr(s.created_ip)}</span>
+            </div>
+          </div>
+          {#if !s.current}
+            <button
+              type="button"
+              class="flex-shrink-0 rounded border border-border px-2 py-1 text-sm
+                     hover:bg-surface-hover focus-visible:ring-2 focus-visible:ring-accent
+                     disabled:opacity-50"
+              disabled={busy}
+              onclick={() => onRevoke(s)}
+            >
+              Sign out
+            </button>
+          {/if}
+        </li>
+      {/each}
+    </ul>
+
+    {#if others > 0}
+      {#if confirmingLogoutOthers}
+        <div class="flex flex-wrap items-center gap-2">
+          <span class="text-sm text-text-secondary">
+            Sign out {others === 1 ? '1 other device' : `${others} other devices`}? You'll stay
+            signed in here.
+          </span>
+          <button
+            type="button"
+            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}
+          >
+            Sign them out
+          </button>
+          <button
+            type="button"
+            class="rounded border border-border px-3 py-1 text-sm hover:bg-surface-hover
+                   focus-visible:ring-2 focus-visible:ring-accent"
+            onclick={() => (confirmingLogoutOthers = false)}
+          >
+            Cancel
+          </button>
+        </div>
+      {:else}
+        <button
+          type="button"
+          class="rounded border border-border px-3 py-1 text-sm hover:bg-surface-hover
+                 focus-visible:ring-2 focus-visible:ring-accent disabled:opacity-50"
+          disabled={busy}
+          onclick={() => (confirmingLogoutOthers = true)}
+        >
+          Sign out all other devices
+        </button>
+      {/if}
+    {/if}
+  {/if}
+</section>

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

@@ -0,0 +1,126 @@
+import { describe, expect, test, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/svelte';
+import ActiveSessions from './ActiveSessions.svelte';
+
+const listSessions = vi.fn();
+const revokeSession = vi.fn();
+const revokeOtherSessions = vi.fn();
+
+vi.mock('$lib/api/me', () => ({
+  listSessions: (...a: unknown[]) => listSessions(...a),
+  revokeSession: (...a: unknown[]) => revokeSession(...a),
+  revokeOtherSessions: (...a: unknown[]) => revokeOtherSessions(...a)
+}));
+
+vi.mock('$lib/stores/toast.svelte', () => ({ pushToast: vi.fn() }));
+
+type Row = {
+  id: string;
+  user_agent: string;
+  created_ip: string;
+  last_ip: string;
+  created_at: string;
+  last_seen_at: string;
+  current: boolean;
+};
+
+function row(over: Partial<Row> = {}): Row {
+  return {
+    id: 'a1',
+    user_agent: 'Mozilla/5.0 (X11; Linux x86_64) Chrome/120.0',
+    created_ip: '203.0.113.1',
+    last_ip: '203.0.113.1',
+    created_at: new Date().toISOString(),
+    last_seen_at: new Date().toISOString(),
+    current: false,
+    ...over
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('ActiveSessions', () => {
+  test('flags the current session and gives it no sign-out button', async () => {
+    listSessions.mockResolvedValue([
+      row({ id: 'cur', current: true }),
+      row({ id: 'other', current: false })
+    ]);
+    render(ActiveSessions);
+
+    await screen.findByText('This device');
+    // One sign-out button, for the non-current row. Offering one on the
+    // current session would sign the user out of the page they're using.
+    await waitFor(() => {
+      expect(screen.getAllByRole('button', { name: 'Sign out' })).toHaveLength(1);
+    });
+  });
+
+  // The whole reason IP is stored: surfacing the mismatch rather than making
+  // someone compare two addresses by eye.
+  test('warns when a session is used from a different address than it was created', async () => {
+    listSessions.mockResolvedValue([
+      row({ id: 'moved', created_ip: '203.0.113.1', last_ip: '198.51.100.9' })
+    ]);
+    render(ActiveSessions);
+
+    expect(await screen.findByText('Address changed')).toBeTruthy();
+  });
+
+  test('does not warn when the address has not changed', async () => {
+    listSessions.mockResolvedValue([
+      row({ created_ip: '203.0.113.1', last_ip: '203.0.113.1' })
+    ]);
+    render(ActiveSessions);
+
+    await screen.findByText(/Signed in/);
+    expect(screen.queryByText('Address changed')).toBeNull();
+  });
+
+  test('sign-out-all-others confirms before acting', async () => {
+    listSessions.mockResolvedValue([
+      row({ id: 'cur', current: true }),
+      row({ id: 'o1' }),
+      row({ id: 'o2' })
+    ]);
+    revokeOtherSessions.mockResolvedValue(2);
+    render(ActiveSessions);
+
+    const start = await screen.findByRole('button', { name: 'Sign out all other devices' });
+    await fireEvent.click(start);
+    // First click only arms the action.
+    expect(revokeOtherSessions).not.toHaveBeenCalled();
+    expect(screen.getByText(/Sign out 2 other devices\?/)).toBeTruthy();
+
+    await fireEvent.click(screen.getByRole('button', { name: 'Sign them out' }));
+    await waitFor(() => expect(revokeOtherSessions).toHaveBeenCalledTimes(1));
+  });
+
+  test('offers no bulk action when there are no other devices', async () => {
+    listSessions.mockResolvedValue([row({ id: 'cur', current: true })]);
+    render(ActiveSessions);
+
+    await screen.findByText('This device');
+    expect(screen.queryByRole('button', { name: 'Sign out all other devices' })).toBeNull();
+  });
+
+  test('surfaces a retry when loading fails', async () => {
+    listSessions.mockRejectedValue(new Error('boom'));
+    render(ActiveSessions);
+
+    const retry = await screen.findByRole('button', { name: 'Try again' });
+    listSessions.mockResolvedValue([row({ id: 'cur', current: true })]);
+    await fireEvent.click(retry);
+    await screen.findByText('This device');
+  });
+
+  test('renders unknown for a missing address rather than an empty cell', async () => {
+    listSessions.mockResolvedValue([row({ created_ip: '', last_ip: '' })]);
+    render(ActiveSessions);
+
+    await waitFor(() => {
+      expect(screen.getAllByText('unknown').length).toBeGreaterThan(0);
+    });
+  });
+});

web/src/lib/components/MinstrelMark.svelte

@@ -0,0 +1,57 @@
+<script lang="ts">
+  // The Minstrel mark: a Didone M whose right leg is an eighth note.
+  //
+  // Inlined rather than <img src="mark.svg"> on purpose — an <img> cannot
+  // inherit currentColor, and inheriting it is the whole point: the letter
+  // takes the surrounding text colour, so it reads on both the dark and light
+  // palettes without a second asset. Parchment-on-parchment is invisible,
+  // which is exactly the bug a fixed fill would reintroduce.
+  //
+  // The note keeps the accent in both modes — one of the places the design
+  // system sanctions the accent (the wordmark).
+  //
+  // ⚠ These paths are duplicated in web/static/brand/favicon.svg and
+  // web/static/brand/mark.svg, which need literal colours instead of
+  // currentColor (a favicon has no cascade to inherit from). Change the
+  // silhouette here, change it there.
+  //
+  // aria-hidden: every current use sits directly beside the words "Minstrel",
+  // so labelling it would make a screen reader announce the name twice. A
+  // STANDALONE use would need its own label.
+  let { size = 20, class: klass = '' }: { size?: number; class?: string } = $props();
+</script>
+
+<svg
+  viewBox="202 251 902 723"
+  width={size * 902 / 723}
+  height={size}
+  class={klass}
+  aria-hidden="true"
+  focusable="false"
+>
+  <g transform="translate(0,1254) scale(0.1,-0.1)" fill-rule="evenodd">
+    <path fill="currentColor" d="M2252 9878 l3 -152 109 -22 c342 -72 492 -184 538 -405 16 -74 24
+-4823 9 -5024 -20 -266 -73 -375 -236 -484 -116 -77 -332 -150 -543 -181 -114
+-18 -107 -6 -110 -165 -1 -76 2 -143 7 -148 9 -9 2607 -11 2623 -1 14 9 10
+280 -4 291 -7 5 -49 15 -93 22 -380 60 -638 193 -720 374 -63 136 -59 -12 -61
+2247 -3 1999 -2 2054 15 2015 116 -253 646 -1520 1183 -2825 71 -173 216 -524
+322 -780 206 -494 266 -640 370 -895 97 -237 68 -210 226 -210 l135 0 23 50
+c13 27 95 212 182 410 134 307 747 1685 1015 2285 92 205 726 1599 910 2000
+65 140 126 274 137 297 22 50 52 71 74 52 12 -10 14 -266 14 -1864 l0 -1852
+-82 -7 c-347 -29 -716 -203 -973 -460 -710 -712 -343 -1645 650 -1649 453 -2
+892 184 1206 510 193 202 295 397 351 676 l23 112 0 2357 c0 1297 0 2358 1
+2358 12 0 142 -49 179 -67 342 -173 607 -545 715 -1004 85 -361 66 -801 -51
+-1215 -43 -151 -40 -173 18 -174 53 0 284 377 396 650 243 590 303 1238 163
+1754 -178 652 -643 1100 -1294 1248 -93 21 -122 22 -716 25 -707 4 -649 12
+-696 -90 -15 -34 -78 -172 -140 -307 -593 -1297 -1123 -2469 -1717 -3800 -210
+-472 -193 -437 -204 -418 -11 19 -173 423 -630 1568 -214 536 -394 986 -400
+1000 -6 14 -76 187 -156 385 -80 198 -182 452 -228 565 -46 113 -140 346 -209
+518 -205 507 -225 554 -244 568 -14 11 -209 13 -1055 14 l-1038 0 3 -152z"/>
+    <path fill="#4A6B5C" d="M8830 7450 l0 -2582 -32 6 c-517 106 -1064 -47 -1442 -405 -598 -566
+-501 -1354 196 -1598 489 -170 1134 -19 1548 363 234 217 350 418 423 736 l22
+95 3 2373 c2 1961 5 2372 16 2372 27 0 132 -41 205 -81 315 -169 569 -524 675
+-944 50 -198 60 -285 60 -525 0 -288 -27 -487 -105 -756 -34 -120 -35 -130
+-11 -143 33 -18 64 11 154 144 227 334 402 795 469 1235 37 238 34 646 -4 843
+-149 761 -637 1271 -1353 1418 -98 20 -147 23 -466 27 l-358 4 0 -2582z"/>
+  </g>
+</svg>

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,109 @@
+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);
+
+    // The address legitimately appears twice — as the detected client and
+    // inside the forwarded chain — so wait on the unique label, not the value.
+    await screen.findByText('Your address right now');
+    expect(screen.getAllByText('198.51.100.7').length).toBeGreaterThan(0);
+    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('Your address right now');
+    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('Your address right now');
+  });
+});

web/src/lib/components/QueueTrackRow.svelte

@@ -57,22 +57,41 @@
   class="flex items-center gap-2 border-b border-border px-3 py-2 h-16
          {isCurrent ? 'border-l-2 border-l-accent bg-surface-hover' : ''}"
 >
-  <button
-    type="button"
-    aria-label="Reorder track (use arrow keys)"
-    aria-keyshortcuts="ArrowUp ArrowDown"
-    onkeydown={handleHandleKeydown}
-    class="cursor-grab text-text-secondary hover:text-text-primary flex-shrink-0"
-  >
-    <GripVertical size={16} />
-  </button>
+  <!--
+    The album art is the grab surface (#2395). The grip used to occupy its own
+    column in every row; it now sits OVER the art, so it costs no horizontal
+    space at all. `use:draggable` is on the row (above), so dragging already
+    worked from anywhere — the grip's real jobs are being the visual cue and
+    the keyboard target, and both survive here.
 
-  <img
-    src={coverUrl(track.album_id)}
-    alt=""
-    onerror={(e) => ((e.currentTarget as HTMLImageElement).src = FALLBACK_COVER)}
-    class="h-10 w-10 flex-shrink-0 rounded object-cover"
-  />
+    It stays VISIBLE at rest, just quiet — it is the only thing that says this
+    list can be reordered at all, so hiding it until hover would trade the
+    operator's space complaint for a discoverability one (rule #24), and would
+    leave nothing for touch, which has no hover. The scrim only appears on
+    hover/focus so the artwork stays legible the rest of the time; the drop
+    shadow is what keeps the glyph readable over pale covers without one.
+  -->
+  <div class="relative h-10 w-10 flex-shrink-0">
+    <img
+      src={coverUrl(track.album_id)}
+      alt=""
+      onerror={(e) => ((e.currentTarget as HTMLImageElement).src = FALLBACK_COVER)}
+      class="h-10 w-10 rounded object-cover"
+    />
+    <button
+      type="button"
+      aria-label="Reorder track (use arrow keys)"
+      aria-keyshortcuts="ArrowUp ArrowDown"
+      onkeydown={handleHandleKeydown}
+      class="group absolute inset-0 flex cursor-grab items-center justify-center rounded
+             text-white/70 transition hover:bg-black/45 hover:text-white
+             focus-visible:bg-black/45 focus-visible:text-white
+             focus-visible:outline focus-visible:outline-2 focus-visible:outline-accent"
+      style="filter: drop-shadow(0 1px 1px rgb(0 0 0 / 0.9))"
+    >
+      <GripVertical size={16} />
+    </button>
+  </div>
 
   <button
     type="button"

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

@@ -94,4 +94,30 @@ describe('QueueTrackRow', () => {
     await fireEvent.keyDown(handle, { key: ' ' });
     expect(moveQueueItem).not.toHaveBeenCalled();
   });
+
+  // --- handle placement (#2395) ---
+
+  it('the reorder handle overlays the album art instead of taking its own column', () => {
+    const { container } = render(QueueTrackRow, {
+      props: { track: sampleTrack, index: 3, isCurrent: false }
+    });
+    const handle = screen.getByLabelText(/reorder track/i);
+    const art = container.querySelector('img');
+    expect(art).not.toBeNull();
+    // Sharing a parent is what "overlaid" means structurally. If someone moves
+    // the grip back into its own flex slot, this fails — which is the point:
+    // that slot cost horizontal space in every row and is why #2395 exists.
+    expect(handle.parentElement).toBe(art!.parentElement);
+  });
+
+  it('the handle is visible at rest, not hover-revealed', () => {
+    render(QueueTrackRow, { props: { track: sampleTrack, index: 3, isCurrent: false } });
+    const handle = screen.getByLabelText(/reorder track/i);
+    // Overlaying already solved the space complaint, so there is nothing to buy
+    // by hiding it — and hiding it would cost the only cue that the queue can
+    // be reordered, on touch especially, where there is no hover at all.
+    // Asserting the absence of `opacity-0` is stylistic and a bit brittle, but
+    // it is the only handle jsdom gives us on a decision worth protecting.
+    expect(handle.className).not.toMatch(/\bopacity-0\b/);
+  });
 });

web/src/lib/components/Shell.svelte

@@ -5,6 +5,7 @@
   import { user, logout } from '$lib/auth/store.svelte';
   import { player } from '$lib/player/store.svelte';
   import { appName } from '$lib/branding';
+  import MinstrelMark from './MinstrelMark.svelte';
   import PlayerBar from './PlayerBar.svelte';
   import SearchInput from './SearchInput.svelte';
 
@@ -66,7 +67,11 @@
        whenever search or the user menu grew, so the nav drifted off
        window-center. Grid pins each column to a fixed lane. -->
   <header class="grid grid-cols-3 items-center border-b border-border bg-surface px-3 md:px-4 py-2 gap-3 md:gap-6">
-    <a href="/" class="font-semibold text-sm md:text-base whitespace-nowrap justify-self-start">
+    <a
+      href="/"
+      class="flex items-center gap-2 font-semibold text-sm md:text-base whitespace-nowrap justify-self-start"
+    >
+      <MinstrelMark size={20} class="shrink-0" />
       {appName()}
     </a>
 

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

web/src/routes/settings/+page.svelte

@@ -26,6 +26,7 @@
   import { pushToast } from '$lib/stores/toast.svelte';
   import MobileAppDownload from '$lib/components/MobileAppDownload.svelte';
   import ServerVersion from '$lib/components/ServerVersion.svelte';
+  import ActiveSessions from '$lib/components/ActiveSessions.svelte';
 
   const queryClient = useQueryClient();
 
@@ -526,6 +527,11 @@
     </div>
   </section>
 
+  <!-- Sits with Password and API Token rather than near the bottom: these
+       three are the account-security group, and this is the one that tells
+       you the other two need attention. -->
+  <ActiveSessions />
+
   <section class="space-y-3 rounded border border-border bg-surface p-4">
     <h2 class="text-lg font-semibold">Library</h2>
     <ul class="space-y-2 text-sm">

web/static/brand/favicon.svg

@@ -0,0 +1,35 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="157 116 992 992">
+  <!-- Minstrel mark. The M flips with the viewer's scheme because a favicon
+       sits on browser chrome we don't control: parchment would vanish on a
+       light tab strip, obsidian on a dark one. The note keeps the accent in
+       both — teal holds against either. -->
+  <style>
+    .m { fill: #E8E4D8; }
+    @media (prefers-color-scheme: light) { .m { fill: #14171A; } }
+  </style>
+  <g transform="translate(0,1254) scale(0.1,-0.1)" fill-rule="evenodd">
+    <path class="m" d="M2252 9878 l3 -152 109 -22 c342 -72 492 -184 538 -405 16 -74 24
+-4823 9 -5024 -20 -266 -73 -375 -236 -484 -116 -77 -332 -150 -543 -181 -114
+-18 -107 -6 -110 -165 -1 -76 2 -143 7 -148 9 -9 2607 -11 2623 -1 14 9 10
+280 -4 291 -7 5 -49 15 -93 22 -380 60 -638 193 -720 374 -63 136 -59 -12 -61
+2247 -3 1999 -2 2054 15 2015 116 -253 646 -1520 1183 -2825 71 -173 216 -524
+322 -780 206 -494 266 -640 370 -895 97 -237 68 -210 226 -210 l135 0 23 50
+c13 27 95 212 182 410 134 307 747 1685 1015 2285 92 205 726 1599 910 2000
+65 140 126 274 137 297 22 50 52 71 74 52 12 -10 14 -266 14 -1864 l0 -1852
+-82 -7 c-347 -29 -716 -203 -973 -460 -710 -712 -343 -1645 650 -1649 453 -2
+892 184 1206 510 193 202 295 397 351 676 l23 112 0 2357 c0 1297 0 2358 1
+2358 12 0 142 -49 179 -67 342 -173 607 -545 715 -1004 85 -361 66 -801 -51
+-1215 -43 -151 -40 -173 18 -174 53 0 284 377 396 650 243 590 303 1238 163
+1754 -178 652 -643 1100 -1294 1248 -93 21 -122 22 -716 25 -707 4 -649 12
+-696 -90 -15 -34 -78 -172 -140 -307 -593 -1297 -1123 -2469 -1717 -3800 -210
+-472 -193 -437 -204 -418 -11 19 -173 423 -630 1568 -214 536 -394 986 -400
+1000 -6 14 -76 187 -156 385 -80 198 -182 452 -228 565 -46 113 -140 346 -209
+518 -205 507 -225 554 -244 568 -14 11 -209 13 -1055 14 l-1038 0 3 -152z"/>
+    <path fill="#4A6B5C" d="M8830 7450 l0 -2582 -32 6 c-517 106 -1064 -47 -1442 -405 -598 -566
+-501 -1354 196 -1598 489 -170 1134 -19 1548 363 234 217 350 418 423 736 l22
+95 3 2373 c2 1961 5 2372 16 2372 27 0 132 -41 205 -81 315 -169 569 -524 675
+-944 50 -198 60 -285 60 -525 0 -288 -27 -487 -105 -756 -34 -120 -35 -130
+-11 -143 33 -18 64 11 154 144 227 334 402 795 469 1235 37 238 34 646 -4 843
+-149 761 -637 1271 -1353 1418 -98 20 -147 23 -466 27 l-358 4 0 -2582z"/>
+  </g>
+</svg>

web/static/brand/mark.svg

@@ -0,0 +1,27 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="202 251 902 723">
+  <g transform="translate(0,1254) scale(0.1,-0.1)" fill-rule="evenodd">
+    <path fill="currentColor" d="M2252 9878 l3 -152 109 -22 c342 -72 492 -184 538 -405 16 -74 24
+-4823 9 -5024 -20 -266 -73 -375 -236 -484 -116 -77 -332 -150 -543 -181 -114
+-18 -107 -6 -110 -165 -1 -76 2 -143 7 -148 9 -9 2607 -11 2623 -1 14 9 10
+280 -4 291 -7 5 -49 15 -93 22 -380 60 -638 193 -720 374 -63 136 -59 -12 -61
+2247 -3 1999 -2 2054 15 2015 116 -253 646 -1520 1183 -2825 71 -173 216 -524
+322 -780 206 -494 266 -640 370 -895 97 -237 68 -210 226 -210 l135 0 23 50
+c13 27 95 212 182 410 134 307 747 1685 1015 2285 92 205 726 1599 910 2000
+65 140 126 274 137 297 22 50 52 71 74 52 12 -10 14 -266 14 -1864 l0 -1852
+-82 -7 c-347 -29 -716 -203 -973 -460 -710 -712 -343 -1645 650 -1649 453 -2
+892 184 1206 510 193 202 295 397 351 676 l23 112 0 2357 c0 1297 0 2358 1
+2358 12 0 142 -49 179 -67 342 -173 607 -545 715 -1004 85 -361 66 -801 -51
+-1215 -43 -151 -40 -173 18 -174 53 0 284 377 396 650 243 590 303 1238 163
+1754 -178 652 -643 1100 -1294 1248 -93 21 -122 22 -716 25 -707 4 -649 12
+-696 -90 -15 -34 -78 -172 -140 -307 -593 -1297 -1123 -2469 -1717 -3800 -210
+-472 -193 -437 -204 -418 -11 19 -173 423 -630 1568 -214 536 -394 986 -400
+1000 -6 14 -76 187 -156 385 -80 198 -182 452 -228 565 -46 113 -140 346 -209
+518 -205 507 -225 554 -244 568 -14 11 -209 13 -1055 14 l-1038 0 3 -152z"/>
+    <path fill="#4A6B5C" d="M8830 7450 l0 -2582 -32 6 c-517 106 -1064 -47 -1442 -405 -598 -566
+-501 -1354 196 -1598 489 -170 1134 -19 1548 363 234 217 350 418 423 736 l22
+95 3 2373 c2 1961 5 2372 16 2372 27 0 132 -41 205 -81 315 -169 569 -524 675
+-944 50 -198 60 -285 60 -525 0 -288 -27 -487 -105 -756 -34 -120 -35 -130
+-11 -143 33 -18 64 11 154 144 227 334 402 795 469 1235 37 238 34 646 -4 843
+-149 761 -637 1271 -1353 1418 -98 20 -147 23 -466 27 l-358 4 0 -2582z"/>
+  </g>
+</svg>