feat(installer): wire post-enroll tunnel verification and drop gateway-url override

After `agent.exe up` succeeds, the agent-tunnel installation now invokes
`agent.exe verify-tunnel --timeout 10` and only reports success if a real
QUIC handshake + RouteAdvertise/Heartbeat round-trip completes. The CA
parses the structured JSON triple from agent stderr and surfaces
`{kind, detail, next_step}` via `session.Message(InstallMessage.Error, ...)`
so installer failure dialogs contain an actionable next step instead of
"setup failed".

The 10s timeout is hardcoded by design (no MSI property, no escape
hatch); a few extra seconds of wall-clock budget guard against a
misbehaving process. MSI rollbacks engage on any non-zero exit.

Also drops the Gateway URL override field from the AgentTunnel dialog
(textbox, label, hint, RowCount/RowStyles, property declaration,
deferred-CA UsesProperties wiring, localization strings in en-us and
fr-fr). With the identity refactor the enrollment JWT is the single
source of truth for the agent-facing URL — overriding it server-side
would defeat the host validation against AdvertisedNames on the gateway.

Author: irvingoujAtDevolution

package/AgentWindowsManaged/Actions/AgentActions.cs

@@ -294,14 +294,39 @@ internal static class AgentActions
         UsesProperties = string.Join(";", new[]
         {
             AgentProperties.AgentTunnelEnrollmentString,
-            AgentProperties.AgentTunnelGatewayUrl,
             AgentProperties.AgentTunnelAgentName,
             AgentProperties.AgentTunnelAdvertiseSubnets,
             AgentProperties.AgentTunnelAdvertiseDomains,
             AgentProperties.InstallDir,
         }.Select(p => $"{p}=[{p}]")),
     };
 
+    /// <summary>
+    /// After `up` returns success, run `agent.exe verify-tunnel` with a hardcoded 10s timeout
+    /// to confirm the tunnel is actually reachable.
+    /// </summary>
+    /// <remarks>
+    /// Per the identity refactor, the installer's "success" means "the tunnel is up", not just
+    /// "a cert was written to disk". The CA parses the agent's structured JSON triple from
+    /// stderr and surfaces it through `session.Message(InstallMessage.Error, ...)` so the
+    /// dialog box contains an actionable `next_step` for the operator.
+    /// </remarks>
+    private static readonly ElevatedManagedAction verifyAgentTunnel = new(
+        new Id($"CA.{nameof(verifyAgentTunnel)}"),
+        CustomActions.VerifyAgentTunnel,
+        Return.check,
+        When.After, new Step(enrollAgentTunnel.Id),
+        Features.AGENT_TUNNEL_FEATURE.BeingInstall(),
+        Sequence.InstallExecuteSequence)
+    {
+        Execute = Execute.deferred,
+        Impersonate = false,
+        UsesProperties = string.Join(";", new[]
+        {
+            AgentProperties.InstallDir,
+        }.Select(p => $"{p}=[{p}]")),
+    };
+
     private static readonly ElevatedManagedAction registerExplorerCommand = new(
         CustomActions.RegisterExplorerCommand
     )
@@ -376,6 +401,7 @@ private static string UseProperties(IEnumerable<IWixProperty> properties)
         setFeaturesToConfigure,
         configureFeatures,
         enrollAgentTunnel,
+        verifyAgentTunnel,
         createProgramDataDirectory,
         setProgramDataDirectoryPermissions,
         createProgramDataPedmDirectories,

package/AgentWindowsManaged/Actions/CustomActions.cs

@@ -325,7 +325,6 @@ public static ActionResult EnrollAgentTunnel(Session session)
             string enrollmentString = session.Property(AgentProperties.AgentTunnelEnrollmentString)?.Trim() ?? string.Empty;
             string subnetsArg = session.Property(AgentProperties.AgentTunnelAdvertiseSubnets)?.Trim() ?? string.Empty;
             string domainsArg = session.Property(AgentProperties.AgentTunnelAdvertiseDomains)?.Trim() ?? string.Empty;
-            string gatewayUrlArg = session.Property(AgentProperties.AgentTunnelGatewayUrl)?.Trim() ?? string.Empty;
             string agentNameArg = session.Property(AgentProperties.AgentTunnelAgentName)?.Trim() ?? string.Empty;
 
             ActionResult Fail(string msg)
@@ -361,7 +360,6 @@ ActionResult Fail(string msg)
                 }
 
                 string arguments = $"up --enrollment-string \"{enrollmentString}\"";
-                if (gatewayUrlArg.Length != 0) arguments += $" --gateway \"{gatewayUrlArg}\"";
                 if (resolvedName.Length != 0) arguments += $" --name \"{resolvedName}\"";
                 if (subnetsArg.Length != 0) arguments += $" --advertise-subnets \"{subnetsArg}\"";
 
@@ -472,6 +470,117 @@ private static void WriteAdvertiseDomainsToConfig(Session session, string domain
             }
         }
 
+        /// <summary>
+        /// After `EnrollAgentTunnel` succeeds, exercises one real QUIC handshake +
+        /// `RouteAdvertise`/`Heartbeat` round-trip via `agent.exe verify-tunnel` so the
+        /// installer only reports success when the tunnel is actually reachable.
+        ///
+        /// The agent emits a single-line JSON triple `{kind, detail, next_step}` on stderr
+        /// when verification fails. The CA parses that triple, logs it, and surfaces
+        /// `next_step` (the operator-facing help text) through `session.Message(InstallMessage.Error, ...)`.
+        /// If the agent exits with a non-zero status but stderr contains no parseable triple,
+        /// the CA falls back to a generic "unexpected_error" message — it never silently
+        /// swallows a failure.
+        /// </summary>
+        [CustomAction]
+        public static ActionResult VerifyAgentTunnel(Session session)
+        {
+            ActionResult Fail(string title, string detail, string nextStep)
+            {
+                string composed = string.IsNullOrEmpty(nextStep)
+                    ? $"{title}\n\n{detail}"
+                    : $"{title}\n\n{detail}\n\n{nextStep}";
+                session.Log($"verify-tunnel failure: kind={title}; detail={detail}; next_step={nextStep}");
+                using Record record = new(0) { FormatString = composed };
+                session.Message(InstallMessage.Error, record);
+                return ActionResult.Failure;
+            }
+
+            try
+            {
+                string installDir = session.Property(AgentProperties.InstallDir);
+                string exePath = Path.Combine(installDir, Includes.EXECUTABLE_NAME);
+
+                // The 10s budget is hardcoded by design: no MSI property, no escape hatch.
+                // If real deployments later need a longer budget for slow customer networks,
+                // expose a property then — not pre-emptively.
+                const int VerifyTimeoutSeconds = 10;
+                string arguments = $"verify-tunnel --timeout {VerifyTimeoutSeconds}";
+
+                session.Log($"Running verify-tunnel: {exePath} {arguments}");
+
+                ProcessStartInfo startInfo = new(exePath, arguments)
+                {
+                    UseShellExecute = false,
+                    RedirectStandardOutput = true,
+                    RedirectStandardError = true,
+                    CreateNoWindow = true,
+                    WorkingDirectory = ProgramDataDirectory,
+                };
+
+                using Process process = Process.Start(startInfo);
+                // Hard wall-clock cap a few seconds beyond the agent's own --timeout so a
+                // misbehaving process can't hang the installer.
+                if (!process.WaitForExit((VerifyTimeoutSeconds + 5) * 1000))
+                {
+                    try { process.Kill(); } catch { /* already gone */ }
+                    return Fail(
+                        "quic_handshake_timeout",
+                        $"verify-tunnel exceeded {VerifyTimeoutSeconds + 5}s wall-clock budget without exiting.",
+                        "Re-run the installer. If the failure repeats, network path likely drops UDP mid-flow; check Windows Firewall, NAT, and EDR network inspection.");
+                }
+
+                string stdout = process.StandardOutput.ReadToEnd();
+                string stderr = process.StandardError.ReadToEnd();
+
+                if (!string.IsNullOrEmpty(stdout)) session.Log($"verify-tunnel stdout: {stdout}");
+                if (!string.IsNullOrEmpty(stderr)) session.Log($"verify-tunnel stderr: {stderr}");
+
+                if (process.ExitCode == 0)
+                {
+                    session.Log("Agent tunnel verification succeeded");
+                    return ActionResult.Success;
+                }
+
+                // Failure path: parse the last non-blank stderr line as the JSON triple.
+                string triple = (stderr ?? string.Empty)
+                    .Split(new[] { '\r', '\n' }, StringSplitOptions.RemoveEmptyEntries)
+                    .Reverse()
+                    .FirstOrDefault(l => l.TrimStart().StartsWith("{"));
+
+                if (string.IsNullOrEmpty(triple))
+                {
+                    return Fail(
+                        "unexpected_error",
+                        $"verify-tunnel exited with code {process.ExitCode} but emitted no parseable JSON triple on stderr.",
+                        "Collect the agent log and the installer log (.msi /l*v) and file a support issue.");
+                }
+
+                try
+                {
+                    JObject parsed = JObject.Parse(triple);
+                    string kind = parsed.Value<string>("kind") ?? "unexpected_error";
+                    string detail = parsed.Value<string>("detail") ?? string.Empty;
+                    string nextStep = parsed.Value<string>("next_step") ?? string.Empty;
+                    return Fail(kind, detail, nextStep);
+                }
+                catch (Exception e)
+                {
+                    return Fail(
+                        "unexpected_error",
+                        $"verify-tunnel emitted unparseable stderr ({e.Message}). Raw: {triple}",
+                        "Collect the agent log and the installer log (.msi /l*v) and file a support issue.");
+                }
+            }
+            catch (Exception e)
+            {
+                return Fail(
+                    "unexpected_error",
+                    $"Failed to invoke verify-tunnel: {e.Message}",
+                    "Collect the agent log and the installer log (.msi /l*v) and file a support issue.");
+            }
+        }
+
         [CustomAction]
         public static ActionResult ConfigureFeatures(Session session)
         {

package/AgentWindowsManaged/Dialogs/AgentTunnelDialog.Designer.cs

@@ -21,11 +21,14 @@ public AgentTunnelDialog()
 
     public override bool ToProperties()
     {
+        // The Gateway URL override field was removed in the identity refactor: the JWT
+        // is now the single source of truth for the agent-facing URL. Overriding it
+        // server-side would defeat the whole point of validating that the agent reached
+        // the gateway through one of `AgentTunnel.AdvertisedNames`.
         Runtime.Session[AgentProperties.AgentTunnelEnrollmentString] = enrollmentString.Text.Trim();
         Runtime.Session[AgentProperties.AgentTunnelAgentName] = agentName.Text.Trim();
         Runtime.Session[AgentProperties.AgentTunnelAdvertiseSubnets] = advertiseSubnets.Text.Trim();
         Runtime.Session[AgentProperties.AgentTunnelAdvertiseDomains] = advertiseDomains.Text.Trim();
-        Runtime.Session[AgentProperties.AgentTunnelGatewayUrl] = gatewayUrl.Text.Trim();
 
         return true;
     }
@@ -38,7 +41,6 @@ public override void OnLoad(object sender, EventArgs e)
         agentName.Text = Runtime.Session.Property(AgentProperties.AgentTunnelAgentName);
         advertiseSubnets.Text = Runtime.Session.Property(AgentProperties.AgentTunnelAdvertiseSubnets);
         advertiseDomains.Text = Runtime.Session.Property(AgentProperties.AgentTunnelAdvertiseDomains);
-        gatewayUrl.Text = Runtime.Session.Property(AgentProperties.AgentTunnelGatewayUrl);
 
         base.OnLoad(sender, e);
     }

package/AgentWindowsManaged/Dialogs/AgentTunnelDialog.cs

@@ -352,7 +352,6 @@ static void Main()
         // Agent tunnel properties: must be declared Secure so the values set in the wizard UI
         // survive the UAC boundary and reach the deferred CA via CustomActionData.
         projectProperties.Add(new Property(AgentProperties.AgentTunnelEnrollmentString, "") { Hidden = true, Secure = true });
-        projectProperties.Add(new Property(AgentProperties.AgentTunnelGatewayUrl, "") { Secure = true });
         projectProperties.Add(new Property(AgentProperties.AgentTunnelAgentName, "") { Secure = true });
         projectProperties.Add(new Property(AgentProperties.AgentTunnelAdvertiseSubnets, "") { Secure = true });
         projectProperties.Add(new Property(AgentProperties.AgentTunnelAdvertiseDomains, "") { Secure = true });

package/AgentWindowsManaged/Program.cs

@@ -31,13 +31,6 @@ internal partial class AgentProperties
         /// </summary>
         public static string AgentTunnelAdvertiseDomains = "AGENT_TUNNEL_ADVERTISE_DOMAINS";
 
-        /// <summary>
-        /// Optional gateway URL override. When set, the agent uses this URL instead of the JWT's
-        /// jet_gw_url claim. Useful when the JWT was minted with a URL that isn't reachable from
-        /// the agent's network (e.g. DVLS embedded "localhost" but the agent is remote).
-        /// </summary>
-        public static string AgentTunnelGatewayUrl = "AGENT_TUNNEL_GATEWAY_URL";
-
         /// <summary>
         /// Optional agent display name. Resolution order at install time:
         /// dialog value (if non-empty) > JWT's jet_agent_name claim (if present) > local computer name.

package/AgentWindowsManaged/Properties/AgentProperties.cs

@@ -69,6 +69,4 @@ If it appears minimized then active it from the taskbar.</String>
                 <String Id="AgentTunnelDlgDomainsHint">Comma-separated DNS suffixes the agent can resolve, e.g. corp.example.com, lab.example.com. Leave blank to skip.</String>
                 <String Id="AgentTunnelDlgAgentNameLabel">Agent name (optional):</String>
                 <String Id="AgentTunnelDlgAgentNameHint">Identifier for this agent. Leave blank to use the name in the JWT, or the local computer name as a final fallback.</String>
-                <String Id="AgentTunnelDlgGatewayUrlLabel">Gateway URL (advanced, optional):</String>
-                <String Id="AgentTunnelDlgGatewayUrlHint">Override the URL embedded in the enrollment JWT. Leave blank to use the JWT's value.</String>
                     </WixLocalization>

package/AgentWindowsManaged/Resources/DevolutionsAgent_en-us.wxl

@@ -14,8 +14,6 @@
                 <String Id="AgentTunnelDlgDomainsHint">Suffixes DNS séparés par des virgules que l'agent peut résoudre, p. ex. corp.example.com, lab.example.com. Laissez vide pour ignorer.</String>
                 <String Id="AgentTunnelDlgAgentNameLabel">Nom de l'agent (facultatif) :</String>
                 <String Id="AgentTunnelDlgAgentNameHint">Identifiant de cet agent. Laissez vide pour utiliser le nom inscrit dans le JWT, ou le nom de l'ordinateur local comme dernier recours.</String>
-                <String Id="AgentTunnelDlgGatewayUrlLabel">URL de la passerelle (avancé, facultatif) :</String>
-                <String Id="AgentTunnelDlgGatewayUrlHint">Remplace l'URL incluse dans le JWT d'enrôlement. Laissez vide pour utiliser la valeur du JWT.</String>
                 <String Id="Language">1036</String>
                 <String Id="ProductDescription">Service à l’échelle du système pour étendre les fonctionnalités de Devolutions Gateway.</String>
                 <String Id="VendorFullName">Devolutions Inc.</String>