@lifeaitools/clauth 1.31.1 → 2.0.1

package/cli/commands/ops-install.js

@@ -0,0 +1,211 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import pm2 from "pm2";
+
+const DEFAULT_PORT = 52439;
+const DEFAULT_NAME = "clauth-deployment";
+const INSTALLER_MARKER = "clauth.ops.install.v1";
+const OPS_ENV_KEYS = new Set([
+  "CLAUTH_OPS_INSTALLER_MARKER", "CLAUTH_OPS_ENABLED", "CLAUTH_OPS_APPLICATIONS", "CLAUTH_OPS_ADMIN_ENABLED",
+  "CLAUTH_OPS_ADMIN_APPLICATIONS", "CLAUTH_OPS_ALLOW_HOST_WIDE", "CLAUTH_OPS_DEPLOYMENTS", "CLAUTH_COOLIFY_PROMOTE_UUIDS",
+]);
+const RUNTIME_ENV_KEYS = new Set(["PATH", "Path", "HOME", "USERPROFILE", "APPDATA", "LOCALAPPDATA", "SystemRoot", "SYSTEMROOT", "ComSpec", "TMP", "TEMP"]);
+const RESTORABLE_PM2_KEYS = ["node_args", "exec_mode", "instances", "namespace", "watch", "kill_retry_time", "merge_logs", "windowsHide", "stop_exit_codes"];
+
+function requiredString(value, label) {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${label} is required`);
+  return value.trim();
+}
+
+function stringList(value, label) {
+  if (value == null) return [];
+  if (!Array.isArray(value) || !value.every((item) => typeof item === "string" && item.trim())) throw new Error(`${label} must be an array of non-empty strings`);
+  return value.map((item) => item.trim());
+}
+
+function applicationPolicy(value, label) {
+  if (value == null) return {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
+  return Object.fromEntries(Object.entries(value).map(([operation, targets]) => [operation, stringList(targets, `${label}.${operation}`)]));
+}
+
+/**
+ * An operation is only usable when it ALSO has a target allowlist.
+ *
+ * `createOperationPolicy` reads the allowlist from `applications[operation]` and
+ * rejects with `service_not_available` when it is empty (operation-policy.js,
+ * the `!allowed.length` guard). That code reads like the service is down, but
+ * it actually means "no targets configured" — so a config carrying only
+ * `agent_enabled` installs cleanly, passes the health and bearer-gate probes,
+ * and then rejects every authenticated call. That exact combination shipped to
+ * the canary and was misdiagnosed for a day as a missing credential.
+ *
+ * Read operations (`list`, `describe`, `ping`, `logs`, …) are affected too: the
+ * `!allowed.length` guard runs before the read/mutate distinction, so a read op
+ * with no allowlist is rejected just the same.
+ *
+ * Fail at install instead, naming the operations that would silently break.
+ */
+function assertEnabledOperationsHaveTargets(enabled, applications, label) {
+  const missing = enabled.filter((operation) => !(applications[operation] || []).length);
+  if (!missing.length) return;
+  const applicationsLabel = label.replace("_enabled", "_applications");
+  throw new Error(
+    `${label}: ${missing.join(", ")} enabled but absent from ${applicationsLabel}. An enabled operation with no target allowlist is rejected at runtime with service_not_available. Add a target list (e.g. {"${missing[0]}": ["*"]}) or remove it from the enabled list.`,
+  );
+}
+
+export function loadOpsInstallConfig(configPath) {
+  const raw = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("ops installer config must be a JSON object");
+  const port = raw.port == null ? DEFAULT_PORT : Number(raw.port);
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error("port must be an integer from 1024 through 65535");
+  const pm2Name = raw.pm2_name == null ? DEFAULT_NAME : requiredString(raw.pm2_name, "pm2_name");
+  const operations = raw.operations && typeof raw.operations === "object" && !Array.isArray(raw.operations) ? raw.operations : {};
+
+  const enabled = stringList(operations.agent_enabled, "operations.agent_enabled");
+  const applications = applicationPolicy(operations.agent_applications, "operations.agent_applications");
+  const adminEnabled = stringList(operations.admin_enabled, "operations.admin_enabled");
+  const adminApplications = applicationPolicy(operations.admin_applications, "operations.admin_applications");
+
+  assertEnabledOperationsHaveTargets(enabled, applications, "operations.agent_enabled");
+  assertEnabledOperationsHaveTargets(adminEnabled, adminApplications, "operations.admin_enabled");
+
+  return {
+    port,
+    pm2Name,
+    enabled,
+    applications,
+    adminEnabled,
+    adminApplications,
+    allowHostWide: operations.allow_host_wide === true,
+    deployments: raw.deployments && typeof raw.deployments === "object" && !Array.isArray(raw.deployments) ? raw.deployments : {},
+    coolifyPromoteUuids: stringList(raw.coolify_promote_uuids, "coolify_promote_uuids"),
+  };
+}
+
+export function buildOpsServiceSpec({ config, rootDir }) {
+  const cli = path.join(rootDir, "cli", "index.js");
+  const runtimeEnv = Object.fromEntries([...RUNTIME_ENV_KEYS].flatMap((key) => process.env[key] == null ? [] : [[key, process.env[key]]]));
+  return {
+    name: config.pm2Name,
+    script: cli,
+    args: `serve foreground --port ${config.port} --isolated`,
+    cwd: rootDir,
+    autorestart: true,
+    restart_delay: 1000,
+    max_restarts: 20,
+    // Do not inherit the invoking agent or shell environment: PM2 otherwise
+    // stores every inherited value in its process metadata.
+    // PM2 only activates filtering for a non-empty array.  Exclude every
+    // inherited key, then explicitly add the small runtime allowlist above.
+    filter_env: Object.keys(process.env),
+    env: {
+      ...runtimeEnv,
+      CLAUTH_OPS_INSTALLER_MARKER: INSTALLER_MARKER,
+      CLAUTH_OPS_ENABLED: [...config.enabled, ...(Object.keys(config.deployments).length ? ["deploy"] : []), ...(config.coolifyPromoteUuids.length ? ["coolify_promote"] : [])].join(","),
+      CLAUTH_OPS_APPLICATIONS: JSON.stringify(config.applications),
+      CLAUTH_OPS_ADMIN_ENABLED: config.adminEnabled.join(","),
+      CLAUTH_OPS_ADMIN_APPLICATIONS: JSON.stringify(config.adminApplications),
+      CLAUTH_OPS_ALLOW_HOST_WIDE: config.allowHostWide ? "1" : "0",
+      CLAUTH_OPS_DEPLOYMENTS: JSON.stringify(config.deployments),
+      CLAUTH_COOLIFY_PROMOTE_UUIDS: JSON.stringify(config.coolifyPromoteUuids),
+    },
+  };
+}
+
+function pm2Call(method, ...args) {
+  return new Promise((resolve, reject) => pm2[method](...args, (error, value) => error ? reject(error) : resolve(value)));
+}
+
+async function probe(endpoint) {
+  const health = await fetch(`${endpoint}/health`, { signal: AbortSignal.timeout(5000) });
+  const healthBody = health.ok ? await health.json() : null;
+  if (healthBody?.status !== "ok") throw new Error(`health probe failed at ${endpoint}`);
+  const catalog = await fetch(`${endpoint}/v1/ops/catalog`, { signal: AbortSignal.timeout(5000) });
+  if (catalog.status !== 401) throw new Error(`bearer gate probe failed: expected HTTP 401, received ${catalog.status}`);
+  return { health_status: health.status, bearer_gate_status: catalog.status, listening_port: healthBody.listening_port, process_id: healthBody.process_id };
+}
+
+function argsFor(entry) {
+  const value = entry?.pm2_env?.args ?? entry?.args ?? "";
+  return Array.isArray(value) ? value.join(" ") : String(value || "");
+}
+
+function ownedService(entry, spec) {
+  const env = entry?.pm2_env || {};
+  return env.CLAUTH_OPS_INSTALLER_MARKER === INSTALLER_MARKER
+    && path.resolve(env.pm_exec_path || "") === path.resolve(spec.script)
+    && path.resolve(env.pm_cwd || "") === path.resolve(spec.cwd)
+    && argsFor(entry) === spec.args;
+}
+
+export function previousSpec(entry) {
+  const env = entry.pm2_env || {};
+  const restored = {
+    name: env.name,
+    script: env.pm_exec_path,
+    args: argsFor(entry),
+    cwd: env.pm_cwd,
+    autorestart: env.autorestart !== false,
+    restart_delay: env.restart_delay || 1000,
+    max_restarts: env.max_restarts || 20,
+    filter_env: Object.keys(process.env),
+    env: Object.fromEntries(Object.entries(env).filter(([key]) => OPS_ENV_KEYS.has(key) || RUNTIME_ENV_KEYS.has(key))),
+  };
+  if (env.exec_interpreter !== undefined) restored.interpreter = env.exec_interpreter;
+  for (const key of RESTORABLE_PM2_KEYS) if (env[key] !== undefined) restored[key] = env[key];
+  return restored;
+}
+
+async function rollback(previous, name) {
+  try { await pm2Call("delete", name); } catch {}
+  if (previous) await pm2Call("start", previous);
+}
+
+export async function runOpsInstall(opts = {}) {
+  const configPath = path.resolve(requiredString(opts.config, "--config"));
+  const config = loadOpsInstallConfig(configPath);
+  const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+  const spec = buildOpsServiceSpec({ config, rootDir });
+  const endpoint = `http://127.0.0.1:${config.port}`;
+  if (opts.dryRun) {
+    process.stdout.write(`${JSON.stringify({ action: "install", dry_run: true, platform: process.platform, endpoint, pm2_name: config.pm2Name, policy_file: configPath, operations: Object.keys(config.applications).sort() }, null, 2)}\n`);
+    return;
+  }
+  await new Promise((resolve, reject) => pm2.connect(false, (error) => error ? reject(error) : resolve()));
+  let result;
+  let previous = null;
+  try {
+    const existing = (await pm2Call("list")).find((entry) => (entry.name || entry.pm2_env?.name) === config.pm2Name);
+    // PM2 rejects an inline `env` object on restart-by-name.  Replacing only
+    // this dedicated control-plane process is the supported way to apply a
+    // changed server policy without touching any managed application.
+    if (existing && !ownedService(existing, spec)) throw new Error(`refusing to replace non-installer PM2 process: ${config.pm2Name}`);
+    previous = existing ? previousSpec(existing) : null;
+    if (existing) await pm2Call("delete", config.pm2Name);
+    await pm2Call("start", spec);
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+      try {
+        result = await probe(endpoint);
+        const current = (await pm2Call("list")).find((entry) => (entry.name || entry.pm2_env?.name) === config.pm2Name);
+        const pid = current?.pid ?? current?.pm2_env?.pm_pid;
+        const status = current?.pm2_env?.status ?? current?.status;
+        if (status !== "online" || !Number.isInteger(pid) || result.process_id !== pid || result.listening_port !== config.port) {
+          throw new Error("new PM2 process does not own the verified control-plane endpoint");
+        }
+        break;
+      } catch (error) {
+        if (attempt === 19) throw error;
+        await new Promise((resolve) => setTimeout(resolve, 250));
+      }
+    }
+  } catch (error) {
+    await rollback(previous, config.pm2Name);
+    throw error;
+  } finally {
+    await new Promise((resolve) => pm2.disconnect(() => resolve()));
+  }
+  process.stdout.write(`${JSON.stringify({ action: "install", platform: process.platform, endpoint, pm2_name: config.pm2Name, policy_file: configPath, health_status: result.health_status, bearer_gate_status: result.bearer_gate_status }, null, 2)}\n`);
+}

package/cli/commands/ops.js

@@ -0,0 +1,69 @@
+const DEFAULT_LOCAL_CLAUTH = "http://127.0.0.1:52437";
+
+function endpointFrom(opts) {
+  const approved = process.env.CLAUTH_OPS_APPROVED_ORIGIN;
+  if (!approved) throw new Error("Ops endpoint unavailable: CLAUTH_OPS_APPROVED_ORIGIN is required");
+  const approvedUrl = new URL(approved);
+  const requested = opts.endpoint ? new URL(opts.endpoint) : approvedUrl;
+  if (approvedUrl.protocol !== "https:" || requested.origin !== approvedUrl.origin) throw new Error("Ops endpoint is not the approved Vultr origin");
+  return approvedUrl.toString().replace(/\/$/, "");
+}
+
+async function bearer(service = process.env.CLAUTH_OPS_TOKEN_SERVICE || "vultr-ops-api-token") {
+  const response = await fetch(`${process.env.CLAUTH_LOCAL_URL || DEFAULT_LOCAL_CLAUTH}/v/${encodeURIComponent(service)}`);
+  if (!response.ok) throw new Error(`${service} unavailable from local clauth`);
+  const token = (await response.text()).trim();
+  if (!token) throw new Error("vultr-ops-api-token is empty");
+  return token;
+}
+
+export async function requestOps({ endpoint, token, method, path, body }) {
+  const response = await fetch(`${endpoint}${path}`, {
+    method,
+    headers: { Authorization: `Bearer ${token}`, Accept: "application/json", ...(body ? { "Content-Type": "application/json" } : {}) },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+  });
+  const payload = await response.json().catch(() => ({ error: "invalid_json_response" }));
+  if (!response.ok) throw new Error(payload.error || `ops HTTP ${response.status}`);
+  return payload;
+}
+
+function print(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+export async function runOps(action, opts = {}) {
+  const endpoint = endpointFrom(opts);
+  const token = await bearer(opts.tokenService);
+  const request = (method, path, body) => requestOps({ endpoint, token, method, path, body });
+  if (action === "catalog") return print(await request("GET", "/v1/ops/catalog"));
+  if (action === "list") return print(await request("GET", "/v1/ops/processes"));
+  if (action === "describe") {
+    if (!opts.target) throw new Error("--target is required for describe");
+    return print(await request("GET", `/v1/ops/processes/${encodeURIComponent(opts.target)}`));
+  }
+  if (action === "run") {
+    if (!opts.operation) throw new Error("--operation is required for run");
+    const input = {
+      ...(opts.target ? { target: opts.target } : {}),
+      ...(opts.script ? { script: opts.script } : {}),
+      ...(opts.instances ? { instances: Number(opts.instances) } : {}),
+      ...(opts.argsJson ? { args: JSON.parse(opts.argsJson) } : {}),
+      ...(opts.optionsJson ? { options: JSON.parse(opts.optionsJson) } : {}),
+    };
+    return print(await request("POST", "/v1/ops/operations", { operation: opts.operation, input }));
+  }
+  if (action === "promote") {
+    if (!opts.application) throw new Error("--application is required for promote");
+    return print(await request("POST", "/v1/ops/promotions", { application_uuid: opts.application }));
+  }
+  if (action === "deploy") {
+    if (!opts.application) throw new Error("--application is required for deploy");
+    return print(await request("POST", "/v1/ops/deployments", { application: opts.application, ...(opts.ref ? { ref: opts.ref } : {}) }));
+  }
+  if (action === "job") {
+    if (!opts.job) throw new Error("--job is required for job");
+    return print(await request("GET", `/v1/ops/jobs/${encodeURIComponent(opts.job)}`));
+  }
+  throw new Error(`unknown ops action: ${action}`);
+}