alksocks/docs/research/poc-bind-findings.md

---
status: complete
last_updated: 2026-09-20 (ledger statuses updated with the graduation
landed; both alktunnels asks superseded in shape)
---

# alksocks POC findings: channels-native SOCKS5 BIND

POC #5 from phase-0 §OQ-SK-07, run 2026-09-15. Crate:
`alksocks-bind-poc` (standalone, `/workspace/alksocks-bind-poc/`), against
alkcall 0.7.1 (crates.io), alktunnels 0.1.0 (crates.io, `local` feature;
the listen surface is complete in the published version),
fast-socks5 1.0.0 (crates.io). 9 tests, all pass; `cargo clippy
--all-targets -- -D warnings` and `cargo fmt --check` clean.

Validates OQ-SK-08's design shape: **one channel per BIND session; the
phase model extends (request → reply#1 with `BND.ADDR` → quiet wait →
exactly one inbound accept → reply#2 with the peer address → raw
pass-through data plane); both accept variants behind the accept
callback; the `socks5:bind` scope gate.** fast-socks5 parses the
command but refuses it (`lib.rs:384-386`, `server.rs:813-816`); the
wrapper drives the typestate directly and owns the whole BIND shape:
**zero fast-socks5 upstream ask for BIND itself** (the typestate's
`read_command()` returns `(cmd, target)` and the wrapper branches;
`reply_success`'s `sock_addr` parameter is the reply#1 carrier;
`pump_bidi` is the data plane).

## What was validated

1. **The BIND phase model was confirmed end to end.** The RFC
   conversation and the data plane ride the same channel `BiStream`:
   the typestate runs `accept_no_auth → read_command` (BIND arrives
   as `Socks5Command::TCPBind`), reply#1 carries `BND.ADDR`, the
   quiet wait selects the one inbound accept against the control
   stream, reply#2 carries the peer address, and `pump_bidi`
   (inline, R-02) two-pumps the accepted connection against the
   channel. Zero per-packet headers in-band; the CONNECT pass-through
   conclusion extends literally (BIND's post-reply#2 stage is a
   plain byte stream).
2. **The local accept variant (variant 1, the faithful RFC shape),
   confirmed.** A real `TcpListener` per BIND session: reply#1
   carries the listener's *actual* `local_addr` (a real network-B
   address); the "app server" dials the advertised address; reply#2
   carries the *real* peer address (`accept()`'s peer, byte-exact;
   the test asserts the app's ephemeral port); the data plane echoes
   both directions. Vanilla front-door clients work (test 6).
3. **The composed accept variant (variant 2) confirmed, with the
   sequencing finding below.** The listener lives on an alktunnels
   listen-tunnel resource (`register_tunnel_listen_openable` +
   `AcceptQueue` + a real far-side `TcpListener`); the SOCKS5
   producer opens the tunnel *during the quiet wait* and the popped
   accept's halves become the data-plane peer. The full stack
   round-trips: SOCKS5 consumer → SOCKS5 producer → composed accept →
   `alk/tunnel` listen channel → tunnel producer → real listener →
   the app server's connection → back through the pump. Per-listener
   ACL for free (the tunnel resource's ACL governs who can mint the
   listener), hub-relayable, the variant's whole point.
4. **The scope gate is confirmed.** The pump handler reads the
   open-op `AuthContext`'s identity and requires `socks5:bind` before
   serving a BIND; an identity without it gets the RFC-faithful
   `ConnectionNotAllowed` (0x02) refusal, while CONNECT still works
   for the same identity (the gate distinguishes ingress listeners
   from proxy egress; one identity having egress does not imply
   ingress). The gate is the open-op identity seam consumed at
   command-dispatch time; no new ops, no params change, no
   one-way-door exposure.
5. **The quiet wait's semantics are confirmed.** A control byte after
   reply#1 is protocol garbage (the ASSOCIATE post-reply semantic
   BIND shares; RFC 1928 §3's "BIND: no further control data"
   reading); the session is refused with no data plane. A client
   that BINDs and vanishes (EOF mid-wait) tears the listener down
    with its session; the accept future (which owns the listener)
    is dropped by the `select!` branch; a fresh dial to the
    advertised address fails with connection refused. The session's
    natural end (half-close post-data-plane) releases the listener
    the same way.
6. **Failure mapping is confirmed RFC-faithful.** A factory failure
   (pre-reply#1: an unbindable port, a held port) maps to reply#1
   with the factory error's reply code (shortage → GeneralFailure);
   an accept-stage failure (post-reply#1) maps to reply#2 with the
   mapped refusal code and no data plane. No phantom listeners, no
   phantom data planes; refusals are typed end to end.
7. **One registration, all three commands, regression-guarded.**
   CONNECT (POC #1's data plane, unchanged) and UDP ASSOCIATE (the
   POC #2 skeleton) still serve on the same `channels/socks5/sub` op
   after the BIND branch lands. The RFC 1928 command surface is now
   complete in the crate's shape: CONNECT + BIND + ASSOCIATE.
8. **The vanilla front door is confirmed for BIND.** The raw-pipe
   bridge (POC #1's CONNECT front-door shape, reused verbatim) carries
   a full vanilla BIND conversation: an in-process RFC 1928 client
   (greeting → BIND command → reply#1 → reply#2 → data plane) through
   a `copy_bidirectional` pipe onto the channel. Zero protocol
   translation at the door; the RFC conversation passes through
   transparently (0 B pass-through, exercised for the BIND
   conversation this time).

## Structural findings (the load-bearing discoveries)

**The address-first-vs-accept-first deadlock: the POC's one real
discovery, and the composed variant's sequencing is now pinned.**
SOCKS5 BIND is address-first (reply#1 must carry `BND.ADDR` *before*
the app server can dial), while alktunnels' listen establisher is
accept-first (its establishment phase pops an already-accepted
connection, so the open op blocks until one arrives). The first cut
opened the listen-tunnel in the factory call (before reply#1) and
deadlocked into the establishment timeout: the app server cannot dial
until reply#1 tells it the address, and the open cannot complete until
it dials. **The resolution: reply#1 first, the tunnel open rides the
accept future.** The quiet wait is exactly where the establisher's
accept-pop block belongs. What remains upstream-blocked is *learning
the bound address without consuming an accept* (ledger ask #1): the
stand-in is the factory's carried `bind_addr` (the expected
`local_addr` the far-side real listener reports).

Consequence for the ADR: variant 2 needs TWO upstream asks, not one:
(1) listen-addr inspection without consuming an accept (the address
half), and (2) accepted handles carrying peer metadata (the reply#2
half). Both are additive surface additions, not changes; the ask
ledger below records both with the evidence.

**Establishment-bound interaction (the composed variant's wait
bound).** The accept future's tunnel open runs under the listen
establisher's default 10s establishment bound; a BIND wait longer
than that resolves as a refusal (reply#2, GeneralFailure via the
mapped open error). Correct-by-backstop, but a real BIND deployment
(FTP control sessions idle far longer than 10s) needs either a raised
bound (the open-op's `timeout` parameter; a registration choice, no
wire change) or the accept future structured so the bound covers only
the open, not the wait (POC note: the bound covered the whole accept
here; the crate's shape should bound only the open-op round trip).
Phase 1 pins this with the registration posture.

**The teardown-at-birth lesson repeats, and the fix is structural.**
The composed variant's first working cut dropped the
`TakenHalves::session` (the channel-entry owner) while destructuring
it; the tunnel EOF'd at birth and the data plane read `early eof`
(POC #2's findings predicted exactly this: "the session must live
inside the table entry; the *compiler* should enforce it"). The fix:
`BindTargetHandle` carries `_session: Option<TunnelSession>`; the
owner rides the handle and drops with it. This is now the third
witness of the pattern (POC #2's egress table, alktunnels ADR-005's
teardown contract, here); the crate's Phase 1 shape should make the
plan payload own its channel handles structurally, never by let-binding.

**Peer-address fidelity is lost through the composed path** (ledger
ask #2). The popped accept handle (`alktunnels::TargetHandle`) carries
boxed halves only; the real peer address exists at the tunnel
producer's listener; in-band the composed variant reports the sentinel
(`0.0.0.0:0`) for reply#2 (the handle-swap reading applied to BIND:
the reply is RFC-compatibility surface; the data plane is the
channel). The local variant reports the real peer (no hop). Ledger
item #2 is the fidelity ask.

**The quiet wait is `select!`-single-shot, not a loop** (unlike
ASSOCIATE's stage): the accept resolves at most once, and the control
stream's first byte ends the session (garbage). A loop was
unnecessary; clippy's `never_loop` caught the first cut's vestigial
`loop`; the phase model's clean statement is that BIND's quiet wait
has exactly two exits (the accept, or the control stream's
EOF/garbage/error). The data plane starts only from the accept
branch.

**`BindAccept`'s future-ownership shape is the accept-side twin of
the egress's readiness contract.** The accept future owns the
listener (local variant) or the tunnel-open + popped halves (composed
variant); the quiet wait's `select!` drops it on the control-stream
branch, and that drop IS the client-gone teardown. The crate's Phase 1
equivalent: the accept callback's future must own its resources
end-to-end (the same ownership lesson as POC #2's egress, mirrored).

## Wire/API notes for the wrapper

- fast-socks5's client `request()` reads exactly one reply: BIND's
  reply#2 is hand-read with fast-socks5's own public
  `read_address` codec (reply#1's codec applied again; no second
  codec hand-rolled). The consumer's reply#2 reader (`read_reply2`)
  is the Phase 1 client-session sketch.
- `Socks5ServerProtocol::reply_success(sock_addr)` is reply#1's
  carrier: the `sock_addr` parameter carries `BND.ADDR` verbatim
  (the local variant's real listener; the composed variant's
  expected far-side address). No upstream change needed.
- fast-socks5's `new_reply` helper is private; the BIND reply#2
  writer hand-rolls the 10-byte reply (VER, REP, RSV, ATYP, addr,
  port; 10 bytes v4 / 22 v6). Ledger ask #3 (fast-socks5, courtesy):
  publish `new_reply` (or a `reply(code, addr)` constructor) so
  embedders don't re-encode replies. (2026-09-20: rides the inline
  vendor; see §ledger statuses.)
- `ToTargetAddr::to_target_addr()` (not `From`) is the
  `SocketAddr → TargetAddr` conversion; `TargetAddr::from` does not
  exist (the POC hit this; the wrapper's accept layer will too).
- The listen establisher's default 10s bound covers the composed
  variant's whole accept future in this POC's shape; see the
  establishment-bound finding above for the Phase 1 posture.
- The scope gate is read from the `OpenHandler`'s `AuthContext`
  (CF-005/CF-006's per-call opener identity), the same seam POC #1
  validated for session-gating, now consumed for a *command-class*
  distinction. `socks5:bind` as a scope string follows the
  `socks5:open` convention (Phase 1 pins the exact convention).

## Upstream-ask ledger (the one-version alktunnels bump)

**Ledger statuses (2026-09-20, the graduation landed).** The user's
standing note held: alktunnels 0.2.0 (ADRs 007/008, over alkcall
0.8.0) shipped in one version bump, but adopted the ssh
`forwarded-tcpip`-shaped alternative over the per-ask carriers, so
both asks are **superseded in shape**, not implemented as posed:

1. **Listen-addr inspection without consuming an accept: dissolved.**
   The bind-first establisher (`bindfirst_establisher`, ADR-008 §1)
   binds during establishment, so the open-op reply natively carries
   the real OS-chosen bound address (the `bound` reply field via
   alkcall 0.8.0's `Establishment::with_reply_field`, ADR-049
   amendment 3; consumed via `open_channel_with_reply` /
   `TunnelListener::bound()`). There is no accept to avoid consuming;
   this ask's stand-in (the factory's carried `bind_addr`) is retired,
   as is the POC's "open rides the accept future" sequencing
   workaround, and the 10s establishment-bound finding dissolves with
   it (the accept wait lives in the pump phase now). The
   accept-first surface (`listen_establisher` + `AcceptQueue`) remains
   in 0.2.0 unchanged for the accept-as-open shape.
2. **Accepted handles carrying peer metadata: landed at the wire's
   native moment.** The forwarded op (`channels/tunnel/forwarded`,
   ADR-008 §3) carries `{listen, substrate, peer}` params per accept;
   `TargetHandle` gained no peer field; the graduation chose the
   forwarded-op shape over this item's option-i carrier. Correlation
   is a producer-minted u32 token (Amendment 1, 2026-09-18), not the
   originally-planned channel-ID key.
3. **(fast-socks5, courtesy)** `new_reply` is private; publish it
   (or a constructor) so embedders don't re-encode the reply wire
   form. Also still open from POC #4: the `net` feature gate and the
   `run_udp_proxy_custom` unconditional-bind seam. (Posture note,
   2026-09-20: fast-socks5 is third-party upstream and these are no
   longer asks; all three move into the inline vendor, OQ-SK-04
   resolved. 2026-09-21: under the extraction (ADR-011 §Amendment),
   `new_reply` is the one that rides in-tree; the `net` gate and the
   bind seam dissolve with the kernel-net region, which is not
   copied.)

The POC's evidence stands as the record of what was validated against
alktunnels 0.1.0; the Phase 1 shape composes variant 2 against 0.2.0
(`register_tunnel_bindfirst_openable` + `BindFirstInjections`).

The user's standing note: collect alktunnels additions so one version
bump ships them all. The POC ran against published alktunnels 0.1.0
(no fork needed; the listen surface is complete there), and the asks
are additive surface, discovered in priority order:

1. **Listen-addr inspection without consuming an accept** (the
   address half of address-first-vs-accept-first). The plan carries
   `local_addr` + an inspect-only open, or a `listen/addr` query op
   (OQ-SK-08 variant 2's original blocker, now POC-evidenced: the
   factory's carried `bind_addr` stand-in is the exact shape the ask
   retires). Evidence: the composed accept's reply#1 advertises an
   *expected* address; without the ask, a producer whose listener
   binds an OS-chosen port cannot advertise it before the accept.
2. **Accepted handles carrying peer metadata** (the reply#2 half).
   `AcceptFn`'s `TargetHandle` carries boxed halves only; the real
   peer address exists at the tunnel producer's listener. Evidence:
   the composed accept's reply#2 reports the sentinel; the RFC's
   "reply#2 carries the address of the incoming connection" is
   unfilled on the composed path. Shape: `TargetHandle` gaining an
    optional `peer: Option<SocketAddr>` (or a sibling
    `AcceptedHandle`); additive, no wire change.
3. **(fast-socks5, courtesy)** `new_reply` is private; publish it
   (or a constructor) so embedders don't re-encode the reply wire
   form. Also still open from POC #4: the `net` feature gate and the
   `run_udp_proxy_custom` unconditional-bind seam. (2026-09-21: under
   the extraction, ADR-011 §Amendment, `new_reply` is the one that
   rides in-tree; the `net` gate and the bind seam dissolve with the
   kernel-net region, which is not copied.)

No asks block the POC's conclusions; 1–2 shape variant 2's *full*
fidelity, and the POC's stand-ins (carried `bind_addr`; sentinel
reply#2) are honest interim shapes.

## OQ status after this POC

- **OQ-SK-08 (BIND)**: POC-validated end to end: the phase model
  extends (reply#1 → quiet wait → accept → reply#2 → pass-through);
  both accept variants implemented (local faithful + composed
  listen-tunnel); the scope gate (`socks5:bind`) distinguishes
  ingress from egress; the address-first-vs-accept-first question is
  *resolved in shape* (reply#1 first, the open rides the accept
  future) with the two upstream asks pinned as the remaining blockers
  for variant 2's full fidelity. Remaining for Phase 1: ship-in-base-
  crate + default-accept-variant ADR (the support is additive, old
  consumers still get the RFC refusal, so nothing here is a
  one-way door); the establishment-bound posture; the exact
  scope-string convention.
- **OQ-SK-07**: #1, #2, #4, #5 complete; #3 dropped (transferred with
  OQ-SK-06). The register is closed for this crate's Phase 0.
- **OQ-SK-01 (dial policy)**: the accept seam is the dial-callback
  shape's mirror (`BindAcceptFactory`: function-not-trait, boxed
  halves, one instance per session). The no-trait precedent now holds
  for the accept plane too.

## POC placement

Standalone crate (global workspace, `/workspace/alksocks-bind-poc/`)
per the placement conventions; it composes three published crates
(alkcall 0.7.1, alktunnels 0.1.0, fast-socks5 1.0.0) and needs no code
from this repo. Findings land here; the crate is the artifact.