@mark1russell7/netdiag 0.0.0-stage → 0.1.1

package/src/readers.ts

@@ -0,0 +1,367 @@
+import { addressKind, canonicalAddress } from "./address/index.ts";
+import type { Evidence } from "./diagnosis/model.ts";
+import { isFactOf, type Fact, type FactKind } from "./fact.ts";
+import {
+  DNS_ANSWER,
+  HTTP_RESPONSE,
+  ICMP_ECHO,
+  PATH_REPORT,
+  PATH_TRACE,
+  TCP_CONNECT,
+  TLS_HANDSHAKE,
+  type ConnectOutcome,
+  type DnsAnswer,
+  type DnsOutcome,
+  type EchoOutcome,
+  type HandshakeOutcome,
+  type HttpResponse,
+  type IcmpEcho,
+  type PathReport,
+  type PathTrace,
+  type TcpConnect,
+  type TlsHandshake,
+  type Trust,
+} from "./kinds.ts";
+
+// The readers change facts into evidence for the model. Each value that they give is a value of a feature of the
+// standard catalog, and a test holds it.
+
+/** A fact that gave no evidence, with the reason in plain words. */
+export interface Skipped {
+  readonly fact: string;
+  readonly reason: string;
+}
+
+/** The evidence of a list of facts, and the facts that gave no evidence. */
+export interface Reading {
+  readonly evidence: readonly Evidence[];
+  readonly skipped: readonly Skipped[];
+}
+
+/** The options of `readEvidence`. */
+export interface ReadOptions {
+  /** This function tells if a fact is about the target (`true`) or about a reference host (`false`). The default is `true`. */
+  readonly primary?: ((fact: Fact) => boolean) | undefined;
+  /**
+   * The IP address of the default gateway. The ICMP echo facts of this address give the feature `gateway.reply`. The
+   * ICMP echo facts of the other addresses give the feature `icmp.reply`.
+   */
+  readonly gateway?: string | undefined;
+}
+
+/** A bin of a time or a ratio. A number below `below` gets `value`. The last bin has no limit. */
+export interface Bin {
+  readonly below?: number | undefined;
+  readonly value: string;
+}
+
+/** The bins of the feature `tcp.time`, in milliseconds. A connect of 900 ms or more sent its SYN again. */
+export const TCP_TIME_BINS: readonly Bin[] = [{ below: 150, value: "short" }, { below: 900, value: "long" }, { value: "retry" }];
+
+/** The bins of the feature `tls.ratio`: the time of the TLS handshake divided by the time of the TCP connect. */
+export const TLS_RATIO_BINS: readonly Bin[] = [{ below: 3, value: "low" }, { below: 8, value: "mid" }, { value: "high" }];
+
+/** The bins of the feature `http.ttfb`: the time to the first byte divided by the time of the TCP connect. */
+export const HTTP_TTFB_BINS: readonly Bin[] = [{ below: 4, value: "low" }, { below: 20, value: "mid" }, { value: "high" }];
+
+/**
+ * The smallest time of a TCP connect in a ratio, in milliseconds. On a local link, a ratio with a smaller time measures
+ * only the cost of the cryptography.
+ */
+export const MIN_CONNECT_MS = 1;
+
+/** The value of the feature `dns.answer` for each outcome of a DNS query. `nodata` tells that the name exists. */
+export const DNS_ANSWER_VALUES: Readonly<Partial<Record<DnsOutcome, string>>> = {
+  ok: "ok",
+  nodata: "ok",
+  nxdomain: "nxdomain",
+  servfail: "servfail",
+  refused: "refused",
+  timeout: "timeout",
+  unreachable: "unreachable",
+};
+
+/** The value of the feature `tcp.connect` for each outcome of a TCP connect. */
+export const TCP_CONNECT_VALUES: Readonly<Partial<Record<ConnectOutcome, string>>> = {
+  connected: "connected",
+  refused: "refused",
+  timeout: "timeout",
+  unreachable: "unreachable",
+  reset: "reset",
+};
+
+/**
+ * The value of the feature `tls.handshake` for each outcome of a TLS handshake. The catalog has no value for `not-tls`
+ * and `closed` yet. The lab runs (ND-7) tell which faults cause them.
+ */
+export const TLS_HANDSHAKE_VALUES: Readonly<Partial<Record<HandshakeOutcome, string>>> = {
+  ok: "ok",
+  "cert-error": "cert-error",
+  alert: "alert",
+  timeout: "timeout",
+  reset: "reset",
+};
+
+/** The value of the feature `tls.trust` for each trust. A chain that ends at no root of the store has no public root. */
+export const TLS_TRUST_VALUES: Readonly<Record<Trust, string>> = { public: "public", private: "private", none: "private" };
+
+/** The value of the feature `icmp.reply` for each outcome of the ICMP echo requests to an address. */
+export const ICMP_REPLY_VALUES: Readonly<Partial<Record<EchoOutcome, string>>> = { reply: "reply", none: "none", unreachable: "unreachable" };
+
+/**
+ * The value of the feature `gateway.reply` for each outcome of the ICMP echo requests to the gateway. When this computer
+ * tells that the gateway is unreachable, the gateway gives no reply.
+ */
+export const GATEWAY_REPLY_VALUES: Readonly<Partial<Record<EchoOutcome, string>>> = { reply: "reply", none: "none", unreachable: "none" };
+
+/**
+ * The bins of the feature `path.loss`, on the share of the echo requests with a reply. A share of 1 has no loss. A share
+ * of 0.95 or more has a loss of up to 5 %.
+ */
+export const PATH_LOSS_BINS: readonly Bin[] = [{ below: 0.95, value: "high" }, { below: 1, value: "some" }, { value: "none" }];
+
+/**
+ * The smallest number of echo requests that gives the feature `path.loss`. With 20 requests, one lost request is a loss
+ * of 5 %. With no reply, the feature `icmp.reply` tells the result, not `path.loss`.
+ */
+export const LOSS_MIN_SENT = 20;
+
+/** The suffixes of the names of local networks and of the special-use names (RFC 6761, RFC 6762 and RFC 8375). */
+export const LOCAL_SUFFIXES: readonly string[] = ["local", "localhost", "test", "invalid", "example", "home.arpa", "internal", "lan", "home", "corp", "intranet", "private"];
+
+/** This function gives the value of the first bin that holds `x`. */
+export function binOf(bins: readonly Bin[], x: number): string {
+  for (const bin of bins) if (bin.below === undefined || x < bin.below) return bin.value;
+  throw new RangeError("The last bin has a limit.");
+}
+
+/** This function tells if a name is a local name: a name with one label, or a name with a local suffix. */
+export function isLocalName(name: string): boolean {
+  const lower = name.toLowerCase().replace(/\.$/, "");
+  if (!lower.includes(".")) return true;
+  return LOCAL_SUFFIXES.some((suffix) => lower === suffix || lower.endsWith(`.${suffix}`));
+}
+
+interface Slot {
+  readonly feature: string;
+  readonly primary: boolean;
+  value: string;
+  readonly facts: string[];
+}
+
+interface Facts {
+  readonly dns: Fact<DnsAnswer>[];
+  readonly tcp: Fact<TcpConnect>[];
+  readonly tls: Fact<TlsHandshake>[];
+  readonly http: Fact<HttpResponse>[];
+  readonly icmp: Fact<IcmpEcho>[];
+  readonly report: Fact<PathReport>[];
+  readonly trace: Fact<PathTrace>[];
+}
+
+const READ_KINDS: readonly [keyof Facts, FactKind<unknown>][] = [
+  ["dns", DNS_ANSWER],
+  ["tcp", TCP_CONNECT],
+  ["tls", TLS_HANDSHAKE],
+  ["http", HTTP_RESPONSE],
+  ["icmp", ICMP_ECHO],
+  ["report", PATH_REPORT],
+  ["trace", PATH_TRACE],
+];
+
+/**
+ * This function changes facts into evidence for the model.
+ *
+ * - The reader gives one evidence for each feature, subject and role. When a subject has more facts, the last fact decides.
+ * - For `dns.answer`, one answer `ok` of a name and a resolver decides. For `dns.address`, one private address decides.
+ * - The order of the facts is the order of the runner. A ratio uses the last TCP connect before the handshake or the request.
+ * - An ICMP echo fact gives `gateway.reply` for the gateway, and `icmp.reply` for each other address.
+ * - An ICMP echo fact with replies to `LOSS_MIN_SENT` requests or more gives `path.loss`. A report of `mtr` gives it from
+ *   the last hop, when the address answered there.
+ * - A trace of `traceroute` gives no evidence. The catalog has no feature for the hops of a path.
+ */
+export function readEvidence(facts: readonly Fact[], options: ReadOptions = {}): Reading {
+  const primaryOf = options.primary ?? (() => true);
+  const slots = new Map<string, Slot>();
+  const skipped: Skipped[] = [];
+  const sorted: Facts = { dns: [], tcp: [], tls: [], http: [], icmp: [], report: [], trace: [] };
+
+  for (const fact of facts) {
+    const entry = READ_KINDS.find(([, kind]) => kind.kind === fact.kind);
+    if (entry === undefined) skipped.push({ fact: fact.id, reason: `netdiag has no reader for the kind ${fact.kind}.` });
+    else if (!entry[1].check(fact.value)) skipped.push({ fact: fact.id, reason: `The value does not pass the check of the kind ${fact.kind}.` });
+    else (sorted[entry[0]] as Fact[]).push(fact);
+  }
+
+  /** This function puts a value in the slot of a feature and a group. A `sticky` value stays when a later fact disagrees. */
+  const note = (feature: string, group: string, fact: Fact, value: string, sticky?: string): void => {
+    const primary = primaryOf(fact);
+    const key = `${feature}\u0000${primary ? 1 : 0}\u0000${group}`;
+    const slot = slots.get(key);
+    if (slot === undefined) slots.set(key, { feature, primary, value, facts: [fact.id] });
+    else {
+      if (slot.value !== sticky) slot.value = value;
+      slot.facts.push(fact.id);
+    }
+  };
+  const skip = (fact: Fact, feature: string, outcome: string): void => {
+    skipped.push({ fact: fact.id, reason: `The outcome "${outcome}" of ${fact.kind} has no value of the feature ${feature}.` });
+  };
+
+  for (const fact of sorted.dns) {
+    const answer = fact.value;
+    const group = `${answer.name.toLowerCase()}\u0000${answer.resolver}`;
+    const value = DNS_ANSWER_VALUES[answer.outcome];
+    if (value === undefined) {
+      skip(fact, "dns.answer", answer.outcome);
+      continue;
+    }
+    note("dns.answer", group, fact, value, "ok");
+    if (answer.addresses.length > 0 && !isLocalName(answer.name)) {
+      const kinds = answer.addresses.map(addressKind);
+      note("dns.address", group, fact, kinds.includes("private") ? "private" : "public", "private");
+    }
+  }
+
+  readFamily(sorted, primaryOf, note);
+
+  const subject = (value: { readonly address: string; readonly port: number }): string => `${value.address}\u0000${value.port}`;
+  for (const fact of sorted.tcp) {
+    const connect = fact.value;
+    const value = TCP_CONNECT_VALUES[connect.outcome];
+    if (value === undefined) {
+      skip(fact, "tcp.connect", connect.outcome);
+      continue;
+    }
+    note("tcp.connect", subject(connect), fact, value);
+    if (connect.outcome === "connected") note("tcp.time", subject(connect), fact, binOf(TCP_TIME_BINS, connect.ms));
+  }
+
+  const connectBefore = (fact: Fact, value: { readonly address: string; readonly port: number }): Fact<TcpConnect> | undefined => {
+    let best: Fact<TcpConnect> | undefined;
+    for (const tcp of sorted.tcp) {
+      const same = tcp.value.address === value.address && tcp.value.port === value.port && primaryOf(tcp) === primaryOf(fact);
+      if (!same || tcp.value.outcome !== "connected" || tcp.time.end > fact.time.start) continue;
+      if (best === undefined || tcp.time.end >= best.time.end) best = tcp;
+    }
+    return best;
+  };
+  const ratio = (ms: number, tcp: Fact<TcpConnect>): number => ms / Math.max(tcp.value.ms, MIN_CONNECT_MS);
+
+  for (const fact of sorted.tls) {
+    const handshake = fact.value;
+    const group = `${subject(handshake)}\u0000${handshake.servername ?? ""}`;
+    const value = TLS_HANDSHAKE_VALUES[handshake.outcome];
+    if (value === undefined) {
+      skip(fact, "tls.handshake", handshake.outcome);
+      continue;
+    }
+    note("tls.handshake", group, fact, value);
+    if (handshake.certificate !== undefined) note("tls.trust", group, fact, TLS_TRUST_VALUES[handshake.certificate.trust]);
+    const tcp = handshake.outcome === "ok" || handshake.outcome === "cert-error" ? connectBefore(fact, handshake) : undefined;
+    if (tcp !== undefined) note("tls.ratio", group, fact, binOf(TLS_RATIO_BINS, ratio(handshake.ms, tcp)));
+  }
+
+  for (const fact of sorted.http) {
+    const response = fact.value;
+    const group = [subject(response), response.scheme, response.host, response.method, response.path].join("\u0000");
+    const status = statusValue(response);
+    if (status === undefined) {
+      skip(fact, "http.status", response.outcome === "response" ? `response ${response.status ?? ""}`.trim() : response.outcome);
+      continue;
+    }
+    note("http.status", group, fact, status);
+    const tcp = response.ttfbMs === undefined ? undefined : connectBefore(fact, response);
+    if (tcp !== undefined && response.ttfbMs !== undefined) note("http.ttfb", group, fact, binOf(HTTP_TTFB_BINS, ratio(response.ttfbMs, tcp)));
+  }
+
+  const gateway = options.gateway === undefined ? undefined : canonicalAddress(options.gateway);
+  for (const fact of sorted.icmp) {
+    const echo = fact.value;
+    const address = canonicalAddress(echo.address);
+    const isGateway = address === gateway;
+    const feature = isGateway ? "gateway.reply" : "icmp.reply";
+    const value = (isGateway ? GATEWAY_REPLY_VALUES : ICMP_REPLY_VALUES)[echo.outcome];
+    if (value === undefined) {
+      skip(fact, feature, echo.outcome);
+      continue;
+    }
+    note(feature, address, fact, value);
+  }
+
+  // The feature path.loss comes from ping and from mtr. The facts of both kinds go in the order of the runner.
+  const lossFacts = new Set<Fact>([...sorted.icmp, ...sorted.report]);
+  for (const fact of facts) {
+    if (!lossFacts.has(fact)) continue;
+    const loss = lossOf(fact);
+    if (typeof loss === "string") skipped.push({ fact: fact.id, reason: loss });
+    else if (loss !== undefined) note("path.loss", loss.address, fact, binOf(PATH_LOSS_BINS, loss.share));
+  }
+
+  for (const fact of sorted.trace) {
+    skipped.push({ fact: fact.id, reason: "The catalog has no feature for the hops of a path. The lab runs fit such a feature later." });
+  }
+
+  const evidence = [...slots.values()].map(({ feature, value, primary, facts: ids }) => ({ feature, value, primary, facts: ids }));
+  return { evidence, skipped };
+}
+
+/**
+ * This function gives the share of the probes with an answer, for the feature `path.loss`. It gives a reason when a report
+ * of `mtr` gives no evidence, and `undefined` when an echo fact gives no share.
+ */
+function lossOf(fact: Fact): { readonly address: string; readonly share: number } | string | undefined {
+  if (isFactOf(ICMP_ECHO, fact)) {
+    const echo = fact.value;
+    return echo.received > 0 && echo.sent >= LOSS_MIN_SENT ? { address: canonicalAddress(echo.address), share: echo.received / echo.sent } : undefined;
+  }
+  if (!isFactOf(PATH_REPORT, fact)) return undefined;
+  const report = fact.value;
+  const last = report.hops.at(-1);
+  if (report.outcome !== "reached" || last === undefined) return `The outcome "${report.outcome}" of ${fact.kind} has no value of the feature path.loss.`;
+  if (last.sent < LOSS_MIN_SENT) return `The last hop of the report has ${last.sent} probes. The feature path.loss needs ${LOSS_MIN_SENT} probes or more.`;
+  return { address: canonicalAddress(report.address), share: last.received / last.sent };
+}
+
+function statusValue(response: HttpResponse): string | undefined {
+  if (response.outcome === "error") return undefined;
+  if (response.outcome !== "response") return "none";
+  const status = response.status ?? 0;
+  if (status >= 200 && status < 400) return "ok";
+  if (status >= 400 && status < 500) return "client-error";
+  if (status >= 500 && status < 600) return "server-error";
+  return undefined;
+}
+
+/**
+ * This function gives the feature `ip.family` for a name with IPv4 and IPv6 addresses. It needs a TCP connect to an
+ * address of each family.
+ */
+function readFamily(sorted: Facts, primaryOf: (fact: Fact) => boolean, note: (feature: string, group: string, fact: Fact, value: string) => void): void {
+  const names = new Map<string, { v4: Set<string>; v6: Set<string>; facts: Fact[]; primary: boolean }>();
+  for (const fact of sorted.dns) {
+    if (fact.value.outcome !== "ok") continue;
+    const key = `${primaryOf(fact) ? 1 : 0}\u0000${fact.value.name.toLowerCase()}`;
+    const entry = names.get(key) ?? { v4: new Set<string>(), v6: new Set<string>(), facts: [], primary: primaryOf(fact) };
+    for (const address of fact.value.addresses) (fact.value.record === "A" ? entry.v4 : entry.v6).add(address);
+    entry.facts.push(fact);
+    names.set(key, entry);
+  }
+  for (const [key, entry] of names) {
+    if (entry.v4.size === 0 || entry.v6.size === 0) continue;
+    const tried = sorted.tcp.filter((tcp) => primaryOf(tcp) === entry.primary && (entry.v4.has(tcp.value.address) || entry.v6.has(tcp.value.address)));
+    const works = (family: Set<string>): boolean | undefined => {
+      const connects = tried.filter((tcp) => family.has(tcp.value.address));
+      return connects.length === 0 ? undefined : connects.some((tcp) => tcp.value.outcome === "connected");
+    };
+    const v4 = works(entry.v4);
+    const v6 = works(entry.v6);
+    if (v4 === undefined || v6 === undefined || (!v4 && !v6)) continue;
+    const value = v4 && v6 ? "both" : v4 ? "ipv4-only" : "ipv6-only";
+    const evidenceFacts = [...entry.facts, ...tried];
+    const [first, ...rest] = evidenceFacts;
+    if (first === undefined) continue;
+    note("ip.family", key, first, value);
+    for (const fact of rest) note("ip.family", key, fact, value);
+  }
+}

package/src/run.ts

@@ -0,0 +1,163 @@
+import type { Clock } from "@mark1russell7/algebra/clock";
+import type { Fact, FactTime, Observation } from "./fact.ts";
+import type { Probe, ProbeContext } from "./probe.ts";
+import { decideScope, widen, type Grant, type PortLedger, type Scope } from "./scope.ts";
+import { canonicalHost, formatTarget, type Target } from "./target.ts";
+
+/**
+ * The outcome of one run of a probe.
+ *
+ * - `done`: the probe did its work. The facts include each network failure that it saw.
+ * - `refused`: a peer is not in the scope, so the probe did not start.
+ * - `unavailable`: the probe cannot operate on this computer.
+ * - `failed`: the probe or its parser has a fault. The raw output is present when the run ended.
+ * - `aborted`: the signal stopped the run.
+ */
+export type ProbeOutcome<R> =
+  | { readonly status: "done"; readonly time: FactTime; readonly raw: R; readonly facts: readonly Fact[] }
+  | { readonly status: "refused"; readonly peer: Target; readonly reason: string }
+  | { readonly status: "unavailable"; readonly reason: string }
+  | { readonly status: "failed"; readonly stage: "probe" | "run" | "parse"; readonly error: string; readonly raw?: R | undefined }
+  | { readonly status: "aborted"; readonly reason: string };
+
+/** The wall-clock time of one monotonic time of the runner. */
+export interface ClockOrigin {
+  readonly wall: string;
+  readonly monotonic: number;
+}
+
+/** The options of a runner. */
+export interface RunnerOptions {
+  readonly scope: Scope;
+  readonly clock: Clock;
+  /** The wall-clock time of the start, as an ISO 8601 text. The default is the time of the computer. */
+  readonly wall?: string | undefined;
+}
+
+/**
+ * A runner starts probes in one scope, and keeps the facts of the diagnosis.
+ *
+ * It gives each fact an id in sequence. It keeps the ledger of the ports of each host, for the limit of ports of the scope.
+ */
+export interface Runner {
+  readonly origin: ClockOrigin;
+  scope(): Scope;
+  facts(): readonly Fact[];
+  /** This method adds grants to the scope, for example the addresses of a granted name. */
+  grant(grants: readonly Grant[]): void;
+  run<I, R>(probe: Probe<I, R>, input: I, signal?: AbortSignal): Promise<ProbeOutcome<R>>;
+}
+
+function message(thrown: unknown): string {
+  if (thrown instanceof Error) return thrown.message;
+  return String(thrown);
+}
+
+function abortReason(signal: AbortSignal): string {
+  const reason: unknown = signal.reason;
+  return reason === undefined ? "The signal stopped the run." : message(reason);
+}
+
+/** This function makes a runner. */
+export function createRunner(options: RunnerOptions): Runner {
+  const { clock } = options;
+  const origin: ClockOrigin = { wall: options.wall ?? new Date().toISOString(), monotonic: clock.now() };
+  let scope = options.scope;
+  const facts: Fact[] = [];
+  let ledger: PortLedger = new Map();
+  let next = 1;
+
+  /** This function gives the ledger with the ports of the peers, or the refusal of the first peer out of the scope. */
+  function reserve(peers: readonly Target[]): PortLedger | { readonly peer: Target; readonly reason: string } {
+    const planned = new Map([...ledger].map(([host, ports]) => [host, new Set(ports)]));
+    for (const peer of peers) {
+      const decision = decideScope(scope, peer, planned);
+      if (!decision.allowed) return { peer, reason: decision.reason };
+      if (peer.port === undefined) continue;
+      const host = canonicalHost(peer.host);
+      planned.set(host, (planned.get(host) ?? new Set<number>()).add(peer.port));
+    }
+    return planned;
+  }
+
+  function stamp<I, R>(probe: Probe<I, R>, observations: readonly Observation[], time: FactTime): Fact[] | string {
+    const stamped: Fact[] = [];
+    for (const observation of observations) {
+      const { kind } = observation;
+      if (!probe.kinds.some((known) => known.kind === kind.kind)) return `The probe gave the kind "${kind.kind}", which it does not declare.`;
+      if (!kind.check(observation.value)) return `The value of a "${kind.kind}" fact does not pass the check of its kind.`;
+      stamped.push({
+        id: `f${next + stamped.length}`,
+        kind: kind.kind,
+        layer: kind.layer,
+        subject: observation.subject,
+        time: observation.time ?? time,
+        source: probe.tool === undefined ? { probe: probe.id, version: probe.version } : { probe: probe.id, version: probe.version, tool: probe.tool },
+        value: observation.value,
+      });
+    }
+    return stamped;
+  }
+
+  async function run<I, R>(probe: Probe<I, R>, input: I, signal: AbortSignal = new AbortController().signal): Promise<ProbeOutcome<R>> {
+    if (signal.aborted) return { status: "aborted", reason: abortReason(signal) };
+    let peers: readonly Target[];
+    try {
+      peers = probe.peers(input);
+    } catch (thrown) {
+      return { status: "failed", stage: "probe", error: message(thrown) };
+    }
+    if (probe.mode === "passive" && peers.length > 0) {
+      return { status: "failed", stage: "probe", error: `The passive probe "${probe.id}" gives peers: ${peers.map(formatTarget).join(", ")}.` };
+    }
+    if (probe.mode === "active" && peers.length === 0) {
+      return { status: "failed", stage: "probe", error: `The active probe "${probe.id}" gives no peer.` };
+    }
+    // The decision and the reservation of the ports happen with no await between them. Thus two runs at the same time
+    // cannot both pass the limit of ports. A run that does not start keeps its reservation: the ledger only grows.
+    const reserved = reserve(peers);
+    if ("reason" in reserved) return { status: "refused", peer: reserved.peer, reason: reserved.reason };
+    ledger = reserved;
+    const context: ProbeContext = { clock, signal };
+    let availability;
+    try {
+      availability = await probe.available(context);
+    } catch (thrown) {
+      return { status: "failed", stage: "probe", error: message(thrown) };
+    }
+    if (!availability.available) return { status: "unavailable", reason: availability.reason };
+    if (signal.aborted) return { status: "aborted", reason: abortReason(signal) };
+    const start = clock.now();
+    let raw: R;
+    try {
+      raw = await probe.run(input, context);
+    } catch (thrown) {
+      if (signal.aborted) return { status: "aborted", reason: abortReason(signal) };
+      return { status: "failed", stage: "run", error: message(thrown) };
+    }
+    const time: FactTime = { start, end: clock.now() };
+    let observations: readonly Observation[];
+    try {
+      observations = probe.parse(raw, input);
+    } catch (thrown) {
+      return { status: "failed", stage: "parse", error: message(thrown), raw };
+    }
+    const stamped = stamp(probe, observations, time);
+    if (typeof stamped === "string") return { status: "failed", stage: "parse", error: stamped, raw };
+    facts.push(...stamped);
+    next += stamped.length;
+    return { status: "done", time, raw, facts: stamped };
+  }
+
+  return {
+    origin,
+    scope: () => scope,
+    facts: () => [...facts],
+    grant(grants) {
+      const widened = widen(scope, grants);
+      if (widened.tag === "err") throw new RangeError(widened.error.join(" "));
+      scope = widened.value;
+    },
+    run,
+  };
+}

package/src/scope.ts

@@ -0,0 +1,152 @@
+import { isIP } from "node:net";
+import { err, ok, type Result } from "@mark1russell7/optional";
+import { cidrContains, parseCidr } from "./address/index.ts";
+import { canonicalHost, formatTarget, type Target } from "./target.ts";
+
+/**
+ * The basis of a grant: why a target is in the scope.
+ *
+ * - `named`: the user named the target for this diagnosis.
+ * - `owned`: the user declares that the user owns the network or the host.
+ * - `configured`: the configuration of the computer of the user names it, for example the gateway or the DNS resolver.
+ * - `resolved`: a DNS answer for a granted name gave this address.
+ */
+export type GrantBasis = "named" | "owned" | "configured" | "resolved";
+
+/**
+ * A grant puts targets in the scope.
+ *
+ * A `host` grant puts a DNS name in the scope, and with `subdomains` each name under it. A `range` grant puts the
+ * addresses of a CIDR range in the scope, for example `192.0.2.0/24` or `2001:db8::/32`.
+ */
+export type Grant = HostGrant | RangeGrant;
+
+/** A grant of a DNS name, and with `subdomains` of each name under it. */
+export interface HostGrant {
+  readonly kind: "host";
+  readonly host: string;
+  readonly subdomains?: boolean | undefined;
+  readonly basis: GrantBasis;
+  readonly note?: string | undefined;
+}
+
+/** A grant of the addresses of a CIDR range, for example `192.0.2.0/24` or `2001:db8::/32`. */
+export interface RangeGrant {
+  readonly kind: "range";
+  readonly cidr: string;
+  readonly basis: GrantBasis;
+  readonly note?: string | undefined;
+}
+
+/**
+ * The scope of a diagnosis: the grants, and the largest number of ports for each host.
+ *
+ * An active probe sends packets only to a peer in the scope. The limit of ports stops a port scan: netdiag does no
+ * vulnerability scan.
+ */
+export interface Scope {
+  readonly grants: readonly Grant[];
+  readonly maxPortsPerHost: number;
+}
+
+/** The default limit of the different ports of one host in one runner. */
+export const DEFAULT_MAX_PORTS_PER_HOST = 8;
+
+/** The decision of the scope for one peer of an active probe. A refusal has the reason in plain words. */
+export type ScopeDecision =
+  | { readonly allowed: true; readonly grant: Grant }
+  | { readonly allowed: false; readonly reason: string };
+
+/** The ports that a runner sent packets to, for each host. */
+export type PortLedger = ReadonlyMap<string, ReadonlySet<number>>;
+
+/** This function gives the problems of a grant, or an empty list for a correct grant. */
+export function grantProblems(grant: Grant): string[] {
+  if (grant.kind === "range") {
+    const range = parseCidr(grant.cidr);
+    return range.tag === "err" ? [range.error] : [];
+  }
+  const host = canonicalHost(grant.host);
+  if (host.length === 0) return ["A host grant has an empty host."];
+  if (isIP(host) !== 0) return [`The host grant "${grant.host}" is an IP address. Use a range grant for an address.`];
+  return [];
+}
+
+/**
+ * This function makes a scope from grants. It refuses a grant with a problem, so a typing error cannot widen the scope.
+ *
+ * The default limit of ports is `DEFAULT_MAX_PORTS_PER_HOST`.
+ */
+export function scopeOf(grants: readonly Grant[], options: { readonly maxPortsPerHost?: number } = {}): Result<Scope, string[]> {
+  const problems = grants.flatMap(grantProblems);
+  const maxPortsPerHost = options.maxPortsPerHost ?? DEFAULT_MAX_PORTS_PER_HOST;
+  if (!Number.isInteger(maxPortsPerHost) || maxPortsPerHost < 1) problems.push("The limit of ports for each host is not a positive integer.");
+  if (problems.length > 0) return err(problems);
+  return ok({ grants: [...grants], maxPortsPerHost });
+}
+
+/**
+ * This function gives the grant for a target that the user names. A name gets a host grant. An IP address gets a
+ * range grant of one address.
+ */
+export function namedGrant(t: Target, note?: string): Grant {
+  if (t.kind === "name") return { kind: "host", host: t.host, basis: "named", note };
+  return { kind: "range", cidr: `${t.host}/${t.kind === "ipv4" ? 32 : 128}`, basis: "named", note };
+}
+
+/** This function gives the grant of one address that a DNS answer for a granted name gave. */
+export function resolvedGrant(name: string, address: string, factId?: string): RangeGrant {
+  const host = canonicalHost(address);
+  const family = isIP(host);
+  if (family === 0) throw new RangeError(`"${address}" is not an IP address`);
+  const note = factId === undefined ? `${canonicalHost(name)} resolved to it` : `${canonicalHost(name)} resolved to it (fact ${factId})`;
+  return { kind: "range", cidr: `${host}/${family === 4 ? 32 : 128}`, basis: "resolved", note };
+}
+
+/** This function gives a scope with more grants. The limit of ports does not change. */
+export function widen(scope: Scope, grants: readonly Grant[]): Result<Scope, string[]> {
+  return scopeOf([...scope.grants, ...grants], { maxPortsPerHost: scope.maxPortsPerHost });
+}
+
+function grantFor(scope: Scope, peer: Target): Grant | undefined {
+  const host = canonicalHost(peer.host);
+  const family = isIP(host);
+  for (const grant of scope.grants) {
+    if (grant.kind === "host") {
+      if (family !== 0) continue;
+      const granted = canonicalHost(grant.host);
+      if (host === granted || (grant.subdomains === true && host.endsWith(`.${granted}`))) return grant;
+      continue;
+    }
+    if (family === 0) continue;
+    const range = parseCidr(grant.cidr);
+    if (range.tag === "ok" && cidrContains(range.value, host)) return grant;
+  }
+  return undefined;
+}
+
+/**
+ * This function decides if an active probe can send packets to a peer.
+ *
+ * The peer must match a grant of the scope. A new port of a host must also stay in the limit of ports for each host.
+ * The ledger has the ports that the runner sent packets to before.
+ */
+export function decideScope(scope: Scope, peer: Target, ledger: PortLedger = new Map()): ScopeDecision {
+  const grant = grantFor(scope, peer);
+  if (grant === undefined) {
+    return {
+      allowed: false,
+      reason: `${formatTarget(peer)} is not in the scope. Name it, or add a grant for a network that you own.`,
+    };
+  }
+  if (peer.port !== undefined) {
+    const ports = ledger.get(canonicalHost(peer.host)) ?? new Set<number>();
+    if (!ports.has(peer.port) && ports.size >= scope.maxPortsPerHost) {
+      return {
+        allowed: false,
+        reason: `${formatTarget(peer)} is a new port after ${ports.size} ports of the same host. netdiag does no port scan.`,
+      };
+    }
+  }
+  return { allowed: true, grant };
+}