charness 3.6.1 → 3.8.0

package/dist/runners/hubAddress.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanHostKey = void 0;
+exports.parseHubAddress = parseHubAddress;
+exports.parseKeyscanOutput = parseKeyscanOutput;
+exports.checkHubAddress = checkHubAddress;
+const child_process_1 = require("child_process");
+const hubIds_1 = require("./hubIds");
+const sshKeys_1 = require("./sshKeys");
+/**
+ * @description The address runners dial and the check that it really is THIS machine's sshd. A pairing code pins the host key found
+ * at that address, so a mistyped address, or one that reaches another machine, must be caught before a code is made — otherwise the
+ * runner would be told to trust somebody else's key. The check compares what `ssh-keyscan` reads at the address with what it reads
+ * on the machine's own loopback port.
+ */
+const defaultSshPort = 22;
+const scanTimeoutSeconds = 5;
+const scanKillMs = 8 * 1000;
+const loopbackHosts = ['127.0.0.1', 'localhost', '::1'];
+const loopbackAddress = '127.0.0.1';
+/** Host key types in the order a pairing prefers them. */
+const hostKeyTypePreference = ['ssh-ed25519', 'ecdsa-sha2-nistp256', 'ecdsa-sha2-nistp384', 'ecdsa-sha2-nistp521', 'ssh-rsa'];
+/** @description `host`, `host:port`, `[v6]:port` or a bare IPv6 address, as an address (port 22 when none is given). */
+function parseHubAddress(text) {
+    const trimmed = text.trim();
+    const bracketed = /^\[([^\]]+)\](?::(\d+))?$/.exec(trimmed);
+    const hostAndPort = /^([^:]+):(\d+)$/.exec(trimmed);
+    const [host, portText] = bracketed !== null ? [bracketed[1], bracketed[2]] : hostAndPort !== null ? [hostAndPort[1], hostAndPort[2]] : [trimmed, undefined];
+    const port = portText === undefined ? defaultSshPort : Number(portText);
+    if (!hubIds_1.hubHostSchema.safeParse(host).success)
+        return { ok: false, error: 'the address must be a host name or an IP address, optionally with :port' };
+    if (!hubIds_1.hubPortSchema.safeParse(port).success)
+        return { ok: false, error: 'the port must be a number from 1 to 65535' };
+    return { ok: true, address: { host, port } };
+}
+/** @description The host key to pin out of `ssh-keyscan` output: the most preferred type that is a well-formed key, as `<type> <base64>`. */
+function parseKeyscanOutput(output) {
+    const keys = output
+        .split('\n')
+        .filter((line) => !line.startsWith('#'))
+        .map((line) => line.trim().split(/\s+/).slice(1, 3).join(' '))
+        .filter((key) => (0, sshKeys_1.parsePublicKey)(key) !== null);
+    for (const type of hostKeyTypePreference) {
+        const found = keys.find((key) => key.startsWith(`${type} `));
+        if (found !== undefined)
+            return found;
+    }
+    return null;
+}
+/** @description The real scanner: `ssh-keyscan`, bounded. */
+const scanHostKey = (host, port) => new Promise((resolve) => {
+    const child = (0, child_process_1.spawn)('ssh-keyscan', ['-T', scanTimeoutSeconds.toString(), '-p', port.toString(), host], { stdio: ['ignore', 'pipe', 'ignore'] });
+    let output = '';
+    const killTimer = setTimeout(() => child.kill('SIGKILL'), scanKillMs);
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { output += chunk; });
+    child.on('error', () => {
+        clearTimeout(killTimer);
+        resolve(null);
+    });
+    child.on('close', () => {
+        clearTimeout(killTimer);
+        resolve(parseKeyscanOutput(output));
+    });
+});
+exports.scanHostKey = scanHostKey;
+function describeKey(key) {
+    return (0, sshKeys_1.getPublicKeyFingerprint)(key);
+}
+/**
+ * @description Does `address` answer with an ssh server, and is it this machine's own? Returns the host key to pin. The machine's own
+ * sshd is read on its loopback; when that cannot be read the address is accepted with a note that it was not compared.
+ */
+async function checkHubAddress(address, scan) {
+    const found = await scan(address.host, address.port);
+    if (found === null)
+        return { ok: false, error: `nothing answers with an ssh host key at ${address.host}:${address.port} (is sshd running, and is the port reachable from outside?)` };
+    if (loopbackHosts.includes(address.host))
+        return { ok: true, hostKey: found, note: null };
+    const own = await scan(loopbackAddress, address.port);
+    if (own === null)
+        return { ok: true, hostKey: found, note: `this machine's own sshd could not be read on ${loopbackAddress}:${address.port}, so the address was not compared with it` };
+    if (own !== found) {
+        return { ok: false, error: `${address.host}:${address.port} answers with the ssh key ${describeKey(found)}, not this machine's own (${describeKey(own)}) — it is another machine, or a forward to one` };
+    }
+    return { ok: true, hostKey: found, note: null };
+}
+//# sourceMappingURL=hubAddress.js.map

package/dist/runners/hubAddress.js.map

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

package/dist/runners/hubAddressCandidates.d.ts

@@ -0,0 +1,16 @@
+import * as os from 'os';
+import { type HostKeyScanner, type HubAddress } from './hubAddress';
+/** @description `host:port`, a bare IPv6 host in brackets (`[2001:db8::1]:22`) — the spelling `parseHubAddress` reads back. */
+export declare function formatHubAddress(address: HubAddress): string;
+/** @description The globally routable addresses among `interfaces` (default: this machine's), IPv4 before IPv6, each once. */
+export declare function listPublicAddressCandidates(interfaces?: NodeJS.Dict<os.NetworkInterfaceInfo[]>): string[];
+export interface ProposedHubAddress {
+    address: HubAddress;
+    hostKey: string;
+}
+/**
+ * @description The first of `candidates` (on port 22) that answers with this machine's own ssh host key, or `null` when none does.
+ * A candidate whose own sshd could not be compared (`note` set) is not proposed: a proposal is a promise that the check passed.
+ */
+export declare function findProposedHubAddress(candidates: readonly string[], scan: HostKeyScanner): Promise<ProposedHubAddress | null>;
+//# sourceMappingURL=hubAddressCandidates.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hubAddressCandidates.d.ts","sourceRoot":"","sources":["../../src/runners/hubAddressCandidates.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,EAAmB,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAerF,+HAA+H;AAC/H,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAE5D;AAwBD,8HAA8H;AAC9H,wBAAgB,2BAA2B,CAAC,UAAU,GAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAA0B,GAAG,MAAM,EAAE,CAKjI;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,UAAU,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAOpI"}

package/dist/runners/hubAddressCandidates.js

@@ -0,0 +1,96 @@
+"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.formatHubAddress = formatHubAddress;
+exports.listPublicAddressCandidates = listPublicAddressCandidates;
+exports.findProposedHubAddress = findProposedHubAddress;
+const os = __importStar(require("os"));
+const hubAddress_1 = require("./hubAddress");
+/**
+ * @description The public address `/runners` proposes to the operator at the first pairing: the globally routable addresses of this
+ * machine's own network interfaces, on the ssh port 22, the first of which that answers with THIS machine's own sshd (the check of
+ * `hubAddress.ts`). A machine behind NAT (a cloud VPS whose public address lives on the provider's router) has none, and the
+ * operator types one — nothing is asked of a third-party service to learn it.
+ */
+const defaultCandidatePort = 22;
+const ipv6GlobalUnicastMask = 0xe000;
+const ipv6GlobalUnicastPrefix = 0x2000;
+const hexRadix = 16;
+const octetCount = 4;
+/** @description `host:port`, a bare IPv6 host in brackets (`[2001:db8::1]:22`) — the spelling `parseHubAddress` reads back. */
+function formatHubAddress(address) {
+    return address.host.includes(':') ? `[${address.host}]:${address.port}` : `${address.host}:${address.port}`;
+}
+function checkIsPublicIpv4(address) {
+    const octets = address.split('.').map(Number);
+    if (octets.length !== octetCount || octets.some((octet) => !Number.isInteger(octet)))
+        return false;
+    const [first, second] = octets;
+    const isPrivateOrReserved = first === 0 ||
+        first === 10 ||
+        first === 127 ||
+        (first === 100 && second >= 64 && second <= 127) ||
+        (first === 169 && second === 254) ||
+        (first === 172 && second >= 16 && second <= 31) ||
+        (first === 192 && second === 168) ||
+        first >= 224;
+    return !isPrivateOrReserved;
+}
+/** Global unicast is 2000::/3; a link-local, unique-local or loopback address never is. */
+function checkIsPublicIpv6(address) {
+    const firstGroup = Number.parseInt(address.split(':')[0], hexRadix);
+    return Number.isInteger(firstGroup) && (firstGroup & ipv6GlobalUnicastMask) === ipv6GlobalUnicastPrefix;
+}
+/** @description The globally routable addresses among `interfaces` (default: this machine's), IPv4 before IPv6, each once. */
+function listPublicAddressCandidates(interfaces = os.networkInterfaces()) {
+    const addresses = Object.values(interfaces).flatMap((entries) => entries ?? []).filter((entry) => !entry.internal);
+    const ipv4 = addresses.filter((entry) => entry.family === 'IPv4' && checkIsPublicIpv4(entry.address)).map((entry) => entry.address);
+    const ipv6 = addresses.filter((entry) => entry.family === 'IPv6' && checkIsPublicIpv6(entry.address)).map((entry) => entry.address);
+    return [...new Set([...ipv4, ...ipv6])];
+}
+/**
+ * @description The first of `candidates` (on port 22) that answers with this machine's own ssh host key, or `null` when none does.
+ * A candidate whose own sshd could not be compared (`note` set) is not proposed: a proposal is a promise that the check passed.
+ */
+async function findProposedHubAddress(candidates, scan) {
+    for (const host of candidates) {
+        const address = { host, port: defaultCandidatePort };
+        const check = await (0, hubAddress_1.checkHubAddress)(address, scan);
+        if (check.ok && check.note === null)
+            return { address, hostKey: check.hostKey };
+    }
+    return null;
+}
+//# sourceMappingURL=hubAddressCandidates.js.map

package/dist/runners/hubAddressCandidates.js.map

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

package/dist/runners/hubIds.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+/**
+ * @description The shapes of the identifiers that travel through ssh command lines, file names and the registry. Every one is matched
+ * against a strict pattern at the boundary it enters by (a gate's arguments, a pair code, a registry file), so none can carry a quote,
+ * a space, a slash or a leading dash into a shell word, a path or an `authorized_keys` option.
+ */
+/** Ids made by {@link createRandomId}: 12 lowercase hex digits. */
+export declare const hubIdPattern: RegExp;
+export declare const hubIdSchema: z.ZodString;
+/** A host name or address a runner dials: no spaces, no leading dash or dot, nothing a shell or ssh would read as an option. */
+export declare const hubHostSchema: z.ZodString;
+export declare const hubPortSchema: z.ZodNumber;
+export declare const hubSshUserSchema: z.ZodString;
+/** The hub's ssh host key as `<type> <base64>` — what a runner pins. */
+export declare const hubHostKeySchema: z.ZodString;
+//# sourceMappingURL=hubIds.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hubIds.d.ts","sourceRoot":"","sources":["../../src/runners/hubIds.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AAEH,mEAAmE;AACnE,eAAO,MAAM,YAAY,QAAmB,CAAC;AAQ7C,eAAO,MAAM,WAAW,aAA8D,CAAC;AACvF,gIAAgI;AAChI,eAAO,MAAM,aAAa,aAA4H,CAAC;AACvJ,eAAO,MAAM,aAAa,aAAuC,CAAC;AAClE,eAAO,MAAM,gBAAgB,aAAmE,CAAC;AAGjG,wEAAwE;AACxE,eAAO,MAAM,gBAAgB,aAAgE,CAAC"}

package/dist/runners/hubIds.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hubHostKeySchema = exports.hubSshUserSchema = exports.hubPortSchema = exports.hubHostSchema = exports.hubIdSchema = exports.hubIdPattern = void 0;
+const zod_1 = require("zod");
+/**
+ * @description The shapes of the identifiers that travel through ssh command lines, file names and the registry. Every one is matched
+ * against a strict pattern at the boundary it enters by (a gate's arguments, a pair code, a registry file), so none can carry a quote,
+ * a space, a slash or a leading dash into a shell word, a path or an `authorized_keys` option.
+ */
+/** Ids made by {@link createRandomId}: 12 lowercase hex digits. */
+exports.hubIdPattern = /^[0-9a-f]{12}$/;
+const hostNamePattern = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,252}$/;
+/** An IPv6 literal: hex digits, colons (at least two) and an optional dotted tail. */
+const ipv6Pattern = /^(?=(?:[^:]*:){2})[0-9A-Fa-f:.]{2,45}$/;
+const sshUserPattern = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$/;
+const maxPort = 65535;
+exports.hubIdSchema = zod_1.z.string().regex(exports.hubIdPattern, 'must be a 12-digit hex id');
+/** A host name or address a runner dials: no spaces, no leading dash or dot, nothing a shell or ssh would read as an option. */
+exports.hubHostSchema = zod_1.z.string().refine((host) => hostNamePattern.test(host) || ipv6Pattern.test(host), 'must be a host name or an IP address');
+exports.hubPortSchema = zod_1.z.number().int().min(1).max(maxPort);
+exports.hubSshUserSchema = zod_1.z.string().regex(sshUserPattern, 'must be a plain account name');
+const hostKeyPattern = /^(ssh-ed25519|ecdsa-sha2-nistp(?:256|384|521)|ssh-rsa) [A-Za-z0-9+/]+={0,2}$/;
+/** The hub's ssh host key as `<type> <base64>` — what a runner pins. */
+exports.hubHostKeySchema = zod_1.z.string().regex(hostKeyPattern, 'must be an ssh public key');
+//# sourceMappingURL=hubIds.js.map

package/dist/runners/hubIds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hubIds.js","sourceRoot":"","sources":["../../src/runners/hubIds.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAExB;;;;GAIG;AAEH,mEAAmE;AACtD,QAAA,YAAY,GAAG,gBAAgB,CAAC;AAE7C,MAAM,eAAe,GAAG,qCAAqC,CAAC;AAC9D,sFAAsF;AACtF,MAAM,WAAW,GAAG,wCAAwC,CAAC;AAC7D,MAAM,cAAc,GAAG,oCAAoC,CAAC;AAC5D,MAAM,OAAO,GAAG,KAAK,CAAC;AAET,QAAA,WAAW,GAAG,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,oBAAY,EAAE,2BAA2B,CAAC,CAAC;AACvF,gIAAgI;AACnH,QAAA,aAAa,GAAG,OAAC,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,sCAAsC,CAAC,CAAC;AAC1I,QAAA,aAAa,GAAG,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACrD,QAAA,gBAAgB,GAAG,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,cAAc,EAAE,8BAA8B,CAAC,CAAC;AAEjG,MAAM,cAAc,GAAG,8EAA8E,CAAC;AACtG,wEAAwE;AAC3D,QAAA,gBAAgB,GAAG,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,cAAc,EAAE,2BAA2B,CAAC,CAAC"}

package/dist/runners/hubKey.d.ts

@@ -0,0 +1,6 @@
+import { type SshKeyPair } from './sshKeys';
+/** @description The hub key, or `null` when none was made yet (or its files do not read). */
+export declare function readHubKey(dir: string): SshKeyPair | null;
+/** @description The hub key, made now when it is missing. The registry lock must be held (two first pairings must not make two keys). */
+export declare function readOrCreateHubKeyLocked(dir: string): SshKeyPair;
+//# sourceMappingURL=hubKey.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hubKey.d.ts","sourceRoot":"","sources":["../../src/runners/hubKey.ts"],"names":[],"mappings":"AAIA,OAAO,EAAmD,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAY7F,6FAA6F;AAC7F,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CASzD;AAED,yIAAyI;AACzI,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAYhE"}

package/dist/runners/hubKey.js

@@ -0,0 +1,78 @@
+"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.readHubKey = readHubKey;
+exports.readOrCreateHubKeyLocked = readOrCreateHubKeyLocked;
+const fs = __importStar(require("fs"));
+const configDirFile_1 = require("../configDirFile");
+const hubPaths_1 = require("./hubPaths");
+const hubRegistry_1 = require("./hubRegistry");
+const sshKeys_1 = require("./sshKeys");
+/**
+ * @description The hub's own client key (`hub_ed25519`): the one key every runner's built-in ssh server accepts, and the one the
+ * stock `ssh` calls of `remote-run` log in with. It is made on the first pairing; one key for all runners, because it only proves
+ * "this is the hub" to a machine that already trusts this hub.
+ */
+const privateKeyMode = 0o600;
+const publicKeyMode = 0o644;
+const hubKeyComment = 'charness-hub';
+/** @description The hub key, or `null` when none was made yet (or its files do not read). */
+function readHubKey(dir) {
+    const paths = (0, hubPaths_1.getHubFilePaths)(dir);
+    try {
+        const privateKey = fs.readFileSync(paths.hubKey, 'utf8');
+        const publicKey = fs.readFileSync(paths.hubPublicKey, 'utf8').trim().split(' ').slice(0, 2).join(' ');
+        return (0, sshKeys_1.checkIsEd25519PublicKey)(publicKey) ? { privateKey, publicKey } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** @description The hub key, made now when it is missing. The registry lock must be held (two first pairings must not make two keys). */
+function readOrCreateHubKeyLocked(dir) {
+    const existing = readHubKey(dir);
+    if (existing !== null)
+        return existing;
+    const paths = (0, hubPaths_1.getHubFilePaths)(dir);
+    // Every paired runner trusts THIS key: a half-present pair is never quietly replaced by a new one.
+    if (fs.existsSync(paths.hubKey) || fs.existsSync(paths.hubPublicKey)) {
+        throw new hubRegistry_1.HubRegistryError('hub_ed25519 and hub_ed25519.pub do not read as a pair; restore them, or delete both and pair the runners again');
+    }
+    const created = (0, sshKeys_1.generateEd25519KeyPair)(hubKeyComment);
+    (0, configDirFile_1.writeTextFileAtomically)(paths.hubKey, created.privateKey, privateKeyMode);
+    (0, configDirFile_1.writeTextFileAtomically)(paths.hubPublicKey, `${created.publicKey} ${hubKeyComment}\n`, publicKeyMode);
+    return created;
+}
+//# sourceMappingURL=hubKey.js.map

package/dist/runners/hubKey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hubKey.js","sourceRoot":"","sources":["../../src/runners/hubKey.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiBA,gCASC;AAGD,4DAYC;AAzCD,uCAAyB;AACzB,oDAA2D;AAC3D,yCAA6C;AAC7C,+CAAiD;AACjD,uCAA6F;AAE7F;;;;GAIG;AAEH,MAAM,cAAc,GAAG,KAAK,CAAC;AAC7B,MAAM,aAAa,GAAG,KAAK,CAAC;AAC5B,MAAM,aAAa,GAAG,cAAc,CAAC;AAErC,6FAA6F;AAC7F,SAAgB,UAAU,CAAC,GAAW;IACpC,MAAM,KAAK,GAAG,IAAA,0BAAe,EAAC,GAAG,CAAC,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACzD,MAAM,SAAS,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACtG,OAAO,IAAA,iCAAuB,EAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,yIAAyI;AACzI,SAAgB,wBAAwB,CAAC,GAAW;IAClD,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAC;IACvC,MAAM,KAAK,GAAG,IAAA,0BAAe,EAAC,GAAG,CAAC,CAAC;IACnC,mGAAmG;IACnG,IAAI,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,8BAAgB,CAAC,gHAAgH,CAAC,CAAC;IAC/I,CAAC;IACD,MAAM,OAAO,GAAG,IAAA,gCAAsB,EAAC,aAAa,CAAC,CAAC;IACtD,IAAA,uCAAuB,EAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;IAC1E,IAAA,uCAAuB,EAAC,KAAK,CAAC,YAAY,EAAE,GAAG,OAAO,CAAC,SAAS,IAAI,aAAa,IAAI,EAAE,aAAa,CAAC,CAAC;IACtG,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/runners/hubLock.d.ts

@@ -0,0 +1,7 @@
+/** @description Make the registry folder (0700) if it is missing. */
+export declare function ensureHubDir(dir: string): void;
+/** @description What tells one process from another that has the same pid: the start time (`/proc` on Linux, `ps` elsewhere), or `null`. */
+export declare function getProcessStartKey(pid: number): string | null;
+/** @description Run `action` while holding the registry lock; waits up to 15 s for it, then throws. */
+export declare function withHubLock<TResult>(dir: string, action: () => TResult | Promise<TResult>): Promise<TResult>;
+//# sourceMappingURL=hubLock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hubLock.d.ts","sourceRoot":"","sources":["../../src/runners/hubLock.ts"],"names":[],"mappings":"AAuDA,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE9C;AA4BD,4IAA4I;AAC5I,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS7D;AAoFD,uGAAuG;AACvG,wBAAsB,WAAW,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAelH"}

package/dist/runners/hubLock.js

@@ -0,0 +1,230 @@
+"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.ensureHubDir = ensureHubDir;
+exports.getProcessStartKey = getProcessStartKey;
+exports.withHubLock = withHubLock;
+const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const zod_1 = require("zod");
+/**
+ * @description The ONE lock of the runner registry: the gate processes sshd starts (a redeem, an unpair), the bot and the CLI all change
+ * `paired.json`, `pending.json`, `known_hosts` and the managed `authorized_keys` block, and a change reads what the others wrote first.
+ *
+ * A lock that is taken over by DELETING a dead holder's file cannot be made safe: two processes that judged the same holder dead can
+ * each delete «the» file, the second one deleting the lock the first has just taken. So nothing here is ever deleted on someone else's
+ * word. The lock is a numbered file, `lock.<n>`, and the holder is whoever created the HIGHEST number:
+ *
+ *   - to take the lock, create `lock.<top + 1>` exclusively (a hard link of a finished temp file, so it never shows half written;
+ *     `link` fails with EEXIST like `O_EXCL`) — of any number of contenders exactly one creates a given number, which is the whole
+ *     arbitration, also when they all found the same dead holder;
+ *   - the top file is free when its holder released it (the record says so) or is dead (its pid is gone, or belongs to a process that
+ *     started at another time — pid reuse); otherwise the contender waits. A holder that is ALIVE is never overtaken, however long it
+ *     has held: a process that is suspended inside its critical section (a stopped job, a laptop asleep) resumes where it was, and
+ *     overtaking it would let both write the registry. A holder that hangs for good blocks the registry loudly (the waiting caller
+ *     fails after 15 s naming the lock) instead of silently risking two writers;
+ *   - after creating its file the contender lists the folder again: if a higher number exists, its judgement was out of date (it saw
+ *     an old listing) — it removes its own file and starts over;
+ *   - a released lock stays as a marker (the next number is made after it, so numbers never repeat while a stale observer could still
+ *     be acting on them); the new holder removes the lower files.
+ */
+const lockFilePattern = /^lock\.(\d+)$/;
+const lockFilePrefix = 'lock.';
+const lockTempPrefix = 'lock-temp.';
+const lockPollMs = 25;
+const lockWaitLimitMs = 15 * 1000;
+/** A temp file of a process that died between writing it and linking it is swept after this long. */
+const abandonedTempAgeMs = 60 * 1000;
+const registryDirMode = 0o700;
+const tokenBytes = 8;
+const lockRecordSchema = zod_1.z.strictObject({
+    pid: zod_1.z.number().int().positive(),
+    /** Tells this holder's file from another's with the same number. */
+    token: zod_1.z.string(),
+    startedAtMs: zod_1.z.number(),
+    /** Identifies the holder's process beyond its pid (its start time), so a reused pid is not taken for the holder; `null` where it cannot be read. */
+    startKey: zod_1.z.string().nullable(),
+    /** Set when the holder gives the lock back; the file then stays as the marker of the number. */
+    releasedAtMs: zod_1.z.number().nullable(),
+});
+/** @description Make the registry folder (0700) if it is missing. */
+function ensureHubDir(dir) {
+    fs.mkdirSync(dir, { recursive: true, mode: registryDirMode });
+}
+function sleep(ms) {
+    return new Promise((resolve) => { setTimeout(resolve, ms); });
+}
+function getLockFilePath(dir, generation) {
+    return path.join(dir, `${lockFilePrefix}${generation}`);
+}
+function listGenerations(dir) {
+    return fs.readdirSync(dir)
+        .flatMap((name) => {
+        const match = lockFilePattern.exec(name);
+        return match === null ? [] : [Number(match[1])];
+    })
+        .sort((left, right) => left - right);
+}
+function readRecord(filePath) {
+    try {
+        const parsed = lockRecordSchema.safeParse(JSON.parse(fs.readFileSync(filePath, 'utf8')));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** @description What tells one process from another that has the same pid: the start time (`/proc` on Linux, `ps` elsewhere), or `null`. */
+function getProcessStartKey(pid) {
+    try {
+        const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+        // Field 22 counts from the state field that follows the command name's closing parenthesis.
+        return stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19] ?? null;
+    }
+    catch {
+        const listing = (0, child_process_1.spawnSync)('ps', ['-p', pid.toString(), '-o', 'lstart='], { encoding: 'utf8', timeout: 5000 });
+        return listing.status === 0 && listing.stdout.trim() !== '' ? listing.stdout.trim() : null;
+    }
+}
+function checkIsProcessAlive(record) {
+    try {
+        process.kill(record.pid, 0);
+    }
+    catch (error) {
+        // EPERM: the process exists but is another account's.
+        if (!(error instanceof Error && 'code' in error && error.code === 'EPERM'))
+            return false;
+    }
+    if (record.startKey === null)
+        return true;
+    const currentKey = getProcessStartKey(record.pid);
+    return currentKey === null || currentKey === record.startKey;
+}
+/** A record that does not read counts as a dead holder: a file nobody finished writing is never left by a live one (it is linked whole). */
+function checkIsHeld(record) {
+    return record !== null && record.releasedAtMs === null && checkIsProcessAlive(record);
+}
+function writeTempRecord(dir, record) {
+    const temporaryPath = path.join(dir, `${lockTempPrefix}${process.pid}.${(0, crypto_1.randomBytes)(tokenBytes).toString('hex')}`);
+    fs.writeFileSync(temporaryPath, JSON.stringify(record));
+    return temporaryPath;
+}
+/** Create `lock.<generation>` holding `record`, whole, only if no such file exists. */
+function createGenerationFile(dir, generation, record) {
+    const temporaryPath = writeTempRecord(dir, record);
+    try {
+        fs.linkSync(temporaryPath, getLockFilePath(dir, generation));
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'EEXIST')
+            return false;
+        throw error;
+    }
+    finally {
+        fs.rmSync(temporaryPath, { force: true });
+    }
+}
+function removeGenerationFileIfOwned(dir, generation, token) {
+    const filePath = getLockFilePath(dir, generation);
+    if (readRecord(filePath)?.token === token)
+        fs.rmSync(filePath, { force: true });
+}
+function createRelease(dir, generation, record) {
+    return () => {
+        const filePath = getLockFilePath(dir, generation);
+        if (readRecord(filePath)?.token !== record.token)
+            return;
+        const temporaryPath = writeTempRecord(dir, { ...record, releasedAtMs: Date.now() });
+        fs.renameSync(temporaryPath, filePath);
+    };
+}
+/** A process killed between writing its temp file and linking it leaves the temp file behind. */
+function removeAbandonedTempFiles(dir, nowMs) {
+    for (const name of fs.readdirSync(dir)) {
+        if (!name.startsWith(lockTempPrefix))
+            continue;
+        const filePath = path.join(dir, name);
+        try {
+            if (nowMs - fs.statSync(filePath).mtimeMs > abandonedTempAgeMs)
+                fs.rmSync(filePath, { force: true });
+        }
+        catch {
+            // Gone already: another contender swept it.
+        }
+    }
+}
+/** Try once. `null`: somebody holds the lock, or this attempt lost a race — the caller waits and tries again. */
+function tryAcquire(dir, nowMs) {
+    const generations = listGenerations(dir);
+    const top = generations.at(-1) ?? 0;
+    if (top > 0 && checkIsHeld(readRecord(getLockFilePath(dir, top))))
+        return null;
+    const generation = top + 1;
+    const record = { pid: process.pid, token: (0, crypto_1.randomBytes)(tokenBytes).toString('hex'), startedAtMs: nowMs, startKey: getProcessStartKey(process.pid), releasedAtMs: null };
+    if (!createGenerationFile(dir, generation, record))
+        return null;
+    const after = listGenerations(dir);
+    if (after.some((other) => other > generation)) {
+        removeGenerationFileIfOwned(dir, generation, record.token);
+        return null;
+    }
+    for (const lower of after.filter((other) => other < generation))
+        fs.rmSync(getLockFilePath(dir, lower), { force: true });
+    removeAbandonedTempFiles(dir, nowMs);
+    return { release: createRelease(dir, generation, record) };
+}
+/** @description Run `action` while holding the registry lock; waits up to 15 s for it, then throws. */
+async function withHubLock(dir, action) {
+    ensureHubDir(dir);
+    const deadline = Date.now() + lockWaitLimitMs;
+    for (;;) {
+        const lock = tryAcquire(dir, Date.now());
+        if (lock !== null) {
+            try {
+                return await action();
+            }
+            finally {
+                lock.release();
+            }
+        }
+        if (Date.now() >= deadline)
+            throw new Error('the runner registry is locked by another process (waited 15 s)');
+        await sleep(lockPollMs);
+    }
+}
+//# sourceMappingURL=hubLock.js.map

package/dist/runners/hubLock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hubLock.js","sourceRoot":"","sources":["../../src/runners/hubLock.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwDA,oCAEC;AA6BD,gDASC;AAqFD,kCAeC;AApMD,iDAA0C;AAC1C,mCAAqC;AACrC,uCAAyB;AACzB,2CAA6B;AAC7B,6BAAwB;AAExB;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,eAAe,GAAG,eAAe,CAAC;AACxC,MAAM,cAAc,GAAG,OAAO,CAAC;AAC/B,MAAM,cAAc,GAAG,YAAY,CAAC;AACpC,MAAM,UAAU,GAAG,EAAE,CAAC;AACtB,MAAM,eAAe,GAAG,EAAE,GAAG,IAAI,CAAC;AAClC,qGAAqG;AACrG,MAAM,kBAAkB,GAAG,EAAE,GAAG,IAAI,CAAC;AACrC,MAAM,eAAe,GAAG,KAAK,CAAC;AAC9B,MAAM,UAAU,GAAG,CAAC,CAAC;AAErB,MAAM,gBAAgB,GAAG,OAAC,CAAC,YAAY,CAAC;IACtC,GAAG,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IAChC,oEAAoE;IACpE,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;IACjB,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE;IACvB,oJAAoJ;IACpJ,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,gGAAgG;IAChG,YAAY,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACpC,CAAC,CAAC;AAQH,qEAAqE;AACrE,SAAgB,YAAY,CAAC,GAAW;IACtC,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC,CAAC;AAChE,CAAC;AAED,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,GAAG,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChE,CAAC;AAED,SAAS,eAAe,CAAC,GAAW,EAAE,UAAkB;IACtD,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,cAAc,GAAG,UAAU,EAAE,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,eAAe,CAAC,GAAW;IAClC,OAAO,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC;SACvB,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;QAChB,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzC,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAClD,CAAC,CAAC;SACD,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC;AACzC,CAAC;AAED,SAAS,UAAU,CAAC,QAAgB;IAClC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,gBAAgB,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;QACzF,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,4IAA4I;AAC5I,SAAgB,kBAAkB,CAAC,GAAW;IAC5C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,SAAS,GAAG,OAAO,EAAE,MAAM,CAAC,CAAC;QAC1D,4FAA4F;QAC5F,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC;IACtE,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,OAAO,GAAG,IAAA,yBAAS,EAAC,IAAI,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9G,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7F,CAAC;AACH,CAAC;AAED,SAAS,mBAAmB,CAAC,MAAkB;IAC7C,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,sDAAsD;QACtD,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC;YAAE,OAAO,KAAK,CAAC;IAC3F,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC1C,MAAM,UAAU,GAAG,kBAAkB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAClD,OAAO,UAAU,KAAK,IAAI,IAAI,UAAU,KAAK,MAAM,CAAC,QAAQ,CAAC;AAC/D,CAAC;AAED,4IAA4I;AAC5I,SAAS,WAAW,CAAC,MAAyB;IAC5C,OAAO,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,YAAY,KAAK,IAAI,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAAC;AACxF,CAAC;AAED,SAAS,eAAe,CAAC,GAAW,EAAE,MAAkB;IACtD,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,cAAc,GAAG,OAAO,CAAC,GAAG,IAAI,IAAA,oBAAW,EAAC,UAAU,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACnH,EAAE,CAAC,aAAa,CAAC,aAAa,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IACxD,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,uFAAuF;AACvF,SAAS,oBAAoB,CAAC,GAAW,EAAE,UAAkB,EAAE,MAAkB;IAC/E,MAAM,aAAa,GAAG,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACnD,IAAI,CAAC;QACH,EAAE,CAAC,QAAQ,CAAC,aAAa,EAAE,eAAe,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC;QAC7D,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QACvF,MAAM,KAAK,CAAC;IACd,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,MAAM,CAAC,aAAa,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,CAAC;AACH,CAAC;AAED,SAAS,2BAA2B,CAAC,GAAW,EAAE,UAAkB,EAAE,KAAa;IACjF,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IAClD,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,KAAK,KAAK,KAAK;QAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAClF,CAAC;AAED,SAAS,aAAa,CAAC,GAAW,EAAE,UAAkB,EAAE,MAAkB;IACxE,OAAO,GAAG,EAAE;QACV,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QAClD,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,KAAK,KAAK,MAAM,CAAC,KAAK;YAAE,OAAO;QACzD,MAAM,aAAa,GAAG,eAAe,CAAC,GAAG,EAAE,EAAE,GAAG,MAAM,EAAE,YAAY,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACpF,EAAE,CAAC,UAAU,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;IACzC,CAAC,CAAC;AACJ,CAAC;AAED,iGAAiG;AACjG,SAAS,wBAAwB,CAAC,GAAW,EAAE,KAAa;IAC1D,KAAK,MAAM,IAAI,IAAI,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;QACvC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC;YAAE,SAAS;QAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACtC,IAAI,CAAC;YACH,IAAI,KAAK,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,OAAO,GAAG,kBAAkB;gBAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACvG,CAAC;QAAC,MAAM,CAAC;YACP,4CAA4C;QAC9C,CAAC;IACH,CAAC;AACH,CAAC;AAED,iHAAiH;AACjH,SAAS,UAAU,CAAC,GAAW,EAAE,KAAa;IAC5C,MAAM,WAAW,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,GAAG,GAAG,CAAC,IAAI,WAAW,CAAC,UAAU,CAAC,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/E,MAAM,UAAU,GAAG,GAAG,GAAG,CAAC,CAAC;IAC3B,MAAM,MAAM,GAAe,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,IAAA,oBAAW,EAAC,UAAU,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAE,kBAAkB,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;IACnL,IAAI,CAAC,oBAAoB,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAChE,MAAM,KAAK,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,UAAU,CAAC,EAAE,CAAC;QAC9C,2BAA2B,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QAC3D,OAAO,IAAI,CAAC;IACd,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,UAAU,CAAC;QAAE,EAAE,CAAC,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACzH,wBAAwB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,CAAC;AAC7D,CAAC;AAED,uGAAuG;AAChG,KAAK,UAAU,WAAW,CAAU,GAAW,EAAE,MAAwC;IAC9F,YAAY,CAAC,GAAG,CAAC,CAAC;IAClB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,eAAe,CAAC;IAC9C,SAAS,CAAC;QACR,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACzC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,IAAI,CAAC;gBACH,OAAO,MAAM,MAAM,EAAE,CAAC;YACxB,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,CAAC;QACH,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;QAC9G,MAAM,KAAK,CAAC,UAAU,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC"}