@fedify/vocab-runtime 2.0.0-dev.12

package/src/request.ts

@@ -0,0 +1,115 @@
+import type { Logger } from "@logtape/logtape";
+import process from "node:process";
+import metadata from "../deno.json" with { type: "json" };
+
+/**
+ * Error thrown when fetching a JSON-LD document failed.
+ */
+export class FetchError extends Error {
+  /**
+   * The URL that failed to fetch.
+   */
+  url: URL;
+
+  /**
+   * Constructs a new `FetchError`.
+   *
+   * @param url The URL that failed to fetch.
+   * @param message Error message.
+   */
+  constructor(url: URL | string, message?: string) {
+    super(message == null ? url.toString() : `${url}: ${message}`);
+    this.name = "FetchError";
+    this.url = typeof url === "string" ? new URL(url) : url;
+  }
+}
+
+/**
+ * Options for creating a request.
+ * @internal
+ */
+export interface CreateRequestOptions {
+  userAgent?: GetUserAgentOptions | string;
+}
+
+/**
+ * Creates a request for the given URL.
+ * @param url The URL to create the request for.
+ * @param options The options for the request.
+ * @returns The created request.
+ * @internal
+ */
+export function createActivityPubRequest(
+  url: string,
+  options: CreateRequestOptions = {},
+): Request {
+  return new Request(url, {
+    headers: {
+      Accept: "application/activity+json, application/ld+json",
+      "User-Agent": typeof options.userAgent === "string"
+        ? options.userAgent
+        : getUserAgent(options.userAgent),
+    },
+    redirect: "manual",
+  });
+}
+
+/**
+ * Options for making `User-Agent` string.
+ * @see {@link getUserAgent}
+ * @since 1.3.0
+ */
+export interface GetUserAgentOptions {
+  /**
+   * An optional software name and version, e.g., `"Hollo/1.0.0"`.
+   */
+  software?: string | null;
+  /**
+   * An optional URL to append to the user agent string.
+   * Usually the URL of the ActivityPub instance.
+   */
+  url?: string | URL | null;
+}
+
+/**
+ * Gets the user agent string for the given application and URL.
+ * @param options The options for making the user agent string.
+ * @returns The user agent string.
+ * @since 1.3.0
+ */
+export function getUserAgent(
+  { software, url }: GetUserAgentOptions = {},
+): string {
+  const fedify = `Fedify/${metadata.version}`;
+  const runtime = globalThis.Deno?.version?.deno != null
+    ? `Deno/${Deno.version.deno}`
+    : globalThis.process?.versions?.bun != null
+    ? `Bun/${process.versions.bun}`
+    : "navigator" in globalThis &&
+        navigator.userAgent === "Cloudflare-Workers"
+    ? navigator.userAgent
+    : globalThis.process?.versions?.node != null
+    ? `Node.js/${process.versions.node}`
+    : null;
+  const userAgent = software == null ? [fedify] : [software, fedify];
+  if (runtime != null) userAgent.push(runtime);
+  if (url != null) userAgent.push(`+${url.toString()}`);
+  const first = userAgent.shift();
+  return `${first} (${userAgent.join("; ")})`;
+}
+
+/**
+ * Logs the request.
+ * @param request The request to log.
+ * @internal
+ */
+export function logRequest(logger: Logger, request: Request) {
+  logger.debug(
+    "Fetching document: {method} {url} {headers}",
+    {
+      method: request.method,
+      url: request.url,
+      headers: Object.fromEntries(request.headers.entries()),
+    },
+  );
+}

package/src/url.test.ts

@@ -0,0 +1,59 @@
+import { deepStrictEqual, ok, rejects } from "node:assert";
+import { test } from "node:test";
+import {
+  expandIPv6Address,
+  isValidPublicIPv4Address,
+  isValidPublicIPv6Address,
+  UrlError,
+  validatePublicUrl,
+} from "./url.ts";
+
+test("validatePublicUrl()", async () => {
+  await rejects(() => validatePublicUrl("ftp://localhost"), UrlError);
+  await rejects(
+    // cSpell: disable
+    () => validatePublicUrl("data:text/plain;base64,SGVsbG8sIFdvcmxkIQ=="),
+    // cSpell: enable
+    UrlError,
+  );
+  await rejects(() => validatePublicUrl("https://localhost"), UrlError);
+  await rejects(() => validatePublicUrl("https://127.0.0.1"), UrlError);
+  await rejects(() => validatePublicUrl("https://[::1]"), UrlError);
+});
+
+test("isValidPublicIPv4Address()", () => {
+  ok(isValidPublicIPv4Address("8.8.8.8")); // Google DNS
+  ok(!isValidPublicIPv4Address("192.168.1.1")); // private
+  ok(!isValidPublicIPv4Address("127.0.0.1")); // localhost
+  ok(!isValidPublicIPv4Address("10.0.0.1")); // private
+  ok(!isValidPublicIPv4Address("127.16.0.1")); // private
+  ok(!isValidPublicIPv4Address("169.254.0.1")); // link-local
+});
+
+test("isValidPublicIPv6Address()", () => {
+  ok(isValidPublicIPv6Address("2001:db8::1"));
+  ok(!isValidPublicIPv6Address("::1")); // localhost
+  ok(!isValidPublicIPv6Address("fc00::1")); // ULA
+  ok(!isValidPublicIPv6Address("fe80::1")); // link-local
+  ok(!isValidPublicIPv6Address("ff00::1")); // multicast
+  ok(!isValidPublicIPv6Address("::")); // unspecified
+});
+
+test("expandIPv6Address()", () => {
+  deepStrictEqual(
+    expandIPv6Address("::"),
+    "0000:0000:0000:0000:0000:0000:0000:0000",
+  );
+  deepStrictEqual(
+    expandIPv6Address("::1"),
+    "0000:0000:0000:0000:0000:0000:0000:0001",
+  );
+  deepStrictEqual(
+    expandIPv6Address("2001:db8::"),
+    "2001:0db8:0000:0000:0000:0000:0000:0000",
+  );
+  deepStrictEqual(
+    expandIPv6Address("2001:db8::1"),
+    "2001:0db8:0000:0000:0000:0000:0000:0001",
+  );
+});

package/src/url.ts

@@ -0,0 +1,96 @@
+import type { LookupAddress } from "node:dns";
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+
+export class UrlError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UrlError";
+  }
+}
+
+/**
+ * Validates a URL to prevent SSRF attacks.
+ */
+export async function validatePublicUrl(url: string): Promise<void> {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new UrlError(`Unsupported protocol: ${parsed.protocol}`);
+  }
+  let hostname = parsed.hostname;
+  if (hostname.startsWith("[") && hostname.endsWith("]")) {
+    hostname = hostname.substring(1, hostname.length - 2);
+  }
+  if (hostname === "localhost") {
+    throw new UrlError("Localhost is not allowed");
+  }
+  if ("Deno" in globalThis && !isIP(hostname)) {
+    // If the `net` permission is not granted, we can't resolve the hostname.
+    // However, we can safely assume that it cannot gain access to private
+    // resources.
+    const netPermission = await Deno.permissions.query({ name: "net" });
+    if (netPermission.state !== "granted") return;
+  }
+  // FIXME: This is a temporary workaround for the `Bun` runtime; for unknown
+  // reasons, the Web Crypto API does not work as expected after a DNS lookup.
+  // This workaround purposes to prevent unit tests from hanging up:
+  if ("Bun" in globalThis) {
+    if (hostname === "example.com" || hostname.endsWith(".example.com")) {
+      return;
+    } else if (hostname === "fedify-test.internal") {
+      throw new UrlError("Invalid or private address: fedify-test.internal");
+    }
+  }
+  // To prevent SSRF via DNS rebinding, we need to resolve all IP addresses
+  // and ensure that they are all public:
+  let addresses: LookupAddress[];
+  try {
+    addresses = await lookup(hostname, { all: true });
+  } catch {
+    addresses = [];
+  }
+  for (const { address, family } of addresses) {
+    if (
+      family === 4 && !isValidPublicIPv4Address(address) ||
+      family === 6 && !isValidPublicIPv6Address(address) ||
+      family < 4 || family === 5 || family > 6
+    ) {
+      throw new UrlError(`Invalid or private address: ${address}`);
+    }
+  }
+}
+
+export function isValidPublicIPv4Address(address: string): boolean {
+  const parts = address.split(".");
+  const first = parseInt(parts[0]);
+  if (first === 0 || first === 10 || first === 127) return false;
+  const second = parseInt(parts[1]);
+  if (first === 169 && second === 254) return false;
+  if (first === 172 && second >= 16 && second <= 31) return false;
+  if (first === 192 && second === 168) return false;
+  return true;
+}
+
+export function isValidPublicIPv6Address(address: string): boolean {
+  address = expandIPv6Address(address);
+  if (address.at(4) !== ":") return false;
+  const firstWord = parseInt(address.substring(0, 4), 16);
+  return !(
+    (firstWord >= 0xfc00 && firstWord <= 0xfdff) || // ULA
+    (firstWord >= 0xfe80 && firstWord <= 0xfebf) || // Link-local
+    firstWord === 0 || firstWord >= 0xff00 // Multicast
+  );
+}
+
+export function expandIPv6Address(address: string): string {
+  address = address.toLowerCase();
+  if (address === "::") return "0000:0000:0000:0000:0000:0000:0000:0000";
+  if (address.startsWith("::")) address = "0000" + address;
+  if (address.endsWith("::")) address = address + "0000";
+  address = address.replace(
+    "::",
+    ":0000".repeat(8 - (address.match(/:/g) || []).length) + ":",
+  );
+  const parts = address.split(":");
+  return parts.map((part) => part.padStart(4, "0")).join(":");
+}

package/tsdown.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: ["src/mod.ts"],
+  dts: true,
+  format: ["esm", "cjs"],
+  platform: "node",
+  external: [/^node:/],
+});