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>

crates/punktfunk-client-linux/src/app.rs

@@ -44,7 +44,10 @@ pub fn run() -> glib::ExitCode {
 }
 
 /// `--connect host[:port]` — skip the hosts page and start a session immediately
-/// (scripting + headless testing; trust follows the same known-hosts/TOFU rules).
+/// (scripting + headless testing). Trust follows the same rules as a manual entry: a host
+/// already pinned at this address connects silently on its stored pin; an unknown host is
+/// routed to the PIN ceremony (never a silent TOFU connect — `fp_hex`/`pair_optional` are
+/// unset, so `initiate_connect`'s manual arm mandates pairing).
 fn cli_connect_request() -> Option<ConnectRequest> {
     let args: Vec<String> = std::env::args().collect();
     let target = args
@@ -61,7 +64,7 @@ fn cli_connect_request() -> Option<ConnectRequest> {
         addr,
         port,
         fp_hex: None,
-        pair_required: false,
+        pair_optional: false,
     })
 }
 
@@ -119,10 +122,18 @@ fn build_ui(gtk_app: &adw::Application) {
     }
 }
 
-/// The trust gate in front of every connect. Discovered hosts carry their fingerprint in
-/// the mDNS advert, so trust is decided *before* any traffic: known → pinned connect;
-/// unknown → TOFU prompt (or straight to pairing when the host requires it). Manual
-/// entries have no advance fingerprint: trust on first use, pin from then on.
+/// The trust gate in front of every connect. The host is the policy authority (it
+/// advertises `pair=optional` only when it accepts unpaired clients); the client renders
+/// its trust UI from that:
+///   1. PINNED RECONNECT — a host already pinned to this exact fingerprint connects silently.
+///   2. FINGERPRINT CHANGED — a host we know at this address but whose fingerprint no longer
+///      matches is the impostor signal: force re-pairing via the PIN ceremony, regardless of
+///      the advertised policy.
+///   3. NEW host — TOFU is offered only when the host advertised `pair=optional` (rule 3a);
+///      otherwise (pair=required, unknown/empty policy, or a manual entry) PIN pairing is
+///      mandatory (rule 3b).
+///
+/// A new host is never auto-connected without a stored pin or an explicit trust decision.
 fn initiate_connect(app: Rc<App>, req: ConnectRequest) {
     if app.busy.get() {
         return;
@@ -131,19 +142,31 @@ fn initiate_connect(app: Rc<App>, req: ConnectRequest) {
     match &req.fp_hex {
         Some(fp_hex) => {
             if known.find_by_fp(fp_hex).is_some() {
+                // Rule 1: pinned fingerprint matches — silent connect.
                 start_session(app, req.clone(), crate::trust::parse_hex32(fp_hex));
-            } else if req.pair_required {
-                // TOFU alone won't pass the host's gate — go straight to the ceremony.
+            } else if known.find_by_addr(&req.addr, req.port).is_some() {
+                // Rule 2: we trust a host at this address but the fingerprint changed —
+                // the impostor signal. Re-pair via the PIN ceremony (no TOFU shortcut).
+                app.toast("Host fingerprint changed — re-pair with a PIN to continue");
                 pin_dialog(app, req);
-            } else {
+            } else if req.pair_optional {
+                // Rule 3a: the host opted into reduced-security TOFU; offer it alongside PIN.
                 tofu_dialog(app, req);
+            } else {
+                // Rule 3b: pair=required or unknown policy — PIN pairing is mandatory.
+                pin_dialog(app, req);
             }
         }
         None => {
-            let pin = known
+            // Manual entry (no advertised fingerprint). A known address connects silently
+            // on its stored pin (rule 1); an unknown one must pair — never silent TOFU.
+            match known
                 .find_by_addr(&req.addr, req.port)
-                .and_then(|k| crate::trust::parse_hex32(&k.fp_hex));
-            start_session(app, req, pin);
+                .and_then(|k| crate::trust::parse_hex32(&k.fp_hex))
+            {
+                Some(pin) => start_session(app, req, Some(pin)),
+                None => pin_dialog(app, req), // rule 3b
+            }
         }
     }
 }
@@ -457,10 +480,21 @@ fn start_session(app: Rc<App>, req: ConnectRequest, pin: Option<[u8; 32]>) {
                         p.update_stats(s);
                     }
                 }
-                SessionEvent::Failed(msg) => {
-                    tracing::warn!(%msg, "connect failed");
-                    app.toast(&msg);
+                SessionEvent::Failed {
+                    msg,
+                    trust_rejected,
+                } => {
+                    tracing::warn!(%msg, trust_rejected, "connect failed");
                     app.busy.set(false);
+                    // A pinned connect rejected on trust grounds means the host's cert no
+                    // longer matches the stored pin (rotated cert or impostor) — route to
+                    // the PIN ceremony to re-establish trust rather than dead-ending.
+                    if trust_rejected && !tofu {
+                        app.toast("Host fingerprint changed — re-pair with a PIN to continue");
+                        pin_dialog(app.clone(), req.clone());
+                    } else {
+                        app.toast(&msg);
+                    }
                     break;
                 }
                 SessionEvent::Ended(err) => {

crates/punktfunk-client-linux/src/session.rs

@@ -42,7 +42,13 @@ pub enum SessionEvent {
         mode: Mode,
         fingerprint: [u8; 32],
     },
-    Failed(String),
+    /// `trust_rejected` is set when the connect failed the TLS trust check (a `Crypto`
+    /// error): for a pinned connect this is the fingerprint-changed signal, so the UI can
+    /// offer a re-pair (PIN) path rather than a dead-end error.
+    Failed {
+        msg: String,
+        trust_rejected: bool,
+    },
     Ended(Option<String>),
     Stats(Stats),
 }
@@ -97,6 +103,7 @@ fn pump(
     ) {
         Ok(c) => Arc::new(c),
         Err(e) => {
+            let trust_rejected = matches!(e, PunktfunkError::Crypto);
             let msg = match e {
                 PunktfunkError::Crypto => {
                     "Host identity rejected — wrong fingerprint, or the host requires pairing"
@@ -105,7 +112,10 @@ fn pump(
                 PunktfunkError::Timeout => "Connection timed out".to_string(),
                 other => format!("Connect failed: {other:?}"),
             };
-            let _ = ev_tx.send_blocking(SessionEvent::Failed(msg));
+            let _ = ev_tx.send_blocking(SessionEvent::Failed {
+                msg,
+                trust_rejected,
+            });
             return;
         }
     };

crates/punktfunk-client-linux/src/ui_hosts.rs

@@ -9,15 +9,17 @@ use std::collections::HashMap;
 use std::rc::Rc;
 
 /// What the user asked to connect to. `fp_hex` comes from the mDNS TXT record when the
-/// host was discovered (drives the TOFU prompt *before* connecting); manual entries have
-/// none and trust on first use.
+/// host was discovered (drives the trust decision *before* connecting); manual entries have
+/// none. `pair_optional` is true ONLY when a discovered host advertised `pair=optional`,
+/// which is the sole case in which the reduced-security TOFU path may be offered — every
+/// other case (pair=required, unknown/empty policy, manual entry) mandates PIN pairing.
 #[derive(Clone, Debug)]
 pub struct ConnectRequest {
     pub name: String,
     pub addr: String,
     pub port: u16,
     pub fp_hex: Option<String>,
-    pub pair_required: bool,
+    pub pair_optional: bool,
 }
 
 pub fn new(
@@ -80,7 +82,9 @@ pub fn new(
                                     addr: h.addr.clone(),
                                     port: h.port,
                                     fp_hex: (!h.fp_hex.is_empty()).then(|| h.fp_hex.clone()),
-                                    pair_required: h.pair == "required",
+                                    // TOFU is offered only when the host explicitly opts in
+                                    // with pair=optional; required/empty means mandatory PIN.
+                                    pair_optional: h.pair == "optional",
                                 });
                             }
                         });
@@ -119,7 +123,8 @@ pub fn new(
                 addr,
                 port,
                 fp_hex: None,
-                pair_required: false,
+                // Manual entry carries no advertised policy — never eligible for TOFU.
+                pair_optional: false,
             });
         }
     };
@@ -172,7 +177,9 @@ pub fn new(
                     addr: k.addr.clone(),
                     port: k.port,
                     fp_hex: Some(k.fp_hex.clone()),
-                    pair_required: false,
+                    // Saved host: its fp is already pinned, so this routes to a silent
+                    // pinned connect; TOFU eligibility is irrelevant.
+                    pair_optional: false,
                 };
                 let speed_btn = gtk::Button::from_icon_name("network-transmit-receive-symbolic");
                 speed_btn.set_tooltip_text(Some("Test network speed"));