@sys9/chord-ctl 0.0.0

package/README.md

@@ -0,0 +1,12 @@
+# @sys9/chord-ctl
+
+`@sys9/chord-ctl` is the transient bootstrap used to install or repair a Chord Host.
+It obtains the server-selected native release, verifies it, and delegates setup to the
+native runner.
+
+```sh
+npx -y @sys9/chord-ctl@latest setup --server https://chord-api.sys9.ai
+```
+
+The bootstrap exits after handing control to the native runner. It does not install or
+invoke a package manager while acquiring the selected release.

package/bin/chord-ctl

@@ -0,0 +1,609 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const crypto = require("node:crypto");
+const { spawn } = require("node:child_process");
+const fs = require("node:fs");
+const http = require("node:http");
+const https = require("node:https");
+const os = require("node:os");
+const path = require("node:path");
+const { TextDecoder } = require("node:util");
+const zlib = require("node:zlib");
+
+const PACKAGE_NAME = "@sys9/chord-cli";
+const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org/";
+const BOOTSTRAP_SCHEMA = 1;
+const REQUEST_TIMEOUT_MS = 30_000;
+const MAX_URL_BYTES = 4096;
+const MAX_BOOTSTRAP_BYTES = 64 * 1024;
+const MAX_METADATA_BYTES = 1024 * 1024;
+const MAX_TARBALL_BYTES = 128 * 1024 * 1024;
+const MAX_ARCHIVE_BYTES = 512 * 1024 * 1024;
+const MAX_ENTRY_BYTES = 128 * 1024 * 1024;
+const MAX_ARCHIVE_ENTRIES = 1024;
+
+const VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const ENVIRONMENT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+const PLATFORM_TAGS = {
+  "linux:x64": "linux-x64",
+  "linux:arm64": "linux-arm64",
+  "darwin:x64": "darwin-x64",
+  "darwin:arm64": "darwin-arm64",
+};
+
+const textDecoder = new TextDecoder("utf-8", { fatal: true });
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function parseArguments(argv) {
+  if (!Array.isArray(argv) || argv.length === 0 || argv[0] !== "setup") {
+    throw new Error("expected: setup --server URL");
+  }
+
+  let server = null;
+  for (let index = 1; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--server") {
+      if (server !== null || index + 1 >= argv.length) {
+        throw new Error("setup requires exactly one --server URL");
+      }
+      server = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (argument.startsWith("--server=")) {
+      if (server !== null || argument.length === "--server=".length) {
+        throw new Error("setup requires exactly one --server URL");
+      }
+      server = argument.slice("--server=".length);
+      continue;
+    }
+    throw new Error("unsupported argument: " + argument);
+  }
+
+  if (server === null) {
+    throw new Error("missing required --server URL");
+  }
+  return { server };
+}
+
+function parseHTTPURL(value, label, { allowPath = false, allowQuery = false } = {}) {
+  if (typeof value !== "string" || value.length === 0 || value.length > MAX_URL_BYTES) {
+    throw new Error(label + " must be a bounded URL");
+  }
+  if (value !== value.trim()) {
+    throw new Error(label + " must not contain surrounding whitespace");
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error(label + " must be a valid URL");
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(label + " must use http or https");
+  }
+  if (parsed.username || parsed.password || parsed.hash || (!allowQuery && parsed.search)) {
+    throw new Error(
+      label +
+        (allowQuery
+          ? " must not contain credentials or fragment"
+          : " must not contain credentials, query, or fragment"),
+    );
+  }
+  if (!allowPath && parsed.pathname !== "/") {
+    throw new Error(label + " must be an HTTP origin");
+  }
+  return parsed;
+}
+
+function platformTag(platform = process.platform, arch = process.arch) {
+  const tag = PLATFORM_TAGS[platform + ":" + arch];
+  if (!tag) {
+    throw new Error("unsupported platform: " + platform + " (" + arch + ")");
+  }
+  return tag;
+}
+
+function isVersion(value) {
+  return typeof value === "string" && value.length <= 128 && VERSION_PATTERN.test(value);
+}
+
+function parseJSON(body, label) {
+  let text;
+  try {
+    text = textDecoder.decode(body);
+  } catch {
+    throw new Error(label + " is not valid UTF-8");
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(label + " is not valid JSON");
+  }
+}
+
+function validateBootstrapResponse(payload) {
+  if (!isPlainObject(payload)) {
+    throw new Error("bootstrap response must be an object");
+  }
+  const keys = Object.keys(payload).sort();
+  if (
+    keys.length !== 3 ||
+    keys[0] !== "approved_cli_version" ||
+    keys[1] !== "canonical_environment_id" ||
+    keys[2] !== "schema_version"
+  ) {
+    throw new Error("bootstrap response has an invalid schema");
+  }
+  if (payload.schema_version !== BOOTSTRAP_SCHEMA) {
+    throw new Error("unsupported bootstrap schema");
+  }
+  if (
+    typeof payload.canonical_environment_id !== "string" ||
+    !ENVIRONMENT_ID_PATTERN.test(payload.canonical_environment_id)
+  ) {
+    throw new Error("bootstrap response has an invalid canonical_environment_id");
+  }
+  if (!isVersion(payload.approved_cli_version)) {
+    throw new Error("bootstrap response has an invalid version");
+  }
+  return {
+    environmentID: payload.canonical_environment_id,
+    version: payload.approved_cli_version,
+  };
+}
+
+function requestBytes(target, limit, label, accept) {
+  return new Promise((resolve, reject) => {
+    const client = target.protocol === "https:" ? https : http;
+    let settled = false;
+    let request;
+
+    const finish = (error, value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (error) {
+        reject(error);
+      } else {
+        resolve(value);
+      }
+    };
+
+    try {
+      request = client.get(
+        target,
+        {
+          headers: {
+            accept: accept || "*/*",
+            "accept-encoding": "identity",
+          },
+        },
+        (response) => {
+          const status = response.statusCode || 0;
+          if (status !== 200) {
+            response.destroy();
+            finish(new Error(label + " returned HTTP " + status));
+            return;
+          }
+
+          const lengthHeader = response.headers["content-length"];
+          if (lengthHeader !== undefined) {
+            if (!/^\d+$/.test(lengthHeader) || Number(lengthHeader) > limit) {
+              response.destroy();
+              finish(new Error(label + " exceeds the size limit"));
+              return;
+            }
+          }
+
+          const chunks = [];
+          let size = 0;
+          response.on("data", (chunk) => {
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            size += bytes.length;
+            if (size > limit) {
+              response.destroy();
+              finish(new Error(label + " exceeds the size limit"));
+              return;
+            }
+            chunks.push(bytes);
+          });
+          response.on("end", () => finish(null, Buffer.concat(chunks, size)));
+          response.on("aborted", () => finish(new Error(label + " response was interrupted")));
+          response.on("error", (error) => finish(new Error(label + " failed: " + error.message)));
+        },
+      );
+    } catch (error) {
+      finish(new Error(label + " failed: " + error.message));
+      return;
+    }
+
+    request.setTimeout(REQUEST_TIMEOUT_MS, () => {
+      request.destroy(new Error(label + " request timed out"));
+    });
+    request.on("error", (error) => finish(new Error(label + " failed: " + error.message)));
+  });
+}
+
+async function fetchBootstrap(serverURL) {
+  const server = parseHTTPURL(serverURL, "--server");
+  const endpoint = new URL("/api/bootstrap", server);
+  const body = await requestBytes(endpoint, MAX_BOOTSTRAP_BYTES, "bootstrap request", "application/json");
+  return validateBootstrapResponse(parseJSON(body, "bootstrap response"));
+}
+
+function registryURL(environment = process.env) {
+  const hasOverride = Object.prototype.hasOwnProperty.call(environment, "CHORD_NPM_REGISTRY");
+  const value = hasOverride ? environment.CHORD_NPM_REGISTRY : DEFAULT_NPM_REGISTRY;
+  const registry = parseHTTPURL(value, "CHORD_NPM_REGISTRY", { allowPath: true });
+  if (!registry.pathname.endsWith("/")) {
+    registry.pathname += "/";
+  }
+  return registry;
+}
+
+function metadataURL(registry, version) {
+  return new URL("@sys9/chord-cli/" + encodeURIComponent(version), registry);
+}
+
+function parseIntegrity(value) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error("package metadata has an invalid sha512 integrity");
+  }
+  const digests = [];
+  for (const token of value.trim().split(/\s+/)) {
+    if (!token.startsWith("sha512-")) {
+      continue;
+    }
+    const encoded = token.slice("sha512-".length);
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(encoded)) {
+      throw new Error("package metadata has an invalid sha512 integrity");
+    }
+    const digest = Buffer.from(encoded, "base64");
+    if (digest.length !== 64 || digest.toString("base64") !== encoded) {
+      throw new Error("package metadata has an invalid sha512 integrity");
+    }
+    digests.push(digest);
+  }
+  if (digests.length === 0) {
+    throw new Error("package metadata has an invalid sha512 integrity");
+  }
+  return digests;
+}
+
+function validatePackageMetadata(payload, expectedVersion, registry) {
+  if (!isPlainObject(payload) || payload.name !== PACKAGE_NAME || payload.version !== expectedVersion) {
+    throw new Error("package metadata does not describe the requested package version");
+  }
+  if (!isPlainObject(payload.dist)) {
+    throw new Error("package metadata has no dist object");
+  }
+  const integrity = parseIntegrity(payload.dist.integrity);
+  if (typeof payload.dist.tarball !== "string") {
+    throw new Error("package metadata has no tarball URL");
+  }
+  const tarball = parseHTTPURL(payload.dist.tarball, "package tarball", {
+    allowPath: true,
+    allowQuery: true,
+  });
+  if (tarball.origin !== registry.origin) {
+    throw new Error("package tarball origin does not match the registry");
+  }
+  return { integrity, tarball };
+}
+
+async function fetchPackage(registry, version) {
+  const metadata = metadataURL(registry, version);
+  const metadataBody = await requestBytes(
+    metadata,
+    MAX_METADATA_BYTES,
+    "package metadata request",
+    "application/json",
+  );
+  const packageInfo = validatePackageMetadata(parseJSON(metadataBody, "package metadata"), version, registry);
+  const tarballBody = await requestBytes(packageInfo.tarball, MAX_TARBALL_BYTES, "package tarball request");
+  const actual = crypto.createHash("sha512").update(tarballBody).digest();
+  if (!packageInfo.integrity.some((digest) => crypto.timingSafeEqual(actual, digest))) {
+    throw new Error("package tarball integrity mismatch");
+  }
+  return tarballBody;
+}
+
+function tarText(bytes, label) {
+  const end = bytes.indexOf(0);
+  const field = end === -1 ? bytes : bytes.subarray(0, end);
+  try {
+    return textDecoder.decode(field);
+  } catch {
+    throw new Error("tar archive has an invalid " + label);
+  }
+}
+
+function tarNumber(bytes, label) {
+  const raw = tarText(bytes, label).trim();
+  if (!/^[0-7]+$/.test(raw)) {
+    throw new Error("tar archive has an invalid " + label);
+  }
+  const value = Number.parseInt(raw, 8);
+  if (!Number.isSafeInteger(value)) {
+    throw new Error("tar archive has an invalid " + label);
+  }
+  return value;
+}
+
+function isZeroBlock(block) {
+  for (const byte of block) {
+    if (byte !== 0) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function validateTarPath(value, directory) {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > 512 ||
+    value.includes("\\") ||
+    value.includes("\0") ||
+    value.startsWith("/") ||
+    /^[A-Za-z]:/.test(value)
+  ) {
+    throw new Error("tar archive contains an unsafe path");
+  }
+  const pathValue = directory && value.endsWith("/") ? value.slice(0, -1) : value;
+  const components = pathValue.split("/");
+  if (
+    components.some(
+      (component) =>
+        component.length === 0 ||
+        component === "." ||
+        component === ".." ||
+        component.includes(":")
+    )
+  ) {
+    throw new Error("tar archive contains an unsafe path");
+  }
+  return pathValue;
+}
+
+function targetDirectory(platform = process.platform, arch = process.arch) {
+  const goarch = arch === "x64" ? "amd64" : arch;
+  if (platform !== "linux" && platform !== "darwin") {
+    throw new Error("unsupported platform: " + platform + " (" + arch + ")");
+  }
+  if (goarch !== "amd64" && goarch !== "arm64") {
+    throw new Error("unsupported platform: " + platform + " (" + arch + ")");
+  }
+  return platform + "_" + goarch;
+}
+
+function parseTar(tar, target = targetDirectory()) {
+  if (!Buffer.isBuffer(tar) || tar.length === 0 || tar.length > MAX_ARCHIVE_BYTES) {
+    throw new Error("tar archive exceeds the size limit");
+  }
+  if (!/^(?:linux|darwin)_(?:amd64|arm64)$/.test(target)) {
+    throw new Error("invalid native release target");
+  }
+  const targetRoot = "package/vendor/" + target;
+  const expectedPaths = new Map([
+    [targetRoot + "/runner", "runner"],
+    [targetRoot + "/chord-daemon", "chord-daemon"],
+    [targetRoot + "/chord-bridge", "chord-bridge"],
+  ]);
+  const entries = new Map();
+  const extractedNames = new Set();
+  let offset = 0;
+  let entryCount = 0;
+  let endBlocks = 0;
+
+  while (offset + 512 <= tar.length) {
+    const header = tar.subarray(offset, offset + 512);
+    offset += 512;
+    if (isZeroBlock(header)) {
+      endBlocks += 1;
+      if (endBlocks === 2) {
+        break;
+      }
+      continue;
+    }
+    if (endBlocks !== 0) {
+      throw new Error("tar archive has data after its end marker");
+    }
+    entryCount += 1;
+    if (entryCount > MAX_ARCHIVE_ENTRIES) {
+      throw new Error("tar archive has too many entries");
+    }
+
+    const checksum = tarNumber(header.subarray(148, 156), "checksum");
+    let computedChecksum = 0;
+    for (let index = 0; index < header.length; index += 1) {
+      computedChecksum += index >= 148 && index < 156 ? 32 : header[index];
+    }
+    if (checksum !== computedChecksum) {
+      throw new Error("tar archive has an invalid checksum");
+    }
+
+    const name = tarText(header.subarray(0, 100), "path");
+    const prefix = tarText(header.subarray(345, 500), "path");
+    const fullName = prefix ? prefix + "/" + name : name;
+    const type = header[156];
+    const directory = type === 53;
+    const safeName = validateTarPath(fullName, directory);
+    if (safeName !== "package" && !safeName.startsWith("package/")) {
+      throw new Error("tar archive entry is outside package/");
+    }
+    if (extractedNames.has(safeName)) {
+      throw new Error("tar archive contains a duplicate path");
+    }
+    extractedNames.add(safeName);
+
+    if (type !== 0 && type !== 48 && !directory) {
+      throw new Error("tar archive contains a link or special file");
+    }
+    const size = tarNumber(header.subarray(124, 136), "file size");
+    if (size > MAX_ENTRY_BYTES) {
+      throw new Error("tar archive entry exceeds the size limit");
+    }
+    const end = offset + size;
+    if (end < offset || end > tar.length) {
+      throw new Error("tar archive entry is truncated");
+    }
+    if (directory && size !== 0) {
+      throw new Error("tar archive directory has data");
+    }
+    const padding = (512 - (size % 512)) % 512;
+    if (end + padding > tar.length) {
+      throw new Error("tar archive entry padding is truncated");
+    }
+    const outputName = expectedPaths.get(safeName);
+    const inTarget = safeName === targetRoot || safeName.startsWith(targetRoot + "/");
+    if (inTarget && safeName !== targetRoot && !outputName) {
+      throw new Error("tar archive contains an unexpected target entry " + safeName);
+    }
+    if (type === 0 || type === 48) {
+      if (outputName) {
+        const mode = tarNumber(header.subarray(100, 108), "file mode");
+        if ((mode & 0o111) === 0 || size === 0) {
+          throw new Error("native release file " + safeName + " is not executable");
+        }
+        if (entries.has(outputName)) {
+          throw new Error("tar archive contains a duplicate binary");
+        }
+        entries.set(outputName, Buffer.from(tar.subarray(offset, end)));
+      }
+    }
+    offset = end + padding;
+  }
+
+  if (endBlocks < 2 || offset > tar.length || (tar.length - offset) % 512 !== 0) {
+    throw new Error("tar archive has no complete end marker");
+  }
+  for (const byte of tar.subarray(offset)) {
+    if (byte !== 0) {
+      throw new Error("tar archive has trailing data");
+    }
+  }
+  for (const name of ["runner", "chord-daemon", "chord-bridge"]) {
+    const content = entries.get(name);
+    if (!content || content.length === 0) {
+      throw new Error("tar archive is missing " + name);
+    }
+  }
+  return entries;
+}
+
+function unpackPackage(tarball, target = targetDirectory()) {
+  let tar;
+  try {
+    tar = zlib.gunzipSync(tarball, { maxOutputLength: MAX_ARCHIVE_BYTES });
+  } catch (error) {
+    if (error && error.code === "ERR_BUFFER_TOO_LARGE") {
+      throw new Error("package tarball exceeds the uncompressed size limit");
+    }
+    throw new Error("package tarball is not a valid gzip archive: " + error.message);
+  }
+  return parseTar(tar, target);
+}
+
+function materializeBinaries(entries) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "chord-ctl-"));
+  try {
+    for (const name of ["runner", "chord-daemon", "chord-bridge"]) {
+      const target = path.join(root, name);
+      fs.writeFileSync(target, entries.get(name), { encoding: null, mode: 0o700, flag: "wx" });
+      fs.chmodSync(target, 0o700);
+      if (!fs.lstatSync(target).isFile()) {
+        throw new Error("extracted " + name + " is not a regular file");
+      }
+    }
+    return root;
+  } catch (error) {
+    fs.rmSync(root, { recursive: true, force: true });
+    throw new Error("could not materialize package binaries: " + error.message);
+  }
+}
+
+function runRunner(root, serverURL, environmentID) {
+  const runnerPath = path.join(root, "runner");
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn(
+        runnerPath,
+        ["setup", "--server", serverURL, "--environment-id", environmentID],
+        { stdio: "inherit" },
+      );
+    } catch (error) {
+      reject(error);
+      return;
+    }
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (signal) {
+        resolve(1);
+      } else {
+        resolve(code === null ? 1 : code);
+      }
+    });
+  });
+}
+
+async function setup(serverURL, environment = process.env) {
+  const bootstrap = await fetchBootstrap(serverURL);
+  const version = bootstrap.version + "-" + platformTag();
+  const tarball = await fetchPackage(registryURL(environment), version);
+  const binaries = unpackPackage(tarball);
+  const root = materializeBinaries(binaries);
+  try {
+    return await runRunner(root, serverURL, bootstrap.environmentID);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+async function main(argv = process.argv.slice(2), environment = process.env) {
+  const args = parseArguments(argv);
+  return setup(args.server, environment);
+}
+
+if (require.main === module) {
+  main().then(
+    (exitCode) => {
+      if (exitCode) {
+        process.exitCode = exitCode;
+      }
+    },
+    (error) => {
+      console.error("chord-ctl: " + error.message);
+      process.exitCode = 1;
+    },
+  );
+}
+
+module.exports = {
+  BOOTSTRAP_SCHEMA,
+  DEFAULT_NPM_REGISTRY,
+  MAX_ARCHIVE_BYTES,
+  MAX_BOOTSTRAP_BYTES,
+  MAX_ENTRY_BYTES,
+  MAX_METADATA_BYTES,
+  MAX_TARBALL_BYTES,
+  parseArguments,
+  parseTar,
+  platformTag,
+  registryURL,
+  setup,
+  unpackPackage,
+  validateBootstrapResponse,
+  validatePackageMetadata,
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@sys9/chord-ctl",
+  "version": "0.0.0",
+  "description": "Transient Chord Host setup bootstrap",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sys9-ai/chord.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "chord-ctl": "bin/chord-ctl"
+  },
+  "files": [
+    "README.md",
+    "bin"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}