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

fede-kamel · fede-kamel · commit 69637a53b7b8 · 2026-05-31T08:16:15.000-04:00
verifyDeviceBootstrapToken is withLock-serialized in src/infra/device-bootstrap.ts
and runs an fs read + fs write per attempt. Reaching it in resolveConnectAuthDecision
required only a connect frame with a valid Ed25519 device signature (trivially
producible by an attacker with their own keypair) plus auth.bootstrapToken — the
device-token sibling path was rate-limited but bootstrap-token was not, so an
unauthenticated attacker could keep the bootstrap mutex saturated and starve
legitimate node onboarding during the attack.

Adds AUTH_RATE_LIMIT_SCOPE_BOOTSTRAP_TOKEN with the same optimistic-check pattern
as device-token: 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.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2338,6 +2338,7 @@ Docs: https://docs.openclaw.ai
 - Codex harness: honor `models.providers.openai-codex.models[].contextTokens` for native `openai/*` Codex runtime runs and `/status` context reporting, so subscription-backed Codex agents use the configured OAuth context cap without inflating past the runtime model window. Fixes #77858. Thanks @lilesjtu.
 - Sessions cleanup: add `openclaw sessions cleanup --fix-dm-scope` so operators who return `session.dmScope` to `main` can dry-run and retire stale direct-DM session rows while preserving transcripts as deleted archives. Fixes #47561 and #45554. Thanks @BunsDev.
 - Doctor/Codex: repair legacy `openai-codex/*` routes and cron payload model refs to canonical `openai/*`, keep OpenAI agent turns on Codex by default, ignore stale whole-agent/session runtime pins, preserve explicit provider/model runtime policy, and migrate legacy runtime model refs to model-scoped runtime entries. Thanks @vincentkoc.
+- Gateway/security: rate-limit the pre-auth bootstrap-token verify per IP so a remote attacker producing a valid device signature cannot flood the mutex-serialized pairing-state read/write loop and stall legitimate node onboarding.
 - Video generation: wait up to 20 minutes for slow fal/MiniMax queue-backed jobs, stop forwarding unsupported Google Veo generated-audio options, and normalize MiniMax `720P` requests to its supported `768P` resolution with the usual override warning/details instead of failing fallback.
 - Channels/durable delivery: preserve channel-specific final reply semantics when using durable sends, including Telegram selected quotes and silent error replies plus WhatsApp message-sending cancellations.
 - Channels/message lifecycle: build legacy channel delivery results from message receipts and add receipts to BlueBubbles, Feishu, Google Chat, iMessage, IRC, LINE, Nextcloud Talk, QQ Bot, Signal, Synology Chat, Tlon, Twitch, WhatsApp, Zalo, and Zalo Personal send results and owner-path reply delivery plus Discord, Matrix, Mattermost, Slack, and Teams send results while preserving existing message id compatibility.
diff --git a/src/gateway/auth-rate-limit.ts b/src/gateway/auth-rate-limit.ts
@@ -38,6 +38,13 @@ export interface RateLimitConfig {
 export const AUTH_RATE_LIMIT_SCOPE_DEFAULT = "default";
 export const AUTH_RATE_LIMIT_SCOPE_SHARED_SECRET = "shared-secret";
 export const AUTH_RATE_LIMIT_SCOPE_DEVICE_TOKEN = "device-token";
+// Per-IP gate for the pre-auth bootstrap-token verify path.
+// `verifyDeviceBootstrapToken` is `withLock`-serialized in
+// `device-bootstrap.ts` and runs fs read + fs write on every attempt;
+// without a scope-specific limiter, attackers presenting a valid
+// device signature can queue the bootstrap-pairing flow behind their
+// requests, blocking legitimate node onboarding during the attack.
+export const AUTH_RATE_LIMIT_SCOPE_BOOTSTRAP_TOKEN = "bootstrap-token";
 export const AUTH_RATE_LIMIT_SCOPE_HOOK_AUTH = "hook-auth";
 const BROWSER_ORIGIN_RATE_LIMIT_KEY_PREFIX = "browser-origin:";
 
diff --git a/src/gateway/server.preauth-bootstrap-token-rate-limit.test.ts b/src/gateway/server.preauth-bootstrap-token-rate-limit.test.ts
@@ -0,0 +1,115 @@
+import { randomUUID } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, test } from "vitest";
+import { WebSocket } from "ws";
+import {
+  connectReq,
+  installGatewayTestHooks,
+  testState,
+  trackConnectChallengeNonce,
+  withGatewayServer,
+} from "./test-helpers.js";
+
+installGatewayTestHooks({ scope: "suite" });
+
+async function openWs(port: number) {
+  const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+  trackConnectChallengeNonce(ws);
+  await new Promise<void>((resolve) => ws.once("open", resolve));
+  return ws;
+}
+
+async function attemptForgedBootstrap(port: number, identityPath: string) {
+  const ws = await openWs(port);
+  try {
+    const res = await connectReq(ws, {
+      skipDefaultAuth: true,
+      bootstrapToken: "forged-bootstrap-token",
+      deviceIdentityPath: identityPath,
+    });
+    return res;
+  } finally {
+    ws.close();
+    await new Promise<void>((resolve) => {
+      if (ws.readyState === WebSocket.CLOSED) {
+        resolve();
+        return;
+      }
+      ws.once("close", () => resolve());
+    });
+  }
+}
+
+describe("pre-auth bootstrap-token rate limit", () => {
+  test("locks out forged bootstrap-token attempts after maxAttempts", async () => {
+    // exemptLoopback:false ensures the limiter applies to loopback test
+    // clients. In production the same gate applies to remote clients via
+    // the per-IP bucket.
+    testState.gatewayAuth = {
+      mode: "token",
+      token: "secret",
+      rateLimit: {
+        maxAttempts: 3,
+        windowMs: 60_000,
+        lockoutMs: 60_000,
+        exemptLoopback: false,
+      },
+    };
+    await withGatewayServer(async ({ port }) => {
+      const identityPath = path.join(
+        os.tmpdir(),
+        `openclaw-preauth-bootstrap-${randomUUID()}.json`,
+      );
+
+      // The first maxAttempts forged tokens reach verifyDeviceBootstrapToken
+      // and fail with bootstrap_token_invalid (the verify path ran).
+      const reasons: Array<string | undefined> = [];
+      for (let i = 0; i < 3; i++) {
+        const res = await attemptForgedBootstrap(port, identityPath);
+        expect(res.ok).toBe(false);
+        const detail = res.error?.details as { authReason?: string } | undefined;
+        reasons.push(detail?.authReason);
+      }
+      expect(reasons.every((r) => r === "bootstrap_token_invalid")).toBe(true);
+
+      // The next attempt is the one that proves the gate fires: the gateway
+      // rejects without invoking the mutex-locked verify path.
+      const lockedOut = await attemptForgedBootstrap(port, identityPath);
+      expect(lockedOut.ok).toBe(false);
+      const detail = lockedOut.error?.details as
+        | { authReason?: string; retryAfterMs?: number }
+        | undefined;
+      expect(detail?.authReason).toBe("rate_limited");
+    });
+  });
+
+  test("forged bootstrap-token failures consume their own bucket independent of device-token", async () => {
+    testState.gatewayAuth = {
+      mode: "token",
+      token: "secret",
+      rateLimit: {
+        maxAttempts: 1,
+        windowMs: 60_000,
+        lockoutMs: 60_000,
+        exemptLoopback: false,
+      },
+    };
+    await withGatewayServer(async ({ port }) => {
+      const identityPath = path.join(
+        os.tmpdir(),
+        `openclaw-preauth-bootstrap-shared-${randomUUID()}.json`,
+      );
+
+      const first = await attemptForgedBootstrap(port, identityPath);
+      expect(first.ok).toBe(false);
+      const firstDetail = first.error?.details as { authReason?: string } | undefined;
+      expect(firstDetail?.authReason).toBe("bootstrap_token_invalid");
+
+      const second = await attemptForgedBootstrap(port, identityPath);
+      expect(second.ok).toBe(false);
+      const secondDetail = second.error?.details as { authReason?: string } | undefined;
+      expect(secondDetail?.authReason).toBe("rate_limited");
+    });
+  });
+});
diff --git a/src/gateway/server/ws-connection/auth-context.test.ts b/src/gateway/server/ws-connection/auth-context.test.ts
@@ -9,7 +9,9 @@ type VerifyBootstrapTokenFn = Parameters<
 
 function createRateLimiter(params?: { allowed?: boolean; retryAfterMs?: number }): {
   limiter: AuthRateLimiter;
+  check: ReturnType<typeof vi.fn>;
   reset: ReturnType<typeof vi.fn>;
+  recordFailure: ReturnType<typeof vi.fn>;
 } {
   const allowed = params?.allowed ?? true;
   const retryAfterMs = params?.retryAfterMs ?? 5_000;
@@ -22,7 +24,31 @@ function createRateLimiter(params?: { allowed?: boolean; retryAfterMs?: number }
       reset,
       recordFailure,
     } as unknown as AuthRateLimiter,
+    check,
     reset,
+    recordFailure,
+  };
+}
+
+function createPerScopeRateLimiter(
+  scopes: Record<string, { allowed: boolean; retryAfterMs?: number }>,
+): {
+  limiter: AuthRateLimiter;
+  check: ReturnType<typeof vi.fn>;
+  reset: ReturnType<typeof vi.fn>;
+  recordFailure: ReturnType<typeof vi.fn>;
+} {
+  const check = vi.fn((_ip: string | undefined, scope?: string) => {
+    const cfg = scopes[scope ?? ""] ?? { allowed: true };
+    return { allowed: cfg.allowed, retryAfterMs: cfg.retryAfterMs ?? 5_000 };
+  });
+  const reset = vi.fn();
+  const recordFailure = vi.fn();
+  return {
+    limiter: { check, reset, recordFailure } as unknown as AuthRateLimiter,
+    check,
+    reset,
+    recordFailure,
   };
 }
 
@@ -281,4 +307,82 @@ describe("resolveConnectAuthDecision", () => {
     expect(verifyBootstrapToken).toHaveBeenCalledOnce();
     expect(verifyDeviceToken).not.toHaveBeenCalled();
   });
+
+  it("gates bootstrap-token verify when the bootstrap-token bucket is exceeded", async () => {
+    const rateLimiter = createPerScopeRateLimiter({
+      "bootstrap-token": { allowed: false, retryAfterMs: 30_000 },
+      "device-token": { allowed: true },
+      "shared-secret": { allowed: true },
+    });
+    const verifyBootstrapToken = vi.fn<VerifyBootstrapTokenFn>(async () => ({ ok: true }));
+    const verifyDeviceToken = vi.fn<VerifyDeviceTokenFn>(async () => ({ ok: true }));
+    const decision = await resolveDeviceTokenDecision({
+      verifyBootstrapToken,
+      verifyDeviceToken,
+      rateLimiter: rateLimiter.limiter,
+      clientIp: "203.0.113.20",
+      stateOverrides: {
+        bootstrapTokenCandidate: "bootstrap-token",
+        deviceTokenCandidate: undefined,
+        deviceTokenCandidateSource: undefined,
+      },
+    });
+    expect(decision.authOk).toBe(false);
+    expect(decision.authResult.reason).toBe("rate_limited");
+    expect(decision.authResult.retryAfterMs).toBe(30_000);
+    // The verify path is mutex-locked + does fs I/O — confirm we never invoke
+    // it once the bucket is exhausted.
+    expect(verifyBootstrapToken).not.toHaveBeenCalled();
+  });
+
+  it("records a bootstrap-token failure when the verify rejects", async () => {
+    const rateLimiter = createPerScopeRateLimiter({
+      "bootstrap-token": { allowed: true },
+      "device-token": { allowed: true },
+      "shared-secret": { allowed: true },
+    });
+    const verifyBootstrapToken = vi.fn<VerifyBootstrapTokenFn>(async () => ({
+      ok: false,
+      reason: "bootstrap_token_invalid",
+    }));
+    const verifyDeviceToken = vi.fn<VerifyDeviceTokenFn>(async () => ({ ok: true }));
+    await resolveDeviceTokenDecision({
+      verifyBootstrapToken,
+      verifyDeviceToken,
+      rateLimiter: rateLimiter.limiter,
+      clientIp: "203.0.113.20",
+      stateOverrides: {
+        bootstrapTokenCandidate: "bootstrap-token",
+        deviceTokenCandidate: undefined,
+        deviceTokenCandidateSource: undefined,
+      },
+    });
+    expect(rateLimiter.recordFailure).toHaveBeenCalledWith("203.0.113.20", "bootstrap-token");
+    expect(rateLimiter.reset).not.toHaveBeenCalledWith("203.0.113.20", "bootstrap-token");
+  });
+
+  it("resets the bootstrap-token bucket when the verify succeeds", async () => {
+    const rateLimiter = createPerScopeRateLimiter({
+      "bootstrap-token": { allowed: true },
+      "device-token": { allowed: true },
+      "shared-secret": { allowed: true },
+    });
+    const verifyBootstrapToken = vi.fn<VerifyBootstrapTokenFn>(async () => ({ ok: true }));
+    const verifyDeviceToken = vi.fn<VerifyDeviceTokenFn>(async () => ({ ok: true }));
+    const decision = await resolveDeviceTokenDecision({
+      verifyBootstrapToken,
+      verifyDeviceToken,
+      rateLimiter: rateLimiter.limiter,
+      clientIp: "203.0.113.20",
+      stateOverrides: {
+        bootstrapTokenCandidate: "bootstrap-token",
+        deviceTokenCandidate: undefined,
+        deviceTokenCandidateSource: undefined,
+      },
+    });
+    expect(decision.authOk).toBe(true);
+    expect(decision.authMethod).toBe("bootstrap-token");
+    expect(rateLimiter.reset).toHaveBeenCalledWith("203.0.113.20", "bootstrap-token");
+    expect(rateLimiter.recordFailure).not.toHaveBeenCalledWith("203.0.113.20", "bootstrap-token");
+  });
 });
diff --git a/src/gateway/server/ws-connection/auth-context.ts b/src/gateway/server/ws-connection/auth-context.ts
@@ -1,6 +1,7 @@
 import type { IncomingMessage } from "node:http";
 import { normalizeOptionalString } from "../../../shared/string-coerce.js";
 import {
+  AUTH_RATE_LIMIT_SCOPE_BOOTSTRAP_TOKEN,
   AUTH_RATE_LIMIT_SCOPE_DEVICE_TOKEN,
   AUTH_RATE_LIMIT_SCOPE_SHARED_SECRET,
   type AuthRateLimiter,
@@ -187,23 +188,51 @@ export async function resolveConnectAuthDecision(params: {
 
   const bootstrapTokenCandidate = params.state.bootstrapTokenCandidate;
   if (params.hasDeviceIdentity && params.deviceId && params.publicKey && bootstrapTokenCandidate) {
-    const tokenCheck = await params.verifyBootstrapToken({
-      deviceId: params.deviceId,
-      publicKey: params.publicKey,
-      token: bootstrapTokenCandidate,
-      role: params.role,
-      scopes: params.scopes,
-    });
-    if (tokenCheck.ok) {
-      // Prefer an explicit valid bootstrap token even when another auth path
-      // (for example tailscale serve header auth) already succeeded. QR pairing
-      // relies on the server classifying the handshake as bootstrap-token so the
-      // initial node pairing can be silently auto-approved and the bootstrap
-      // token can be revoked after approval.
-      authOk = true;
-      authMethod = "bootstrap-token";
-    } else if (!authOk) {
-      authResult = { ok: false, reason: tokenCheck.reason ?? "bootstrap_token_invalid" };
+    // Per-IP gate on the bootstrap-token verify path.
+    // verifyDeviceBootstrapToken is mutex-serialized and runs fs read + fs
+    // write per attempt, so unrate-limited attackers can queue the bootstrap
+    // pairing flow behind their requests and block legitimate onboarding.
+    let bootstrapRateLimited = false;
+    if (params.rateLimiter) {
+      const bootstrapRateCheck = params.rateLimiter.check(
+        params.clientIp,
+        AUTH_RATE_LIMIT_SCOPE_BOOTSTRAP_TOKEN,
+      );
+      if (!bootstrapRateCheck.allowed) {
+        bootstrapRateLimited = true;
+        if (!authOk) {
+          authResult = {
+            ok: false,
+            reason: "rate_limited",
+            rateLimited: true,
+            retryAfterMs: bootstrapRateCheck.retryAfterMs,
+          };
+        }
+      }
+    }
+    if (!bootstrapRateLimited) {
+      const tokenCheck = await params.verifyBootstrapToken({
+        deviceId: params.deviceId,
+        publicKey: params.publicKey,
+        token: bootstrapTokenCandidate,
+        role: params.role,
+        scopes: params.scopes,
+      });
+      if (tokenCheck.ok) {
+        // Prefer an explicit valid bootstrap token even when another auth path
+        // (for example tailscale serve header auth) already succeeded. QR pairing
+        // relies on the server classifying the handshake as bootstrap-token so the
+        // initial node pairing can be silently auto-approved and the bootstrap
+        // token can be revoked after approval.
+        authOk = true;
+        authMethod = "bootstrap-token";
+        params.rateLimiter?.reset(params.clientIp, AUTH_RATE_LIMIT_SCOPE_BOOTSTRAP_TOKEN);
+      } else {
+        params.rateLimiter?.recordFailure(params.clientIp, AUTH_RATE_LIMIT_SCOPE_BOOTSTRAP_TOKEN);
+        if (!authOk) {
+          authResult = { ok: false, reason: tokenCheck.reason ?? "bootstrap_token_invalid" };
+        }
+      }
     }
   }
 
