@lifeaitools/clauth 2.1.1 → 2.10.1

package/cli/http/components/vault-auth-component.js

@@ -0,0 +1,264 @@
+// cli/http/components/vault-auth-component.js
+// The Vault/Auth component: the actual security core -- vault unlock
+// (/auth), lock (/lock), write-token issuance (/write-token), and master
+// password change (/change-pw). Every closure variable these routes
+// read or mutate (password, writeSession, authFailCount, authHardLocked,
+// tunnelHostname, tunnelStatus) is exposed via ctx as get/set accessor
+// properties -- same pattern as the Tunnel component's ctx.tunnel, just
+// flattened here since these 6 span multiple concerns (auth state,
+// tunnel state) that don't share one natural sub-object.
+//
+// rotationEngine/fetchTunnelConfig/startTunnel/stopTunnel/
+// invalidateCallAgentCtxCache/isTerminalAuthVerdict all stay defined in
+// serve.js and are passed via ctx as plain references -- avoid-circular-
+// import reasoning, same as every other component this session.
+import { deriveToken, deriveSeedHash } from "../../fingerprint.js";
+import * as api from "../../api.js";
+import { operation } from "../../supervisor-registry.js";
+import { readBody } from "../request-utils.js";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { execSync } from "node:child_process";
+
+const LOG_FILE = path.join(os.tmpdir(), "clauth-serve.log");
+const MAX_AUTH_FAILS = 10;
+const WRITE_TOKEN_BYTES = 32;
+const WRITE_TOKEN_TTL_MS = 10 * 60 * 1000;
+
+function makeWriteToken() {
+  return {
+    token: crypto.randomBytes(WRITE_TOKEN_BYTES).toString("base64url"),
+    expiresAt: Date.now() + WRITE_TOKEN_TTL_MS,
+  };
+}
+
+export function registerVaultAuthRoutes(ctx) {
+  // POST /write-token — hand the dashboard a current write token for an
+  // ALREADY-UNLOCKED vault, with no second password prompt.
+  //
+  // A human looking at the dashboard has already passed the lock screen (or
+  // the daemon was auto-unlocked via --pw/boot.key). Making them re-enter the
+  // password to press a button is ceremony, not security: GET / at the route
+  // above already embeds a write token on exactly this condition. This route
+  // just lets the page RENEW it, which GET / could only do on a full reload.
+  //
+  // Why the write token still exists at all: every request reaching this
+  // server is already loopback-only (hard 403 above), but cloudflared proxies
+  // the public tunnel FROM localhost, so a remote request and a local one are
+  // indistinguishable by address. The token is what a page-driven write has
+  // and a blind remote POST does not, so the gate stays; only the prompt goes.
+  //
+  // Mint-or-reuse, mirroring GET /: reusing a still-valid session keeps
+  // multiple open tabs working instead of each one invalidating the last.
+  ctx.registerWriteRoute("POST", "/write-token", async (req, res) => {
+      if (!ctx.password) {
+        res.writeHead(403, { "Content-Type": "application/json", ...ctx.CORS });
+        return res.end(JSON.stringify({ error: "vault_locked", locked: true }));
+      }
+      if (!ctx.writeSession || Date.now() > ctx.writeSession.expiresAt) ctx.writeSession = makeWriteToken();
+      return ctx.ok(res, {
+        ok: true,
+        write_token: ctx.writeSession.token,
+        write_expires_at: new Date(ctx.writeSession.expiresAt).toISOString(),
+      });
+  });
+  // POST /auth — unlock the vault with a password (verifies against Edge Function)
+  ctx.registerWriteRoute("POST", "/auth", async (req, res) => {
+      let body;
+      try { body = await readBody(req); } catch {
+        res.writeHead(400, { "Content-Type": "application/json", ...ctx.CORS });
+        return res.end(JSON.stringify({ error: "Invalid JSON body" }));
+      }
+
+      const pw = body.password;
+      if (!pw || typeof pw !== "string") {
+        res.writeHead(400, { "Content-Type": "application/json", ...ctx.CORS });
+        return res.end(JSON.stringify({ error: "password is required" }));
+      }
+
+      if (ctx.authHardLocked) {
+        res.writeHead(401, { "Content-Type": "application/json", ...ctx.CORS });
+        return res.end(JSON.stringify({ error: "Too many failed attempts — restart daemon to try again", hard_locked: true }));
+      }
+
+      try {
+        const { token, timestamp } = deriveToken(pw, ctx.machineHash);
+        const result = await api.test(pw, ctx.machineHash, token, timestamp);
+        if (result.error) {
+          // Preserve the server's `reason` (invalid_token (N/5), machine_locked, …)
+          // so the catch block can surface it AND decide whether to keep retrying.
+          const authError = new Error(result.error);
+          authError.serverReason = result.reason || null;
+          throw authError;
+        }
+        ctx.password = pw;   // unlock — store in process memory only
+        ctx.writeSession = makeWriteToken();
+        ctx.authFailCount = 0;
+        ctx.authHardLocked = false;
+        const logLine = `[${new Date().toISOString()}] Vault unlocked\n`;
+        try { fs.appendFileSync(LOG_FILE, logLine); } catch {}
+        // Start rotation engine on unlock
+        ctx.rotationEngine.start();
+        // Auto-seal: DPAPI-encrypt password to boot.key for passwordless crash recovery
+        // Only on Windows; only if autostart dir exists (i.e., install was run)
+        if (os.platform() === "win32") {
+          const autostartDir = path.join(os.homedir(), "AppData", "Roaming", "clauth");
+          const bootKeyPath = path.join(autostartDir, "boot.key");
+          if (fs.existsSync(autostartDir)) {
+            try {
+              const pwEscaped = pw.replace(/'/g, "''");
+              const psExpr = `Add-Type -AssemblyName System.Security; [Convert]::ToBase64String([Security.Cryptography.ProtectedData]::Protect([Text.Encoding]::UTF8.GetBytes('${pwEscaped}'),$null,'CurrentUser'))`;
+              const psExe = process.env.SystemRoot
+                ? `${process.env.SystemRoot}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe`
+                : "powershell.exe";
+              const encrypted = execSync(`"${psExe}" -NoProfile -Command "${psExpr}"`, { encoding: "utf8", timeout: 5000 }).trim();
+              fs.writeFileSync(bootKeyPath, encrypted, "utf8");
+              const sealLog = `[${new Date().toISOString()}] Auto-sealed boot.key via DPAPI (crash recovery enabled)\n`;
+              try { fs.appendFileSync(LOG_FILE, sealLog); } catch {}
+            } catch (sealErr) {
+              const sealLog = `[${new Date().toISOString()}] Auto-seal failed (non-fatal): ${sealErr.message}\n`;
+              try { fs.appendFileSync(LOG_FILE, sealLog); } catch {}
+            }
+          }
+        }
+        // Auto-start tunnel: --tunnel flag takes priority, otherwise fetch from DB
+        if (!ctx.tunnelHostname) {
+          ctx.fetchTunnelConfig().then(configured => {
+            if (configured) {
+              ctx.tunnelHostname = configured;
+              ctx.tunnelStatus = "starting";
+              ctx.startTunnel().catch(() => {});
+            } else {
+              // No tunnel configured in DB and no --tunnel flag
+              ctx.tunnelStatus = "not_configured";
+              const msg = [
+                `[${new Date().toISOString()}] No tunnel configured.`,
+                "  claude.ai web integration is inactive.",
+                "  To enable: run 'clauth tunnel setup'",
+              ].join("\n");
+              try { fs.appendFileSync(LOG_FILE, msg + "\n"); } catch {}
+              console.log("\n  ⚠  No tunnel configured — claude.ai web integration inactive.");
+              console.log("     Run: clauth tunnel setup\n");
+            }
+          }).catch(() => {
+            ctx.tunnelStatus = "error";
+          });
+        } else {
+          ctx.tunnelStatus = "starting";
+          ctx.startTunnel().catch(() => {});
+        }
+        operation("vault.unlock", {}, null, { ok: true });
+        return ctx.ok(res, { ok: true, locked: false, write_token: ctx.writeSession.token, write_expires_at: new Date(ctx.writeSession.expiresAt).toISOString() });
+      } catch (authErr) {
+        const msg = authErr.message || "";
+        const serverReason = authErr.serverReason || null;
+        // Classify FIRST: is this a backend/external-resource failure (the vault
+        // backend or its database never rendered an auth verdict), or a genuine
+        // credential verdict? A database timeout, a 5xx, a network drop, or a
+        // rate-limit is NOT a wrong password and MUST NOT take a strike — that is
+        // exactly what turned a DB blip into a permanent lockout. Both the thrown
+        // error (timeout/network/typed VaultBackendError) and any server `reason`
+        // (rate_limited/db_error) are checked.
+        const backendKind = api.classifyBackendError(authErr) || api.classifyServerReason(serverReason);
+        if (backendKind) {
+          const BACKEND_MSG = {
+            timeout: "Vault backend (database) is not responding — try again in a moment",
+            db_error: "Vault backend database error — try again in a moment",
+            network: "Vault backend is unreachable — check your network and try again",
+            rate_limited: "Vault backend is rate-limiting — wait a few seconds and retry",
+            server_error: "Vault backend error — try again in a moment",
+          };
+          const friendly = BACKEND_MSG[backendKind] || "Vault backend is unreachable — try again in a moment";
+          const detail = authErr.detail || msg;
+          // No strike, no hard-lock — the verdict was never rendered.
+          const failLog = `[${new Date().toISOString()}] [BACKEND ${backendKind}] vault backend unreachable, no auth strike — ${detail}\n`;
+          try { fs.appendFileSync(LOG_FILE, failLog); } catch {}
+          operation("vault.unlock", {}, null, { ok: false, backend_error: true, kind: backendKind });
+          res.writeHead(503, { "Content-Type": "application/json", ...ctx.CORS });
+          return res.end(JSON.stringify({
+            error: friendly,
+            transport_error: true,   // back-compat: existing lock screen renders this
+            backend_error: true,
+            kind: backendKind,
+            detail,
+          }));
+        }
+        // Server rendered a verdict. Surface its `reason` so the CLI/log shows
+        // WHY (invalid_token (N/5) vs machine_locked) instead of a bare "auth_failed".
+        const reasonSuffix = serverReason ? ` (${serverReason})` : "";
+        // STOP-ON-REJECTION: a server-side machine lock or invalid_token is terminal —
+        // each retry only burns another of the 5 server-side strikes toward a DB lockout.
+        // Hard-lock locally NOW so the browser/CLI cannot keep hammering the vault.
+        const isTerminalVerdict = ctx.isTerminalAuthVerdict(serverReason);
+        ctx.authFailCount++;
+        const authRemaining = MAX_AUTH_FAILS - ctx.authFailCount;
+        const failLog = `[${new Date().toISOString()}] [AUTH FAIL ${ctx.authFailCount}/${MAX_AUTH_FAILS}] ${msg || "Wrong password"}${reasonSuffix}\n`;
+        try { fs.appendFileSync(LOG_FILE, failLog); } catch {}
+        if (isTerminalVerdict) {
+          ctx.authHardLocked = true;
+          const lockLog = `[${new Date().toISOString()}] Server rejected with terminal verdict${reasonSuffix} — hard-locking locally to stop strike accrual; recover via the runbook (unlock machine + re-seal boot.key)\n`;
+          try { fs.appendFileSync(LOG_FILE, lockLog); } catch {}
+          operation("vault.unlock", {}, null, { ok: false, terminal: true, reason: serverReason });
+          res.writeHead(401, { "Content-Type": "application/json", ...ctx.CORS });
+          return res.end(JSON.stringify({ error: "Vault rejected credentials — recovery required", reason: serverReason, hard_locked: true, terminal: true }));
+        }
+        if (ctx.authFailCount >= MAX_AUTH_FAILS) {
+          ctx.authHardLocked = true;
+          const lockLog = `[${new Date().toISOString()}] Auth failure limit reached — vault hard-locked\n`;
+          try { fs.appendFileSync(LOG_FILE, lockLog); } catch {}
+          operation("vault.unlock", {}, null, { ok: false, hard_locked: true, reason: serverReason });
+          res.writeHead(401, { "Content-Type": "application/json", ...ctx.CORS });
+          return res.end(JSON.stringify({ error: "Too many failed attempts — restart daemon to try again", reason: serverReason, hard_locked: true }));
+        }
+        operation("vault.unlock", {}, null, { ok: false, reason: serverReason, failures_remaining: authRemaining });
+        res.writeHead(401, { "Content-Type": "application/json", ...ctx.CORS });
+        return res.end(JSON.stringify({ error: "Invalid password", reason: serverReason, failures_remaining: authRemaining }));
+      }
+  });
+  // POST /lock — clear password from memory
+  ctx.registerWriteRoute("POST", "/lock", async (req, res) => {
+      ctx.password = null;
+      ctx.writeSession = null;
+      ctx.invalidateCallAgentCtxCache();
+      ctx.stopTunnel();
+      const logLine = `[${new Date().toISOString()}] Vault locked\n`;
+      try { fs.appendFileSync(LOG_FILE, logLine); } catch {}
+      operation("vault.lock", {}, null, { ok: true });
+      return ctx.ok(res, { ok: true, locked: true, hard_locked: ctx.authHardLocked });
+  });
+  // POST /change-pw — change master password (must be unlocked)
+  ctx.registerWriteRoute("POST", "/change-pw", async (req, res) => {
+      if (ctx.writeGuard(req, res)) return;
+
+      let body;
+      try { body = await readBody(req); } catch {
+        res.writeHead(400, { "Content-Type": "application/json", ...ctx.CORS });
+        return res.end(JSON.stringify({ error: "Invalid JSON body" }));
+      }
+
+      const { newPassword } = body;
+      if (!newPassword || typeof newPassword !== "string" || newPassword.length < 8) {
+        res.writeHead(400, { "Content-Type": "application/json", ...ctx.CORS });
+        return res.end(JSON.stringify({ error: "newPassword must be at least 8 characters" }));
+      }
+
+      try {
+        const { token, timestamp } = deriveToken(ctx.password, ctx.machineHash);
+        const newSeedHash = deriveSeedHash(ctx.machineHash, newPassword);
+        const result = await api.changePassword(ctx.password, ctx.machineHash, token, timestamp, newSeedHash);
+        if (result.error) throw new Error(result.error);
+        ctx.password = newPassword;  // update in-memory password to new one
+        ctx.writeSession = makeWriteToken();
+        const logLine = `[${new Date().toISOString()}] Password changed\n`;
+        try { fs.appendFileSync(LOG_FILE, logLine); } catch {}
+        operation("vault.change_password", {}, null, { ok: true });
+        return ctx.ok(res, { ok: true, write_token: ctx.writeSession.token, write_expires_at: new Date(ctx.writeSession.expiresAt).toISOString() });
+      } catch (err) {
+        operation("vault.change_password", {}, null, { ok: false, error: err.message });
+        res.writeHead(502, { "Content-Type": "application/json", ...ctx.CORS });
+        return res.end(JSON.stringify({ error: err.message }));
+      }
+  });
+}

package/cli/http/components/watchdog-component.js

@@ -0,0 +1,28 @@
+// cli/http/components/watchdog-component.js
+// The Watchdog component: read-only status/event views over
+// watchdog-registry.js's child-service monitor, plus the one dynamic-segment
+// mutation (restart a named watchdog-owned service). All three functions are
+// real exports of watchdog-registry.js -- imported directly, no ctx needed
+// for them since there's no circular-import risk (this component is never
+// imported back into that module).
+import {
+  getWatchdogStatuses,
+  readWatchdogEvents,
+  restartWatchdogService,
+} from "../../watchdog-registry.js";
+
+export function registerWatchdogRoutes(ctx) {
+  ctx.registerReadOnlyRoute("GET", "/watchdog/services", async (req, res) => ctx.ok(res, await getWatchdogStatuses()));
+
+  ctx.registerReadOnlyRoute("GET", "/watchdog/events", async (req, res, url) => {
+      const limit = Number(url.searchParams.get("limit") || 100);
+      return ctx.ok(res, { events: readWatchdogEvents(limit) });
+  });
+
+  // POST /watchdog/services/:name/restart
+  ctx.registerPatternRoute("POST", /^\/watchdog\/services\/([^/]+)\/restart$/, async (req, res, match) => {
+      const result = restartWatchdogService(decodeURIComponent(match[1]));
+      res.writeHead(result.ok ? 200 : 403, { "Content-Type": "application/json", ...ctx.CORS });
+      return res.end(JSON.stringify(result));
+  });
+}

package/cli/http/request-utils.js

@@ -0,0 +1,21 @@
+// cli/http/request-utils.js
+// Small stateless HTTP request helpers shared across serve.js and the
+// per-feature components under cli/http/components/. Pure functions only --
+// nothing here closes over daemon instance state.
+export function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    req.on("data", chunk => { data += chunk; if (data.length > 65536) reject(new Error("Body too large")); });
+    req.on("end", () => { try { resolve(JSON.parse(data)); } catch { reject(new Error("Invalid JSON")); } });
+    req.on("error", reject);
+  });
+}
+
+export   function readRawBody(req) {
+    return new Promise((resolve, reject) => {
+      let data = "";
+      req.on("data", chunk => { data += chunk; if (data.length > 65536) reject(new Error("Body too large")); });
+      req.on("end", () => resolve(data));
+      req.on("error", reject);
+    });
+  }

package/cli/http/servers/ops-server.js

@@ -0,0 +1,335 @@
+// cli/http/servers/ops-server.js
+// The Ops server: a SEPARATE HTTP listener, its own port, for the
+// PM2/Coolify/deployment operations plane. Bearer-token gated
+// (requireOpsBearer), entirely distinct from the main daemon's vault-
+// password gate -- this plane exists for remote/agent-driven
+// infrastructure operations, not local vault access, so it gets its own
+// port rather than sharing fate with the vault daemon's port/lifecycle.
+//
+// Fully self-contained: no reference to the main daemon's createServer
+// closure state (password/whitelist/etc.) survives in this subsystem --
+// confirmed by grep before extraction. createOpsServer() takes no
+// dependency-injection context; it builds its own ops-job state.
+import http from "node:http";
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+import crypto from "node:crypto";
+import { ensurePm2 } from "../../ops/pm2-preflight.js";
+import { createPm2Adapter, PM2_OPERATION_CATALOG } from "../../ops/pm2-adapter.js";
+import { createOperationPolicy } from "../../ops/operation-policy.js";
+import { createJobStore } from "../../ops/job-store.js";
+import { createSerializedExecutor } from "../../ops/serialized-executor.js";
+import { createCoolifyAdapter, deploymentUuidFrom } from "../../ops/coolify-adapter.js";
+import { createDeploymentAdapter, parseDeploymentRegistry } from "../../ops/deployment-adapter.js";
+import { getSupervisorDir } from "../../supervisor-registry.js";
+import { readBody } from "../request-utils.js";
+
+const LIVE_PORT = 52437;
+const LOG_FILE = path.join(os.tmpdir(), "clauth-serve.log");
+
+// Duplicated from serve.js's own isLoopbackAddress -- trivial, zero
+// dependency, kept local to avoid a circular import back into serve.js
+// (which imports createOpsServer from this file).
+function isLoopbackAddress(remote) {
+  return remote === "127.0.0.1" || remote === "::1" || remote === "::ffff:127.0.0.1";
+}
+
+const CORS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type, Authorization, Mcp-Session-Id, mcp-protocol-version, mcp-session-id",
+};
+
+function ok(res, data) {
+  res.writeHead(200, { "Content-Type": "application/json", ...CORS });
+  res.end(JSON.stringify(data));
+}
+
+export async function createOpsServer() {
+  // pm2 is a real declared dependency, but was previously a static top-level
+  // import here -- a missing/corrupted node_modules/pm2 threw at MODULE-LOAD
+  // time, which (since serve.js imports this file unconditionally) crashed
+  // the entire clauth daemon, vault included, with no recovery attempt.
+  // ensurePm2() resolves it dynamically and repairs via `npm install` once
+  // before giving up, so a missing pm2 degrades only the ops plane's own
+  // startup, not clauth as a whole.
+  const pm2 = await ensurePm2();
+  const opsAdapter = createPm2Adapter(pm2);
+  const executePm2 = createSerializedExecutor();
+  const opsPolicy = createOperationPolicy({
+    enabled: String(process.env.CLAUTH_OPS_ENABLED || "").split(",").map((item) => item.trim()).filter(Boolean),
+    applications: (() => { try { return JSON.parse(process.env.CLAUTH_OPS_APPLICATIONS || "{}"); } catch { return {}; } })(),
+    adminEnabled: String(process.env.CLAUTH_OPS_ADMIN_ENABLED || "").split(",").map((item) => item.trim()).filter(Boolean),
+    adminApplications: (() => { try { return JSON.parse(process.env.CLAUTH_OPS_ADMIN_APPLICATIONS || "{}"); } catch { return {}; } })(),
+    allowHostWide: process.env.CLAUTH_OPS_ALLOW_HOST_WIDE === "1",
+  });
+  const opsJobs = createJobStore({
+    filePath: process.env.CLAUTH_OPS_JOB_STORE_PATH || path.join(getSupervisorDir(), "ops-jobs.json"),
+  });
+
+  async function getLoopbackSecret(service) {
+    const response = await fetch(`http://127.0.0.1:${LIVE_PORT}/v/${encodeURIComponent(service)}`, { signal: AbortSignal.timeout(5000) });
+    if (!response.ok) throw new Error(`${service} unavailable from local clauth`);
+    const value = (await response.text()).trim();
+    if (!value) throw new Error(`${service} is empty`);
+    return value;
+  }
+  const coolify = createCoolifyAdapter({
+    baseUrl: process.env.CLAUTH_COOLIFY_BASE_URL || "https://deploy.regendevcorp.com",
+    getToken: () => getLoopbackSecret("coolify-api"),
+  });
+  const deployments = (() => { try { return parseDeploymentRegistry(process.env.CLAUTH_OPS_DEPLOYMENTS || "{}"); } catch { return {}; } })();
+  const deploymentAdapter = createDeploymentAdapter({
+    deployments,
+    reload: async (target) => {
+      await executePm2(async () => {
+        await opsAdapter.connect();
+        try { await opsAdapter.execute("reload", { target, options: { updateEnv: true } }); } finally { await opsAdapter.disconnect(); }
+      });
+    },
+  });
+
+  /**
+   * Record an ops failure's upstream message to the LOCAL log only.
+   *
+   * job-store's sanitizer deliberately drops free-form `error` text so an
+   * upstream message cannot carry a credential into the persisted job file or
+   * the API response. That protection left every failure with an empty detail,
+   * so jobs reported `failed` with no reason at all. Jobs now carry an
+   * enumerated `code`; the underlying message goes here, to the same
+   * operator-only log as the rest of the daemon's diagnostics.
+   */
+  function logOpsFailure(kind, operation, error) {
+    const message = String(error?.message || error || "unknown");
+    try {
+      fs.appendFileSync(LOG_FILE, `[${new Date().toISOString()}] [OPS ${kind}/${operation}] ${message}\n`);
+    } catch {}
+  }
+
+  async function opsBearerRole(req) {
+    const header = req.headers.authorization;
+    const supplied = Array.isArray(header) ? header[0] : header;
+    if (!supplied || !String(supplied).startsWith("Bearer ")) return null;
+    const actual = String(supplied).slice(7).trim();
+    let admin; let agent;
+    try { admin = await getLoopbackSecret(process.env.CLAUTH_OPS_ADMIN_TOKEN_SERVICE || "vultr-ops-admin-token"); } catch {}
+    try { agent = await getLoopbackSecret(process.env.CLAUTH_OPS_AGENT_TOKEN_SERVICE || "vultr-ops-api-token"); } catch {}
+    if (admin && agent && admin === agent) return null;
+    for (const [role, expected] of [["admin", admin], ["agent", agent]]) {
+      if (!expected) continue;
+      const a = Buffer.from(actual); const b = Buffer.from(expected);
+      if (a.length === b.length && crypto.timingSafeEqual(a, b)) return role;
+    }
+    return null;
+  }
+
+  async function requireOpsBearer(req, res) {
+    const role = await opsBearerRole(req);
+    if (role) { req._opsRole = role; return true; }
+    res.writeHead(401, { "Content-Type": "application/json", ...CORS });
+    res.end(JSON.stringify({ error: "ops_bearer_required" }));
+    return false;
+  }
+
+  function submitOpsJob(operation, input, role = "agent") {
+    const authorization = opsPolicy.authorize(operation, input, role);
+    const job = opsJobs.create({ kind: "pm2", operation, target: input.target || input.name || null });
+    if (!authorization.ok) {
+      return opsJobs.event(job.id, "rejected", { code: authorization.code });
+    }
+    void (async () => {
+      opsJobs.event(job.id, "running");
+      try {
+        const result = await executePm2(async () => {
+          await opsAdapter.connect();
+          try { return await opsAdapter.execute(operation, input); } finally { await opsAdapter.disconnect(); }
+        });
+        opsJobs.event(job.id, "succeeded", operationReceipt(operation, result, authorization.allowed_targets || []));
+      } catch (error) {
+        // `error` alone is dropped by job-store's sanitizer (it refuses
+        // free-form upstream text so a credential cannot ride along), which
+        // left every failure with an empty detail. Emit an enumerated code so
+        // the failure has a reason; keep the message for the local log only.
+        logOpsFailure("pm2", operation, error);
+        opsJobs.event(job.id, "failed", { code: "pm2_operation_failed" });
+      }
+    })();
+    return opsJobs.get(job.id);
+  }
+
+  function operationReceipt(operation, result, allowedTargets) {
+    if (["list", "describe", "logs"].includes(operation)) {
+      const processes = Array.isArray(result)
+        ? result.filter((process) => allowedTargets.includes("*") || allowedTargets.includes(process?.name))
+        : [];
+      return { processes };
+    }
+    if (operation === "ping") return { status: "connected" };
+    return { status: "completed" };
+  }
+
+  function submitPromotionJob(applicationUuid) {
+    const job = opsJobs.create({ kind: "coolify", operation: "promote", target: applicationUuid });
+    const enabled = String(process.env.CLAUTH_OPS_ENABLED || "").split(",").map((item) => item.trim()).includes("coolify_promote");
+    const allowlist = (() => { try { return JSON.parse(process.env.CLAUTH_COOLIFY_PROMOTE_UUIDS || "[]"); } catch { return []; } })();
+    if (!enabled || !Array.isArray(allowlist) || !allowlist.includes(applicationUuid)) {
+      return opsJobs.event(job.id, "rejected", { code: "service_not_available" });
+    }
+    void (async () => {
+      opsJobs.event(job.id, "running");
+      try {
+        const deployment = await coolify.promote(applicationUuid);
+        // Coolify answers with a `deployments` ARRAY, not a flat object — see
+        // deploymentUuidFrom. Reading the flat field alone marked the job failed
+        // while the deployment was actually running.
+        const deploymentUuid = deploymentUuidFrom(deployment);
+        if (!deploymentUuid) {
+          // The deploy request itself SUCCEEDED (no throw); only the UUID was
+          // unreadable, so the deployment may well be RUNNING. The code says so
+          // explicitly rather than a bare "failed", because a plain failure
+          // invites a retry and a duplicate production deploy.
+          //
+          // An enumerated code, not a free-form error: job-store's sanitizer
+          // drops `error` on purpose to keep upstream text (and any credential
+          // inside it) out of the persisted job.
+          return opsJobs.event(job.id, "failed", { code: "coolify_deploy_accepted_uuid_unreadable" });
+        }
+        opsJobs.event(job.id, "waiting", { deployment_uuid: deploymentUuid });
+        const terminal = await coolify.poll(deploymentUuid, { attempts: Number(process.env.CLAUTH_COOLIFY_POLL_ATTEMPTS || 60), delay: () => new Promise((resolve) => setTimeout(resolve, 5000)) });
+        opsJobs.event(job.id, terminal.state === "succeeded" ? "succeeded" : terminal.state, { deployment_uuid: deploymentUuid, status: terminal.deployment?.status || null });
+      } catch (error) {
+        // The throw may have happened AFTER Coolify accepted the deploy (e.g.
+        // the poll lost the network), so this is not proof nothing shipped.
+        logOpsFailure("coolify", "promote", error);
+        opsJobs.event(job.id, "failed", { code: "coolify_promote_failed" });
+      }
+    })();
+    return opsJobs.get(job.id);
+  }
+
+  function submitDeploymentJob(application, ref) {
+    const job = opsJobs.create({ kind: "deployment", operation: "deploy", target: application });
+    const enabled = String(process.env.CLAUTH_OPS_ENABLED || "").split(",").map((item) => item.trim()).includes("deploy");
+    if (!enabled || !deployments[application]) return opsJobs.event(job.id, "rejected", { code: "service_not_available" });
+    void (async () => {
+      opsJobs.event(job.id, "running");
+      try { opsJobs.event(job.id, "building"); opsJobs.event(job.id, "succeeded", { result: await deploymentAdapter.deploy({ application, ref }) }); }
+      catch (error) { logOpsFailure("deployment", "deploy", error); opsJobs.event(job.id, "failed", { code: "deployment_failed" }); }
+    })();
+    return opsJobs.get(job.id);
+  }
+
+  return http.createServer(async (req, res) => {
+    const remote = req.socket.remoteAddress;
+    if (!isLoopbackAddress(remote)) {
+      res.writeHead(403, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify({ error: "loopback_only" }));
+    }
+    if (req.method === "OPTIONS") {
+      res.writeHead(204, CORS);
+      return res.end();
+    }
+    const url = new URL(req.url, "http://127.0.0.1");
+    const reqPath = url.pathname;
+    const method = req.method;
+
+    if (method === "GET" && reqPath === "/v1/ops/catalog") {
+      if (!await requireOpsBearer(req, res)) return;
+      return ok(res, { schema: "clauth.ops.v1", operations: PM2_OPERATION_CATALOG });
+    }
+
+    if (method === "GET" && reqPath === "/v1/ops/processes") {
+      if (!await requireOpsBearer(req, res)) return;
+      const job = submitOpsJob("list", {}, req._opsRole);
+      res.writeHead(job.phase === "rejected" ? 403 : 202, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify(job));
+    }
+
+    const opsProcessMatch = reqPath.match(/^\/v1\/ops\/processes\/([^/]+)$/);
+    if (method === "GET" && opsProcessMatch) {
+      if (!await requireOpsBearer(req, res)) return;
+      const job = submitOpsJob("describe", { target: decodeURIComponent(opsProcessMatch[1]) }, req._opsRole);
+      res.writeHead(job.phase === "rejected" ? 403 : 202, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify(job));
+    }
+
+    if (method === "POST" && reqPath === "/v1/ops/operations") {
+      if (!await requireOpsBearer(req, res)) return;
+      let body;
+      try { body = await readBody(req); } catch {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "invalid_json" }));
+      }
+      const operation = String(body?.operation || "");
+      if (!PM2_OPERATION_CATALOG[operation]) {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "unknown_operation" }));
+      }
+      const job = submitOpsJob(operation, body?.input && typeof body.input === "object" ? body.input : {}, req._opsRole);
+      res.writeHead(job.phase === "rejected" ? 403 : 202, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify(job));
+    }
+
+    if (method === "POST" && reqPath === "/v1/ops/promotions") {
+      if (!await requireOpsBearer(req, res)) return;
+      let body;
+      try { body = await readBody(req); } catch {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "invalid_json" }));
+      }
+      const applicationUuid = String(body?.application_uuid || "").trim();
+      if (!applicationUuid) {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "application_uuid_required" }));
+      }
+      const job = submitPromotionJob(applicationUuid);
+      res.writeHead(job.phase === "rejected" ? 403 : 202, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify(job));
+    }
+
+    if (method === "POST" && reqPath === "/v1/ops/deployments") {
+      if (!await requireOpsBearer(req, res)) return;
+      let body;
+      try { body = await readBody(req); } catch {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "invalid_json" }));
+      }
+      const application = String(body?.application || "").trim();
+      if (!application) {
+        res.writeHead(400, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "application_required" }));
+      }
+      const job = submitDeploymentJob(application, body?.ref ? String(body.ref) : undefined);
+      res.writeHead(job.phase === "rejected" ? 403 : 202, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify(job));
+    }
+
+    const opsJobMatch = reqPath.match(/^\/v1\/ops\/jobs\/([^/]+)$/);
+    if (method === "GET" && opsJobMatch) {
+      if (!await requireOpsBearer(req, res)) return;
+      const job = opsJobs.get(decodeURIComponent(opsJobMatch[1]));
+      res.writeHead(job ? 200 : 404, { "Content-Type": "application/json", ...CORS });
+      return res.end(JSON.stringify(job || { error: "job_not_found" }));
+    }
+
+    const opsJobEventsMatch = reqPath.match(/^\/v1\/ops\/jobs\/([^/]+)\/events$/);
+    if (method === "GET" && opsJobEventsMatch) {
+      if (!await requireOpsBearer(req, res)) return;
+      const jobId = decodeURIComponent(opsJobEventsMatch[1]);
+      if (!opsJobs.get(jobId)) {
+        res.writeHead(404, { "Content-Type": "application/json", ...CORS });
+        return res.end(JSON.stringify({ error: "job_not_found" }));
+      }
+      res.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", Connection: "keep-alive", ...CORS });
+      const unsubscribe = opsJobs.subscribe(jobId, (job) => {
+        if (!res.writableEnded) res.write(`event: job\ndata: ${JSON.stringify(job)}\n\n`);
+      });
+      req.on("close", unsubscribe);
+      return;
+    }
+
+    res.writeHead(404, { "Content-Type": "application/json", ...CORS });
+    res.end(JSON.stringify({ error: "not_found" }));
+  });
+}