@lifeaitools/clauth 2.0.0 → 2.0.1

package/cli/supervisor-registry.js

@@ -213,6 +213,13 @@ function normalizeDestination(destination) {
   return value;
 }
 
+// "Remote" means "not running on this box", read off the validated destination
+// enum. Expressed as NOT-local so a destination added to DESTINATIONS later is
+// treated as remote by default rather than silently escaping the port rule.
+function isRemoteDestination(destination) {
+  return !String(destination).startsWith("local/");
+}
+
 function normalizeDocumentation(value) {
   if (value == null) return null;
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("documentation must be an object");
@@ -250,6 +257,32 @@ function normalizeSurface(surface, plugin) {
   const id = String(surface.id || "").trim();
   if (!/^[a-zA-Z0-9_.-]+$/.test(id) || /^\.+$/.test(id)) throw new Error("surface.id may contain only letters, numbers, dot, underscore, and dash, and may not be all dots");
   const destination = normalizeDestination(surface.destination || plugin.destination);
+  // A remote surface names a service running somewhere else (Vultr/Coolify).
+  // It is reached by URL and its port is the deployment registry's fact, not
+  // the manifest's. A local surface is the opposite case and keeps its port on
+  // purpose: that port describes how the service runs on a developer box,
+  // which is intrinsic to the service and correctly lives in the product repo.
+  //
+  // Keyed on the VALIDATED destination enum, not on the surface's free-text
+  // id/role. Keying on the label `remote` was tried and is wrong twice over:
+  // it lets the drift back in under any other surface name, and it falsely
+  // rejects a genuinely local surface that happens to be named "remote". A
+  // ported non-local surface is also actively harmful, not just untidy —
+  // localhostHealth() below would synthesize http://127.0.0.1:<port>/health
+  // for it, pointing the health reconciler at the wrong box entirely.
+  if (isRemoteDestination(destination) && surface.port !== undefined && surface.port !== null) {
+    throw new Error(`a remote surface must not declare a port — destination ${destination} is not on this box, so its port is the deployment registry's fact, not the manifest's`);
+  }
+  // Same rule, second route to the same harm. Banning `port` alone closes only
+  // the narrower half: localhostHealth() below accepts an ABSOLUTE health URL
+  // and permits localhost hosts only, so any absolute health on a non-local
+  // destination is by construction pointed at the wrong box — the identical
+  // defect the port rule exists to prevent, arriving through a different field.
+  // A remote surface's health is reached by its public route, not by a
+  // loopback URL this box could dial.
+  if (isRemoteDestination(destination) && surface.health && /^https?:\/\//i.test(String(surface.health))) {
+    throw new Error(`a remote surface must not declare an absolute health URL — destination ${destination} is not on this box, so a localhost health URL would probe the wrong machine`);
+  }
   const lifecycle_owner = normalizeLifecycleOwner(surface.lifecycle_owner || plugin.lifecycle_owner);
   const port = surface.port === undefined || surface.port === null || surface.port === "auto" ? surface.port ?? null : Number(surface.port);
   if (port !== null && port !== "auto" && (!Number.isInteger(port) || port < 1 || port > 65535)) throw new Error("surface.port must be auto or a TCP port");
@@ -400,6 +433,15 @@ export function discoverPlugins() {
           id,
           source,
           sourcePath: manifestPath,
+          // discovery_root must be recorded even on the quarantine path.
+          // deregisterPlugin() resolves its target via `prior?.sourcePath &&
+          // prior?.discovery_root`; omitting it here made that check false for
+          // every manifest_invalid row, so deregister fell back to the flat
+          // managed probe, missed the real directory, and returned a
+          // false-success "not_registered" while the plugin stayed on disk.
+          // A broken manifest is precisely what an operator reaches for
+          // deregister to remove, so this path must not be the weak one.
+          discovery_root: root,
           manifest_hash: hash,
           state: "manifest_invalid",
           enabled: false,
@@ -483,6 +525,255 @@ export function registerPlugin(manifestPath, actor = "localhost") {
   }, actor);
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// plugin sync — SWEEP, NOT A CATALOG.
+//
+// This reads the ORIGINAL clauth-plugin.json in each product repo and hands it
+// to registerPlugin. It deliberately stores NO inventory: no list of which
+// plugins exist, no copy of manifest content, no port assignments, no versions.
+// The table below is a list of PLACES TO LOOK, not a record of what is there —
+// every fact still comes from the product repo's own manifest, read fresh.
+//
+// That distinction is load-bearing. A central catalog of copied manifests
+// (lifeai-env's services/plugins/catalog.json + generate-catalog.mjs + its 7
+// generated manifests) was just retired precisely because a copy drifts from
+// the original and then two homes disagree about one fact. If a future cleanup
+// pass is tempted to "consolidate" this into a file that lists which plugins
+// exist, or to cache what was found, that rebuilds the thing that was deleted —
+// stop instead.
+// ─────────────────────────────────────────────────────────────────────────────
+const PRODUCT_REPO_MANIFESTS = [
+  { repo: "regen-root", manifest: "packages/codeflow/clauth-plugin.json" },
+  { repo: "regen-root", manifest: "apps/dev-center/clauth-plugin.json" },
+  { repo: "regen-root", manifest: "mcp-servers/regen-media/clauth-plugin.json" },
+  { repo: "regen-root", manifest: "mcp-servers/web-research/clauth-plugin.json" },
+  { repo: "rdc-skills", manifest: "clauth-plugin.json" },
+];
+
+// Sweep outcomes that mean "nothing was there to sync", as distinct from
+// "syncing it failed". Absence is expected on a partial checkout and must not
+// fail the sweep; a malformed manifest or a typo'd repo name must. Exported so
+// the CLI classifies receipts from the same list the audit receipt counts from.
+export const SYNC_SKIP_STATES = Object.freeze(["repo_root_missing", "manifest_missing", "repo_root_unknown"]);
+
+// The repo names syncPluginsFromRepos understands. Exported so a caller can
+// validate an override key up front rather than having a typo'd repo name
+// silently ignored and the sweep quietly read the default checkout instead.
+export const SYNC_REPO_NAMES = Object.freeze([...new Set(PRODUCT_REPO_MANIFESTS.map((entry) => entry.repo))]);
+
+// Mirrors expandPathToken()'s REGEN_ROOT resolution so a box that has already
+// pointed the manifest ${REGEN_ROOT} token somewhere resolves the sweep to the
+// same checkout rather than needing a second, differently-named env var.
+function defaultRepoRoot(repo) {
+  if (repo === "regen-root") return process.env.REGEN_ROOT || process.env.LIFEAI_REPO_ROOT || "C:/Dev/regen-root";
+  if (repo === "rdc-skills") return process.env.RDC_SKILLS_ROOT || "C:/Dev/rdc-skills";
+  return null;
+}
+
+/**
+ * Sweep the known product-repo manifest locations and register each one via the
+ * existing registerPlugin path (which owns validation, idempotence, and the
+ * managed-root containment assertion — none of it is re-implemented here).
+ *
+ * A missing repo root or a missing manifest WARNS AND CONTINUES. A box that has
+ * never checked out regen-root must still be able to sync whatever it does have,
+ * so absence is a reportable observation, never a thrown error.
+ *
+ * @param {Record<string,string>} [repoRoots] partial map of repo name -> root
+ *   path; any repo omitted falls back to its env/default root.
+ * @returns {Array<{repo:string,path:string,id:string|null,state:string,ok:boolean}>}
+ *   one receipt per ATTEMPTED manifest — this array is the return value, not a
+ *   persisted inventory.
+ */
+export function syncPluginsFromRepos(repoRoots = {}, actor = "localhost") {
+  const overrides = repoRoots && typeof repoRoots === "object" && !Array.isArray(repoRoots) ? repoRoots : {};
+  const receipts = [];
+  // An override key naming no known repo is a caller error, not a silent
+  // no-op: dropping it would sweep the DEFAULT checkout while reporting ✓ on
+  // every line, so the operator sees success from the wrong repo.
+  for (const key of Object.keys(overrides)) {
+    if (!SYNC_REPO_NAMES.includes(key)) {
+      receipts.push({ repo: key, path: null, id: null, state: "unknown_repo_name", ok: false, error: `unknown repo name — expected one of ${SYNC_REPO_NAMES.join(", ")}` });
+      appendSupervisorEvent({ kind: "plugin_sync_rejected", repo: key, manifest: null, reason: "unknown_repo_name" });
+    }
+  }
+
+  for (const { repo, manifest } of PRODUCT_REPO_MANIFESTS) {
+    const root = overrides[repo] || defaultRepoRoot(repo);
+    // Validate BEFORE path.resolve() — a non-string root makes path.resolve
+    // throw, which would abort the whole sweep and lose every later repo's
+    // receipt. This function's contract is that a bad or absent root is a
+    // reported observation, never a thrown error, and callers include HTTP.
+    if (typeof root !== "string" || !root.trim()) {
+      receipts.push({ repo, path: null, id: null, state: "repo_root_unknown", ok: false });
+      appendSupervisorEvent({ kind: "plugin_sync_skipped", repo, manifest, reason: "repo_root_unknown" });
+      continue;
+    }
+    const manifestPath = path.resolve(root, manifest);
+    if (!fs.existsSync(root)) {
+      receipts.push({ repo, path: manifestPath, id: null, state: "repo_root_missing", ok: false });
+      appendSupervisorEvent({ kind: "plugin_sync_skipped", repo, manifest: manifestPath, reason: "repo_root_missing" });
+      continue;
+    }
+    if (!fs.existsSync(manifestPath)) {
+      receipts.push({ repo, path: manifestPath, id: null, state: "manifest_missing", ok: false });
+      appendSupervisorEvent({ kind: "plugin_sync_skipped", repo, manifest: manifestPath, reason: "manifest_missing" });
+      continue;
+    }
+    let receipt;
+    try {
+      receipt = registerPlugin(manifestPath, actor);
+    } catch (error) {
+      // registerPlugin already returns receipts for the failure modes it knows
+      // about; this only catches an unforeseen throw so one bad manifest can
+      // never abort the rest of the sweep.
+      receipts.push({
+        repo,
+        path: manifestPath,
+        id: null,
+        state: "register_threw",
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      continue;
+    }
+    receipts.push({
+      repo,
+      path: manifestPath,
+      id: receipt.target?.plugin_id || null,
+      state: receipt.resulting_state?.state || "unknown",
+      ok: receipt.resulting_state?.ok === true,
+      operation_id: receipt.operationId,
+      error: receipt.resulting_state?.error || null,
+    });
+  }
+
+  // One audit receipt for the sweep itself (who swept, when, what happened).
+  // Counts only — deliberately not a stored list of what exists.
+  const isSkip = (entry) => SYNC_SKIP_STATES.includes(entry.state);
+  operation("plugin.sync", { repos: SYNC_REPO_NAMES }, null, {
+    ok: receipts.every((entry) => entry.ok || isSkip(entry)),
+    state: "sync_completed",
+    attempted: receipts.length,
+    registered: receipts.filter((entry) => entry.state === "registered").length,
+    unchanged: receipts.filter((entry) => entry.state === "unchanged").length,
+    skipped: receipts.filter(isSkip).length,
+    failed: receipts.filter((entry) => !entry.ok && !isSkip(entry)).length,
+  }, actor);
+
+  return receipts;
+}
+
+// Removes exactly one managed-plugin directory by id, then re-runs discovery so
+// the removal is reflected immediately. The inverse of registerPlugin — an id
+// reaching this function is attacker-influenced input (a CLI arg or an HTTP
+// field, with no manifest validation upstream to lean on) and this deletes
+// recursively, so both guards below are load-bearing.
+export function deregisterPlugin(id, actor = "localhost", { dryRun = false } = {}) {
+  const pluginId = String(id ?? "").trim();
+  // Guard 1 — charset + all-dots, the same rule a manifest id must satisfy.
+  //
+  // This one is NOT redundant with the containment assert below, and the
+  // containment assert is NOT a safety net for relaxing it. Measured: because
+  // path.resolve() normalizes `..` away and Windows re-anchors drive-relative
+  // paths, `sub/../web-research`, `C:web-research` and `web-research::$DATA`
+  // all resolve back INSIDE the root and sail through containment. Only the
+  // charset rule stops them. Relaxing it to admit a separator, a colon or a
+  // drive letter reopens a real hole — the tests pin all three forms.
+  if (!/^[a-zA-Z0-9_.-]+$/.test(pluginId) || /^\.+$/.test(pluginId)) {
+    return operation("plugin.deregister", { plugin_id: pluginId }, null, {
+      ok: false, state: "invalid_plugin_id", error: "plugin id may contain only letters, numbers, dot, underscore, and dash, and may not be all dots",
+    }, actor);
+  }
+  const roots = rootEntries();
+  const managedRoots = roots.filter((entry) => entry.source === "managed");
+  const prior = (loadSupervisorState().plugins || []).find((plugin) => plugin.id === pluginId) || null;
+
+  // Resolve the plugin's ACTUAL directory rather than assuming a flat
+  // <first-managed-root>/<id> layout. Three real layouts exist that assumption
+  // misses, and in every one of them a bare <root>/<id> probe finds nothing and
+  // would report a green "not_registered" while the plugin stays installed and
+  // ENABLED — the one receipt a removal verb must never get wrong:
+  //   1. a scoped npm package at <root>/@scope/pkg/ (findManifestFiles descends
+  //      one extra level for these; see the @scope arm above),
+  //   2. a plugin in the 2nd..Nth entry of a path-delimited
+  //      CLAUTH_MANAGED_PLUGIN_ROOTS,
+  //   3. a plugin in the USER root, which must be refused explicitly rather
+  //      than silently reported as absent.
+  // Discovery already records discovery_root + sourcePath per plugin, so the
+  // location comes from there when state knows the plugin.
+  let targetDir = null;
+  let containingRoot = null;
+  if (prior?.sourcePath && prior?.discovery_root) {
+    if (prior.source === "user") {
+      return operation("plugin.deregister", { plugin_id: pluginId }, prior, {
+        ok: false,
+        state: "not_managed",
+        error: "plugin is installed in a user plugin root; deregister only removes managed plugins",
+      }, actor);
+    }
+    targetDir = path.resolve(path.dirname(prior.sourcePath));
+    containingRoot = path.resolve(prior.discovery_root);
+  } else {
+    // State does not know this id (never discovered, or state was reset). Fall
+    // back to probing the flat layout in every managed root, not just the first.
+    for (const { root } of managedRoots) {
+      const candidate = path.resolve(root, pluginId);
+      if (fs.existsSync(candidate)) {
+        targetDir = candidate;
+        containingRoot = path.resolve(root);
+        break;
+      }
+    }
+  }
+
+  if (!targetDir || !containingRoot || !fs.existsSync(targetDir)) {
+    return operation("plugin.deregister", { plugin_id: pluginId }, prior, {
+      ok: true, state: "not_registered", plugin_state: "not_found", surfaces: [],
+    }, actor);
+  }
+
+  // Guard 2 — containment assert at the delete site, against the root that
+  // actually contains the plugin. Note the difference from registerPlugin:
+  // targetDir === containingRoot is a REJECT here, not an accept. This deletes
+  // a directory recursively, so a path resolving to the plugin root itself
+  // would take the entire root with it.
+  if (targetDir === containingRoot || !targetDir.startsWith(containingRoot + path.sep)) {
+    return operation("plugin.deregister", { plugin_id: pluginId }, prior, {
+      ok: false, state: "invalid_plugin_id", error: "resolved plugin directory escapes its plugin root",
+    }, actor);
+  }
+  if (!managedRoots.some((entry) => path.resolve(entry.root) === containingRoot)) {
+    return operation("plugin.deregister", { plugin_id: pluginId }, prior, {
+      ok: false, state: "not_managed", error: "resolved plugin directory is not inside a managed plugin root",
+    }, actor);
+  }
+  if (dryRun) {
+    return operation("plugin.deregister.dry_run", { plugin_id: pluginId }, prior, {
+      ok: true,
+      state: "would_deregister",
+      target_dir: targetDir,
+      plugin_state: prior?.state || "unknown",
+      surfaces: (prior?.surfaces || []).map((surface) => surface.id),
+    }, actor);
+  }
+  try {
+    fs.rmSync(targetDir, { recursive: true, force: true });
+  } catch (error) {
+    return operation("plugin.deregister", { plugin_id: pluginId }, prior, {
+      ok: false, state: "remove_failed", error: error instanceof Error ? error.message : String(error),
+    }, actor);
+  }
+  const discovery = discoverPlugins();
+  const after = discovery.plugins.find((plugin) => plugin.id === pluginId);
+  return operation("plugin.deregister", { plugin_id: pluginId }, prior, {
+    ok: true,
+    state: "deregistered",
+    plugin_state: after?.state || "not_found",
+    surfaces: (prior?.surfaces || []).map((surface) => surface.id),
+  }, actor);
+}
+
 export function listPlugins() {
   return loadSupervisorState().plugins || [];
 }