@lifeaitools/clauth 2.10.1 → 2.10.2

package/cli/index.js

@@ -150,7 +150,7 @@ import { runInstall } from './commands/install.js';
 import { runUninstall } from './commands/uninstall.js';
 import { runScrub } from './commands/scrub.js';
 import { runServe, MCP_TOOLS } from './commands/serve.js';
-import { deregisterPlugin, listPlugins, registerPlugin, syncPluginsFromRepos, SYNC_REPO_NAMES, SYNC_SKIP_STATES } from './supervisor-registry.js';
+import { deregisterPlugin, isMcpServerPlugin, listPlugins, registerPlugin, syncPluginsFromRepos, SYNC_REPO_NAMES, SYNC_SKIP_STATES } from './supervisor-registry.js';
 import { runOps } from './commands/ops.js';
 import { runOpsInstall } from './commands/ops-install.js';
 import { runNpm, runPublish } from './commands/npm.js';
@@ -927,20 +927,6 @@ tunnelCmd
 // ──────────────────────────────────────────────
 // clauth mcp list
 // ──────────────────────────────────────────────
-// Known MCP-server plugin ids in the managed fleet. Positive allowlist
-// rather than a naming heuristic (credential-name conventions and health
-// route "kind" vary across these) — dev-center and any future non-MCP
-// pm2-managed surface stay excluded by construction. Deliberately distinct
-// from `clauth list` (vault credential services); this never touches those.
-const MCP_SERVER_PLUGIN_IDS = new Set([
-  "fs-mcp",
-  "web-research",
-  "regen-media",
-  "regen-media-local",
-  "codeflow-mcp",
-  "rdc-skills",
-]);
-
 const mcpCmd = program.command("mcp").description("Inspect clauth's own MCP tool catalog and managed MCP-server surfaces");
 
 mcpCmd
@@ -951,7 +937,7 @@ mcpCmd
     for (const tool of MCP_TOOLS) {
       console.log(`  ${chalk.white(tool.name)}  ${chalk.gray(tool.description || "")}`);
     }
-    const mcpPlugins = listPlugins().filter((p) => MCP_SERVER_PLUGIN_IDS.has(p.id));
+    const mcpPlugins = listPlugins().filter(isMcpServerPlugin);
     console.log(chalk.cyan(`\n  Managed MCP-server surfaces (${mcpPlugins.length}):\n`));
     if (!mcpPlugins.length) {
       console.log(chalk.gray("  none discovered — is the daemon running? clauth serve"));
@@ -1047,10 +1033,16 @@ pluginCmd
   .command('deregister <id>')
   .description('Remove one managed plugin directory by id and re-run discovery. Removing an unregistered id is a safe no-op.')
   .option('--dry-run', 'Resolve and print the directory that would be deleted, without deleting it')
+  .option('--expected-root <path>', 'Refuse unless the registered plugin originated from this package root')
+  .option('--force', 'Recovery only: remove managed metadata even when process cleanup fails; receipt records the bypass')
   .action((id, opts) => {
     let receipt;
     try {
-      receipt = deregisterPlugin(id, 'cli', { dryRun: Boolean(opts.dryRun) });
+      receipt = deregisterPlugin(id, 'cli', {
+        dryRun: Boolean(opts.dryRun),
+        expectedRoot: opts.expectedRoot,
+        force: Boolean(opts.force),
+      });
     } catch (error) {
       console.error(`  ✗ deregister_failed: ${error instanceof Error ? error.message : String(error)}`);
       process.exitCode = 1;

package/cli/supervisor-registry.js

@@ -20,6 +20,65 @@ const DEFAULT_HEALTH_TIMEOUT_MS = 2500;
 const HEALTH_RECONCILE_COOLDOWN_MS = 15000;
 const DOCUMENTATION_FIELDS = ["architecture", "operator_guide", "install", "runbook", "tool_reference", "release", "agent_context"];
 
+function hasMcpToken(value) {
+  return /(^|[^a-z0-9])mcp([^a-z0-9]|$)/i.test(String(value || ""));
+}
+
+function routeDeclaresMcp(route) {
+  if (!route || typeof route !== "object") return false;
+  if (hasMcpToken(route.id) || hasMcpToken(route.kind)) return true;
+  try {
+    return new URL(String(route.url || "")).pathname
+      .split("/")
+      .some((segment) => segment.toLowerCase() === "mcp");
+  } catch {
+    return false;
+  }
+}
+
+function normalizeCapabilities(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return { kinds: [] };
+  const kinds = Array.isArray(value.kinds)
+    ? [...new Set(value.kinds.map((kind) => String(kind || "").trim().toLowerCase())
+      .filter((kind) => /^[a-z0-9_.-]+$/.test(kind)))]
+    : [];
+  return { kinds };
+}
+
+function normalizeMcpContract(value) {
+  if (value === true) return { declared: true, transport: null, url: null, stdio: [], tools: [] };
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return {
+    declared: true,
+    transport: value.transport ? String(value.transport) : null,
+    url: value.url ? String(value.url) : null,
+    stdio: normalizeCommand(value.stdio, "mcp.stdio"),
+    tools: Array.isArray(value.tools)
+      ? value.tools.map((tool) => String(tool || "").trim()).filter((tool) => /^[a-zA-Z0-9_.-]+$/.test(tool))
+      : [],
+  };
+}
+
+/**
+ * Classify an MCP server from its own manifest contract. New plugins declare
+ * `mcp` or `capabilities.kinds`; route/name/document signals retain backwards
+ * compatibility with manifests created before those fields existed.
+ */
+export function isMcpServerPlugin(plugin) {
+  if (!plugin || typeof plugin !== "object") return false;
+  if (plugin.mcp === true || (plugin.mcp && typeof plugin.mcp === "object")) return true;
+  if ((plugin.capabilities?.kinds || []).some((kind) => ["mcp", "mcp-server"].includes(String(kind).toLowerCase()))) return true;
+
+  const routes = [
+    ...(Array.isArray(plugin.routes) ? plugin.routes : []),
+    ...(Array.isArray(plugin.surfaces) ? plugin.surfaces.flatMap((surface) => surface?.routes || []) : []),
+  ];
+  if (routes.some(routeDeclaresMcp)) return true;
+  if (hasMcpToken(plugin.id)) return true;
+  if ((plugin.surfaces || []).some((surface) => hasMcpToken(surface?.id) || hasMcpToken(surface?.name))) return true;
+  return hasMcpToken(plugin.documentation?.agent_context);
+}
+
 export function getSupervisorPort() {
   return Number(process.env.CLAUTH_SUPERVISOR_PORT || DEFAULT_SUPERVISOR_PORT);
 }
@@ -454,6 +513,7 @@ export function validatePluginManifest(manifest, sourcePath = "") {
     core: manifest.core === true,
     enable_default: manifest.enable_default === true,
     sourcePath,
+    package_root: manifest._clauth?.package_root ? path.resolve(String(manifest._clauth.package_root)) : null,
     destination: normalizeDestination(manifest.destination),
     lifecycle_owner: normalizeLifecycleOwner(manifest.lifecycle_owner),
     credentials: Array.isArray(manifest.credentials) ? manifest.credentials.map((c) => ({
@@ -462,6 +522,8 @@ export function validatePluginManifest(manifest, sourcePath = "") {
       description: String(c.description || ""),
       required: c.required !== false,
     })).filter((c) => /^[a-zA-Z0-9_.-]+$/.test(c.name)) : [],
+    capabilities: normalizeCapabilities(manifest.capabilities),
+    mcp: normalizeMcpContract(manifest.mcp),
     surfaces: [],
     routes: Array.isArray(manifest.routes) ? manifest.routes : [],
     test: manifest.test && typeof manifest.test === "object" ? {
@@ -472,6 +534,7 @@ export function validatePluginManifest(manifest, sourcePath = "") {
     } : null,
   };
   plugin.surfaces = (Array.isArray(manifest.surfaces) ? manifest.surfaces : []).map((surface) => normalizeSurface(surface, plugin));
+  plugin.mcp_server = isMcpServerPlugin(plugin);
   return plugin;
 }
 
@@ -635,7 +698,10 @@ export function registerPlugin(manifestPath, actor = "localhost") {
     .replace(/%PACKAGE_ROOT%/gi, packageRoot);
   let manifest;
   try {
-    manifest = validatePluginManifest(JSON.parse(raw), manifestPath);
+    const parsed = JSON.parse(raw);
+    parsed._clauth = { package_root: packageRoot };
+    raw = `${JSON.stringify(parsed, null, 2)}\n`;
+    manifest = validatePluginManifest(parsed, manifestPath);
   } catch (error) {
     return operation("plugin.register", { manifest_path: manifestPath }, null, {
       ok: false, state: "manifest_invalid", error: error instanceof Error ? error.message : String(error),
@@ -820,7 +886,7 @@ export function syncPluginsFromRepos(repoRoots = {}, actor = "localhost") {
 // 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 } = {}) {
+export function deregisterPlugin(id, actor = "localhost", { dryRun = false, expectedRoot = null, force = false } = {}) {
   const pluginId = String(id ?? "").trim();
   // Guard 1 — charset + all-dots, the same rule a manifest id must satisfy.
   //
@@ -838,7 +904,7 @@ export function deregisterPlugin(id, actor = "localhost", { dryRun = false } = {
   }
   const roots = rootEntries();
   const managedRoots = roots.filter((entry) => entry.source === "managed");
-  const prior = (loadSupervisorState().plugins || []).find((plugin) => plugin.id === pluginId) || null;
+  let 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
@@ -899,6 +965,26 @@ export function deregisterPlugin(id, actor = "localhost", { dryRun = false } = {
       ok: false, state: "not_managed", error: "resolved plugin directory is not inside a managed plugin root",
     }, actor);
   }
+  if (!prior) {
+    prior = discoverPlugins().plugins.find((plugin) => plugin.id === pluginId) || null;
+  }
+  if (expectedRoot) {
+    const expected = path.resolve(String(expectedRoot));
+    if (!prior?.package_root) {
+      return operation("plugin.deregister", { plugin_id: pluginId }, prior, {
+        ok: false, state: "ownership_unverified", error: "registered plugin has no package-root ownership record; re-register it before deregistering",
+      }, actor);
+    }
+    const actual = path.resolve(prior.package_root);
+    const matches = process.platform === "win32"
+      ? actual.toLowerCase() === expected.toLowerCase()
+      : actual === expected;
+    if (!matches) {
+      return operation("plugin.deregister", { plugin_id: pluginId }, prior, {
+        ok: false, state: "ownership_mismatch", error: `registered package root ${actual} does not match expected root ${expected}`,
+      }, actor);
+    }
+  }
   if (dryRun) {
     return operation("plugin.deregister.dry_run", { plugin_id: pluginId }, prior, {
       ok: true,
@@ -906,8 +992,43 @@ export function deregisterPlugin(id, actor = "localhost", { dryRun = false } = {
       target_dir: targetDir,
       plugin_state: prior?.state || "unknown",
       surfaces: (prior?.surfaces || []).map((surface) => surface.id),
+      package_root: prior?.package_root || null,
     }, actor);
   }
+
+  const cleanup = [];
+  const seenStopCommands = new Set();
+  for (const surface of prior?.surfaces || []) {
+    if (surface.lifecycle_owner !== "clauth" || surface.destination !== "local/clauth/pm2") continue;
+    const signature = `${surface.cwd || ""}\0${JSON.stringify(surface.stop || [])}`;
+    if (seenStopCommands.has(signature)) continue;
+    seenStopCommands.add(signature);
+    if (!Array.isArray(surface.stop) || surface.stop.length === 0) {
+      const unavailable = { surface_id: surface.id, ok: false, state: "command_missing", forced: Boolean(force) };
+      cleanup.push(unavailable);
+      if (!force) {
+        return operation("plugin.deregister", { plugin_id: pluginId }, prior, {
+          ok: false, state: "surface_cleanup_unavailable", error: `managed surface ${surface.id} has no stop command`, cleanup,
+        }, actor);
+      }
+      continue;
+    }
+    const stopReceipt = runSurfaceAction(`${pluginId}:${surface.id}`, "stop", actor);
+    const summary = {
+      surface_id: surface.id,
+      ok: stopReceipt.resulting_state?.ok === true,
+      state: stopReceipt.resulting_state?.state || stopReceipt.error || "unknown",
+    };
+    cleanup.push(summary);
+    if (!summary.ok) {
+      summary.forced = Boolean(force);
+      if (!force) {
+        return operation("plugin.deregister", { plugin_id: pluginId }, prior, {
+          ok: false, state: "surface_cleanup_failed", error: `failed to stop managed surface ${surface.id}`, cleanup,
+        }, actor);
+      }
+    }
+  }
   try {
     fs.rmSync(targetDir, { recursive: true, force: true });
   } catch (error) {
@@ -919,9 +1040,12 @@ export function deregisterPlugin(id, actor = "localhost", { dryRun = false } = {
   const after = discovery.plugins.find((plugin) => plugin.id === pluginId);
   return operation("plugin.deregister", { plugin_id: pluginId }, prior, {
     ok: true,
-    state: "deregistered",
+    state: force && cleanup.some((entry) => !entry.ok) ? "deregistered_forced" : "deregistered",
     plugin_state: after?.state || "not_found",
     surfaces: (prior?.surfaces || []).map((surface) => surface.id),
+    cleanup,
+    forced: Boolean(force),
+    evidence: force && cleanup.some((entry) => !entry.ok) ? ["force_cleanup_bypass=true"] : [],
   }, actor);
 }
 

package/cli/supervisor-registry.test.js

@@ -9,6 +9,7 @@ import {
   deregisterPlugin,
   discoverPlugins,
   getClauthPm2Home,
+  isMcpServerPlugin,
   listPlugins,
   listSurfaces,
   probeAllSurfaceHealth,
@@ -88,6 +89,7 @@ function baseManifest(id, overrides = {}) {
       lifecycle_owner: "clauth",
       port: 39111,
       health: "/health",
+      stop: [process.execPath, "--version"],
       restart: ["node", "--version"],
     }],
     test: { command: ["node", "--version"], port: "auto", health: "/health", selfTest: [["node", "--version"]] },
@@ -111,6 +113,50 @@ test("validatePluginManifest accepts LIFEAI plugin contract with isolated test c
   assert.equal(plugin.documentation.operator_guide, "docs/systems/example/OPERATE.md");
 });
 
+test("MCP-server classification is derived from manifest capabilities and legacy contract signals", () => {
+  const rtp = validatePluginManifest(baseManifest("rtp", {
+    capabilities: { kinds: ["cli", "http-service", "mcp-server"] },
+    mcp: {
+      transport: "http+stdio",
+      url: "http://127.0.0.1:3116/mcp",
+      stdio: ["node", "bin/rtp.mjs", "mcp"],
+      tools: ["rtp_query", "rtp_parse"],
+    },
+  }));
+  assert.equal(isMcpServerPlugin(rtp), true);
+  assert.deepEqual(rtp.capabilities.kinds, ["cli", "http-service", "mcp-server"]);
+  assert.deepEqual(rtp.mcp.tools, ["rtp_query", "rtp_parse"]);
+
+  const legacyMcpManifests = [
+    baseManifest("codeflow-mcp"),
+    baseManifest("fs-mcp"),
+    baseManifest("rdc-skills", {
+      routes: [{ id: "provider", kind: "external", url: "https://rdc-skills.example/mcp" }],
+    }),
+    baseManifest("regen-media", {
+      routes: [{ id: "provider", kind: "external", url: "https://media.example/mcp" }],
+    }),
+    baseManifest("web-research", {
+      documentation: {
+        architecture: "ARCHITECTURE.md",
+        agent_context: ".claude/context/web-research-mcp.md",
+      },
+    }),
+    baseManifest("regen-media-local", {
+      documentation: {
+        architecture: "ARCHITECTURE.md",
+        agent_context: ".claude/context/mcp-endpoint-design.md",
+      },
+    }),
+  ];
+  for (const manifest of legacyMcpManifests) {
+    assert.equal(isMcpServerPlugin(validatePluginManifest(manifest)), true, manifest.id);
+  }
+
+  assert.equal(isMcpServerPlugin(validatePluginManifest(baseManifest("dev-center"))), false);
+  assert.equal(isMcpServerPlugin(validatePluginManifest(baseManifest("factory-test-plugin"))), false);
+});
+
 test("validatePluginManifest accepts empty test command arrays from the v1 template", () => {
   const plugin = validatePluginManifest(baseManifest("empty-test-command", {
     test: { command: [], port: "auto", health: "/health", selfTest: [] },
@@ -625,6 +671,7 @@ test("registerPlugin validates, writes into the managed root, and discovers the
   assert.equal(written, true);
   const found = listPlugins().find((plugin) => plugin.id === "registered-demo");
   assert.equal(found.enabled, true);
+  assert.equal(found.package_root, path.resolve(sourceDir));
 
   const second = registerPlugin(manifestPath, "test");
   assert.equal(second.resulting_state.state, "unchanged", "re-registering identical content must be a no-op, not a rewrite");
@@ -763,6 +810,8 @@ test("deregisterPlugin removes only the named plugin and leaves siblings intact"
   const receipt = deregisterPlugin("web-research", "test");
   assert.equal(receipt.resulting_state.ok, true);
   assert.equal(receipt.resulting_state.state, "deregistered");
+  assert.equal(receipt.resulting_state.cleanup.length, 1);
+  assert.equal(receipt.resulting_state.cleanup[0].ok, true);
   assert.equal(fs.existsSync(path.join(managed, "web-research")), false, "the named plugin directory is gone");
 
   for (const sibling of ["codeflow-mcp", "dev-center", "regen-media", "rdc-skills"]) {
@@ -887,6 +936,63 @@ test("deregisterPlugin removes a scoped @scope/pkg plugin instead of falsely rep
   assert.equal(after.state, "missing_default");
 }));
 
+test("deregisterPlugin proves package-root ownership before stopping or deleting", () => withTempSupervisor((root) => {
+  const managed = path.join(root, "managed");
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
+  const sourceDir = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-owned-source-"));
+  const manifestPath = path.join(sourceDir, "clauth-plugin.json");
+  fs.writeFileSync(manifestPath, JSON.stringify(baseManifest("owned-demo", { core: true, enable_default: true })), "utf8");
+  assert.equal(registerPlugin(manifestPath, "test").resulting_state.ok, true);
+
+  const wrong = deregisterPlugin("owned-demo", "test", { expectedRoot: path.join(root, "other-install") });
+  assert.equal(wrong.resulting_state.ok, false);
+  assert.equal(wrong.resulting_state.state, "ownership_mismatch");
+  assert.equal(fs.existsSync(path.join(managed, "owned-demo")), true, "ownership mismatch deleted the plugin");
+
+  const correct = deregisterPlugin("owned-demo", "test", { expectedRoot: sourceDir });
+  assert.equal(correct.resulting_state.ok, true);
+  assert.equal(correct.resulting_state.state, "deregistered");
+  assert.deepEqual(correct.resulting_state.cleanup.map((entry) => entry.ok), [true]);
+  assert.equal(fs.existsSync(path.join(managed, "owned-demo")), false);
+  fs.rmSync(sourceDir, { recursive: true, force: true });
+}));
+
+test("deregisterPlugin requires an explicit audited force to recover stale metadata after its stop executable disappears", () => withTempSupervisor((root) => {
+  const managed = path.join(root, "managed");
+  process.env.CLAUTH_MANAGED_PLUGIN_ROOTS = managed;
+  process.env.CLAUTH_USER_PLUGIN_ROOTS = path.join(root, "user");
+  const sourceDir = fs.mkdtempSync(path.join(os.tmpdir(), "clauth-stale-source-"));
+  const manifestPath = path.join(sourceDir, "clauth-plugin.json");
+  fs.writeFileSync(manifestPath, JSON.stringify(baseManifest("stale-demo", {
+    core: true,
+    enable_default: true,
+    surfaces: [{
+      id: "primary",
+      destination: "local/clauth/pm2",
+      lifecycle_owner: "clauth",
+      port: 39111,
+      health: "/health",
+      stop: [process.execPath, path.join(sourceDir, "removed-stop-script.cjs")],
+    }],
+  })), "utf8");
+  assert.equal(registerPlugin(manifestPath, "test").resulting_state.ok, true);
+
+  const ordinary = deregisterPlugin("stale-demo", "test", { expectedRoot: sourceDir });
+  assert.equal(ordinary.resulting_state.ok, false);
+  assert.equal(ordinary.resulting_state.state, "surface_cleanup_failed");
+  assert.equal(fs.existsSync(path.join(managed, "stale-demo")), true, "default failure must preserve recovery metadata");
+
+  const forced = deregisterPlugin("stale-demo", "test", { force: true });
+  assert.equal(forced.resulting_state.ok, true);
+  assert.equal(forced.resulting_state.state, "deregistered_forced");
+  assert.equal(forced.resulting_state.cleanup[0].ok, false);
+  assert.equal(forced.resulting_state.cleanup[0].forced, true);
+  assert.deepEqual(forced.evidence, ["force_cleanup_bypass=true"]);
+  assert.equal(fs.existsSync(path.join(managed, "stale-demo")), false);
+  fs.rmSync(sourceDir, { recursive: true, force: true });
+}));
+
 test("deregisterPlugin finds a plugin in a non-first managed root and refuses a user-root plugin", () => withTempSupervisor((root) => {
   // CLAUTH_MANAGED_PLUGIN_ROOTS is a path-delimited LIST; honoring only the
   // first entry silently reports a real plugin as absent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/clauth",
-  "version": "2.10.1",
+  "version": "2.10.2",
   "description": "Hardware-bound credential vault for the LIFEAI infrastructure stack",
   "type": "module",
   "bin": {