@poolzin/pool-bot 2026.2.24 → 2026.2.26

package/dist/gateway/call.js

@@ -1,11 +1,11 @@
 import { randomUUID } from "node:crypto";
 import { loadConfig, resolveConfigPath, resolveGatewayPort, resolveStateDir, } from "../config/config.js";
 import { loadOrCreateDeviceIdentity } from "../infra/device-identity.js";
-import { pickPrimaryTailnetIPv4 } from "../infra/tailnet.js";
 import { loadGatewayTlsRuntime } from "../infra/tls/gateway.js";
 import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES, } from "../utils/message-channel.js";
 import { GatewayClient } from "./client.js";
-import { pickPrimaryLanIPv4 } from "./net.js";
+import { CLI_DEFAULT_OPERATOR_SCOPES, resolveLeastPrivilegeOperatorScopesForMethod, } from "./method-scopes.js";
+import { isSecureWebSocketUrl } from "./net.js";
 import { PROTOCOL_VERSION } from "./protocol/index.js";
 export function resolveExplicitGatewayAuth(opts) {
     const token = typeof opts?.token === "string" && opts.token.trim().length > 0 ? opts.token.trim() : undefined;
@@ -37,17 +37,10 @@ export function buildGatewayConnectionDetails(options = {}) {
     const remote = isRemoteMode ? config.gateway?.remote : undefined;
     const tlsEnabled = config.gateway?.tls?.enabled === true;
     const localPort = resolveGatewayPort(config);
-    const tailnetIPv4 = pickPrimaryTailnetIPv4();
     const bindMode = config.gateway?.bind ?? "loopback";
-    const preferTailnet = bindMode === "tailnet" && !!tailnetIPv4;
-    const preferLan = bindMode === "lan";
-    const lanIPv4 = preferLan ? pickPrimaryLanIPv4() : undefined;
     const scheme = tlsEnabled ? "wss" : "ws";
-    const localUrl = preferTailnet && tailnetIPv4
-        ? `${scheme}://${tailnetIPv4}:${localPort}`
-        : preferLan && lanIPv4
-            ? `${scheme}://${lanIPv4}:${localPort}`
-            : `${scheme}://127.0.0.1:${localPort}`;
+    // Self-connections should always target loopback; bind mode only controls listener exposure.
+    const localUrl = `${scheme}://127.0.0.1:${localPort}`;
     const urlOverride = typeof options.url === "string" && options.url.trim().length > 0
         ? options.url.trim()
         : undefined;
@@ -60,15 +53,23 @@ export function buildGatewayConnectionDetails(options = {}) {
             ? "config gateway.remote.url"
             : remoteMisconfigured
                 ? "missing gateway.remote.url (fallback local)"
-                : preferTailnet && tailnetIPv4
-                    ? `local tailnet ${tailnetIPv4}`
-                    : preferLan && lanIPv4
-                        ? `local lan ${lanIPv4}`
-                        : "local loopback";
+                : "local loopback";
     const remoteFallbackNote = remoteMisconfigured
         ? "Warn: gateway.mode=remote but gateway.remote.url is missing; set gateway.remote.url or switch gateway.mode=local."
         : undefined;
     const bindDetail = !urlOverride && !remoteUrl ? `Bind: ${bindMode}` : undefined;
+    // Security check: block ALL insecure ws:// to non-loopback addresses (CWE-319, CVSS 9.8)
+    // This applies to the FINAL resolved URL, regardless of source (config, CLI override, etc).
+    // Both credentials and chat/conversation data must not be transmitted over plaintext to remote hosts.
+    if (!isSecureWebSocketUrl(url)) {
+        throw new Error([
+            `SECURITY ERROR: Gateway URL "${url}" uses plaintext ws:// to a non-loopback address.`,
+            "Both credentials and chat data would be exposed to network interception.",
+            `Source: ${urlSource}`,
+            `Config: ${configPath}`,
+            "Fix: Use wss:// for the gateway URL, or connect via SSH tunnel to localhost.",
+        ].join("\n"));
+    }
     const message = [
         `Gateway target: ${url}`,
         `Source: ${urlSource}`,
@@ -86,77 +87,89 @@ export function buildGatewayConnectionDetails(options = {}) {
         message,
     };
 }
-export async function callGateway(opts) {
-    const timeoutMs = typeof opts.timeoutMs === "number" && Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : 10_000;
+function trimToUndefined(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function resolveGatewayCallTimeout(timeoutValue) {
+    const timeoutMs = typeof timeoutValue === "number" && Number.isFinite(timeoutValue) ? timeoutValue : 10_000;
     const safeTimerTimeoutMs = Math.max(1, Math.min(Math.floor(timeoutMs), 2_147_483_647));
+    return { timeoutMs, safeTimerTimeoutMs };
+}
+function resolveGatewayCallContext(opts) {
     const config = opts.config ?? loadConfig();
+    const configPath = opts.configPath ?? resolveConfigPath(process.env, resolveStateDir(process.env));
     const isRemoteMode = config.gateway?.mode === "remote";
-    const remote = isRemoteMode ? config.gateway?.remote : undefined;
-    const urlOverride = typeof opts.url === "string" && opts.url.trim().length > 0 ? opts.url.trim() : undefined;
+    const remote = isRemoteMode
+        ? config.gateway?.remote
+        : undefined;
+    const urlOverride = trimToUndefined(opts.url);
+    const remoteUrl = trimToUndefined(remote?.url);
     const explicitAuth = resolveExplicitGatewayAuth({ token: opts.token, password: opts.password });
-    ensureExplicitGatewayAuth({
-        urlOverride,
-        auth: explicitAuth,
-        errorHint: "Fix: pass --token or --password (or gatewayToken in tools).",
-        configPath: opts.configPath ?? resolveConfigPath(process.env, resolveStateDir(process.env)),
-    });
-    const remoteUrl = typeof remote?.url === "string" && remote.url.trim().length > 0 ? remote.url.trim() : undefined;
-    if (isRemoteMode && !urlOverride && !remoteUrl) {
-        const configPath = opts.configPath ?? resolveConfigPath(process.env, resolveStateDir(process.env));
-        throw new Error([
-            "gateway remote mode misconfigured: gateway.remote.url missing",
-            `Config: ${configPath}`,
-            "Fix: set gateway.remote.url, or set gateway.mode=local.",
-        ].join("\n"));
+    return { config, configPath, isRemoteMode, remote, urlOverride, remoteUrl, explicitAuth };
+}
+function ensureRemoteModeUrlConfigured(context) {
+    if (!context.isRemoteMode || context.urlOverride || context.remoteUrl) {
+        return;
     }
-    const authToken = config.gateway?.auth?.token;
-    const authPassword = config.gateway?.auth?.password;
-    const connectionDetails = buildGatewayConnectionDetails({
-        config,
-        url: urlOverride,
-        ...(opts.configPath ? { configPath: opts.configPath } : {}),
-    });
-    const url = connectionDetails.url;
-    const useLocalTls = config.gateway?.tls?.enabled === true && !urlOverride && !remoteUrl && url.startsWith("wss://");
-    const tlsRuntime = useLocalTls ? await loadGatewayTlsRuntime(config.gateway?.tls) : undefined;
-    const remoteTlsFingerprint = isRemoteMode && !urlOverride && remoteUrl && typeof remote?.tlsFingerprint === "string"
-        ? remote.tlsFingerprint.trim()
-        : undefined;
-    const overrideTlsFingerprint = typeof opts.tlsFingerprint === "string" ? opts.tlsFingerprint.trim() : undefined;
-    const tlsFingerprint = overrideTlsFingerprint ||
-        remoteTlsFingerprint ||
-        (tlsRuntime?.enabled ? tlsRuntime.fingerprintSha256 : undefined);
-    const token = explicitAuth.token ||
-        (!urlOverride
-            ? isRemoteMode
-                ? typeof remote?.token === "string" && remote.token.trim().length > 0
-                    ? remote.token.trim()
-                    : undefined
-                : process.env.POOLBOT_GATEWAY_TOKEN?.trim() ||
-                    process.env.CLAWDBOT_GATEWAY_TOKEN?.trim() ||
-                    (typeof authToken === "string" && authToken.trim().length > 0
-                        ? authToken.trim()
-                        : undefined)
+    throw new Error([
+        "gateway remote mode misconfigured: gateway.remote.url missing",
+        `Config: ${context.configPath}`,
+        "Fix: set gateway.remote.url, or set gateway.mode=local.",
+    ].join("\n"));
+}
+function resolveGatewayCredentials(context) {
+    const authToken = context.config.gateway?.auth?.token;
+    const authPassword = context.config.gateway?.auth?.password;
+    const token = context.explicitAuth.token ||
+        (!context.urlOverride
+            ? context.isRemoteMode
+                ? trimToUndefined(context.remote?.token)
+                : trimToUndefined(process.env.POOLBOT_GATEWAY_TOKEN) ||
+                    trimToUndefined(process.env.CLAWDBOT_GATEWAY_TOKEN) ||
+                    trimToUndefined(authToken)
             : undefined);
-    const password = explicitAuth.password ||
-        (!urlOverride
-            ? process.env.POOLBOT_GATEWAY_PASSWORD?.trim() ||
-                process.env.CLAWDBOT_GATEWAY_PASSWORD?.trim() ||
-                (isRemoteMode
-                    ? typeof remote?.password === "string" && remote.password.trim().length > 0
-                        ? remote.password.trim()
-                        : undefined
-                    : typeof authPassword === "string" && authPassword.trim().length > 0
-                        ? authPassword.trim()
-                        : undefined)
+    const password = context.explicitAuth.password ||
+        (!context.urlOverride
+            ? trimToUndefined(process.env.POOLBOT_GATEWAY_PASSWORD) ||
+                trimToUndefined(process.env.CLAWDBOT_GATEWAY_PASSWORD) ||
+                (context.isRemoteMode
+                    ? trimToUndefined(context.remote?.password)
+                    : trimToUndefined(authPassword))
             : undefined);
-    const formatCloseError = (code, reason) => {
-        const reasonText = reason?.trim() || "no close reason";
-        const hint = code === 1006 ? "abnormal closure (no close frame)" : code === 1000 ? "normal closure" : "";
-        const suffix = hint ? ` ${hint}` : "";
-        return `gateway closed (${code}${suffix}): ${reasonText}\n${connectionDetails.message}`;
-    };
-    const formatTimeoutError = () => `gateway timeout after ${timeoutMs}ms\n${connectionDetails.message}`;
+    return { token, password };
+}
+async function resolveGatewayTlsFingerprint(params) {
+    const { opts, context, url } = params;
+    const useLocalTls = context.config.gateway?.tls?.enabled === true &&
+        !context.urlOverride &&
+        !context.remoteUrl &&
+        url.startsWith("wss://");
+    const tlsRuntime = useLocalTls
+        ? await loadGatewayTlsRuntime(context.config.gateway?.tls)
+        : undefined;
+    const overrideTlsFingerprint = trimToUndefined(opts.tlsFingerprint);
+    const remoteTlsFingerprint = context.isRemoteMode && !context.urlOverride && context.remoteUrl
+        ? trimToUndefined(context.remote?.tlsFingerprint)
+        : undefined;
+    return (overrideTlsFingerprint ||
+        remoteTlsFingerprint ||
+        (tlsRuntime?.enabled ? tlsRuntime.fingerprintSha256 : undefined));
+}
+function formatGatewayCloseError(code, reason, connectionDetails) {
+    const reasonText = reason?.trim() || "no close reason";
+    const hint = code === 1006 ? "abnormal closure (no close frame)" : code === 1000 ? "normal closure" : "";
+    const suffix = hint ? ` ${hint}` : "";
+    return `gateway closed (${code}${suffix}): ${reasonText}\n${connectionDetails.message}`;
+}
+function formatGatewayTimeoutError(timeoutMs, connectionDetails) {
+    return `gateway timeout after ${timeoutMs}ms\n${connectionDetails.message}`;
+}
+async function executeGatewayRequestWithScopes(params) {
+    const { opts, scopes, url, token, password, tlsFingerprint, timeoutMs, safeTimerTimeoutMs } = params;
     return await new Promise((resolve, reject) => {
         let settled = false;
         let ignoreClose = false;
@@ -185,7 +198,7 @@ export async function callGateway(opts) {
             platform: opts.platform,
             mode: opts.mode ?? GATEWAY_CLIENT_MODES.CLI,
             role: "operator",
-            scopes: ["operator.admin", "operator.approvals", "operator.pairing"],
+            scopes,
             deviceIdentity: loadOrCreateDeviceIdentity(),
             minProtocol: opts.minProtocol ?? PROTOCOL_VERSION,
             maxProtocol: opts.maxProtocol ?? PROTOCOL_VERSION,
@@ -210,17 +223,73 @@ export async function callGateway(opts) {
                 }
                 ignoreClose = true;
                 client.stop();
-                stop(new Error(formatCloseError(code, reason)));
+                stop(new Error(formatGatewayCloseError(code, reason, params.connectionDetails)));
             },
         });
         const timer = setTimeout(() => {
             ignoreClose = true;
             client.stop();
-            stop(new Error(formatTimeoutError()));
+            stop(new Error(formatGatewayTimeoutError(timeoutMs, params.connectionDetails)));
         }, safeTimerTimeoutMs);
         client.start();
     });
 }
+async function callGatewayWithScopes(opts, scopes) {
+    const { timeoutMs, safeTimerTimeoutMs } = resolveGatewayCallTimeout(opts.timeoutMs);
+    const context = resolveGatewayCallContext(opts);
+    ensureExplicitGatewayAuth({
+        urlOverride: context.urlOverride,
+        auth: context.explicitAuth,
+        errorHint: "Fix: pass --token or --password (or gatewayToken in tools).",
+        configPath: context.configPath,
+    });
+    ensureRemoteModeUrlConfigured(context);
+    const connectionDetails = buildGatewayConnectionDetails({
+        config: context.config,
+        url: context.urlOverride,
+        ...(opts.configPath ? { configPath: opts.configPath } : {}),
+    });
+    const url = connectionDetails.url;
+    const tlsFingerprint = await resolveGatewayTlsFingerprint({ opts, context, url });
+    const { token, password } = resolveGatewayCredentials(context);
+    return await executeGatewayRequestWithScopes({
+        opts,
+        scopes,
+        url,
+        token,
+        password,
+        tlsFingerprint,
+        timeoutMs,
+        safeTimerTimeoutMs,
+        connectionDetails,
+    });
+}
+export async function callGatewayScoped(opts) {
+    return await callGatewayWithScopes(opts, opts.scopes);
+}
+export async function callGatewayCli(opts) {
+    const scopes = Array.isArray(opts.scopes) ? opts.scopes : CLI_DEFAULT_OPERATOR_SCOPES;
+    return await callGatewayWithScopes(opts, scopes);
+}
+export async function callGatewayLeastPrivilege(opts) {
+    const scopes = resolveLeastPrivilegeOperatorScopesForMethod(opts.method);
+    return await callGatewayWithScopes(opts, scopes);
+}
+export async function callGateway(opts) {
+    if (Array.isArray(opts.scopes)) {
+        return await callGatewayWithScopes(opts, opts.scopes);
+    }
+    const callerMode = opts.mode ?? GATEWAY_CLIENT_MODES.BACKEND;
+    const callerName = opts.clientName ?? GATEWAY_CLIENT_NAMES.GATEWAY_CLIENT;
+    if (callerMode === GATEWAY_CLIENT_MODES.CLI || callerName === GATEWAY_CLIENT_NAMES.CLI) {
+        return await callGatewayCli(opts);
+    }
+    return await callGatewayLeastPrivilege({
+        ...opts,
+        mode: callerMode,
+        clientName: callerName,
+    });
+}
 export function randomIdempotencyKey() {
     return randomUUID();
 }

package/dist/gateway/canvas-capability.js

@@ -0,0 +1,75 @@
+import { randomBytes } from "node:crypto";
+export const CANVAS_CAPABILITY_PATH_PREFIX = "/__poolbot__/cap";
+export const CANVAS_CAPABILITY_QUERY_PARAM = "oc_cap";
+export const CANVAS_CAPABILITY_TTL_MS = 10 * 60_000;
+function normalizeCapability(raw) {
+    const trimmed = raw?.trim();
+    return trimmed ? trimmed : undefined;
+}
+export function mintCanvasCapabilityToken() {
+    return randomBytes(18).toString("base64url");
+}
+export function buildCanvasScopedHostUrl(baseUrl, capability) {
+    const normalizedCapability = normalizeCapability(capability);
+    if (!normalizedCapability) {
+        return undefined;
+    }
+    try {
+        const url = new URL(baseUrl);
+        const trimmedPath = url.pathname.replace(/\/+$/, "");
+        const prefix = `${CANVAS_CAPABILITY_PATH_PREFIX}/${encodeURIComponent(normalizedCapability)}`;
+        url.pathname = `${trimmedPath}${prefix}`;
+        url.search = "";
+        url.hash = "";
+        return url.toString().replace(/\/$/, "");
+    }
+    catch {
+        return undefined;
+    }
+}
+export function normalizeCanvasScopedUrl(rawUrl) {
+    const url = new URL(rawUrl, "http://localhost");
+    const prefix = `${CANVAS_CAPABILITY_PATH_PREFIX}/`;
+    let scopedPath = false;
+    let malformedScopedPath = false;
+    let capabilityFromPath;
+    let rewrittenUrl;
+    if (url.pathname.startsWith(prefix)) {
+        scopedPath = true;
+        const remainder = url.pathname.slice(prefix.length);
+        const slashIndex = remainder.indexOf("/");
+        if (slashIndex <= 0) {
+            malformedScopedPath = true;
+        }
+        else {
+            const encodedCapability = remainder.slice(0, slashIndex);
+            const canonicalPath = remainder.slice(slashIndex) || "/";
+            let decoded;
+            try {
+                decoded = decodeURIComponent(encodedCapability);
+            }
+            catch {
+                malformedScopedPath = true;
+            }
+            capabilityFromPath = normalizeCapability(decoded);
+            if (!capabilityFromPath || !canonicalPath.startsWith("/")) {
+                malformedScopedPath = true;
+            }
+            else {
+                url.pathname = canonicalPath;
+                if (!url.searchParams.has(CANVAS_CAPABILITY_QUERY_PARAM)) {
+                    url.searchParams.set(CANVAS_CAPABILITY_QUERY_PARAM, capabilityFromPath);
+                }
+                rewrittenUrl = `${url.pathname}${url.search}`;
+            }
+        }
+    }
+    const capability = capabilityFromPath ?? normalizeCapability(url.searchParams.get(CANVAS_CAPABILITY_QUERY_PARAM));
+    return {
+        pathname: url.pathname,
+        capability,
+        rewrittenUrl,
+        scopedPath,
+        malformedScopedPath,
+    };
+}

package/dist/gateway/client.js

@@ -2,11 +2,13 @@ import { randomUUID } from "node:crypto";
 import { WebSocket } from "ws";
 import { clearDeviceAuthToken, loadDeviceAuthToken, storeDeviceAuthToken, } from "../infra/device-auth-store.js";
 import { loadOrCreateDeviceIdentity, publicKeyRawBase64UrlFromPem, signDevicePayload, } from "../infra/device-identity.js";
+import { clearDevicePairing } from "../infra/device-pairing.js";
 import { normalizeFingerprint } from "../infra/tls/fingerprint.js";
 import { rawDataToString } from "../infra/ws.js";
 import { logDebug, logError } from "../logger.js";
 import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES, } from "../utils/message-channel.js";
 import { buildDeviceAuthPayload } from "./device-auth.js";
+import { isSecureWebSocketUrl } from "./net.js";
 import { PROTOCOL_VERSION, validateEventFrame, validateRequestFrame, validateResponseFrame, } from "./protocol/index.js";
 export const GATEWAY_CLOSE_CODE_HINTS = {
     1000: "normal closure",
@@ -46,6 +48,24 @@ export class GatewayClient {
             this.opts.onConnectError?.(new Error("gateway tls fingerprint requires wss:// gateway url"));
             return;
         }
+        // Security check: block ALL plaintext ws:// to non-loopback addresses (CWE-319, CVSS 9.8)
+        // This protects both credentials AND chat/conversation data from MITM attacks.
+        // Device tokens may be loaded later in sendConnect(), so we block regardless of hasCredentials.
+        if (!isSecureWebSocketUrl(url)) {
+            // Safe hostname extraction - avoid throwing on malformed URLs in error path
+            let displayHost = url;
+            try {
+                displayHost = new URL(url).hostname || url;
+            }
+            catch {
+                // Use raw URL if parsing fails
+            }
+            const error = new Error(`SECURITY ERROR: Cannot connect to "${displayHost}" over plaintext ws://. ` +
+                "Both credentials and chat data would be exposed to network interception. " +
+                "Use wss:// for the gateway URL, or connect via SSH tunnel to localhost.");
+            this.opts.onConnectError?.(error);
+            return;
+        }
         // Allow node screen snapshots and other large responses.
         const wsOptions = {
             maxPayload: 25 * 1024 * 1024,
@@ -87,17 +107,21 @@ export class GatewayClient {
         this.ws.on("close", (code, reason) => {
             const reasonText = rawDataToString(reason);
             this.ws = null;
-            // If closed due to device token mismatch, clear the stored token so next attempt can get a fresh one
+            // If closed due to device token mismatch, clear the stored token and pairing so next attempt can get a fresh one
             if (code === 1008 &&
                 reasonText.toLowerCase().includes("device token mismatch") &&
                 this.opts.deviceIdentity) {
+                const deviceId = this.opts.deviceIdentity.deviceId;
                 const role = this.opts.role ?? "operator";
                 try {
-                    clearDeviceAuthToken({ deviceId: this.opts.deviceIdentity.deviceId, role });
-                    logDebug(`cleared stale device-auth token for device ${this.opts.deviceIdentity.deviceId}`);
+                    clearDeviceAuthToken({ deviceId, role });
+                    void clearDevicePairing(deviceId).catch((err) => {
+                        logDebug(`failed clearing stale device pairing for device ${deviceId}: ${String(err)}`);
+                    });
+                    logDebug(`cleared stale device-auth token for device ${deviceId}`);
                 }
                 catch (err) {
-                    logDebug(`failed clearing stale device-auth token for device ${this.opts.deviceIdentity.deviceId}: ${String(err)}`);
+                    logDebug(`failed clearing stale device-auth token for device ${deviceId}: ${String(err)}`);
                 }
             }
             this.flushPendingErrors(new Error(`gateway closed (${code}): ${reasonText}`));

package/dist/gateway/config-reload.js

@@ -1,3 +1,4 @@
+import { isDeepStrictEqual } from "node:util";
 import chokidar from "chokidar";
 import { listChannelPlugins } from "../channels/plugins/index.js";
 import { getActivePluginRegistry } from "../plugins/runtime.js";
@@ -102,10 +103,8 @@ export function diffConfigPaths(prev, next, prefix = "") {
         }
         return paths;
     }
-    if (Array.isArray(prev) && Array.isArray(next)) {
-        if (prev.length === next.length && prev.every((val, idx) => val === next[idx])) {
-            return [];
-        }
+    if (isDeepStrictEqual(prev, next)) {
+        return [];
     }
     return [prefix || "<root>"];
 }

package/dist/gateway/control-plane-audit.js

@@ -0,0 +1,28 @@
+function normalizePart(value, fallback) {
+    if (typeof value !== "string") {
+        return fallback;
+    }
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : fallback;
+}
+export function resolveControlPlaneActor(client) {
+    return {
+        actor: normalizePart(client?.connect?.client?.id, "unknown-actor"),
+        deviceId: normalizePart(client?.connect?.device?.id, "unknown-device"),
+        clientIp: normalizePart(client?.clientIp, "unknown-ip"),
+        connId: normalizePart(client?.connId, "unknown-conn"),
+    };
+}
+export function formatControlPlaneActor(actor) {
+    return `actor=${actor.actor} device=${actor.deviceId} ip=${actor.clientIp} conn=${actor.connId}`;
+}
+export function summarizeChangedPaths(paths, maxPaths = 8) {
+    if (paths.length === 0) {
+        return "<none>";
+    }
+    if (paths.length <= maxPaths) {
+        return paths.join(",");
+    }
+    const head = paths.slice(0, maxPaths).join(",");
+    return `${head},+${paths.length - maxPaths} more`;
+}

package/dist/gateway/control-plane-rate-limit.js

@@ -0,0 +1,53 @@
+const CONTROL_PLANE_RATE_LIMIT_MAX_REQUESTS = 3;
+const CONTROL_PLANE_RATE_LIMIT_WINDOW_MS = 60_000;
+const controlPlaneBuckets = new Map();
+function normalizePart(value, fallback) {
+    if (typeof value !== "string") {
+        return fallback;
+    }
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : fallback;
+}
+export function resolveControlPlaneRateLimitKey(client) {
+    const deviceId = normalizePart(client?.connect?.device?.id, "unknown-device");
+    const clientIp = normalizePart(client?.clientIp, "unknown-ip");
+    return `${deviceId}|${clientIp}`;
+}
+export function consumeControlPlaneWriteBudget(params) {
+    const nowMs = params.nowMs ?? Date.now();
+    const key = resolveControlPlaneRateLimitKey(params.client);
+    const bucket = controlPlaneBuckets.get(key);
+    if (!bucket || nowMs - bucket.windowStartMs >= CONTROL_PLANE_RATE_LIMIT_WINDOW_MS) {
+        controlPlaneBuckets.set(key, {
+            count: 1,
+            windowStartMs: nowMs,
+        });
+        return {
+            allowed: true,
+            retryAfterMs: 0,
+            remaining: CONTROL_PLANE_RATE_LIMIT_MAX_REQUESTS - 1,
+            key,
+        };
+    }
+    if (bucket.count >= CONTROL_PLANE_RATE_LIMIT_MAX_REQUESTS) {
+        const retryAfterMs = Math.max(0, bucket.windowStartMs + CONTROL_PLANE_RATE_LIMIT_WINDOW_MS - nowMs);
+        return {
+            allowed: false,
+            retryAfterMs,
+            remaining: 0,
+            key,
+        };
+    }
+    bucket.count += 1;
+    return {
+        allowed: true,
+        retryAfterMs: 0,
+        remaining: Math.max(0, CONTROL_PLANE_RATE_LIMIT_MAX_REQUESTS - bucket.count),
+        key,
+    };
+}
+export const __testing = {
+    resetControlPlaneRateLimitState() {
+        controlPlaneBuckets.clear();
+    },
+};