@takodotid/circuit 0.43.1 → 1.0.0-rc.2

package/src/cli/versions.ts

@@ -0,0 +1,158 @@
+// Each project pins its Circuit in `.circuit/version`, committed. The installed `circuit`, the manager, runs that version for every command in the project, kept once in ~/.circuit/versions/<version>/, so two projects on different versions never clash and the manager updating itself changes no project. A version not here yet is downloaded once the person says yes, signed and checked; one a security advisory affects never runs. Circuit remembers the projects it ran in, so a kept version no project pins any more is removed.
+
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { Releases } from "./releases";
+import { Ui } from "./ui";
+import { VERSION } from "./version";
+
+export class Versions {
+    /** The file at a project's root that names its Circuit version. */
+    static readonly FILE = ".circuit/version";
+
+    /** Set in the environment of a pinned Circuit this one started, so it doesn't start another. */
+    private static readonly RUNNING = "CIRCUIT_PINNED";
+
+    /** The version a project pins, or undefined when it pins none. */
+    static pinned(root: string): string | undefined {
+        const path = join(root, Versions.FILE);
+        if (!existsSync(path)) return undefined;
+
+        const version = readFileSync(path, "utf8").trim();
+        return version || undefined;
+    }
+
+    static pin(root: string, version: string): void {
+        mkdirSync(join(root, ".circuit"), { recursive: true });
+        writeFileSync(join(root, Versions.FILE), `${version}\n`);
+    }
+
+    /** The projects Circuit ran in on this machine, by folder. */
+    private static projectsFile(): string {
+        return join(Releases.home(), "projects.json");
+    }
+
+    /** The projects Circuit remembers. */
+    static known(): string[] {
+        try {
+            const read = JSON.parse(readFileSync(Versions.projectsFile(), "utf8")) as { projects?: unknown };
+            return Array.isArray(read.projects) ? read.projects.filter((root): root is string => typeof root === "string") : [];
+        } catch {
+            return [];
+        }
+    }
+
+    private static save(projects: readonly string[]): void {
+        try {
+            mkdirSync(Releases.home(), { recursive: true });
+            writeFileSync(Versions.projectsFile(), `${JSON.stringify({ projects }, null, 4)}\n`);
+        } catch {}
+    }
+
+    /** Remember a project, so the version it pins is kept. */
+    static remember(root: string): void {
+        const path = resolve(root);
+        const known = Versions.known();
+        if (!known.includes(path)) Versions.save([...known, path]);
+    }
+
+    /**
+     * Remove each kept version no project pins any more: a project is one Circuit ran in that is still there, and its version is what its
+     * `.circuit/version` says now. The app's own version is never kept apart: the app runs it. Gives back the versions removed.
+     */
+    static prune(app: string = VERSION): string[] {
+        const projects = Versions.known().filter((root) => existsSync(join(root, "circuit.ts")));
+        Versions.save(projects);
+
+        const folder = join(Releases.home(), "versions");
+        if (!existsSync(folder)) return [];
+
+        const used = new Set(projects.map((root) => Versions.pinned(root)));
+        const removed: string[] = [];
+        for (const version of readdirSync(folder)) {
+            if (used.has(version) && version !== app) continue;
+            // One still running in another terminal is locked on Windows: it goes on a later run.
+            try {
+                rmSync(join(folder, version), { recursive: true, force: true });
+                removed.push(version);
+            } catch {}
+        }
+        return removed;
+    }
+
+    /** Where a version is kept once downloaded. */
+    static path(version: string): string {
+        return join(Releases.home(), "versions", version, process.platform === "win32" ? "circuit.exe" : "circuit");
+    }
+
+    /** A version's binary: downloaded, signed and checked, once the person says yes, when it is not here yet. Without a person to ask, such as in CI, it is downloaded. */
+    static async ensure(version: string): Promise<string> {
+        const path = Versions.path(version);
+        if (existsSync(path)) return path;
+
+        if (
+            Ui.interactive &&
+            !(await Ui.confirm(`This project runs Circuit ${version}, which is not on this machine yet. Download it?`, true))
+        )
+            Ui.fail(`Not run. This project needs Circuit ${version}; or move it to another version with circuit update.`);
+
+        const bytes = await Ui.step(`Downloading Circuit ${version}`, () => Releases.fetchBinary(version));
+        mkdirSync(join(path, ".."), { recursive: true });
+        writeFileSync(`${path}.part`, bytes);
+        if (process.platform !== "win32") chmodSync(`${path}.part`, 0o755);
+        renameSync(`${path}.part`, path);
+
+        return path;
+    }
+
+    /**
+     * Before a command in a project: a version a security advisory affects never runs, so the person moves the project to a fixed one
+     * first. Then, when the project pins another version than this one, run that version with these arguments, and end with its exit
+     * code. Nothing to do when this Circuit is the one to run.
+     */
+    static async run(root: string, argv: string[]): Promise<void> {
+        if (process.env[Versions.RUNNING] || !Releases.binary()) return;
+
+        let pinned = Versions.pinned(root) ?? VERSION;
+        const { advisories } = await Ui.wait("Checking the project's Circuit for security problems", () => Releases.advisories());
+        const affected = Releases.affecting(advisories, pinned);
+        if (affected.length) {
+            if (!Ui.interactive)
+                Ui.fail(
+                    `This project runs Circuit ${pinned}, which has a security problem: ${affected.map((advisory) => `${advisory.summary} (${advisory.url})`).join("; ")}. Fixed in ${[...new Set(affected.flatMap((advisory) => advisory.patched))].join(" or ")}. Run circuit update in a terminal.`
+                );
+            pinned =
+                (await Versions.updateProject(root, false)) ?? Ui.fail("Not run: the project stays on a version with a security problem.");
+        }
+        if (pinned === VERSION) return;
+
+        const binary = await Versions.ensure(pinned);
+        const result = spawnSync(binary, argv, { stdio: "inherit", env: { ...process.env, [Versions.RUNNING]: "1" } });
+        if (result.error) Ui.fail(`Circuit ${pinned} could not start: ${result.error.message}`);
+        process.exit(result.status ?? 1);
+    }
+
+    /** Whether this Circuit was started by the manager to run a project's version, so it leaves checking and updating to it. */
+    static started(): boolean {
+        return Boolean(process.env[Versions.RUNNING]);
+    }
+
+    /** Move a project to a version the person picks. Gives back the version it moved to. */
+    static async updateProject(root: string, confirmed: boolean): Promise<string | undefined> {
+        const current = Versions.pinned(root) ?? VERSION;
+        const target = await Releases.pick(current, confirmed, "This project");
+        if (!target) return undefined;
+
+        const binary = target === VERSION ? (Releases.binary() ?? (await Versions.ensure(target))) : await Versions.ensure(target);
+        Versions.pin(root, target);
+        Versions.remember(root);
+
+        // The new version writes its own editor types and hook.
+        spawnSync(binary, ["setup", root], { stdio: "inherit", env: { ...process.env, [Versions.RUNNING]: "1" } });
+        Ui.done(`This project runs Circuit ${target} now. Commit ${Versions.FILE}.`);
+
+        Versions.prune();
+        return target;
+    }
+}

package/src/config/address.ts

@@ -0,0 +1,102 @@
+// `address`, a global beside `presets`: standard IP math for a project's own checks, IPv4 prefixes by RFC 4632 and IPv6 by RFC 4291,
+// each address written back in its standard form (RFC 5952 for IPv6). Each helper takes an address alone, a /32 or a /128, or with its length.
+
+import type { Family, IP, Prefix } from "./common";
+
+/** An address alone, such as `10.0.0.1`, or with its length, such as `10.0.0.0/24` or `10.0.0.1/24`. */
+export type AddressOrPrefix = IP | Prefix;
+
+/** An address or prefix as numbers: the address written, and the first and last address of its range. */
+function parse(text: string) {
+    const bad = () => new Error(`address: ${JSON.stringify(text)} is not an IPv4 or IPv6 address, alone or with its length.`);
+    const [ip = "", length, extra] = text.split("/");
+    const v6 = ip.includes(":");
+    const bits = v6 ? 128 : 32;
+    const len = length === undefined ? bits : /^\d{1,3}$/.test(length) ? Number(length) : -1;
+    if (extra !== undefined || len < 0 || len > bits) throw bad();
+
+    let value = 0n;
+    if (v6) {
+        // An IPv4 address may end an IPv6 one, `::ffff:192.0.2.1` (RFC 4291, 2.2): it is the last two groups.
+        let text6 = ip;
+        const tail = /(\d+\.\d+\.\d+\.\d+)$/.exec(ip);
+        if (tail) {
+            const v4 = parse(tail[1]!).address;
+            text6 = `${ip.slice(0, -tail[1]!.length)}${(v4 >> 16n).toString(16)}:${(v4 & 0xffffn).toString(16)}`;
+        }
+        const halves = text6.split("::");
+        const groups = (s: string) => (s === "" ? [] : s.split(":"));
+        const head = groups(halves[0]!);
+        const rest = halves.length === 2 ? groups(halves[1]!) : [];
+        const zeros = 8 - head.length - rest.length;
+        // `::` stands for one or more groups of zeros.
+        if (halves.length > 2 || (halves.length === 2 ? zeros < 1 : zeros !== 0)) throw bad();
+        const all = [...head, ...Array<string>(halves.length === 2 ? zeros : 0).fill("0"), ...rest];
+        if (all.some((g) => !/^[0-9a-f]{1,4}$/i.test(g))) throw bad();
+        for (const g of all) value = (value << 16n) + BigInt(parseInt(g, 16));
+    } else {
+        const parts = ip.split(".");
+        if (parts.length !== 4 || parts.some((p) => !/^\d{1,3}$/.test(p) || Number(p) > 255)) throw bad();
+        for (const p of parts) value = (value << 8n) + BigInt(p);
+    }
+    const size = 1n << BigInt(bits - len);
+    const first = value - (value % size);
+    return { family: (v6 ? "ipv6" : "ipv4") as Family, address: value, first, last: first + size - 1n };
+}
+
+/** A number written as an address of `family`: dotted for IPv4; for IPv6 lowercase, no leading zeros, the longest run of two or more zero groups as `::`, the first if two tie (RFC 5952). */
+function format(family: Family, n: bigint): IP {
+    if (family === "ipv4") return [24n, 16n, 8n, 0n].map((s) => String((n >> s) & 255n)).join(".") as IP;
+    const groups = [112n, 96n, 80n, 64n, 48n, 32n, 16n, 0n].map((s) => ((n >> s) & 0xffffn).toString(16));
+    let best = { at: -1, length: 1 };
+    for (let i = 0; i < 8; i++) {
+        let j = i;
+        while (j < 8 && groups[j] === "0") j++;
+        if (j - i > best.length) best = { at: i, length: j - i };
+    }
+    if (best.at < 0) return groups.join(":") as IP;
+    return `${groups.slice(0, best.at).join(":")}::${groups.slice(best.at + best.length).join(":")}` as IP;
+}
+
+/**
+ * IP math for your own checks, by RFC 4632 (IPv4) and RFC 4291 (IPv6). Each takes an address alone (a /32 or a /128) or with its
+ * length. An address it can't read is an error naming it.
+ */
+export const address = {
+    /** Whether `inner` lies wholly inside `outer`, of the same family: `address.contains("10.0.0.0/8", "10.1.0.0/16")` is true. */
+    contains(outer: AddressOrPrefix, inner: AddressOrPrefix): boolean {
+        const a = parse(outer);
+        const b = parse(inner);
+        return a.family === b.family && a.first <= b.first && b.last <= a.last;
+    },
+
+    /** Whether `a` and `b` share any address: one contains the other. */
+    overlaps(a: AddressOrPrefix, b: AddressOrPrefix): boolean {
+        const x = parse(a);
+        const y = parse(b);
+        return x.family === y.family && x.first <= y.last && y.first <= x.last;
+    },
+
+    /** `ipv4` or `ipv6`. */
+    family(x: AddressOrPrefix): Family {
+        return parse(x).family;
+    },
+
+    /** The address without its length, in its standard form: `address.host("2001:db8:0:0::33/64")` is `2001:db8::33`. */
+    host(x: AddressOrPrefix): IP {
+        const p = parse(x);
+        return format(p.family, p.address);
+    },
+
+    /** The first address of a prefix, its network address: `address.first("192.0.2.33/27")` is `192.0.2.32`. */
+    first(x: AddressOrPrefix): IP {
+        const p = parse(x);
+        return format(p.family, p.first);
+    },
+
+    /** The last address of a prefix: `address.last("192.0.2.32/27")` is `192.0.2.63`. */
+    last(x: AddressOrPrefix): IP {
+        const p = parse(x);
+        return format(p.family, p.last);
+    },
+};

package/src/config/circuit.d.ts

@@ -0,0 +1,30 @@
+// Circuit's functions, `presets` and `address`, declared as globals, so a project's files use them with no import. The project's tsconfig.json
+// includes this file (Circuit writes both). Each is the same as index.ts gives, which Circuit puts on `globalThis` when it reads a project.
+
+import type * as Circuit from "./index";
+
+declare global {
+    /**
+     * Declare a network, in `circuit.ts` at the project's root: `export const as64500 = circuit({ asn, prefixes, sites, checks, integrations })`, named after its AS. Each
+     * device is `as64500.device({ name, include: [sources], ... })` in its own file under `sites/`, typed from the network. Several networks: one `circuit()` each.
+     */
+    const circuit: typeof Circuit.circuit;
+    /** A part written in one file and used in another: `part("device", {...})`, or a rule list such as `part("filter", [...])`. */
+    const part: typeof Circuit.part;
+    /** Items made into one list or one map, by the field it lands in. */
+    const merge: typeof Circuit.merge;
+    /** A value written once and kept as written. */
+    const literal: typeof Circuit.literal;
+    /** A value read by name when a device is applied. */
+    const secret: typeof Circuit.secret;
+    /** A value read from a file when a device is applied. */
+    const secretFile: typeof Circuit.secretFile;
+    /** An address set Circuit fills with every BGP neighbor address of the device. */
+    const bgpNeighbors: typeof Circuit.bgpNeighbors;
+    /** Values every network writes the same way, each from a public standard. */
+    const presets: typeof Circuit.presets;
+    /** IP math for your own checks (RFC 4632, RFC 4291): `address.contains`, `.overlaps`, `.family`, `.host`, `.first`, `.last`. */
+    const address: typeof Circuit.address;
+}
+
+export {};

package/src/config/common.ts

@@ -0,0 +1,65 @@
+// Shapes every group shares: secrets, addresses, ordered rules, lists in a match.
+
+/**
+ * A value kept out of the repository and resolved only when a device is applied.
+ *
+ * `secret("NAME")` reads a secret from the network's secrets file, `.circuit/secrets`, set with `circuit secrets`, or from the environment; a value written as `op://vault/item/field` is read from 1Password. `secretFile("path")` reads a file, relative to the project root, for a value that spans lines such as a private key in PEM. Keep that file out of git.
+ */
+export type Secret =
+    | {
+          /** Name of the secret, as `circuit secrets set NAME` sets it. */
+          readonly secret: string;
+      }
+    | {
+          /** Path of the file with the value, relative to the project root. */
+          readonly secret_file: string;
+      };
+
+/** An IPv4 address, four numbers with dots between them, for example `10.0.0.1`. The type checks the shape; `circuit validate` checks each number is 0 to 255. */
+export type IPv4 = `${number}.${number}.${number}.${number}`;
+
+/** An IPv6 address, groups with colons between them, for example `2001:db8::1`. The type only checks there is a colon; `circuit validate` checks the rest. */
+export type IPv6 = `${string}:${string}`;
+
+/** An address without a length, IPv4 or IPv6, for example `10.0.0.1` or `2001:db8::1`. */
+export type IP = IPv4 | IPv6;
+
+/** A network with its length, for example `10.0.0.0/24` or `2001:db8::/32`. */
+export type Prefix = `${IP}/${number}`;
+
+/** An interface address with its length, for example `10.0.0.1/24` or `2001:db8::1/64`. */
+export type InterfaceAddress = `${IP}/${number}`;
+
+/**
+ * One address, alone or with its length: `10.0.0.1` or `10.0.0.1/24`. A field that names one host takes either, so an address written
+ * once with its length (on a site, for an interface) is used as it is. Circuit writes the address alone there.
+ */
+export type HostAddress = IP | InterfaceAddress;
+
+/** A MAC address, six pairs of hex digits with colons between them, for example `02:00:00:00:00:01`. */
+export type MacAddress = `${string}:${string}:${string}:${string}:${string}:${string}`;
+
+/** An address family. */
+export type Family = "ipv4" | "ipv6";
+
+/** Bits per second, for example `2G`, `500M` or `64k`. */
+export type Rate = `${number}${"k" | "M" | "G"}`;
+
+/** A log severity, most severe first. A threshold includes everything above it. */
+export type Severity = "emergency" | "alert" | "critical" | "error" | "warning" | "notice" | "info" | "debug";
+
+/** A TCP or UDP port number, 1 to 65535. */
+export type PortNumber = number;
+
+/**
+ * Rules where order decides: the first runs first. An ordered list is written whole in one place, the device or one part, and
+ * places rules from other files where they go with `merge`: `merge([own_rule, tenants.rules.router_input, last_rule])`. The same list from two places
+ * is an error naming both.
+ */
+export type Ordered<Rule> = readonly Rule[];
+
+/** One value, or a list of them. In a rule's match, a list matches any of them: Circuit writes one rule for each, where the platform has no list of its own. */
+export type OneOrMore<T> = T | readonly T[];
+
+/** Entries keyed by name, such as VLANs or policies. A name written here is one the device declares: what its other fields may refer to. */
+export type Named<K extends string, V> = { [N in K]?: V };