charness 3.7.0 → 3.9.0

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,13 @@
+import { type PairCodePayload } from './pairCode';
+/** @description The account the admin line pairs unless the operator changes its last word. */
+export declare const defaultRunnerAccount = "runner";
+/** @description Is `name` a plain account name (letters, digits, `.`, `_`, `-`; no leading `-`)? The admin line refuses anything else. */
+export declare function checkIsAccountName(name: string): boolean;
+/** @description The command to paste on the runner machine, as the account that will run jobs, for the pairing `payload`. */
+export declare function buildBootstrapLine(payload: PairCodePayload): string;
+/**
+ * @description The command to paste in an ADMIN account's terminal on the runner machine: it checks `account`, pairs it, and installs its
+ * always-on service. `account` is the line's last word, so the operator can change it by hand.
+ */
+export declare function buildAdminBootstrapLine(payload: PairCodePayload, account?: string): 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":"AAGA,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAuDlE,+FAA+F;AAC/F,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAK7C,0IAA0I;AAC1I,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAkDD,6HAA6H;AAC7H,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAGnE;AA2BD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,GAAE,MAA6B,GAAG,MAAM,CAGhH"}

package/dist/runners/bootstrapLine.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultRunnerAccount = void 0;
+exports.checkIsAccountName = checkIsAccountName;
+exports.buildBootstrapLine = buildBootstrapLine;
+exports.buildAdminBootstrapLine = buildAdminBootstrapLine;
+const adminCheck_1 = require("../runnerUtility/adminCheck");
+const pairArgs_1 = require("../runnerUtility/pairArgs");
+const gateProtocol_1 = require("./gateProtocol");
+const pairCode_1 = require("./pairCode");
+/**
+ * @description The lines the operator runs on the runner machine. They are plain `sh` (a runner has nothing of charness yet): they
+ * write the pairing's temporary key and the hub's host key into a private temp folder (removed on exit), download the hub's own
+ * charness package through the gate's `bootstrap` request, unpack it, and hand over to the runner utility's `pair` step with the
+ * pairing code and the id of the archive they 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.
+ *
+ * The PLAIN line ({@link buildBootstrapLine}) is run as the runner account itself: all of it is that account's.
+ *
+ * The ADMIN line ({@link buildAdminBootstrapLine}), `sudo sh -c '<script>' sh <account>`, is run from an admin account and does everything
+ * for the account named by its last word. The runner account runs the agents' code, so ROOT never executes, reads through or writes into
+ * anything that account can change. As root the script (1) checks the account (it exists; not root; not an admin; the OS is known),
+ * (2) downloads the package into a folder of ITS OWN in `/tmp` — root-owned, readable by the account, extracted with `--no-same-owner`
+ * — (3) has the account pair itself from that copy (`sudo -u <account> -H node …/runnerCli.js pair`: its files are the account's, never
+ * root's), and (4) runs the root step from the same root-owned copy (`rootServiceCli.js install <account>`: Node built-ins only, because
+ * the copy has no dependencies — it installs the always-on service, and touches the account's side only through `sudo -u`, see
+ * `runnerUtility/adminService.ts`). The pairing code stays single use, 10 minutes, a secret; sudo logs the command line, so a code that
+ * is neither used nor closed stays live in that log until it runs out: a refused line (no such account, an admin account) leaves it open ON
+ * PURPOSE — the operator fixes the last word and pastes the same line again — and an already-paired account's line closes its own code (the
+ * gate's `cancel`). Nothing creates an account. Run again for an account that is already paired, the line pairs nothing twice and installs
+ * the service — that is its way to retry.
+ *
+ * What the admin line trusts: the charness host. The line is text the host made, and the program root runs from it is the one in the host's
+ * own install, so whoever can change that install (its user, and the agents that run as that user) controls code that runs as root on the
+ * runner machine — and what it installs outlasts the paste. The plain line trusts the host only with the runner account. Every place that
+ * offers the line says so: the Telegram message (`runners.pairingAdminIntro`) and the CLI's text (`adminLineTrustSentence` in `runnersCli.ts`).
+ */
+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._:@/-]*)*$`;
+const runnerCliInPackage = 'dist/runnerUtility/runnerCli.js';
+const rootServiceCliInPackage = 'dist/runnerUtility/rootServiceCli.js';
+/** Where the admin line's root-owned copy is made: a folder the account can read, which `$TMPDIR` (the admin's own, private) is not. */
+const adminCopyBase = '/tmp';
+function getPrivateKeyBody(privateKey) {
+    return privateKey.replace(privateKeyHeader, '').replace(privateKeyFooter, '').replace(/\s+/g, '');
+}
+/** @description The account the admin line pairs unless the operator changes its last word. */
+exports.defaultRunnerAccount = 'runner';
+/** The characters of an account name the admin line lets through (a character class body): none is special to a shell, and a name never starts with `-`. */
+const accountNameChars = 'A-Za-z0-9._-';
+const accountNamePattern = new RegExp(`^(?!-)[${accountNameChars}]+$`);
+/** @description Is `name` a plain account name (letters, digits, `.`, `_`, `-`; no leading `-`)? The admin line refuses anything else. */
+function checkIsAccountName(name) {
+    return accountNamePattern.test(name);
+}
+/**
+ * The steps that make the package ready in `$d/pkg` (and its archive in `$d/package.tgz`): `sh` that needs nothing of charness. `isForAccount`:
+ * the copy is made by ROOT for an account to read — its folder is world-readable (the key files in it stay 0600), the archive and the
+ * package are extracted readable, and without taking the owner from the archive, so root's copy stays root's.
+ */
+function renderFetchSteps(payload, isForAccount) {
+    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(' ');
+    return [
+        'umask 077',
+        `d=$(mktemp -d "${isForAccount ? adminCopyBase : '${TMPDIR:-/tmp}'}/charness-runner.XXXXXXXX")`,
+        ...(isForAccount ? ['chmod 755 "$d"'] : []),
+        '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: ${isForAccount ? `sudo finds no Node.js ${minNodeMajor}.${minNodeMinor} or newer on its PATH (install it system-wide)` : `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" || { echo "charness-runner: the hub refused or did not answer (has the line expired or been used already? the ssh message above says which)" >&2; exit 1; }`,
+        `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#*:}',
+        ...(isForAccount ? ['umask 022'] : []),
+        'tail -c +$((o + ${#t} + 2)) "$d/answer" > "$d/package.tgz"',
+        'mkdir "$d/pkg"',
+        `tar ${isForAccount ? '--no-same-owner ' : ''}-xzf "$d/package.tgz" -C "$d/pkg"`,
+    ];
+}
+/** The `pair` command on the unpacked package, for the pairing `code`. */
+function renderPairCommand(code, isServiceFollowing) {
+    return `"$d/pkg/${runnerCliInPackage}" pair --bootstrap "$d/pkg" --archive "$d/package.tgz" --package-id "\${t##*id=}"${isServiceFollowing ? ` ${pairArgs_1.serviceFollowsFlag}` : ''} ${code}`;
+}
+function checkScriptHasNoQuote(script, what) {
+    if (script.includes("'"))
+        throw new Error(`the ${what} script must not hold a single quote`);
+    return script;
+}
+/** @description The command to paste on the runner machine, as the account that will run jobs, for the pairing `payload`. */
+function buildBootstrapLine(payload) {
+    const script = [...renderFetchSteps(payload, false), `node ${renderPairCommand((0, pairCode_1.encodePairCode)(payload), false)}`];
+    return `sh -c '${checkScriptHasNoQuote(['set -eu', ...script].join('; '), 'bootstrap')}'`;
+}
+/**
+ * The admin script. `$1` is the account. Messages are plain ASCII with no apostrophe (the whole line sits in single quotes) and short: the
+ * line plus its text must fit one Telegram message.
+ */
+function renderAdminScript(payload) {
+    const checks = [
+        'f() { echo "charness-runner: $*" >&2; exit 1; }',
+        'a=$1',
+        '[ "$(id -u)" = 0 ] || f "run this line with sudo"',
+        `case $a in ""|-*|*[!${accountNameChars}]*) f "$a is not an account name";; esac`,
+        'i=$(id -u "$a" 2>/dev/null) || f "no account $a here: create a standard user or fix the last word"',
+        '[ "$i" != 0 ] || f "$a is root: use a standard user"',
+        `case $(uname -s) in Darwin) g="${adminCheck_1.macAdminGroup}";; Linux) g="${adminCheck_1.linuxAdminGroups.join(' ')}";; *) f "only macOS and Linux";; esac`,
+        'gs=$(id -Gn "$a") || f "no groups for $a"',
+        'for x in $gs; do case " $g " in *" $x "*) f "$a is an admin: the agents code runs with its rights";; esac; done',
+    ];
+    const steps = [
+        ...renderFetchSteps(payload, true),
+        'n=$(command -v node)',
+        `sudo -u "$a" -H "$n" ${renderPairCommand((0, pairCode_1.encodePairCode)(payload), true)}`,
+        `"$n" "$d/pkg/${rootServiceCliInPackage}" install "$a" || f "$a is paired, but has no service: fix the above and paste a fresh admin line"`,
+    ];
+    return checkScriptHasNoQuote(['set -eu', ...checks, ...steps].join('; '), 'admin');
+}
+/**
+ * @description The command to paste in an ADMIN account's terminal on the runner machine: it checks `account`, pairs it, and installs its
+ * always-on service. `account` is the line's last word, so the operator can change it by hand.
+ */
+function buildAdminBootstrapLine(payload, account = exports.defaultRunnerAccount) {
+    if (!checkIsAccountName(account))
+        throw new Error('the runner account must be a plain account name');
+    return `sudo sh -c '${renderAdminScript(payload)}' sh ${account}`;
+}
+//# 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":"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"}

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,EAQL,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;AA4FD,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,CAoD3I"}

package/dist/runners/gate.js

@@ -0,0 +1,225 @@
+"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;
+    }
+}
+/** `cancel`: the line that held this code is done without using it (an admin line pasted again for a machine that is already paired). Idempotent. */
+async function handleCancel(ctx, pairId, io, now) {
+    const reply = { ok: await (0, hubPairing_1.cancelPairing)(ctx, pairId, now()) };
+    io.stdout.write((0, gateProtocol_1.formatGateAnswerHead)('cancel'));
+    io.stdout.write(`${JSON.stringify(reply)}\n`);
+    return 0;
+}
+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');
+            }
+            if (request === 'cancel')
+                return await handleCancel(ctx, invocation.pairId, io, now);
+            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"}