DodoSSH/docs/adr/0004-relay-authorization.md

ADR 0004 — Relay as a raw TCP tunnel, and how its targets are authorized

• Status: accepted
• Date: 2026-07-28

Context

Some hosts are not reachable from a user's laptop. The obvious answer is a server-side jump host — but that conflicts directly with ADR 0001: a server that terminates SSH needs plaintext credentials for the target.

A server that dials arbitrary addresses on an authenticated user's behalf is also a textbook SSRF and lateral-movement primitive, aimed at the operator's own network.

Decision

The relay forwards bytes, it does not terminate SSH

The client opens a WebSocket to the backend; the backend pipes raw bytes to host:port. The SSH handshake still terminates on the client, so the relay sees only SSH ciphertext. Zero-knowledge survives. Subprotocol dodossh.relay.v1; no framing of our own, because SSH is already a byte stream.

Two steps, so the WebSocket carries no API authority

1. POST /relay/tickets — full bearer JWT, full ACL context. Takes { hostId }, never a client-supplied address.
2. GET /relay/connect — WebSocket upgrade with the ticket only, zero API access.

Tickets are IDataProtectionProvider payloads (key management and rotation for free) carrying jti, userId, deviceId, hostId, targetIps[], targetPort, exp ≤ 30s, single-use via a unique insert into relay_ticket_use. The ticket travels in Sec-WebSocket-Protocol: dodossh.relay.v1, ticket.<token>, since constrained WebSocket clients cannot set arbitrary headers; a ?ticket= fallback exists and requires query scrubbing in access logs and OTel spans.

Anti-SSRF, in order of importance

1. The server resolves the target from host_id. relay_enabled = true and non-null hostname/port are enforced by a database CHECK constraint. Arbitrary targets are not supported in v1 at all.
2. DNS resolves at ticket-issue time and the resolved IPs go into the ticket; the relay dials the IP, never the name. This is what defeats DNS rebinding, which otherwise breaks naive allow-listing.
3. A non-overridable deny list with no configuration escape: loopback, link-local, 0.0.0.0/8, multicast, cloud metadata (169.254.169.254, 100.100.100.200, fd00:ec2::254), and IPv4-mapped IPv6 normalised and then re-checked — a classic bypass.
4. A configurable layer: Relay:AllowPrivateNetworks defaults true, because RFC1918 is the primary use case for a self-hosted SSH tool, plus allow/deny CIDRs. Ports allow everything except SMTP. Database ports stay open, because forwarding to 5432 is a headline feature — the real control is the ACL: you can only dial hosts in a vault you hold Connect on.
5. Limits: 10 concurrent sessions per user, 200 per node, 12 h maximum, 10 min idle, 5 s connect.

Why host addresses are plaintext

Encrypting hostnames sounds strictly better and is not. The relay must resolve its target server-side or point 1 above collapses and the relay becomes an authenticated open TCP proxy — a worse risk than the metadata it would protect. Plaintext address and port are therefore stored only when the user opts that host into relay, enforced by the CHECK constraint. Everything else about a host — username, notes, jump chain, options — is always ciphertext, and there is no plaintext host label at all, because ACL administration runs on the client, which can decrypt names.

Searchability is explicitly not the argument: vaults hold thousands of items, not millions, so the client syncs everything and searches in memory. The relay and audit arguments are the real ones.

Consequences

• No session recording or command auditing is possible in relay mode. The relay sees ciphertext. Do not promise otherwise. Recording would need a separate, explicitly non-zero-knowledge "recorded bastion" mode opted into per host.
• Useful audit remains: target_host:port, duration, byte counts, close reason, client IP.
• Backpressure comes from System.IO.Pipelines with pauseWriterThreshold: 1 MiB. When the WebSocket peer is slow, FlushAsync stops completing, which stops reading the socket, which lets TCP's own receive window throttle the origin end-to-end. No custom flow control, ~2 MiB bounded per session — which is what makes 200 sessions per node viable.
• The relay must not hold a DbContext for the session lifetime. Insert the row, dispose the scope, relay, then open a fresh scope to write the close row. Otherwise the connection pool dies around 100 concurrent sessions.
• Tickets are stateless-verifiable and relay_ticket_use is the only shared state, so any node accepts any ticket: plain round-robin, no session affinity. That table is also the extraction seam — a standalone relay process needs the Data Protection key ring and one table, no ACL code. Extraction is worthwhile eventually because long-lived connections and short requests have opposite scaling and rollout profiles.
• Graceful shutdown sends close 1001 and drains for 30 s, so a docker compose up -d does not guillotine live shells.
• On the client, SSH.NET cannot be handed a pre-connected stream, so the relay is reached via a loopback TCP bridge. The same bridge provides ProxyJump via a SOCKS5 dynamic forward — one mechanism, two features.

Rejected

• Server terminates SSH (a true bastion). Enables recording and central credential control; destroys zero-knowledge. Out of scope, possibly a separate product line.
• Client-supplied target address. One line of convenience, and the relay becomes an open proxy into the operator's network.
• Allow-listing by hostname. Defeated by DNS rebinding.

Implementation notes

Built in DodoSSH.Api/Features/Relay and, on the client, RelayBridge and ServerRelay; see docs/reaching-a-host-you-cannot-dial.md, "What step 3 built". Three places differ from the text above:

• Backpressure is an awaited copy loop, not System.IO.Pipelines. Each direction reads one buffer and writes it before reading again. The property is the same — a slow peer stops the read, and TCP throttles the origin — and the bound is tighter: two 32 KiB buffers per session.
• There is no ?ticket= fallback. Both clients can set a subprotocol, and the fallback's cost — a bearer credential in the URL — was the reason it needed scrubbing at all. It can be added if a constrained client ever needs it; the scrubbing requirement stands.
• The ticket carries no device id. The server does not see a device on an ordinary request, so there was nothing to put there. PortForwardId on the request is refused: a forward's port is ciphertext, and honouring one would mean taking the port from the client.

The loopback bridge serves the relay only. SSH.NET's ForwardedPortDynamic already is the jump-host path's listener, so "one mechanism, two features" is true one level down: both features reach their target through a loopback SOCKS5 proxy named on the connection request.