fix(relay): the operator's onion-relay opt-in leaks through a shared rate-limit bucket

[MichaelTaylor3d]

Task

A stranger can determine whether this operator enabled onion relaying, by draining a rate-limit
bucket and watching a different RPC method change shape. Close the side channel, or decide
deliberately that the opt-in is not a secret and record that.

Why the equal-frames guard does not cover this

relay_capsule's five refusal sites all return one payload-free RelayStatus::Refused, and
dig-node#356's new guard pins the refusal FRAME equal to a plain miss. That closes the frame
channel. It does not close this one, because the leak is not in the frame — it is in a state
change the refusal leaves behind.

The mechanism

1. relay_capsule gate 3 (module_relay.rs:124) calls allow_proxy_fetch(requestor).
2. allow_proxy_fetch (download.rs:1643) CONSUMES a token, not merely inspects one.
3. That bucket is shared with miss_outcome's second leg (download.rs:2721), where exhaustion
   degrades a later read from fetch-through to redirect.

So the probe is:

• Spam dig.getModuleInfo with proxy: true to drain the bucket. Burst is 4.0
  (rate_limit.rs:179).
• Then issue dig.getContent and watch which shape comes back.
• Bytes means relaying is OFF — gate 2 refused before gate 3, so nothing was ever consumed.
• Redirect means relaying is ON — gate 3 was reached and the tokens were spent.

The operator's opt-in is inferable from ~5 cheap requests, and nothing in the relay path looks
anomalous while it happens.

Why gate ORDER is the root cause

Gate 2 (operator opt-in, :120) returns BEFORE gate 3 (:124) ever runs. That ordering is what makes
token consumption a proxy for the opt-in: the presence or absence of a side effect answers a question
the frames were carefully built not to answer.

A related, smaller ordering defect sits beside it: :124 also runs before the capsule-warmer check at
:127, so on a build with no warmer a requestor's allowance is spent on a relay that could never have
happened. Same class, lower severity.

The fork, so whoever takes this does not have to invent it

• (a) Do not consume on a path that cannot relay. Check-then-consume, or refund when a later gate
  refuses. Removes the signal; costs a small amount of limiter accuracy under abuse.
• (b) Separate the buckets so the proxy-class allowance is not observable through miss_outcome.
  Removes the cross-method coupling that makes the probe cheap; more moving parts.
• (c) Decide the opt-in is not a secret and say so in module_relay.rs's module doc — deleting
  the confidentiality claim rather than leaving a claim the code does not honour. Legitimate, and
  strictly better than the current state, where the doc implies a property the system does not have.

(a) is the recommendation. It is the smallest change and it addresses the root — a refusal should
not leave evidence of how far it got.

Evidence bar

A guard here must distinguish "the bucket was charged" from "the bucket was not", so it needs two
runs that differ ONLY in the operator opt-in, with the post-state asserted unequal. Asserting the
refusal frames are equal is already done by #356's guard and is not sufficient — that is the
whole point of this ticket.

Provenance

Found by the pre-merge security audit on PR #504 (the dig-node#356 NC-12 doc-claim audit), which
was asked whether the equal-frames guard actually closed the oracle and demonstrated that it does
not. Not fixed there: #504 is a measurement PR, and a security change grown inside it would make it
ungateable.

The correctness of #504's guard is unaffected — it closes the frame channel it claims to close,
and its doc now names this channel explicitly rather than implying the oracle is shut.

Audit: #356
Parent: https://github.com/DIG-Network/dig_ecosystem/issues/3128

[MichaelTaylor3d]

Diagnosis — this is the OBSERVABLE kind, not the stale kind

An opt-in can leak three ways and they need different fixes. Measured on origin/main @ 04079d57:

It is (1) — the flag is observable to a peer who should not see it, through a side effect rather than the frame. Explicitly not the other two:

• Not (3), staleness. ONION_RELAY_ENV being read once at construction (download.rs:194, field doc :885) is deliberate and correct — it fixes the node's amplification posture for its lifetime, which is a property worth having. set_onion_relay (download.rs:1630) is #[cfg(test)] only, so there is no runtime path that changes the answer after construction and therefore no later change that could fail to take effect.
• Not (2), honoured on an unchecked path. Gate 2 is checked on the only path that relays.

The mechanism, confirmed line by line

• module_relay.rs:124 — gate 3 calls content.allow_proxy_fetch(requestor).
• download.rs:1643 — that is requestor.is_local() || self.proxy_rate_limiter.check(requestor).
• rate_limit.rs:289 -> TokenBucket::try_acquire (rate_limit.rs:120) decrements on admit. A refused acquire decrements nothing.
• download.rs:2721 — miss_outcome leg 2 checks the same proxy_rate_limiter instance, reached through the same p2p_content() handle.

So token consumed <=> gate 3 was reached <=> (requestor asked AND engine present AND operator opted in). The attacker supplies the first and the second is stable, which leaves the operator's opt-in as the only free variable. The ticket's probe is correct as written.

Shape locked: option (a), realised as a pure REORDER

Making the proxy-allowance check the last gate — after the capsule-warmer check, immediately before the spawn — gives check-then-consume with no refund path, no second bucket and no new state.

The resulting invariant is exact and total: every path returning RelayStatus::Refused consumes nothing. Consumption then implies gates 1/2/warmer passed and gate 3 admitted, which implies the call returns Landed or Pending — a frame that already tells the requestor relaying is on. The channel therefore reveals nothing the frame did not. Gate 3 refusing consumes nothing either, so the exhausted-allowance case also refuses without trace.

It fixes the smaller ordering defect in the same change (allowance spent on a build with no warmer), and it is not a DoS regression: the checks that move earlier are an atomic load and an Option clone, both cheaper than the limiter's mutex + hashmap.

Timing is a declared non-goal. The arms still return at different depths in wall-clock terms; equalising that is not attempted and is not what this ticket asks for.

Guard

attach_p2p (lib.rs:14792) wires no capsule warmer, so with relay ON the current code refuses at the warmer gate after charging — the red condition is reachable from the existing fixture pattern at lib.rs:~15636. Two arms differing only in set_onion_relay(false|true), both asserted to return RESOURCE_UNAVAILABLE, then the shared bucket probed through the other method and the two observations asserted equal. Equal refusal frames are #504's guard and are not sufficient — that is the point of this ticket.

SPEC.md does not describe this leg (checked); the normative home is the module_relay.rs module doc, which currently states the old gate order. lib.rs:~8126 — the #504 comment that names this channel as open — is updated in the same change.

[MichaelTaylor3d]

Lane complete — draft PR #517, head 834139bf, branch loop/512-relay-optin-oracle, version 0.257.0.

Fixed as ticket option (a), check-then-consume, realised as a pure reorder: the capsule-warmer gate moves above allow_proxy_fetch, making the proxy allowance the LAST gate in relay_capsule. No refund path, no second bucket, no new state. Post-fix invariant: every path returning RelayStatus::Refused consumes nothing, so a spend implies Landed/Pending — a frame that already tells the requestor relaying is on.

Red evidence (test written and run against unmodified origin/main; the fix commit follows the test commit):

assertion `left == right` failed: the operator's onion-relay opt-in is observable through the proxy
allowance ... relay ON saw {"error_code":-32008,"served":false}, relay OFF saw {"error_code":null,"served":true}
test result: FAILED. 0 passed; 1 failed; 1101 filtered out

-32008 is CONTENT_REDIRECT — the relay-ON arm's stolen token degraded a later dig.fetchRange, exactly the predicted mechanism.

Green: test result: ok. 1102 passed; 0 failed; 0 filtered out (cargo test -p dig-node-core --lib).

Guard: a_refused_relay_leaves_no_trace_in_the_proxy_allowance — two arms varying ONLY set_onion_relay(false|true), both asserted to answer RESOURCE_UNAVAILABLE, then the shared bucket read through the OTHER method. Equal refusal frames (#356/#504) pass under the defect and are deliberately not the assertion.

Docs updated: the module doc's gate list (three → four, with the ordering rationale), the RelayStatus::Refused variant doc, and the #504 comment at lib.rs that named this channel as open. SPEC.md checked — it does not describe this leg's gates; no change needed.

Timing equalisation is an explicit non-goal, stated in the module doc.

Not merged, not undrafted — gates run next.