@openclaw/discord 2026.3.13 → 2026.5.2-beta.1

package/src/outbound-session-route.ts

@@ -0,0 +1,72 @@
+import { buildThreadAwareOutboundSessionRoute } from "openclaw/plugin-sdk/channel-core";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { buildOutboundBaseSessionKey, type RoutePeer } from "openclaw/plugin-sdk/routing";
+import { parseDiscordTarget } from "./target-parsing.js";
+
+export type ResolveDiscordOutboundSessionRouteParams = {
+  cfg: OpenClawConfig;
+  agentId: string;
+  accountId?: string | null;
+  target: string;
+  resolvedTarget?: { kind: string };
+  replyToId?: string | null;
+  threadId?: string | number | null;
+};
+
+export function resolveDiscordOutboundSessionRoute(
+  params: ResolveDiscordOutboundSessionRouteParams,
+) {
+  const parsed = parseDiscordTarget(params.target, {
+    defaultKind: resolveDiscordOutboundTargetKindHint(params),
+  });
+  if (!parsed) {
+    return null;
+  }
+  const isDm = parsed.kind === "user";
+  const peer: RoutePeer = {
+    kind: isDm ? "direct" : "channel",
+    id: parsed.id,
+  };
+  const baseSessionKey = buildOutboundBaseSessionKey({
+    cfg: params.cfg,
+    agentId: params.agentId,
+    channel: "discord",
+    accountId: params.accountId,
+    peer,
+  });
+  return buildThreadAwareOutboundSessionRoute({
+    route: {
+      sessionKey: baseSessionKey,
+      baseSessionKey,
+      peer,
+      chatType: isDm ? ("direct" as const) : ("channel" as const),
+      from: isDm ? `discord:${parsed.id}` : `discord:channel:${parsed.id}`,
+      to: isDm ? `user:${parsed.id}` : `channel:${parsed.id}`,
+    },
+    threadId: params.threadId,
+    precedence: ["threadId"],
+    useSuffix: false,
+  });
+}
+
+function resolveDiscordOutboundTargetKindHint(params: {
+  target: string;
+  resolvedTarget?: { kind: string };
+}): "user" | "channel" | undefined {
+  const resolvedKind = params.resolvedTarget?.kind;
+  if (resolvedKind === "user") {
+    return "user";
+  }
+  if (resolvedKind === "group" || resolvedKind === "channel") {
+    return "channel";
+  }
+
+  const target = params.target.trim();
+  if (/^channel:/i.test(target)) {
+    return "channel";
+  }
+  if (/^(user:|discord:|@|<@!?)/i.test(target)) {
+    return "user";
+  }
+  return undefined;
+}

package/src/pluralkit.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it, vi } from "vitest";
+import { fetchPluralKitMessageInfo } from "./pluralkit.js";
+
+type MockResponse = {
+  status: number;
+  ok: boolean;
+  text: () => Promise<string>;
+  json: () => Promise<unknown>;
+};
+
+const buildResponse = (params: { status: number; body?: unknown }): MockResponse => {
+  const body = params.body;
+  const textPayload = typeof body === "string" ? body : body == null ? "" : JSON.stringify(body);
+  return {
+    status: params.status,
+    ok: params.status >= 200 && params.status < 300,
+    text: async () => textPayload,
+    json: async () => body ?? {},
+  };
+};
+
+describe("fetchPluralKitMessageInfo", () => {
+  it("returns null when disabled", async () => {
+    const fetcher = vi.fn();
+    const result = await fetchPluralKitMessageInfo({
+      messageId: "123",
+      config: { enabled: false },
+      fetcher: fetcher as unknown as typeof fetch,
+    });
+    expect(result).toBeNull();
+    expect(fetcher).not.toHaveBeenCalled();
+  });
+
+  it("returns null on 404", async () => {
+    const fetcher = vi.fn(async () => buildResponse({ status: 404 }));
+    const result = await fetchPluralKitMessageInfo({
+      messageId: "missing",
+      config: { enabled: true },
+      fetcher: fetcher as unknown as typeof fetch,
+    });
+    expect(result).toBeNull();
+  });
+
+  it("returns payload and sends token when configured", async () => {
+    let receivedHeaders: Record<string, string> | undefined;
+    const fetcher = vi.fn(async (_url: string, init?: RequestInit) => {
+      receivedHeaders = init?.headers as Record<string, string> | undefined;
+      return buildResponse({
+        status: 200,
+        body: {
+          id: "123",
+          member: { id: "mem_1", name: "Alex" },
+          system: { id: "sys_1", name: "System" },
+        },
+      });
+    });
+
+    const result = await fetchPluralKitMessageInfo({
+      messageId: "123",
+      config: { enabled: true, token: "pk_test" },
+      fetcher: fetcher as unknown as typeof fetch,
+    });
+
+    expect(result?.member?.id).toBe("mem_1");
+    expect(receivedHeaders?.Authorization).toBe("pk_test");
+  });
+});

package/src/pluralkit.ts

@@ -0,0 +1,58 @@
+import { resolveFetch } from "openclaw/plugin-sdk/fetch-runtime";
+
+const PLURALKIT_API_BASE = "https://api.pluralkit.me/v2";
+
+export type DiscordPluralKitConfig = {
+  enabled?: boolean;
+  token?: string;
+};
+
+export type PluralKitSystemInfo = {
+  id: string;
+  name?: string | null;
+  tag?: string | null;
+};
+
+export type PluralKitMemberInfo = {
+  id: string;
+  name?: string | null;
+  display_name?: string | null;
+};
+
+export type PluralKitMessageInfo = {
+  id: string;
+  original?: string | null;
+  sender?: string | null;
+  system?: PluralKitSystemInfo | null;
+  member?: PluralKitMemberInfo | null;
+};
+
+export async function fetchPluralKitMessageInfo(params: {
+  messageId: string;
+  config?: DiscordPluralKitConfig;
+  fetcher?: typeof fetch;
+}): Promise<PluralKitMessageInfo | null> {
+  if (!params.config?.enabled) {
+    return null;
+  }
+  const fetchImpl = resolveFetch(params.fetcher);
+  if (!fetchImpl) {
+    return null;
+  }
+  const headers: Record<string, string> = {};
+  if (params.config.token?.trim()) {
+    headers.Authorization = params.config.token.trim();
+  }
+  const res = await fetchImpl(`${PLURALKIT_API_BASE}/messages/${params.messageId}`, {
+    headers,
+  });
+  if (res.status === 404) {
+    return null;
+  }
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    const detail = text.trim() ? `: ${text.trim()}` : "";
+    throw new Error(`PluralKit API failed (${res.status})${detail}`);
+  }
+  return (await res.json()) as PluralKitMessageInfo;
+}

package/src/preview-streaming.ts

@@ -0,0 +1,32 @@
+type DiscordPreviewStreamMode = "off" | "partial" | "block";
+
+function parsePreviewStreamingMode(value: unknown): DiscordPreviewStreamMode | undefined {
+  return value === "off" || value === "partial" || value === "block" ? value : undefined;
+}
+
+export function resolveDiscordPreviewStreamMode(
+  params: {
+    streamMode?: unknown;
+    streaming?: unknown;
+  } = {},
+): DiscordPreviewStreamMode {
+  const parsedStreaming =
+    params.streaming && typeof params.streaming === "object" && !Array.isArray(params.streaming)
+      ? parsePreviewStreamingMode(
+          (params.streaming as Record<string, unknown>).mode ??
+            (params.streaming as Record<string, unknown>).streaming,
+        )
+      : parsePreviewStreamingMode(params.streaming);
+  if (parsedStreaming) {
+    return parsedStreaming;
+  }
+
+  const legacy = parsePreviewStreamingMode(params.streamMode);
+  if (legacy) {
+    return legacy;
+  }
+  if (typeof params.streaming === "boolean") {
+    return params.streaming ? "partial" : "off";
+  }
+  return "off";
+}

package/src/probe.intents.test.ts

@@ -0,0 +1,94 @@
+import { withFetchPreconnect } from "openclaw/plugin-sdk/test-env";
+import { describe, expect, it } from "vitest";
+import {
+  fetchDiscordApplicationId,
+  fetchDiscordApplicationSummary,
+  resolveDiscordPrivilegedIntentsFromFlags,
+} from "./probe.js";
+import { jsonResponse } from "./test-http-helpers.js";
+
+describe("resolveDiscordPrivilegedIntentsFromFlags", () => {
+  it("reports disabled when no bits set", () => {
+    expect(resolveDiscordPrivilegedIntentsFromFlags(0)).toEqual({
+      presence: "disabled",
+      guildMembers: "disabled",
+      messageContent: "disabled",
+    });
+  });
+
+  it("reports enabled when full intent bits set", () => {
+    const flags = (1 << 12) | (1 << 14) | (1 << 18);
+    expect(resolveDiscordPrivilegedIntentsFromFlags(flags)).toEqual({
+      presence: "enabled",
+      guildMembers: "enabled",
+      messageContent: "enabled",
+    });
+  });
+
+  it("reports limited when limited intent bits set", () => {
+    const flags = (1 << 13) | (1 << 15) | (1 << 19);
+    expect(resolveDiscordPrivilegedIntentsFromFlags(flags)).toEqual({
+      presence: "limited",
+      guildMembers: "limited",
+      messageContent: "limited",
+    });
+  });
+
+  it("prefers enabled over limited when both set", () => {
+    const flags = (1 << 12) | (1 << 13) | (1 << 14) | (1 << 15) | (1 << 18) | (1 << 19);
+    expect(resolveDiscordPrivilegedIntentsFromFlags(flags)).toEqual({
+      presence: "enabled",
+      guildMembers: "enabled",
+      messageContent: "enabled",
+    });
+  });
+
+  it("retries Cloudflare HTML rate limits during application id lookup", async () => {
+    let calls = 0;
+    const fetcher = withFetchPreconnect(async () => {
+      calls += 1;
+      if (calls === 1) {
+        return new Response("<html><title>Error 1015</title></html>", {
+          status: 429,
+          headers: { "content-type": "text/html", "retry-after": "0" },
+        });
+      }
+      return jsonResponse({ id: "app-1" });
+    });
+
+    await expect(fetchDiscordApplicationId("unparseable.token", 1_000, fetcher)).resolves.toBe(
+      "app-1",
+    );
+    expect(calls).toBe(2);
+  });
+
+  it("does not retry Cloudflare HTML rate limits during application summary probes", async () => {
+    let calls = 0;
+    const fetcher = withFetchPreconnect(async () => {
+      calls += 1;
+      return new Response("<html><title>Error 1015</title></html>", {
+        status: 429,
+        headers: { "content-type": "text/html" },
+      });
+    });
+
+    await expect(
+      fetchDiscordApplicationSummary("unparseable.token", 1_000, fetcher),
+    ).resolves.toBeUndefined();
+    expect(calls).toBe(1);
+  });
+
+  it("derives application id from parseable tokens before probing REST", async () => {
+    let calls = 0;
+    const fetcher = withFetchPreconnect(async () => {
+      calls += 1;
+      return new Response("<html><title>Error 1015</title></html>", {
+        status: 429,
+        headers: { "content-type": "text/html" },
+      });
+    });
+
+    await expect(fetchDiscordApplicationId("MTIz.abc.def", 1_000, fetcher)).resolves.toBe("123");
+    expect(calls).toBe(0);
+  });
+});

package/src/probe.parse-token.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { parseApplicationIdFromToken } from "./probe.js";
+
+describe("parseApplicationIdFromToken", () => {
+  it("extracts application ID from a valid token", () => {
+    // "1234567890" base64-encoded is "MTIzNDU2Nzg5MA=="
+    const token = `${Buffer.from("1234567890").toString("base64")}.timestamp.hmac`;
+    expect(parseApplicationIdFromToken(token)).toBe("1234567890");
+  });
+
+  it("extracts large snowflake IDs without precision loss", () => {
+    // ID that exceeds Number.MAX_SAFE_INTEGER (2^53 - 1 = 9007199254740991)
+    const largeId = "1477179610322964541";
+    const token = `${Buffer.from(largeId).toString("base64")}.GhIiP9.vU1xEpJ6NjFm`;
+    expect(parseApplicationIdFromToken(token)).toBe(largeId);
+  });
+
+  it("handles tokens with Bot prefix", () => {
+    const token = `Bot ${Buffer.from("9876543210").toString("base64")}.ts.hmac`;
+    expect(parseApplicationIdFromToken(token)).toBe("9876543210");
+  });
+
+  it("returns undefined for empty string", () => {
+    expect(parseApplicationIdFromToken("")).toBeUndefined();
+  });
+
+  it("returns undefined for token without dots", () => {
+    expect(parseApplicationIdFromToken("nodots")).toBeUndefined();
+  });
+
+  it("returns undefined when decoded segment is not numeric", () => {
+    const token = `${Buffer.from("not-a-number").toString("base64")}.ts.hmac`;
+    expect(parseApplicationIdFromToken(token)).toBeUndefined();
+  });
+
+  it("returns undefined for whitespace-only input", () => {
+    expect(parseApplicationIdFromToken("   ")).toBeUndefined();
+  });
+
+  it("returns undefined when first segment is empty (starts with dot)", () => {
+    expect(parseApplicationIdFromToken(".ts.hmac")).toBeUndefined();
+  });
+});

package/src/probe.runtime.ts

@@ -0,0 +1 @@
+export * from "./probe.js";

package/src/probe.ts

@@ -0,0 +1,237 @@
+import type { BaseProbeResult } from "openclaw/plugin-sdk/channel-contract";
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
+import { resolveFetch } from "openclaw/plugin-sdk/fetch-runtime";
+import { fetchWithTimeout } from "openclaw/plugin-sdk/text-runtime";
+import { DiscordApiError, fetchDiscord } from "./api.js";
+import { normalizeDiscordToken } from "./token.js";
+
+const DISCORD_API_BASE = "https://discord.com/api/v10";
+
+export type DiscordProbe = BaseProbeResult & {
+  status?: number | null;
+  elapsedMs: number;
+  bot?: { id?: string | null; username?: string | null };
+  application?: DiscordApplicationSummary;
+};
+
+export type DiscordPrivilegedIntentStatus = "enabled" | "limited" | "disabled";
+
+export type DiscordPrivilegedIntentsSummary = {
+  messageContent: DiscordPrivilegedIntentStatus;
+  guildMembers: DiscordPrivilegedIntentStatus;
+  presence: DiscordPrivilegedIntentStatus;
+};
+
+export type DiscordApplicationSummary = {
+  id?: string | null;
+  flags?: number | null;
+  intents?: DiscordPrivilegedIntentsSummary;
+};
+
+const DISCORD_APP_FLAG_GATEWAY_PRESENCE = 1 << 12;
+const DISCORD_APP_FLAG_GATEWAY_PRESENCE_LIMITED = 1 << 13;
+const DISCORD_APP_FLAG_GATEWAY_GUILD_MEMBERS = 1 << 14;
+const DISCORD_APP_FLAG_GATEWAY_GUILD_MEMBERS_LIMITED = 1 << 15;
+const DISCORD_APP_FLAG_GATEWAY_MESSAGE_CONTENT = 1 << 18;
+const DISCORD_APP_FLAG_GATEWAY_MESSAGE_CONTENT_LIMITED = 1 << 19;
+
+async function fetchDiscordApplicationMe(
+  token: string,
+  timeoutMs: number,
+  fetcher: typeof fetch,
+): Promise<{ id?: string; flags?: number } | undefined> {
+  try {
+    const normalized = normalizeDiscordToken(token, "channels.discord.token");
+    if (!normalized) {
+      return undefined;
+    }
+    return await fetchDiscord<{ id?: string; flags?: number }>(
+      "/oauth2/applications/@me",
+      normalized,
+      createDiscordTimeoutFetch(fetcher, timeoutMs),
+      { retry: { attempts: 1 } },
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+function createDiscordTimeoutFetch(fetcher: typeof fetch, timeoutMs: number): typeof fetch {
+  const fetchImpl = getResolvedFetch(fetcher);
+  return ((input: RequestInfo | URL, init?: RequestInit) =>
+    fetchWithTimeout(
+      typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url,
+      init ?? {},
+      timeoutMs,
+      fetchImpl,
+    )) as typeof fetch;
+}
+
+export function resolveDiscordPrivilegedIntentsFromFlags(
+  flags: number,
+): DiscordPrivilegedIntentsSummary {
+  const resolve = (enabledBit: number, limitedBit: number) => {
+    if ((flags & enabledBit) !== 0) {
+      return "enabled";
+    }
+    if ((flags & limitedBit) !== 0) {
+      return "limited";
+    }
+    return "disabled";
+  };
+  return {
+    presence: resolve(DISCORD_APP_FLAG_GATEWAY_PRESENCE, DISCORD_APP_FLAG_GATEWAY_PRESENCE_LIMITED),
+    guildMembers: resolve(
+      DISCORD_APP_FLAG_GATEWAY_GUILD_MEMBERS,
+      DISCORD_APP_FLAG_GATEWAY_GUILD_MEMBERS_LIMITED,
+    ),
+    messageContent: resolve(
+      DISCORD_APP_FLAG_GATEWAY_MESSAGE_CONTENT,
+      DISCORD_APP_FLAG_GATEWAY_MESSAGE_CONTENT_LIMITED,
+    ),
+  };
+}
+
+export async function fetchDiscordApplicationSummary(
+  token: string,
+  timeoutMs: number,
+  fetcher: typeof fetch = fetch,
+): Promise<DiscordApplicationSummary | undefined> {
+  const json = await fetchDiscordApplicationMe(token, timeoutMs, fetcher);
+  if (!json) {
+    return undefined;
+  }
+  const flags =
+    typeof json.flags === "number" && Number.isFinite(json.flags) ? json.flags : undefined;
+  return {
+    id: json.id ?? null,
+    flags: flags ?? null,
+    intents:
+      typeof flags === "number" ? resolveDiscordPrivilegedIntentsFromFlags(flags) : undefined,
+  };
+}
+
+function getResolvedFetch(fetcher: typeof fetch): typeof fetch {
+  const fetchImpl = resolveFetch(fetcher);
+  if (!fetchImpl) {
+    throw new Error("fetch is not available");
+  }
+  return fetchImpl;
+}
+
+export async function probeDiscord(
+  token: string,
+  timeoutMs: number,
+  opts?: { fetcher?: typeof fetch; includeApplication?: boolean },
+): Promise<DiscordProbe> {
+  const started = Date.now();
+  const fetcher = opts?.fetcher ?? fetch;
+  const includeApplication = opts?.includeApplication === true;
+  const normalized = normalizeDiscordToken(token, "channels.discord.token");
+  const result: DiscordProbe = {
+    ok: false,
+    status: null,
+    error: null,
+    elapsedMs: 0,
+  };
+  if (!normalized) {
+    return {
+      ...result,
+      error: "missing token",
+      elapsedMs: Date.now() - started,
+    };
+  }
+  try {
+    const res = await fetchWithTimeout(
+      `${DISCORD_API_BASE}/users/@me`,
+      { headers: { Authorization: `Bot ${normalized}` } },
+      timeoutMs,
+      getResolvedFetch(fetcher),
+    );
+    if (!res.ok) {
+      result.status = res.status;
+      result.error = `getMe failed (${res.status})`;
+      return { ...result, elapsedMs: Date.now() - started };
+    }
+    const json = (await res.json()) as { id?: string; username?: string };
+    result.ok = true;
+    result.bot = {
+      id: json.id ?? null,
+      username: json.username ?? null,
+    };
+    if (includeApplication) {
+      result.application =
+        (await fetchDiscordApplicationSummary(normalized, timeoutMs, fetcher)) ?? undefined;
+    }
+    return { ...result, elapsedMs: Date.now() - started };
+  } catch (err) {
+    return {
+      ...result,
+      status: err instanceof Response ? err.status : result.status,
+      error: formatErrorMessage(err),
+      elapsedMs: Date.now() - started,
+    };
+  }
+}
+
+/**
+ * Extract the application (bot user) ID from a Discord bot token by
+ * base64-decoding the first segment.  Discord tokens have the format:
+ *   base64(user_id) . timestamp . hmac
+ * The decoded first segment is the numeric snowflake ID as a plain string,
+ * so we keep it as a string to avoid precision loss for IDs that exceed
+ * Number.MAX_SAFE_INTEGER.
+ */
+export function parseApplicationIdFromToken(token: string): string | undefined {
+  const normalized = normalizeDiscordToken(token, "channels.discord.token");
+  if (!normalized) {
+    return undefined;
+  }
+  const firstDot = normalized.indexOf(".");
+  if (firstDot <= 0) {
+    return undefined;
+  }
+  try {
+    const decoded = Buffer.from(normalized.slice(0, firstDot), "base64").toString("utf-8");
+    if (/^\d+$/.test(decoded)) {
+      return decoded;
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function fetchDiscordApplicationId(
+  token: string,
+  timeoutMs: number,
+  fetcher: typeof fetch = fetch,
+): Promise<string | undefined> {
+  const normalized = normalizeDiscordToken(token, "channels.discord.token");
+  if (!normalized) {
+    return undefined;
+  }
+  const parsedApplicationId = parseApplicationIdFromToken(token);
+  if (parsedApplicationId) {
+    return parsedApplicationId;
+  }
+  try {
+    const json = await fetchDiscord<{ id?: string }>(
+      "/oauth2/applications/@me",
+      normalized,
+      createDiscordTimeoutFetch(fetcher, timeoutMs),
+    );
+    if (json?.id) {
+      return json.id;
+    }
+    return undefined;
+  } catch (error) {
+    if (error instanceof DiscordApiError) {
+      if (error.status === 429) {
+        throw error;
+      }
+      return undefined;
+    }
+    return undefined;
+  }
+}

package/src/proxy-fetch.ts

@@ -0,0 +1,92 @@
+import { isIP } from "node:net";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { makeProxyFetch } from "openclaw/plugin-sdk/fetch-runtime";
+import { danger } from "openclaw/plugin-sdk/runtime-env";
+import type { RuntimeEnv } from "openclaw/plugin-sdk/runtime-env";
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
+import type { ResolvedDiscordAccount } from "./accounts.js";
+
+function resolveDiscordProxyUrl(
+  account: Pick<ResolvedDiscordAccount, "config">,
+  cfg: OpenClawConfig,
+): string | undefined {
+  const accountProxy = account.config.proxy?.trim();
+  if (accountProxy) {
+    return accountProxy;
+  }
+  const channelProxy = cfg?.channels?.discord?.proxy;
+  if (typeof channelProxy !== "string") {
+    return undefined;
+  }
+  const trimmed = channelProxy.trim();
+  return trimmed || undefined;
+}
+
+function resolveDiscordProxyFetchByUrl(
+  proxyUrl: string | undefined,
+  runtime?: Pick<RuntimeEnv, "error">,
+): typeof fetch | undefined {
+  return withValidatedDiscordProxy(proxyUrl, runtime, (proxy) => makeProxyFetch(proxy));
+}
+
+export function resolveDiscordProxyFetchForAccount(
+  account: Pick<ResolvedDiscordAccount, "config">,
+  cfg: OpenClawConfig,
+  runtime?: Pick<RuntimeEnv, "error">,
+): typeof fetch | undefined {
+  return resolveDiscordProxyFetchByUrl(resolveDiscordProxyUrl(account, cfg), runtime);
+}
+
+export function withValidatedDiscordProxy<T>(
+  proxyUrl: string | undefined,
+  runtime: Pick<RuntimeEnv, "error"> | undefined,
+  createValue: (proxyUrl: string) => T,
+): T | undefined {
+  const proxy = proxyUrl?.trim();
+  if (!proxy) {
+    return undefined;
+  }
+  try {
+    validateDiscordProxyUrl(proxy);
+    return createValue(proxy);
+  } catch (err) {
+    runtime?.error?.(danger(`discord: invalid rest proxy: ${String(err)}`));
+    return undefined;
+  }
+}
+
+export function validateDiscordProxyUrl(proxyUrl: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(proxyUrl);
+  } catch {
+    throw new Error("Proxy URL must be a valid http or https URL");
+  }
+  if (!["http:", "https:"].includes(parsed.protocol)) {
+    throw new Error("Proxy URL must use http or https");
+  }
+  if (!isLoopbackProxyHostname(parsed.hostname)) {
+    throw new Error("Proxy URL must target a loopback host");
+  }
+  return proxyUrl;
+}
+
+function isLoopbackProxyHostname(hostname: string): boolean {
+  const normalized = normalizeLowercaseStringOrEmpty(hostname);
+  if (!normalized) {
+    return false;
+  }
+  const bracketless =
+    normalized.startsWith("[") && normalized.endsWith("]") ? normalized.slice(1, -1) : normalized;
+  if (bracketless === "localhost") {
+    return true;
+  }
+  const ipFamily = isIP(bracketless);
+  if (ipFamily === 4) {
+    return bracketless.startsWith("127.");
+  }
+  if (ipFamily === 6) {
+    return bracketless === "::1" || bracketless === "0:0:0:0:0:0:0:1";
+  }
+  return false;
+}