charness 3.6.1 → 3.8.0

package/dist/runners/gateLink.js

@@ -0,0 +1,240 @@
+"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.defaultGateLinkTimings = void 0;
+exports.runGateLink = runGateLink;
+const crypto_1 = require("crypto");
+const fs = __importStar(require("fs"));
+const net = __importStar(require("net"));
+const path = __importStar(require("path"));
+const stream_1 = require("stream");
+const ssh2_1 = require("ssh2");
+const configDirFile_1 = require("../configDirFile");
+const gateProtocol_1 = require("./gateProtocol");
+const hubPaths_1 = require("./hubPaths");
+const hubKey_1 = require("./hubKey");
+const hubRegistry_1 = require("./hubRegistry");
+const linkControl_1 = require("./linkControl");
+const sshKeys_1 = require("./sshKeys");
+/**
+ * @description The `link` request: the hub end of a runner's permanent connection.
+ *
+ * The runner dials the hub with an ordinary ssh client and runs `link`; sshd starts this gate, whose stdin and stdout ARE that
+ * channel. Over it the roles turn around: the gate is an ssh CLIENT (`ssh2`) and the runner's built-in server is the SERVER — the gate
+ * checks the server's host key against the one pinned at pairing and logs in with the hub key. The gate then listens on
+ * `link/<id>.sock`; for every connection to it, it opens a `direct-tcpip` channel to the runner, whose server treats the channel as
+ * a socket of its own and speaks ssh over it to whoever is on the other end — stock `ssh` through `runner-proxy`, with everything
+ * remote-run needs from ssh (one master, rsync, exec). The runner has no listening port, and the hub's only exposure is the forced
+ * command of a key that cannot forward anything.
+ *
+ * A request from the runner side to open a channel or a forwarding is refused by the client library itself (nothing is registered
+ * for it); the gate accepts none.
+ *
+ * NEWEST LINK WINS: a gate that starts takes the socket path over (it renames its freshly bound socket onto it). The gate that was
+ * replaced notices within one check interval — the file at the path is not the one it bound — and leaves, which also ends the runner's
+ * half-open old connection. The same check ends a gate whose runner was removed from the registry. A stock sshd with
+ * `ClientAliveInterval 0` would never notice a dead peer; the ssh keepalive of this client does.
+ */
+const loopbackAddress = '127.0.0.1';
+/** The port of the `direct-tcpip` request. The runner's server ignores it: every channel goes to its one ssh server. */
+const runnerServerPort = 22;
+const socketMode = 0o600;
+const linkDirMode = 0o700;
+const socketSuffixBytes = 3;
+const keepaliveCountMax = 3;
+const sshHostKeyAlgorithm = 'ssh-ed25519';
+exports.defaultGateLinkTimings = { checkIntervalMs: 10 * 1000, keepaliveIntervalMs: 15 * 1000, readyTimeoutMs: 20 * 1000 };
+/**
+ * A writable that hands everything to `target` and never ends it: the gate's stdout is `process.stdout`, which is not to be closed
+ * (the gate ends by leaving), and the ssh client ends its transport when it is done.
+ */
+function createNonClosingWritable(target) {
+    return new stream_1.Writable({
+        write(chunk, _encoding, callback) {
+            target.write(chunk, callback);
+        },
+    });
+}
+/** @description Run the link until it ends; resolves with the exit code of the gate (0: it held the link and it ended; 1: it never came up). */
+function runGateLink(params) {
+    const { ctx, runnerId, log } = params;
+    const timings = { ...exports.defaultGateLinkTimings, ...params.timings };
+    const now = params.now ?? Date.now;
+    const paths = (0, hubPaths_1.getRunnerLinkPaths)(ctx.dir, runnerId);
+    const runner = (0, hubRegistry_1.readPairedFile)(ctx.dir).runners.find((candidate) => candidate.id === runnerId);
+    const hubKey = (0, hubKey_1.readHubKey)(ctx.dir);
+    const pinnedHostKey = runner === undefined ? null : (0, sshKeys_1.parsePublicKey)(runner.hostKey);
+    if (runner === undefined || hubKey === null || pinnedHostKey === null) {
+        log('this runner is not paired here');
+        return Promise.resolve(1);
+    }
+    const pinnedBlob = pinnedHostKey.blob;
+    return new Promise((resolve) => {
+        const client = new ssh2_1.Client();
+        const openConnections = new Set();
+        const sinceMs = now();
+        let server = null;
+        let boundInode = null;
+        let checkTimer = null;
+        let isReady = false;
+        let isFinished = false;
+        const duplex = stream_1.Duplex.from({ readable: params.input, writable: createNonClosingWritable(params.output) });
+        const readSocketInode = () => {
+            try {
+                return fs.statSync(paths.socket).ino;
+            }
+            catch {
+                return null;
+            }
+        };
+        const writeState = (state) => {
+            try {
+                (0, linkControl_1.writeLinkState)(ctx.dir, runnerId, state);
+            }
+            catch (error) {
+                // The link works without its status file; the hub only loses "last seen".
+                log(`cannot write the link status (${(0, configDirFile_1.getCaughtErrnoCode)(error)})`);
+            }
+        };
+        const finish = (reason) => {
+            if (isFinished)
+                return;
+            isFinished = true;
+            if (checkTimer !== null)
+                clearInterval(checkTimer);
+            for (const connection of openConnections)
+                connection.destroy();
+            // The socket file is NOT deleted here: checking that the file is still this gate's and then deleting it is two steps, and a
+            // successor may rename its own socket onto the path between them. A leftover file only refuses connections (the runner reads as
+            // offline); the next gate renames over it and `cutRunnerLink` deletes it.
+            server?.close();
+            const state = (0, linkControl_1.readLinkState)(ctx.dir, runnerId);
+            if (isReady && state?.pid === process.pid)
+                writeState({ ...state, endedAtMs: now() });
+            log(`link ended: ${reason}`);
+            client.end();
+            duplex.destroy();
+            resolve(isReady ? 0 : 1);
+        };
+        const beat = () => {
+            writeState({ pid: process.pid, sinceMs, lastBeatMs: now(), endedAtMs: null });
+        };
+        const check = () => {
+            if (readSocketInode() !== boundInode) {
+                finish('another link took over');
+                return;
+            }
+            try {
+                if (!(0, hubRegistry_1.readPairedFile)(ctx.dir).runners.some((candidate) => candidate.id === runnerId)) {
+                    finish('the runner was removed');
+                    return;
+                }
+            }
+            catch {
+                // An unreadable registry says nothing about this runner: keep the link and look again at the next check.
+            }
+            beat();
+        };
+        const acceptConnection = (connection) => {
+            openConnections.add(connection);
+            connection.on('close', () => openConnections.delete(connection));
+            connection.on('error', () => connection.destroy());
+            try {
+                client.forwardOut(loopbackAddress, 0, loopbackAddress, runnerServerPort, (error, channel) => {
+                    if (error !== undefined) {
+                        connection.destroy();
+                        return;
+                    }
+                    if (connection.destroyed) {
+                        channel.destroy();
+                        return;
+                    }
+                    connection.pipe(channel);
+                    channel.pipe(connection);
+                    channel.on('close', () => connection.destroy());
+                    channel.on('error', () => connection.destroy());
+                    connection.on('close', () => channel.destroy());
+                });
+            }
+            catch {
+                connection.destroy();
+            }
+        };
+        // The socket is bound under a name of its own and RENAMED onto the link's path: renaming is the atomic takeover, and a gate that is
+        // replaced closes its server without touching the new gate's file (`net.Server.close()` deletes whatever file is at the path it was
+        // bound to — at the link's path that would be the successor's socket).
+        const bindSocket = () => {
+            fs.mkdirSync(path.dirname(paths.socket), { recursive: true, mode: linkDirMode });
+            const ownPath = `${paths.socket}.${(0, crypto_1.randomBytes)(socketSuffixBytes).toString('hex')}`;
+            const listener = net.createServer(acceptConnection);
+            server = listener;
+            listener.once('error', (error) => finish(`cannot listen on the link socket (${(0, configDirFile_1.getCaughtErrnoCode)(error)})`));
+            listener.listen(ownPath, () => {
+                try {
+                    fs.chmodSync(ownPath, socketMode);
+                    boundInode = fs.statSync(ownPath).ino;
+                    fs.renameSync(ownPath, paths.socket);
+                }
+                catch (error) {
+                    finish(`cannot publish the link socket (${(0, configDirFile_1.getCaughtErrnoCode)(error)})`);
+                    return;
+                }
+                isReady = true;
+                beat();
+                checkTimer = setInterval(check, timings.checkIntervalMs);
+            });
+        };
+        params.output.write((0, gateProtocol_1.formatGateAnswerHead)('link', { package: params.packageId ?? gateProtocol_1.noPackageMarker }));
+        duplex.on('error', () => finish('the connection to the runner failed'));
+        // The channel from the runner ended cleanly (EOF: the ssh session that carried it is gone). A duplex whose readable side ended stays half
+        // open, so the ssh client never sees a close — only a failed write or the keepalive's silence would tell, and until then the hub shows a
+        // runner that has left as online.
+        params.input.once('end', () => finish('the channel from the runner ended'));
+        client.on('error', (error) => finish(`ssh: ${error.message}`));
+        client.on('close', () => finish('the runner disconnected'));
+        client.on('ready', bindSocket);
+        client.connect({
+            sock: duplex,
+            username: gateProtocol_1.linkUserName,
+            privateKey: hubKey.privateKey,
+            algorithms: { serverHostKey: [sshHostKeyAlgorithm] },
+            hostVerifier: (key) => Buffer.isBuffer(key) && key.equals(pinnedBlob),
+            keepaliveInterval: timings.keepaliveIntervalMs,
+            keepaliveCountMax,
+            readyTimeout: timings.readyTimeoutMs,
+        });
+    });
+}
+//# sourceMappingURL=gateLink.js.map

package/dist/runners/gateLink.js.map

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

package/dist/runners/gateProtocol.d.ts

@@ -0,0 +1,98 @@
+import type { Readable } from 'stream';
+import { z } from 'zod';
+/**
+ * @description What a runner and the hub's gate say to each other over the forced command of the runner's ssh key. The runner runs
+ * `ssh … <request>`; sshd starts the gate with the request word in `SSH_ORIGINAL_COMMAND`.
+ *
+ *   temporary key (a pairing code):  `bootstrap`  marker line, then the packed charness package (raw gzip)
+ *                                    `redeem`     stdin: a {@link RedeemRequest} as JSON; stdout: marker line, then a {@link RedeemReply}
+ *   permanent key (a paired runner): `link`       marker line, then an ssh session in which the GATE is the client (see gateLink.ts)
+ *                                    `package`    marker line, then the packed package (raw gzip)
+ *                                    `version`    marker line with the hub's current `package=<id>`, nothing else — asked every few minutes over
+ *                                                 the connection that is already open, so a linked runner learns of an update
+ *                                    `identity`   marker line, then a {@link RedeemReply} — what `redeem` answered for this key's runner. The
+ *                                                 way back for a runner whose redeem answer was lost: the hub committed the pairing and
+ *                                                 removed the temporary key, so only the permanent key can still ask
+ *                                    `unpair`     marker line, then {@link UnpairReply}
+ *
+ * Every answer starts with a MARKER line (after a line break, see {@link formatGateAnswerHead}): a shell that prints something before the
+ * forced command (a chatty `.bashrc`) would otherwise corrupt the stream; the reader discards everything up to the marker — the runner
+ * utility with {@link readUntilGateMarker}, the pasted `sh` line with `grep -b` over the first {@link maxGateNoiseBytes} bytes.
+ */
+/** The text every marker line starts with; the `1` is the protocol version. */
+export declare const gateMarker = "--charness-gate-1--";
+export declare const gateRequests: readonly ["bootstrap", "redeem", "link", "package", "version", "identity", "unpair"];
+/** @name GateRequest @description One of the words a runner may send. */
+export type GateRequest = (typeof gateRequests)[number];
+export declare const temporaryKeyRequests: readonly GateRequest[];
+export declare const runnerKeyRequests: readonly GateRequest[];
+/** What a `link` / `version` answer names as the package when the hub cannot pack one. */
+export declare const noPackageMarker = "none";
+/** The username the gate's ssh client logs in with inside the link (the runner's server ignores it). */
+export declare const linkUserName = "charness";
+/** The most bytes of a request body the gate reads from stdin. */
+export declare const maxGateRequestBytes: number;
+/**
+ * @description What every answer of the gate starts with: a line break, then the marker line. The break ends whatever unfinished line a
+ * shell rc printed before the gate ran (a banner without its newline), so the marker always opens a line of its own.
+ */
+export declare function formatGateAnswerHead(request: GateRequest, fields?: Readonly<Record<string, string>>): string;
+/** @description `--charness-gate-1-- link package=abc…`, newline included. Field values are limited to a safe alphabet. */
+export declare function formatGateMarkerLine(request: GateRequest, fields?: Readonly<Record<string, string>>): string;
+export interface GateMarker {
+    request: GateRequest;
+    fields: Record<string, string>;
+}
+/** @description The marker `line` (without its newline) says, or `null` when it is not a marker line. */
+export declare function parseGateMarkerLine(line: string): GateMarker | null;
+/** How much text before the marker (a chatty shell rc) a reader puts up with. */
+export declare const maxGateNoiseBytes: number;
+/**
+ * @description Read `stream` up to and including the marker line: lines before it (noise from the hub's shell) are dropped. Resolves with
+ * the marker and the bytes that followed it in what was read — the caller puts them back (`stream.unshift(rest)`) before handing the
+ * stream on, since they already belong to the answer. `null`: the stream ended or the noise was too long without a marker. The stream
+ * is paused when this resolves.
+ */
+export declare function readUntilGateMarker(stream: Readable, maxNoiseBytes?: number): Promise<{
+    marker: GateMarker;
+    rest: Buffer;
+} | null>;
+/** @description What the runner tells the hub when it redeems a pairing code. */
+export declare const redeemRequestSchema: z.ZodObject<{
+    suggestedName: z.ZodString;
+    publicKey: z.ZodString;
+    hostKey: z.ZodString;
+    workDir: z.ZodString;
+    os: z.ZodString;
+    arch: z.ZodString;
+    version: z.ZodString;
+    serviceKind: z.ZodEnum<{
+        unknown: "unknown";
+        foreground: "foreground";
+        "user-service": "user-service";
+        "system-service": "system-service";
+    }>;
+}, z.core.$strict>;
+/** @name RedeemRequest @description The body of a `redeem`. */
+export type RedeemRequest = z.infer<typeof redeemRequestSchema>;
+export declare const redeemReplySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    runnerId: z.ZodString;
+    name: z.ZodString;
+    hubPublicKey: z.ZodString;
+    label: z.ZodString;
+    host: z.ZodString;
+    port: z.ZodNumber;
+    packageId: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    reason: z.ZodString;
+}, z.core.$strict>], "ok">;
+/** @name RedeemReply @description What `redeem` answers. */
+export type RedeemReply = z.infer<typeof redeemReplySchema>;
+export declare const unpairReplySchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+}, z.core.$strict>;
+/** @name UnpairReply @description What `unpair` answers. */
+export type UnpairReply = z.infer<typeof unpairReplySchema>;
+//# sourceMappingURL=gateProtocol.d.ts.map

package/dist/runners/gateProtocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateProtocol.d.ts","sourceRoot":"","sources":["../../src/runners/gateProtocol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;;;;;;;;;;;;;;;;;GAkBG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,UAAU,wBAAwB,CAAC;AAChD,eAAO,MAAM,YAAY,sFAAuF,CAAC;AACjH,yEAAyE;AACzE,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD,eAAO,MAAM,oBAAoB,EAAE,SAAS,WAAW,EAA4B,CAAC;AACpF,eAAO,MAAM,iBAAiB,EAAE,SAAS,WAAW,EAAyD,CAAC;AAE9G,0FAA0F;AAC1F,eAAO,MAAM,eAAe,SAAS,CAAC;AACtC,wGAAwG;AACxG,eAAO,MAAM,YAAY,aAAa,CAAC;AACvC,kEAAkE;AAClE,eAAO,MAAM,mBAAmB,QAAY,CAAC;AAK7C;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,GAAG,MAAM,CAEhH;AAMD,2HAA2H;AAC3H,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,GAAG,MAAM,CAGhH;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,WAAW,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,yGAAyG;AACzG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CASnE;AAGD,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,QAAY,CAAC;AAE3C;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAE,MAA0B,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAsCrJ;AAID,iFAAiF;AACjF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;kBAU9B,CAAC;AACH,+DAA+D;AAC/D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;0BAa5B,CAAC;AACH,4DAA4D;AAC5D,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,iBAAiB;;kBAAsC,CAAC;AACrE,4DAA4D;AAC5D,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/runners/gateProtocol.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unpairReplySchema = exports.redeemReplySchema = exports.redeemRequestSchema = exports.maxGateNoiseBytes = exports.maxGateRequestBytes = exports.linkUserName = exports.noPackageMarker = exports.runnerKeyRequests = exports.temporaryKeyRequests = exports.gateRequests = exports.gateMarker = void 0;
+exports.formatGateAnswerHead = formatGateAnswerHead;
+exports.formatGateMarkerLine = formatGateMarkerLine;
+exports.parseGateMarkerLine = parseGateMarkerLine;
+exports.readUntilGateMarker = readUntilGateMarker;
+const zod_1 = require("zod");
+const runnersConfig_1 = require("../remoteRun/runnersConfig");
+const hubIds_1 = require("./hubIds");
+const sshKeys_1 = require("./sshKeys");
+const hubRegistry_1 = require("./hubRegistry");
+/**
+ * @description What a runner and the hub's gate say to each other over the forced command of the runner's ssh key. The runner runs
+ * `ssh … <request>`; sshd starts the gate with the request word in `SSH_ORIGINAL_COMMAND`.
+ *
+ *   temporary key (a pairing code):  `bootstrap`  marker line, then the packed charness package (raw gzip)
+ *                                    `redeem`     stdin: a {@link RedeemRequest} as JSON; stdout: marker line, then a {@link RedeemReply}
+ *   permanent key (a paired runner): `link`       marker line, then an ssh session in which the GATE is the client (see gateLink.ts)
+ *                                    `package`    marker line, then the packed package (raw gzip)
+ *                                    `version`    marker line with the hub's current `package=<id>`, nothing else — asked every few minutes over
+ *                                                 the connection that is already open, so a linked runner learns of an update
+ *                                    `identity`   marker line, then a {@link RedeemReply} — what `redeem` answered for this key's runner. The
+ *                                                 way back for a runner whose redeem answer was lost: the hub committed the pairing and
+ *                                                 removed the temporary key, so only the permanent key can still ask
+ *                                    `unpair`     marker line, then {@link UnpairReply}
+ *
+ * Every answer starts with a MARKER line (after a line break, see {@link formatGateAnswerHead}): a shell that prints something before the
+ * forced command (a chatty `.bashrc`) would otherwise corrupt the stream; the reader discards everything up to the marker — the runner
+ * utility with {@link readUntilGateMarker}, the pasted `sh` line with `grep -b` over the first {@link maxGateNoiseBytes} bytes.
+ */
+/** The text every marker line starts with; the `1` is the protocol version. */
+exports.gateMarker = '--charness-gate-1--';
+exports.gateRequests = ['bootstrap', 'redeem', 'link', 'package', 'version', 'identity', 'unpair'];
+exports.temporaryKeyRequests = ['bootstrap', 'redeem'];
+exports.runnerKeyRequests = ['link', 'package', 'version', 'identity', 'unpair'];
+/** What a `link` / `version` answer names as the package when the hub cannot pack one. */
+exports.noPackageMarker = 'none';
+/** The username the gate's ssh client logs in with inside the link (the runner's server ignores it). */
+exports.linkUserName = 'charness';
+/** The most bytes of a request body the gate reads from stdin. */
+exports.maxGateRequestBytes = 64 * 1024;
+const maxTextLength = 200;
+const markerLinePattern = new RegExp(`^${exports.gateMarker} (${exports.gateRequests.join('|')})((?: [a-z]+=[A-Za-z0-9._:@/-]*)*)$`);
+/**
+ * @description What every answer of the gate starts with: a line break, then the marker line. The break ends whatever unfinished line a
+ * shell rc printed before the gate ran (a banner without its newline), so the marker always opens a line of its own.
+ */
+function formatGateAnswerHead(request, fields = {}) {
+    return `\n${formatGateMarkerLine(request, fields)}`;
+}
+function checkIsGateRequest(value) {
+    return exports.gateRequests.some((request) => request === value);
+}
+/** @description `--charness-gate-1-- link package=abc…`, newline included. Field values are limited to a safe alphabet. */
+function formatGateMarkerLine(request, fields = {}) {
+    const rendered = Object.entries(fields).map(([key, value]) => ` ${key}=${value}`).join('');
+    return `${exports.gateMarker} ${request}${rendered}\n`;
+}
+/** @description The marker `line` (without its newline) says, or `null` when it is not a marker line. */
+function parseGateMarkerLine(line) {
+    const match = markerLinePattern.exec(line);
+    if (match === null || !checkIsGateRequest(match[1]))
+        return null;
+    const fields = {};
+    for (const field of match[2].split(' ').filter((part) => part !== '')) {
+        const separator = field.indexOf('=');
+        fields[field.slice(0, separator)] = field.slice(separator + 1);
+    }
+    return { request: match[1], fields };
+}
+const newlineByte = 0x0a;
+/** How much text before the marker (a chatty shell rc) a reader puts up with. */
+exports.maxGateNoiseBytes = 64 * 1024;
+/**
+ * @description Read `stream` up to and including the marker line: lines before it (noise from the hub's shell) are dropped. Resolves with
+ * the marker and the bytes that followed it in what was read — the caller puts them back (`stream.unshift(rest)`) before handing the
+ * stream on, since they already belong to the answer. `null`: the stream ended or the noise was too long without a marker. The stream
+ * is paused when this resolves.
+ */
+function readUntilGateMarker(stream, maxNoiseBytes = exports.maxGateNoiseBytes) {
+    return new Promise((resolve) => {
+        let buffered = Buffer.alloc(0);
+        let droppedBytes = 0;
+        const settle = (result) => {
+            stream.off('data', onData);
+            stream.off('end', onEnd);
+            stream.off('close', onEnd);
+            stream.pause();
+            resolve(result);
+        };
+        const onData = (chunk) => {
+            buffered = Buffer.concat([buffered, chunk]);
+            for (;;) {
+                const newline = buffered.indexOf(newlineByte);
+                if (newline === -1) {
+                    if (droppedBytes + buffered.length > maxNoiseBytes)
+                        settle(null);
+                    return;
+                }
+                const marker = parseGateMarkerLine(buffered.subarray(0, newline).toString('utf8').replace(/\r$/, ''));
+                const rest = buffered.subarray(newline + 1);
+                if (marker !== null) {
+                    settle({ marker, rest });
+                    return;
+                }
+                droppedBytes += newline + 1;
+                buffered = rest;
+                if (droppedBytes > maxNoiseBytes) {
+                    settle(null);
+                    return;
+                }
+            }
+        };
+        const onEnd = () => settle(null);
+        stream.on('data', onData);
+        stream.once('end', onEnd);
+        stream.once('close', onEnd);
+    });
+}
+const publicKeySchema = zod_1.z.string().refine(sshKeys_1.checkIsEd25519PublicKey, 'must be an ed25519 public key (type and key, no comment)');
+/** @description What the runner tells the hub when it redeems a pairing code. */
+exports.redeemRequestSchema = zod_1.z.strictObject({
+    /** A name the runner would like (its host name); the hub makes it valid and unique. */
+    suggestedName: zod_1.z.string().max(maxTextLength),
+    publicKey: publicKeySchema,
+    hostKey: publicKeySchema,
+    workDir: runnersConfig_1.runnerWorkDirSchema,
+    os: zod_1.z.string().max(maxTextLength),
+    arch: zod_1.z.string().max(maxTextLength),
+    version: zod_1.z.string().max(maxTextLength),
+    serviceKind: zod_1.z.enum(hubRegistry_1.runnerServiceKinds),
+});
+exports.redeemReplySchema = zod_1.z.discriminatedUnion('ok', [
+    zod_1.z.strictObject({
+        ok: zod_1.z.literal(true),
+        runnerId: hubIds_1.hubIdSchema,
+        name: zod_1.z.string(),
+        hubPublicKey: publicKeySchema,
+        label: zod_1.z.string(),
+        host: zod_1.z.string(),
+        port: zod_1.z.number().int(),
+        /** The hub's current package (what the runner just downloaded, or something newer); `null` when it cannot be packed. */
+        packageId: zod_1.z.string().nullable(),
+    }),
+    zod_1.z.strictObject({ ok: zod_1.z.literal(false), reason: zod_1.z.string() }),
+]);
+exports.unpairReplySchema = zod_1.z.strictObject({ ok: zod_1.z.boolean() });
+//# sourceMappingURL=gateProtocol.js.map

package/dist/runners/gateProtocol.js.map

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

package/dist/runners/gateWrapper.d.ts

@@ -0,0 +1,6 @@
+import { type HubContext } from './hubPaths';
+/** @description The text of the wrapper for `ctx`. */
+export declare function renderGateWrapper(ctx: Pick<HubContext, 'nodePath' | 'cliPath'>): string;
+/** @description Write the wrapper (only when it differs from what is there) and return its path. */
+export declare function ensureGateWrapper(ctx: HubContext): string;
+//# sourceMappingURL=gateWrapper.d.ts.map

package/dist/runners/gateWrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateWrapper.d.ts","sourceRoot":"","sources":["../../src/runners/gateWrapper.ts"],"names":[],"mappings":"AAIA,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAW9D,sDAAsD;AACtD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC,GAAG,MAAM,CAEvF;AAED,oGAAoG;AACpG,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAYzD"}

package/dist/runners/gateWrapper.js

@@ -0,0 +1,70 @@
+"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.renderGateWrapper = renderGateWrapper;
+exports.ensureGateWrapper = ensureGateWrapper;
+const fs = __importStar(require("fs"));
+const configDirFile_1 = require("../configDirFile");
+const tmuxExec_1 = require("../utils/tmuxExec");
+const hubLock_1 = require("./hubLock");
+const hubPaths_1 = require("./hubPaths");
+/**
+ * @description The `gate` file every runner key's `authorized_keys` line points at: a two-line `sh` wrapper that runs THIS install's
+ * `node` on THIS install's `cli.js`. The lines carry its path (not node's or the checkout's), and the file is rewritten at every
+ * start, so a Node upgrade, a moved checkout or a switch from npm to a git checkout never leaves a key line pointing at nothing.
+ */
+const wrapperMode = 0o700;
+const permissionBitsMask = 0o777;
+/** @description The text of the wrapper for `ctx`. */
+function renderGateWrapper(ctx) {
+    return `#!/bin/sh\nexec ${(0, tmuxExec_1.shellSingleQuote)(ctx.nodePath)} ${(0, tmuxExec_1.shellSingleQuote)(ctx.cliPath)} runner-gate "$@"\n`;
+}
+/** @description Write the wrapper (only when it differs from what is there) and return its path. */
+function ensureGateWrapper(ctx) {
+    (0, hubLock_1.ensureHubDir)(ctx.dir);
+    const gatePath = (0, hubPaths_1.getHubFilePaths)(ctx.dir).gate;
+    const text = renderGateWrapper(ctx);
+    let current = null;
+    try {
+        current = fs.readFileSync(gatePath, 'utf8');
+    }
+    catch {
+        current = null;
+    }
+    if (current !== text || (fs.statSync(gatePath).mode & permissionBitsMask) !== wrapperMode)
+        (0, configDirFile_1.writeTextFileAtomically)(gatePath, text, wrapperMode);
+    return gatePath;
+}
+//# sourceMappingURL=gateWrapper.js.map

package/dist/runners/gateWrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateWrapper.js","sourceRoot":"","sources":["../../src/runners/gateWrapper.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgBA,8CAEC;AAGD,8CAYC;AAjCD,uCAAyB;AACzB,oDAA2D;AAC3D,gDAAqD;AACrD,uCAAyC;AACzC,yCAA8D;AAE9D;;;;GAIG;AAEH,MAAM,WAAW,GAAG,KAAK,CAAC;AAC1B,MAAM,kBAAkB,GAAG,KAAK,CAAC;AAEjC,sDAAsD;AACtD,SAAgB,iBAAiB,CAAC,GAA6C;IAC7E,OAAO,mBAAmB,IAAA,2BAAgB,EAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,IAAA,2BAAgB,EAAC,GAAG,CAAC,OAAO,CAAC,qBAAqB,CAAC;AACjH,CAAC;AAED,oGAAoG;AACpG,SAAgB,iBAAiB,CAAC,GAAe;IAC/C,IAAA,sBAAY,EAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACtB,MAAM,QAAQ,GAAG,IAAA,0BAAe,EAAC,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;IAC/C,MAAM,IAAI,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,OAAO,GAAkB,IAAI,CAAC;IAClC,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IACD,IAAI,OAAO,KAAK,IAAI,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,GAAG,kBAAkB,CAAC,KAAK,WAAW;QAAE,IAAA,uCAAuB,EAAC,QAAQ,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;IAChJ,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/runners/hubAddress.d.ts

@@ -0,0 +1,33 @@
+export interface HubAddress {
+    host: string;
+    port: number;
+}
+export type HubAddressParsing = {
+    ok: true;
+    address: HubAddress;
+} | {
+    ok: false;
+    error: string;
+};
+/** @description `host`, `host:port`, `[v6]:port` or a bare IPv6 address, as an address (port 22 when none is given). */
+export declare function parseHubAddress(text: string): HubAddressParsing;
+/** @description The host key to pin out of `ssh-keyscan` output: the most preferred type that is a well-formed key, as `<type> <base64>`. */
+export declare function parseKeyscanOutput(output: string): string | null;
+/** @description Reads the ssh host key an address answers with (`null`: nothing answered). */
+export type HostKeyScanner = (host: string, port: number) => Promise<string | null>;
+/** @description The real scanner: `ssh-keyscan`, bounded. */
+export declare const scanHostKey: HostKeyScanner;
+export type HubAddressCheck = {
+    ok: true;
+    hostKey: string;
+    note: string | null;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * @description Does `address` answer with an ssh server, and is it this machine's own? Returns the host key to pin. The machine's own
+ * sshd is read on its loopback; when that cannot be read the address is accepted with a note that it was not compared.
+ */
+export declare function checkHubAddress(address: HubAddress, scan: HostKeyScanner): Promise<HubAddressCheck>;
+//# sourceMappingURL=hubAddress.d.ts.map

package/dist/runners/hubAddress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hubAddress.d.ts","sourceRoot":"","sources":["../../src/runners/hubAddress.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,iBAAiB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjG,wHAAwH;AACxH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAS/D;AAED,6IAA6I;AAC7I,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWhE;AAED,8FAA8F;AAC9F,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAEpF,6DAA6D;AAC7D,eAAO,MAAM,WAAW,EAAE,cAcxB,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAMhH;;;GAGG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAUzG"}