Reach a Spelunk-managed server through Spelunk, and open one from a Spelunk link

A server Spelunk manages runs Spelunk's agent, which keeps a connection open
to Spelunk. A host can now be marked "Connect through Spelunk": a connect
asks Spelunk for a ticket, opens a WebSocket, and the agent connects to the
SSH server on the machine's own loopback, so the server needs no open SSH
port. Shells and file transfers both go this way.

Client, in Client.Session:

- SpelunkTunnel implements Spelunk's contract: POST
  {api}/api/servers/{id}/tunnel-tickets with the API key as a bearer token
  and {"port":N}, then a WebSocket to the API's own origin at the path
  Spelunk returns, offering spelunk.tunnel.v1 and ticket.<ticket>. After the
  upgrade the relay's RelayBridge carries the bytes unchanged. Every refusal
  is a sentence: 401 key, 403 role (with Spelunk's detail), 404 server, 503
  agent not connected, 401/503 on the upgrade, and close codes 4502 (agent
  could not reach the port, or is too old: "Unknown stream kind") and 4503
  (agent disconnected). Only a path is taken from the ticket response, so it
  cannot send the ticket to another host.
- IConnectionRoute is what RelayRoute and SpelunkTunnelRoute have in common,
  so the connect path has one shape for both.

Host model: HostSecret.Spelunk is a SpelunkRoute (normalised API base,
server id, and the id of the credential holding the API key), at payload
schema version 8. It is written last and only when present, so every other
host keeps its bytes and its version; an older build reads a Spelunk host
as read-only rather than dropping the route. A half-written route makes the
item unreadable instead of dialled. It merges as one value and is exclusive
with RelayEnabled. The API address must be https, or http to loopback.

The API key is an ordinary keychain credential whose password is the key,
referenced by id, so it is encrypted, synced, merged and rotated like every
other secret, one credential serves every server in the organisation, and
the used-by list and deletion warning count it.

Routing: OpenRouteAsync is the one decision for both transports. A Spelunk
host is never dialled directly, never probed after a failure, and a route
that hung up with a reason replaces SSH.NET's transport error.

UI: a "Connect through Spelunk" card beside the relay card in the desktop
drawer and the phone's editor; ticking one unticks the other.

dodossh://spelunk/connect?api=&server=&name=&host= links:

- SpelunkLink parses them strictly and never reads a credential from one.
- Program reads a link from the arguments; a launch that finds DodoSSH
  running passes it down the doorbell as "dodossh.open-link <link>", which
  the running instance parses again, bounded, and otherwise ignores whole.
  The plain come-forward ring is unchanged.
- A saved host routed to that server on that Spelunk is connected to;
  otherwise the editor opens on a new, unsaved Spelunk host, with the key
  pre-chosen only when another host already sends it to that Spelunk. A link
  that arrives while locked waits for the unlock.
- Windows registers the scheme under HKCU from Velopack's install and update
  hooks and removes it on uninstall only if it still points at this
  executable; the macOS plist template declares CFBundleURLTypes and the app
  takes the URL from Avalonia's activation event; the Linux desktop entry
  gets %u and MimeType=x-scheme-handler/dodossh.

src/DodoSSH.Client.App/Program.cs

@@ -8,6 +8,16 @@ namespace DodoSSH.Client.App;
 
 internal static class Program
 {
+    /// <summary>
+    /// The <c>dodossh://</c> link this process was started with, once it has claimed the profile; null for an
+    /// ordinary launch.
+    /// </summary>
+    /// <remarks>
+    /// A static handed across to <c>DodoSshApp</c> rather than a constructor argument, because Avalonia
+    /// constructs the application itself — and the designer does too, through <see cref="BuildAvaloniaApp"/>,
+    /// with no arguments to have.
+    /// </remarks>
+    internal static SpelunkLink? LaunchLink { get; private set; }
     /// <summary>
     /// Entry point.
     /// </summary>
@@ -29,11 +39,12 @@ internal static class Program
         // and a silent installer run that reached either would be a background process holding the cache
         // file open during the very file operations the installer is performing.
         //
-        // There are deliberately no OnFirstRun or OnAfterUpdate hooks. A hook process has no passphrase,
-        // so the cache is bytes it cannot read, and the one thing that would want doing after an update —
-        // a schema migration — already runs on every ordinary launch from MainWindowViewModel.StartAsync,
-        // before unlock and touching no encrypted content.
-        VelopackApp.Build().Run();
+        // There are deliberately no OnFirstRun or OnAfterUpdate hooks that touch the profile. A hook process
+        // has no passphrase, so the cache is bytes it cannot read, and the one thing that would want doing
+        // after an update — a schema migration — already runs on every ordinary launch from
+        // MainWindowViewModel.StartAsync, before unlock and touching no encrypted content. The hooks it does
+        // have touch only the registry; see RunVelopack.
+        RunVelopack();
 
         KeepTheWebViewProfileOutOfTheInstallDirectory();
 
@@ -51,16 +62,100 @@ internal static class Program
         */
         var paths = ClientPaths.ForChannel(DesktopChannel.Name);
 
-        using var claim = SingleInstance.Claim(paths);
+        // Read before the claim, because a launch that carries a link and finds DodoSSH already running
+        // passes the link on rather than merely asking for the window.
+        var link = LinkFrom(args);
+
+        using var claim = SingleInstance.Claim(paths, link: link);
 
         if (claim is null)
         {
             return;
         }
 
+        LaunchLink = link;
+
         BuildAvaloniaApp().StartWithClassicDesktopLifetime(args);
     }
 
+    /// <summary>Lets Velopack do its install bookkeeping, with this application's three hooks.</summary>
+    /// <remarks>
+    /// The hooks touch only the registry: they make this executable the handler for <c>dodossh://</c> links,
+    /// which is how Spelunk's "Open in DodoSSH" reaches it, and take that away again on uninstall. Velopack
+    /// runs them on Windows only, and offers them only there; the other desktops declare the scheme in their
+    /// packages instead — build/macos's Info.plist template and build/linux's desktop entry. See
+    /// <see cref="WindowsUrlScheme"/>.
+    /// </remarks>
+    private static void RunVelopack()
+    {
+        var velopack = VelopackApp.Build();
+
+        if (OperatingSystem.IsWindows())
+        {
+            velopack = velopack
+                .OnAfterInstallFastCallback(_ => RegisterUrlScheme())
+                .OnAfterUpdateFastCallback(_ => RegisterUrlScheme())
+                .OnBeforeUninstallFastCallback(_ => UnregisterUrlScheme());
+        }
+
+        velopack.Run();
+    }
+
+    /// <summary>
+    /// The <c>dodossh://</c> link among this launch's arguments, if there is one and it passes the checks.
+    /// </summary>
+    /// <remarks>
+    /// A link that fails them is dropped and the launch goes ahead as an ordinary one: the user clicked
+    /// something that meant "open DodoSSH", and a window is still the right answer to that even when what
+    /// came with it cannot be trusted. See <see cref="SpelunkLink.TryParse"/> for what is checked.
+    /// </remarks>
+    private static SpelunkLink? LinkFrom(string[] args) =>
+        args.FirstOrDefault(SpelunkLink.LooksLikeOne) is { } candidate
+            && SpelunkLink.TryParse(candidate, out var link)
+                ? link
+                : null;
+
+    /// <summary>Makes this executable the handler for <c>dodossh://</c> links, where that is a registry key.</summary>
+    /// <remarks>
+    /// Failures are swallowed. This runs inside Velopack's install, and an installer that failed because a
+    /// convenience could not be set up would be the wrong trade — the application works without it, and the
+    /// only thing lost is Spelunk's button opening it.
+    /// </remarks>
+    private static void RegisterUrlScheme()
+    {
+        if (!OperatingSystem.IsWindows() || Environment.ProcessPath is not { } executable)
+        {
+            return;
+        }
+
+        try
+        {
+            WindowsUrlScheme.Register(executable);
+        }
+        catch (Exception exception) when (exception is IOException or UnauthorizedAccessException or System.Security.SecurityException)
+        {
+            // See the remarks.
+        }
+    }
+
+    /// <inheritdoc cref="RegisterUrlScheme" path="/remarks" />
+    private static void UnregisterUrlScheme()
+    {
+        if (!OperatingSystem.IsWindows() || Environment.ProcessPath is not { } executable)
+        {
+            return;
+        }
+
+        try
+        {
+            WindowsUrlScheme.Unregister(executable);
+        }
+        catch (Exception exception) when (exception is IOException or UnauthorizedAccessException or System.Security.SecurityException)
+        {
+            // See the remarks on RegisterUrlScheme.
+        }
+    }
+
     /// <summary>
     /// Puts WebView2's user data folder beside the vault cache instead of beside the executable.
     /// </summary>