alksocks/docs/research/phase-0.md

---
status: draft
last_updated: 2026-09-14 (post-POC #2 review: OQ-SK-08 BIND, OQ-SK-09
capacity, OQ-SK-05 virtual-subnet addendum, POC #5)
---

# alksocks — Phase 0 (Exploration)

This document captures Phase 0 (Exploration) for the `alksocks` crate:
vision, guiding principles, prior art, open questions (OQ-SK-01..NN), and
POC candidates. Phase 0's objective per `docs/sdd_process.md`: *capture
vision and guiding principles; research options; validate approaches;
converge on a recommended approach.* It is the input to Phase 1
(Architecture), where the Architect will produce `docs/architecture/`
specs, ADRs, and the open-questions tracker.

Drafted 2026-09-12, emerging from the initial setup discussion. The crate
is the sibling of alktty (`alk/tty`) and alktunnels (`alk/tunnel`) on the
alkcall substrate; where alktunnels realizes the `-L`/`-R` forwarding
flavors, alksocks realizes the `-D` flavor (dynamic / SOCKS5 proxy) —
the one alktunnels explicitly deferred to composition.

## Vision and guiding principles

**One sentence:** a SOCKS5 (RFC 1928) producer/consumer protocol crate on
alkcall channels — an arbitrary-egress proxy service that never binds a
port unless explicitly configured to, wrapping `fast-socks5` so the RFC
conversation rides inside a channels data channel like any other produced
resource.

**The three components (2026-09-12 clarification — they serve different
purposes and were at risk of being conflated):**

1. **Producer half** — a side exposes the SOCKS5 service as a produced,
   ACL-scoped resource (registers openable channels; the open handler
   runs the RFC state machine; target dials happen there or further
   downstream). This is the `-D` service over channels.
2. **Consumer half** — a side opens SOCKS5 channels against a produced
   service and speaks RFC 1928 inside them. *Optionally* it may expose
   the service locally: bind a real `socks5://127.0.0.1:port` endpoint
   and relay each accepted connection into a channel (the ssh `-D`
   local-exposure shape, and the path tun2proxy/curl/browser point at).
3. **SOCKS client wrapper for QUIC runtimes** — `AsyncUdpSocket`
   implementations (quinn and noq) so downstream clients (alknet) can
   route QUIC through *any* third-party SOCKS5 server — not just one
   produced by this crate. The motivating case is iroh's privacy
   posture: iroh relays see the real IP (intended for relay-assisted
   p2p), and a client that doesn't want to leak it needs a SOCKS hop
   ahead of the QUIC dial. This component is a plain client library
   (the alknet ADR-090 descendant); it neither produces nor consumes
   channels.

Components 1+2 form the producer/consumer protocol pair (channels in,
RFC 1928 inside); component 3 is standalone and composes with any
RFC 1928 server. Keep them structurally separate in the crate layout.

**Scope resolution (2026-09-14, post-POC): component 3 moves to the
alknet rewrite.** The QUIC-runtime client wrapper's natural home is
alknet — it is alknet's own ancestor (ADR-090 + the quinn-proxy POC
live there), it neither produces nor consumes channels, and the
planned alknet rewrite is where downstream clients (iroh privacy
posture) will actually consume it. That pins alksocks' scope to the
producer/consumer pair only: **socks + channels.** Consequence: the
OQ-SK-06 noq research (and its would-be POC #3) transfers to alknet's
Phase 0; the quinn 0.11 variant is already proven there
(quinn-proxy POC). This crate's client-side story reduces to the
channels-native consumer session (`Socks5Stream::use_stream` over a
`BiStream` — POC #1) plus the wrapper-aware associate session (POC
#2) and the optional front doors.

Guiding principles, inherited from the alk* family:

1. **"ALPN as a service," not "a server."** The SOCKS5 service is a
   produced, ACL-scoped resource on a channels connection — the same
   shape as an alktty terminal or an alktunnels TCP tunnel. Kernel
   binds exist only as explicit, optional assembly-layer shapes on
   *either side* — the producer may serve from a real listener (a
   feature-gated local backend, component 1's optional shape), and the
   consumer may expose the resource on a local port (component 2's
   optional shape, the ssh `-D` front door). The protocol itself never
   binds; the binding decision belongs to the caller.
2. **The `-D` conclusion, realized.** alktunnels' Phase 0 settled that
   `-D` composes at the assembly layer: "`-D` is just tunnel a socks5
   connection"; target selection lives in the SOCKS5 protocol at the
   producing side, governed by the same op-level ACL as the resource.
   This crate is that conclusion's realization as a first-class protocol
   crate, not an assembly-layer afterthought.
3. **Wrap `fast-socks5`, preserve its genericity.** `fast-socks5`'s
   explicit typestate server API (`Socks5ServerProtocol<T, states::*>`)
   is generic over `T: AsyncRead + AsyncWrite + Unpin`, and its
   interception points (`run_tcp_proxy`, `run_udp_proxy_custom`,
   `transfer`) accept any such `T`. The channels adapter feeds the state
   machine a `BiStream`; a local backend feeds it a `TcpStream`. The
   wrapper must not leak either substrate into the protocol layer
   (alktty `TtyBackend` / alktunnels pump-halves inversion-point
   precedent).
4. **Producer/consumer vocabulary.** Both sides of a channels connection
   can initiate; a producer registers openable SOCKS5 channels
   (`ChannelCore::register_openable`), a consumer opens them and speaks
   RFC 1928 inside. RFC 1928's own client/server roles keep their RFC
   names *inside* the protocol layer, but crate-level docs and API use
   producer/consumer. Avoid "SOCKS5 server" as a crate-level noun.
5. **Extract-and-improve from alknet.** alknet's SOCKS5 story is the
   direct ancestor: the client side (`alknet-client/src/socks5.rs`,
   ADR-090 — `Socks5UdpSocket` implements `quinn::AsyncUdpSocket` so
   QUIC rides UDP ASSOCIATE, validated by the quinn-proxy POC) and the
   server side (the `-D` capability alktunnels deferred). This crate
   rehomes both halves behind one protocol crate and improves them.
6. **The vpn-like endgame composition.** A SOCKS5 server + tun2proxy is
   the last step (ish) of "vpn-like without actually being a vpn": a
   user tunnels a produced SOCKS5 resource to a local port (component
   2's optional shape), then points tun2proxy (`/workspace/tun2proxy`
   — it takes `--proxy socks5://user:pass@host:port` natively,
   `src/args.rs`) at it, and the whole host's traffic rides the alk*
   egress. This crate is the SOCKS5 leg of that composition; alktunnels
   carries the tunnel; tun2proxy closes the loop. (The udpgw framing
   alktunnels' UDP format is based on is the same prior art
   OQ-SK-03's datagram codec draws on.)

## What is already settled

The foundation is POC-validated and ADR-pinned upstream; this crate does
not start from zero. It inherits:

- **The channels data path** — demux→Connection→handler→mux, validated
  by the alknet-channels POC and production alktty/alktunnels. The SOCKS5
  payload is raw bytes inside a channels data channel's `BiStream`;
  channels strips its 8-byte header transparently (alknet ADR-093 /
  alkcall ADR-035). SOCKS5 CONNECT is one `BiStream` per session — the
  RFC conversation *is* the stream; no sub-demux, no framing, no flow
  key (one channel per SOCKS5 session).
- **The two-pump data plane** — the CONNECT proxy loop is the canonical
  two-pump shape; `alkcall::channels::pump_bidi` (ADR-050) is pinned
  upstream and alktunnels-validated. Use it; do not hand-roll.
- **The establishment story** — session opens use
  `register_openable_with_establisher` (alkcall ADR-049 + amendment 2):
  the establisher runs as an awaited, bounded establishment phase; a
  refused session is a typed `channel:open_failed` call error
  (`reason ∈ dial_failed / unknown_resource / resource_shortage /
  handler_error / timeout`), never a phantom channel. The negotiate/
  auth half of the RFC conversation still runs in-stream over the
  `BiStream` — establishment covers only the producer's accept policy,
  not the RFC handshake.
- **The producer/consumer model** — producer registers openable channels
  (authorization for free via `AccessControl`); consumer opens them via
  `ChannelClient` (alkcall ADR-037, ADR-043). Connection direction is
  independent of service direction.
- **The relay/hub story** — a SOCKS5 resource traverses alkcall hub
  relays like any produced resource; the hub's terminate-and-re-produce
  proxy (alktunnels' refinement of alkcall ADR-042) applies per hop, and
  a SOCKS5 resource is exactly the "further downstream" shape alktunnels
  described. No socks5-specific relay work.
- **The identity seam** — alkcall 0.7.0's CF-005/CF-006: the per-call
  opener identity arrives on the open-op hooks. Auth mapping (identity →
  SOCKS5 credentials/ACL, if any) happens there, not via in-band SOCKS
  auth, unless RFC-facing username/password is needed for vanilla SOCKS5
  clients (OQ-SK-02).
- **The backend inversion point pattern** — substrate-specific types
  confined to feature-gated backend modules, injected at the assembly
  layer (alktty `TtyBackend` / alktunnels no-trait precedent).
- **The wasm-clean default crate** — protocol-only code should compile
  to `wasm32-unknown-unknown` (alktty/alktunnels precedent). Caveat:
  `fast-socks5` itself is not yet known to be wasm-clean (OQ-SK-04).

## Prior art

### alktunnels Phase 0 — the closest sibling

`/workspace/@alkdev/alktunnels/docs/research/phase-0-findings.md`. The
load-bearing conclusions this crate inherits:

- **Hub-owns-the-connection model** — role follows the resource;
  whoever can reach the target is the producer, whoever wants the bytes
  is the consumer. The "exposed port" is a virtual, ACL-scoped resource,
  not a bind. For alksocks: the producer is the side that dials targets
  (the egress side); the consumer is the side that wants proxied
  egress. "A SOCKS5 service is the same shape [as a produced tunnel
  resource], further downstream" is alktunnels' own wording — this
  crate exists to make it literal.
- **`-D` composes at the assembly layer** — the original half-answer,
  now with the mechanism named: a SOCKS5 server at some assembly layer
  is just a consumer opening channels with per-connection dynamic
  targets. The refinement this crate adds: the SOCKS5 *service* is
  itself a produced resource (producer half), so a vanilla SOCKS5 client
  (curl, a browser, ssh -D's own client half) can attach through the
  optional local backend, and channels-native consumers get the same
  service in-band. Both halves wrap the same protocol layer.
- **Target policy = resource policy.** alktunnels OQ-TN-08 dissolved
  dynamic-target policy: whatever ACL governs the socks5 resource
  governs everything reachable through it, plus whatever policy the
  SOCKS5 implementation itself applies downstream. No target allowlists
  in the base crate unless Phase 1 wants them (OQ-SK-05).
- **The codec conclusion does NOT transfer.** alktunnels needed
  length-framing only for datagram substrates; a SOCKS5 CONNECT session
  is a byte stream end to end (RFC 1928 defines its own framing on the
  wire) — the channel payload is pure pass-through, 0 B overhead over
  the channels 8-byte header. UDP ASSOCIATE's datagram stage is the
  exception (OQ-SK-03).

### fast-socks5 — the implementation to wrap

`/workspace/fast-socks5` (v1.0.0, MIT, we own upstream). Read the source
before designing against it. Key surface points, verified:

- **Explicit typestate server API** (`src/server.rs`):
  `Socks5ServerProtocol<T, states::Opened|Authenticated|CommandRead>`,
  generic over `T: AsyncRead + AsyncWrite + Unpin`. Flow:
  `start(inner)` → `negotiate_auth(&methods)` →
  `finish_auth()` / `accept_no_auth` / `accept_password_auth` →
  `read_command()` → (`reply_success`, `reply_error`). The legacy
  `Socks5Server`/`Socks5Socket`/`Incoming` API (binds a `TcpListener`)
  is deprecated — the wrapper uses the explicit API only.
- **Auth surface** — the `AuthMethod<T>` trait (metadata: `method_id`,
  `new`) + `AuthMethodSuccessState<T>` (carry the socket back out);
  `StandardAuthentication` enum for NoAuth + Password with static
  dispatch; custom methods implement the trait. Username/password check
  is a closure (`accept_password_auth`). The auth *decision* is where
  the alkcall identity seam plugs in (OQ-SK-02).
- **Command handling is swappable** — the interception points:
  - `run_tcp_proxy(proto, addr, timeout, nodelay)` — dials, replies,
    then `transfer(inbound, outbound)` (a `copy_bidirectional` wrapper,
    itself generic). This is where a channels-native dial replaces the
    `tokio::net` dial: the wrapper's producer half intercepts here,
    dials via alktunnels/alkcall primitives (or its own dial policy),
    and returns the `T` back.
  - `run_udp_proxy_custom(proto, addr, peer_bind_ip, reply_ip, transfer)`
    — the customizable UDP ASSOCIATE handler. **Caveat (verified
    2026-09-13):** the "custom" seam is narrower than it looks — it calls
    `udp_bind_random_port(peer_bind_ip)` *unconditionally* and derives
    the reply port from that kernel socket; the wrapper can customize
    the relay loop (`transfer`) and the reply *IP* only. The channels
    path therefore cannot use this handler: it drives the typestate
    directly (`reply_success(sentinel_addr)` + own datagram stage). The
    unconditional bind is a fileable upstream ask (we own fast-socks5):
    make the bind optional or accept a caller-supplied socket.
  - `transfer(inbound, outbound)` — plain two-pump copy; a channels
    `BiStream` is a legal `T` on either side.
- **UDP support** — `new_udp_header(target)` / `parse_udp_request(buf)`
  are public and pure (no socket I/O) — the SOCKS5 UDP datagram header
  codec is reusable without the `Socket2`-based relay machinery. The
  default `run_udp_proxy` binds two kernel sockets (`Socket2`, random
  ports) — the *binds are in the default handler, not in the protocol*,
  which is exactly the seam the no-bind requirement needs.
- **Client side** — `Socks5Stream<S>` (generic over the backing socket;
  `use_stream` upgrades any `AsyncRead + AsyncWrite + Unpin` already
  connected) and `Socks5Datagram<S>` (UDP associate; also accepts a
  caller-supplied socket via `use_socket`). `Socks5Stream` impls
  `AsyncRead + AsyncWrite` itself, so a consumer session over a
  channels `BiStream` is the intended use, not a hack. Note:
  `Socks5Stream::connect` convenience constructors dial
  `tokio::net::TcpStream` and are non-wasm; `use_stream` is the
  substrate-free path.
- **Error surface** — `ReplyError` (the RFC reply codes, `as_u8`/
  `from_u8`) and `SocksError`; `SocksServerError` on the explicit API.
  Map these faithfully; never collapse a refusal into a generic error.
- **`router.rs` example** — the "conditional interception" template: a
  server that inspects the command/target, then decides whether to
  proxy, refuse, or handle in-process. Structurally the shape of the
  channels open handler (inspect params → dial or refuse) and of the
  alknet ADR-090 client (hand the established stream to quinn).

### iroh-socks5 — the structural sibling (evaluated, not the base)

`crates.io/crates/iroh-socks5` (v0.5.0, MIT OR Apache-2.0, repo:
`github.com/mattgeddes/iroh-socks5` — crates.io lacks the repository
link). A ~1.3k-LoC iroh `ProtocolHandler` tunneling SOCKS5 over iroh
QUIC: framed `Request`/`Reply` protocol postcard-encoded over one
bidirectional stream, then raw pass-through (CONNECT/BIND) or framed
`Datagram`s (UDP ASSOCIATE); producer-side dial + allow-list
(`EndpointId`s), consumer-side local TCP front door for vanilla clients.
Full evaluation: `docs/research/iroh-socks5-eval.md`. Verified:

- **Independent confirmation of POC #1's shape** — one stream per SOCKS5
  session, framed control phase then pass-through, RFC codec only at
  vanilla-client boundaries, resolution producer-side. Convergent
  evolution from a codebase with no alk* lineage.
- **The load-bearing OQ-SK-03 prior art** — its UDP ASSOCIATE design
  carries framed `{addr, data}` datagrams in-stream (no RFC UDP header
  on the tunnel wire; the RFC header codec applies only at the local
  front-door socket), needs no producer-side flow table (per-datagram
  addressing in the frame does the demux), ends the association on
  control-stream EOF, and refuses FRAG ≠ 0. This is the phase-model
  hunch's cleaner expression; adopt as the POC #2 design baseline.
- **Why it is not the base:** iroh types are load-bearing in the data
  plane (`SendStream`/`RecvStream` in relay signatures; no generic `T`
  seam), the RFC surface is a subset (no-auth only, no auth-method
  machinery, no reply-code enum fidelity), and the client side has no
  in-band session type (local front door only). Extracting a
  substrate-agnostic core yields ~550 LoC of codecs fast-socks5 already
  provides in stricter form — the POC #1/#4 base decision stands.

### alknet's SOCKS5 client + the quinn-proxy POC — the client-side ancestor

`/workspace/@alkdev/alknet/crates/alknet-client/src/socks5.rs` (ADR-090)
implements `Socks5UdpSocket: quinn::AsyncUdpSocket` — a SOCKS5 UDP
ASSOCIATE tunnel wrapped as the socket QUIC polls. The quinn-proxy POC
(`/workspace/@alkdev/alknet/docs/research/quinn-quic-proxy/findings.md`)
validated the approach end-to-end (5/5 clean runs) against quinn 0.11:
one public trait (`AsyncUdpSocket`), one public constructor
(`Endpoint::new_with_abstract_socket`), no fork. Known limitations
there, likely inherited: ECN is lost through the SOCKS5 header; the
proxy must support UDP ASSOCIATE; `may_fragment() == true` disables
path MTU discovery.

This crate's client half rehomes that work (cleaned up, `ClientDialError`
→ thiserror types, and the datagram codec sourced from fast-socks5
rather than hand-rolled inline). The open question is noq (OQ-SK-06).

### noq — the quinn fork the client story must also fit

`/workspace/noq` (v1.2.0; iroh's fork of quinn — iroh depends on
`noq = "1.2.0"`). Surface verified:

- `noq::AsyncUdpSocket` exists (`noq/src/runtime/mod.rs:44`) but with a
  **different shape** than quinn 0.11: `create_io_poller` +
  `try_send` are replaced by `create_sender() -> Pin<Box<dyn UdpSender>>`
  with `poll_send(transmit, cx)` — a sender-object split (any number of
  `UdpSender`s per socket, each holding its own waker).
- `RecvMeta` gained fields (`interface_index`, `timestamp`) but stays
  default-constructible; `Transmit` is unchanged in the fields the
  SOCKS5 wrapper touches (`destination`, `contents`, `ecn`, `src_ip`,
  `segment_size`).
- `Endpoint::new_with_abstract_socket` exists (`noq/src/endpoint.rs:162`)
  with the same doc-comment intent, but takes
  `Box<dyn AsyncUdpSocket>` rather than `Arc<dyn AsyncUdpSocket>` — the
  poller-removal reshuffle also changed the ownership shape.
- The alknet `Socks5UdpSocket` does **not** drop in unchanged: the impl
  must be rewritten against `create_sender`/`poll_send`, and the
  `Arc`→`Box` change ripples into construction. Whether one crate can
  serve both quinn and noq behind feature flags (shared core, two thin
  trait-impl shells) or whether the shapes have diverged enough to
  justify two impls is the research question (OQ-SK-06). iroh's own
  adoption makes noq support the practically-important target.

### Anti-prior-art (what NOT to carry over)

- **The alknet client's hand-rolled SOCKS5 codec** —
  `socks5.rs` inlines the greeting/auth/CONNECT/ASSOCIATE byte logic
  twice (handshake for UDP, again for CONNECT). fast-socks5's client
  types and `new_udp_header`/`parse_udp_request` supersede it; the
  wrapper should not vendor a second codec.
- **`Socks5Server` (the legacy bind-based API)** — deprecated upstream;
  never the default path here.
- **In-band SOCKS auth as the primary auth story** — alkcall's identity
  seam (CF-005/CF-006) authorizes at the open-op layer. In-band RFC
  username/password remains available only for vanilla-client
  compatibility (OQ-SK-02).

## Open Questions

These are the design questions Phase 0 must resolve (or explicitly
defer) before the architecture spec. Numbered OQ-SK-01.. so they can be
referenced, tracked, and promoted into `docs/architecture/
open-questions.md` in Phase 1. Half-answers and hunches are marked as
such — the point of this document is to hold them without forcing
premature decisions.

### OQ-SK-01: Producer dial policy — what dials the target?

When the producer's SOCKS5 state machine reads a CONNECT command, the
target dial must happen *somewhere*. Options:

- **Option A: dial via alktunnels** — the producer composes with a
  local alktunnels consumer: the SOCKS5 handler opens an `alk/tunnel`
  channel naming the target, and the two-pump data plane is
  tunnel-channel ↔ SOCKS5-`BiStream`. Maximum composition ("further
  downstream" made literal), but adds a runtime dependency and a hop.
- **Option B: dial directly** — the producer dials the target itself
  (`TcpStream` behind the `local` feature, or an injected dial
  callback). No alktunnels dependency; the dial policy (allowlists,
  routing through another alksocks hop) is the caller's callback.
- **Option C: injected dialer trait** — a `Dialer`-shaped trait
  (`async fn dial(target) -> impl AsyncRead + AsyncWrite`) with
  alktunnels and local-TCP implementations behind features. Middle
  ground; the trait is a backend-inversion-point decision (compare
  alktunnels OQ-TN-05's resolution: *no trait*, a function producing
  boxed halves sufficed).

Considerations: substrate-agnostic-by-construction (AGENTS.md
convention 7) favors injection over hardwiring; the "hub terminates and
re-produces" story means a hub-hop SOCKS5 resource's dialer is just
"open a channel further downstream," which is Option A's shape — so
whatever is decided must not *prevent* A when composing. Hunch: a dial
callback/trait at the protocol layer, with alktunnels and local-TCP
providers feature-gated — but alktunnels' no-trait precedent warns
against a trait unless two real implementations converge; decide with
the Phase 1 spec.

### OQ-SK-02: Auth mapping — identity seam vs in-band SOCKS auth

The producer's open-op hooks receive the per-call opener identity
(alkcall CF-005/CF-006). The SOCKS5 RFC conversation also carries its
own optional username/password auth (RFC 1929). Questions:

- Is the identity seam the *only* auth story (the open op is
  authorized; the in-band handshake is skipped via
  `skip_auth_this_is_not_rfc_compliant` or a no-op NoAuth), with
  RFC-facing username/password available only for the optional local
  backend (where vanilla SOCKS5 clients connect)?
- If both exist, how do they compose — does in-band auth *replace* the
  channel identity for target-policy purposes, or is it a second gate?
- Does the wrapper need a fast-socks5 `AuthMethod` implementation that
  consults the alkcall `AuthContext`/`Identity` (filed upstream if the
  hook shape doesn't fit — AGENTS.md convention 17)?

(Answered in direction by the 2026-09-13 posture statement below:
yes / planes-don't-compare / probably-not — Phase 1 formalizes.)

**Posture — settled direction (2026-09-13 discussion): "both," split
by the door.** The planned end-to-end story is the vpn-like
composition: a consumer connects to an endpoint producing the SOCKS5
resource, *optionally* binds it locally (component 2's front door —
ssh `-D`'s shape, with the defining difference that no port is bound by
default), and points tun2proxy (`--proxy socks5://user:pass@host:port`
natively, per §Vision principle 6) at the local port. That makes "both"
auth mechanisms real, each on its own side of the door:

- **Producer side: identity only.** The channels-native open is
  authorized by the alkcall ACL/identity seam (CF-005/CF-006); a
  producer-side password is moot — the ACL system is strictly better
  than a shared secret, and the producer's in-band conversation runs
  NoAuth/no-op. A password there would add nothing the identity seam
  doesn't already do.
- **Consumer side (the front door): RFC 1929 where vanilla clients
  need it.** The door is where the vanilla world meets the ACL world,
  so it owns credential presentation: a vanilla client carrying
  `user:pass` (tun2proxy, curl) gets a real RFC 1929 conversation at
  the door. The door then maps the accepted credential to *local*
  configuration — which channel identity/endpoint to open the producer
  channel with — and that identity reaches the producer via the
  CF-005/CF-006 seam. The SOCKS password never crosses the channel as
  a SOCKS password; the channel identity never reaches the vanilla
  client.

The "replace or second-gate" sub-question dissolves: the mechanisms
occupy different planes (in-band creds are door-local; identity is
channel-level). The NoAuth door (POC #1's raw-pipe shape, zero
protocol translation) remains valid for loopback-only or wrapper-aware
use; the cred-bearing door is the same bridge plus the greeting half
(fast-socks5's server typestate for auth + `read_command`, then the
consumer session in-band) — an assembly-layer choice, not a protocol
one.

Remaining for Phase 1: the door's credential→identity mapping shape
(static config vs pluggable lookup); whether the producer-side
optional local backend offers the same door surface (same code shape —
door = vanilla↔ACL boundary — so presumably yes); and whether the door
needs a fast-socks5 `AuthMethod` impl or simply checks credentials
itself before handing the stream to the typestate (likely the latter —
the door is this crate's code, the trait was designed for embedders
who don't own the accept loop).

### OQ-SK-03: UDP ASSOCIATE without binding — the hard case

RFC 1928 §7: the client sends UDP ASSOCIATE over the TCP control
connection; the server replies with a UDP relay address (`BND.ADDR`/
`BND.PORT`); the client then sends UDP datagrams (SOCKS5 UDP header +
payload) *to that address*. On channels there is no UDP relay socket —
the datagram stage must ride a channel. Sub-questions:

- **Where does the datagram stage live?** Options:
  - **Same channel, extended protocol** — after ASSOCIATE, the channel's
    `BiStream` carries length-prefixed datagrams (the alktunnels UDP
    codec shape, `[len: u16 BE]` per datagram; 65507 < 65535 so u16
    suffices). The reply to the client rewrites `BND.ADDR`/`BND.PORT`
    — originally imagined as a sentinel address meaning "same channel,"
    but the handle swap below supersedes that: no virtualized address
    is needed at all, because the in-band relay handle is the channel
    itself, not an address. Vanilla SOCKS5 clients will literally
    `sendto()` whatever address the reply carries, so this shape only
    works for *wrapper-aware* client halves (the crate's own consumer
    session, or an assembly layer bridging a real UDP socket).
    **iroh-socks5's refinement (2026-09-13 eval):** the in-band datagram
    carries `{addr, data}` (boundary-preserving, no RFC header on the
    tunnel wire) and the RFC UDP-header codec lives only at the
    vanilla-client front doors — cleaner than putting the length
    framing *inside* the RFC header stream as first hunched; see
    `docs/research/iroh-socks5-eval.md`.
  - **Second channel for the datagram stage** — the producer
    establishes the association on channel 1, then the client opens a
    second channel that becomes the relay. Keeps CONNECT-shaped
    `BiStream` semantics clean but adds an open-op round trip and
    needs correlation (params carry the association id?).
  - **Local-backend bridge only** — UDP ASSOCIATE is offered only
    through the optional local backend (which binds a real UDP relay
    socket as the assembly layer's explicit choice), never
    channels-natively. Simplest; weakens the "ALPN as a service"
    story for UDP.
- **What does `BND.ADDR`/`BND.PORT` reply contain on the channels
  path?** Largely resolved (2026-09-13, see the handle-swap discussion
  below): on the in-band path the relay handle *is the channel itself*
  — no address needs to be invented, and the reply's `BND.ADDR`/
  `BND.PORT` are pure RFC-compatibility surface (zeros, or whatever
  the front-door bridge reports). Only the vanilla-client front door
  has a real socket address to report, and there it comes from the
  real relay socket the assembly layer chose to bind.
- **Per-datagram addressing** — the SOCKS5 UDP header carries the
  destination per datagram (ATYP + addr + port), so one association
  multiplexes many endpoints. alknet's model used a producer-side
  per-endpoint flow table; iroh-socks5 demonstrates the simpler cut —
  per-datagram addressing *in the frame* does the demultiplexing, no
  flow table. Boundary preservation is mandatory (empty
  datagram ≠ EOF — alktunnels F-2's lesson transfers directly; the
  `{addr, data}` frame shape meets it structurally).
- **Do vanilla (wrapper-unaware) clients need channels-native UDP at
  all?** If the only UDP ASSOCIATE consumers are wrapper-aware, the
  in-band shape needs no relay address at all (the handle is the
  channel — see the handle swap below) and no virtualized address is
  ever invented.

**The handle swap (2026-09-13 discussion) — "tell the client about a
UDP port" → "tell the client about the UDP tunnel."** The design's
load-bearing reading of RFC 1928: the ASSOCIATE reply's `BND.ADDR`/
`BND.PORT` is *just the handle for the relay*, and one relay serves the
whole association — the per-datagram destination is carried in the
datagram header (ATYP/addr/port), not in the handle. The relay port was
never "a port that goes to one place"; it is a multiplexing endpoint.
So swapping the handle preserves every RFC property:

- one relay per association → **one channel per association** (the
  CONNECT shape; no second channel, no correlation params);
- per-datagram destinations → `{addr, data}` frames in-band;
- lifetime tied to the control connection → channel EOF;
- "bind locally if you want" → the optional front door on either side
  (a real UDP socket bridged to the channel, RFC codec at that
  boundary only).

Vanilla clients still literally `sendto()` the replied address, so the
in-band path is wrapper-aware-only by RFC necessity — the front-door
bridge is where a real socket address exists.

**Producer egress — two variants (the "no ports" story has two
halves).** The handle swap settles the *consumer-facing* half. The
*producing-side* half is: after `{addr, data}` frames exit the channel,
what gets each datagram to `addr`?

1. **Local egress** — the handler binds a real `UdpSocket` and
   `send_to`s per datagram (iroh-socks5's `relay_udp_server` behind
   this crate's `local` feature). No flow table, native-only.
2. **Composed egress (OQ-SK-01 Option A for the datagram stage)** —
   the dial callback opens an alktunnels `udp`-substrate tunnel per
   destination: a lazy destination→tunnel table (open on first
   datagram, LRU-evict). The flow table is *reborn as channel
   handles* — because alktunnels' udp substrate is **connected**
   (`connect_udp(target)`: one tunnel, one fixed target) while
   ASSOCIATE names a different destination per datagram. Cost: one
   open per destination (the per-connection/per-identity channel
   defaults are 256 — ADR-040/041 policy knobs, configurable without a
   wire change; the `u32` wire space is ~4 billion — so fine for DNS +
   browsing, and the per-destination open latency is a POC #2
   measurement). Benefit: **per-target ACL for free** — the ACL
   governing the udp-tunnel resource governs egress per destination
   (dissolving most of OQ-SK-05 for the composed path), and hub
   relaying is per-target terminate-and-re-produce.

Both variants are dial-callback policy (OQ-SK-01's shape) — nothing in
the fork or the protocol layer sees the difference. **No upstream ask
exists here:** alktunnels' connected-udp substrate is correct as-is for
per-target composition; an "unconnected arbitrary-egress udp resource"
upstream would just be SOCKS5 again with different framing (circular).
Prior note retained: fast-socks5's `run_udp_proxy_custom` lets the
wrapper supply the reply and the relay half — the seam exists upstream;
the local-egress variant uses it or drives the typestate directly (the
unconditional-bind caveat above).

**Phase model vs alktty-style demux (2026-09-12 discussion).** An
alternative shape surfaced: alktty's logical demux (input/output/error/
control sub-streams inside one channel, type byte per chunk, up to the
u8 = 255 stream-type limit) applied to the SOCKS5 channel — a `data`
stream and a `udp-relay` stream type would carry the two phases
structurally. Analysis against RFC 1928's actual structure: **RFC 1928
is one command per connection, and control and data never interleave in
either direction.** CONNECT's control conversation ends at the reply,
after which the channel is a pure byte stream (alktunnels' 0 B
pass-through conclusion); ASSOCIATE's control stream goes silent after
the reply — fast-socks5's own `wait_on_tcp` (`src/server.rs:1195`)
treats any post-reply control byte as protocol garbage
(`UnexpectedUdpControlGarbage`). So the per-chunk type byte demuxes a
problem SOCKS5 doesn't have; a **phase model** (raw RFC conversation
until the reply, then a mode switch synchronized by the reply itself —
pass-through for CONNECT, `[len: u16 BE]` datagrams for ASSOCIATE)
subsumes it with no type byte and no sentinel address: wrapper-aware
clients know "post-reply = datagram mode," the same way they'd know
"relay stream = datagram mode" under the demux. What the demux genuinely
buys that the phase model does not: an **additive in-band vocabulary** —
new stream types extend the wire additively (no format break), whereas
adding a post-reply phase later is a wire break. alktunnels accepted the
opposite ("no in-band control path, ever — the escape hatch is a new
ALPN, a wire change is not"); the demux reintroduces that vocabulary at
2 B/chunk (type byte + length prefix) on every datagram. The one-way-door
cost is real either way: demux bakes the vocabulary in before it has a
user; phase model keeps 0 B overhead on CONNECT and 2 B on ASSOCIATE
datagrams. Hunch: phase model (simpler, RFC-shaped); the extensibility
argument is the honest case for the demux if Phase 1 wants the
vocabulary. Decide via ADR with the first consumer in sight.

Hunch (datagram stage, updated 2026-09-13 by the handle swap):
wrapper-aware client halves ride the same-channel `{addr, data}` frame
shape (one channel per association, per-datagram addressing in-band,
channel EOF = association lifetime); vanilla clients get UDP ASSOCIATE
only via the optional local front-door bridge. The remaining choice is
producer-egress policy (local socket vs per-target alktunnels
composition) — a dial-callback question owned by OQ-SK-01, with the
composed variant's ACL benefit making it the hunch for the base crate's
composed story. But this is still the crate's largest unknown — a POC
candidate (OQ-SK-07 #2), decided by an ADR before the first consumer
(the datagram framing is wire-stable once published).

### OQ-SK-04: fast-socks5 wasm posture (blocks the wasm-clean invariant)

`fast-socks5` uses `tokio::net` (`TcpListener`, `TcpStream`,
`UdpSocket`) and `socket2` unconditionally (`Cargo.toml`: tokio features
`io-util, net, time, macros`; deps `socket2 = "0.5.8"`); `wasm32-
unknown-unknown` has no `tokio::net`. The wrapper's own protocol layer
can stay wasm-clean (the typestate API is generic over `T`), but
depending on the crate at all may break `cargo check --target
wasm32-unknown-unknown` at the dependency-graph level.

**The decision tree (2026-09-12 clarification — two main forks, and the
preference between them is conditional):**

- **Case 1: wasm matters for this crate → fork-first.** Make the
  minimal fork and use it — offer it upstream as a PR (merge if they
  want it; we carry the fork regardless; never wait on approval).
  The gating change is genuinely small (feature-gate
  `tokio::net`/`socket2` behind a default-on `net` feature, per the
  alktty `local` pattern); the long-term cost of maintaining a
  minimal fork of a well-written lib trends toward zero. Concretely
  "fork" likely means **vendoring the relevant subset into this
  crate** (the codecs, typestate machinery, client `use_stream` path —
  the parts that are already `T`-generic) and gating the native-net
  pieces behind the crate's own `local` feature, rather than
  publishing a divergent crate. fast-socks5 remains the reference
  checkout for differential testing of RFC edge cases (reply-code
  mapping, domain addressing, fragmentation) and the PR source; if
  upstream accepts the PR, the fork shrinks to a plain dependency.
- **Case 2: wasm doesn't matter for this crate → plain dependency, no
  fork.** Ride the `router.rs` native path exactly as-is (the
  alkhttp precedent — a crate in this suite can ship native-only).
  This is strictly better *if its premise holds*: no fork burden, no
  vendoring, upstream stays upstream. The alkhttp contrast is
  instructive — alkhttp's substance (axum/hyper/reqwest) is
  socket-native, so nobody misses wasm there.

**The root question is therefore: does wasm make sense for alksocks?**
Not "how do we get wasm" — that is Case 1's solved problem. Analysis
for the decision:

- **What wasm would serve:** the protocol layer (components 1+2 of the
  three-component split, §Vision) in a sandboxed adapter — the
  alktty/alktunnels posture that a wasm-compiled protocol crate is the
  protocol layer for downstream TS/Python adapters. The natural wasm
  shape is a **consumer**: speak RFC 1928 client-side over a channels
  `BiStream` (pure byte framing; the producer dials targets, so no
  local sockets are needed on the client side). A wasm **producer** is
  odd standalone (no kernel egress) but composes — its dialer can open
  alktunnels channels further downstream, which is the hub story.
- **What wasm would not serve:** component 3 (the quinn/noq client
  wrapper) is native-only in practice — it wraps kernel UDP sockets for
  UDP ASSOCIATE; no wasm story is expected there regardless.
- **The alkhttp contrast, honestly weighed:** for alkhttp,
  "an HTTP client accessed over a channel" was judged weird, and the
  crate ships native-only. alksocks differs structurally: its protocol
  substance *is* byte-framing over a generic `T` — the part that costs
  nothing to keep wasm-clean. But "costs nothing under the fork" is
  only an argument once Case 1 is chosen; it is not itself the use
  case. The use case is a planned sandboxed SOCKS consumer.

**Decision inputs (what actually settles Case 1 vs Case 2):**

1. **Is there a planned sandboxed (wasm) consumer of the SOCKS5
   service?** If the downstream TS/Python adapter story includes a
   channels-connected sandbox that wants proxied egress, wasm matters
   → Case 1. If not → Case 2.
2. **Is the fork genuinely minimal?** POC #4 (OQ-SK-07) verifies
   empirically how invasive the gating is. If the gating turns out
   structural (the `T`-generic surface can't be separated from
   `tokio::net` without a rewrite), the fork cost rises and Case 2
   gains weight — reimplementing the protocol to serve a wasm story
   nobody has yet defeats the purpose.

Both inputs point the same way when aligned: fork-first in Case 1 is
the preferred branch *because* wasm is wanted there — not as a general
preference for forks over upstream asks. If the adapter story never
materializes, Case 2 (plain dep, router path) is the obvious choice,
and no one should carry a fork for an invariant's sake.

### OQ-SK-05: Target policy and egress scoping

SOCKS5 is arbitrary-egress by nature — the open gate plus the target
policy are the security boundary (AGENTS.md convention 12). alktunnels
resolved that whatever ACL governs the socks5 resource governs
everything reachable through it; OQ-SK-01's dial policy is the
mechanism. Residual questions for Phase 1 (note the 2026-09-13
OQ-SK-03 handle-swap finding: for the *composed* UDP egress path,
per-target ACL comes free — each destination rides its own
alktunnels udp-tunnel channel governed by the tunnel resource's ACL,
dissolving most of this OQ for that path):

- Does the base crate ship a per-target allowlist hook (producer-side
  policy injected at registration), or is target policy entirely the
  dialer's concern (the dial callback refuses)? The dialer-refuses
  shape avoids a second policy layer (alktunnels' resolution pattern);
  the allowlist-hook shape makes a common policy declarative.
- Is there a `SOCKS5_OPEN_SCOPE` (scope-gate on the open op, alktty
  `TTY_OPEN_SCOPE` shape) — presumably yes, but the exact scope-string
  convention should follow alkcall's registry conventions.
- Domain-form targets (RFC 1928 ATYP 0x03): resolve producer-side
  (fast-socks5's `dns_resolve` config), refuse, or pass through to the
  dialer unresolved? (DNS-on-the-producer is the SSH `-D` semantic;
  wasm producers may not have a resolver at all — another OQ-SK-04
  interaction.)

**Virtual address space / identity-scoped subnets (added 2026-09-14,
post-POC #2).** A proposal surfaced during the findings review: give
identities scoped virtual subnets (e.g. 10.x.0.0/16 slices) so proxied
resources become IP-addressable — "BND.ADDR ↔ channel id" translation,
a hub exposing proxied resources per identity under ACL. The goal is
adoptable; the mechanism needs **no wire change**: DST.ADDR and
BND.ADDR are arbitrary RFC fields, so virtual addresses ride ordinary
CONNECT/BIND requests — the translation layer is the dial callback
(OQ-SK-01's shape: `dial(target)` matches a virtual subnet against a
per-identity resource table), per-identity scoping is resources + ACL
+ target policy (this OQ), and hub exposure is the
terminate-and-re-produce story with no new wire vocabulary. BND.ADDR
stays per the handle swap (OQ-SK-03): in-band the handle is the
channel (compat surface only); a real network-B address exists
wherever a local backend binds — the listener's `local_addr` (OQ-SK-08
variants 1–2 cover BIND's reply#1). The one place a virtual subnet
becomes *routable from vanilla apps* is the full-tunnel composition:
the host routes the subnet into the proxy (tun2proxy), so
`connect(10.x.y.z:p)` is an ordinary CONNECT the producer translates.
Worth checking tun2proxy's virtual-network/virtual-DNS support as
prior art before Phase 1 decides whether the crate ships a
translation-table helper or leaves it entirely to assembly-layer
policy.

### OQ-SK-06: noq client support (and the quinn/noq shape split)

**Scope clarification (2026-09-12):** the SOCKS client wrapper is
component 3 of the three-component split (§Vision) — a standalone
client library for downstream users (alknet) that must work with *any*
RFC 1928 server, not just one this crate produces. The motivating case
is iroh's privacy posture: iroh relays (and the peer) see the client's
real IP — intended for relay-assisted p2p, but a client that doesn't
want to leak its IP needs a SOCKS hop ahead of the QUIC dial. This is
the alknet ADR-090 use case generalized; it neither produces nor
consumes channels.

The client wrapper's UDP story is "implement the QUIC runtime's
abstract socket trait over a SOCKS5 UDP association." quinn 0.11 is
proven (quinn-proxy POC, ADR-090). noq (iroh's fork, v1.2.0) has the
same extension point (`AsyncUdpSocket`,
`Endpoint::new_with_abstract_socket`) but the trait shape changed:
`create_sender() -> Pin<Box<dyn UdpSender>>` replaces
`create_io_poller` + `try_send`, and the constructor takes
`Box<dyn AsyncUdpSocket>` instead of `Arc<dyn AsyncUdpSocket>`.

Questions:

- Does this crate ship `Socks5UdpSocket` against noq (behind a feature
  like `noq`), quinn (behind `quinn`), or both? Both implies a shared
  substrate-free core (associate handshake, datagram codec, flow table)
  with two thin trait shells — feasible only if the shared core is
  genuinely trait-agnostic. iroh's adoption makes noq the
  practically-important target; alknet's precedent is quinn.
- noq is not on crates.io at this version (iroh consumes it from the
  n0 workspace/git) — how does this crate depend on it (git dep? wait
  for publication? feature-gate so it is optional)? This may block
  `cargo publish --dry-run` for the client features; a publish-lean
  default (quinn optional, noq git-optional) may be needed.
- Do the ECN/MTU limitations carry over (they should — the SOCKS5 UDP
  header has no ECN field), and does noq's `may_fragment` default
  (`true`) behave the same as quinn's?

This is a research question first (read noq's endpoint/driver loops;
write the trait-shape comparison), then possibly a POC (OQ-SK-07 #3).

**Resolved by the scope decision (2026-09-14, §Vision): transferred to
the alknet rewrite.** The client wrapper is alknet's ancestor-shaped
component (ADR-090 + quinn-proxy POC already live there), consumes no
channels, and has no consumers planned inside this crate — so its
research questions (noq trait-shape comparison, dependency posture,
ECN/MTU carry-over) move to alknet's Phase 0 wholesale. This crate's
client-side story is complete without it: the channels-native consumer
session is POC-validated (POC #1's `use_stream` over a `BiStream`,
POC #2's associate session). The noq POC (OQ-SK-07 #3) is dropped from
this crate's POC list accordingly.

### OQ-SK-07: POC scope for what remains unvalidated

Candidates, in rough priority order (per the SDD process's "validate
promising approaches"):

1. **Channels-native SOCKS5 CONNECT POC** — the producer half over a
   real alkcall channels connection: consumer opens a SOCKS5 channel,
   speaks RFC 1928 CONNECT (via fast-socks5's client types), producer's
   open handler runs the typestate machine over the `BiStream`, dials a
   local echo target, two-pump proxy loop completes. Validates: the
   `register_openable_with_establisher` fit, `pump_bidi` as the data
   plane, params shape (trivial — probably no params), and the
   `BiStream`-as-`T` genericity claim. This is the crate's core value
   proposition and the cheapest to validate (alktunnels' forward POC is
   the template). **Run 2026-09-13 — passed** (`alksocks-connect-poc`,
   8 tests + a curl front-door example; findings in
   `poc-connect-wasm-findings.md`: dial-at-command-read layering
   resolved, identity seam works, refusal paths typed).
2. **UDP ASSOCIATE POC** — the OQ-SK-03 chosen shape, end to end: a
   wrapper-aware client associates, sends length-prefixed datagrams
   down the channel, producer relays to a real UDP endpoint. Validates:
   the sentinel-reply semantics, the datagram codec (fast-socks5's
   `new_udp_header`/`parse_udp_request` over the length framing), the
   flow table, and empty-datagram handling (alktunnels F-2 transfers).
   (Reuses POC #1's producer skeleton; note `run_udp_proxy_custom`
   cannot be used as-is — see the corrected §Prior art caveat.)
   **Design baseline updated 2026-09-13:** the iroh-socks5 eval
   (`docs/research/iroh-socks5-eval.md`) suggests the in-band datagram
   carries `{addr, data}` directly (no RFC UDP header on the tunnel
   wire; RFC codec at front doors only) and drops the producer-side
   flow table (per-datagram addressing in the frame); the sentinel
   question may dissolve for the in-band path (no `BND.ADDR` needed
   when the datagram stage needs no relay address).
   **Baseline settled by the handle swap (2026-09-13, OQ-SK-03):** one
   channel per association; `{addr, data}` frames in-band; channel EOF
   ends the association; RFC codec only at front doors. The POC should
   sketch **both egress variants** behind the dial callback — local
   `UdpSocket` (no flow table) and composed per-target alktunnels
   udp-tunnels (lazy destination→tunnel table, LRU) — and measure the
   per-destination open cost of the composed variant empirically.
   **Run 2026-09-14 — passed** (`alksocks-udp-poc`, 11 tests; findings
   in `poc-udp-associate-findings.md`: the handle-swap data plane
   validated end to end, both egress variants implemented + composed
   per-destination open cost measured at ~0.8 ms, front-door RFC-codec
   composition confirmed, select!-driven stage with the egress
   readiness contract as the load-bearing API finding).
3. **noq `AsyncUdpSocket` impl POC** — the client-side story against
   noq 1.2: associate through a fast-socks5 server, wrap as
   `noq::AsyncUdpSocket`, complete a QUIC handshake. Derisks OQ-SK-06
   (the `create_sender`/`Box` shape changes) before the client spec is
   written. (The quinn variant is already proven by the quinn-proxy
   POC — re-validating it here is optional.)
   **Dropped from this crate (2026-09-14, the scope decision):** the
   client wrapper transfers to the alknet rewrite (§Vision) — OQ-SK-06
   and this POC go with it. (At the time of the decision the list was
   #1, #2, #4 — all passed; #5 (BIND) was added later with OQ-SK-08.)
4. **fast-socks5 wasm check** — minimal crate, `cargo check --target
   wasm32-unknown-unknown`, confirm/inflect OQ-SK-04. Cheap; can fold
   into #1's worktree. **Run 2026-09-13 — fork-minimality verified**
   (~120 lines of `#[cfg]` insertions; wasm-clean `--no-default-
   features` build + functional RFC round-trip test pass; findings in
   `poc-connect-wasm-findings.md`).
5. **BIND POC** — the RFC 1928 BIND command channels-native
   (OQ-SK-08): the producer drives the typestate directly
   (`read_command()` → match `TCPBind` — fast-socks5 parses but
   refuses the command, `lib.rs:384-386`/`server.rs:813-816`; the
   wrapper owns the whole BIND shape, no upstream ask), the phase
   model extends naturally (request → reply#1 with `BND.ADDR` →
   quiet wait → one inbound accept → reply#2 with the peer address →
   raw pass-through data plane, zero per-packet headers in-band;
   iroh-socks5's channels-native BIND is the convergent precedent,
   `docs/research/iroh-socks5-eval.md` §BIND). Sketch **both accept
   variants** behind the accept callback (OQ-SK-08): a feature-gated
   real `TcpListener` backend (faithful RFC — a real network-B
   address in reply#1, vanilla front-door clients work, FTP active
   mode as the canonical test) and the composed alktunnels
   listen-tunnel variant (`register_tunnel_listen_openable` +
   `listen_establisher` + `AcceptQueue` — per-listener ACL for free,
   hub-relayable). Plus a wrapper-aware in-band test and a vanilla
   front-door BIND test ("app server" dials the bound address after
   reply#1). Validates: the accept-side data plane (the mirror of the
   dial callback), reply#1/#2 sequencing on one channel, and the
   alktunnels listen-addr ask's shape. Completes the RFC 1928 command
   surface (all three commands) in the crate.

POC placement conventions (inherited from alktunnels): a POC that needs
code from this repo runs in a worktree/branch (`.worktrees/research/
<task-id>/` per the SDD process); a self-contained POC runs as a
standalone crate in the global workspace with findings written into
`docs/research/` here. Findings always land in `docs/research/`
regardless of where the code lives.

### OQ-SK-08: BIND — the accept-side command (use case found)

**Status: new (2026-09-14, post-POC #2).** Both POCs refused BIND as
RFC-correct; the findings review surfaced a real use case and a
mechanism, so "out of scope until a use case exists" has been met.

**The gap, precisely:** fast-socks5 parses `TCPBind`
(`Socks5Command::TCPBind`, `lib.rs:91`) but every handler refuses it
(`lib.rs:384-386`, `server.rs:813-816` — `CommandNotSupported`); no
bind machinery exists. The typestate flow (`read_command()` returning
`cmd` + `TargetAddr`) means the wrapper drives the command dispatch
itself — implementing BIND is wrapper-side code, **zero upstream
ask** (unlike UDP ASSOCIATE's `run_udp_proxy_custom` bind, which sits
inside an upstream handler).

**The shape (convergent precedent: iroh-socks5's channels-native
BIND, `docs/research/iroh-socks5-eval.md` §BIND):** one channel per
BIND session, phase model — request → reply#1 carrying `BND.ADDR` →
quiet wait (any control byte after reply#1 is protocol garbage, same
as ASSOCIATE's post-reply stage) → exactly one inbound accept →
reply#2 carrying the peer address → raw pass-through data plane (zero
per-packet headers in-band, same as CONNECT; only the ASSOCIATE
datagram stage is framed). RFC-refusal of BIND remains valid for old
consumers; support is purely additive (same ALPN, same params, no
framing change — no one-way-door exposure).

**The mechanism — accept-side resources (the `-R` far-side listener
shape).** The consumer's `-R` path in alktunnels
(`register_tunnel_listen_openable` + `listen_establisher` +
`AcceptQueue`, `alktunnels/src/producer.rs:207,392`) proves accept-side
resources exist without forced binds; SOCKS5 BIND is their mirror
image: the producer-side listener (network B — the app server must
reach it) is the accept resource, each popped accept two-pumps against
the SOCKS5 `BiStream`. The phase-0 hand-off note ("a producer-side
BIND wants the accept-side shape, not a dial") predicted exactly this;
the composition supplies the use case it lacked.

**Accept variants (mirror of OQ-SK-03's egress variants) — the one
real design question is address-first vs accept-first:** RFC BIND is
address-first (bind → advertise in reply#1 → client tells the app
server → it connects → accept → reply#2), while the listen establisher
is accept-first (opening the channel pops an already-accepted
connection — you cannot open before reply#1 to learn the address).
Three resolutions:

1. **Local backend binds for real** (feature-gated `local`) — the
   faithful RFC shape, iroh-socks5-faithful. A real network-B address
   goes in reply#1, vanilla front-door clients work; FTP active mode
   is the canonical use and the reason vanilla client libraries speak
   BIND at all. No upstream ask.
2. **Composed + small alktunnels ask** — the listener lives on a
   listen resource (per-listener ACL for free, hub-relayable per the
   terminate-and-re-produce story); needs "learn the bound address
   without consuming an accept" — the plan carries `local_addr` +
   an inspect-only open, or a `listen/addr` query op. Small ask; we
   own alktunnels (the same finding-first pattern that landed the
   E-01/E-02 sweep in alkcall 0.5.0).
3. **Wrapper-aware only** — zeros in reply#1, reply#2 in-band;
   simplest, but vanilla clients lose BIND and the use case mostly
   evaporates. Retained for completeness; weak hunch against.

Variant 1 is the POC #5 hunch (faithful + zero ask), with variant 2
sketched behind the same accept callback — the composed variant's
value (hub story, per-listener ACL) is the reason to measure it, and
its blocker is the address-inspection ask.

**Security boundary note:** BIND is an *inbound* listener — the
accept-side twin of arbitrary egress. Whatever ACL governs the socks5
resource now also governs who can mint listeners on the producer's
network; per-listener policy (address/port ranges allowed to bind) is
the accept-callback's target-policy twin (OQ-SK-05's mirror). The
open-op gate (`SOCKS5_OPEN_SCOPE`) must distinguish CONNECT/ASSOCIATE
from BIND, or any identity with proxy egress can also open ingress
listeners.

### OQ-SK-09: Channel capacity for proxy workloads (the 256 default)

**Status: new (2026-09-14, post-POC #2).** The 256-channel default
cap (per-connection ADR-040; per-identity ADR-041) is tight for a
proxy workload: every proxied flow *is* a channel (a browser or
tun2proxy fan-out opens one CONNECT channel per flow; composed UDP
egress (OQ-SK-03) spends a downstream channel per destination; BIND
(OQ-SK-08) will spend an accept resource per listener). The caps are
policy knobs — configurable without a wire change, the `u32` wire
space is ~4 billion — so the resolution is config, not wire:

- **No wire change.** Rejected permanently as unnecessary: the u32
  channel-ID space is not the constraint; the caps are policy.
- **Assembly-layer config** is the mechanism (ADR-040/041 are
  explicitly "policy knobs, configurable without a wire change").
  A proxy-shaped deployment raises the per-connection/per-identity
  caps; the default stays conservative for everyone else.
- **Documented proxy-workload default** for Phase 1: the crate docs
  should recommend a raised cap (and its memory arithmetic: a session
  is bounded + predictable — CONNECT/ASSOCIATE are bounded-buffer
  pumps, BIND adds one listener + one accept) so deployments don't
  discover the cap in production.
- **Defense-in-depth posture:** the cap's rationales both still apply
  under SOCKS5. Per-connection memory bound — arguably *weaker* here,
  since the three command shapes are well-known and bounded
  (a session's memory is predictable); per-identity DoS brake —
  arguably *stronger* here, since each SOCKS5 session maps to real
  producer-side resources (a dial, a downstream channel, an accept
  listener) and the cap is the brake on one identity opening
  thousands. Layered defense: ACL → per-connection cap → per-identity
  cap → dial/accept policy; relaxing the caps leans on the rest.

**Considered and rejected: in-channel port multiplexing.** A related
proposal (2026-09-14 review) would reframe the cap by multiplexing
"ports" inside one channel — a `[port: u16][len][payload]` per-chunk
prefix (channel-id-as-IP, port-as-port; modeled on alktty's wire).
Rejected on the established grounds: it re-opens the demux-vs-phase
trade OQ-SK-03 already resolved (phase model, no in-band control
vocabulary needed across both POCs), it breaks the 0-B pass-through
that lets fast-socks5's raw `transfer` drop in unchanged (POC #1's
validated fit), it imposes chunk boundaries on a stream RFC 1928
treats as unstructured, and it violates the one-channel-per-SOCKS5-
session convention (AGENTS.md #10). Channel-ID economy is not a wire
problem the u32 space + policy knobs fail at. **Revisit trigger:** if
a deployment hits a fixed upstream channel budget that config cannot
raise, the additive escape is a *new multiplexed ALPN* — never a
change to this ALPN's framing.

**The related idea that survives — virtual address space /
identity-scoped subnets** — is recorded under OQ-SK-05 (added
2026-09-14): BND.ADDR/DST.ADDR translation via the dial callback,
no wire change.

## Survey / prior-art list

Candidate reading for the research specialist (to be expanded):

- RFC 1928 (SOCKS5) — the fixed protocol: method negotiation, CONNECT,
  BIND, UDP ASSOCIATE, reply codes. RFC 1929 (username/password).
- fast-socks5 `/workspace/fast-socks5` — `src/server.rs` (typestate
  API, interception points, auth traits), `src/client.rs`
  (`Socks5Stream`/`Socks5Datagram`, `use_stream`), `src/lib.rs`
  (`new_udp_header`/`parse_udp_request`, `ReplyError`),
  `examples/router.rs` (conditional interception), `examples/
  custom_auth_server.rs`.
- iroh-socks5 — `crates.io/crates/iroh-socks5` v0.5.0, repo
  `github.com/mattgeddes/iroh-socks5` (crates.io has no repository
  link; the published source matches). Evaluated in
  `docs/research/iroh-socks5-eval.md`: not the protocol base (iroh
  coupling, RFC subset), but the OQ-SK-03 UDP prior art (framed
  `{addr, data}` in-band datagrams, no flow table, control-EOF
  association lifetime) and an independent confirmation of POC #1's
  one-stream-per-session shape.
- alktunnels — `docs/research/phase-0-findings.md` (the `-D`
  composition conclusion, hub-owns-the-connection, the UDP codec
  decision + F-2), `docs/architecture/` (params/ALPN/ACL ADR template),
  POC summaries (POC placement and findings conventions).
- alkcall — `docs/architecture/decisions/` ADR-037/039/049/050 (channel
  ops, params-is-ALPN-specific, establishment, pump_bidi), ledger
  CF-005/CF-006 (identity seam), `src/channels/operations.rs`
  (`ChannelCore`, `OpenHandler`, `Establishment`, `ChannelPlan`),
  `src/channels/pump.rs`.
- alknet — `crates/alknet-client/src/socks5.rs` (ADR-090, the client
  ancestor), `docs/research/quinn-quic-proxy/findings.md` (the POC
  findings: trait + constructor surface, ECN/MTU limitations,
  BotBrowser production precedent).
- noq — `/workspace/noq`: `noq/src/runtime/mod.rs` (`AsyncUdpSocket`,
  `UdpSender`), `noq/src/endpoint.rs` (`new_with_abstract_socket`),
  `noq-udp/src/lib.rs` (`RecvMeta`, `Transmit`), `Cargo.toml` (workspace
  versioning / publication posture).
- alktty — backend inversion point (`TtyBackend`), `TTY_OPEN_SCOPE`
  scope-gating shape, feature-gated `local` backend, wasm-clean
  default-crate verification commands.
- tun2proxy — `/workspace/tun2proxy` `src/udpgw.rs` and its SOCKS5
  files (`socks.rs`, `proxy_handler.rs`): UDP-over-stream framing and
  flow-table prior art (analyzed in alktunnels phase-0-findings; the
  SOCKS5-specific parts feed OQ-SK-03). Also the endgame composition
  partner: it takes `--proxy socks5://...` upstream natively
  (`src/args.rs`) — the vpn-like endgame is tunnel + local bind +
  tun2proxy (§Vision, principle 6).
- alkhttp — `/workspace/@alkdev/alkhttp`: the native-only precedent in
  the suite (axum/reqwest/hyper, no wasm target) — cited in OQ-SK-04
  as the "wasm-clean is preferred, not mandatory" escape hatch.
- iroh — `/workspace/iroh` `iroh/Cargo.toml` (the noq dependency
  posture: `noq = "1.2.0"` from the n0 workspace) — context for
  OQ-SK-06's dependency question; also the privacy motivation for the
  client wrapper (relays/peers see the real IP).

## Convergence checklist (what Phase 0 must produce)

- [ ] Vision + guiding principles captured (this doc, §Vision —
      including the three-component split)
- [ ] Prior-art pass complete: fast-socks5 surface verified (§Prior
      art), alktunnels/alknet/noq lineage mapped, anti-prior-art list
      written; iroh-socks5 evaluated (structural sibling, not the base;
      OQ-SK-03 prior art — `docs/research/iroh-socks5-eval.md`)
- [x] OQ-SK-01 (dial policy) — researched, half-answered (injected
      dialer hunch); **POC #1 resolved the shape empirically** (dial
      callback at the command-read interception point, boxed halves, no
      trait); final decision in Phase 1 against the spec
- [x] OQ-SK-02 (auth mapping) — posture drafted (identity seam
      primary, in-band auth for the local backend); **POC #1 validated
      the seam end to end** (per-call opener identity at the
      establisher; channel-0 identity propagation is a producer
      harness wiring requirement); **direction settled 2026-09-13**
      ("both," split by the door: producer-side identity only — a
      password there is moot against the ACL; consumer-side front door
      owns RFC 1929 for vanilla clients and maps credentials to the
      channel identity); Phase 1 formalizes the door's
      credential→identity mapping
- [ ] OQ-SK-03 (UDP ASSOCIATE) — the shape space written (including
      the phase-model-vs-alktty-demux analysis); resolve via research
      + POC #2, ADR before the first consumer
      **(POC #2 run 2026-09-14 — passed; the handle-swap baseline is
      POC-validated end to end, findings in
      `poc-udp-associate-findings.md`; the datagram framing is
      wire-stable once published — the Phase 1 ADR decision remains)**
- [ ] OQ-SK-04 (fast-socks5 wasm) — the decision tree is written
      (Case 1: wasm wanted → fork-first; Case 2: wasm unwanted →
      plain dep, router path); **POC #4 verified the fork is genuinely
      minimal** (~120 lines of cfg gating; wasm-clean subset is
      functionally complete); the root question ("does wasm make
      sense for alksocks?") now reduces to the adapter-story input
- [ ] OQ-SK-05 (target policy) — folded into the OQ-SK-01 decision;
      scope-gate convention pinned in Phase 1; the 2026-09-14
      virtual-subnet proposal (dial-callback translation, no wire
      change) recorded for Phase 1
- [ ] OQ-SK-08 (BIND) — new (2026-09-14): the gap + use case +
      accept-side mechanism written; resolve via POC #5 + the Phase 1
      ADR (ship in base crate? default accept variant?)
- [ ] OQ-SK-09 (channel capacity) — new (2026-09-14): the proxy-
      workload analysis written (wire change rejected; config is the
      mechanism; in-channel port multiplexing considered and
      rejected); Phase 1 pins the documented proxy-workload
      recommendation
- [x] OQ-SK-06 (noq client) — **resolved by the scope decision
      (2026-09-14, §Vision): transferred to the alknet rewrite**
      (the client wrapper is alknet's ancestor-shaped component,
      consumes no channels, has no consumers planned here); its
      research questions move to alknet's Phase 0; this crate's
      channels-native client story is POC-complete without it
- [x] Targeted POC(s) run + summaries in `docs/research/`
      (three complete: #1 + #4 in `poc-connect-wasm-findings.md`,
      #2 in `poc-udp-associate-findings.md`; #3 dropped with the
      scope decision; **#5 (BIND) added 2026-09-14 with OQ-SK-08 —
      pending**)
- [x] Converge: recommended approach written up, ready to hand to the
      Architect for Phase 1 (§Convergence, 2026-09-14)

## Convergence — the recommended approach

This is Phase 0's output: a clear WHAT/WHY with validated approaches,
ready for the Architect.

### The crate, scoped

**alksocks = the SOCKS5 producer/consumer protocol pair on alkcall
channels (socks + channels, nothing else).** The three-component split
resolved: components 1+2 are this crate; component 3 (the quinn/noq
`AsyncUdpSocket` client wrapper) moves to the alknet rewrite, where
its ancestor work (ADR-090, quinn-proxy POC) already lives. No local
binds except the two explicit, optional, feature-gated assembly shapes
(producer's local backend; consumer's front door).

### The recommended approach (validated pieces → crate shape)

- **Protocol base: fast-socks5's explicit typestate API** — the
  `T: AsyncRead + AsyncWrite + Unpin` genericity carries both
  substrates (POC #1: a channels `BiStream` drops in directly; the
  local backend would feed a `TcpStream`). Drive the typestate
  directly for UDP ASSOCIATE (`run_udp_proxy_custom` is unusable —
  unconditional kernel bind; file the upstream ask).
- **Wire shape: the handle swap** (POC #2-validated) — one ALPN
  (`alk/socks5`), one open op (`channels/socks5/sub`), trivial
  params; the RFC conversation is the data plane; CONNECT =
  `pump_bidi` pass-through post-reply (POC #1); ASSOCIATE = the
  `select!`-driven datagram stage over `[len: u16 BE][addr + data]`
  frames (alktunnels' length codec; RSV/FRAG only at front doors;
  channel EOF ends the association; per-datagram addressing, no flow
  table).
- **Egress seam: the dial-callback shape, extended** — `DialFn` for
  CONNECT (POC #1's command-read interception point) +
  `EgressFactory` for ASSOCIATE (POC #2), both function-not-trait,
  both returning boxed halves. Local-socket and composed
  (per-target alktunnels udp-tunnels) providers are assembly-layer
  policies; the composed variant's per-destination open cost is
  measured (~0.8 ms) and its per-target-ACL-for-free benefit is
  validated.
- **Auth: "both," split by the door** (OQ-SK-02's settled posture) —
  producer side: the alkcall identity seam only (the in-band
  conversation runs NoAuth); the consumer's front door owns RFC 1929
  for vanilla clients and maps credentials to the channel identity.
- **Layering: the alktty/alktunnels precedents** — substrate-agnostic
  protocol modules at the crate core; feature-gated backend modules
  (local binds) never imported by the protocol layer; producer +
  consumer + params modules mirroring POC #1/#2's structure; the
  fork posture for fast-socks5 is vendoring the `T`-generic subset
  into this crate gated behind a `net`-shaped feature (POC #4:
  ~120 cfg lines, wasm-clean subset functionally complete).
- **Open for Phase 1 ADRs** (inputs collected, decisions pending):
  the demux-vs-phase extensibility trade (evidence now favors the
  phase model — no in-band control vocabulary was needed across both
  POCs); the params-format/ALPN naming ADRs (wire-stable once
  published, no consumers exist yet); `SOCKS5_OPEN_SCOPE` convention
  (must distinguish BIND from CONNECT/ASSOCIATE — OQ-SK-08's security
  note); the door's credential→identity mapping shape; the wasm
  decision (Case 1 vs Case 2) once the adapter story is confirmed;
  BIND's base-crate inclusion + default accept variant (OQ-SK-08);
  the proxy-workload channel-cap recommendation (OQ-SK-09); the
  virtual-subnet translation-layer shape (OQ-SK-05 addendum).
- **Upstream asks (we own both upstreams; file early, land there):**
  fast-socks5 — the `net` feature gate (POC #4's ~120-line change)
  and the `run_udp_proxy_custom` unconditional-bind seam. alktunnels —
  listen-addr inspection without consuming an accept (OQ-SK-08
  variant 2's blocker). First-real-consumer asks, the alkcall
  E-01/E-02 precedent.

### What Phase 0 could NOT answer (handed to Phase 1)

- The datagram-framing ADR (the one-way door) — now has empirical
  ground: framing validated, LRU/dedup semantics pinned, open cost
  measured. Decide with the first consumer in sight.
- The wasm root question (OQ-SK-04) — mechanism de-risked; the
  adapter-story input is a product decision, not a research one.
- Target-policy shape (OQ-SK-05) — the dialer-refuses shape is
  evidence-backed; the declarative-allowlist variant stays a Phase 1
  choice. (The 2026-09-14 virtual-subnet proposal is recorded there —
  dial-callback translation, no wire change.)
- Channel capacity for proxy workloads (OQ-SK-09) — wire change
  rejected; assembly-layer config + a documented proxy-workload cap
  recommendation stay Phase 1 decisions. In-channel port
  multiplexing considered and rejected there.
- BIND — RFC-refused in both POCs; **a use case and a mechanism were
  found in the 2026-09-14 findings review** — OQ-SK-08 records the
  gap, the accept-side-resource shape (mirroring alktunnels' `-R`
  far-side listener), the address-first-vs-accept-first design
  question, and POC #5. Deciding whether BIND ships in the base
  crate (and which accept variant is default) is a Phase 1 ADR —
  support is additive (old consumers still get the RFC refusal), so
  nothing here is a one-way door.