@bygghammar/cms-platform 0.95.0 → 0.97.0

package/src/popups/runtime.tsx

@@ -25,7 +25,8 @@ import type {
 import { ManagedForm } from "../forms/FormRenderer";
 import { onFormSubmissionSuccess } from "../forms/success-listeners";
 import { siteConfig } from "../config/site-config";
-import { containsBookingTarget, isBookingHref, stripBookingDeep } from "../cms/booking-links";
+import { containsBookingTarget, containsLinkTo, isBookingHref, stripBookingDeep } from "../cms/booking-links";
+import { isHiddenFromDiscovery, type LinkVisibilityPolicy } from "../navigation/visibility";
 import { useLinkVisibility } from "../site/link-visibility";
 import type { PopupPublicHost } from "./host";
 import { popupPublicHost } from "./host";
@@ -111,14 +112,25 @@ export function PopupModuleRuntime(): ReactNode {
    * it found through the same rules, and only the latest read counts, so one
    * begun under the old policy cannot bring booking back. Without a policy
    * provider booking is visible and nothing changes.
+   *
+   * The same goes for a popup that leads to a page hidden from the website
+   * while booking is hidden (a booking-off landing page): not offered, and
+   * retired if it is the one on screen, until the page is shown again.
    */
-  const bookingVisible = useLinkVisibility().bookingVisible;
+  const linkPolicy = useLinkVisibility();
+  const bookingVisible = linkPolicy.bookingVisible;
+  const hiddenKey = hiddenPagesKey(linkPolicy);
   const [loaded, setLoaded] = useState<readonly PopupConfig[] | null>(null);
   const offered = useRef<Offered>(NOTHING_OFFERED);
   const offer = useMemo(
-    () => popupsToOffer(loaded ?? [], offered.current, bookingVisible),
-    // `offered` is what the runtime was last handed, read for identity only.
-    [loaded, bookingVisible],
+    () =>
+      popupsToOffer(loaded ?? [], offered.current, bookingVisible, (href) =>
+        isHiddenFromDiscovery(href, linkPolicy),
+      ),
+    // `offered` is what the runtime was last handed, read for identity only;
+    // the policy matters only through what `hiddenKey` names.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [loaded, bookingVisible, hiddenKey],
   );
   useEffect(() => {
     offered.current = offer;
@@ -126,14 +138,23 @@ export function PopupModuleRuntime(): ReactNode {
 
   // The repository is asked again when the host or the policy changes — and
   // only once the runtime asks for its popups, so never where it does not run.
-  const askedFor = useRef<{ configs: PopupPublicHost["configs"]; bookingVisible: boolean } | null>(null);
+  const askedFor = useRef<{
+    configs: PopupPublicHost["configs"];
+    bookingVisible: boolean;
+    hiddenKey: string;
+  } | null>(null);
   const latestRead = useRef(0);
   const configs = useMemo<RuntimeAdapters["configs"]>(
     () => ({
       listActive: async () => {
         const asked = askedFor.current;
-        if (asked === null || asked.configs !== host.configs || asked.bookingVisible !== bookingVisible) {
-          askedFor.current = { configs: host.configs, bookingVisible };
+        if (
+          asked === null ||
+          asked.configs !== host.configs ||
+          asked.bookingVisible !== bookingVisible ||
+          asked.hiddenKey !== hiddenKey
+        ) {
+          askedFor.current = { configs: host.configs, bookingVisible, hiddenKey };
           const read = ++latestRead.current;
           Promise.resolve()
             .then(() => host.configs.listActive())
@@ -152,7 +173,7 @@ export function PopupModuleRuntime(): ReactNode {
         return offer.list;
       },
     }),
-    [host.configs, bookingVisible, offer],
+    [host.configs, bookingVisible, hiddenKey, offer],
   );
 
   // The argument type comes from the port, not a copy of it: a package that
@@ -189,6 +210,15 @@ type ContentBlock = PopupConfig["steps"][number]["blocks"][number];
 type PopupButton = Extract<ContentBlock, { type: "buttons" }>["buttons"][number];
 type BlockAction = PopupButton["action"];
 
+/** The booking-off pages a policy hides, as one comparable string. */
+function hiddenPagesKey(policy: LinkVisibilityPolicy): string {
+  return Object.entries(policy.hiddenPaths)
+    .filter(([, reason]) => reason === "booking-off")
+    .map(([path]) => path)
+    .sort()
+    .join("\n");
+}
+
 /** The list last handed to the runtime, and each popup's content, by key. */
 type Offered = { list: readonly PopupConfig[]; content: ReadonlyMap<string, string> };
 const NOTHING_OFFERED: Offered = { list: [], content: new Map() };
@@ -197,7 +227,8 @@ const NOTHING_OFFERED: Offered = { list: [], content: new Map() };
  * What the runtime is handed from a load, given what it already holds.
  *
  * - While booking is hidden, a popup that leads to booking is not offered: it
- *   is handed over retired (see {@link retire}).
+ *   is handed over retired (see {@link retire}). So is a popup that leads to
+ *   a page hidden while booking is hidden (`hiddenPage`).
  * - A popup the runtime already holds is never dropped, even when the load no
  *   longer has it (a server that withholds booking popups, a popup paused or
  *   deleted since). The runtime tracks the open popup by key, so dropping the
@@ -213,7 +244,11 @@ function popupsToOffer(
   loaded: readonly PopupConfig[],
   previous: Offered,
   bookingVisible: boolean,
+  hiddenPage: (href: string) => boolean,
 ): Offered {
+  const hideBooking = !bookingVisible;
+  const withheld = (popup: PopupConfig) =>
+    (hideBooking && containsBookingTarget(popup)) || containsLinkTo(popup, hiddenPage);
   const held = new Map(previous.list.map((popup) => [popup.key, popup]));
   const content = new Map<string, string>();
   const list: PopupConfig[] = [];
@@ -224,10 +259,10 @@ function popupsToOffer(
     list.push(same !== undefined && previous.content.get(popup.key) === text ? same : popup);
   };
   for (const popup of loaded) {
-    offer(bookingVisible || !containsBookingTarget(popup) ? popup : retire(popup, true));
+    offer(withheld(popup) ? retire(popup, hideBooking, hiddenPage) : popup);
   }
   for (const popup of previous.list) {
-    if (!content.has(popup.key)) offer(retire(popup, !bookingVisible));
+    if (!content.has(popup.key)) offer(retire(popup, hideBooking, hiddenPage));
   }
   const unchanged =
     list.length === previous.list.length && list.every((popup, index) => popup === previous.list[index]);
@@ -237,43 +272,51 @@ function popupsToOffer(
 /**
  * A popup the runtime keeps but never offers again.
  *
- * Paused, which the runtime neither shows nor reports as suppressed. With
- * `hideBooking`, everything in it that leads to booking is taken out too —
- * links, buttons, an answer or a form that would open the booking site now
- * simply closes — so if it is the one on screen, the visitor keeps what they
- * were reading, cannot reach booking from it, and closes it the usual way.
- * The stored popup is not touched; this is the copy the visitor sees.
+ * Paused, which the runtime neither shows nor reports as suppressed. Every
+ * place in it that leads to booking (with `hideBooking`) or to a page hidden
+ * while booking is hidden (`hiddenPage`) is taken out too: links and
+ * buttons go, an answer or a form that would open it now simply closes. So if
+ * it is the one on screen, the visitor keeps what they were reading, cannot
+ * follow it anywhere it must not lead, and closes it the usual way. The
+ * stored popup is not touched; this is the copy the visitor sees.
  */
-function retire(popup: PopupConfig, hideBooking: boolean): PopupConfig {
+function retire(
+  popup: PopupConfig,
+  hideBooking: boolean,
+  hiddenPage: (href: string) => boolean,
+): PopupConfig {
+  const blocked = (href: string) => (hideBooking && isBookingHref(href)) || hiddenPage(href);
   const paused: PopupConfig = { ...popup, status: "paused" };
-  if (!hideBooking) return paused;
-  return stripBookingDeep({
+  const cleaned: PopupConfig = {
     ...paused,
-    steps: paused.steps.map((step) => ({ ...step, blocks: step.blocks.flatMap(withoutBookingTargets) })),
-  });
+    steps: paused.steps.map((step) => ({
+      ...step,
+      blocks: step.blocks.flatMap((block) => withoutTargets(block, blocked)),
+    })),
+  };
+  // Booking links inside text are removed as before, and only for booking.
+  return hideBooking ? stripBookingDeep(cleaned) : cleaned;
 }
 
-function withoutBookingTargets(block: ContentBlock): ContentBlock[] {
+function withoutTargets(block: ContentBlock, blocked: (href: string) => boolean): ContentBlock[] {
+  const opens = (action: BlockAction) => action.kind === "openUrl" && blocked(action.href);
+  const closingInstead = (button: PopupButton): PopupButton =>
+    opens(button.action) ? { ...button, action: { kind: "close" } } : button;
   switch (block.type) {
     case "link":
-      return isBookingHref(block.href) ? [] : [block];
+      return blocked(block.href) ? [] : [block];
     case "buttons": {
-      const buttons = block.buttons.filter((button) => !opensBooking(button.action));
+      const buttons = block.buttons.filter((button) => !opens(button.action));
       return buttons.length === 0 ? [] : [{ ...block, buttons }];
     }
     case "choice":
       return [{ ...block, yes: closingInstead(block.yes), no: closingInstead(block.no) }];
     case "form":
-      return [opensBooking(block.onSuccess) ? { ...block, onSuccess: { kind: "close" } } : block];
+      return [opens(block.onSuccess) ? { ...block, onSuccess: { kind: "close" } } : block];
     default:
       return [block];
   }
 }
 
-const opensBooking = (action: BlockAction) => action.kind === "openUrl" && isBookingHref(action.href);
-
-const closingInstead = (button: PopupButton): PopupButton =>
-  opensBooking(button.action) ? { ...button, action: { kind: "close" } } : button;
-
 // Default export so the module host can load this file lazily.
 export default PopupModuleRuntime;

package/src/server/forms-core.ts

@@ -11,6 +11,7 @@
  *  - a field key that already has stored answers can never be removed
  *  - snapshots and audit entries never block the write they describe
  */
+import { checkWebhookUrl } from "./webhook-url-guard";
 import {
   defaultFieldsFor,
   mergeFields,
@@ -410,6 +411,14 @@ export async function saveFormCore(
     }
   }
 
+  // A webhook address is checked when it is saved, not first when a visitor's
+  // submission tries to reach it (where it is checked again, on every hop).
+  const webhookUrl = (data.private_settings as { webhookUrl?: unknown }).webhookUrl;
+  if (typeof webhookUrl === "string" && webhookUrl.trim() !== "") {
+    const checked = checkWebhookUrl(webhookUrl);
+    if (!checked.ok) throw new Error(`Webhook URL: ${checked.message}`);
+  }
+
   const row = {
     key: data.key,
     name: data.name,

package/src/server/forms-delivery-core.ts

@@ -13,6 +13,8 @@
  */
 
 import type { FormFieldDef } from "../forms/field-sets";
+import { safeRequest, WEBHOOK_POLICY, type Resolver, type Transport } from "./outbound-http";
+import { checkWebhookUrl } from "./webhook-url-guard";
 import { sendViaProvider } from "./email-send-core";
 import { logEmail } from "./email-log-core";
 import { appendGoogleSheetRow, DEFAULT_WORKSHEET } from "./google-sheets-core";
@@ -489,6 +491,11 @@ export async function appendToSheetCore(opts: {
  * POST one submission to an external endpoint (CRM, Zapier, Make…).
  * Signed with an optional shared secret so the receiver can verify origin.
  * Never throws: the submission is already stored and must never be lost.
+ *
+ * The endpoint is reached only through the shared outbound policy: https
+ * only, public addresses only (looked up, pinned, every redirect hop checked),
+ * one deadline and a capped reply. A failure says what kind it was; the
+ * endpoint's own reply is never copied into it.
  */
 export async function postWebhookCore(opts: {
   url: string;
@@ -501,11 +508,13 @@ export async function postWebhookCore(opts: {
   createdAt: string;
   payload: Record<string, string>;
   timeoutMs?: number;
+  /** Test seams: a fake resolver and transport instead of the network. */
+  network?: { resolver?: Resolver; transport?: Transport };
 }): Promise<DeliveryResult & { status?: number }> {
   const url = (opts.url ?? "").trim();
   if (!url) return { ok: false, error: "No webhook URL configured." };
-  if (!/^https:\/\//i.test(url))
-    return { ok: false, error: "Webhook URL must start with https://" };
+  const checked = checkWebhookUrl(url);
+  if (!checked.ok) return { ok: false, error: checked.message };
 
   const body = JSON.stringify({
     event: "form.submission",
@@ -530,28 +539,26 @@ export async function postWebhookCore(opts: {
       const { createHmac } = await import("crypto");
       headers["X-Signature"] = createHmac("sha256", secret).update(body).digest("hex");
     } catch {
-      /* signing unavailable — send unsigned rather than dropping the delivery */
+      // A receiver that was promised a signature must never get an unsigned
+      // request it cannot tell from a forgery.
+      return { ok: false, error: "Webhook not sent: it could not be signed." };
     }
   }
 
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 10_000);
-  try {
-    const res = await fetch(url, {
-      method: "POST",
-      headers,
-      body,
-      signal: controller.signal,
-    });
-    if (!res.ok) {
-      const text = (await res.text().catch(() => "")).slice(0, 300);
-      return { ok: false, status: res.status, error: `Webhook [${res.status}]: ${text}` };
-    }
-    return { ok: true, status: res.status };
-  } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e);
-    return { ok: false, error: msg === "The operation was aborted." ? "Webhook timed out." : msg };
-  } finally {
-    clearTimeout(timer);
+  const res = await safeRequest({
+    url: checked.url.toString(),
+    method: "POST",
+    headers,
+    body,
+    policy: { ...WEBHOOK_POLICY, timeoutMs: opts.timeoutMs ?? WEBHOOK_POLICY.timeoutMs },
+    resolver: opts.network?.resolver,
+    transport: opts.network?.transport,
+  });
+  if (!res.ok) {
+    return { ok: false, error: res.failure === "timeout" ? "Webhook timed out." : `Webhook not delivered: ${res.message}` };
+  }
+  if (res.status < 200 || res.status >= 300) {
+    return { ok: false, status: res.status, error: `Webhook answered ${res.status}.` };
   }
+  return { ok: true, status: res.status };
 }

package/src/server/forms-submissions-core.ts

@@ -34,6 +34,7 @@ import {
   type FormsDb,
 } from "./forms-core";
 import { auditAs } from "./audit-core";
+import { redactUrl } from "./outbound-http";
 import {
   evaluateRule,
   isFieldVisible,
@@ -358,7 +359,7 @@ export async function submitFormCore(admin: FormsDb, data: SubmitInput, meta: Re
       formKey: form.key,
       channel: "webhook",
       ok: res.ok,
-      target: eff.webhookUrl,
+      target: redactUrl(eff.webhookUrl),
       error: res.error,
       durationMs: Date.now() - startedAt,
       meta: { status: res.status ?? null },
@@ -1170,10 +1171,12 @@ export async function deliverChannelCore(
       })
       .eq("id", sub.id);
   } else if (channel === "webhook") {
-    target = toOverride?.trim() || eff.webhookUrl;
-    if (!target) throw new Error(`No webhook URL configured for "${form.key}".`);
+    const webhookUrl = toOverride?.trim() || eff.webhookUrl;
+    if (!webhookUrl) throw new Error(`No webhook URL configured for "${form.key}".`);
+    // Recorded without its query string, which may carry the receiver's key.
+    target = redactUrl(webhookUrl);
     result = await postWebhookCore({
-      url: target,
+      url: webhookUrl,
       secret: eff.webhookSecret,
       formKey: form.key,
       formName: form.name,
@@ -1385,7 +1388,7 @@ export async function testWebhookCore(
     formKey: form.key,
     channel: "webhook",
     ok: res.ok,
-    target: url,
+    target: redactUrl(url),
     error: res.error,
     durationMs: Date.now() - startedAt,
     meta: { test: true, status: res.status ?? null },

package/src/server/media-usage-core.ts

@@ -10,6 +10,15 @@
  */
 import { variantSiblings } from "../media/srcset";
 import { cleanFileName, splitExt, uniqueFileName } from "../media/filename";
+import {
+  MEDIA_IMPORT_POLICY,
+  redactUrl,
+  safeRequest,
+  sniffMedia,
+  type MediaKind,
+  type Resolver,
+  type Transport,
+} from "./outbound-http";
 import type { MediaImportResult, MediaUsage, MediaUsageReport } from "../media/usage-types";
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
@@ -42,6 +51,8 @@ export type MediaImportHost = MediaUsageHost & {
   admin: any;
   /** User-Agent sent when fetching remote media. */
   userAgent?: string;
+  /** Test seams: a fake resolver and transport instead of the network. */
+  network?: { resolver?: Resolver; transport?: Transport };
 };
 
 const URL_RE = /https?:\/\/[^\s"'<>)]+/gi;
@@ -154,28 +165,55 @@ export function remoteUrlCandidates(rawUrl: string): string[] {
   return Array.from(candidates);
 }
 
-async function fetchRemoteMedia(rawUrl: string, userAgent: string) {
+/**
+ * Download one remote media file, under the shared outbound policy: public
+ * addresses only (looked up, pinned, every redirect hop checked), one
+ * deadline, a capped size. What it is comes from its first bytes — never from
+ * the server's content type or the address's extension.
+ */
+async function fetchRemoteMedia(
+  rawUrl: string,
+  userAgent: string,
+  network: MediaImportHost["network"],
+): Promise<{ bytes: Uint8Array; kind: MediaKind; resolvedUrl: string } | { error: string }> {
   let lastStatus: number | null = null;
   let lastError: string | null = null;
 
   const headers = {
     "User-Agent": userAgent,
-    Accept:
-      "image/avif,image/webp,image/apng,image/svg+xml,image/*,video/*,application/pdf,*/*;q=0.8",
+    Accept: "image/avif,image/webp,image/apng,image/*,video/*,audio/*,application/pdf;q=0.9",
   };
 
   for (const url of remoteUrlCandidates(rawUrl)) {
-    try {
-      const response = await fetch(url, { headers, redirect: "follow" });
-      if (response.ok) return { response, resolvedUrl: url };
-      lastStatus = response.status;
-    } catch (error) {
-      lastError = error instanceof Error ? error.message : "Network error";
+    const res = await safeRequest({
+      url,
+      method: "GET",
+      headers,
+      policy: MEDIA_IMPORT_POLICY,
+      resolver: network?.resolver,
+      transport: network?.transport,
+    });
+    if (!res.ok) {
+      // Every candidate is a spelling of the same address: a refused one is refused for all.
+      if (res.failure === "blocked-url" || res.failure === "blocked-address") {
+        return { error: `${res.message} (${redactUrl(rawUrl)})` };
+      }
+      lastError = res.message;
+      continue;
+    }
+    if (res.status < 200 || res.status >= 300) {
+      lastStatus = res.status;
+      continue;
+    }
+    const kind = sniffMedia(res.body);
+    if (!kind) {
+      return { error: `Not an image, video, audio or PDF file (${redactUrl(rawUrl)}).` };
     }
+    return { bytes: res.body, kind, resolvedUrl: url };
   }
 
   const reason = lastStatus ? `Fetch failed: ${lastStatus}` : (lastError ?? "Fetch failed");
-  return { error: `${reason} for ${rawUrl}` };
+  return { error: `${reason} (${redactUrl(rawUrl)})` };
 }
 
 /** Scan every CMS content column and report which library files are used where. */
@@ -417,19 +455,21 @@ export async function importRemoteUrlCore(
   const remote = await fetchRemoteMedia(
     data.url,
     host.userAgent ?? "Mozilla/5.0 (compatible; CmsMediaImporter/1.0)",
+    host.network,
   );
   if ("error" in remote) {
     return { path: "", url: "", skipped: true, error: remote.error ?? "Fetch failed" };
   }
 
-  const contentType = remote.response.headers.get("content-type") ?? "application/octet-stream";
-  const buffer = new Uint8Array(await remote.response.arrayBuffer());
+  // Stored as what the bytes are: their sniffed type and its extension.
+  const contentType = remote.kind.mime;
+  const buffer = remote.bytes;
   const urlObj = new URL(remote.resolvedUrl);
   const rawName =
     data.filename ||
     urlObj.pathname.split("/").filter(Boolean).map(safeDecodeURIComponent).pop() ||
     "imported-file";
-  const clean = cleanFileName(rawName, "imported-file");
+  const clean = `${splitExt(cleanFileName(rawName.replace(/[\\/]/g, "-"), "imported-file")).base}${remote.kind.ext}`;
 
   const all = await host.storage.list();
   const existing = all

package/src/server/outbound-address.ts

@@ -0,0 +1,131 @@
+/**
+ * Which network addresses a server-side request may connect to.
+ *
+ * Only globally routable unicast addresses. Everything that names this
+ * machine, its private network, a cloud metadata service, a multicast group
+ * or a reserved block is refused — in IPv4 and IPv6, and in every IPv6 form
+ * that carries an IPv4 address inside it (mapped, compatible, NAT64, 6to4).
+ *
+ * Pure and runtime-independent: it only reads address text.
+ */
+
+/** IPv4 blocks that are not public destinations: [network, prefix length]. */
+const BLOCKED_V4: ReadonlyArray<readonly [string, number]> = [
+  ["0.0.0.0", 8], // "this network"
+  ["10.0.0.0", 8], // private
+  ["100.64.0.0", 10], // carrier-grade NAT
+  ["127.0.0.0", 8], // loopback
+  ["169.254.0.0", 16], // link-local, incl. cloud metadata 169.254.169.254
+  ["172.16.0.0", 12], // private
+  ["192.0.0.0", 24], // IETF protocol assignments
+  ["192.0.2.0", 24], // documentation
+  ["192.88.99.0", 24], // 6to4 relay anycast
+  ["192.168.0.0", 16], // private
+  ["198.18.0.0", 15], // benchmarking
+  ["198.51.100.0", 24], // documentation
+  ["203.0.113.0", 24], // documentation
+  ["224.0.0.0", 4], // multicast
+  ["240.0.0.0", 4], // reserved, incl. broadcast
+];
+
+/** IPv6 blocks that are not public destinations. */
+const BLOCKED_V6: ReadonlyArray<readonly [string, number]> = [
+  ["::", 128], // unspecified
+  ["::1", 128], // loopback
+  ["::ffff:0:0", 96], // IPv4-mapped
+  ["::", 96], // IPv4-compatible (deprecated)
+  ["64:ff9b::", 96], // NAT64
+  ["64:ff9b:1::", 48], // local-use NAT64
+  ["100::", 64], // discard
+  ["2001::", 23], // IETF protocol assignments, incl. Teredo
+  ["2001:db8::", 32], // documentation
+  ["2002::", 16], // 6to4
+  ["3fff::", 20], // documentation
+  ["5f00::", 16], // segment routing
+  ["fc00::", 7], // unique local, incl. fd00:ec2::254 (cloud metadata)
+  ["fe80::", 10], // link-local
+  ["fec0::", 10], // site-local (deprecated)
+  ["ff00::", 8], // multicast
+];
+
+/** An IPv4 address as a 32-bit number, or null. Dotted decimal only (as DNS and URL produce). */
+export function parseIPv4(text: string): number | null {
+  const parts = text.split(".");
+  if (parts.length !== 4) return null;
+  let value = 0;
+  for (const part of parts) {
+    if (!/^(0|[1-9][0-9]{0,2})$/.test(part)) return null;
+    const octet = Number(part);
+    if (octet > 255) return null;
+    value = value * 256 + octet;
+  }
+  return value;
+}
+
+/** An IPv6 address as a 128-bit number, or null. Zone ids are refused. */
+export function parseIPv6(text: string): bigint | null {
+  let address = text.trim().toLowerCase();
+  if (address.startsWith("[") && address.endsWith("]")) address = address.slice(1, -1);
+  if (address === "" || address.includes("%")) return null;
+
+  // An IPv4 tail ("::ffff:1.2.3.4") becomes two hex groups.
+  const lastColon = address.lastIndexOf(":");
+  const tail = address.slice(lastColon + 1);
+  if (tail.includes(".")) {
+    const v4 = parseIPv4(tail);
+    if (v4 === null) return null;
+    address = `${address.slice(0, lastColon + 1)}${(v4 >>> 16).toString(16)}:${(v4 & 0xffff).toString(16)}`;
+  }
+
+  const halves = address.split("::");
+  if (halves.length > 2) return null;
+  const parse = (half: string) => (half === "" ? [] : half.split(":"));
+  const head = parse(halves[0] ?? "");
+  const rest = halves.length === 2 ? parse(halves[1] ?? "") : [];
+  const zeros = 8 - head.length - rest.length;
+  // "::" stands for at least one group of zeros; without it there are exactly eight groups.
+  if (halves.length === 2 ? zeros < 1 : zeros !== 0) return null;
+  const groups = [...head, ...Array<string>(halves.length === 2 ? zeros : 0).fill("0"), ...rest];
+
+  let value = 0n;
+  for (const group of groups) {
+    if (!/^[0-9a-f]{1,4}$/.test(group)) return null;
+    value = (value << 16n) | BigInt(Number.parseInt(group, 16));
+  }
+  return value;
+}
+
+function inV4Block(address: number, [network, prefix]: readonly [string, number]): boolean {
+  const base = parseIPv4(network)!;
+  if (prefix === 0) return true;
+  const shift = 32 - prefix;
+  return Math.floor(address / 2 ** shift) === Math.floor(base / 2 ** shift);
+}
+
+function inV6Block(address: bigint, [network, prefix]: readonly [string, number]): boolean {
+  const base = parseIPv6(network)!;
+  const shift = BigInt(128 - prefix);
+  return address >> shift === base >> shift;
+}
+
+export type AddressFamily = 4 | 6;
+
+/** The family of an address literal, or null when it is not one. */
+export function addressFamily(text: string): AddressFamily | null {
+  if (parseIPv4(text) !== null) return 4;
+  if (parseIPv6(text) !== null) return 6;
+  return null;
+}
+
+/** True only for a globally routable unicast address. Anything unparseable is refused. */
+export function isPublicAddress(text: string): boolean {
+  const v4 = parseIPv4(text);
+  if (v4 !== null) return !BLOCKED_V4.some((block) => inV4Block(v4, block));
+  const v6 = parseIPv6(text);
+  if (v6 !== null) {
+    if (BLOCKED_V6.some((block) => inV6Block(v6, block))) return false;
+    // Only the global unicast range 2000::/3 is public.
+    return v6 >> 125n === 1n;
+  }
+  return false;
+}