feat(host): GameStream/Moonlight compat is now opt-in (--gamestream) — secure native-only by default

Follows the security audit (#5/#9): the GameStream-compat plane carries inherent on-path weaknesses
that can't be fixed on the wire without breaking stock Moonlight — its pairing runs over plain HTTP
(#9, MITM-able during the pairing window) and its legacy control encryption can reuse GCM nonces (#5,
a passive eavesdropper can recover/forge input). The native punktfunk/1 plane (SPAKE2 PIN pairing +
per-direction AEAD nonces) has neither. So flip the default to secure-by-default:

- `serve`              → native punktfunk/1 plane + management API ONLY (no GameStream surface).
- `serve --gamestream` → ALSO the GameStream/Moonlight-compat planes (nvhttp pairing, RTSP, ENet
  control, _nvstream mDNS). Opt-in, logged with a trusted-LAN caveat. `--moonlight` is an alias.
- The native plane is now ALWAYS on in `serve` (`--native` is a kept-for-compat no-op); the unified
  GameStream+native host is `serve --gamestream`.

`gamestream::serve` gates the GameStream spawns (nvhttp/rtsp/control/mdns) on the flag; the native
plane + mgmt + native-pairing handle always run.

To avoid silently regressing validated Moonlight deployments, the explicit deployment configs PRESERVE
Moonlight via `--gamestream` (each documents dropping it for a secure native-only host): the Linux
systemd unit, the Steam Deck installer, and the Windows service default (DEFAULT_HOST_CMD). The bare
`serve` default (new/manual use) is secure.

Docs swept to match (host-cli, moonlight, quickstart, install, packaging READMEs, CLAUDE.md, README,
…): Moonlight setup now instructs `--gamestream`; native/console refs use bare `serve`. OpenAPI
regenerated (a stale "run `serve --native`" string). fmt + clippy clean; 94 host tests green.

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

crates/punktfunk-host/src/gamestream/mod.rs

@@ -154,56 +154,72 @@ impl AppState {
 /// QUIC server on `cfg.port` in the same process, sharing one [`crate::native_pairing`] handle with
 /// the management API so the web console can arm pairing and show the PIN. `None` = GameStream only
 /// (the mgmt API's native endpoints report `enabled: false`).
+/// Run the host. The **native punktfunk/1 plane + management API always run** (the secure default —
+/// SPAKE2 pairing, per-direction AEAD nonces); `gamestream` additionally brings up the
+/// GameStream/Moonlight-compat planes (nvhttp pairing, RTSP, ENet control, `_nvstream` mDNS), which
+/// carry inherent on-path weaknesses (plain-HTTP pairing + legacy GCM nonce reuse, security-review
+/// #5/#9) — so it is **opt-in** (`serve --gamestream`) and gated on a trusted LAN.
 pub fn serve(
     mgmt: crate::mgmt::Options,
-    native: Option<crate::punktfunk1::NativeServe>,
+    native: crate::punktfunk1::NativeServe,
+    gamestream: bool,
 ) -> Result<()> {
     let host = Host::detect()?;
     let identity = cert::ServerIdentity::load_or_create().context("host certificate")?;
     let state = Arc::new(AppState::new(host, identity));
-    // The shared native-pairing handle exists only when we run the native host; it links the QUIC
-    // ceremony and the management API.
-    let np = match &native {
-        Some(_) => Some(Arc::new(
-            crate::native_pairing::NativePairing::load_with(None, None, false)
-                .context("native pairing store")?,
-        )),
-        None => None,
-    };
+    // The native plane always runs, so the shared native-pairing handle (linking the QUIC ceremony
+    // and the management API) always exists.
+    let np = Arc::new(
+        crate::native_pairing::NativePairing::load_with(None, None, false)
+            .context("native pairing store")?,
+    );
     tracing::info!(
         hostname = %state.host.hostname,
         uniqueid = %state.host.uniqueid,
         ip = %state.host.local_ip,
-        native = native.is_some(),
-        require_pairing = native.as_ref().map(|n| n.require_pairing),
-        "punktfunk host (GameStream P1.1: serverinfo + pairing + mDNS)"
+        native_port = native.port,
+        require_pairing = native.require_pairing,
+        gamestream,
+        "punktfunk host"
     );
+    if gamestream {
+        tracing::warn!(
+            "GameStream/Moonlight compat ENABLED (--gamestream): its pairing runs over plain HTTP and \
+             its legacy control encryption can reuse GCM nonces (security-review #5/#9) — an on-path \
+             LAN attacker could MITM pairing or recover input. Enable only on a TRUSTED network; prefer \
+             the native punktfunk/1 plane + clients for untrusted/WAN use."
+        );
+    }
     let rt = tokio::runtime::Runtime::new().context("build tokio runtime")?;
     rt.block_on(async move {
         // rustls needs a process-wide crypto provider before any TLS config is built.
         let _ = rustls::crypto::aws_lc_rs::default_provider().install_default();
-        let _advert = mdns::advertise(&state.host).context("mDNS advertise")?;
-        rtsp::spawn(state.clone()).context("start RTSP server")?;
-        control::spawn(state.clone()).context("start ENet control server")?;
-        match (native, np) {
-            (Some(cfg), Some(np)) => {
-                tracing::info!(
-                    port = cfg.port,
-                    require_pairing = cfg.require_pairing,
-                    "unified host: also serving native punktfunk/1 (QUIC)"
-                );
-                tokio::try_join!(
-                    nvhttp::run(state.clone()),
-                    crate::mgmt::run(state.clone(), mgmt, Some(np.clone())),
-                    crate::punktfunk1::serve(crate::punktfunk1::native_serve_opts(&cfg), np),
-                )?;
-            }
-            _ => {
-                tokio::try_join!(
-                    nvhttp::run(state.clone()),
-                    crate::mgmt::run(state, mgmt, None)
-                )?;
-            }
+        let native_opts = crate::punktfunk1::native_serve_opts(&native);
+        if gamestream {
+            // Unified host: GameStream compat planes + native + mgmt.
+            let _advert = mdns::advertise(&state.host).context("mDNS advertise")?;
+            rtsp::spawn(state.clone()).context("start RTSP server")?;
+            control::spawn(state.clone()).context("start ENet control server")?;
+            tracing::info!(
+                port = native.port,
+                "unified host: GameStream/Moonlight compat + native punktfunk/1 (QUIC)"
+            );
+            tokio::try_join!(
+                nvhttp::run(state.clone()),
+                crate::mgmt::run(state.clone(), mgmt, Some(np.clone())),
+                crate::punktfunk1::serve(native_opts, np),
+            )?;
+        } else {
+            // Secure default: native punktfunk/1 + management API only (no GameStream surface).
+            tracing::info!(
+                port = native.port,
+                "secure host: native punktfunk/1 (QUIC) + management API \
+                 (GameStream OFF — pass --gamestream for stock-Moonlight compat)"
+            );
+            tokio::try_join!(
+                crate::mgmt::run(state.clone(), mgmt, Some(np.clone())),
+                crate::punktfunk1::serve(native_opts, np),
+            )?;
         }
         Ok(())
     })

crates/punktfunk-host/src/main.rs

@@ -6,10 +6,10 @@
 //! `#[cfg(target_os = "linux")]`; the crate compiles everywhere so the workspace builds
 //! on non-Linux dev machines — it just can't run the pipeline there.
 //!
-//! Subcommands: `serve` runs the GameStream-compatible host + management REST API (and, with
-//! `--native`, the native punktfunk/1 host in-process); `punktfunk1-host` runs the native
-//! punktfunk/1 host standalone; `spike` is a capture→encode→file pipeline dev tool that also
-//! round-trips the encoded AUs through a `punktfunk_core` loopback.
+//! Subcommands: `serve` runs the native punktfunk/1 host + management REST API by default, and —
+//! with `--gamestream` — the GameStream/Moonlight-compat planes too (opt-in, trusted-LAN only);
+//! `punktfunk1-host` runs the native punktfunk/1 host standalone; `spike` is a capture→encode→file
+//! pipeline dev tool that also round-trips the encoded AUs through a `punktfunk_core` loopback.
 
 // Scaffold: trait methods and config paths are defined ahead of their backends.
 #![allow(dead_code)]
@@ -103,11 +103,11 @@ fn real_main() -> Result<()> {
     crate::capture::dxgi::install_gpu_pref_hook();
 
     match args.first().map(String::as_str) {
-        // GameStream host control plane (P1.1: mDNS + serverinfo) + management API, and (with
-        // --native) the native punktfunk/1 host in the same process — the unified host.
+        // The host: the native punktfunk/1 plane + management API by default (secure), and — with
+        // --gamestream — the GameStream/Moonlight-compat planes too (opt-in; #5/#9 trusted-LAN caveat).
         Some("serve") => {
-            let (mgmt_opts, native) = parse_serve(&args[1..])?;
-            gamestream::serve(mgmt_opts, native)
+            let (mgmt_opts, native, gamestream) = parse_serve(&args[1..])?;
+            gamestream::serve(mgmt_opts, native, gamestream)
         }
         // Print the management API's OpenAPI document (for client codegen).
         Some("openapi") => {
@@ -332,14 +332,16 @@ fn input_test() -> Result<()> {
     bail!("input-test requires Linux")
 }
 
-/// `serve` options: the management API (GameStream ports are protocol-fixed) + whether to also run
-/// the native punktfunk/1 host in-process (`--native`, the unified host). Returns the mgmt options
-/// and the native host config (`None` = GameStream only). Native pairing is **required by default**
+/// `serve` options. The **native punktfunk/1 plane + management API are the secure default and always
+/// run**; `--gamestream` additionally enables the GameStream/Moonlight-compat planes (opt-in — they
+/// carry the inherent on-path #5/#9 weaknesses, so only on a trusted LAN). Returns the mgmt options,
+/// the native host config, and whether GameStream is enabled. Native pairing is **required by default**
 /// (an open host any LAN device can stream from is insecure); `--open` turns it off.
-fn parse_serve(args: &[String]) -> Result<(mgmt::Options, Option<punktfunk1::NativeServe>)> {
+fn parse_serve(args: &[String]) -> Result<(mgmt::Options, punktfunk1::NativeServe, bool)> {
     let mut opts = mgmt::Options::default();
-    let mut native_port: Option<u16> = None;
+    let mut native_port: u16 = 9777; // the native plane always runs now
     let mut open = false;
+    let mut gamestream = false;
     let mut i = 0;
     while i < args.len() {
         let arg = args[i].as_str();
@@ -365,16 +367,17 @@ fn parse_serve(args: &[String]) -> Result<(mgmt::Options, Option<punktfunk1::Nat
                 }
                 opts.token = Some(token);
             }
-            // Also run the native punktfunk/1 (QUIC) host in this process — the unified host.
-            // Pairing is then armed on demand from the management API / web console.
-            "--native" => native_port = Some(native_port.unwrap_or(9777)),
+            // The native plane is now the DEFAULT (always runs in `serve`); `--native` is kept as an
+            // accepted no-op for back-compat / explicitness.
+            "--native" => {}
             "--native-port" => {
-                native_port = Some(
-                    next()?
-                        .parse()
-                        .map_err(|_| anyhow::anyhow!("bad --native-port (want a port number)"))?,
-                )
+                native_port = next()?
+                    .parse()
+                    .map_err(|_| anyhow::anyhow!("bad --native-port (want a port number)"))?
             }
+            // Opt into the GameStream/Moonlight-compat planes (off by default — they carry the
+            // inherent on-path #5/#9 weaknesses; only for a trusted LAN).
+            "--gamestream" | "--moonlight" => gamestream = true,
             // Disable mandatory native pairing — any device can connect (trusted single-user
             // setups only). The default REQUIRES pairing.
             "--open" => open = true,
@@ -393,11 +396,11 @@ fn parse_serve(args: &[String]) -> Result<(mgmt::Options, Option<punktfunk1::Nat
     if opts.token.is_none() {
         opts.token = Some(crate::mgmt_token::load_or_generate()?);
     }
-    let native = native_port.map(|port| punktfunk1::NativeServe {
-        port,
+    let native = punktfunk1::NativeServe {
+        port: native_port,
         require_pairing: !open,
-    });
-    Ok((opts, native))
+    };
+    Ok((opts, native, gamestream))
 }
 
 fn parse_spike(args: &[String]) -> Result<Options> {
@@ -502,8 +505,8 @@ fn print_usage() {
         "punktfunk-host — Linux streaming host
 
 USAGE:
-    punktfunk-host serve [OPTIONS]            GameStream host control plane (mDNS + serverinfo …)
-                                              + the management REST API
+    punktfunk-host serve [OPTIONS]            native punktfunk/1 host + management REST API
+                                              (secure default; add --gamestream for Moonlight compat)
     punktfunk-host openapi                    print the management API's OpenAPI document (codegen)
     punktfunk-host punktfunk1-host [OPTIONS]  native punktfunk/1 host (QUIC control + UDP data plane)
     punktfunk-host probe-compositor           exit 0 iff the compositor is up + ready (bringup gate)
@@ -513,9 +516,12 @@ SERVE OPTIONS:
     --mgmt-bind <IP:PORT>        management API address (default: 127.0.0.1:47990)
     --mgmt-token <TOKEN>         bearer token for the management API (or PUNKTFUNK_MGMT_TOKEN);
                                  required when --mgmt-bind is not loopback
-    --native                     also run the native punktfunk/1 (QUIC) host in this process —
-                                 the unified host; pairing is armed from the management API/console
-    --native-port <PORT>         native QUIC port (default 9777; implies --native)
+    --gamestream  (--moonlight)  ALSO run the GameStream/Moonlight-compat planes (nvhttp pairing,
+                                 RTSP, ENet control, _nvstream mDNS). OFF by default — they carry
+                                 inherent on-path weaknesses (plain-HTTP pairing + legacy GCM nonce
+                                 reuse, security-review #5/#9); enable only on a TRUSTED LAN
+    --native                     no-op (the native punktfunk/1 plane always runs in `serve` now)
+    --native-port <PORT>         native QUIC port (default 9777)
     --open                       disable mandatory native pairing (default: pairing REQUIRED —
                                  an open host any LAN device can stream from is insecure)
 
@@ -550,7 +556,7 @@ NOTES:
     (see docs/linux-setup.md). 'synthetic' needs no capture session and always runs.
     Encoded AUs are written to a playable file AND (unless --no-loopback) fed through a
     punktfunk_core host→client loopback that reassembles and byte-verifies each one.
-    Both 'serve --native' and 'punktfunk1-host' advertise the native service over mDNS
+    Both 'serve' and 'punktfunk1-host' advertise the native service over mDNS
     (_punktfunk._udp) for client auto-discovery — 'punktfunk-probe --discover' lists them."
     );
     #[cfg(target_os = "windows")]

crates/punktfunk-host/src/mgmt.rs

@@ -850,7 +850,7 @@ async fn get_native_pairing(State(st): State<Arc<MgmtState>>) -> Json<NativePair
     request_body = ArmNativePairing,
     responses(
         (status = OK, description = "Pairing armed; the response carries the PIN to display", body = NativePairStatus),
-        (status = SERVICE_UNAVAILABLE, description = "Native host not enabled (run `serve --native`)", body = ApiError),
+        (status = SERVICE_UNAVAILABLE, description = "Native host not available in this process", body = ApiError),
         (status = UNAUTHORIZED, description = "Missing or invalid bearer token", body = ApiError),
     )
 )]
@@ -861,7 +861,7 @@ async fn arm_native_pairing(
     let Some(np) = &st.native else {
         return api_error(
             StatusCode::SERVICE_UNAVAILABLE,
-            "native host not enabled (run `serve --native`)",
+            "native host not available in this process",
         );
     };
     let ttl = req.ttl_secs.unwrap_or(120).clamp(15, 600);

crates/punktfunk-host/src/service.rs

@@ -58,9 +58,11 @@ const SERVICE_DESCRIPTION: &str =
     "Low-latency desktop/game streaming host. Launches the punktfunk host into the active session.";
 
 /// The host subcommand the service launches, overridable via `PUNKTFUNK_HOST_CMD` in host.env.
-/// `serve --native` runs the GameStream (Moonlight) host + the native punktfunk/1 QUIC host in one
-/// process — the unified host an end user wants.
-const DEFAULT_HOST_CMD: &str = "serve --native";
+/// `serve --gamestream` runs the native punktfunk/1 QUIC host (always on) PLUS the GameStream
+/// (Moonlight) compat planes — the unified host a Windows end user typically wants (Moonlight is the
+/// common Windows client). Drop `--gamestream` for a secure native-only host (no plain-HTTP pairing /
+/// legacy GCM nonce reuse — security-review #5/#9; native clients only).
+const DEFAULT_HOST_CMD: &str = "serve --gamestream";
 
 /// Event handles shared between the SCM control handler (which signals them) and the supervision loop
 /// (which waits on them). Stored as raw `isize` so the `'static + Send` handler can reach them without
@@ -619,8 +621,9 @@ fn ensure_default_host_env() -> Result<()> {
         PUNKTFUNK_SECURE_DDA=1\n\
         RUST_LOG=info\n\
         \n\
-        # The host subcommand the service launches (default: serve --native).\n\
-        # PUNKTFUNK_HOST_CMD=serve --native\n\
+        # The host subcommand the service launches (default: serve --gamestream = native + Moonlight\n\
+        # compat). Use `serve` for a SECURE native-only host (no GameStream #5/#9 surface).\n\
+        # PUNKTFUNK_HOST_CMD=serve --gamestream\n\
         \n\
         # Force a specific NVENC render GPU by name substring (multi-GPU boxes only):\n\
         # PUNKTFUNK_RENDER_ADAPTER=4090\n";