@chordra.ai/ctl 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# @chordra.ai/ctl
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@chordra.ai/ctl` is the transient bootstrap used to install or repair a Chordra Host. It provides the
+`chordra-ai-ctl` command.
+It obtains the server-selected native release, verifies it, and delegates setup to the
+native runner.
+
+Requires Node.js **22.22.0 or newer**. The setup command enforces the package's
+`engines.node` requirement before making network requests or installing files,
+even when npm's `engine-strict` is disabled.
+
+```sh
+npx -y @chordra.ai/ctl@latest setup --server https://api.chordra.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.
+
+Its version belongs to this package's `package.json`, independently of the native release
+selected by the server. Native daemon releases do not rebuild or republish this package.
+Bootstrap changes use the [independent publication procedure](../../deploy/runbook.md#bootstrap-publication).

package/bin/chord-ctl

@@ -0,0 +1,607 @@
+#!/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 BOOTSTRAP_SCHEMA = 2;
+const REQUEST_TIMEOUT_MS = 30_000;
+const MAX_URL_BYTES = 4096;
+const MAX_BOOTSTRAP_BYTES = 64 * 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 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 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");
+  }
+  if (payload.schema_version !== BOOTSTRAP_SCHEMA) {
+    throw new Error("unsupported bootstrap schema");
+  }
+  if (Object.keys(payload).sort().join(",") !== "approved_cli_version,canonical_environment_id,release,schema_version") {
+    throw new Error("bootstrap response has an invalid 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");
+  }
+  const release = validateRelease(payload.release, payload.approved_cli_version);
+  return {
+    environmentID: payload.canonical_environment_id,
+    version: payload.approved_cli_version,
+    release,
+  };
+}
+
+function validateRelease(release, approvedVersion) {
+  if (!isPlainObject(release) || release.version !== approvedVersion) {
+    throw new Error("bootstrap release does not match the approved version");
+  }
+  if (!Array.isArray(release.sources) || release.sources.length !== 1 || release.sources[0] !== "native") {
+    throw new Error("bootstrap release has invalid sources");
+  }
+  if (Object.keys(release).sort().join(",") !== "archive,sources,version" || !isPlainObject(release.archive)) {
+    throw new Error("native release has an invalid schema");
+  }
+  const archive = release.archive;
+  if (Object.keys(archive).sort().join(",") !== "goarch,goos,integrity,size,url") {
+    throw new Error("native archive has an invalid schema");
+  }
+  const arch = process.arch === "x64" ? "amd64" : process.arch;
+  if (archive.goos !== process.platform || archive.goarch !== arch) {
+    throw new Error("native archive does not match this platform");
+  }
+  if (!Number.isSafeInteger(archive.size) || archive.size <= 0 || archive.size > MAX_TARBALL_BYTES) {
+    throw new Error("native archive has an invalid size");
+  }
+  if (typeof archive.url !== "string" || Buffer.byteLength(archive.url) > MAX_URL_BYTES || /[\x00-\x20\x7f?#]/.test(archive.url)) {
+    throw new Error("native archive has an invalid URL");
+  }
+  const url = parseHTTPURL(archive.url, "native archive URL", { allowPath: true });
+  if (url.protocol !== "https:" && !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)) {
+    throw new Error("native archive URL must use HTTPS");
+  }
+  const digests = parseIntegrity(archive.integrity);
+  if (digests.length !== 1 || archive.integrity !== "sha512-" + digests[0].toString("base64")) {
+    throw new Error("native archive has an invalid sha512 integrity");
+  }
+  return release;
+}
+
+function requestBytes(target, limit, label, accept) {
+  return new Promise((resolve, reject) => {
+    const client = target.protocol === "https:" ? https : http;
+    let settled = false;
+    let request;
+    let deadline;
+
+    const finish = (error, value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(deadline);
+      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) {
+            finish(new Error(label + " returned HTTP " + status));
+            response.destroy();
+            return;
+          }
+
+          const lengthHeader = response.headers["content-length"];
+          if (lengthHeader !== undefined) {
+            if (!/^\d+$/.test(lengthHeader) || Number(lengthHeader) > limit) {
+              finish(new Error(label + " exceeds the size limit"));
+              response.destroy();
+              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) {
+              finish(new Error(label + " exceeds the size limit"));
+              response.destroy();
+              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;
+    }
+
+    deadline = setTimeout(() => {
+      request.destroy(new Error(label + " request timed out"));
+    }, REQUEST_TIMEOUT_MS);
+    request.on("error", (error) => finish(new Error(label + " failed: " + error.message)));
+  });
+}
+
+async function fetchBootstrap(serverURL) {
+  const server = parseHTTPURL(serverURL, "--server");
+  targetDirectory();
+  const endpoint = new URL("/api/bootstrap", server);
+  endpoint.searchParams.set("schema", String(BOOTSTRAP_SCHEMA));
+  endpoint.searchParams.set("os", process.platform);
+  endpoint.searchParams.set("arch", process.arch === "x64" ? "amd64" : process.arch);
+  const body = await requestBytes(endpoint, MAX_BOOTSTRAP_BYTES, "bootstrap request", "application/json");
+  return validateBootstrapResponse(parseJSON(body, "bootstrap response"));
+}
+
+function parseIntegrity(value) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error("archive 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("archive has an invalid sha512 integrity");
+    }
+    const digest = Buffer.from(encoded, "base64");
+    if (digest.length !== 64 || digest.toString("base64") !== encoded) {
+      throw new Error("archive has an invalid sha512 integrity");
+    }
+    digests.push(digest);
+  }
+  if (digests.length === 0) {
+    throw new Error("archive has an invalid sha512 integrity");
+  }
+  return digests;
+}
+
+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 unpackArchive(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("archive exceeds the uncompressed size limit");
+    }
+    throw new Error("archive 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 release 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 acquireRelease(release) {
+  const archive = release.archive;
+  try {
+    const tarball = await requestBytes(new URL(archive.url), archive.size, "native archive request");
+    if (tarball.length !== archive.size) {
+      throw new Error("archive size mismatch");
+    }
+    const actual = crypto.createHash("sha512").update(tarball).digest();
+    const expected = parseIntegrity(archive.integrity)[0];
+    if (!crypto.timingSafeEqual(actual, expected)) {
+      throw new Error("archive integrity mismatch");
+    }
+    return unpackArchive(tarball);
+  } catch (error) {
+    throw new Error("could not acquire approved CLI release: " + error.message);
+  }
+}
+
+async function setup(serverURL) {
+  const bootstrap = await fetchBootstrap(serverURL);
+  const binaries = await acquireRelease(bootstrap.release);
+  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)) {
+  // npm treats engines as advisory by default. Enforce the same package-owned
+  // floor before argument processing, network access, or native setup.
+  const requirement = require("../package.json").engines.node;
+  const minimum = /^>=(\d+)\.(\d+)\.(\d+)$/.exec(requirement);
+  if (!minimum) {
+    throw new Error("unsupported package Node.js requirement: " + requirement);
+  }
+  const current = /^(\d+)\.(\d+)\.(\d+)$/.exec(process.versions.node);
+  let supported = current !== null;
+  if (current) {
+    for (let index = 1; index <= 3; index += 1) {
+      if (Number(current[index]) !== Number(minimum[index])) {
+        supported = Number(current[index]) > Number(minimum[index]);
+        break;
+      }
+    }
+  }
+  if (!supported) {
+    throw new Error("Node.js " + requirement + " is required; found " + process.versions.node + ". Upgrade Node.js and run setup again.");
+  }
+  const args = parseArguments(argv);
+  return setup(args.server);
+}
+
+if (require.main === module) {
+  main().then(
+    (exitCode) => {
+      if (exitCode) {
+        process.exitCode = exitCode;
+      }
+    },
+    (error) => {
+      console.error("chordra-ai-ctl: " + error.message);
+      process.exitCode = 1;
+    },
+  );
+}
+
+module.exports = {
+  BOOTSTRAP_SCHEMA,
+  MAX_ARCHIVE_BYTES,
+  MAX_BOOTSTRAP_BYTES,
+  MAX_ENTRY_BYTES,
+  MAX_TARBALL_BYTES,
+  parseArguments,
+  parseTar,
+  setup,
+  unpackArchive,
+  validateBootstrapResponse,
+};

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@chordra.ai/ctl",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "Transient Chordra Host setup bootstrap",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "chordra-ai-ctl": "bin/chord-ctl"
+  },
+  "files": [
+    "README.md",
+    "bin"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=22.22.0"
+  }
+}