@lamalibre/create-lamaste 4.3.1 → 4.4.0

package/vendor/server/src/commands/plugins.js

@@ -27,8 +27,9 @@
  *   hooks <name>         The plugin's lifecycle hooks and what needs approval: the relay
  *                        hook set (stages, routes, fail-open hooks, effects), the agent
  *                        half Lamaste installs, the approval digest; agent hooks
- *   approve-hooks <name> --digest <sha256>
- *                        Approve with the approval digest `hooks` shows (or a pending update's)
+ *   approve-hooks <name> --digest <sha256> [--version <v>]
+ *                        Approve with the approval digest `hooks` shows; a pending update with
+ *                        its version too (`--version` alone when it has no digest)
  *   auto-approve <name> on|off
  *                        Approve what this plugin's later versions bring automatically (audited)
  *   update <name> [--version <v>]
@@ -45,6 +46,12 @@
  *                        followed to its end
  *   forget-data <name> --agent <label>
  *                        Drop only the relay's record of it; the data stays on the agent
+ *   settings <name>      An agent-hosted plugin's settings: each field's value (a secret
+ *                        only as set or not), whether it still needs configuration,
+ *                        where the values come from, the hosting
+ *   configure <name> [--set key=value]... [--clear key]... [--secrets-stdin]
+ *                        Change them (kept by its agent half); in a terminal without
+ *                        flags, field by field — a secret never on the command line
  *
  * Every subcommand goes through the running panel (`/api/plugins/*`, admin
  * certificate): the panel owns the plugin registry (SQLite `state.db`), runs
@@ -61,6 +68,14 @@ import { AGENT_LABEL_REGEX } from '@lamalibre/lamaste';
 import { PANEL_SERVICE } from '../config.js';
 import { panelRequest } from '../panel-api.js';
 import { emit, emitStep, emitError, emitComplete, emitLog } from '../ndjson.js';
+import { configureCmd, settingsCmd } from './plugin-settings.js';
+import { settingsDiffLines, terminalText } from '../plugin-settings.js';
+import {
+  APPROVE_HOOKS_USAGE,
+  approveHooksCommand,
+  parseApproveArgs,
+  pendingUpdateReasons,
+} from '../plugin-approval.js';
 
 /** npm runs inside the panel for install and uninstall (its own limit is 120 s). */
 const NPM_CALL_TIMEOUT_MS = 180_000;
@@ -115,6 +130,10 @@ export async function runPlugins(args, { json }) {
       return purgeDataCmd(args.slice(1), { json });
     case 'forget-data':
       return forgetDataCmd(args.slice(1), { json });
+    case 'settings':
+      return settingsCmd(args.slice(1), { json });
+    case 'configure':
+      return configureCmd(args.slice(1), { json });
     default:
       printPluginUsage();
       process.exit(sub ? 1 : 0);
@@ -148,8 +167,9 @@ ${b('Subcommands:')}
   ${c('rotate-hosting-secret <name>')}
                        New installation secret (the agent fetches it on its next sync)
   ${c('hooks <name>')}         Lifecycle hooks and what needs approval: relay hooks, agent half
-  ${c('approve-hooks <name> --digest <sha256>')}
-                       Approve with the approval digest "hooks" showed (or a pending update's)
+  ${c('approve-hooks <name> --digest <sha256> [--version <v>]')}
+                       Approve with the approval digest "hooks" showed; a pending update
+                       with its version too (--version alone when it has no digest)
   ${c('auto-approve <name> on|off')}
                        Approve what this plugin's later versions bring automatically
   ${c('update <name> [--version <v>]')}
@@ -164,6 +184,13 @@ ${b('Subcommands:')}
                        Delete it on the agent — its data directory and account (a push)
   ${c('forget-data <name> --agent <label>')}
                        Drop only the relay's record; the data stays on the agent
+  ${c('settings <name>')}      Settings of an agent-hosted plugin: values (secrets only as set or
+                       not), what is missing, where they come from, the hosting
+  ${c('configure <name> [--set key=value]... [--clear key]... [--secrets-stdin]')}
+                       Change them: --set parses by the field's type (never a secret),
+                       --clear puts a field back to its default or clears a secret,
+                       --secrets-stdin reads {"key": "value" | null} from stdin;
+                       in a terminal without flags, asked field by field
 `);
 }
 
@@ -732,11 +759,14 @@ function printAgentHalf(agentHalf, title) {
 
 /**
  * Print what a version brings that needs approval — the approval digest
- * (the one value `approve-hooks` takes), its relay hook set and the agent
- * half Lamaste installs.
+ * (what `approve-hooks` takes; none for an update that brings neither
+ * relay hooks nor an agent half Lamaste installs), its relay hook set and
+ * the agent half Lamaste installs.
  */
 function printApprovalContents({ digest, relay, agentHalf }) {
-  console.log(`    approval digest: ${chalk.cyan(digest)}`);
+  console.log(
+    `    approval digest: ${digest ? chalk.cyan(digest) : chalk.dim('none — no relay hooks, no agent half Lamaste installs')}`,
+  );
   if (relay) {
     console.log('');
     printRelayHookSet(relay, 'Relay hooks — run in a sandbox on the relay');
@@ -747,9 +777,43 @@ function printApprovalContents({ digest, relay, agentHalf }) {
   }
 }
 
-/** The command that approves `digest` for plugin `name`. */
-function approveCommand(name, digest) {
-  return chalk.cyan(`lamaste-server plugins approve-hooks ${name} --digest ${digest}`);
+/**
+ * Print an update that waits for approval under `title`: why it waits
+ * (`approvalRequired` — a secret turned plain in red), what it brings
+ * (its digest, relay hook set and agent half), how it changes the settings
+ * schema (outside the digest) — fields added and removed with their types,
+ * retyped ones, newly required ones, and a warning for secrets that become
+ * plain values — what auto-approve could not cover beyond the reasons, and
+ * the command that approves it.
+ */
+function printPendingUpdate(name, update, title) {
+  console.log('');
+  console.log(chalk.bold(`  ${title}`));
+  const { required, notCovered } = pendingUpdateReasons(update);
+  for (const line of required) {
+    console.log(line.warning ? chalk.red(`    - ${line.text}`) : `    - ${line.text}`);
+  }
+  console.log('');
+  printApprovalContents(update);
+  const lines = settingsDiffLines(update.settings);
+  if (lines.length > 0) {
+    console.log('');
+    console.log(chalk.bold('  Settings — what this version changes (not part of the digest)'));
+    for (const line of lines) {
+      console.log(`    ${line.warning ? chalk.red(line.text) : line.text}`);
+    }
+  }
+  if (notCovered.length > 0) {
+    console.log('');
+    console.log(chalk.bold('  Auto-approve does not cover it'));
+    for (const reason of notCovered) console.log(chalk.yellow(`    ${reason}`));
+  }
+  console.log(`\n    Approve and update with: ${approveCommand(name, update)}`);
+}
+
+/** The command that approves the installed version (`{ digest }`) or a pending update (`{ digest, version }`). */
+function approveCommand(name, target) {
+  return chalk.cyan(approveHooksCommand(name, target));
 }
 
 /**
@@ -794,7 +858,7 @@ async function hooksCmd(name, { json }) {
       `\n    auto-approve for later versions: ${hooks.autoApprove ? chalk.yellow('on') : 'off'}`,
     );
     if (approval.state !== 'approved') {
-      console.log(`\n    Approve with: ${approveCommand(name, approval.digest)}`);
+      console.log(`\n    Approve with: ${approveCommand(name, { digest: approval.digest })}`);
     }
   }
   if (hooks.agent) {
@@ -805,10 +869,11 @@ async function hooksCmd(name, { json }) {
   }
   if (hooks.pendingUpdate) {
     const update = hooks.pendingUpdate;
-    console.log('');
-    console.log(chalk.bold(`  Update to ${update.version} — waits for approval`));
-    printApprovalContents(update);
-    console.log(`\n    Approve and update with: ${approveCommand(name, update.digest)}`);
+    printPendingUpdate(
+      name,
+      update,
+      `Update to ${terminalText(update.version)} — waits for your approval:`,
+    );
   }
   console.log('');
 }
@@ -819,18 +884,16 @@ async function hooksCmd(name, { json }) {
  * @param {{ json: boolean }} options
  */
 async function approveHooksCmd(name, rest, { json }) {
-  const idx = rest.indexOf('--digest');
-  const digest = idx !== -1 ? rest[idx + 1] : undefined;
-  if (!name || !digest || !/^[a-f0-9]{64}$/.test(digest)) {
-    fail(
-      'Usage: lamaste-server plugins approve-hooks <name> --digest <sha256> (the approval digest `hooks <name>` shows)',
-      json,
-    );
-  }
+  if (!name) fail(APPROVE_HOOKS_USAGE, json);
+  const args = parseApproveArgs(rest);
+  if (args.error) fail(args.error, json);
+  const { digest, version } = args;
   let result;
   try {
+    // A version names the pending update; its digest, when it has one, goes with it.
     result = await panelRequest('POST', `/api/plugins/${encodeURIComponent(name)}/hooks/approve`, {
       digest,
+      ...(version ? { version } : {}),
     });
   } catch (err) {
     // Approving a pending update starts it: its agent half is a push.
@@ -899,10 +962,12 @@ async function updateCmd(name, rest, { json }) {
       return;
     }
     const update = result.pendingUpdate;
+    printPendingUpdate(
+      name,
+      update,
+      `${name} ${terminalText(update.version)} waits for your approval:`,
+    );
     console.log('');
-    console.log(chalk.bold(`  ${name} ${update.version} waits for approval`));
-    printApprovalContents(update);
-    console.log(`\n    Approve and update with: ${approveCommand(name, update.digest)}\n`);
     return;
   }
   if (!json) console.log(`\n  Updating ${chalk.cyan(name)}`);
@@ -1111,7 +1176,9 @@ async function installPluginCmd(packageName, { json }) {
       agentHalf: result.hooks.agentHalf,
     });
     if (approval.state === 'pending') {
-      console.log(`\n    Approve with: ${approveCommand(plugin.name, approval.digest)}`);
+      console.log(
+        `\n    Approve with: ${approveCommand(plugin.name, { digest: approval.digest })}`,
+      );
     }
     console.log('');
   }

package/vendor/server/src/panel-api.js

@@ -22,6 +22,7 @@ import { mkdtemp, open, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { execa } from 'execa';
+import { SETTINGS_KEY_RE } from '@lamalibre/lamaste';
 import { PKI_DIR, readConfig } from './config.js';
 import { PANEL_LOOPBACK, assertPanelListener, readPanelIdentity } from './panel-identity.js';
 
@@ -244,12 +245,31 @@ function detailsText(details) {
   return [...new Set(found)].join('; ');
 }
 
+/**
+ * The per-field messages of a refused settings change (`errors`: a setting
+ * key, or `_` for the change as a whole, to a message), or null when the
+ * panel sent none. Only string messages under a key a setting can have are
+ * kept — the panel's and the agent half's messages never contain a value.
+ *
+ * @param {unknown} errors
+ * @returns {Record<string, string> | null}
+ */
+function settingsErrors(errors) {
+  if (errors === null || typeof errors !== 'object' || Array.isArray(errors)) return null;
+  const kept = Object.entries(errors).filter(
+    ([key, message]) => (key === '_' || SETTINGS_KEY_RE.test(key)) && typeof message === 'string',
+  );
+  return kept.length > 0 ? Object.fromEntries(kept) : null;
+}
+
 /**
  * Split curl's output (`<payload>\n<status>`) and turn a non-2xx status
  * into an error carrying the panel's `error` (and `details`) in its message,
  * the status as `statusCode`, and what a caller acts on beyond the message
- * when the panel sent it: `code` (e.g. `agent_not_eligible`), `reasons` and
- * a running operation's `operationId`. Pure, exported for tests.
+ * when the panel sent it: `code` (e.g. `agent_not_eligible`), `reasons`, a
+ * running operation's `operationId`, and for a refused settings change its
+ * per-field `errors`, the current `revision` (`revision_mismatch`) and the
+ * `hosting` (`hosting_offline`). Pure, exported for tests.
  *
  * @param {string} stdout
  * @param {string} method
@@ -282,6 +302,17 @@ export function parsePanelResponse(stdout, method, path) {
       err.reasons = parsed.reasons.filter((r) => typeof r === 'string');
     }
     if (typeof parsed.operationId === 'string') err.operationId = parsed.operationId;
+    const errors = settingsErrors(parsed.errors);
+    if (errors) err.errors = errors;
+    if (Number.isSafeInteger(parsed.revision) && parsed.revision >= 0) {
+      err.revision = parsed.revision;
+    }
+    if (
+      parsed.hosting === null ||
+      (typeof parsed.hosting === 'object' && !Array.isArray(parsed.hosting))
+    ) {
+      err.hosting = parsed.hosting;
+    }
     throw err;
   }
 
@@ -337,8 +368,9 @@ export async function curlPanelRequest({
  * client certificate (mTLS); neither the P12 password nor the body is ever
  * in curl's arguments. Resolves with the JSON body; rejects with an Error
  * (`statusCode`, the panel's `error` in the message, a refusal's `code`,
- * `reasons` and `operationId`) for any non-2xx answer, and with one that
- * says why when the request could not be made.
+ * `reasons` and `operationId`, a refused settings change's `errors`,
+ * `revision` and `hosting`) for any non-2xx answer, and with one that says
+ * why when the request could not be made.
  *
  * @param {string} method
  * @param {string} path  e.g. '/api/tunnels'

package/vendor/server/src/plugin-approval.js

@@ -0,0 +1,78 @@
+/**
+ * `lamaste-server plugins hooks|update|approve-hooks`: why an update waits
+ * for approval, the command that approves it, and the arguments that
+ * command takes. Pure — no output — so they are tested as they are.
+ */
+
+import { terminalText } from './plugin-settings.js';
+
+const DIGEST_RE = /^[a-f0-9]{64}$/;
+const VERSION_RE = /^[0-9A-Za-z.+-]{1,64}$/;
+/** The reason an update turns secret settings into plain ones. */
+const SETTINGS_SECRET_TO_PLAIN = 'settings.secret-to-plain';
+
+/** How `approve-hooks` is called. */
+export const APPROVE_HOOKS_USAGE =
+  'Usage: lamaste-server plugins approve-hooks <name> --digest <sha256> [--version <v>] (what `hooks <name>` shows)';
+
+/**
+ * Why a pending update waits, as the terminal shows it: each reason of
+ * `approvalRequired` (`[{ code, reason }]`; a secret turned plain is a
+ * warning), and the sentences of `autoApproveWithheld` that do not repeat
+ * one of them — what auto-approve, when on, could not cover beyond that.
+ * Every text as {@link terminalText}.
+ *
+ * @param {{ approvalRequired?: unknown, autoApproveWithheld?: unknown }} update
+ * @returns {{ required: Array<{ text: string, warning: boolean }>, notCovered: string[] }}
+ */
+export function pendingUpdateReasons(update) {
+  const required = (Array.isArray(update?.approvalRequired) ? update.approvalRequired : [])
+    .filter((entry) => entry !== null && typeof entry === 'object')
+    .map((entry) => ({
+      text: terminalText(entry.reason),
+      warning: entry.code === SETTINGS_SECRET_TO_PLAIN,
+    }));
+  const said = new Set(required.map((line) => line.text));
+  const notCovered = (Array.isArray(update?.autoApproveWithheld) ? update.autoApproveWithheld : [])
+    .map((reason) => terminalText(reason))
+    .filter((text) => !said.has(text));
+  return { required, notCovered };
+}
+
+/**
+ * The command that approves what plugin `name` brings: the installed
+ * version by its digest (`{ digest }`), or a pending update by its version
+ * and — when it has one — its digest (`{ digest, version }`).
+ *
+ * @param {string} name
+ * @param {{ digest?: string | null, version?: string | null }} target
+ */
+export function approveHooksCommand(name, { digest = null, version = null }) {
+  return [
+    `lamaste-server plugins approve-hooks ${terminalText(name)}`,
+    ...(digest ? [`--digest ${terminalText(digest)}`] : []),
+    ...(version ? [`--version ${terminalText(version)}`] : []),
+  ].join(' ');
+}
+
+/**
+ * The arguments of `approve-hooks <name>` after the name: `--digest
+ * <sha256>` (the installed version's, or a pending update's) and
+ * `--version <v>` (a pending update's) — at least one; `--version` alone
+ * approves an update that brings neither relay hooks nor an agent half.
+ *
+ * @param {string[]} rest
+ * @returns {{ digest: string | null, version: string | null } | { error: string }}
+ */
+export function parseApproveArgs(rest) {
+  const valueOf = (flag) => {
+    const idx = rest.indexOf(flag);
+    return idx === -1 ? null : (rest[idx + 1] ?? '');
+  };
+  const digest = valueOf('--digest');
+  const version = valueOf('--version');
+  if (digest === null && version === null) return { error: APPROVE_HOOKS_USAGE };
+  if (digest !== null && !DIGEST_RE.test(digest)) return { error: APPROVE_HOOKS_USAGE };
+  if (version !== null && !VERSION_RE.test(version)) return { error: APPROVE_HOOKS_USAGE };
+  return { digest, version };
+}