charness 3.7.0 → 3.9.0

package/dist/runnerUtility/appUpdate.d.ts

@@ -0,0 +1,39 @@
+import { connectToHub } from './hubClient';
+import { type RunnerConfig } from './runnerConfig';
+import type { RunnerHomePaths } from './runnerHome';
+/**
+ * @description Updating the runner to the hub's current package: the hub's `link` answer names the package id; when it is not the one
+ * installed, an IDLE runner fetches the package with the `package` request (a connection of its own), checks that the archive hashes to
+ * the id the hub announced, installs it next to the running copy, points `current` at it and records the id. The caller then exits with
+ * the restart code and the launcher starts the new copy. Nothing is changed in the running copy.
+ */
+export type UpdateOutcome = {
+    ok: true;
+    packageId: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface UpdateParams {
+    paths: RunnerHomePaths;
+    config: RunnerConfig;
+    clientPrivateKey: string;
+    connect?: typeof connectToHub;
+}
+/** @description Fetch, verify and install the hub's package; on success `current` and `config.json` point at it. */
+export declare function updateFromHub(params: UpdateParams): Promise<UpdateOutcome>;
+export interface UpdateDecisionInputs {
+    /** What the hub named in the `link` answer (`none`: it could not pack one). */
+    hubPackageId: string | undefined;
+    installedPackageId: string | null;
+    activeExecCount: number;
+    /** The id of an update that already failed, and when — it is not tried again for {@link updateRetryDelayMs}. */
+    failedPackageId: string | null;
+    failedAtMs: number;
+    nowMs: number;
+}
+export declare const updateRetryDelayMs: number;
+export type UpdateDecision = 'none' | 'wait-until-idle' | 'update-now';
+/** @description Update only to a package the hub named and the runner does not have; only while no command runs; not again right after a failure. */
+export declare function decideUpdate(inputs: UpdateDecisionInputs): UpdateDecision;
+//# sourceMappingURL=appUpdate.d.ts.map

package/dist/runnerUtility/appUpdate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appUpdate.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/appUpdate.ts"],"names":[],"mappings":"AAGA,OAAO,EAAY,YAAY,EAAoB,MAAM,aAAa,CAAC;AAGvE,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;GAKG;AAEH,MAAM,MAAM,aAAa,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5F,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,eAAe,CAAC;IACvB,MAAM,EAAE,YAAY,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,YAAY,CAAC;CAC/B;AAED,oHAAoH;AACpH,wBAAsB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CA2BhF;AAED,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,gHAAgH;IAChH,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,kBAAkB,QAAiB,CAAC;AAEjD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,iBAAiB,GAAG,YAAY,CAAC;AAEvE,qJAAqJ;AACrJ,wBAAgB,YAAY,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CAIzE"}

package/dist/runnerUtility/appUpdate.js

@@ -0,0 +1,90 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateRetryDelayMs = void 0;
+exports.updateFromHub = updateFromHub;
+exports.decideUpdate = decideUpdate;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const gateProtocol_1 = require("../runners/gateProtocol");
+const hubClient_1 = require("./hubClient");
+const packageId_1 = require("./packageId");
+const appInstall_1 = require("./appInstall");
+const runnerConfig_1 = require("./runnerConfig");
+/** @description Fetch, verify and install the hub's package; on success `current` and `config.json` point at it. */
+async function updateFromHub(params) {
+    const endpoint = { host: params.config.hub.host, port: params.config.hub.port, user: params.config.hub.user, hostKey: params.config.hub.hostKey };
+    const archivePath = path.join(params.paths.root, `package.${process.pid}.tgz`);
+    try {
+        const client = await (params.connect ?? hubClient_1.connectToHub)(endpoint, params.clientPrivateKey);
+        try {
+            const answer = await (0, hubClient_1.callGate)(client, 'package', null);
+            const expectedId = answer?.marker.fields.id;
+            if (answer === null || expectedId === undefined)
+                return { ok: false, reason: 'the hub did not send the package' };
+            const chunks = [];
+            for await (const chunk of answer.channel)
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+            const archive = Buffer.concat(chunks);
+            if ((0, packageId_1.getPackageIdOfArchive)(archive) !== expectedId)
+                return { ok: false, reason: 'the package the hub sent does not match the id it announced' };
+            fs.writeFileSync(archivePath, archive, { mode: 0o600 });
+            const appDir = (0, appInstall_1.installAppFromArchive)(archivePath, params.paths);
+            (0, appInstall_1.switchCurrentApp)(params.paths, appDir);
+            (0, runnerConfig_1.writeRunnerConfig)(params.paths, { ...params.config, packageId: expectedId });
+            (0, appInstall_1.removeOldApps)(params.paths);
+            return { ok: true, packageId: expectedId };
+        }
+        finally {
+            client.end();
+        }
+    }
+    catch (error) {
+        return { ok: false, reason: error instanceof Error ? error.message : 'the update failed' };
+    }
+    finally {
+        fs.rmSync(archivePath, { force: true });
+    }
+}
+exports.updateRetryDelayMs = 10 * 60 * 1000;
+/** @description Update only to a package the hub named and the runner does not have; only while no command runs; not again right after a failure. */
+function decideUpdate(inputs) {
+    if (inputs.hubPackageId === undefined || inputs.hubPackageId === gateProtocol_1.noPackageMarker || inputs.hubPackageId === inputs.installedPackageId)
+        return 'none';
+    if (inputs.failedPackageId === inputs.hubPackageId && inputs.nowMs - inputs.failedAtMs < exports.updateRetryDelayMs)
+        return 'none';
+    return inputs.activeExecCount === 0 ? 'update-now' : 'wait-until-idle';
+}
+//# sourceMappingURL=appUpdate.js.map

package/dist/runnerUtility/appUpdate.js.map

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

package/dist/runnerUtility/execEnv.d.ts

@@ -0,0 +1,21 @@
+import type { RunnerHomePaths } from './runnerHome';
+/** @description `KEY=VALUE` lines; blank lines and `#` comments are skipped, `export ` is allowed, one pair of quotes around a value is removed. A line that is not a pair is returned in `rejected` (its number, never its text — a value may be a secret). */
+export declare function parseEnvFile(text: string): {
+    values: Record<string, string>;
+    rejected: number[];
+};
+/** @description The Android SDK folder if one is where the installers put it (or the environment says), else `null`. */
+export declare function findAndroidSdk(homeDir: string, environment: NodeJS.ProcessEnv, checkExists?: (candidate: string) => boolean): string | null;
+export interface ExecEnvInputs {
+    paths: RunnerHomePaths;
+    accountName: string;
+    /** The utility's own environment: only LANG and TMPDIR are taken from it. */
+    environment: NodeJS.ProcessEnv;
+    nodeDir: string;
+    operatorEnv: Readonly<Record<string, string>>;
+    androidSdk: string | null;
+}
+export declare function buildExecEnv(inputs: ExecEnvInputs): NodeJS.ProcessEnv;
+/** @description The environment for the next command: the `env` file is read fresh each time, so an edit applies to the next job without a restart. */
+export declare function readExecEnv(paths: RunnerHomePaths, environment?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+//# sourceMappingURL=execEnv.d.ts.map

package/dist/runnerUtility/execEnv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execEnv.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/execEnv.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAapD,gQAAgQ;AAChQ,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAiBjG;AAED,wHAAwH;AACxH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,UAAU,EAAE,WAAW,GAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAuB,GAAG,MAAM,GAAG,IAAI,CAG1J;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,eAAe,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC,UAAU,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9C,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAAC,UAAU,CAYrE;AAED,uJAAuJ;AACvJ,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,EAAE,WAAW,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAAC,UAAU,CAenH"}

package/dist/runnerUtility/execEnv.js

@@ -0,0 +1,109 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEnvFile = parseEnvFile;
+exports.findAndroidSdk = findAndroidSdk;
+exports.buildExecEnv = buildExecEnv;
+exports.readExecEnv = readExecEnv;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+/**
+ * @description The environment of a command that runs over the link — CLEAN, like a login by a service: the runner's own environment
+ * (a launchd job's, a terminal's) never leaks into the agents' jobs. HOME, USER, LOGNAME, LANG, TMPDIR; a PATH of `~/.charness-runner/bin`
+ * (pueue, rsync), the folder of the `node` that runs the utility, the Homebrew and system folders; the Android SDK when it is where
+ * the usual installers put it; then the operator's own `KEY=VALUE` lines from `~/.charness-runner/env`.
+ */
+const systemPathDirs = ['/opt/homebrew/bin', '/opt/homebrew/sbin', '/usr/local/bin', '/usr/local/sbin', '/usr/bin', '/bin', '/usr/sbin', '/sbin'];
+const defaultLang = 'en_US.UTF-8';
+const envNamePattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** @description `KEY=VALUE` lines; blank lines and `#` comments are skipped, `export ` is allowed, one pair of quotes around a value is removed. A line that is not a pair is returned in `rejected` (its number, never its text — a value may be a secret). */
+function parseEnvFile(text) {
+    const values = {};
+    const rejected = [];
+    text.split('\n').forEach((rawLine, index) => {
+        const line = rawLine.trim().replace(/^export\s+/, '');
+        if (line === '' || line.startsWith('#'))
+            return;
+        const separator = line.indexOf('=');
+        const name = separator === -1 ? '' : line.slice(0, separator).trim();
+        if (!envNamePattern.test(name)) {
+            rejected.push(index + 1);
+            return;
+        }
+        let value = line.slice(separator + 1).trim();
+        if (value.length >= 2 && (value.startsWith('"') || value.startsWith("'")) && value.endsWith(value[0]))
+            value = value.slice(1, -1);
+        values[name] = value;
+    });
+    return { values, rejected };
+}
+/** @description The Android SDK folder if one is where the installers put it (or the environment says), else `null`. */
+function findAndroidSdk(homeDir, environment, checkExists = fs.existsSync) {
+    const candidates = [environment.ANDROID_HOME, environment.ANDROID_SDK_ROOT, path.join(homeDir, 'Library', 'Android', 'sdk'), path.join(homeDir, 'Android', 'Sdk'), '/opt/android-sdk'];
+    return candidates.find((candidate) => candidate !== undefined && candidate !== '' && checkExists(candidate)) ?? null;
+}
+function buildExecEnv(inputs) {
+    const pathDirs = [inputs.paths.binDir, inputs.nodeDir, ...systemPathDirs];
+    return {
+        HOME: inputs.paths.homeDir,
+        USER: inputs.accountName,
+        LOGNAME: inputs.accountName,
+        LANG: inputs.environment.LANG ?? defaultLang,
+        TMPDIR: inputs.environment.TMPDIR ?? os.tmpdir(),
+        PATH: [...new Set(pathDirs)].join(path.delimiter),
+        ...(inputs.androidSdk === null ? {} : { ANDROID_HOME: inputs.androidSdk, ANDROID_SDK_ROOT: inputs.androidSdk }),
+        ...inputs.operatorEnv,
+    };
+}
+/** @description The environment for the next command: the `env` file is read fresh each time, so an edit applies to the next job without a restart. */
+function readExecEnv(paths, environment = process.env) {
+    let operatorEnv = {};
+    try {
+        operatorEnv = parseEnvFile(fs.readFileSync(paths.envFile, 'utf8')).values;
+    }
+    catch {
+        operatorEnv = {};
+    }
+    return buildExecEnv({
+        paths,
+        accountName: os.userInfo().username,
+        environment,
+        nodeDir: path.dirname(process.execPath),
+        operatorEnv,
+        androidSdk: findAndroidSdk(paths.homeDir, environment),
+    });
+}
+//# sourceMappingURL=execEnv.js.map

package/dist/runnerUtility/execEnv.js.map

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

package/dist/runnerUtility/execSession.d.ts

@@ -0,0 +1,13 @@
+import type { ServerChannel } from 'ssh2';
+export interface ExecTracker {
+    started: () => void;
+    ended: () => void;
+}
+export interface ExecOptions {
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    tracker: ExecTracker;
+}
+/** @description Run `command` for `channel`. */
+export declare function serveExec(channel: ServerChannel, command: string, options: ExecOptions): void;
+//# sourceMappingURL=execSession.d.ts.map

package/dist/runnerUtility/execSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execSession.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/execSession.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAe1C,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,WAAW,CAAC;CACtB;AAYD,gDAAgD;AAChD,wBAAgB,SAAS,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CA2B7F"}

package/dist/runnerUtility/execSession.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serveExec = serveExec;
+const child_process_1 = require("child_process");
+/**
+ * @description One `exec` request of a session: the command runs under `bash -c` in a clean environment, its stdin is the channel's
+ * (the client's EOF is the command's EOF — phase 1's lease relies on it), its stdout and stderr go back on the channel's two streams,
+ * and its end is reported as an exit status or a signal.
+ *
+ * Sshd's semantics for a channel that is CLOSED by the client: the pipes close, the command is NOT killed. Here: stdout and stderr are
+ * destroyed (the command's next write fails, as with a closed pipe), its stdin is closed, and the process runs on. Only the real end
+ * of the process closes the books on it ({@link ExecTracker.ended}), which is what «the runner is busy» means.
+ */
+const commandNotFoundStatus = 127;
+const signalPrefix = /^SIG/;
+function sendExitStatus(channel, exitCode, signal) {
+    try {
+        if (signal !== null)
+            channel.exit(signal.replace(signalPrefix, ''), false, '');
+        else
+            channel.exit(exitCode ?? commandNotFoundStatus);
+        channel.end();
+    }
+    catch {
+        // The client closed the channel first: nobody is waiting for the status.
+    }
+}
+/** @description Run `command` for `channel`. */
+function serveExec(channel, command, options) {
+    options.tracker.started();
+    const child = (0, child_process_1.spawn)('bash', ['-c', command], { env: options.env, cwd: options.cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+    child.stdin.on('error', () => undefined);
+    channel.on('error', () => undefined);
+    channel.stderr.on('error', () => undefined);
+    channel.pipe(child.stdin);
+    child.stdout.pipe(channel, { end: false });
+    child.stderr.pipe(channel.stderr, { end: false });
+    channel.once('close', () => {
+        child.stdin.destroy();
+        child.stdout.destroy();
+        child.stderr.destroy();
+    });
+    // A failed start emits `error` and then `close`: the command is finished exactly once, or the busy count would go negative.
+    let isFinished = false;
+    const finish = (exitCode, signal) => {
+        if (isFinished)
+            return;
+        isFinished = true;
+        sendExitStatus(channel, exitCode, signal);
+        options.tracker.ended();
+    };
+    child.once('error', (error) => {
+        channel.stderr.write(`charness-runner: cannot start the command (${error.message})\n`);
+        finish(commandNotFoundStatus, null);
+    });
+    child.once('close', (exitCode, signal) => finish(exitCode, signal));
+}
+//# sourceMappingURL=execSession.js.map

package/dist/runnerUtility/execSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execSession.js","sourceRoot":"","sources":["../../src/runnerUtility/execSession.ts"],"names":[],"mappings":";;AAsCA,8BA2BC;AAjED,iDAAsC;AAGtC;;;;;;;;GAQG;AAEH,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAClC,MAAM,YAAY,GAAG,MAAM,CAAC;AAa5B,SAAS,cAAc,CAAC,OAAsB,EAAE,QAAuB,EAAE,MAA6B;IACpG,IAAI,CAAC;QACH,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;;YAC1E,OAAO,CAAC,IAAI,CAAC,QAAQ,IAAI,qBAAqB,CAAC,CAAC;QACrD,OAAO,CAAC,GAAG,EAAE,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;IAC3E,CAAC;AACH,CAAC;AAED,gDAAgD;AAChD,SAAgB,SAAS,CAAC,OAAsB,EAAE,OAAe,EAAE,OAAoB;IACrF,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IAC1B,MAAM,KAAK,GAAG,IAAA,qBAAK,EAAC,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IACtH,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACzC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACrC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC5C,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC1B,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3C,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE;QACzB,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACtB,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC,CAAC,CAAC;IACH,4HAA4H;IAC5H,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,MAAM,MAAM,GAAG,CAAC,QAAuB,EAAE,MAA6B,EAAQ,EAAE;QAC9E,IAAI,UAAU;YAAE,OAAO;QACvB,UAAU,GAAG,IAAI,CAAC;QAClB,cAAc,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC1C,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;QAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8CAA8C,KAAK,CAAC,OAAO,KAAK,CAAC,CAAC;QACvF,MAAM,CAAC,qBAAqB,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IACH,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;AACtE,CAAC"}

package/dist/runnerUtility/hubClient.d.ts

@@ -0,0 +1,30 @@
+import { Client, type ClientChannel } from 'ssh2';
+import type { z } from 'zod';
+import { type GateMarker, type GateRequest } from '../runners/gateProtocol';
+export interface HubEndpoint {
+    host: string;
+    port: number;
+    user: string;
+    /** `<type> <base64>`: the only host key that is accepted. */
+    hostKey: string;
+}
+export type HubConnectionFailure = 'auth' | 'hostKey' | 'network';
+/** @description Why the hub could not be reached: the key was refused (`auth` — for a paired runner, it was removed), the host key is not the pinned one, or the network/sshd. */
+export declare class HubConnectionError extends Error {
+    readonly failure: HubConnectionFailure;
+    constructor(failure: HubConnectionFailure, message: string);
+}
+/** @description Connect and log in; resolves with the ready client. The caller ends it. */
+export declare function connectToHub(endpoint: HubEndpoint, privateKey: string): Promise<Client>;
+export interface GateAnswer {
+    marker: GateMarker;
+    /** The channel, positioned right after the marker line (what came with it is put back). */
+    channel: ClientChannel;
+}
+/** @description Run the gate request `request` and read its marker line; `null` when the answer has none (the hub refused, or the key line is gone). `body` is sent as stdin and ends it; without one stdin stays open (`link`). */
+export declare function callGate(client: Client, request: GateRequest, body: string | null): Promise<GateAnswer | null>;
+/** @description Everything the channel still sends, as text. */
+export declare function readChannelText(channel: ClientChannel): Promise<string>;
+/** @description A gate request whose answer is one JSON line (`redeem`, `cancel`, `identity`, `unpair`), parsed with `schema`. */
+export declare function requestGateJson<TReply>(client: Client, request: 'redeem' | 'cancel' | 'unpair' | 'identity', body: string | null, schema: z.ZodType<TReply>): Promise<TReply>;
+//# sourceMappingURL=hubClient.d.ts.map

package/dist/runnerUtility/hubClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hubClient.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/hubClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAA+B,MAAM,MAAM,CAAC;AAC/E,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAuB,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAejG,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AAElE,kLAAkL;AAClL,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;gBAE3B,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM;CAK3D;AAiBD,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA+BvF;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,UAAU,CAAC;IACnB,2FAA2F;IAC3F,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,oOAAoO;AACpO,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAkB9G;AAED,gEAAgE;AAChE,wBAAsB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAI7E;AAED,kIAAkI;AAClI,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAanL"}

package/dist/runnerUtility/hubClient.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HubConnectionError = void 0;
+exports.connectToHub = connectToHub;
+exports.callGate = callGate;
+exports.readChannelText = readChannelText;
+exports.requestGateJson = requestGateJson;
+const ssh2_1 = require("ssh2");
+const gateProtocol_1 = require("../runners/gateProtocol");
+const sshKeys_1 = require("../runners/sshKeys");
+/**
+ * @description The runner's side of every conversation with the hub's sshd: an ssh2 client that pins the hub's host key (the one in the
+ * pairing code, then in `config.json`), logs in with a key, and runs one of the gate's request words (`redeem`, `package`, `link`,
+ * `unpair`). Whatever the hub's shell printed before the gate ran is skipped up to the marker line (`readUntilGateMarker`).
+ */
+const connectReadyTimeoutMs = 20 * 1000;
+const keepaliveIntervalMs = 15 * 1000;
+const keepaliveCountMax = 3;
+const clientAuthenticationLevel = 'client-authentication';
+const hostDeniedText = 'Host denied';
+/** @description Why the hub could not be reached: the key was refused (`auth` — for a paired runner, it was removed), the host key is not the pinned one, or the network/sshd. */
+class HubConnectionError extends Error {
+    failure;
+    constructor(failure, message) {
+        super(message);
+        this.name = 'HubConnectionError';
+        this.failure = failure;
+    }
+}
+exports.HubConnectionError = HubConnectionError;
+/** The signature algorithms the client offers for each key type: only those of the pinned key, so a hub with several host keys cannot answer with another one. */
+const hostKeyAlgorithms = {
+    'ssh-ed25519': ['ssh-ed25519'],
+    'ecdsa-sha2-nistp256': ['ecdsa-sha2-nistp256'],
+    'ecdsa-sha2-nistp384': ['ecdsa-sha2-nistp384'],
+    'ecdsa-sha2-nistp521': ['ecdsa-sha2-nistp521'],
+    'ssh-rsa': ['rsa-sha2-512', 'rsa-sha2-256', 'ssh-rsa'],
+};
+function classifyFailure(error) {
+    if (error.level === clientAuthenticationLevel)
+        return new HubConnectionError('auth', 'the hub refused the runner\'s key');
+    if (error.message.includes(hostDeniedText))
+        return new HubConnectionError('hostKey', 'the hub\'s ssh host key is not the one pinned at pairing');
+    return new HubConnectionError('network', error.message);
+}
+/** @description Connect and log in; resolves with the ready client. The caller ends it. */
+function connectToHub(endpoint, privateKey) {
+    const pinned = (0, sshKeys_1.parsePublicKey)(endpoint.hostKey);
+    const serverHostKey = pinned === null ? undefined : hostKeyAlgorithms[pinned.type];
+    if (pinned === null || serverHostKey === undefined)
+        return Promise.reject(new HubConnectionError('hostKey', 'the pinned hub host key does not read'));
+    const pinnedBlob = pinned.blob;
+    return new Promise((resolve, reject) => {
+        const client = new ssh2_1.Client();
+        let isReady = false;
+        client.once('ready', () => {
+            isReady = true;
+            resolve(client);
+        });
+        // Kept for the life of the client: an error after `ready` (a reset connection) must never be an unhandled event; whoever uses the
+        // client listens for `close` / `error` itself.
+        client.on('error', (error) => {
+            if (isReady)
+                return;
+            client.end();
+            reject(classifyFailure(error));
+        });
+        client.connect({
+            host: endpoint.host,
+            port: endpoint.port,
+            username: endpoint.user,
+            privateKey,
+            algorithms: { serverHostKey },
+            hostVerifier: (key) => Buffer.isBuffer(key) && key.equals(pinnedBlob),
+            keepaliveInterval: keepaliveIntervalMs,
+            keepaliveCountMax,
+            readyTimeout: connectReadyTimeoutMs,
+        });
+    });
+}
+/** @description Run the gate request `request` and read its marker line; `null` when the answer has none (the hub refused, or the key line is gone). `body` is sent as stdin and ends it; without one stdin stays open (`link`). */
+function callGate(client, request, body) {
+    return new Promise((resolve, reject) => {
+        client.exec(request, async (error, channel) => {
+            if (error !== undefined) {
+                reject(new HubConnectionError('network', error.message));
+                return;
+            }
+            if (body !== null)
+                channel.end(body);
+            const read = await (0, gateProtocol_1.readUntilGateMarker)(channel);
+            if (read === null || read.marker.request !== request) {
+                channel.destroy();
+                resolve(null);
+                return;
+            }
+            channel.unshift(read.rest);
+            resolve({ marker: read.marker, channel });
+        });
+    });
+}
+/** @description Everything the channel still sends, as text. */
+async function readChannelText(channel) {
+    const chunks = [];
+    for await (const chunk of channel)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf8');
+}
+/** @description A gate request whose answer is one JSON line (`redeem`, `cancel`, `identity`, `unpair`), parsed with `schema`. */
+async function requestGateJson(client, request, body, schema) {
+    const answer = await callGate(client, request, body ?? '');
+    if (answer === null)
+        throw new HubConnectionError('network', 'the hub did not answer the request');
+    const text = await readChannelText(answer.channel);
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(text);
+    }
+    catch {
+        throw new HubConnectionError('network', 'the hub\'s answer is not valid JSON');
+    }
+    const parsed = schema.safeParse(parsedJson);
+    if (!parsed.success)
+        throw new HubConnectionError('network', 'the hub\'s answer is not what this version expects');
+    return parsed.data;
+}
+//# sourceMappingURL=hubClient.js.map

package/dist/runnerUtility/hubClient.js.map

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

package/dist/runnerUtility/injectStream.d.ts

@@ -0,0 +1,9 @@
+import type { Duplex } from 'stream';
+import type { Server } from 'ssh2';
+/**
+ * @description ssh2's `Server.injectSocket` is typed for a `net.Socket` but takes any bidirectional stream «as though it were a TCP
+ * socket connection» — the channel the hub's gate speaks over, and a `direct-tcpip` channel of that session, are such streams; this is
+ * how the runner serves ssh over a link. The one cast the library's typing needs is here.
+ */
+export declare function injectStreamIntoSshServer(server: Server, stream: Duplex): void;
+//# sourceMappingURL=injectStream.d.ts.map

package/dist/runnerUtility/injectStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"injectStream.d.ts","sourceRoot":"","sources":["../../src/runnerUtility/injectStream.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAE9E"}

package/dist/runnerUtility/injectStream.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.injectStreamIntoSshServer = injectStreamIntoSshServer;
+/**
+ * @description ssh2's `Server.injectSocket` is typed for a `net.Socket` but takes any bidirectional stream «as though it were a TCP
+ * socket connection» — the channel the hub's gate speaks over, and a `direct-tcpip` channel of that session, are such streams; this is
+ * how the runner serves ssh over a link. The one cast the library's typing needs is here.
+ */
+function injectStreamIntoSshServer(server, stream) {
+    server.injectSocket(stream);
+}
+//# sourceMappingURL=injectStream.js.map

package/dist/runnerUtility/injectStream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"injectStream.js","sourceRoot":"","sources":["../../src/runnerUtility/injectStream.ts"],"names":[],"mappings":";;AASA,8DAEC;AAPD;;;;GAIG;AACH,SAAgB,yBAAyB,CAAC,MAAc,EAAE,MAAc;IACtE,MAAM,CAAC,YAAY,CAAC,MAAgB,CAAC,CAAC;AACxC,CAAC"}