@takodotid/circuit 0.34.2 → 0.35.0

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

@@ -1,34 +0,0 @@
-import type { Family } from "../schema";
-export declare const familyOf: (address: string) => Family;
-/** An address as a number, or null when it is not one. */
-export declare function parse(address: string): bigint | null;
-/** `10.0.0.1/24` to its parts. Throws when it is not an address with a length. */
-export declare function split(cidr: string): {
-    addr: string;
-    len: number;
-    family: Family;
-};
-export declare const isAddress: (text: string) => boolean;
-export declare function isCidr(text: string): boolean;
-/** `10.0.0.1/24` to `10.0.0.0/24`. */
-export declare function network(cidr: string): string;
-/** Is the address or prefix `inner` inside `outer`? */
-export declare function contains(outer: string, inner: string): boolean;
-/** A number back to the address it stands for. */
-export declare const formatAddress: (value: bigint, family: Family) => string;
-/** The first and last address of a prefix, as numbers. */
-export declare function rangeOf(cidr: string): {
-    first: bigint;
-    last: bigint;
-    family: Family;
-};
-/** The fewest prefixes that cover every address from `first` to `last` and nothing else. */
-export declare function prefixesBetween(first: bigint, last: bigint, family: Family): string[];
-/** `/25` to `255.255.255.128`. */
-export declare const netmask: (length: number) => string;
-/** `/24` to `0.0.0.255`, the inverted mask some ACLs take. */
-export declare const wildcard: (length: number) => string;
-/** The address with its length dropped. */
-export declare const host: (cidr: string) => string;
-/** Whether another network can reach the address. IPv6 is global only inside 2000::/3, less documentation space. */
-export declare function isGlobal(address: string): boolean;

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

@@ -1,6 +0,0 @@
-/** Every TypeScript file of the project, relative to its root, in name order. */
-export declare function projectSources(root: string, directory?: string): string[];
-/** Whether a file's text declares the device: it calls defineDevice and gives it the name, written out whole. */
-export declare function declaresDevice(text: string, name: string): boolean;
-/** The project files that declare the device, relative to the root. */
-export declare function deviceFiles(root: string, name: string, sources?: string[]): string[];

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

@@ -1,4 +0,0 @@
-type Merged<T extends readonly object[]> = T extends readonly [infer Head, ...infer Tail extends readonly object[]] ? Head & Merged<Tail> : unknown;
-/** Combine records into one. Unlike spreading them, a name two of them hold is an error rather than one silently replacing the other. */
-export declare function merge<const T extends readonly Record<string, unknown>[]>(...records: T): Merged<T>;
-export {};

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

@@ -1,2 +0,0 @@
-/** Minutes east of UTC an IANA zone is at now, for platforms that take an offset rather than a zone. */
-export declare function offset(zone: string): number;

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

@@ -1,2 +0,0 @@
-import type { Finding, Network } from "./define";
-export declare function validate(network: Network): Finding[];

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

@@ -1,183 +0,0 @@
-import type { Check, Community } from "../core/define";
-import type { AclRule, Device, FilterRule, IP, PolicyRule, Port, Prefix } from "../schema";
-/** IPv4 sources that never arrive from the internet: loopback, link-local and "this network", after RFC 6890. */
-export declare const MARTIANS: readonly ["127.0.0.0/8", "169.254.0.0/16", "0.0.0.0/8"];
-/** IPv4 private space, RFC 1918. */
-export declare const PRIVATE_RANGES: readonly ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"];
-/** 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. */
-export declare const antiSpoofing: <V extends string>(vlan: V, sources: readonly Prefix[]) => AclRule<V>[];
-/** 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. */
-export declare const 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;
-};
-/** What `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[];
-};
-/**
- * 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`.
- */
-export declare function 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. */
-export declare const badTcpFlags: () => FilterRule<never, never>[];
-/** 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;
-    };
-};
-/** 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. */
-export declare function bgpSanity(lengths?: SanityLengths): PolicyRule<never, never>[];
-/** Each BGP neighbor's own policies and role, or its group's. */
-export declare function neighborPolicies(device: Device): {
-    name: string;
-    address: string;
-    role: import("..").BgpRole | undefined;
-    import: string | undefined;
-    export: string | undefined;
-}[];
-/** The prefixes an export policy accepts by name. */
-export declare function offered(device: Device, policy: string | undefined): string[];
-/**
- * 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.
- */
-export declare const exportsEndInReject: Check;
-/** The VLANs a port carries, untagged or tagged. */
-export declare const vlansOf: (port: {
-    access_vlan?: string;
-    trunk_vlans?: readonly string[];
-}) => string[];
-/** 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])[];
-};
-/** 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. */
-export declare const trustBoundary: (boundary: TrustBoundary) => 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. */
-export declare const tunnelsOutsideOffered: Check;
-/**
- * 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.
- */
-export type CommunityScheme<Class extends string = string> = {
-    /** Your AS. It is the first part of every community. */
-    asn: number;
-    /** Set on import: the kind of neighbor a route came from, `asn:function:class`. */
-    learned_from?: {
-        function: number;
-        classes: Readonly<Record<Class, number>>;
-    };
-    /** 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, string>>;
-    };
-};
-/**
- * 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`.
- */
-export declare function communityScheme<const Class extends string>(scheme: CommunityScheme<Class>): {
-    community: (fn: number, parameter: number | string) => string;
-    tag: (neighborClass: Class, 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 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;
-};
-/**
- * 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.
- * - `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.
- */
-export declare function internetExchange<const V extends string>(exchange: InternetExchange<V>, members: readonly ExchangeMember[]): {
-    ports: (device: string) => Record<string, Port<V, string, string, string>>;
-    check: Check;
-};

package/src/adapters/devices/catalog.ts

@@ -1,41 +0,0 @@
-// Every model each platform supports. Types read from here, so a model or port name that does not exist fails to compile.
-
-import { models as fortios } from "./fortios/models";
-import { models as junos } from "./junos/models";
-import { models as raisecom } from "./raisecom-ros/models";
-import { models as routeros } from "./routeros/models";
-import { models as vrp } from "./vrp/models";
-
-export const catalog = { routeros, vrp, "raisecom-ros": raisecom, junos, fortios } as const;
-
-export type Catalog = typeof catalog;
-export type PlatformName = keyof Catalog;
-export type ModelName<Pl extends PlatformName> = keyof Catalog[Pl] & string;
-
-type Upto<N extends number, A extends unknown[] = [], R = never> = A["length"] extends N
-    ? R
-    : Upto<N, [...A, 0], R | `${[...A, 0]["length"]}`>;
-type PortsOf<Pl extends PlatformName, M extends ModelName<Pl>> = Catalog[Pl][M] extends { ports: infer P } ? P : never;
-
-/** `10g-1` to `10g-48` on a model with 48 10G ports. */
-export type PortName<Pl extends PlatformName, M extends ModelName<Pl>> = {
-    [S in keyof PortsOf<Pl, M>]: `${S & string}-${Upto<PortsOf<Pl, M>[S] & number>}`;
-}[keyof PortsOf<Pl, M>];
-
-/** Every port a model has, in order. */
-export function portsOf(platform: string, model: string): string[] {
-    const spec = (catalog as Record<string, Record<string, { ports: Record<string, number> }>>)[platform]?.[model];
-    if (!spec) throw new Error(`${platform} has no model ${model}`);
-    return Object.entries(spec.ports).flatMap(([speed, count]) => Array.from({ length: count }, (_, i) => `${speed}-${i + 1}`));
-}
-
-/** The platform's own name for a port. */
-export function spell(platform: string, model: string, port: string): string {
-    const spec = (catalog as Record<string, Record<string, { spelling: Record<string, string> }>>)[platform]?.[model];
-    const parts = /^(\d+[gm])-(\d+)$/.exec(port);
-    const template = parts && spec?.spelling[parts[1]!];
-    if (!template) throw new Error(`${model} has no port ${port}`);
-
-    // A platform that counts from 0, or numbers one class after another, shifts the position: `{n-1}`, `{n+47}`.
-    return template.replace(/\{n([+-]\d+)?\}/, (_, shift?: string) => String(Number(parts[2]) + Number(shift ?? 0)));
-}

package/src/adapters/devices/derive.ts

@@ -1,59 +0,0 @@
-// Values more than one adapter derives from a device in the same way.
-
-import { familyOf, network } from "../../core/addr";
-import type { Device } from "../../schema";
-
-/** Each LAG's number: its own `id`, or its position among the device's LAGs. */
-export function lagIds(device: Device): Map<string, number> {
-    const numbers = new Map<string, number>();
-    let position = 0;
-
-    for (const [name, iface] of Object.entries(device.interfaces ?? {})) {
-        if (iface.type !== "lag") continue;
-
-        position++;
-        numbers.set(name, iface.id ?? position);
-    }
-
-    return numbers;
-}
-
-/** The IPv4 networks of a port's or an interface's addresses. */
-export function ipv4Networks(device: Device, iface: string): string[] {
-    const settings = device.interfaces?.[iface] ?? device.ports?.[iface as keyof typeof device.ports];
-    const addresses = (settings?.addresses ?? []).map((entry) => (typeof entry === "string" ? entry : entry.address));
-
-    return addresses.filter((address) => familyOf(address) === "ipv4").map((address) => network(address));
-}
-
-/** Services the switch platforms run. Each takes its sources from `management.allow`, on the protocol's own port. */
-const SWITCH_SERVICES = ["ssh", "telnet", "snmp"] as const;
-
-/** Fields neither switch platform, VRP nor Raisecom ROS, expresses: a service's own sources or port, a user's description or keys, the IP stack's host settings, a point-to-point address, and offload per interface. */
-export function switchUnsupported(device: Device): string[] {
-    const found: string[] = [];
-
-    for (const service of SWITCH_SERVICES) {
-        const settings = device.management?.[service];
-        if (settings?.allow) found.push(`management.${service}.allow, every service takes management.allow`);
-        if (settings?.port) found.push(`management.${service}.port`);
-    }
-
-    for (const [name, user] of Object.entries(device.users ?? {})) {
-        if (user.description) found.push(`users.${name}.description`);
-        if (user.ssh_keys?.length) found.push(`users.${name}.ssh_keys`);
-    }
-
-    if (device.system?.ip) found.push("system.ip");
-
-    for (const [name, port] of Object.entries(device.ports ?? {})) {
-        if (port?.hardware_offload !== undefined) found.push(`ports.${name}.hardware_offload`);
-    }
-
-    for (const [name, iface] of Object.entries(device.interfaces ?? {})) {
-        if (iface.addresses?.some((entry) => typeof entry !== "string")) found.push(`interfaces.${name}.addresses with a peer`);
-        if (iface.hardware_offload !== undefined) found.push(`interfaces.${name}.hardware_offload`);
-    }
-
-    return found;
-}