Move files to and from a host over SFTP

M2's file transfer, built bottom-up: an SFTP session on the SSH layer, a
transfer queue in a project of its own, and the two-pane browser the design
asked for replacing the screen that said it did not exist. Remote listings
carry names, sizes, modification times and a real drwxr-xr-x — nothing in this
repository could render a POSIX mode before — and the queue moves one file at a
time with progress, throughput and resume.

The design import assumed this would be an SFTP subsystem channel on
ISshConnection, beside the shell on a transport that is already up. SSH.NET
does not offer that: SftpClient derives from BaseClient and owns its own
transport, and there is no supported way to hand it an SshClient's session. So
file transfer opens a second authenticated connection, and it is named for
that rather than dressed up as a channel — OpenSftpAsync is on
ISftpSessionFactory, not on a connection. The difference is visible to a user:
the host records a second login, and a host whose password is typed each time
asks for it again on this screen. It goes through the same host key gate, the
same pin and the same two refusals a shell does, so a fingerprint approved for
a terminal is approved here and one approved here reaches the other machines
with the next sync. docs/design-import-gaps.md is corrected, and marked as the
one row where what shipped differs from what it predicted.

Nothing is written at its final name until it is complete. Every transfer goes
to a .dodossh-part file beside its destination and is renamed into place at the
end, so an interrupted transfer can never be mistaken for a finished one —
which matters most for what this screen is actually for, which is copying a
build artefact onto a server and then running it. A destination that already
exists is refused outright rather than overwritten: the queue has no way to
ask, and silently replacing a file somebody's process is serving is the worse
of the two failures. The remote pane has DELETE and MKDIR so that refusal is
not a dead end. A test against the container pins the assumption underneath all
of this — that SFTP's rename does not clobber.

Resume works within a run of the application and not across a restart, and the
limit is deliberate rather than unfinished. Nothing records which source wrote
a part file, and resuming one on the strength of its name matching is how a
corrupt artefact gets delivered with nothing reporting a failure; a part file
found at startup is started over. Making it survive a restart needs the
preferences store this client still has not got. The offset a resume starts at
is the part file's own length rather than the transfer's recorded progress: a
cancellation can land between a write completing and the counter moving, and
only one of those two is a fact about the bytes that are there.

The queue and its connection outlive a lock, as shells do. LockAsync already
argues that locking must not destroy work in flight — it is what somebody does
when they walk away from the machine, which is exactly when a long transfer is
most likely to be running — so TransfersViewModel is created once and the vault
is attached on unlock and detached on lock. What locking takes is the host
list, and it has to: those rows carry decrypted secrets.

DodoSSH.Client.Transfer is a new project rather than more of Client.Ssh. The
two answer different questions — one is about reaching a host, the other about
moving bytes and what to do when moving them stops halfway — and this is the
only client project that deliberately touches the local filesystem.

Three defects the tests found, none of which review would have. SftpPath.Name
answered an empty string for the root. NavigateRemoteAsync wrapped itself in
the busy guard, so navigating from inside another command did nothing at all
and the remote pane simply stayed empty after connecting, with no failure
anywhere to explain it. And opening an SFTP session per test made two
handshakes per test — this client learns a host key by being refused — which
pushed the SSH assembly past sshd's MaxStartups and failed a different few
unrelated tests each run; the session is shared through the fixture now, with
the reason written where the next person will hit it.

1004 tests green across 18 projects, 24 of them new: the SFTP subsystem against
the OpenSSH container, the queue against a real temporary directory and a fake
host, and three more layout measurements because a screen this window has never
laid out is a screen never checked.

Not verified: the screen has not been looked at running. The layout harness
measures it at the window's minimum in three shapes, which is the class of
defect that has shipped here before, but reaching it in the application needs
the compose stack, the migrations, the API and a browser sign-in. What is still
absent — the status bar's transfer count, dragging between the panes,
transferring a directory, and sftp over a bastion — is in
docs/design-import-gaps.md.

tests/DodoSSH.Client.App.Tests/FakeSsh.cs

@@ -10,7 +10,7 @@ namespace DodoSSH.Client.App.Tests;
 /// sshd — which <c>DodoSSH.Client.Ssh.Tests</c> already covers against a container. What this makes
 /// testable is everything the connect path does <em>around</em> the connection.
 /// </remarks>
-internal sealed class FakeSshConnectionFactory : ISshConnectionFactory
+internal sealed class FakeSshConnectionFactory : ISshConnectionFactory, ISftpSessionFactory
 {
     /// <summary>Thrown instead of connecting, when set. Used for the host-key paths.</summary>
     internal Exception? Failure { get; set; }
@@ -18,6 +18,14 @@ internal sealed class FakeSshConnectionFactory : ISshConnectionFactory
     /// <summary>Requests this factory was asked for, in order.</summary>
     internal List<SshConnectionRequest> Requests { get; } = [];
 
+    /// <summary>Requests for a file-transfer session, in order.</summary>
+    /// <remarks>
+    /// Kept apart from <see cref="Requests"/> deliberately: file transfer is a separate connection, and a
+    /// test asserting that opening a terminal did not also open one would have nothing to look at if the two
+    /// shared a list.
+    /// </remarks>
+    internal List<SshConnectionRequest> SftpRequests { get; } = [];
+
     /// <inheritdoc />
     public Task<ISshConnection> ConnectAsync(
         SshConnectionRequest request,
@@ -29,6 +37,81 @@ internal sealed class FakeSshConnectionFactory : ISshConnectionFactory
             ? Task.FromException<ISshConnection>(failure)
             : Task.FromResult<ISshConnection>(new FakeSshConnection(request));
     }
+
+    /// <inheritdoc />
+    public Task<ISftpSession> OpenSftpAsync(
+        SshConnectionRequest request,
+        CancellationToken cancellationToken)
+    {
+        SftpRequests.Add(request);
+
+        return Failure is { } failure
+            ? Task.FromException<ISftpSession>(failure)
+            : Task.FromResult<ISftpSession>(new FakeSftpSession(request));
+    }
+}
+
+/// <summary>A remote filesystem with one directory in it.</summary>
+/// <remarks>
+/// Enough for the shell suite, which is about what the screen does around a session rather than about
+/// moving bytes. The queue's own behaviour is covered against a fuller fake in
+/// <c>DodoSSH.Client.Transfer.Tests</c>, and the real subsystem against a container in
+/// <c>DodoSSH.Client.Ssh.Tests</c>.
+/// </remarks>
+internal sealed class FakeSftpSession(SshConnectionRequest request) : ISftpSession
+{
+    /// <inheritdoc />
+    public bool IsConnected { get; private set; } = true;
+
+    /// <inheritdoc />
+    public HostKeyPresentation HostKey { get; } =
+        new(request.Host, request.Port, "ssh-ed25519", "SHA256:fake");
+
+    /// <inheritdoc />
+    public string HomeDirectory => $"/home/{request.Username}";
+
+    /// <inheritdoc />
+    public Task<IReadOnlyList<SftpEntry>> ListAsync(string path, CancellationToken cancellationToken) =>
+        Task.FromResult<IReadOnlyList<SftpEntry>>(
+        [
+            new SftpEntry(
+                "notes.txt",
+                SftpPath.Combine(path, "notes.txt"),
+                SftpEntryKind.File,
+                12,
+                DateTimeOffset.UnixEpoch,
+                "-rw-r--r--"),
+        ]);
+
+    /// <inheritdoc />
+    public Task<SftpEntry?> StatAsync(string path, CancellationToken cancellationToken) =>
+        Task.FromResult<SftpEntry?>(null);
+
+    /// <inheritdoc />
+    public Task<Stream> OpenReadAsync(string path, long offset, CancellationToken cancellationToken) =>
+        Task.FromResult<Stream>(new MemoryStream("hello there\n"u8.ToArray(), writable: false));
+
+    /// <inheritdoc />
+    public Task<Stream> OpenWriteAsync(string path, long offset, CancellationToken cancellationToken) =>
+        Task.FromResult<Stream>(new MemoryStream());
+
+    /// <inheritdoc />
+    public Task CreateDirectoryAsync(string path, CancellationToken cancellationToken) =>
+        Task.CompletedTask;
+
+    /// <inheritdoc />
+    public Task DeleteAsync(string path, CancellationToken cancellationToken) => Task.CompletedTask;
+
+    /// <inheritdoc />
+    public Task RenameAsync(string fromPath, string toPath, CancellationToken cancellationToken) =>
+        Task.CompletedTask;
+
+    /// <inheritdoc />
+    public ValueTask DisposeAsync()
+    {
+        IsConnected = false;
+        return ValueTask.CompletedTask;
+    }
 }
 
 internal sealed class FakeSshConnection(SshConnectionRequest request) : ISshConnection

tests/DodoSSH.Client.App.Tests/ShellFlowTests.cs

@@ -110,6 +110,7 @@ public sealed class ShellFlowTests : IAsyncLifetime
             deviceKeys,
             SignInAsync,
             TimeProvider.System,
+            ssh,
             CheapProfile);
 
         return ValueTask.CompletedTask;
@@ -293,6 +294,7 @@ public sealed class ShellFlowTests : IAsyncLifetime
             new UnavailableDeviceKeyStore(),
             (_, _) => throw new InvalidOperationException("The shell went to the network to unlock."),
             TimeProvider.System,
+            ssh,
             CheapProfile);
 
         await using var _ = offline.ConfigureAwait(false);
@@ -738,6 +740,7 @@ public sealed class ShellFlowTests : IAsyncLifetime
             new UnavailableDeviceKeyStore(),
             (_, _) => throw new InvalidOperationException("unreachable"),
             TimeProvider.System,
+            ssh,
             CheapProfile);
 
         await using var _ = offline.ConfigureAwait(false);
@@ -1966,7 +1969,8 @@ public sealed class ShellFlowTests : IAsyncLifetime
         await AddHostAsync(vault, "prod-web-01");
         await AddHostAsync(vault, "prod-web-02");
 
-        vault.SelectedHost = vault.Hosts.Single(host => host.Label == "prod-web-01");
+        vault.SelectedHost = vault.Hosts.Single(
+            host => string.Equals(host.Label, "prod-web-01", StringComparison.Ordinal));
 
         vault.HostFilter = "prod";
 
@@ -1999,7 +2003,8 @@ public sealed class ShellFlowTests : IAsyncLifetime
         await AddHostAsync(vault, "prod-db");
         await AddHostAsync(vault, "stage-web");
 
-        vault.SelectedHost = vault.Hosts.Single(host => host.Label == "stage-web");
+        vault.SelectedHost = vault.Hosts.Single(
+            host => string.Equals(host.Label, "stage-web", StringComparison.Ordinal));
 
         await vault.LoadAsync(Token);
 
@@ -2153,6 +2158,7 @@ public sealed class ShellFlowTests : IAsyncLifetime
             deviceKeys,
             (_, _) => throw new InvalidOperationException("The shell went to the network."),
             TimeProvider.System,
+            ssh,
             CheapProfile);
 
         await using var _ = offline.ConfigureAwait(false);
@@ -2210,6 +2216,85 @@ public sealed class ShellFlowTests : IAsyncLifetime
         shell.State.ShouldBe(ShellState.Unlocked, shell.StatusMessage);
     }
 
+    // ---- File transfer ----
+
+    [Fact]
+    public async Task TheTransfersScreen_TakesItsHostListFromTheUnlockedVault()
+    {
+        await UnlockedAsync();
+        await AddHostAsync(shell.Vault!, "prod-db");
+
+        // Attached at unlock, after the vault has loaded. Before that ordering was right the picker was
+        // empty until something else happened to reload it.
+        shell.Transfers.Hosts.ShouldBeEmpty("the vault had no hosts when it was attached");
+
+        await shell.LockCommand.ExecuteAsync(null);
+        shell.Passphrase = Passphrase;
+        await shell.UnlockCommand.ExecuteAsync(null);
+
+        shell.Transfers.Hosts.Select(host => host.Label).ShouldBe(["prod-db"]);
+    }
+
+    /// <remarks>
+    /// The lock policy, applied to the other thing that can be in flight. <c>LockAsync</c> argues that
+    /// locking must not destroy work — it is what somebody does when they walk away from the machine, which
+    /// is exactly when a long transfer is most likely to be running. A screen rebuilt per unlock would have
+    /// dropped the session and with it whatever was moving.
+    /// </remarks>
+    [Fact]
+    public async Task Locking_LeavesAFileTransferConnectionOpenAndOnlyTakesTheHostListAway()
+    {
+        await UnlockedAsync();
+
+        var vault = shell.Vault!;
+        await AddHostAsync(vault, "prod-db");
+
+        shell.Transfers.Attach(vault, knownHosts);
+        shell.Transfers.SelectedHost = shell.Transfers.Hosts[0];
+
+        await shell.Transfers.ConnectCommand.ExecuteAsync(null);
+
+        shell.Transfers.IsConnected.ShouldBeTrue(shell.Transfers.Status);
+
+        await shell.LockCommand.ExecuteAsync(null);
+
+        shell.Transfers.IsConnected.ShouldBeTrue("locking the vault is not a disconnect");
+
+        // What it does take is the host list, and it has to: those rows carry decrypted secrets and the
+        // vault they came from has just been disposed.
+        shell.Transfers.Hosts.ShouldBeEmpty();
+        shell.Transfers.SelectedHost.ShouldBeNull();
+    }
+
+    /// <remarks>
+    /// The consequence of SSH.NET having no way to open an SFTP subsystem on an existing transport, made
+    /// visible: browsing a host's files authenticates again rather than reusing the terminal's connection.
+    /// It is asserted rather than merely written down because the host's audit log shows a second login,
+    /// and somebody will eventually be asked to explain it.
+    /// </remarks>
+    [Fact]
+    public async Task ConnectingTheTransfersScreen_OpensItsOwnConnectionRatherThanReusingATerminals()
+    {
+        var vault = await ReadyToConnectAsync();
+
+        await ConnectWithRendererAsync(vault);
+
+        ssh.Requests.Count.ShouldBe(1);
+        ssh.SftpRequests.ShouldBeEmpty("opening a terminal must not open a file-transfer session");
+
+        shell.Transfers.Attach(vault, knownHosts);
+        shell.Transfers.SelectedHost = shell.Transfers.Hosts[0];
+
+        await shell.Transfers.ConnectCommand.ExecuteAsync(null);
+
+        ssh.SftpRequests.Count.ShouldBe(1);
+        ssh.Requests.Count.ShouldBe(1, "and it must not open a shell either");
+
+        // It opens on the account's home directory, which is the only path the layer knows without asking.
+        shell.Transfers.RemotePath.ShouldBe("/home/deploy");
+        shell.Transfers.RemoteEntries.Select(entry => entry.Name).ShouldBe(["notes.txt"]);
+    }
+
     private async Task UnlockedAsync()
     {
         await EnrolledAndConfirmedAsync();

tests/DodoSSH.Client.App.Tests/packages.lock.json

@@ -476,7 +476,8 @@
           "CommunityToolkit.Mvvm": "[8.4.2, )",
           "DodoSSH.Client.Session": "[1.0.0, )",
           "DodoSSH.Client.Ssh": "[1.0.0, )",
-          "DodoSSH.Client.Terminal": "[1.0.0, )"
+          "DodoSSH.Client.Terminal": "[1.0.0, )",
+          "DodoSSH.Client.Transfer": "[1.0.0, )"
         }
       },
       "dodossh.client.auth": {
@@ -527,6 +528,12 @@
           "DodoSSH.Client.Ssh": "[1.0.0, )"
         }
       },
+      "dodossh.client.transfer": {
+        "type": "Project",
+        "dependencies": {
+          "DodoSSH.Client.Ssh": "[1.0.0, )"
+        }
+      },
       "dodossh.contracts": {
         "type": "Project"
       },