@mark1russell7/netdiag 0.0.0-stage → 0.1.0

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,171 @@
+import { BlockList, isIP } from "node:net";
+import { err, ok, type Result } from "@mark1russell7/optional";
+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>>;
+
+interface Range {
+  readonly address: string;
+  readonly prefix: number;
+  readonly family: "ipv4" | "ipv6";
+}
+
+function parseRange(cidr: string): Result<Range, string> {
+  const slash = cidr.indexOf("/");
+  const address = canonicalHost(slash === -1 ? cidr : cidr.slice(0, slash));
+  const family = isIP(address);
+  if (family === 0) return err(`"${cidr}" is not an IP address or a CIDR range.`);
+  const max = family === 4 ? 32 : 128;
+  const prefixText = slash === -1 ? String(max) : cidr.slice(slash + 1);
+  if (!/^\d{1,3}$/.test(prefixText) || Number(prefixText) > max) return err(`"${cidr}" has no prefix from 0 to ${max}.`);
+  return ok({ address, prefix: Number(prefixText), family: family === 4 ? "ipv4" : "ipv6" });
+}
+
+/** 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 = parseRange(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 = parseRange(grant.cidr);
+    if (range.tag === "err" || (range.value.family === "ipv4") !== (family === 4)) continue;
+    const list = new BlockList();
+    list.addSubnet(range.value.address, range.value.prefix, range.value.family);
+    if (list.check(host, family === 4 ? "ipv4" : "ipv6")) 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 };
+}

package/src/target.ts

@@ -0,0 +1,116 @@
+import { isIP } from "node:net";
+import { err, ok, type Result } from "@mark1russell7/optional";
+
+/** The kind of the host of a target: a DNS name, an IPv4 address or an IPv6 address. */
+export type HostKind = "name" | "ipv4" | "ipv6";
+
+/**
+ * A host that a probe examines, and an optional port.
+ *
+ * The host is in its canonical form: lower case, with no final dot and no brackets around an IPv6 address.
+ */
+export interface Target {
+  readonly host: string;
+  readonly kind: HostKind;
+  readonly port?: number | undefined;
+}
+
+/** The ports of the URL schemes that a target can have. */
+const SCHEME_PORTS: ReadonlyMap<string, number> = new Map([
+  ["http:", 80],
+  ["https:", 443],
+  ["ws:", 80],
+  ["wss:", 443],
+  ["dns:", 53],
+  ["tls:", 443],
+]);
+
+/** This function gives the kind of a host in its canonical form. */
+export function hostKind(host: string): HostKind {
+  const family = isIP(host);
+  if (family === 4) return "ipv4";
+  if (family === 6) return "ipv6";
+  return "name";
+}
+
+/** This function gives the canonical form of a host: lower case, with no final dot and no brackets. */
+export function canonicalHost(host: string): string {
+  let text = host.trim().toLowerCase();
+  if (text.startsWith("[") && text.endsWith("]")) text = text.slice(1, -1);
+  if (text.endsWith(".")) text = text.slice(0, -1);
+  return text;
+}
+
+/** This function makes a target from a host and an optional port. */
+export function target(host: string, port?: number): Target {
+  const canonical = canonicalHost(host);
+  return port === undefined ? { host: canonical, kind: hostKind(canonical) } : { host: canonical, kind: hostKind(canonical), port };
+}
+
+/** This function gives the text of a target: `host`, `host:port`, or `[address]:port` for an IPv6 address. */
+export function formatTarget(t: Target): string {
+  const host = t.kind === "ipv6" && t.port !== undefined ? `[${t.host}]` : t.host;
+  return t.port === undefined ? host : `${host}:${t.port}`;
+}
+
+/** This function tells if two targets have the same host and the same port. */
+export function sameTarget(a: Target, b: Target): boolean {
+  return a.host === b.host && a.port === b.port;
+}
+
+const LABEL = /^(?!-)[a-z0-9-]{1,63}(?<!-)$/;
+
+function validName(host: string): boolean {
+  if (host.length === 0 || host.length > 253) return false;
+  return host.split(".").every((label) => LABEL.test(label) || label === "_" || /^_[a-z0-9-]{1,62}$/.test(label));
+}
+
+function portOf(text: string): number | undefined {
+  if (!/^\d{1,5}$/.test(text)) return undefined;
+  const port = Number(text);
+  return port >= 1 && port <= 65535 ? port : undefined;
+}
+
+/**
+ * This function reads a target from the text that a user gives.
+ *
+ * It accepts a URL (`https://example.com/a`), a host (`example.com`) and a host with a port (`example.com:8443`).
+ * It also accepts an IPv4 address, and an IPv6 address in brackets with a port (`[2001:db8::1]:443`).
+ * A URL with a known scheme and no port gets the port of its scheme.
+ */
+export function parseTarget(text: string): Result<Target, string> {
+  const input = text.trim();
+  if (input.length === 0) return err("The target is empty.");
+  if (input.includes("://")) {
+    let url: URL;
+    try {
+      url = new URL(input);
+    } catch {
+      return err(`"${input}" is not a valid URL.`);
+    }
+    const host = canonicalHost(url.hostname);
+    if (host.length === 0) return err(`The URL "${input}" has no host.`);
+    const port = url.port === "" ? SCHEME_PORTS.get(url.protocol) : Number(url.port);
+    return checked(host, port, input);
+  }
+  if (isIP(input) === 6) return checked(canonicalHost(input), undefined, input);
+  const bracket = /^\[([^\]]+)\](?::(.*))?$/.exec(input);
+  if (bracket !== null) {
+    const host = bracket[1] ?? "";
+    if (isIP(host) !== 6) return err(`"${host}" is not an IPv6 address.`);
+    if (bracket[2] === undefined) return checked(canonicalHost(host), undefined, input);
+    const port = portOf(bracket[2]);
+    return port === undefined ? err(`"${bracket[2]}" is not a port from 1 to 65535.`) : checked(canonicalHost(host), port, input);
+  }
+  const colon = input.lastIndexOf(":");
+  if (colon === -1) return checked(canonicalHost(input), undefined, input);
+  const port = portOf(input.slice(colon + 1));
+  if (port === undefined) return err(`"${input.slice(colon + 1)}" is not a port from 1 to 65535.`);
+  return checked(canonicalHost(input.slice(0, colon)), port, input);
+}
+
+function checked(host: string, port: number | undefined, input: string): Result<Target, string> {
+  const kind = hostKind(host);
+  if (kind === "name" && !validName(host)) return err(`"${input}" has no valid host name.`);
+  return ok(port === undefined ? { host, kind } : { host, kind, port });
+}