alksocks/AGENTS.md

AGENTS.md

Operating instructions for opencode agents working in this repo. opencode auto-loads this file as instructions, overriding the built-in defaults for this project. Custom agents in .opencode/agents/ inherit these rules unless their own prompts say otherwise.

Git Workflow

Commit and push when reasonable. When a change is complete and verified (build + lint + tests pass), commit and push to origin/main without asking. This overrides the built-in default of "only commit when explicitly asked."

The workflow:

1. Make the change
2. Verify: cargo test, cargo clippy --all-targets -- -D warnings, cargo fmt --check, cargo doc --no-deps if docs changed
3. Inspect git status and git diff before staging; stage only the intended files, never secrets
4. Write a concise commit message matching the repo style (see git log --oneline -10). For multi-point changes, use a summary line plus a body with bullet points and a verification block.
5. git push origin main
6. Report the commit hash and the verification summary

Exceptions (do not commit or push without asking):

• The change is exploratory / speculative (you're not sure the user wants it kept)
• The user is actively reviewing the diff and may ask for changes
• The change touches the wire format or a trait shape that backends or consumers implement (one-way doors; see "Wire formats are stable" and "Backend trait shapes are one-way doors" below; once consumers exist, those signatures are wire-stable contracts)
• You'd be force-pushing, amending a published commit, creating an empty commit, or skipping hooks

Never commit secrets, keys, or credentials. If a commit fails or hooks reject it, fix the issue and create a new commit; do not amend the failed one.

Git identity is preconfigured (glm-5.3-flash <glm-5.3-flash@alk.dev>). Do not change git config, skip hooks, or use git commit -i.

Project Conventions (Rust / SOCKS5 protocol crate)

This is the SOCKS5 protocol crate, a wrapper around fast-socks5 that offers the SSH -D (dynamic / SOCKS5 proxy) capability alongside alktunnels' -R and -L, composed with alkcall channels ("ALPN as a service"). It sits in the alk* family: alkcall (call + channels, the substrate), alktty (terminal sessions), alktunnels (arbitrary -L/-R/ tunnels). The distinguishing posture of this crate: the SOCKS5 server never binds a port unless explicitly configured to: the protocol is served inside alkcall channels data channels (a produced, ACL-scoped resource), not on a kernel socket. A local bind is one optional assembly-layer shape, not the protocol's home. The conventions below apply to all work in src/ and tests/. They mirror .opencode/agents/implementation-specialist.md §Project Conventions and are repeated here so they apply to every session, not just spawned implementation agents.

1. No comments in code unless the user explicitly asks. This is a project-wide convention. Doc comments (///, //!) are fine and expected on public API. Inline // comments only when the user asks or when a non-obvious safety/correctness constraint would otherwise be missed (e.g., "a two-pump tunnel must shut down the opposite sink on pump completion, since try_join! alone deadlocks; see alkcall ADR-050's pump_bidi / alknet ADR-078").

2. Error handling: thiserror for library error types; map SOCKS5 reply codes (fast_socks5::ReplyError) faithfully per RFC 1928. No panics in library code. No unwrap() or expect() outside tests. If you reach for unwrap, the error path wasn't specified, so stop and decide what should actually happen. For poisoned RwLock/Mutex, use unwrap_or_else(|e| e.into_inner()) so a panic in one operation does not cascade to other operations.

3. tokio is the async runtime: all I/O is async. fast-socks5 is tokio-native; the wrapper's protocol layer, pumps, and client session types are all async. Use tokio::sync primitives (oneshot, mpsc) for lifecycle correlation. Any non-wasm backend module (local TCP listener for a "real" socks5:// endpoint) lives behind a feature flag like alktty/alktunnels' local.

4. WASM target is load-bearing (by default), meaning the default crate (protocol-only) should compile to wasm32-unknown-unknown, following the alktty/alktunnels precedent. Use the wasm-clean tokio subset (rt, sync, io-util, macros, time); do NOT use features = ["full"]; and keep socket/platform I/O feature-gated. Note: fast-socks5 uses tokio::net and socket2 unconditionally as published; the posture is the targeted fork (OQ-SK-04, resolved 2026-09-20, convention 17; extraction pinned 2026-09-21, ADR-011 §Amendment; fork 2026-09-22, ADR-013): the T-generic subset was extracted in-tree (the kernel-net handlers are not copied), so the RFC 1928 core (src/rfc1928/) is wasm-clean by construction with no net-shaped feature; socket I/O rides local alone. Run the wasm check whenever a non-backend module changes; it is a hard gate (no dependency-graph failure is expected, since the core contains no tokio::net).

5. Wire format is stable: the SOCKS5 protocol itself is RFC 1928 (fixed); this crate's wire surface is the ALPN + the channel open-op params that carry it. Those params are a one-way door once consumers exist. Follow the alktunnels precedent: params are a self-contained JSON object identifying the produced resource (alkcall ADR-039, whose params is ALPN-specific, interpreted by the open handler). Any params-format ADR must be written before the first consumer exists; after that, changes are additive-only.

6. Producer/consumer, not server/client, because both sides of a channels connection can initiate. A producer exposes the SOCKS5 service (registers openable channels via ChannelCore::register_openable); a consumer opens SOCKS5 channels and speaks RFC 1928 inside them. Both sides can be both simultaneously; connection direction (who opened it) is independent of service direction (who dials targets, who serves). Avoid "server" and "client" framing in docs and API names; use "producer" and "consumer," or "accept side" / "connect side" for the connection-establishment half specifically. (SOCKS5's own client/server roles are RFC vocabulary and keep their RFC names inside the protocol layer.) See alkcall ADR-022, ADR-037.

7. Substrate-agnostic by construction: the protocol layer must not know whether the far side of a SOCKS5 connection is a kernel TCP socket, a channels BiStream, a unix socket, or an in-process pipe. fast-socks5's explicit server API is generic over T: AsyncRead + AsyncWrite + Unpin (Socks5ServerProtocol<T, ...>, transfer(inbound, outbound)); the wrapper must preserve that genericity: the channels adapter feeds the SOCKS5 state machine a BiStream (which is AsyncRead + AsyncWrite), the local backend feeds it a TcpStream. Substrate-specific types are confined to feature-gated backend modules, injected at the assembly layer, the same inversion-point pattern as alktty's TtyBackend and alktunnels' pump halves.

8. Two-pump shutdown-on-completion is a contract: the SOCKS5 CONNECT data plane is the canonical two-pump shape (one pump per direction). Each pump MUST shut down the opposite sink when it completes; tokio::try_join! alone deadlocks. The helper is pinned upstream as alkcall channels::pump_bidi (ADR-050, review 007 R-03), so use it; do not hand-roll the two-pump shape. The channels layer drops all per-channel senders on transport EOF, so rely on that for teardown, and emit EOF sentinels (zero-length chunks) on clean sink shutdown. Await pump_bidi inline inside the OpenHandler's task, because the returned JoinHandle must track the data-plane lifetime (R-02; early return = teardown-at-birth).

9. No forced local binding: the defining requirement of this crate. The SOCKS5 server must run without binding any port: the RFC 1928 conversation is carried inside a channels data channel, and target dials happen on the producing side (or hop further through alktunnels/alksocks). Local 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), and the consumer may expose the resource on a local port (the ssh -D front door that vanilla clients (curl, browsers, tun2proxy) point at). The protocol itself never binds. UDP ASSOCIATE is the hard case: RFC 1928 replies with a UDP relay address and the client sends datagrams to it, which seems to demand a bind; how the relay address is virtualized (or the associate shape adapted) is a Phase 0 question (OQ-SK-03). Binding decisions belong to the caller (assembly layer), never the protocol crate.

10. Backpressure and limits are inherited, not redefined: bounded per-channel buffers, the 256-channel default caps (per-connection memory bound, ADR-040; per-identity DoS defense, ADR-041, i.e. policy knobs, configurable without a wire change; the u32 wire space itself is ~4 billion), monotonic channel IDs, and the zero-length-sentinel EOF convention are alkcall channels invariants (see alkcall ADR-040/041/034). The crate consumes them via ChannelCore/ChannelClient; do not build a second demux/mux or re-derive limits. SOCKS5 CONNECT is a single stream per open (no sub-demux inside the channel); one channel per SOCKS5 session, no protocol-level flow key.

11. Vendored core types come from alkcall: Connection, ProtocolHandler, BiStream, BidiStreamSource, AuthContext, Identity, IdentityProvider, AccessControl, OwnershipProvider, HandlerError, StreamError come from alkcall::core. Do not vendor copies into this crate. alkcall is v0.10.x, where breaking changes are expected at this major-zero stage; this is an early consumer, so we find and fix issues upstream rather than working around them. Pin alkcall = "0.10.1" and bump deliberately. The establishment surface (alkcall ADR-049 + amendments) is load-bearing for this crate: SOCKS5 session opens use register_openable_with_establisher so a refused/auth-failed session is a typed channel:open_failed call error, never a phantom channel; the establisher returns the negotiated handle via Establishment::new(plan) (typed-opaque ChannelPlan, whose payloads must be Send + Sync; 0.8.0 adds the optional reply projection, with_reply_field(s) from ADR-049 amendment 3). The 0.7.0 identity surface (ledger CF-005/CF-006) is load-bearing for auth mapping: the per-call opener identity arrives on the open-op hooks; map it to SOCKS5 credentials/ACL there, not via any in-band SOCKS auth unless clients need RFC-facing username/password.

12. Access control: the producer's openable channels get authorization for free via ChannelCore::register_openable, which wires AccessControl into the operation spec (the registry runs the ACL before the open handler). Scope-gate SOCKS5 opens (e.g. SOCKS5_OPEN_SCOPE, shape following alktty's TTY_OPEN_SCOPE) and optionally consult OwnershipProvider for resource ownership. SOCKS5 is arbitrary-egress by nature; treat the open gate and the target policy as the security boundary; per-target allowlists (if any) are a producer-side policy question for Phase 1 (OQ-SK-05). See alknet ADR-024 (registry layering, alkcall ADR-019), alknet ADR-050 (ownership, alkcall ADR-011), and alktunnels' resolved posture (target selection lives in the SOCKS5 protocol at the producing side; whatever ACL governs the socks5 resource governs everything reachable through it).

13. Feature flags: substrate backends are feature-gated if the need arises. The base crate should compile lean (no socket/platform deps unless the feature is on). Verify both cargo test (default) and cargo test --all-features pass if features are added.

14. Naming follows the Rust standard: snake_case for functions/variables/ modules, PascalCase for types/traits, SCREAMING_SNAKE_CASE for constants.

15. Module structure: one module per file under src/, re-exported from src/lib.rs. Public API surface is lib.rs re-exports. The expected shape (pending Phase 1 pinning): the SOCKS5 protocol wrapper (server state machine + client session), the channels adapter (the producer half, the open handler for this crate's ALPN), the consumer half (a typed client that opens SOCKS5 channels and speaks RFC 1928 through them), and feature-gated backend modules (the optional local-bind listener). Backend modules are feature-gated and never imported from the protocol/adapter/client modules.

16. ALPN naming: this crate owns a alk/-prefixed ALPN (provisional alk/socks5; final naming per alkcall ADR-004/ADR-006 convention). One ALPN per protocol. The ALPN string is wire-stable once published; decide via ADR before the first consumer.

17. Upstream: alkcall is ours to shape; fast-socks5 is forked in-tree. alkcall is ours (the actively co-developed substrate): file asks early and land them there rather than working around them locally; the alktunnels precedent (the E-01/E-02 sweep, filed from its Phase 0 and landed in alkcall 0.5.0 within a day; the graduation sweep landed in alkcall 0.8.0 / alktunnels 0.2.0). fast-socks5 is NOT ours and never will be; it is third-party upstream (/workspace/fast-socks5 is a read-only reference checkout, v1.0.0, MIT), but the T-generic subset we depend on is now ours, as a targeted fork (OQ-SK-04 resolved 2026-09-20 as the inline-vendor extraction; extraction pinned 2026-09-21, ADR-011 §Amendment; fork posture pinned 2026-09-22, ADR-013): the subset lives in src/rfc1928/ as fully owned code, and project conventions apply to it unconditionally (no vendor carve-outs, no lint-allow posture, no verbatim preservation). The extraction cut (ADR-011's table) is the hand-port map: if a future need surfaces (e.g. the kernel-net region for a standalone vanilla-server example), port the piece from the reference checkout, adapt it to the conventions, and let the differential suite guard it. A future upstream fix that matters is a hand-port too; nothing is absorbed silently, and nothing waits on upstream. Keep /workspace/fast-socks5 for differential testing of RFC edge cases. Provenance is permanent: the module docs and the bundled license notice (src/rfc1928/LICENSE) always name the origin (v1.0.0, the extraction range, the fork point): extend, never replace, the notice.

18. No em dashes in prose. Do not use the em dash (U+2014) in source doc comments, markdown docs (including all of docs/ and tasks/), agent prompts under .opencode/agents/, or commit messages. Restructure instead: split the sentence, use parentheses, commas, a colon, or a semicolon, whichever reads naturally, and vary the choice rather than converting every instance the same way. A spaced hyphen (-) is not an acceptable substitute; it reads as a different but equally recognizable writing tell. Inside fenced code blocks the rule applies to prose-y content only: line comments, ASCII-diagram label separators, and template placeholders are rewritten too, while wire data, JSON/BAST examples, and tool transcripts survive verbatim. The same rule covers en dashes used as clause separators, though en dashes inside numeric ranges keep their normal meaning. Hyphens in compound words (wasm-clean, fast-socks5, alk/socks5) are untouched. The one exemption is docs/reviews/: reviews are archived historical records, so their prose is preserved verbatim and is excluded from the em-dash greps.

Verification Commands

Run these before committing. All must pass.

cargo test                                    # full suite
cargo clippy --all-targets -- -D warnings
cargo fmt --check
cargo doc --no-deps                           # if docs changed
cargo test --all-features                     # if features are added
cargo test --manifest-path fuzz/shared/Cargo.toml   # corpus replay (the fuzz gate)
cargo check --target wasm32-unknown-unknown   # default crate stays wasm-clean
cargo clippy --target wasm32-unknown-unknown -- -D warnings
cargo publish --dry-run --allow-dirty         # before a release

Release steps (after the version bump + verification)

1. Commit the release (bump + CHANGELOG/README/AGENTS pins).
2. Tag it: git tag -a vX.Y.Z -m "release: vX.Y.Z (<the tag>)" annotated, always (v0.1.0/v0.2.0 are lightweight; annotated since the v0.3.0 release, 2026-10-19).
3. git push origin main && git push origin vX.Y.Z.
4. cargo publish (no --allow-dirty once the tree is clean).
5. Confirm with cargo search / cargo info.

The corpus replay is the fuzz gate (the alkcall §7.9 posture): it replays every committed seed through the same invariant functions the fuzz targets run, on stable, without nightly. Campaigns (nightly, cargo-fuzz) run manually via fuzz/run-detached.sh when src/wire.rs, src/rfc1928/, or src/params.rs change, never as a foreground child of an agent session (docs/research/fuzzing.md §5).

The wasm check is the structural guard for the "default crate is wasm-clean" invariant (same as alktty/alktunnels); run it whenever a non-backend module changes. It is a hard gate: the RFC 1928 core is an extraction with no kernel-net code (ADR-011 §Amendment), so no dependency-graph failure is expected.

Architecture Context

• docs/research/phase-0.md holds the Phase 0 (Exploration) document and the current state of this repo: vision, prior art, open questions (OQ-SK-01..NN), and POC candidates. Read it before non-trivial work. The SDD process lives in docs/sdd_process.md (Phase 0 in progress; docs/architecture/ does not exist yet).
• The prior art for this crate:
  • alktunnels (/workspace/@alkdev/alktunnels, v0.1, the closest sibling): the producer/consumer tunnel crate on alkcall channels. Its Phase 0 findings (docs/research/phase-0-findings.md) settled the hub-owns-the-connection model, the two-pump shape, the establishment story (alkcall ADR-049), and the -D-composes-at-the- assembly-layer conclusion; this crate is that conclusion's realization. Its Phase 1 ADRs (params shape, ALPN strategy, access-control posture) are the template for this crate's Phase 1.
  • alktty (/workspace/@alkdev/alktty, v0.4): the first producer/consumer protocol crate on alkcall channels; the backend inversion point, wasm-clean default crate, and feature-gated local backend precedents.
  • alkcall (/workspace/@alkdev/alkcall, v0.9.x, crates.io). The substrate: call protocol + channels multiplexing. This crate consumes alkcall::core types and the channels ChannelCore/ChannelClient/register_openable_with_establisher surface, same as alktty/alktunnels. 0.8.0 adds the establisher reply projection (with_reply_field, ADR-049 amendment 3), flavor-form open-op ids in discovery (ADR-047 amendment 3), and the in-tree ChannelRelay/HubLegTemplate (ADR-051), the hub re-produce machinery the SOCKS5 hub story composes on.
  • alktunnels (v0.2.0, ADRs 007/008): the direct op (channels/tunnel/direct, dynamic-target egress; OQ-SK-01 Option A's vehicle), the bind-first establisher + forwarded op (the composed BIND substrate; OQ-SK-08 variant 2), and TunnelListener.
  • fast-socks5 (/workspace/fast-socks5, v1.0.0, MIT, third-party upstream, NOT ours and never will be). The SOCKS5 implementation the RFC 1928 core forked: explicit typestate server API (Socks5ServerProtocol<T, states::*>), generic over T: AsyncRead + AsyncWrite + Unpin; run_tcp_proxy / run_udp_proxy_custom / transfer are the interception points; client side has Socks5Stream (generic over the backing socket) and Socks5Datagram (UDP associate). The posture is the targeted fork (OQ-SK-04 resolved 2026-09-20 as the inline-vendor extraction; extraction pinned 2026-09-21, ADR-011 §Amendment; fork 2026-09-22, ADR-013, convention 17): the T-generic subset lives in src/rfc1928/ as owned code, no kernel-net code and no net feature; BIND and the new_reply publication are the two carried changes; the reference checkout stays for differential testing of RFC edge cases.
  • alknet's SOCKS5 client at /workspace/@alkdev/alknet/crates/alknet-client/src/socks5.rs (ADR-090), the client-side example: Socks5UdpSocket implements quinn::AsyncUdpSocket so QUIC rides SOCKS5 UDP ASSOCIATE. Validated by the quinn-proxy POC (/workspace/@alkdev/alknet/docs/research/quinn-quic-proxy/ findings.md). The open question for this crate's client story: the same trait impl against noq (iroh's quinn fork, /workspace/noq, which has noq::AsyncUdpSocket, Endpoint:: new_with_abstract_socket exist but with a different surface shape; see OQ-SK-06).
• Key upstream ADRs that inform this crate's design (alknet numbers; alkcall's ports live in /workspace/@alkdev/alkcall/docs/architecture/ decisions/):
  • alknet ADR-093 / alkcall ADR-035: channels pure channel multiplexing (8-byte header, no stream_type); the SOCKS5 session rides inside the channel's BiStream
  • alknet ADR-078 / alkcall ADR-050: two-pump shutdown-on-completion; the helper is pinned upstream as alkcall::channels::pump_bidi (use it, do not hand-roll)
  • alkcall ADR-049 (amendment 2): the establishment phase; the establisher returns the negotiated handle via Establishment::new (typed-opaque ChannelPlan, Send + Sync payload constraint)
  • alknet ADR-074 / alkcall ADR-038: ChannelConnection as a BidiStreamSource; every handler receives a Connection
  • alknet ADR-075 / alkcall ADR-039: ChannelsAdapter / ChannelManager (substrate-agnostic demux; params is ALPN-specific, i.e. for this crate the SOCKS5 service identity/policy)
  • alknet ADR-071 / alkcall ADR-034: channels wire format (one-way door); alkcall ADR-036: channel 0 is pre-negotiated alk/call; alkcall ADR-037: channel lifecycle operations (channel/open on channel 0)
  • alkcall ADR-042: hub relay; alktunnels' hub-proxy refinement, in which the hub terminates and re-produces per-hop ACL (a SOCKS5 resource is the same shape, "further downstream", per alktunnels phase-0-findings §Prior art)
  • alkcall ledger CF-005/CF-006 (0.7.0): the connect-side serving identity seam: caller identity precedence (token > ServingConfig.identity > transport), per-call opener identity on the open-op hooks
• The suite decomposition context: alknet was the massive POC ("vpn-like without being a vpn" + transport agnosticism) being rewritten; this crate extracts and improves its SOCKS5 story (client side: ADR-090's proxy support; server side: the -D capability alktunnels deferred to composition). alknet-client/src/socks5.rs and the quinn-proxy POC findings are the direct ancestors of this crate's client work.
• If a TODO references a design direction that a later ADR has decided against, the TODO is stale; remove it and align with the ADR. Do not implement the rejected design.