charness 3.6.1 → 3.8.0

package/dist/runners/authorizedKeys.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @description The part of the account's `authorized_keys` that charness owns: ONE marked block, replaced as a whole and derived from
+ * the registry (`hubRegistry.ts` renders it), so the file and the registry never drift apart. Every line outside the markers is the
+ * operator's and is kept byte for byte. A file with a damaged block (a marker without its twin, two blocks) is NOT edited — guessing
+ * which lines are ours could delete a key of the operator.
+ *
+ * A runner's key is a forced-command key with NO forwarding of any kind: `restrict` turns off port, unix-socket, agent and X11
+ * forwarding, ptys and `~/.ssh/rc`; OpenSSH cannot limit forwarding of unix sockets in any finer way, and a key that could forward
+ * one could open the bot's tmux sockets.
+ */
+export declare const authorizedKeysBlockStart = "# charness runners: managed block, do not edit between the markers";
+export declare const authorizedKeysBlockEnd = "# charness runners: end of the managed block";
+export declare class AuthorizedKeysBlockError extends Error {
+    constructor(message: string);
+}
+/** @description The lines between the markers (none when there is no block). */
+export declare function extractManagedBlock(text: string): string[];
+/**
+ * @description `text` with the managed block holding exactly `blockLines`: an existing block is replaced in place, a new one is
+ * appended, and no lines remove the block (the file is returned as it was when there is none). Nothing outside the block changes.
+ */
+export declare function replaceManagedBlock(text: string, blockLines: readonly string[]): string;
+/** @description `YYYYMMDDHHMMSSZ` (UTC), the form of sshd's `expiry-time` option. */
+export declare function formatExpiryTime(epochMs: number): string;
+export interface TempKeyLineParams {
+    publicKey: string;
+    expiresAtMs: number;
+    gatePath: string;
+    keysPath: string;
+    dir: string;
+    pairId: string;
+}
+/** @description The line of a pairing's temporary key: it may log in until `expiresAtMs` and only to be handed to the gate's `redeem` mode. */
+export declare function buildTempKeyLine(params: TempKeyLineParams): string;
+export interface RunnerKeyLineParams {
+    publicKey: string;
+    gatePath: string;
+    keysPath: string;
+    dir: string;
+    runnerId: string;
+}
+/** @description The line of a paired runner's key: no expiry, the gate's `runner` mode. */
+export declare function buildRunnerKeyLine(params: RunnerKeyLineParams): string;
+/** @description Throws {@link AuthorizedKeysBlockError} when the file holds a damaged block — asked BEFORE a change is committed, so a block that cannot be edited never leaves a half-done change behind. */
+export declare function assertManagedBlockIntact(authorizedKeysPath: string): void;
+/**
+ * @description Make the managed block of `authorizedKeysPath` hold exactly `blockLines`. The folder is created 0700 when missing
+ * (sshd's StrictModes refuses a writable one), the file is written 0600 through a temp file and a rename — into the file a symlink
+ * points to, never over the link (a dotfile manager keeps the real file elsewhere). Nothing is written when nothing changes.
+ */
+export declare function writeManagedBlock(authorizedKeysPath: string, blockLines: readonly string[]): void;
+//# sourceMappingURL=authorizedKeys.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"authorizedKeys.d.ts","sourceRoot":"","sources":["../../src/runners/authorizedKeys.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AAEH,eAAO,MAAM,wBAAwB,uEAAuE,CAAC;AAC7G,eAAO,MAAM,sBAAsB,iDAAiD,CAAC;AAOrF,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAiBD,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAI1D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAUvF;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGxD;AAUD,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,+IAA+I;AAC/I,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAElE;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAEtE;AAWD,8MAA8M;AAC9M,wBAAgB,wBAAwB,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,kBAAkB,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAOjG"}

package/dist/runners/authorizedKeys.js

@@ -0,0 +1,153 @@
+"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.AuthorizedKeysBlockError = exports.authorizedKeysBlockEnd = exports.authorizedKeysBlockStart = void 0;
+exports.extractManagedBlock = extractManagedBlock;
+exports.replaceManagedBlock = replaceManagedBlock;
+exports.formatExpiryTime = formatExpiryTime;
+exports.buildTempKeyLine = buildTempKeyLine;
+exports.buildRunnerKeyLine = buildRunnerKeyLine;
+exports.assertManagedBlockIntact = assertManagedBlockIntact;
+exports.writeManagedBlock = writeManagedBlock;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const configDirFile_1 = require("../configDirFile");
+const ssh_1 = require("../remoteRun/ssh");
+/**
+ * @description The part of the account's `authorized_keys` that charness owns: ONE marked block, replaced as a whole and derived from
+ * the registry (`hubRegistry.ts` renders it), so the file and the registry never drift apart. Every line outside the markers is the
+ * operator's and is kept byte for byte. A file with a damaged block (a marker without its twin, two blocks) is NOT edited — guessing
+ * which lines are ours could delete a key of the operator.
+ *
+ * A runner's key is a forced-command key with NO forwarding of any kind: `restrict` turns off port, unix-socket, agent and X11
+ * forwarding, ptys and `~/.ssh/rc`; OpenSSH cannot limit forwarding of unix sockets in any finer way, and a key that could forward
+ * one could open the bot's tmux sockets.
+ */
+exports.authorizedKeysBlockStart = '# charness runners: managed block, do not edit between the markers';
+exports.authorizedKeysBlockEnd = '# charness runners: end of the managed block';
+const sshDirectoryMode = 0o700;
+const authorizedKeysMode = 0o600;
+/** What may not appear in the folder path inside `command="…"`: sshd cannot escape a backslash, and a quote ends the option. */
+const unsafeCommandCharacters = /["'\\\n\r]/;
+const msPerSecond = 1000;
+class AuthorizedKeysBlockError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuthorizedKeysBlockError';
+    }
+}
+exports.AuthorizedKeysBlockError = AuthorizedKeysBlockError;
+function findBlock(lines) {
+    const starts = lines.flatMap((line, index) => (line.trimEnd() === exports.authorizedKeysBlockStart ? [index] : []));
+    const ends = lines.flatMap((line, index) => (line.trimEnd() === exports.authorizedKeysBlockEnd ? [index] : []));
+    if (starts.length === 0 && ends.length === 0)
+        return null;
+    if (starts.length !== 1 || ends.length !== 1 || ends[0] < starts[0]) {
+        throw new AuthorizedKeysBlockError('authorized_keys holds a damaged charness block (the two marker lines do not pair up); fix it by hand — nothing was changed');
+    }
+    return { startIndex: starts[0], endIndex: ends[0] };
+}
+/** @description The lines between the markers (none when there is no block). */
+function extractManagedBlock(text) {
+    const lines = text.split('\n');
+    const block = findBlock(lines);
+    return block === null ? [] : lines.slice(block.startIndex + 1, block.endIndex);
+}
+/**
+ * @description `text` with the managed block holding exactly `blockLines`: an existing block is replaced in place, a new one is
+ * appended, and no lines remove the block (the file is returned as it was when there is none). Nothing outside the block changes.
+ */
+function replaceManagedBlock(text, blockLines) {
+    const lines = text.split('\n');
+    const block = findBlock(lines);
+    if (block === null) {
+        if (blockLines.length === 0)
+            return text;
+        const prefix = text === '' || text.endsWith('\n') ? text : `${text}\n`;
+        return `${prefix}${[exports.authorizedKeysBlockStart, ...blockLines, exports.authorizedKeysBlockEnd].join('\n')}\n`;
+    }
+    const replacement = blockLines.length === 0 ? [] : [exports.authorizedKeysBlockStart, ...blockLines, exports.authorizedKeysBlockEnd];
+    return [...lines.slice(0, block.startIndex), ...replacement, ...lines.slice(block.endIndex + 1)].join('\n');
+}
+/** @description `YYYYMMDDHHMMSSZ` (UTC), the form of sshd's `expiry-time` option. */
+function formatExpiryTime(epochMs) {
+    const iso = new Date(Math.floor(epochMs / msPerSecond) * msPerSecond).toISOString();
+    return `${iso.slice(0, 4)}${iso.slice(5, 7)}${iso.slice(8, 10)}${iso.slice(11, 13)}${iso.slice(14, 16)}${iso.slice(17, 19)}Z`;
+}
+function buildGateCommand(gatePath, keysPath, dir, kind, id) {
+    for (const value of [gatePath, keysPath, dir]) {
+        if (unsafeCommandCharacters.test(value))
+            throw new AuthorizedKeysBlockError('the charness folder path holds a quote, a backslash or a line break, which an authorized_keys command cannot carry');
+    }
+    const command = [(0, ssh_1.quoteShellWord)(gatePath), '--dir', (0, ssh_1.quoteShellWord)(dir), '--keys', (0, ssh_1.quoteShellWord)(keysPath), kind, id].join(' ');
+    return `command="${command}"`;
+}
+/** @description The line of a pairing's temporary key: it may log in until `expiresAtMs` and only to be handed to the gate's `redeem` mode. */
+function buildTempKeyLine(params) {
+    return `restrict,expiry-time="${formatExpiryTime(params.expiresAtMs)}",${buildGateCommand(params.gatePath, params.keysPath, params.dir, 'redeem', params.pairId)} ${params.publicKey} charness-pairing:${params.pairId}`;
+}
+/** @description The line of a paired runner's key: no expiry, the gate's `runner` mode. */
+function buildRunnerKeyLine(params) {
+    return `restrict,${buildGateCommand(params.gatePath, params.keysPath, params.dir, 'runner', params.runnerId)} ${params.publicKey} charness-runner:${params.runnerId}`;
+}
+function readTextIfPresent(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return '';
+        throw error;
+    }
+}
+/** @description Throws {@link AuthorizedKeysBlockError} when the file holds a damaged block — asked BEFORE a change is committed, so a block that cannot be edited never leaves a half-done change behind. */
+function assertManagedBlockIntact(authorizedKeysPath) {
+    extractManagedBlock(readTextIfPresent(authorizedKeysPath));
+}
+/**
+ * @description Make the managed block of `authorizedKeysPath` hold exactly `blockLines`. The folder is created 0700 when missing
+ * (sshd's StrictModes refuses a writable one), the file is written 0600 through a temp file and a rename — into the file a symlink
+ * points to, never over the link (a dotfile manager keeps the real file elsewhere). Nothing is written when nothing changes.
+ */
+function writeManagedBlock(authorizedKeysPath, blockLines) {
+    fs.mkdirSync(path.dirname(authorizedKeysPath), { recursive: true, mode: sshDirectoryMode });
+    const targetPath = fs.existsSync(authorizedKeysPath) ? fs.realpathSync(authorizedKeysPath) : authorizedKeysPath;
+    const current = readTextIfPresent(targetPath);
+    const next = replaceManagedBlock(current, blockLines);
+    if (next === current)
+        return;
+    (0, configDirFile_1.writeTextFileAtomically)(targetPath, next, authorizedKeysMode);
+}
+//# sourceMappingURL=authorizedKeys.js.map

package/dist/runners/authorizedKeys.js.map

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

package/dist/runners/bootstrapLine.d.ts

@@ -0,0 +1,4 @@
+import { type PairCodePayload } from './pairCode';
+/** @description The command to paste on the runner machine, for the pairing `payload`. */
+export declare function buildBootstrapLine(payload: PairCodePayload): string;
+//# sourceMappingURL=bootstrapLine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrapLine.d.ts","sourceRoot":"","sources":["../../src/runners/bootstrapLine.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA+BlE,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAkCnE"}

package/dist/runners/bootstrapLine.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildBootstrapLine = buildBootstrapLine;
+const gateProtocol_1 = require("./gateProtocol");
+const pairCode_1 = require("./pairCode");
+/**
+ * @description The one line the operator runs on the runner machine. It is plain `sh` (a runner has nothing of charness yet): it
+ * writes the pairing's temporary key and the hub's host key into a private temp folder (removed on exit), downloads the hub's own
+ * charness package through the gate's `bootstrap` request, unpacks it, and hands over to the runner utility's `pair` step with the
+ * pairing code and the id of the archive it downloaded (the hub announces it in the marker line; the first step checks the archive against it). What the hub's shell printed before the gate ran (a banner, a motd) is skipped: the answer opens with the marker line,
+ * which `grep -b` finds among the first {@link maxGateNoiseBytes} bytes, and the archive is cut out from the byte after it.
+ *
+ * Contract with the runner utility: `runnerCli.js pair --bootstrap <unpacked folder> --archive <file> --package-id <id> <code>` is started with a package that has NO
+ * `node_modules` yet, so it reaches its install step (`npm install --omit=dev --ignore-scripts` into its own app folder) using
+ * Node's built-ins only.
+ *
+ * Every value in the line passed a strict pattern (`pairCode.ts`) that has no quote, space, `$`, backtick or backslash; the line
+ * itself is wrapped in single quotes and so holds none.
+ */
+const minNodeMajor = 22;
+const minNodeMinor = 12;
+const hubHostAlias = 'charness-hub';
+const privateKeyFoldWidth = 70;
+const privateKeyHeader = '-----BEGIN OPENSSH PRIVATE KEY-----';
+const privateKeyFooter = '-----END OPENSSH PRIVATE KEY-----';
+const connectTimeoutSeconds = 20;
+/** The marker line of a `bootstrap` answer as an extended regular expression: the marker, the request, optional `key=value` fields. */
+const bootstrapMarkerPattern = `^${gateProtocol_1.gateMarker} bootstrap( [a-z]+=[A-Za-z0-9._:@/-]*)*$`;
+function getPrivateKeyBody(privateKey) {
+    return privateKey.replace(privateKeyHeader, '').replace(privateKeyFooter, '').replace(/\s+/g, '');
+}
+/** @description The command to paste on the runner machine, for the pairing `payload`. */
+function buildBootstrapLine(payload) {
+    const code = (0, pairCode_1.encodePairCode)(payload);
+    const sshOptions = [
+        '-T', '-F /dev/null', '-i "$d/key"',
+        '-o BatchMode=yes', '-o IdentitiesOnly=yes', '-o IdentityAgent=none',
+        '-o StrictHostKeyChecking=yes', '-o UserKnownHostsFile="$d/kh"', '-o GlobalKnownHostsFile=/dev/null',
+        `-o HostKeyAlias=${hubHostAlias}`, `-o ConnectTimeout=${connectTimeoutSeconds}`,
+        '-p "$p"',
+    ].join(' ');
+    const script = [
+        'set -eu',
+        'umask 077',
+        'd=$(mktemp -d "${TMPDIR:-/tmp}/charness-runner.XXXXXXXX")',
+        'trap "rm -rf \\"$d\\"" EXIT',
+        'trap "exit 1" INT TERM',
+        `u="${payload.user}"`,
+        `h="${payload.host}"`,
+        `p="${payload.port}"`,
+        `k="${payload.hostKey}"`,
+        `b="${getPrivateKeyBody(payload.privateKey)}"`,
+        `command -v node >/dev/null 2>&1 && node -e "var v=process.versions.node.split(/[.]/);process.exit(v[0]>${minNodeMajor}||v[0]==${minNodeMajor}&&v[1]>=${minNodeMinor}?0:1)" || { echo "charness-runner: Node.js ${minNodeMajor}.${minNodeMinor} or newer is needed on this machine (https://nodejs.org)" >&2; exit 1; }`,
+        `{ printf "%s\\n" "${privateKeyHeader}"; printf "%s" "$b" | fold -w ${privateKeyFoldWidth}; printf "\\n%s\\n" "${privateKeyFooter}"; } > "$d/key"`,
+        `printf "%s %s\\n" ${hubHostAlias} "$k" > "$d/kh"`,
+        `ssh ${sshOptions} "$u@$h" bootstrap > "$d/answer"`,
+        `hit=$(head -c ${gateProtocol_1.maxGateNoiseBytes} "$d/answer" | LC_ALL=C grep -a -b -o -E -e "${bootstrapMarkerPattern}" | head -n 1)`,
+        '[ -n "$hit" ] || { echo "charness-runner: the hub did not send the package (has the line expired or been used already?)" >&2; exit 1; }',
+        'o=${hit%%:*}; t=${hit#*:}',
+        'tail -c +$((o + ${#t} + 2)) "$d/answer" > "$d/package.tgz"',
+        'mkdir "$d/pkg"',
+        'tar -xzf "$d/package.tgz" -C "$d/pkg"',
+        `node "$d/pkg/dist/runnerUtility/runnerCli.js" pair --bootstrap "$d/pkg" --archive "$d/package.tgz" --package-id "\${t##*id=}" ${code}`,
+    ].join('; ');
+    if (script.includes("'"))
+        throw new Error('the bootstrap script must not hold a single quote');
+    return `sh -c '${script}'`;
+}
+//# sourceMappingURL=bootstrapLine.js.map

package/dist/runners/bootstrapLine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrapLine.js","sourceRoot":"","sources":["../../src/runners/bootstrapLine.ts"],"names":[],"mappings":";;AAiCA,gDAkCC;AAnED,iDAA+D;AAC/D,yCAAkE;AAElE;;;;;;;;;;;;;GAaG;AAEH,MAAM,YAAY,GAAG,EAAE,CAAC;AACxB,MAAM,YAAY,GAAG,EAAE,CAAC;AACxB,MAAM,YAAY,GAAG,cAAc,CAAC;AACpC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAC/B,MAAM,gBAAgB,GAAG,qCAAqC,CAAC;AAC/D,MAAM,gBAAgB,GAAG,mCAAmC,CAAC;AAC7D,MAAM,qBAAqB,GAAG,EAAE,CAAC;AACjC,uIAAuI;AACvI,MAAM,sBAAsB,GAAG,IAAI,yBAAU,0CAA0C,CAAC;AAExF,SAAS,iBAAiB,CAAC,UAAkB;IAC3C,OAAO,UAAU,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACpG,CAAC;AAED,0FAA0F;AAC1F,SAAgB,kBAAkB,CAAC,OAAwB;IACzD,MAAM,IAAI,GAAG,IAAA,yBAAc,EAAC,OAAO,CAAC,CAAC;IACrC,MAAM,UAAU,GAAG;QACjB,IAAI,EAAE,cAAc,EAAE,aAAa;QACnC,kBAAkB,EAAE,uBAAuB,EAAE,uBAAuB;QACpE,8BAA8B,EAAE,+BAA+B,EAAE,mCAAmC;QACpG,mBAAmB,YAAY,EAAE,EAAE,qBAAqB,qBAAqB,EAAE;QAC/E,SAAS;KACV,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACZ,MAAM,MAAM,GAAG;QACb,SAAS;QACT,WAAW;QACX,2DAA2D;QAC3D,6BAA6B;QAC7B,wBAAwB;QACxB,MAAM,OAAO,CAAC,IAAI,GAAG;QACrB,MAAM,OAAO,CAAC,IAAI,GAAG;QACrB,MAAM,OAAO,CAAC,IAAI,GAAG;QACrB,MAAM,OAAO,CAAC,OAAO,GAAG;QACxB,MAAM,iBAAiB,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG;QAC9C,0GAA0G,YAAY,WAAW,YAAY,WAAW,YAAY,8CAA8C,YAAY,IAAI,YAAY,0EAA0E;QACxT,qBAAqB,gBAAgB,iCAAiC,mBAAmB,wBAAwB,gBAAgB,iBAAiB;QAClJ,qBAAqB,YAAY,iBAAiB;QAClD,OAAO,UAAU,kCAAkC;QACnD,iBAAiB,gCAAiB,gDAAgD,sBAAsB,gBAAgB;QACxH,yIAAyI;QACzI,2BAA2B;QAC3B,4DAA4D;QAC5D,gBAAgB;QAChB,uCAAuC;QACvC,iIAAiI,IAAI,EAAE;KACxI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IAC/F,OAAO,UAAU,MAAM,GAAG,CAAC;AAC7B,CAAC"}

package/dist/runners/gate.d.ts

@@ -0,0 +1,41 @@
+import type { Readable, Writable } from 'stream';
+import { type GateLinkTimings } from './gateLink';
+import { type GateRequest } from './gateProtocol';
+import { type HubContext } from './hubPaths';
+export type GateInvocation = {
+    role: 'temporary';
+    dir: string;
+    keysPath: string;
+    pairId: string;
+} | {
+    role: 'runner';
+    dir: string;
+    keysPath: string;
+    runnerId: string;
+};
+export type GateArgsParsing = {
+    ok: true;
+    invocation: GateInvocation;
+} | {
+    ok: false;
+    error: string;
+};
+/** @description The arguments of the forced command: `--dir <abs> --keys <abs> redeem|runner <id>`, nothing else. */
+export declare function parseGateArgs(argv: readonly string[]): GateArgsParsing;
+/** @description The request the runner may make with a key of `role`: `originalCommand` as a whole must be one of the role's words. */
+export declare function routeGateRequest(role: GateInvocation['role'], originalCommand: string | undefined): GateRequest | null;
+export interface GateIo {
+    stdin: Readable;
+    stdout: Writable;
+    /** One line to the runner's side of stderr. */
+    log: (line: string) => void;
+}
+export interface GateOptions {
+    /** Override pieces of the context (tests); `dir` and `keysPath` always come from the arguments. */
+    context?: Partial<HubContext>;
+    now?: () => number;
+    linkTimings?: Partial<GateLinkTimings>;
+}
+/** @description Serve one request of one runner; resolves with the exit code of the gate process. */
+export declare function runRunnerGate(argv: readonly string[], env: NodeJS.ProcessEnv, io: GateIo, options?: GateOptions): Promise<number>;
+//# sourceMappingURL=gate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/runners/gate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAGjD,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAOL,KAAK,WAAW,EAGjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAmB/D,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,cAAc,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtG,qHAAqH;AACrH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,eAAe,CAUtE;AAED,uIAAuI;AACvI,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,EAAE,eAAe,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,GAAG,IAAI,CAGtH;AAED,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,EAAE,QAAQ,CAAC;IACjB,+CAA+C;IAC/C,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,mGAAmG;IACnG,OAAO,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;CACxC;AAoFD,qGAAqG;AACrG,wBAAsB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmD3I"}

package/dist/runners/gate.js

@@ -0,0 +1,216 @@
+"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.parseGateArgs = parseGateArgs;
+exports.routeGateRequest = routeGateRequest;
+exports.runRunnerGate = runRunnerGate;
+const path = __importStar(require("path"));
+const promises_1 = require("stream/promises");
+const authorizedKeys_1 = require("./authorizedKeys");
+const configDirFile_1 = require("../configDirFile");
+const gateLink_1 = require("./gateLink");
+const gateProtocol_1 = require("./gateProtocol");
+const hubIds_1 = require("./hubIds");
+const hubPaths_1 = require("./hubPaths");
+const hubRegistry_1 = require("./hubRegistry");
+const hubPackage_1 = require("./hubPackage");
+const hubPairing_1 = require("./hubPairing");
+const linkControl_1 = require("./linkControl");
+/**
+ * @description `charness runner-gate` — what sshd starts for a runner's key (the forced command of its `authorized_keys` line, via
+ * the `gate` wrapper). It is NOT a child of the bot: it survives bot restarts, and a hot reload never cuts a runner's link.
+ *
+ * The line names the registry folder, the `authorized_keys` file and the role of the key — `--dir D --keys K redeem <pairId>` for a
+ * pairing's temporary key, `--dir D --keys K runner <runnerId>` for a paired runner's. What the runner asks for arrives in
+ * `SSH_ORIGINAL_COMMAND` and is matched, as a whole, against the few words its role allows; anything else — another word, arguments,
+ * no command at all (a shell login) — is refused. See `gateProtocol.ts` for what each request says.
+ */
+const refusedExitCode = 2;
+const failedExitCode = 1;
+/** @description The arguments of the forced command: `--dir <abs> --keys <abs> redeem|runner <id>`, nothing else. */
+function parseGateArgs(argv) {
+    const [dirFlag, dir, keysFlag, keysPath, mode, id, ...rest] = argv;
+    if (dirFlag !== '--dir' || keysFlag !== '--keys' || dir === undefined || keysPath === undefined || id === undefined || rest.length > 0) {
+        return { ok: false, error: 'usage: runner-gate --dir <folder> --keys <authorized_keys> redeem|runner <id>' };
+    }
+    if (!path.isAbsolute(dir) || !path.isAbsolute(keysPath))
+        return { ok: false, error: 'the folder and the keys file must be absolute paths' };
+    if (!hubIds_1.hubIdPattern.test(id))
+        return { ok: false, error: 'the id is not a valid id' };
+    if (mode === 'redeem')
+        return { ok: true, invocation: { role: 'temporary', dir, keysPath, pairId: id } };
+    if (mode === 'runner')
+        return { ok: true, invocation: { role: 'runner', dir, keysPath, runnerId: id } };
+    return { ok: false, error: 'the mode must be redeem or runner' };
+}
+/** @description The request the runner may make with a key of `role`: `originalCommand` as a whole must be one of the role's words. */
+function routeGateRequest(role, originalCommand) {
+    const allowed = role === 'temporary' ? gateProtocol_1.temporaryKeyRequests : gateProtocol_1.runnerKeyRequests;
+    return allowed.find((request) => request === originalCommand) ?? null;
+}
+async function readLimitedText(stream, maxBytes) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of stream) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buffer.length;
+        if (total > maxBytes)
+            return null;
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+/** Send the package: its marker (`request` says which answer it is), then the archive, read from a file opened BEFORE the marker is sent. */
+async function writePackage(ctx, io, request) {
+    const opened = await (0, hubPackage_1.openHubPackage)(ctx);
+    io.stdout.write((0, gateProtocol_1.formatGateAnswerHead)(request, { id: opened.id }));
+    await (0, promises_1.pipeline)(opened.handle.createReadStream(), io.stdout, { end: false });
+    return 0;
+}
+async function handleRedeem(ctx, pairId, io, now) {
+    const body = await readLimitedText(io.stdin, gateProtocol_1.maxGateRequestBytes);
+    let reply;
+    const parsed = body === null ? null : safeParseJson(body);
+    if (parsed === null) {
+        reply = { ok: false, reason: 'the request is not valid JSON or is too large' };
+    }
+    else {
+        const request = gateProtocol_1.redeemRequestSchema.safeParse(parsed);
+        reply = request.success
+            ? await (0, hubPairing_1.redeemPairing)(ctx, pairId, request.data, now(), getPackageIdOrNull(ctx, io.log))
+            : { ok: false, reason: `the request is invalid: ${request.error.issues.map((issue) => `${issue.path.join('.') || '(root)'} ${issue.message}`).join('; ')}` };
+    }
+    io.stdout.write((0, gateProtocol_1.formatGateAnswerHead)('redeem'));
+    io.stdout.write(`${JSON.stringify(reply)}\n`);
+    return reply.ok ? 0 : failedExitCode;
+}
+function safeParseJson(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return parsed !== null && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function handleUnpair(ctx, runnerId, io, now) {
+    const removed = await (0, hubPairing_1.removePairedRunner)(ctx, runnerId, now());
+    if (removed !== null)
+        (0, linkControl_1.cutRunnerLink)(ctx.dir, runnerId);
+    const reply = { ok: removed !== null };
+    io.stdout.write((0, gateProtocol_1.formatGateAnswerHead)('unpair'));
+    io.stdout.write(`${JSON.stringify(reply)}\n`);
+    return 0;
+}
+/** What the runner is told about a failure on the hub: our own registry messages, else only an error code — never a hub path. */
+function describeFailure(error) {
+    if (error instanceof hubRegistry_1.HubRegistryError || error instanceof authorizedKeys_1.AuthorizedKeysBlockError)
+        return error.message;
+    return `internal error (${(0, configDirFile_1.getCaughtErrnoCode)(error)})`;
+}
+async function handleIdentity(ctx, runnerId, io) {
+    const reply = (0, hubPairing_1.describeRunnerIdentity)(ctx, runnerId, getPackageIdOrNull(ctx, io.log));
+    io.stdout.write((0, gateProtocol_1.formatGateAnswerHead)('identity'));
+    io.stdout.write(`${JSON.stringify(reply)}\n`);
+    return reply.ok ? 0 : failedExitCode;
+}
+async function handleVersion(ctx, io) {
+    io.stdout.write((0, gateProtocol_1.formatGateAnswerHead)('version', { package: getPackageIdOrNull(ctx, io.log) ?? gateProtocol_1.noPackageMarker }));
+    return 0;
+}
+function getPackageIdOrNull(ctx, log) {
+    try {
+        return (0, hubPackage_1.getHubPackage)(ctx).id;
+    }
+    catch (error) {
+        log(`the package cannot be packed (${describeFailure(error)}); the link goes up without one`);
+        return null;
+    }
+}
+/** @description Serve one request of one runner; resolves with the exit code of the gate process. */
+async function runRunnerGate(argv, env, io, options = {}) {
+    const parsed = parseGateArgs(argv);
+    if (!parsed.ok) {
+        io.log(parsed.error);
+        return refusedExitCode;
+    }
+    const { invocation } = parsed;
+    const request = routeGateRequest(invocation.role, env.SSH_ORIGINAL_COMMAND);
+    if (request === null) {
+        io.log('refused: this key may only be used by charness-runner');
+        return refusedExitCode;
+    }
+    const ctx = (0, hubPaths_1.createHubContext)({ ...options.context, dir: invocation.dir, authorizedKeysPath: invocation.keysPath });
+    const now = options.now ?? Date.now;
+    try {
+        if (invocation.role === 'temporary') {
+            if (request === 'bootstrap') {
+                if (!(0, hubPairing_1.checkIsPairingOpen)(ctx, invocation.pairId, now())) {
+                    io.log('refused: this pairing code is unknown, used or expired');
+                    return refusedExitCode;
+                }
+                return await writePackage(ctx, io, 'bootstrap');
+            }
+            return await handleRedeem(ctx, invocation.pairId, io, now);
+        }
+        // The key line is only the way in: a runner that left the registry is refused whatever its line (or an ssh connection it already
+        // has open, which keeps the key's options) still allows. Two requests are answered anyway, because their answer IS «not paired»:
+        // `unpair` (idempotent) and `identity` (a removed runner asks it after a refused `link` to tell a removal from a failure — it
+        // answers `{ok:false}` and discloses nothing).
+        if (request !== 'unpair' && request !== 'identity' && !(0, hubPairing_1.checkIsRunnerPaired)(ctx, invocation.runnerId)) {
+            io.log('refused: this runner is not paired here');
+            return refusedExitCode;
+        }
+        switch (request) {
+            case 'link':
+                return await (0, gateLink_1.runGateLink)({ ctx, runnerId: invocation.runnerId, input: io.stdin, output: io.stdout, packageId: getPackageIdOrNull(ctx, io.log), log: io.log, timings: options.linkTimings, now });
+            case 'package':
+                return await writePackage(ctx, io, 'package');
+            case 'version':
+                return await handleVersion(ctx, io);
+            case 'identity':
+                return await handleIdentity(ctx, invocation.runnerId, io);
+            case 'unpair':
+                return await handleUnpair(ctx, invocation.runnerId, io, now);
+            default:
+                return refusedExitCode;
+        }
+    }
+    catch (error) {
+        io.log(`failed: ${describeFailure(error)}`);
+        return failedExitCode;
+    }
+}
+//# sourceMappingURL=gate.js.map

package/dist/runners/gate.js.map

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

package/dist/runners/gateLink.d.ts

@@ -0,0 +1,26 @@
+import { Writable, type Readable } from 'stream';
+import { type HubContext } from './hubPaths';
+export interface GateLinkTimings {
+    /** How often the gate checks that it still holds the socket and that its runner is still paired. */
+    checkIntervalMs: number;
+    /** How often the ssh keepalive pings the runner. */
+    keepaliveIntervalMs: number;
+    /** How long the ssh handshake with the runner may take. */
+    readyTimeoutMs: number;
+}
+export declare const defaultGateLinkTimings: GateLinkTimings;
+export interface GateLinkParams {
+    ctx: HubContext;
+    runnerId: string;
+    /** The channel from the runner (the gate's stdin) and to it (stdout). */
+    input: Readable;
+    output: Writable;
+    /** The id of the hub's current package, told to the runner in the marker line (`null` when it cannot be packed). */
+    packageId: string | null;
+    log: (line: string) => void;
+    timings?: Partial<GateLinkTimings>;
+    now?: () => number;
+}
+/** @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). */
+export declare function runGateLink(params: GateLinkParams): Promise<number>;
+//# sourceMappingURL=gateLink.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gateLink.d.ts","sourceRoot":"","sources":["../../src/runners/gateLink.ts"],"names":[],"mappings":"AAIA,OAAO,EAAU,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAIzD,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAmCjE,MAAM,WAAW,eAAe;IAC9B,oGAAoG;IACpG,eAAe,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,sBAAsB,EAAE,eAA2G,CAAC;AAEjJ,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,UAAU,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,EAAE,QAAQ,CAAC;IACjB,oHAAoH;IACpH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IACnC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAcD,gJAAgJ;AAChJ,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAqJnE"}