@takodotid/circuit 0.34.3 → 0.36.0

package/dist/types/core/address.d.ts

@@ -0,0 +1,44 @@
+import type { Family, IP, IPv4, Prefix } from "../schema";
+/** Address helpers, for checks of your own. */
+export declare class Address {
+    /** IPv4 space another network cannot reach: this host, private, shared, loopback, link-local and documentation, after RFC 6890. */
+    private static readonly NOT_GLOBAL_V4;
+    static family(address: string): Family;
+    /** How many bits an address of the family has: 32 or 128. */
+    static bits(family: Family): number;
+    /** An address as a number, or null when it is not one. */
+    static toNumber(address: string): bigint | null;
+    /** `10.0.0.1/24` to its parts. Throws when it is not an address with a length. */
+    static split(cidr: string): {
+        addr: string;
+        len: number;
+        family: Family;
+    };
+    static isValid(text: string): boolean;
+    static isCidr(text: string): boolean;
+    private static mask;
+    /** A number back to the address it stands for. */
+    static fromNumber(value: bigint, family: Family): IP;
+    /** An address, with or without its length, in one spelling: IPv6 as RFC 5952 writes it, so `2001:DB8:0:0::1` and `2001:db8::1` compare equal. Text that is not an address comes back as it is. */
+    static canonical(text: string): string;
+    /** `10.0.0.1/24` to `10.0.0.0/24`. */
+    static prefixOf(cidr: string): Prefix;
+    /** Is the address or prefix `inner` inside `outer`? */
+    static contains(outer: string, inner: string): boolean;
+    /** The first and last address of a prefix, as numbers. */
+    static range(cidr: string): {
+        first: bigint;
+        last: bigint;
+        family: Family;
+    };
+    /** The fewest prefixes that cover every address from `first` to `last` and nothing else. */
+    static prefixesBetween(first: bigint, last: bigint, family: Family): Prefix[];
+    /** `/25` to `255.255.255.128`. */
+    static netmask(length: number): IPv4;
+    /** `/24` to `0.0.0.255`, the inverted mask some ACLs take. */
+    static wildcard(length: number): IPv4;
+    /** The address with its length dropped. */
+    static host(cidr: string): IP;
+    /** Whether another network can reach the address. IPv6 is global only inside 2000::/3, less documentation space. */
+    static isGlobal(address: string): boolean;
+}

package/dist/types/core/cabling.d.ts

@@ -0,0 +1,41 @@
+import type { Device } from "../schema";
+import type { Finding } from "./define";
+/** A device one of our ports sees at the far end of its cable, over LLDP. */
+export type Neighbor = {
+    /** Our port, by Circuit's name, such as `10g-1`. */
+    port: string;
+    /** The system name the far device sends, its hostname. */
+    system: string;
+    /** The far device's port, as that device spells it, such as `XGigabitEthernet0/0/1`. */
+    remote_port: string;
+};
+export declare class Cabling {
+    /** The end of a state file that holds a device's LLDP neighbors, beside its config. */
+    static readonly SUFFIX = ".lldp.json";
+    /** The file a device's neighbors are saved in. */
+    static path(stateDirectory: string, device: string): string;
+    /** Save what a device sees, sorted, so a file changes only when a neighbor does. */
+    static save(stateDirectory: string, device: string, neighbors: readonly Neighbor[]): void;
+    /** Forget what a device saw, when its neighbors could not be read this time. */
+    static forget(stateDirectory: string, device: string): void;
+    /** What a device saw at its last snapshot, or undefined when its neighbors were never read. */
+    static load(stateDirectory: string, device: string): Neighbor[] | undefined;
+    private static order;
+    /** The device runs LLDP somewhere: on every port, on the interfaces it lists, or on a port that turns it on. */
+    static runsAnywhere(device: Device): boolean;
+    /** The port runs LLDP, by the port's own `lldp`, or else the device's. */
+    static runsOn(device: Device, port: string): boolean;
+    /**
+     * Warnings where LLDP and `link` disagree, from each device's own view: a cable in another port than `link` names, a cable `link` names that LLDP does not see, and another of our devices on a port without `link`.
+     *
+     * Only ports where both ends run LLDP, by the config, are compared, and only on devices whose neighbors were read. LLDP can be off at the far end, so each is a warning.
+     */
+    static compare(devices: readonly Device[], neighbors: ReadonlyMap<string, readonly Neighbor[]>): Finding[];
+    /** A system name is the device's name, alone or with a domain after it. */
+    private static isDevice;
+    private static deviceOf;
+    /** A port LLDP reports, as the far device spells it, is that device's port by Circuit's name. */
+    private static isPort;
+    /** Circuit's name for a port LLDP reports, or the report itself when no port of the device is spelled that way. */
+    private static portOf;
+}

package/dist/types/core/cross-checks.d.ts

@@ -0,0 +1,28 @@
+import type { Device } from "../schema";
+import type { Finding } from "./define";
+export declare class CrossChecks {
+    /** Every rule across devices. */
+    static run(devices: readonly Device[]): Finding[];
+    /** The VLAN ids a port or LAG carries, by how it carries them, so two ends can be compared across devices. */
+    private static carried;
+    /** How a port carries its VLANs, in words: "VLANs 10, 20 tagged and VLAN 30 untagged as native". */
+    private static describeCarried;
+    /** VLAN names by id, for the VLANs a port or LAG carries. */
+    private static vlanNames;
+    /** What a port's settings are kept on: the LAG when the port is a member of one, otherwise the port. */
+    private static carrierOf;
+    /** The plain addresses of one family on an interface, leaving out point-to-point ones. */
+    private static plainAddresses;
+    /** Why the two ends of a cable cannot reach each other by address, or undefined when they can. */
+    private static addressDisagreement;
+    /** A link names a device and port that exist, the far end links back, and both ends carry the same VLANs the same way, with the same MTU, speed and addresses. */
+    private static checkLinks;
+    /** No address is held by two devices in one VRF. Two loopbacks may hold one on purpose, for anycast, so that is a warning. */
+    private static checkAddresses;
+    /** A BGP session to an address another of our devices holds needs that device's session back, in the AS it expects, from the address it names. */
+    private static checkSessions;
+    /** On one segment, a VRRP id has one address and an address has one id, on every device. */
+    private static checkVrrp;
+    /** A GRE or VXLAN tunnel to another of our devices has a tunnel back there, with the endpoints mirrored and, for VXLAN, the same VNI and port. */
+    private static checkTunnels;
+}

package/dist/types/core/define.d.ts

@@ -1,4 +1,4 @@
-import type { ModelName, PlatformName, PortName } from "../adapters/devices/catalog";
+import type { ModelName, PlatformName, PortName } from "../platforms/catalog";
 import type { Device, Secret } from "../schema";
 /** A value resolved by name when a device is applied, from the environment or `.env` beside the config, and through 1Password when that value is an `op://` reference. Never the value itself. */
 export declare const secret: (name: string) => Secret;
@@ -40,18 +40,40 @@ export type Network = {
     asn?: number;
     /** The BGP communities the network defines, printed by `circuit communities` for a looking glass or bgp.tools. */
     communities?: readonly Community[];
+    /**
+     * The site each device is at, such as a data centre or an office, by name. Devices ignore it.
+     *
+     * `circuit netbox` puts the device on the NetBox site of that name, and `circuit librenms` puts it in a LibreNMS device group of that name.
+     */
+    site?: (device: Device) => string;
     /** Keeps the network's PeeringDB record in step with the config: `circuit peeringdb`. Needs `asn`. */
     peeringdb?: {
         /** An API key with write access to the network's record. */
         api_key: Secret;
     };
-    /** Keeps LibreNMS monitoring every device: `circuit librenms`. */
+    /** Keeps LibreNMS monitoring every device, under its name, with its SNMP credentials and location, and in a group for its `site`: `circuit librenms`. */
     librenms?: {
         /** Where LibreNMS is, such as `https://librenms.example.com`. */
         url: string;
-        /** An API token that can add devices. */
+        /** An API token that can add and change devices and device groups. */
         api_token: Secret;
     };
+    /** Keeps NetBox in step with the config: `circuit netbox`. Needs `site`. */
+    netbox?: {
+        /** Where NetBox is, such as `https://netbox.example.com`. */
+        url: string;
+        /** An API token that can write. */
+        api_token: Secret;
+        /** What NetBox needs to know about a device that its config does not say. */
+        device: (device: Device) => NetBoxDevice;
+    };
+};
+/** What NetBox needs to know about a device that its config does not say. */
+export type NetBoxDevice = {
+    /** The device role's name in NetBox, such as `Core switch`. Circuit makes the role when NetBox has none of that name. */
+    role: string;
+    /** The device type's model name in NetBox, made by the platform's vendor. The device's `model` when absent. */
+    device_type?: string;
 };
 /** Declare the network, in `circuit.config.ts`. */
 export declare const defineNetwork: (network: Network) => Network;

package/dist/types/core/project-files.d.ts

@@ -0,0 +1,12 @@
+export declare class ProjectFiles {
+    /** Directories that hold no config of the project's own. */
+    private static readonly SKIPPED;
+    /** The first name written out after a call to defineDevice: the device's own, not that of another device a link, a peer or a tunnel names further on. */
+    private static readonly FIRST_NAME;
+    /** Every TypeScript file of the project, relative to its root, in name order. */
+    static sources(root: string, directory?: string): string[];
+    /** Whether a file's text declares the device: it calls defineDevice and gives it the name, written out whole. */
+    static declaresDevice(text: string, name: string): boolean;
+    /** The project files that declare the device, relative to the root. */
+    static deviceFiles(root: string, name: string, sources?: string[]): string[];
+}

package/dist/types/core/schema-docs.d.ts

@@ -1,5 +1,3 @@
-/** The schema files in reading order, with the title each gets. */
-export declare const SCHEMA_FILES: readonly [readonly ["device.ts", "Device"], readonly ["interfaces.ts", "Ports and interfaces"], readonly ["routing.ts", "Routing"], readonly ["policy.ts", "Route policies"], readonly ["firewall.ts", "Firewall and ACLs"], readonly ["system.ts", "System and management"], readonly ["common.ts", "Common values"]];
 export type Field = {
     path: string;
     type: string;
@@ -12,5 +10,16 @@ export type TypeDoc = {
     includes?: string[];
     fields: Field[];
 };
-/** Every type in each schema file, in the order given. Every file is read first, so a type is known to take parameters wherever it is used. */
-export declare function schemaTypes(sources: readonly string[]): TypeDoc[][];
+export declare class SchemaDocs {
+    /** The schema files in reading order, with the title each gets. */
+    static readonly FILES: readonly [readonly ["device.ts", "Device"], readonly ["interfaces.ts", "Ports and interfaces"], readonly ["routing.ts", "Routing"], readonly ["policy.ts", "Route policies"], readonly ["firewall.ts", "Firewall and ACLs"], readonly ["system.ts", "System and management"], readonly ["common.ts", "Common values"]];
+    /** The text of a JSDoc comment, without its markers, as one paragraph. */
+    private static commentText;
+    /** What a type parameter stands for, where it is not one of the device's names. */
+    private static readonly PARAMETER_MEANING;
+    /** A type as a reader needs it: "name" for each of the device's names, and no parameter list on the schema's own types. */
+    private static withoutGenerics;
+    private static parse;
+    /** Every type in each schema file, in the order given. Every file is read first, so a type is known to take parameters wherever it is used. */
+    static read(sources: readonly string[]): TypeDoc[][];
+}

package/dist/types/core/secrets.d.ts

@@ -1,21 +1,62 @@
-import type { Secret } from "../schema";
-/** Find `.env` and secret files from this directory, the config file's, instead of the working directory. */
-export declare function useRoot(directory: string): void;
-export declare const isSecret: (value: unknown) => value is Secret;
-/** How a reference is written inside a marker: a variable's name, or `file:` and a path. */
-export declare const referenceOf: (secret: Secret) => string;
-/** Where a reference's value comes from, such as `.env` or `1Password, through .env`, without reading it. Undefined when it is set nowhere. */
-export declare function sourceOf(reference: string): string | undefined;
-/** The value behind a reference, as `referenceOf` writes it. */
-declare function valueOf(reference: string): string;
-/** The value of a secret, or of a variable named directly. */
-export declare const resolve: (secret: Secret | string) => string;
-/** How a secret appears in rendered config. Replaced with its value only when sent to a device. */
-export declare const marker: (secret: Secret) => string;
-/** A marker anywhere in a command. Its group is the reference. */
-export declare const MARKER: RegExp;
-/** Replace every marker in a command with its value. */
-export declare const substitute: (text: string) => string;
-/** The value behind one marker's reference, for a platform that takes a secret interactively. */
-export declare const valueOfReference: typeof valueOf;
-export {};
+import type { Network } from "./define";
+import type { Console, Device, IP, Secret } from "../schema";
+/** How a device is logged in to: its management address and SSH port, its connection user and that user's password, and its console. */
+export type DeviceLogin = {
+    /** Absent for a device reached only through its console. */
+    host?: IP;
+    port: number;
+    user: string;
+    /** The value, not a reference. Never print it. */
+    password: string;
+    console?: Console;
+};
+export declare class Secrets {
+    /** The directory of the config file. `.env` and secret files are found from here. */
+    private static root;
+    private static envFile;
+    private static readonly fromOnePassword;
+    /** Every value read in this run, so `scrub` can hide it. */
+    private static readonly revealed;
+    /** What `scrub` puts where a secret was. */
+    static readonly REDACTED = "<redacted>";
+    /** A value in `.env` shorter than this is not hidden: `.env` can hold settings that are not secrets, and hiding a short one would garble the text. */
+    private static readonly SHORTEST_DOTENV_VALUE;
+    /** A marker anywhere in a command. Its group is the reference. */
+    static readonly MARKER: RegExp;
+    /** Find `.env` and secret files from this directory, the config file's, instead of the working directory. */
+    static useRoot(directory: string): void;
+    /** `.env` beside the config, read once. Node and Bun read it the same way they load `.env` themselves: a `#` starts a comment unless the value is quoted. */
+    private static dotenv;
+    /** An unquoted value is cut at a `#`. A `#` after a space is a comment, but one inside the value, as in `abc#def`, would cut a password short and send that to a device, so it stops the run and asks for quotes. */
+    private static refuseCutValues;
+    /** Read a 1Password reference with the 1Password CLI, `op`, once per run. */
+    private static readOnePassword;
+    static isSecret(value: unknown): value is Secret;
+    /** How a reference is written inside a marker: a variable's name, or `file:` and a path. */
+    static referenceOf(secret: Secret): string;
+    /** Where a reference's value comes from, such as `.env` or `1Password, through .env`, without reading it. Undefined when it is set nowhere. */
+    static sourceOf(reference: string): string | undefined;
+    /** The value behind a reference, as `referenceOf` writes it: one marker's reference, for a platform that takes a secret interactively. */
+    static valueOf(reference: string): string;
+    /** The value of a secret, or of a variable named directly: from the environment, `.env`, 1Password or a file. */
+    static reveal(secret: Secret | string): string;
+    /** Every secret reference in a value, however deep, such as a network or one device, as `referenceOf` writes it. */
+    static referencesIn(value: unknown, found?: Set<string>): Set<string>;
+    /**
+     * Text with every secret value Circuit knows replaced by `<redacted>`, before it is printed. Devices echo what they are sent, passwords too.
+     *
+     * Hidden are: each value in `.env` of at least six characters, each value read in this run (1Password reads and secret files among them), each secret of `network` that the environment, `.env` or a file holds, and `extra`. A 1Password reference not read in this run is not read for this.
+     */
+    static scrub(text: string, options?: {
+        network?: Network;
+        extra?: readonly string[];
+    }): string;
+    /** The value behind a reference when it can be had without asking anyone: a 1Password reference only once read in this run. Undefined otherwise. */
+    private static storedValueOf;
+    /** How Circuit logs in to a device: its address, port, connection user, that user's password revealed, and its console. */
+    static loginOf(device: Device): DeviceLogin;
+    /** How a secret appears in rendered config. Replaced with its value only when sent to a device. */
+    static marker(secret: Secret): string;
+    /** Replace every marker in a command with its value. */
+    static substitute(text: string): string;
+}

package/dist/types/core/{graph.d.ts → topology.d.ts}

@@ -2,7 +2,6 @@ import type { Device, Routed } from "../schema";
 import type { Finding } from "./define";
 /** One view of the network. Every edge belongs to one. */
 export type Layer = "l1" | "l2" | "l3" | "bgp" | "ospf" | "tunnels";
-export declare const LAYERS: readonly Layer[];
 /** One of our devices, a segment several of them share, or something outside the network. */
 export type GraphNode = {
     /** Unique among the nodes, such as `device:edge-01` or `as:64501`. */
@@ -63,14 +62,35 @@ export type Holder = {
     /** The VRF the address is in. The default table when absent. */
     vrf?: string;
 };
-export declare const deviceId: (name: string) => string;
-/** An address as a key, so two spellings of one address compare equal. Undefined when it is not an address. */
-export declare function keyOf(address: string | undefined): string | undefined;
-/** Ports, then interfaces, that can hold an address. */
-export declare function routedOf(device: Device): [string, Routed<string>][];
-/** Every valid address the devices hold. An invalid one is left for `validate` to report. */
-export declare function holdersOf(devices: readonly Device[]): Holder[];
-/** The network as a graph. It reads the config only, never a device, and works on a config that does not validate. */
-export declare function graphOf(devices: readonly Device[]): Graph;
-/** Only the edges on these layers, and among those only the ones that touch these devices when any are named. Every device named stays. */
-export declare function only(graph: Graph, layers: readonly Layer[], deviceNames?: readonly string[]): Graph;
+export declare class Topology {
+    static readonly LAYERS: readonly Layer[];
+    static deviceId(name: string): string;
+    /** An address as a key, so two spellings of one address compare equal. Undefined when it is not an address. */
+    static keyOf(address: string | undefined): string | undefined;
+    private static isHostRoute;
+    /** Ports, then interfaces, that can hold an address. */
+    static routedOf(device: Device): [string, Routed<string>][];
+    /** Every valid address the devices hold. An invalid one is left for `validate` to report. */
+    static holders(devices: readonly Device[]): Holder[];
+    private static describeDevice;
+    /** The VLANs a port or LAG carries, by id. */
+    private static carriedBy;
+    private static vlanLabel;
+    /** `l1`, every cable, with a LAG's member cables as one edge; and `l2`, the VLANs each one carries. */
+    private static cables;
+    /** `l3`: prefixes several devices hold an address in, and point-to-point addresses whose far end is another device. */
+    private static segments;
+    /** `bgp`: sessions between our devices, matched by the address each names, and to every AS outside. */
+    private static sessions;
+    /** `ospf`: two devices with OSPF on interfaces in one area and one prefix, neither passive. */
+    private static adjacencies;
+    /** `host:port` or `[host]:port` to the host. */
+    private static endpointHost;
+    /** `tunnels`: GRE and VXLAN tunnels matched by their endpoints, and WireGuard peers matched to the device at the far end. */
+    private static tunnels;
+    private static wireguard;
+    /** The network as a graph. It reads the config only, never a device, and works on a config that does not validate. */
+    static of(devices: readonly Device[]): Graph;
+    /** Only the edges on these layers, and among those only the ones that touch these devices when any are named. Every device named stays. */
+    static only(graph: Graph, layers: readonly Layer[], deviceNames?: readonly string[]): Graph;
+}

package/dist/types/core/utils.d.ts

@@ -0,0 +1,8 @@
+type Merged<T extends readonly object[]> = T extends readonly [infer Head, ...infer Tail extends readonly object[]] ? Head & Merged<Tail> : unknown;
+export declare class Utils {
+    /** Combine records into one, such as a device's own interfaces and those a module derives for it. Unlike spreading them, a name two of them hold is an error rather than one silently replacing the other. */
+    static merge<const T extends readonly Record<string, unknown>[]>(...records: T): Merged<T>;
+    /** Minutes east of UTC an IANA zone is at now, for platforms that take an offset rather than a zone. */
+    static timeZoneOffset(zone: string): number;
+}
+export {};

package/dist/types/core/validator.d.ts

@@ -0,0 +1,19 @@
+import type { Finding, Network } from "./define";
+export declare class Validator {
+    static run(network: Network): Finding[];
+    private static checkDevice;
+    /** What the model's hardware holds, from the catalog. A LAG with too many members is an error; too many switch rules is a warning, since the limit is only roughly known. */
+    private static checkLimits;
+    private static checkVlans;
+    /** Every address is valid, and no address sits on two interfaces of one routing table. Two VRFs may hold the same address. */
+    private static checkAddresses;
+    private static checkPorts;
+    /** A MAC limit is a whole number above 0, and an ethertype filter lets at least one kind in, each once. */
+    private static checkFrames;
+    private static checkInterfaces;
+    private static checkRouting;
+    private static checkPolicies;
+    private static checkFirewall;
+    private static checkServices;
+    private static checkCertificates;
+}

package/dist/types/helpers/bgp.d.ts

@@ -0,0 +1,97 @@
+import type { Community } from "../core/define";
+import type { Device, PolicyRule, Prefix, StandardCommunity } from "../schema";
+/** The prefix lengths a BGP import accepts. */
+export type SanityLengths = {
+    /** Shortest and longest IPv4 prefix accepted. /8 to /24 when absent. */
+    ipv4?: {
+        min: number;
+        max: number;
+    };
+    /** Shortest and longest IPv6 prefix accepted. /16 to /48 when absent. */
+    ipv6?: {
+        min: number;
+        max: number;
+    };
+};
+/** Kinds of neighbor and the number each is tagged with, such as `{ transit: 1, customer: 3 }`. */
+export type CommunityClasses = Readonly<Record<string, number>>;
+/**
+ * A BGP community scheme of large communities, `asn:function:parameter`, in the style of RFC 8195. Each field names the function number your network uses for it; leave out what your network does not offer.
+ *
+ * The type parameters keep the exact numbers you write, so the communities `Bgp.communityScheme` gives back show them in the editor: Asn your AS, LearnedFrom the function of `learned_from`, Classes its classes.
+ */
+export type CommunityScheme<Asn extends number = number, LearnedFrom extends number = number, Classes extends CommunityClasses = CommunityClasses> = {
+    /** Your AS. It is the first part of every community. */
+    asn: Asn;
+    /** Set on import: the kind of neighbor a route came from, `asn:function:class`. */
+    learned_from?: {
+        function: LearnedFrom;
+        classes: Classes;
+    };
+    /** Set on import: the site a route was learned at, `asn:function:site`. `sites` names the sites, for the catalogue. */
+    learned_at?: {
+        function: number;
+        sites?: Readonly<Record<number, string>>;
+    };
+    /** Set on import: the AS a route was learned from, `asn:function:asn`. */
+    learned_from_as?: number;
+    /** A neighbor asks: do not announce the route to an AS, `asn:function:asn`, or to anyone, `asn:function:0`. */
+    do_not_announce?: number;
+    /** A neighbor asks: prepend toward an AS once, twice or three times, `asn:function:asn`. */
+    prepend?: {
+        once?: number;
+        twice?: number;
+        three_times?: number;
+    };
+    /**
+     * A neighbor asks: drop all traffic to this route, `asn:function:0`, usually one address under attack. Your router drops it, and so does every upstream in `upstreams`.
+     *
+     * `upstreams` maps an upstream's AS to its own blackhole community, as its NOC gives it. The route is passed to that upstream with it, so the traffic stops before it reaches your links. An upstream not listed never receives the route.
+     */
+    blackhole?: {
+        function: number;
+        upstreams?: Readonly<Record<number, StandardCommunity>>;
+    };
+};
+/** The class names a scheme declares, or any name when it declares none. */
+type ClassName<Classes extends CommunityClasses> = {} extends Classes ? string : Extract<keyof Classes, string>;
+/** BGP policy: an import sanity policy, a community scheme, and helpers that read a device's BGP neighbors. */
+export declare class Bgp {
+    private static readonly PREPENDS;
+    /** Route policy rules rejecting what no neighbor should send: prefixes too short or too long for the global table, and RPKI invalid. Place it first in an import, or as a policy other imports call. */
+    static sanity(lengths?: SanityLengths): PolicyRule<never, never>[];
+    /** Each BGP neighbor's own policies and role, or its group's. */
+    static neighborPolicies(device: Device): {
+        name: string;
+        address: import("..").IP;
+        role: import("..").BgpRole | undefined;
+        import: string | undefined;
+        export: string | undefined;
+    }[];
+    /** The prefixes an export policy accepts by name. */
+    static offered(device: Device, policy: string | undefined): Prefix[];
+    /**
+     * Policy rules and a catalogue from one community scheme, so the communities your routers set, the ones they act on, and the ones you publish never disagree.
+     *
+     * - `tag(neighborClass, neighborAs, { site, trusted })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. A `trusted` neighbor keeps its requests: do not announce, prepend, blackhole. `site` is needed when the scheme has `learned_at`.
+     * - `actions(neighborAs, { blackhole })`: rules for an export policy toward one neighbor. They act on a customer's action communities, then remove all of yours. Place them before the rules that accept. A blackholed route goes no further, unless `blackhole` names the neighbor's own blackhole community: then it is passed on with it, so the neighbor drops the traffic too.
+     * - `blackhole(prefixSets)`: rules for the import policy of a neighbor you trust with blackholes, before anything that rejects long prefixes. They take a route the neighbor asked to blackhole, but only inside `prefixSets`, its own space, and drop traffic to it here. One rule per set, so one call covers both families.
+     * - `catalogue`: every community, for `communities` in `defineNetwork`.
+     * - `community(fn, parameter)`: one community of yours, for a rule of your own.
+     * - `learned_from`: the community each class is tagged with, by class name, such as `learned_from.customer`.
+     */
+    static communityScheme<const Asn extends number, const LearnedFrom extends number = number, const Classes extends CommunityClasses = {}>(scheme: CommunityScheme<Asn, LearnedFrom, Classes>): {
+        community: <const Fn extends number, const Parameter extends number>(fn: Fn, parameter: Parameter) => `${Asn}:${Fn}:${Parameter}`;
+        learned_from: { readonly [Name in keyof Classes]: `${Asn}:${LearnedFrom}:${Classes[Name]}`; };
+        tag: (neighborClass: ClassName<Classes>, neighborAs: number, options?: {
+            site?: number;
+            trusted?: boolean;
+        }) => PolicyRule<never, never>;
+        actions: (neighborAs: number) => PolicyRule<never, never>[];
+        blackhole: <S extends string>(prefixSets: readonly S[]) => PolicyRule<never, S>[];
+        catalogue: Community[];
+    };
+    /** A word with its article: "a customer", "an upstream". */
+    private static article;
+}
+export {};

package/dist/types/helpers/checks.d.ts

@@ -0,0 +1,32 @@
+import type { Check } from "../core/define";
+/** Where traffic from outside, before anything filters it, may go. Every VLAN not listed as untrusted is trusted, so a VLAN added later is protected without being listed. */
+export type TrustBoundary = {
+    /** VLANs carrying traffic straight from outside: transits, exchanges, an ISP handoff. */
+    untrusted: readonly string[];
+    /** The devices that filter: the only ones that may give an untrusted VLAN an address, and the only ones a port carrying both kinds may face. */
+    routers: readonly string[];
+    /**
+     * Links between two switches that may carry both kinds, each named by its two devices: a site's switch extended to another building, with an exchange's VLAN and its own management on one cable. Neither end gives an untrusted VLAN an address.
+     */
+    extended?: readonly (readonly [string, string])[];
+};
+/** Checks for `checks` in `defineNetwork`, and helpers for checks of your own. */
+export declare class Checks {
+    /**
+     * Every BGP export ends in a reject that matches everything, so nothing leaves by accident. An export to a neighbor whose `role` is `customer` is left out: sending a customer everything you know is what it pays for, and cannot leak a route to the rest of the internet.
+     */
+    static readonly exportsEndInReject: Check;
+    /** A GRE or VXLAN tunnel's local address is outside what the neighbors over it are offered, or their replies route back into the tunnel. */
+    static readonly tunnelsOutsideOffered: Check;
+    /**
+     * A native VLAN is a dead end: native on one trunk (a port or a LAG) of a device at most, and never an access VLAN or a tagged VLAN anywhere on that device. On a switch, a native VLAN is an untagged member of every trunk it is native on, so one native VLAN shared by two trunks joins them: every untagged frame from one leaves on the other.
+     */
+    static readonly nativeVlansAreDeadEnds: Check;
+    /** The VLANs a port carries, untagged or tagged. */
+    static vlansOf(port: {
+        access_vlan?: string;
+        trunk_vlans?: readonly string[];
+    }): string[];
+    /** A check: traffic from outside reaches your own VLANs only through a router. A port or LAG carrying an untrusted VLAN beside any other is on a router or faces one, and only a router gives an untrusted VLAN an address. */
+    static trustBoundary(boundary: TrustBoundary): Check;
+}

package/dist/types/helpers/exchange.d.ts

@@ -0,0 +1,49 @@
+import type { Check } from "../core/define";
+import type { Ethertype, IP, Port, Prefix } from "../schema";
+import { type RouteServer } from "./route-server";
+/** A member of an internet exchange: a network with a port on the fabric and an address on the peering LAN. */
+export type ExchangeMember = {
+    /** Lowercase, and never reused. */
+    name: string;
+    asn: number;
+    /** The member's port on each fabric switch, by switch name. */
+    ports: Readonly<Record<string, string>>;
+    /** Its addresses on the peering LAN. The route servers peer with these. */
+    ipv4?: IP;
+    ipv6?: IP;
+};
+/** An internet exchange's peering LAN, as its fabric carries it. */
+export type InternetExchange<V extends string> = {
+    /** The peering VLAN, by the name the fabric switches give it. */
+    vlan: V;
+    /** The peering LAN's subnets. */
+    lan: {
+        ipv4?: Prefix;
+        ipv6?: Prefix;
+    };
+    /** Addresses on the peering LAN no member may take, such as the route servers'. */
+    reserved?: readonly IP[];
+    /** How much broadcast, multicast and unknown unicast a member port lets through, in percent of its speed. 1 when absent. */
+    storm_percent?: number;
+    /** The most MAC addresses a member port learns, usually 1. No limit when absent. No platform renders it yet, so `validate` refuses it. */
+    mac_limit?: number;
+    /** The only kinds of frame a member port takes in, usually `ipv4`, `ipv6` and `arp`. Every kind when absent. No platform renders it yet, so `validate` refuses it. */
+    ethertypes?: readonly Ethertype[];
+};
+/** An internet exchange's fabric: its member ports, a check of its members, and its route servers' config. */
+export declare class Exchange {
+    /**
+     * Member ports and a check for an internet exchange's fabric.
+     *
+     * - `ports(device)`: every member's port on one switch. A member port is in the peering VLAN and nothing else, takes no part in spanning tree or LLDP, and lets only a trickle of broadcast, multicast and unknown unicast through. With `mac_limit` and `ethertypes`, it also learns that many MAC addresses at most and takes in only those kinds of frame.
+     * - `check`: members never share a name, an AS, an address or a port; every address is inside the peering LAN and not reserved; every member port carries the peering VLAN alone.
+     * - `bird(server)`: one route server's BIRD 2 config, with a session to every member. Write it to a file for the server; Circuit never logs in to a route server.
+     * - `openbgpd(server)`: the same route server's config for OpenBGPD, its `bgpd.conf`, with the same sessions and the same rules.
+     */
+    static build<const V extends string>(exchange: InternetExchange<V>, members: readonly ExchangeMember[]): {
+        ports: (device: string) => Record<string, Port<V, string, string, string>>;
+        check: Check;
+        bird: (server: RouteServer) => string;
+        openbgpd: (server: RouteServer) => string;
+    };
+}

package/dist/types/helpers/filters.d.ts

@@ -0,0 +1,51 @@
+import type { AclRule, FilterRule, Prefix } from "../schema";
+/** What `Filters.antiAmplification` leaves alone. */
+export type AntiAmplificationOptions = {
+    /** Prefixes inside the destinations whose UDP fragments pass: for a host that receives UDP too large for one packet, such as SIP or some VPNs. Every fragment after the first is dropped when absent. */
+    keep_fragments?: readonly Prefix[];
+};
+/** Address lists and edge filters: hardware ACL rules and firewall rules for traffic from outside. */
+export declare class Filters {
+    /** IPv4 sources that never arrive from the internet: loopback, link-local and "this network", after RFC 6890. */
+    static readonly MARTIANS: readonly ["127.0.0.0/8", "169.254.0.0/16", "0.0.0.0/8"];
+    /** IPv4 private space, RFC 1918. */
+    static readonly PRIVATE_RANGES: readonly ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"];
+    /** UDP ports of services that answer a small request with a much larger reply, which attackers use to reflect floods at a victim. A reflected flood arrives from these ports. */
+    static readonly AMPLIFIERS: {
+        readonly qotd: 17;
+        readonly chargen: 19;
+        readonly dns: 53;
+        readonly portmap: 111;
+        readonly ntp: 123;
+        readonly netbios: 137;
+        readonly snmp: 161;
+        readonly cldap: 389;
+        readonly slp: 427;
+        readonly rip: 520;
+        readonly "ms-sql": 1434;
+        readonly ssdp: 1900;
+        readonly ard: 3283;
+        readonly "ws-discovery": 3702;
+        readonly mdns: 5353;
+        readonly coap: 5683;
+        readonly ubiquiti: 10001;
+        readonly memcached: 11211;
+        readonly dvr: 37810;
+    };
+    /** Of the amplifiers, the services hosts do ask across the internet: resolvers, time servers, monitoring. A reply to a real request goes back to the asking port, 1024 or above, or to the service's own port when two servers talk. */
+    private static readonly ASKED;
+    /** TCP flag combinations no legitimate packet carries: name, flags set, flags unset. */
+    private static readonly BAD_TCP_FLAGS;
+    /** Hardware ACL rules dropping traffic arriving on a VLAN from sources that cannot be there: your own space, martians, private ranges. One rule per source. */
+    static antiSpoofing<V extends string>(vlan: V, sources: readonly Prefix[]): AclRule<V>[];
+    /**
+     * Hardware ACL rules dropping reflected UDP floods toward `destinations`, in the switch chip, without limiting anything else.
+     *
+     * - Replies from an amplifier no host asks across the internet are dropped.
+     * - Replies from DNS, NTP and SNMP are dropped only toward a port below 1024 that is not the service's own. A host that runs its own resolver, time server or monitoring keeps its answers. The service's own port passes first, so every drop takes the one range 0 to 1023: a switch chip has few port-range checkers, and on RouterOS a rule past them is invalid with every rule after it.
+     * - The fragments after the first carry no port, and a switch chip reads them as port 0. They are dropped, but toward `keep_fragments`.
+     */
+    static antiAmplification(destinations: readonly Prefix[], options?: AntiAmplificationOptions): AclRule<never>[];
+    /** Firewall rules dropping packets with a TCP flag combination no legitimate packet carries, for a forward chain. */
+    static badTcpFlags(): FilterRule<never, never>[];
+}

package/dist/types/helpers/index.d.ts

@@ -0,0 +1,10 @@
+export { Bgp } from "./bgp";
+export type { CommunityScheme, SanityLengths } from "./bgp";
+export { Checks } from "./checks";
+export type { TrustBoundary } from "./checks";
+export { Exchange } from "./exchange";
+export type { ExchangeMember, InternetExchange } from "./exchange";
+export { Filters } from "./filters";
+export { RouteServerConfig } from "./route-server";
+export type { RouteServer } from "./route-server";
+export type { AntiAmplificationOptions } from "./filters";