charness 3.7.0 → 3.8.0

package/dist/runners/hubPackage.d.ts

@@ -0,0 +1,23 @@
+import * as fsp from 'fs/promises';
+import { type HubContext } from './hubPaths';
+/** An archive that is no longer the current one is kept this long: a gate that was handed its path a moment ago must still find it. */
+export declare const supersededArchiveGraceMs: number;
+/** @description The packed package: where the gzip file is, and its id. */
+export interface HubPackage {
+    id: string;
+    filePath: string;
+}
+/**
+ * @description The current package of this hub, packed now unless the cache already holds this exact source. Throws when the source
+ * (`dist/`, `package.json`, `remoteRun/runner.sh` under `ctx.packageRoot`) is missing. Safe without the registry lock: a cache file
+ * is written whole and named by its id, and two packers of one source write identical bytes.
+ */
+export declare function getHubPackage(ctx: HubContext): HubPackage;
+export interface OpenedHubPackage {
+    id: string;
+    /** The archive, open for reading; the caller closes it (a read stream made from it does). */
+    handle: fsp.FileHandle;
+}
+/** @description The current package, opened. Retries when a file vanishes between the lookup and the open (a sweep, a packer of a newer source). */
+export declare function openHubPackage(ctx: HubContext): Promise<OpenedHubPackage>;
+//# sourceMappingURL=hubPackage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hubPackage.d.ts","sourceRoot":"","sources":["../../src/runners/hubPackage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AAMnC,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAuB9D,uIAAuI;AACvI,eAAO,MAAM,wBAAwB,QAAiB,CAAC;AAavD,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;CAClB;AA6DD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,GAAG,UAAU,CAoBzD;AAgBD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,6FAA6F;IAC7F,MAAM,EAAE,GAAG,CAAC,UAAU,CAAC;CACxB;AAED,oJAAoJ;AACpJ,wBAAsB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAS/E"}

package/dist/runners/hubPackage.js

@@ -0,0 +1,184 @@
+"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.supersededArchiveGraceMs = void 0;
+exports.getHubPackage = getHubPackage;
+exports.openHubPackage = openHubPackage;
+const crypto_1 = require("crypto");
+const fs = __importStar(require("fs"));
+const fsp = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const zlib_1 = require("zlib");
+const zod_1 = require("zod");
+const configDirFile_1 = require("../configDirFile");
+const hubLock_1 = require("./hubLock");
+const hubPaths_1 = require("./hubPaths");
+const tarArchive_1 = require("./tarArchive");
+/**
+ * @description The charness package a runner installs: the hub's OWN `dist/`, `package.json` and `remoteRun/runner.sh`, packed into a
+ * gzip tar, so a runner and its hub never run different code and no npm release is needed. Its id is the sha256 of the tar before
+ * compression (stable — gzip's bytes depend on the zlib build), 16 hex digits. The packed file is cached in `package/`; whether the
+ * cache is current is decided by a stamp of the source files (path, size, mtime), so asking for the id costs a walk of `stat`s.
+ *
+ * Several gates and packers run at once, none of them coordinated, so nothing is deleted on a packer's word: an archive is published
+ * whole by a rename (named by its id, so two packers of one source write the same bytes), `current.json` is only a pointer that heals
+ * (a packer that is late writes an older pointer; the next call sees the stamp differ and packs again), an archive that is no longer
+ * current is removed only after {@link supersededArchiveGraceMs}, and a reader {@link openHubPackage OPENS} the archive at once — a file
+ * that is deleted afterwards stays readable through the open handle.
+ */
+const packageIdLength = 16;
+const gzipLevel = 9;
+const cacheFileMode = 0o600;
+const executableBits = 0o111;
+const executableMode = 0o755;
+const plainFileMode = 0o644;
+const currentFileName = 'current.json';
+/** An archive that is no longer the current one is kept this long: a gate that was handed its path a moment ago must still find it. */
+exports.supersededArchiveGraceMs = 10 * 60 * 1000;
+const archiveSuffix = '.tgz';
+const temporarySuffix = '.tmp';
+const maxOpenAttempts = 3;
+/** `dist/` entries a runner never needs: tests, type declarations and source maps. */
+const skippedFilePattern = /(?:\.d\.ts|\.d\.ts\.map|\.js\.map)$/;
+const skippedFolderName = '__tests__';
+const runnerScriptRelativePath = 'remoteRun/runner.sh';
+const packageJsonRelativePath = 'package.json';
+const distRelativePath = 'dist';
+const currentSchema = zod_1.z.strictObject({ stamp: zod_1.z.string(), id: zod_1.z.string(), fileName: zod_1.z.string() });
+function listDistFiles(distRoot, relativeFolder) {
+    const files = [];
+    const entries = fs.readdirSync(path.join(distRoot, relativeFolder), { withFileTypes: true }).sort((left, right) => (left.name < right.name ? -1 : 1));
+    for (const entry of entries) {
+        const relativePath = path.posix.join(relativeFolder, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name !== skippedFolderName)
+                files.push(...listDistFiles(distRoot, relativePath));
+        }
+        else if (entry.isFile() && !skippedFilePattern.test(entry.name)) {
+            files.push(statSourceFile(distRoot, relativePath));
+        }
+    }
+    return files;
+}
+function statSourceFile(root, relativePath) {
+    const absolutePath = path.join(root, relativePath);
+    const stat = fs.statSync(absolutePath);
+    return { relativePath, absolutePath, size: stat.size, mtimeMs: stat.mtimeMs, mode: stat.mode };
+}
+/** The files in archive order: `package.json`, the runner script, then everything under `dist/` sorted by path. */
+function listPackageFiles(packageRoot) {
+    const distFiles = listDistFiles(packageRoot, distRelativePath);
+    return [statSourceFile(packageRoot, packageJsonRelativePath), statSourceFile(packageRoot, runnerScriptRelativePath), ...distFiles];
+}
+function createSourceStamp(files) {
+    const hash = (0, crypto_1.createHash)('sha256');
+    for (const file of files)
+        hash.update(`${file.relativePath}:${file.size}:${file.mtimeMs}\n`);
+    return hash.digest('hex');
+}
+function readCurrent(packageDir) {
+    try {
+        const parsed = currentSchema.safeParse(JSON.parse(fs.readFileSync(path.join(packageDir, currentFileName), 'utf8')));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+function packFiles(files) {
+    const entries = files.map((file) => ({
+        path: file.relativePath,
+        content: fs.readFileSync(file.absolutePath),
+        mode: (file.mode & executableBits) === 0 ? plainFileMode : executableMode,
+    }));
+    const tar = (0, tarArchive_1.createTarArchive)(entries);
+    return { id: (0, crypto_1.createHash)('sha256').update(tar).digest('hex').slice(0, packageIdLength), gzip: (0, zlib_1.gzipSync)(tar, { level: gzipLevel }) };
+}
+/**
+ * @description The current package of this hub, packed now unless the cache already holds this exact source. Throws when the source
+ * (`dist/`, `package.json`, `remoteRun/runner.sh` under `ctx.packageRoot`) is missing. Safe without the registry lock: a cache file
+ * is written whole and named by its id, and two packers of one source write identical bytes.
+ */
+function getHubPackage(ctx) {
+    const packageDir = (0, hubPaths_1.getHubFilePaths)(ctx.dir).packageDir;
+    const files = listPackageFiles(ctx.packageRoot);
+    const stamp = createSourceStamp(files);
+    const current = readCurrent(packageDir);
+    if (current !== null && current.stamp === stamp && fs.existsSync(path.join(packageDir, current.fileName))) {
+        removeSupersededArchives(packageDir, current.fileName, Date.now());
+        return { id: current.id, filePath: path.join(packageDir, current.fileName) };
+    }
+    (0, hubLock_1.ensureHubDir)(ctx.dir);
+    const packed = packFiles(files);
+    const fileName = `${packed.id}${archiveSuffix}`;
+    const filePath = path.join(packageDir, fileName);
+    fs.mkdirSync(packageDir, { recursive: true, mode: 0o700 });
+    const temporaryPath = `${filePath}.${process.pid}.${Math.random().toString(36).slice(2)}${temporarySuffix}`;
+    fs.writeFileSync(temporaryPath, packed.gzip, { mode: cacheFileMode });
+    fs.renameSync(temporaryPath, filePath);
+    (0, configDirFile_1.writeJsonFileAtomically)(path.join(packageDir, currentFileName), { stamp, id: packed.id, fileName }, cacheFileMode);
+    removeSupersededArchives(packageDir, fileName, Date.now());
+    return { id: packed.id, filePath };
+}
+/** Remove archives (and temp files of a packer that died) that are not `currentFileName` and have not been touched for the grace period. */
+function removeSupersededArchives(packageDir, currentFileName, nowMs) {
+    for (const name of fs.readdirSync(packageDir)) {
+        const isArchive = name.endsWith(archiveSuffix) && name !== currentFileName;
+        if (!isArchive && !name.endsWith(temporarySuffix))
+            continue;
+        const filePath = path.join(packageDir, name);
+        try {
+            if (nowMs - fs.statSync(filePath).mtimeMs > exports.supersededArchiveGraceMs)
+                fs.rmSync(filePath, { force: true });
+        }
+        catch {
+            // Already gone: another gate swept it.
+        }
+    }
+}
+/** @description The current package, opened. Retries when a file vanishes between the lookup and the open (a sweep, a packer of a newer source). */
+async function openHubPackage(ctx) {
+    for (let attempt = 1;; attempt += 1) {
+        const hubPackage = getHubPackage(ctx);
+        try {
+            return { id: hubPackage.id, handle: await fsp.open(hubPackage.filePath, 'r') };
+        }
+        catch (error) {
+            if ((0, configDirFile_1.getCaughtErrnoCode)(error) !== 'ENOENT' || attempt >= maxOpenAttempts)
+                throw error;
+        }
+    }
+}
+//# sourceMappingURL=hubPackage.js.map

package/dist/runners/hubPackage.js.map

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

package/dist/runners/hubPairing.d.ts

@@ -0,0 +1,63 @@
+import type { RedeemReply, RedeemRequest } from './gateProtocol';
+import { type HubContext } from './hubPaths';
+import { type PairedRunner, type PendingPairing } from './hubRegistry';
+import { type PairCodePayload } from './pairCode';
+export interface CreatePairingParams {
+    /** The address the runner dials, and the hub's ssh host key found there. */
+    host: string;
+    port: number;
+    hostKey: string;
+    /** Whose charness it is, as the runner shows it. */
+    label: string;
+    /** What the offering instance wants to find again when the code is used or expires; the CLI sets none. */
+    messageRef?: string | null;
+    nowMs: number;
+    /** How long the code works (default: the production lifetime, 10 minutes). */
+    lifetimeMs?: number;
+    /** The account the runner logs in as (default: the account this process runs as). */
+    sshUser?: string;
+}
+export interface CreatedPairing {
+    pairId: string;
+    expiresAtMs: number;
+    /** The secret to hand to the runner machine. */
+    code: string;
+    payload: PairCodePayload;
+}
+/** @description Make a pairing code: a temporary key good for 10 minutes, its line in `authorized_keys`, its entry in `pending.json`. */
+export declare function createPairing(ctx: HubContext, params: CreatePairingParams): Promise<CreatedPairing>;
+/** @description Is the pairing code `pairId` still open (made, not used, not expired)? The gate asks before it sends the package. */
+export declare function checkIsPairingOpen(ctx: HubContext, pairId: string, nowMs: number): boolean;
+/**
+ * @description Forget the pairing codes that have expired (their lines are gone from `authorized_keys` too) and return them, so the
+ * offering instance can edit its messages. A code that was used but whose entry outlived a crash is dropped without being returned.
+ * Run at boot, on a timer and by the CLI; sshd already refuses an expired key by itself.
+ */
+export declare function sweepExpiredPairings(ctx: HubContext, nowMs: number): Promise<PendingPairing[]>;
+/** @description What a runner may call itself: lowercase letters and digits with single dashes, short, never empty. */
+export declare function sanitizeRunnerName(suggestedName: string): string;
+/** @description `name`, or `name-2`, `name-3`, … — the first that no paired or hand-made runner has. */
+export declare function pickFreeRunnerName(suggestedName: string, takenNames: ReadonlySet<string>): string;
+/**
+ * @description What `redeem` answered (or would answer) for the paired runner `runnerId` — for the runner that lost the answer.
+ * `ok: false` ONLY when the runner is not in the registry: that answer makes the runner stop its jobs, so a fault of the hub (a hub key
+ * that cannot be read, a file mode that changed) must not look like it — it throws, the gate fails without an answer, and the runner
+ * just tries again.
+ */
+export declare function describeRunnerIdentity(ctx: HubContext, runnerId: string, packageId: string | null): RedeemReply;
+/**
+ * @description Use the pairing code `pairId`: the runner's keys become a paired runner and the code is spent. A code that is unknown,
+ * used (by another key) or expired, and a key that is already registered, are refused with the reason (no values) and change nothing.
+ * The SAME machine asking again for a code it has already used — its answer was lost, or the hub failed after the registry was written —
+ * is answered again, and the derived files are repaired on the way. `packageId` is the hub's current package, told to the runner.
+ */
+export declare function redeemPairing(ctx: HubContext, pairId: string, request: RedeemRequest, nowMs: number, packageId?: string | null): Promise<RedeemReply>;
+/** @description Find a paired runner by its name or id. */
+export declare function findPairedRunner(runners: readonly PairedRunner[], nameOrId: string): PairedRunner | undefined;
+/** @description Is the runner `runnerId` in the registry? Every request of a runner's key asks, so a removed runner is refused at once even when its key line is still there. */
+export declare function checkIsRunnerPaired(ctx: HubContext, runnerId: string): boolean;
+/** @description Take a runner out: its entry leaves the registry, its line `authorized_keys`. `null` when there is no such runner. The link is cut by the caller (`linkControl.ts`). A retry after a failed step finds nothing to remove and repairs the files. */
+export declare function removePairedRunner(ctx: HubContext, nameOrId: string, nowMs: number): Promise<PairedRunner | null>;
+/** @description Pause or resume a runner from the hub: it stays attached but is never picked for a job while paused. `null` when there is no such runner. */
+export declare function setPairedRunnerPaused(ctx: HubContext, nameOrId: string, isPaused: boolean): Promise<PairedRunner | null>;
+//# sourceMappingURL=hubPairing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hubPairing.d.ts","sourceRoot":"","sources":["../../src/runners/hubPairing.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAA0B,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAGrE,OAAO,EAQL,KAAK,YAAY,EAEjB,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAqBlE,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,0GAA0G;IAC1G,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,eAAe,CAAC;CAC1B;AA0CD,yIAAyI;AACzI,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CA0BnG;AAED,qIAAqI;AACrI,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAG1F;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAK9F;AAED,uHAAuH;AACvH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAQhE;AAED,wGAAwG;AACxG,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,MAAM,CAOjG;AAWD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,WAAW,CAM/G;AAID;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,MAAM,GAAG,IAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAkC3J;AAED,2DAA2D;AAC3D,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAE7G;AAED,iLAAiL;AACjL,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE9E;AAED,mQAAmQ;AACnQ,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAMjH;AAED,6JAA6J;AAC7J,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAQxH"}

package/dist/runners/hubPairing.js

@@ -0,0 +1,261 @@
+"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.createPairing = createPairing;
+exports.checkIsPairingOpen = checkIsPairingOpen;
+exports.sweepExpiredPairings = sweepExpiredPairings;
+exports.sanitizeRunnerName = sanitizeRunnerName;
+exports.pickFreeRunnerName = pickFreeRunnerName;
+exports.describeRunnerIdentity = describeRunnerIdentity;
+exports.redeemPairing = redeemPairing;
+exports.findPairedRunner = findPairedRunner;
+exports.checkIsRunnerPaired = checkIsRunnerPaired;
+exports.removePairedRunner = removePairedRunner;
+exports.setPairedRunnerPaused = setPairedRunnerPaused;
+const os = __importStar(require("os"));
+const runnersConfig_1 = require("../remoteRun/runnersConfig");
+const authorizedKeys_1 = require("./authorizedKeys");
+const hubPaths_1 = require("./hubPaths");
+const hubLock_1 = require("./hubLock");
+const hubKey_1 = require("./hubKey");
+const hubRegistry_1 = require("./hubRegistry");
+const pairCode_1 = require("./pairCode");
+const pairingTiming_1 = require("./pairingTiming");
+const sshKeys_1 = require("./sshKeys");
+/**
+ * @description The registry's operations — each one a transaction under the registry lock (`runTransaction`):
+ *
+ *   1. the `authorized_keys` block is checked first — a damaged one stops the operation before anything is written;
+ *   2. the AUTHORITATIVE files change: `paired.json`, then `pending.json`;
+ *   3. everything derived from them (`known_hosts`, the block) is rewritten from the registry — and this last step runs at the end of
+ *      EVERY operation, whether it changed anything or not, so a step that failed (or a crash between two writes) is mended by the
+ *      next operation, a plain `ls` included.
+ *
+ * Nothing in the middle can lose or double-spend a pairing: `redeem` records the runner with the id of the code that made it, so a
+ * code is single use even when the pending entry outlives a crash (the entry is dropped by the next transaction, before anything else), and
+ * a retry from the same machine is answered the same way (idempotent). A runner that is removed from `paired.json` is refused by every gate request at once, whatever its key line still says.
+ */
+const maxRunnerNameLength = 24;
+const fallbackRunnerName = 'runner';
+function runTransaction(ctx, nowMs, work) {
+    return (0, hubLock_1.withHubLock)(ctx.dir, () => {
+        (0, authorizedKeys_1.assertManagedBlockIntact)(ctx.authorizedKeysPath);
+        const paired = (0, hubRegistry_1.readPairedFile)(ctx.dir);
+        // A pending entry whose code was already used (a crash between the two writes of a redemption) is dropped BEFORE anything else is
+        // done, and persisted: the paired runner is the only proof that the code is spent, and a later removal of that runner must not leave
+        // the entry — and with it the code's temporary key — behind to be redeemed again.
+        const pending = (0, hubRegistry_1.readPendingFile)(ctx.dir);
+        const openPending = { pending: pending.pending.filter((pairing) => !checkIsPairingUsed(paired, pairing.pairId)) };
+        if (openPending.pending.length !== pending.pending.length)
+            (0, hubRegistry_1.writePendingFile)(ctx.dir, openPending);
+        const state = { paired, pending: openPending };
+        const outcome = work(state);
+        if (outcome.paired !== undefined)
+            (0, hubRegistry_1.writePairedFile)(ctx.dir, outcome.paired);
+        if (outcome.pending !== undefined)
+            (0, hubRegistry_1.writePendingFile)(ctx.dir, outcome.pending);
+        (0, hubRegistry_1.syncDerivedHubFiles)(ctx, outcome.pending ?? state.pending, outcome.paired ?? state.paired, nowMs);
+        return outcome.result;
+    });
+}
+function removeExpired(pending, nowMs) {
+    const expired = pending.pending.filter((pairing) => pairing.expiresAtMs <= nowMs);
+    return { kept: { pending: pending.pending.filter((pairing) => pairing.expiresAtMs > nowMs) }, expired };
+}
+function checkIsPairingUsed(paired, pairId) {
+    return paired.runners.some((runner) => runner.pairId === pairId);
+}
+/** @description Make a pairing code: a temporary key good for 10 minutes, its line in `authorized_keys`, its entry in `pending.json`. */
+function createPairing(ctx, params) {
+    return runTransaction(ctx, params.nowMs, (state) => {
+        const pairId = (0, sshKeys_1.createRandomId)();
+        const expiresAtMs = params.nowMs + (params.lifetimeMs ?? pairingTiming_1.pairingLifetimeMs);
+        const temporaryKey = (0, sshKeys_1.generateEd25519KeyPair)(`charness-pairing-${pairId}`);
+        const pairing = {
+            pairId,
+            publicKey: temporaryKey.publicKey,
+            keyFingerprint: (0, sshKeys_1.getPublicKeyFingerprint)(temporaryKey.publicKey),
+            expiresAtMs,
+            host: params.host,
+            port: params.port,
+            label: params.label,
+            messageRef: params.messageRef ?? null,
+        };
+        const payload = {
+            host: params.host,
+            port: params.port,
+            user: params.sshUser ?? os.userInfo().username,
+            hostKey: params.hostKey,
+            privateKey: temporaryKey.privateKey,
+            pairId,
+        };
+        // Codes that expired stay listed until `sweepExpiredPairings` hands them back: the instance that offered one still has a message to edit.
+        return { result: { pairId, expiresAtMs, code: (0, pairCode_1.encodePairCode)(payload), payload }, pending: { pending: [...state.pending.pending, pairing] } };
+    });
+}
+/** @description Is the pairing code `pairId` still open (made, not used, not expired)? The gate asks before it sends the package. */
+function checkIsPairingOpen(ctx, pairId, nowMs) {
+    return (0, hubRegistry_1.readPendingFile)(ctx.dir).pending.some((pairing) => pairing.pairId === pairId && pairing.expiresAtMs > nowMs)
+        && !checkIsPairingUsed((0, hubRegistry_1.readPairedFile)(ctx.dir), pairId);
+}
+/**
+ * @description Forget the pairing codes that have expired (their lines are gone from `authorized_keys` too) and return them, so the
+ * offering instance can edit its messages. A code that was used but whose entry outlived a crash is dropped without being returned.
+ * Run at boot, on a timer and by the CLI; sshd already refuses an expired key by itself.
+ */
+function sweepExpiredPairings(ctx, nowMs) {
+    return runTransaction(ctx, nowMs, (state) => {
+        const { kept, expired } = removeExpired(state.pending, nowMs);
+        return { result: expired, ...(kept.pending.length === state.pending.pending.length ? {} : { pending: kept }) };
+    });
+}
+/** @description What a runner may call itself: lowercase letters and digits with single dashes, short, never empty. */
+function sanitizeRunnerName(suggestedName) {
+    const cleaned = suggestedName
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, maxRunnerNameLength)
+        .replace(/-+$/g, '');
+    return cleaned === '' ? fallbackRunnerName : cleaned;
+}
+/** @description `name`, or `name-2`, `name-3`, … — the first that no paired or hand-made runner has. */
+function pickFreeRunnerName(suggestedName, takenNames) {
+    const base = sanitizeRunnerName(suggestedName);
+    if (!takenNames.has(base))
+        return base;
+    for (let suffix = 2;; suffix += 1) {
+        const candidate = `${base}-${suffix}`;
+        if (!takenNames.has(candidate))
+            return candidate;
+    }
+}
+function getTakenRunnerNames(ctx, paired) {
+    const handMade = (0, runnersConfig_1.loadRunnersConfigAt)((0, hubPaths_1.getHandMadeRunnersPath)(ctx.dir)).config?.runners ?? [];
+    return new Set([...paired.map((runner) => runner.name), ...handMade.map((runner) => runner.name)]);
+}
+function buildRedeemReply(runner, hubPublicKey, packageId) {
+    return { ok: true, runnerId: runner.id, name: runner.name, hubPublicKey, label: runner.label, host: runner.host, port: runner.port, packageId };
+}
+/**
+ * @description What `redeem` answered (or would answer) for the paired runner `runnerId` — for the runner that lost the answer.
+ * `ok: false` ONLY when the runner is not in the registry: that answer makes the runner stop its jobs, so a fault of the hub (a hub key
+ * that cannot be read, a file mode that changed) must not look like it — it throws, the gate fails without an answer, and the runner
+ * just tries again.
+ */
+function describeRunnerIdentity(ctx, runnerId, packageId) {
+    const runner = (0, hubRegistry_1.readPairedFile)(ctx.dir).runners.find((candidate) => candidate.id === runnerId);
+    if (runner === undefined)
+        return { ok: false, reason: 'this runner is not paired here' };
+    const hubKey = (0, hubKey_1.readHubKey)(ctx.dir);
+    if (hubKey === null)
+        throw new hubRegistry_1.HubRegistryError('the hub key cannot be read');
+    return buildRedeemReply(runner, hubKey.publicKey, packageId);
+}
+const unusableCodeReply = { ok: false, reason: 'this pairing code is unknown or already used' };
+/**
+ * @description Use the pairing code `pairId`: the runner's keys become a paired runner and the code is spent. A code that is unknown,
+ * used (by another key) or expired, and a key that is already registered, are refused with the reason (no values) and change nothing.
+ * The SAME machine asking again for a code it has already used — its answer was lost, or the hub failed after the registry was written —
+ * is answered again, and the derived files are repaired on the way. `packageId` is the hub's current package, told to the runner.
+ */
+function redeemPairing(ctx, pairId, request, nowMs, packageId = null) {
+    return runTransaction(ctx, nowMs, (state) => {
+        const used = state.paired.runners.find((runner) => runner.pairId === pairId);
+        if (used !== undefined) {
+            return { result: used.publicKey === request.publicKey ? buildRedeemReply(used, (0, hubKey_1.readOrCreateHubKeyLocked)(ctx.dir).publicKey, packageId) : unusableCodeReply };
+        }
+        const pairing = state.pending.pending.find((candidate) => candidate.pairId === pairId);
+        if (pairing === undefined)
+            return { result: unusableCodeReply };
+        if (pairing.expiresAtMs <= nowMs)
+            return { result: { ok: false, reason: 'this pairing code has expired' } };
+        if (state.paired.runners.some((runner) => runner.publicKey === request.publicKey))
+            return { result: { ok: false, reason: 'this machine is already paired' } };
+        const runner = {
+            id: (0, sshKeys_1.createRandomId)(),
+            name: pickFreeRunnerName(request.suggestedName, getTakenRunnerNames(ctx, state.paired.runners)),
+            publicKey: request.publicKey,
+            keyFingerprint: (0, sshKeys_1.getPublicKeyFingerprint)(request.publicKey),
+            hostKey: request.hostKey,
+            workDir: request.workDir,
+            os: request.os,
+            arch: request.arch,
+            version: request.version,
+            serviceKind: request.serviceKind,
+            pairedAtMs: nowMs,
+            pairId,
+            label: pairing.label,
+            host: pairing.host,
+            port: pairing.port,
+            isPaused: false,
+        };
+        return {
+            result: buildRedeemReply(runner, (0, hubKey_1.readOrCreateHubKeyLocked)(ctx.dir).publicKey, packageId),
+            paired: { rev: state.paired.rev + 1, runners: [...state.paired.runners, runner] },
+            pending: { pending: state.pending.pending.filter((candidate) => candidate.pairId !== pairId) },
+        };
+    });
+}
+/** @description Find a paired runner by its name or id. */
+function findPairedRunner(runners, nameOrId) {
+    return runners.find((runner) => runner.name === nameOrId) ?? runners.find((runner) => runner.id === nameOrId);
+}
+/** @description Is the runner `runnerId` in the registry? Every request of a runner's key asks, so a removed runner is refused at once even when its key line is still there. */
+function checkIsRunnerPaired(ctx, runnerId) {
+    return (0, hubRegistry_1.readPairedFile)(ctx.dir).runners.some((runner) => runner.id === runnerId);
+}
+/** @description Take a runner out: its entry leaves the registry, its line `authorized_keys`. `null` when there is no such runner. The link is cut by the caller (`linkControl.ts`). A retry after a failed step finds nothing to remove and repairs the files. */
+function removePairedRunner(ctx, nameOrId, nowMs) {
+    return runTransaction(ctx, nowMs, (state) => {
+        const runner = findPairedRunner(state.paired.runners, nameOrId);
+        if (runner === undefined)
+            return { result: null };
+        return { result: runner, paired: { rev: state.paired.rev + 1, runners: state.paired.runners.filter((candidate) => candidate.id !== runner.id) } };
+    });
+}
+/** @description Pause or resume a runner from the hub: it stays attached but is never picked for a job while paused. `null` when there is no such runner. */
+function setPairedRunnerPaused(ctx, nameOrId, isPaused) {
+    return runTransaction(ctx, Date.now(), (state) => {
+        const runner = findPairedRunner(state.paired.runners, nameOrId);
+        if (runner === undefined)
+            return { result: null };
+        const updated = { ...runner, isPaused };
+        if (runner.isPaused === isPaused)
+            return { result: updated };
+        return { result: updated, paired: { rev: state.paired.rev + 1, runners: state.paired.runners.map((candidate) => (candidate.id === runner.id ? updated : candidate)) } };
+    });
+}
+//# sourceMappingURL=hubPairing.js.map

package/dist/runners/hubPairing.js.map

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

package/dist/runners/hubPaths.d.ts

@@ -0,0 +1,38 @@
+/** @description Everything the hub side needs to know about the machine it runs on; tests build their own. */
+export interface HubContext {
+    /** The registry folder (0700). */
+    dir: string;
+    /** The `authorized_keys` file sshd reads for the account (a flow test points its sshd at a temp one). */
+    authorizedKeysPath: string;
+    /** The node binary and the charness `cli.js` the gate wrapper runs. */
+    nodePath: string;
+    cliPath: string;
+    /** The folder with `package.json`, `dist/` and `remoteRun/` — the package a runner installs. */
+    packageRoot: string;
+}
+export interface HubFilePaths {
+    paired: string;
+    pending: string;
+    hubKey: string;
+    hubPublicKey: string;
+    knownHosts: string;
+    gate: string;
+    linkDir: string;
+    packageDir: string;
+}
+/** @description The hand-made `runners.json` that sits beside the registry folder (see {@link createHubContext}). */
+export declare function getHandMadeRunnersPath(dir: string): string;
+export interface RunnerLinkPaths {
+    socket: string;
+    state: string;
+}
+/** @description The context of the real machine for `homeDir`; every field can be overridden. */
+export declare function createHubContext(overrides?: Partial<HubContext> & {
+    homeDir?: string;
+}): HubContext;
+export declare function getHubFilePaths(dir: string): HubFilePaths;
+/** @description The socket the gate of runner `runnerId` listens on, and the file that says who holds it. */
+export declare function getRunnerLinkPaths(dir: string, runnerId: string): RunnerLinkPaths;
+/** @description The host alias of a runner in the hub's `known_hosts` (and the `HostKeyAlias` of the ssh calls to it). */
+export declare function getRunnerHostAlias(runnerId: string): string;
+//# sourceMappingURL=hubPaths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hubPaths.d.ts","sourceRoot":"","sources":["../../src/runners/hubPaths.ts"],"names":[],"mappings":"AAeA,8GAA8G;AAC9G,MAAM,WAAW,UAAU;IACzB,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,yGAAyG;IACzG,kBAAkB,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,gGAAgG;IAChG,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qHAAqH;AACrH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAOD,iGAAiG;AACjG,wBAAgB,gBAAgB,CAAC,SAAS,GAAE,OAAO,CAAC,UAAU,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,UAAU,CAUvG;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAWzD;AAED,6GAA6G;AAC7G,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe,CAGjF;AAED,0HAA0H;AAC1H,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE3D"}