Skip to content

fix(relay): bound pairing-code guessing on join - #26

Draft
Jeon1691 wants to merge 1 commit into
masterfrom
Jeon1691/sec-relay-join-rate-limit
Draft

Jeon1691 wants to merge 1 commit into
masterfrom
Jeon1691/sec-relay-join-rate-limit

Conversation

@Jeon1691

Copy link
Copy Markdown
Owner

Problem

POST /v1/pairing/join never counted a failed join. Unknown codes returned 404 without being recorded. RelayState::record_ip_fail existed but nothing called it, so the per-IP limit in check_ip could never trigger. The per-session attempts counter only increments after a code has already matched, so it does not limit guessing.

Attack scenario

One client can submit wrong 6-digit codes as fast as the relay answers and never be throttled. At loopback speed that covers a large share of the 10^6 code space within one 120 s pairing TTL. The code is also the SPAKE2 password, so an attacker who hits it can complete pairing and join the victim's room. Before this change, a sweep of 20,000 wrong codes from one address got only 404s and no 429s, and the correct code still joined afterwards.

Resulting behavior

  • All failures count. Unknown, expired, busy, over-attempted and otherwise rejected joins are charged to the client and to a relay-wide budget. The charge is reserved before the code lookup, so concurrent guesses cannot overshoot, and it is refunded only when the join succeeds.
  • Per-client budget: 10 failed joins per 15 minutes. IPv4 addresses are counted individually, IPv6 by /64, and IPv4-mapped IPv6 as IPv4.
  • Relay-wide budget: 20 failed joins per pairing TTL (120 s).
    • A code's lifetime overlaps at most two of those fixed windows. So at most 40 of the 10^6 codes can be tested while a session is open, however many addresses the attacker uses. That puts the chance of guessing one session at or below 4e-5, under the 1e-4 implied by NIST SP 800-63B's 100-attempt ceiling.
    • A const assertion fails the build if the constants stop satisfying this bound.
  • No existence oracle. Once either budget is spent, every join gets the same 429 too_many_attempts body, including one with the correct code. Refused attempts are not counted and allocate no state.
  • Trusted proxies (opt-in). New CLIPSYNC_RELAY_TRUSTED_PROXIES / --trusted-proxies takes a comma-separated list of addresses and CIDRs. X-Forwarded-For is read only when the TCP peer is in that list, and the relay uses the rightmost hop that is not itself trusted. A malformed hop falls back to the nearest trusted proxy. Default: the TCP peer address only, unchanged from before.
  • Bounded memory. gc() removes ip_fails entries whose window has ended.
  • Client message. On a 429 the CLI/core now says the relay is limiting pairing attempts and to retry later with a new code, instead of echoing the raw body.

Compatibility

There are no protocol, wire or persisted-format changes. The 429 too_many_attempts code and body already existed. Code length and format are unchanged. router(config) and RelayState::new(config) keep their signatures and behavior; router_with_trusted_proxies / RelayState::with_trusted_proxies are additive. record_ip_fail is now test-only because nothing in production called it.

Verification

  • Regression tests were written first and failed on unchanged master:
    • The 20,000-wrong-code sweep followed by the correct code failed with "wrong-code sweep was never throttled".
    • The GC test failed because the stale entry was never removed.
  • New tests cover:
    • Per-client exhaustion refusing the correct code.
    • Relay-wide exhaustion across many addresses, with identical bodies for unknown and correct codes.
    • Refund on success.
    • IPv6 /64 grouping.
    • X-Forwarded-For honored only from configured proxies, with forged leftmost entries ignored. This test was checked by mutation: honoring the header from any peer makes it fail.
    • Trusted-proxy parsing.
    • GC.
    • The core 429 mapping.
  • cargo +1.100.0 fmt --all -- --check: pass
  • cargo +1.100.0 clippy --workspace --all-targets --locked -- -D warnings: pass
  • cargo +1.100.0 test -p clipsync-relay --locked: 86 passed, 0 failed
  • cargo +1.100.0 test -p clipsync-core --locked: 58 passed, 0 failed
  • cargo +1.100.0 test --workspace --locked --no-fail-fast: 338 passed, 0 failed (46 test binaries)
    • In one earlier workspace run, secure_listener::tls12_and_tls13_verify_issuer_hostname_and_reject_plaintext hit a TLS-handshake ConnectionReset under parallel load. It passed in 5 of 5 isolated reruns and in the full rerun, and that test does not depend on the join limits.
  • cargo +1.95.0 check --workspace --all-targets --locked: pass

Remaining limitations

  • Denial of pairing. Anyone who can spend the relay-wide budget, which takes about two exhausted client budgets per window, can keep refusing new pairings, including correct codes. This is the deliberate trade-off: guessing becomes a denial of service instead of a room compromise. Rate limiting the relay at the network edge remains the deployment's job.
  • Shared addresses. Users behind a NAT or untrusted proxy share one client budget. A legitimate user who shares an address with a guesser is refused until the window ends. Successful joins do not clear earlier failures.
  • Fixed constants. The limits are not configurable. A large multi-tenant relay may want different budgets.
  • Proxy trust. Any process that can connect from a trusted-proxy address can claim any client address. docs/self-hosting.md documents this.
  • Regression ledger. This defect is not yet registered in docs/regressions.json / docs/regression-audit.md.

Every failed POST /v1/pairing/join now counts against the client and a
relay-wide budget. The attempt is reserved before the code lookup and
refunded only if the join succeeds. Once either budget is spent, every join
is refused with 429 too_many_attempts, including one with the correct code,
so the response never reveals whether a code exists.

- Per client: 10 failures per 15 minutes, IPv6 grouped by /64.
- Relay-wide: 20 failures per pairing TTL (120 s). A code's lifetime overlaps
  at most two windows, so at most 40 of the 10^6 codes can be tested while a
  session is open (<= 4e-5). Compile-time assertions keep this bound in sync
  with the constants.
- Opt-in CLIPSYNC_RELAY_TRUSTED_PROXIES / --trusted-proxies: X-Forwarded-For
  is read only from these peers, using the rightmost untrusted hop. Unset
  means the TCP peer address only, as before.
- gc() expires ip_fails entries. Refused attempts allocate no entries.
- The client maps 429 to an actionable message.
@coderabbitai

coderabbitai Bot commented Nov 16, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

));
}
assert!(matches!(
state.join_pairing(join(&wrong_code(&offer, 0), DeviceId::new()), attacker),
let fresh: IpAddr = "192.0.2.200".parse().unwrap();
// Unknown and correct codes are refused identically once the budget is spent.
assert!(matches!(
state.join_pairing(join(&wrong_code(&offer, 0), DeviceId::new()), fresh),
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants