---
status: draft
last_updated: 2026-09-25 (the cred-bearing door's call-connection
contract reconciled — TokenClient's door-only posture, one command per
accepted connection; the BIND spent posture reconciled — the
take-guarded reply#2 reader, review 002 C-1/D-1; the landed session
signatures reconciled 2026-09-24; Phase 1 initial draft 2026-09-20)
---
# alksocks — The Consumer Half
The consumer opens SOCKS5 channels against a produced service and
speaks RFC 1928 inside them. Two consumption shapes, structurally
separate (the Phase 0 scope resolution):
1. **The channels-native session** — a typed client that opens
`channels/socks5/sub` and drives the RFC conversation in-stream
(wrapper-aware; the POC #1 `use_stream` / POC #2 associate
session shapes).
2. **The front door** (optional, feature `local`) — a real local
endpoint (TCP for CONNECT/BIND; UDP for ASSOCIATE) that vanilla
clients point at; the door bridges each accepted
connection/socket onto a channel, with the RFC codec living only
at that boundary.
Both wrap the same protocol layer; neither is required by the other.
## The Channels-Native Sessions
### `Socks5ChannelSession` (CONNECT)
Opens `channels/socks5/sub` via `ChannelClient::open_channel`
(alkcall ADR-037/043), then drives the client side of the RFC
conversation in-stream over the channel's `BiStream`:
- the forked client typestate's `use_stream` path — generic over
the backing stream (POC #1: `Socks5Stream` impls
`AsyncRead + AsyncWrite` itself, so the session over a `BiStream`
is the intended use, not a hack);
- target construction via `ToTargetAddr` (IP-string forms parse to
IP targets; domain form passes through unresolved — ADR-012);
- after the reply, the session is a raw byte pipe — the consumer
reads/writes payload bytes directly (0 B framing, CONNECT).
### The associate session
The UDP ASSOCIATE client (POC #2's shape):
- opens the channel, negotiates, sends ASSOCIATE, reads the reply —
**receives the sentinel `BND.ADDR` and never uses it for
addressing** (the handle is the channel; ADR-003);
- `send_datagram(dst, bytes)` frames once
(`[len: u16 BE][addr + data]`, the RFC 1928 address encoding) and
writes the frame;
- `recv_datagram()` returns `Some((source_addr, bytes))` per
datagram — its incremental reader state (mid-frame position +
batched-datagram pending queue) **persists across calls** (a
datagram split across channel chunks survives a caller-driven
receive loop; POC #2's finding);
- `shutdown()` half-closes the stream — the mux's implicit-EOF
sentinel reaches the producer's stage as EOF and the association
ends (association lifetime = channel lifetime);
- **teardown ownership**: the session owns the channel; on Drop it
closes/joins — the alktunnels ADR-005 posture (the consumer
session type owns teardown), combined with ADR-004's
ownership-rides-the-handle contract.
### The BIND client
The BIND reply#2 reader (POC #5's `read_reply2` sketch): the forked
client `request()` reads reply#1; reply#2 is hand-read with the
forked public `read_address` codec (reply#1's codec applied again;
no second codec). The session then rides the pass-through data
plane. The reply#2 phase is take-guarded: the one normative reader
is `await_inbound` — the first read consumes the session's stream
(the returned plane owns it; the session stays the teardown owner),
so a second call returns the family's spent shape (`Ok(None)`, the
same posture the sibling sessions pin) and cannot re-read the live
data plane; a failed read restores the inner (the producer ends the
session on every post-reply#1 failure exit, so a re-call EOFs —
never a live data-plane re-read either way). The
`reply1()` handle is a view (the advertised BND.ADDR + the raw
pre-reply#2 stream), not a reader. The BIND client is a
wrapper-aware-consumer convenience — vanilla clients reach BIND
through the front door instead.
### Error surface
`SocksServerError` / `SocksError` (the forked surface) mapped
faithfully; channel-open failures are the typed
`channel:open_failed` reasons (alkcall ADR-049). A refused session
never yields a phantom channel; a refused target is an RFC reply
code surfaced through the session type.
## The Front Doors (feature `local`, optional)
The consumer's optional local exposure — the ssh `-D` shape (POC #1:
curl end-to-end; POC #2 test 8: the UDP door; POC #5 test 8: the
BIND door):
- **The CONNECT/BIND door**: bind a real TCP listener; for each
accepted connection, pipe it raw onto a channel `BiStream`
(`copy_bidirectional`, **zero protocol translation** — POC #1's
literal 0 B pass-through conclusion). The door's credential half
(below) is the only RFC work it does.
- **The UDP door**: bind a real UDP socket; decode RFC-header'd
datagrams (`parse_udp_request`), send `{addr, data}` frames
in-band, return replies RFC-header'd (`new_udp_header`) — the RFC
codec at the door boundary only (ADR-003). FRAG ≠ 0 → refuse (the
v1 posture).
- **The BIND door's reply#2 fidelity**: the local variant's real
listener/peer addresses pass through the pipe unchanged (the
conversation is the vanilla client's own); the door adds nothing.
### Door variants and auth (ADR-005)
- **The NoAuth door** (POC #1's raw-pipe shape): zero protocol
translation; for loopback-only or wrapper-aware use.
- **The cred-bearing door** (RFC 1929): a vanilla client carrying
`user:pass` gets a real RFC 1929 conversation at the door; the
door maps the accepted credential to *local* configuration —
which channel identity/endpoint to open the producer channel
with — via a **static config table** (ADR-005: `user:pass →`
channel identity/endpoint selection). The SOCKS password never
crosses the channel as a SOCKS password; the channel identity
never reaches the vanilla client. The door checks credentials
itself (no forked `AuthMethod` impl needed — the door owns the
accept loop). The mapped identity rides the open-op call's
`auth_token` payload (CF-005 precedence (1)) via
`TokenClient::wrap` — the client's channel-0 `CallConnection` is
taken once per door (the door-only contract: a cred-bearing
door's client is a door client; other shapes — the UDP door's
association, channels-native sessions — ride their own
connections to the same producer registration, one registration,
many connections). The vanilla conversation is
**one command per accepted connection** (the door's RFC half
consumes the greeting + one command; the data plane rides to
EOF).
Door variant selection (NoAuth vs cred-bearing; the UDP door's bind
address) is assembly-layer configuration.
## Wiring (Assembly Layer)
```rust
let session = Socks5ChannelSession::connect(
&channel_client, target).await?;
let (mut read, mut write) = session.split(); // post-reply payload pipe
let assoc = AssociateSession::associate(&channel_client).await?;
assoc.send_datagram(dst, &bytes).await?; // frames once, ADR-003
let (src, bytes) = assoc.recv_datagram().await?.expect("a datagram");
let door = FrontDoor::builder()
.credentials(cred_table) // RFC 1929 mapping, ADR-005
.bind("127.0.0.1:1080")
.build();
door.serve(channel_client).await?;
```
The landed session signatures: the constructors take `&ChannelClient`
(shared — many sessions ride one client, the concurrency posture);
`send_datagram` takes `impl ToTargetAddr` (the CONNECT session's
target-construction posture, ADR-012); `recv_datagram()` returns
`Result<Option<(TargetAddr, Bytes)>, SocksSessionError>` — `None` is
the channel EOF (the association's clean end), never an empty
datagram (F-2: an empty payload is a legal datagram).
## Design Decisions
| [001](decisions/001-alpn-and-open-op.md) | ALPN + op | the consumer opens the one op |
| [003](decisions/003-udp-handle-swap.md) | The associate session | sentinel BND.ADDR; frames once; reader state persists |
| [004](decisions/004-dial-callback-shape.md) | Ownership rides the handle | handle payloads own channel sessions; the session-teardown posture is inherited from **alktunnels ADR-005** (the consumer session type owns teardown) |
| [005](decisions/005-auth-split-by-door.md) | Door auth | RFC 1929 at the door; static credential→identity mapping |
| [007](decisions/007-bind-in-base.md) | BIND client | the reply#2 reader; vanilla clients via the door |
| [011](decisions/011-inline-vendor.md) | The extraction | the client `use_stream` path in-tree |
| [013](decisions/013-targeted-fork.md) | The targeted fork | the core is owned (`src/rfc1928/`) |
## Open Questions
Open questions are tracked in [open-questions.md](open-questions.md).
None currently blocking this document.
## References
- POC #1 (`poc-connect-wasm-findings.md` — the raw-pipe door, the
`use_stream` fit), POC #2 (`poc-udp-associate-findings.md` — the
associate session, the reader-state finding, the UDP door), POC #5
(`poc-bind-findings.md` — the reply#2 reader, the BIND door)
- Upstream: alkcall ADR-037/043 (channel open), **alktunnels
ADR-005** (consumer session owns teardown — the posture
inherited), the CF-005/CF-006 seam
- [producer.md](producer.md) (the other half),
[wire.md](wire.md) (the normative wire)