@zaip-ai/cli 6.3.0 → 7.5.0

package/templates/.agents/tools/cloud-onboarding-ssh.mjs

@@ -0,0 +1,223 @@
+import { dirname } from "node:path";
+import { credentialPath, recheckIdentity } from "./cloud-onboarding-credentials.mjs";
+import { fail, fingerprint, hash, inside } from "./cloud-onboarding-policy.mjs";
+
+export const PROBES = Object.freeze({
+  os: "sed -n '/^\\(ID\\|NAME\\)=/p' /etc/os-release",
+  os_version: "sed -n '/^VERSION_ID=/p' /etc/os-release",
+  architecture: "uname -sm",
+  cpu: "getconf _NPROCESSORS_ONLN",
+  memory: "sed -n '/^Mem\\(Total\\|Available\\):/p' /proc/meminfo",
+  disk: "df -Pk /",
+  hostname: "hostname",
+  network: "ip -brief address",
+  user: "id",
+  docker: "docker version --format '{{.Server.Version}}'",
+  compose: "docker compose version --short",
+  services: "systemctl list-units --type=service --state=running --no-legend --no-pager",
+  ports: "ss -lntu",
+  firewall:
+    "if command -v ufw >/dev/null 2>&1; then ufw status; elif command -v nft >/dev/null 2>&1; then nft list tables; else exit 127; fi",
+  storage: "ls -ld /srv /opt /var/lib/docker/volumes",
+  mounts:
+    "findmnt --list --output TARGET,SOURCE,FSTYPE,OPTIONS --target /srv && findmnt --list --output TARGET,SOURCE,FSTYPE,OPTIONS --target /opt && findmnt --list --output TARGET,SOURCE,FSTYPE,OPTIONS --target /var/lib/docker/volumes",
+  volumes: "docker volume ls --format '{{.Name}} {{.Driver}}'",
+});
+export function sanitize(value, max = 4096) {
+  return (
+    String(value)
+      .replace(
+        /-----BEGIN [^-]*(?:PRIVATE KEY|OPENSSH)[^-]*-----[\s\S]*?(?:-----END [^-]+-----|$)/g,
+        "[redacted]",
+      )
+      .replace(
+        /(?:Bearer\s+|(?:token|password|secret|api[_-]?key|credential|authorization)[A-Za-z0-9_-]*[\s:=]+)[^\s]+/gi,
+        "[redacted]",
+      )
+      .replace(/\b(?:sk-[A-Za-z0-9_-]{12,}|CANARY[A-Za-z0-9_-]*)\b/g, "[redacted]")
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: reject or remove unsafe control bytes at the public input/output boundary.
+      .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, "")
+      .slice(0, max)
+  );
+}
+const hostLabel = (ssh) => (ssh.port === 22 ? ssh.host : `[${ssh.host}]:${ssh.port}`);
+export function verifyKnown(content, target) {
+  const lines = content.trim().split(/\r?\n/).filter(Boolean);
+  if (!lines.length || lines.length > 8) fail("host_key_mismatch");
+  for (const line of lines) {
+    if (
+      line.split(/\s+/)[0] !== hostLabel(target.ssh) ||
+      fingerprint(line) !== target.ssh.host_fingerprint
+    )
+      fail("host_key_mismatch");
+  }
+  return `${lines.join("\n")}\n`;
+}
+export async function trustHost(target, ctx) {
+  const ssh = target.ssh;
+  const known = inside(ctx.root, `.agents/private/state/ssh/${target.name}/known_hosts`);
+  await ctx.files.localDirectory(dirname(known));
+  await ctx.files.untracked(known);
+  let existing;
+  try {
+    await ctx.files.checked(known);
+    existing = await ctx.files.readFile(known, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  if (existing !== undefined) {
+    verifyKnown(existing, target);
+    return {
+      state: "verified",
+      trust_source: ssh.trust.source,
+      known_hosts: `.agents/private/state/ssh/${target.name}/known_hosts`,
+    };
+  }
+  let publicKey = ssh.host_public_key;
+  if (!publicKey) {
+    const collected = await ctx.exec("ssh-keyscan", ["-T", "5", "-p", String(ssh.port), ssh.host], {
+      timeout: 8000,
+      maxOutput: 16384,
+    });
+    if (collected.code !== 0) fail("host_key_collection_unavailable");
+    const matches = String(collected.stdout)
+      .split(/\r?\n/)
+      .filter((line) => {
+        if (!line || line.startsWith("#")) return false;
+        try {
+          return fingerprint(line) === ssh.host_fingerprint;
+        } catch {
+          return false;
+        }
+      });
+    if (!matches.length) fail("host_key_mismatch");
+    publicKey = matches[0].split(/\s+/).slice(1, 3).join(" ");
+  }
+  const line = verifyKnown(`${hostLabel(ssh)} ${publicKey}\n`, target);
+  await ctx.files.exclusive(known, line);
+  await ctx.files.protect(known);
+  return {
+    state: "verified",
+    trust_source: ssh.trust.source,
+    known_hosts: `.agents/private/state/ssh/${target.name}/known_hosts`,
+  };
+}
+export function sshArguments(target, key, known, command) {
+  const ssh = target.ssh,
+    credential = target.credential;
+  const optionPath = (path) => {
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: reject or remove unsafe control bytes at the public input/output boundary.
+    if (/["\r\n\x00]/.test(path)) fail("invalid_ssh_option_path");
+    return `"${path.replaceAll("\\", "/")}"`;
+  };
+  return [
+    "-F",
+    process.platform === "win32" ? "NUL" : "/dev/null",
+    "-i",
+    key,
+    "-l",
+    ssh.user,
+    "-p",
+    String(ssh.port),
+    "-o",
+    "IdentitiesOnly=yes",
+    "-o",
+    `IdentityAgent=${credential.mode === "agent" ? optionPath(credential.agent_endpoint) : "none"}`,
+    "-o",
+    "BatchMode=yes",
+    "-o",
+    "PasswordAuthentication=no",
+    "-o",
+    "KbdInteractiveAuthentication=no",
+    "-o",
+    "StrictHostKeyChecking=yes",
+    "-o",
+    "GlobalKnownHostsFile=none",
+    "-o",
+    `UserKnownHostsFile=${optionPath(known)}`,
+    "-o",
+    "ConnectTimeout=10",
+    "-o",
+    "ConnectionAttempts=1",
+    "-o",
+    "ForwardAgent=no",
+    "-o",
+    "ClearAllForwardings=yes",
+    "-o",
+    "ControlMaster=no",
+    "-o",
+    "ControlPath=none",
+    ssh.host,
+    command,
+  ];
+}
+export async function sshRead(target, operation, ctx) {
+  const inventory = operation === "vps:ssh:inventory";
+  const script = inventory
+    ? Object.entries(PROBES)
+        .map(
+          ([name, command]) =>
+            `printf '\\nZAIP_BEGIN_${name}\\n'\n( ${command} ) 2>/dev/null\nprintf '\\nZAIP_END_${name}_%s\\n' "$?"`,
+        )
+        .join("\n")
+    : undefined;
+  const { result, identity } = await sshTransport(target, ctx, inventory ? "sh -s" : "true", {
+    input: script,
+    timeout: inventory ? 30000 : 15000,
+    maxOutput: 65536,
+  });
+  if (result.timedOut || result.overflow)
+    fail(result.timedOut ? "ssh_inventory_timeout" : "ssh_inventory_output_limit");
+  if (result.code !== 0) fail("ssh_authentication_or_host_verification_failed");
+  if (!inventory)
+    return { state: "verified", access: "tested", public_fingerprint: identity.public_fingerprint };
+  const fields = {};
+  for (const name of Object.keys(PROBES)) {
+    const match = new RegExp(
+      `(?:^|\\n)ZAIP_BEGIN_${name}\\n([\\s\\S]*?)\\nZAIP_END_${name}_(\\d+)(?:\\n|$)`,
+    ).exec(String(result.stdout));
+    fields[name] =
+      match && match[2] === "0" && match[1].trim()
+        ? { state: "observed", value: sanitize(match[1]) }
+        : { state: "unavailable", reason: "tool_missing_or_insufficient_privilege" };
+  }
+  const observed = {
+    schema_version: 1,
+    source: "ssh",
+    observed_at: ctx.now(),
+    target: target.name,
+    access_binding: hash({ project: ctx.root, ssh: target.ssh, credential: target.credential }),
+    fields,
+    provider: {
+      id: null,
+      plan: null,
+      billing: null,
+      backups: null,
+      reason: "not_observable_via_ssh",
+    },
+  };
+  const locator = await ctx.files.receipt(
+    ["inventory", target.name, observed.observed_at],
+    observed,
+  );
+  return { state: "observed", inventory: locator, fields, provider: observed.provider };
+}
+export async function sshTransport(target, ctx, command, options = {}) {
+  const known = inside(ctx.root, `.agents/private/state/ssh/${target.name}/known_hosts`);
+  await ctx.files.checked(known);
+  const knownText = await ctx.files.readFile(known, "utf8");
+  verifyKnown(knownText, target);
+  const identity = await credentialPath(target, ctx);
+  await recheckIdentity(identity, ctx);
+  await ctx.files.checked(known);
+  if ((await ctx.files.readFile(known, "utf8")) !== knownText)
+    fail("host_identity_changed_after_validation");
+  const result = await ctx.exec("ssh", sshArguments(target, identity.path, known, command), {
+    timeout: 15000,
+    maxOutput: 65536,
+    ...options,
+    env:
+      target.credential.mode === "agent" ? { SSH_AUTH_SOCK: target.credential.agent_endpoint } : {},
+  });
+  return { result, identity };
+}

package/templates/.agents/tools/cloud-onboarding-terraform.mjs

@@ -0,0 +1,80 @@
+import { fail, hash, inside, text } from "./cloud-onboarding-policy.mjs";
+
+/** Local adoption preparation only. No init/import/plan/apply or credential loading. */
+export async function prepareTerraform(target, contract, ctx) {
+  const config = target.terraform;
+  if (
+    !config?.authorization_reference ||
+    !/^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*(?:\["[a-z0-9_-]+"\])?$/.test(config.resource_address ?? "")
+  )
+    fail("terraform_adoption_scope_unavailable");
+  if (
+    !/^\.agents\/private\/state\/cloud\/onboarding\/[a-f0-9]{64}\.json$/.test(
+      config.provider_inventory ?? "",
+    )
+  )
+    fail("terraform_provider_observation_required");
+  const observation = await ctx.files.json(inside(ctx.root, config.provider_inventory));
+  if (
+    hash(observation) !== config.provider_inventory_sha256 ||
+    !observation.observed_at ||
+    observation.source?.version !== "1.66.0" ||
+    observation.account_reference !== target.provider?.account_reference ||
+    observation.id !== target.provider?.vps_id ||
+    !/^\d+$/.test(observation.id ?? "")
+  )
+    fail("terraform_provider_observation_mismatch");
+  if (
+    !/^(?:infra|infrastructure)\/[A-Za-z0-9_/-]+\.tf(?:\.json)?$/.test(config.source_path ?? "") ||
+    /(?:^|[/_-])(?:secret|credential|private|state|plan|env)(?:[/_.-]|$)/i.test(config.source_path)
+  )
+    fail("terraform_source_path_denied");
+  const path = inside(ctx.root, text(config.source_path, 1024));
+  await ctx.files.checked(path);
+  const info = await ctx.files.lstat(path);
+  if (!info.isFile() || info.nlink !== 1 || info.size > 262144)
+    fail("terraform_source_path_denied");
+  if (hash(await ctx.files.readFile(path)) !== config.source_sha256)
+    fail("terraform_source_changed");
+  const planned = contract.architecture?.hosts?.length ?? contract.targets.length;
+  if (
+    !Number.isInteger(config.interpreted_host_count) ||
+    config.interpreted_host_count < 1 ||
+    planned < 1
+  )
+    fail("terraform_topology_interpretation_required");
+  const record = {
+    state: "prepared",
+    source: "local-adoption-preparation",
+    observed_at: ctx.now(),
+    target: target.name,
+    authorization: config.authorization_reference,
+    access_binding: contract.bindings[target.name],
+    resource: {
+      address: config.resource_address,
+      existing_vps_id: observation.id,
+      account_reference: observation.account_reference,
+    },
+    provider_observation: config.provider_inventory,
+    provider_observation_sha256: config.provider_inventory_sha256,
+    code: {
+      path: config.source_path,
+      sha256: config.source_sha256,
+      host_count: config.interpreted_host_count,
+      count_source: "agent_interpretation_of_hash_bound_code",
+    },
+    chosen_host_count: planned,
+    divergence: planned === config.interpreted_host_count ? null : "terraform_adaptation_pending",
+    backend: "requires_independent_verified_configuration_and_locking",
+    import_execution: "unsupported_by_generic_executor",
+    pending: [
+      "Review provider schema and resource address against selected installed provider",
+      "Configure and verify own backend and locking",
+      "Use an import executor supporting the chosen topology before any import",
+    ],
+    remote_operations_executed: false,
+    grants_create_reinstall_apply: false,
+  };
+  const plan = await ctx.files.receipt(["terraform-adoption", target.name, hash(record)], record);
+  return { ...record, adoption_plan: plan };
+}

package/templates/.agents/tools/cloud-onboarding-test-fixture.mjs

@@ -0,0 +1,184 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { after } from "node:test";
+import { runOnboarding } from "./cloud-onboarding.mjs";
+import { binding, CONTRACT, fingerprint, hash } from "./cloud-onboarding-policy.mjs";
+import { PROBES } from "./cloud-onboarding-ssh.mjs";
+
+export const hostKey = `ssh-ed25519 ${Buffer.from("fictional ephemeral host identity").toString("base64")}`;
+export const userKey = `ssh-ed25519 ${Buffer.from("fictional ephemeral user identity").toString("base64")}`;
+export const root = mkdtempSync(resolve(tmpdir(), "zaip-fictional-consumer-"));
+after(() => rmSync(root, { recursive: true, force: true }));
+export function fixture() {
+  const data = new Map(),
+    directories = new Set(),
+    calls = [],
+    reads = [];
+  const target = {
+    name: "primary",
+    purpose: "inventory-existing-vps",
+    ssh: {
+      host: "192.0.2.10",
+      user: "operator",
+      port: 2222,
+      host_fingerprint: fingerprint(hostKey),
+      host_public_key: hostKey,
+      trust: { source: "human-public-confirmation", reference: "public-confirmation-fixture" },
+    },
+    credential: {
+      name: "selected",
+      mode: "external-key",
+      path: resolve(root, "../dedicated keys/selected"),
+      public_fingerprint: fingerprint(userKey),
+    },
+    allowed_operations: [
+      "vps:credential:prepare",
+      "vps:ssh:trust",
+      "vps:ssh:test",
+      "vps:ssh:inventory",
+      "vps:discover",
+      "vps:public-key:register",
+    ],
+  };
+  const contract = {
+    version: 1,
+    profile: "vps-onboarding",
+    project_root: root,
+    authorization: { confirmed: true, reference: "fixture-task", architecture: true },
+    targets: [target],
+  };
+  const save = () => {
+    contract.bindings = { primary: binding(root, target) };
+    data.set(resolve(root, CONTRACT), JSON.stringify(contract));
+  };
+  const absent = () => Object.assign(new Error("not found"), { code: "ENOENT" });
+  let signature = 1;
+  const files = {
+    constants: { COPYFILE_EXCL: 1 },
+    checked: async (path, missing = false) => {
+      if (!data.has(path) && !directories.has(path) && !missing) throw absent();
+      return path;
+    },
+    lstat: async (path) => {
+      if (!data.has(path) && !directories.has(path)) throw absent();
+      return {
+        isFile: () => !directories.has(path),
+        isDirectory: () => directories.has(path),
+        nlink: 1,
+        ino: 1,
+        dev: 1,
+        size: Buffer.byteLength(String(data.get(path))),
+        mtimeMs: signature,
+        ctimeMs: signature,
+      };
+    },
+    readFile: async (path, encoding) => {
+      reads.push(path);
+      if (!data.has(path)) throw absent();
+      return encoding ? String(data.get(path)) : Buffer.from(data.get(path));
+    },
+    json: async (path) => {
+      if (!data.has(path)) throw absent();
+      return JSON.parse(data.get(path));
+    },
+    protect: async (path) => {
+      calls.push(["protect", path]);
+    },
+    verifyPermissions: async (path) => {
+      calls.push(["verifyPermissions", path]);
+    },
+    localDirectory: async (path) => {
+      calls.push(["localDirectory", path]);
+    },
+    untracked: async () => {},
+    exclusive: async (path, content) => {
+      if (data.has(path) && String(data.get(path)) !== String(content))
+        throw Object.assign(new Error("existing_file_conflict"), {
+          code: "existing_file_conflict",
+        });
+      const created = !data.has(path);
+      data.set(path, content);
+      return created;
+    },
+    copyFile: async (a, b) => {
+      if (data.has(b)) throw Error("overwrite");
+      data.set(b, data.get(a));
+    },
+    mkdir: async (path) => {
+      directories.add(path);
+    },
+    rename: async (a, b) => {
+      data.set(b, data.get(a));
+      data.delete(a);
+    },
+    readdir: async (path) =>
+      [...data.keys()]
+        .filter((key) => resolve(key, "..") === path)
+        .map((key) => key.slice(path.length + 1)),
+    lock: async (_, work) => work(),
+    replace: async (path, content, expected) => {
+      if (hash(data.get(path)) !== expected) throw Error("concurrent_file_change");
+      data.set(path, content);
+    },
+    receipt: async (name, value) => {
+      const path = `.agents/private/state/cloud/onboarding/${hash(name)}.json`;
+      data.set(resolve(root, path), JSON.stringify(value));
+      return path;
+    },
+  };
+  const exec = async (file, args, options = {}) => {
+    calls.push([file, args, options]);
+    if (file === "ssh-keygen")
+      return args.includes("-y")
+        ? { code: 255, stderr: "incorrect passphrase" }
+        : { code: 0, stdout: `256 ${fingerprint(userKey)} selected (ED25519)` };
+    if (file === "ssh-add")
+      return {
+        code: 0,
+        stdout: `256 ${fingerprint(userKey)} selected\n256 SHA256:${"Z".repeat(43)} other`,
+      };
+    if (file === "ssh-keyscan") return { code: 0, stdout: `[${target.ssh.host}]:2222 ${hostKey}` };
+    if (file === "ssh")
+      return {
+        code: 0,
+        stdout: Object.keys(PROBES)
+          .map((name) => `\nZAIP_BEGIN_${name}\nfictional-${name}\nZAIP_END_${name}_0\n`)
+          .join(""),
+      };
+    return { code: 0, stdout: "" };
+  };
+  const ctx = {
+    root,
+    files,
+    exec,
+    now: () => "2026-10-15T00:00:00Z",
+    authorization: "fixture-task",
+  };
+  data.set(target.credential.path, "encrypted-ephemeral-fixture-bytes");
+  data.set(`${target.credential.path}.pub`, userKey);
+  save();
+  const invoke = (operation, extra = {}) =>
+    runOnboarding(
+      {
+        operation,
+        contract: CONTRACT,
+        target: target.name,
+        binding: binding(root, target),
+        ...extra,
+      },
+      ctx,
+    );
+  return {
+    data,
+    calls,
+    reads,
+    target,
+    contract,
+    save,
+    files,
+    ctx,
+    invoke,
+    changeIdentity: () => signature++,
+  };
+}

package/templates/.agents/tools/cloud-onboarding-test-fixtures.mjs

@@ -0,0 +1,117 @@
+import { createServer as createAgentServer } from "node:net";
+
+const uint32 = (value) => {
+  const b = Buffer.alloc(4);
+  b.writeUInt32BE(value);
+  return b;
+};
+const string = (value) => {
+  const b = Buffer.from(value);
+  return Buffer.concat([uint32(b.length), b]);
+};
+function readString(buffer, offset) {
+  const n = buffer.readUInt32BE(offset);
+  return [buffer.subarray(offset + 4, offset + 4 + n), offset + 4 + n];
+}
+
+export function ownedListener(accept) {
+  const sockets = new Set();
+  const server = createAgentServer((socket) => {
+    sockets.add(socket);
+    socket.on("close", () => sockets.delete(socket));
+    socket.on("error", () => {});
+    accept(socket);
+  });
+  return { server, sockets, controller: new AbortController() };
+}
+export async function boundedFixture(phase, operation, timeoutMs = 5000) {
+  let timer;
+  try {
+    return await Promise.race([
+      operation(),
+      new Promise((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`fixture ${phase} exceeded ${timeoutMs}ms`)),
+          timeoutMs,
+        );
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+export async function listenFixture(listener, address, timeoutMs = 5000) {
+  try {
+    await boundedFixture(
+      "listen",
+      () =>
+        new Promise((done, reject) => {
+          listener.server.once("error", reject);
+          listener.server.listen({ ...address, signal: listener.controller.signal }, () => {
+            listener.server.removeListener("error", reject);
+            done();
+          });
+        }),
+      timeoutMs,
+    );
+  } catch (error) {
+    listener.controller.abort();
+    for (const socket of listener.sockets) socket.destroy();
+    throw error;
+  }
+}
+export async function closeFixture(listener, phase) {
+  if (!listener) return;
+  for (const socket of listener.sockets) socket.destroy();
+  if (!listener.server.listening) {
+    listener.controller.abort();
+    return;
+  }
+  await boundedFixture(
+    phase,
+    () =>
+      new Promise((done, reject) => {
+        listener.server.once("error", reject);
+        listener.server.once("close", () => {
+          listener.server.removeListener("error", reject);
+          done();
+        });
+        listener.controller.abort();
+      }),
+  );
+}
+
+// Ephemeral agent implements the real OpenSSH agent wire protocol, with two fixture identities.
+export function agentFixture(keys) {
+  const listener = ownedListener((socket) => {
+    let pending = Buffer.alloc(0);
+    socket.on("error", () => {});
+    socket.on("data", (data) => {
+      pending = Buffer.concat([pending, data]);
+      while (pending.length >= 4 && pending.length >= 4 + pending.readUInt32BE(0)) {
+        const length = pending.readUInt32BE(0),
+          body = pending.subarray(4, 4 + length);
+        pending = pending.subarray(4 + length);
+        let response = Buffer.from([5]);
+        if (body[0] === 11)
+          response = Buffer.concat([
+            Buffer.from([12]),
+            uint32(keys.length),
+            ...keys.flatMap((key) => [string(key.getPublicSSH()), string("ephemeral-fixture")]),
+          ]);
+        if (body[0] === 13) {
+          const [publicKey, at] = readString(body, 1),
+            [payload] = readString(body, at);
+          const key = keys.find((k) => k.getPublicSSH().equals(publicKey));
+          if (key)
+            response = Buffer.concat([
+              Buffer.from([14]),
+              string(Buffer.concat([string("ssh-ed25519"), string(key.sign(payload))])),
+            ]);
+        }
+        socket.write(Buffer.concat([uint32(response.length), response]));
+      }
+    });
+  });
+  return listener;
+}