@getformation/cloud-cli 1.0.0

package/src/connector.mjs

@@ -0,0 +1,408 @@
+import { createHash, randomBytes } from "node:crypto";
+import { lstat, mkdir, open, readFile, readdir, realpath, rmdir, stat, unlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fail } from "./errors.mjs";
+
+export const CONNECTOR_RECEIPT_NAME = ".formation-connector-install.json";
+export const CONNECTOR_VERSION = "1.0.0";
+const CONNECTOR_NAME = "formation";
+const PACKAGE_NAME = "@getformation/cloud-cli";
+const MAX_CONNECTOR_BYTES = 65_536;
+const POSIX_PATH_LIMIT_BYTES = 1_024;
+const INSTALL_TOKEN_BYTES = 18;
+const INSTALL_TOKEN_HEX_LENGTH = INSTALL_TOKEN_BYTES * 2;
+const INSTALL_TOKEN_PLACEHOLDER = "0".repeat(INSTALL_TOKEN_HEX_LENGTH);
+const LOCK_PREFIX = ".formation-connector-lock-";
+const STAGE_PREFIX = ".formation-connector-stage-";
+const CONNECTOR_FILE_NAME = "SKILL.md";
+
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+
+function connectorFiles(directory) {
+  return {
+    skill: path.join(directory, CONNECTOR_FILE_NAME),
+    receipt: path.join(directory, CONNECTOR_RECEIPT_NAME),
+  };
+}
+
+function installPaths(target, token = INSTALL_TOKEN_PLACEHOLDER) {
+  const parent = path.dirname(target);
+  const lock = path.join(parent, `${LOCK_PREFIX}${sha256(Buffer.from(target, "utf8"))}`);
+  const stage = path.join(parent, `${STAGE_PREFIX}${token}`);
+  return {
+    lock,
+    stage,
+    targetFiles: connectorFiles(target),
+    stageFiles: connectorFiles(stage),
+  };
+}
+
+function assertInstallPathBudget(paths) {
+  const candidates = [
+    paths.lock, paths.stage, ...Object.values(paths.targetFiles), ...Object.values(paths.stageFiles),
+  ];
+  if (candidates.some((candidate) => Buffer.byteLength(candidate, "utf8") + 1 > POSIX_PATH_LIMIT_BYTES)) {
+    fail("invalid_target", "The connector target is too long for a safe portable install.",
+      "Choose a shorter absolute target path.");
+  }
+}
+
+function identity(info) {
+  return { dev: info.dev, ino: info.ino, type: info.isDirectory() ? "directory" : info.isFile() ? "file" : "other" };
+}
+
+function sameIdentity(left, right) {
+  return left?.dev === right?.dev && left?.ino === right?.ino && left?.type === right?.type;
+}
+
+async function artifact() {
+  const bytes = await readFile(new URL("../connector/SKILL.md", import.meta.url));
+  if (!bytes.length || bytes.length > MAX_CONNECTOR_BYTES) {
+    fail("invalid_connector", "The bundled Formation connector is empty or oversized.", "Install a valid @getformation/cloud-cli package.");
+  }
+  const digest = sha256(bytes);
+  return { bytes, sha256: digest, artifactRevisionId: `connectorrev_${digest}` };
+}
+
+function exactTarget(target) {
+  if (typeof target !== "string" || !path.isAbsolute(target) || path.resolve(target) !== target) {
+    fail("invalid_target", "The connector target must be one exact normalized absolute path.",
+      "Pass --target with an absolute path that contains no dot segments or trailing separator.");
+  }
+  if ([path.parse(target).root, path.resolve(os.homedir())].includes(target)) {
+    fail("unsafe_target", "The filesystem root and home directory cannot be connector targets.",
+      "Choose a dedicated absent connector directory below an owner-controlled parent.");
+  }
+}
+
+function assertOwnerSafe(info, subject) {
+  if (typeof process.getuid === "function" && info.uid !== process.getuid()) {
+    fail("install_conflict", `${subject} has foreign ownership.`, "Choose an owner-controlled target.");
+  }
+  if ((info.mode & 0o022) !== 0) {
+    fail("install_conflict", `${subject} is group- or world-writable.`, "Choose an owner-controlled target.");
+  }
+}
+
+async function maybeLstat(filePath) {
+  try { return await lstat(filePath); }
+  catch (error) { if (error?.code === "ENOENT") return null; throw error; }
+}
+
+async function safeParent(target) {
+  const root = path.parse(target).root;
+  let cursor = root;
+  for (const part of path.relative(root, path.dirname(target)).split(path.sep).filter(Boolean)) {
+    cursor = path.join(cursor, part);
+    const info = await maybeLstat(cursor);
+    if (!info || !info.isDirectory() || info.isSymbolicLink()) {
+      fail("invalid_target_parent", "Every target ancestor must be one existing real directory.",
+        "Create one owner-controlled parent without symbolic links.");
+    }
+  }
+  const parent = await realpath(path.dirname(target));
+  if (parent !== path.dirname(target)) {
+    fail("install_conflict", "The connector target parent uses an alias.", "Use the canonical parent path.");
+  }
+  const info = await stat(parent);
+  assertOwnerSafe(info, "The connector target parent");
+  return { path: parent, identity: identity(info) };
+}
+
+async function boundedRegularFile(filePath, maximum) {
+  const info = await lstat(filePath);
+  if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1 || info.size < 1 || info.size > maximum) {
+    fail("install_conflict", "The connector target contains an invalid file.", "Use a new absent target.");
+  }
+  assertOwnerSafe(info, "A connector target file");
+  const bytes = await readFile(filePath);
+  if (bytes.length !== info.size) fail("install_conflict", "A connector target file changed while it was read.", "Use a new absent target.");
+  return bytes;
+}
+
+function exactReceipt(value, expected) {
+  const keys = ["schemaVersion", "installer", "connector", "connectorVersion", "artifactRevisionId", "sha256", "installedAt", "file"];
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || Object.keys(value).sort().join("\0") !== keys.sort().join("\0")
+    || value.schemaVersion !== 1 || value.installer !== PACKAGE_NAME || value.connector !== CONNECTOR_NAME
+    || value.connectorVersion !== CONNECTOR_VERSION || value.artifactRevisionId !== expected.artifactRevisionId
+    || value.sha256 !== expected.sha256 || value.file !== CONNECTOR_FILE_NAME
+    || typeof value.installedAt !== "string" || !Number.isFinite(Date.parse(value.installedAt))) {
+    fail("install_conflict", "The connector install receipt is invalid or stale.", "Use a new absent target.");
+  }
+  return value;
+}
+
+async function inspect(target, expected, { allowEmpty = false } = {}) {
+  const info = await maybeLstat(target);
+  if (!info) return { exists: false };
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    fail("install_conflict", "The connector target is not one real directory.", "Use a new absent target.");
+  }
+  assertOwnerSafe(info, "The connector target");
+  const entries = (await readdir(target)).sort();
+  if (allowEmpty && entries.length === 0) {
+    return { exists: true, empty: true, identity: identity(info) };
+  }
+  if (entries.join("\0") !== [CONNECTOR_RECEIPT_NAME, CONNECTOR_FILE_NAME].sort().join("\0")) {
+    fail("install_conflict", "The connector target contains missing or extra paths.", "Use a new absent target.");
+  }
+  const files = connectorFiles(target);
+  const body = await boundedRegularFile(files.skill, MAX_CONNECTOR_BYTES);
+  const receiptBytes = await boundedRegularFile(files.receipt, 16_384);
+  let receipt;
+  try { receipt = exactReceipt(JSON.parse(receiptBytes.toString("utf8")), expected); }
+  catch (error) {
+    if (error?.code) throw error;
+    fail("install_conflict", "The connector install receipt is not valid JSON.", "Use a new absent target.");
+  }
+  if (sha256(body) !== expected.sha256) {
+    fail("install_conflict", "The installed connector bytes do not match their receipt.", "Use a new absent target.");
+  }
+  return { exists: true, empty: false, identity: identity(info), receipt };
+}
+
+async function assertIdentity(filePath, expected, subject) {
+  const info = await maybeLstat(filePath);
+  if (!info || !sameIdentity(identity(info), expected)) {
+    fail("install_conflict", `${subject} changed during installation.`, "Inspect the target and retry with one unchanged owner-controlled parent.");
+  }
+  assertOwnerSafe(info, subject);
+}
+
+async function writeExclusive(filePath, bytes, onCreate, afterWrite) {
+  const handle = await open(filePath, "wx", 0o600);
+  try {
+    const descriptor = { identity: identity(await handle.stat()), complete: false };
+    onCreate?.(descriptor);
+    await handle.writeFile(bytes);
+    await afterWrite?.({ filePath });
+    await handle.sync();
+    Object.assign(descriptor, { complete: true, byteLength: bytes.length, sha256: sha256(bytes) });
+  } finally { await handle.close(); }
+}
+
+async function syncDirectory(directory) {
+  const handle = await open(directory, "r");
+  try { await handle.sync(); } finally { await handle.close(); }
+}
+
+async function removeOwnedFile(filePath, expectedIdentity, expectedContents = null) {
+  const info = await maybeLstat(filePath);
+  if (!info || !info.isFile() || info.isSymbolicLink() || info.nlink !== 1
+    || !sameIdentity(identity(info), expectedIdentity)) return false;
+  assertOwnerSafe(info, "An installer-owned file");
+  if (expectedContents !== null && await readFile(filePath, "utf8").catch(() => null) !== expectedContents) return false;
+  const current = await maybeLstat(filePath);
+  if (!current || !sameIdentity(identity(current), expectedIdentity)) return false;
+  await unlink(filePath);
+  return true;
+}
+
+async function removeOwnedDirectory(directory, parent) {
+  if (!directory?.path || !directory.identity) return false;
+  try {
+    const parentInfo = await maybeLstat(parent.path);
+    if (!parentInfo || !sameIdentity(identity(parentInfo), parent.identity)) return false;
+    assertOwnerSafe(parentInfo, "The connector target parent");
+    const directoryInfo = await maybeLstat(directory.path);
+    if (!directoryInfo || !directoryInfo.isDirectory() || directoryInfo.isSymbolicLink()
+      || !sameIdentity(identity(directoryInfo), directory.identity)) return false;
+    assertOwnerSafe(directoryInfo, "An installer-owned connector directory");
+    const entries = (await readdir(directory.path)).sort();
+    if (entries.some((entry) => !directory.files.has(entry))) return false;
+    for (const entry of entries) {
+      const descriptor = directory.files.get(entry);
+      const filePath = path.join(directory.path, entry);
+      const info = await maybeLstat(filePath);
+      if (!info || !info.isFile() || info.isSymbolicLink() || info.nlink !== 1
+        || !sameIdentity(identity(info), descriptor.identity)) return false;
+      if (descriptor.complete) {
+        const bytes = await readFile(filePath);
+        if (bytes.length !== descriptor.byteLength || sha256(bytes) !== descriptor.sha256) return false;
+      }
+    }
+    if (!sameIdentity(identity(await lstat(directory.path)), directory.identity)
+      || (await readdir(directory.path)).sort().join("\0") !== entries.join("\0")) return false;
+    for (const entry of entries) {
+      if (!await removeOwnedFile(path.join(directory.path, entry), directory.files.get(entry).identity)) return false;
+    }
+    const current = await maybeLstat(directory.path);
+    if (!current || !sameIdentity(identity(current), directory.identity) || (await readdir(directory.path)).length !== 0) return false;
+    await rmdir(directory.path);
+    await syncDirectory(parent.path);
+    return true;
+  } catch { return false; }
+}
+
+async function removeOwnedTargetFiles(target, files) {
+  try {
+    for (const [name, descriptor] of files) {
+      const filePath = path.join(target, name);
+      const info = await maybeLstat(filePath);
+      if (!info || !info.isFile() || info.isSymbolicLink() || info.nlink !== 1
+        || !sameIdentity(identity(info), descriptor.identity)) continue;
+      if (descriptor.complete) {
+        const bytes = await readFile(filePath);
+        if (bytes.length !== descriptor.byteLength || sha256(bytes) !== descriptor.sha256) continue;
+      }
+      await removeOwnedFile(filePath, descriptor.identity);
+    }
+    const targetInfo = await maybeLstat(target);
+    if (targetInfo?.isDirectory() && !targetInfo.isSymbolicLink()) await syncDirectory(target);
+  } catch {
+    return false;
+  }
+  return true;
+}
+
+async function ensureRetryableTarget(target, expected) {
+  try { await mkdir(target, { mode: 0o700 }); }
+  catch (error) { if (error?.code !== "EEXIST") throw error; }
+  const state = await inspect(target, expected, { allowEmpty: true });
+  if (!state.exists || !state.empty) {
+    fail("install_conflict", "The connector target changed before publication.",
+      "Inspect it and retry only when it is one owner-safe empty directory.");
+  }
+}
+
+async function acquireLock(paths, token, parent) {
+  await assertIdentity(parent.path, parent.identity, "The connector target parent");
+  let handle;
+  try { handle = await open(paths.lock, "wx", 0o600); }
+  catch (error) {
+    if (error?.code === "EEXIST") fail("install_conflict", "Another connector install lock exists.", "Wait for that install to finish.");
+    throw error;
+  }
+  let lockIdentity;
+  try {
+    lockIdentity = identity(await handle.stat());
+    await handle.writeFile(token);
+    await handle.sync();
+    await syncDirectory(parent.path);
+  } catch (error) {
+    await handle.close().catch(() => {});
+    if (lockIdentity) await removeOwnedFile(paths.lock, lockIdentity).catch(() => {});
+    await syncDirectory(parent.path).catch(() => {});
+    throw error;
+  }
+  await handle.close();
+  return {
+    path: paths.lock,
+    token,
+    async release() {
+      if (await removeOwnedFile(paths.lock, lockIdentity, token)) await syncDirectory(parent.path);
+    },
+  };
+}
+
+export async function installConnector({ target, apply = false, hooks = {} }) {
+  exactTarget(target);
+  assertInstallPathBudget(installPaths(target));
+  const parent = await safeParent(target);
+  const expected = await artifact();
+  const before = await inspect(target, expected, { allowEmpty: true });
+  if (before.exists && !before.empty) {
+    return { status: "current", action: "unchanged", applied: false, target,
+      artifactRevisionId: expected.artifactRevisionId, sha256: expected.sha256 };
+  }
+  if (!apply) {
+    return { status: "ready", action: "would_install", applied: false, target,
+      artifactRevisionId: expected.artifactRevisionId, sha256: expected.sha256 };
+  }
+  const token = randomBytes(INSTALL_TOKEN_BYTES).toString("hex");
+  const paths = installPaths(target, token);
+  const lock = await acquireLock(paths, token, parent);
+  const stage = {
+    path: paths.stage,
+    identity: null,
+    files: new Map(),
+  };
+  const published = { files: new Map(), committed: false };
+  try {
+    await assertIdentity(parent.path, parent.identity, "The connector target parent");
+    const lockedTarget = await inspect(target, expected, { allowEmpty: true });
+    if (lockedTarget.exists && !lockedTarget.empty) {
+      return { status: "current", action: "unchanged", applied: false, target,
+        artifactRevisionId: expected.artifactRevisionId, sha256: expected.sha256 };
+    }
+    await mkdir(stage.path, { mode: 0o700 });
+    stage.identity = identity(await lstat(stage.path));
+    await hooks.afterStageDirectoryCreate?.({ stage: stage.path, target });
+    await writeExclusive(paths.stageFiles.skill, expected.bytes,
+      (descriptor) => stage.files.set(CONNECTOR_FILE_NAME, descriptor));
+    const receipt = {
+      schemaVersion: 1, installer: PACKAGE_NAME, connector: CONNECTOR_NAME, connectorVersion: CONNECTOR_VERSION,
+      artifactRevisionId: expected.artifactRevisionId, sha256: expected.sha256,
+      installedAt: new Date().toISOString(), file: CONNECTOR_FILE_NAME,
+    };
+    await writeExclusive(paths.stageFiles.receipt, Buffer.from(`${JSON.stringify(receipt, null, 2)}\n`, "utf8"),
+      (descriptor) => stage.files.set(CONNECTOR_RECEIPT_NAME, descriptor));
+    await syncDirectory(stage.path);
+    await syncDirectory(parent.path);
+    await hooks.afterStage?.({ stage: stage.path, target });
+    const staged = await inspect(stage.path, expected);
+    if (!staged.exists || !sameIdentity(staged.identity, stage.identity)) {
+      fail("install_conflict", "The staged connector changed during installation.", "Inspect the staged path and retry with a new absent target.");
+    }
+    await assertIdentity(parent.path, parent.identity, "The connector target parent");
+    const publishTarget = await inspect(target, expected, { allowEmpty: true });
+    if (publishTarget.exists && !publishTarget.empty) {
+      fail("install_conflict", "The connector target changed during installation.",
+        "Inspect it and retry only when it is one owner-safe empty directory.");
+    }
+    await assertIdentity(stage.path, stage.identity, "The staged connector");
+    const verifiedStage = await inspect(stage.path, expected);
+    if (!verifiedStage.exists || !sameIdentity(verifiedStage.identity, stage.identity)) {
+      fail("install_conflict", "The staged connector changed before installation.", "Inspect the staged path and retry with a new absent target.");
+    }
+    await hooks.beforeInstall?.({ stage: stage.path, target });
+    await ensureRetryableTarget(target, expected);
+    await hooks.afterTargetDirectoryCreate?.({ stage: stage.path, target });
+    await writeExclusive(paths.targetFiles.skill, expected.bytes,
+      (descriptor) => published.files.set(CONNECTOR_FILE_NAME, descriptor),
+      (context) => hooks.afterSkillWrite?.({ ...context, stage: stage.path, target }));
+    await writeExclusive(paths.targetFiles.receipt, Buffer.from(`${JSON.stringify(receipt, null, 2)}\n`, "utf8"),
+      (descriptor) => published.files.set(CONNECTOR_RECEIPT_NAME, descriptor));
+    await syncDirectory(target);
+    await syncDirectory(parent.path);
+    const installed = await inspect(target, expected);
+    if (!installed.exists) {
+      fail("install_conflict", "The installed connector changed before it committed.", "Inspect the target before retrying.");
+    }
+    if (!await removeOwnedDirectory(stage, parent)) {
+      fail("install_conflict", "The staged connector changed before cleanup.", "Inspect the staged path before retrying.");
+    }
+    stage.path = null;
+    published.committed = true;
+    return { status: "current", action: "installed", applied: true, target,
+      artifactRevisionId: expected.artifactRevisionId, sha256: expected.sha256 };
+  } catch (error) {
+    if (["EEXIST", "ENOTEMPTY", "ENOTDIR", "EISDIR"].includes(error?.code)) {
+      fail("install_conflict", "The connector target appeared during installation.", "Inspect it and choose a new absent target.");
+    }
+    throw error;
+  } finally {
+    if (!published.committed) await removeOwnedTargetFiles(target, published.files).catch(() => {});
+    await removeOwnedDirectory(stage, parent).catch(() => {});
+    await lock.release().catch(() => {});
+  }
+}
+
+export async function checkConnector({ target }) {
+  exactTarget(target);
+  try {
+    await safeParent(target);
+    const expected = await artifact();
+    const state = await inspect(target, expected);
+    if (!state.exists) return { status: "conflict", target, reason: "not_installed", deleted: false };
+    return { status: "current", target, artifactRevisionId: expected.artifactRevisionId,
+      sha256: expected.sha256, deleted: false };
+  } catch (error) {
+    if (["install_conflict", "invalid_target_parent"].includes(error?.code)) {
+      return { status: "conflict", target, reason: error.message, deleted: false };
+    }
+    throw error;
+  }
+}

package/src/errors.mjs

@@ -0,0 +1,29 @@
+export class CloudCliError extends Error {
+  constructor(code, message, recovery, details = undefined) {
+    super(message);
+    this.name = "CloudCliError";
+    this.code = code;
+    this.recovery = recovery;
+    if (details !== undefined) this.details = details;
+  }
+}
+
+export function fail(code, message, recovery, details) {
+  throw new CloudCliError(code, message, recovery, details);
+}
+
+export function safeFailure(error) {
+  if (error instanceof CloudCliError) {
+    return {
+      code: error.code,
+      error: error.message,
+      recovery: error.recovery,
+      ...(error.details === undefined ? {} : { details: error.details }),
+    };
+  }
+  return {
+    code: "command_failed",
+    error: "The Cloud command could not complete safely.",
+    recovery: "Check the command, configured origin, and current target state.",
+  };
+}