fix: resolve issue #507 (#607)

Co-authored-by: issue-solver-bot <issue-solver-bot@users.noreply.github.com>
Co-authored-by: Abel Osaretin <76490851+AbelOsaretin@users.noreply.github.com>

Author: 3 people

src/__tests__/webhooks.spec.ts

@@ -47,6 +47,48 @@ describe("webhooks routes", () => {
       .expect(400);
   });
 
+  it("POST /api/webhooks — rejects non-http(s) protocols", async () => {
+    await request(app)
+      .post("/api/webhooks")
+      .send({ url: "ftp://example.com/hook", secret: "my-super-secret-key" })
+      .expect(400);
+  });
+
+  it("POST /api/webhooks — rejects strings merely starting with 'http'", async () => {
+    await request(app)
+      .post("/api/webhooks")
+      .send({ url: "httpanything", secret: "my-super-secret-key" })
+      .expect(400);
+  });
+
+  it("POST /api/webhooks — rejects loopback URLs", async () => {
+    await request(app)
+      .post("/api/webhooks")
+      .send({ url: "http://127.0.0.1/hook", secret: "my-super-secret-key" })
+      .expect(400);
+  });
+
+  it("POST /api/webhooks — rejects private IP URLs", async () => {
+    await request(app)
+      .post("/api/webhooks")
+      .send({ url: "http://10.0.0.1/hook", secret: "my-super-secret-key" })
+      .expect(400);
+  });
+
+  it("POST /api/webhooks — rejects link-local / metadata URLs", async () => {
+    await request(app)
+      .post("/api/webhooks")
+      .send({ url: "http://169.254.169.254/latest/meta-data", secret: "my-super-secret-key" })
+      .expect(400);
+  });
+
+  it("POST /api/webhooks — rejects IPv6 loopback URLs", async () => {
+    await request(app)
+      .post("/api/webhooks")
+      .send({ url: "http://[::1]/hook", secret: "my-super-secret-key" })
+      .expect(400);
+  });
+
   it("GET /api/webhooks — lists registered webhooks without secrets", async () => {
     await request(app)
       .post("/api/webhooks")

src/lib/webhooks.ts

@@ -1,5 +1,6 @@
 import { createHmac } from "crypto";
 import { lookup } from "dns/promises";
+import { isIP } from "net";
 import { BlockList, isIP } from "net";
 import { withRetry } from "./retry";
 import { logger } from "./logger";
@@ -15,6 +16,112 @@ export interface WebhookConfig {
 
 const webhooks = new Map<string, WebhookConfig>();
 
+/**
+ * Validate that a webhook URL is a well-formed http/https URL whose resolved
+ * hostname does not point at private, loopback, link-local, or metadata
+ * address ranges. This is a defense-in-depth SSRF guard: even though the
+ * webhook endpoint is admin-only, we never want the server to make outbound
+ * requests to internal infrastructure on behalf of a caller.
+ *
+ * Returns the normalized URL string on success, or throws an Error with a
+ * human-readable message describing why the URL was rejected.
+ */
+export async function validateWebhookUrl(rawUrl: string): Promise<string> {
+  let parsed: URL;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    throw new Error("url must be a valid http/https URL");
+  }
+
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("url must be a valid http/https URL");
+  }
+
+  if (!parsed.hostname) {
+    throw new Error("url must include a hostname");
+  }
+
+  // Resolve the hostname to every address it currently maps to and reject if
+  // any of them is in a forbidden range. We check all addresses because a
+  // hostname could resolve to a mix of public and private IPs.
+  let addresses: string[];
+  try {
+    const result = await lookup(parsed.hostname, { all: true });
+    addresses = result.map((entry) => entry.address);
+  } catch {
+    throw new Error("url hostname could not be resolved");
+  }
+
+  if (addresses.length === 0) {
+    throw new Error("url hostname could not be resolved");
+  }
+
+  for (const address of addresses) {
+    if (isForbiddenAddress(address)) {
+      throw new Error("url must not point to a private, loopback, link-local, or metadata address");
+    }
+  }
+
+  return parsed.toString();
+}
+
+function ipv4ToNumber(ip: string): number {
+  const parts = ip.split(".").map(Number);
+  return ((parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]) >>> 0;
+}
+
+function ipv4InRange(ipNum: number, network: string, prefix: number): boolean {
+  const networkNum = ipv4ToNumber(network);
+  const mask = prefix === 0 ? 0 : ~((1 << (32 - prefix)) - 1) >>> 0;
+  return (ipNum & mask) === (networkNum & mask);
+}
+
+function isForbiddenIPv4(ip: string): boolean {
+  const num = ipv4ToNumber(ip);
+  const ranges: Array<[string, number]> = [
+    ["0.0.0.0", 8], // "this" network
+    ["10.0.0.0", 8], // private
+    ["100.64.0.0", 10], // CGNAT
+    ["127.0.0.0", 8], // loopback
+    ["169.254.0.0", 16], // link-local (incl. cloud metadata)
+    ["172.16.0.0", 12], // private
+    ["192.0.0.0", 24], // IETF protocol assignments
+    ["192.0.2.0", 24], // TEST-NET-1
+    ["192.168.0.0", 16], // private
+    ["198.18.0.0", 15], // benchmarking
+    ["198.51.100.0", 24], // TEST-NET-2
+    ["203.0.113.0", 24], // TEST-NET-3
+    ["224.0.0.0", 4], // multicast
+    ["240.0.0.0", 4], // reserved
+  ];
+  return ranges.some(([network, prefix]) => ipv4InRange(num, network, prefix));
+}
+
+function isForbiddenIPv6(ip: string): boolean {
+  const lower = ip.toLowerCase();
+  // IPv4-mapped IPv6 addresses (::ffff:a.b.c.d) — check the embedded IPv4.
+  const mappedMatch = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  if (mappedMatch) {
+    return isForbiddenIPv4(mappedMatch[1]);
+  }
+  // Normalize the common "::" forms for prefix matching.
+  if (lower === "::" || lower === "::1") return true; // unspecified / loopback
+  if (lower.startsWith("fc") || lower.startsWith("fd")) return true; // unique local fc00::/7
+  if (lower.startsWith("fe8") || lower.startsWith("fe9") || lower.startsWith("fea") || lower.startsWith("feb")) return true; // link-local fe80::/10
+  if (lower.startsWith("fec") || lower.startsWith("fed") || lower.startsWith("fee") || lower.startsWith("fef")) return true; // site-local fec0::/10
+  if (lower.startsWith("ff")) return true; // multicast ff00::/8
+  if (lower.startsWith("2001:db8")) return true; // documentation 2001:db8::/32
+  return false;
+}
+
+function isForbiddenAddress(address: string): boolean {
+  const family = isIP(address);
+  if (family === 4) return isForbiddenIPv4(address);
+  if (family === 6) return isForbiddenIPv6(address);
+  // Unknown address family — treat as forbidden to be safe.
+  return true;
+}
 const BLOCKED_IPS = new BlockList();
 BLOCKED_IPS.addSubnet("0.0.0.0", 8);
 BLOCKED_IPS.addSubnet("10.0.0.0", 8);
@@ -114,6 +221,7 @@ export async function validateWebhookUrl(rawUrl: string): Promise<URL> {
 }
 
 async function deliverOnce(url: string, body: string, signature: string): Promise<void> {
+  // Re-validate at delivery time in case DNS changed after registration.
   // Re-validate immediately before sending to avoid DNS rebinding attacks after registration.
   await validateWebhookUrl(url);
   const response = await fetch(url, {

src/routes/webhooks.ts

@@ -10,6 +10,48 @@ import { badRequest } from "../middleware/errors";
 
 const router = Router();
 
+/**
+ * POST /api/webhooks
+ * Body: { url, secret, max_retries?, retry_delay_ms? }
+ * Registers a new webhook endpoint.
+ */
+router.post("/", async (req: Request, res: Response) => {
+  const { url, secret, max_retries, retry_delay_ms } = req.body as {
+    url?: unknown;
+    secret?: unknown;
+    max_retries?: unknown;
+    retry_delay_ms?: unknown;
+  };
+
+  if (typeof url !== "string") {
+    throw badRequest("url must be a valid http/https URL");
+  }
+  if (typeof secret !== "string" || secret.length < 16) {
+    throw badRequest("secret must be a string of at least 16 characters");
+  }
+
+  let validatedUrl: string;
+  try {
+    validatedUrl = await validateWebhookUrl(url);
+  } catch (err) {
+    throw badRequest(err instanceof Error ? err.message : "url must be a valid http/https URL");
+  }
+
+  const maxRetries =
+    typeof max_retries === "number" && max_retries >= 0 ? Math.floor(max_retries) : 3;
+  const retryDelay =
+    typeof retry_delay_ms === "number" && retry_delay_ms >= 0
+      ? Math.floor(retry_delay_ms)
+      : 2000;
+
+  const wh = registerWebhook(validatedUrl, secret, maxRetries, retryDelay);
+  res.status(201).json({
+    id: wh.id,
+    url: wh.url,
+    max_retries: wh.max_retries,
+    retry_delay_ms: wh.retry_delay_ms,
+    created_at: wh.created_at,
+  });
 router.post("/", async (req: Request, res: Response, next: NextFunction) => {
   try {
     const { url, secret, max_retries, retry_delay_ms } = req.body as {