--- status: draft last_updated: 2026-09-24 (the phase lifetimes' timeout posture decided: teardown-governed, no protocol-layer idle bound, ADR-014; Phase 1 initial draft 2026-09-20; the POC-validated wire shapes promoted into the normative spec) --- # alksocks: Wire Format The `alk/socks5` wire surface. Two layers: the **open op** (JSON params on the channels call plane; trivial here, ADR-001) and the **data plane** (the RFC 1928 conversation + the data streams inside the channel `BiStream`). The channels layer strips its own 8-byte header transparently (alknet ADR-093 / alkcall ADR-035); alksocks owns everything inside the `BiStream`, which is, per the phase model (ADR-003/ADR-007), the RFC conversation itself plus raw pass-through, with exactly one framed stage (ASSOCIATE datagrams). Design decisions live in the ADRs ([001](decisions/001-alpn-and-open-op.md), [003](decisions/003-udp-handle-swap.md), [007](decisions/007-bind-in-base.md), [011](decisions/011-inline-vendor.md), [013](decisions/013-targeted-fork.md), [014](decisions/014-idle-timeout-posture.md)); this document is the normative WHAT. RFC 1928's own wire rules (method negotiation, command encoding, reply encoding, the RFC UDP datagram header) are specified by the RFC itself; this document covers the channels-specific surface and the phase model's stage boundaries. ## The Open Op (`channels/socks5/sub`) `Sub`-typed operation (alkcall ADR-047): the reply carries `{ "channel_id": }` once; everything else (the entire RFC 1928 conversation and the data plane) flows on the channel's `BiStream`, never in the call response stream. ALPN marker `alk/socks5` (ADR-001). ### Input (params) ```json {} ``` - Trivial: the SOCKS5 target is unknown at open time (it arrives in-stream post-negotiation); the establisher is a session gate, not a dial (POC #1's structural finding, ADR-004). - Schema: `{type: object}` with `additionalProperties: false`. Empty params stay valid forever; a future per-session option would be an additive schema extension (ADR-001). ### Reply / errors - Success: `{ "channel_id": }`: the establishment phase (the session gate) succeeded, the open handler is running. - Failure: a typed `channel:open_failed` call error with `details: { reason, message }` where `reason ∈ dial_failed` / `unknown_resource` / `resource_shortage` / `handler_error` / `timeout` (alkcall ADR-049 §3). The registry's ACL gate runs before the wrapper (`FORBIDDEN` for a scope-less identity; POC #1). **A failed open never returns a `channel_id`**: no phantom channel. Session-level refusal is always channels-level; *target-level* refusal happens later, in-stream, as an RFC reply code (ADR-004). - The scope gate: `required_scopes = ["socks5:open"]` (`SOCKS5_OPEN_SCOPE`, ADR-006). Caller identity resolves in the alkcall CF-005 precedence order (payload `auth_token` > `ServingConfig.identity` > transport identity); the establisher and open handler receive the per-call opener identity (CF-006). No extra reply fields in v1 (the session gate has nothing to project; `with_reply_field` stays available additively). ## The Phase Model RFC 1928 is one command per connection, and control and data never interleave in either direction. The channel's `BiStream` therefore has a **phase structure with no mode byte**: the reply itself synchronizes the switch (POC #2 confirmed post-reply garbage is refused structurally; the demux-vs-phase trade is resolved by ADR-003/ADR-007): | Command | Phase 1 (control) | Phase 2 (data) | Framing in phase 2 | |---------|-------------------|----------------|--------------------| | CONNECT | negotiate → command → reply | raw pass-through | none (0 B) | | BIND | negotiate → command → reply#1 | quiet wait (no bytes allowed) → accept → reply#2, then pass-through | none after reply#2 | | UDP ASSOCIATE | negotiate → command → reply (sentinel BND.ADDR) | datagram stage | `[len: u16 BE][addr + data]` per datagram | - **Post-reply control bytes are protocol garbage.** CONNECT: the stream is a pure byte pipe; any non-data interpretation is a consumer violation. ASSOCIATE: the frame's first byte is ATYP, so any post-reply control byte parses as a garbage ATYP and fails the association loud (`udp_undecodable_frame_ends_association`, POC #2). BIND: any byte in the quiet wait ends the session with no data plane (POC #5, the RFC 1928 §3 reading). - **No in-band control vocabulary.** The alktunnels resolution ("no in-band control path, ever; the escape hatch is a new ALPN") holds: no KEEPALIVE, no error frames, no flow-expiry frames. No idle/inactivity vocabulary either: every phase's lifetime is teardown-governed (EOF / garbage / error sentinels), never protocol-layer timed (ADR-014; ADR-007 decided the BIND quiet wait's ends the same way). A deployment enforces idle policy at its edges, not in-band. Errors are EOF-shaped (channels-level) or reply-code-shaped (in-stream, pre-data-plane). - **One channel per SOCKS5 session** (no sub-demux, no flow key; AGENTS.md convention 10; the ASSOCIATE handle swap makes the channel the relay handle, ADR-003). ## The Data Plane ### CONNECT: raw pass-through Post-reply, the handler runs `alkcall::channels::pump_bidi(channel_ bistream, target_read, target_write)` (ADR-050), the canonical two-pump shape (alknet ADR-078); each pump shuts down the opposite sink on completion (half-close semantics fall out); EOF sentinels are the channels layer's. Zero protocol framing in-band: the RFC conversation *is* the stream (POC #1: echo round-trips clean; the front door adds no framing). The dial seam (`DialFn`, ADR-004) is invoked at the command-read interception point with the parsed target. Per-target refusal: `reply_error` with the mapped RFC code (POC #1: dial refusal → `ConnectionRefused` 0x05); no phantom data plane. ### UDP ASSOCIATE: the handle swap + framed datagram stage The ASSOCIATE reply's `BND.ADDR`/`BND.PORT` is the sentinel `127.0.0.1:0` on the in-band path (pure RFC-compatibility surface); the channel is the relay handle (ADR-003). The datagram stage rides the same channel: - **Frame:** `[len: u16 BE][addr + data]` where `addr + data` is the RFC address encoding (`TargetAddr::to_be_bytes()`: ATYP + addr + port; the RFC UDP header minus RSV/FRAG). One frame per datagram, both directions. **A zero-length payload is a legal empty datagram (never EOF; the F-2 invariant, shaped on alktunnels ADR-003's codec, re-implemented in first-party `src/wire.rs`); `len == 0` (zero inner bytes) is unreachable from a compliant peer, since `addr` is always ≥ 7 bytes, so the operative invariant lives at payload level.** The length covers `addr + data`, not data alone; the joint bound is the constraint:** a frame is rejected (`Oversize`, at frame time) whenever `len(addr) + len(data) > 65535`. The UDP payload bound alone (65507) does *not* fit u16 unconditionally: a 65507-byte datagram to a 255-character domain is 65507 + 259 (max domain-form address: ATYP + length byte + 255 + port) = 65766 bytes of frame payload, a legal RFC 1928 datagram that would overflow u16. The joint rejection keeps the length field honest: max data is 65276 for domain-form destinations, 65516 for IPv6, 65528 for IPv4. Implementations must not use unchecked u16 arithmetic on the payload bound. - **RSV/FRAG do not ride the tunnel wire**: fragmentation cannot be expressed in-band; FRAG ≠ 0 is refused at front doors (the iroh-socks5 v1 posture). - **The RFC header codec (`new_udp_header`/`parse_udp_request`) exists only at vanilla front-door boundaries** (ADR-003; POC #2 test 8: RFC datagram in, `{addr, data}` frames in-band, RFC reply-header'd datagrams out, zero payload translation). - **Association lifetime = channel lifetime.** Channel EOF (the channels-level sentinel) ends the association; no extra control vocabulary (POC #2 test 4: a fresh associate succeeds immediately after a half-close teardown). No inactivity timer exists at the protocol layer: every phase (the pre-command handshake, the BIND quiet wait, the association) is teardown-governed, never idle-expired (ADR-014); a deployment wanting an idle bound enforces it outside the protocol layer (door accept paths, caller-side wrappers). - **The stage is `select!`-driven** (channel reads ∥ egress replies), with the egress readiness contract: `next_reply` is `Pending` when nothing is ready (an instantly-ready `Ok(None)` starves a biased select into livelock; POC #2's load-bearing API finding). **Framing is applied exactly once, by the wire layer:** `Egress::next_reply` returns *inner* bytes (`addr + data`); the frame writer adds the single length prefix (the double-framing bug class POC #2 caught is an API-design invariant). - **Producer egress** is the `EgressFactory` seam (ADR-004/ADR-008): local-socket (one `UdpSocket` per association, per-datagram `send_to`/`recv_from`, no flow table; replies attributed by the sender's address per the RFC's per-datagram source semantics) or composed (a lazy destination→direct-op-tunnel table, LRU-evicted; open cost ~0.8 ms measured, per-target ACL for free). **Per-datagram `send` is awaited inline** (the stage interleaves sends with reply drains); a slow egress applies backpressure to the association, not to other channels; the batch-2 composed-egress author inherits this bound knowingly. ### BIND: the phase model extended (ADR-007) - Phase 1 ends at **reply#1 carrying `BND.ADDR`** (the accept variant's real listener address; the sentinel on the wrapper-aware in-band path). - **The quiet wait**: no bytes are legal; the `select!` is single-shot with exactly two exits: the one inbound accept (from the `BindAcceptFactory` seam, whose future owns the listener), or the control stream's EOF/garbage/error (the client-gone teardown riding the accept future's drop). - **reply#2 carries the peer address** (the real peer on both non-sentinel variants: local is `accept()`'s peer, byte-exact; composed is the forwarded op's `peer` param since the bind-first graduation, alktunnels `docs/research/tunnels-graduation.md`; sentinel `0.0.0.0:0` wrapper-aware). - **Phase 2 is raw pass-through** (`pump_bidi`, the CONNECT shape) between the channel and the accepted halves. - Failure mapping is RFC-faithful: factory failure (pre-reply#1) → reply#1 with the mapped code; accept-stage failure (post-reply#1) → reply#2 with the mapped code, no data plane (POC #5 test 6). ### Sentinels and lifecycle (all commands) - **EOF** is the channels-level zero-length chunk, per-direction (half-close); written by `pump_bidi`'s shutdown-on-completion or teardown. CONNECT/BIND data planes end on EOF; the ASSOCIATE association ends on EOF. - **No mid-stream control frames** in any phase (the phase model's whole point); pump-phase failures are EOF-shaped (alkcall ADR-049 §6). - **BAST:** the ASSOCIATE datagram frame is the one binary framing beyond pass-through; its BAST document is [bast.md](bast.md). ## Normative byte diagrams CONNECT (post-reply, one direction's view inside the channel `BiStream`, after the channels layer's 8-byte header per chunk): ``` ... ``` UDP ASSOCIATE (the datagram stage, one direction's view): ``` [len:u16 BE][ATYP + addr + port + data] [len:u16 BE][...] ... zero-length data: an empty datagram (legal payload, NOT EOF; the F-2 invariant at payload level) len == 0 (no addr bytes): unreachable from a compliant peer EOF: the channels-level sentinel, outside the codec ``` BIND (the phase sequence, one channel's view): ``` | <- reply#1 (BND.ADDR) | | (accept) <- reply#2 (peer addr) | ... ``` ## Open Questions Open questions are tracked in [open-questions.md](open-questions.md). None currently open against this document: the datagram framing (the one-way door) is decided (ADR-003); the phase lifetimes' timeout posture is decided (ADR-014: teardown-governed, no protocol-layer idle bound); OQ-SK2-07 (the virtual-subnet translation layer) rides the dial callback and does not touch this surface. ## References - ADR-001 (op/params), ADR-003 (the handle swap + frame), ADR-004 (the seams + phase-model refusal paths), ADR-007 (BIND), ADR-011 (the forked codecs), ADR-014 (the teardown-governed phase lifetimes; no protocol-layer idle timeout) - POC findings: `poc-connect-wasm-findings.md` (CONNECT pass-through, refusal mapping), `poc-udp-associate-findings.md` (the stage, readiness contract, framing-once invariant, association lifetime), `poc-bind-findings.md` (the BIND phases, quiet-wait semantics, failure mapping) - Upstream: alkcall ADR-035 (channels pure multiplexing), ADR-037 (channel open), ADR-049 (establishment/typed errors), ADR-050 (`pump_bidi`); alktunnels ADR-003 (the length codec + F-2) - RFC 1928 (the protocol's own wire rules), iroh-socks5 eval (`docs/research/iroh-socks5-eval.md`, the frame prior art)