feat(debug-console): fix invalid websocket host and let clients choose network

The debug session URL was built as wss://Invalid Value:65479/debug/join on any
processor without a control subnet. DebugWebsocketSink.Url hard-coded ethernet
adapter id 1 as "the CS LAN adapter" and guarded it with IsNullOrEmpty, but
CrestronEthernetHelper.GetEthernetParameter does not return null or empty for an
absent adapter - it returns the literal string "Invalid Value". The guard passed,
the bad host won, and the fallback URL that would have rescued it was never built
because GetAdapterdIdForSpecifiedAdapterType threw instead.

Add ProcessorEthernetInfo, which resolves addresses by adapter type rather than
guessed index and returns null for the SDK's sentinel, and use it wherever the
processor's own addresses are read.

The session handlers now return every network the websocket is reachable on so a
client on either side of the processor can pick, since a tech may be on the LAN or
on the control subnet:

- networks[] lists each reachable address as {id, label, host, url}
- ?network=lan|cslan|current selects one; an unavailable id falls back to
  auto-selection rather than failing
- without an explicit choice, the request's Host header picks the side the client
  is already on
- port and path are returned so a client that already knows the processor's
  address can build the URL itself - the debug app was served from the processor,
  so window.location.hostname is by definition an address that reaches it

url and fallbackUrl keep their existing meaning, so the current dev tools app
works untouched.

Also:
- CreateCert validated no parameters, so a CN=Invalid Value.Invalid Value cert was
  possible; it now falls back to the IP address and adds the control subnet IP and
  bare hostname to the SAN list
- DebugSessionRequestHandler's outer catch logged and returned nothing, leaving
  the browser on a hung request; it now sends a 500
- RoutingFeedbackSessionRequestHandler carried the same duplicated URL logic and
  gets the same treatment

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CshF5gZ4qiGbEWZWB9Mi2U

Author: aknous

src/PepperDash.Core.Tests/ProcessorEthernetInfoTests.cs

@@ -0,0 +1,36 @@
+using FluentAssertions;
+using Xunit;
+
+namespace PepperDash.Core.Tests;
+
+/// <summary>
+/// Tests for <see cref="ProcessorEthernetInfo"/>'s parameter validation. The adapter lookups themselves
+/// need the Crestron SDK, but the sentinel handling that produced URLs such as
+/// <c>wss://Invalid Value:65479/debug/join</c> is pure and testable.
+/// </summary>
+public class ProcessorEthernetInfoTests
+{
+    [Theory]
+    [InlineData("Invalid Value")]
+    [InlineData("invalid value")]
+    [InlineData("  Invalid Value  ")]
+    public void NullIfInvalid_RejectsSdkSentinel(string value)
+    {
+        ProcessorEthernetInfo.NullIfInvalid(value).Should().BeNull();
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("   ")]
+    public void NullIfInvalid_RejectsBlankValues(string? value)
+    {
+        ProcessorEthernetInfo.NullIfInvalid(value!).Should().BeNull();
+    }
+
+    [Fact]
+    public void NullIfInvalid_ReturnsTrimmedAddress()
+    {
+        ProcessorEthernetInfo.NullIfInvalid(" 10.0.0.5 ").Should().Be("10.0.0.5");
+    }
+}

src/PepperDash.Core/Logging/DebugWebsocketSink.cs

@@ -52,24 +52,56 @@ public int Port
     /// <summary>
     /// Gets the WebSocket URL for the current server instance.
     /// </summary>
-    /// <remarks>The URL is dynamically constructed based on the server's current IP address, port,
-    /// and WebSocket path.</remarks>
+    /// <remarks>
+    /// The URL is dynamically constructed from the processor's LAN IP address, the port and the
+    /// WebSocket path. The control subnet address is only used when there is no usable LAN address,
+    /// since the debug app is normally reached over the LAN. Returns an empty string when the server
+    /// is not listening or no usable address can be read.
+    /// </remarks>
     public string Url
     {
         get
         {
-            if (_httpsServer == null || !_httpsServer.IsListening) return "";
-            var service = _httpsServer.WebSocketServices[_path];
-            if (service == null) return "";
+            var host = ProcessorEthernetInfo.GetLanIpAddress() ?? ProcessorEthernetInfo.GetCsLanIpAddress();
 
-            // Use CSLAN IP if available, otherwise fallback to primary IP. This ensures we provide a reachable URL in dual-stack environments.
-            if (!string.IsNullOrEmpty(CrestronEthernetHelper.GetEthernetParameter(CrestronEthernetHelper.ETHERNET_PARAMETER_TO_GET.GET_CURRENT_IP_ADDRESS, 1)))
-                return $"wss://{CrestronEthernetHelper.GetEthernetParameter(CrestronEthernetHelper.ETHERNET_PARAMETER_TO_GET.GET_CURRENT_IP_ADDRESS, 1)}:{_httpsServer.Port}{service.Path}";
-            else
-                return $"wss://{CrestronEthernetHelper.GetEthernetParameter(CrestronEthernetHelper.ETHERNET_PARAMETER_TO_GET.GET_CURRENT_IP_ADDRESS, 0)}:{_httpsServer.Port}{service.Path}";
+            return GetUrlForHost(host);
+        }
+    }
+
+    /// <summary>
+    /// Gets the WebSocket path clients connect to, e.g. <c>/debug/join</c>. Exposed so a client that
+    /// already knows the processor's address — a browser on a page the processor served, for instance —
+    /// can build the URL itself from its own location.
+    /// </summary>
+    public string ServicePath
+    {
+        get
+        {
+            var service = _httpsServer?.WebSocketServices[_path];
+
+            return service?.Path ?? _path.TrimEnd('/');
         }
     }
 
+    /// <summary>
+    /// Builds the WebSocket URL for this server using the supplied host, which lets callers hand back
+    /// the address the client actually used to reach the processor.
+    /// </summary>
+    /// <param name="host">Host name or IP address, without scheme or port. IPv6 literals must already be bracketed.</param>
+    /// <returns>The <c>wss://</c> URL, or an empty string when the server is not listening or <paramref name="host"/> is unusable.</returns>
+    public string GetUrlForHost(string host)
+    {
+        if (_httpsServer == null || !_httpsServer.IsListening) return "";
+
+        var service = _httpsServer.WebSocketServices[_path];
+        if (service == null) return "";
+
+        host = ProcessorEthernetInfo.NullIfInvalid(host);
+        if (host == null) return "";
+
+        return $"wss://{host}:{_httpsServer.Port}{service.Path}";
+    }
+
     /// <summary>
     /// Gets a value indicating whether the HTTPS server is currently listening for incoming connections.
     /// </summary>
@@ -131,14 +163,29 @@ private static void CreateCert()
         // CrestronConsole.PrintLine only, to avoid a NullReferenceException that would poison the Debug type.
         try
         {
-            var ipAddress = CrestronEthernetHelper.GetEthernetParameter(CrestronEthernetHelper.ETHERNET_PARAMETER_TO_GET.GET_CURRENT_IP_ADDRESS, 0);
-            var hostName = CrestronEthernetHelper.GetEthernetParameter(CrestronEthernetHelper.ETHERNET_PARAMETER_TO_GET.GET_HOSTNAME, 0);
-            var domainName = CrestronEthernetHelper.GetEthernetParameter(CrestronEthernetHelper.ETHERNET_PARAMETER_TO_GET.GET_DOMAIN_NAME, 0);
-
-            CrestronConsole.PrintLine(string.Format("CreateCert: DomainName: {0} | HostName: {1} | {1}.{0}@{2}", domainName, hostName, ipAddress));
+            // GetEthernetParameter returns the literal string "Invalid Value" rather than throwing when a
+            // parameter cannot be read, so every value has to be validated before it goes into the cert.
+            var ipAddress = ProcessorEthernetInfo.GetLanIpAddress();
+            var csIpAddress = ProcessorEthernetInfo.GetCsLanIpAddress();
+            var hostName = ProcessorEthernetInfo.GetParameter(CrestronEthernetHelper.ETHERNET_PARAMETER_TO_GET.GET_HOSTNAME, 0);
+            var domainName = ProcessorEthernetInfo.GetParameter(CrestronEthernetHelper.ETHERNET_PARAMETER_TO_GET.GET_DOMAIN_NAME, 0);
+
+            CrestronConsole.PrintLine(string.Format("CreateCert: DomainName: {0} | HostName: {1} | IP: {2} | CS IP: {3}",
+                domainName ?? "<none>", hostName ?? "<none>", ipAddress ?? "<none>", csIpAddress ?? "<none>"));
+
+            // Fall back to the IP address when there is no usable host name, so the subject is never
+            // built out of unreadable parameters.
+            var fqdn = hostName == null
+                ? ipAddress
+                : domainName == null ? hostName : string.Format("{0}.{1}", hostName, domainName);
+
+            if (string.IsNullOrEmpty(fqdn))
+            {
+                CrestronConsole.PrintLine("CreateCert: No usable host name or IP address; aborting certificate creation");
+                return;
+            }
 
-            var subjectName = string.Format("CN={0}.{1}", hostName, domainName);
-            var fqdn = string.Format("{0}.{1}", hostName, domainName);
+            var subjectName = string.Format("CN={0}", fqdn);
 
             using var rsa = RSA.Create(2048);
 
@@ -162,11 +209,15 @@ private static void CreateCert()
                     },
                     false));
 
-            // Subject Alternative Names: DNS + IP
+            // Subject Alternative Names: DNS + every address the browser could reach the processor on
             var sanBuilder = new SubjectAlternativeNameBuilder();
             sanBuilder.AddDnsName(fqdn);
+            if (hostName != null && hostName != fqdn)
+                sanBuilder.AddDnsName(hostName);
             if (System.Net.IPAddress.TryParse(ipAddress, out var ip))
                 sanBuilder.AddIpAddress(ip);
+            if (System.Net.IPAddress.TryParse(csIpAddress, out var csIp))
+                sanBuilder.AddIpAddress(csIp);
             request.CertificateExtensions.Add(sanBuilder.Build());
 
             var notBefore = DateTimeOffset.UtcNow;

src/PepperDash.Core/ProcessorEthernetInfo.cs

@@ -0,0 +1,113 @@
+using System;
+using Crestron.SimplSharp;
+
+namespace PepperDash.Core;
+
+/// <summary>
+/// Helpers for reading the processor's own network addresses.
+/// </summary>
+/// <remarks>
+/// <c>CrestronEthernetHelper.GetEthernetParameter</c> does not throw when it is asked for a parameter
+/// belonging to an adapter that the processor does not have — it returns the literal string
+/// <c>"Invalid Value"</c>. Callers that only null/empty-check the result end up building URLs such as
+/// <c>wss://Invalid Value:65479/debug/join</c>. These helpers return <c>null</c> in that case so callers
+/// can fall back cleanly.
+/// </remarks>
+public static class ProcessorEthernetInfo
+{
+    /// <summary>
+    /// The sentinel string the Crestron SDK returns for a parameter that cannot be read.
+    /// </summary>
+    public const string InvalidValue = "Invalid Value";
+
+    /// <summary>
+    /// Returns the supplied network parameter, or <c>null</c> when it is blank or the SDK's
+    /// <c>"Invalid Value"</c> sentinel.
+    /// </summary>
+    /// <param name="value">The raw value returned by <c>GetEthernetParameter</c>.</param>
+    /// <returns>The trimmed value, or <c>null</c> when it is not usable.</returns>
+    public static string NullIfInvalid(string value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+            return null;
+
+        var trimmed = value.Trim();
+
+        return trimmed.Equals(InvalidValue, StringComparison.OrdinalIgnoreCase) ? null : trimmed;
+    }
+
+    /// <summary>
+    /// Gets the current IP address of the processor's LAN adapter, or <c>null</c> when it cannot be read.
+    /// </summary>
+    /// <remarks>
+    /// Falls back to adapter id 0 on platforms (such as Virtual Control) where the adapter type lookup
+    /// is not supported.
+    /// </remarks>
+    public static string GetLanIpAddress() =>
+        GetIpAddressForAdapterType(EthernetAdapterType.EthernetLANAdapter) ?? GetIpAddressForAdapterId(0);
+
+    /// <summary>
+    /// Gets the current IP address of the processor's control subnet (CS LAN) adapter, or <c>null</c>
+    /// when the processor has no control subnet.
+    /// </summary>
+    public static string GetCsLanIpAddress() =>
+        GetIpAddressForAdapterType(EthernetAdapterType.EthernetCSAdapter);
+
+    /// <summary>
+    /// Gets the current IP address for the specified adapter type, or <c>null</c> when that adapter is
+    /// not present on this processor.
+    /// </summary>
+    /// <param name="adapterType">The adapter type to look up.</param>
+    public static string GetIpAddressForAdapterType(EthernetAdapterType adapterType)
+    {
+        try
+        {
+            var adapterId = CrestronEthernetHelper.GetAdapterdIdForSpecifiedAdapterType(adapterType);
+
+            return adapterId < 0 ? null : GetIpAddressForAdapterId(adapterId);
+        }
+        catch (ArgumentException)
+        {
+            // This processor does not have an adapter of the requested type.
+            return null;
+        }
+        catch (Exception)
+        {
+            return null;
+        }
+    }
+
+    /// <summary>
+    /// Gets the current IP address for the specified adapter id, or <c>null</c> when it cannot be read.
+    /// </summary>
+    /// <param name="adapterId">The Crestron ethernet adapter id.</param>
+    public static string GetIpAddressForAdapterId(short adapterId)
+    {
+        try
+        {
+            return NullIfInvalid(CrestronEthernetHelper.GetEthernetParameter(
+                CrestronEthernetHelper.ETHERNET_PARAMETER_TO_GET.GET_CURRENT_IP_ADDRESS, adapterId));
+        }
+        catch (Exception)
+        {
+            return null;
+        }
+    }
+
+    /// <summary>
+    /// Gets the specified parameter for the given adapter id, or <c>null</c> when it cannot be read.
+    /// </summary>
+    /// <param name="parameter">The parameter to read.</param>
+    /// <param name="adapterId">The Crestron ethernet adapter id.</param>
+    public static string GetParameter(CrestronEthernetHelper.ETHERNET_PARAMETER_TO_GET parameter, short adapterId)
+    {
+        try
+        {
+            return NullIfInvalid(CrestronEthernetHelper.GetEthernetParameter(parameter, adapterId));
+        }
+        catch (Exception)
+        {
+            return null;
+        }
+    }
+}