@oneuptime/common 14.0.7 → 14.0.8

package/Tests/Server/Utils/DataSource/EgressGuard.test.ts

@@ -1,6 +1,5 @@
 import dns from "dns";
 import { afterEach, beforeEach, describe, expect, test } from "@jest/globals";
-import { IsBillingEnabled } from "../../../../Server/EnvironmentConfig";
 import DataSourceEgressGuard, {
   AddressVerdict,
   DEFAULT_DNS_RESOLVE_ATTEMPTS,
@@ -17,12 +16,22 @@ import EgressGuardException, {
 } from "../../../../Types/Exception/EgressGuardException";
 
 const ENV_VAR_NAME: string = "DATA_SOURCE_BLOCK_PRIVATE_ADDRESSES";
+const BILLING_ENV_VAR_NAME: string = "BILLING_ENABLED";
 
 let savedEnvValue: string | undefined = undefined;
+let savedBillingValue: string | undefined = undefined;
 
+/*
+ * Every test starts on a self-hosted install. Both variables decide how much a
+ * refusal is allowed to say, and CI exports BILLING_ENABLED=true, so a test
+ * that inherited the environment would assert a different contract there than
+ * on a laptop. Tests about SaaS set BILLING_ENABLED themselves.
+ */
 beforeEach(() => {
   savedEnvValue = process.env[ENV_VAR_NAME];
+  savedBillingValue = process.env[BILLING_ENV_VAR_NAME];
   delete process.env[ENV_VAR_NAME];
+  delete process.env[BILLING_ENV_VAR_NAME];
 });
 
 afterEach(() => {
@@ -31,6 +40,11 @@ afterEach(() => {
   } else {
     process.env[ENV_VAR_NAME] = savedEnvValue;
   }
+  if (savedBillingValue === undefined) {
+    delete process.env[BILLING_ENV_VAR_NAME];
+  } else {
+    process.env[BILLING_ENV_VAR_NAME] = savedBillingValue;
+  }
   jest.restoreAllMocks();
 });
 
@@ -905,6 +919,33 @@ describe("DataSourceEgressGuard.assertHostnameAllowed - numeric hostname encodin
   }
 });
 
+describe("DataSourceEgressGuard.shouldIncludeResolutionDetail", () => {
+  test("defaults to detail on a self-hosted install", () => {
+    expect(DataSourceEgressGuard.shouldIncludeResolutionDetail()).toBe(true);
+  });
+
+  test("defaults to no detail on SaaS", () => {
+    process.env[BILLING_ENV_VAR_NAME] = "true";
+    expect(DataSourceEgressGuard.shouldIncludeResolutionDetail()).toBe(false);
+  });
+
+  test("defaults to no detail once an operator forces SaaS policy", () => {
+    process.env[ENV_VAR_NAME] = "true";
+    expect(DataSourceEgressGuard.shouldIncludeResolutionDetail()).toBe(false);
+  });
+
+  test("an explicit value wins in either deployment", () => {
+    expect(DataSourceEgressGuard.shouldIncludeResolutionDetail(false)).toBe(
+      false,
+    );
+
+    process.env[BILLING_ENV_VAR_NAME] = "true";
+    expect(DataSourceEgressGuard.shouldIncludeResolutionDetail(true)).toBe(
+      true,
+    );
+  });
+});
+
 describe("DataSourceEgressGuard.shouldBlockPrivateAddresses", () => {
   test("returns true when DATA_SOURCE_BLOCK_PRIVATE_ADDRESSES=true", () => {
     process.env[ENV_VAR_NAME] = "true";
@@ -913,16 +954,18 @@ describe("DataSourceEgressGuard.shouldBlockPrivateAddresses", () => {
 
   test("falls back to the billing flag when the env var is unset", () => {
     delete process.env[ENV_VAR_NAME];
-    expect(DataSourceEgressGuard.shouldBlockPrivateAddresses()).toBe(
-      IsBillingEnabled,
-    );
+    expect(DataSourceEgressGuard.shouldBlockPrivateAddresses()).toBe(false);
+
+    process.env[BILLING_ENV_VAR_NAME] = "true";
+    expect(DataSourceEgressGuard.shouldBlockPrivateAddresses()).toBe(true);
   });
 
   test("treats any value other than 'true' as unset", () => {
     process.env[ENV_VAR_NAME] = "false";
-    expect(DataSourceEgressGuard.shouldBlockPrivateAddresses()).toBe(
-      IsBillingEnabled,
-    );
+    expect(DataSourceEgressGuard.shouldBlockPrivateAddresses()).toBe(false);
+
+    process.env[BILLING_ENV_VAR_NAME] = "true";
+    expect(DataSourceEgressGuard.shouldBlockPrivateAddresses()).toBe(true);
   });
 
   test("checkAddress derives the policy from the env var when options omit the flag", () => {
@@ -1174,7 +1217,7 @@ describe("DataSourceEgressGuard - typed failure reasons", () => {
   );
 
   test.each([undefined, true])(
-    "a resolver rejection is ResolutionFailed when includeResolvedAddressInError is %s",
+    "a resolver rejection is ResolutionFailed on a self-hosted install when includeResolvedAddressInError is %s",
     async (includeResolvedAddressInError: boolean | undefined) => {
       const error: Error = await captureRejection(
         DataSourceEgressGuard.assertHostnameAllowed("missing.example.com", {
@@ -1195,7 +1238,7 @@ describe("DataSourceEgressGuard - typed failure reasons", () => {
   );
 
   test.each([undefined, true])(
-    "an empty DNS answer is ResolutionFailed when includeResolvedAddressInError is %s",
+    "an empty DNS answer is ResolutionFailed on a self-hosted install when includeResolvedAddressInError is %s",
     async (includeResolvedAddressInError: boolean | undefined) => {
       const resolver: Resolver = makeResolver([]);
       const error: Error = await captureRejection(
@@ -1217,7 +1260,7 @@ describe("DataSourceEgressGuard - typed failure reasons", () => {
   );
 
   test.each([undefined, true])(
-    "a blocked resolved address is AddressBlocked when includeResolvedAddressInError is %s",
+    "a blocked resolved address is AddressBlocked on a self-hosted install when includeResolvedAddressInError is %s",
     async (includeResolvedAddressInError: boolean | undefined) => {
       const resolver: Resolver = makeResolver([
         { address: "10.23.45.67", family: 4 },
@@ -1542,6 +1585,199 @@ describe("DataSourceEgressGuard - the sanitized failure is one indistinguishable
       expect(line).toContain(ORACLE_HOSTNAME);
     }
   });
+
+  /*
+   * Most callers never set includeResolvedAddressInError: the workflow Send
+   * Email step, a project's SMTP server, OAuth token URLs, LLM providers,
+   * data sources, Runbook HTTP steps. Each echoes the guard's message to
+   * project members, so on OneUptime Cloud the default itself has to be the
+   * sanitized path — a member typing `redis` or
+   * `kubernetes.default.svc.cluster.local` into any of those fields must not
+   * learn whether the name exists or what it points at.
+   */
+  describe("when the caller leaves includeResolvedAddressInError unset", () => {
+    const callerOptions: EgressGuardOptions = { targetLabel: "SMTP server" };
+
+    const resolverReturnsLoopback: EgressResolveFunction = makeResolver([
+      { address: "127.0.0.1", family: 4 },
+    ]).resolveFunction;
+
+    test.each([
+      ["on SaaS (BILLING_ENABLED=true)", BILLING_ENV_VAR_NAME],
+      [
+        "once an operator forces SaaS policy (DATA_SOURCE_BLOCK_PRIVATE_ADDRESSES=true)",
+        ENV_VAR_NAME,
+      ],
+    ])(
+      "%s a DNS failure and a blocked resolution are indistinguishable",
+      async (_deployment: string, envVarName: string) => {
+        process.env[envVarName] = "true";
+
+        const errors: Array<Error> = [
+          await failWith(resolverRejects, callerOptions),
+          await failWith(resolverReturnsNothing, callerOptions),
+          await failWith(resolverReturnsPrivateAddress, callerOptions),
+          await failWith(resolverReturnsLoopback, callerOptions),
+        ];
+
+        const expectedFingerprint: EgressFailureFingerprint = fingerprint(
+          errors[0]!,
+        );
+        expect(expectedFingerprint.message).toBe(
+          `SMTP server host ${ORACLE_HOSTNAME} could not be reached.`,
+        );
+        expect(expectedFingerprint.reason).toBe(
+          EgressFailureReason.Unreachable,
+        );
+
+        for (const error of errors) {
+          expect(fingerprint(error)).toEqual(expectedFingerprint);
+          expect(Object.keys(error).sort()).toEqual(["_code", "reason"]);
+          expect(JSON.stringify(error)).not.toContain(SECRET_ADDRESS);
+          expect(error.message).not.toContain("127.0.0.1");
+          expect(error.message).not.toContain("ENOTFOUND");
+        }
+      },
+    );
+
+    test("on SaaS the URL entry points are sanitized too", async () => {
+      /*
+       * LLM providers, OAuth token URLs, Runbook HTTP steps and domain
+       * verification come in through the URL forms, not the hostname one.
+       */
+      process.env[BILLING_ENV_VAR_NAME] = "true";
+
+      const missingError: Error = await captureRejection(
+        DataSourceEgressGuard.assertUrlAllowedAndPin(
+          `https://${ORACLE_HOSTNAME}/v1/chat/completions`,
+          { targetLabel: "LLM provider", resolveFunction: resolverRejects },
+        ),
+      );
+      const internalError: Error = await captureRejection(
+        DataSourceEgressGuard.assertUrlAllowed(
+          `https://${ORACLE_HOSTNAME}/token`,
+          {
+            targetLabel: "LLM provider",
+            resolveFunction: resolverReturnsPrivateAddress,
+          },
+        ),
+      );
+
+      expect(fingerprint(internalError)).toEqual(fingerprint(missingError));
+      expect(missingError.message).toBe(
+        `LLM provider host ${ORACLE_HOSTNAME} could not be reached.`,
+      );
+    });
+
+    test("on SaaS a caller that loosens blockPrivateAddresses still gets no detail", async () => {
+      /*
+       * The default follows the deployment, not the per-call address policy:
+       * who typed the target is what makes the detail an oracle.
+       */
+      process.env[BILLING_ENV_VAR_NAME] = "true";
+      const loosenedOptions: EgressGuardOptions = {
+        ...callerOptions,
+        blockPrivateAddresses: false,
+      };
+
+      const missingError: Error = await failWith(
+        resolverRejects,
+        loosenedOptions,
+      );
+      const loopbackError: Error = await failWith(
+        resolverReturnsLoopback,
+        loosenedOptions,
+      );
+
+      expect(fingerprint(loopbackError)).toEqual(fingerprint(missingError));
+      expect(loopbackError.message).toBe(
+        `SMTP server host ${ORACLE_HOSTNAME} could not be reached.`,
+      );
+    });
+
+    test("on SaaS an explicit true still gets the detail", async () => {
+      process.env[BILLING_ENV_VAR_NAME] = "true";
+      const detailedOptions: EgressGuardOptions = {
+        ...callerOptions,
+        includeResolvedAddressInError: true,
+      };
+
+      const missingError: Error = await failWith(
+        resolverRejects,
+        detailedOptions,
+      );
+      const internalError: Error = await failWith(
+        resolverReturnsPrivateAddress,
+        detailedOptions,
+      );
+
+      expectEgressFailure(missingError, EgressFailureReason.ResolutionFailed);
+      expectEgressFailure(internalError, EgressFailureReason.AddressBlocked);
+      expect(internalError.message).toBe(
+        `SMTP server host ${ORACLE_HOSTNAME} resolves to ${SECRET_ADDRESS}, which is not allowed: private network address.`,
+      );
+    });
+
+    test("on SaaS a literal IP is still refused with its reason", async () => {
+      // It restates what the member typed and reveals nothing about DNS.
+      process.env[BILLING_ENV_VAR_NAME] = "true";
+
+      const error: Error = await captureRejection(
+        DataSourceEgressGuard.assertHostnameAllowed(SECRET_ADDRESS, {
+          ...callerOptions,
+        }),
+      );
+
+      expectEgressFailure(error, EgressFailureReason.AddressBlocked);
+      expect(error.message).toBe(
+        `SMTP server host ${SECRET_ADDRESS} is not allowed: private network address.`,
+      );
+    });
+
+    test("on SaaS the operator still gets the precise cause in the debug log", async () => {
+      process.env[BILLING_ENV_VAR_NAME] = "true";
+      const debugSpy: jest.SpyInstance = jest
+        .spyOn(logger, "debug")
+        .mockImplementation((): void => {
+          // Swallow the output; only the call itself is under test.
+        });
+
+      await failWith(resolverRejects, callerOptions);
+      await failWith(resolverReturnsNothing, callerOptions);
+      await failWith(resolverReturnsPrivateAddress, callerOptions);
+
+      const loggedLines: Array<string> = debugSpy.mock.calls.map(
+        (call: Array<unknown>) => {
+          return String(call[0]);
+        },
+      );
+
+      expect(loggedLines).toHaveLength(3);
+      expect(loggedLines[0]).toContain("ENOTFOUND");
+      expect(loggedLines[1]).toContain("no addresses");
+      expect(loggedLines[2]).toContain(SECRET_ADDRESS);
+      expect(loggedLines[2]).toContain("private network address");
+    });
+
+    test("a self-hosted install keeps the operator-friendly detail", async () => {
+      // Private ranges are reachable here, so loopback is the refused case.
+      const missingError: Error = await failWith(
+        resolverRejects,
+        callerOptions,
+      );
+      const loopbackError: Error = await failWith(
+        resolverReturnsLoopback,
+        callerOptions,
+      );
+
+      expect(missingError.message).toBe(
+        `Could not resolve smtp server host ${ORACLE_HOSTNAME}: getaddrinfo ENOTFOUND ${ORACLE_HOSTNAME} ${SECRET_ADDRESS}`,
+      );
+      expect(loopbackError.message).toBe(
+        `SMTP server host ${ORACLE_HOSTNAME} resolves to 127.0.0.1, which is not allowed: loopback address.`,
+      );
+    });
+  });
 });
 
 /*

package/Tests/Server/Utils/DataSource/EgressGuardDeploymentConfig.test.ts

@@ -0,0 +1,226 @@
+import { afterEach, beforeEach, describe, expect, test } from "@jest/globals";
+import fs from "fs";
+import path from "path";
+import yaml from "js-yaml";
+import DataSourceEgressGuard, {
+  ResolvedAddress,
+} from "../../../../Server/Utils/DataSource/EgressGuard";
+
+/*
+ * DATA_SOURCE_BLOCK_PRIVATE_ADDRESSES lets a self-hosted operator make the
+ * egress guard refuse private ranges for data sources, LLM providers, SMTP,
+ * OAuth token URLs, OIDC discovery and runbook HTTP steps. The guard has read
+ * it for a long time, and the docs told operators to set it, but Docker
+ * Compose never passed it to the app container and config.example.env had no
+ * line for it -- so setting it in config.env did nothing.
+ *
+ * This pins the Compose half of the wiring (the Helm half is covered by
+ * HelmChart/Public/oneuptime/tests/outbound-connections-egress_test.yaml) and
+ * ties it to the name the guard actually reads, by feeding the interpolated
+ * value to the real guard rather than comparing strings.
+ */
+
+const ENV_VAR_NAME: string = "DATA_SOURCE_BLOCK_PRIVATE_ADDRESSES";
+// The webhook half of the egress policy, already wired end to end.
+const SIBLING_ENV_VAR_NAME: string = "ALLOW_PRIVATE_NETWORK_WEBHOOKS";
+
+const REPO_ROOT: string = path.resolve(__dirname, "../../../../../..");
+const COMPOSE_PATH: string = path.join(REPO_ROOT, "docker-compose.base.yml");
+const EXAMPLE_ENV_PATH: string = path.join(REPO_ROOT, "config.example.env");
+
+type ComposeEnvironment = Record<string, string | number | boolean | null>;
+
+interface ComposeService {
+  environment?: ComposeEnvironment;
+}
+
+interface ComposeConfig {
+  "x-common-variables": ComposeEnvironment;
+  services: Record<string, ComposeService>;
+}
+
+// js-yaml resolves the `<<: *anchor` merge keys, as Compose does.
+const loadCompose: () => ComposeConfig = (): ComposeConfig => {
+  return yaml.load(fs.readFileSync(COMPOSE_PATH, "utf8")) as ComposeConfig;
+};
+
+const exampleEnvLines: (name: string) => Array<string> = (
+  name: string,
+): Array<string> => {
+  const source: string = fs.readFileSync(EXAMPLE_ENV_PATH, "utf8");
+  return source.split("\n").filter((line: string) => {
+    return line.startsWith(`${name}=`);
+  });
+};
+
+/*
+ * Resolve a Compose `${NAME:-default}` reference the way Compose does: the
+ * default applies when the variable is unset OR empty. config.env is exported
+ * into the shell before `docker compose up`, so `shellEnv` stands in for it.
+ */
+const interpolate: (
+  reference: string,
+  shellEnv: Record<string, string | undefined>,
+) => string = (
+  reference: string,
+  shellEnv: Record<string, string | undefined>,
+): string => {
+  const match: RegExpMatchArray | null = reference.match(
+    /^\$\{([A-Z0-9_]+):-(.*)\}$/,
+  );
+  if (!match) {
+    throw new Error(`Not a defaulted Compose reference: ${reference}`);
+  }
+  const value: string | undefined = shellEnv[match[1]!];
+  return value ? value : match[2]!;
+};
+
+const appReference: () => string = (): string => {
+  const reference: unknown =
+    loadCompose().services["app"]?.environment?.[ENV_VAR_NAME];
+  expect(typeof reference).toBe("string");
+  return reference as string;
+};
+
+describe("DATA_SOURCE_BLOCK_PRIVATE_ADDRESSES deployment wiring", () => {
+  let savedValue: string | undefined = undefined;
+  let savedBilling: string | undefined = undefined;
+
+  beforeEach(() => {
+    savedValue = process.env[ENV_VAR_NAME];
+    savedBilling = process.env["BILLING_ENABLED"];
+  });
+
+  afterEach(() => {
+    for (const [name, saved] of [
+      [ENV_VAR_NAME, savedValue],
+      ["BILLING_ENABLED", savedBilling],
+    ] as Array<[string, string | undefined]>) {
+      if (saved === undefined) {
+        delete process.env[name];
+      } else {
+        process.env[name] = saved;
+      }
+    }
+  });
+
+  test("Docker Compose passes it in the shared environment, defaulted off", () => {
+    expect(loadCompose()["x-common-variables"][ENV_VAR_NAME]).toBe(
+      `\${${ENV_VAR_NAME}:-false}`,
+    );
+  });
+
+  /*
+   * The app container runs the API, the queue workers, workflows and the
+   * notification (SMTP) code, which is every server-side caller of the guard.
+   */
+  test("the app container receives it", () => {
+    expect(appReference()).toBe(`\${${ENV_VAR_NAME}:-false}`);
+  });
+
+  test("every Compose service that gets the webhook policy gets this one too", () => {
+    const services: Record<string, ComposeService> = loadCompose().services;
+    const withWebhookPolicy: Array<string> = Object.keys(services).filter(
+      (name: string) => {
+        return (
+          services[name]?.environment?.[SIBLING_ENV_VAR_NAME] !== undefined
+        );
+      },
+    );
+
+    expect(withWebhookPolicy).toContain("app");
+    for (const name of withWebhookPolicy) {
+      expect({
+        service: name,
+        value: services[name]?.environment?.[ENV_VAR_NAME],
+      }).toEqual({ service: name, value: `\${${ENV_VAR_NAME}:-false}` });
+    }
+  });
+
+  /*
+   * One line, so an operator flips it instead of appending a second one (the
+   * later line would win), and MergeEnvTemplate adds it to an existing
+   * config.env on upgrade.
+   */
+  test("config.example.env ships exactly one line, set to false", () => {
+    expect(exampleEnvLines(ENV_VAR_NAME)).toEqual([`${ENV_VAR_NAME}=false`]);
+  });
+
+  test("a self-hosted install keeps private ranges reachable with the shipped line", () => {
+    const shipped: string = exampleEnvLines(ENV_VAR_NAME)[0]!.split("=")[1]!;
+    process.env["BILLING_ENABLED"] = "false";
+    process.env[ENV_VAR_NAME] = interpolate(appReference(), {
+      [ENV_VAR_NAME]: shipped,
+    });
+
+    expect(DataSourceEgressGuard.shouldBlockPrivateAddresses()).toBe(false);
+  });
+
+  test("a config.env written before the line existed keeps private ranges reachable", () => {
+    process.env["BILLING_ENABLED"] = "false";
+    process.env[ENV_VAR_NAME] = interpolate(appReference(), {});
+
+    expect(process.env[ENV_VAR_NAME]).toBe("false");
+    expect(DataSourceEgressGuard.shouldBlockPrivateAddresses()).toBe(false);
+  });
+
+  // The regression itself: the operator's value has to reach the guard.
+  test("setting it to true in config.env makes the guard block private ranges", () => {
+    process.env["BILLING_ENABLED"] = "false";
+    process.env[ENV_VAR_NAME] = interpolate(appReference(), {
+      [ENV_VAR_NAME]: "true",
+    });
+
+    expect(DataSourceEgressGuard.shouldBlockPrivateAddresses()).toBe(true);
+    expect(DataSourceEgressGuard.checkAddress("10.0.0.5").blocked).toBe(true);
+  });
+
+  /*
+   * The self-hosted docs quote the refusal an operator sees once the switch is
+   * on, so they can match it against a log. Produce it with the real guard,
+   * the way LLMService calls it, rather than trusting the copy.
+   */
+  test("the docs quote the refusal the guard actually reports", async () => {
+    const docs: string = fs.readFileSync(
+      path.join(
+        REPO_ROOT,
+        "packages/App/FeatureSet/Docs/Content/en/self-hosted/private-network-access.md",
+      ),
+      "utf8",
+    );
+    // The refused name first, then the same address typed as an IP.
+    const quotes: Array<string> = Array.from(
+      docs.matchAll(/_"(LLM provider host [^"]+)"_/g),
+      (match: RegExpMatchArray) => {
+        return match[1]!;
+      },
+    );
+    expect(quotes).toHaveLength(2);
+
+    process.env["BILLING_ENABLED"] = "false";
+    process.env[ENV_VAR_NAME] = "true";
+
+    const refusalFor: (url: string) => Promise<string> = async (
+      url: string,
+    ): Promise<string> => {
+      try {
+        await DataSourceEgressGuard.assertUrlAllowedAndPin(url, {
+          targetLabel: "LLM provider",
+          resolveFunction: async (): Promise<Array<ResolvedAddress>> => {
+            return [{ address: "10.0.4.12", family: 4 }];
+          },
+        });
+      } catch (err) {
+        return (err as Error).message;
+      }
+      return "";
+    };
+
+    expect(
+      await refusalFor("http://ollama.internal:11434/v1/chat/completions"),
+    ).toBe(quotes[0]);
+    expect(await refusalFor("http://10.0.4.12:11434/v1/chat/completions")).toBe(
+      quotes[1],
+    );
+  });
+});

package/Tests/Server/Utils/DataSource/EgressGuardPinning.test.ts

@@ -6,6 +6,9 @@ import DataSourceEgressGuard, {
 } from "../../../../Server/Utils/DataSource/EgressGuard";
 import BadDataException from "../../../../Types/Exception/BadDataException";
 import { describe, expect, test } from "@jest/globals";
+import { ClientRequest } from "http";
+import https from "https";
+import { startEachTestOnSelfHostedEgressPolicy } from "../EgressPolicyEnvironment";
 
 /*
  * The egress guard is only half a control on its own: validating an address
@@ -61,6 +64,9 @@ const callLookup: CallLookup = (
   });
 };
 
+// Detailed refusals are asserted throughout; SaaS behaviour is tested apart.
+startEachTestOnSelfHostedEgressPolicy();
+
 describe("DataSourceEgressGuard.createPinnedLookup", () => {
   const addresses: Array<ResolvedAddress> = [
     { address: "93.184.216.34", family: 4 },
@@ -113,6 +119,131 @@ describe("DataSourceEgressGuard.createPinnedLookup", () => {
 
     expect(result.address).toBe("93.184.216.34");
   });
+
+  /*
+   * dns.lookup never calls back synchronously, and Node's net/tls connect
+   * relies on that. See the regression test below for what broke.
+   */
+  test.each([
+    ["every address", { all: true }],
+    ["the first address", { all: false }],
+    ["no address of the wanted family", { family: 6 as number }],
+  ])(
+    "answers asynchronously with %s",
+    async (
+      _label: string,
+      options: { all?: boolean | undefined; family?: number | undefined },
+    ) => {
+      const lookup: EgressLookupFunction =
+        DataSourceEgressGuard.createPinnedLookup([
+          { address: "93.184.216.34", family: 4 },
+        ]);
+      let hasAnswered: boolean = false;
+
+      const answered: Promise<LookupResult> = new Promise(
+        (resolve: (value: LookupResult) => void) => {
+          lookup(
+            "anything.example",
+            options,
+            (
+              error: NodeJS.ErrnoException | null,
+              address: string | Array<{ address: string; family: number }>,
+              family?: number,
+            ) => {
+              hasAnswered = true;
+              resolve({ error, address, family });
+            },
+          );
+        },
+      );
+
+      expect(hasAnswered).toBe(false);
+
+      const result: LookupResult = await answered;
+
+      expect(hasAnswered).toBe(true);
+      if (options.family === 6) {
+        expect(result.error?.code).toBe("ENOTFOUND");
+      } else {
+        expect(result.error).toBeNull();
+      }
+    },
+  );
+});
+
+/*
+ * REGRESSION: an HTTPS request through a pinned agent whose every address
+ * fails at connect() time. That is what a probe with no IPv6 gets for an
+ * IPv6-only hostname (EADDRNOTAVAIL/ENETUNREACH from connect() itself), and
+ * with a lookup that answered synchronously Node destroyed the TLSSocket
+ * before tls.connect called setServername on it: https.get threw
+ * "Cannot read properties of null (reading 'setServername')", which the
+ * monitor reported instead of the real error, and the real error escaped as
+ * an unhandled 'error' event on the socket.
+ *
+ * connect() to the broadcast address fails the same way, locally and with no
+ * packet sent (EAFNOSUPPORT on macOS, ENETUNREACH on Linux).
+ */
+describe("DataSourceEgressGuard.createPinnedLookup through an https agent", () => {
+  test("a connect that fails on every pinned address rejects cleanly instead of throwing", async () => {
+    const uncaught: Array<unknown> = [];
+    const onUncaught: (error: unknown) => void = (error: unknown): void => {
+      uncaught.push(error);
+    };
+
+    process.on("uncaughtException", onUncaught);
+
+    try {
+      const agent: https.Agent = new https.Agent({
+        lookup: DataSourceEgressGuard.createPinnedLookup([
+          { address: "255.255.255.255", family: 4 },
+        ]) as never,
+      });
+
+      const requestError: Error = await new Promise(
+        (resolve: (error: Error) => void, reject: (error: Error) => void) => {
+          let request: ClientRequest;
+
+          try {
+            request = https.get("https://pinned.example/", {
+              agent: agent,
+              timeout: 5000,
+            });
+          } catch (error) {
+            reject(error as Error);
+            return;
+          }
+
+          request.on("error", (error: Error) => {
+            resolve(error);
+          });
+          request.on("timeout", () => {
+            request.destroy(new Error("request timed out"));
+          });
+          request.on("response", () => {
+            reject(new Error("broadcast address answered"));
+          });
+        },
+      );
+
+      // Give a stray 'error' event on the socket a chance to surface.
+      await new Promise<void>((resolve: () => void) => {
+        setTimeout(resolve, 50);
+      });
+
+      expect(requestError).not.toBeInstanceOf(TypeError);
+      expect(requestError.message).not.toContain("setServername");
+      expect(
+        typeof (requestError as NodeJS.ErrnoException).code === "string" ||
+          Array.isArray((requestError as { errors?: unknown }).errors),
+      ).toBe(true);
+      expect(uncaught).toEqual([]);
+
+      agent.destroy();
+    } finally {
+      process.removeListener("uncaughtException", onUncaught);
+    }
+  });
 });
 
 describe("DataSourceEgressGuard.createPinnedAgents", () => {