@lamalibre/portlama-agent 1.0.21 → 1.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lamalibre/portlama-agent",
-  "version": "1.0.21",
+  "version": "1.0.22",
   "description": "Tunnel agent for Portlama — manages Chisel tunnel client as a system service",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/commands/panel.js

@@ -24,9 +24,9 @@ const DEFAULT_PANEL_PORT = 9393;
 
 /**
  * @param {string[]} args
- * @param {{ label: string }} options
+ * @param {{ label: string, json?: boolean }} options
  */
-export async function runPanel(args, { label }) {
+export async function runPanel(args, { label, json: globalJson = false }) {
   assertSupportedPlatform();
 
   const config = await loadAgentConfig(label);
@@ -35,9 +35,10 @@ export async function runPanel(args, { label }) {
     process.exit(1);
   }
 
-  const isJson = args.includes('--json');
+  const isJson = globalJson || args.includes('--json');
   const isEnable = args.includes('--enable');
   const isDisable = args.includes('--disable');
+  const isLocalOnly = args.includes('--local-only');
   const isStatus = args.includes('--status') || (!isEnable && !isDisable);
 
   // Parse --port flag
@@ -51,24 +52,24 @@ export async function runPanel(args, { label }) {
   }
 
   if (isEnable) {
-    await enablePanel(label, config, port, isJson);
+    await enablePanel(label, config, port, isJson, isLocalOnly);
   } else if (isDisable) {
-    await disablePanel(label, config, isJson);
+    await disablePanel(label, config, isJson, isLocalOnly);
   } else if (isStatus) {
     await showStatus(label, config, isJson);
   }
 }
 
-async function enablePanel(label, config, port, isJson) {
+async function enablePanel(label, config, port, isJson, localOnly = false) {
   // 1. Check if already enabled
   const loaded = await isPanelLoaded(label);
   if (loaded) {
     if (isJson) {
-      console.log(JSON.stringify({ error: 'Panel service already running' }));
+      console.log(JSON.stringify({ ok: true, alreadyRunning: true, port: config.panelPort || port }));
     } else {
       console.log(chalk.yellow('Panel service is already running.'));
     }
-    process.exit(1);
+    return;
   }
 
   // 2. Generate and write service config
@@ -78,7 +79,24 @@ async function enablePanel(label, config, port, isJson) {
   // 3. Start the panel service
   await loadPanelService(label);
 
-  // 4. Create the tunnel on the panel server
+  // 4. Save panel config
+  config.panelPort = port;
+  config.panelEnabled = true;
+  config.updatedAt = new Date().toISOString();
+  await saveAgentConfig(label, config);
+
+  // 5. If local-only, skip tunnel exposure and chisel restart
+  if (localOnly) {
+    if (isJson) {
+      console.log(JSON.stringify({ ok: true, port }));
+    } else {
+      console.log(chalk.green('\nAgent panel started locally.'));
+      console.log(`  Port: ${chalk.cyan(port)}`);
+    }
+    return;
+  }
+
+  // 6. Create the tunnel on the panel server
   let tunnel;
   try {
     const result = await exposePanelTunnel(config, port);
@@ -87,6 +105,9 @@ async function enablePanel(label, config, port, isJson) {
     // Rollback: stop the panel service we just started
     await unloadPanelService(label);
     await removePanelServiceConfig(label);
+    config.panelEnabled = false;
+    delete config.panelPort;
+    await saveAgentConfig(label, config);
     const msg = err instanceof Error ? err.message : 'Unknown error';
     if (isJson) {
       console.log(JSON.stringify({ error: msg }));
@@ -96,13 +117,7 @@ async function enablePanel(label, config, port, isJson) {
     process.exit(1);
   }
 
-  // 5. Save panel config
-  config.panelPort = port;
-  config.panelEnabled = true;
-  config.updatedAt = new Date().toISOString();
-  await saveAgentConfig(label, config);
-
-  // 6. Update the agent's chisel service (needs new tunnel mapping)
+  // 7. Update the agent's chisel service (needs new tunnel mapping)
   try {
     const { fetchAgentConfig } = await import('../lib/panel-api.js');
     const { generateServiceConfig, writeServiceConfigFile } =
@@ -132,14 +147,16 @@ async function enablePanel(label, config, port, isJson) {
   }
 }
 
-async function disablePanel(label, config, isJson) {
-  // 1. Retract the tunnel
-  try {
-    await retractPanelTunnel(config);
-  } catch (err) {
-    if (!isJson) {
-      const msg = err instanceof Error ? err.message : 'Unknown error';
-      console.log(chalk.yellow(`Warning: Could not retract panel tunnel: ${msg}`));
+async function disablePanel(label, config, isJson, localOnly = false) {
+  // 1. Retract the tunnel (skip in local-only mode)
+  if (!localOnly) {
+    try {
+      await retractPanelTunnel(config);
+    } catch (err) {
+      if (!isJson) {
+        const msg = err instanceof Error ? err.message : 'Unknown error';
+        console.log(chalk.yellow(`Warning: Could not retract panel tunnel: ${msg}`));
+      }
     }
   }
 
@@ -149,21 +166,23 @@ async function disablePanel(label, config, isJson) {
   // 3. Remove service config
   await removePanelServiceConfig(label);
 
-  // 4. Update chisel (remove the panel tunnel mapping)
-  try {
-    const { fetchAgentConfig } = await import('../lib/panel-api.js');
-    const { generateServiceConfig, writeServiceConfigFile } =
-      await import('../lib/service-config.js');
-    const { unloadAgent, loadAgent } = await import('../lib/service.js');
-    const agentConfig = await fetchAgentConfig(config);
-    const serviceContent = generateServiceConfig(agentConfig.chiselArgs, label);
-    await writeServiceConfigFile(serviceContent, label);
-    await unloadAgent(label);
-    await loadAgent(label);
-  } catch (err) {
-    if (!isJson) {
-      const msg = err instanceof Error ? err.message : 'Unknown error';
-      console.log(chalk.yellow(`Warning: Could not restart chisel: ${msg}`));
+  // 4. Update chisel (remove the panel tunnel mapping) — skip in local-only mode
+  if (!localOnly) {
+    try {
+      const { fetchAgentConfig } = await import('../lib/panel-api.js');
+      const { generateServiceConfig, writeServiceConfigFile } =
+        await import('../lib/service-config.js');
+      const { unloadAgent, loadAgent } = await import('../lib/service.js');
+      const agentConfig = await fetchAgentConfig(config);
+      const serviceContent = generateServiceConfig(agentConfig.chiselArgs, label);
+      await writeServiceConfigFile(serviceContent, label);
+      await unloadAgent(label);
+      await loadAgent(label);
+    } catch (err) {
+      if (!isJson) {
+        const msg = err instanceof Error ? err.message : 'Unknown error';
+        console.log(chalk.yellow(`Warning: Could not restart chisel: ${msg}`));
+      }
     }
   }
 
@@ -176,7 +195,7 @@ async function disablePanel(label, config, isJson) {
   if (isJson) {
     console.log(JSON.stringify({ ok: true }));
   } else {
-    console.log(chalk.green('Agent panel retracted.'));
+    console.log(chalk.green(localOnly ? 'Agent panel stopped.' : 'Agent panel retracted.'));
   }
 }
 

package/src/commands/plugin.js

@@ -1,46 +1,12 @@
 import chalk from 'chalk';
-import { execa } from 'execa';
-import { readFile, writeFile, rename, open, mkdir, rm } from 'node:fs/promises';
-import { createRequire } from 'node:module';
-import path from 'node:path';
-import { assertSupportedPlatform, agentDataDir, agentPluginsFile, agentPluginsDir } from '../lib/platform.js';
+import { assertSupportedPlatform } from '../lib/platform.js';
 import { validateLabel } from '../lib/registry.js';
-
-/**
- * Read the local plugin registry.
- * @param {string} label - Agent label
- */
-async function readLocalPlugins(label) {
-  try {
-    const raw = await readFile(agentPluginsFile(label), 'utf-8');
-    const parsed = JSON.parse(raw);
-    return Array.isArray(parsed.plugins) ? parsed : { plugins: [] };
-  } catch (err) {
-    if (err.code === 'ENOENT') {
-      return { plugins: [] };
-    }
-    throw new Error(`Failed to read local plugin registry: ${err.message}`);
-  }
-}
-
-/**
- * Write the local plugin registry atomically.
- * @param {string} label - Agent label
- * @param {object} data
- */
-async function writeLocalPlugins(label, data) {
-  const pluginsFile = agentPluginsFile(label);
-  const tmpPath = `${pluginsFile}.tmp`;
-
-  const content = JSON.stringify(data, null, 2) + '\n';
-  await writeFile(tmpPath, content, { encoding: 'utf-8', mode: 0o600 });
-
-  const fd = await open(tmpPath, 'r');
-  await fd.sync();
-  await fd.close();
-
-  await rename(tmpPath, pluginsFile);
-}
+import {
+  readAgentPluginRegistry,
+  installAgentPlugin,
+  uninstallAgentPlugin,
+  updateAgentPlugin,
+} from '../lib/agent-plugins.js';
 
 /**
  * Install a plugin locally on the agent.
@@ -48,71 +14,14 @@ async function writeLocalPlugins(label, data) {
  * @param {string} packageName
  */
 async function installLocal(label, packageName) {
-  if (!packageName.startsWith('@lamalibre/')) {
-    console.error(chalk.red('  Only @lamalibre/ scoped packages are allowed'));
-    process.exit(1);
-  }
-
-  const registry = await readLocalPlugins(label);
-  const existing = registry.plugins.find((p) => p.packageName === packageName);
-  if (existing) {
-    console.log(chalk.yellow(`  Plugin "${packageName}" is already installed`));
-    return;
-  }
-
   console.log(chalk.cyan(`  Installing ${packageName}...`));
-
-  // Ensure agent dir has a package.json so npm installs locally
-  const agentDir = agentDataDir(label);
-  await mkdir(agentDir, { recursive: true, mode: 0o700 });
-  const agentPkgJson = path.join(agentDir, 'package.json');
-  try {
-    await readFile(agentPkgJson, 'utf-8');
-  } catch (err) {
-    if (err.code === 'ENOENT') {
-      await writeFile(agentPkgJson, '{"private":true}\n', { encoding: 'utf-8', mode: 0o600 });
-    }
-  }
-
   try {
-    await execa('npm', ['install', '--ignore-scripts', packageName], { cwd: agentDir, stdio: 'inherit' });
+    const entry = await installAgentPlugin(label, packageName);
+    console.log(chalk.green(`  Plugin "${entry.name}" installed`));
   } catch (err) {
-    console.error(chalk.red(`  Failed to install: ${err.message}`));
-    process.exit(1);
-  }
-
-  // Read the plugin manifest
-  let manifest;
-  try {
-    const require = createRequire(path.join(agentDir, '/'));
-    const manifestPath = require.resolve(`${packageName}/portlama-plugin.json`);
-    const manifestRaw = await readFile(manifestPath, 'utf-8');
-    manifest = JSON.parse(manifestRaw);
-  } catch {
-    console.log(chalk.yellow('  Warning: No portlama-plugin.json found — registering with package name only'));
-    manifest = { name: packageName.replace('@lamalibre/', ''), version: 'unknown' };
-  }
-
-  // Validate manifest name to prevent path traversal
-  if (!/^[a-z0-9-]+$/.test(manifest.name)) {
-    console.error(chalk.red(`  Invalid plugin name: "${manifest.name}"`));
+    console.error(chalk.red(`  ${err.message}`));
     process.exit(1);
   }
-
-  // Create local plugin directory
-  const pluginDir = path.join(agentPluginsDir(label), manifest.name);
-  await mkdir(pluginDir, { recursive: true, mode: 0o700 });
-
-  registry.plugins.push({
-    name: manifest.name,
-    packageName,
-    version: manifest.version,
-    installedAt: new Date().toISOString(),
-    status: 'installed',
-  });
-
-  await writeLocalPlugins(label, registry);
-  console.log(chalk.green(`  Plugin "${manifest.name}" installed`));
 }
 
 /**
@@ -121,38 +30,24 @@ async function installLocal(label, packageName) {
  * @param {string} nameOrPackage
  */
 async function uninstallLocal(label, nameOrPackage) {
-  const registry = await readLocalPlugins(label);
-  const index = registry.plugins.findIndex(
+  // Resolve name from registry if a package name was given
+  const registry = await readAgentPluginRegistry(label);
+  const plugin = registry.plugins.find(
     (p) => p.name === nameOrPackage || p.packageName === nameOrPackage,
   );
-
-  if (index === -1) {
+  if (!plugin) {
     console.error(chalk.red(`  Plugin "${nameOrPackage}" not found`));
     process.exit(1);
   }
 
-  const plugin = registry.plugins[index];
-
-  if (!plugin.packageName.startsWith('@lamalibre/')) {
-    console.error(chalk.red('  Registry corruption: invalid package scope'));
-    process.exit(1);
-  }
-
   console.log(chalk.cyan(`  Uninstalling ${plugin.packageName}...`));
-
   try {
-    await execa('npm', ['uninstall', plugin.packageName], { cwd: agentDataDir(label), stdio: 'inherit' });
+    await uninstallAgentPlugin(label, plugin.name);
+    console.log(chalk.green(`  Plugin "${plugin.name}" uninstalled`));
   } catch (err) {
-    console.log(chalk.yellow(`  npm uninstall warning: ${err.message}`));
+    console.error(chalk.red(`  ${err.message}`));
+    process.exit(1);
   }
-
-  // Remove local plugin directory
-  const pluginDir = path.join(agentPluginsDir(label), plugin.name);
-  await rm(pluginDir, { recursive: true, force: true }).catch(() => {});
-
-  registry.plugins.splice(index, 1);
-  await writeLocalPlugins(label, registry);
-  console.log(chalk.green(`  Plugin "${plugin.name}" uninstalled`));
 }
 
 /**
@@ -161,45 +56,14 @@ async function uninstallLocal(label, nameOrPackage) {
  * @param {string} nameOrPackage
  */
 async function updateLocal(label, nameOrPackage) {
-  const registry = await readLocalPlugins(label);
-  const plugin = registry.plugins.find(
-    (p) => p.name === nameOrPackage || p.packageName === nameOrPackage,
-  );
-
-  if (!plugin) {
-    console.error(chalk.red(`  Plugin "${nameOrPackage}" not found`));
-    process.exit(1);
-  }
-
-  if (!plugin.packageName.startsWith('@lamalibre/')) {
-    console.error(chalk.red('  Registry corruption: invalid package scope'));
-    process.exit(1);
-  }
-
-  console.log(chalk.cyan(`  Updating ${plugin.packageName}...`));
-
-  const agentDir = agentDataDir(label);
+  console.log(chalk.cyan(`  Updating ${nameOrPackage}...`));
   try {
-    await execa('npm', ['install', '--ignore-scripts', plugin.packageName], { cwd: agentDir, stdio: 'inherit' });
+    const plugin = await updateAgentPlugin(label, nameOrPackage);
+    console.log(chalk.green(`  Plugin "${plugin.name}" updated to v${plugin.version}`));
   } catch (err) {
-    console.error(chalk.red(`  Failed to update: ${err.message}`));
+    console.error(chalk.red(`  ${err.message}`));
     process.exit(1);
   }
-
-  // Re-read manifest to capture the updated version
-  try {
-    const require = createRequire(path.join(agentDir, '/'));
-    const manifestPath = require.resolve(`${plugin.packageName}/portlama-plugin.json`);
-    const manifestRaw = await readFile(manifestPath, 'utf-8');
-    const manifest = JSON.parse(manifestRaw);
-    plugin.version = manifest.version || plugin.version;
-  } catch {
-    // Manifest may not exist — keep existing version
-  }
-
-  plugin.updatedAt = new Date().toISOString();
-  await writeLocalPlugins(label, registry);
-  console.log(chalk.green(`  Plugin "${plugin.name}" updated`));
 }
 
 /**
@@ -207,7 +71,7 @@ async function updateLocal(label, nameOrPackage) {
  * @param {string} label - Agent label
  */
 async function showStatus(label) {
-  const registry = await readLocalPlugins(label);
+  const registry = await readAgentPluginRegistry(label);
   const b = chalk.bold;
   const c = chalk.cyan;
   const d = chalk.dim;

package/src/commands/update.js

@@ -84,6 +84,36 @@ export async function runUpdate({ label }) {
           });
         },
       },
+      {
+        title: 'Reporting installed plugins',
+        task: async (_ctx, task) => {
+          const { readAgentPluginRegistry } = await import('../lib/agent-plugins.js');
+          const registry = await readAgentPluginRegistry(label);
+          const enabledPlugins = registry.plugins.filter((p) => p.status === 'enabled');
+          if (enabledPlugins.length === 0) {
+            task.skip('No enabled plugins');
+            return;
+          }
+          const pluginReport = enabledPlugins.map((p) => ({
+            name: p.name,
+            version: p.version,
+            capabilities: p.capabilities || [],
+          }));
+          try {
+            const { curlAuthenticatedJson } = await import('../lib/panel-api.js');
+            await curlAuthenticatedJson(config, [
+              '-X', 'POST',
+              '-H', 'Content-Type: application/json',
+              '-d', JSON.stringify({ plugins: pluginReport }),
+              `${config.panelUrl}/api/agents/plugins/report`,
+            ]);
+            task.output = `Reported ${enabledPlugins.length} plugin(s)`;
+          } catch {
+            task.skip('Server does not support plugin reporting yet');
+          }
+        },
+        rendererOptions: { persistentOutput: true },
+      },
     ],
     {
       renderer: 'default',

package/src/index.js

@@ -163,7 +163,7 @@ export async function main() {
       const { runPanel } = await import('./commands/panel.js');
       const { resolveLabel } = await import('./lib/registry.js');
       const resolved = await resolveLabel(label);
-      await runPanel(args.slice(1), { label: resolved });
+      await runPanel(args.slice(1), { label: resolved, json });
       break;
     }
     case 'list': {

package/src/lib/agent-plugin-router.js

@@ -0,0 +1,141 @@
+/**
+ * Agent plugin router — mounts enabled plugin server routes and serves
+ * panel bundles on the agent panel server.
+ *
+ * Registered as a Fastify plugin under '/api/plugins' prefix in panel-server.js.
+ * mTLS validation is handled by the parent panel server (panel-server.js),
+ * so no additional auth guard is needed here.
+ *
+ * Combines patterns from:
+ * - plugin-router.js (server-side two-level encapsulation)
+ * - local-plugin-host.js (CJS/ESM plugin loading)
+ */
+
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { readAgentPluginRegistry } from './agent-plugins.js';
+import { agentDataDir, agentPluginsDir } from './platform.js';
+
+// Reserved prefixes that are never plugin route names.
+const RESERVED_PREFIXES = new Set(['install']);
+
+/**
+ * Fastify plugin that mounts agent plugin routes and panel bundles.
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {{ label: string }} opts
+ */
+export default async function agentPluginRouter(fastify, { label }) {
+  const registry = await readAgentPluginRegistry(label);
+  const dir = agentDataDir(label);
+  const pluginsDir = agentPluginsDir(label);
+
+  for (const plugin of registry.plugins) {
+    if (plugin.status !== 'enabled') continue;
+
+    const pluginName = plugin.name;
+
+    if (plugin.packages?.server) {
+      // Defense-in-depth: verify scope at load time
+      if (!plugin.packages.server.startsWith('@lamalibre/')) {
+        fastify.log.error(
+          { plugin: pluginName },
+          'Plugin server package scope violation — skipping',
+        );
+        continue;
+      }
+
+      try {
+        const require = createRequire(path.join(dir, '/'));
+        const modulePath = require.resolve(plugin.packages.server);
+        let serverModule;
+        try {
+          // Try require first (CJS packages)
+          serverModule = require(plugin.packages.server);
+        } catch {
+          // Fall back to dynamic import (ESM packages)
+          serverModule = await import(modulePath);
+        }
+
+        // Resolve the Fastify plugin function from the module.
+        let pluginFn = serverModule.default || serverModule;
+        if (typeof pluginFn !== 'function' && typeof serverModule.buildPlugin === 'function') {
+          pluginFn = serverModule.buildPlugin();
+        }
+
+        if (typeof pluginFn === 'function') {
+          const pluginDir = path.join(pluginsDir, pluginName) + '/';
+
+          // Two-level encapsulation: outer scope isolates the plugin code from
+          // the router's hooks, preventing plugins from overriding auth or
+          // adding hooks above their encapsulation boundary.
+          await fastify.register(async function pluginScope(outer) {
+            await outer.register(pluginFn, {
+              pluginDir,
+              logger: fastify.log,
+            });
+          }, { prefix: `/${pluginName}` });
+          fastify.log.info({ plugin: pluginName }, 'Agent plugin routes mounted');
+        }
+      } catch (err) {
+        fastify.log.error(
+          { plugin: pluginName, err: err.message },
+          'Failed to mount agent plugin routes',
+        );
+      }
+    }
+
+    // Serve plugin panel bundle
+    if (plugin.packages?.server) {
+      const serverPkg = plugin.packages.server;
+      fastify.get(`/${pluginName}/panel.js`, async (_request, reply) => {
+        try {
+          if (!serverPkg.startsWith('@lamalibre/')) {
+            return reply.code(403).send({ error: 'Plugin server package scope violation' });
+          }
+          const require = createRequire(path.join(dir, '/'));
+          const panelPath = require.resolve(`${serverPkg}/panel.js`);
+          const content = await readFile(panelPath, 'utf-8');
+          return reply
+            .header('Content-Type', 'application/javascript')
+            .header('Cache-Control', 'public, max-age=3600')
+            .send(content);
+        } catch {
+          return reply.code(404).send({ error: 'Plugin panel bundle not found' });
+        }
+      });
+    }
+  }
+
+  // --- Disabled plugin catch-all ---
+
+  let cachedDisabledPlugins = new Set();
+  let cacheExpiry = 0;
+
+  async function getDisabledPlugins() {
+    const now = Date.now();
+    if (now < cacheExpiry) return cachedDisabledPlugins;
+
+    const currentRegistry = await readAgentPluginRegistry(label);
+    cachedDisabledPlugins = new Set(
+      currentRegistry.plugins.filter((p) => p.status !== 'enabled').map((p) => p.name),
+    );
+    cacheExpiry = now + 5000;
+    return cachedDisabledPlugins;
+  }
+
+  fastify.addHook('onRequest', async (request, reply) => {
+    // Match /<pluginName>/... under the /api/plugins prefix
+    const match = request.url.match(/^\/([a-z0-9-]+)(\/|$)/);
+    if (!match) return;
+
+    const name = match[1];
+    if (RESERVED_PREFIXES.has(name)) return;
+
+    const disabled = await getDisabledPlugins();
+    if (disabled.has(name)) {
+      return reply.code(503).send({ error: `Plugin "${name}" is disabled` });
+    }
+  });
+}