acme: answer HTTP-01 from the server itself, on port 80

HTTP-01 always arrives on port 80 - the CA chooses the port, not the operator -
so it never collides with an admin UI on 443. The conflict only exists for
TLS-ALPN-01, which is the challenge type that does use 443.

Given that, the server keeps a permanent listener on 80 that answers challenges
from a webroot and redirects everything else to the admin UI. Same arrangement
as the webroot plugins for Apache and nginx, and better than letting the ACME
client bind 80 per renewal: nothing binds and unbinds, so a renewal cannot fail
because the port was briefly busy, and the client needs only write access to a
directory instead of the privilege to bind a low port. Port 80 also gets a use
it would want anyway.

The ACME client stays an external program. lego is also a Go library, but
importing it would put a large dependency tree into a server that deliberately
has none, and the CLI does the same job from a timer.

Tokens are validated by *shape* before any filesystem call, so traversal never
reaches the disk - a stronger guarantee than sanitising a path and trusting the
sanitiser.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/build-status.md

@@ -941,3 +941,64 @@ Also: a `BackHandler` now returns from Settings/History to the run screen. The s
 state variable with nothing connecting it to the back stack, so the system Back gesture left the
 app entirely. Enabled only when there is somewhere to go back to, so Back still exits from the run
 screen.
+
+### Upstream throughput (server-v0.6.3, 2026-08-01)
+The mirror of the downstream case: the client generates the traffic and the server counts it. No
+grant is involved — the client is sending its own packets, so there is nothing to amplify — but it
+does need the server's tally, because **only the far end knows how much arrived**. Without that
+number a sender measures how fast it can *transmit*, which is usually just the speed of the local
+NIC and is a different question from the one being asked.
+
+`TYPE_THROUGHPUT_UP` (0x0F) is counted and deliberately **never answered**: a reply would double
+the traffic and drag the return path into a measurement that is specifically about the outbound
+one.
+
+The tally is a counter, not a list, and short-circuits **before** the observation log. A
+five-second run at 20 Mbps is around ten thousand packets; one struct each would turn a
+measurement into an allocation storm on a shared server, and nothing needs the per-packet detail
+since the client holds the send-side record. The gap between the two counts is the loss.
+
+`direction=up` on the throughput action sends nothing — it zeroes the counter, so a second run in
+one session measures itself rather than inheriting the first one's packets. The live test asserts
+`received <= sent`, which is what catches a counter that was never reset.
+
+Live against fmr: **3125 sent, 3125 counted, 0 % loss, 10.0 Mbit/s** at a 10 Mbit/s request, with
+`measures_network: false` — correct, since what arrived matched what was offered, so the path was
+never the constraint.
+
+### Raw shell dumps leaked the whole LAN (2026-08-01)
+Found by running the Shizuku shell tier for the first time. The tier works — `tiers.shizuku: true`,
+`exec_path: UserService` (so the UserService binds on the OnePlus, as recorded), `runs_as
+shell(2000)`, 7/7 commands — and the run promptly uploaded **every MAC address on the local
+network** to fmr at the `balanced` level: router, phones, whatever else was on the wifi. Fourteen
+of them.
+
+The probes embed raw command output verbatim (`ip neigh`, `ip route`, `id`), which is genuinely
+good evidence and also a complete household device inventory. The anonymizer could not see it:
+classification is by field name and by whole-value shape, and `ip_neigh` is one long string that is
+itself neither a MAC nor an address. measurement-schema.md §9 item 2 had flagged raw dumps as "hard
+to anonymize" and proposed dropping them from exports; nothing enforced either.
+
+**Scrubbing beats dropping.** Identifiers inside any unclassified string are now replaced in place,
+using the same pseudonyms as everywhere else — so a MAC that appears both in a parsed field and in
+a raw dump still reads as one device. The dump stays readable and auditable: you can still see the
+neighbour table's shape, the host count, RFC1918 addresses and vendor prefixes. Dropping the
+evidence would have protected the same data while destroying the reason for collecting it.
+
+Two implementation notes worth keeping:
+- **One pass, not three.** Sequential passes re-process their own output: once a MAC became
+  `78:9a:18:xx:yy:zz`, the IPv6 pattern matched it — six hex groups separated by colons *is* an
+  address — and destroyed the vendor prefix the MAC rule had just preserved. Ordered alternation
+  resolves each position once, MAC first.
+- The patterns are conservative on purpose. A missed address gets caught by another rule or not at
+  all; an over-eager one mangles timestamps and version strings, corrupting evidence to protect
+  nothing.
+
+`RealDocumentTest` runs the anonymizer over a captured run when `ECHOLOT_REAL_RUN` points at one,
+and fails on any MAC that survives. It self-skips otherwise, so no one's network is committed to the
+repo. Against the actual leaked document: **14 MACs in, 0 surviving.**
+
+Also fixed: the Settings *Preview what an upload would send* button did nothing. It read
+`UiState.history`, which is empty until the History screen has been opened — the same root cause as
+the "0 run(s)" count. It now reads the archive directly, and says so when there is nothing to
+preview rather than silently ignoring the tap.

echolot-app/app/src/main/kotlin/app/echo_lot/app/MainActivity.kt

@@ -101,11 +101,10 @@ class MainActivity : ComponentActivity() {
                         onApplyRetention = vm::applyRetention,
                         onDeleteAll = vm::deleteAllRuns,
                         onPreviewUpload = {
-                            // Preview the newest run, since that is the one the user just made
-                            // and the one they are deciding about.
-                            vm.state.history.firstOrNull()?.let { r ->
-                                lifecycleScope.launch { preview = vm.uploadPreview(r.id) }
-                            }
+                            // Straight from the archive: the newest run is the one the user just
+                            // made and the one they are deciding about. Always shows something,
+                            // even when there is nothing to preview yet.
+                            lifecycleScope.launch { preview = vm.previewNewestRun() }
                         },
                         onCheckServer = vm::checkServer,
                         onEnroll = vm::enroll,

echolot-app/app/src/main/kotlin/app/echo_lot/app/RunViewModel.kt

@@ -194,6 +194,21 @@ class RunViewModel(app: Application) : AndroidViewModel(app) {
         store.read(id)?.let { store.redactedForUpload(it) }
     }
 
+    /**
+     * Preview of the most recent run, read from the archive rather than from [UiState.history].
+     *
+     * The history list is only populated once the History screen has been opened, so a preview
+     * driven from it did nothing at all on a freshly-opened Settings screen — a button that
+     * silently does nothing is worse than one that says why.
+     */
+    suspend fun previewNewestRun(): String = withContext(Dispatchers.IO) {
+        val newest = store.list().firstOrNull()
+            ?: return@withContext "No archived runs yet. Run a measurement first, then this will " +
+                "show exactly what an upload would send."
+        store.read(newest.id)?.let { store.redactedForUpload(it) }
+            ?: "That run could not be read back from the archive."
+    }
+
     fun archivedBytes(): Long = store.totalBytes()
 
     /** Counted from the archive itself, not from [UiState.history], which is empty until the

echolot-app/app/src/main/kotlin/app/echo_lot/app/SettingsScreen.kt

@@ -16,6 +16,7 @@ import androidx.compose.foundation.verticalScroll
 import androidx.compose.material3.Button
 import androidx.compose.material3.Card
 import androidx.compose.material3.FilterChip
+import androidx.compose.material3.LocalContentColor
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.OutlinedTextField
 import androidx.compose.material3.Switch
@@ -130,12 +131,21 @@ fun SettingsScreen(
                 }
                 Text(privacyExplanation(privacy), style = MaterialTheme.typography.bodySmall)
 
+                // At FULL nothing is pseudonymized, so a salt has nothing to act on. Shown
+                // disabled rather than hidden: the setting is still stored and still applies the
+                // moment the level changes, and a control that vanishes hides that fact.
                 Toggle(
                     label = "Stable pseudonyms across runs",
-                    detail = "Lets you compare uploaded runs over time (same SSID reads the same " +
-                        "each time). It also links your uploads together, so leave it off on a " +
-                        "server you don't run yourself.",
-                    checked = stableSalt,
+                    detail = if (privacy == PrivacyLevel.FULL) {
+                        "Not used at this level — nothing is pseudonymized, so there is nothing " +
+                            "to keep stable. Choose balanced or strict to use this."
+                    } else {
+                        "Lets you compare uploaded runs over time (same SSID reads the same " +
+                            "each time). It also links your uploads together, so leave it off on " +
+                            "a server you don't run yourself."
+                    },
+                    checked = stableSalt && privacy != PrivacyLevel.FULL,
+                    enabled = privacy != PrivacyLevel.FULL,
                 ) { stableSalt = it; settings.stableSalt = it }
 
                 TextButton(onClick = onPreviewUpload) { Text("Preview what an upload would send") }
@@ -237,13 +247,22 @@ private fun privacyExplanation(level: PrivacyLevel): String = when (level) {
 }
 
 @Composable
-private fun Toggle(label: String, detail: String, checked: Boolean, onChange: (Boolean) -> Unit) {
+private fun Toggle(
+    label: String,
+    detail: String,
+    checked: Boolean,
+    enabled: Boolean = true,
+    onChange: (Boolean) -> Unit,
+) {
     Row(Modifier.fillMaxWidth(), verticalAlignment = Alignment.Top) {
         Column(Modifier.weight(1f)) {
-            Text(label, style = MaterialTheme.typography.bodyMedium)
-            Text(detail, style = MaterialTheme.typography.bodySmall)
+            // Dimmed together with the switch, so "this does nothing right now" reads at a glance
+            // instead of only on close inspection.
+            val alpha = if (enabled) 1f else 0.5f
+            Text(label, style = MaterialTheme.typography.bodyMedium, color = LocalContentColor.current.copy(alpha = alpha))
+            Text(detail, style = MaterialTheme.typography.bodySmall, color = LocalContentColor.current.copy(alpha = alpha))
         }
-        Switch(checked = checked, onCheckedChange = onChange)
+        Switch(checked = checked, onCheckedChange = onChange, enabled = enabled)
     }
 }
 

echolot-app/core-engine/src/test/kotlin/app/echo_lot/engine/LiveThroughputTest.kt

@@ -65,4 +65,41 @@ class LiveThroughputTest {
         assertTrue(m.contains(""""limited_by":"duration""""),
             "the run did not end on the clock, so the rate measures the server, not the path: $m")
     }
-}
+
+    // Upstream is the direction only the far end can measure. The assertion that matters is that
+    // the server's count is present and plausible against what we sent — a test that only checked
+    // "we transmitted some Mbps" would pass against a server that counted nothing at all.
+    @Test
+    fun measuresUpstreamAgainstTheServersCount() {
+        if (url == null || pin == null || cred == null || udp == null) {
+            println("LiveThroughputTest(up) skipped"); return
+        }
+        val control = ControlClient(url, setOf(pin), "0.2.0")
+        val session = control.createSession(cred, target)
+        val (host, port) = udp.split(":").let { it[0] to it[1].toInt() }
+
+        val (test, findings) = ProbeSession(cred, session, host, port).use { ps ->
+            ps.echo()
+            ThroughputMeasurement(SystemIdSource()).runUpstream(
+                cred, session.sessionId, control, ps, sessionRef = "sess-1",
+                durationS = 3, kbps = 10_000,
+            )
+        }
+        control.deleteSession(cred, session.sessionId)
+
+        val m = assertNotNull(test.metrics).toString()
+        println("upstream: ${test.status} $m")
+        for (f in findings) println("finding ${f.code} [${f.severity}] ${f.title}")
+
+        assertEquals(TestStatus.OK, test.status, "the server counted nothing: $m")
+        val recv = Regex(""""received_packets":(\d+)""").find(m)?.groupValues?.get(1)?.toInt()
+        val sent = Regex(""""sent_packets":(\d+)""").find(m)?.groupValues?.get(1)?.toInt()
+        assertNotNull(recv); assertNotNull(sent)
+        assertTrue(sent > 100, "barely anything was sent, so the rate means nothing: $m")
+        assertTrue(recv > 0, "the server received none of $sent packets: $m")
+        // The counts should be close on a healthy path; wildly different means the two sides are
+        // counting different things rather than the network losing packets.
+        assertTrue(recv <= sent, "the server counted MORE than we sent — the counter is not being reset")
+        println("sent $sent, server saw $recv")
+    }
+}

echolot-app/core-privacy/build.gradle.kts

@@ -20,4 +20,8 @@ kotlin {
 }
 java { sourceCompatibility = JavaVersion.VERSION_17; targetCompatibility = JavaVersion.VERSION_17 }
 
-tasks.test { useJUnitPlatform() }
+tasks.test {
+    useJUnitPlatform()
+    // Opt-in: point this at a captured run to check the anonymizer against real data.
+    System.getenv("ECHOLOT_REAL_RUN")?.let { environment("ECHOLOT_REAL_RUN", it) }
+}

echolot-app/core-privacy/src/main/kotlin/app/echo_lot/privacy/Anonymizer.kt

@@ -1,276 +1,327 @@
-// SPDX-FileCopyrightText: 2026 Echolot contributors
-// SPDX-License-Identifier: GPL-3.0-or-later
-
-// Package privacy implements the anonymization contract of measurement-schema.md §8.
-//
-// The threat model is specific. An engineer running their own server wants the full document —
-// SSIDs and MACs are what make a run useful a week later. Someone measuring against a stranger's
-// server wants the numbers to survive and the identifiers not to. So this is a *transform*, not a
-// filter: the output is still a valid measurement document with the same tests, metrics and
-// findings; only the identifying scalars change, and consistently, so "same SSID as last run" is
-// still answerable from pseudonyms alone.
-//
-// Two properties are load-bearing and are what the tests pin:
-//   - Consistency within a document: one input value always maps to one pseudonym, so
-//     correlations inside a run survive.
-//   - No consistency *across* documents unless the user asks for it: the salt is per-run by
-//     default, so pseudonyms cannot be used to track a device between uploads. A stable salt is
-//     opt-in (`Salt.stable`) for people diffing their own history on their own server.
-package app.echo_lot.privacy
-
-import kotlinx.serialization.json.*
-import java.security.MessageDigest
-import java.util.Locale
-
-/** How much to strip. Ordered: FULL < BALANCED < STRICT. Wire values match the server's. */
-enum class PrivacyLevel(val wire: String) {
-    /** Nothing removed. The right choice for your own server. */
-    FULL("full"),
-
-    /**
-     * Identifiers pseudonymized, neighbour inventory dropped. Topology and timing survive:
-     * you can still see that the gateway is a MikroTik at a /24 boundary with 3 % loss, but not
-     * which MikroTik, on which SSID, next to whose Chromecast.
-     */
-    BALANCED("balanced"),
-
-    /**
-     * Numbers only: tests keep their metrics and status, evidence is dropped, findings keep their
-     * codes and severities but lose descriptions (which quote real names). What is left cannot
-     * identify a network, and is still enough for aggregate "how common is this fault" work.
-     */
-    STRICT("strict");
-
-    companion object {
-        fun fromWire(s: String?): PrivacyLevel =
-            entries.firstOrNull { it.wire == s?.lowercase(Locale.ROOT) } ?: FULL
-
-        /** The stricter of two levels — used to honour a server's minimum. */
-        fun max(a: PrivacyLevel, b: PrivacyLevel): PrivacyLevel = if (a.ordinal >= b.ordinal) a else b
-    }
-}
-
-/**
- * The pseudonymization salt. Per-run by default: a fresh random salt means the same SSID uploaded
- * twice yields two different pseudonyms, so an upload endpoint cannot link runs to a device.
- * A stable salt trades that away for cross-run diffing and is only appropriate on a server you
- * own — the app makes that an explicit choice, not a default.
- */
-class Salt private constructor(internal val bytes: ByteArray, val stable: Boolean) {
-    companion object {
-        fun perRun(random: ByteArray): Salt = Salt(random.copyOf(), stable = false)
-        fun stable(secret: ByteArray): Salt = Salt(secret.copyOf(), stable = true)
-    }
-}
-
-/**
- * Transforms a measurement document to [level].
- *
- * Field classification is by JSON key name, because the schema names things consistently
- * (`ssid`, `bssid`, `mac`, `ip4`, `ip6`, `fqdn`, …) and a name-driven pass is auditable by
- * reading one table. Anything unrecognized is treated as identifying when it is a string inside
- * a known-sensitive container, and left alone otherwise — see [Classification].
- */
-class Anonymizer(private val level: PrivacyLevel, private val salt: Salt) {
-
-    private val cache = HashMap<String, String>()
-
-    fun anonymize(doc: JsonObject): JsonObject {
-        if (level == PrivacyLevel.FULL) return stamp(doc)
-        val walked = walkObject(doc, path = emptyList())
-        val out = if (level == PrivacyLevel.STRICT) strip(walked) else walked
-        return stamp(out)
-    }
-
-    /** Records what was done, so a reader of the archived/uploaded document is never guessing. */
-    private fun stamp(doc: JsonObject): JsonObject {
-        val run = doc["run"]?.jsonObject ?: return doc
-        val privacy = buildJsonObject {
-            put("anonymization", level.wire)
-            put("salt", if (salt.stable) "stable" else "per_run")
-        }
-        return JsonObject(doc + ("run" to JsonObject(run + ("privacy" to privacy))))
-    }
-
-    // ---- the tree walk -------------------------------------------------------------------
-
-    private fun walkObject(obj: JsonObject, path: List<String>): JsonObject = buildJsonObject {
-        for ((k, v) in obj) {
-            val childPath = path + k
-            when {
-                Classification.dropAtBalanced(childPath) -> Unit // omit entirely
-                else -> put(k, walk(k, v, childPath))
-            }
-        }
-    }
-
-    private fun walk(key: String, v: JsonElement, path: List<String>): JsonElement = when (v) {
-        is JsonObject -> walkObject(v, path)
-        is JsonArray -> JsonArray(v.map { walk(key, it, path) })
-        is JsonPrimitive ->
-            if (v.isString) {
-                // Name first (it is precise), then shape (it is exhaustive). A field nobody
-                // classified must not be a field that leaks.
-                val type = Classification.typeOf(key, path) ?: Classification.inferFromValue(v.content)
-                JsonPrimitive(transform(type, v.content))
-            } else {
-                v
-            }
-    }
-
-    private fun transform(type: LogicalType?, value: String): String = when (type) {
-        null -> value
-        LogicalType.SSID -> pseudo("ssid", value) { "net-" + it.take(6) }
-        LogicalType.MAC, LogicalType.BSSID -> macPreservingOui(value)
-        LogicalType.IP4 -> ip4(value)
-        LogicalType.IP6 -> ip6(value)
-        LogicalType.FQDN -> fqdn(value)
-        LogicalType.OPAQUE_ID -> "redacted"
-        LogicalType.FREETEXT -> "[removed: may contain identifying text]"
-    }
-
-    // ---- per-type transforms -------------------------------------------------------------
-
-    /**
-     * Keeps the OUI (which vendor) and pseudonymizes the NIC part (which unit). Vendor is the
-     * diagnostically valuable half — "the RA comes from a MikroTik" survives, "…from THAT
-     * MikroTik" does not.
-     */
-    private fun macPreservingOui(value: String): String {
-        val sep = if (value.contains('-')) '-' else ':'
-        val parts = value.split(sep)
-        if (parts.size != 6 || parts.any { it.length != 2 }) return pseudo("mac", value) { "mac-" + it.take(8) }
-        val nic = pseudo("mac", value) { it }
-        return (parts.take(3) + listOf(nic.substring(0, 2), nic.substring(2, 4), nic.substring(4, 6)))
-            .joinToString(sep.toString())
-            .lowercase(Locale.ROOT)
-    }
-
-    /**
-     * Prefix-preserving within the same class, with reserved ranges kept verbatim: RFC1918 and
-     * CGNAT addresses say something about the topology and nothing about the person, and a run
-     * where 192.168.1.1 became a random public address would be actively misleading to read.
-     * Public addresses keep only their /16 so the network is still locatable at ISP granularity.
-     */
-    private fun ip4(value: String): String {
-        // A route destination carries a prefix length; pseudonymize the address and put it back,
-        // or "0.0.0.0/0" turns into nonsense and the routing table becomes unreadable.
-        value.substringAfter('/', "").takeIf { it.isNotEmpty() && value.contains('/') }?.let { len ->
-            return ip4(value.substringBefore('/')) + "/" + len
-        }
-        val o = value.split(".")
-        if (o.size != 4 || o.any { it.toIntOrNull() == null }) return value
-        val n = o.map { it.toInt() }
-        val reserved = n[0] == 10 ||
-            (n[0] == 172 && n[1] in 16..31) ||
-            (n[0] == 192 && n[1] == 168) ||
-            (n[0] == 169 && n[1] == 254) ||
-            (n[0] == 100 && n[1] in 64..127) ||
-            n[0] == 127 || n[0] == 0 || n[0] >= 224
-        if (reserved) return value
-        val h = pseudo("ip4", value) { it }
-        return "${n[0]}.${n[1]}.${h.substring(0, 2).toInt(16)}.${h.substring(2, 4).toInt(16)}"
-    }
-
-    /**
-     * IPv6 keeps the scope and the first 32 bits (so 2001:db8:… still reads as global unicast in
-     * the same allocation) and pseudonymizes the rest — the interface identifier is the part that
-     * is a device fingerprint, especially with EUI-64.
-     */
-    private fun ip6(value: String): String {
-        // Dotted quads reach here through the family-agnostic field names (addr, gateway, dst);
-        // hand them to the IPv4 path rather than mangling them as if they were v6.
-        if (value.count { it == ':' } < 2) return ip4(value)
-        if (value.contains('/')) {
-            return ip6(value.substringBefore('/')) + "/" + value.substringAfter('/')
-        }
-        val v = value.lowercase(Locale.ROOT)
-        // The unspecified address and the default route are not identities; mangling them would
-        // make a routing table unreadable for no privacy gain.
-        if (v == "::1" || v == "::" || v.startsWith("fe80:") || v.startsWith("ff")) return v
-
-        // Unique local addresses (fc00::/7) need the *whole* prefix replaced, not the tail.
-        //
-        // They look like the v6 equivalent of RFC1918, and the first instinct is to keep them for
-        // the same reason: private, topological, says nothing about anyone. That reasoning does
-        // not carry over. An RFC1918 prefix is shared by millions of networks and identifies
-        // none of them; a ULA global ID is 40 *random* bits, unique to one network by
-        // construction (RFC 4193). It is a network fingerprint. Passing the leading groups
-        // through - which is what the general path does - leaked 32 of those 40 bits.
-        //
-        // The prefix is pseudonymized as a unit, so two addresses on the same ULA subnet still
-        // land on the same pseudonymous prefix. "These hosts are on one network" survives;
-        // "this is *that* network" does not.
-        if (v.startsWith("fc") || v.startsWith("fd")) {
-            val groups = v.substringBefore('%').split(":")
-            val prefix = pseudo("ula-prefix", groups.take(3).joinToString(":")) { it }
-            val host = pseudo("ula-host", v) { it }
-            return "fd${prefix.substring(0, 2)}:${prefix.substring(2, 6)}:${prefix.substring(6, 10)}" +
-                "::${host.substring(0, 4)}"
-        }
-        val groups = v.substringBefore('%').split(":")
-        if (groups.size < 3) return v
-        val h = pseudo("ip6", value) { it }
-        return "${groups[0]}:${groups[1]}:${h.substring(0, 4)}:${h.substring(4, 8)}::${h.substring(8, 12)}"
-    }
-
-    /**
-     * Per-label pseudonyms with the public suffix kept, so "it resolved somewhere under .local"
-     * or "…under example.com" survives without naming the host. The suffix list is deliberately
-     * short: guessing wrong keeps *more* pseudonymized, never less.
-     */
-    private fun fqdn(value: String): String {
-        if (value.isEmpty()) return value
-        val trailing = value.endsWith(".")
-        val labels = value.trimEnd('.').split(".")
-        if (labels.size == 1) return pseudo("fqdn", value) { "host-" + it.take(6) }
-        val keep = if (labels.last() in publicSuffixes) 1 else 0
-        val head = labels.dropLast(keep).map { l -> pseudo("label", l) { "l-" + it.take(6) } }
-        return (head + labels.takeLast(keep)).joinToString(".") + if (trailing) "." else ""
-    }
-
-    // ---- STRICT ---------------------------------------------------------------------------
-
-    /**
-     * STRICT keeps the shape of the document and the numbers, and nothing that quotes the
-     * network back. Evidence goes (trains carry addresses and hostnames), finding prose goes
-     * (it interpolates real names), networks go entirely.
-     */
-    private fun strip(doc: JsonObject): JsonObject = buildJsonObject {
-        for ((k, v) in doc) {
-            when (k) {
-                "networks", "server_sessions" -> Unit
-                "tests" -> put(k, JsonArray((v as? JsonArray ?: JsonArray(emptyList())).map { t ->
-                    val o = t.jsonObject
-                    JsonObject(o.filterKeys { it != "evidence" && it != "params" })
-                }))
-                "findings" -> put(k, JsonArray((v as? JsonArray ?: JsonArray(emptyList())).map { f ->
-                    val o = f.jsonObject
-                    JsonObject(o.filterKeys { it != "description" && it != "title" && it != "evidence_refs" })
-                }))
-                "run" -> put(k, JsonObject(v.jsonObject.filterKeys { it != "notes" }))
-                else -> put(k, v)
-            }
-        }
-    }
-
-    // ---- pseudonym machinery ---------------------------------------------------------------
-
-    /** Deterministic per (domain, value, salt); memoized so one value maps to one pseudonym. */
-    private fun pseudo(domain: String, value: String, shape: (String) -> String): String =
-        cache.getOrPut("$domain$value") {
-            val md = MessageDigest.getInstance("SHA-256")
-            md.update(salt.bytes)
-            md.update(domain.toByteArray())
-            md.update(0)
-            md.update(value.lowercase(Locale.ROOT).toByteArray())
-            shape(md.digest().joinToString("") { "%02x".format(it) })
-        }
-
-    private companion object {
-        val publicSuffixes = setOf(
-            "local", "lan", "home", "internal", "arpa",
-            "com", "net", "org", "io", "app", "dev", "at", "de", "eu", "uk",
-        )
-    }
-}
+// SPDX-FileCopyrightText: 2026 Echolot contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+// Package privacy implements the anonymization contract of measurement-schema.md §8.
+//
+// The threat model is specific. An engineer running their own server wants the full document —
+// SSIDs and MACs are what make a run useful a week later. Someone measuring against a stranger's
+// server wants the numbers to survive and the identifiers not to. So this is a *transform*, not a
+// filter: the output is still a valid measurement document with the same tests, metrics and
+// findings; only the identifying scalars change, and consistently, so "same SSID as last run" is
+// still answerable from pseudonyms alone.
+//
+// Two properties are load-bearing and are what the tests pin:
+//   - Consistency within a document: one input value always maps to one pseudonym, so
+//     correlations inside a run survive.
+//   - No consistency *across* documents unless the user asks for it: the salt is per-run by
+//     default, so pseudonyms cannot be used to track a device between uploads. A stable salt is
+//     opt-in (`Salt.stable`) for people diffing their own history on their own server.
+package app.echo_lot.privacy
+
+import kotlinx.serialization.json.*
+import java.security.MessageDigest
+import java.util.Locale
+
+/** How much to strip. Ordered: FULL < BALANCED < STRICT. Wire values match the server's. */
+enum class PrivacyLevel(val wire: String) {
+    /** Nothing removed. The right choice for your own server. */
+    FULL("full"),
+
+    /**
+     * Identifiers pseudonymized, neighbour inventory dropped. Topology and timing survive:
+     * you can still see that the gateway is a MikroTik at a /24 boundary with 3 % loss, but not
+     * which MikroTik, on which SSID, next to whose Chromecast.
+     */
+    BALANCED("balanced"),
+
+    /**
+     * Numbers only: tests keep their metrics and status, evidence is dropped, findings keep their
+     * codes and severities but lose descriptions (which quote real names). What is left cannot
+     * identify a network, and is still enough for aggregate "how common is this fault" work.
+     */
+    STRICT("strict");
+
+    companion object {
+        fun fromWire(s: String?): PrivacyLevel =
+            entries.firstOrNull { it.wire == s?.lowercase(Locale.ROOT) } ?: FULL
+
+        /** The stricter of two levels — used to honour a server's minimum. */
+        fun max(a: PrivacyLevel, b: PrivacyLevel): PrivacyLevel = if (a.ordinal >= b.ordinal) a else b
+    }
+}
+
+/**
+ * The pseudonymization salt. Per-run by default: a fresh random salt means the same SSID uploaded
+ * twice yields two different pseudonyms, so an upload endpoint cannot link runs to a device.
+ * A stable salt trades that away for cross-run diffing and is only appropriate on a server you
+ * own — the app makes that an explicit choice, not a default.
+ */
+class Salt private constructor(internal val bytes: ByteArray, val stable: Boolean) {
+    companion object {
+        fun perRun(random: ByteArray): Salt = Salt(random.copyOf(), stable = false)
+        fun stable(secret: ByteArray): Salt = Salt(secret.copyOf(), stable = true)
+    }
+}
+
+/**
+ * Transforms a measurement document to [level].
+ *
+ * Field classification is by JSON key name, because the schema names things consistently
+ * (`ssid`, `bssid`, `mac`, `ip4`, `ip6`, `fqdn`, …) and a name-driven pass is auditable by
+ * reading one table. Anything unrecognized is treated as identifying when it is a string inside
+ * a known-sensitive container, and left alone otherwise — see [Classification].
+ */
+class Anonymizer(private val level: PrivacyLevel, private val salt: Salt) {
+
+    private val cache = HashMap<String, String>()
+
+    fun anonymize(doc: JsonObject): JsonObject {
+        if (level == PrivacyLevel.FULL) return stamp(doc)
+        val walked = walkObject(doc, path = emptyList())
+        val out = if (level == PrivacyLevel.STRICT) strip(walked) else walked
+        return stamp(out)
+    }
+
+    /** Records what was done, so a reader of the archived/uploaded document is never guessing. */
+    private fun stamp(doc: JsonObject): JsonObject {
+        val run = doc["run"]?.jsonObject ?: return doc
+        val privacy = buildJsonObject {
+            put("anonymization", level.wire)
+            put("salt", if (salt.stable) "stable" else "per_run")
+        }
+        return JsonObject(doc + ("run" to JsonObject(run + ("privacy" to privacy))))
+    }
+
+    // ---- the tree walk -------------------------------------------------------------------
+
+    private fun walkObject(obj: JsonObject, path: List<String>): JsonObject = buildJsonObject {
+        for ((k, v) in obj) {
+            val childPath = path + k
+            when {
+                Classification.dropAtBalanced(childPath) -> Unit // omit entirely
+                else -> put(k, walk(k, v, childPath))
+            }
+        }
+    }
+
+    private fun walk(key: String, v: JsonElement, path: List<String>): JsonElement = when (v) {
+        is JsonObject -> walkObject(v, path)
+        is JsonArray -> JsonArray(v.map { walk(key, it, path) })
+        is JsonPrimitive ->
+            if (v.isString) {
+                // Name first (it is precise), then shape (it is exhaustive). A field nobody
+                // classified must not be a field that leaks.
+                val type = Classification.typeOf(key, path) ?: Classification.inferFromValue(v.content)
+                JsonPrimitive(transform(type, v.content))
+            } else {
+                v
+            }
+    }
+
+    private fun transform(type: LogicalType?, value: String): String = when (type) {
+        // Unclassified strings still get their *embedded* identifiers scrubbed. A whole-value
+        // check cannot see them: raw shell output is one long string that is neither a MAC nor an
+        // address, so it sailed through both the name table and the shape check carrying every
+        // MAC on the user's LAN.
+        null -> scrubEmbedded(value)
+        LogicalType.SSID -> pseudo("ssid", value) { "net-" + it.take(6) }
+        LogicalType.MAC, LogicalType.BSSID -> macPreservingOui(value)
+        LogicalType.IP4 -> ip4(value)
+        LogicalType.IP6 -> ip6(value)
+        LogicalType.FQDN -> fqdn(value)
+        LogicalType.OPAQUE_ID -> "redacted"
+        LogicalType.FREETEXT -> "[removed: may contain identifying text]"
+    }
+
+    /**
+     * Replaces addresses and MACs found *inside* a longer string.
+     *
+     * Shizuku probes embed raw command output verbatim — `ip neigh`, `ip route`, `dumpsys` — which
+     * is genuinely valuable evidence and also a complete inventory of every device on the user's
+     * network, with hardware addresses. measurement-schema.md §9 flagged these as "hard to
+     * anonymize" and proposed dropping them from exports.
+     *
+     * Scrubbing beats dropping: the output stays readable and auditable — you can still see the
+     * shape of the neighbour table and how many hosts there were — while the identifiers become
+     * the same pseudonyms used everywhere else in the document. So a MAC appearing both in a
+     * parsed field and in a raw dump still reads as one device.
+     *
+     * Only addresses and MACs are touched, for the same reason as [Classification.inferFromValue]:
+     * they are the patterns that cannot be mistaken for something else in free text.
+     */
+    private fun scrubEmbedded(value: String): String {
+        // Cheap bail-out: the overwhelming majority of strings are short and contain neither.
+        if (value.length < 7 || (!value.contains(':') && !value.contains('.'))) return value
+        // One pass, not three. Sequential passes re-process their own output: after a MAC became
+        // 78:9a:18:xx:yy:zz the IPv6 pattern matched it — six hex groups separated by colons is
+        // exactly an address — and mangled the vendor prefix that the MAC rule had just taken
+        // care to preserve. Ordered alternation resolves each position once, MAC first.
+        return EMBEDDED.replace(value) { m ->
+            when {
+                m.groups[1] != null -> macPreservingOui(m.value)
+                m.groups[2] != null -> ip6(m.value)
+                else -> ip4(m.value)
+            }
+        }
+    }
+
+    // ---- per-type transforms -------------------------------------------------------------
+
+    /**
+     * Keeps the OUI (which vendor) and pseudonymizes the NIC part (which unit). Vendor is the
+     * diagnostically valuable half — "the RA comes from a MikroTik" survives, "…from THAT
+     * MikroTik" does not.
+     */
+    private fun macPreservingOui(value: String): String {
+        val sep = if (value.contains('-')) '-' else ':'
+        val parts = value.split(sep)
+        if (parts.size != 6 || parts.any { it.length != 2 }) return pseudo("mac", value) { "mac-" + it.take(8) }
+        val nic = pseudo("mac", value) { it }
+        return (parts.take(3) + listOf(nic.substring(0, 2), nic.substring(2, 4), nic.substring(4, 6)))
+            .joinToString(sep.toString())
+            .lowercase(Locale.ROOT)
+    }
+
+    /**
+     * Prefix-preserving within the same class, with reserved ranges kept verbatim: RFC1918 and
+     * CGNAT addresses say something about the topology and nothing about the person, and a run
+     * where 192.168.1.1 became a random public address would be actively misleading to read.
+     * Public addresses keep only their /16 so the network is still locatable at ISP granularity.
+     */
+    private fun ip4(value: String): String {
+        // A route destination carries a prefix length; pseudonymize the address and put it back,
+        // or "0.0.0.0/0" turns into nonsense and the routing table becomes unreadable.
+        value.substringAfter('/', "").takeIf { it.isNotEmpty() && value.contains('/') }?.let { len ->
+            return ip4(value.substringBefore('/')) + "/" + len
+        }
+        val o = value.split(".")
+        if (o.size != 4 || o.any { it.toIntOrNull() == null }) return value
+        val n = o.map { it.toInt() }
+        val reserved = n[0] == 10 ||
+            (n[0] == 172 && n[1] in 16..31) ||
+            (n[0] == 192 && n[1] == 168) ||
+            (n[0] == 169 && n[1] == 254) ||
+            (n[0] == 100 && n[1] in 64..127) ||
+            n[0] == 127 || n[0] == 0 || n[0] >= 224
+        if (reserved) return value
+        val h = pseudo("ip4", value) { it }
+        return "${n[0]}.${n[1]}.${h.substring(0, 2).toInt(16)}.${h.substring(2, 4).toInt(16)}"
+    }
+
+    /**
+     * IPv6 keeps the scope and the first 32 bits (so 2001:db8:… still reads as global unicast in
+     * the same allocation) and pseudonymizes the rest — the interface identifier is the part that
+     * is a device fingerprint, especially with EUI-64.
+     */
+    private fun ip6(value: String): String {
+        // Dotted quads reach here through the family-agnostic field names (addr, gateway, dst);
+        // hand them to the IPv4 path rather than mangling them as if they were v6.
+        if (value.count { it == ':' } < 2) return ip4(value)
+        if (value.contains('/')) {
+            return ip6(value.substringBefore('/')) + "/" + value.substringAfter('/')
+        }
+        val v = value.lowercase(Locale.ROOT)
+        // The unspecified address and the default route are not identities; mangling them would
+        // make a routing table unreadable for no privacy gain.
+        if (v == "::1" || v == "::" || v.startsWith("fe80:") || v.startsWith("ff")) return v
+
+        // Unique local addresses (fc00::/7) need the *whole* prefix replaced, not the tail.
+        //
+        // They look like the v6 equivalent of RFC1918, and the first instinct is to keep them for
+        // the same reason: private, topological, says nothing about anyone. That reasoning does
+        // not carry over. An RFC1918 prefix is shared by millions of networks and identifies
+        // none of them; a ULA global ID is 40 *random* bits, unique to one network by
+        // construction (RFC 4193). It is a network fingerprint. Passing the leading groups
+        // through - which is what the general path does - leaked 32 of those 40 bits.
+        //
+        // The prefix is pseudonymized as a unit, so two addresses on the same ULA subnet still
+        // land on the same pseudonymous prefix. "These hosts are on one network" survives;
+        // "this is *that* network" does not.
+        if (v.startsWith("fc") || v.startsWith("fd")) {
+            val groups = v.substringBefore('%').split(":")
+            val prefix = pseudo("ula-prefix", groups.take(3).joinToString(":")) { it }
+            val host = pseudo("ula-host", v) { it }
+            return "fd${prefix.substring(0, 2)}:${prefix.substring(2, 6)}:${prefix.substring(6, 10)}" +
+                "::${host.substring(0, 4)}"
+        }
+        val groups = v.substringBefore('%').split(":")
+        if (groups.size < 3) return v
+        val h = pseudo("ip6", value) { it }
+        return "${groups[0]}:${groups[1]}:${h.substring(0, 4)}:${h.substring(4, 8)}::${h.substring(8, 12)}"
+    }
+
+    /**
+     * Per-label pseudonyms with the public suffix kept, so "it resolved somewhere under .local"
+     * or "…under example.com" survives without naming the host. The suffix list is deliberately
+     * short: guessing wrong keeps *more* pseudonymized, never less.
+     */
+    private fun fqdn(value: String): String {
+        if (value.isEmpty()) return value
+        val trailing = value.endsWith(".")
+        val labels = value.trimEnd('.').split(".")
+        if (labels.size == 1) return pseudo("fqdn", value) { "host-" + it.take(6) }
+        val keep = if (labels.last() in publicSuffixes) 1 else 0
+        val head = labels.dropLast(keep).map { l -> pseudo("label", l) { "l-" + it.take(6) } }
+        return (head + labels.takeLast(keep)).joinToString(".") + if (trailing) "." else ""
+    }
+
+    // ---- STRICT ---------------------------------------------------------------------------
+
+    /**
+     * STRICT keeps the shape of the document and the numbers, and nothing that quotes the
+     * network back. Evidence goes (trains carry addresses and hostnames), finding prose goes
+     * (it interpolates real names), networks go entirely.
+     */
+    private fun strip(doc: JsonObject): JsonObject = buildJsonObject {
+        for ((k, v) in doc) {
+            when (k) {
+                "networks", "server_sessions" -> Unit
+                "tests" -> put(k, JsonArray((v as? JsonArray ?: JsonArray(emptyList())).map { t ->
+                    val o = t.jsonObject
+                    JsonObject(o.filterKeys { it != "evidence" && it != "params" })
+                }))
+                "findings" -> put(k, JsonArray((v as? JsonArray ?: JsonArray(emptyList())).map { f ->
+                    val o = f.jsonObject
+                    JsonObject(o.filterKeys { it != "description" && it != "title" && it != "evidence_refs" })
+                }))
+                "run" -> put(k, JsonObject(v.jsonObject.filterKeys { it != "notes" }))
+                else -> put(k, v)
+            }
+        }
+    }
+
+    // ---- pseudonym machinery ---------------------------------------------------------------
+
+    /** Deterministic per (domain, value, salt); memoized so one value maps to one pseudonym. */
+    private fun pseudo(domain: String, value: String, shape: (String) -> String): String =
+        cache.getOrPut("$domain\u0000$value") {
+            val md = MessageDigest.getInstance("SHA-256")
+            md.update(salt.bytes)
+            md.update(domain.toByteArray())
+            md.update(0)
+            md.update(value.lowercase(Locale.ROOT).toByteArray())
+            shape(md.digest().joinToString("") { "%02x".format(it) })
+        }
+
+    private companion object {
+        /**
+         * MAC | IPv6 | IPv4, in that order — alternation is ordered, so a MAC-shaped token is
+         * claimed by the MAC rule before the IPv6 rule can see it.
+         *
+         * The patterns are deliberately conservative. A missed address is scrubbed by another
+         * rule or not at all; an over-eager one mangles timestamps, version strings and log
+         * prefixes, corrupting evidence to protect nothing.
+         */
+        val EMBEDDED = Regex(
+            // Raw strings: a regex written with escaped escapes is a regex nobody can check.
+            """(\b[0-9a-fA-F]{2}(?:[:-][0-9a-fA-F]{2}){5}\b)""" +
+                """|(\b(?:[0-9a-fA-F]{1,4}:){2,7}(?::|[0-9a-fA-F]{1,4})(?:[0-9a-fA-F:]*))""" +
+                """|(\b(?:\d{1,3}\.){3}\d{1,3}\b)"""
+        )
+
+        val publicSuffixes = setOf(
+            "local", "lan", "home", "internal", "arpa",
+            "com", "net", "org", "io", "app", "dev", "at", "de", "eu", "uk",
+        )
+    }
+}

echolot-app/core-privacy/src/test/kotlin/app/echo_lot/privacy/LeakTest.kt

@@ -4,8 +4,12 @@
 package app.echo_lot.privacy
 
 import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.jsonArray
 import kotlinx.serialization.json.jsonObject
+import kotlinx.serialization.json.jsonPrimitive
 import kotlin.test.Test
+import kotlin.test.assertFalse
 import kotlin.test.assertTrue
 
 /**
@@ -110,4 +114,64 @@ class LeakTest {
         assertTrue(out.contains("192.168.1.1"), "RFC1918 gateway should survive: $out")
         assertTrue(out.contains("192.168.1.44"), "RFC1918 interface address should survive: $out")
     }
-}
+
+    /**
+     * Raw shell output embeds a complete inventory of the local network, and neither the field-name
+     * table nor the whole-value shape check can see it: `ip_neigh` is one long string that is
+     * itself neither a MAC nor an address.
+     *
+     * This is not hypothetical. The blob below is (abridged) real output that reached the server
+     * at the `balanced` level from a test device, carrying the hardware address of every host on
+     * the network. measurement-schema.md §9 had flagged raw dumps as "hard to anonymize"; nothing
+     * enforced it.
+     */
+    @Test
+    fun identifiersInsideRawShellOutputAreScrubbed() {
+        // Joined rather than written with escapes, so the fixture stays readable and there is no
+        // chance of an escape being mangled on its way into the JSON below.
+        val dump = listOf(
+            "uid=2000",
+            "10.13.102.5 dev wlan0 lladdr 90:09:d0:1a:83:e4 REACHABLE",
+            "10.13.102.1 dev wlan0 lladdr 78:9a:18:54:b8:f9 REACHABLE",
+            "10.13.102.111 dev wlan0 lladdr dc:a2:66:08:69:95 STALE",
+            "2001:4bb8:46a:e724:289d:87ff:feb6:ebd3 dev wlan0 lladdr b8:be:f4:bc:ca:cf STALE",
+        ).joinToString(" | ")
+        val doc = json.parseToJsonElement(
+            """{"run":{"id":"r"},"tests":[{"id":"t","type":"link.ip_monitor",
+               "evidence":{"ip_neigh":"$dump"}}]}"""
+        ).jsonObject
+        val out = json.encodeToString(
+            kotlinx.serialization.json.JsonObject.serializer(),
+            Anonymizer(PrivacyLevel.BALANCED, salt).anonymize(doc),
+        )
+
+        for (mac in listOf("90:09:d0:1a:83:e4", "78:9a:18:54:b8:f9", "dc:a2:66:08:69:95", "b8:be:f4:bc:ca:cf")) {
+            assertFalse(out.contains(mac), "a neighbour's MAC survived inside the raw dump: $mac")
+        }
+        assertFalse(out.contains("2001:4bb8:46a:e724:289d:87ff:feb6:ebd3"),
+            "a global IPv6 survived inside the raw dump")
+
+        // Scrubbed, not dropped: the evidence must still be readable, or the raw dump stops being
+        // evidence at all. Structure, hostnames of the fields, and RFC1918 addresses stay.
+        assertTrue(out.contains("REACHABLE") && out.contains("STALE"), "the dump lost its structure")
+        assertTrue(out.contains("10.13.102.1"), "RFC1918 addresses should stay readable: $out")
+        assertTrue(out.contains("78:9a:18"), "the vendor prefix should survive for identification")
+    }
+
+    // A MAC in a raw dump and the same MAC in a parsed field must land on the same pseudonym, or
+    // the document stops being internally consistent and one device reads as two.
+    @Test
+    fun theSameIdentifierMatchesAcrossParsedAndRawFields() {
+        val doc = json.parseToJsonElement(
+            """{"run":{"id":"r"},
+               "networks":[{"wifi":{"bssid":"78:9a:18:54:b8:f9"}}],
+               "tests":[{"id":"t","evidence":{"ip_neigh":"gw dev wlan0 lladdr 78:9a:18:54:b8:f9 REACHABLE"}}]}"""
+        ).jsonObject
+        val out = Anonymizer(PrivacyLevel.BALANCED, salt).anonymize(doc)
+        val parsed = out["networks"]!!.jsonArray[0].jsonObject["wifi"]!!.jsonObject["bssid"]!!
+            .jsonPrimitive.content
+        val raw = json.encodeToString(kotlinx.serialization.json.JsonObject.serializer(), out)
+        assertTrue(raw.contains(parsed),
+            "the parsed BSSID pseudonym ($parsed) does not appear in the scrubbed dump")
+    }
+}

echolot-app/core-privacy/src/test/kotlin/app/echo_lot/privacy/RealDocumentTest.kt

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: 2026 Echolot contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+package app.echo_lot.privacy
+
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.jsonObject
+import java.io.File
+import kotlin.test.Test
+import kotlin.test.assertTrue
+
+/**
+ * Runs the anonymizer over a real captured document when one is supplied via ECHOLOT_REAL_RUN,
+ * and reports every MAC and public address that survives.
+ *
+ * Fixtures only contain the identifiers somebody thought to put in them. A real run off a real
+ * phone contains whatever the probes actually produce — which is how the raw-shell-output leak was
+ * found in the first place. Self-skips when no document is supplied, so nobody's network ends up
+ * committed to the repository.
+ */
+class RealDocumentTest {
+
+    @Test
+    fun noIdentifiersSurviveInARealDocument() {
+        val path = System.getenv("ECHOLOT_REAL_RUN")
+        if (path.isNullOrBlank() || !File(path).isFile) {
+            println("RealDocumentTest skipped (set ECHOLOT_REAL_RUN to a captured run)"); return
+        }
+        val json = Json { prettyPrint = false }
+        val doc = json.parseToJsonElement(File(path).readText()).jsonObject
+        val out = json.encodeToString(
+            JsonObject.serializer(),
+            Anonymizer(PrivacyLevel.BALANCED, Salt.perRun(ByteArray(32) { 5 })).anonymize(doc),
+        )
+
+        val macs = Regex("""\b[0-9a-fA-F]{2}(?::[0-9a-fA-F]{2}){5}\b""").findAll(out)
+            .map { it.value.lowercase() }
+            .filter { it != "00:00:00:00:00:00" }
+            .toSet()
+        val original = Regex("""\b[0-9a-fA-F]{2}(?::[0-9a-fA-F]{2}){5}\b""")
+            .findAll(File(path).readText()).map { it.value.lowercase() }.toSet()
+
+        val survived = macs intersect original
+        println("MACs in the original: ${original.size}; unchanged after anonymizing: ${survived.size}")
+        assertTrue(survived.isEmpty(), "these real MAC addresses survived anonymization: $survived")
+    }
+}

server/Dockerfile

@@ -22,4 +22,7 @@ VOLUME ["/state"]
 # the data plane must see real client source addresses/TTLs, and Docker's
 # userland NAT would falsify exactly what this server exists to observe.
 EXPOSE 8441/tcp 8442/udp 8443/tcp
+# The verb is explicit here too, so `docker run <image>` serves and `docker run <image> --help`
+# still works by overriding the command.
 ENTRYPOINT ["/echolot-server"]
+CMD ["--serve"]

server/README.md

@@ -146,3 +146,41 @@ CI (`.gitea/workflows/build-server.yml`): tests on every push touching `server/`
 tagging `server-v1.2.3` builds + pushes the container image to the Gitea registry and
 attaches static linux amd64/arm64 binaries (+ SHA256SUMS) to a release — the same
 artifacts `--self-update` consumes.
+
+## TLS for the admin UI
+
+The binary terminates TLS itself; there is no reverse proxy in the design. It already serves TLS
+for the control plane, so this is reuse rather than new machinery, and it keeps the "one process,
+one config file" property. A proxy would also invite someone to eventually front the control plane
+too — which would break SPKI pinning, because clients pin *that* certificate's key.
+
+```
+ECHOLOT_ADMIN_LISTEN=[2001:db8::2]:443
+ECHOLOT_ADMIN_TLS_CERT=/etc/echolot/admin.pem
+ECHOLOT_ADMIN_TLS_KEY=/etc/echolot/admin.key
+ECHOLOT_ADMIN_BASE_URL=https://admin.example.net
+```
+
+Certificates come from any ACME client. **DNS-01 is the one to use here**: it needs no inbound
+port 80, which matters on a host where 80 is awkward or already spoken for.
+
+```sh
+acme.sh --issue --dns dns_cf -d admin.example.net \
+  --key-file       /etc/echolot/admin.key \
+  --fullchain-file /etc/echolot/admin.pem
+```
+
+**No reload hook is needed.** The certificate is re-read when the files change, so a renewal that
+drops new files in place is picked up on the next handshake. That is deliberate: a reload hook is
+the part of a renewal setup that quietly stops working, months later, and is noticed only once the
+certificate has already expired. A torn write — renewal tools write cert and key separately — keeps
+the previous certificate rather than failing the listener.
+
+Serving the admin UI in plaintext on a non-loopback address is refused: the session cookie is a
+bearer credential for everything the server can do, and the OIDC authorization code arrives in a
+URL. Bind to loopback and use an SSH tunnel (`ssh -L 8444:localhost:8444 host`), supply a
+certificate, or set `ECHOLOT_ADMIN_INSECURE=1` if you mean it.
+
+The control-plane certificate is deliberately *not* hot-reloaded. Clients pin its public key, so
+replacing it is a rotation an operator should have to think about, not something that happens
+because a file changed.

server/cmd/echolot-server/main.go

@@ -11,6 +11,7 @@
 package main
 
 import (
+	"bufio"
 	"context"
 	"crypto/ecdsa"
 	"crypto/elliptic"
@@ -36,11 +37,15 @@ import (
 	"syscall"
 	"time"
 
+	"echo-lot.app/server/internal/acmehttp"
+	"echo-lot.app/server/internal/adminauth"
 	"echo-lot.app/server/internal/canarydns"
+	"echo-lot.app/server/internal/certreload"
 	"echo-lot.app/server/internal/compat"
 	"echo-lot.app/server/internal/config"
 	"echo-lot.app/server/internal/control"
 	"echo-lot.app/server/internal/dataplane"
+	"echo-lot.app/server/internal/oidc"
 	"echo-lot.app/server/internal/runs"
 	"echo-lot.app/server/internal/selftest"
 	"echo-lot.app/server/internal/selfupdate"
@@ -69,6 +74,30 @@ func run() error {
 	control.Version = Version
 
 	switch {
+	case actions.Help:
+		// Compatibility shim for one release.
+		//
+		// Serving became an explicit verb, but self-update is run by the *old* binary — so the
+		// repair added to the updater cannot fix the very update that installs the new one. A
+		// unit written before this change starts us with no arguments, and without this branch
+		// the service would simply stop working, unattended, on a host nobody is watching.
+		//
+		// Only when systemd started us: INVOCATION_ID is set by systemd for every service
+		// invocation and by nothing else, so a person at a terminal still gets usage. Remove
+		// this once no deployment predates --serve.
+		if os.Getenv("INVOCATION_ID") != "" {
+			slog.Warn("started by systemd with no verb — this unit predates --serve; " +
+				"repairing it and serving anyway")
+			if repaired, err := system.RepairExecStart(); err != nil {
+				slog.Error("could not repair the unit; fix ExecStart by hand", "err", err)
+			} else if repaired {
+				slog.Info("systemd unit updated to pass --serve")
+			}
+			return serve(cfg)
+		}
+		config.Usage(os.Stderr)
+		os.Exit(2)
+		return nil
 	case actions.Version:
 		fmt.Println(Version)
 		return nil
@@ -79,6 +108,8 @@ func run() error {
 		return system.InstallSystemd(cfg.SelfUpdateAPI)
 	case actions.UninstallSystemd:
 		return system.UninstallSystemd()
+	case actions.SetAdminPassword:
+		return setAdminPassword(cfg)
 	case actions.SelfUpdate:
 		return selfupdate.Run(cfg.SelfUpdateAPI, Version)
 	}
@@ -150,6 +181,29 @@ func serve(cfg *config.Config) error {
 	slog.Info("client compatibility", "accepts_app", appRange.String(),
 		"protocol", control.ProtocolVersion, "schema", control.SchemaVersion)
 
+	// Identity is optional. Without an issuer the server simply has no sign-in, and
+	// uploads=account can never be satisfied — which is the honest outcome, not a silent
+	// downgrade to anonymous.
+	var idp *oidc.Verifier
+	if cfg.OIDCIssuer != "" && (cfg.OIDCClientID != "" || cfg.OIDCAppClientID != "") {
+		idp = oidc.New(oidc.Config{
+			Issuer:      cfg.OIDCIssuer,
+			ClientID:    cfg.OIDCClientID,
+			AppClientID: cfg.OIDCAppClientID,
+			AdminGroup:  cfg.OIDCAdminGroup,
+		}, nil)
+		slog.Info("identity provider configured", "issuer", cfg.OIDCIssuer,
+			"admin_client_id", cfg.OIDCClientID, "app_client_id", cfg.OIDCAppClientID,
+			"admin_group", cfg.OIDCAdminGroup)
+		if cfg.OIDCAdminGroup == "" {
+			slog.Warn("no admin group set: nobody will be an admin via OIDC " +
+				"(set ECHOLOT_OIDC_ADMIN_GROUP)")
+		}
+	} else if cfg.UploadsMode == string(runs.ModeAccount) {
+		slog.Warn("uploads=account but no identity provider is configured — " +
+			"every upload will be refused")
+	}
+
 	ctl := &control.Server{
 		Store: st, Sessions: sessions, Name: cfg.Name,
 		UDPPort: mustPort(firstAddr(cfg.UDPListen)), TCPPort: mustPort(firstAddr(cfg.TCPListen)),
@@ -161,6 +215,7 @@ func serve(cfg *config.Config) error {
 		Runs:             runStore,
 		AppRange:         appRange,
 		PublicControlURL: publicControlURL(cfg),
+		OIDC:             idp,
 	}
 	// Left nil when there is no raw socket, so the handler answers "not implemented" with a
 	// reason rather than failing somewhere deeper.
@@ -261,7 +316,47 @@ func serve(cfg *config.Config) error {
 		})
 	})
 	adminSrv := &http.Server{Addr: cfg.AdminListen, Handler: admin, ReadHeaderTimeout: 10 * time.Second}
-	go func() { errCh <- fmt.Errorf("admin: %w", adminSrv.ListenAndServe()) }()
+	if cfg.AdminTLSCert != "" {
+		// Terminated here rather than behind a reverse proxy: this binary already serves TLS for
+		// the control plane, so it is reuse rather than new machinery, and one process with one
+		// config file is the property that makes this pleasant to run. A proxy would also invite
+		// someone to later front the control plane too, which would break SPKI pinning.
+		reloader, err := certreload.New(cfg.AdminTLSCert, cfg.AdminTLSKey)
+		if err != nil {
+			return fmt.Errorf("admin TLS: %w", err)
+		}
+		adminSrv.TLSConfig = reloader.TLSConfig()
+		if exp := reloader.NotAfter(); !exp.IsZero() {
+			slog.Info("admin UI TLS", "listen", cfg.AdminListen, "cert_expires", exp.Format(time.RFC3339))
+			if time.Until(exp) < 14*24*time.Hour {
+				slog.Warn("admin certificate expires soon", "expires", exp.Format(time.RFC3339))
+			}
+		}
+		go func() { errCh <- fmt.Errorf("admin: %w", adminSrv.ListenAndServeTLS("", "")) }()
+	} else {
+		go func() { errCh <- fmt.Errorf("admin: %w", adminSrv.ListenAndServe()) }()
+	}
+
+	// ACME HTTP-01 responder. Permanent rather than started per renewal: nothing binds and
+	// unbinds, so a renewal cannot fail because the port was briefly busy, and the ACME client
+	// needs only write access to a directory instead of the privilege to bind a low port.
+	if cfg.ACMEHTTPListen != "" {
+		webroot := cfg.ACMEWebroot
+		if webroot == "" {
+			webroot = filepath.Join(cfg.StateDir, "acme")
+		}
+		if err := acmehttp.EnsureWebroot(webroot); err != nil {
+			return fmt.Errorf("acme webroot: %w", err)
+		}
+		acmeSrv := &http.Server{
+			Addr:              cfg.ACMEHTTPListen,
+			Handler:           acmehttp.Handler(webroot, cfg.AdminBaseURL),
+			ReadHeaderTimeout: 10 * time.Second,
+		}
+		slog.Info("acme http-01 responder", "listen", cfg.ACMEHTTPListen, "webroot", webroot,
+			"redirects_to", cfg.AdminBaseURL)
+		go func() { errCh <- fmt.Errorf("acme-http: %w", acmeSrv.ListenAndServe()) }()
+	}
 
 	// UDP data plane — one socket per configured address. Distinct sockets
 	// (not wildcard) also guarantee responses leave from the address the
@@ -493,3 +588,48 @@ func publicControlURL(cfg *config.Config) string {
 	}
 	return "https://" + addr
 }
+
+// setAdminPassword stores the break-glass admin credential.
+//
+// The password is read from stdin rather than taken as a flag, so it never lands in shell
+// history, in the process list where any local user can see it, or in a systemd unit. Piping is
+// still possible for automation:
+//
+//	printf '%s' "$PW" | echolot-server --set-admin-password --admin-user ops
+func setAdminPassword(cfg *config.Config) error {
+	st, err := store.Open(cfg.StateDir)
+	if err != nil {
+		return fmt.Errorf("state store: %w", err)
+	}
+	fmt.Fprintf(os.Stderr, "New password for %q (input is not echoed if this is a terminal): ", cfg.AdminUser)
+	pw, err := readSecret()
+	if err != nil {
+		return err
+	}
+	fmt.Fprintln(os.Stderr)
+
+	cred, err := adminauth.NewCredential(cfg.AdminUser, pw)
+	if err != nil {
+		return err
+	}
+	if err := st.SetLocalAdmin(cred); err != nil {
+		return err
+	}
+	fmt.Fprintf(os.Stderr, "Break-glass admin %q set. This account works even when the identity\n"+
+		"provider does not, which is the point of it — treat the password accordingly.\n", cfg.AdminUser)
+	return nil
+}
+
+// readSecret reads one line from stdin, without echo where the terminal allows it.
+func readSecret() (string, error) {
+	restore, _ := system.DisableEcho(os.Stdin)
+	if restore != nil {
+		defer restore()
+	}
+	r := bufio.NewReader(os.Stdin)
+	line, err := r.ReadString('\n')
+	if err != nil && line == "" {
+		return "", err
+	}
+	return strings.TrimSpace(line), nil
+}

server/internal/acmehttp/acmehttp.go

@@ -0,0 +1,100 @@
+// SPDX-FileCopyrightText: 2026 Echolot contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+// Package acmehttp answers ACME HTTP-01 challenges and sends everything else to HTTPS.
+//
+// HTTP-01 validation always arrives on port 80 — the CA chooses the port, not the operator — so
+// it never collides with an admin UI on 443. That leaves two ways to answer it: let the ACME
+// client bind port 80 for a few seconds during each renewal, or keep something there permanently
+// that serves the challenge directory. This is the second, and it is the better trade:
+//
+//   - nothing binds and unbinds, so renewal cannot fail because the port was briefly busy;
+//   - the ACME client needs no privileges to bind a low port, only write access to a directory;
+//   - port 80 gets a use it would want anyway, redirecting people who typed http:// to the real
+//     thing instead of hanging.
+//
+// It is the same arrangement as the webroot plugins for Apache and nginx, and it works with any
+// ACME client that can write a file: `lego --http.webroot`, `certbot --webroot`, `acme.sh -w`.
+//
+// The ACME client stays an external program on purpose. lego is also a Go library, but importing
+// it would put a large dependency tree into a server that deliberately has none — and the CLI does
+// the same job from a timer.
+package acmehttp
+
+import (
+	"log/slog"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// ChallengePath is the fixed prefix ACME uses. It is not configurable, by the specification.
+const ChallengePath = "/.well-known/acme-challenge/"
+
+// Handler serves challenge tokens from webroot and redirects everything else to redirectTo.
+//
+// webroot is the directory an ACME client writes into; the tokens themselves land in
+// <webroot>/.well-known/acme-challenge/<token>, which is exactly what --http.webroot expects.
+func Handler(webroot, redirectTo string) http.Handler {
+	mux := http.NewServeMux()
+
+	mux.HandleFunc(ChallengePath, func(w http.ResponseWriter, r *http.Request) {
+		token := strings.TrimPrefix(r.URL.Path, ChallengePath)
+		// Tokens are base64url from the CA. Anything else is somebody probing, and refusing by
+		// shape means path traversal never gets as far as touching the filesystem.
+		if token == "" || !validToken(token) {
+			http.NotFound(w, r)
+			return
+		}
+		body, err := os.ReadFile(filepath.Join(webroot, filepath.FromSlash(ChallengePath), token))
+		if err != nil {
+			// Logged at info: a challenge that cannot be answered is why a renewal failed, and
+			// that is worth being able to see afterwards rather than guessing at it.
+			slog.Info("acme challenge not found", "token", token, "webroot", webroot)
+			http.NotFound(w, r)
+			return
+		}
+		slog.Info("answered acme challenge", "token", token, "from", r.RemoteAddr)
+		w.Header().Set("Content-Type", "text/plain")
+		_, _ = w.Write(body)
+	})
+
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		if redirectTo == "" {
+			http.Error(w, "this port serves ACME challenges only", http.StatusNotFound)
+			return
+		}
+		// 308 rather than 302: the method must not change, and the redirect is permanent in the
+		// sense that matters — this port will never serve the application.
+		http.Redirect(w, r, strings.TrimRight(redirectTo, "/")+r.URL.RequestURI(), http.StatusPermanentRedirect)
+	})
+
+	return mux
+}
+
+// validToken accepts only the base64url alphabet the ACME spec uses for tokens.
+//
+// A shape check rather than a path check: "../../etc/shadow" fails here before any filesystem
+// call, which is a stronger guarantee than sanitising a path and hoping the sanitiser is right.
+func validToken(s string) bool {
+	if len(s) > 128 {
+		return false
+	}
+	for _, r := range s {
+		switch {
+		case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9', r == '-', r == '_', r == '.':
+		default:
+			return false
+		}
+	}
+	// A bare "." or ".." never appears in a real token and is the one traversal the alphabet
+	// above would otherwise permit.
+	return s != "." && s != ".."
+}
+
+// EnsureWebroot creates the challenge directory, so an ACME client's first run does not fail on a
+// missing path and an operator does not have to know the layout.
+func EnsureWebroot(webroot string) error {
+	return os.MkdirAll(filepath.Join(webroot, filepath.FromSlash(ChallengePath)), 0o755)
+}

server/internal/acmehttp/acmehttp_test.go

@@ -0,0 +1,98 @@
+// SPDX-FileCopyrightText: 2026 Echolot contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+package acmehttp
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func serve(t *testing.T, redirectTo string) (http.Handler, string) {
+	t.Helper()
+	root := t.TempDir()
+	if err := EnsureWebroot(root); err != nil {
+		t.Fatal(err)
+	}
+	return Handler(root, redirectTo), root
+}
+
+func TestServesAChallengeTokenWrittenByAnAcmeClient(t *testing.T) {
+	h, root := serve(t, "https://admin.example.net")
+	// Exactly what `lego --http.webroot` writes.
+	token := "abc-123_XYZ"
+	want := "abc-123_XYZ.keyauthorization-part"
+	if err := os.WriteFile(filepath.Join(root, ".well-known", "acme-challenge", token), []byte(want), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, httptest.NewRequest("GET", ChallengePath+token, nil))
+	if rec.Code != 200 {
+		t.Fatalf("challenge not served: %d", rec.Code)
+	}
+	if rec.Body.String() != want {
+		t.Fatalf("body = %q, want %q", rec.Body.String(), want)
+	}
+}
+
+// The token comes from the network and is used to build a path. Rejecting by *shape* means
+// traversal never reaches the filesystem at all, which is a stronger guarantee than sanitising.
+func TestTraversalNeverTouchesTheFilesystem(t *testing.T) {
+	h, root := serve(t, "https://admin.example.net")
+	secret := filepath.Join(filepath.Dir(root), "secret.txt")
+	if err := os.WriteFile(secret, []byte("do not serve me"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	for _, bad := range []string{
+		"../secret.txt",
+		"..%2Fsecret.txt",
+		"../../etc/passwd",
+		"..",
+		".",
+		"a/b",
+		"tok%20en", // a space arrives percent-encoded; a literal one is not a valid request line
+	} {
+		rec := httptest.NewRecorder()
+		h.ServeHTTP(rec, httptest.NewRequest("GET", ChallengePath+bad, nil))
+		if rec.Code == 200 && rec.Body.String() == "do not serve me" {
+			t.Fatalf("served a file outside the challenge directory via %q", bad)
+		}
+	}
+}
+
+func TestEverythingElseRedirectsToHTTPS(t *testing.T) {
+	h, _ := serve(t, "https://admin.example.net")
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, httptest.NewRequest("GET", "/devices?page=2", nil))
+	if rec.Code != http.StatusPermanentRedirect {
+		t.Fatalf("code = %d, want 308", rec.Code)
+	}
+	// The path and query must survive, or a bookmarked link lands on the wrong page.
+	if got := rec.Header().Get("Location"); got != "https://admin.example.net/devices?page=2" {
+		t.Fatalf("Location = %q", got)
+	}
+}
+
+// With no admin URL configured there is nowhere to send people, and inventing one would be worse
+// than saying so.
+func TestNoRedirectTargetIsHonest(t *testing.T) {
+	h, _ := serve(t, "")
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, httptest.NewRequest("GET", "/", nil))
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("code = %d, want 404", rec.Code)
+	}
+}
+
+func TestMissingTokenIsNotFound(t *testing.T) {
+	h, _ := serve(t, "https://admin.example.net")
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, httptest.NewRequest("GET", ChallengePath+"never-written", nil))
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("code = %d, want 404", rec.Code)
+	}
+}

server/internal/adminauth/adminauth.go

@@ -0,0 +1,253 @@
+// SPDX-FileCopyrightText: 2026 Echolot contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+// Package adminauth handles who may administer the server.
+//
+// Two ways in, deliberately:
+//
+//   - **OIDC**, the normal one. Identity lives in the operator's own IdP.
+//   - **A local admin password**, the break-glass one. If the IdP is misconfigured, unreachable,
+//     or the operator fat-fingered the admin group, they would otherwise be locked out of their
+//     own server with no way back in short of editing JSON on disk. A fallback that only works
+//     when everything else is broken is exactly the thing you cannot add later, because by then
+//     you cannot get in to add it.
+//
+// The local password is stored as PBKDF2-HMAC-SHA256, from the standard library (Go 1.24+), with
+// a per-credential salt. Not because password login is encouraged — it is the fallback — but
+// because a break-glass credential is precisely the one most likely to end up in a backup or a
+// config-management repo, and a hash survives that where a bearer token does not.
+//
+// There is no email reset flow and there should not be: `--set-admin-password` on the host *is*
+// the reset, and anyone who can run it already has the machine.
+package adminauth
+
+import (
+	"crypto/hmac"
+	"crypto/pbkdf2"
+	"crypto/rand"
+	"crypto/sha256"
+	"crypto/subtle"
+	"encoding/base64"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// iterations follows OWASP's guidance for PBKDF2-HMAC-SHA256. Deliberately slow: this credential
+// is used a handful of times in a server's life, so the cost is invisible to the operator and
+// meaningful to anyone grinding a stolen hash.
+const iterations = 600_000
+
+const (
+	saltLen = 16
+	keyLen  = 32
+)
+
+// Credential is a stored local admin password.
+type Credential struct {
+	Username   string `json:"username"`
+	Salt       string `json:"salt"` // hex
+	Hash       string `json:"hash"` // hex
+	Iterations int    `json:"iterations"`
+	Updated    string `json:"updated,omitempty"`
+}
+
+// NewCredential derives a stored credential from a plaintext password.
+func NewCredential(username, password string) (Credential, error) {
+	if strings.TrimSpace(username) == "" {
+		return Credential{}, errors.New("username must not be empty")
+	}
+	// Twelve is not a policy so much as a floor: this is the one account that can reach
+	// everything, and it is not rate-limited by a human being's patience.
+	if len(password) < 12 {
+		return Credential{}, errors.New("password must be at least 12 characters")
+	}
+	salt := make([]byte, saltLen)
+	if _, err := rand.Read(salt); err != nil {
+		return Credential{}, err
+	}
+	key, err := pbkdf2.Key(sha256.New, password, salt, iterations, keyLen)
+	if err != nil {
+		return Credential{}, err
+	}
+	return Credential{
+		Username:   username,
+		Salt:       hex.EncodeToString(salt),
+		Hash:       hex.EncodeToString(key),
+		Iterations: iterations,
+		Updated:    time.Now().UTC().Format(time.RFC3339),
+	}, nil
+}
+
+// Verify checks a username and password against this credential.
+//
+// Both comparisons are constant-time, including the username: a fast rejection on an unknown
+// username is a timing oracle for which usernames exist. The stored iteration count is used
+// rather than the current constant, so raising the constant does not lock out existing passwords.
+func (c Credential) Verify(username, password string) bool {
+	if c.Username == "" || c.Hash == "" {
+		return false
+	}
+	salt, err := hex.DecodeString(c.Salt)
+	if err != nil {
+		return false
+	}
+	want, err := hex.DecodeString(c.Hash)
+	if err != nil {
+		return false
+	}
+	iter := c.Iterations
+	if iter <= 0 {
+		iter = iterations
+	}
+	got, err := pbkdf2.Key(sha256.New, password, salt, iter, len(want))
+	if err != nil {
+		return false
+	}
+	userOK := subtle.ConstantTimeCompare([]byte(c.Username), []byte(username)) == 1
+	passOK := subtle.ConstantTimeCompare(got, want) == 1
+	return userOK && passOK
+}
+
+// Throttle slows repeated failures against the local password.
+//
+// The local admin is a single well-known account guarding everything, so an unthrottled login
+// form is an offline-speed guessing oracle that happens to be online. This is deliberately crude
+// — a delay that grows with consecutive failures and resets on success — because the goal is to
+// make guessing impractical, not to build a lockout system that an operator can trap themselves
+// with. It never locks permanently: a break-glass credential that can be locked out by an
+// attacker is a denial of service against the person who needs it most.
+type Throttle struct {
+	mu       sync.Mutex
+	failures int
+	last     time.Time
+	now      func() time.Time
+}
+
+func NewThrottle() *Throttle { return &Throttle{now: time.Now} }
+
+// Delay is how long the caller should wait before answering, given the failures so far.
+func (t *Throttle) Delay() time.Duration {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	// A quiet minute forgives everything, so an operator returning later is not punished for
+	// somebody else's earlier attempts.
+	if !t.last.IsZero() && t.now().Sub(t.last) > time.Minute {
+		t.failures = 0
+	}
+	switch {
+	case t.failures == 0:
+		return 0
+	case t.failures < 3:
+		return 250 * time.Millisecond
+	case t.failures < 6:
+		return time.Second
+	default:
+		return 3 * time.Second
+	}
+}
+
+func (t *Throttle) Failed() {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	t.failures++
+	t.last = t.now()
+}
+
+func (t *Throttle) Succeeded() {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	t.failures = 0
+}
+
+// ---- sessions ---------------------------------------------------------------------------
+
+// Session is an authenticated admin, however they proved it.
+type Session struct {
+	// Subject is the account id: "local:<username>" or "<issuer>#<sub>" from OIDC.
+	Subject string
+	// Display is what the UI shows.
+	Display string
+	Expires time.Time
+}
+
+// Sessions mints and checks signed session cookies.
+//
+// The cookie carries its own contents and a MAC, so there is no server-side session table to
+// grow, expire, or lose on restart — and equally no way to revoke one early, which is why they
+// are short-lived. The secret is persisted, so an operator's session survives a service restart;
+// regenerating it (deleting it from the state file) invalidates every session at once, which is
+// the revocation mechanism.
+type Sessions struct {
+	secret []byte
+	ttl    time.Duration
+}
+
+func NewSessions(secret []byte, ttl time.Duration) *Sessions {
+	if ttl <= 0 {
+		ttl = 12 * time.Hour
+	}
+	return &Sessions{secret: append([]byte(nil), secret...), ttl: ttl}
+}
+
+// NewSecret makes a fresh signing secret for first start.
+func NewSecret() ([]byte, error) {
+	b := make([]byte, 32)
+	_, err := rand.Read(b)
+	return b, err
+}
+
+var ErrSession = errors.New("session is not valid")
+
+// Issue returns the cookie value for a newly authenticated admin.
+func (s *Sessions) Issue(subject, display string) string {
+	exp := time.Now().Add(s.ttl).Unix()
+	payload := base64.RawURLEncoding.EncodeToString([]byte(subject)) + "." +
+		base64.RawURLEncoding.EncodeToString([]byte(display)) + "." +
+		strconv.FormatInt(exp, 10)
+	return payload + "." + s.mac(payload)
+}
+
+// Parse checks a cookie value and returns the session it encodes.
+func (s *Sessions) Parse(value string) (*Session, error) {
+	i := strings.LastIndex(value, ".")
+	if i < 0 {
+		return nil, ErrSession
+	}
+	payload, sig := value[:i], value[i+1:]
+	// MAC first, always. Nothing in the payload is believed — not even its shape — before the
+	// signature has been checked.
+	if !hmac.Equal([]byte(sig), []byte(s.mac(payload))) {
+		return nil, ErrSession
+	}
+	parts := strings.Split(payload, ".")
+	if len(parts) != 3 {
+		return nil, ErrSession
+	}
+	subject, err := base64.RawURLEncoding.DecodeString(parts[0])
+	if err != nil {
+		return nil, ErrSession
+	}
+	display, err := base64.RawURLEncoding.DecodeString(parts[1])
+	if err != nil {
+		return nil, ErrSession
+	}
+	exp, err := strconv.ParseInt(parts[2], 10, 64)
+	if err != nil {
+		return nil, ErrSession
+	}
+	if time.Now().After(time.Unix(exp, 0)) {
+		return nil, fmt.Errorf("%w: expired", ErrSession)
+	}
+	return &Session{Subject: string(subject), Display: string(display), Expires: time.Unix(exp, 0)}, nil
+}
+
+func (s *Sessions) mac(payload string) string {
+	m := hmac.New(sha256.New, s.secret)
+	m.Write([]byte(payload))
+	return base64.RawURLEncoding.EncodeToString(m.Sum(nil))
+}

server/internal/adminauth/adminauth_test.go

@@ -0,0 +1,203 @@
+// SPDX-FileCopyrightText: 2026 Echolot contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+package adminauth
+
+import (
+	"strings"
+	"testing"
+	"time"
+)
+
+// PBKDF2 at 600k iterations is slow on purpose, so these use a reduced count where the test is
+// about logic rather than cost.
+func fastCredential(t *testing.T, user, pass string) Credential {
+	t.Helper()
+	c, err := NewCredential(user, pass)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return c
+}
+
+func TestVerifyAcceptsOnlyTheRightPair(t *testing.T) {
+	c := fastCredential(t, "admin", "correct-horse-battery")
+
+	if !c.Verify("admin", "correct-horse-battery") {
+		t.Fatal("the correct credentials were rejected")
+	}
+	for _, tc := range []struct{ user, pass string }{
+		{"admin", "wrong-password-here"},
+		{"admin", ""},
+		{"root", "correct-horse-battery"},
+		{"", "correct-horse-battery"},
+		{"ADMIN", "correct-horse-battery"}, // usernames are not case-folded
+	} {
+		if c.Verify(tc.user, tc.pass) {
+			t.Errorf("accepted %q/%q", tc.user, tc.pass)
+		}
+	}
+}
+
+// Two credentials with the same password must not share a hash, or one cracked password reveals
+// every reuse of it and a precomputed table works against all of them.
+func TestSaltsDiffer(t *testing.T) {
+	a := fastCredential(t, "admin", "the-same-password-x")
+	b := fastCredential(t, "admin", "the-same-password-x")
+	if a.Salt == b.Salt {
+		t.Fatal("two credentials share a salt")
+	}
+	if a.Hash == b.Hash {
+		t.Fatal("the same password produced the same hash twice")
+	}
+	// Both must still verify — a salt that is not actually used would also produce differing
+	// hashes if it were mixed in wrongly.
+	if !a.Verify("admin", "the-same-password-x") || !b.Verify("admin", "the-same-password-x") {
+		t.Fatal("a salted credential does not verify")
+	}
+}
+
+// The stored iteration count is used rather than the current constant, so raising the constant
+// later does not silently lock out every existing password.
+func TestOldIterationCountsStillVerify(t *testing.T) {
+	c := fastCredential(t, "admin", "a-perfectly-fine-pw")
+	c.Iterations = iterations // as stored
+	if !c.Verify("admin", "a-perfectly-fine-pw") {
+		t.Fatal("credential does not verify with its stored iteration count")
+	}
+	// A credential written before the field existed must not be treated as zero-iteration.
+	c.Iterations = 0
+	if !c.Verify("admin", "a-perfectly-fine-pw") {
+		t.Fatal("a credential with no recorded iteration count failed to verify")
+	}
+}
+
+func TestWeakInputsAreRefusedAtCreation(t *testing.T) {
+	if _, err := NewCredential("", "long-enough-password"); err == nil {
+		t.Error("an empty username was accepted")
+	}
+	if _, err := NewCredential("admin", "short"); err == nil {
+		t.Error("a short password was accepted")
+	}
+}
+
+func TestAnEmptyCredentialNeverVerifies(t *testing.T) {
+	var zero Credential
+	if zero.Verify("", "") {
+		t.Fatal("a server with no local admin configured accepted empty credentials")
+	}
+	if zero.Verify("admin", "anything") {
+		t.Fatal("an unset credential verified")
+	}
+}
+
+// ---- sessions ----------------------------------------------------------------------------
+
+func TestSessionRoundTrip(t *testing.T) {
+	secret, _ := NewSecret()
+	s := NewSessions(secret, time.Hour)
+	got, err := s.Parse(s.Issue("local:admin", "Admin"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.Subject != "local:admin" || got.Display != "Admin" {
+		t.Fatalf("session did not round-trip: %+v", got)
+	}
+}
+
+// The cookie carries its own contents, so the MAC is the only thing standing between a user and
+// promoting themselves. Every tampered form must fail.
+func TestTamperedSessionsAreRejected(t *testing.T) {
+	secret, _ := NewSecret()
+	s := NewSessions(secret, time.Hour)
+	good := s.Issue("local:admin", "Admin")
+
+	parts := strings.Split(good, ".")
+	tampered := []string{
+		"",
+		"garbage",
+		good + "x", // signature altered
+		strings.Replace(good, parts[0], "Zm9v", 1), // subject swapped
+		strings.Join(parts[:len(parts)-1], "."),    // signature removed
+		parts[0] + "." + parts[1] + "." + parts[2], // signature removed, well-formed payload
+	}
+	for _, v := range tampered {
+		if _, err := s.Parse(v); err == nil {
+			t.Errorf("accepted a tampered session: %q", v)
+		}
+	}
+}
+
+func TestSessionsFromAnotherSecretAreRejected(t *testing.T) {
+	a, _ := NewSecret()
+	b, _ := NewSecret()
+	issued := NewSessions(a, time.Hour).Issue("local:admin", "Admin")
+	if _, err := NewSessions(b, time.Hour).Parse(issued); err == nil {
+		t.Fatal("a session signed with a different secret was accepted — rotating the secret " +
+			"must invalidate every existing session")
+	}
+}
+
+func TestExpiredSessionsAreRejected(t *testing.T) {
+	secret, _ := NewSecret()
+	// A negative TTL is not reachable through NewSessions, so issue with a real one and check
+	// the boundary via a session that has already run out.
+	s := NewSessions(secret, time.Millisecond)
+	v := s.Issue("local:admin", "Admin")
+	time.Sleep(10 * time.Millisecond)
+	if _, err := s.Parse(v); err == nil {
+		t.Fatal("an expired session was accepted")
+	}
+}
+
+// ---- throttle ------------------------------------------------------------------------------
+
+func TestThrottleGrowsWithFailuresAndResetsOnSuccess(t *testing.T) {
+	tr := NewThrottle()
+	if d := tr.Delay(); d != 0 {
+		t.Fatalf("a first attempt was delayed by %v", d)
+	}
+	for i := 0; i < 2; i++ {
+		tr.Failed()
+	}
+	first := tr.Delay()
+	for i := 0; i < 6; i++ {
+		tr.Failed()
+	}
+	later := tr.Delay()
+	if !(later > first && first > 0) {
+		t.Fatalf("delay did not grow with failures: %v then %v", first, later)
+	}
+	tr.Succeeded()
+	if d := tr.Delay(); d != 0 {
+		t.Fatalf("a successful login did not clear the throttle: %v", d)
+	}
+}
+
+// A break-glass credential that an attacker can lock out is a denial of service against the one
+// person who needs it. The delay must stay bounded rather than becoming a lockout.
+func TestThrottleNeverLocksOutPermanently(t *testing.T) {
+	tr := NewThrottle()
+	for i := 0; i < 1000; i++ {
+		tr.Failed()
+	}
+	if d := tr.Delay(); d > 10*time.Second {
+		t.Fatalf("throttle became a lockout: %v", d)
+	}
+}
+
+func TestThrottleForgivesAfterAQuietPeriod(t *testing.T) {
+	tr := NewThrottle()
+	now := time.Now()
+	tr.now = func() time.Time { return now }
+	for i := 0; i < 10; i++ {
+		tr.Failed()
+	}
+	if tr.Delay() == 0 {
+		t.Fatal("failures did not register")
+	}
+	now = now.Add(2 * time.Minute)
+	if d := tr.Delay(); d != 0 {
+		t.Fatalf("an operator returning later was still throttled: %v", d)
+	}
+}

server/internal/certreload/certreload.go

@@ -0,0 +1,124 @@
+// SPDX-FileCopyrightText: 2026 Echolot contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+// Package certreload serves a TLS certificate that can be replaced on disk without a restart.
+//
+// The hard part of TLS is never termination — the stdlib does that — it is renewal. A certificate
+// obtained from an ACME client expires every sixty days, and the usual arrangement is a renewal
+// hook that reloads or restarts the service. That hook is the part that quietly fails: it works
+// when it is written and then, months later, does not, and nobody notices until the certificate
+// has already expired.
+//
+// So the certificate is re-read when the file changes. There is no hook to forget, no reload to
+// coordinate, and a renewal that drops new files in place is picked up on the next handshake.
+//
+// Deliberately not used for the control plane. Clients pin that certificate's public key
+// (probe-protocol.md §1), so swapping it at runtime would silently break every enrolled device —
+// there the operator *should* have to think, and a restart is the least of what a key rotation
+// costs. Two listeners, two different right answers.
+package certreload
+
+import (
+	"crypto/tls"
+	"fmt"
+	"os"
+	"sync"
+	"time"
+)
+
+// Reloader holds a certificate and refreshes it when the files on disk change.
+type Reloader struct {
+	certPath, keyPath string
+
+	mu       sync.RWMutex
+	cert     *tls.Certificate
+	certMod  time.Time
+	keyMod   time.Time
+	checked  time.Time
+	interval time.Duration
+}
+
+// New loads the pair once so a bad path fails at startup rather than at the first handshake,
+// when the only symptom is a connection error at the far end.
+func New(certPath, keyPath string) (*Reloader, error) {
+	r := &Reloader{certPath: certPath, keyPath: keyPath, interval: 30 * time.Second}
+	if err := r.load(); err != nil {
+		return nil, err
+	}
+	return r, nil
+}
+
+// TLSConfig returns a config that asks this reloader for the certificate on every handshake.
+func (r *Reloader) TLSConfig() *tls.Config {
+	return &tls.Config{
+		MinVersion:     tls.VersionTLS12,
+		GetCertificate: r.getCertificate,
+	}
+}
+
+func (r *Reloader) getCertificate(*tls.ClientHelloInfo) (*tls.Certificate, error) {
+	r.maybeReload()
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	if r.cert == nil {
+		return nil, fmt.Errorf("no certificate loaded")
+	}
+	return r.cert, nil
+}
+
+// maybeReload stats the files at most once per interval.
+//
+// Rate-limited because this runs on every handshake: a busy listener would otherwise stat twice
+// per connection, and a certificate that is thirty seconds stale has never mattered to anyone.
+func (r *Reloader) maybeReload() {
+	r.mu.RLock()
+	fresh := time.Since(r.checked) < r.interval
+	r.mu.RUnlock()
+	if fresh {
+		return
+	}
+
+	r.mu.Lock()
+	r.checked = time.Now()
+	certMod, keyMod := modTime(r.certPath), modTime(r.keyPath)
+	unchanged := certMod.Equal(r.certMod) && keyMod.Equal(r.keyMod)
+	r.mu.Unlock()
+	if unchanged {
+		return
+	}
+	// A failed reload keeps the certificate already in memory. Renewal tools write the two files
+	// separately, so there is a window where the pair does not match; serving the previous
+	// certificate through that window is strictly better than serving none.
+	_ = r.load()
+}
+
+func (r *Reloader) load() error {
+	cert, err := tls.LoadX509KeyPair(r.certPath, r.keyPath)
+	if err != nil {
+		return fmt.Errorf("loading %s / %s: %w", r.certPath, r.keyPath, err)
+	}
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.cert = &cert
+	r.certMod, r.keyMod = modTime(r.certPath), modTime(r.keyPath)
+	return nil
+}
+
+// NotAfter is when the loaded certificate expires, for the admin UI to show and for a startup
+// warning. An expiry an operator can see is one they can act on before a browser tells them.
+func (r *Reloader) NotAfter() time.Time {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	if r.cert == nil || r.cert.Leaf == nil {
+		return time.Time{}
+	}
+	return r.cert.Leaf.NotAfter
+}
+
+func modTime(path string) time.Time {
+	fi, err := os.Stat(path)
+	if err != nil {
+		return time.Time{}
+	}
+	return fi.ModTime()
+}

server/internal/certreload/certreload_test.go

@@ -0,0 +1,119 @@
+// SPDX-FileCopyrightText: 2026 Echolot contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+package certreload
+
+import (
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/x509"
+	"crypto/x509/pkix"
+	"encoding/pem"
+	"math/big"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+func writePair(t *testing.T, dir, cn string) (string, string) {
+	t.Helper()
+	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	tmpl := x509.Certificate{
+		SerialNumber: big.NewInt(time.Now().UnixNano()),
+		Subject:      pkix.Name{CommonName: cn},
+		NotBefore:    time.Now().Add(-time.Hour),
+		NotAfter:     time.Now().Add(24 * time.Hour),
+	}
+	der, err := x509.CreateCertificate(rand.Reader, &tmpl, &tmpl, &key.PublicKey, key)
+	if err != nil {
+		t.Fatal(err)
+	}
+	certPath := filepath.Join(dir, "cert.pem")
+	keyPath := filepath.Join(dir, "key.pem")
+	cb := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der})
+	kb, _ := x509.MarshalECPrivateKey(key)
+	if err := os.WriteFile(certPath, cb, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(keyPath, pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: kb}), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return certPath, keyPath
+}
+
+func TestBadPathsFailAtStartupNotAtHandshake(t *testing.T) {
+	if _, err := New("/nonexistent/cert.pem", "/nonexistent/key.pem"); err == nil {
+		t.Fatal("a missing certificate was accepted; the failure would surface as an " +
+			"unexplained connection error at the client instead")
+	}
+}
+
+// The whole point: a renewal that drops new files in place is picked up without a restart and
+// without a reload hook that can silently stop working.
+func TestANewCertificateOnDiskIsPickedUp(t *testing.T) {
+	dir := t.TempDir()
+	certPath, keyPath := writePair(t, dir, "first")
+	r, err := New(certPath, keyPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	r.interval = 0 // check on every handshake, rather than waiting out the rate limit
+
+	got, err := r.getCertificate(nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	first := got.Leaf
+
+	time.Sleep(10 * time.Millisecond) // ensure a distinct mtime
+	writePair(t, dir, "second")
+
+	got, err = r.getCertificate(nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.Leaf != nil && first != nil && got.Leaf.SerialNumber.Cmp(first.SerialNumber) == 0 {
+		t.Fatal("the replaced certificate was not picked up")
+	}
+}
+
+// Renewal tools write the certificate and the key separately, so there is a window where the two
+// do not match. Serving the previous certificate through it beats serving none.
+func TestAHalfWrittenPairKeepsTheOldCertificate(t *testing.T) {
+	dir := t.TempDir()
+	certPath, keyPath := writePair(t, dir, "good")
+	r, err := New(certPath, keyPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	r.interval = 0
+
+	time.Sleep(10 * time.Millisecond)
+	if err := os.WriteFile(certPath, []byte("-----BEGIN CERTIFICATE-----\ntruncated\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	got, err := r.getCertificate(nil)
+	if err != nil {
+		t.Fatalf("a torn write took the listener down: %v", err)
+	}
+	if got == nil {
+		t.Fatal("no certificate served during a torn write")
+	}
+}
+
+func TestExpiryIsVisible(t *testing.T) {
+	dir := t.TempDir()
+	certPath, keyPath := writePair(t, dir, "x")
+	r, err := New(certPath, keyPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := r.NotAfter(); got.IsZero() || time.Until(got) > 48*time.Hour {
+		t.Fatalf("expiry not reported sensibly: %v", got)
+	}
+}

server/internal/config/config.go

@@ -10,6 +10,8 @@ package config
 import (
 	"flag"
 	"fmt"
+	"io"
+	"net"
 	"os"
 	"strconv"
 	"strings"
@@ -67,10 +69,57 @@ type Config struct {
 	// first control listen address.
 	PublicControlURL string // ECHOLOT_PUBLIC_URL / --public-url
 
+	// Identity provider. Empty issuer disables sign-in entirely; the server is a relying
+	// party and never stores passwords.
+	OIDCIssuer      string // ECHOLOT_OIDC_ISSUER / --oidc-issuer
+	OIDCClientID    string // ECHOLOT_OIDC_CLIENT_ID / --oidc-client-id (confidential, admin UI)
+	OIDCAppClientID string // ECHOLOT_OIDC_APP_CLIENT_ID / --oidc-app-client-id (public, the phone app)
+	OIDCAdminGroup  string // ECHOLOT_OIDC_ADMIN_GROUP / --oidc-admin-group
+
+	// Break-glass admin username; the password lives hashed in the state store.
+	AdminUser string // ECHOLOT_ADMIN_USER / --admin-user
+
+	// Secret for the *confidential* admin client. Prefer ECHOLOT_OIDC_CLIENT_SECRET_FILE: a path
+	// keeps the secret out of the environment, where it is readable by anything that can see
+	// /proc/<pid>/environ and lands in every dump of the unit's configuration.
+	OIDCClientSecret string // ECHOLOT_OIDC_CLIENT_SECRET / _FILE
+
+	// Where the admin UI is reachable, used to build the OIDC redirect URI. Must match what is
+	// registered at the IdP exactly.
+	AdminBaseURL string // ECHOLOT_ADMIN_BASE_URL / --admin-base-url
+	// TLS for the admin listener. Without these it serves plaintext, which is only acceptable on
+	// loopback — see checkAdminExposure.
+	AdminTLSCert string // ECHOLOT_ADMIN_TLS_CERT / --admin-tls-cert
+	AdminTLSKey  string // ECHOLOT_ADMIN_TLS_KEY / --admin-tls-key
+	// Deliberate override for serving the admin UI in plaintext off loopback, so that decision
+	// is made rather than stumbled into.
+	AdminInsecure bool // ECHOLOT_ADMIN_INSECURE / --admin-insecure
+
+	// Port-80 listener that answers ACME HTTP-01 challenges and redirects everything else to
+	// the admin UI. Empty disables it. HTTP-01 always arrives on port 80 — the CA picks the
+	// port — so this never collides with the admin UI on 443.
+	ACMEHTTPListen string // ECHOLOT_ACME_HTTP_LISTEN / --acme-http-listen
+	// Directory an ACME client writes challenge tokens into. Defaults to <state-dir>/acme.
+	ACMEWebroot string // ECHOLOT_ACME_WEBROOT / --acme-webroot
+
 	// Mode
 	Docker bool // --docker (or autodetected; env ECHOLOT_DOCKER=1 forces)
 }
 
+// secretOr reads ECHOLOT_<key>, or the contents of the file named by ECHOLOT_<key>_FILE.
+//
+// The file form exists because a secret in the environment is readable by anything that can see
+// /proc/<pid>/environ and lands in every dump of the unit's configuration. A path costs nothing
+// and keeps the value in one file whose permissions an operator can reason about.
+func secretOr(key, def string) string {
+	if path := envOr(key+"_FILE", ""); path != "" {
+		if b, err := os.ReadFile(path); err == nil {
+			return strings.TrimSpace(string(b))
+		}
+	}
+	return envOr(key, def)
+}
+
 // envInt reads ECHOLOT_<key> as an integer with a fallback.
 func envInt(key string, def int) int {
 	if v := envOr(key, ""); v != "" {
@@ -115,6 +164,17 @@ func Load(args []string) (*Config, *Actions, error) {
 	fs.IntVar(&c.UploadRetentionDays, "upload-retention-days", envInt("UPLOAD_RETENTION_DAYS", 90), "delete uploaded runs older than this; 0 disables")
 	fs.IntVar(&c.UploadMaxRuns, "upload-max-runs", envInt("UPLOAD_MAX_RUNS", 200), "keep at most this many runs per device; 0 disables")
 	fs.StringVar(&c.UploadMinAnon, "upload-min-anonymization", envOr("UPLOAD_MIN_ANONYMIZATION", "full"), "least anonymization accepted: full|balanced|strict")
+	fs.StringVar(&c.OIDCIssuer, "oidc-issuer", envOr("OIDC_ISSUER", ""), "OpenID Connect issuer URL; empty disables sign-in")
+	fs.StringVar(&c.OIDCClientID, "oidc-client-id", envOr("OIDC_CLIENT_ID", ""), "confidential OIDC client id for the admin UI")
+	fs.StringVar(&c.OIDCAppClientID, "oidc-app-client-id", envOr("OIDC_APP_CLIENT_ID", ""), "public OIDC client id used by the Android app (PKCE)")
+	fs.StringVar(&c.OIDCAdminGroup, "oidc-admin-group", envOr("OIDC_ADMIN_GROUP", ""), "group claim required for admin access; empty means nobody is an admin via OIDC")
+	fs.StringVar(&c.OIDCClientSecret, "oidc-client-secret", secretOr("OIDC_CLIENT_SECRET", ""), "secret for the confidential admin client; prefer ECHOLOT_OIDC_CLIENT_SECRET_FILE")
+	fs.StringVar(&c.AdminBaseURL, "admin-base-url", envOr("ADMIN_BASE_URL", ""), "public URL of the admin UI, for the OIDC redirect (e.g. https://admin.example.net)")
+	fs.StringVar(&c.AdminTLSCert, "admin-tls-cert", envOr("ADMIN_TLS_CERT", ""), "TLS certificate for the admin listener")
+	fs.StringVar(&c.AdminTLSKey, "admin-tls-key", envOr("ADMIN_TLS_KEY", ""), "TLS key for the admin listener")
+	fs.BoolVar(&c.AdminInsecure, "admin-insecure", envOr("ADMIN_INSECURE", "") == "1", "allow the admin UI in plaintext off loopback (you are on your own)")
+	fs.StringVar(&c.ACMEHTTPListen, "acme-http-listen", envOr("ACME_HTTP_LISTEN", ""), "port-80 listener for ACME HTTP-01 challenges and http->https redirects")
+	fs.StringVar(&c.ACMEWebroot, "acme-webroot", envOr("ACME_WEBROOT", ""), "directory an ACME client writes challenges into (default <state-dir>/acme)")
 	fs.StringVar(&c.PublicControlURL, "public-url", envOr("PUBLIC_URL", ""), "public control-plane URL for enrollment links, e.g. https://probe.example.net:8443")
 	fs.StringVar(&c.MinAppVersion, "min-app-version", envOr("MIN_APP_VERSION", "0.2.0"), "oldest app version this server will serve (SemVer, inclusive)")
 	fs.StringVar(&c.MaxAppVersion, "max-app-version", envOr("MAX_APP_VERSION", "1.0.0"), "first app version this server will refuse (SemVer, exclusive); empty = unbounded")
@@ -122,6 +182,12 @@ func Load(args []string) (*Config, *Actions, error) {
 
 	fs.BoolVar(&a.InstallSystemd, "install-systemd", false, "install a systemd unit for this binary and exit")
 	fs.BoolVar(&a.UninstallSystemd, "uninstall-systemd", false, "remove the systemd unit and exit")
+	var daemon bool
+	fs.BoolVar(&a.Serve, "serve", false, "run the server (bind listeners and answer requests)")
+	fs.BoolVar(&daemon, "daemon", false, "alias for --serve")
+	fs.BoolVar(&a.SetAdminPassword, "set-admin-password", false,
+		"set the break-glass admin password (username as --admin-user, password read from stdin) and exit")
+	fs.StringVar(&c.AdminUser, "admin-user", envOr("ADMIN_USER", "admin"), "username for the break-glass admin")
 	fs.BoolVar(&a.SelfUpdate, "self-update", false, "check for a newer release, replace this binary, and exit")
 	fs.BoolVar(&a.Version, "version", false, "print version and exit")
 
@@ -131,12 +197,78 @@ func Load(args []string) (*Config, *Actions, error) {
 	if !c.Docker {
 		c.Docker = inContainer()
 	}
+	a.Serve = a.Serve || daemon
+	// No verb at all means the caller has not said what they want. Usage is the answer, and it
+	// is a usage error rather than success — otherwise a service manager sees a clean exit and
+	// concludes the server ran and finished.
+	if !a.Serve && !a.InstallSystemd && !a.UninstallSystemd && !a.SelfUpdate &&
+		!a.SetAdminPassword && !a.Version {
+		a.Help = true
+	}
+	if a.Serve {
+		if err := c.checkAdminExposure(); err != nil {
+			return nil, nil, err
+		}
+	}
 	if c.Docker && (a.InstallSystemd || a.UninstallSystemd || a.SelfUpdate) {
 		return nil, nil, fmt.Errorf("systemd/self-update actions are native-mode only (container detected; override with ECHOLOT_DOCKER=0 if this is wrong)")
 	}
 	return c, a, nil
 }
 
+// Usage prints the verbs first and the tuning flags second, because the question someone has
+// when they run this by name is "what does it do", not "what can I set".
+func Usage(w io.Writer) {
+	fmt.Fprint(w, `echolot-server — the Echolot probe server
+
+USAGE
+  echolot-server --serve                 run the server
+  echolot-server --version               print the version
+  echolot-server --install-systemd       install and enable a systemd unit
+  echolot-server --uninstall-systemd     remove it
+  echolot-server --self-update           replace this binary with the latest release
+  echolot-server --set-admin-password    set the break-glass admin password (stdin)
+  echolot-server --help                  full flag list
+
+Every flag can also be set as an environment variable: --control-listen becomes
+ECHOLOT_CONTROL_LISTEN. In a container, configuration comes from the environment.
+
+Running with no verb prints this and exits non-zero: starting to serve the internet
+should be something you asked for.
+`)
+}
+
+// checkAdminExposure refuses to serve an unencrypted admin UI on a non-loopback address.
+//
+// The admin session cookie is a bearer credential for everything this server can do, and the OIDC
+// authorization code arrives in a URL. In plaintext, both are readable by anyone on the path — and
+// on a globally routable address "the path" means the internet. This is a hard stop rather than a
+// warning because a warning in a log is not read by the person who most needs it, and because the
+// two safe answers are cheap: bind to loopback and tunnel, or supply a certificate.
+func (c *Config) checkAdminExposure() error {
+	if c.AdminTLSCert != "" || c.AdminInsecure {
+		return nil
+	}
+	for _, addr := range Addrs(c.AdminListen) {
+		host, _, err := net.SplitHostPort(addr)
+		if err != nil {
+			continue
+		}
+		ip := net.ParseIP(strings.Trim(host, "[]"))
+		if host == "" || ip == nil || ip.IsLoopback() {
+			continue // loopback, or a name we cannot judge; RFC 8252 blesses loopback plaintext
+		}
+		return fmt.Errorf(
+			"refusing to serve the admin UI in plaintext on %s: the session cookie and the OIDC "+
+				"authorization code would cross the network in the clear.\n"+
+				"  Fix it one of three ways:\n"+
+				"    - bind to 127.0.0.1 and reach it over an SSH tunnel (no certificate needed)\n"+
+				"    - set ECHOLOT_ADMIN_TLS_CERT and ECHOLOT_ADMIN_TLS_KEY\n"+
+				"    - set ECHOLOT_ADMIN_INSECURE=1 if you genuinely mean it", addr)
+	}
+	return nil
+}
+
 // Addrs splits a comma-separated listen spec into individual addresses.
 // Explicit per-address binds matter on multi-IP hosts: a wildcard bind
 // (":8443") would also claim addresses reserved for other purposes (e.g. an
@@ -151,11 +283,19 @@ func Addrs(spec string) []string {
 	return out
 }
 
-// Actions are one-shot verbs that exit instead of serving.
+// Actions are the verbs. Serving is one of them, and it is explicit: running the binary with no
+// arguments prints usage rather than binding a dozen ports and starting to answer the internet.
+// Someone typing the name of an unfamiliar program on a terminal should be told what it does, not
+// have it start doing it.
 type Actions struct {
+	Serve bool
+	// Help is set when there is nothing to do: no verb was given.
+	Help bool
+
 	InstallSystemd   bool
 	UninstallSystemd bool
 	SelfUpdate       bool
+	SetAdminPassword bool
 	Version          bool
 }
 

server/internal/control/control.go

@@ -7,6 +7,7 @@
 package control
 
 import (
+	"context"
 	"crypto/rand"
 	"crypto/sha256"
 	"crypto/tls"
@@ -27,6 +28,7 @@ import (
 
 	"echo-lot.app/server/internal/compat"
 	"echo-lot.app/server/internal/dataplane"
+	"echo-lot.app/server/internal/oidc"
 	"echo-lot.app/server/internal/runs"
 	"echo-lot.app/server/internal/session"
 	"echo-lot.app/server/internal/store"
@@ -57,6 +59,8 @@ type Server struct {
 	// Granted server->client sends (spec §5). Both consume an asymmetric grant.
 	DownTrain func(sess *session.Session, g *session.Grant, count, sizeBytes, intervalUs int) (int, error)
 	BigSend   func(sess *session.Session, g *session.Grant, sizes []int, df bool) ([]dataplane.BigSendResult, error)
+	// OIDC verifies ID tokens when the operator has configured an issuer (may be nil).
+	OIDC *oidc.Verifier
 	// Runs stores uploaded measurement documents (may be nil: uploads unsupported).
 	Runs *runs.Store
 	// FragSend emits one datagram as hand-built IP fragments in a chosen order (may be nil:
@@ -162,6 +166,9 @@ func (s *Server) Handler() http.Handler {
 	mux.HandleFunc("GET /v1/runs", gate(s.listRuns))
 	mux.HandleFunc("GET /v1/runs/{id}", gate(s.getRun))
 	mux.HandleFunc("DELETE /v1/runs/{id}", gate(s.deleteRun))
+	mux.HandleFunc("POST /v1/account/link", gate(s.linkAccount))
+	mux.HandleFunc("DELETE /v1/account/link", gate(s.unlinkAccount))
+	mux.HandleFunc("GET /v1/account", gate(s.accountStatus))
 	// TODO(spec §5): frag_send, throughput (both build on the same grant machinery)
 	return mux
 }
@@ -618,6 +625,10 @@ func (s *Server) profile(w http.ResponseWriter, r *http.Request) {
 		// The app needs the upload rules before it offers the switch: whether uploads are
 		// accepted at all, and how much identifying detail it must strip first.
 		"uploads": s.uploadPolicy(),
+		// What a client needs to start a sign-in, without hard-coding the operator's IdP into
+		// the app: where to authorize, which client id to use, and whether it is worth offering
+		// sign-in at all on this server.
+		"auth": s.authInfo(r.Context()),
 		// What this build speaks, and which app versions it will serve. A client checks the
 		// server side of the same question against its own bounds.
 		"compat": map[string]any{
@@ -714,7 +725,7 @@ func (s *Server) uploadRun(w http.ResponseWriter, r *http.Request) {
 		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "read failed"})
 		return
 	}
-	meta, err := s.Runs.Put(dev.ID, body)
+	meta, err := s.Runs.Put(dev.ID, body, dev.LinkedToAccount())
 	switch {
 	case err == nil:
 		slog.Info("run uploaded", "device", dev.ID, "run", meta.ID,
@@ -808,3 +819,108 @@ func upstreamJSON(sess *session.Session) map[string]any {
 		"span_ms": u.SpanMs(), "kbps": u.Kbps(),
 	}
 }
+
+// authInfo advertises the sign-in configuration, so the app can present a Sign in button only
+// when there is something behind it, and can drive the flow without the user typing an issuer URL.
+func (s *Server) authInfo(ctx context.Context) map[string]any {
+	if s.OIDC == nil || !s.OIDC.Config().Enabled() {
+		return map[string]any{"enabled": false}
+	}
+	cfg := s.OIDC.Config()
+	out := map[string]any{
+		"enabled": true,
+		"issuer":  cfg.Issuer,
+		// The app's client, not the server's: this is what a phone should authorize as.
+		"client_id": cfg.AppClientID,
+		// The app is a public client on a phone: no secret can be kept, so PKCE is what
+		// protects the code exchange (RFC 7636), and the redirect comes back through the
+		// scheme the app already registers for enrollment links.
+		"flow":         "authorization_code+pkce",
+		"redirect_uri": "echolot://auth",
+		"scopes":       "openid profile email",
+	}
+	if d, err := s.OIDC.Discover(ctx); err == nil {
+		out["authorization_endpoint"] = d.AuthorizationEndpoint
+		out["token_endpoint"] = d.TokenEndpoint
+		out["end_session_endpoint"] = d.EndSessionEndpoint
+	} else {
+		// Reported rather than hidden: an unreachable IdP is the operator's problem to see, and
+		// a client that knows the difference can say "sign-in is configured but the provider is
+		// not answering" instead of failing obscurely.
+		out["discovery_error"] = err.Error()
+	}
+	return out
+}
+
+// linkAccount ties the calling device to the person whose ID token it presents.
+//
+// The device credential proves *which device*; the ID token proves *which person*. Both are
+// required, and neither substitutes for the other: enrollment admits a device to the server,
+// signing in attributes it to someone.
+func (s *Server) linkAccount(w http.ResponseWriter, r *http.Request) {
+	dev := s.Store.DeviceByCredential(bearer(r))
+	if dev == nil {
+		writeJSON(w, http.StatusUnauthorized, map[string]string{"error": "unknown credential"})
+		return
+	}
+	if s.OIDC == nil || !s.OIDC.Config().Enabled() {
+		writeJSON(w, http.StatusNotImplemented, map[string]string{
+			"error": "this server has no identity provider configured, so there is nothing to sign in to",
+		})
+		return
+	}
+	var body struct {
+		IDToken string `json:"id_token"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil || body.IDToken == "" {
+		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "expected an id_token"})
+		return
+	}
+	claims, err := s.OIDC.Verify(r.Context(), body.IDToken)
+	if err != nil {
+		// Deliberately terse to the client and detailed in the log: a caller probing token
+		// handling should not be told which check it failed.
+		slog.Info("rejected sign-in", "device", dev.ID, "err", err)
+		writeJSON(w, http.StatusForbidden, map[string]string{"error": "the identity token was not accepted"})
+		return
+	}
+	if err := s.Store.LinkAccount(dev.ID, claims.AccountID(), claims.Display()); err != nil {
+		writeJSON(w, http.StatusInternalServerError, map[string]string{"error": err.Error()})
+		return
+	}
+	slog.Info("device linked to account", "device", dev.ID, "account", claims.AccountID(),
+		"admin", s.OIDC.IsAdmin(claims))
+	writeJSON(w, http.StatusOK, map[string]any{
+		"account_id": claims.AccountID(), "display_name": claims.Display(),
+		"admin": s.OIDC.IsAdmin(claims),
+	})
+}
+
+// unlinkAccount signs out on this device. The device stays enrolled: signing out should not cost
+// someone their enrollment, which an operator had to grant.
+func (s *Server) unlinkAccount(w http.ResponseWriter, r *http.Request) {
+	dev := s.Store.DeviceByCredential(bearer(r))
+	if dev == nil {
+		writeJSON(w, http.StatusUnauthorized, map[string]string{"error": "unknown credential"})
+		return
+	}
+	if err := s.Store.LinkAccount(dev.ID, "", ""); err != nil {
+		writeJSON(w, http.StatusInternalServerError, map[string]string{"error": err.Error()})
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+func (s *Server) accountStatus(w http.ResponseWriter, r *http.Request) {
+	dev := s.Store.DeviceByCredential(bearer(r))
+	if dev == nil {
+		writeJSON(w, http.StatusUnauthorized, map[string]string{"error": "unknown credential"})
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{
+		"signed_in":    dev.LinkedToAccount(),
+		"account_id":   dev.AccountID,
+		"display_name": dev.AccountName,
+		"device_id":    dev.ID,
+	})
+}

server/internal/oidc/oidc.go

@@ -0,0 +1,504 @@
+// SPDX-FileCopyrightText: 2026 Echolot contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+// Package oidc verifies OpenID Connect ID tokens against a configured issuer.
+//
+// Echolot is a *relying party*, never an identity provider. It delegates to whatever IdP the
+// operator already runs and stores no passwords — no hashing, no reset flow, no lockout policy,
+// and no credential database to leak. For a tool people self-host on a box they also use for
+// other things, that is the difference between "one more service" and "one more thing that can
+// lose your users' passwords".
+//
+// Verification is written against the stdlib rather than a JWT library, because the server has no
+// external dependencies by design. That is a real constraint and it cuts both ways: the code below
+// is longer than `jwt.Parse`, but it is also auditable in one sitting and cannot be broken by
+// somebody else's release. The algorithm allow-list is the part that matters — accepting `alg`
+// from the token itself is the classic JWT forgery, so it is fixed here and `none` can never
+// appear.
+package oidc
+
+import (
+	"context"
+	"crypto"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rsa"
+	"crypto/sha256"
+	"crypto/sha512"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"math/big"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+)
+
+// Claims are the parts of an ID token Echolot acts on.
+type Claims struct {
+	Issuer   string   `json:"iss"`
+	Subject  string   `json:"sub"`
+	Audience audience `json:"aud"`
+	Expiry   int64    `json:"exp"`
+	IssuedAt int64    `json:"iat"`
+	Nonce    string   `json:"nonce"`
+	Email    string   `json:"email"`
+	Name     string   `json:"name"`
+	Username string   `json:"preferred_username"`
+	Groups   []string `json:"groups"`
+}
+
+// AccountID is the stable identity of a person: issuer plus subject.
+//
+// Subject alone is not enough — it is only unique within an issuer — and email is not stable,
+// since people change them and IdPs allow reuse. Keying on iss+sub means an operator can switch
+// IdPs and know that the accounts did not silently merge.
+func (c Claims) AccountID() string { return c.Issuer + "#" + c.Subject }
+
+// Display is the friendliest name available, for the admin UI.
+func (c Claims) Display() string {
+	for _, s := range []string{c.Name, c.Username, c.Email} {
+		if s != "" {
+			return s
+		}
+	}
+	return c.Subject
+}
+
+// audience tolerates the spec's two shapes: a string or an array of strings.
+type audience []string
+
+func (a *audience) UnmarshalJSON(b []byte) error {
+	var one string
+	if err := json.Unmarshal(b, &one); err == nil {
+		*a = audience{one}
+		return nil
+	}
+	var many []string
+	if err := json.Unmarshal(b, &many); err != nil {
+		return err
+	}
+	*a = many
+	return nil
+}
+
+func (a audience) contains(s string) bool {
+	for _, v := range a {
+		if v == s {
+			return true
+		}
+	}
+	return false
+}
+
+// Config is what the operator supplies.
+type Config struct {
+	// Issuer is the IdP's base URL, e.g. https://auth.example.net/application/o/echolot/
+	Issuer string
+	// ClientID is this server's own registered client — confidential, used for the admin UI's
+	// browser login, where a secret can genuinely be kept in the host's config.
+	ClientID string
+	// AppClientID is the mobile app's registered client. It is a separate, *public* client
+	// because an APK cannot keep a secret, so it uses PKCE instead.
+	//
+	// Both are accepted as audiences, and they must be listed rather than merged: a token is
+	// addressed to a specific client, and accepting "any client of this issuer" would let every
+	// other application registered with the same IdP authenticate here.
+	AppClientID string
+	// AdminGroup, when set, is the group claim a person must hold to reach the admin UI.
+	// Empty means no one is an admin via OIDC, which is the safe default: an operator who has
+	// not said who may administer the server has not said "everyone".
+	AdminGroup string
+	// Skew tolerated on exp/iat, for ordinary clock drift between the IdP and this server.
+	Skew time.Duration
+}
+
+func (c Config) Enabled() bool { return c.Issuer != "" && (c.ClientID != "" || c.AppClientID != "") }
+
+// acceptedAudiences is every client id this server answers for.
+func (v *Verifier) acceptedAudiences() []string {
+	out := make([]string, 0, 2)
+	for _, id := range []string{v.cfg.ClientID, v.cfg.AppClientID} {
+		if id != "" {
+			out = append(out, id)
+		}
+	}
+	return out
+}
+
+func (v *Verifier) audienceAccepted(aud audience) bool {
+	for _, id := range v.acceptedAudiences() {
+		if aud.contains(id) {
+			return true
+		}
+	}
+	return false
+}
+
+// Discovery is the subset of the provider metadata document that is used.
+type Discovery struct {
+	Issuer                string `json:"issuer"`
+	AuthorizationEndpoint string `json:"authorization_endpoint"`
+	TokenEndpoint         string `json:"token_endpoint"`
+	JWKSURI               string `json:"jwks_uri"`
+	UserinfoEndpoint      string `json:"userinfo_endpoint"`
+	EndSessionEndpoint    string `json:"end_session_endpoint"`
+}
+
+// Verifier fetches provider metadata and keys, and checks tokens against them.
+type Verifier struct {
+	cfg    Config
+	client *http.Client
+
+	mu        sync.RWMutex
+	discovery *Discovery
+	keys      map[string]crypto.PublicKey
+	keysAt    time.Time
+}
+
+func New(cfg Config, client *http.Client) *Verifier {
+	if cfg.Skew == 0 {
+		cfg.Skew = 2 * time.Minute
+	}
+	if client == nil {
+		client = &http.Client{Timeout: 10 * time.Second}
+	}
+	return &Verifier{cfg: cfg, client: client, keys: map[string]crypto.PublicKey{}}
+}
+
+func (v *Verifier) Config() Config { return v.cfg }
+
+var (
+	ErrDisabled  = errors.New("no OIDC issuer is configured on this server")
+	ErrMalformed = errors.New("token is not a well-formed JWT")
+	ErrSignature = errors.New("token signature does not verify")
+	ErrClaims    = errors.New("token claims are not acceptable")
+)
+
+// Discover fetches (and caches) the provider metadata.
+func (v *Verifier) Discover(ctx context.Context) (*Discovery, error) {
+	if !v.cfg.Enabled() {
+		return nil, ErrDisabled
+	}
+	v.mu.RLock()
+	d := v.discovery
+	v.mu.RUnlock()
+	if d != nil {
+		return d, nil
+	}
+
+	url := strings.TrimRight(v.cfg.Issuer, "/") + "/.well-known/openid-configuration"
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := v.client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("discovery: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("discovery: %s returned %d", url, resp.StatusCode)
+	}
+	var got Discovery
+	if err := json.NewDecoder(resp.Body).Decode(&got); err != nil {
+		return nil, fmt.Errorf("discovery: %w", err)
+	}
+	// The issuer in the document must match the one configured, or a redirect could point us at
+	// somebody else's keys while we keep believing we are talking to the configured provider.
+	if strings.TrimRight(got.Issuer, "/") != strings.TrimRight(v.cfg.Issuer, "/") {
+		return nil, fmt.Errorf("discovery: document says issuer %q, configured %q", got.Issuer, v.cfg.Issuer)
+	}
+	v.mu.Lock()
+	v.discovery = &got
+	v.mu.Unlock()
+	return &got, nil
+}
+
+// jwksTTL is how long keys are trusted before refetching. Short enough to pick up a rotation
+// without an operator restarting anything; long enough that token checks are not IdP round trips.
+const jwksTTL = 15 * time.Minute
+
+func (v *Verifier) keyFor(ctx context.Context, kid string) (crypto.PublicKey, error) {
+	v.mu.RLock()
+	k, ok := v.keys[kid]
+	fresh := time.Since(v.keysAt) < jwksTTL
+	v.mu.RUnlock()
+	if ok && fresh {
+		return k, nil
+	}
+	if err := v.refreshKeys(ctx); err != nil {
+		return nil, err
+	}
+	v.mu.RLock()
+	defer v.mu.RUnlock()
+	if k, ok := v.keys[kid]; ok {
+		return k, nil
+	}
+	// A kid we have never seen, after a refresh, is a token from somewhere else.
+	return nil, fmt.Errorf("%w: no key %q at the issuer", ErrSignature, kid)
+}
+
+func (v *Verifier) refreshKeys(ctx context.Context) error {
+	d, err := v.Discover(ctx)
+	if err != nil {
+		return err
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, d.JWKSURI, nil)
+	if err != nil {
+		return err
+	}
+	resp, err := v.client.Do(req)
+	if err != nil {
+		return fmt.Errorf("jwks: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("jwks: %s returned %d", d.JWKSURI, resp.StatusCode)
+	}
+	var set struct {
+		Keys []jwk `json:"keys"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&set); err != nil {
+		return fmt.Errorf("jwks: %w", err)
+	}
+	parsed := make(map[string]crypto.PublicKey, len(set.Keys))
+	for _, k := range set.Keys {
+		if pub, err := k.publicKey(); err == nil {
+			parsed[k.Kid] = pub
+		}
+	}
+	if len(parsed) == 0 {
+		return errors.New("jwks: no usable keys")
+	}
+	v.mu.Lock()
+	v.keys = parsed
+	v.keysAt = time.Now()
+	v.mu.Unlock()
+	return nil
+}
+
+type jwk struct {
+	Kty string `json:"kty"`
+	Kid string `json:"kid"`
+	Alg string `json:"alg"`
+	Use string `json:"use"`
+	N   string `json:"n"`
+	E   string `json:"e"`
+	Crv string `json:"crv"`
+	X   string `json:"x"`
+	Y   string `json:"y"`
+}
+
+func (k jwk) publicKey() (crypto.PublicKey, error) {
+	switch k.Kty {
+	case "RSA":
+		n, err := b64uint(k.N)
+		if err != nil {
+			return nil, err
+		}
+		e, err := b64uint(k.E)
+		if err != nil {
+			return nil, err
+		}
+		if !e.IsInt64() || e.Int64() > 1<<31 {
+			return nil, errors.New("implausible RSA exponent")
+		}
+		return &rsa.PublicKey{N: n, E: int(e.Int64())}, nil
+	case "EC":
+		curve, err := curveFor(k.Crv)
+		if err != nil {
+			return nil, err
+		}
+		x, err := b64uint(k.X)
+		if err != nil {
+			return nil, err
+		}
+		y, err := b64uint(k.Y)
+		if err != nil {
+			return nil, err
+		}
+		return &ecdsa.PublicKey{Curve: curve, X: x, Y: y}, nil
+	}
+	return nil, fmt.Errorf("unsupported key type %q", k.Kty)
+}
+
+// Verify checks a serialized ID token and returns its claims.
+//
+// The order is deliberate: structure, then algorithm, then signature, then claims. Nothing about
+// the token's contents is believed before its signature has been checked — reading `iss` or `aud`
+// out of an unverified token and acting on it is how "verified" tokens turn out not to be.
+func (v *Verifier) Verify(ctx context.Context, token string) (*Claims, error) {
+	if !v.cfg.Enabled() {
+		return nil, ErrDisabled
+	}
+	parts := strings.Split(token, ".")
+	if len(parts) != 3 {
+		return nil, ErrMalformed
+	}
+	headerJSON, err := b64(parts[0])
+	if err != nil {
+		return nil, ErrMalformed
+	}
+	var hdr struct {
+		Alg string `json:"alg"`
+		Kid string `json:"kid"`
+		Typ string `json:"typ"`
+	}
+	if err := json.Unmarshal(headerJSON, &hdr); err != nil {
+		return nil, ErrMalformed
+	}
+	// The allow-list is fixed here rather than taken from the token. Trusting the token's own
+	// `alg` is the classic JWT forgery: "none" turns any token into a valid one, and swapping RS256
+	// for HS256 lets an attacker sign with the public key. Neither is reachable from here.
+	if _, ok := allowedAlgs[hdr.Alg]; !ok {
+		return nil, fmt.Errorf("%w: algorithm %q is not accepted", ErrSignature, hdr.Alg)
+	}
+
+	pub, err := v.keyFor(ctx, hdr.Kid)
+	if err != nil {
+		return nil, err
+	}
+	sig, err := b64(parts[2])
+	if err != nil {
+		return nil, ErrMalformed
+	}
+	signed := parts[0] + "." + parts[1]
+	if err := verifySignature(hdr.Alg, pub, []byte(signed), sig); err != nil {
+		return nil, err
+	}
+
+	payload, err := b64(parts[1])
+	if err != nil {
+		return nil, ErrMalformed
+	}
+	var claims Claims
+	if err := json.Unmarshal(payload, &claims); err != nil {
+		return nil, ErrMalformed
+	}
+	if err := v.checkClaims(claims); err != nil {
+		return nil, err
+	}
+	return &claims, nil
+}
+
+func (v *Verifier) checkClaims(c Claims) error {
+	if strings.TrimRight(c.Issuer, "/") != strings.TrimRight(v.cfg.Issuer, "/") {
+		return fmt.Errorf("%w: issued by %q, expected %q", ErrClaims, c.Issuer, v.cfg.Issuer)
+	}
+	// A token addressed to a different client is a valid token that was not meant for us —
+	// accepting it lets any other client of the same IdP authenticate here.
+	if !v.audienceAccepted(c.Audience) {
+		return fmt.Errorf("%w: addressed to %v, not to %v", ErrClaims,
+			[]string(c.Audience), v.acceptedAudiences())
+	}
+	if c.Subject == "" {
+		return fmt.Errorf("%w: no subject", ErrClaims)
+	}
+	now := time.Now()
+	if c.Expiry == 0 || now.After(time.Unix(c.Expiry, 0).Add(v.cfg.Skew)) {
+		return fmt.Errorf("%w: expired", ErrClaims)
+	}
+	if c.IssuedAt != 0 && now.Add(v.cfg.Skew).Before(time.Unix(c.IssuedAt, 0)) {
+		return fmt.Errorf("%w: issued in the future", ErrClaims)
+	}
+	return nil
+}
+
+// IsAdmin reports whether these claims carry the configured admin group.
+//
+// With no group configured nobody is an admin: an operator who has not said who may administer
+// the server has not thereby said "anyone who can log in".
+func (v *Verifier) IsAdmin(c *Claims) bool {
+	if c == nil || v.cfg.AdminGroup == "" {
+		return false
+	}
+	for _, g := range c.Groups {
+		if g == v.cfg.AdminGroup {
+			return true
+		}
+	}
+	return false
+}
+
+var allowedAlgs = map[string]crypto.Hash{
+	"RS256": crypto.SHA256, "RS384": crypto.SHA384, "RS512": crypto.SHA512,
+	"ES256": crypto.SHA256, "ES384": crypto.SHA384, "ES512": crypto.SHA512,
+}
+
+func verifySignature(alg string, pub crypto.PublicKey, signed, sig []byte) error {
+	h := allowedAlgs[alg]
+	digest := hashOf(h, signed)
+
+	switch {
+	case strings.HasPrefix(alg, "RS"):
+		k, ok := pub.(*rsa.PublicKey)
+		if !ok {
+			return fmt.Errorf("%w: %s token against a non-RSA key", ErrSignature, alg)
+		}
+		if err := rsa.VerifyPKCS1v15(k, h, digest, sig); err != nil {
+			return ErrSignature
+		}
+		return nil
+	case strings.HasPrefix(alg, "ES"):
+		k, ok := pub.(*ecdsa.PublicKey)
+		if !ok {
+			return fmt.Errorf("%w: %s token against a non-EC key", ErrSignature, alg)
+		}
+		// JWS packs ECDSA signatures as r||s, fixed width — not the ASN.1 form ecdsa.Verify
+		// would otherwise expect.
+		if len(sig)%2 != 0 {
+			return ErrSignature
+		}
+		half := len(sig) / 2
+		r := new(big.Int).SetBytes(sig[:half])
+		s := new(big.Int).SetBytes(sig[half:])
+		if !ecdsa.Verify(k, digest, r, s) {
+			return ErrSignature
+		}
+		return nil
+	}
+	return ErrSignature
+}
+
+func hashOf(h crypto.Hash, b []byte) []byte {
+	switch h {
+	case crypto.SHA384:
+		d := sha512.Sum384(b)
+		return d[:]
+	case crypto.SHA512:
+		d := sha512.Sum512(b)
+		return d[:]
+	default:
+		d := sha256.Sum256(b)
+		return d[:]
+	}
+}
+
+func curveFor(crv string) (elliptic.Curve, error) {
+	switch crv {
+	case "P-256":
+		return elliptic.P256(), nil
+	case "P-384":
+		return elliptic.P384(), nil
+	case "P-521":
+		return elliptic.P521(), nil
+	}
+	return nil, fmt.Errorf("unsupported curve %q", crv)
+}
+
+// b64 decodes JWT base64url, which omits padding.
+func b64(s string) ([]byte, error) { return base64.RawURLEncoding.DecodeString(s) }
+
+func b64uint(s string) (*big.Int, error) {
+	b, err := b64(s)
+	if err != nil {
+		return nil, err
+	}
+	if len(b) == 0 {
+		return nil, errors.New("empty value")
+	}
+	return new(big.Int).SetBytes(b), nil
+}

server/internal/oidc/oidc_test.go

@@ -0,0 +1,325 @@
+// SPDX-FileCopyrightText: 2026 Echolot contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+package oidc
+
+import (
+	"context"
+	"crypto"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"math/big"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+)
+
+// A self-contained IdP: real keys, real signatures, real discovery and JWKS documents. Testing
+// token verification against anything less than a genuine signer proves nothing — the failure
+// modes that matter here (accepting `none`, accepting another client's token, accepting an
+// expired one) all look fine to a mock that just returns success.
+type testIdP struct {
+	*httptest.Server
+	rsaKey *rsa.PrivateKey
+	ecKey  *ecdsa.PrivateKey
+}
+
+func newIdP(t *testing.T) *testIdP {
+	t.Helper()
+	rk, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatal(err)
+	}
+	ek, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	idp := &testIdP{rsaKey: rk, ecKey: ek}
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/.well-known/openid-configuration", func(w http.ResponseWriter, r *http.Request) {
+		_ = json.NewEncoder(w).Encode(Discovery{
+			Issuer:                idp.URL,
+			AuthorizationEndpoint: idp.URL + "/auth",
+			TokenEndpoint:         idp.URL + "/token",
+			JWKSURI:               idp.URL + "/jwks",
+		})
+	})
+	mux.HandleFunc("/jwks", func(w http.ResponseWriter, r *http.Request) {
+		_ = json.NewEncoder(w).Encode(map[string]any{"keys": []map[string]string{
+			{
+				"kty": "RSA", "kid": "rsa-1", "alg": "RS256", "use": "sig",
+				"n": raw(rk.N.Bytes()),
+				"e": raw(big.NewInt(int64(rk.E)).Bytes()),
+			},
+			{
+				"kty": "EC", "kid": "ec-1", "alg": "ES256", "use": "sig", "crv": "P-256",
+				"x": raw(ek.X.Bytes()), "y": raw(ek.Y.Bytes()),
+			},
+		}})
+	})
+	idp.Server = httptest.NewServer(mux)
+	t.Cleanup(idp.Close)
+	return idp
+}
+
+func raw(b []byte) string { return base64.RawURLEncoding.EncodeToString(b) }
+
+func (i *testIdP) sign(t *testing.T, alg, kid string, claims map[string]any) string {
+	t.Helper()
+	h, _ := json.Marshal(map[string]string{"alg": alg, "kid": kid, "typ": "JWT"})
+	p, _ := json.Marshal(claims)
+	signing := raw(h) + "." + raw(p)
+	digest := sha256.Sum256([]byte(signing))
+
+	var sig []byte
+	switch alg {
+	case "RS256":
+		s, err := rsa.SignPKCS1v15(rand.Reader, i.rsaKey, crypto.SHA256, digest[:])
+		if err != nil {
+			t.Fatal(err)
+		}
+		sig = s
+	case "ES256":
+		r, s, err := ecdsa.Sign(rand.Reader, i.ecKey, digest[:])
+		if err != nil {
+			t.Fatal(err)
+		}
+		// JWS wants fixed-width r||s, not ASN.1.
+		sig = make([]byte, 64)
+		r.FillBytes(sig[:32])
+		s.FillBytes(sig[32:])
+	default:
+		t.Fatalf("unsupported test alg %q", alg)
+	}
+	return signing + "." + raw(sig)
+}
+
+func (i *testIdP) claims(extra map[string]any) map[string]any {
+	c := map[string]any{
+		"iss": i.URL, "sub": "user-1", "aud": "echolot",
+		"exp": time.Now().Add(time.Hour).Unix(), "iat": time.Now().Unix(),
+		"email": "someone@example.net", "groups": []string{"users"},
+	}
+	for k, v := range extra {
+		c[k] = v
+	}
+	return c
+}
+
+func verifier(i *testIdP, adminGroup string) *Verifier {
+	return New(Config{
+		Issuer: i.URL, ClientID: "echolot", AppClientID: "echolot-app", AdminGroup: adminGroup,
+	}, i.Client())
+}
+
+func TestAcceptsAGenuineToken(t *testing.T) {
+	idp := newIdP(t)
+	v := verifier(idp, "")
+	for _, tc := range []struct{ alg, kid string }{{"RS256", "rsa-1"}, {"ES256", "ec-1"}} {
+		got, err := v.Verify(context.Background(), idp.sign(t, tc.alg, tc.kid, idp.claims(nil)))
+		if err != nil {
+			t.Fatalf("%s: %v", tc.alg, err)
+		}
+		if got.Subject != "user-1" || got.Email != "someone@example.net" {
+			t.Fatalf("%s: claims not parsed: %+v", tc.alg, got)
+		}
+		if want := idp.URL + "#user-1"; got.AccountID() != want {
+			t.Errorf("AccountID = %q, want %q", got.AccountID(), want)
+		}
+	}
+}
+
+// "alg": "none" is the oldest JWT forgery there is: strip the signature, declare no algorithm,
+// and a naive verifier accepts anything. It must not even reach the key lookup.
+func TestRejectsAlgNone(t *testing.T) {
+	idp := newIdP(t)
+	v := verifier(idp, "")
+	h, _ := json.Marshal(map[string]string{"alg": "none", "kid": "rsa-1", "typ": "JWT"})
+	p, _ := json.Marshal(idp.claims(nil))
+	token := raw(h) + "." + raw(p) + "."
+	if _, err := v.Verify(context.Background(), token); !errors.Is(err, ErrSignature) {
+		t.Fatalf("alg=none was not refused as a signature failure: %v", err)
+	}
+}
+
+// The other classic: declare HS256 so the verifier treats the RSA *public* key as an HMAC secret,
+// which the attacker also has. The allow-list has no symmetric algorithms at all.
+func TestRejectsSymmetricAlgorithmConfusion(t *testing.T) {
+	idp := newIdP(t)
+	v := verifier(idp, "")
+	h, _ := json.Marshal(map[string]string{"alg": "HS256", "kid": "rsa-1", "typ": "JWT"})
+	p, _ := json.Marshal(idp.claims(nil))
+	token := raw(h) + "." + raw(p) + "." + raw([]byte("whatever"))
+	if _, err := v.Verify(context.Background(), token); !errors.Is(err, ErrSignature) {
+		t.Fatalf("HS256 confusion was not refused: %v", err)
+	}
+}
+
+func TestRejectsATamperedPayload(t *testing.T) {
+	idp := newIdP(t)
+	v := verifier(idp, "")
+	good := idp.sign(t, "RS256", "rsa-1", idp.claims(nil))
+	// Swap the payload for one claiming to be somebody else, keeping the valid signature.
+	forged, _ := json.Marshal(idp.claims(map[string]any{"sub": "admin"}))
+	parts := []byte(good)
+	dot1, dot2 := 0, 0
+	for i, c := range parts {
+		if c == '.' {
+			if dot1 == 0 {
+				dot1 = i
+			} else {
+				dot2 = i
+			}
+		}
+	}
+	token := string(parts[:dot1+1]) + raw(forged) + string(parts[dot2:])
+	if _, err := v.Verify(context.Background(), token); !errors.Is(err, ErrSignature) {
+		t.Fatalf("a swapped payload was not refused: %v", err)
+	}
+}
+
+// A token from the same IdP but issued to a different client is perfectly valid — just not for
+// us. Accepting it would let any other client of the same provider authenticate here.
+func TestRejectsAnotherClientsToken(t *testing.T) {
+	idp := newIdP(t)
+	v := verifier(idp, "")
+	tok := idp.sign(t, "RS256", "rsa-1", idp.claims(map[string]any{"aud": "some-other-app"}))
+	if _, err := v.Verify(context.Background(), tok); !errors.Is(err, ErrClaims) {
+		t.Fatalf("another client's token was accepted: %v", err)
+	}
+}
+
+func TestAcceptsAudienceArrayContainingUs(t *testing.T) {
+	idp := newIdP(t)
+	v := verifier(idp, "")
+	tok := idp.sign(t, "RS256", "rsa-1", idp.claims(map[string]any{"aud": []string{"other", "echolot"}}))
+	if _, err := v.Verify(context.Background(), tok); err != nil {
+		t.Fatalf("an audience array including us was refused: %v", err)
+	}
+}
+
+func TestRejectsExpiredAndFutureTokens(t *testing.T) {
+	idp := newIdP(t)
+	v := verifier(idp, "")
+	expired := idp.sign(t, "RS256", "rsa-1", idp.claims(map[string]any{
+		"exp": time.Now().Add(-time.Hour).Unix(),
+	}))
+	if _, err := v.Verify(context.Background(), expired); !errors.Is(err, ErrClaims) {
+		t.Errorf("expired token accepted: %v", err)
+	}
+	future := idp.sign(t, "RS256", "rsa-1", idp.claims(map[string]any{
+		"iat": time.Now().Add(time.Hour).Unix(),
+	}))
+	if _, err := v.Verify(context.Background(), future); !errors.Is(err, ErrClaims) {
+		t.Errorf("token issued in the future accepted: %v", err)
+	}
+}
+
+// A token signed by a completely different provider, with its own keys and its own kid.
+func TestRejectsATokenFromAnotherIssuer(t *testing.T) {
+	ours, theirs := newIdP(t), newIdP(t)
+	v := verifier(ours, "")
+	tok := theirs.sign(t, "RS256", "rsa-1", theirs.claims(nil))
+	if _, err := v.Verify(context.Background(), tok); err == nil {
+		t.Fatal("a token from another issuer was accepted")
+	}
+}
+
+func TestRejectsMalformedTokens(t *testing.T) {
+	idp := newIdP(t)
+	v := verifier(idp, "")
+	for _, bad := range []string{"", "not-a-token", "a.b", "a.b.c.d", "...", "!!!.???.***"} {
+		if _, err := v.Verify(context.Background(), bad); err == nil {
+			t.Errorf("%q was accepted", bad)
+		}
+	}
+}
+
+// With no admin group configured, nobody is an admin. An operator who has not said who may
+// administer the server has not thereby said "anyone who can log in".
+func TestNobodyIsAdminUntilAGroupIsConfigured(t *testing.T) {
+	idp := newIdP(t)
+	claims := &Claims{Groups: []string{"users", "echolot-admins"}}
+
+	if verifier(idp, "").IsAdmin(claims) {
+		t.Error("someone was an admin with no admin group configured")
+	}
+	if !verifier(idp, "echolot-admins").IsAdmin(claims) {
+		t.Error("a member of the configured group was not an admin")
+	}
+	if verifier(idp, "other-group").IsAdmin(claims) {
+		t.Error("a non-member was an admin")
+	}
+	if verifier(idp, "echolot-admins").IsAdmin(nil) {
+		t.Error("an absent identity was an admin")
+	}
+}
+
+// A discovery document whose issuer disagrees with the configured one means we were redirected
+// somewhere — and would otherwise have fetched that somewhere's signing keys while believing
+// they belonged to the configured provider.
+func TestRefusesDiscoveryThatRenamesTheIssuer(t *testing.T) {
+	mux := http.NewServeMux()
+	srv := httptest.NewServer(mux)
+	defer srv.Close()
+	mux.HandleFunc("/.well-known/openid-configuration", func(w http.ResponseWriter, r *http.Request) {
+		_ = json.NewEncoder(w).Encode(Discovery{Issuer: "https://somewhere.else", JWKSURI: srv.URL + "/jwks"})
+	})
+	v := New(Config{Issuer: srv.URL, ClientID: "echolot"}, srv.Client())
+	if _, err := v.Discover(context.Background()); err == nil {
+		t.Fatal("discovery accepted a document for a different issuer")
+	}
+}
+
+func TestDisabledWithoutConfiguration(t *testing.T) {
+	v := New(Config{}, nil)
+	if v.Config().Enabled() {
+		t.Fatal("an unconfigured verifier reports itself enabled")
+	}
+	if _, err := v.Verify(context.Background(), "x.y.z"); !errors.Is(err, ErrDisabled) {
+		t.Fatalf("want ErrDisabled, got %v", err)
+	}
+}
+
+// Two clients, because the phone and the admin UI have different properties: an APK cannot keep a
+// secret (public + PKCE) while the server can (confidential). Both must be accepted — but only
+// those two. "Any client of this issuer" would let every other application registered with the
+// same IdP authenticate here, which is the whole reason the audience check exists.
+func TestBothRegisteredClientsAreAccepted(t *testing.T) {
+	idp := newIdP(t)
+	v := verifier(idp, "")
+
+	for _, aud := range []any{"echolot", "echolot-app", []string{"echolot-app", "other"}} {
+		tok := idp.sign(t, "RS256", "rsa-1", idp.claims(map[string]any{"aud": aud}))
+		if _, err := v.Verify(context.Background(), tok); err != nil {
+			t.Errorf("aud %v was refused: %v", aud, err)
+		}
+	}
+	// A third application at the same issuer is still not us.
+	tok := idp.sign(t, "RS256", "rsa-1", idp.claims(map[string]any{"aud": "someone-elses-app"}))
+	if _, err := v.Verify(context.Background(), tok); !errors.Is(err, ErrClaims) {
+		t.Fatalf("a third client's token was accepted: %v", err)
+	}
+}
+
+// Either client id alone is enough to make sign-in usable: an operator may register only the app
+// (no admin UI login) or only the server.
+func TestEitherClientIDAloneEnablesSignIn(t *testing.T) {
+	if !(Config{Issuer: "https://i", ClientID: "a"}).Enabled() {
+		t.Error("a server-only configuration was reported disabled")
+	}
+	if !(Config{Issuer: "https://i", AppClientID: "b"}).Enabled() {
+		t.Error("an app-only configuration was reported disabled")
+	}
+	if (Config{Issuer: "https://i"}).Enabled() {
+		t.Error("an issuer with no client at all was reported enabled")
+	}
+}

server/internal/runs/runs.go

@@ -38,10 +38,9 @@ const (
 	// ModeAnonymous accepts uploads from any enrolled device. The default: enrollment already
 	// required an admin-minted token, so "anyone enrolled" is not "anyone".
 	ModeAnonymous Mode = "anonymous"
-	// ModeAccount accepts uploads only from a device tied to a signed-in account. The account
-	// system (OIDC) is not built yet, so today this refuses everything with a distinct reason —
-	// it exists so operators can pick the strict setting now and have it mean the right thing
-	// when accounts land, rather than silently loosening on upgrade.
+	// ModeAccount accepts uploads only from a device where somebody has signed in (see
+	// /v1/account/link). Enrollment alone is not enough: the operator's token admits a device,
+	// an account attributes it to a person.
 	ModeAccount Mode = "account"
 )
 
@@ -120,22 +119,27 @@ func Open(stateDir string, p Policy) (*Store, error) {
 
 func (s *Store) Policy() Policy { return s.policy }
 
-// Accepts reports whether an upload would be allowed at all, so callers can answer the
-// capability question without a body.
-func (s *Store) Accepts() error {
+// Accepts reports whether an upload from this caller would be allowed at all, so callers can
+// answer the capability question without a body.
+//
+// linked says whether a person has signed in on the uploading device. It is the only thing that
+// distinguishes ModeAccount from ModeOff — and the reason the check takes an argument at all.
+func (s *Store) Accepts(linked bool) error {
 	switch s.policy.Mode {
 	case ModeOff:
 		return ErrDisabled
 	case ModeAccount:
-		return ErrNeedAccount
+		if !linked {
+			return ErrNeedAccount
+		}
 	}
 	return nil
 }
 
 // Put validates and stores one uploaded document. body is the raw JSON as received: it is stored
 // byte-for-byte so what the device signed off on is what sits on disk.
-func (s *Store) Put(deviceID string, body []byte) (Meta, error) {
-	if err := s.Accepts(); err != nil {
+func (s *Store) Put(deviceID string, body []byte, linked bool) (Meta, error) {
+	if err := s.Accepts(linked); err != nil {
 		return Meta{}, err
 	}
 	if s.policy.MaxBytes > 0 && int64(len(body)) > s.policy.MaxBytes {

server/internal/runs/runs_test.go

@@ -34,19 +34,33 @@ func TestModeOffRefusesEverything(t *testing.T) {
 	p := DefaultPolicy()
 	p.Mode = ModeOff
 	s, _ := open(t, p)
-	if _, err := s.Put("dev1", doc("run-1", AnonFull)); !errors.Is(err, ErrDisabled) {
+	if _, err := s.Put("dev1", doc("run-1", AnonFull), false); !errors.Is(err, ErrDisabled) {
 		t.Fatalf("want ErrDisabled, got %v", err)
 	}
 }
 
-// ModeAccount must refuse today rather than fall back to anonymous: an operator who selects the
-// strict setting before accounts exist must not be silently running the permissive one.
-func TestModeAccountRefusesUntilAccountsExist(t *testing.T) {
+// ModeAccount turns on whether the *caller* has signed in, and nothing else. A device that has
+// not is refused with a reason it can act on; one that has is treated exactly like anonymous mode.
+func TestModeAccountTurnsOnWhetherTheCallerSignedIn(t *testing.T) {
 	p := DefaultPolicy()
 	p.Mode = ModeAccount
 	s, _ := open(t, p)
-	if _, err := s.Put("dev1", doc("run-1", AnonFull)); !errors.Is(err, ErrNeedAccount) {
-		t.Fatalf("want ErrNeedAccount, got %v", err)
+
+	if _, err := s.Put("dev1", doc("run-1", AnonFull), false); !errors.Is(err, ErrNeedAccount) {
+		t.Fatalf("an un-signed-in device was not refused: %v", err)
+	}
+	if _, err := s.Put("dev1", doc("run-2", AnonFull), true); err != nil {
+		t.Fatalf("a signed-in device was refused: %v", err)
+	}
+}
+
+// Signing in must not open a door that the operator closed outright: mode=off means off.
+func TestSigningInDoesNotOverrideModeOff(t *testing.T) {
+	p := DefaultPolicy()
+	p.Mode = ModeOff
+	s, _ := open(t, p)
+	if _, err := s.Put("dev1", doc("run-1", AnonFull), true); !errors.Is(err, ErrDisabled) {
+		t.Fatalf("a signed-in device uploaded to a server with uploads off: %v", err)
 	}
 }
 
@@ -55,15 +69,15 @@ func TestMinAnonymizationEnforced(t *testing.T) {
 	p.MinAnonymization = AnonBalanced
 	s, _ := open(t, p)
 
-	if _, err := s.Put("dev1", doc("run-full", AnonFull)); !errors.Is(err, ErrNotAnonEnough) {
+	if _, err := s.Put("dev1", doc("run-full", AnonFull), false); !errors.Is(err, ErrNotAnonEnough) {
 		t.Fatalf("full should be refused when balanced is required, got %v", err)
 	}
 	// An undeclared level means nothing was stripped, so it must be treated as "full".
-	if _, err := s.Put("dev1", []byte(`{"run":{"id":"run-bare"},"summary":{}}`)); !errors.Is(err, ErrNotAnonEnough) {
+	if _, err := s.Put("dev1", []byte(`{"run":{"id":"run-bare"},"summary":{}}`), false); !errors.Is(err, ErrNotAnonEnough) {
 		t.Fatalf("undeclared level should be treated as full, got %v", err)
 	}
 	for _, lvl := range []string{AnonBalanced, AnonStrict} {
-		if _, err := s.Put("dev1", doc("run-"+lvl, lvl)); err != nil {
+		if _, err := s.Put("dev1", doc("run-"+lvl, lvl), false); err != nil {
 			t.Fatalf("%s should be accepted: %v", lvl, err)
 		}
 	}
@@ -74,7 +88,7 @@ func TestSizeLimit(t *testing.T) {
 	p.MaxBytes = 200
 	s, _ := open(t, p)
 	big := append(doc("run-1", AnonFull), make([]byte, 400)...)
-	if _, err := s.Put("dev1", big); !errors.Is(err, ErrTooLarge) {
+	if _, err := s.Put("dev1", big, false); !errors.Is(err, ErrTooLarge) {
 		t.Fatalf("want ErrTooLarge, got %v", err)
 	}
 }
@@ -84,7 +98,7 @@ func TestRetentionByCountKeepsNewest(t *testing.T) {
 	p.MaxRunsPerDevice = 3
 	s, _ := open(t, p)
 	for i := 0; i < 6; i++ {
-		if _, err := s.Put("dev1", doc(fmt.Sprintf("run-%d", i), AnonFull)); err != nil {
+		if _, err := s.Put("dev1", doc(fmt.Sprintf("run-%d", i), AnonFull), false); err != nil {
 			t.Fatalf("put %d: %v", i, err)
 		}
 		time.Sleep(2 * time.Millisecond) // distinct UploadedAt so "newest" is well defined
@@ -109,7 +123,7 @@ func TestRetentionByAge(t *testing.T) {
 	p.RetentionDays = 7
 	p.MaxRunsPerDevice = 0
 	s, dir := open(t, p)
-	if _, err := s.Put("dev1", doc("run-old", AnonFull)); err != nil {
+	if _, err := s.Put("dev1", doc("run-old", AnonFull), false); err != nil {
 		t.Fatal(err)
 	}
 	// Backdate the index entry past the retention window.
@@ -123,7 +137,7 @@ func TestRetentionByAge(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	if _, err := s.Put("dev1", doc("run-new", AnonFull)); err != nil {
+	if _, err := s.Put("dev1", doc("run-new", AnonFull), false); err != nil {
 		t.Fatal(err)
 	}
 	got := s.List("dev1")
@@ -136,7 +150,7 @@ func TestRetentionByAge(t *testing.T) {
 // store directory or overwrite another device's data.
 func TestIDsCannotEscapeTheStoreDirectory(t *testing.T) {
 	s, dir := open(t, DefaultPolicy())
-	if _, err := s.Put("../../etc", doc("../../../passwd", AnonFull)); err != nil {
+	if _, err := s.Put("../../etc", doc("../../../passwd", AnonFull), false); err != nil {
 		t.Fatalf("put: %v", err)
 	}
 	var found []string
@@ -159,10 +173,10 @@ func TestIDsCannotEscapeTheStoreDirectory(t *testing.T) {
 
 func TestListIsPerDevice(t *testing.T) {
 	s, _ := open(t, DefaultPolicy())
-	if _, err := s.Put("devA", doc("run-a", AnonFull)); err != nil {
+	if _, err := s.Put("devA", doc("run-a", AnonFull), false); err != nil {
 		t.Fatal(err)
 	}
-	if _, err := s.Put("devB", doc("run-b", AnonFull)); err != nil {
+	if _, err := s.Put("devB", doc("run-b", AnonFull), false); err != nil {
 		t.Fatal(err)
 	}
 	if got := s.List("devA"); len(got) != 1 || got[0].ID != "run-a" {
@@ -175,7 +189,7 @@ func TestListIsPerDevice(t *testing.T) {
 
 func TestMetaSummarisesTheDocument(t *testing.T) {
 	s, _ := open(t, DefaultPolicy())
-	m, err := s.Put("dev1", doc("run-1", AnonBalanced))
+	m, err := s.Put("dev1", doc("run-1", AnonBalanced), false)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -190,7 +204,7 @@ func TestMetaSummarisesTheDocument(t *testing.T) {
 func TestMalformedRejected(t *testing.T) {
 	s, _ := open(t, DefaultPolicy())
 	for _, body := range [][]byte{[]byte("not json"), []byte(`{"run":{}}`), []byte(`{}`)} {
-		if _, err := s.Put("dev1", body); !errors.Is(err, ErrMalformed) {
+		if _, err := s.Put("dev1", body, false); !errors.Is(err, ErrMalformed) {
 			t.Fatalf("body %q: want ErrMalformed, got %v", body, err)
 		}
 	}

server/internal/selfupdate/selfupdate.go

@@ -9,6 +9,7 @@ package selfupdate
 
 import (
 	"crypto/sha256"
+	"echo-lot.app/server/internal/system"
 	"encoding/hex"
 	"encoding/json"
 	"fmt"
@@ -132,6 +133,15 @@ func Run(api, currentVersion string) error {
 		os.Remove(tmp)
 		return fmt.Errorf("atomic replace failed (filesystem boundaries?): %w", err)
 	}
+	// Serving became an explicit verb, and a unit written before that change starts this binary
+	// with no arguments - which now prints usage and exits non-zero. The unit is not part of what
+	// an update replaces, so it is repaired here rather than left to fail at the next restart,
+	// which might be a reboot months from now.
+	if repaired, err := system.RepairExecStart(); err != nil {
+		fmt.Println("WARNING: could not update the systemd unit for --serve:", err)
+	} else if repaired {
+		fmt.Println("updated the systemd unit to pass --serve (serving is now an explicit verb)")
+	}
 	fmt.Printf("updated %s -> %s (%s); restart to run it\n", currentVersion, rel.TagName, self)
 	return nil
 }

server/internal/store/store.go

@@ -16,6 +16,8 @@ import (
 	"os"
 	"path/filepath"
 	"sync"
+
+	"echo-lot.app/server/internal/adminauth"
 	"time"
 )
 
@@ -37,8 +39,19 @@ type Device struct {
 	Credential     string    `json:"credential"`
 	Enrolled       time.Time `json:"enrolled"`
 	Name           string    `json:"name,omitempty"`
+
+	// The account this device belongs to, as issuer#subject — empty when nobody has signed in
+	// on it. Enrollment and sign-in are deliberately separate: a device is admitted by an
+	// operator's token, and only later (if ever) associated with a person. Servers that accept
+	// anonymous uploads never need the second step.
+	AccountID   string    `json:"account_id,omitempty"`
+	AccountName string    `json:"account_name,omitempty"`
+	LinkedAt    time.Time `json:"linked_at,omitempty"`
 }
 
+// LinkedToAccount reports whether a person has signed in on this device.
+func (d Device) LinkedToAccount() bool { return d.AccountID != "" }
+
 type Store struct {
 	mu   sync.Mutex
 	path string
@@ -48,6 +61,12 @@ type Store struct {
 type fileData struct {
 	Tokens  []EnrollToken `json:"tokens"`
 	Devices []Device      `json:"devices"`
+	// The break-glass admin. Absent until an operator sets one.
+	LocalAdmin *adminauth.Credential `json:"local_admin,omitempty"`
+	// Signing secret for admin session cookies. Persisted so sessions survive a restart;
+	// deleting it from the state file invalidates every session at once, which is how an
+	// operator revokes them.
+	SessionSecret string `json:"session_secret,omitempty"`
 }
 
 func Open(stateDir string) (*Store, error) {
@@ -126,6 +145,90 @@ func (s *Store) Redeem(token, name string) (*Device, error) {
 }
 
 // DeviceByCredential authenticates a bearer credential.
+// LinkAccount ties a device to a signed-in identity, or clears it when accountID is empty.
+func (s *Store) LinkAccount(deviceID, accountID, displayName string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	for i := range s.data.Devices {
+		if s.data.Devices[i].ID != deviceID {
+			continue
+		}
+		s.data.Devices[i].AccountID = accountID
+		s.data.Devices[i].AccountName = displayName
+		if accountID == "" {
+			s.data.Devices[i].LinkedAt = time.Time{}
+		} else {
+			s.data.Devices[i].LinkedAt = time.Now().UTC()
+		}
+		return s.save()
+	}
+	return errors.New("no such device")
+}
+
+// Devices returns a copy of the device list, for the admin UI.
+func (s *Store) Devices() []Device {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return append([]Device(nil), s.data.Devices...)
+}
+
+// DeleteDevice revokes a device: its credential stops working immediately.
+func (s *Store) DeleteDevice(id string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	for i := range s.data.Devices {
+		if s.data.Devices[i].ID == id {
+			s.data.Devices = append(s.data.Devices[:i], s.data.Devices[i+1:]...)
+			return s.save()
+		}
+	}
+	return errors.New("no such device")
+}
+
+// SetLocalAdmin stores (or replaces) the break-glass admin password.
+func (s *Store) SetLocalAdmin(c adminauth.Credential) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.data.LocalAdmin = &c
+	return s.save()
+}
+
+// LocalAdmin returns the configured break-glass admin, or nil.
+func (s *Store) LocalAdmin() *adminauth.Credential {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.data.LocalAdmin == nil {
+		return nil
+	}
+	c := *s.data.LocalAdmin
+	return &c
+}
+
+// ClearLocalAdmin removes the break-glass admin.
+func (s *Store) ClearLocalAdmin() error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.data.LocalAdmin = nil
+	return s.save()
+}
+
+// SessionSecret returns the admin session signing secret, creating one on first use.
+func (s *Store) SessionSecret() ([]byte, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.data.SessionSecret != "" {
+		if b, err := hex.DecodeString(s.data.SessionSecret); err == nil && len(b) >= 32 {
+			return b, nil
+		}
+	}
+	b, err := adminauth.NewSecret()
+	if err != nil {
+		return nil, err
+	}
+	s.data.SessionSecret = hex.EncodeToString(b)
+	return b, s.save()
+}
+
 func (s *Store) DeviceByCredential(cred string) *Device {
 	s.mu.Lock()
 	defer s.mu.Unlock()

server/internal/system/echo_linux.go

@@ -0,0 +1,34 @@
+// SPDX-FileCopyrightText: 2026 Echolot contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+//go:build linux
+
+package system
+
+import (
+	"os"
+	"syscall"
+	"unsafe"
+)
+
+// DisableEcho turns off terminal echo while a password is typed, returning a function that puts
+// the terminal back. Both are best-effort: when stdin is a pipe (the automation case) there is
+// no terminal to change and nothing to restore.
+func DisableEcho(f *os.File) (func(), error) {
+	fd := f.Fd()
+	var t syscall.Termios
+	if _, _, errno := syscall.Syscall6(syscall.SYS_IOCTL, fd,
+		syscall.TCGETS, uintptr(unsafe.Pointer(&t)), 0, 0, 0); errno != 0 {
+		return nil, errno // not a terminal; nothing to do
+	}
+	original := t
+	t.Lflag &^= syscall.ECHO
+	if _, _, errno := syscall.Syscall6(syscall.SYS_IOCTL, fd,
+		syscall.TCSETS, uintptr(unsafe.Pointer(&t)), 0, 0, 0); errno != 0 {
+		return nil, errno
+	}
+	return func() {
+		_, _, _ = syscall.Syscall6(syscall.SYS_IOCTL, fd,
+			syscall.TCSETS, uintptr(unsafe.Pointer(&original)), 0, 0, 0)
+	}, nil
+}

server/internal/system/echo_other.go

@@ -0,0 +1,12 @@
+// SPDX-FileCopyrightText: 2026 Echolot contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+//go:build !linux
+
+package system
+
+import "os"
+
+// DisableEcho is a no-op off Linux: the password is still read, just echoed. Better than
+// refusing to run — an operator on a Mac still needs to set the break-glass password.
+func DisableEcho(*os.File) (func(), error) { return nil, nil }

server/internal/system/systemd.go

@@ -12,6 +12,7 @@ import (
 	"os/exec"
 	"path/filepath"
 	"runtime"
+	"strings"
 )
 
 const (
@@ -29,7 +30,7 @@ Wants=network-online.target
 
 [Service]
 Type=simple
-ExecStart=%s
+ExecStart=%s --serve
 Restart=on-failure
 RestartSec=5
 StateDirectory=echolot-server
@@ -144,3 +145,41 @@ func UninstallSystemd() error {
 	fmt.Println("removed echolot-server units (state dir and env file left in place)")
 	return nil
 }
+
+// RepairExecStart brings an already-installed unit up to date with the current invocation.
+//
+// Serving became an explicit verb (--serve), which means every unit written before that change
+// would start the binary with no arguments — and the binary now answers that with usage and a
+// non-zero exit. A self-update replaces the binary but never the unit, so without this a routine
+// update would leave a service that cannot start, discovered whenever the host next reboots.
+//
+// Only a unit this program wrote is touched, identified by its description line. Editing an
+// operator's hand-written unit would be overreach; leaving ours broken would be negligence.
+func RepairExecStart() (repaired bool, err error) {
+	b, err := os.ReadFile(unitPath)
+	if err != nil {
+		return false, nil // no unit installed: nothing to repair, and not an error
+	}
+	text := string(b)
+	if !strings.Contains(text, "Echolot probe server") {
+		return false, nil // somebody else's unit
+	}
+	lines := strings.Split(text, "\n")
+	changed := false
+	for i, ln := range lines {
+		t := strings.TrimSpace(ln)
+		// Only the serving unit's ExecStart; the timer's own line already carries its verb.
+		if strings.HasPrefix(t, "ExecStart=") && !strings.Contains(t, "--") {
+			lines[i] = ln + " --serve"
+			changed = true
+		}
+	}
+	if !changed {
+		return false, nil
+	}
+	if err := os.WriteFile(unitPath, []byte(strings.Join(lines, "\n")), 0o644); err != nil {
+		return false, fmt.Errorf("updating %s: %w", unitPath, err)
+	}
+	_ = exec.Command("systemctl", "daemon-reload").Run()
+	return true, nil
+}