refactor(plugin): migrate plugin system to use allowlist policy and improve security

- Rename all plugin-related commands from 'plugins' to 'plugin' scope
- Implement plugin allowlist policy with required scopes (e.g., @ali)
- Add security checks to prevent unauthorized plugin installation
- Restrict npm child process environment variables to prevent credential leaks
- Enhance plugin validation with scope and allowlist verification
- Add proper error handling for malformed plugin manifests
- Introduce noAuthSetup validation to ensure rules match plugin commands
- Move plugin commands to dedicated subdirectory structure
- Add comprehensive plugin policy enforcement functions
- Update tests and fixtures to use new @ali scoped plugin naming

Author: hopelynd

packages/cli/src/commands/catalog.ts

@@ -35,10 +35,10 @@ import consoleCall from "./console/call.ts";
 import usageFree from "./usage/free.ts";
 import pipelineRun from "./pipeline/run.ts";
 import pipelineValidate from "./pipeline/validate.ts";
-import pluginsList from "./plugins/list.ts";
-import pluginsInstall from "./plugins/install.ts";
-import pluginsLink from "./plugins/link.ts";
-import pluginsRemove from "./plugins/remove.ts";
+import pluginList from "./plugin/list.ts";
+import pluginInstall from "./plugin/install.ts";
+import pluginLink from "./plugin/link.ts";
+import pluginRemove from "./plugin/remove.ts";
 
 /** Command registry map (no dependency on registry.ts — safe for build-time import). */
 export const commands: Record<string, Command> = {
@@ -73,10 +73,10 @@ export const commands: Record<string, Command> = {
   "usage free": usageFree,
   "pipeline run": pipelineRun,
   "pipeline validate": pipelineValidate,
-  "plugins list": pluginsList,
-  "plugins install": pluginsInstall,
-  "plugins link": pluginsLink,
-  "plugins remove": pluginsRemove,
+  "plugin list": pluginList,
+  "plugin install": pluginInstall,
+  "plugin link": pluginLink,
+  "plugin remove": pluginRemove,
   "config show": configShow,
   "config set": configSet,
   "config export-schema": configExportSchema,

packages/cli/src/commands/config/export-schema.ts

@@ -8,7 +8,7 @@ import { loadCommandCatalog } from "../../load-commands.ts";
 /**
  * Commands that are infrastructure/auth-related and not suitable as Agent tools.
  */
-const SKIP_PREFIXES = ["auth ", "config ", "update", "plugins "];
+const SKIP_PREFIXES = ["auth ", "config ", "update", "plugin "];
 
 export default defineCommand({
   name: "config export-schema",

…ages/cli/src/commands/plugins/install.ts …kages/cli/src/commands/plugin/install.tspackages/cli/src/commands/plugins/install.ts renamed to packages/cli/src/commands/plugin/install.ts packages/cli/src/commands/plugins/install.ts renamed to packages/cli/src/commands/plugin/install.ts

@@ -10,13 +10,13 @@ import { resetCommandCatalogCache } from "../../load-commands.ts";
 import { createRegistry, resetRegistry } from "../../registry.ts";
 
 export default defineCommand({
-  name: "plugins install",
+  name: "plugin install",
   description: "Install a bailian-cli plugin package into ~/.bailian/plugins",
-  usage: "bl plugins install <package>",
+  usage: "bl plugin install <package>",
   options: [],
   examples: [
-    "bl plugins install @ali/bailian-plugin-agent",
-    "bl plugins install bailian-plugin-agent",
+    "bl plugin install @ali/bailian-plugin-agent",
+    "bl plugin install bailian-plugin-agent",
   ],
   async run(_config: Config, flags: GlobalFlags) {
     const positional = flags._positional as string[] | undefined;
@@ -25,7 +25,7 @@ export default defineCommand({
       throw new BailianError(
         "Missing plugin package name.",
         ExitCode.USAGE,
-        "bl plugins install <package>",
+        "bl plugin install <package>",
       );
     }
 

packages/cli/src/commands/plugins/link.ts packages/cli/src/commands/plugin/link.tspackages/cli/src/commands/plugins/link.ts renamed to packages/cli/src/commands/plugin/link.ts

@@ -10,15 +10,15 @@ import { resetCommandCatalogCache } from "../../load-commands.ts";
 import { createRegistry, resetRegistry } from "../../registry.ts";
 
 export default defineCommand({
-  name: "plugins link",
+  name: "plugin link",
   description: "Link a local bailian-cli plugin directory",
-  usage: "bl plugins link <path>",
-  examples: ["bl plugins link ../bailian-plugin-agent"],
+  usage: "bl plugin link <path>",
+  examples: ["bl plugin link ../bailian-plugin-agent"],
   async run(_config: Config, flags: GlobalFlags) {
     const positional = flags._positional as string[] | undefined;
     const pluginPath = positional?.[0];
     if (!pluginPath) {
-      throw new BailianError("Missing plugin path.", ExitCode.USAGE, "bl plugins link <path>");
+      throw new BailianError("Missing plugin path.", ExitCode.USAGE, "bl plugin link <path>");
     }
 
     await linkPlugin(pluginPath);

packages/cli/src/commands/plugins/list.ts packages/cli/src/commands/plugin/list.tspackages/cli/src/commands/plugins/list.ts renamed to packages/cli/src/commands/plugin/list.ts

@@ -2,10 +2,10 @@ import { defineCommand, type Config, type GlobalFlags } from "bailian-cli-core";
 import { listPlugins } from "../../plugins/manager.ts";
 
 export default defineCommand({
-  name: "plugins list",
+  name: "plugin list",
   description: "List installed and discovered bailian-cli plugins",
-  usage: "bl plugins list",
-  examples: ["bl plugins list"],
+  usage: "bl plugin list",
+  examples: ["bl plugin list"],
   async run(_config: Config, flags: GlobalFlags) {
     const { plugins, errors } = await listPlugins();
     const format = flags.output === "json" ? "json" : "text";

…kages/cli/src/commands/plugins/remove.ts …ckages/cli/src/commands/plugin/remove.tspackages/cli/src/commands/plugins/remove.ts renamed to packages/cli/src/commands/plugin/remove.ts packages/cli/src/commands/plugins/remove.ts renamed to packages/cli/src/commands/plugin/remove.ts

@@ -10,15 +10,15 @@ import { resetCommandCatalogCache } from "../../load-commands.ts";
 import { createRegistry, resetRegistry } from "../../registry.ts";
 
 export default defineCommand({
-  name: "plugins remove",
+  name: "plugin remove",
   description: "Remove an installed bailian-cli plugin",
-  usage: "bl plugins remove <name>",
-  examples: ["bl plugins remove bailian-plugin-agent"],
+  usage: "bl plugin remove <name>",
+  examples: ["bl plugin remove bailian-plugin-agent"],
   async run(_config: Config, flags: GlobalFlags) {
     const positional = flags._positional as string[] | undefined;
     const name = positional?.[0];
     if (!name) {
-      throw new BailianError("Missing plugin name.", ExitCode.USAGE, "bl plugins remove <name>");
+      throw new BailianError("Missing plugin name.", ExitCode.USAGE, "bl plugin remove <name>");
     }
 
     await removePlugin(name);

packages/cli/src/load-commands.ts

@@ -12,16 +12,17 @@ import {
 } from "./plugins/cache.ts";
 import { discoverPlugins } from "./plugins/discover.ts";
 import { mergeCommands, type PluginCommandEntry } from "./plugins/priority.ts";
-import { extractCommandMeta, lazyCommandFromMeta, scanPluginCommands } from "./plugins/scan.ts";
+import {
+  extractCommandMeta,
+  filterValidNoAuthSetup,
+  lazyCommandFromMeta,
+  scanPluginCommands,
+} from "./plugins/scan.ts";
 import type { CommandCatalog, DiscoveredPlugin, PluginLoadError } from "./plugins/types.ts";
 import { CLI_VERSION } from "./version.ts";
 
 let cachedCatalog: CommandCatalog | undefined;
 
-function collectNoAuthSetup(plugin: DiscoveredPlugin): string[] {
-  return (plugin.bailianCli.noAuthSetup ?? []).map((p) => p.trim()).filter(Boolean);
-}
-
 function expandNoAuthSetup(paths: string[]): string[][] {
   return paths.map((p) => p.split(/\s+/).filter(Boolean));
 }
@@ -64,22 +65,20 @@ async function loadPluginCommandsWithCache(plugins: DiscoveredPlugin[]): Promise
 
     if (useCache) needsWrite = true;
 
-    const { commands: scanned, error } = await scanPluginCommands(plugin);
-    if (error) pluginErrors.push(error);
-
-    const noAuthPaths = collectNoAuthSetup(plugin);
-    for (const paths of expandNoAuthSetup(noAuthPaths)) {
-      noAuthSetup.push(paths);
-    }
+    const { commands: scanned, error: scanError } = await scanPluginCommands(plugin);
+    const scanFailed = scanError !== undefined;
+    if (scanError) pluginErrors.push(scanError);
 
     const metas = [];
+    let loadFailed = false;
     for (const item of scanned) {
       const meta = await extractCommandMeta(item);
       if (!meta) {
         pluginErrors.push({
           plugin: plugin.name,
           message: `Could not load command module: ${item.commandPath}`,
         });
+        loadFailed = true;
         continue;
       }
       metas.push(meta);
@@ -90,11 +89,22 @@ async function loadPluginCommandsWithCache(plugins: DiscoveredPlugin[]): Promise
       });
     }
 
-    if (useCache) {
+    const { paths: validNoAuthPaths, errors: noAuthErrors } = filterValidNoAuthSetup(
+      plugin,
+      scanned.map((item) => item.commandPath),
+    );
+    pluginErrors.push(...noAuthErrors);
+    for (const paths of expandNoAuthSetup(validNoAuthPaths)) {
+      noAuthSetup.push(paths);
+    }
+
+    // Do not cache partial or failed scans so the next startup retries loading.
+    const canCache = !scanFailed && !loadFailed;
+    if (useCache && canCache) {
       nextPlugins[plugin.name] = {
         fingerprint,
         commands: metas,
-        noAuthSetup: noAuthPaths,
+        noAuthSetup: validNoAuthPaths,
       };
     }
   }
@@ -146,7 +156,3 @@ export async function loadCommandCatalog(): Promise<CommandCatalog> {
 export function resetCommandCatalogCache(): void {
   cachedCatalog = undefined;
 }
-
-export function getCachedCommandCatalog(): CommandCatalog | undefined {
-  return cachedCatalog;
-}

packages/cli/src/main.ts

@@ -37,10 +37,10 @@ const BUILTIN_NO_AUTH_SETUP: string[][] = [
   ["app", "list"],
   ["console", "call"],
   ["usage", "free"],
-  ["plugins", "list"],
-  ["plugins", "install"],
-  ["plugins", "link"],
-  ["plugins", "remove"],
+  ["plugin", "list"],
+  ["plugin", "install"],
+  ["plugin", "link"],
+  ["plugin", "remove"],
 ];
 
 function matchesNoAuthSetup(commandPath: string[], rules: string[][]): boolean {

packages/cli/src/plugins/discover.ts

@@ -8,6 +8,7 @@ import {
   type BailianCliPackageMeta,
 } from "bailian-cli-core";
 import { getNodeModuleRoots } from "./paths.ts";
+import { isPluginAllowed } from "./policy.ts";
 import type { DiscoveredPlugin, UserPluginRecord, UserPluginsManifest } from "./types.ts";
 
 const PACKAGE_JSON = "package.json";
@@ -40,6 +41,8 @@ function toDiscovered(
   if (!name || !pjson.bailianCli) return undefined;
   if (!isBailianPluginPackage(name, pjson.bailianCli)) return undefined;
   if (!pjson.bailianCli.commands) return undefined;
+  // white list check
+  if (!isPluginAllowed(name)) return undefined;
   return {
     name,
     root,

packages/cli/src/plugins/manager.ts

@@ -14,13 +14,16 @@ import { resetCommandCatalogCache } from "../load-commands.ts";
 import { clearCommandsCache } from "./cache.ts";
 import { discoverPlugins, readPackageJson } from "./discover.ts";
 import {
+  buildNpmEnv,
   diffAddedDepNames,
+  parsePackageNameFromSpec,
   pickInstalledPackageName,
-  readSandboxPjsonDepNames,
+  readSandboxDeps,
   resolveSandboxPackageRoot,
   topLevelDepNamesFromNpmLs,
   type NpmLsNode,
 } from "./npm-sandbox.ts";
+import { assertPluginAllowed } from "./policy.ts";
 import type { UserPluginsManifest } from "./types.ts";
 
 const INIT_MANIFEST: UserPluginsManifest = {
@@ -44,7 +47,11 @@ async function readManifest(): Promise<UserPluginsManifest> {
       },
     };
   } catch {
-    return structuredClone(INIT_MANIFEST);
+    throw new BailianError(
+      `Plugin manifest at ${path} is corrupted and could not be parsed.`,
+      ExitCode.GENERAL,
+      "Restore from backup or delete the file, then run bl plugin install again.",
+    );
   }
 }
 
@@ -90,7 +97,7 @@ function runNpm(args: string[], cwd: string): void {
   const result = spawnSync("npm", npmArgs, {
     cwd,
     stdio: "inherit",
-    env: process.env,
+    env: buildNpmEnv(),
   });
   if (result.status !== 0) {
     throw new BailianError(
@@ -106,7 +113,7 @@ function runNpmJson(args: string[], cwd: string): NpmLsNode {
   const result = spawnSync("npm", npmArgs, {
     cwd,
     encoding: "utf8",
-    env: process.env,
+    env: buildNpmEnv(),
   });
   const stdout = result.stdout?.trim();
   if (!stdout) {
@@ -125,7 +132,7 @@ async function listTopLevelSandboxDeps(pluginsDir: string): Promise<string[]> {
     const tree = runNpmJson(["ls", "--json", "--depth=0"], pluginsDir);
     return topLevelDepNamesFromNpmLs(tree);
   } catch {
-    return readSandboxPjsonDepNames(pluginsDir);
+    return readSandboxDeps(pluginsDir);
   }
 }
 
@@ -183,6 +190,7 @@ export async function listPlugins(): Promise<{
 export async function linkPlugin(pluginPath: string): Promise<void> {
   const root = resolve(pluginPath);
   const { name } = await validatePluginPackageAsync(root);
+  assertPluginAllowed(name);
   const manifest = await readManifest();
   const plugins = manifest.bailianCli!.plugins!.filter(
     (p) => !(p.type === "link" && p.name === name),
@@ -194,6 +202,16 @@ export async function linkPlugin(pluginPath: string): Promise<void> {
 
 /** 安装 npm 插件到用户沙箱 */
 export async function installPlugin(packageSpec: string): Promise<string> {
+  // 安装前先按 spec 解析包名做准入校验,避免对不被允许的包执行任何 npm 操作
+  const specName = parsePackageNameFromSpec(packageSpec);
+  if (!specName) {
+    throw new BailianError(
+      `无法从 "${packageSpec}" 识别 npm 包名(不支持 git / tarball / 本地路径安装)。目前仅支持安装官方白名单插件(@ali 作用域),暂不支持用户自定义插件。`,
+      ExitCode.USAGE,
+    );
+  }
+  assertPluginAllowed(specName);
+
   const pluginsDir = getPluginsDir();
   await mkdir(pluginsDir, { recursive: true, mode: 0o700 });
 
@@ -202,8 +220,10 @@ export async function installPlugin(packageSpec: string): Promise<string> {
   }
 
   const beforeDeps = await listTopLevelSandboxDeps(pluginsDir);
-
-  runNpm(["install", packageSpec, "--save-exact", "--no-fund", "--no-audit"], pluginsDir);
+  runNpm(
+    ["install", packageSpec, "--save-exact", "--ignore-scripts", "--no-fund", "--no-audit"],
+    pluginsDir,
+  );
 
   const afterDeps = await listTopLevelSandboxDeps(pluginsDir);
   const added = diffAddedDepNames(beforeDeps, afterDeps);
@@ -223,6 +243,7 @@ export async function installPlugin(packageSpec: string): Promise<string> {
 
   const root = resolveSandboxPackageRoot(pluginsDir, packageName);
   const { name } = await validatePluginPackageAsync(root);
+  assertPluginAllowed(name);
 
   const manifest = await readManifest();
   const plugins = manifest.bailianCli!.plugins!.filter((p) => p.name !== name);
@@ -232,7 +253,7 @@ export async function installPlugin(packageSpec: string): Promise<string> {
   return name;
 }
 
-/** 从用户沙箱移除插件 */
+/** remove plugin from user sandbox */
 export async function removePlugin(name: string): Promise<void> {
   const manifest = await readManifest();
   const record = manifest.bailianCli!.plugins!.find((p) => p.name === name);
@@ -243,9 +264,9 @@ export async function removePlugin(name: string): Promise<void> {
   if (record.type === "user") {
     const pluginsDir = getPluginsDir();
     try {
-      runNpm(["uninstall", name, "--no-fund", "--no-audit"], pluginsDir);
+      runNpm(["uninstall", name, "--ignore-scripts", "--no-fund", "--no-audit"], pluginsDir);
     } catch {
-      /* 包可能已被手动删除 */
+      /* package may have been manually deleted */
     }
   }