@honeybbq/teamspeak 0.0.1 → 1.0.0-beta.7

package/dist/query/ssh.d.ts

@@ -0,0 +1,345 @@
+import { StreamTransport } from "./stream.js";
+import type { QueryStream } from "./stream.js";
+/**
+ * The part of an SSH client this transport uses: `ssh2`'s `Client` is one, and
+ * so is anything else with these methods.
+ *
+ * Declared here rather than imported from `@types/ssh2`, which a caller
+ * without the optional peer dependency does not have: the types are a
+ * devDependency and are not published with the package. A later release may
+ * widen this, and every new member will be optional, so an implementation
+ * written today keeps compiling.
+ */
+export interface SshClient {
+    /**
+     * Begin the connection; `ready` is emitted once the handshake is done.
+     *
+     * `hostVerifier` is asked about the server's key before anything is
+     * authenticated, so before the password is sent. It is given the key's wire
+     * encoding and returns whether to go on: a client must end the connection
+     * when it returns `false`, and must not treat a missing answer as a yes.
+     */
+    connect(config: {
+        host: string;
+        port: number;
+        username: string;
+        password: string;
+        readyTimeout: number;
+        hostVerifier: (key: Uint8Array) => boolean;
+    }): void;
+    /** Open a shell channel, or report why it could not be opened. */
+    shell(pty: false, callback: (error: Error | undefined, channel: SshChannel) => void): void;
+    /** End the connection. */
+    end(): void;
+    /** Listen for the handshake completing, once. */
+    once(event: "ready", listener: () => void): unknown;
+    /** Listen for the next failure, once. */
+    once(event: "error", listener: (error: Error) => void): unknown;
+    /** Listen for each failure. */
+    on(event: "error", listener: (error: Error) => void): unknown;
+    /** Stop listening for failures. */
+    off(event: "error", listener: (error: Error) => void): unknown;
+}
+/** The channel an SSH client's shell opens: a byte stream, and the errors on it. */
+export interface SshChannel extends QueryStream {
+    /** Report a failure on the stream, as a socket would: the transport reads it. */
+    emit(event: "error", error: Error): unknown;
+    /** Listen for the stream closing, once. */
+    once(event: "close", listener: () => void): unknown;
+}
+/**
+ * An SSH client this transport uses instead of loading `ssh2` itself: either
+ * one that is connected already, or a factory that makes one.
+ *
+ * A caller that holds its own connected client — authenticated through an
+ * agent, a jump host or a key file this transport knows nothing about — hands
+ * it over. A factory is asked for one per connection attempt, which a
+ * reconnection needs.
+ */
+export type SshConnection = SshClient | (() => Promise<SshClient>);
+/**
+ * The key an SSH server presented, as the check a caller supplies sees it.
+ *
+ * A type of this package's own rather than the SSH library's, so a policy can
+ * be written without importing that library.
+ *
+ * @experimental Part of the `@honeybbq/teamspeak/query` entry, which may
+ * change in a minor release.
+ */
+export interface SshHostKey {
+    /** The host that was dialled, as it was given. */
+    readonly host: string;
+    /** The port that was dialled. */
+    readonly port: number;
+    /** The key's algorithm, such as `ssh-ed25519`, as its own encoding names it. */
+    readonly keyType: string;
+    /** The key's wire encoding: the blob a `known_hosts` line carries in base64. */
+    readonly key: Uint8Array;
+    /**
+     * The key's SHA-256 fingerprint in OpenSSH form, such as `SHA256:HR5y2ZQ…`.
+     * It is what `ssh-keygen -lf` and `ssh-keyscan` print, so it can be compared
+     * with the one the server's operator published.
+     */
+    readonly fingerprint: string;
+}
+/**
+ * A caller's check of an SSH server's host key: returns to accept the key and
+ * throws to refuse it.
+ *
+ * Throwing is how a callback with no error channel says no, and the error it
+ * throws is kept as the `cause` of the {@link SshHostKeyError} the connection
+ * fails with. It runs before the login is sent, and it has to be synchronous
+ * and return nothing: a return value, a `false` included, is not an answer this
+ * can read, so it refuses the key rather than guess, as does a promise, whose
+ * rejection would arrive too late to stop anything.
+ *
+ * @experimental Part of the `@honeybbq/teamspeak/query` entry, which may
+ * change in a minor release.
+ */
+export type SshHostKeyVerifier = (key: SshHostKey) => void;
+/**
+ * Your own check of the server's host key. Use it when the key you trust does
+ * not live in a `known_hosts` file: a fingerprint from configuration, a pinned
+ * key, a lookup somewhere else.
+ *
+ * One of the three arms of {@link SshHostKeyPolicy}: giving it excludes the
+ * other two.
+ *
+ * @experimental Part of the `@honeybbq/teamspeak/query` entry, which may
+ * change in a minor release.
+ */
+export interface SshHostKeyCallbackPolicy {
+    /**
+     * The check; see {@link SshHostKeyVerifier}. Called once per connection
+     * attempt, before the login is sent.
+     */
+    readonly hostKey: SshHostKeyVerifier;
+    /** Left out: `hostKey` is the policy, and a second one would not say which decides. */
+    readonly knownHosts?: never;
+    /** Left out: `hostKey` is the policy, and a second one would not say which decides. */
+    readonly insecureIgnoreHostKey?: never;
+}
+/**
+ * Accept whatever key the server presents. Use it for a test or a throwaway
+ * server on a network that is already trusted, and for nothing else.
+ *
+ * One of the three arms of {@link SshHostKeyPolicy}: giving it excludes the
+ * other two.
+ *
+ * @experimental Part of the `@honeybbq/teamspeak/query` entry, which may
+ * change in a minor release.
+ */
+export interface SshInsecureHostKeyPolicy {
+    /**
+     * Only `true` is a value: this is not a switch to be left `false`, but a
+     * decision a call site makes out loud.
+     *
+     * It gives up the one thing the host key is for. Anyone who can answer the
+     * port, on the path or at the address, receives the query login and its
+     * password and is indistinguishable from the server. Use
+     * {@link SshKnownHostsPolicy.knownHosts} otherwise.
+     */
+    readonly insecureIgnoreHostKey: true;
+    /** Left out: accepting any key leaves nothing for a second policy to decide. */
+    readonly hostKey?: never;
+    /** Left out: accepting any key leaves nothing for a second policy to decide. */
+    readonly knownHosts?: never;
+}
+/**
+ * Check the server against an OpenSSH `known_hosts` file. Use it for a server
+ * whose key you have recorded with `ssh-keyscan`, or already trust through
+ * `ssh`.
+ *
+ * One of the three arms of {@link SshHostKeyPolicy}: giving it excludes the
+ * other two.
+ *
+ * @experimental Part of the `@honeybbq/teamspeak/query` entry, which may
+ * change in a minor release.
+ */
+export interface SshKnownHostsPolicy {
+    /**
+     * A path to the `known_hosts` file, in the format `ssh-keyscan` writes and
+     * `ssh-keygen -H` hashes.
+     *
+     * Read when each connection is attempted, so a reconnection sees the file as
+     * it is then, and only from the path given: `~/.ssh/known_hosts` is never
+     * assumed, because a library reading the home directory on its own is a
+     * surprise. The check is what `ssh` does with `StrictHostKeyChecking=yes`: a
+     * host the file does not mention is refused, so is one recorded with another
+     * key, and so is a key a `@revoked` line names. Plain, `[host]:port` and
+     * hashed entries are read; a line that cannot be read fails the connection
+     * rather than being skipped.
+     *
+     * A port other than 22 is recorded as `[host]:port`, which is what
+     * `ssh-keyscan -p` writes: an entry for port 22 does not vouch for the query
+     * port.
+     */
+    readonly knownHosts: string;
+    /** Left out: `knownHosts` is the policy, and a second one would not say which decides. */
+    readonly hostKey?: never;
+    /** Left out: `knownHosts` is the policy, and a second one would not say which decides. */
+    readonly insecureIgnoreHostKey?: never;
+}
+/**
+ * How the server's host key is checked: exactly one of `hostKey`, `knownHosts`
+ * and `insecureIgnoreHostKey`.
+ *
+ * There is no default, and a missing or doubled choice does not compile. The
+ * query login is a credential, normally `serveradmin`'s, and a client that
+ * accepts any key hands it to whatever answers the port. The same rule is
+ * checked when the program runs, for callers that are not type checked.
+ *
+ * @experimental Part of the `@honeybbq/teamspeak/query` entry, which may
+ * change in a minor release.
+ */
+export type SshHostKeyPolicy = SshHostKeyCallbackPolicy | SshKnownHostsPolicy | SshInsecureHostKeyPolicy;
+/**
+ * The address and the login of a server this transport dials itself: the part
+ * of {@link SshDialOptions} that is not the host key policy.
+ *
+ * @experimental Part of the `@honeybbq/teamspeak/query` entry, which may
+ * change in a minor release.
+ */
+export interface SshDialTarget {
+    /** The server's host. */
+    readonly host: string;
+    /** The SSH query port; 10022 by default. */
+    readonly port?: number | undefined;
+    /** The query login name, such as `serveradmin`. */
+    readonly username: string;
+    /** The query login's password. */
+    readonly password: string;
+    /** Left out: a connection of your own is {@link SshSuppliedConnectionOptions}. */
+    readonly connection?: never;
+}
+/**
+ * Connect to a server this transport dials itself: with a login, and with a
+ * host key policy. The usual way, and the one to use unless you already hold a
+ * connected SSH client.
+ *
+ * It is {@link SshHostKeyPolicy} together with the address and the login, so
+ * leaving the policy out is a type error that names the three ways to give one.
+ *
+ * @experimental Part of the `@honeybbq/teamspeak/query` entry, which may
+ * change in a minor release.
+ */
+export type SshDialOptions = SshDialTarget & SshHostKeyPolicy;
+/**
+ * Use an SSH client you made and connected yourself, or a factory for one:
+ * authenticated through an agent, a jump host or a key file this transport
+ * knows nothing about.
+ *
+ * Only a shell is opened on it, so no login and no host key policy are taken:
+ * the client you supply has done both already, and an option nothing would
+ * read is a type error rather than something that could suggest the key was
+ * verified here. The host and port are the server's identity, for messages.
+ *
+ * @experimental Part of the `@honeybbq/teamspeak/query` entry, which may
+ * change in a minor release.
+ */
+export interface SshSuppliedConnectionOptions {
+    /** The server's host, for identity and messages: nothing is dialled. */
+    readonly host: string;
+    /** The server's SSH query port, for identity and messages; 10022 by default. */
+    readonly port?: number | undefined;
+    /**
+     * The SSH client to use, or a factory for one. A client that is already
+     * connected skips the handshake; a factory is asked for one per connection
+     * attempt, which a reconnection needs.
+     *
+     * Deliberately narrow, so a later release can widen it without breaking an
+     * implementation written today. Its host key is checked by whoever made it.
+     */
+    readonly connection: SshConnection;
+    /** Left out: the supplied client is authenticated already. */
+    readonly username?: never;
+    /** Left out: the supplied client is authenticated already. */
+    readonly password?: never;
+    /** Left out: the supplied client's host key is checked by whoever made it. */
+    readonly hostKey?: never;
+    /** Left out: the supplied client's host key is checked by whoever made it. */
+    readonly knownHosts?: never;
+    /** Left out: the supplied client's host key is checked by whoever made it. */
+    readonly insecureIgnoreHostKey?: never;
+}
+/**
+ * How a ServerQuery over SSH is reached, without the cancellation: one of
+ * {@link SshDialOptions} and {@link SshSuppliedConnectionOptions}.
+ *
+ * What a `QueryClient`'s `ssh` transport is built from, so that the two cannot
+ * drift apart.
+ *
+ * @experimental Part of the `@honeybbq/teamspeak/query` entry, which may
+ * change in a minor release.
+ */
+export type SshConnectOptions = SshDialOptions | SshSuppliedConnectionOptions;
+/**
+ * Where a ServerQuery over SSH listens, who logs in, and how the server's host
+ * key is checked.
+ *
+ * One of two shapes. The usual one, {@link SshDialOptions}, takes the host, the
+ * login and exactly one of `hostKey`, `knownHosts` and `insecureIgnoreHostKey`:
+ * there is no default, because the login is a credential and a client that
+ * accepts any key hands it to whatever answers the port. The other,
+ * {@link SshSuppliedConnectionOptions}, takes an SSH client you connected
+ * yourself, and no login or policy.
+ *
+ * @experimental Part of the `@honeybbq/teamspeak/query` entry, which may
+ * change in a minor release.
+ */
+export type SshOptions = SshConnectOptions & {
+    /** Abandons the connection attempt. */
+    readonly signal?: AbortSignal | undefined;
+};
+/** How the host key is to be decided, once the options have been read. */
+export type HostKeyDecision = {
+    readonly kind: "verifier";
+    readonly verify: SshHostKeyVerifier;
+} | {
+    readonly kind: "knownHosts";
+    readonly path: string;
+} | {
+    readonly kind: "insecure";
+}
+/** The caller supplied the connection, so the key was theirs to check. */
+ | {
+    readonly kind: "connection";
+};
+/**
+ * What the decision reads. Every member is `unknown`: the types of
+ * {@link SshOptions} already make a wrong combination a compile error, and this
+ * is for the callers they do not reach, a JavaScript program or an `as` cast.
+ */
+export interface SshChoice {
+    readonly hostKey?: unknown;
+    readonly knownHosts?: unknown;
+    readonly insecureIgnoreHostKey?: unknown;
+    readonly connection?: unknown;
+    readonly username?: unknown;
+    readonly password?: unknown;
+}
+/**
+ * Read the trust decision out of the options, or refuse them.
+ *
+ * Fails closed: with none of the three there is no policy, and this throws
+ * rather than choose one. Two is a `TypeError`, since a caller who passed both
+ * has not decided which is authoritative. Runs when a client is built as well
+ * as when it connects, so a missing decision is heard about before the first
+ * attempt.
+ *
+ * The same rule as the types state, for the callers they do not reach.
+ */
+export declare function hostKeyDecision(options: SshChoice): HostKeyDecision;
+/**
+ * Open a ServerQuery over SSH.
+ *
+ * SSH logs in itself, so there is no `login` command to send afterwards: the
+ * session is already the query account, and only `use` is left.
+ *
+ * The server's host key is checked first, by whichever of `hostKey`,
+ * `knownHosts` and `insecureIgnoreHostKey` was given, and the password is sent
+ * only to a server whose key was accepted. With none of them, or with two,
+ * this rejects before anything is opened or dialled.
+ */
+export declare function connectSsh(options: SshOptions): Promise<StreamTransport>;
+//# sourceMappingURL=ssh.d.ts.map

package/dist/query/ssh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssh.d.ts","sourceRoot":"","sources":["../../src/query/ssh.ts"],"names":[],"mappings":"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"}

package/dist/query/ssh.js

@@ -0,0 +1,241 @@
+import { readFile } from "node:fs/promises";
+import { MissingDependencyError, QueryAuthError, SshHostKeyError } from "./errors.js";
+import { KnownHosts, fingerprintOf, keyTypeOf } from "./knownhosts.js";
+import { StreamTransport } from "./stream.js";
+/**
+ * Read the trust decision out of the options, or refuse them.
+ *
+ * Fails closed: with none of the three there is no policy, and this throws
+ * rather than choose one. Two is a `TypeError`, since a caller who passed both
+ * has not decided which is authoritative. Runs when a client is built as well
+ * as when it connects, so a missing decision is heard about before the first
+ * attempt.
+ *
+ * The same rule as the types state, for the callers they do not reach.
+ */
+export function hostKeyDecision(options) {
+    const { hostKey, knownHosts, insecureIgnoreHostKey, connection, username, password } = options;
+    if (hostKey !== undefined && typeof hostKey !== "function") {
+        throw new TypeError("hostKey is a function that throws to refuse a host key");
+    }
+    if (knownHosts !== undefined && (typeof knownHosts !== "string" || knownHosts === "")) {
+        throw new TypeError("knownHosts is the path of a known_hosts file");
+    }
+    if (insecureIgnoreHostKey !== undefined && insecureIgnoreHostKey !== true) {
+        throw new TypeError("insecureIgnoreHostKey is `true` or left out: it is a decision, not a switch to set to false");
+    }
+    const given = [];
+    if (hostKey !== undefined)
+        given.push("hostKey");
+    if (knownHosts !== undefined)
+        given.push("knownHosts");
+    if (insecureIgnoreHostKey !== undefined)
+        given.push("insecureIgnoreHostKey");
+    if (given.length > 1) {
+        throw new TypeError(`${given.join(", ")} were given together; exactly one of hostKey, knownHosts and insecureIgnoreHostKey decides whether the host key is accepted`);
+    }
+    if (connection !== undefined) {
+        if (given.length > 0) {
+            throw new TypeError(`${given[0]} has no effect with connection, which makes the connection itself: its host key is checked by whoever made it`);
+        }
+        if (username !== undefined || password !== undefined) {
+            throw new TypeError("username and password have no effect with connection, which is authenticated already: nothing would send them");
+        }
+        return { kind: "connection" };
+    }
+    if (hostKey !== undefined)
+        return { kind: "verifier", verify: hostKey };
+    if (knownHosts !== undefined)
+        return { kind: "knownHosts", path: knownHosts };
+    if (insecureIgnoreHostKey !== undefined)
+        return { kind: "insecure" };
+    throw new Error("the SSH host key has to be checked, and none of hostKey, knownHosts or insecureIgnoreHostKey was given: a query login is a credential, normally serveradmin's, and this client will not send it to a host it has not verified");
+}
+/**
+ * `ssh2`, or a `MissingDependencyError` naming it. Loaded on demand: it is an
+ * optional peer dependency, so importing it at the top of this module would
+ * make it a requirement of the whole entry point — including the TCP and
+ * WebQuery transports, which need nothing but Node.
+ */
+async function loadSsh2() {
+    try {
+        return await import("ssh2");
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            error.code === "ERR_MODULE_NOT_FOUND") {
+            throw new MissingDependencyError();
+        }
+        throw error;
+    }
+}
+/**
+ * Open a ServerQuery over SSH.
+ *
+ * SSH logs in itself, so there is no `login` command to send afterwards: the
+ * session is already the query account, and only `use` is left.
+ *
+ * The server's host key is checked first, by whichever of `hostKey`,
+ * `knownHosts` and `insecureIgnoreHostKey` was given, and the password is sent
+ * only to a server whose key was accepted. With none of them, or with two,
+ * this rejects before anything is opened or dialled.
+ */
+export async function connectSsh(options) {
+    const { host, port = 10022, signal, connection } = options;
+    const decision = hostKeyDecision(options);
+    // The login is read only where this module dials: a supplied client is
+    // authenticated already. Checked here, so a missing one fails before ssh2 is
+    // loaded or anything is opened.
+    const login = connection === undefined
+        ? {
+            username: nonEmptyString(options.username, "username"),
+            password: nonEmptyString(options.password, "password"),
+        }
+        : undefined;
+    signal?.throwIfAborted();
+    const verify = await verifierFor(decision, host, port);
+    const ssh = await clientFor(connection);
+    signal?.throwIfAborted();
+    // What the caller's check said, so that the failure ssh2 reports for a
+    // refused key can be told from any other and carry the reason.
+    let refusal;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const failed = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener("abort", onAbort);
+            reject(error);
+        };
+        const onAbort = () => {
+            ssh.end();
+            failed(signal.reason);
+        };
+        const onAuthError = (error) => {
+            if (refusal !== undefined) {
+                failed(new SshHostKeyError(host, port, `the SSH host key of ${host}:${port} was not accepted, so no login was sent: ${refusal.message}`, { cause: refusal }));
+                return;
+            }
+            // ssh2 reports a refused credential through `level`, which its types do
+            // not name; a wrong password is the one that leaves the client unable to
+            // authenticate rather than unable to reach the server.
+            const level = error.level;
+            failed(level === "client-authentication"
+                ? new QueryAuthError(login.username, `SSH authentication failed for ${login.username}`, { cause: error })
+                : error);
+        };
+        const openShell = () => {
+            ssh.shell(false, (error, channel) => {
+                if (error) {
+                    ssh.end();
+                    failed(error);
+                    return;
+                }
+                ssh.off("error", onAuthError);
+                settled = true;
+                signal?.removeEventListener("abort", onAbort);
+                // `ssh2` reports a failure after the handshake on the connection, and the
+                // stream closes with it.
+                ssh.on("error", (failure) => channel.emit("error", failure));
+                channel.once("close", () => ssh.end());
+                resolve(new StreamTransport(channel, () => ssh.end()));
+            });
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (connection !== undefined) {
+            // A client the caller handed over is one they say is connected, and one
+            // from their own factory is dialled on their terms: neither is connected
+            // here, and neither can be a wrong credential this module knows of.
+            openShell();
+            return;
+        }
+        ssh.once("error", onAuthError);
+        ssh.once("ready", openShell);
+        ssh.connect({
+            host,
+            port,
+            // Set exactly when `connection` is not, and this is the dial path.
+            username: login.username,
+            password: login.password,
+            readyTimeout: 10_000,
+            hostVerifier: (blob) => {
+                const outcome = decide(verify, host, port, blob);
+                if (outcome !== undefined)
+                    refusal = outcome;
+                return outcome === undefined;
+            },
+        });
+    });
+}
+function nonEmptyString(value, name) {
+    if (typeof value !== "string" || value === "")
+        throw new TypeError(`${name} is a non-empty string`);
+    return value;
+}
+/**
+ * The check the options chose, ready to run: the caller's own, one over the
+ * `known_hosts` file read now, or the one that accepts anything.
+ *
+ * A file that cannot be read or parsed is a failure to verify, and ends the
+ * connection as a refused key does.
+ */
+async function verifierFor(policy, host, port) {
+    if (policy.kind === "verifier")
+        return policy.verify;
+    // `connection` never reaches a handshake of ours, so for it this is not asked.
+    if (policy.kind !== "knownHosts")
+        return () => { };
+    let hosts;
+    try {
+        hosts = KnownHosts.parse(await readFile(policy.path, "utf8"), policy.path);
+    }
+    catch (error) {
+        throw new SshHostKeyError(host, port, `the host key of ${host}:${port} cannot be checked: ${error.message}`, { cause: error });
+    }
+    return (key) => hosts.verify(key);
+}
+/**
+ * Run the check on the key ssh2 found, returning why it was refused, or
+ * `undefined` for a key it accepted.
+ *
+ * Everything that is not a plain return counts as a refusal: a throw, naturally,
+ * but also an answer. A check that returns `false` was written in ssh2's
+ * convention and means no; one that returns `true` means yes in that
+ * convention, and a promise means whatever it later settles to. None of those
+ * is the contract, and acting on a guess at which was meant is how a refused key
+ * gets through, so each fails closed and says what to write instead.
+ */
+function decide(verify, host, port, blob) {
+    try {
+        const key = new Uint8Array(blob);
+        const answer = verify({
+            host,
+            port,
+            keyType: keyTypeOf(key),
+            key,
+            fingerprint: fingerprintOf(key),
+        });
+        if (answer === undefined)
+            return undefined;
+        // A rejection nobody awaits would otherwise surface as an unhandled one.
+        if (typeof answer.then === "function") {
+            void Promise.resolve(answer).catch(() => { });
+        }
+        return new TypeError("the hostKey check returned a value; it has to return nothing to accept the key and throw to refuse it, and be synchronous");
+    }
+    catch (error) {
+        return error instanceof Error ? error : new Error(String(error));
+    }
+}
+/** The client to talk over: the caller's, their factory's, or a fresh `ssh2`. */
+async function clientFor(connection) {
+    if (typeof connection === "function")
+        return connection();
+    if (connection !== undefined)
+        return connection;
+    const { Client } = await loadSsh2();
+    return new Client();
+}
+//# sourceMappingURL=ssh.js.map

package/dist/query/ssh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssh.js","sourceRoot":"","sources":["../../src/query/ssh.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACtF,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAkV9C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,OAAkB;IAChD,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAC/F,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAC3D,MAAM,IAAI,SAAS,CAAC,wDAAwD,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,UAAU,KAAK,SAAS,IAAI,CAAC,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,KAAK,EAAE,CAAC,EAAE,CAAC;QACtF,MAAM,IAAI,SAAS,CAAC,8CAA8C,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,qBAAqB,KAAK,SAAS,IAAI,qBAAqB,KAAK,IAAI,EAAE,CAAC;QAC1E,MAAM,IAAI,SAAS,CACjB,6FAA6F,CAC9F,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,OAAO,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACjD,IAAI,UAAU,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACvD,IAAI,qBAAqB,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IAC7E,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,SAAS,CACjB,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,6HAA6H,CACjJ,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,SAAS,CACjB,GAAG,KAAK,CAAC,CAAC,CAAC,+GAA+G,CAC3H,CAAC;QACJ,CAAC;QACD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YACrD,MAAM,IAAI,SAAS,CACjB,+GAA+G,CAChH,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;IAChC,CAAC;IACD,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,OAA6B,EAAE,CAAC;IAC9F,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IAC9E,IAAI,qBAAqB,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IACrE,MAAM,IAAI,KAAK,CACb,+NAA+N,CAChO,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,QAAQ;IACrB,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IACE,OAAO,KAAK,KAAK,QAAQ;YACzB,KAAK,KAAK,IAAI;YACb,KAA4B,CAAC,IAAI,KAAK,sBAAsB,EAC7D,CAAC;YACD,MAAM,IAAI,sBAAsB,EAAE,CAAC;QACrC,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,OAAmB;IAClD,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAC3D,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IAC1C,uEAAuE;IACvE,6EAA6E;IAC7E,gCAAgC;IAChC,MAAM,KAAK,GACT,UAAU,KAAK,SAAS;QACtB,CAAC,CAAC;YACE,QAAQ,EAAE,cAAc,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC;YACtD,QAAQ,EAAE,cAAc,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC;SACvD;QACH,CAAC,CAAC,SAAS,CAAC;IAChB,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACvD,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,UAAU,CAAC,CAAC;IACxC,MAAM,EAAE,cAAc,EAAE,CAAC;IAEzB,uEAAuE;IACvE,+DAA+D;IAC/D,IAAI,OAA0B,CAAC;IAE/B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,MAAM,GAAG,CAAC,KAAY,EAAQ,EAAE;YACpC,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC9C,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC,CAAC;QACF,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,GAAG,CAAC,GAAG,EAAE,CAAC;YACV,MAAM,CAAC,MAAO,CAAC,MAAe,CAAC,CAAC;QAClC,CAAC,CAAC;QACF,MAAM,WAAW,GAAG,CAAC,KAAY,EAAQ,EAAE;YACzC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,CACJ,IAAI,eAAe,CACjB,IAAI,EACJ,IAAI,EACJ,uBAAuB,IAAI,IAAI,IAAI,4CAA4C,OAAO,CAAC,OAAO,EAAE,EAChG,EAAE,KAAK,EAAE,OAAO,EAAE,CACnB,CACF,CAAC;gBACF,OAAO;YACT,CAAC;YACD,wEAAwE;YACxE,yEAAyE;YACzE,uDAAuD;YACvD,MAAM,KAAK,GAAI,KAA6B,CAAC,KAAK,CAAC;YACnD,MAAM,CACJ,KAAK,KAAK,uBAAuB;gBAC/B,CAAC,CAAC,IAAI,cAAc,CAChB,KAAM,CAAC,QAAQ,EACf,iCAAiC,KAAM,CAAC,QAAQ,EAAE,EAClD,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB;gBACH,CAAC,CAAC,KAAK,CACV,CAAC;QACJ,CAAC,CAAC;QACF,MAAM,SAAS,GAAG,GAAS,EAAE;YAC3B,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;gBAClC,IAAI,KAAK,EAAE,CAAC;oBACV,GAAG,CAAC,GAAG,EAAE,CAAC;oBACV,MAAM,CAAC,KAAK,CAAC,CAAC;oBACd,OAAO;gBACT,CAAC;gBACD,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;gBAC9B,OAAO,GAAG,IAAI,CAAC;gBACf,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAC9C,0EAA0E;gBAC1E,yBAAyB;gBACzB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;gBAC7D,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC;gBACvC,OAAO,CAAC,IAAI,eAAe,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACzD,CAAC,CAAC,CAAC;QACL,CAAC,CAAC;QAEF,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3D,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,wEAAwE;YACxE,yEAAyE;YACzE,oEAAoE;YACpE,SAAS,EAAE,CAAC;YACZ,OAAO;QACT,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAC/B,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAC7B,GAAG,CAAC,OAAO,CAAC;YACV,IAAI;YACJ,IAAI;YACJ,mEAAmE;YACnE,QAAQ,EAAE,KAAM,CAAC,QAAQ;YACzB,QAAQ,EAAE,KAAM,CAAC,QAAQ;YACzB,YAAY,EAAE,MAAM;YACpB,YAAY,EAAE,CAAC,IAAI,EAAE,EAAE;gBACrB,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;gBACjD,IAAI,OAAO,KAAK,SAAS;oBAAE,OAAO,GAAG,OAAO,CAAC;gBAC7C,OAAO,OAAO,KAAK,SAAS,CAAC;YAC/B,CAAC;SACF,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,cAAc,CAAC,KAAc,EAAE,IAAY;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE;QAC3C,MAAM,IAAI,SAAS,CAAC,GAAG,IAAI,wBAAwB,CAAC,CAAC;IACvD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,WAAW,CACxB,MAAuB,EACvB,IAAY,EACZ,IAAY;IAEZ,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC;IACrD,+EAA+E;IAC/E,IAAI,MAAM,CAAC,IAAI,KAAK,YAAY;QAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAElD,IAAI,KAAiB,CAAC;IACtB,IAAI,CAAC;QACH,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7E,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,eAAe,CACvB,IAAI,EACJ,IAAI,EACJ,mBAAmB,IAAI,IAAI,IAAI,uBAAwB,KAAe,CAAC,OAAO,EAAE,EAChF,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,MAAM,CACb,MAA0B,EAC1B,IAAY,EACZ,IAAY,EACZ,IAAgB;IAEhB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,MAAM,GAAY,MAAM,CAAC;YAC7B,IAAI;YACJ,IAAI;YACJ,OAAO,EAAE,SAAS,CAAC,GAAG,CAAC;YACvB,GAAG;YACH,WAAW,EAAE,aAAa,CAAC,GAAG,CAAC;SAChC,CAAC,CAAC;QACH,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC3C,yEAAyE;QACzE,IAAI,OAAQ,MAA6B,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC9D,KAAK,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC/C,CAAC;QACD,OAAO,IAAI,SAAS,CAClB,2HAA2H,CAC5H,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACnE,CAAC;AACH,CAAC;AAED,iFAAiF;AACjF,KAAK,UAAU,SAAS,CAAC,UAAqC;IAC5D,IAAI,OAAO,UAAU,KAAK,UAAU;QAAE,OAAO,UAAU,EAAE,CAAC;IAC1D,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC;IAChD,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,QAAQ,EAAE,CAAC;IACpC,OAAO,IAAI,MAAM,EAAE,CAAC;AACtB,CAAC"}

package/dist/query/stream.d.ts

@@ -0,0 +1,38 @@
+import type { QueryTransport } from "./transport.js";
+/**
+ * The part of a duplex byte stream a line transport uses. A `node:net` socket
+ * is one; so is an SSH shell channel, or a test double.
+ */
+export interface QueryStream {
+    /** Write bytes to the peer; `callback` runs once they are flushed, with the failure if any. */
+    write(data: string, callback: (error?: Error | null) => void): unknown;
+    /** Close the stream. */
+    end(): unknown;
+    /** Listen for each chunk received. */
+    on(event: "data", listener: (chunk: Uint8Array) => void): unknown;
+    /** Listen for a failure, which ends the connection. */
+    on(event: "error", listener: (error: Error) => void): unknown;
+    /** Listen for the stream closing. */
+    on(event: "close", listener: () => void): unknown;
+}
+/**
+ * A {@link QueryTransport} over a byte stream: raw TCP, or an SSH shell.
+ *
+ * Both greet with a two-line banner, `TS3` and a welcome sentence, before any
+ * answer. It is skipped, so the client sees only answers and notifications.
+ */
+export declare class StreamTransport implements QueryTransport {
+    #private;
+    /** A raw TCP connection and an SSH session both carry pushed notifications. */
+    readonly supportsNotifications = true;
+    onLine: ((line: string) => void) | null;
+    onClose: ((error: Error | undefined) => void) | null;
+    /**
+     * `onEnd` runs once the stream is closed, to release what the stream sits
+     * on: an SSH session's connection, say.
+     */
+    constructor(stream: QueryStream, onEnd?: () => void);
+    send(line: string): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=stream.d.ts.map

package/dist/query/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/query/stream.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,+FAA+F;IAC/F,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,GAAG,OAAO,CAAC;IACvE,wBAAwB;IACxB,GAAG,IAAI,OAAO,CAAC;IACf,sCAAsC;IACtC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC;IAClE,uDAAuD;IACvD,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC;IAC9D,qCAAqC;IACrC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;CACnD;AAED;;;;;GAKG;AACH,qBAAa,eAAgB,YAAW,cAAc;;IACpD,+EAA+E;IAC/E,QAAQ,CAAC,qBAAqB,QAAQ;IACtC,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IAC/C,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IAW5D;;;OAGG;IACH,YAAY,MAAM,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,MAAM,IAAI,EAQlD;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKhC;IAED,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAUrB;CAkBF"}