socks5

type AddrSpec struct {
	FQDN string // fully-qualified domain name (used when ATYP is DOMAINNAME)
	IP   net.IP // IP address (used when ATYP is IPv4 or IPv6)
	Port int    // port number
}

type AuthContext struct {
	// Method is the authentication method that was used.
	Method uint8
	// Identity is the verified principal — for RFC 1929 username/password
	// this is the authenticated username. It MUST NOT contain credentials.
	// Empty when no identity is associated with the method (e.g. NoAuth).
	// (Sec-06)
	Identity string
	// Payload carries method-specific data. Implementations MUST NEVER
	// place passwords or other secrets here; loggers may write this map
	// at debug level. Prefer Identity for the verified principal name.
	// For backward compatibility, UserPassAuthenticator continues to set
	// Payload["username"] alongside Identity. (Sec-06)
	Payload map[string]string
}

type Authenticator interface {
	// Authenticate performs the method-specific sub-negotiation. It is
	// invoked *after* Server.authenticate has written the
	// method-selection reply (R-03).
	Authenticate(reader io.Reader, writer io.Writer) (*AuthContext, error)
	// GetCode returns the method identifier byte for this authenticator.
	GetCode() uint8
}

type BoundConn struct {
	net.Conn
	// contains filtered or unexported fields
}

type BytesPool interface {
	// Get returns a byte slice of at least n bytes.
	Get(n int) []byte
	// Put returns a byte slice to the pool.
	Put(buf []byte)
}

type Client struct {
	*ClientConfig
}

type ClientConfig struct {
	// ProxyAddr is the "host:port" of the SOCKS5 proxy.
	ProxyAddr string

	// Username and Password for RFC 1929 authentication. When Username
	// is non-empty the client offers AuthMethodUserPass.
	Username string
	Password string

	// Auth is an optional custom authenticator. For username/password
	// auth prefer the Username/Password fields instead. Auth is used
	// as a fallback for custom authentication methods only.
	Auth Authenticator

	// Dialer is the dialer used to connect to the proxy. If nil and
	// DialFunc is also nil, a default net.Dialer is used.
	Dialer *net.Dialer

	// DialFunc is a custom dial function for connecting to the proxy.
	// When set it takes precedence over Dialer. This allows custom
	// transport layers (TLS, Unix sockets, SSH tunnels, etc.).
	DialFunc func(ctx context.Context, network, addr string) (net.Conn, error)

	// HandshakeTimeout is the maximum time for the SOCKS5 handshake
	// (method negotiation + auth + request/reply). Zero means no
	// separate handshake timeout; Dialer.Timeout or context deadlines
	// still apply to the TCP connect and handshake respectively.
	HandshakeTimeout time.Duration

	// ResolveOnProxy enables SOCKS5h hostname-forwarding mode.
	// When true, the client always sends the target hostname as an FQDN
	// in the SOCKS5 request, leaving DNS resolution to the proxy. When
	// false (default), the client resolves IP literals locally but still
	// sends hostnames as FQDNs.
	ResolveOnProxy bool
}

type CloseReader interface {
	CloseRead() error
}

type CloseWriter interface {
	CloseWrite() error
}

type CredentialStore interface {
	// Valid returns true if the given username/password pair is valid.
	Valid(user, password string) bool
}

type Datagram struct {
	// Frag is the SOCKS5 UDP fragment field (RFC 1928 §7). Bit 0x80
	// marks the end-of-sequence fragment; the low 7 bits encode the
	// position (1..127). FRAG=0x00 means a standalone (non-fragmented)
	// datagram. (Clean-06)
	Frag    uint8
	DstAddr *AddrSpec
	Data    []byte
}

type Handler func(ctx context.Context, writer io.Writer, request *Request) error

type Listener struct {
	// contains filtered or unexported fields
}

type MethodReply struct {
	Version uint8
	Method  uint8
}

type MethodRequest struct {
	Version uint8
	Methods []byte
}

type Metrics interface {
	// IncConnectionsAccepted is called for every accepted TCP connection,
	// before any per-IP limit or semaphore check.
	IncConnectionsAccepted(ctx context.Context)

	// IncConnectionsRejected is called when a connection is rejected by a
	// per-IP limit, an auth failure, or a ruleset denial. The reason
	// string is a stable short identifier such as "per_ip_limit",
	// "auth_failed", or "rule_denied".
	IncConnectionsRejected(ctx context.Context, reason string)

	// IncCommand is called once per accepted CONNECT/BIND/ASSOCIATE,
	// after the request has passed rule checks. The command argument
	// is one of CommandConnect, CommandBind, CommandAssociate.
	IncCommand(ctx context.Context, command uint8)

	// IncAuthFailure is called every time an Authenticator returns an
	// error. The method byte identifies the authenticator (e.g.,
	// AuthMethodUserPass).
	IncAuthFailure(ctx context.Context, method uint8)

	// AddBytesProxied may be called by custom Forwarders to report the
	// number of bytes transferred in a given direction ("inbound" or
	// "outbound"). The built-in DefaultForwarder does not currently
	// emit this event; it is exposed for users who wrap their own
	// Forwarder and want per-byte accounting.
	AddBytesProxied(ctx context.Context, direction string, n int64)
}

type Middleware func(next Handler) Handler

type MiddlewareChain []Middleware

type NoAuthAuthenticator struct{}

type NoOpMetrics struct{}

type NoOpObserver struct{}

type Observer interface {
	// OnConnect is called after a CONNECT request is accepted and the
	// target connection is established.
	OnConnect(ctx context.Context, req *Request, target net.Conn)

	// OnBind is called after a BIND listener is successfully created.
	OnBind(ctx context.Context, req *Request, listener net.Listener)

	// OnAssociate is called after a UDP ASSOCIATE is set up.
	OnAssociate(ctx context.Context, req *Request, conn net.PacketConn)

	// OnError is called when an error occurs during request handling.
	OnError(ctx context.Context, req *Request, err error)

	// OnShutdown is called when the server has finished shutting down.
	OnShutdown()
}

type PacketConn struct {
	// contains filtered or unexported fields
}

type ProtoReply struct {
	Version  uint8
	Reply    uint8
	Reserved uint8
	BndAddr  *AddrSpec
}

type ProtoRequest struct {
	Version  uint8
	Command  uint8
	Reserved uint8
	DstAddr  *AddrSpec
}

type ReplyError struct {
	Code    uint8
	Message string
}

type Request struct {
	Version     uint8
	Command     uint8
	Reserved    uint8
	AuthContext *AuthContext
	RemoteAddr  net.Addr
	DestAddr    *AddrSpec
	// contains filtered or unexported fields
}

type RoutinePool interface {
	// Submit submits a function for execution. It may block if the
	// pool is at capacity. Returns an error if the task cannot be
	// submitted (e.g., pool is shut down).
	Submit(f func()) error
}

type Server struct {
	// contains filtered or unexported fields
}

type ServerConfig struct {
	// AuthMethods is the list of supported authentication methods, tried
	// in order. If nil, NoAuthAuthenticator is used.
	AuthMethods []Authenticator

	// NameResolver resolves domain names to IP addresses. If nil,
	// DNSResolver is used. The returned slice should be in resolver
	// order; the CONNECT handler tries each address in turn
	// (happy-eyeballs) until one succeeds. BIND and ASSOCIATE use only
	// the first address. (C-10)
	NameResolver func(ctx context.Context, name string) (context.Context, []net.IP, error)

	// RuleSet determines whether to allow or deny requests. If nil,
	// PermitAll is used.
	RuleSet func(ctx context.Context, req *Request) (context.Context, bool)

	// AddressRewriter optionally rewrites the destination address before
	// connecting. If nil, no rewriting is performed.
	AddressRewriter func(ctx context.Context, request *Request) (context.Context, *AddrSpec)

	// Logger is used to log errors and informational messages. If nil,
	// a default zerolog.Logger writing to stderr is used.
	Logger *zerolog.Logger

	// Dial is the function used to establish outbound TCP connections for
	// CONNECT requests. If nil, net.Dialer is used.
	Dial func(ctx context.Context, network, addr string) (net.Conn, error)

	// BindIP is the IP address to bind to for BIND and ASSOCIATE replies.
	// If nil, 0.0.0.0 is used.
	BindIP net.IP

	// BindPort is the port to bind to for BIND and ASSOCIATE replies.
	// If zero, a random port is chosen.
	BindPort int

	// ProxyListen creates a TCP listener with custom control (e.g., for
	// transparent proxying or reuseport). If nil, net.Listen is used.
	ProxyListen func(ctx context.Context, network, addr string) (net.Listener, error)

	// ProxyListenPacket creates a UDP packet connection. If nil,
	// net.ListenPacket is used.
	ProxyListenPacket func(ctx context.Context, network, addr string) (net.PacketConn, error)

	// ProxyOutgoingListenPacket creates a UDP packet connection for
	// outgoing relay traffic. If nil, ProxyListenPacket (or net.ListenPacket)
	// is used.
	ProxyOutgoingListenPacket func(ctx context.Context, network, addr string) (net.PacketConn, error)

	// PacketForwardAddress determines the source address for forwarded
	// UDP packets. If nil, the default implementation returns the local
	// address of the packet connection.
	PacketForwardAddress func(ctx context.Context, destinationAddr string, packet net.PacketConn, conn net.Conn) (net.IP, int, error)

	// ProxyListenBind creates a TCP listener specifically for BIND
	// requests. If nil, ProxyListen (or net.Listen) is used.
	ProxyListenBind func(ctx context.Context, network, addr string) (net.Listener, error)

	// ListenBindReuseTimeout is the duration for which a BIND listener
	// port can be reused after the previous binding is released.
	ListenBindReuseTimeout time.Duration

	// ListenBindAcceptTimeout is the maximum time to wait for an incoming
	// connection on a BIND listener.
	ListenBindAcceptTimeout time.Duration

	// Forwarder copies data between client and target connections. If
	// nil, DefaultForwarder is used.
	//
	// The signature was changed from func(src, dst io.ReadWriter)
	// error to func(src, dst net.Conn) error. The previous signature
	// type-asserted to net.Conn internally; making net.Conn explicit
	// removes a hidden interface requirement. For pure io.ReadWriter
	// use cases (e.g., in-process pipes) call LiteForwarder directly.
	//
	// C-11: custom Forwarders MUST perform a TCP half-close (CloseWrite)
	// on EOF in each direction so that BIND-style two-way streams finish
	// cleanly; otherwise long-lived peers may stall waiting for FIN. The
	// built-in DefaultForwarder (backed by ProxyStream) already honours
	// this contract via the CloseWriter interface.
	//
	// MeteredForwarder(metrics) is the canonical wrapper for
	// reporting per-byte traffic to a Metrics implementation without
	// re-implementing the half-close logic.
	Forwarder func(src, dst net.Conn) error

	// Observer receives lifecycle events. If nil, NoOpObserver is used.
	Observer Observer

	// Metrics receives operational counter events such as accepted
	// connections, rejected connections, command counts and auth
	// failures. If nil, NoOpMetrics is used. (C-07)
	Metrics Metrics

	// IdleTimeout is the maximum time a connection can remain idle before
	// being closed. Zero means no idle timeout.
	IdleTimeout time.Duration

	// BytesPool is used to allocate byte slices. If nil, a default pool
	// is used.
	BytesPool BytesPool

	// Context is the base context for the server. If nil, context.Background
	// is used.
	Context context.Context

	// FragmentTimeout is the maximum time to wait for a complete sequence
	// of UDP fragments before discarding. Default is 5 seconds.
	// (RFC 1928 §7 requires a reassembly timer.)
	FragmentTimeout time.Duration

	// FragmentPoolSize is the maximum byte size for which the fragment
	// reassembler uses a sync.Pool to reuse allocations. Fragments larger
	// than this are heap-allocated. Default 1500 (typical MTU). (P3-2)
	FragmentPoolSize int

	// MaxDatagramSize limits the maximum acceptable UDP datagram payload
	// size. Datagrams exceeding this limit are silently dropped.
	// Zero means no limit (up to 65535 bytes).
	MaxDatagramSize int

	// RateLimit limits per-client UDP datagram throughput (tokens per
	// second). Zero means no rate limiting.
	RateLimit float64

	// StrictRSV controls whether a non-zero RSV byte in the SOCKS5
	// request header causes the connection to be rejected. When false
	// (default), a non-zero RSV is logged but the request proceeds.
	// When true, the server replies with ReplyGeneralFailure.
	StrictRSV bool
	// LenientUDPRSV, when true, allows non-zero RSV bytes in incoming
	// UDP relay datagrams (logged but accepted). Default false (strict
	// rejection per RFC 1928 §7). This is the UDP counterpart of the
	// TCP-side StrictRSV escape hatch. (R-09)
	//
	// Note: the field is inverted vs. StrictRSV so that the zero value
	// preserves the current strict / RFC-compliant behaviour.
	LenientUDPRSV bool
	// StrictAssociateBinding, when true, pins both IP *and* port from
	// the first datagram on late-binding UDP ASSOCIATE sessions
	// (DST.ADDR=0.0.0.0:0). When false (default), only the IP is
	// pinned, matching prior behaviour. (R-04)
	StrictAssociateBinding bool

	// StrictBindOrigin, when true, refuses BIND requests that leave
	// the expected peer address unspecified (DST.ADDR=0.0.0.0:0).
	// RFC 1928 §6 lets the client leave the peer unspecified and
	// resolve it on the first accepted connection, but that lets
	// any peer take over the bind slot. With StrictBindOrigin=true,
	// the server replies with ReplyConnectionNotAllowed instead of
	// opening a wildcard listener, forcing the client to pre-commit
	// to a specific peer. (Sec-05)
	StrictBindOrigin bool

	// RoutinePool is an optional goroutine pool for limiting concurrency.
	// If nil, a new goroutine is spawned per connection.
	RoutinePool RoutinePool

	// ConnectHandle, BindHandle, AssociateHandle are optional custom
	// handlers that replace the default implementation for each command.
	ConnectHandle   Handler
	BindHandle      Handler
	AssociateHandle Handler

	// Listeners maps listener addresses to in-process virtual
	// listeners. When a CONNECT request targets a virtual listener,
	// the server routes the connection through the listener instead
	// of making an outbound TCP dial. The map key must match the
	// address returned by the listener's Addr().String().
	Listeners map[string]*Listener

	// ConnectMiddleware, BindMiddleware, AssociateMiddleware are optional
	// middleware chains applied to each command handler.
	ConnectMiddleware   MiddlewareChain
	BindMiddleware      MiddlewareChain
	AssociateMiddleware MiddlewareChain

	// MaxConnections limits concurrent connections. Zero means no limit.
	// When the limit is reached, new connections block until a slot is
	// available. (D2)
	MaxConnections int

	// MaxConnectionsPerIP limits the number of concurrent connections from
	// a single source IP. Zero means no per-IP limit (only the global
	// MaxConnections, if set, applies). When the limit is reached, new
	// connections from that IP are accepted at the TCP layer but
	// immediately closed by the server. (C-04)
	MaxConnectionsPerIP int

	// HandshakeTimeout is the maximum time for the SOCKS5 handshake
	// (version check + auth + request). If zero, no handshake timeout
	// is applied (IdleTimeout still covers the whole connection). (D6)
	HandshakeTimeout time.Duration

	// AssociateSetupTimeout is the maximum time the server waits for the
	// first datagram from the expected UDP client after a successful
	// ASSOCIATE reply. If no datagram arrives in time, the association is
	// torn down. Zero disables the timeout. (Sec-02 — slow-loris defence
	// on UDP ASSOCIATE setup.)
	AssociateSetupTimeout time.Duration

	// ReadBufferSize sets the kernel read buffer (SO_RCVBUF) on accepted
	// connections. Zero means use OS default. (D7)
	ReadBufferSize int

	// WriteBufferSize sets the kernel write buffer (SO_SNDBUF) on accepted
	// connections. Zero means use OS default. (D7)
	WriteBufferSize int

	// KeepAlivePeriod controls TCP keep-alive on accepted connections.
	// When > 0, SetKeepAlive(true) is called and the keep-alive period
	// is set to this value on every accepted *net.TCPConn. Zero leaves
	// the keep-alive setting at the OS default (typically off on most
	// kernels for accepted sockets). Useful for long-lived CONNECT
	// tunnels behind NAT where dead-peer detection would otherwise
	// take minutes or hours. (C-09)
	KeepAlivePeriod time.Duration

	// TLSConfig optionally wraps the accept-side listener in
	// tls.NewListener before the SOCKS5 version byte is read. The TLS
	// handshake completes first, then the SOCKS5 protocol runs on the
	// inner cleartext stream. This is the symmetric counterpart to
	// ClientConfig.DialFunc: clients that need to speak SOCKS5-over-TLS
	// already wrap their dialer; the server side now has an equivalent
	// one-liner.
	//
	// When non-nil, both Server.Serve and Server.ListenAndServe wrap
	// the listener via tls.NewListener(ln, TLSConfig). The TLS
	// handshake is lazy (triggered by the first Read/Write on the
	// *tls.Conn) and thus respects the connection deadline set by
	// HandshakeTimeout before the SOCKS5 negotiation begins.
	// A separate TLSHandshakeTimeout is therefore unnecessary in the
	// common case; if the OS TCP timeout is insufficient, set
	// HandshakeTimeout to bound both the TLS and SOCKS5 phases. (Sec-15)
	TLSConfig *tls.Config

	// AcceptProxyProtocol, when true, makes the server read a HAProxy
	// PROXY protocol v1 (text) or v2 (binary) header from each accepted
	// connection BEFORE the SOCKS5 version byte. The source address
	// from the header replaces the underlying TCP RemoteAddr() for the
	// rest of the connection's lifetime, which means MaxConnectionsPerIP
	// (C-04) and PermitSource (C-13) see the real client behind an L4
	// load balancer. When the header is malformed, the connection is
	// closed before any SOCKS5 negotiation occurs.
	//
	// Use this only when every accepted connection comes from a trusted
	// proxy that always emits the header (e.g. an HAProxy / AWS NLB
	// frontend). Enabling it on a public listener allows attackers to
	// spoof their source IP.
	AcceptProxyProtocol bool
}

type SocksConn struct {
	net.Conn
	// contains filtered or unexported fields
}

type StaticCredentials map[string]string

type UDPRelay struct {
	// contains filtered or unexported fields
}

type UserPassAuthenticator struct {
	Credentials CredentialStore
}

type UserPassReply struct {
	Version uint8
	Status  uint8
}

type UserPassRequest struct {
	Version  uint8
	Username string
	Password string
}