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/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