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/Platform/SingleInstance.cs

@@ -34,6 +34,12 @@ namespace DodoSSH.Client.App.Platform;
 /// process asks the first to come forward and then leaves, which is what every desktop application does and
 /// what makes the exclusion invisible rather than mysterious.
 /// </para>
+/// <para>
+/// <b>A launch that carries a link passes the link on.</b> Clicking "Open in DodoSSH" in Spelunk starts
+/// this executable with a <c>dodossh://</c> link, and while DodoSSH is already running that start is a
+/// second launch like any other — so the doorbell has a second message, which carries the link to the
+/// instance that can act on it. See <see cref="OpenLinkPrefix"/>.
+/// </para>
 /// </remarks>
 internal static class SingleInstance
 {
@@ -46,6 +52,30 @@ internal static class SingleInstance
     /// </remarks>
     private const string ComeForward = "dodossh.come-forward";
 
+    /// <summary>The other thing a second launch may say: come forward, and open this link.</summary>
+    /// <remarks>
+    /// <para>
+    /// Followed by the link, on the same one line. Checked as strictly as <see cref="ComeForward"/> is, and
+    /// for the same reason: anything on this machine may write to the pipe, so the link is parsed again here
+    /// by <see cref="SpelunkLink.TryParse"/>, and a message that is not exactly this prefix and a link that
+    /// passes is ignored whole — the window does not even come forward for it.
+    /// </para>
+    /// <para>
+    /// A second message rather than a second line after <see cref="ComeForward"/>, so that an older running
+    /// build, which compares the whole line against that constant, ignores a link it cannot act on rather
+    /// than half-obeying it.
+    /// </para>
+    /// </remarks>
+    private const string OpenLinkPrefix = "dodossh.open-link ";
+
+    /// <summary>The longest message the doorbell reads before it stops listening to that caller.</summary>
+    /// <remarks>
+    /// The longest link a second launch could send, and its prefix. A caller that goes on past it is not a
+    /// DodoSSH, and reading a line of whatever length it likes would let it decide how much memory this
+    /// process spends on it.
+    /// </remarks>
+    private const int MaxMessageLength = 64 + SpelunkLink.MaxLength;
+
     /// <summary>How long a second launch waits for the first to answer its pipe.</summary>
     /// <remarks>
     /// Short, because the pipe is local and the process on the other end is either listening or not. It is
@@ -86,7 +116,11 @@ internal static class SingleInstance
     /// How long to keep trying a lock nobody answers for, or null for <see cref="DefaultPatience"/>. Named
     /// by a test so the give-up path does not cost the suite three seconds; the application never passes it.
     /// </param>
-    internal static IDisposable? Claim(ClientPaths paths, TimeSpan? patience = null)
+    /// <param name="link">
+    /// The link this launch was started with, if any — passed to the running instance instead of a bare
+    /// request to come forward.
+    /// </param>
+    internal static IDisposable? Claim(ClientPaths paths, TimeSpan? patience = null, SpelunkLink? link = null)
     {
         ArgumentNullException.ThrowIfNull(paths);
 
@@ -116,7 +150,7 @@ internal static class SingleInstance
 
             // Asked before waiting, so the ordinary case — an instance that is up and running — costs one
             // round trip on a local pipe rather than the whole window below.
-            if (AskTheRunningOneToComeForward(paths))
+            if (AskTheRunningOneToComeForward(paths, link))
             {
                 return null;
             }
@@ -142,25 +176,32 @@ internal static class SingleInstance
     /// </remarks>
     /// <param name="paths">The profile this instance claimed.</param>
     /// <param name="comeForward">What to do when another launch asks for the window.</param>
-    internal static IAsyncDisposable Listen(ClientPaths paths, Action comeForward)
+    /// <param name="openLink">
+    /// What to do with a link another launch passed on, after <paramref name="comeForward"/>; null to ignore
+    /// links, which then still bring the window forward. Invoked on the same thread pool thread.
+    /// </param>
+    internal static IAsyncDisposable Listen(
+        ClientPaths paths,
+        Action comeForward,
+        Action<SpelunkLink>? openLink = null)
     {
         ArgumentNullException.ThrowIfNull(paths);
         ArgumentNullException.ThrowIfNull(comeForward);
 
-        var listener = new Doorbell(PipeNameFor(paths), comeForward);
+        var listener = new Doorbell(PipeNameFor(paths), comeForward, openLink);
 
         listener.Start();
 
         return listener;
     }
 
-    /// <summary>Tells the instance that holds this profile to raise its window.</summary>
+    /// <summary>Tells the instance that holds this profile to raise its window, and to open a link if given one.</summary>
     /// <returns>Whether anything was listening.</returns>
     /// <remarks>
     /// Internal rather than private because it is the half a test can drive: the exclusion is a file handle
     /// and proves itself, and this is the part with a protocol in it.
     /// </remarks>
-    internal static bool AskTheRunningOneToComeForward(ClientPaths paths)
+    internal static bool AskTheRunningOneToComeForward(ClientPaths paths, SpelunkLink? link = null)
     {
         ArgumentNullException.ThrowIfNull(paths);
 
@@ -175,7 +216,9 @@ internal static class SingleInstance
 
             using var writer = new StreamWriter(pipe, Encoding.UTF8) { AutoFlush = true };
 
-            writer.WriteLine(ComeForward);
+            // The link as this build writes it, rather than as it arrived: the receiver parses what a DodoSSH
+            // sent, and a link that parsed here has exactly one spelling. See SpelunkLink.ToString.
+            writer.WriteLine(Message(link));
 
             return true;
         }
@@ -188,6 +231,42 @@ internal static class SingleInstance
         }
     }
 
+    /// <summary>What a launch says down the pipe: come forward, with or without a link to open.</summary>
+    internal static string Message(SpelunkLink? link) =>
+        link is null ? ComeForward : OpenLinkPrefix + link;
+
+    /// <summary>
+    /// Reads what a caller said: whether it is a ring at all, and the link that came with it.
+    /// </summary>
+    /// <returns>
+    /// True for exactly <see cref="ComeForward"/>, with no link, and for <see cref="OpenLinkPrefix"/> followed
+    /// by a link <see cref="SpelunkLink.TryParse"/> accepts, with that link. False for everything else,
+    /// including a link that is almost right — the caller then does nothing at all.
+    /// </returns>
+    internal static bool TryRead(string? said, out SpelunkLink? link)
+    {
+        link = null;
+
+        if (said is null || said.Length > MaxMessageLength)
+        {
+            return false;
+        }
+
+        if (string.Equals(said, ComeForward, StringComparison.Ordinal))
+        {
+            return true;
+        }
+
+        if (said.StartsWith(OpenLinkPrefix, StringComparison.Ordinal)
+            && SpelunkLink.TryParse(said[OpenLinkPrefix.Length..], out var parsed))
+        {
+            link = parsed;
+            return true;
+        }
+
+        return false;
+    }
+
     /// <summary>Takes the lock, or answers null if somebody else has it.</summary>
     /// <remarks>
     /// The file is left in place rather than deleted on close. <c>FileOptions.DeleteOnClose</c> looks
@@ -278,14 +357,16 @@ internal static class SingleInstance
     {
         private readonly string name;
         private readonly Action comeForward;
+        private readonly Action<SpelunkLink>? openLink;
         private readonly CancellationTokenSource lifetime = new();
 
         private Task? loop;
 
-        internal Doorbell(string name, Action comeForward)
+        internal Doorbell(string name, Action comeForward, Action<SpelunkLink>? openLink)
         {
             this.name = name;
             this.comeForward = comeForward;
+            this.openLink = openLink;
         }
 
         internal void Start() => loop = RunAsync(lifetime.Token);
@@ -324,11 +405,16 @@ internal static class SingleInstance
                     // leaveOpen, because this server outlives the conversation. See the remark above.
                     using (var reader = new StreamReader(server, Encoding.UTF8, false, 1024, leaveOpen: true))
                     {
-                        var said = await reader.ReadLineAsync(cancellationToken).ConfigureAwait(false);
+                        var said = await ReadBoundedLineAsync(reader, cancellationToken).ConfigureAwait(false);
 
-                        if (string.Equals(said, ComeForward, StringComparison.Ordinal))
+                        if (TryRead(said, out var link))
                         {
                             comeForward();
+
+                            if (link is not null)
+                            {
+                                openLink?.Invoke(link);
+                            }
                         }
                     }
 
@@ -348,6 +434,39 @@ internal static class SingleInstance
             }
         }
 
+        /// <summary>
+        /// Reads one line, or null once it runs past <see cref="MaxMessageLength"/> or the caller hangs up.
+        /// </summary>
+        /// <remarks>
+        /// <see cref="StreamReader.ReadLineAsync(CancellationToken)"/> reads a line of whatever length the
+        /// caller sends, and the caller is anybody on this machine. A character at a time is cheap here — the
+        /// reader buffers underneath, and a real message is one short line.
+        /// </remarks>
+        private static async Task<string?> ReadBoundedLineAsync(
+            StreamReader reader,
+            CancellationToken cancellationToken)
+        {
+            var line = new StringBuilder();
+            var next = new char[1];
+
+            while (await reader.ReadAsync(next.AsMemory(), cancellationToken).ConfigureAwait(false) == 1)
+            {
+                if (next[0] == '\n')
+                {
+                    return line.ToString().TrimEnd('\r');
+                }
+
+                if (line.Length == MaxMessageLength)
+                {
+                    return null;
+                }
+
+                line.Append(next[0]);
+            }
+
+            return line.Length == 0 ? null : line.ToString().TrimEnd('\r');
+        }
+
         /// <summary>Ends one conversation without ending the doorbell.</summary>
         /// <remarks>
         /// Guarded, because <c>Disconnect</c> throws on a server that is not connected — which is the state

src/DodoSSH.Client.App/Platform/WindowsUrlScheme.cs

@@ -0,0 +1,82 @@
+using System.Runtime.Versioning;
+using DodoSSH.Client.Session;
+using Microsoft.Win32;
+
+namespace DodoSSH.Client.App.Platform;
+
+/// <summary>
+/// Registers this executable as the handler for <c>dodossh://</c> links, for this user, on Windows.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Under HKCU\Software\Classes, because the install is per user.</b> Velopack installs into the user's
+/// own profile with no elevation, and a handler registered machine-wide would need the elevation the
+/// installer deliberately never asks for. Windows merges this key into <c>HKEY_CLASSES_ROOT</c> for the
+/// user, which is all a browser consults.
+/// </para>
+/// <para>
+/// <b>Written by Velopack's install and update hooks, removed by its uninstall hook</b> — see
+/// <c>Program.Main</c>. An update rewrites it because the first update to a build that has this is how an
+/// existing installation gets it at all, and because it costs nothing to say again.
+/// </para>
+/// <para>
+/// <b>Removed only when it is still ours.</b> The release and the nightly are separate installations that
+/// both answer <c>dodossh://</c>, and the last one installed holds the key. Uninstalling the other must not
+/// take the handler away from the one that is still there.
+/// </para>
+/// </remarks>
+[SupportedOSPlatform("windows")]
+internal static class WindowsUrlScheme
+{
+    private const string KeyPath = @"Software\Classes\" + SpelunkLink.Scheme;
+    private const string CommandPath = @"shell\open\command";
+
+    /// <summary>Points <c>dodossh://</c> at <paramref name="executable"/>.</summary>
+    internal static void Register(string executable)
+    {
+        using var scheme = Registry.CurrentUser.CreateSubKey(KeyPath);
+
+        scheme.SetValue(string.Empty, "URL:DodoSSH");
+
+        // Empty, and its presence is the whole of it: this value is what makes the key a URL scheme rather
+        // than a file type.
+        scheme.SetValue("URL Protocol", string.Empty);
+
+        using (var icon = scheme.CreateSubKey("DefaultIcon"))
+        {
+            icon.SetValue(string.Empty, $"\"{executable}\",0");
+        }
+
+        using var command = scheme.CreateSubKey(CommandPath);
+
+        command.SetValue(string.Empty, CommandFor(executable));
+    }
+
+    /// <summary>Takes the handler away, if it is still <paramref name="executable"/>'s.</summary>
+    internal static void Unregister(string executable)
+    {
+        string? registered;
+
+        using (var command = Registry.CurrentUser.OpenSubKey($@"{KeyPath}\{CommandPath}"))
+        {
+            registered = command?.GetValue(string.Empty) as string;
+        }
+
+        if (IsOurs(registered, executable))
+        {
+            Registry.CurrentUser.DeleteSubKeyTree(KeyPath, throwOnMissingSubKey: false);
+        }
+    }
+
+    /// <summary>The command Windows runs for a link: this executable, with the link as its one argument.</summary>
+    /// <remarks>
+    /// Both halves quoted. The path has spaces in it on any profile whose user name does, and the link is
+    /// handed over whole as <c>%1</c> — which Windows quotes into one argument only because it is quoted
+    /// here. Program.Main then reads it back and checks it before anything acts on it.
+    /// </remarks>
+    internal static string CommandFor(string executable) => $"\"{executable}\" \"%1\"";
+
+    /// <summary>Whether a registered command is the one <see cref="Register"/> writes for this executable.</summary>
+    internal static bool IsOurs(string? registered, string executable) =>
+        string.Equals(registered, CommandFor(executable), StringComparison.OrdinalIgnoreCase);
+}