alktunnels/docs/research/ssh-socks5-survey.md

status, last_updated

status	last_updated
draft	2026-09-06

SSH & SOCKS5 Tunnel Survey (Phase 0)

This document completes the last open survey item on the Phase 0 convergence checklist: SSH and SOCKS5 addressing/framing prior art, scoped to what alktunnels actually needs. It complements the tun2proxy UDP-gateway prior art already in phase-0-findings.md (§Prior art: tun2proxy UDP gateway) and answers the residue questions on OQ-TN-01, OQ-TN-02, OQ-TN-07, and OQ-TN-09.

Sources: RFC 4254 §4–7 (SSH Connection Protocol), RFC 1928 (SOCKS5), russh (/workspace/russh — Rust SSH implementation), tun2proxy's SOCKS5 client (/workspace/tun2proxy/src/socks.rs, src/proxy_handler.rs, src/lib.rs), alktty's negotiation/control frames (/workspace/@alkdev/alktty/src/negotiation.rs, src/wire.rs, src/control.rs), and the alknet-channels POC tunnel handler (/workspace/alknet-channels-poc/src/tunnel_handler.rs).

SSH forwarding model

RFC 4254 §5.1 — the channel-open envelope

Every SSH channel open (RFC 4254 §5.1) is:

byte      SSH_MSG_CHANNEL_OPEN        (90)
string    channel type                (US-ASCII name)
uint32    sender channel              (opener's local id)
uint32    initial window size
uint32    maximum packet size
....      channel-type-specific data

The channel-type-specific data is the SSH analogue of alktunnels' params: a type-tagged payload appended to a generic open envelope. SSH's "channel type" string plays the role of the ALPN/substrate discriminator; the trailing bytes play the role of the resource identification.

RFC 4254 §7.2 — direct-tcpip and forwarded-tcpip

Both TCP forwarding channel types share one payload shape (TcpChannelInfo in russh, russh/src/parsing.rs:116-153):

string    host to connect        (direct-tcpip)   |  address that was connected (forwarded-tcpip)
uint32    port to connect        (direct-tcpip)   |  port that was connected   (forwarded-tcpip)
string    originator IP address
uint32    originator port

• direct-tcpip (RFC 4254 §7.2, second block): sent by the side that accepted a local TCP connection; 'host to connect' may be a domain name or numeric IP; the recipient dials it. This is the -L/-D data path.
• forwarded-tcpip (§7.2, first block): sent by the side that accepted a connection on a remotely-requested forwarded port; 'address that was connected' is the forwarded listen address, and the recipient is the side that requested the forward. This is the -R data path.
• The originator pair is informational. RFC 4254 §7.2: "the 'originator IP address' is the numeric IP address of the machine from where the connection request originates" — it is for the recipient's logging/policy, not routing. russh carries it verbatim (channel_open_direct_tcpip(host, port, originator_address, originator_port), russh/src/client/mod.rs:718-741), and the example passes the real accepted peer address (russh/examples/client_open_direct_tcpip.rs:135-143). It is the one piece of SSH addressing that has no alktunnels analogue in the base params — it is metadata, not routing.

OpenSSH extension for unix sockets (present in russh, russh/src/client/session.rs:90-100): direct-streamlocal@openssh.com carries only socket_path plus two reserved fields ("" string, 0u32) — the same 4-slot shape with the address slots emptied. This is prior art for "a new substrate = same open-op shape, degenerate address fields," which supports OQ-TN-01's substrate-discriminator reframe.

RFC 4254 §7.1 — the -R registration (tcpip-forward)

Remote forwarding is registered with a global request, not a channel:

byte      SSH_MSG_GLOBAL_REQUEST      (80)
string    "tcpip-forward"
boolean   want reply
string    address to bind             ("" | "0.0.0.0" | "::" | "localhost" | "127.0.0.1" | ...)
uint32    port number to bind

Reply is SSH_MSG_REQUEST_SUCCESS (81) — carrying uint32 port that was bound when the client passed port 0 (server allocates) — or SSH_MSG_REQUEST_FAILURE (82). Cancellation is the cancel-tcpip-forward global request (§7.1). After registration, each accepted connection arrives as a forwarded-tcpip channel open from the listening side (russh: server/session.rs:1090-1104, server/session.rs:1186-1233 for the global request; the RFC notes channel opens may keep arriving until the cancel reply lands).

This is the only SSH mechanism with no alktunnels counterpart yet: a "please listen on your side, then open channels to me per accept" advertisement. It maps onto OQ-TN-03's resolved model as an assembly-layer concern, but the registration/lifecycle shape (register → per-accept channel-open → cancel) is the prior art for the reverse-flow POC (OQ-TN-10 #2).

Open-failure path (RFC 4254 §5.1)

byte      SSH_MSG_CHANNEL_OPEN_FAILURE   (92)
uint32    recipient channel              (the opener's channel id)
uint32    reason code
string    description                    (UTF-8)
string    language tag

Reason codes (RFC 4254 §5.1; russh lib_inner.rs:405-423):

code	symbolic name	meaning
1	SSH_OPEN_ADMINISTRATIVELY_PROHIBITED	policy/ACL rejection
2	SSH_OPEN_CONNECT_FAILED	target dial failed
3	SSH_OPEN_UNKNOWN_CHANNEL_TYPE	unsupported channel type
4	SSH_OPEN_RESOURCE_SHORTAGE	limits exhausted
0xFE000000–0xFFFFFFFF	private use	implementation-specific

russh's handling confirms the mechanics end to end: the server dispatches per channel type and answers fail(reason, message) on rejection (server/encrypted.rs:1244-1250 for unknown types, server/encrypted.rs:1254-1278 finalize_channel_open answering SSH_OPEN_ADMINISTRATIVELY_PROHIBITED with "Rejected" when the handler says no); the client parses the failure, removes the channel, and surfaces ChannelMsg::OpenFailure(reason) plus the description/language strings to the handler (client/encrypted.rs:414-434). Key structural property: the open failure is a first-class reply to the open, carrying a reason code plus a human-readable description, and the channel never exists on the opener's side afterward.

Which side opens what (-L / -R / -D at protocol level)

• -L (local forward): the client accepts on a local port, and for each accept opens a direct-tcpip channel naming the target; the server dials. Consumer opens, producer handles — the POC's shape.
• -R (remote forward): the client sends tcpip-forward (global request) to register the listen; the server then opens forwarded-tcpip channels per accepted connection toward the client, which dials the real target. Producer-side accept, consumer-side dial — the roles are the same pair, entry point on the other machine (matches the phase-0 hub model resolution of OQ-TN-03).
• -D (dynamic/SOCKS): the client runs a SOCKS server locally; for each SOCKS CONNECT it parses the target out of the SOCKS request and opens a direct-tcpip channel with that target (stackoverflow.com/questions/78045232; confirmed by OpenSSH's sshd(8)/ssh(1) "dynamic forward" description). At the SSH protocol level -D is indistinguishable from -L: one direct-tcpip channel per application connection, target chosen per-channel by the SOCKS layer in the client. There is no "dynamic" channel type on the wire. This is direct protocol-level confirmation of the phase-0 resolution that -D = "just tunnel a socks5 connection" (OQ-TN-08): SSH itself implements -D exactly as "SOCKS5 server in front of per-connection direct-tcpip opens."

SSH has no UDP forwarding. RFC 4254 defines only TCP/X11/session channels; there is no direct-udp/forwarded-udp anywhere in the RFC or in OpenSSH. russh confirms: zero occurrences of "udp" in russh/src/ (grep clean, checked 2026-09-06). The only "SSH with UDP" prior art is SSH3 (draft-michel-remote-terminal-http3), a different protocol over HTTP/3, not SSH-the-RFC. Correction to the phase-0 doc: OQ-TN-02's line "SSH's -D UDP associate tunnels UDP as a stream with per-datagram framing re-added by the tunnel protocol (e.g. SOCKS5 UDP over TCP)" is a category error — SSH -D carries the SOCKS5 TCP control connection only; SOCKS5 UDP ASSOCIATE datagrams never traverse an SSH channel in any standard SSH implementation. The real UDP-over-stream prior art is tun2proxy's udpgw (already analyzed) and SOCKS5's own UDP relay (below).

SOCKS5 model

ATYP addressing (RFC 1928 §5)

Every address field (DST.ADDR in requests, BND.ADDR in replies) is:

ATYP (1 byte):
  0x01  IPv4        → 4 octets
  0x03  DOMAINNAME  → 1 length octet + name (no NUL), max 255
  0x04  IPv6        → 16 octets
+ port (2 bytes, network order)

This is the encoding udpgw reuses verbatim per data packet (udpgw.rs:68-76), and the encoding the phase-0 doc already flagged as concrete prior art for scheme-tagged addressing.

CONNECT flow (RFC 1928 §3–6)

1. TCP connect to the SOCKS port (1080).
2. Method negotiation: VER | NMETHODS | METHODS → VER | METHOD (0x00 no-auth, 0x02 user/pass, 0xFF no acceptable methods).
3. Optional method sub-negotiation (user/pass per RFC 1929).
4. Request: VER | CMD | RSV(0x00) | ATYP | DST.ADDR | DST.PORT with CMD 0x01 CONNECT / 0x02 BIND / 0x03 UDP ASSOCIATE.
5. Reply: VER | REP | RSV | ATYP | BND.ADDR | BND.PORT.

Reply codes (RFC 1928 §6):

REP	meaning
0x00	succeeded
0x01	general SOCKS server failure
0x02	connection not allowed by ruleset
0x03	network unreachable
0x04	host unreachable
0x05	connection refused
0x06	TTL expired
0x07	command not supported
0x08	address type not supported

On failure the server MUST close the TCP connection within 10 seconds of sending the reply (§6 "Reply Processing") — the same "error-then-close" shape SSH open-failure has, and the same shape OQ-TN-09's accepted direction implies for tunnel establishment (control frame, then channel death).

tun2proxy's client side implements exactly this state machine: SocksState::{ClientHello, ServerHello, SendAuthData, ReceiveAuthResponse, SendRequest, ReceiveResponse, Established} (socks.rs:11-20), with the reply parsed in receive_connection_status (socks.rs:226-248) and non-Succeeded replies aborting the session. The ProxyHandler trait (proxy_handler.rs:9-22) is the handler-inversion point — same shape as alktty's TtyBackend/this crate's OQ-TN-05 question, with get_udp_associate() as the UDP-specific handle.

UDP ASSOCIATE flow (RFC 1928 §7)

1. The client sends UDP ASSOCIATE over the TCP control connection, with DST.ADDR/DST.PORT = the client's expected datagram source (all zeros if unknown — the common case; tun2proxy sends Address::unspecified(), socks.rs:214-215).
2. The reply's BND.ADDR/BND.PORT is the relay endpoint the client must send UDP datagrams to — this is how the client learns where to send (socks.rs:241-244 stores it as udp_associate).
3. Each datagram to/from that endpoint carries the UDP request header:

+----+------+------+----------+----------+----------+
|RSV | FRAG | ATYP | DST.ADDR | DST.PORT |   DATA   |
+----+------+------+----------+----------+----------+
| 2  |  1   |  1   | Variable |    2     | Variable |

RSV is 0x0000; FRAG is the fragmentation sequence number (0 = standalone, 1–127 = position, high bit = end-of-sequence); fragmentation is optional and implementations that don't support it MUST drop datagrams with FRAG ≠ 0 (§7). 4. The relay server pins the association to the client's source IP and drops datagrams from any other source (§7). The association terminates when the TCP control connection terminates (§6) — the TCP session is the UDP flow's lifecycle anchor. 5. Replies are relayed silently; there is no per-datagram acknowledgment or error channel. Errors are signaled only by dropping, or by the control connection's reply codes.

tun2proxy's non-udpgw path implements this verbatim: handle_udp_associate_session (lib.rs:625-724) wraps each datagram in a UdpHeader (the RSV/FRAG/ATYP/DST.ADDR/DST.PORT header) toward the relay and strips it on the way back.

What udpgw dropped vs kept from RFC 1928

udpgw's packet format (udpgw.rs:55-88) is LEN(u16 BE) | FLAGS(u8) | CONN_ID(u16) | [SOCKS5 address] | DATA — "referenced from SOCKS5 packet format, with additional flags and connection ID fields" (udpgw.rs:57):

• Kept: the ATYP/DST.ADDR/DST.PORT address encoding per datagram (§5's scheme-tagged addressing, unchanged).
• Kept (implicitly): per-datagram boundary framing — but udpgw re-derives it with an explicit LEN prefix, because it rides a TCP stream, not a datagram socket. SOCKS5 UDP never needed a length prefix because UDP itself preserves boundaries; udpgw's LEN is the price of moving the relay onto TCP.
• Dropped: RSV — pointless over a stream (it exists only to word-align the UDP header).
• Dropped: FRAG — fragmentation over a reliable in-order stream is unnecessary; udpgw caps datagram size with an MTU check instead (parse_udp_response rejects data.len() > udp_mtu, udpgw.rs:527).
• Dropped: the TCP-control-connection lifecycle model — SOCKS5 binds each UDP association to a TCP session and learns the relay endpoint from a reply; udpgw multiplexes all flows over pooled gateway connections with a client-allocated CONN_ID(u16) (udpgw.rs:66) and replaces "reply carries the relay endpoint" with "the gateway connection is the endpoint."
• Added: FLAGS — KEEPALIVE(0x01) and ERR(0x20) as address-less, data-less control packets (udpgw.rs:21-26), giving the stream a minimal frame vocabulary: DATA / KEEPALIVE / ERR.
• Dropped: reply codes — the ERR flag carries no reason information (build_error_packet is just header + conn_id, udpgw.rs:151-153). SOCKS5's 9 reply codes and SSH's 4 reason codes
  • description both collapse to a single opaque bit. This is the weakest error vocabulary of the three prior arts.

Comparison: error/establishment vocabularies

	SSH open-failure (RFC 4254 §5.1)	SOCKS5 reply (RFC 1928 §6)	udpgw flags (udpgw.rs:21-26)	alktty ctrl frames (control.rs:58-93)
establishment ack	CHANNEL_OPEN_CONFIRMATION (91)	REP 0x00 + BND.ADDR/BND.PORT	(none — data just flows)	negotiation frame reply (negotiation.rs)
failure signal	CHANNEL_OPEN_FAILURE (92)	REP 0x01–0x08	ERR flag packet	length-prefixed JSON error frame (error_response_bytes, negotiation.rs:263-277)
failure granularity	4 IANA codes + private range	8 codes	1 opaque bit	free-form JSON {"error": ...}
human-readable detail	description string + language tag	none (codes only)	none	JSON fields
channel survives failure	no — channel removed client-side (client/encrypted.rs:421-427)	TCP connection closed ≤10s	flow-level (conn_id), stream survives	stream never established
in-band vs op-level	in-channel reply message	control-connection reply	in-stream flag packet	first frame on the stream

Observations for the alktunnels control-frame ADR (OQ-TN-09):

• SSH is the only prior art that puts a reason code + description in the failure reply; SOCKS5 has codes but no detail; udpgw has neither. The alktty-shaped JSON control frame can carry both (a machine code field and a detail string) at zero structural cost — it is the strictly richest of the four, and it is already the accepted direction.
• All four agree on the lifecycle consequence: establishment failure kills the channel/connection before data flows. None of them supports "fail the open but keep the channel for a retry" — there is no prior art for a retry-without-reopen path, and none is needed (the consumer just opens a new channel).
• SSH's reason-code taxonomy (policy / dial-failed / unknown-type / resource-shortage) is a useful minimal set to mirror in the control frame's error field: it covers exactly the four failure classes an open handler can produce (ACL denied, dial failed, unknown substrate/resource, channels limits). SOCKS5's set adds network-unreachable vs host-unreachable vs connection-refused granularity inside "dial failed" — worth considering as sub-codes or just leaving to the detail string.

UDP: endpoint-at-open vs per-datagram

What each prior art does:

	endpoint model	where the address lives	flow multiplexing
SSH (TCP only)	fixed at open	direct-tcpip/forwarded-tcpip payload	none needed — one channel = one TCP connection
SOCKS5 UDP ASSOCIATE	relay endpoint fixed at open (BND.ADDR/BND.PORT); destination per-datagram	DST.ADDR/DST.PORT in each UDP header	one association per control connection; source-IP pinning
udpgw	destination per-datagram	SOCKS5 address in each DATA packet	CONN_ID(u16) client-allocated, many flows per gateway stream
alktunnels base open-op (OQ-TN-01 reframe)	resource fixed at open	params (resource id + substrate)	the channel ID itself

Implications for a channels-based tunnel:

1. The two prior arts disagree because they solve different problems. SOCKS5/udpgw are proxies: the client picks arbitrary destinations per datagram, so per-datagram addressing is intrinsic. alktunnels' base open-op is a resource access: the consumer names a produced resource, and the producer owns the backing endpoint. Under the hub model (phase-0 §Prior art), endpoint-at-open is the natural fit for the base op — the resource is the endpoint binding, and per-datagram addressing would reintroduce exactly the "general addressing in params" that the OQ-TN-01 reframe removed.
2. Per-datagram addressing belongs to the -D/dynamic composition path, not the base op. If a UDP SOCKS5-style service is produced, the consumer tunnels to it (base op, substrate udp or even tcp for the control leg) and the SOCKS5 UDP header rides inside the tunnel payload — exactly as tun2proxy's socks path does over its proxy connection (lib.rs:672-687). The base protocol never sees per-datagram addresses.
3. If a base-op UDP resource ever needs multiple remote endpoints (a "UDP gateway" resource), the udpgw shape is the template: length-prefixed datagrams, SOCKS5-style per-datagram address, a flow key, and DATA/KEEPALIVE/ERR flags — all inside the channel, self-describing, invisible to the open-op params. That keeps OQ-TN-07's option A (single alk/tunnel ALPN) viable: udpgw proves one framing can carry the datagram case over a stream substrate without the ALPN knowing.
4. The channel ID replaces CONN_ID. udpgw needs CONN_ID because it multiplexes over 1–5 pooled TCP streams (a throughput choice, UDPGW_MAX_CONNECTIONS = 5, udpgw.rs:15); channels already multiplexes per channel ID with a 256-channel cap. One channel per UDP flow (or per association) needs no protocol-level flow key — the OQ-TN-02 residue question "is a u16 conn-id vocabulary right" resolves to no: the channel ID does the demux, and a conn-id inside the channel would be a second demux layer (AGENTS.md convention 10: don't build a second demux/mux).
5. KEEPALIVE likely drops too. udpgw's 30s heartbeats exist because its gateway streams are long-lived TCP connections that NAT middleboxes silently drop; on channels, transport liveness is the alkcall layer's concern (phase-0 §Prior art already noted this). Flow-level idle expiry (the udp_timeout concept) remains producer-side bookkeeping, not a wire frame.

What NOT to carry over

Explicit anti-prior-art — mechanisms the prior arts have that alkcall channels already owns, or that don't survive the substrate change:

1. SSH window updates (SSH_MSG_CHANNEL_WINDOW_ADJUST, RFC 4254 §5.2). SSH multiplexes channels over one stream with sender-side window accounting; alkcall channels already provides bounded per-channel buffers and backpressure (alkcall ADR-040/041). A tunnel-level window mechanism would be a second backpressure layer (AGENTS.md convention 10). russh's whole WindowSizeRef machinery (channels/mod.rs:116-139) is the thing we don't build.
2. SSH's maximum packet size negotiation. Channels owns chunk sizing; the tunnel codec inherits it. (udpgw's MTU cap is the datagram-flavored version — also producer-side, not wire.)
3. SSH's sender/recipient dual channel numbering. Channels allocates monotonic IDs with a single namespace (alkcall ADR-034/040); the open op's channel ID is already agreed before the handler runs. No ID translation in the tunnel protocol.
4. SOCKS5's FRAG byte. Fragmentation over a reliable in-order channel is redundant — udpgw already dropped it for exactly that reason. If a datagram is too big for the channel's buffer, the producer-side MTU cap rejects it; reassembly is not the tunnel's job.
5. SOCKS5's method negotiation / auth sub-negotiation. alkcall's AuthContext/AccessControl at the connection and open-op layers owns authentication (AGENTS.md convention 13); SOCKS5 auth exists only because SOCKS rides raw TCP. The -D composition inherits alkcall's auth for free.
6. SOCKS5's BND.ADDR/BND.PORT reply semantics. The "reply tells you where to send datagrams" pattern exists because SOCKS5's UDP relay is a separate socket from the control connection. On channels there is no second endpoint — the channel is the endpoint. An establishment-ack control frame needs no address payload.
7. udpgw's KEEPALIVE flag and connection pooling. Both are transport-layer concerns (NAT keepalive, TCP stream count) that channels absorbs (see §UDP above).
8. SSH's tcpip-forward port-0 "server allocates a port" reply. The hub model produces named resources, not dynamically-allocated listen ports; if a reverse-flow advertisement ever needs an allocation reply it is an assembly-layer concern, and the ops listing (OQ-TN-08) is how the allocated name propagates.

Answers for the OQ ledger

OQ-TN-01 residue (params field set; open-failure error path)

Minimal field set. The SSH/SOCKS5 prior art supports the reframe's two-field shape:

• SSH's direct-tcpip payload is exactly "target + (informational originator)" — and the informational half is the only part with no alktunnels analogue, because ACL/identity is carried by the channels open-op machinery, not by params. The routing-relevant payload reduces to one address-ish field + one port — which under the resource model collapses further into one resource identifier.
• OpenSSH's direct-streamlocal shows the extensibility pattern: same open-op shape, degenerate address slots, new type string. For alktunnels this maps to: params = { "resource": <id>, "substrate": "tcp" | "udp" | <extensible> } with any substrate-specific detail owned by the producer's registry, not the wire. A new substrate is a new substrate value, not a format change — the same additive property SSH gets from channel-type strings and SOCKS5 gets from ATYP values.
• SOCKS5's ATYP (v4/domain/v6) is not needed in the base params: it is per-datagram/per-request addressing for the dynamic path, which rides inside the tunnel payload (see §UDP). If the resource identifier is ever an address rather than a name, ATYP's scheme-tagged encoding is the fallback shape — but the resource-name direction makes that unnecessary.

Open-failure error path. The prior art converges on: a structured failure reply to the open, with a reason code, followed by connection/channel teardown; the channel never carries data after a failed open. Concretely for alktunnels (feeding the OQ-TN-09 frame ADR):

• Establishment result rides the accepted control-frame direction (phase-0 OQ-TN-09): a single JSON frame before any data chunk, with at minimum {"ok": true} or {"error": <code>, "detail": <string>}.
• The reason-code vocabulary should cover SSH's four (policy-denied / dial-failed / unknown-resource-or-substrate / resource-shortage) — they map 1:1 onto what an open handler can actually produce: AccessControl denial, target dial failure, unregistered resource/substrate, channels limits. SOCKS5's finer network/host/refused granularity can live in detail rather than more codes (v1 minimalism; codes are wire-stable, detail strings are not).
• udpgw's opaque ERR bit is the counterexample to avoid: an error the consumer cannot distinguish "ACL denied" from "target down" makes client UX and retry policy impossible.

OQ-TN-02 fork (endpoint-at-open vs per-datagram)

Resolved as a split by path, not a single choice (§UDP above):

• Base open-op UDP resources: endpoint-at-open. The resource identifies the endpoint; one channel = one UDP flow (or one pinned association). This aligns with resource naming, needs no in-band addressing, and matches how the hub model produces any resource. Boundary preservation inside the channel is still per-datagram length framing (tun2proxy-proven) — endpoint-at-open is about addressing, not about dropping the LEN prefix.
• Dynamic/-D UDP (SOCKS5-style): per-datagram addressing inside the tunnel payload, using the SOCKS5 UDP header or udpgw's ADDR-bearing packet format — composed at the assembly layer, never in base params.
• The channel ID replaces udpgw's CONN_ID (no second demux); KEEPALIVE drops; the ERR flag's job is done better by the control frame.

OQ-TN-07 (ALPN strategy)

The udpgw precedent (one framing over a plain stream, datagram self-describing) already favored option A; the SSH/SOCKS5 survey strengthens it:

• SSH uses one channel mechanism for all forwarding types; the type string is per-open metadata, not a separate transport. SOCKS5 likewise runs CONNECT and UDP ASSOCIATE over the same control connection with a CMD discriminator.
• With endpoint-at-open for base UDP resources (OQ-TN-02 answer), the datagram framing is confined to UDP-substrate channels and is self-describing from the first chunk (a length prefix is unambiguous against raw pass-through only if TCP channels are also framed — see the codec decision on the convergence checklist; if TCP is raw pass-through, the substrate discriminator in params tells the handler which framing to expect, which is exactly option A's "substrate is a params field").
• Option B (alk/tunnel-dgram) remains defensible only if Phase 1 wants structurally different framing from byte zero with no params-dependent dispatch. Prior art gives no reason to prefer that.

OQ-TN-09 (establishment/error frame vocabulary)

Inputs from this survey (§Comparison table above):

• Shape: alktty-style JSON control frame (already the accepted direction) — it is the richest vocabulary of the four prior arts (code + detail) and needs no new framing layer.
• Content: an establishment ack (SSH's CONFIRMATION / SOCKS5's success reply analogue) and a failure frame with a small reason-code set (SSH's four) + detail string. Failure ⇒ channel closes before data (all four prior arts agree).
• What the frame does not need: window adjustments (channels owns backpressure), keepalives (channels owns liveness), fragmentation (not the tunnel's job), per-datagram error replies (SOCKS5 relays silently; udpgw's ERR is flow-level at most — dial errors are channel-closing per the accepted direction).

References

• RFC 4254, The Secure Shell (SSH) Connection Protocol — §4 (global requests), §5.1 (channel open / open-failure reason codes), §5.2 (window adjust), §7.1 (tcpip-forward), §7.2 (direct-tcpip, forwarded-tcpip). https://www.rfc-editor.org/rfc/rfc4254.txt
• RFC 1928, SOCKS Protocol Version 5 — §3 (method negotiation), §4 (request format), §5 (ATYP addressing), §6 (replies, UDP ASSOCIATE lifecycle), §7 (UDP relay header, FRAG). https://www.rfc-editor.org/rfc/rfc1928.txt
• russh — /workspace/russh:
  • russh/src/parsing.rs:8-153 — OpenChannelMessage parse, TcpChannelInfo (direct-tcpip/forwarded-tcpip payload), StreamLocalChannelInfo, confirm/fail encoders.
  • russh/src/lib_inner.rs:402-423 — ChannelOpenFailure reason enum.
  • russh/src/client/mod.rs:675-760 — public channel_open_* API; client/session.rs:74-100 — wire encoding of direct-tcpip / direct-streamlocal payloads.
  • russh/src/server/encrypted.rs:1150-1278 — server-side open dispatch, finalize_channel_open failure path; server/session.rs:1055-1115, 1186-1233 — server-initiated opens and tcpip-forward global request.
  • russh/src/client/encrypted.rs:414-434 — client-side open-failure handling.
  • russh/examples/client_open_direct_tcpip.rs:129-184 — the -L pump shape (two select arms, EOF handling).
  • Confirmed: no UDP anywhere in russh/src/ (grep, 2026-09-06).
• tun2proxy — /workspace/tun2proxy:
  • src/udpgw.rs:55-88 — packet format doc comment; :21-26 flags; :147-153 keepalive/error packet builders; :527 MTU cap. (Analyzed in phase-0-findings.md §Prior art.)
  • src/socks.rs:11-20 — SOCKS5 client state machine; :213-224 request encoding (UDP ASSOCIATE sends unspecified address); :226-248 reply parsing + udp_associate capture.
  • src/proxy_handler.rs:9-32 — ProxyHandler/ProxyHandlerManager inversion point.
  • src/lib.rs:625-724 — handle_udp_associate_session: SOCKS5 UDP header added/stripped per datagram over the relay endpoint.
• alktty — /workspace/@alkdev/alktty:
  • src/negotiation.rs:64-120 — NegotiateRequest (self-contained JSON open-op precedent); :127-277 — length-prefixed framing + error_response_bytes (the error-frame shape).
  • src/wire.rs:1-57 — 5-byte chunk codec, stream types, zero-length sentinels.
  • src/control.rs:58-108 — ControlMessage JSON control frames.
• alknet-channels POC — /workspace/alknet-channels-poc:
  • src/tunnel_handler.rs:24-59 — the two-pump tunnel handler (no establishment ack — the gap OQ-TN-09 closes).
• OpenSSH -D protocol-level behavior (no local source; web):
  • stackoverflow.com/questions/78045232 and /questions/51347627 — -D = local SOCKS server feeding per-connection direct-tcpip opens; no distinct channel type.
  • SSH3 (draft-michel-remote-terminal-http3) — the only "direct-udp" prior art found; a different protocol (HTTP/3), not RFC SSH.