From 83fea2224475749bc88ef7aae46fc837aa81210a Mon Sep 17 00:00:00 2001
From: Vijit Singh <vijit.n.singh@gmail.com>
Date: Sun, 23 Aug 2026 23:06:48 -0500
Subject: [PATCH] feat(pools): dial a pool through a SOCKS5 proxy (#400)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

XMRig supports a per-pool `socks5`; RigForge dropped it. `parse_config` rebuilds
every pool from a fixed key set, so the key was gone before the XMRig config was
generated, and `_warn_unknown_config_keys` told the operator it was ignored. That
left a rig no way to reach a stratum published as an onion service.

- The mapper re-attaches `socks5` in a single-line pass modelled on the #115
  `tls-fingerprint` pass above it, for the same two reasons: emitted ONLY when
  set, so no existing rig's generated config changes shape on its next apply,
  and a one-line pass because kcov cannot attribute in-string program lines.
  POOLS_JSON reaches generate_xmrig_config wholesale, so nothing else changed.
- `socks5` joins the pool-key allowlist, so the "ignored" warning stops.
- config.reference.json gains `"socks5": null` and a `_docs` sentence;
  docs/configuration.md gains a pool-field row.

The issue asks for the proxy to be validated with "the same rules the pool URL
gets". A second copy of those checks would satisfy that on the day it was written
and drift the first time either side was touched, so the rules now live in one
`_validate_host_port <value> <label> <example-port>` that both keys call. Every
check and regex inside it is verbatim from the pool-url path it replaces.

One operator-facing string changes as a result, and only this one: the port-range
error was "Pool port must be between 1 and 65535" and is now "Pool url port must
be between 1 and 65535", now that two keys can produce it. The other three are
byte-identical for the url path.

Why the onion case works: Client::Socks5::connect() uses ATYP 0x03 (DOMAINNAME)
for any host that is not an IP literal, so the name goes to the proxy and the
proxy resolves it — which is why there is no `socks5h` to ask for. The pool URL
host pattern already accepted a v3 .onion.

Verified: `bash tests/run.sh` -> 1867 passed, 0 failed (baseline 1853; exactly the
14 new assertions, each confirmed to have executed rather than inferred from a
green suite). Three mutants, all killed: dropping the validation call kills the
four rejection assertions (the IPv6 acceptance correctly survives); dropping the
re-attach pass kills eight; reverting the allowlist kills exactly the unknown-key
assertion. Two of the fourteen survive every mutant and should — `no socks5 key
when unset` and `null socks5 = absent` assert an absence that also holds without
the feature, so they are shape-regression guards, not proof it works. The
extraction is guarded by the pre-existing pool-url tests, which pass unchanged.
`shfmt -i 4 -d` and `bash -n` clean; config.reference.json re-parsed.

NOT run locally: shellcheck (its peak on a file this size has OOM-killed sessions
on this box) and the Docker e2e — CI covers both. Also unproven: a real SOCKS5
dial to an onion stratum, which needs bench hardware.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E5tRnh79JUNv6q2q4F5qRh
---
 CHANGELOG.md          | 10 ++++++++
 config.reference.json |  4 +--
 docs/configuration.md |  1 +
 rigforge.sh           | 58 ++++++++++++++++++++++++++++++++-----------
 tests/run.sh          | 50 +++++++++++++++++++++++++++++++++++++
 5 files changed, 107 insertions(+), 16 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b4ee78b..828094c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,16 @@ All notable changes to RigForge are documented here. The format is based on
 
 ## [Unreleased]
 
+### Added
+
+- **A pool can be dialled through a SOCKS5 proxy (#400).** XMRig has always supported a per-pool
+  `socks5`, but RigForge rebuilt each pool from a fixed key set, so the key was dropped and the
+  operator got a warning that it was ignored — leaving a rig no way to reach a stratum published as
+  an onion service. `socks5` now passes through as `host:port`, emitted only when set, so no existing
+  rig's generated config changes shape on its next apply. Its address is checked by the same
+  validator as the pool `url`, which is now shared between the two rather than copied. RigForge
+  points the miner at a proxy; running one is still the operator's to arrange.
+
 ### Fixed
 
 - **A failed watchdog re-render no longer reports the change as applied (#395).** `install_watchdog`
diff --git a/config.reference.json b/config.reference.json
index 3e96b08..7cb87d4 100644
--- a/config.reference.json
+++ b/config.reference.json
@@ -1,8 +1,8 @@
 {
-    "_docs": "Reference for every config.json key, each shown with its default value. Copy ONLY the keys you actually want to change into config.json; any key you omit keeps the default shown here. The pool target is the native XMRig 'pools' array: each pool needs a 'url' (host:port); every other field falls back to a Pithead-friendly default. A pool's 'user' is the rig's label on the dashboard (defaults to the machine hostname); list multiple entries for failover. An empty ACCESS_TOKEN (the default) leaves the rig's read-only HTTP API open (no token) — which matches Pithead's default no-auth stats probe; set a value only to require a Bearer token (then match it dashboard-side). 'autotune' is one of \"disabled\" (default — no scheduled tuning), \"performance\" (monthly tune for raw hashrate), or \"efficiency\" (monthly tune for hashrate-per-watt). 'watchdog' set to \"enabled\" installs a timer that health-checks the miner every 'watchdog_interval_min' minutes (default 5) and restarts it after two consecutive checks see 0 H/s or a dead API; 'max_temp_c' (empty = off) additionally stops the miner above that °C and starts it again 5°C below — check what your board's thermal_zone0 reports before setting it. 'miner_user' (empty = run as root, the default) runs the miner as that dedicated non-root system user — RigForge applies the MSR preset root-side; on CPU families without a known preset the ~10-15% MSR boost is skipped. 'api_allow_from' (empty = off) scopes the API port(s) — including the writable control port when 'control' is enabled — to one IPv4 or IPv6 address/CIDR source + loopback via an own nftables table (Linux, needs nft; for an IPv6 source the served port must bind a v6 address, so set 'api_bind'/'control_bind' to \"::\"). Set 'api' to enabled for the sister API: a second read-only port (default 8081) serving XMRig's summary enriched with RigForge tune/power/health/provenance data, gated by the same ACCESS_TOKEN; 'api_port'/'api_bind' place it. Set 'control' to \"enabled\" for the WRITABLE control path (#236): a SEPARATE authenticated port (default 8082, 'control_port'/'control_bind' place it) that lets a Pithead stack apply config changes through RigForge so config.json stays authoritative. Fail-closed: enabling it REQUIRES both ACCESS_TOKEN and api_allow_from (a writable API with no token or no pinned source is refused). Only pools, DONATION, autotune, watchdog(+interval), and max_temp_c are writable through it (and the REMOTE path refuses to disable watchdog or to unset/out-of-band max_temp_c — a rig's thermal protection can only be removed by a local rigforge.sh apply, #257); every change is validated, the old config is snapshotted to config-backups/, and a change that doesn't come back live is rolled back. Set 'control_upgrade' to \"enabled\" (a SECOND opt-in, only valid when 'control' is also enabled) to let the stack trigger this rig to upgrade its own RigForge to the latest release (#308, ADR 0002) — i.e. fetch and run new root code on a remote trigger. Default off, and never on just because 'control' is: the rig refuses any target that isn't a real release newer than the one running, verifies the release commit is reachable on main (the release branch), throttles repeat runs, and health-gates the swap with rollback. It rides the control path's own Bearer token + api_allow_from pin. Releases are checksummed, not signed — GitHub is the trust root (see SECURITY.md). For co-locating a miner on a busy box (e.g. a Pithead stack host), 'hugepages_reserve_extra_mb' (default 0) adds that many MB of HugePages to RigForge's computed mining reservation so the pool covers stack + miner — RigForge stays the sole writer of the reservation and, when the box's existing reservation already covers both, changes nothing and needs no reboot; 'hugepages_pool_ceiling_mb' (default 0 = no ceiling) is a HARD CAP on the runtime pool RigForge will grow to, in MB, distinct from hugepages_reserve_extra_mb (which adds declared headroom into the computed requirement rather than bounding the write) — set it on a RAM-constrained co-resident box so the grow-only write can never exceed the box's honest capacity no matter what the requirement/availability math computes (rigforge#398; an odd MB value floors to the 2MB page below, e.g. 5121 -> 5120MB effective, never rounds up past the declared ceiling); 'threads' (empty/null = auto) caps the RandomX thread count (a ceiling — min(auto, threads), e.g. nproc-2) so the miner leaves spare cores, and it sizes the reservation to match. A TLS pool can pin the server certificate with 'tls-fingerprint' (its SHA-256 as 64 hex chars; null = no pin) — XMRig does no CA verification for stratum, so the pin is the only server authentication TLS stratum has. Full descriptions: https://github.com/p2pool-starter-stack/rigforge/blob/main/docs/configuration.md#configuration-reference",
+    "_docs": "Reference for every config.json key, each shown with its default value. Copy ONLY the keys you actually want to change into config.json; any key you omit keeps the default shown here. The pool target is the native XMRig 'pools' array: each pool needs a 'url' (host:port); every other field falls back to a Pithead-friendly default. A pool's 'user' is the rig's label on the dashboard (defaults to the machine hostname); list multiple entries for failover. A pool's 'socks5' (default null) dials that pool through a SOCKS5 proxy given as host:port \u2014 e.g. \"127.0.0.1:9050\" for a local Tor client, which is how a rig reaches a stratum published as an onion service; XMRig sends the hostname to the proxy, so the proxy resolves it. RigForge points the miner at a proxy, it does not install or run one. An empty ACCESS_TOKEN (the default) leaves the rig's read-only HTTP API open (no token) — which matches Pithead's default no-auth stats probe; set a value only to require a Bearer token (then match it dashboard-side). 'autotune' is one of \"disabled\" (default — no scheduled tuning), \"performance\" (monthly tune for raw hashrate), or \"efficiency\" (monthly tune for hashrate-per-watt). 'watchdog' set to \"enabled\" installs a timer that health-checks the miner every 'watchdog_interval_min' minutes (default 5) and restarts it after two consecutive checks see 0 H/s or a dead API; 'max_temp_c' (empty = off) additionally stops the miner above that °C and starts it again 5°C below — check what your board's thermal_zone0 reports before setting it. 'miner_user' (empty = run as root, the default) runs the miner as that dedicated non-root system user — RigForge applies the MSR preset root-side; on CPU families without a known preset the ~10-15% MSR boost is skipped. 'api_allow_from' (empty = off) scopes the API port(s) — including the writable control port when 'control' is enabled — to one IPv4 or IPv6 address/CIDR source + loopback via an own nftables table (Linux, needs nft; for an IPv6 source the served port must bind a v6 address, so set 'api_bind'/'control_bind' to \"::\"). Set 'api' to enabled for the sister API: a second read-only port (default 8081) serving XMRig's summary enriched with RigForge tune/power/health/provenance data, gated by the same ACCESS_TOKEN; 'api_port'/'api_bind' place it. Set 'control' to \"enabled\" for the WRITABLE control path (#236): a SEPARATE authenticated port (default 8082, 'control_port'/'control_bind' place it) that lets a Pithead stack apply config changes through RigForge so config.json stays authoritative. Fail-closed: enabling it REQUIRES both ACCESS_TOKEN and api_allow_from (a writable API with no token or no pinned source is refused). Only pools, DONATION, autotune, watchdog(+interval), and max_temp_c are writable through it (and the REMOTE path refuses to disable watchdog or to unset/out-of-band max_temp_c — a rig's thermal protection can only be removed by a local rigforge.sh apply, #257); every change is validated, the old config is snapshotted to config-backups/, and a change that doesn't come back live is rolled back. Set 'control_upgrade' to \"enabled\" (a SECOND opt-in, only valid when 'control' is also enabled) to let the stack trigger this rig to upgrade its own RigForge to the latest release (#308, ADR 0002) — i.e. fetch and run new root code on a remote trigger. Default off, and never on just because 'control' is: the rig refuses any target that isn't a real release newer than the one running, verifies the release commit is reachable on main (the release branch), throttles repeat runs, and health-gates the swap with rollback. It rides the control path's own Bearer token + api_allow_from pin. Releases are checksummed, not signed — GitHub is the trust root (see SECURITY.md). For co-locating a miner on a busy box (e.g. a Pithead stack host), 'hugepages_reserve_extra_mb' (default 0) adds that many MB of HugePages to RigForge's computed mining reservation so the pool covers stack + miner — RigForge stays the sole writer of the reservation and, when the box's existing reservation already covers both, changes nothing and needs no reboot; 'hugepages_pool_ceiling_mb' (default 0 = no ceiling) is a HARD CAP on the runtime pool RigForge will grow to, in MB, distinct from hugepages_reserve_extra_mb (which adds declared headroom into the computed requirement rather than bounding the write) — set it on a RAM-constrained co-resident box so the grow-only write can never exceed the box's honest capacity no matter what the requirement/availability math computes (rigforge#398; an odd MB value floors to the 2MB page below, e.g. 5121 -> 5120MB effective, never rounds up past the declared ceiling); 'threads' (empty/null = auto) caps the RandomX thread count (a ceiling — min(auto, threads), e.g. nproc-2) so the miner leaves spare cores, and it sizes the reservation to match. A TLS pool can pin the server certificate with 'tls-fingerprint' (its SHA-256 as 64 hex chars; null = no pin) — XMRig does no CA verification for stratum, so the pin is the only server authentication TLS stratum has. Full descriptions: https://github.com/p2pool-starter-stack/rigforge/blob/main/docs/configuration.md#configuration-reference",
 
     "pools": [
-        { "url": "<YOUR_POOL_HOST>:3333", "user": "", "pass": "x", "keepalive": true, "tls": false, "tls-fingerprint": null, "enabled": true }
+        { "url": "<YOUR_POOL_HOST>:3333", "user": "", "pass": "x", "keepalive": true, "tls": false, "tls-fingerprint": null, "socks5": null, "enabled": true }
     ],
 
     "ACCESS_TOKEN": "",
diff --git a/docs/configuration.md b/docs/configuration.md
index 0770f2b..ec7a33f 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -113,6 +113,7 @@ you care about:
 | `keepalive` | `true` |
 | `tls` | `false` — set `true` when you connect on the pool's TLS/SSL port. |
 | `tls-fingerprint` | `null` (no pin) — the pool cert's SHA-256 as 64 hex chars. XMRig does no CA validation on stratum TLS, so the pin is the only server authentication; without it, TLS encrypts but doesn't authenticate. Requires `"tls": true`. See [Pithead Integration › Stratum over TLS](pithead-integration.md#stratum-over-tls-optional). |
+| `socks5` | `null` (direct connection) — dial this pool through a SOCKS5 proxy at `host:port`, e.g. `"127.0.0.1:9050"` for a local Tor client. Same address rules as `url`. XMRig sends the pool's **hostname** to the proxy rather than resolving it first, so a v3 `.onion` stratum works with no extra setting. RigForge points the miner at a proxy; running one is yours to arrange. |
 | `enabled` | `true` |
 
 Two common setups follow; pick the one that matches where you're mining.
diff --git a/rigforge.sh b/rigforge.sh
index b012907..060a3aa 100755
--- a/rigforge.sh
+++ b/rigforge.sh
@@ -383,6 +383,31 @@ ensure_config_exists() {
     fi
 }
 
+# #400: ONE host:port validator, shared by a pool's `url` and its `socks5` proxy. The issue asks for
+# the socks5 value to get "the same rules the pool URL gets" — a second copy of these four checks
+# would satisfy that on the day it was written and drift the first time either side is touched, so
+# the rules live in one place instead. <value> <label> <example-port>: the label leads the operator
+# -facing message, and the example port makes the hint fit its key (a pool is :3333, a SOCKS5 proxy
+# is :9050). Every check and every regex below is verbatim from the pool-url path it replaces.
+_validate_host_port() { # <value> <label> <example-port>
+    local _v="$1" _label="$2" _eg="$3" _h _p
+    if ! [[ "$_v" =~ :[0-9]+$ ]]; then
+        error "$_label '$_v' must include a port, e.g. $_v:$_eg."
+    fi
+    _h="${_v%:*}"
+    _p="${_v##*:}"
+    if [ "$_p" -lt 1 ] || [ "$_p" -gt 65535 ]; then
+        error "$_label port must be between 1 and 65535 (got '$_p' in '$_v')."
+    fi
+    # The host must be a valid hostname / FQDN / IPv4, or a bracketed IPv6 literal. This also
+    # rejects the unfilled template placeholder (<...>), whitespace, and shell/URL metacharacters.
+    # A v3 .onion is an ordinary hostname to this pattern, which is what makes #400 work at all.
+    case "$_h" in
+    \[*\]) [[ "$_h" =~ ^\[[0-9A-Fa-f:]+\]$ ]] || error "$_label '$_v' has an invalid IPv6 literal (use [addr]:port)." ;;
+    *) [[ "$_h" =~ ^[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?$ ]] || error "$_label host '$_h' is not a valid hostname or IP." ;;
+    esac
+}
+
 parse_config() {
     log "Parsing configuration..."
     # A missing config (e.g. `apply`/`tune` before `setup`) is a different, clearer error than bad JSON.
@@ -430,6 +455,14 @@ parse_config() {
     # attribute in-string program lines, and the patch-coverage gate needs every new line hittable.
     POOLS_JSON=$(jq -c --argjson base "$POOLS_JSON" '[$base, [.pools[] | ."tls-fingerprint"]] | transpose | map(.[0] + (if (.[1] // null) != null then {"tls-fingerprint": .[1]} else {} end))' "$CONFIG_JSON") || error "Could not parse 'pools' in $CONFIG_JSON."
 
+    # socks5 (#400): re-attach the per-pool proxy from the raw config, emitted ONLY when set — the map
+    # above rebuilds each pool from a fixed key set, which is what dropped this key. Same shape and
+    # the same reasons as the #115 pass directly above: emitting it unconditionally (null) would
+    # change the generated config's shape for every existing rig on its next apply, and it is a
+    # single-line pass rather than lines inside the map because kcov cannot attribute in-string
+    # program lines and the patch-coverage gate needs every new line hittable.
+    POOLS_JSON=$(jq -c --argjson base "$POOLS_JSON" '[$base, [.pools[] | .socks5]] | transpose | map(.[0] + (if (.[1] // null) != null then {"socks5": .[1]} else {} end))' "$CONFIG_JSON") || error "Could not parse 'pools' in $CONFIG_JSON."
+
     # #265: jq's `//` treats an explicit false like null/missing, so the map above rewrites an
     # operator's "keepalive": false / "enabled": false to the true default. Restore explicit falses
     # from the raw config in another single-line pass (same kcov rationale as #115 above). Only a
@@ -447,20 +480,17 @@ parse_config() {
         _user=$(jq -r '.user' <<<"$_pool")
         _pass=$(jq -r '.pass' <<<"$_pool")
         [ -n "$_u" ] || error "A pool entry has no url — set 'pools[].url' (host:port) in $CONFIG_JSON."
-        if ! [[ "$_u" =~ :[0-9]+$ ]]; then
-            error "Pool url '$_u' must include a port, e.g. $_u:3333."
-        fi
-        _host="${_u%:*}"
-        _port="${_u##*:}"
-        if [ "$_port" -lt 1 ] || [ "$_port" -gt 65535 ]; then
-            error "Pool port must be between 1 and 65535 (got '$_port' in '$_u')."
+        _validate_host_port "$_u" "Pool url" 3333
+        # SOCKS5 proxy (#400), per pool, emitted only when set. XMRig dials the pool through it and
+        # sends the HOSTNAME in the CONNECT request (Client::Socks5::connect uses ATYP 0x03 for
+        # anything that is not an IP literal), so the proxy resolves the name — which is what lets a
+        # v3 .onion stratum work with no `socks5h` variant to ask for. Same host:port rules as the
+        # pool url, via the shared validator, so an onion pool and its proxy cannot be judged by two
+        # different standards.
+        _s5=$(jq -r '.socks5 // empty' <<<"$_pool")
+        if [ -n "$_s5" ]; then
+            _validate_host_port "$_s5" "Pool socks5" 9050
         fi
-        # The host must be a valid hostname / FQDN / IPv4, or a bracketed IPv6 literal. This also
-        # rejects the unfilled template placeholder (<...>), whitespace, and shell/URL metacharacters.
-        case "$_host" in
-        \[*\]) [[ "$_host" =~ ^\[[0-9A-Fa-f:]+\]$ ]] || error "Pool url '$_u' has an invalid IPv6 literal (use [addr]:port)." ;;
-        *) [[ "$_host" =~ ^[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?$ ]] || error "Pool url host '$_host' is not a valid hostname or IP." ;;
-        esac
         if [ -n "$_user" ] && ! [[ "$_user" =~ ^[A-Za-z0-9._:@+-]+$ ]]; then
             error "Pool user '$_user' has invalid characters (allowed: letters, digits, . _ - : @ +)."
         fi
@@ -689,7 +719,7 @@ parse_config() {
 # #1 image seed. Warn NAMES only, never values — a fat-fingered token must not land in a log.
 _warn_unknown_config_keys() {
     local known="pools ACCESS_TOKEN DONATION autotune add_to_path HOME_DIR api api_port api_bind api_allow_from miner_user RIG_NAME watchdog watchdog_interval_min max_temp_c control control_port control_bind control_upgrade hugepages_reserve_extra_mb hugepages_pool_ceiling_mb threads"
-    local known_pool="url user pass keepalive tls enabled tls-fingerprint"
+    local known_pool="url user pass keepalive tls enabled tls-fingerprint socks5"
     local k lk m lm hit hint unknown_seen=0
     while IFS= read -r k; do
         case "$k" in _*) continue ;; esac
diff --git a/tests/run.sh b/tests/run.sh
index 0d34064..17a5a23 100644
--- a/tests/run.sh
+++ b/tests/run.sh
@@ -345,6 +345,40 @@ assert_rc "fingerprint without tls:true rejected (#115)" "$?" "1"
 c="$(mkconf p_fpok "{ \"pools\": [{\"url\":\"h:443\",\"tls\":true,\"tls-fingerprint\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}] }")"
 parse_rc "$c" "$ROOT"
 assert_rc "valid fingerprint + tls accepted (#115)" "$?" "0"
+# #400: socks5 passes through as host:port and the key is absent when unset/null, so a pre-#400
+# config keeps producing byte-identical POOLS_JSON.
+c="$(mkconf p_s5 "{ \"pools\": [{\"url\":\"h:3333\",\"socks5\":\"127.0.0.1:9050\"}] }")"
+assert_eq "socks5 passed through (#400)" "$(PJ "$c" | jq -r '.[0].socks5')" "127.0.0.1:9050"
+c="$(mkconf p_nos5 "{ \"pools\": [{\"url\":\"h:3333\"}] }")"
+assert_eq "no socks5 key when unset (#400)" "$(PJ "$c" | jq -c '.[0] | has("socks5")')" "false"
+c="$(mkconf p_nulls5 "{ \"pools\": [{\"url\":\"h:3333\",\"socks5\":null}] }")"
+assert_eq "null socks5 = absent (#400)" "$(PJ "$c" | jq -c '.[0] | has("socks5")')" "false"
+# The point of the issue: an onion stratum reached through a local Tor SOCKS port.
+c="$(mkconf p_s5onion "{ \"pools\": [{\"url\":\"vww6ybal4bd7szmgncyruucpgfkqahzddi37ktceo3ah7ngmcopnpyyd.onion:3333\",\"socks5\":\"127.0.0.1:9050\"}] }")"
+assert_eq "onion pool + socks5 parses (#400)" "$(PJ "$c" | jq -r '[.[0].url, .[0].socks5] | join(" ")')" "vww6ybal4bd7szmgncyruucpgfkqahzddi37ktceo3ah7ngmcopnpyyd.onion:3333 127.0.0.1:9050"
+# Index alignment: a proxy on the SECOND pool must land on the second pool, not the first.
+c="$(mkconf p_s52 "{ \"pools\": [{\"url\":\"plain:3333\"}, {\"url\":\"onion:3333\",\"socks5\":\"127.0.0.1:9050\"}] }")"
+assert_eq "second-pool socks5 stays on the second pool (#400)" "$(PJ "$c" | jq -c '[(.[0] | has("socks5")), (.[1].socks5 == "127.0.0.1:9050")]')" "[false,true]"
+# A pool may carry BOTH a pin and a proxy — the two re-attach passes must not clobber each other.
+c="$(mkconf p_s5fp "{ \"pools\": [{\"url\":\"h:443\",\"tls\":true,\"tls-fingerprint\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"socks5\":\"127.0.0.1:9050\"}] }")"
+assert_eq "socks5 and tls-fingerprint coexist (#400)" "$(PJ "$c" | jq -c '[(.[0]."tls-fingerprint" != null), (.[0].socks5 == "127.0.0.1:9050")]')" "[true,true]"
+# #400 validation: the socks5 address gets the SAME host:port rules as the pool url. Each of these
+# is rejected for the pool url already; assert the proxy is judged by the same standard.
+c="$(mkconf p_s5noport "{ \"pools\": [{\"url\":\"h:3333\",\"socks5\":\"127.0.0.1\"}] }")"
+parse_rc "$c" "$ROOT"
+assert_rc "socks5 without a port rejected (#400)" "$?" "1"
+c="$(mkconf p_s5badhost "{ \"pools\": [{\"url\":\"h:3333\",\"socks5\":\"evil;rm:9050\"}] }")"
+parse_rc "$c" "$ROOT"
+assert_rc "socks5 with a bad host rejected (#400)" "$?" "1"
+c="$(mkconf p_s5badport "{ \"pools\": [{\"url\":\"h:3333\",\"socks5\":\"127.0.0.1:70000\"}] }")"
+parse_rc "$c" "$ROOT"
+assert_rc "socks5 port above 65535 rejected (#400)" "$?" "1"
+c="$(mkconf p_s5bad6 "{ \"pools\": [{\"url\":\"h:3333\",\"socks5\":\"[not:hex:zz]:9050\"}] }")"
+parse_rc "$c" "$ROOT"
+assert_rc "socks5 with an invalid IPv6 literal rejected (#400)" "$?" "1"
+c="$(mkconf p_s6ok "{ \"pools\": [{\"url\":\"h:3333\",\"socks5\":\"[::1]:9050\"}] }")"
+parse_rc "$c" "$ROOT"
+assert_rc "socks5 as a bracketed IPv6 literal accepted (#400)" "$?" "0"
 c="$(mkconf p_nopools "{ }")"
 parse_rc "$c" "$ROOT"
 assert_rc "no pools rejected" "$?" "1"
@@ -461,6 +495,11 @@ assert_contains "pool-field typo warns with a did-you-mean (#138)" "$out" 'unkno
 c="$(mkconf lint_quiet "{ $POOL, \"_note\": \"comment\", \"RIG_NAME\": \"rig9\", \"api\": \"enabled\" }")"
 out="$(lint_out "$c")"
 assert_absent "underscore keys, RIG_NAME, and known keys stay quiet (#138)" "$out" "unknown key"
+# #400: socks5 is a KNOWN pool field now — the warning that used to tell operators it was ignored
+# was the visible half of the defect, so assert it is gone rather than only that the value survives.
+c="$(mkconf lint_s5 "{ \"pools\": [{\"url\":\"h:3333\",\"socks5\":\"127.0.0.1:9050\"}] }")"
+out="$(lint_out "$c")"
+assert_absent "socks5 no longer warns as an unknown pool field (#400)" "$out" 'unknown pool field "socks5"'
 c="$(mkconf lint_novel "{ $POOL, \"frobnicate\": 1 }")"
 out="$(lint_out "$c")"
 assert_contains "novel key warns without a hint (#138)" "$out" 'unknown key "frobnicate" is ignored.'
@@ -822,6 +861,17 @@ cfg="$d/config.json"
 unset SIM_POOLS STUB_CPU_MODEL STUB_NPROC STUB_HOSTNAME
 assert_eq "tls-fingerprint survives generation (#115)" "$(J "$cfg" '.pools[0]."tls-fingerprint"')" "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
 
+# #400: the proxy has to reach the GENERATED xmrig config, not just POOLS_JSON — that is the file
+# the miner actually reads, and a key that stops at the mapper would mine direct while looking set.
+echo "== config-gen: socks5 passthrough (#400) =="
+export STUB_CPU_MODEL="Intel(R) Xeon" STUB_NPROC=8 STUB_HOSTNAME=rigbox
+SIM_OS=Linux SIM_DON=1 SIM_POOLS='[{"url":"vww6ybal4bd7szmgncyruucpgfkqahzddi37ktceo3ah7ngmcopnpyyd.onion:3333","user":"","pass":"x","keepalive":true,"tls":false,"enabled":true,"socks5":"127.0.0.1:9050"}]'
+d="$(gen_config)"
+cfg="$d/config.json"
+unset SIM_POOLS STUB_CPU_MODEL STUB_NPROC STUB_HOSTNAME
+assert_eq "socks5 survives generation (#400)" "$(J "$cfg" '.pools[0].socks5')" "127.0.0.1:9050"
+assert_eq "the onion pool url survives generation (#400)" "$(J "$cfg" '.pools[0].url')" "vww6ybal4bd7szmgncyruucpgfkqahzddi37ktceo3ah7ngmcopnpyyd.onion:3333"
+
 echo "== config-gen: miner_user disables in-process MSR writes (#140) =="
 export STUB_CPU_MODEL="AMD Ryzen 9 7950X" STUB_NPROC=8 STUB_HOSTNAME=rigbox
 d="$(SIM_OS=Linux SIM_DON=1 SIM_MINER_USER=xmrig gen_config)"