@poolzin/pool-bot 2026.2.21 → 2026.2.22

package/dist/gateway/call.js

@@ -1,11 +1,35 @@
 import { randomUUID } from "node:crypto";
 import { loadConfig, resolveConfigPath, resolveGatewayPort, resolveStateDir, } from "../config/config.js";
-import { pickPrimaryTailnetIPv4 } from "../infra/tailnet.js";
 import { loadOrCreateDeviceIdentity } from "../infra/device-identity.js";
-import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES, } from "../utils/message-channel.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 { 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;
+    const password = typeof opts?.password === "string" && opts.password.trim().length > 0
+        ? opts.password.trim()
+        : undefined;
+    return { token, password };
+}
+export function ensureExplicitGatewayAuth(params) {
+    if (!params.urlOverride) {
+        return;
+    }
+    if (params.auth.token || params.auth.password) {
+        return;
+    }
+    const message = [
+        "gateway url override requires explicit credentials",
+        params.errorHint,
+        params.configPath ? `Config: ${params.configPath}` : undefined,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    throw new Error(message);
+}
 export function buildGatewayConnectionDetails(options = {}) {
     const config = options.config ?? loadConfig();
     const configPath = options.configPath ?? resolveConfigPath(process.env, resolveStateDir(process.env));
@@ -16,10 +40,14 @@ export function buildGatewayConnectionDetails(options = {}) {
     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}`
-        : `${scheme}://127.0.0.1:${localPort}`;
+        : preferLan && lanIPv4
+            ? `${scheme}://${lanIPv4}:${localPort}`
+            : `${scheme}://127.0.0.1:${localPort}`;
     const urlOverride = typeof options.url === "string" && options.url.trim().length > 0
         ? options.url.trim()
         : undefined;
@@ -34,7 +62,9 @@ export function buildGatewayConnectionDetails(options = {}) {
                 ? "missing gateway.remote.url (fallback local)"
                 : preferTailnet && tailnetIPv4
                     ? `local tailnet ${tailnetIPv4}`
-                    : "local loopback";
+                    : preferLan && lanIPv4
+                        ? `local lan ${lanIPv4}`
+                        : "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;
@@ -57,11 +87,19 @@ export function buildGatewayConnectionDetails(options = {}) {
     };
 }
 export async function callGateway(opts) {
-    const timeoutMs = opts.timeoutMs ?? 10_000;
+    const timeoutMs = typeof opts.timeoutMs === "number" && Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : 10_000;
+    const safeTimerTimeoutMs = Math.max(1, Math.min(Math.floor(timeoutMs), 2_147_483_647));
     const config = opts.config ?? loadConfig();
     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 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));
@@ -88,30 +126,30 @@ export async function callGateway(opts) {
     const tlsFingerprint = overrideTlsFingerprint ||
         remoteTlsFingerprint ||
         (tlsRuntime?.enabled ? tlsRuntime.fingerprintSha256 : undefined);
-    const token = (typeof opts.token === "string" && opts.token.trim().length > 0
-        ? opts.token.trim()
-        : undefined) ||
-        (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));
-    const password = (typeof opts.password === "string" && opts.password.trim().length > 0
-        ? opts.password.trim()
-        : undefined) ||
-        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 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)
+            : 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)
+            : 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" : "";
@@ -123,14 +161,17 @@ export async function callGateway(opts) {
         let settled = false;
         let ignoreClose = false;
         const stop = (err, value) => {
-            if (settled)
+            if (settled) {
                 return;
+            }
             settled = true;
             clearTimeout(timer);
-            if (err)
+            if (err) {
                 reject(err);
-            else
+            }
+            else {
                 resolve(value);
+            }
         };
         const client = new GatewayClient({
             url,
@@ -164,8 +205,9 @@ export async function callGateway(opts) {
                 }
             },
             onClose: (code, reason) => {
-                if (settled || ignoreClose)
+                if (settled || ignoreClose) {
                     return;
+                }
                 ignoreClose = true;
                 client.stop();
                 stop(new Error(formatCloseError(code, reason)));
@@ -175,7 +217,7 @@ export async function callGateway(opts) {
             ignoreClose = true;
             client.stop();
             stop(new Error(formatTimeoutError()));
-        }, timeoutMs);
+        }, safeTimerTimeoutMs);
         client.start();
     });
 }

package/dist/gateway/channel-health-monitor.js

@@ -26,71 +26,78 @@ export function startChannelHealthMonitor(deps) {
     const restartRecords = new Map();
     const startedAt = Date.now();
     let stopped = false;
+    let checkInFlight = false;
     let timer = null;
     const rKey = (channelId, accountId) => `${channelId}:${accountId}`;
     function pruneOldRestarts(record, now) {
         record.restartsThisHour = record.restartsThisHour.filter((r) => now - r.at < ONE_HOUR_MS);
     }
     async function runCheck() {
-        if (stopped) {
+        if (stopped || checkInFlight) {
             return;
         }
-        const now = Date.now();
-        if (now - startedAt < startupGraceMs) {
-            return;
-        }
-        const snapshot = channelManager.getRuntimeSnapshot();
-        for (const [channelId, accounts] of Object.entries(snapshot.channelAccounts)) {
-            if (!accounts) {
-                continue;
+        checkInFlight = true;
+        try {
+            const now = Date.now();
+            if (now - startedAt < startupGraceMs) {
+                return;
             }
-            for (const [accountId, status] of Object.entries(accounts)) {
-                if (!status) {
-                    continue;
-                }
-                if (!isManagedAccount(status)) {
-                    continue;
-                }
-                if (channelManager.isManuallyStopped(channelId, accountId)) {
+            const snapshot = channelManager.getRuntimeSnapshot();
+            for (const [channelId, accounts] of Object.entries(snapshot.channelAccounts)) {
+                if (!accounts) {
                     continue;
                 }
-                if (isChannelHealthy(status)) {
-                    continue;
-                }
-                const key = rKey(channelId, accountId);
-                const record = restartRecords.get(key) ?? {
-                    lastRestartAt: 0,
-                    restartsThisHour: [],
-                };
-                if (now - record.lastRestartAt <= cooldownMs) {
-                    continue;
-                }
-                pruneOldRestarts(record, now);
-                if (record.restartsThisHour.length >= maxRestartsPerHour) {
-                    log.warn?.(`[${channelId}:${accountId}] health-monitor: hit ${maxRestartsPerHour} restarts/hour limit, skipping`);
-                    continue;
-                }
-                const reason = !status.running
-                    ? status.reconnectAttempts && status.reconnectAttempts >= 10
-                        ? "gave-up"
-                        : "stopped"
-                    : "stuck";
-                log.info?.(`[${channelId}:${accountId}] health-monitor: restarting (reason: ${reason})`);
-                try {
-                    if (status.running) {
-                        await channelManager.stopChannel(channelId, accountId);
+                for (const [accountId, status] of Object.entries(accounts)) {
+                    if (!status) {
+                        continue;
+                    }
+                    if (!isManagedAccount(status)) {
+                        continue;
+                    }
+                    if (channelManager.isManuallyStopped(channelId, accountId)) {
+                        continue;
+                    }
+                    if (isChannelHealthy(status)) {
+                        continue;
+                    }
+                    const key = rKey(channelId, accountId);
+                    const record = restartRecords.get(key) ?? {
+                        lastRestartAt: 0,
+                        restartsThisHour: [],
+                    };
+                    if (now - record.lastRestartAt <= cooldownMs) {
+                        continue;
+                    }
+                    pruneOldRestarts(record, now);
+                    if (record.restartsThisHour.length >= maxRestartsPerHour) {
+                        log.warn?.(`[${channelId}:${accountId}] health-monitor: hit ${maxRestartsPerHour} restarts/hour limit, skipping`);
+                        continue;
+                    }
+                    const reason = !status.running
+                        ? status.reconnectAttempts && status.reconnectAttempts >= 10
+                            ? "gave-up"
+                            : "stopped"
+                        : "stuck";
+                    log.info?.(`[${channelId}:${accountId}] health-monitor: restarting (reason: ${reason})`);
+                    try {
+                        if (status.running) {
+                            await channelManager.stopChannel(channelId, accountId);
+                        }
+                        channelManager.resetRestartAttempts(channelId, accountId);
+                        await channelManager.startChannel(channelId, accountId);
+                        record.lastRestartAt = now;
+                        record.restartsThisHour.push({ at: now });
+                        restartRecords.set(key, record);
+                    }
+                    catch (err) {
+                        log.error?.(`[${channelId}:${accountId}] health-monitor: restart failed: ${String(err)}`);
                     }
-                    channelManager.resetRestartAttempts(channelId, accountId);
-                    await channelManager.startChannel(channelId, accountId);
-                    record.lastRestartAt = now;
-                    record.restartsThisHour.push({ at: now });
-                    restartRecords.set(key, record);
-                }
-                catch (err) {
-                    log.error?.(`[${channelId}:${accountId}] health-monitor: restart failed: ${String(err)}`);
                 }
             }
         }
+        finally {
+            checkInFlight = false;
+        }
     }
     function stop() {
         stopped = true;

package/dist/gateway/client.js

@@ -1,10 +1,10 @@
 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 { normalizeFingerprint } from "../infra/tls/fingerprint.js";
 import { rawDataToString } from "../infra/ws.js";
 import { logDebug, logError } from "../logger.js";
-import { loadOrCreateDeviceIdentity, publicKeyRawBase64UrlFromPem, signDevicePayload, } from "../infra/device-identity.js";
-import { clearDeviceAuthToken, loadDeviceAuthToken, storeDeviceAuthToken, } from "../infra/device-auth-store.js";
 import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES, } from "../utils/message-channel.js";
 import { buildDeviceAuthPayload } from "./device-auth.js";
 import { PROTOCOL_VERSION, validateEventFrame, validateRequestFrame, validateResponseFrame, } from "./protocol/index.js";
@@ -38,8 +38,9 @@ export class GatewayClient {
         };
     }
     start() {
-        if (this.closed)
+        if (this.closed) {
             return;
+        }
         const url = this.opts.url ?? "ws://127.0.0.1:18789";
         if (this.opts.tlsFingerprint && !url.startsWith("wss://")) {
             this.opts.onConnectError?.(new Error("gateway tls fingerprint requires wss:// gateway url"));
@@ -67,6 +68,7 @@ export class GatewayClient {
                     return new Error("gateway tls fingerprint mismatch");
                 }
                 return undefined;
+                // oxlint-disable-next-line typescript/no-explicit-any
             });
         }
         this.ws = new WebSocket(url, wsOptions);
@@ -85,6 +87,19 @@ 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 (code === 1008 &&
+                reasonText.toLowerCase().includes("device token mismatch") &&
+                this.opts.deviceIdentity) {
+                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}`);
+                }
+                catch (err) {
+                    logDebug(`failed clearing stale device-auth token for device ${this.opts.deviceIdentity.deviceId}: ${String(err)}`);
+                }
+            }
             this.flushPendingErrors(new Error(`gateway closed (${code}): ${reasonText}`));
             this.scheduleReconnect();
             this.opts.onClose?.(code, reasonText);
@@ -107,8 +122,9 @@ export class GatewayClient {
         this.flushPendingErrors(new Error("gateway client stopped"));
     }
     sendConnect() {
-        if (this.connectSent)
+        if (this.connectSent) {
             return;
+        }
         this.connectSent = true;
         if (this.connectTimer) {
             clearTimeout(this.connectTimer);
@@ -118,8 +134,9 @@ export class GatewayClient {
         const storedToken = this.opts.deviceIdentity
             ? loadDeviceAuthToken({ deviceId: this.opts.deviceIdentity.deviceId, role })?.token
             : null;
-        const authToken = storedToken ?? this.opts.token ?? undefined;
-        const canFallbackToShared = Boolean(storedToken && this.opts.token);
+        // Prefer explicitly provided credentials (e.g. CLI `--token`) over any persisted
+        // device-auth tokens. Persisted tokens are only used when no token is provided.
+        const authToken = this.opts.token ?? storedToken ?? undefined;
         const auth = authToken || this.opts.password
             ? {
                 token: authToken,
@@ -130,8 +147,9 @@ export class GatewayClient {
         const nonce = this.connectNonce ?? undefined;
         const scopes = this.opts.scopes ?? ["operator.admin"];
         const device = (() => {
-            if (!this.opts.deviceIdentity)
+            if (!this.opts.deviceIdentity) {
                 return undefined;
+            }
             const payload = buildDeviceAuthPayload({
                 deviceId: this.opts.deviceIdentity.deviceId,
                 clientId: this.opts.clientName ?? GATEWAY_CLIENT_NAMES.GATEWAY_CLIENT,
@@ -194,18 +212,14 @@ export class GatewayClient {
             this.opts.onHelloOk?.(helloOk);
         })
             .catch((err) => {
-            if (canFallbackToShared && this.opts.deviceIdentity) {
-                clearDeviceAuthToken({
-                    deviceId: this.opts.deviceIdentity.deviceId,
-                    role,
-                });
-            }
             this.opts.onConnectError?.(err instanceof Error ? err : new Error(String(err)));
             const msg = `gateway connect failed: ${String(err)}`;
-            if (this.opts.mode === GATEWAY_CLIENT_MODES.PROBE)
+            if (this.opts.mode === GATEWAY_CLIENT_MODES.PROBE) {
                 logDebug(msg);
-            else
+            }
+            else {
                 logError(msg);
+            }
             this.ws?.close(1008, "connect failed");
         });
     }
@@ -238,8 +252,9 @@ export class GatewayClient {
             }
             if (validateResponseFrame(parsed)) {
                 const pending = this.pending.get(parsed.id);
-                if (!pending)
+                if (!pending) {
                     return;
+                }
                 // If the payload is an ack with status accepted, keep waiting for final.
                 const payload = parsed.payload;
                 const status = payload?.status;
@@ -247,10 +262,12 @@ export class GatewayClient {
                     return;
                 }
                 this.pending.delete(parsed.id);
-                if (parsed.ok)
+                if (parsed.ok) {
                     pending.resolve(parsed.payload);
-                else
+                }
+                else {
                     pending.reject(new Error(parsed.error?.message ?? "unknown error"));
+                }
             }
         }
         catch (err) {
@@ -260,15 +277,21 @@ export class GatewayClient {
     queueConnect() {
         this.connectNonce = null;
         this.connectSent = false;
-        if (this.connectTimer)
+        const rawConnectDelayMs = this.opts.connectDelayMs;
+        const connectDelayMs = typeof rawConnectDelayMs === "number" && Number.isFinite(rawConnectDelayMs)
+            ? Math.max(0, Math.min(5_000, rawConnectDelayMs))
+            : 750;
+        if (this.connectTimer) {
             clearTimeout(this.connectTimer);
+        }
         this.connectTimer = setTimeout(() => {
             this.sendConnect();
-        }, 750);
+        }, connectDelayMs);
     }
     scheduleReconnect() {
-        if (this.closed)
+        if (this.closed) {
             return;
+        }
         if (this.tickTimer) {
             clearInterval(this.tickTimer);
             this.tickTimer = null;
@@ -284,14 +307,21 @@ export class GatewayClient {
         this.pending.clear();
     }
     startTickWatch() {
-        if (this.tickTimer)
+        if (this.tickTimer) {
             clearInterval(this.tickTimer);
-        const interval = Math.max(this.tickIntervalMs, 1000);
+        }
+        const rawMinInterval = this.opts.tickWatchMinIntervalMs;
+        const minInterval = typeof rawMinInterval === "number" && Number.isFinite(rawMinInterval)
+            ? Math.max(1, Math.min(30_000, rawMinInterval))
+            : 1000;
+        const interval = Math.max(this.tickIntervalMs, minInterval);
         this.tickTimer = setInterval(() => {
-            if (this.closed)
+            if (this.closed) {
                 return;
-            if (!this.lastTick)
+            }
+            if (!this.lastTick) {
                 return;
+            }
             const gap = Date.now() - this.lastTick;
             if (gap > this.tickIntervalMs * 2) {
                 this.ws?.close(4000, "tick timeout");
@@ -299,21 +329,25 @@ export class GatewayClient {
         }, interval);
     }
     validateTlsFingerprint() {
-        if (!this.opts.tlsFingerprint || !this.ws)
+        if (!this.opts.tlsFingerprint || !this.ws) {
             return null;
+        }
         const expected = normalizeFingerprint(this.opts.tlsFingerprint);
-        if (!expected)
+        if (!expected) {
             return new Error("gateway tls fingerprint missing");
+        }
         const socket = this.ws._socket;
         if (!socket || typeof socket.getPeerCertificate !== "function") {
             return new Error("gateway tls fingerprint unavailable");
         }
         const cert = socket.getPeerCertificate();
         const fingerprint = normalizeFingerprint(cert?.fingerprint256 ?? "");
-        if (!fingerprint)
+        if (!fingerprint) {
             return new Error("gateway tls fingerprint unavailable");
-        if (fingerprint !== expected)
+        }
+        if (fingerprint !== expected) {
             return new Error("gateway tls fingerprint mismatch");
+        }
         return null;
     }
     async request(method, params, opts) {

package/dist/gateway/control-ui-contract.js

@@ -1 +1 @@
-export const CONTROL_UI_BOOTSTRAP_CONFIG_PATH = "/__openclaw/control-ui-config.json";
+export const CONTROL_UI_BOOTSTRAP_CONFIG_PATH = "/__poolbot/control-ui-config.json";

package/dist/gateway/gateway-config-prompts.shared.js

@@ -20,6 +20,6 @@ export const TAILSCALE_MISSING_BIN_NOTE_LINES = [
 ];
 export const TAILSCALE_DOCS_LINES = [
     "Docs:",
-    "https://docs.openclaw.ai/gateway/tailscale",
-    "https://docs.openclaw.ai/web",
+    "https://docs.poolbot.dev/gateway/tailscale",
+    "https://docs.poolbot.dev/web",
 ];

package/dist/gateway/net.js

@@ -23,6 +23,27 @@ export function pickPrimaryLanIPv4() {
     }
     return undefined;
 }
+export function normalizeHostHeader(hostHeader) {
+    return (hostHeader ?? "").trim().toLowerCase();
+}
+export function resolveHostName(hostHeader) {
+    const host = normalizeHostHeader(hostHeader);
+    if (!host) {
+        return "";
+    }
+    if (host.startsWith("[")) {
+        const end = host.indexOf("]");
+        if (end !== -1) {
+            return host.slice(1, end);
+        }
+    }
+    // Unbracketed IPv6 host (e.g. "::1") has no port and should be returned as-is.
+    if (net.isIP(host) === 6) {
+        return host;
+    }
+    const [name] = host.split(":");
+    return name ?? "";
+}
 export function isLoopbackAddress(ip) {
     if (!ip) {
         return false;
@@ -41,6 +62,47 @@ export function isLoopbackAddress(ip) {
     }
     return false;
 }
+/**
+ * Returns true if the IP belongs to a private or loopback network range.
+ * Private ranges: RFC1918, link-local, ULA IPv6, and CGNAT (100.64/10), plus loopback.
+ */
+export function isPrivateOrLoopbackAddress(ip) {
+    if (!ip) {
+        return false;
+    }
+    if (isLoopbackAddress(ip)) {
+        return true;
+    }
+    const normalized = normalizeIPv4MappedAddress(ip.trim().toLowerCase());
+    const family = net.isIP(normalized);
+    if (!family) {
+        return false;
+    }
+    if (family === 4) {
+        const octets = normalized.split(".").map((value) => Number.parseInt(value, 10));
+        if (octets.length !== 4 || octets.some((value) => Number.isNaN(value))) {
+            return false;
+        }
+        const [o1, o2] = octets;
+        // RFC1918 IPv4 private ranges.
+        if (o1 === 10 || (o1 === 172 && o2 >= 16 && o2 <= 31) || (o1 === 192 && o2 === 168)) {
+            return true;
+        }
+        // IPv4 link-local and CGNAT (commonly used by Tailnet-like networks).
+        if ((o1 === 169 && o2 === 254) || (o1 === 100 && o2 >= 64 && o2 <= 127)) {
+            return true;
+        }
+        return false;
+    }
+    // IPv6 unique-local and link-local ranges.
+    if (normalized.startsWith("fc") || normalized.startsWith("fd")) {
+        return true;
+    }
+    if (/^fe[89ab]/.test(normalized)) {
+        return true;
+    }
+    return false;
+}
 function normalizeIPv4MappedAddress(ip) {
     if (ip.startsWith("::ffff:")) {
         return ip.slice("::ffff:".length);
@@ -87,12 +149,58 @@ function parseRealIp(realIp) {
     }
     return normalizeIp(stripOptionalPort(raw));
 }
+/**
+ * Check if an IP address matches a CIDR block.
+ * Supports IPv4 CIDR notation (e.g., "10.42.0.0/24").
+ *
+ * @param ip - The IP address to check (e.g., "10.42.0.59")
+ * @param cidr - The CIDR block (e.g., "10.42.0.0/24")
+ * @returns True if the IP is within the CIDR block
+ */
+function ipMatchesCIDR(ip, cidr) {
+    // Handle exact IP match (no CIDR notation)
+    if (!cidr.includes("/")) {
+        return ip === cidr;
+    }
+    const [subnet, prefixLenStr] = cidr.split("/");
+    const prefixLen = parseInt(prefixLenStr, 10);
+    // Validate prefix length
+    if (Number.isNaN(prefixLen) || prefixLen < 0 || prefixLen > 32) {
+        return false;
+    }
+    // Convert IPs to 32-bit integers
+    const ipParts = ip.split(".").map((p) => parseInt(p, 10));
+    const subnetParts = subnet.split(".").map((p) => parseInt(p, 10));
+    // Validate IP format
+    if (ipParts.length !== 4 ||
+        subnetParts.length !== 4 ||
+        ipParts.some((p) => Number.isNaN(p) || p < 0 || p > 255) ||
+        subnetParts.some((p) => Number.isNaN(p) || p < 0 || p > 255)) {
+        return false;
+    }
+    const ipInt = (ipParts[0] << 24) | (ipParts[1] << 16) | (ipParts[2] << 8) | ipParts[3];
+    const subnetInt = (subnetParts[0] << 24) | (subnetParts[1] << 16) | (subnetParts[2] << 8) | subnetParts[3];
+    // Create mask and compare
+    const mask = prefixLen === 0 ? 0 : (-1 >>> (32 - prefixLen)) << (32 - prefixLen);
+    return (ipInt & mask) === (subnetInt & mask);
+}
 export function isTrustedProxyAddress(ip, trustedProxies) {
     const normalized = normalizeIp(ip);
     if (!normalized || !trustedProxies || trustedProxies.length === 0) {
         return false;
     }
-    return trustedProxies.some((proxy) => normalizeIp(proxy) === normalized);
+    return trustedProxies.some((proxy) => {
+        const candidate = proxy.trim();
+        if (!candidate) {
+            return false;
+        }
+        // Handle CIDR notation
+        if (candidate.includes("/")) {
+            return ipMatchesCIDR(normalized, candidate);
+        }
+        // Exact IP match
+        return normalizeIp(candidate) === normalized;
+    });
 }
 export function resolveGatewayClientIp(params) {
     const remote = normalizeIp(params.remoteAddr);