Implement CatHub-owned UMDF virtual COM transport

.github/workflows/ci.yml

@@ -46,3 +46,44 @@ jobs:
         with:
           dotnet-version: 10.0.x
       - run: dotnet build CatHub.slnx -c Release
+
+  umdf-driver:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v7.0.0
+      - uses: dtolnay/rust-toolchain@1.91.0
+        with:
+          components: rustfmt, clippy
+          targets: x86_64-pc-windows-msvc
+      - uses: NuGet/setup-nuget@v4.0
+        with:
+          nuget-version: 6.14.3
+      - name: Restore pinned WDK
+        shell: pwsh
+        run: |
+          $packageRoot = Join-Path $env:LOCALAPPDATA 'CatHub\wdk\packages'
+          nuget install Microsoft.Windows.WDK.x64 `
+            -Version 10.0.28000.2526 `
+            -OutputDirectory $packageRoot `
+            -NonInteractive `
+            -DirectDownload `
+            -Source https://api.nuget.org/v3/index.json
+      - name: Build, test, and lint pure-Rust UMDF driver
+        shell: pwsh
+        run: .\scripts\Test-UmdfPoc.ps1
+
+  supply-chain:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.0
+      - name: Audit application dependencies
+        uses: EmbarkStudios/cargo-deny-action@v2.1.1
+        with:
+          command: check
+          command-arguments: advisories bans sources
+      - name: Audit UMDF driver dependencies
+        uses: EmbarkStudios/cargo-deny-action@v2.1.1
+        with:
+          command: check
+          command-arguments: advisories bans sources
+          manifest-path: drivers/cathub-virtual-serial-umdf/Cargo.toml

.gitignore

@@ -5,6 +5,8 @@ target
 artifacts
 .vs
 **/bin
+!crates/cathub-virtual-serial/src/bin/
+!crates/cathub-virtual-serial/src/bin/serial-conformance.rs
 **/obj
 
 # These are backup files generated by rustfmt

Cargo.toml

@@ -5,6 +5,7 @@ members = [
     "crates/cathub-protocol",
     "crates/cathub-virtual-serial",
 ]
+exclude = ["drivers/cathub-virtual-serial-umdf"]
 
 [workspace.package]
 version = "0.2.1"

README.md

@@ -132,8 +132,9 @@ Clients must validate that process ID before they use the endpoint.
 ## Client interfaces
 
 - Hamlib-aware clients connect to a configured `[[hamlib_net]]` TCP listener.
-- Serial CAT clients connect to the application side of a dedicated virtual serial pair.
-- Legacy WinKeyer clients connect to their own virtual serial pair.
+- On Windows, serial CAT clients can connect to a single CatHub-owned UMDF COM endpoint; existing
+  physical and externally provisioned serial transports remain supported.
+- Legacy WinKeyer clients can use their own CatHub-owned UMDF COM endpoint.
 - Typed WinKeyer clients connect to the loopback gRPC address in `[winkeyer].api_bind`.
 
 A launcher-managed client uses the endpoint in CatHub's runtime file.
@@ -165,6 +166,8 @@ Registry publication is a separate authorized operation. See
 - [Virtual serial Phase 1](docs/design/virtual-serial-transport-phase-1.md)
 - [Serial client inventory](docs/testing/serial-client-inventory.md)
 - [Operator setup](docs/integration/setup.md)
+- [Windows CatHub-owned virtual serial](docs/integration/windows-virtual-serial.md)
+- [Virtual serial signing decision](docs/design/virtual-serial-signing-decision.md)
 - [Release and compatibility](docs/architecture/release-and-compatibility.md)
 
 ## License

config/cathub.toml

@@ -7,8 +7,9 @@
 # Validate without touching hardware:
 #   cargo run -p cathub -- --config config/cathub.toml --dry-run
 #
-# Virtual serial pairs (com0com): the daemon binds the first port of each pair, the
-# application binds the second. Create one pair per serial client.
+# CatHub-managed virtual serial endpoints expose one application-facing COM port each.
+# The daemon connects through the private UMDF interface selected by `virtual_endpoint`.
+# Provision them with `cathub --config config/cathub.toml virtual-serial apply --inf <INF>`.
 
 [radio]
 backend = "ts590"        # first-class native Kenwood TS-590 driver (no Hamlib linked)
@@ -30,8 +31,7 @@ native_push = true       # daemon enables and owns the TS-590 AI2; stream
 # --- WinKeyer broker ------------------------------------------------------------------
 #
 # CatHub owns the physical keyer. Typed clients use the loopback API; legacy clients use
-# the application side of a dedicated virtual serial pair. Change COM40/COM41 if that pair
-# is not installed on this station.
+# a dedicated CatHub-managed COM endpoint.
 
 [winkeyer]
 port = "COM3"
@@ -41,15 +41,15 @@ api_bind = "127.0.0.1:50071"
 
 [[winkeyer_endpoint]]
 name = "n1mm-cw"
-transport = "COM40"    # N1MM WinKeyer port is the paired COM41
+virtual_endpoint = "n1mm-winkeyer"
 application_transport = "COM41"
 baud = 1200
 primary = true
 perms = ["status", "send", "control", "ptt"]
 
 [[winkeyer_endpoint]]
 name = "wktools-maintenance"
-transport = "COM42"    # WKTools maintenance port is the paired COM43
+virtual_endpoint = "wktools"
 application_transport = "COM43"
 baud = 1200
 primary = false
@@ -92,16 +92,10 @@ bind = "127.0.0.1:4534"
 single_vfo = true
 perms = ["read", "write"]
 
-# --- Serial endpoints (com0com virtual pairs) ----------------------------------------------
+# --- CatHub-managed serial endpoints ---------------------------------------------------
 #
-# IMPORTANT: each com0com pair has TWO port numbers. The daemon binds the port named below
-# (`transport`); your application must connect to the OTHER port in the same pair. Never
-# point an application at the daemon's port -- they cannot both open the same port.
-#
-#   pair                 daemon binds (transport)   application connects to
-#   COM10 <-> COM11      COM10                      COM11  (HDSDR / OmniRig)
-#   COM20 <-> COM21      COM20                      COM21  (N1MM)
-#   COM30 <-> COM31      COM30                      COM31  (ARCP-590)
+# Each application opens `application_transport`; CatHub attaches to the same device through
+# its private interface. There is no daemon-side COM port and no null-modem pair.
 
 # HDSDR via OmniRig as a TS-2000-style controller. The panadapter follows the radio, and
 # click-to-tune on the waterfall may set frequency. Mode writes are denied so OmniRig cannot
@@ -110,7 +104,7 @@ perms = ["read", "write"]
 # can never oscillate the TS-590's A/B VFO selection.
 [[serial_endpoint]]
 name = "hdsdr-omnirig"
-transport = "COM10"      # OmniRig binds COM11
+virtual_endpoint = "hdsdr-cat"
 application_transport = "COM11"
 baud = 115200
 dialect = "ts2000"
@@ -122,7 +116,7 @@ perms = ["read", "frequency_write"]
 # whichever VFO the radio is actually on, so A/B switching tracks seamlessly.
 [[serial_endpoint]]
 name = "n1mm"
-transport = "COM20"      # N1MM binds COM21
+virtual_endpoint = "n1mm-cat"
 application_transport = "COM21"
 baud = 115200
 dialect = "ts590"
@@ -134,7 +128,7 @@ perms = ["read", "write", "ptt"]
 # single_vfo off (the default).
 [[serial_endpoint]]
 name = "arcp590"
-transport = "COM30"      # ARCP-590 binds COM31
+virtual_endpoint = "arcp590-cat"
 application_transport = "COM31"
 baud = 115200
 dialect = "ts590"

crates/cathub-virtual-serial/Cargo.toml

@@ -9,14 +9,23 @@ repository.workspace = true
 readme = "README.md"
 publish = false
 
+[features]
+default = ["conformance"]
+conformance = ["dep:clap", "dep:serde", "dep:serde_json", "dep:windows-sys"]
+
+[[bin]]
+name = "serial-conformance"
+path = "src/bin/serial-conformance.rs"
+required-features = ["conformance"]
+
 [dependencies]
-clap = { workspace = true }
-serde = { workspace = true }
-serde_json = { workspace = true }
+clap = { workspace = true, optional = true }
+serde = { workspace = true, optional = true }
+serde_json = { workspace = true, optional = true }
 thiserror = { workspace = true }
 
 [target.'cfg(windows)'.dependencies]
-windows-sys = { version = "0.59", features = [
+windows-sys = { version = "0.59", optional = true, features = [
     "Win32_Devices_Communication",
     "Win32_Foundation",
     "Win32_Security",

crates/cathub-virtual-serial/README.md

@@ -23,3 +23,18 @@ cargo run -p cathub-virtual-serial --bin serial-conformance -- run `
 ```
 
 Do not use a physical radio or a physical WinKeyer for this test.
+
+For an installed CatHub-owned UMDF endpoint, start CatHub's hidden loopback-only test peer and use
+the private-channel conformance mode instead of creating a second COM port:
+
+```powershell
+cathub virtual-serial test-peer --endpoint cathub-default `
+  --kind cat --listen 127.0.0.1:39116
+
+serial-conformance run --application-port COM91 `
+  --peer-tcp 127.0.0.1:39116 --profile n1mm-radio `
+  --output artifacts\serial-conformance\managed-n1mm-radio.json
+```
+
+The test peer binds only the explicitly supplied address; the isolated-target harness always uses
+IPv4 loopback and terminates it before starting the production daemon path.

crates/cathub-virtual-serial/src/bin/serial-conformance.rs

@@ -0,0 +1,85 @@
+//! Windows serial API conformance command.
+
+use std::net::SocketAddr;
+use std::path::PathBuf;
+
+use cathub_virtual_serial::conformance::{profiles, run, run_with_tcp_peer, ConformanceError};
+use clap::{Parser, Subcommand};
+
+#[derive(Debug, Parser)]
+#[command(
+    name = "serial-conformance",
+    version,
+    about = "Test a virtual serial pair with the Windows serial API"
+)]
+struct Cli {
+    #[command(subcommand)]
+    command: Command,
+}
+
+#[derive(Debug, Subcommand)]
+enum Command {
+    /// List the supported application profiles as JSON.
+    Profiles,
+    /// Run one profile against an isolated virtual serial pair.
+    Run {
+        /// Application-facing COM port.
+        #[arg(long)]
+        application_port: String,
+        /// Paired COM port that the harness uses as the transport peer.
+        #[arg(
+            long,
+            required_unless_present = "peer_tcp",
+            conflicts_with = "peer_tcp"
+        )]
+        peer_port: Option<String>,
+        /// TCP bridge to a CatHub-managed endpoint's private transport peer.
+        #[arg(
+            long,
+            required_unless_present = "peer_port",
+            conflicts_with = "peer_port"
+        )]
+        peer_tcp: Option<SocketAddr>,
+        /// Stable profile name from the profiles command.
+        #[arg(long)]
+        profile: String,
+        /// Optional JSON report path.
+        #[arg(long)]
+        output: Option<PathBuf>,
+    },
+}
+
+fn main() -> Result<(), ConformanceError> {
+    match Cli::parse().command {
+        Command::Profiles => {
+            println!("{}", serde_json::to_string_pretty(profiles())?);
+            Ok(())
+        }
+        Command::Run {
+            application_port,
+            peer_port,
+            peer_tcp,
+            profile,
+            output,
+        } => {
+            let report = match (peer_port, peer_tcp) {
+                (Some(peer_port), None) => run(&profile, &application_port, &peer_port)?,
+                (None, Some(peer_address)) => {
+                    run_with_tcp_peer(&profile, &application_port, peer_address)?
+                }
+                _ => unreachable!("clap requires exactly one peer transport"),
+            };
+            println!("{}", serde_json::to_string_pretty(&report)?);
+            if let Some(path) = output {
+                report.write_json(&path)?;
+            }
+            if report.required_cases_pass() {
+                Ok(())
+            } else {
+                Err(ConformanceError::InvalidResult(
+                    "one or more required conformance cases failed".to_string(),
+                ))
+            }
+        }
+    }
+}