@fedify/vocab-runtime 2.1.23 → 2.1.25

package/src/url.test.ts

@@ -1,4 +1,4 @@
-import { deepStrictEqual, ok, rejects, throws } from "node:assert";
+import { deepStrictEqual, ok, rejects, strictEqual, throws } from "node:assert";
 import { test } from "node:test";
 import {
   expandIPv6Address,
@@ -9,6 +9,28 @@ import {
   validatePublicUrl,
 } from "./url.ts";
 
+test("UrlError reason is independent of its cause", () => {
+  const cause = new Error("Underlying failure");
+  strictEqual(new UrlError("Rejected URL").reason, "disallowed");
+  const disallowedError = new UrlError("Rejected URL", { cause });
+  strictEqual(disallowedError.reason, "disallowed");
+  strictEqual(disallowedError.cause, cause);
+  const dnsError = new UrlError("Lookup failed", { reason: "dns", cause });
+  strictEqual(dnsError.reason, "dns");
+  strictEqual(dnsError.cause, cause);
+});
+
+test("validatePublicUrl() classifies disallowed URLs", async () => {
+  for (
+    const url of ["ftp://example.com", "https://localhost", "https://127.0.0.1"]
+  ) {
+    await rejects(() => validatePublicUrl(url), {
+      name: "UrlError",
+      reason: "disallowed",
+    });
+  }
+});
+
 test("validatePublicUrl()", async () => {
   await rejects(() => validatePublicUrl("ftp://localhost"), UrlError);
   await rejects(
@@ -81,15 +103,19 @@ test("validateLookupAddresses() rejects unsafe or CNAME-only Cloudflare Workers
         { address: "private-host.example.net.", family: 4 },
         { address: "127.0.0.1", family: 4 },
       ]),
-    UrlError,
+    { name: "UrlError", reason: "disallowed" },
   );
   throws(
     () =>
       validateLookupAddresses([
         { address: "app-host.example.net.", family: 4 },
       ]),
-    UrlError,
+    { name: "UrlError", reason: "dns" },
   );
+  throws(() => validateLookupAddresses([]), {
+    name: "UrlError",
+    reason: "dns",
+  });
 });
 
 test("isValidPublicIPv4Address()", () => {

package/src/url.ts

@@ -1,11 +1,25 @@
 import type { LookupAddress } from "node:dns";
-import { lookup } from "node:dns/promises";
+// FIXME: the default dns import exists since tests can stub `dns.lookup()`.
+// This should be replaced by injecting the lookup function such as an internal
+// option on `validatePublicUrl()`
+import dns from "node:dns/promises";
 import { isIP } from "node:net";
 
 export class UrlError extends Error {
-  constructor(message: string, options?: { cause?: unknown }) {
+  /**
+   * The failure category. Defaults to `"disallowed"`.
+   * `"dns"` includes lookup errors and results with no usable IP addresses.
+   * @since 2.0.29
+   */
+  readonly reason: "dns" | "disallowed";
+
+  constructor(
+    message: string,
+    options?: { cause?: unknown; reason?: "dns" | "disallowed" },
+  ) {
     super(message, options);
     this.name = "UrlError";
+    this.reason = options?.reason ?? "disallowed";
   }
 }
 
@@ -50,9 +64,9 @@ export async function validatePublicUrl(url: string): Promise<void> {
   // and ensure that they are all public:
   let addresses: LookupAddress[];
   try {
-    addresses = await lookup(hostname, { all: true });
+    addresses = await dns.lookup(hostname, { all: true });
   } catch (error) {
-    throw new UrlError("DNS lookup failed", { cause: error });
+    throw new UrlError("DNS lookup failed", { cause: error, reason: "dns" });
   }
   validateLookupAddresses(addresses);
 }
@@ -85,7 +99,9 @@ export function validateLookupAddresses(
     validatePublicIpAddress(address, family);
   }
   if (ipAddressCount === 0) {
-    throw new UrlError("DNS lookup did not return any IP address");
+    throw new UrlError("DNS lookup did not return any IP address", {
+      reason: "dns",
+    });
   }
 }