feat(trust): host-gated trust-on-first-use — PIN pairing mandatory by default

TOFU let anyone who could reach the host click "Trust" and stream, which defeats the point
on a LAN. Make SPAKE2 PIN pairing the default and only way to trust a NEW host; TOFU survives
as an explicit HOST opt-in (for fully trusted networks), advertised over mDNS so clients render
their trust UI from the host's policy rather than offering trust on faith.

Contract:
- Host advertises pair=required (default) or pair=optional. pair=required rejects unpaired
  clients at the handshake; pair=optional accepts them (TOFU).
- Clients: a pinned host whose fingerprint matches connects silently; a pinned host whose
  fingerprint CHANGED forces re-pairing via PIN (no re-trust shortcut); a NEW host is offered
  TOFU only if it advertised pair=optional, otherwise PIN pairing is mandatory; a manually-typed
  or unknown-policy host is always PIN.

Host (crates/punktfunk-host/src/main.rs):
- m3-host now REQUIRES pairing by default (was open by default). New --allow-tofu opts into
  accepting unpaired clients + advertising pair=optional; pairing is always armed (PIN logged at
  startup). serve --native was already secure-by-default (serve --open). The mDNS advert and the
  accept loop already mapped require_pairing -> pair=required + reject; only the m3-host CLI
  default + help text changed.

Clients honor the advertised policy:
- Android (MainActivity.kt): TOFU only for a discovered pair=optional host; manual/unknown -> PIN;
  fp-change -> re-pair only (dropped the "Forget & re-TOFU" shortcut).
- Apple (HostDiscovery/SessionModel/ContentView/HostCards/HostStore): new allowsTofu
  (pair==optional, distinct from unknown); connect() gates .awaitingTrust on it; unpinned
  non-optional hosts route to the PIN sheet; "Forget Identity" re-pairs rather than re-TOFUs.
- Linux (app.rs/ui_hosts.rs/session.rs): ConnectRequest.pair_required -> pair_optional;
  initiate_connect routes pinned/fp-changed/optional/else; manual + --connect unknown -> PIN; a
  pinned connect rejected on trust grounds re-pairs.

Docs (CLAUDE.md, README.md, docs-site/content/docs/pairing.md): describe the gated model — PIN is
the default, TOFU an explicit opt-in with an impostor warning.

Verified: host cargo check/clippy/fmt clean; Android built + live (emulator -> home-worker-2):
a manual connect now opens the PIN dialog (no Trust button) and the PIN ceremony streams; Apple
swift build clean; Linux clippy -D warnings + fmt clean on the Linux box.

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

clients/android/app/src/main/kotlin/io/unom/punktfunk/MainActivity.kt

@@ -145,13 +145,17 @@ private sealed interface Screen {
     data class Stream(val handle: Long) : Screen
 }
 
-/** A trust decision awaiting the user before a connect proceeds. [hostId] is the PinStore key. */
+/**
+ * A trust decision awaiting the user before a connect proceeds. [hostId] is the PinStore key.
+ * Trust-on-first-use ([Kind.TRUST_NEW]) is only ever offered when the host ADVERTISED pair=optional;
+ * a pair=required host or a manually-typed/unknown-policy host goes straight to PIN pairing
+ * ([Kind.PAIR]), and a changed fingerprint forces re-pairing — never a silent re-trust shortcut.
+ */
 private data class PendingTrust(
     val host: String,
     val port: Int,
     val hostId: String,
     val advertisedFp: String?,
-    val pairingRequired: Boolean,
     val kind: Kind,
 ) {
     enum class Kind { TRUST_NEW, FP_CHANGED, PAIR }
@@ -237,32 +241,28 @@ private fun ConnectScreen(onConnected: (Long) -> Unit) {
         }
     }
 
-    // Decide TOFU vs pinned vs pairing before connecting.
+    // Decide pinned-reconnect vs fp-changed vs TOFU vs PIN pairing before connecting. Trust-on-
+    // first-use is permitted ONLY when the host advertised pair=optional (dh.pairingRequired ==
+    // false); a pair=required host, or a manually-typed/unknown-policy host (dh == null), must pair
+    // by PIN — we never trust an unverified cert on faith.
     fun connect(targetHost: String, targetPort: Int, dh: DiscoveredHost? = null) {
         val hostId = hostIdFor(targetHost, targetPort, dh)
         val stored = pinStore.get(hostId)
-        val pairingReq = dh?.pairingRequired ?: false
+        val adv = dh?.fingerprint?.lowercase()
         when {
-            stored != null -> {
-                val adv = dh?.fingerprint?.lowercase()
-                if (adv != null && adv != stored) {
-                    // Advertised fp no longer matches the pin — host reinstall, or an impostor.
-                    pendingTrust = PendingTrust(
-                        targetHost, targetPort, hostId, adv, pairingReq, PendingTrust.Kind.FP_CHANGED,
-                    )
-                } else {
-                    doConnect(targetHost, targetPort, hostId, stored)
-                }
-            }
-            // Never trusted + host requires pairing → TOFU can't pass the gate; go straight to PIN.
-            pairingReq -> pendingTrust = PendingTrust(
-                // pairingReq true ⇒ dh != null (smart-cast), so the fp is the advertised one.
-                targetHost, targetPort, hostId, dh.fingerprint, true, PendingTrust.Kind.PAIR,
-            )
-            // Never trusted, TOFU allowed → confirm trust first.
-            else -> pendingTrust = PendingTrust(
-                targetHost, targetPort, hostId, dh?.fingerprint, false, PendingTrust.Kind.TRUST_NEW,
-            )
+            // Known host whose advertised fp still matches the pin → silent pinned reconnect.
+            stored != null && (adv == null || adv == stored) ->
+                doConnect(targetHost, targetPort, hostId, stored)
+            // Known host whose fp changed → force re-pairing (no silent re-trust shortcut).
+            stored != null -> pendingTrust =
+                PendingTrust(targetHost, targetPort, hostId, adv, PendingTrust.Kind.FP_CHANGED)
+            // Host explicitly advertised pair=optional → trust-on-first-use is permitted (offer it,
+            // clearly labeled, alongside PIN pairing). Smart-cast: this branch ⇒ dh != null.
+            dh?.pairingRequired == false -> pendingTrust =
+                PendingTrust(targetHost, targetPort, hostId, dh.fingerprint, PendingTrust.Kind.TRUST_NEW)
+            // pair=required, or a manual/unknown-policy host → PIN pairing is mandatory.
+            else -> pendingTrust =
+                PendingTrust(targetHost, targetPort, hostId, adv, PendingTrust.Kind.PAIR)
         }
     }
 
@@ -328,7 +328,10 @@ private fun ConnectScreen(onConnected: (Long) -> Unit) {
                     Column {
                         Text("First connection to ${pt.host}:${pt.port}.")
                         pt.advertisedFp?.let { Text("Fingerprint ${it.take(16)}…") }
-                        Text("Pairing with a PIN is stronger — it verifies both sides.")
+                        Text(
+                            "This host allows trust-on-first-use, but that can't tell an impostor " +
+                                "from the real host. Pairing with a PIN is stronger — it proves both sides.",
+                        )
                     }
                 },
                 confirmButton = {
@@ -351,22 +354,15 @@ private fun ConnectScreen(onConnected: (Long) -> Unit) {
                 text = {
                     Text(
                         "The pinned fingerprint for ${pt.host} no longer matches what it now " +
-                            "advertises. This can mean a host reinstall — or an impostor. Re-pair, " +
-                            "or forget the saved fingerprint to trust the new one.",
+                            "advertises. This can mean a host reinstall — or an impostor. Re-pair " +
+                            "with the host's PIN to continue.",
                     )
                 },
                 confirmButton = {
                     TextButton({ pendingTrust = pt.copy(kind = PendingTrust.Kind.PAIR) }) { Text("Re-pair") }
                 },
                 dismissButton = {
-                    Row {
-                        TextButton({
-                            pinStore.remove(pt.hostId)
-                            pendingTrust = null
-                            doConnect(pt.host, pt.port, pt.hostId, null)
-                        }) { Text("Forget & re-TOFU") }
-                        TextButton({ pendingTrust = null }) { Text("Cancel") }
-                    }
+                    TextButton({ pendingTrust = null }) { Text("Cancel") }
                 },
             )
             PendingTrust.Kind.PAIR -> {
@@ -442,8 +438,8 @@ private fun DiscoveredHostRow(dh: DiscoveredHost, enabled: Boolean, onTap: () ->
     ) {
         Column(Modifier.padding(12.dp)) {
             Text(dh.name, style = MaterialTheme.typography.bodyLarge)
-            val pairing = if (dh.pairingRequired) "pairing required" else "TOFU"
-            Text("${dh.host}:${dh.port} · $pairing", style = MaterialTheme.typography.bodySmall)
+            val trust = if (dh.pairingRequired) "PIN pairing" else "PIN or trust-on-first-use"
+            Text("${dh.host}:${dh.port} · $trust", style = MaterialTheme.typography.bodySmall)
             dh.fingerprint?.let { fp ->
                 Text("fp ${fp.take(16)}…", style = MaterialTheme.typography.labelSmall)
             }

clients/apple/Sources/PunktfunkClient/ContentView.swift

@@ -181,7 +181,21 @@ struct ContentView: View {
 
     // MARK: - Connect
 
-    private func connect(_ host: StoredHost, launchID: String? = nil) {
+    private func connect(_ host: StoredHost, launchID: String? = nil, allowTofu: Bool? = nil) {
+        // A pinned host connects on its stored fingerprint; an unpinned host may only TOFU when
+        // the host's LIVE advert says `pair=optional` (rule 3a). When the caller doesn't already
+        // know the policy (a saved-card tap / manual entry), resolve it from the current mDNS set:
+        // an unpinned host with no matching `pair=optional` advert routes to PIN pairing instead
+        // of silently entering the trust prompt (rules 3b + 4). A pinned host ignores all of this.
+        if host.pinnedSHA256 == nil {
+            let tofuOK = allowTofu ?? discovery.hosts.contains {
+                host.matches($0) && $0.allowsTofu
+            }
+            if !tofuOK {
+                pairingTarget = host
+                return
+            }
+        }
         // The gamepad-type setting resolves NOW (Automatic → match the active physical
         // controller): the host's virtual pad backend is fixed per session.
         model.connect(
@@ -194,7 +208,8 @@ struct ContentView: View {
                 setting: PunktfunkConnection.GamepadType(
                     rawValue: UInt32(clamping: gamepadType)) ?? .auto),
             bitrateKbps: UInt32(clamping: bitrateKbps),
-            launchID: launchID)
+            launchID: launchID,
+            allowTofu: host.pinnedSHA256 == nil)
     }
 
     /// Picked a title in the (experimental) library: dismiss the browser and start a session that
@@ -205,16 +220,18 @@ struct ContentView: View {
     }
 
     /// Tap a discovered host: save it (so the session has a stored identity and the trust pin
-    /// persists), then connect — TOFU shows the fingerprint, which should match the advertised
-    /// `fp`. A `pair=required` host goes straight to the pairing ceremony instead.
+    /// persists), then connect or pair per the host's advertised policy. The host is the policy
+    /// authority — TOFU is offered ONLY when it explicitly advertised `pair=optional` (rule 3a);
+    /// a `pair=required` host, or one with no/unknown `pair` field, goes straight to the PIN
+    /// pairing ceremony (rule 3b). (A pinned discovered host connects silently inside `connect`.)
     private func connectDiscovered(_ d: DiscoveredHost) {
         guard !model.isBusy else { return }
         let host = StoredHost(name: d.name, address: d.host, port: d.port)
         store.add(host)
-        if d.requiresPairing {
-            pairingTarget = host
+        if d.allowsTofu {
+            connect(host, allowTofu: true)
         } else {
-            connect(host)
+            pairingTarget = host
         }
     }
 

clients/apple/Sources/PunktfunkClient/HostCards.swift

@@ -110,7 +110,9 @@ struct HostCardView: View {
                 Button("Browse Library…", action: onBrowseLibrary)
             }
             if host.pinnedSHA256 != nil {
-                Button("Forget Identity", action: onForget)
+                // Dropping the pin does NOT downgrade to TOFU: the next connect must re-pair via
+                // PIN (unless the host advertises pair=optional). Wording reflects that.
+                Button("Forget Identity (re-pair to reconnect)", action: onForget)
             }
             Button("Remove", role: .destructive, action: onRemove)
         }

clients/apple/Sources/PunktfunkClient/HostStore.swift

@@ -86,8 +86,9 @@ final class HostStore: ObservableObject {
         hosts[i].pinnedSHA256 = fingerprint
     }
 
-    /// Drop the pinned identity (e.g. after a legitimate host reinstall) — the next
-    /// connect goes through the trust prompt again.
+    /// Drop the pinned identity (e.g. after a legitimate host reinstall). This does NOT downgrade
+    /// to TOFU: the next connect re-pairs via the PIN ceremony, unless the host advertises
+    /// `pair=optional` (the only case the connect path still offers the trust prompt).
     func forgetIdentity(_ host: StoredHost) {
         guard let i = hosts.firstIndex(where: { $0.id == host.id }) else { return }
         hosts[i].pinnedSHA256 = nil

clients/apple/Sources/PunktfunkClient/SessionModel.swift

@@ -83,11 +83,18 @@ final class SessionModel: ObservableObject {
 
     var isBusy: Bool { phase != .idle }
 
+    /// `allowTofu` gates the trust-on-first-use prompt for an unpinned host: it is only true
+    /// when the host EXPLICITLY advertised `pair=optional` (rule 3a). For any other unpinned host
+    /// — `pair=required`, a manually-typed host, or a discovered host with no/unknown `pair`
+    /// field — TOFU is forbidden (rule 3b): the connect refuses rather than offering trust, and
+    /// the user is routed to PIN pairing by the caller. (A pinned host connects regardless: its
+    /// stored fingerprint is the trust decision.)
     func connect(to host: StoredHost, width: UInt32, height: UInt32, hz: UInt32,
                  compositor: PunktfunkConnection.Compositor = .auto,
                  gamepad: PunktfunkConnection.GamepadType = .auto,
                  bitrateKbps: UInt32 = 0,
                  launchID: String? = nil,
+                 allowTofu: Bool = false,
                  autoTrust: Bool = false) {
         guard phase == .idle else { return }
         phase = .connecting
@@ -118,12 +125,24 @@ final class SessionModel: ObservableObject {
                 }
                 switch result {
                 case .success(let conn):
-                    self.connection = conn
-                    self.startStatsTimer()
                     if pin != nil || autoTrust {
+                        self.connection = conn
+                        self.startStatsTimer()
                         self.beginStreaming()
-                    } else {
+                    } else if allowTofu {
+                        // Host advertised pair=optional — offer the reduced-security TOFU prompt
+                        // over the live (blurred) stream (rule 3a).
+                        self.connection = conn
+                        self.startStatsTimer()
                         self.phase = .awaitingTrust(fingerprint: conn.hostFingerprint)
+                    } else {
+                        // Unpinned and TOFU not permitted (rule 3b): never let this silently
+                        // become trustable. Drop the connection; the caller routes to pairing.
+                        Task.detached { conn.close() } // joins Rust threads — off-main
+                        self.phase = .idle
+                        self.activeHost = nil
+                        self.errorMessage = "\(host.displayName) is not paired yet. "
+                            + "Pair with its PIN before streaming."
                     }
                 case .failure:
                     self.phase = .idle

clients/apple/Sources/PunktfunkKit/HostDiscovery.swift

@@ -27,6 +27,10 @@ public struct DiscoveredHost: Identifiable, Sendable, Equatable {
     public let fingerprintHex: String?
     /// The host advertised `pair=required` — a client must pair before it can stream.
     public let requiresPairing: Bool
+    /// The host EXPLICITLY advertised `pair=optional` — only then may the client offer the
+    /// reduced-security TOFU "Trust" path. A missing/unknown `pair` field is NOT optional:
+    /// pairing is mandatory unless this is true (the policy authority is the host's advert).
+    public let allowsTofu: Bool
 }
 
 @MainActor
@@ -124,7 +128,8 @@ public final class HostDiscovery: ObservableObject {
                         self.resolved[key] = DiscoveredHost(
                             id: (id?.isEmpty == false) ? id! : name,
                             name: name, host: address, port: port.rawValue,
-                            fingerprintHex: fp, requiresPairing: pair == "required")
+                            fingerprintHex: fp, requiresPairing: pair == "required",
+                            allowsTofu: pair == "optional")
                         self.publish()
                     }
                     conn.cancel()