@takodotid/circuit 0.4.3

package/src/schema/system.ts

@@ -0,0 +1,191 @@
+import type { IP, Prefix, Secret, Severity } from "./common";
+
+/** Device-wide settings. */
+export type System = {
+    /** IANA zone, for example `Asia/Jakarta`. UTC when absent. */
+    timezone?: string;
+    /** Shown at login. */
+    banner?: string;
+    /** Resolvers the device uses. */
+    dns?: {
+        /** Resolvers, in order of preference. */
+        servers: readonly IP[];
+        /** Answer queries from others. Off when absent. */
+        serve?: boolean;
+    };
+    /** Time the device keeps. */
+    ntp?: {
+        /** Time sources, by address or name. */
+        servers: readonly string[];
+        /** Answer time queries from others. Off when absent. */
+        serve?: boolean;
+    };
+    /** Where log messages go. */
+    logging?: {
+        /** Kept on the device's own storage, from `level` up. */
+        local?: {
+            /** The least severe message kept. */
+            level: Severity;
+            /** How many rotated files to keep. */
+            files?: number;
+            /** Lines in each file before it rotates. */
+            lines_per_file?: number;
+        };
+        /** Sent to syslog collectors, each from its own `level` up. */
+        remote?: readonly {
+            address: IP;
+            /** UDP port. 514 when absent. */
+            port?: number;
+            /** The least severe message sent. */
+            level: Severity;
+        }[];
+    };
+    /** Software release track the device updates from. */
+    release_channel?: string;
+    /** Read optic temperature, power and voltage. */
+    transceiver_monitoring?: boolean;
+    /** Host behaviour of the IP stack. */
+    ip?: {
+        /** Send ICMP redirects. Off when absent. */
+        icmp_redirects?: boolean;
+        /** Answer a TCP SYN flood with SYN cookies. Off when absent. */
+        syn_cookies?: boolean;
+    };
+};
+
+/** A login on the device. */
+export type User = {
+    /** What the user may do. */
+    role: "admin" | "operator" | "read-only";
+    /** The login password. */
+    password: Secret;
+    /** Who the account is for. */
+    description?: string;
+    /** Public keys accepted instead of the password over SSH. */
+    ssh_keys?: readonly string[];
+};
+
+/** A way into the device. Absent means turned off. */
+export type Service = {
+    /** Sources allowed. `management.allow` when absent. */
+    allow?: readonly Prefix[];
+    /** TCP or UDP port. The protocol's own when absent. */
+    port?: number;
+};
+
+/** One SNMPv3 user. */
+export type SnmpUser = {
+    /** How messages are authenticated. */
+    auth: "sha1" | "sha256";
+    /** The authentication passphrase. */
+    auth_password: Secret;
+    /** How messages are encrypted. */
+    privacy: "aes128" | "des";
+    /** The encryption passphrase. */
+    privacy_password: Secret;
+};
+
+/** How the device is reached and managed. */
+export type Management<I extends string, C extends string> = {
+    /** Sources allowed to every service that does not state its own. */
+    allow?: readonly Prefix[];
+    /** Secure shell. */
+    ssh?: Service & {
+        /** Also offer legacy ciphers, MACs and key exchanges. Off when absent. */
+        weak_crypto?: boolean;
+        /** Seconds a login may take. */
+        auth_timeout?: number;
+        /** Failed attempts allowed per connection. */
+        auth_retries?: number;
+    };
+    /** Unencrypted remote login. */
+    telnet?: Service;
+    /** Web interface, unencrypted. */
+    http?: Service;
+    /** Web interface over TLS. */
+    https?: Service & {
+        /** One of the device's `certificates`. */
+        certificate?: C;
+    };
+    /** The platform's own API, unencrypted. */
+    api?: Service;
+    /** The platform's own API over TLS. */
+    api_tls?: Service & {
+        /** One of the device's `certificates`. */
+        certificate?: C;
+    };
+    /** File transfer, unencrypted. */
+    ftp?: Service;
+    /** The platform's own management protocol. `interfaces` also allows it at layer 2 on those interfaces. */
+    native?: Service & { interfaces?: readonly I[] };
+    /** Polling by SNMP. */
+    snmp?: Service & {
+        /** Read-only community for version 2c. Version 2c is off when absent. */
+        community?: Secret;
+        /** Version 3 users, keyed by name. */
+        users?: Record<string, SnmpUser>;
+        /** Who to contact about the device. */
+        contact?: string;
+        /** Where the device is. */
+        location?: string;
+    };
+    /** Console login uses this password. The device's users when absent. */
+    console?: { password: Secret };
+    /** Password for privileged mode, on platforms that have one. */
+    privilege_password?: Secret;
+};
+
+/** A DHCP server for one network. */
+export type DhcpServer<I extends string> = {
+    /** Where it answers. */
+    interface: I;
+    /** The network it serves. */
+    network: Prefix;
+    /** Default gateway handed out. */
+    gateway: IP;
+    /** Resolvers handed out. */
+    dns?: readonly IP[];
+    /** First and last address handed out. */
+    pool: readonly [IP, IP];
+    /** Seconds a lease lasts. */
+    lease_time?: number;
+    /** Addresses fixed to a MAC. */
+    reservations?: readonly {
+        address: IP;
+        mac: string;
+        /** Whose address it is. */
+        description?: string;
+    }[];
+};
+
+/** Forward DHCP requests heard on an interface to servers elsewhere. */
+export type DhcpRelay<I extends string> = {
+    /** Where requests are heard. */
+    interface: I;
+    /** Where they are forwarded. */
+    servers: readonly IP[];
+};
+
+/** A certificate the device presents or trusts. */
+export type Certificate = {
+    /** The certificate, PEM. Public, so it lives in the repository. */
+    certificate: string;
+    /** Its private key: a PEM file through `secretFile`, or PEM base64-encoded as one line through `secret`. A certificate only trusted, such as a CA, has none. */
+    private_key?: Secret;
+};
+
+/** Export flow records or packet samples to collectors. */
+export type FlowExport<I extends string> = {
+    /** The record format. */
+    protocol: "sflow" | "netflow-v9" | "ipfix";
+    /** Where records are sent. */
+    collectors: readonly {
+        address: IP;
+        /** UDP port. 6343 for sFlow and 2055 otherwise when absent. */
+        port?: number;
+    }[];
+    /** Sample one packet in this many. Every packet when absent, on a platform that can export every packet. */
+    sampling?: number;
+    /** Where traffic is observed. Every interface when absent. */
+    interfaces?: readonly I[];
+};

package/src/transport/ssh.ts

@@ -0,0 +1,125 @@
+// SSH sessions to devices. Adapters choose how to talk to their platform; this holds what they share.
+
+import { Client, type ClientChannel } from "ssh2";
+
+export type Login = {
+    host: string;
+    port?: number;
+    user: string;
+    password: string;
+    /** Host key algorithms to accept, for a device that negotiates one it then signs wrongly. */
+    hostKeys?: string[];
+};
+
+/** Open a session. */
+export function connect(login: Login): Promise<Client> {
+    return new Promise((resolve, reject) => {
+        const client = new Client();
+
+        client
+            .on("ready", () => resolve(client))
+            .on("error", reject)
+            .connect({
+                host: login.host,
+                port: login.port ?? 22,
+                username: login.user,
+                password: login.password,
+                readyTimeout: 30_000,
+                ...(login.hostKeys ? { algorithms: { serverHostKey: login.hostKeys as never } } : {}),
+            });
+    });
+}
+
+/** Run one command and return what it printed, stderr included. */
+export function exec(client: Client, command: string, timeout = 120_000): Promise<string> {
+    return new Promise((resolve, reject) => {
+        client.exec(command, (error, stream) => {
+            if (error) return reject(error);
+
+            let output = "";
+            const append = (chunk: Buffer) => (output += chunk.toString("utf8"));
+            const timer = setTimeout(() => resolve(output.trim()), timeout);
+
+            stream.on("data", append);
+            stream.stderr.on("data", append);
+
+            stream.on("close", () => {
+                clearTimeout(timer);
+                resolve(output.trim());
+            });
+        });
+    });
+}
+
+/** An interactive shell, for platforms that take configuration only there. */
+export function shell(client: Client, columns = 200, rows = 1000): Promise<ClientChannel> {
+    return new Promise((resolve, reject) => {
+        client.shell({ cols: columns, rows }, (error, channel) => (error ? reject(error) : resolve(channel)));
+    });
+}
+
+/** Collect output until `done` holds, then wait `settle` for stragglers, or give up at `timeout`. */
+export function readUntil(channel: ClientChannel, done: (output: string) => boolean, timeout: number, settle = 400): Promise<string> {
+    return new Promise((resolve) => {
+        let output = "";
+        let finished = false;
+
+        const finish = () => {
+            if (finished) return;
+
+            finished = true;
+            channel.removeListener("data", onData);
+            resolve(output);
+        };
+
+        const onData = (chunk: Buffer) => {
+            output += chunk.toString("utf8");
+            if (done(output)) setTimeout(finish, settle);
+        };
+
+        channel.on("data", onData);
+        setTimeout(finish, timeout);
+    });
+}
+
+/** Send one line into an interactive shell and collect output until it goes quiet for `settle`. */
+export function send(channel: ClientChannel, line: string, timeout = 20_000, settle = 1500): Promise<string> {
+    channel.write(line + "\n");
+
+    return new Promise((resolve) => {
+        let output = "";
+        let timer: ReturnType<typeof setTimeout>;
+
+        const finish = () => {
+            channel.removeListener("data", onData);
+            resolve(output);
+        };
+
+        const onData = (chunk: Buffer) => {
+            output += chunk.toString("utf8");
+            clearTimeout(timer);
+            timer = setTimeout(finish, settle);
+        };
+
+        channel.on("data", onData);
+        timer = setTimeout(finish, timeout);
+    });
+}
+
+export const sleep = (milliseconds: number) => new Promise((done) => setTimeout(done, milliseconds));
+
+/** Write a file to the device over SFTP. */
+export function upload(client: Client, path: string, content: string | Buffer): Promise<void> {
+    return new Promise((resolve, reject) => {
+        client.sftp((error, sftp) => {
+            if (error) return reject(error);
+
+            sftp.writeFile(path, content, (writeError) => {
+                sftp.end();
+
+                if (writeError) reject(writeError);
+                else resolve();
+            });
+        });
+    });
+}