@oneuptime/common 12.0.9 → 12.0.11

package/Tests/Types/API/URLMalformedTolerance.test.ts

@@ -0,0 +1,301 @@
+import Protocol from "../../../Types/API/Protocol";
+import URL from "../../../Types/API/URL";
+import BadDataException from "../../../Types/Exception/BadDataException";
+import { describe, expect, test } from "@jest/globals";
+
+/*
+ * A status page went blank because ONE footer link, saved years earlier by a
+ * looser validator as "https://tel:3136361710/", no longer parsed. The value
+ * was hydrated by the column transformer during findBy, so the throw escaped
+ * the query and 400'd the whole /master-page config endpoint — the page never
+ * got its config and sat on "Loading..." forever.
+ *
+ * The rule these tests pin: reads tolerate a value that no longer validates,
+ * writes never accept one. A single bad legacy row may degrade itself and
+ * nothing else.
+ */
+
+interface Transformer {
+  to: (value: unknown) => unknown;
+  from: (value: unknown) => unknown;
+}
+
+const transformer: Transformer = URL.getDatabaseTransformer() as Transformer;
+
+/*
+ * Values the old character-allowlist Hostname accepted and the current
+ * structural one does not. Every one of these can already be sitting in a
+ * customer's database.
+ */
+const legacyUnparseableValues: Array<string> = [
+  // The value that actually took the status page down.
+  "https://tel:3136361710/",
+  // Ports that are not ports.
+  "https://host:99999999/",
+  "https://example.com:notaport/",
+  // Hosts that are not hosts.
+  "https://-leading-dash.example.com/",
+  "https://trailing-dash-.example.com/",
+  "https:// /",
+  "https://exa mple.com/",
+];
+
+describe("URL — reads tolerate a value that no longer parses", () => {
+  test.each(legacyUnparseableValues)(
+    "fromStringLenient(%s) does not throw",
+    (raw: string) => {
+      expect(() => {
+        return URL.fromStringLenient(raw);
+      }).not.toThrow();
+    },
+  );
+
+  test.each(legacyUnparseableValues)(
+    "fromStringLenient(%s) flags the value as malformed",
+    (raw: string) => {
+      expect(URL.fromStringLenient(raw).isMalformed()).toBe(true);
+    },
+  );
+
+  test.each(legacyUnparseableValues)(
+    "fromStringLenient(%s) preserves the value verbatim",
+    (raw: string) => {
+      // The link still renders as exactly what it always was.
+      expect(URL.fromStringLenient(raw).toString()).toBe(raw);
+    },
+  );
+
+  test.each(legacyUnparseableValues)(
+    "the column transformer reads %s without throwing",
+    (raw: string) => {
+      let result: URL | null = null;
+
+      expect(() => {
+        result = transformer.from(raw) as URL;
+      }).not.toThrow();
+
+      expect(result).toBeInstanceOf(URL);
+      expect((result as unknown as URL).toString()).toBe(raw);
+    },
+  );
+
+  test("fromString stays strict — leniency is opt-in, on read paths only", () => {
+    for (const raw of legacyUnparseableValues) {
+      expect(() => {
+        return URL.fromString(raw);
+      }).toThrow(BadDataException);
+    }
+  });
+});
+
+describe("URL — a malformed value exposes no host", () => {
+  /*
+   * The security property that makes leniency safe: nothing can read a
+   * hostname off a malformed URL and turn it into a request target. The
+   * outbound guards (SSRFProtection) re-parse the raw string with the WHATWG
+   * parser and never trusted this type's parse anyway.
+   */
+  test.each(legacyUnparseableValues)(
+    "%s yields no hostname and no opaque value",
+    (raw: string) => {
+      const url: URL = URL.fromStringLenient(raw);
+
+      expect(url.hostname).toBeUndefined();
+      expect(url.opaqueValue).toBe("");
+    },
+  );
+
+  test("a malformed URL reports the https default protocol", () => {
+    expect(URL.fromStringLenient("https://tel:3136361710/").protocol).toBe(
+      Protocol.HTTPS,
+    );
+  });
+
+  test("removeQueryString on a malformed URL does not throw", () => {
+    const url: URL = URL.fromStringLenient("https://tel:3136361710/?a=1");
+
+    expect(() => {
+      return url.removeQueryString();
+    }).not.toThrow();
+    expect(url.removeQueryString().isMalformed()).toBe(true);
+  });
+});
+
+describe("URL — writes stay strict", () => {
+  test.each(legacyUnparseableValues)(
+    "the column transformer refuses to write back %s",
+    (raw: string) => {
+      const malformed: URL = URL.fromStringLenient(raw);
+
+      expect(() => {
+        return transformer.to(malformed);
+      }).toThrow(BadDataException);
+    },
+  );
+
+  test("a client cannot invent a malformed URL and have it persisted", () => {
+    /*
+     * fromJSON is lenient so the browser can render a legacy link — but the
+     * value it produces is still refused on the way back into the database.
+     */
+    const fromClient: URL = URL.fromJSON({
+      _type: "URL",
+      value: "https://tel:3136361710/",
+    });
+
+    expect(fromClient.isMalformed()).toBe(true);
+    expect(() => {
+      return transformer.to(fromClient);
+    }).toThrow(BadDataException);
+  });
+
+  test("a raw malformed string is refused on write too", () => {
+    expect(() => {
+      return transformer.to("https://tel:3136361710/");
+    }).toThrow(BadDataException);
+  });
+
+  test("the write error names the offending value", () => {
+    expect(() => {
+      return transformer.to(URL.fromStringLenient("https://tel:3136361710/"));
+    }).toThrow("URL https://tel:3136361710/ is not in valid format.");
+  });
+
+  test("valid URLs still write normally", () => {
+    expect(transformer.to(URL.fromString("https://example.com/privacy"))).toBe(
+      "https://example.com/privacy",
+    );
+    expect(transformer.to(URL.fromString("tel:+13136361710"))).toBe(
+      "tel:+13136361710",
+    );
+  });
+});
+
+describe("URL — leniency does not touch valid values", () => {
+  const validValues: Array<string> = [
+    "https://example.com/privacy",
+    "https://docs.voice.izt.cloud/",
+    "http://localhost:5000/api/test",
+    "mailto:support@voice.izt.cloud",
+    "tel:+13136361710",
+    "sms:+15555550123",
+    "wss://localhost:5000/api/test",
+  ];
+
+  test.each(validValues)("%s is not flagged malformed", (raw: string) => {
+    expect(URL.fromStringLenient(raw).isMalformed()).toBe(false);
+    expect((transformer.from(raw) as URL).isMalformed()).toBe(false);
+  });
+
+  test.each(validValues)("%s parses identically either way", (raw: string) => {
+    expect(URL.fromStringLenient(raw).toString()).toBe(
+      URL.fromString(raw).toString(),
+    );
+  });
+
+  test("an empty stored value is still null, not a malformed URL", () => {
+    expect(transformer.from("")).toBeNull();
+    expect(transformer.from(null)).toBeNull();
+  });
+
+  test("undefined is still passed through untouched on write", () => {
+    // A column the caller never set must stay undefined so its DEFAULT applies.
+    expect(transformer.to(undefined)).toBeUndefined();
+  });
+});
+
+/*
+ * The end-to-end shape of the outage: a status page's footer links, one of
+ * which is the bad legacy row. Reading the set must yield every link.
+ */
+describe("URL — one bad link no longer takes down the page that lists it", () => {
+  const storedFooterLinks: Array<{ title: string; link: string }> = [
+    { title: "Phone", link: "https://tel:3136361710/" },
+    { title: "Email", link: "mailto:support@voice.izt.cloud" },
+    { title: "Docs", link: "https://docs.voice.izt.cloud/" },
+    { title: "Portal", link: "https://portal.voice.izt.cloud/" },
+  ];
+
+  test("hydrating the whole set does not throw", () => {
+    expect(() => {
+      return storedFooterLinks.map((row: { link: string }) => {
+        return transformer.from(row.link);
+      });
+    }).not.toThrow();
+  });
+
+  test("every link survives, including the malformed one", () => {
+    const hydrated: Array<URL> = storedFooterLinks.map(
+      (row: { link: string }) => {
+        return transformer.from(row.link) as URL;
+      },
+    );
+
+    expect(hydrated).toHaveLength(4);
+    expect(
+      hydrated.map((url: URL) => {
+        return url.toString();
+      }),
+    ).toEqual([
+      "https://tel:3136361710/",
+      "mailto:support@voice.izt.cloud",
+      "https://docs.voice.izt.cloud/",
+      "https://portal.voice.izt.cloud/",
+    ]);
+  });
+
+  test("only the bad row is degraded", () => {
+    const hydrated: Array<URL> = storedFooterLinks.map(
+      (row: { link: string }) => {
+        return transformer.from(row.link) as URL;
+      },
+    );
+
+    expect(
+      hydrated.map((url: URL) => {
+        return url.isMalformed();
+      }),
+    ).toEqual([true, false, false, false]);
+  });
+
+  test("the whole set still serialises to JSON for the browser", () => {
+    expect(() => {
+      return storedFooterLinks.map((row: { link: string }) => {
+        return (transformer.from(row.link) as URL).toJSON();
+      });
+    }).not.toThrow();
+  });
+
+  /*
+   * Had the fix stopped at the server, the 400 would simply have become a
+   * client-side crash when the browser revived the same value.
+   */
+  test("and the browser can revive every one of them", () => {
+    const revived: Array<URL> = storedFooterLinks.map(
+      (row: { link: string }) => {
+        return URL.fromJSON((transformer.from(row.link) as URL).toJSON());
+      },
+    );
+
+    expect(
+      revived.map((url: URL) => {
+        return url.toString();
+      }),
+    ).toEqual([
+      "https://tel:3136361710/",
+      "mailto:support@voice.izt.cloud",
+      "https://docs.voice.izt.cloud/",
+      "https://portal.voice.izt.cloud/",
+    ]);
+  });
+
+  /*
+   * And the correct value going forward: the same phone link, typed as a real
+   * tel: URI, is valid on write and needs no leniency at all.
+   */
+  test("the same link stored correctly needs no leniency", () => {
+    const stored: unknown = transformer.to(URL.fromString("tel:+13136361710"));
+    expect(stored).toBe("tel:+13136361710");
+    expect((transformer.from(stored) as URL).isMalformed()).toBe(false);
+  });
+});

package/Tests/Types/API/URLTelScheme.test.ts

@@ -0,0 +1,261 @@
+import Protocol from "../../../Types/API/Protocol";
+import URL from "../../../Types/API/URL";
+import BadDataException from "../../../Types/Exception/BadDataException";
+import { describe, expect, test } from "@jest/globals";
+
+/*
+ * "tel:" and "sms:" are opaque schemes: what follows the colon is a phone
+ * number, not an authority. Before they were known to the parser, a status
+ * page footer link of "tel:3136361710" fell through to the https default,
+ * was read as host "tel" + port "3136361710", and toString() normalised it
+ * on save into "https://tel:3136361710/". These tests pin the parse, the
+ * round-trip, and the rule that nothing in an opaque payload may look like an
+ * authority or a path.
+ */
+
+describe("URL — tel: and sms: are parsed as opaque schemes", () => {
+  const validTelUrls: Array<[string, string]> = [
+    // [input, expected opaque value]
+    ["tel:+13136361710", "+13136361710"],
+    ["tel:3136361710", "3136361710"],
+    ["tel:+1-313-636-1710", "+1-313-636-1710"],
+    ["tel:+1.313.636.1710", "+1.313.636.1710"],
+    // RFC 3966 allows a number to open on a visual separator.
+    ["tel:(313)636-1710", "(313)636-1710"],
+    ["tel:+1(313)636-1710", "+1(313)636-1710"],
+    ["tel:-5550123", "-5550123"],
+    ["tel:911", "911"],
+    ["tel:+442071838750", "+442071838750"],
+    // RFC 3966 parameters.
+    ["tel:3136361710;phone-context=+1", "3136361710;phone-context=+1"],
+    ["tel:+13136361710;ext=42", "+13136361710;ext=42"],
+  ];
+
+  test.each(validTelUrls)(
+    "parses %s as a tel: URL with no hostname",
+    (input: string, expectedValue: string) => {
+      const url: URL = URL.fromString(input);
+
+      expect(url.protocol).toBe(Protocol.TEL);
+      expect(url.opaqueValue).toBe(expectedValue);
+      expect(url.isMalformed()).toBe(false);
+      // An opaque URL has no authority — nothing can read a host off it.
+      expect(url.hostname).toBeUndefined();
+    },
+  );
+
+  test.each(validTelUrls)(
+    "round-trips %s unchanged through toString()",
+    (input: string) => {
+      expect(URL.fromString(input).toString()).toBe(input);
+    },
+  );
+
+  test("parses sms: the same way", () => {
+    const url: URL = URL.fromString("sms:+15555550123");
+
+    expect(url.protocol).toBe(Protocol.SMS);
+    expect(url.opaqueValue).toBe("+15555550123");
+    expect(url.toString()).toBe("sms:+15555550123");
+  });
+
+  test("sms: accepts several comma-separated recipients", () => {
+    const url: URL = URL.fromString("sms:+15555550123,+15555550124");
+
+    expect(url.opaqueValue).toBe("+15555550123,+15555550124");
+    expect(url.toString()).toBe("sms:+15555550123,+15555550124");
+  });
+
+  test("sms: keeps a body query string", () => {
+    const url: URL = URL.fromString("sms:+15555550123?body=hello");
+
+    expect(url.protocol).toBe(Protocol.SMS);
+    expect(url.opaqueValue).toBe("+15555550123");
+    expect(url.getQueryParam("body")).toBe("hello");
+    expect(url.toString()).toBe("sms:+15555550123?body=hello");
+  });
+
+  test("scheme match is case-insensitive, per RFC 3986", () => {
+    expect(URL.fromString("TEL:+13136361710").protocol).toBe(Protocol.TEL);
+    expect(URL.fromString("Tel:+13136361710").opaqueValue).toBe("+13136361710");
+    expect(URL.fromString("SMS:+15555550123").protocol).toBe(Protocol.SMS);
+  });
+
+  test("isOpaqueProtocol identifies exactly tel: and sms:", () => {
+    expect(URL.isOpaqueProtocol(Protocol.TEL)).toBe(true);
+    expect(URL.isOpaqueProtocol(Protocol.SMS)).toBe(true);
+    expect(URL.isOpaqueProtocol(Protocol.HTTPS)).toBe(false);
+    expect(URL.isOpaqueProtocol(Protocol.HTTP)).toBe(false);
+    expect(URL.isOpaqueProtocol(Protocol.MAIL)).toBe(false);
+    expect(URL.isOpaqueProtocol(Protocol.WS)).toBe(false);
+    expect(URL.isOpaqueProtocol(Protocol.WSS)).toBe(false);
+    expect(URL.isOpaqueProtocol(Protocol.MONGO_DB)).toBe(false);
+  });
+
+  test("the constructor also takes the opaque path", () => {
+    const url: URL = new URL(Protocol.TEL, "+13136361710");
+
+    expect(url.opaqueValue).toBe("+13136361710");
+    expect(url.hostname).toBeUndefined();
+    expect(url.toString()).toBe("tel:+13136361710");
+  });
+
+  test("isHttps() is false for an opaque URL", () => {
+    expect(URL.fromString("tel:+13136361710").isHttps()).toBe(false);
+    expect(URL.fromString("sms:+15555550123").isHttps()).toBe(false);
+  });
+});
+
+/*
+ * The regression this whole change exists for: the value a customer typed
+ * must survive a save/read cycle instead of being rewritten into a bogus
+ * https URL that a later, stricter Hostname validator then refuses to read.
+ */
+describe("URL — tel: is no longer mangled into an https URL", () => {
+  test("tel:3136361710 does not become https://tel:3136361710/", () => {
+    const url: URL = URL.fromString("tel:3136361710");
+
+    expect(url.toString()).toBe("tel:3136361710");
+    expect(url.toString()).not.toBe("https://tel:3136361710/");
+    expect(url.protocol).not.toBe(Protocol.HTTPS);
+  });
+
+  test("the value survives the database round-trip", () => {
+    const transformer: {
+      to: (value: unknown) => unknown;
+      from: (value: unknown) => unknown;
+    } = URL.getDatabaseTransformer() as {
+      to: (value: unknown) => unknown;
+      from: (value: unknown) => unknown;
+    };
+
+    const stored: unknown = transformer.to(URL.fromString("tel:3136361710"));
+    expect(stored).toBe("tel:3136361710");
+
+    const readBack: URL = transformer.from(stored) as URL;
+    expect(readBack.toString()).toBe("tel:3136361710");
+    expect(readBack.isMalformed()).toBe(false);
+  });
+
+  test("the value survives the JSON round-trip to the browser", () => {
+    const url: URL = URL.fromString("tel:+13136361710");
+    const revived: URL = URL.fromJSON(url.toJSON());
+
+    expect(revived.toString()).toBe("tel:+13136361710");
+    expect(revived.protocol).toBe(Protocol.TEL);
+    expect(revived.isMalformed()).toBe(false);
+  });
+});
+
+describe("URL — an opaque payload may not smuggle an authority or path", () => {
+  const invalidOpaquePayloads: Array<string> = [
+    // Empty.
+    "tel:",
+    "sms:",
+    // Not a number at all.
+    "tel:abc",
+    "tel:not-a-phone",
+    // Path traversal / a path of any kind.
+    "tel:../../etc/passwd",
+    "tel:1/../../admin",
+    "tel:+1555/path",
+    // An authority smuggled behind the number.
+    "tel:1@evil.example.com",
+    "tel:+15555550123@169.254.169.254",
+    "sms:1@evil.example.com",
+    // A fragment.
+    "tel:1#fragment",
+    "tel:+15555550123#.office.com",
+    // Whitespace.
+    "tel:555 0123",
+    "tel: ",
+    // Separators only, with no digit anywhere.
+    "tel:(",
+    "tel:()-.",
+    "tel:+",
+    // Protocol-relative smuggling.
+    "tel://evil.example.com",
+    "sms://evil.example.com",
+  ];
+
+  test.each(invalidOpaquePayloads)("rejects %s", (input: string) => {
+    expect(() => {
+      return URL.fromString(input);
+    }).toThrow(BadDataException);
+  });
+
+  test("rejects a payload longer than 256 characters", () => {
+    expect(() => {
+      return URL.fromString("tel:+" + "1".repeat(300));
+    }).toThrow(BadDataException);
+  });
+
+  test("rejects a parameter that is not a well-formed key=value", () => {
+    expect(() => {
+      return URL.fromString("tel:+15555550123;evil=a/b");
+    }).toThrow(BadDataException);
+    expect(() => {
+      return URL.fromString("tel:+15555550123;a@b");
+    }).toThrow(BadDataException);
+  });
+
+  test("the error names the offending value", () => {
+    expect(() => {
+      return URL.fromString("tel:abc");
+    }).toThrow("Phone number abc is not in valid format.");
+  });
+
+  /*
+   * A dotted quad is a syntactically valid local number, so it parses — but it
+   * stays a tel: URL with no hostname, so it can never become the target of an
+   * HTTP request the way "https://169.254.169.254" would.
+   */
+  test("a dotted quad stays a tel: URL and exposes no host", () => {
+    const url: URL = URL.fromString("tel:169.254.169.254");
+
+    expect(url.protocol).toBe(Protocol.TEL);
+    expect(url.hostname).toBeUndefined();
+    expect(url.toString()).toBe("tel:169.254.169.254");
+  });
+});
+
+describe("URL — adding opaque schemes did not disturb the existing ones", () => {
+  const untouched: Array<[string, Protocol]> = [
+    ["https://example.com/api/test", Protocol.HTTPS],
+    ["http://example.com/api/test", Protocol.HTTP],
+    ["ws://localhost:5000/api/test", Protocol.WS],
+    ["wss://localhost:5000/api/test", Protocol.WSS],
+    ["mongodb://localhost:27017/test", Protocol.MONGO_DB],
+    ["mailto:support@example.com", Protocol.MAIL],
+  ];
+
+  test.each(untouched)(
+    "%s still parses as %s",
+    (input: string, expected: Protocol) => {
+      const url: URL = URL.fromString(input);
+      expect(url.protocol).toBe(expected);
+      expect(url.opaqueValue).toBe("");
+    },
+  );
+
+  test.each(untouched)("%s still round-trips", (input: string) => {
+    expect(URL.fromString(input).toString()).toBe(input);
+  });
+
+  test("query strings on http URLs are unaffected", () => {
+    const url: URL = URL.fromString("https://example.com/api?a=1&b=2");
+    expect(url.getQueryParam("a")).toBe("1");
+    expect(url.getQueryParam("b")).toBe("2");
+    expect(url.toString()).toBe("https://example.com/api?a=1&b=2");
+  });
+
+  /*
+   * "telephone.example.com" starts with "tel" but is not the tel: scheme —
+   * prefix matching must be on "tel:", not "tel".
+   */
+  test("a host that merely starts with tel is not treated as a tel: URL", () => {
+    const url: URL = URL.fromString("https://telephone.example.com/x");
+    expect(url.protocol).toBe(Protocol.HTTPS);
+    expect(url.hostname.toString()).toBe("telephone.example.com");
+  });
+});