port(upstream#1974): per-IP limits and deny list on the /ws upgrade

[adminopenclaw8-sketch]

Split out of #25 (commit c489d70b there). This branch holds exactly one upstream change so it can be reviewed, tested and reverted on its own.

Upstream

• PR: Kpa-clawbot/CoreScope#1974 by @efiten, merged 2026-09-06
• Upstream commit: 1ffaad8eb1d98d8ac2bff48ff3f7f74a93abb175
• Applied with git cherry-pick -x onto master fda24ca5; upstream authorship kept, and the commit message carries the (cherry picked from commit …) line.
• Patch-id identical to the port(upstream): 26 clean upstream fixes — prune batching, /ws limits, observer liveness, watchdog race #25 commit and to the upstream commit.
• Scope: cmd/server/{config,main,routes,types,websocket}.go, new ws_limits.go + test, config.example.json.

Problem

The /ws upgrade had only the browser-facing CheckOrigin allowlist. Non-browser clients can omit or forge Origin, connect in a loop and sit in the hub.

Change

New webSocket config block evaluated before the handshake:

• deny: addresses/CIDRs → 403
• maxConnsPerIP: concurrent cap, default 0 (off)
• upgradesPerMinPerIP: rolling-minute upgrade rate → 429, default 30 (on)
• trustedProxies: only from these peers is X-Forwarded-For believed

Rejections are counted in /api/stats under websocket.

Adaptation to this fork

None. The cherry-pick applied without conflicts and the changed lines are identical to upstream.

Notes for review

Safe with our Docker image as-is: the bundled Caddy proxies to localhost:3000, so the Go server's peer is loopback. With trustedProxies empty, clientIP() marks loopback/private peers as indistinguishable, the per-IP limits are skipped and one warning is logged; only deny still applies. To actually enforce the limits, set trustedProxies to the proxy address(es). Only do that if the proxy's X-Forwarded-For really carries the visitor IP; behind a CDN in front of Caddy, visitors could otherwise share an edge IP and be throttled together.

One local test failure, classified as a pre-existing flake: the first local -race run of the server suite on this branch failed TestIssue1008_HandlerReturns503WhileSubpathIndexLoading (status = 200, want 503), while master's run passed. This PR does not touch that handler, the index build or the test file; its routes.go hunk is confined to handleHealth. Reproduction under identical conditions, see the verification table for the counts:

• a full -race rerun passes on both master and this branch;
• 50 focused iterations pass on both;
• 200 iterations with -race -cpu=1 fail on master 2/200 and on this branch 1/200, with the same assertion.

It is therefore a timing race in the test itself, not a regression.

Dependencies and merge order

• Independent. Branched directly from master fda24ca5 and needs no other PR from this split.
• A merge simulation of all 24 split PRs gives the same tree in upstream order and in reverse order.
• The same simulation also merges cleanly with each of the open API: expose on-wire channelHashHex on channel messages #11, feat(map): support CARTO basemap API keys #13 and chore(deps): bump to golang:1.27.1-alpine3.24 and alpine:3.24 #22, and with test(ingestor): make neighbor metrics pruning deterministic #33 (opened during this split; it makes TestPruneOldNeighborMetrics deterministic). If test(ingestor): make neighbor metrics pruning deterministic #33 lands first, the expected CI failure named below disappears; nothing in this PR depends on it.
• Recommended position: 21 of 24, following upstream's merge order (the order port(upstream): 26 clean upstream fixes — prune batching, /ws limits, observer liveness, watchdog race #25 was assembled in).

Verification

Local run of the same commands as CI's “Go Build & Test” job (server tests with -race), on this branch and on master fda24ca5 under the same conditions (same machine, run one after another):

Check	master fda24ca5	this branch	verdict
go-server-build-vet	PASS	PASS
go-server-test-race	PASS	FAIL TestIssue1008_HandlerReturns503WhileSubpathIndexLoading	intermittent, reproduced on unmodified master: TestIssue1008_HandlerReturns503WhileSubpathIndexLoading is a timing race in the test itself (it asserts the not-ready window without waiting for the background index build). 200 iterations each with -race -cpu=1: master fda24ca5 failed 2/200, this branch 1/200, same assertion status = 200, want 503. With -cpu=2: 0/200 on both. A full -race rerun of the server suite passes on both
channel-lib-test	PASS	PASS
decrypt-cli-build-test	PASS	PASS
dockerfile-copy-invariants	FAIL	FAIL	not runnable locally: script needs bash ≥4 (declare -A), macOS has 3.2; identical on master
staging-disk-monitor	PASS	PASS
css-vars-lint	PASS	PASS

Baseline failures (fail identically on master; not introduced or changed here): see rows marked baseline failure, unchanged.

Browser validation (local, fixture DB, no staging/production): Not applicable (no frontend change).

Not run:

• Playwright E2E suites (no local Playwright install); CI's E2E job will also be skipped, see below.
• eslint (not installed locally; CI installs it on the fly).
• Frontend JS suites (no frontend change).
• Browser tests against staging/production (deliberately none).

Expected GitHub CI: “Go Build & Test” is expected to fail on TestPruneOldNeighborMetrics, which already fails on master (see #25's run). Downstream jobs (Playwright, image build) are therefore skipped. “Deploy Staging” and all GHCR publish steps only run on push to master and cannot run for this PR.
Two further ingestor tests have failed intermittently in this split's CI on branches whose cmd/ingestor tree is byte-identical to master (#27, #28), so they can also appear here without being caused by this change:

• TestBackfillTxLastSeen_ResolvesFromMaxObservationTimestamp: also reproduced locally on unmodified master.
• TestMQTTStallWatchdog_DisconnectedEscalationThrottled_1749: the suite flake that upstream test(ingestor): join the watchdog loop goroutine instead of only asking it to stop Kpa-clawbot/CoreScope#2003 (also split out of port(upstream): 26 clean upstream fixes — prune batching, /ws limits, observer liveness, watchdog race #25) addresses.

GitHub CI result: run 34752482084 on 93f37b91. Go Build & Test: failure; all downstream jobs incl. Deploy Staging skipped. Failed tests:

• TestPruneOldNeighborMetrics: fails on master, documented baseline

🤖 Generated with Claude Code

[dborup]

Verificeret lokalt — de tre sikkerhedsgarantier er ægte dækket

Branchen er synkroniseret med master 96319acc (almindelig merge-commit 3e50c403, ingen rebase/squold/force-push). go build, go vet og hele cmd/server-suiten er grønne. Filomfanget er uændret: ingen Caddy-konfiguration, intet deployment, ingen produktionsberøring.

Mutationstest af det, der kan forårsage et selvforskyldt udfald

PR'ens egen kommentar siger det selv: et per-IP-loft bag en ukonfigureret reverse proxy tæller hele internettet som én klient og giver den sjette legitime browserfane 403. Det er den farligste egenskab i ændringen, så jeg testede, om den faktisk er pinned — ved at genindsætte mutationen og se, at en navngiven test fejler på en rigtig assertion, ikke en compilefejl:

mutation	resultat	fanget af
fjern !distinct-springet, så grænserne håndhæves bag ukonfigureret proxy	dræbt	TestWSLimits_SkippedWhenClientsCannotBeToldApart, TestWSLimits_PrivatePeerAlsoCountsAsIndistinct
lad deny-listen springe over, når klienter ikke kan skelnes	dræbt	TestWSDeny_AppliesEvenWhenIndistinct
lad en nil-limiter afvise i stedet for at tillade	dræbt	TestWSLimits_NilLimiterAllowsEverything

Den første er den vigtigste: den beviser, at udelukkelsesbeskyttelsen ikke bare er en kommentar, men en testet invariant. Den anden beviser den bevidste asymmetri — deny-listen er operatørens egen udtrykkelige instruks og gælder derfor stadig, mens de udledte per-IP-grænser slås fra.

De 19 tests i ws_limits_test.go dækker desuden det, opgaven navngiver: trusted-proxy-kontrakten (TrustedProxyUsesForwardedFor, UntrustedPeerIgnoresForwardedFor, TrustedProxyWithoutForwardedForUsesPeer), forfalskede headers, bar adresse som single-host-CIDR, uparsbar entry der springes over frem for at vælte opstart, rate-vinduet der glider, at en afvist upgrade ikke bruger budget, og at idle per-IP-state samles.

Hvad der ikke kan afgøres her

• IPv6 i praksis. Koden håndterer det (bits = 128 for ikke-IPv4), men det er ikke afprøvet mod en rigtig dual-stack-klient.
• Kontrolleret load-test mod grænserne — opgaven kræver den eksplicit, og den kræver en rigtig server med rigtige WebSocket-klienter.
• At eksisterende staging-trafik ikke låses ude. Det er hele pointen med at teste det på staging frem for i en unit-test.

Hvorfor PARKERET

Opgavens regler kræver staging før merge for WebSocket-/netværksgrænser, med rollback og kontrolleret load-test — og med den udtrykkelige betingelse, at Caddy og produktion ikke røres. Staging kan ikke nås fra den maskine, arbejdet kører på: docker-dæmonen kører ikke, ~/meshcore-staging-data findes ikke, ingen ~/.ssh/config, ingen remote docker-context, og deploy-jobbet kører på den self-hostede runner [self-hosted, meshcore-runner-2], som er fork-guarded fra her. Docker blev bevidst ikke startet: containerne har restart: unless-stopped, så en dæmonstart kunne rejse en ingestor mod en live broker.

Konkret testplan ligger i STAGING-TESTPLAN.md under "#47". Vigtigste punkt: kør først uden trustedProxies konfigureret og bekræft, at mindst 6 samtidige faner alle kommer igennem, og at advarslen logges præcis én gang. Rollback-trigger: en eneste legitim klient der får 403.

🤖 Generated with Claude Code