Let a connection be reached through a proxy on this machine's loopback
ci / build and test (push) Successful in 2m8s
ci / android head (push) Successful in 3m20s
ci / desktop nightly (push) Successful in 46s
ci / api image (push) Successful in 23s

Step 1 of docs/reaching-a-host-you-cannot-dial.md, and it is not the step that document said it was.

SshConnectionRequest carries an optional SshLoopbackProxy and BuildConnectionInfo hands SSH.NET its proxy
ConnectionInfo when there is one. Nothing passes one yet: the callers are jump hosts and the relay, which
are steps 2 and 3.

◆ THE BRIDGE WAS THE WRONG FIRST STEP, AND BUILDING IT WOULD HAVE BEEN THE MISTAKE THIS DOCUMENT IS ABOUT.
ADR 0004 says the relay's loopback bridge "also provides ProxyJump via a SOCKS5 dynamic forward — one
mechanism, two features", and the plan took that to mean the bridge was the shared foundation. It is not:
ForwardedPortDynamic *is* the listener for a jump host — SSH.NET accepts on it, speaks SOCKS5 on it and
tunnels through the bastion — so nothing is left for a bridge of ours to do on that path. The relay is the
case with no SshClient to hang a forward off, so it is the bridge's only consumer, and the bridge belongs in
the commit that uses it. What the two actually share is one level down and a tenth of the size: being told
to reach a target through a loopback proxy while staying about the target. That is what this is.

Three properties, one test each.

A port and nothing else, so a proxy anywhere but loopback cannot be expressed. The failure that shape rules
out is an open SOCKS proxy on the user's network for the life of a shell, which nothing would report — so it
is made unrepresentable rather than validated, on the same grounds AuthenticationChoice carries a kind.

SOCKS5 rather than a dumb pipe, which is what keeps host key pinning honest. The target's own name and port
stay in the request, travel to the proxy in the CONNECT, and are what the gate pins — so a machine reached
through a bastion is pinned under its own name instead of under 127.0.0.1 on whatever ephemeral port that
day's forward got, which is not an identity at all. A pipe would have meant handing SSH.NET a stand-in and
remembering everywhere else that it was one.

And a proxy that is not listening fails as a connection error rather than as an unknown host key. The gate
turns "no host key seen" into a fingerprint prompt, and a connection that never reached a server has seen
none either; the prompt would offer to fix the wrong thing, with no fingerprint to show.

TWO THINGS THE TESTS MEASURED RATHER THAN ASSUMED, both found by the first run failing.

The target is resolved at the *bastion*, not here — a SOCKS CONNECT names it and the far end looks it up. So
the test asks for localhost:2222, the address inside the container, and the published port this host would
use means nothing there. That is not a quirk of the fixture; it is what ProxyJump means, and it is why an
ssh_config writes the target's internal address beside its jump host. Getting it wrong is a SOCKS "general
failure" that names neither end.

And the test server refuses forwarding. linuxserver/openssh-server ships AllowTcpForwarding no, which a
dynamic forward does not notice — opening one asks the server nothing — so every connection through it is
refused at channel-open and reported as the same general failure. The fixture patches it and HUPs sshd.
There are two sshd_config files in that image and the running server uses /config/sshd/sshd_config; the
first attempt patched /etc/ssh/sshd_config, which is the one a search finds first, changed the text and
nothing else, and left the failure exactly where it was.

VERIFIED. Build clean with no new warnings, 85 tests in Client.Ssh.Tests against the real sshd, and the
solution builds. The proxy test was seen to fail — proxy.Port + 1 in BuildConnectionInfo — and seen green
again. An earlier mutation attempt did not compile, and the log said 85 passing because the run never
started and the previous log was still on disk; the second attempt deletes the log first, which is worth
copying whenever a mutation "passes".

dotnet format reports one pre-existing IDE1006 in DodoSSH.Api/Features/Events/EventsEndpoint.cs, in a
project nothing here touches. Left alone.
This commit is contained in:
2026-08-07 13:48:15 +02:00
parent 575a9a9f5e
commit 82966af37b
5 changed files with 441 additions and 28 deletions
+75 -23
View File
@@ -17,10 +17,10 @@ jump chain — see the last section for why that was wrong.
> | Step | State | Notes |
> | --- | --- | --- |
> | 0. Stop promising the relay | **Done** | Both heads say the box is not wired up and that ticking it stores the address and changes nothing. Left tickable, so a host already carrying the flag can lose it |
> | 1. The loopback bridge | Not started | ADR 0004's "one mechanism, two features" |
> | 2. Jump hosts over it | Not started | No server change at all |
> | 3. The relay over it | Not started | Ticket call, WebSocket, then the same bridge |
> | 4. File transfer parity | Not started | The transfers screen opens its own connection |
> | 1. Dial through a loopback proxy | **Done** | `SshLoopbackProxy` on the request, honoured in `BuildConnectionInfo`. **Not the bridge** — see below |
> | 2. Jump hosts over it | Not started | No server change, and no bridge either: SSH.NET's own forward is the proxy |
> | 3. The relay: the bridge, then the ticket | Not started | The bridge's only consumer, so it lands with the feature that uses it |
> | 4. File transfer parity | Not started | The transfers screen opens its own connection. Already half-done — `OpenSftpAsync` shares `BuildConnectionInfo`, so it honours a proxy today; what is missing is anything passing it one |
## ◆ The relay's checkbox is a false promise, and that is a defect
@@ -98,26 +98,56 @@ AuthenticationMethod[])` with `ProxyTypes.Socks5` — checked in `Renci.SshNet.x
- **Relay:** the same shape with a different thing on the loopback socket — a listener that pipes bytes into
the `dodossh.relay.v1` WebSocket instead of into a bastion's forward.
Which means the transport work is shared and the ordering is: bridge, then the cheap feature, then the one
that needs the server.
### ◆ But the bridge is the relay's half, not the shared one
Written into step 1 of this plan and wrong. Building it turned the sentence around: **the jump-host path
needs no bridge from this repository at all.** `ForwardedPortDynamic` *is* the loopback listener — SSH.NET
accepts on it, speaks SOCKS5 on it, and tunnels what it accepts through the bastion. Nothing is left for a
bridge of ours to do. The relay is the case with no `SshClient` to hang a forward off, so it is the one that
needs a listener written here, and it is the bridge's only consumer.
What the two genuinely share is one step lower: **the connection being told to reach its target through a
loopback SOCKS5 proxy, while staying about the target**. That is the piece both features stand on, it is
fifteen lines in `BuildConnectionInfo`, and it is what step 1 turned out to be.
So the bridge moves to step 3 and lands with the feature that uses it. Building it now would have been a
component whose only caller was two steps away — which is the shape of the two defects this document is
about.
## The work, in order
**0. Stop promising the relay.** The checkbox states that the relay is not wired up yet. One line on each
head, and it is the only step that should ship on its own.
**0. Stop promising the relay.** The checkbox states that the relay is not wired up yet. One line on each
head, and the only step that should ship on its own.
**1. The bridge.** A loopback `TcpListener` on an ephemeral port that accepts exactly one connection, hands
it to a `Stream` supplied by whoever opened the bridge, and disposes with the session. It belongs in
`Client.Ssh` beside `SshNetConnectionFactory`, and it needs to bind `127.0.0.1` explicitly — a bridge on
`0.0.0.0` is an open SOCKS proxy on the user's network for the life of a shell.
**1. Dial through a loopback proxy.**`SshConnectionRequest` carries an optional `SshLoopbackProxy`, and
`BuildConnectionInfo` builds SSH.NET's proxy `ConnectionInfo` when it is there. Three properties are worth
knowing, and each is held by a test in `LoopbackProxyTests`:
**2. Jump hosts.** No server change. In order:
- **The type is a port and nothing else.** A proxy on any interface but loopback cannot be expressed, which
matters because the failure mode is an open SOCKS proxy on the user's network for the life of a shell,
and nothing would report it.
- **SOCKS5 rather than a dumb pipe, so the target stays the target.** The host and port in the request are
the ones SSH.NET dials *through* the proxy and the ones the host key gate pins — so the same machine
reached through a bastion is pinned under its own name, not under `127.0.0.1:<ephemeral>`, which is not
an identity at all.
- **A proxy that is not listening fails as a connection error**, not as an unknown host key. The gate
translates "no host key seen" into a fingerprint prompt, and a connection that never reached a server has
seen none either — so the prompt would offer to fix the wrong thing, with no fingerprint to show.
- `SshConnectionRequest` grows a route: the resolved chain, each hop carrying what a connect needs, so the
SSH layer is handed hops rather than ids and never looks anything up.
Nothing calls it with a proxy yet. That is deliberate and it is one step wide: step 2 is the caller.
**2. Jump hosts.** No server change, and no bridge. In order:
- The hop's own connection, and a `ForwardedPortDynamic("127.0.0.1", 0)` started on it, whose `BoundPort`
becomes the `SshLoopbackProxy` for the connection after it. A chain of two is that twice.
- `VaultViewModel` resolves `JumpHostIds` to hosts in the same vault, applying group inheritance per hop the
way the target already gets it, and refuses a chain that crosses a vault — the same refusal
`RefusesTheDrop` and the group picker already make, for the same reason.
-**The target's address is resolved at the last hop, not here.** A SOCKS CONNECT names the target and the
bastion resolves it, so what has to be stored on the host is the address *the bastion* can reach — which
is what an `ssh_config` means by `HostName` beside a `ProxyJump`, and what the importer is already
carrying across verbatim. Nothing needs to change for that to be true; it needs to be said, because a
host that resolves here and not there fails as a SOCKS "general failure" naming neither end.
- Per-hop host keys. Each hop is a separate handshake against a separate endpoint, so the pin, the unknown
key prompt and the changed-key refusal run per hop. **The prompt has to name which hop it is about**, or
somebody approves a bastion's fingerprint believing it is the target's — see `HostKeyCard`, which is built
@@ -131,9 +161,13 @@ it to a `Stream` supplied by whoever opened the bridge, and disposes with the se
- The editor: a picker over other hosts in the same vault, and the host detail's subtitle finally getting
the `⤷ bastion-eu` the design asked for.
**3. The relay.** `POST /relay/tickets` with the host id, then the WebSocket with the ticket in
`Sec-WebSocket-Protocol`, piped into the bridge from step 1. The ticket is single-use and expires in 30
seconds, so it is fetched per connect and never cached. Then the checkbox from step 0 becomes true.
**3. The relay, and the bridge with it.** A loopback `TcpListener` on an ephemeral port that accepts one
connection, answers a SOCKS5 CONNECT on it, and pipes the rest into the `dodossh.relay.v1` WebSocket —
SOCKS5 rather than a raw pipe so that this path presents the same interface step 1 already speaks, and the
target's identity stays the target's. Then `POST /relay/tickets` with the host id and the WebSocket with the
ticket in `Sec-WebSocket-Protocol`; the ticket is single-use and expires in 30 seconds, so it is fetched per
connect and never cached. The bridge binds `127.0.0.1` explicitly, accepts once and stops listening. Then
the sentence step 0 added comes out of both heads.
**4. File transfer.** `ISftpSessionFactory.OpenSftpAsync` opens its own second connection, so a host that
needs a chain or a relay to reach needs it there too, or SFTP silently fails for exactly the hosts this
@@ -154,9 +188,17 @@ discovering it as a stack overflow inside a connect.
through `HostInheritance` exactly as the target does. Skipping that dials 22 as nobody on a bastion that is
on 2222 as `deploy`.
**`ForwardedPortDynamic(0)` and reading the port back.** Binding an ephemeral port and then asking for the
one that was assigned is the part that varies between SSH.NET versions; pin it with a test that opens one
against the test `sshd` rather than trusting the number.
**`ForwardedPortDynamic(0)` reports its port, and the one-argument constructor's bind address is
undocumented.** The first is now pinned by a test rather than trusted. The second is why the two-argument
constructor is always used: if the default were `0.0.0.0` the failure would not be a test failure, it would
be a SOCKS proxy into the developer's network that nothing reports, so the bound host is asserted too.
**◆ The test server refuses forwarding, and says so nowhere useful.** `linuxserver/openssh-server` ships
`AllowTcpForwarding no`. A dynamic forward starts anyway — opening one asks the server nothing — and every
connection through it is then refused at channel-open, which SSH.NET surfaces as `SOCKS5: General failure`,
naming neither the server nor the setting. `SshServerFixture` patches it after start and HUPs sshd. **There
are two `sshd_config` files in that image** and the running server uses `/config/sshd/sshd_config`; patching
`/etc/ssh/sshd_config`, which is the one a search finds first, changes the text and nothing else.
**The relay bridge and the jump bridge are the same class and not the same lifetime.** A ticket is
single-use with a 30-second expiry; a bastion's forward lives as long as the session. Sharing the listener
@@ -164,8 +206,11 @@ is right, sharing a lifetime policy is not.
## Tests
- A two-hop connect against the Testcontainers `sshd`, which `Client.Ssh.Tests` already stands up — one
container as bastion, one as target, with the target refusing connections from anywhere else.
- ✅ A connect through a real SOCKS5 forward to a real `sshd`, in `LoopbackProxyTests`. **One container,
used as both ends** — the forward is opened on a connection to the fixture's server and the connection
under test goes back to the same server through it. A second container would look more like the topology
and establish nothing extra: what is under test is that the proxy is honoured, that the target is what
gets pinned, and that a failure on the way through is reported as itself.
- A cycle in a chain is refused before any socket is opened.
- Each hop's host key is asked about separately, and the question names the hop.
- A chain crossing a vault is refused with a reason, as the group picker's is.
@@ -199,3 +244,10 @@ The lesson is narrower than "read the ADRs": it is that *nothing reads this fiel
field was a mistake, when it was evidence of an unfinished feature — and the same reasoning applied one
paragraph further would have found the relay checkbox, which is the same shape and is actively lying to
users.
**And then step 1 was wrong too**, in the same direction: it named the bridge as the shared foundation on
the strength of ADR 0004's "one mechanism, two features", without checking which half of the mechanism
SSH.NET already provides. It provides the jump host's half entirely. The shared piece was one level down and
a tenth of the size, and the bridge belongs with the relay. Both corrections came from writing the code
rather than from reading more — which is an argument for the step-at-a-time ordering rather than against
planning, but only if the plan is edited when a step answers back.