relay: per-IP rate limit on /v1/server + /v1/client WS upgrades

[ilmoniemi]

Why

docs/threat-model.md § DoS resistance flags connection floods + fork-bomb retry as in-scope concerns. Today both /v1/server and /v1/client accept unbounded WS upgrade attempts from any single IP. A misbehaving phone (or an attacker) can pin per-connection memory + goroutines without amortised cost.

What

A per-IP token bucket on the WS upgrade attempts (NOT on individual frames — frame-level cost is bounded by SetReadLimit #29 + max-phones #30). Reject excess attempts before websocket.Accept with a 429 (HTTP — pre-upgrade) so the cost of rejection is the cheapest possible.

Suggested starting policy (architect to refine from threat model):

• 10 upgrade attempts / IP / minute, burst 20
• Bucket store: in-memory map keyed by client IP, with periodic eviction of stale buckets

Implementation notes

• Lives as middleware around both upgrade handlers in cmd/pyrycode-relay/main.go
• Pure function for bucket-decision (testable in isolation; same shape as Registry's race-tested patterns)
• Behind a reverse proxy (nginx, Cloudflare, fly-proxy), X-Forwarded-For is the source of truth — handle deployment-context awareness via a config flag (--trust-x-forwarded-for) so a misconfigured deploy doesn't trust spoofable headers
• Rate-limit decisions get a slog line (without IP if log hygiene rules forbid; check threat model)

Out of scope

• Rate limiting per server-id or per device token (different threat surface; consider separately if it surfaces)
• Distributed rate limiting (single-instance only — multi-instance would need shared state / Redis)

[ilmoniemi]

Split into two sub-issues:

• relay: per-IP token-bucket rate-limit primitive with eviction #46 — relay: per-IP token-bucket rate-limit primitive with eviction (the type + IP-extraction helper + tests, no wiring)
• relay: wire per-IP rate-limit middleware on /v1/server + /v1/client #47 — relay: wire per-IP rate-limit middleware on /v1/server + /v1/client (middleware composition + --trust-x-forwarded-for flag), blocked by relay: per-IP token-bucket rate-limit primitive with eviction #46

Rationale: matches the always-split pattern in the PO playbook (new public type AND a constructor that uses it from main.go). Slicing keeps each child under the S ceiling, lets the primitive land + be reviewed in isolation, and avoids the architect/dev max_turns failure mode observed on prior oversized tickets. Threat-model framing, suggested defaults, and the XFF-spoof warning are preserved in #47; the bucket-algorithm + race-test requirements are in #46.

[ilmoniemi]

🤖 Product Owner — creates structured issues

po agent has completed work on this ticket.

Agent output (click to expand)

Split #34 into two children and closed the parent.

- **#46** — `relay: per-IP token-bucket rate-limit primitive with eviction` (S, security-sensitive). The type + IP-extraction helper with XFF awareness + race-tested tests. No `main.go` changes.
- **#47** — `relay: wire per-IP rate-limit middleware on /v1/server + /v1/client` (S, security-sensitive). Middleware composition, `--trust-x-forwarded-for` flag, 429 response, slog hygiene. Marked `addBlockedBy(#47, #46)` so the dispatcher serialises them.

Both positioned at top of Backlog on the **Pyrycode-Relay** project (project #3) in dependency order; sub-issue linked under #34; #34 closed and moved to Done with a split-rationale comment.

Mid-task discovery: the system-prompt playbook says `gh project item-add 1` but this repo's board is project #3 — items got created on the wrong project, then cleaned up via `deleteProjectV2Item`. Saved a memory entry so the next refinement doesn't repeat it.

Ready for human review. Move to the next column when approved.