@gloom-sh/terminal 0.19.2 → 0.19.3

package/src/utils/external-url.ts

@@ -1,14 +1,13 @@
 /**
  * Scheme validation for links handed to the operating system.
  *
- * Opening a link natively means spawning `open` / `xdg-open` / `cmd /c start`
- * with a string that usually came from an external feed: RSS items, prediction
- * markets, news, filings, Substack. Two things make an unvalidated string
- * dangerous there — `file://` launches local content, and Windows routes the
- * argument through cmd's parser.
+ * Opening a link natively means spawning `open` / `xdg-open` / `rundll32` with
+ * a string that usually came from an external feed: RSS items, prediction
+ * markets, news, filings, Substack. `file://` and the other local schemes
+ * launch local content, so only http(s) goes through.
  *
- * Restricting to http(s) removes both. Returns the normalised URL so callers
- * spawn the parsed form rather than the raw input.
+ * Returns the normalised URL so callers spawn the parsed form rather than the
+ * raw input.
  */
 export function safeExternalUrl(value: string): string | null {
   if (!value.trim()) return null;
@@ -22,3 +21,17 @@ export function safeExternalUrl(value: string): string | null {
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
   return parsed.toString();
 }
+
+/**
+ * The command that hands an http(s) link to the system's own opener, with the
+ * link as the last argument, or null for any other link. Windows opens it
+ * through `url.dll` rather than `cmd /c start`: `&`, `|`, `^` and `%` are part
+ * of a link, and a command line would read them as its own.
+ */
+export function systemOpenCommand(rawUrl: string, platform: NodeJS.Platform): string[] | null {
+  const url = safeExternalUrl(rawUrl);
+  if (!url) return null;
+  if (platform === "darwin") return ["open", url];
+  if (platform === "win32") return ["rundll32.exe", "url.dll,FileProtocolHandler", url];
+  return ["xdg-open", url];
+}

package/src/utils/futures-generic.ts

@@ -170,9 +170,9 @@ export function futuresGenericPriceBasis(generic: Pick<FuturesGeneric, "root">):
 
 /**
  * How a futures listing's price reads, whichever form it takes: a generic by
- * its root (VX1 points, TY1 32nds), and a continuous (`ES=F`, `SXO=F`) or
- * listed contract (`SXOZ26.CME`) of an index, sector or industry root in index
- * points, on the root's own venue or with none. The quote keeps its currency
+ * its root (VX1 points, TY1 32nds), and a continuous (`ES=F`, `ZN=F`) or
+ * listed contract (`ZNZ26.CBT`) in the same units as its root's generic,
+ * on the root's own venue or with none. The quote keeps its currency
  * for what a tick is worth. Null for every other listing, a security that
  * shares a root's code on another venue (XAU on Toronto, the XAR ETF) included.
  */
@@ -180,7 +180,7 @@ export function futuresListingPriceBasis(symbol: string, exchange?: string | nul
   const generic = futuresGenericListing(symbol, exchange);
   if (generic) return futuresGenericPriceBasis(generic);
   const listing = futuresListingVenue(symbol, exchange);
-  return listing?.root && ROOT_VENUES[listing.root] === listing.venue && POINT_ROOTS.has(listing.root) ? "points" : null;
+  return listing?.root && ROOT_VENUES[listing.root] === listing.venue ? futuresGenericPriceBasis({ root: listing.root }) : null;
 }
 
 /** Whether a root's date rules count back from first notice or from last trade. */

package/src/utils/http-proxy-upstream.ts

@@ -0,0 +1,124 @@
+import type { ProxiedRequestInit } from "./http-proxy-response";
+
+/** Set by the caller's browser or meaningful only to the hop it came from. */
+const STRIPPED_REQUEST_HEADERS = new Set([
+  "connection",
+  "content-length",
+  "host",
+  "keep-alive",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+]);
+/** Dropped when a redirect leaves the origin the plugin set them for. */
+const CROSS_ORIGIN_STRIPPED_HEADERS = ["authorization", "cookie", "proxy-authorization"];
+/** Dropped when a redirect turns the request into a bodiless GET. */
+const REQUEST_BODY_HEADERS = ["content-encoding", "content-language", "content-location", "content-type"];
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const MAX_REDIRECTS = 5;
+
+/** Whether a proxy may reach a URL: the URL to fetch, or why not and the status to answer with. */
+export type ProxyTargetCheck = (url: string) => ProxyTargetVerdict | Promise<ProxyTargetVerdict>;
+type ProxyTargetVerdict = { url: URL } | { error: string; status: number };
+
+export type ProxyUpstreamResult = { response: Response } | { error: string; status: number };
+
+function upstreamHeaders(raw: Record<string, string>): Headers {
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(raw)) {
+    if (STRIPPED_REQUEST_HEADERS.has(name.toLowerCase())) continue;
+    try {
+      headers.set(name, value);
+    } catch {
+      // Intentional ignore: a header name the runtime refuses is dropped, as a browser drops an unsettable header.
+    }
+  }
+  return headers;
+}
+
+/**
+ * Fetches a proxied plugin request, following redirects one hop at a time
+ * instead of letting `fetch` do it, so every `Location` passes the same
+ * `check` as the first URL. A host that redirects elsewhere (an open
+ * redirect, a moved API) would otherwise carry the request anywhere.
+ *
+ * Method and header handling mirror the Fetch spec: 303, and 301/302 after a
+ * POST, become a bodiless GET; credentials the plugin set are dropped when the
+ * redirect leaves the origin they were meant for.
+ */
+export async function fetchCheckingRedirects(
+  first: URL,
+  init: ProxiedRequestInit,
+  options: { fetch: typeof fetch; check: ProxyTargetCheck; signal: AbortSignal },
+): Promise<ProxyUpstreamResult> {
+  const headers = upstreamHeaders(init.headers);
+  const mode = init.redirect ?? "follow";
+  let url = first;
+  let method = init.method;
+  let body = init.body;
+
+  for (let followed = 0; ; followed += 1) {
+    const response = await options.fetch(url, { method, headers, body, redirect: "manual", signal: options.signal });
+    const location = REDIRECT_STATUSES.has(response.status) ? response.headers.get("location") : null;
+    // "manual" hands the redirect back to the plugin. If it follows it, that
+    // comes back through here as a new request and is checked like one.
+    if (location === null || mode === "manual") return { response };
+
+    await response.body?.cancel().catch(() => { /* Intentional ignore: the redirect's own body is never read, only dropped. */ });
+    if (mode === "error") return { error: "The upstream response was a redirect.", status: 502 };
+    if (followed >= MAX_REDIRECTS) return { error: "The upstream redirected too many times.", status: 502 };
+
+    let next: string;
+    try {
+      next = new URL(location, url).href;
+    } catch {
+      // Intentional ignore: a Location that does not parse is reported as an invalid redirect, never followed.
+      return { error: "The upstream sent an invalid redirect.", status: 502 };
+    }
+    const target = await options.check(next);
+    if ("error" in target) return { error: `The upstream redirect was refused. ${target.error}`, status: 502 };
+
+    if (target.url.origin !== url.origin) {
+      for (const name of CROSS_ORIGIN_STRIPPED_HEADERS) headers.delete(name);
+    }
+    if (
+      (response.status === 303 && method !== "GET" && method !== "HEAD")
+      || ((response.status === 301 || response.status === 302) && method === "POST")
+    ) {
+      method = "GET";
+      body = undefined;
+      for (const name of REQUEST_BODY_HEADERS) headers.delete(name);
+    }
+    url = target.url;
+  }
+}
+
+/**
+ * Reads a body, giving up once it passes `maxBytes`. Returns null when it was
+ * too large, after cancelling the stream so the rest is never pulled.
+ */
+export async function readBytesWithin(body: ReadableStream<Uint8Array> | null, maxBytes: number): Promise<Uint8Array | null> {
+  if (!body) return new Uint8Array(0);
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > maxBytes) {
+      await reader.cancel().catch(() => { /* Intentional ignore: the rest of a body past the cap is dropped unread. */ });
+      return null;
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}

package/src/utils/main-thread-stall.ts

@@ -1,4 +1,4 @@
-import { lastPerfSample, recordPerfSample } from "./perf-marks";
+import { lastPerfSample, recordPerfSample, withoutLastStep } from "./perf-marks";
 
 /** How often the monitor checks in. Short enough to date a stall precisely. */
 const SAMPLE_INTERVAL_MS = 250;
@@ -18,7 +18,21 @@ interface StallSqliteDetail {
   lockWait: boolean;
 }
 
+/**
+ * What a platform's own clocks say at one instant (telemetry/stall-clocks.ts),
+ * in ms from any origin. Null where the platform cannot say.
+ */
+export interface StallClockReading {
+  /** Time the computer was awake: sleep and suspend do not count. */
+  awakeMs: number | null;
+  /** CPU time this thread has used. */
+  threadCpuMs: number | null;
+  /** CPU time the whole process has used, every thread together. */
+  processCpuMs: number | null;
+}
+
 export interface StallEvent {
+  /** How long the thread could not run while the computer was awake. */
   blockedMs: number;
   /** The last measured section before the stall (perf-marks), if any. */
   lastMeasured?: string;
@@ -30,9 +44,18 @@ export interface StallEvent {
   uptimeMs?: number;
   /** Whether the process had finished starting (`markStartupComplete`). */
   phase?: "startup" | "steady";
+  /**
+   * Share of the stall the thread spent on the CPU, 0 to 1: near 1 it was
+   * busy (script, a collection), near 0 it waited (the disk, a lock, a
+   * native call answered on another thread).
+   */
+  threadCpu?: number;
+  /** CPU the process's other threads used meanwhile, in cores (1: one core throughout). */
+  otherCpu?: number;
 }
 
 let stallSink: ((event: StallEvent) => void) | null = null;
+let stallClocks: (() => StallClockReading) | null = null;
 let startupComplete = false;
 
 /**
@@ -47,6 +70,32 @@ export function setStallSink(next: ((event: StallEvent) => void) | null): () =>
   };
 }
 
+/**
+ * How this process reads its platform's clocks (telemetry/stall-clocks.ts):
+ * a stall then says whether the thread was busy or waiting, and the time
+ * the computer slept is not counted as one.
+ */
+export function setStallClocks(next: (() => StallClockReading) | null): () => void {
+  stallClocks = next;
+  return () => {
+    if (stallClocks === next) stallClocks = null;
+  };
+}
+
+function readStallClocks(read: (() => StallClockReading) | null): StallClockReading | null {
+  if (!read) return null;
+  try {
+    return read();
+  } catch {
+    // Intentional ignore: a clock that cannot be read leaves the stall's cause unknown, never the stall unseen.
+    return null;
+  }
+}
+
+function delta(after: number | null | undefined, before: number | null | undefined): number | null {
+  return after == null || before == null ? null : after - before;
+}
+
 /**
  * The process is up: its first screen has its data, or (the desktop app's
  * Bun process) the main window has what it asked for. Stalls before this are
@@ -63,7 +112,7 @@ export function resetStartupCompleteForTests(): void {
 
 function noteStall(event: StallEvent): void {
   try {
-    stallSink?.(event);
+    withoutLastStep(() => stallSink?.(event));
   } catch {
     // Intentional ignore: reporting a freeze must never become one.
   }
@@ -84,6 +133,8 @@ export interface MainThreadStallMonitorOptions {
   schedule?: (callback: () => void, delayMs: number) => unknown;
   cancel?: (handle: unknown) => void;
   report?: (blockedMs: number, context: Omit<StallEvent, "blockedMs">) => void;
+  /** Defaults to the clocks `setStallClocks` installed. */
+  clocks?: () => StallClockReading;
 }
 
 function defaultNow(): number {
@@ -101,6 +152,12 @@ function defaultNow(): number {
  * did it" in a report that only says the app hung for a few seconds, and how
  * long the process had been up, so a slow start reads apart from a hang
  * hours in.
+ *
+ * Where the platform's clocks can be read, the time the computer slept is
+ * taken out (a timer cannot fire then either, and a laptop's lid is not a
+ * freeze), and the stall says how much of it the thread spent on the CPU
+ * and how busy the process's other threads were: busy is script or a
+ * collection, idle on both is a wait on the disk or another program.
  */
 export function startMainThreadStallMonitor(
   options: MainThreadStallMonitorOptions = {},
@@ -117,14 +174,25 @@ export function startMainThreadStallMonitor(
       noteStall({ blockedMs, ...context });
     });
 
+  const clocks = () => readStallClocks(options.clocks ?? stallClocks);
   let previous = now();
+  let previousClocks = clocks();
   const handle = schedule(() => {
     const current = now();
-    const blockedMs = current - previous - intervalMs;
+    const currentClocks = clocks();
+    const elapsedMs = current - previous;
+    const before = previousClocks;
     previous = current;
+    previousClocks = currentClocks;
+    const awakeMs = delta(currentClocks?.awakeMs, before?.awakeMs);
+    // Asleep, the computer runs nothing; only the awake part of the gap was a freeze.
+    const asleepMs = awakeMs == null ? 0 : Math.max(0, elapsedMs - awakeMs);
+    const blockedMs = elapsedMs - asleepMs - intervalMs;
     if (blockedMs < thresholdMs) return;
     const sample = lastPerfSample();
     const sqlite = sample?.name === "sqlite.blocked" ? sqliteDetail(sample.metadata) : undefined;
+    const threadCpuMs = delta(currentClocks?.threadCpuMs, before?.threadCpuMs);
+    const processCpuMs = delta(currentClocks?.processCpuMs, before?.processCpuMs);
     report(blockedMs, {
       ...(sample
         ? { lastMeasured: sample.name, lastMeasuredEndedMsAgo: Math.round(current - sample.endedAt) }
@@ -132,6 +200,10 @@ export function startMainThreadStallMonitor(
       ...(sqlite ? { sqlite } : {}),
       uptimeMs: Math.round(current),
       phase: startupComplete ? "steady" : "startup",
+      ...(threadCpuMs == null ? {} : { threadCpu: Math.min(1, Math.max(0, threadCpuMs / blockedMs)) }),
+      ...(threadCpuMs == null || processCpuMs == null
+        ? {}
+        : { otherCpu: Math.max(0, (processCpuMs - threadCpuMs) / (elapsedMs - asleepMs)) }),
     });
   }, intervalMs);
   if (handle && typeof (handle as { unref?: () => void }).unref === "function") {

package/src/utils/perf-marks.ts

@@ -25,7 +25,10 @@ function now(): number {
 // object, kept by reference.
 let lastSampleName: string | null = null;
 let lastSampleEndedAt = 0;
+let lastSampleDurationMs = 0;
 let lastSampleMetadata: Record<string, unknown> | undefined;
+/** Inside `withoutLastStep`: samples are logged, and none becomes the last step. */
+let quietDepth = 0;
 
 /**
  * The most recent measured section, when it ended and what it was measured
@@ -37,15 +40,28 @@ export function lastPerfSample(): { name: string; endedAt: number; metadata?: Re
   return { name: lastSampleName, endedAt: lastSampleEndedAt, ...(lastSampleMetadata ? { metadata: lastSampleMetadata } : {}) };
 }
 
+/**
+ * Whether the last step ended inside a section that started at `startedAt`
+ * and took at least half of its `durationMs`. That step says more about the
+ * time than the section around it: a SQLite statement that held the thread
+ * through most of a window's request keeps its lock and try facts, where a
+ * short one before the request's real work does not.
+ */
+function lastStepAccountsForSection(startedAt: number, durationMs: number): boolean {
+  return lastSampleName != null && lastSampleEndedAt >= startedAt && lastSampleDurationMs * 2 >= durationMs;
+}
+
 function logSlowPerfSample(
   name: string,
   durationMs: number,
   metadata?: Record<string, unknown>,
   lastStep = true,
+  startedAt?: number,
 ): void {
-  if (lastStep) {
+  if (lastStep && quietDepth === 0 && (startedAt === undefined || !lastStepAccountsForSection(startedAt, durationMs))) {
     lastSampleName = name;
     lastSampleEndedAt = now();
+    lastSampleDurationMs = durationMs;
     lastSampleMetadata = metadata;
   }
   const payload = {
@@ -63,6 +79,20 @@ function logSlowPerfSample(
   }
 }
 
+/**
+ * Runs `fn` without any section it measures becoming the step a later stall
+ * names: reporting a stall reads the windows, and the next stall must still
+ * name the work before it, not the report.
+ */
+export function withoutLastStep<T>(fn: () => T): T {
+  quietDepth += 1;
+  try {
+    return fn();
+  } finally {
+    quietDepth -= 1;
+  }
+}
+
 export function isPerfTraceEnabled(): boolean {
   return traceToStderr;
 }
@@ -81,6 +111,10 @@ export function recordPerfSample(
   logSlowPerfSample(name, durationMs, metadata, options?.lastStep !== false);
 }
 
+/**
+ * Measures `fn`. A step measured inside it that took most of its time stays
+ * the step a stall names (`lastStepAccountsForSection`).
+ */
 export function measurePerf<T>(
   name: string,
   fn: () => T,
@@ -90,7 +124,7 @@ export function measurePerf<T>(
   try {
     return fn();
   } finally {
-    logSlowPerfSample(name, now() - start, metadata);
+    logSlowPerfSample(name, now() - start, metadata, true, start);
   }
 }
 

package/src/utils/private-files.ts

@@ -0,0 +1,141 @@
+import { chmodSync, closeSync, constants, fchmodSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, writeSync } from "fs";
+import { chmod, lstat, mkdir, open } from "fs/promises";
+
+/**
+ * The profile keeps broker credentials (config.json), the Cloud session (the
+ * database), a remote-control token and logs of what the user looked at. On
+ * POSIX its folders are opened only by the user and its files read only by
+ * them, whatever the umask. Windows keeps the profile under the user's own
+ * folder, whose access list already does this, and has no such modes: there
+ * every call here only creates and writes.
+ */
+const PRIVATE_DIR_MODE = 0o700;
+const PRIVATE_FILE_MODE = 0o600;
+
+function usesPosixModes(): boolean {
+  return process.platform !== "win32";
+}
+
+function errorCode(error: unknown): unknown {
+  return (error as { code?: unknown } | null)?.code;
+}
+
+/** Creates `path` and the folders above it as `mkdir -p` does, each one it creates open to the user alone. */
+export function makePrivateDirSync(path: string): void {
+  mkdirSync(path, { recursive: true, mode: PRIVATE_DIR_MODE });
+}
+
+export async function makePrivateDir(path: string): Promise<void> {
+  await mkdir(path, { recursive: true, mode: PRIVATE_DIR_MODE });
+}
+
+/** Leaves an existing folder open to the user alone; a missing one stays missing. */
+export async function restrictDir(path: string): Promise<void> {
+  if (!usesPosixModes()) return;
+  try {
+    await chmod(path, PRIVATE_DIR_MODE);
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+  }
+}
+
+/** Leaves an existing file readable by the user alone; a missing one stays missing. */
+export async function restrictFile(path: string): Promise<void> {
+  if (!usesPosixModes()) return;
+  try {
+    await chmod(path, PRIVATE_FILE_MODE);
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+  }
+}
+
+export function restrictFileSync(path: string): void {
+  if (!usesPosixModes()) return;
+  try {
+    chmodSync(path, PRIVATE_FILE_MODE);
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+  }
+}
+
+/** The code of the error a private write throws when its path names a device, a pipe or anything else but a plain file. */
+export const NOT_A_PLAIN_FILE = "ENOTPLAINFILE";
+
+function notAPlainFile(path: string): Error {
+  return Object.assign(new Error(`${path} is not a plain file.`), { code: NOT_A_PLAIN_FILE });
+}
+
+function isALink(path: string): Error {
+  return Object.assign(new Error(`${path} is a link.`), { code: "ELOOP" });
+}
+
+/**
+ * Opened to write without following a link (`O_NOFOLLOW`, which fails with
+ * ELOOP) or waiting on a pipe no one reads (`O_NONBLOCK`). Windows has
+ * neither flag; a link is refused there by looking first.
+ */
+function privateOpenFlags(append: boolean): number {
+  return constants.O_WRONLY | constants.O_CREAT | (append ? constants.O_APPEND : 0)
+    | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
+}
+
+function refuseWindowsLinkSync(path: string): void {
+  if (usesPosixModes()) return;
+  try {
+    if (lstatSync(path).isSymbolicLink()) throw isALink(path);
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+  }
+}
+
+async function refuseWindowsLink(path: string): Promise<void> {
+  if (usesPosixModes()) return;
+  try {
+    if ((await lstat(path)).isSymbolicLink()) throw isALink(path);
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+  }
+}
+
+/**
+ * Writes `contents` to a plain file only the user can read: created so, and
+ * an existing file made so before anything is written to it, so the new
+ * contents are never readable by anyone else. A link, a device or a pipe in
+ * its place is refused, never written through. `append` adds to the end.
+ */
+export function writePrivateFileSync(path: string, contents: string | Uint8Array, options: { append?: boolean } = {}): void {
+  refuseWindowsLinkSync(path);
+  const fd = openSync(path, privateOpenFlags(options.append === true), PRIVATE_FILE_MODE);
+  try {
+    if (!fstatSync(fd).isFile()) throw notAPlainFile(path);
+    if (usesPosixModes()) {
+      try {
+        fchmodSync(fd, PRIVATE_FILE_MODE);
+      } catch {
+        // Intentional ignore: a disk without POSIX modes (FAT, some network shares) cannot restrict the file; the write still goes through.
+      }
+    }
+    if (!options.append) ftruncateSync(fd, 0);
+    const bytes = typeof contents === "string" ? Buffer.from(contents, "utf-8") : contents;
+    for (let written = 0; written < bytes.length;) written += writeSync(fd, bytes, written);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export async function writePrivateFile(path: string, contents: string | Uint8Array): Promise<void> {
+  await refuseWindowsLink(path);
+  const handle = await open(path, privateOpenFlags(false), PRIVATE_FILE_MODE);
+  try {
+    if (!(await handle.stat()).isFile()) throw notAPlainFile(path);
+    if (usesPosixModes()) {
+      await handle.chmod(PRIVATE_FILE_MODE).catch(() => {
+        // Intentional ignore: a disk without POSIX modes (FAT, some network shares) cannot restrict the file; the write still goes through.
+      });
+    }
+    await handle.truncate(0);
+    await handle.writeFile(contents);
+  } finally {
+    await handle.close();
+  }
+}

package/src/utils/public-address.ts

@@ -0,0 +1,99 @@
+import { isIP } from "net";
+
+/**
+ * Whether an IP address is on the public internet: not this machine, not a
+ * private or link-local network, not a carrier-grade NAT (a VPN's own
+ * addresses), documentation, multicast or reserved block. A request made for
+ * a page that only reads public data (the pane screenshot's HTTP bridge) is
+ * refused for anything else, so a URL it is handed cannot reach a service on
+ * the user's machine or network.
+ */
+export function isPublicAddress(address: string): boolean {
+  const bare = address.replace(/^\[|\]$/g, "").replace(/%.*$/, "");
+  const family = isIP(bare);
+  if (family === 4) return isPublicIpv4(parseIpv4(bare)!);
+  if (family === 6) {
+    const groups = parseIpv6(bare);
+    return groups !== null && isPublicIpv6(groups);
+  }
+  return false;
+}
+
+function parseIpv4(address: string): number[] | null {
+  const parts = address.split(".").map(Number);
+  return parts.length === 4 && parts.every((part) => Number.isInteger(part) && part >= 0 && part <= 255) ? parts : null;
+}
+
+/** [first octet, second octet, prefix bits of the second octet that count] per non-public block. */
+const IPV4_BLOCKS: ReadonlyArray<readonly [number, number, number]> = [
+  [0, 0, 0], // 0.0.0.0/8, this network
+  [10, 0, 0], // 10.0.0.0/8, private
+  [100, 64, 2], // 100.64.0.0/10, carrier-grade NAT
+  [127, 0, 0], // 127.0.0.0/8, loopback
+  [169, 254, 8], // 169.254.0.0/16, link-local
+  [172, 16, 4], // 172.16.0.0/12, private
+  [192, 168, 8], // 192.168.0.0/16, private
+  // 198.18.0.0/15 (benchmarking) stays public: proxies that answer every name with a stand-in address use it.
+];
+
+function isPublicIpv4([a, b, c]: number[]): boolean {
+  for (const [first, second, bits] of IPV4_BLOCKS) {
+    if (a !== first) continue;
+    if (bits === 0) return false;
+    const mask = (0xff << (8 - bits)) & 0xff;
+    if ((b! & mask) === second) return false;
+  }
+  // 192.0.0.0/24 protocol assignments, 192.0.2.0/24, 198.51.100.0/24 and 203.0.113.0/24 documentation.
+  if (a === 192 && b === 0 && (c === 0 || c === 2)) return false;
+  if (a === 198 && b === 51 && c === 100) return false;
+  if (a === 203 && b === 0 && c === 113) return false;
+  // 224.0.0.0/4 multicast, 240.0.0.0/4 reserved and the broadcast address.
+  return a! < 224;
+}
+
+/** Eight 16-bit groups, or null when the text is not one IPv6 address. */
+function parseIpv6(address: string): number[] | null {
+  let text = address.toLowerCase();
+  const tail: number[] = [];
+  const dotted = /:(\d+\.\d+\.\d+\.\d+)$/.exec(text);
+  if (dotted) {
+    const v4 = parseIpv4(dotted[1]!);
+    if (!v4) return null;
+    tail.push((v4[0]! << 8) | v4[1]!, (v4[2]! << 8) | v4[3]!);
+    // `::1.2.3.4` keeps its `::`; `1:2:3:4:5:6:1.2.3.4` loses the colon before the dotted part.
+    const before = text.slice(0, dotted.index);
+    text = before.endsWith(":") ? `${before}:` : before;
+  }
+  const halves = text.split("::");
+  if (halves.length > 2) return null;
+  const read = (half: string) => (half ? half.split(":").map((group) => Number.parseInt(group, 16)) : []);
+  const head = read(halves[0]!);
+  const rest = halves.length === 2 ? read(halves[1]!) : [];
+  const known = head.length + rest.length + tail.length;
+  if (halves.length === 1 && known !== 8) return null;
+  if (halves.length === 2 && known > 7) return null;
+  const groups = [...head, ...Array(8 - known).fill(0), ...rest, ...tail];
+  return groups.every((group) => Number.isInteger(group) && group >= 0 && group <= 0xffff) ? groups : null;
+}
+
+function embeddedIpv4(high: number, low: number): number[] {
+  return [high >> 8, high & 0xff, low >> 8, low & 0xff];
+}
+
+function isPublicIpv6(groups: number[]): boolean {
+  const [g0, g1, g2, g3, g4, g5, g6, g7] = groups as [number, number, number, number, number, number, number, number];
+  // ::ffff:a.b.c.d, an IPv4 address written as IPv6: as public as the address it carries.
+  if (g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0xffff) return isPublicIpv4(embeddedIpv4(g6, g7));
+  // ::, ::1 and the retired IPv4-compatible block.
+  if (g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0) return false;
+  // 64:ff9b::/96 NAT64 carries an IPv4 address; 64:ff9b:1::/48 is a local NAT64.
+  if (g0 === 0x64 && g1 === 0xff9b) return g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0 && isPublicIpv4(embeddedIpv4(g6, g7));
+  // 2002::/16 6to4 carries an IPv4 address in its next 32 bits.
+  if (g0 === 0x2002) return isPublicIpv4(embeddedIpv4(g1, g2));
+  // 100::/64 discard.
+  if (g0 === 0x100 && g1 === 0 && g2 === 0 && g3 === 0) return false;
+  // 2001::/23 protocol assignments (Teredo among them) and 2001:db8::/32 documentation.
+  if (g0 === 0x2001 && (g1 < 0x200 || g1 === 0xdb8)) return false;
+  // fc00::/7 unique local, fe80::/10 link-local, fec0::/10 site-local, ff00::/8 multicast.
+  return (g0 & 0xfe00) !== 0xfc00 && (g0 & 0xffc0) !== 0xfe80 && (g0 & 0xffc0) !== 0xfec0 && (g0 & 0xff00) !== 0xff00;
+}