Add the SSH session layer and the terminal data plane

The throughput harness the plan requires before any UI, plus the SSH
plumbing under it. 94 new tests, no WebView involved.

Credit-based flow control is what makes `yes` survivable. A terminal renders
at 60 Hz at best while a remote produces output as fast as the network
allows, and the difference has to accumulate somewhere or be refused.
Credit is reserved *before* reading, never after: because the pump cannot
read more than the renderer has room for, the coalescing buffer is bounded
by the window rather than by how fast the remote can talk. When credit runs
out the pump stops reading, SSH's own receive window closes, and the remote
sshd blocks -- backpressure to the source with no custom protocol.

Verified by falsification, not just by passing: with the credit gate removed
three tests fail, including the throughput harness's bounded-memory
assertion. Acknowledgements are clamped because they cross into JavaScript,
where a buggy or hostile page could otherwise claim to have rendered a
gigabyte and talk the host into an unbounded read.

Host key trust is enforced by *failing* the connection rather than
prompting inside the handshake. SSH.NET raises verification synchronously,
so consulting the user there would block the handshake on a UI round trip
and deadlock the first time the prompt needed the UI thread. Unknown host
and changed key become distinct exceptions the caller resolves
asynchronously. A mismatch has no retry path at all: a dialog offering to
continue is how users are trained to click through the one warning that
actually indicates interception. A legitimately rebuilt server is handled by
removing the pin in settings, away from the moment of connecting.

The data plane serves the renderer page from the same loopback listener as
the socket, which makes Origin predictable -- always http://127.0.0.1:{port}
-- where a WebView virtual-host mapping would give a different origin per
backend and nothing to validate. The token is substituted at serve time, so
it never touches disk and never appears in a URL. Being clear about what
that buys: not protection from a process running as this user, which can
read our memory anyway, but from a page in the user's browser attempting
WebSocket connections to loopback ports, which is a real and routine thing.

Two bugs the tests caught. The accept loop handled connections serially, so
an upgraded WebSocket parked it inside the receive loop and every later
request went unanswered -- the page's own script among them. The suite hung
rather than failed, which is how I found it. And SHA-1 is unavoidable here:
RFC 6455 mandates it for Sec-WebSocket-Accept, where it authenticates
nothing. Suppressed narrowly with that reasoning; the alternative,
HttpListener.AcceptWebSocketAsync, throws PlatformNotSupportedException off
Windows.
This commit is contained in:
2026-07-28 21:58:55 +02:00
parent 94f66be5e8
commit eb354bcdd9
19 changed files with 3216 additions and 0 deletions
+114
View File
@@ -0,0 +1,114 @@
namespace DodoSSH.Client.Ssh;
/// <summary>A host key as the server presented it during the handshake.</summary>
/// <param name="Host">Host as dialled.</param>
/// <param name="Port">Port as dialled.</param>
/// <param name="Algorithm">Key algorithm, e.g. <c>ssh-ed25519</c>.</param>
/// <param name="Fingerprint">OpenSSH-style fingerprint, from <see cref="SshHostKeyFingerprint"/>.</param>
public sealed record HostKeyPresentation(string Host, int Port, string Algorithm, string Fingerprint);
/// <summary>
/// The trusted host keys a user has accumulated.
/// </summary>
/// <remarks>
/// Known hosts live in the end-to-end encrypted vault as a synced entity, not in a local file. Trust
/// then follows the user to every device, and the server cannot tamper with it — which matters,
/// because a server that could silently drop a pin could downgrade every connection to first-use.
/// </remarks>
public interface IKnownHostStore
{
/// <summary>Returns the pinned fingerprint for a host and key algorithm, if there is one.</summary>
/// <remarks>
/// Keyed on algorithm as well as host, because a server legitimately offers several host keys and
/// which one is negotiated can change between connections. Pinning only one and rejecting the
/// others would make a normal server look hostile.
/// </remarks>
ValueTask<string?> FindAsync(string host, int port, string algorithm, CancellationToken cancellationToken);
/// <summary>Records a host key as trusted.</summary>
ValueTask TrustAsync(HostKeyPresentation presentation, CancellationToken cancellationToken);
}
/// <summary>
/// The host has never been seen, so there is nothing to compare against.
/// </summary>
/// <remarks>
/// A distinct exception rather than a prompt inside the handshake, and that is a deliberate design
/// choice. SSH.NET raises host key verification as a synchronous event, so consulting the user from
/// inside it would mean blocking the handshake thread on a UI round trip — sync-over-async, and a
/// deadlock the first time the prompt needs the UI thread. Failing the connection and letting the
/// caller prompt keeps everything asynchronous, at the cost of a second TCP connection the first
/// time a host is used.
/// </remarks>
public sealed class SshHostKeyUnknownException(HostKeyPresentation presentation)
: Exception($"The host key for {presentation.Host}:{presentation.Port} is not trusted yet.")
{
/// <summary>The key the server offered, to show the user before they trust it.</summary>
public HostKeyPresentation Presentation { get; } = presentation;
}
/// <summary>
/// The host presented a different key from the one pinned for it.
/// </summary>
/// <remarks>
/// This must stay a hard block with no "continue anyway" in the connect path. A dialog offering to
/// proceed is how users are trained to click through the one warning that actually indicates an
/// interception. A legitimate key change — a rebuilt server — is handled by explicitly removing the
/// pin in the host's settings, which is a deliberate act performed away from the moment of
/// connecting.
/// </remarks>
public sealed class SshHostKeyMismatchException(HostKeyPresentation presentation, string pinnedFingerprint)
: Exception(
$"The host key for {presentation.Host}:{presentation.Port} has changed. "
+ $"Pinned {pinnedFingerprint}, but the server offered {presentation.Fingerprint}.")
{
/// <summary>The key the server offered.</summary>
public HostKeyPresentation Presentation { get; } = presentation;
/// <summary>The key previously trusted for this host.</summary>
public string PinnedFingerprint { get; } = pinnedFingerprint;
}
/// <summary>
/// A known-host store held in memory.
/// </summary>
/// <remarks>
/// Stands in until the encrypted local cache lands. Trust is lost when the process exits, so a user
/// is asked about every host on every launch — noisy, but the noise is the correct failure mode for a
/// placeholder: it cannot be mistaken for working persistence.
/// </remarks>
public sealed class InMemoryKnownHostStore : IKnownHostStore
{
private readonly Dictionary<string, string> pins = new(StringComparer.Ordinal);
private readonly Lock gate = new();
/// <inheritdoc />
public ValueTask<string?> FindAsync(
string host,
int port,
string algorithm,
CancellationToken cancellationToken)
{
lock (gate)
{
return ValueTask.FromResult(pins.GetValueOrDefault(Key(host, port, algorithm)));
}
}
/// <inheritdoc />
public ValueTask TrustAsync(HostKeyPresentation presentation, CancellationToken cancellationToken)
{
ArgumentNullException.ThrowIfNull(presentation);
lock (gate)
{
pins[Key(presentation.Host, presentation.Port, presentation.Algorithm)] =
presentation.Fingerprint;
}
return ValueTask.CompletedTask;
}
private static string Key(string host, int port, string algorithm) =>
$"{host}:{port}/{algorithm}";
}