DodoTech-Public/DodoSSH
Public Access
3
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Let a host marked for the relay actually be reached through it
ci / build and test (pull_request) Successful in 6m27s
Details
ci / desktop nightly (pull_request) Skipped
Details
ci / android head (pull_request) Successful in 15m47s
Details
ci / api image (pull_request) Failing after 28s
Details

Browse Source 
The relay checkbox said it was not wired up, and the plan said the server
half was built and shipped. It was not: there was ADR 0004, the contract
records, RelayOptions and a CHECK constraint, and RelayOptions said in its
own remarks that there was no endpoint and no dialler. So both halves are
built here, as step 3 of docs/reaching-a-host-you-cannot-dial.md.

Server, in Features/Relay:

- POST /api/v1/relay/tickets makes every decision: the host, Connect on
  its vault, the relay switched on, and the stored name resolved once and
  judged by RelayAddressPolicy. Loopback, link-local, 0.0.0.0/8,
  multicast and the metadata endpoints are refused with no configuration
  escape, with IPv4-mapped and NAT64 spellings unwrapped first; then the
  operator's denials, allow-list and private-network switch. What passes
  goes into a Data Protection ticket, and nothing resolves the name again.
  Every target refusal is the same 403, so the endpoint cannot be used to
  map the operator's DNS; the real reason is logged.
- GET /api/v1/relay/connect takes the ticket as a second subprotocol,
  checks its expiry against TimeProvider and spends it with a unique
  insert into relay_ticket_use before accepting the upgrade. After the
  upgrade a refusal is a close code: 4502 for a host the server could not
  reach, 4429 for a limit, 4408 idle, 4409 lifetime, 1001 after a drain.
- relay_session is the audit row, written from short-lived scopes.

Client:

- RelayBridge is a loopback SOCKS5 listener that accepts once and pipes
  to the relay socket. It rides on the new SshLoopbackProxy.Lifetime, so
  the connection disposes it on every way a session ends and a failed
  connect disposes it before throwing.
- ServerRelay, exposed as IVaultServer.Relay from /api/v1/meta, asks for
  the ticket, opens the socket, starts the bridge and turns every refusal
  into a sentence.
- VaultViewModel and TransfersViewModel reach a relayed host through it,
  never fall back to dialling it directly, and replace SSH.NET's transport
  error with the relay's own reason when it gave one.

Neither side ever cancels a WebSocket operation. Cancelling one aborts
the socket, and an aborted socket sends no close frame, which is the only
way the client learns the server could not reach the host.
AnIdleSession_IsClosedWithTheIdleCode asserts that the code arrives.

Three departures from ADR 0004, recorded in it: awaited copy loops rather
than Pipelines (same backpressure, two 32 KiB buffers), no ?ticket=
fallback, and no device id in the ticket.

Tests: API 245, shell 582 (5 skipped), layout 170, SSH 110 including a
real login through the bridge, API client 30, contracts 25. Not run: the
Android build (its change is copy only) and the Alpine layout oracle.
This commit is contained in:
jaap-jan committed 2026-09-28 14:37:20 +02:00
1 parent 54bc142dce
commit b20f7cae04
51 files changed
+6455 -88
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

tests/DodoSSH.Api.Tests/RelayEndpointTests.cs
+559
View File
@@ -0,0 +1,559 @@
using System.Net;
using System.Net.Sockets;
using System.Net.WebSockets;
using System.Text;
using DodoSSH.Contracts;
using DodoSSH.Domain;
using DodoSSH.Infrastructure;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
namespace DodoSSH.Api.Tests;
/// <summary>
/// The relay, over a real socket, through the real ticket, against a target the test owns.
/// </summary>
/// <remarks>
/// <para>
/// The network is the only thing replaced — see <see cref="FakeRelayNetwork"/> — and it is replaced
/// <em>under</em> the address policy, so every address these tests arrange is still judged by the real
/// rules. That is what lets the refusals here be meaningful: a loopback target is refused because the
/// policy refused it, not because the fake had nothing to route it to, and the tests say which by
/// asserting that nothing was dialled.
/// </para>
/// <para>
/// The refusals share one answer on purpose, and a test holds them to it. A distinct response for "that
/// name resolves internally, but no" is a scanner for the operator's DNS in the hands of anyone who can
/// edit a host.
/// </para>
/// </remarks>
[Collection(ApiCollection.Name)]
public sealed class RelayEndpointTests(ApiFixture fixture)
{
private static readonly DateTimeOffset Now = new(2026, 9, 28, 12, 0, 0, TimeSpan.Zero);
/// <summary>How long a test waits for a frame. Generous, because it bounds a broken build, not a measurement.</summary>
private static readonly TimeSpan FrameTimeout = TimeSpan.FromSeconds(30);
// ---- The ticket ----
[Fact]
public async Task ATicket_NamesTheSocketAndExpiresWithinThirtySeconds()
{
var (subject, hostId) = await SeedRelayHostAsync("10.40.0.1", 22);
var ticket = await IssueAsync(subject, hostId);
ticket.SubProtocol.ShouldBe(RelayProtocol.SubProtocol);
ticket.WebSocketUrl.AbsolutePath.ShouldBe(RelayProtocol.ConnectPath);
ticket.ExpiresAt.ShouldBeLessThanOrEqualTo(TimeProvider.System.GetUtcNow().AddSeconds(31));
// It has to stand in a Sec-WebSocket-Protocol list, so it must be an HTTP token: no padding, no
// slash, no plus — which is what base64url is for.
ticket.Ticket.ShouldAllBe(c => char.IsAsciiLetterOrDigit(c) || c == '-' || c == '_');
}
[Fact]
public async Task EveryTargetRefusal_IsTheSameAnswer()
{
var (subject, relayOff) = await SeedHostAsync(relay: null);
var (_, others) = await SeedRelayHostAsync("10.40.0.2", 22);
var (_, loopback) = await SeedRelayHostAsync("127.0.0.1", 22, subject);
var (_, smtp) = await SeedRelayHostAsync("10.40.0.3", 25, subject);
var (_, unresolvable) = await SeedRelayHostAsync("nowhere.invalid", 22, subject);
var client = fixture.CreateClientFor(subject);
var answers = new List<JsonProblem>();
foreach (var hostId in new[] { relayOff, others, loopback, smtp, unresolvable, Guid.CreateVersion7() })
{
var response = await client.PostContractAsync(RelayProtocol.TicketsPath, new RelayTicketRequest(hostId, null));
response.StatusCode.ShouldBe(HttpStatusCode.Forbidden);
answers.Add((await response.Content.ReadProblemAsync()).ShouldNotBeNull());
}
answers.ShouldAllBe(problem => problem.Code == ProblemCodes.RelayTargetRejected);
answers.Select(problem => problem.Detail).Distinct(StringComparer.Ordinal).Count().ShouldBe(1);
}
[Theory]
[InlineData("127.0.0.1")]
[InlineData("::1")]
[InlineData("::ffff:127.0.0.1")]
[InlineData("169.254.169.254")]
[InlineData("::ffff:169.254.169.254")]
[InlineData("0.0.0.0")]
public async Task AnAddressThePolicyRefuses_IsNeverDialled(string address)
{
var (subject, hostId) = await SeedRelayHostAsync(address, 22);
var dialledBefore = fixture.RelayNetwork.Dialled.Count;
var response = await fixture.CreateClientFor(subject)
.PostContractAsync(RelayProtocol.TicketsPath, new RelayTicketRequest(hostId, null));
response.StatusCode.ShouldBe(HttpStatusCode.Forbidden);
fixture.RelayNetwork.Dialled.Count.ShouldBe(dialledBefore);
}
[Fact]
public async Task ANameResolvingToABadAndAGoodAddress_IsDialledOnlyOnTheGoodOne()
{
// The rebinding shape: one answer the policy likes and one it must never reach. The ticket carries
// only what passed, so the socket has nothing else it could try.
using var target = LoopbackTarget.Echo();
var good = new IPEndPoint(IPAddress.Parse("10.40.1.1"), 22);
fixture.RelayNetwork.Resolve("mixed.test", IPAddress.Parse("169.254.169.254"), good.Address);
fixture.RelayNetwork.Route(good, target.Endpoint);
var (subject, hostId) = await SeedRelayHostAsync("mixed.test", 22);
using var timeout = Timeout();
using var socket = await ConnectAsync(await IssueAsync(subject, hostId), timeout.Token);
await RoundTripAsync(socket, "hello", timeout.Token);
fixture.RelayNetwork.Dialled.ShouldNotContain(endpoint => endpoint.Address.Equals(IPAddress.Parse("169.254.169.254")));
}
[Fact]
public async Task APortForward_IsRefused()
{
// Its port lives in ciphertext, so honouring one would mean taking the port from the client.
var (subject, hostId) = await SeedRelayHostAsync("10.40.0.4", 22);
var response = await fixture.CreateClientFor(subject)
.PostContractAsync(RelayProtocol.TicketsPath, new RelayTicketRequest(hostId, Guid.CreateVersion7()));
response.StatusCode.ShouldBe(HttpStatusCode.Forbidden);
(await response.Content.ReadProblemAsync()).ShouldNotBeNull().Code.ShouldBe(ProblemCodes.RelayTargetRejected);
}
// ---- The socket ----
[Fact]
public async Task BytesGoBothWays_AndTheSessionIsAudited()
{
using var target = LoopbackTarget.Echo();
var (subject, hostId) = await SeedRoutedHostAsync(target, "10.40.2.1");
var ticket = await IssueAsync(subject, hostId);
using var timeout = Timeout();
using (var socket = await ConnectAsync(ticket, timeout.Token))
{
socket.SubProtocol.ShouldBe(RelayProtocol.SubProtocol);
await RoundTripAsync(socket, "SSH-2.0-test", timeout.Token);
await RoundTripAsync(socket, "a second message", timeout.Token);
await socket.CloseAsync(WebSocketCloseStatus.NormalClosure, string.Empty, timeout.Token);
}
var session = await WaitForClosedAuditAsync(ticket.SessionId, timeout.Token);
session.HostId.ShouldBe(hostId);
session.TargetAddress.ShouldBe("10.40.2.1");
session.TargetPort.ShouldBe(22);
session.CloseReason.ShouldBe(RelayCloseReason.ClientClosed);
var sent = Encoding.UTF8.GetByteCount("SSH-2.0-test") + Encoding.UTF8.GetByteCount("a second message");
session.BytesClientToTarget.ShouldBe(sent);
session.BytesTargetToClient.ShouldBe(sent);
}
[Fact]
public async Task ATicket_IsSpentByItsFirstUse()
{
using var target = LoopbackTarget.Echo();
var (subject, hostId) = await SeedRoutedHostAsync(target, "10.40.3.1");
var ticket = await IssueAsync(subject, hostId);
using var timeout = Timeout();
using var first = await ConnectAsync(ticket, timeout.Token);
var replay = await Should.ThrowAsync<InvalidOperationException>(ConnectAsync(ticket, timeout.Token));
replay.Message.ShouldContain("401");
}
[Theory]
[InlineData(null)]
[InlineData("")]
[InlineData("not-a-ticket")]
public async Task AnUpgradeWithoutAGenuineTicket_IsRefused(string? ticket)
{
var client = fixture.Server.CreateWebSocketClient();
client.SubProtocols.Add(RelayProtocol.SubProtocol);
if (ticket is not null)
{
client.SubProtocols.Add(RelayProtocol.TicketProtocolPrefix + ticket);
}
var refused = await Should.ThrowAsync<InvalidOperationException>(client.ConnectAsync(
new Uri(fixture.Server.BaseAddress, RelayProtocol.ConnectPath.TrimStart('/')),
TestContext.Current.CancellationToken));
refused.Message.ShouldContain("401");
}
[Fact]
public async Task APlainGet_SaysItIsAWebSocket()
{
var response = await fixture.CreateClient().GetAsync(
new Uri(RelayProtocol.ConnectPath, UriKind.Relative),
TestContext.Current.CancellationToken);
response.StatusCode.ShouldBe(HttpStatusCode.BadRequest);
(await response.Content.ReadProblemAsync()).ShouldNotBeNull().Code.ShouldBe(ProblemCodes.MalformedRequest);
}
[Fact]
public async Task ATargetThatDoesNotAnswer_ClosesWithItsOwnCode()
{
// Routed nowhere, so the fake refuses the connect the way a closed port does. The user has to be
// told the *server* could not reach the machine, which is not what a direct failure means.
var (subject, hostId) = await SeedRelayHostAsync("10.40.4.1", 22);
var ticket = await IssueAsync(subject, hostId);
using var timeout = Timeout();
using var socket = await ConnectAsync(ticket, timeout.Token);
await ReadUntilCloseAsync(socket, timeout.Token);
socket.CloseStatus.ShouldBe((WebSocketCloseStatus)RelayProtocol.TargetUnreachableCloseCode);
(await WaitForClosedAuditAsync(ticket.SessionId, timeout.Token)).CloseReason
.ShouldBe(RelayCloseReason.TargetUnreachable);
}
[Fact]
public async Task ATargetThatHangsUp_EndsTheSession()
{
using var target = LoopbackTarget.SayThenHangUp("bye");
var (subject, hostId) = await SeedRoutedHostAsync(target, "10.40.5.1");
var ticket = await IssueAsync(subject, hostId);
using var timeout = Timeout();
using var socket = await ConnectAsync(ticket, timeout.Token);
(await ReadTextAsync(socket, timeout.Token)).ShouldBe("bye");
await ReadUntilCloseAsync(socket, timeout.Token);
socket.CloseStatus.ShouldBe(WebSocketCloseStatus.NormalClosure);
(await WaitForClosedAuditAsync(ticket.SessionId, timeout.Token)).CloseReason
.ShouldBe(RelayCloseReason.TargetClosed);
}
[Fact]
public async Task AnIdleSession_IsClosedWithTheIdleCode()
{
// The close code has to arrive, not merely the close. Cancelling a pending receive aborts a .NET
// WebSocket, and an aborted one sends nothing — so a relay that stopped its reader by cancelling
// it would pass a test that only checked the socket ended.
using var target = LoopbackTarget.Echo();
var (subject, hostId) = await SeedRoutedHostAsync(target, "10.40.6.1");
var ticket = await IssueAsync(subject, hostId);
using var timeout = Timeout();
using var socket = await ConnectAsync(ticket, timeout.Token);
await ReadUntilCloseAsync(socket, timeout.Token);
socket.CloseStatus.ShouldBe((WebSocketCloseStatus)RelayProtocol.IdleTimeoutCloseCode);
(await WaitForClosedAuditAsync(ticket.SessionId, timeout.Token)).CloseReason
.ShouldBe(RelayCloseReason.IdleTimeout);
}
[Fact]
public async Task AUserAtTheCap_IsRefusedATicket_AndASocketOverItIsClosed()
{
using var target = LoopbackTarget.Echo();
var (subject, hostId) = await SeedRoutedHostAsync(target, "10.40.7.1");
// Three tickets while nothing is open, so the third reaches the socket and is refused there —
// the authoritative check, which the ticket endpoint's is only an early warning of.
var tickets = new[]
{
await IssueAsync(subject, hostId),
await IssueAsync(subject, hostId),
await IssueAsync(subject, hostId),
};
using var timeout = Timeout();
using var first = await ConnectAsync(tickets[0], timeout.Token);
using var second = await ConnectAsync(tickets[1], timeout.Token);
await RoundTripAsync(first, "one", timeout.Token);
await RoundTripAsync(second, "two", timeout.Token);
var early = await fixture.CreateClientFor(subject)
.PostContractAsync(RelayProtocol.TicketsPath, new RelayTicketRequest(hostId, null));
early.StatusCode.ShouldBe(HttpStatusCode.TooManyRequests);
(await early.Content.ReadProblemAsync()).ShouldNotBeNull().Code.ShouldBe(ProblemCodes.RelayLimitReached);
using var third = await ConnectAsync(tickets[2], timeout.Token);
await ReadUntilCloseAsync(third, timeout.Token);
third.CloseStatus.ShouldBe((WebSocketCloseStatus)RelayProtocol.TooManySessionsCloseCode);
}
// ---- Helpers ----
private static CancellationTokenSource Timeout()
{
var source = CancellationTokenSource.CreateLinkedTokenSource(TestContext.Current.CancellationToken);
source.CancelAfter(FrameTimeout);
return source;
}
private static string NewSubject() => $"relay-{Guid.CreateVersion7():N}";
private async Task<RelayTicketResponse> IssueAsync(string subject, Guid hostId)
{
var response = await fixture.CreateClientFor(subject)
.PostContractAsync(RelayProtocol.TicketsPath, new RelayTicketRequest(hostId, null));
response.StatusCode.ShouldBe(HttpStatusCode.OK);
return (await response.Content.ReadContractAsync<RelayTicketResponse>()).ShouldNotBeNull();
}
private Task<WebSocket> ConnectAsync(RelayTicketResponse ticket, CancellationToken cancellationToken)
{
var client = fixture.Server.CreateWebSocketClient();
client.SubProtocols.Add(RelayProtocol.SubProtocol);
client.SubProtocols.Add(RelayProtocol.TicketProtocolPrefix + ticket.Ticket);
return client.ConnectAsync(
new Uri(fixture.Server.BaseAddress, RelayProtocol.ConnectPath.TrimStart('/')),
cancellationToken);
}
private static async Task RoundTripAsync(WebSocket socket, string text, CancellationToken cancellationToken)
{
await socket.SendAsync(Encoding.UTF8.GetBytes(text), WebSocketMessageType.Binary, true, cancellationToken);
(await ReadTextAsync(socket, cancellationToken, Encoding.UTF8.GetByteCount(text))).ShouldBe(text);
}
/// <summary>
/// Reads until at least <paramref name="expected"/> bytes have arrived, because message boundaries
/// carry no meaning on the relay and an echo may come back split.
/// </summary>
private static async Task<string> ReadTextAsync(
WebSocket socket,
CancellationToken cancellationToken,
int expected = 1)
{
var buffer = new byte[64 * 1024];
var received = 0;
while (received < expected)
{
var result = await socket.ReceiveAsync(buffer.AsMemory(received), cancellationToken);
result.MessageType.ShouldBe(WebSocketMessageType.Binary);
received += result.Count;
}
return Encoding.UTF8.GetString(buffer, 0, received);
}
private static async Task ReadUntilCloseAsync(WebSocket socket, CancellationToken cancellationToken)
{
var buffer = new byte[64 * 1024];
while (true)
{
var result = await socket.ReceiveAsync(buffer.AsMemory(), cancellationToken);
if (result.MessageType == WebSocketMessageType.Close)
{
return;
}
}
}
/// <summary>
/// Waits for the audit row's second write, which lands after the close frame has gone out.
/// </summary>
private async Task<RelaySession> WaitForClosedAuditAsync(Guid sessionId, CancellationToken cancellationToken)
{
while (true)
{
await using (var scope = fixture.CreateScope())
{
var database = scope.ServiceProvider.GetRequiredService<DodoDbContext>();
var session = await database.RelaySessions
.AsNoTracking()
.SingleOrDefaultAsync(s => s.Id == sessionId, cancellationToken);
if (session?.EndedAtUtc is not null)
{
return session;
}
}
await Task.Delay(TimeSpan.FromMilliseconds(50), cancellationToken);
}
}
private async Task<(string Subject, Guid HostId)> SeedRoutedHostAsync(LoopbackTarget target, string address)
{
fixture.RelayNetwork.Route(new IPEndPoint(IPAddress.Parse(address), 22), target.Endpoint);
return await SeedRelayHostAsync(address, 22);
}
private Task<(string Subject, Guid HostId)> SeedRelayHostAsync(
string hostname,
int port,
string? subject = null) =>
SeedHostAsync((hostname, port), subject);
/// <summary>A user, their personal vault, and one host in it — relayed when an address is given.</summary>
private async Task<(string Subject, Guid HostId)> SeedHostAsync(
(string Hostname, int Port)? relay,
string? subject = null)
{
await using var scope = fixture.CreateScope();
var database = scope.ServiceProvider.GetRequiredService<DodoDbContext>();
var user = await FindOrAddUserAsync(database, subject);
var vault = await database.Vaults.FirstOrDefaultAsync(
v => v.OwnerUserId == user.Id,
TestContext.Current.CancellationToken)
?? database.Vaults.Add(new Vault
{
Id = Guid.CreateVersion7(),
Name = "Personal",
OwnerKind = VaultOwnerKind.Personal,
OwnerUserId = user.Id,
KeyGeneration = 1,
CreatedAtUtc = Now,
UpdatedAtUtc = Now,
}).Entity;
var host = new SshHost
{
Id = Guid.CreateVersion7(),
VaultId = vault.Id,
Payload = [1, 2, 3],
KeyGeneration = 1,
PayloadAadVersion = 1,
RelayEnabled = relay is not null,
Hostname = relay?.Hostname,
Port = relay?.Port,
Version = 1,
CreatedAtUtc = Now,
UpdatedAtUtc = Now,
CreatedByUserId = user.Id,
UpdatedByUserId = user.Id,
};
database.Hosts.Add(host);
await database.SaveChangesAsync(TestContext.Current.CancellationToken);
return (user.Subject, host.Id);
}
private async Task<UserAccount> FindOrAddUserAsync(DodoDbContext database, string? subject)
{
if (subject is not null
&& await database.Users.SingleOrDefaultAsync(
u => u.Subject == subject,
TestContext.Current.CancellationToken) is { } existing)
{
return existing;
}
var user = new UserAccount
{
Id = Guid.CreateVersion7(),
Issuer = fixture.IdentityProvider.Authority,
Subject = NewSubject(),
Status = UserStatus.Active,
CreatedAtUtc = Now,
UpdatedAtUtc = Now,
};
database.Users.Add(user);
database.UserKeys.Add(Seed.CurrentKey(user.Id, Now));
return user;
}
/// <summary>A TCP server on loopback, standing in for the machine the relay reaches.</summary>
private sealed class LoopbackTarget : IDisposable
{
private readonly TcpListener listener = new(IPAddress.Loopback, 0);
private readonly CancellationTokenSource stopping = new();
private LoopbackTarget(Func<NetworkStream, CancellationToken, Task> serve)
{
listener.Start();
_ = AcceptAsync(serve);
}
internal IPEndPoint Endpoint => (IPEndPoint)listener.LocalEndpoint;
/// <summary>Writes back everything it reads, on every connection.</summary>
internal static LoopbackTarget Echo() => new(static async (stream, token) =>
{
var buffer = new byte[16 * 1024];
int read;
while ((read = await stream.ReadAsync(buffer, token)) > 0)
{
await stream.WriteAsync(buffer.AsMemory(0, read), token);
}
});
/// <summary>Writes one line and closes, as a server does that refuses the client.</summary>
internal static LoopbackTarget SayThenHangUp(string text) => new(async (stream, token) =>
await stream.WriteAsync(Encoding.UTF8.GetBytes(text), token));
public void Dispose()
{
stopping.Cancel();
listener.Stop();
stopping.Dispose();
}
private async Task AcceptAsync(Func<NetworkStream, CancellationToken, Task> serve)
{
try
{
while (!stopping.IsCancellationRequested)
{
var client = await listener.AcceptTcpClientAsync(stopping.Token);
_ = Task.Run(
async () =>
{
using (client)
{
try
{
await serve(client.GetStream(), stopping.Token);
}
catch (Exception exception) when (exception is IOException or OperationCanceledException or ObjectDisposedException)
{
// The relay hung up, or the test is over.
}
}
},
CancellationToken.None);
}
}
catch (Exception exception) when (exception is SocketException or OperationCanceledException or ObjectDisposedException)
{
// Stopped.
}
}
}
}