@lifeaitools/clauth 1.31.1 → 2.0.1

package/cli/ops/deployment-adapter.js

@@ -0,0 +1,63 @@
+import { execFile as execFileCallback } from "node:child_process";
+
+function execFile(command, args, options) {
+  return new Promise((resolve, reject) => execFileCallback(command, args, { ...options, windowsHide: true }, (error, stdout, stderr) => {
+    if (error) return reject(new Error(`${command} ${args.join(" ")}: ${String(stderr || error.message).trim()}`));
+    resolve({ stdout: String(stdout || "").trim(), stderr: String(stderr || "").trim() });
+  }));
+}
+
+function requireString(value, name) {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${name} is required`);
+  return value.trim();
+}
+
+function validateApplication(config) {
+  if (!config || typeof config !== "object") throw new Error("deployment_not_registered");
+  requireString(config.repo_path, "deployment.repo_path");
+  requireString(config.pm2_name, "deployment.pm2_name");
+  if (!Array.isArray(config.build) || !config.build.every((value) => typeof value === "string" && value)) throw new Error("deployment.build must be a non-empty argv array");
+  if (!Array.isArray(config.allowed_refs) || !config.allowed_refs.every((value) => typeof value === "string" && value)) throw new Error("deployment.allowed_refs must be a string array");
+  if (!requireString(config.health_url, "deployment.health_url").startsWith("http")) throw new Error("deployment.health_url must be HTTP(S)");
+}
+
+export function parseDeploymentRegistry(raw = "{}") {
+  const parsed = typeof raw === "string" ? JSON.parse(raw) : raw;
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("CLAUTH_OPS_DEPLOYMENTS must be a JSON object");
+  for (const config of Object.values(parsed)) validateApplication(config);
+  return parsed;
+}
+
+export function createDeploymentAdapter({ deployments, run = execFile, fetch = globalThis.fetch, delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), reload }) {
+  if (typeof reload !== "function") throw new Error("reload callback is required");
+  return {
+    async deploy({ application, ref }) {
+      const name = requireString(application, "application");
+      const config = deployments[name];
+      validateApplication(config);
+      const requestedRef = requireString(ref || config.default_ref, "ref");
+      if (!config.allowed_refs.includes(requestedRef)) throw new Error("deployment_ref_not_allowed");
+      const cwd = config.repo_path;
+      const steps = [];
+      await run("git", ["fetch", "origin", requestedRef], { cwd });
+      steps.push("fetched");
+      const sha = (await run("git", ["rev-parse", "FETCH_HEAD"], { cwd })).stdout;
+      if (!/^[0-9a-f]{7,64}$/i.test(sha)) throw new Error("deployment_invalid_git_sha");
+      await run("git", ["checkout", "--detach", sha], { cwd });
+      steps.push("checked_out");
+      await run(config.build[0], config.build.slice(1), { cwd });
+      steps.push("built");
+      await reload(config.pm2_name);
+      steps.push("reloaded");
+      const attempts = Number(config.health_attempts || 30);
+      for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        try {
+          const response = await fetch(config.health_url, { signal: AbortSignal.timeout(Number(config.health_timeout_ms || 5000)) });
+          if (response.ok) return { application: name, ref: requestedRef, sha, health_url: config.health_url, attempts: attempt, steps };
+        } catch {}
+        await delay(Number(config.health_delay_ms || 1000));
+      }
+      throw new Error("deployment_health_check_timed_out");
+    },
+  };
+}

package/cli/ops/job-store.js

@@ -0,0 +1,116 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+const TERMINAL = new Set(["succeeded", "failed", "timed_out", "rejected"]);
+
+export function createJobStore({ now = () => new Date().toISOString(), maxJobs = 500, filePath = null } = {}) {
+  const { jobs, recovered } = load(filePath, maxJobs, now);
+  const subscribers = new Map();
+  const persist = () => {
+    if (!filePath) return;
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify({ schema: "clauth.ops.jobs.v1", jobs: [...jobs.values()].map(snapshot) }), { mode: 0o600 });
+    fs.renameSync(tmp, filePath);
+  };
+  if (recovered) persist();
+  const publish = (id) => {
+    const value = get(id);
+    for (const listener of subscribers.get(id) || []) listener(value);
+  };
+  const create = ({ kind, operation, target = null }) => {
+    const id = crypto.randomUUID();
+    const job = { id, kind, operation, target, phase: "queued", created_at: now(), updated_at: now(), events: [] };
+    jobs.set(id, job);
+    event(id, "queued");
+    while (jobs.size > maxJobs) jobs.delete(jobs.keys().next().value);
+    persist();
+    return snapshot(job);
+  };
+  const event = (id, phase, detail = null) => {
+    const job = jobs.get(id);
+    if (!job) return null;
+    if (TERMINAL.has(job.phase)) throw new Error(`job already terminal: ${job.phase}`);
+    job.phase = phase;
+    job.updated_at = now();
+    job.events.push({ phase, at: job.updated_at, detail: detail == null ? null : sanitize(detail) });
+    persist();
+    publish(id);
+    return snapshot(job);
+  };
+  const get = (id) => jobs.has(id) ? snapshot(jobs.get(id)) : null;
+  const subscribe = (id, listener) => {
+    if (!jobs.has(id)) return null;
+    const listeners = subscribers.get(id) || new Set();
+    subscribers.set(id, listeners);
+    listeners.add(listener);
+    listener(get(id));
+    return () => {
+      listeners.delete(listener);
+      if (!listeners.size) subscribers.delete(id);
+    };
+  };
+  return { create, event, get, subscribe };
+}
+
+function load(filePath, maxJobs, now) {
+  if (!filePath || !fs.existsSync(filePath)) return { jobs: new Map(), recovered: false };
+  try {
+    const stored = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    const values = Array.isArray(stored?.jobs) ? stored.jobs.slice(-maxJobs) : [];
+    let recovered = false;
+    const restored = values.filter((job) => job && typeof job.id === "string").map((job) => {
+      const safe = snapshot(job);
+      if (!TERMINAL.has(safe.phase)) {
+        recovered = true;
+        safe.phase = "failed";
+        safe.updated_at = now();
+        safe.events.push({ phase: "failed", at: safe.updated_at, detail: { code: "daemon_restarted" } });
+      }
+      return [safe.id, safe];
+    });
+    return { jobs: new Map(restored), recovered };
+  } catch {
+    return { jobs: new Map(), recovered: false };
+  }
+}
+
+function sanitize(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  // `error` is deliberately NOT allowlisted. Free-form error strings are the
+  // classic credential-leak path -- an upstream message like
+  // `API_KEY=... rejected` would be persisted verbatim to disk and served over
+  // the API. ops-job-store.test.mjs pins this behaviour with an explicit
+  // API_KEY=hidden payload; do not "fix" a missing failure reason by adding
+  // `error` here.
+  //
+  // Producers that need a machine-readable failure reason must emit `code` with
+  // an enumerated value (see submitPromotionJob's coolify_* codes). That keeps
+  // diagnosis available without letting arbitrary upstream text through.
+  const allowed = new Set(["code", "checkout_sha", "ref", "pm2_name", "health_url", "health_status", "deployment_uuid", "status", "processes"]);
+  return Object.fromEntries(Object.entries(value).flatMap(([key, entry]) => {
+    if (!allowed.has(key)) return [];
+    if (key === "processes" && Array.isArray(entry)) {
+      return [[key, entry.filter((process) => process && typeof process === "object").map((process) => ({
+        name: typeof process.name === "string" ? process.name : null,
+        pm_id: typeof process.pm_id === "number" ? process.pm_id : null,
+        pid: typeof process.pid === "number" ? process.pid : null,
+        status: typeof process.status === "string" ? process.status : null,
+        namespace: typeof process.namespace === "string" ? process.namespace : null,
+      }))]];
+    }
+    return (typeof entry === "string" || typeof entry === "number" || typeof entry === "boolean" || entry === null) ? [[key, entry]] : [];
+  }));
+}
+
+function snapshot(job) {
+  return JSON.parse(JSON.stringify({
+    ...job,
+    events: job.events.map((event) => ({
+      phase: event.phase,
+      at: event.at,
+      detail: sanitize(event.detail),
+    })),
+  }));
+}

package/cli/ops/operation-policy.js

@@ -0,0 +1,51 @@
+import { PM2_OPERATION_CATALOG, isReadOperation } from "./pm2-adapter.js";
+
+function configuredProfile(config, role) {
+  if (config?.[role] && typeof config[role] === "object" && !Array.isArray(config[role])) return config[role];
+  return config && typeof config === "object" && !Array.isArray(config) ? config : {};
+}
+
+function targetFrom(input = {}) {
+  const value = input.target || input.name || input.options?.name || (Array.isArray(input.args) ? input.args[0] : null);
+  return value == null ? null : String(value);
+}
+
+function enabled(enabled, operation) {
+  return enabled.has(operation) || enabled.has("*");
+}
+
+export function createOperationPolicy({ enabled: agentEnabled = [], applications = {}, adminEnabled = [], adminApplications = {}, allowHostWide = false } = {}) {
+  const agentEnabledSet = new Set(agentEnabled);
+  const adminEnabledSet = new Set(adminEnabled);
+  return {
+    authorize(operation, input = {}, role = "agent") {
+      if (!PM2_OPERATION_CATALOG[operation]) return { ok: false, code: "service_not_available" };
+      const isAdmin = role === "admin";
+      const profile = configuredProfile(isAdmin ? adminApplications : applications, role);
+      const allowed = Array.isArray(profile[operation])
+        ? profile[operation].filter((target) => typeof target === "string" && target.length > 0)
+        : [];
+      const target = targetFrom(input);
+      const hostWide = operation === "kill_daemon" || operation === "pm2_killDaemon" || target === "all";
+
+      // The public catalog remains complete. Only the remote admin capability
+      // may execute raw PM2 calls or host-level lifecycle actions, and every
+      // one still has to be enabled and allowlisted in Vultr configuration.
+      if (!isAdmin && (operation.startsWith("pm2_") || ["start", "dump", "resurrect", "kill_daemon", "startup", "unstartup", "update", "deep_update"].includes(operation))) {
+        return { ok: false, code: "service_not_available" };
+      }
+      if (hostWide && (!isAdmin || !allowHostWide)) return { ok: false, code: "service_not_available" };
+      if (!isReadOperation(operation) && !enabled(isAdmin ? adminEnabledSet : agentEnabledSet, operation)) {
+        return { ok: false, code: "service_not_available" };
+      }
+      if (!allowed.length) return { ok: false, code: "service_not_available" };
+      if (hostWide) {
+        if (!allowed.includes("*") && !allowed.includes("all")) return { ok: false, code: "service_not_available" };
+        return { ok: true, mode: isReadOperation(operation) ? "read" : "mutate", allowed_targets: allowed };
+      }
+      if (operation === "list" || operation === "ping") return { ok: true, mode: isReadOperation(operation) ? "read" : "mutate", allowed_targets: allowed };
+      if (!target || (!allowed.includes("*") && !allowed.includes(target))) return { ok: false, code: "service_not_available" };
+      return { ok: true, mode: isReadOperation(operation) ? "read" : "mutate", allowed_targets: allowed };
+    },
+  };
+}

package/cli/ops/pm2-adapter.js

@@ -0,0 +1,128 @@
+const READ_OPERATIONS = new Set(["list", "describe", "ping", "logs", "bus", "pm2_list", "pm2_describe", "pm2_ping", "pm2_get", "pm2_getPID", "pm2_getVersion", "pm2_inspect", "pm2_jlist", "pm2_slist", "pm2_monitorState"]);
+
+// Derived from PM2 v7's public API prototype. We intentionally expose every
+// method through a stable prefixed operation name; potentially destructive or
+// interactive methods stay policy-disabled unless an operator explicitly opts in.
+export const PM2_PUBLIC_METHODS = Object.freeze([
+  "agentInfos", "attach", "autodump", "autoinstall", "backward", "boilerplate", "clearDump", "clearSetup", "close", "conf", "connect", "dashboard", "deepUpdate", "delete", "deleteModule", "deploy", "describe", "destroy", "disconnect", "dockerMode", "dump", "env", "exitCli", "flush", "forward", "generateDockerfile", "generateModuleSample", "generateSample", "get", "getPID", "getProcessIdByName", "getVersion", "inspect", "install", "jlist", "kill", "killAgent", "killDaemon", "launchAll", "launchBus", "launchModules", "launchSysMonitoring", "link", "linkManagement", "list", "logrotate", "minimumSetup", "monit", "monitorState", "msgProcess", "multiset", "openDashboard", "package", "ping", "printLogs", "profile", "publish", "pullAndReload", "pullAndRestart", "pullCommitId", "reload", "reloadLogs", "remote", "remoteV2", "report", "reset", "restart", "resurrect", "scale", "sendDataToProcessId", "sendLineToStdin", "sendSignalToProcessId", "sendSignalToProcessName", "serve", "set", "slist", "speedList", "start", "startup", "stop", "streamLogs", "trigger", "uninstall", "uninstallStartup", "unlink", "unset", "update",
+]);
+
+const CORE_OPERATIONS = {
+  list: { mode: "read", args: [] },
+  describe: { mode: "read", args: ["target"] },
+  ping: { mode: "read", args: [] },
+  logs: { mode: "read", args: ["target"] },
+  bus: { mode: "read", args: [] },
+  start: { mode: "mutate", args: ["script", "options"] },
+  stop: { mode: "mutate", args: ["target"] },
+  restart: { mode: "mutate", args: ["target", "options"] },
+  reload: { mode: "mutate", args: ["target", "options"] },
+  delete: { mode: "mutate", args: ["target"] },
+  scale: { mode: "mutate", args: ["target", "instances"] },
+  reset: { mode: "mutate", args: ["target"] },
+  dump: { mode: "mutate", args: [] },
+  resurrect: { mode: "mutate", args: [] },
+  kill_daemon: { mode: "mutate", args: [] },
+  startup: { mode: "mutate", args: ["platform", "options"] },
+  unstartup: { mode: "mutate", args: ["platform"] },
+  update: { mode: "mutate", args: [] },
+  deep_update: { mode: "mutate", args: [] },
+  send_data: { mode: "mutate", args: ["target", "packet"] },
+  send_signal: { mode: "mutate", args: ["target", "signal"] },
+  trigger: { mode: "mutate", args: ["target", "action", "params"] },
+};
+
+export const PM2_OPERATION_CATALOG = Object.freeze({
+  ...CORE_OPERATIONS,
+  ...Object.fromEntries(PM2_PUBLIC_METHODS.map((method) => [`pm2_${method}`, {
+    mode: READ_OPERATIONS.has(`pm2_${method}`) ? "read" : "mutate",
+    args: ["args"],
+    pm2_method: method,
+  }])),
+});
+
+function missing(value, name) {
+  if (value === undefined || value === null || value === "") throw new Error(`${name} is required`);
+  return value;
+}
+
+function callbackCall(pm2, method, args = []) {
+  return new Promise((resolve, reject) => {
+    if (typeof pm2?.[method] !== "function") return reject(new Error(`PM2 method unavailable: ${method}`));
+    pm2[method](...args, (error, result) => error ? reject(error) : resolve(result));
+  });
+}
+
+function normalizeProcess(process) {
+  if (!process || typeof process !== "object") return process;
+  return {
+    name: process.name || process.pm2_env?.name || null,
+    pm_id: process.pm_id ?? process.pm2_env?.pm_id ?? null,
+    pid: process.pid ?? null,
+    status: process.pm2_env?.status ?? process.status ?? null,
+    restart_time: process.pm2_env?.restart_time ?? null,
+    created_at: process.pm2_env?.created_at ?? null,
+    cwd: process.pm2_env?.pm_cwd ?? null,
+    script: process.pm2_env?.pm_exec_path ?? null,
+    namespace: process.pm2_env?.namespace ?? null,
+  };
+}
+
+function normalizeProcessResult(result) {
+  // PM2's lower-level aliases (jlist, inspect, get) can return the same rich
+  // process object as list/describe. Normalize it at the adapter boundary so a
+  // future caller cannot accidentally serialize pm2_env or other credentials.
+  if (Array.isArray(result)) {
+    return result.map((item) => item && typeof item === "object" && (item.pm2_env || "pm_id" in item || "pid" in item)
+      ? normalizeProcess(item)
+      : item);
+  }
+  if (result && typeof result === "object" && (result.pm2_env || "pm_id" in result || "pid" in result)) return normalizeProcess(result);
+  return result;
+}
+
+export function createPm2Adapter(pm2) {
+  if (!pm2) throw new Error("pm2 facade is required");
+  return {
+    catalog() { return PM2_OPERATION_CATALOG; },
+    async connect() { await callbackCall(pm2, "connect", [false]); return { connected: true }; },
+    async disconnect() { await callbackCall(pm2, "disconnect"); return { connected: false }; },
+    async execute(operation, input = {}) {
+      if (!PM2_OPERATION_CATALOG[operation]) throw new Error(`unknown PM2 operation: ${operation}`);
+      if (operation.startsWith("pm2_")) {
+        const method = PM2_OPERATION_CATALOG[operation].pm2_method;
+        const args = Array.isArray(input.args) ? input.args : [];
+        return normalizeProcessResult(await callbackCall(pm2, method, args));
+      }
+      switch (operation) {
+        case "list": return (await callbackCall(pm2, "list")).map(normalizeProcess);
+        case "describe": return (await callbackCall(pm2, "describe", [missing(input.target, "target")])).map(normalizeProcess);
+        case "ping": return { connected: true, processes: (await callbackCall(pm2, "list")).length };
+        case "logs": return (await callbackCall(pm2, "describe", [missing(input.target, "target")])).map(normalizeProcess);
+        case "bus": return callbackCall(pm2, "launchBus");
+        case "start": return callbackCall(pm2, "start", [missing(input.script, "script"), input.options || {}]);
+        case "stop": return callbackCall(pm2, "stop", [missing(input.target, "target")]);
+        case "restart": return callbackCall(pm2, "restart", [missing(input.target, "target"), input.options || {}]);
+        case "reload": return callbackCall(pm2, "reload", [missing(input.target, "target"), input.options || {}]);
+        case "delete": return callbackCall(pm2, "delete", [missing(input.target, "target")]);
+        case "scale": return callbackCall(pm2, "scale", [missing(input.target, "target"), missing(input.instances, "instances")]);
+        case "reset": return callbackCall(pm2, "reset", [missing(input.target, "target")]);
+        case "dump": return callbackCall(pm2, "dump");
+        case "resurrect": return callbackCall(pm2, "resurrect");
+        case "kill_daemon": return callbackCall(pm2, "killDaemon");
+        case "startup": return callbackCall(pm2, "startup", [input.platform, input.options || {}]);
+        case "unstartup": return callbackCall(pm2, "uninstallStartup", [input.platform]);
+        case "update": return callbackCall(pm2, "update");
+        case "deep_update": return callbackCall(pm2, "deepUpdate");
+        case "send_data": return callbackCall(pm2, "sendDataToProcessId", [missing(input.target, "target"), missing(input.packet, "packet")]);
+        case "send_signal": return callbackCall(pm2, "sendSignalToProcessName", [missing(input.target, "target"), input.signal || "SIGINT"]);
+        case "trigger": return callbackCall(pm2, "trigger", [missing(input.target, "target"), missing(input.action, "action"), input.params || {}]);
+        default: throw new Error(`unimplemented PM2 operation: ${operation}`);
+      }
+    },
+  };
+}
+
+export function isReadOperation(operation) {
+  return READ_OPERATIONS.has(operation);
+}

package/cli/ops/serialized-executor.js

@@ -0,0 +1,9 @@
+export function createSerializedExecutor() {
+  let tail = Promise.resolve();
+  return function execute(task) {
+    if (typeof task !== "function") throw new Error("task must be a function");
+    const run = tail.then(task, task);
+    tail = run.catch(() => {});
+    return run;
+  };
+}