ssh3

Abstract

SSH3: faster and rich secure shell using HTTP/3, checkout our article here: https://arxiv.org/abs/2312.08396 and our Internet-Draft: https://datatracker.ietf.org/doc/draft-michel-ssh3/

Here's a concise, professional technical briefing for the SSH3 repository, written in the style of a senior AI engineer consultant.

The Problem

SSH3 reimagines the SSH protocol mapped onto HTTP/3 and QUIC, but the codebase shows significant structural debt. A static analysis of 43 Go files found 12 measurable issues across 4 categories—including deep nesting in critical control flow, duplicated auth logic blocks, oversized entry-point files, and stale TODOs. These aren't minor nits; they affect how quickly a new engineer can safely modify authentication, connection handling, or wire protocol logic.

What This Does

SSH3 is a collection of 8 semi-independent projects sharing a Go codebase, not a monolithic product. The primary domains are: util (8 files, logger, tilde expansion, wire helpers), auth (6 files, OIDC/PKI plugins), client (5 files, connection & agent forwarding), cmd (5 files, CLI entry points), message (4 files, SSH wire protocol), server_auth (3 files, auth plugin scaffolding), integration_tests (2 files), and internal (1 file).

Entry points are explicit: cmd/plugin_endpoint/main.go:8 reaches 114 functions; cmd/ssh3.go:368 (ClientMain) reaches 103. The call graph is dense—ReadVarInt is called from 14 places, ParseSSHString from 11, ChannelID from 9. cmd/ssh3-server.go (832 lines) and cmd/ssh3.go are oversized, and auth logic is duplicated across client/privkey_auth.go, client/pubkey_auth.go, client_auth.go, and channel.go — 41 repeated 6-line blocks.

The project touches the filesystem via os.ReadFile (in ClientMain and openAgentSocketAndForwardAgent) and runs external commands via os.Chown. No Dockerfile is committed; build is Makefile-driven.

How It Is Wired

Execution starts at cmd/plugin_endpoint/main.go:8 (main) or cmd/ssh3.go:368 (ClientMain). From ClientMain, flow reaches Dial, which fans into IntoIdentity, then EstablishClientConversation → GetProtocolVersion. Auth flows through client_auth.go (defines NewPasswordAuthMethod, NewOidcAuthMethod, DoPKCE), then into auth/plugins/pubkey_authentication/client/pubkey_auth.go and privkey_auth.go, which each contain duplicated 6-line auth blocks. Wire protocol parsing lives in message/channel_request.go (43 functions, defines Length, Write, ParseRequestMessage, ParsePtyRequest). channel.go defines buildHeader, Error, and connection error types, called from 9 other files. util/wire.go provides ReadVarInt/WriteVarInt primitives called from across the stack.

The widest blast radius: cmd/ssh3-server.go (25 functions, 13 callees, reads/writes files) and cmd/ssh3.go (10 functions, 10 callees, config + QUIC setup). client/client.go (9 functions, reads/writes files) is the other file with filesystem effects. No circular imports were detected, but the 8-project portfolio structure means a change in auth/plugins can ripple into client, cmd, and message depending on the code path.

How To Use It

Build: make (Makefile present at root). No Dockerfile; binaries are built via Go modules (go.mod + go.sum).

Run server: ./ssh3-server (built from cmd/ssh3-server/main.go) or ssh3-server from the root Make target.

Run client: ssh3 from cmd/ssh3/main.go.

Configuration: No config file was detected in the structure. The README references environment-driven setup (install instructions link to the repo), but no .env, yaml, or toml was found in the file listing. getConnectionMaterialFromURL in cmd/ssh3.go:289 is the nearest thing to config resolution—it parses a URL host/port and loads SSH material, but the exact env vars or file paths it uses are not evident from the static analysis.

Missing: No licence was found in the file structure despite the LICENSE being listed in the repo root; the Makefile and go.mod are present.

Real-World Use

An engineer could deploy an SSH3 server in a sandbox to test QUIC-accelerated session establishment (3 RTTs vs. 5–7 for SSHv2), or experiment with OAuth 2.0/OpenID Connect login flows via the OIDC plugin in auth/oidc/openid_connect.go. The client supports public-key auth through auth/plugins/pubkey_authentication/client/pubkey_auth.go and privkey_auth.go. UDP forwarding is available but not yet widely tested—it’s defined in cmd/ssh3-server.go (forwardUDPInBackground).

Code Health & Issues

The static analysis found 12 issues across 4 categories:

High cognitive_load - Deep nesting x7: client/client.go, cmd/ssh3-server.go, server.go. Max indentation depth 8; control flow hard to follow. Fix: flatten with early returns/guard clauses.
High clarity - Duplicated code blocks: 41 repeated 6-line blocks across auth/plugins/pubkey_authentication/client/privkey_auth.go, client/client.go, auth/plugins/pubkey_authentication/client/pubkey_auth.go, client_auth.go. Fix: extract shared helpers; DRY the repeated logic.
Medium cognitive_load - Oversized file x2: cmd/ssh3-server.go (832 lines), cmd/ssh3.go. Fix: split into cohesive units by responsibility.
Low clarity - 3 TODO/FIXME markers across channel.go, cmd/ssh3-server.go. Fix: triage into issues or resolve; stale markers erode signal.

SDLC observations: tests and CI are present (GitHub Actions), lockfile is present, but no Dockerfile is committed. No committed secrets were found.

The Bottom Line

SSH3 is a technically interesting research prototype that maps SSH semantics onto HTTP/3/QUIC, offering faster session establishment (3 RTTs) and modern auth methods (OIDC, OAuth). The codebase is functional but early-stage: oversized CLI files, duplicated auth logic, and deep nesting make it harder than necessary to modify or audit. It’s suitable for sandbox experimentation or academic review, not production deployment without expert cryptographic review. Engineers interested in QUIC-based transport or next-gen SSH auth should watch this, but expect to do significant refactoring to work confidently in the code.

Word count: 528