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.Shell/ViewModels/VaultViewModel.cs

@@ -1469,7 +1469,8 @@ internal sealed partial class VaultViewModel(
     Func<string, Task>? copyToClipboard = null,
     ConnectionRecorder? connectionLog = null,
     VaultVisibility? visibility = null,
-    ISshReachabilityProbe? reachability = null) : ObservableObject, IAsyncDisposable
+    ISshReachabilityProbe? reachability = null,
+    ISpelunkTunnel? spelunk = null) : ObservableObject, IAsyncDisposable
 {
     /// <summary>What explains a failed connection when no caller supplied something else.</summary>
     /// <remarks>
@@ -4385,6 +4386,7 @@ internal sealed partial class VaultViewModel(
             // longer say what the user chose.
             var authentication = EditorSelectedAuthentication;
             var groupId = EditorSelectedGroup?.EntityId;
+            var spelunkKeyId = EditorSelectedSpelunkKey?.EntityId;
 
             BuildTagChoices();
 
@@ -4403,6 +4405,8 @@ internal sealed partial class VaultViewModel(
                 authentication?.Kind == AuthenticationKind.Credential ? authentication.EntityId : null,
                 asksForPassword: authentication?.Kind == AuthenticationKind.Typed,
                 grouped: EditorSelectedGroup?.EntityId is not null);
+
+            BuildSpelunkKeyChoices(spelunkKeyId);
         }
 
         if (IsEditingGroup)
@@ -7542,6 +7546,7 @@ internal sealed partial class VaultViewModel(
         EditorUsername = string.Empty;
         EditorNotes = string.Empty;
         EditorRelayEnabled = false;
+        LoadEditorSpelunk(route: null);
         editorTagIds = TagSet.Empty;
         EditorNewTag = string.Empty;
         BuildTagChoices();
@@ -7632,6 +7637,7 @@ internal sealed partial class VaultViewModel(
         EditorUsername = row.Host.Username ?? string.Empty;
         EditorNotes = row.Host.Notes ?? string.Empty;
         EditorRelayEnabled = row.Host.RelayEnabled;
+        LoadEditorSpelunk(row.Host.Spelunk);
         editorTagIds = row.Host.TagIds;
         EditorNewTag = string.Empty;
         BuildTagChoices();
@@ -10842,9 +10848,7 @@ internal sealed partial class VaultViewModel(
     private string HostsBoundTo(ResolvedBindingKind kind, Guid entityId)
     {
         var bound = Hosts
-            .Where(row => row.Resolved.Binding is { } binding
-                && binding.Kind == kind
-                && binding.EntityId == entityId)
+            .Where(row => Uses(row, kind, entityId))
             .Select(row => row.Label)
             .ToArray();
 
@@ -11671,10 +11675,13 @@ internal sealed partial class VaultViewModel(
         PhaseReporter reporter,
         CancellationToken cancellationToken)
     {
-        // A relay refusal already says exactly what happened, and a relayed host is reached by a path the
-        // probe does not take: it would dial the host directly — the route the user chose the relay because
-        // they cannot use — and report on that instead.
-        if (reporter.Furthest != SshConnectionPhase.Reaching || exception is ServerRelayException || target.Relayed)
+        // A relay or Spelunk refusal already says exactly what happened, and a routed host is reached by a
+        // path the probe does not take: it would dial the host directly — the route the user chose the relay
+        // or Spelunk because they cannot use, or for a Spelunk host an address that exists only to name its
+        // key — and report on that instead.
+        if (reporter.Furthest != SshConnectionPhase.Reaching
+            || exception is ServerRelayException or SpelunkTunnelException
+            || target.Routed)
         {
             return exception.Message;
         }
@@ -11840,11 +11847,11 @@ internal sealed partial class VaultViewModel(
     /// this machine without touching the host.
     /// </para>
     /// <para>
-    /// Internal because file transfer opens a connection of its own and a relayed host needs the relay
-    /// there too — or the transfers screen would fail for exactly the hosts the relay exists for.
+    /// Reached through <see cref="OpenRouteAsync"/>, which is what both transports call — file transfer
+    /// opens a connection of its own, and a relayed host needs the relay there too.
     /// </para>
     /// </remarks>
-    internal async Task<RelayRoute> OpenRelayAsync(string label, Guid hostId, CancellationToken cancellationToken)
+    private async Task<RelayRoute> OpenRelayAsync(string label, Guid hostId, CancellationToken cancellationToken)
     {
         if (await ResolveServerAsync(cancellationToken).ConfigureAwait(true) is not { } server)
         {
@@ -11857,17 +11864,18 @@ internal sealed partial class VaultViewModel(
     }
 
     /// <summary>
-    /// Opens the session, through the relay when there is one, and puts the relay's reason on a failure.
+    /// Opens the session, through the relay or Spelunk when the host uses one, and puts the route's reason on
+    /// a failure.
     /// </summary>
     /// <remarks>
     /// <para>
-    /// A relay that hung up reaches SSH.NET as a stream that ended, and it reports that the way it reports
-    /// every lost transport — a sentence that reads exactly like the direct failure the relay was ticked to
-    /// get around. When the relay said why it closed, that sentence is the true one and replaces it. The
-    /// host key refusals are left alone: a key was presented, so the relay did its job.
+    /// A route that hung up reaches SSH.NET as a stream that ended, and it reports that the way it reports
+    /// every lost transport — a sentence that reads exactly like the direct failure the route was chosen to
+    /// get around. When the route said why it closed, that sentence is the true one and replaces it. The
+    /// host key refusals are left alone: a key was presented, so the route did its job.
     /// </para>
     /// <para>
-    /// The relay is disposed on every failure. The connection owns it once it is handed over and disposes
+    /// The route is disposed on every failure. The connection owns it once it is handed over and disposes
     /// it on its own failure paths too, but a throw before the factory is reached would otherwise leave a
     /// bridge listening until its own timeout; disposing twice is safe.
     /// </para>
@@ -11880,28 +11888,30 @@ internal sealed partial class VaultViewModel(
     {
         // After the renderer rather than before it: a ticket is dead thirty seconds after issue, and the
         // renderer's wait is the one step of a connect with no bound a user would recognise.
-        var relay = target.Relayed
-            ? await OpenRelayAsync(target.Label, target.HostId!.Value, cancellationToken).ConfigureAwait(true)
+        var route = target.Row is { } row
+            ? await OpenRouteAsync(row, cancellationToken).ConfigureAwait(true)
             : null;
 
         try
         {
             return await workspace
                 .OpenSessionAsync(
-                    relay is null ? request : request with { Proxy = relay.Proxy },
+                    route is null ? request : request with { Proxy = route.Proxy },
                     TerminalSize.Default,
                     reporter,
                     cancellationToken)
                 .ConfigureAwait(true);
         }
-        catch (Exception exception) when (relay is not null)
+        catch (Exception exception) when (route is not null)
         {
-            await relay.DisposeAsync().ConfigureAwait(true);
+            await route.DisposeAsync().ConfigureAwait(true);
 
-            if (relay.Failure is { } failure
+            if (route.Failure is { } failure
                 && exception is not (OperationCanceledException or SshHostKeyUnknownException or SshHostKeyMismatchException))
             {
-                throw new ServerRelayException(failure, exception);
+                throw route is SpelunkTunnelRoute
+                    ? new SpelunkTunnelException(failure, exception)
+                    : new ServerRelayException(failure, exception);
             }
 
             throw;
@@ -12128,13 +12138,13 @@ internal sealed partial class VaultViewModel(
         internal Guid? HostId => Row?.EntityId;
 
         /// <summary>
-        /// Whether this is reached through the server relay rather than dialled.
+        /// Whether this is reached through the server relay or through Spelunk rather than dialled.
         /// </summary>
         /// <remarks>
-        /// Only a keychain host can be: the relay dials the address the server holds for an item, and a
-        /// machine typed into the manual box has no item and therefore nothing on the server to dial.
+        /// Only a keychain host can be: the relay dials the address the server holds for an item, Spelunk is
+        /// reached with a key the item names, and a machine typed into the manual box has neither.
         /// </remarks>
-        internal bool Relayed => Row?.Host.RelayEnabled is true;
+        internal bool Routed => Row?.Host is { } host && (host.RelayEnabled || host.Spelunk is not null);
     }
 
     /// <summary>
@@ -12343,6 +12353,10 @@ internal sealed partial class VaultViewModel(
             Notes = string.IsNullOrWhiteSpace(EditorNotes) ? null : EditorNotes,
             RelayEnabled = EditorRelayEnabled,
 
+            // Null unless the box is ticked, whatever the fields below it still hold: unticking is how a host
+            // goes back to being dialled, and it must not keep a route the user just turned off.
+            Spelunk = BuildSpelunkRoute(),
+
             // Only ever true or null, never false: the two would mean the same thing, and writing false would
             // change the bytes of every host that has never touched this. See HostSecret.AsksForPassword.
             //
@@ -13113,8 +13127,7 @@ internal sealed partial class VaultViewModel(
     private string UsedBySummaryFor(ResolvedBindingKind kind, Guid entityId)
     {
         var names = Hosts
-            .Where(row => row.Resolved.Binding is { } binding
-                && binding.Kind == kind && binding.EntityId == entityId)
+            .Where(row => Uses(row, kind, entityId))
             .Select(row => row.Label)
             .ToList();
 
@@ -13309,8 +13322,7 @@ internal sealed partial class VaultViewModel(
 
         if (kind is { } resolvedKind && value is not null)
         {
-            foreach (var row in Hosts.Where(row => row.Resolved.Binding is { } binding
-                && binding.Kind == resolvedKind && binding.EntityId == value.EntityId))
+            foreach (var row in Hosts.Where(row => Uses(row, resolvedKind, value.EntityId)))
             {
                 SelectedItemUsedByHosts.Add(new UsedByHostRowViewModel(row.Label, row.IsConnected));
             }