@lifeaitools/clauth 1.31.1 → 2.0.0

package/.clauth-skill/SKILL.md

@@ -216,6 +216,37 @@ raw secrets and no Vault secret names. Fetch `GET /v/<service>` only for the one
 exact credential needed by the next command. Never walk every service and never
 bulk-fetch all secrets.
 
+## Managed PM2 Operations Control Plane
+
+For LIFEAI development hosts, manage an approved PM2 application through the
+bearer-authenticated clauth operations control plane. Do **not** invoke PM2
+directly from an agent, dashboard, or deployment script. The policy file is the
+allowlist: it names permitted applications, operations, deployment definitions,
+and whether host-wide actions are available.
+
+Install or validate the local controller with its explicit policy file:
+
+```bash
+# Linux
+clauth ops install --config /etc/clauth/ops-control-plane.json --dry-run
+clauth ops install --config /etc/clauth/ops-control-plane.json
+
+# Windows PowerShell
+clauth ops install --config C:\ProgramData\clauth\ops-control-plane.json --dry-run
+clauth ops install --config C:\ProgramData\clauth\ops-control-plane.json
+```
+
+The live install replaces only the installer-owned `clauth-deployment` PM2
+process, verifies its loopback `/health` response, and checks that an unauthenticated
+catalog request is rejected. It retrieves its bearer only from the local clauth
+service; never paste, print, or place that bearer in a policy file.
+
+Use `clauth ops catalog` or the corresponding scoped MCP operations tools for
+approved process inspection and lifecycle actions. Before a production promotion,
+retain the job receipt and verify the selected application's health route. A
+passing install proves controller setup; it does not by itself prove an arbitrary
+application deployment.
+
 ## MCP Server (v1.16.9+)
 
 clauth runs as an MCP server with five namespaced paths and safe

package/.clauth-skill/references/operator-guide.md

@@ -100,6 +100,33 @@ select vault.create_secret('new-token-here', 'CLAUTH_ADMIN_BOOTSTRAP_TOKEN', 'ro
 
 ---
 
+## Managed PM2 Operations (LIFEAI development hosts)
+
+Use the clauth operations controller for approved PM2 lifecycle and deployment
+actions. Its policy JSON is the server-side allowlist; it must define only the
+applications and operations this host is permitted to expose. Do not grant
+host-wide PM2 actions unless there is an explicit operational requirement.
+
+Validate before changing the process manager, then install:
+
+```bash
+# Linux
+clauth ops install --config /etc/clauth/ops-control-plane.json --dry-run
+clauth ops install --config /etc/clauth/ops-control-plane.json
+
+# Windows PowerShell
+clauth ops install --config C:\ProgramData\clauth\ops-control-plane.json --dry-run
+clauth ops install --config C:\ProgramData\clauth\ops-control-plane.json
+```
+
+The installer owns only the `clauth-deployment` process. It checks the local
+health endpoint and verifies that the catalog remains bearer-gated. Keep the
+controller bearer in clauth, not in a shell history, policy file, or PM2
+environment dump. Use `clauth ops catalog` and scoped operations commands rather
+than invoking PM2 directly.
+
+---
+
 ## Viewing the Audit Log
 
 ```sql

package/README.md

@@ -164,6 +164,54 @@ description, timestamps, and `has_key`. It never returns raw secrets or Vault
 secret names. Use `GET /v/<service>` only for the one exact secret needed by the
 next command. Do not bulk-fetch every service.
 
+### PM2 deployment control-plane installer
+
+On a managed host, store the allowed PM2 targets and deployment definitions in a
+server-side JSON file, then install or update the supervised endpoint:
+
+```bash
+# Linux
+clauth ops install --config /etc/clauth/ops-control-plane.json
+
+# Windows PowerShell
+clauth ops install --config C:\ProgramData\clauth\ops-control-plane.json
+```
+
+The installer is idempotent on Linux and Windows: it creates or updates the
+`clauth-deployment` PM2 process, probes its loopback health endpoint, and proves
+that the operations catalog refuses requests without a bearer token. It does not
+store or print a bearer token. Use `--dry-run` to validate the policy file before
+changing PM2.
+
+The policy is an explicit application allowlist; keep `allow_host_wide` false
+unless a host-wide administrative operation has been deliberately approved. A
+minimal local policy looks like:
+
+```json
+{
+  "port": 53141,
+  "pm2_name": "clauth-deployment",
+  "operations": {
+    "agent_enabled": ["restart", "reload"],
+    "agent_applications": {
+      "restart": ["codeflow-mcp"],
+      "reload": ["codeflow-mcp"]
+    },
+    "allow_host_wide": false
+  }
+}
+```
+
+Verify the policy before installation, then verify the loopback service without
+ever placing a bearer in a shell command:
+
+```bash
+clauth ops install --config <policy-path> --dry-run
+clauth ops install --config <policy-path>
+curl -i http://127.0.0.1:<port>/health
+curl -i http://127.0.0.1:<port>/v1/ops/catalog  # must return 401 without a bearer
+```
+
 ---
 
 ## MCP Server — 5 Namespaces, 63 Tools

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}`);
+}