PR #77527: fix(gateway): rate-limit pre-auth bootstrap-token verify to prevent mutex DoS

• Repository: openclaw/openclaw
• Author: fede-kamel
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/77527

Description (problem / solution / changelog)

Closes #77978

Summary

• verifyDeviceBootstrapToken is withLock-serialized in src/infra/device-bootstrap.ts:39 and runs a JSON state read + write per attempt. The verify call site at src/gateway/server/ws-connection/auth-context.ts:160-179 had no rate limit gate — only the sibling device-token path (line 187) was throttled. An attacker with a self-generated Ed25519 keypair can produce a valid device signature for any connect payload, then send auth.bootstrapToken: "anything" to keep the bootstrap mutex saturated. The mutex is shared with all bootstrap-pairing operations (requestDevicePairing, approveBootstrapDevicePairing, etc.), so the attack starves legitimate node onboarding rather than just CPU.
• Adds AUTH_RATE_LIMIT_SCOPE_BOOTSTRAP_TOKEN and gates verifyBootstrapToken with the same optimistic-check pattern device-token already uses: pre-check for lockout, run verify, recordFailure on mismatch, reset on success. The gate fires for browser-origin clients via the always-on browserRateLimiter (exemptLoopback: false) and for non-browser remote clients when gateway.auth.rateLimit is configured — same reachability envelope as the existing device-token bucket.
• Reaching verifyBootstrapToken only requires a valid Ed25519 signature on the connect payload (trivially producible with the attacker's own keypair) plus auth.bootstrapToken. There is no "must be paired" gate before the verify path.

Reproduction

The integration test (src/gateway/server.preauth-bootstrap-token-rate-limit.test.ts) configures withGatewayServer with rateLimit.maxAttempts: 3, exemptLoopback: false, opens a fresh WS handshake per attempt, and submits connectReq(ws, { skipDefaultAuth: true, bootstrapToken: "forged-bootstrap-token", deviceIdentityPath }). connectReq auto-builds a valid Ed25519 device block — same shape as a real attacker would produce.

The test asserts:

1. The first maxAttempts attempts fail with details.authReason === "bootstrap_token_invalid" (the verify ran).
2. The (N+1)th attempt fails with details.authReason === "rate_limited" — the gate short-circuited before the mutex was entered.

Reverting the recordFailure line in the gate makes the second test fail with expected 'bootstrap_token_invalid' to be 'rate_limited'.

Test plan

• src/gateway/server/ws-connection/auth-context.test.ts — added 3 unit tests: gate fires when bucket exceeded (verify never invoked), recordFailure consumed on mismatch, reset called on success. Existing 9 tests remain green (12/12 pass).
• src/gateway/server.preauth-bootstrap-token-rate-limit.test.ts — new in-process WS integration test (2 cases) using withGatewayServer. Both fail when the gate is removed.
• No regressions: pnpm test src/gateway/server.preauth-bootstrap-token-rate-limit.test.ts src/gateway/server/ws-connection/auth-context.test.ts src/gateway/server.auth.control-ui.test.ts src/gateway/server.auth.browser-hardening.test.ts src/gateway/server.auth.modes.test.ts → 60/60 pass.

Verification

• Targeted lint with TS-aware shard config: OPENCLAW_OXLINT_SKIP_PREPARE=1 node scripts/run-oxlint.mjs --tsconfig config/tsconfig/oxlint.core.json <touched files> → 0 warnings, 0 errors.
• pnpm check:changed: only failure is the pre-existing web-tree-sitter typecheck error in src/infra/command-explainer/* that I did not touch — same error reproduces on origin/main without these changes.

Reachability envelope

• Browser-origin clients: gated unconditionally via browserRateLimiter (always constructed, exemptLoopback: false).
• Non-browser remote clients: gated when operator has configured gateway.auth.rateLimit. When unconfigured, neither this gate nor the existing device-token gate applies — that is a configuration concern that affects the whole pre-auth surface, not specific to bootstrap-token.
• Loopback-exempt connections (default exemptLoopback: true) are unaffected, matching how legitimate local CLI sessions are exempted from all other gateway buckets.

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/gateway/auth-rate-limit.ts (modified, +7/-0)
• src/gateway/server.preauth-bootstrap-token-rate-limit.test.ts (added, +115/-0)
• src/gateway/server/ws-connection/auth-context.test.ts (modified, +104/-0)
• src/gateway/server/ws-connection/auth-context.ts (modified, +46/-17)