@lamalibre/create-lamaste 4.3.0 → 4.4.0

package/vendor/serverd/src/lib/plugin-hosting.js

@@ -48,7 +48,12 @@ import {
 import { httpError } from './app-error.js';
 import { getConfig } from './config.js';
 import { readTunnels } from './state.js';
-import { loadAgentRegistry, saveAgentRegistry, withRegistryLock } from './mtls.js';
+import {
+  getAgentHostFacts,
+  loadAgentRegistry,
+  saveAgentRegistry,
+  withRegistryLock,
+} from './mtls.js';
 import { startPluginOperation } from './plugin-operations.js';
 import {
   pipelineContext,
@@ -62,6 +67,8 @@ import { relaySigner } from './relay-signing.js';
 import { findRetainedData, forgetRetainedData, listRetainedData } from './retained-data.js';
 import { recordAudit } from './audit.js';
 import { onHealthTransition } from './tunnel-hooks.js';
+import { agentLastSeenAt, agentPresenceMap } from './agent-presence.js';
+import { refreshPluginSettingsBestEffort } from './plugin-settings.js';
 
 const STATE_DIR = process.env.LAMALIBRE_LAMASTE_STATE_DIR || '/etc/lamalibre/lamaste';
 
@@ -145,12 +152,6 @@ export async function isActiveAgent(label) {
 // Pushing an agent half: eligibility and the push-install gates
 // ---------------------------------------------------------------------------
 
-/** The host facts agent `label` last reported, or null. */
-async function agentHostFacts(label) {
-  const registry = await loadAgentRegistry();
-  return registry.agents.find((a) => a.label === label && !a.revoked)?.hostFacts ?? null;
-}
-
 /**
  * What this relay brings to eligibility: the id of the key it signs app
  * jobs with — null when the key is unusable (it signs nothing then).
@@ -173,7 +174,7 @@ export async function assertAgentEligible(label, requires, agentHalf, pluginName
   const { eligible, reasons } = hostEligibility(
     requires,
     agentHalf,
-    await agentHostFacts(label),
+    await getAgentHostFacts(label),
     await relayEligibility(),
   );
   if (!eligible) {
@@ -336,7 +337,13 @@ export async function hostPlugin(name, agentLabel, { actor, logger, sourceIp })
     actor,
     params: { agentLabel },
     logger,
-    run: (op) => runInstallPipeline(op, ctx),
+    run: async (op) => {
+      const result = await runInstallPipeline(op, ctx);
+      // The agent half starts without settings — or with those it kept on
+      // this agent from an earlier hosting: the relay's cache follows it.
+      if (result.status === 'succeeded') await refreshPluginSettingsBestEffort(plugin.name, logger);
+      return result;
+    },
   });
   await logAgentHalfPush(push, operation.id, logger);
   return operation;
@@ -398,28 +405,42 @@ export async function isPluginHosted(name) {
 }
 
 /**
+ * The plugin's hosting as the panel shows it, with when its agent last
+ * synced (`agentLastSeenAt`, null when it never did since the panel knew).
+ *
  * @param {string} name
- * @returns {Promise<import('@lamalibre/lamaste/server').PluginHostingView | null>}
+ * @returns {Promise<(import('@lamalibre/lamaste/server').PluginHostingView & { agentLastSeenAt: string | null }) | null>}
  */
 export async function getHostingView(name) {
   const record = await ownHostingOf(name);
-  return record ? withLiveHealth(pluginHostingView(record)) : null;
+  if (!record) return null;
+  return {
+    ...withLiveHealth(pluginHostingView(record)),
+    agentLastSeenAt: await agentLastSeenAt(record.agentLabel),
+  };
 }
 
 /**
  * `agentHosting` for every plugin of a list — null for plugins that are not
- * hosted — and `retainedData`: what agents keep of the plugin's agent half
- * after it was removed without purge.
+ * hosted; with `agentLastSeenAt` as in {@link getHostingView} — and
+ * `retainedData`: what agents keep of the plugin's agent half after it was
+ * removed without purge.
  */
 export async function attachHostings(plugins) {
   const store = await readPluginHostings(STATE_DIR);
   const retained = await listRetainedData();
+  const lastSeen = await agentPresenceMap();
   return plugins.map((p) => {
     const record = p.route ? store[p.route] : undefined;
     const own = record && pluginHostingOwner(record) === p.name ? record : null;
     return {
       ...p,
-      agentHosting: own ? withLiveHealth(pluginHostingView(own)) : null,
+      agentHosting: own
+        ? {
+            ...withLiveHealth(pluginHostingView(own)),
+            agentLastSeenAt: lastSeen.get(own.agentLabel) ?? null,
+          }
+        : null,
       retainedData: retained.filter((r) => r.plugin === p.name),
     };
   });

package/vendor/serverd/src/lib/plugin-lifecycle.js

@@ -12,7 +12,13 @@
  *   and the installed version stays live; then the install pipeline runs
  *   with `phase: "upgrade"` around installing it — the new agent half
  *   first, then the relay package — and a failure restores the previous
- *   version on both sides.
+ *   version on both sides. Settings are outside the approval digest: the
+ *   preview lists how the settings schema changes (`pendingUpdate.settings`)
+ *   and the relay re-reads the agent half's settings after the update — but
+ *   a version that turns a secret setting into a plain one always waits for
+ *   an administrator's approval, its digest approved or not, and whatever
+ *   auto-approve says (`pendingUpdate.approvalRequired` says why an update
+ *   waits).
  */
 
 import {
@@ -24,6 +30,7 @@ import {
   relayHookSetNeedsEntry,
   relayHookSetOf,
   relayHookSetPreview,
+  settingsSchemaDiff,
   validateManifest,
 } from '@lamalibre/lamaste';
 import { pluginHostingPhase } from '@lamalibre/lamaste/server';
@@ -39,6 +46,9 @@ import {
 } from './plugins.js';
 import { pinAgentHalf, readRegistryPackage } from './plugin-packages.js';
 import {
+  DIGEST_UNAPPROVED,
+  SETTINGS_SECRET_TO_PLAIN,
+  digestUnapprovedReason,
   installRunnerModule,
   installedAgentHalf,
   installedApproval,
@@ -71,6 +81,7 @@ import { pipelineContext, runUpgradePipeline } from './hook-pipelines.js';
 import { getConfig } from './config.js';
 import { recordAudit, recordAuditBestEffort } from './audit.js';
 import { notifyAdminsBestEffort } from './notifications.js';
+import { refreshPluginSettingsBestEffort, settingsBlockOf } from './plugin-settings.js';
 
 /** Replaces the OIDC client sync (tests: there is no Authelia to write to). */
 let oidcSyncOverride = null;
@@ -181,25 +192,124 @@ export async function uninstallPluginWithHosting(
  * @returns {string[]}
  */
 export function autoApproveWithheld(before, after) {
+  return agentHalfWithheld(before, after).map((reason) => reason.message);
+}
+
+/**
+ * {@link autoApproveWithheld}, each reason with its stable code (what the
+ * audit entry records beside the sentence): `agent-half.added`,
+ * `agent-half.package`, `agent-half.system-packages`, `agent-half.entry`,
+ * `agent-half.memory-max`.
+ *
+ * @returns {Array<{ code: string, message: string }>}
+ */
+function agentHalfWithheld(before, after) {
   if (!after) return [];
-  if (!before) return ['it brings an agent half Lamaste installs'];
+  if (!before) {
+    return [{ code: 'agent-half.added', message: 'it brings an agent half Lamaste installs' }];
+  }
   const reasons = [];
   if (after.package !== before.package) {
-    reasons.push(`its agent package changes (${before.package} → ${after.package})`);
+    reasons.push({
+      code: 'agent-half.package',
+      message: `its agent package changes (${before.package} → ${after.package})`,
+    });
   }
   const added = after.systemPackages.filter((p) => !before.systemPackages.includes(p));
-  if (added.length > 0) reasons.push(`it adds system packages (${added.join(', ')})`);
+  if (added.length > 0) {
+    reasons.push({
+      code: 'agent-half.system-packages',
+      message: `it adds system packages (${added.join(', ')})`,
+    });
+  }
   if (after.service.entry !== before.service.entry) {
-    reasons.push(`its service entry changes (${before.service.entry} → ${after.service.entry})`);
+    reasons.push({
+      code: 'agent-half.entry',
+      message: `its service entry changes (${before.service.entry} → ${after.service.entry})`,
+    });
   }
   if (after.service.memoryMax !== before.service.memoryMax) {
-    reasons.push(
-      `its service memory limit changes (${before.service.memoryMax ?? 'none'} → ${after.service.memoryMax ?? 'none'})`,
-    );
+    reasons.push({
+      code: 'agent-half.memory-max',
+      message: `its service memory limit changes (${before.service.memoryMax ?? 'none'} → ${after.service.memoryMax ?? 'none'})`,
+    });
   }
   return reasons;
 }
 
+/**
+ * Why a version waits for an administrator because of how it changes the
+ * settings schema: fields that are secrets now and plain values after it
+ * (`settings.secret-to-plain`). Their secrets are dropped on both sides,
+ * never moved — but whatever an administrator types into them next is kept
+ * on the relay and shown in clear, which a plugin release must not decide
+ * on its own. Settings are outside the approval digest, so this is a gate
+ * of its own: such an update waits whether or not its digest is approved,
+ * and auto-approve never covers it.
+ *
+ * @param {import('@lamalibre/lamaste').SettingsSchemaDiff | null} diff
+ * @returns {Array<{ code: string, reason: string }>}
+ */
+export function settingsApprovalRequired(diff) {
+  const keys = diff?.secretToPlain ?? [];
+  if (keys.length === 0) return [];
+  return [
+    {
+      code: SETTINGS_SECRET_TO_PLAIN,
+      reason: `it turns secret settings into plain ones (${keys.join(', ')}) — what is typed into them next is kept on the relay and shown in clear`,
+    },
+  ];
+}
+
+/**
+ * Why a staged version waits for an administrator's approval (`[{ code,
+ * reason }]`; empty: it needs none and runs at once) — what the approval of
+ * the pending update covers. Independent of auto-approve, which may stand
+ * in for an administrator on the first reason alone:
+ *
+ * - `digest.unapproved` — what it brings (relay hooks, the agent half
+ *   Lamaste installs) is not what was approved;
+ * - `settings.secret-to-plain` — {@link settingsApprovalRequired}.
+ *
+ * @param {{ approvalRequired: boolean, digest: string | null, relaySet: object | null, agentHalf: object | null }} staged
+ * @param {{ approvedDigest: string | null } | null} state
+ * @param {import('@lamalibre/lamaste').SettingsSchemaDiff | null} settings
+ * @returns {Array<{ code: string, reason: string }>}
+ */
+function approvalRequiredFor(staged, state, settings) {
+  const digestApproved = !staged.approvalRequired || state?.approvedDigest === staged.digest;
+  return [
+    ...(digestApproved
+      ? []
+      : [digestUnapprovedReason({ relay: staged.relaySet, agentHalf: staged.agentHalf })]),
+    ...settingsApprovalRequired(settings),
+  ];
+}
+
+/**
+ * Check that what an administrator approved (`approvedUpdate`: the pending
+ * update as it was shown — its version, its digest, the secret settings it
+ * turns plain) covers the version as it was fetched again: the same
+ * version and digest, and no secret turned plain that was not approved.
+ */
+function assertApprovalCovers(staged, settings, approvedUpdate) {
+  if (approvedUpdate.version !== staged.version || approvedUpdate.digest !== staged.digest) {
+    throw httpError(
+      `Version ${staged.version} no longer brings what was approved — review it again`,
+      409,
+    );
+  }
+  const unapproved = (settings?.secretToPlain ?? []).filter(
+    (key) => !approvedUpdate.secretToPlain.includes(key),
+  );
+  if (unapproved.length > 0) {
+    throw httpError(
+      `Version ${staged.version} now turns secret settings into plain ones that were not approved (${unapproved.join(', ')}) — review it again`,
+      409,
+    );
+  }
+}
+
 /**
  * What a staged version brings, read without installing it: its manifest,
  * its relay hook set and module, the agent half pinned for it, and the
@@ -290,6 +400,7 @@ async function stageVersion(plugin, requestedVersion, record) {
     hooksEntrySha256: entrySha256,
     agent: manifest.agent,
     agentHalfPin,
+    settings: manifest.settings,
   };
   const approval = installedApproval(entry);
   return {
@@ -309,14 +420,37 @@ async function stageVersion(plugin, requestedVersion, record) {
   };
 }
 
+/**
+ * How a staged version changes the settings schema, for the update's
+ * preview (core's typed `settingsSchemaDiff`): fields added and removed
+ * with their types, retyped ones `from` → `to` (a retyped field's value is
+ * dropped on both sides, never converted), the fields the plugin will need
+ * filled, and the secrets that become plain values (`secretToPlain`, which
+ * makes the update wait for an administrator) — null when neither version
+ * declares settings.
+ *
+ * @param {object} plugin the installed registry entry
+ * @param {object} manifest the staged version's manifest
+ */
+function settingsPreview(plugin, manifest) {
+  const installed = settingsBlockOf(plugin);
+  const staged = settingsBlockOf(manifest);
+  if (!installed && !staged) return null;
+  return settingsSchemaDiff(installed, staged);
+}
+
 /**
  * Update plugin `name` to `requestedVersion` (an exact version or a
  * dist-tag; default `latest`). Returns `{ upToDate }`, `{ pendingUpdate }`
- * (what it brings awaits approval — shaped as the hook status's
+ * (it waits for an administrator's approval — shaped as the hook status's
  * `pendingUpdate`) or `{ operation }`.
  *
- * `approvedDigest` is set when an administrator approves the pending
- * update: the version is fetched again and must still bring exactly that.
+ * An update waits when what it brings is not what was approved — unless
+ * auto-approve covers it — and whenever it turns a secret setting into a
+ * plain one (see {@link approvalRequiredFor}). `approvedUpdate` is set when
+ * an administrator approves the pending update (`{ version, digest,
+ * secretToPlain }`, as it was shown): the version is fetched again and must
+ * still bring exactly that digest, and turn no other secret plain.
  * A hosted plugin whose agent half Lamaste installs is updated on its agent
  * too: the agent must be able to host the new version and the push-install
  * gates must allow `update` (`sourceIp`: the admin's) — checked when the
@@ -325,7 +459,7 @@ async function stageVersion(plugin, requestedVersion, record) {
 export async function updatePlugin(
   name,
   requestedVersion,
-  { actor, certSerial, logger, approvedDigest = null, sourceIp },
+  { actor, certSerial, logger, approvedUpdate = null, sourceIp },
 ) {
   const plugin = await findPlugin(name);
   if (!plugin) throw httpError(`Plugin "${name}" not found`, 404);
@@ -354,77 +488,43 @@ export async function updatePlugin(
   }
 
   const state = await readHookState(name);
+  const settings = settingsPreview(plugin, staged.manifest);
+  const approvalRequired = approvalRequiredFor(staged, state, settings);
   let approvedBy = null;
   let autoApproved = false;
-  if (staged.approvalRequired) {
-    if (state?.approvedDigest === staged.digest) {
-      approvedBy = state.approvedBy ?? 'unchanged';
-    } else if (approvedDigest !== null) {
-      if (approvedDigest !== staged.digest) {
-        throw httpError(
-          `Version ${staged.version} no longer brings what was approved — review it again`,
-          409,
-        );
-      }
-      approvedBy = actor;
-    } else {
-      // Auto-approve covers a new version of the same agent half, never one
-      // that changes what runs as root on the agent.
-      const withheld = state?.autoApprove
-        ? autoApproveWithheld(installedAgentHalf(plugin), staged.agentHalf)
-        : [];
-      if (state?.autoApprove && withheld.length === 0) {
-        approvedBy = 'auto-approve';
-        autoApproved = true;
-      } else {
-        const pendingUpdate = {
-          version: staged.version,
-          digest: staged.digest,
-          stagedAt: new Date().toISOString(),
-          preview: staged.relaySet
-            ? relayHookSetPreview(staged.relaySet, staged.entrySha256)
-            : null,
-          agentHalf: staged.agentHalf
-            ? agentHalfPreview(derivePluginRoute(plugin.name), staged.agentHalf)
-            : null,
-          ...(withheld.length > 0 ? { autoApproveWithheld: withheld } : {}),
-        };
-        await setPendingUpdate(name, pendingUpdate);
-        if (withheld.length > 0) {
-          await recordAudit({
-            actor: 'auto-approve',
-            action: 'hooks.auto-approve.withheld',
-            plugin: name,
-            details: {
-              digest: staged.digest,
-              version: staged.version,
-              reasons: withheld,
-              requestedBy: actor,
-            },
-          });
-        }
-        await recordAudit({
-          actor,
-          action: 'plugin.update.awaiting-approval',
-          plugin: name,
-          details: { from: plugin.version, to: staged.version, digest: staged.digest, certSerial },
-        });
-        await notifyAdminsBestEffort(
-          {
-            source: 'lamaste',
-            level: 'warning',
-            message:
-              withheld.length > 0
-                ? `${name} ${staged.version} waits for your approval — auto-approve does not cover it: ${withheld.join('; ')}.`
-                : staged.agentHalf
-                  ? `${name} ${staged.version} brings a new agent half${staged.relaySet ? ' and relay hooks' : ''} — it waits for your approval.`
-                  : `${name} ${staged.version} brings a changed relay hook set — it waits for your approval.`,
-          },
-          logger,
-        );
-        return { pendingUpdate: pendingUpdateView(pendingUpdate) };
-      }
+  if (approvedUpdate !== null) {
+    assertApprovalCovers(staged, settings, approvedUpdate);
+    approvedBy = actor;
+  } else if (approvalRequired.length > 0) {
+    // Auto-approve stands in for an administrator on a digest that changed,
+    // when the agent half changes nothing that runs as root on the agent —
+    // and on nothing else: every other reason (a secret setting turned
+    // plain) withholds it.
+    const digestChanged = approvalRequired.some((reason) => reason.code === DIGEST_UNAPPROVED);
+    const withheldReasons = state?.autoApprove
+      ? [
+          ...(digestChanged ? agentHalfWithheld(installedAgentHalf(plugin), staged.agentHalf) : []),
+          ...approvalRequired
+            .filter((reason) => reason.code !== DIGEST_UNAPPROVED)
+            .map(({ code, reason }) => ({ code, message: reason })),
+        ]
+      : [];
+    if (!state?.autoApprove || withheldReasons.length > 0) {
+      return awaitApproval({
+        plugin,
+        staged,
+        settings,
+        approvalRequired,
+        withheldReasons,
+        actor,
+        certSerial,
+        logger,
+      });
     }
+    approvedBy = 'auto-approve';
+    autoApproved = true;
+  } else if (staged.approvalRequired) {
+    approvedBy = state.approvedBy ?? 'unchanged';
   }
 
   // The agent half goes onto the hosting agent: a push the agent must be
@@ -451,16 +551,19 @@ export async function updatePlugin(
       staged.agentHalf.package,
     );
   }
-  if (autoApproved) {
+  // The approval takes effect now that the update starts under it: what it
+  // covered (`codes`), by an administrator or by auto-approve.
+  if (autoApproved || approvedUpdate !== null) {
     await recordAudit({
-      actor: 'auto-approve',
+      actor: autoApproved ? 'auto-approve' : actor,
       action: 'hooks.approved',
       plugin: name,
       details: {
         digest: staged.digest,
         version: staged.version,
         for: 'update',
-        requestedBy: actor,
+        codes: approvalRequired.map((reason) => reason.code),
+        ...(autoApproved ? { requestedBy: actor } : { certSerial }),
       },
     });
   }
@@ -477,6 +580,83 @@ export async function updatePlugin(
   return { operation };
 }
 
+/**
+ * Stage `staged` as the plugin's pending update, waiting for an
+ * administrator: stored with why it waits (`approvalRequired`) and why
+ * auto-approve, when on, did not cover it (`withheldReasons`), audited and
+ * notified. The installed version stays live.
+ *
+ * @returns {Promise<{ pendingUpdate: object }>}
+ */
+async function awaitApproval({
+  plugin,
+  staged,
+  settings,
+  approvalRequired,
+  withheldReasons,
+  actor,
+  certSerial,
+  logger,
+}) {
+  const name = plugin.name;
+  const withheld = withheldReasons.map((reason) => reason.message);
+  const pendingUpdate = {
+    version: staged.version,
+    digest: staged.digest,
+    stagedAt: new Date().toISOString(),
+    preview: staged.relaySet ? relayHookSetPreview(staged.relaySet, staged.entrySha256) : null,
+    agentHalf: staged.agentHalf
+      ? agentHalfPreview(derivePluginRoute(plugin.name), staged.agentHalf)
+      : null,
+    settings,
+    approvalRequired,
+    ...(withheld.length > 0 ? { autoApproveWithheld: withheld } : {}),
+  };
+  await setPendingUpdate(name, pendingUpdate);
+  if (withheld.length > 0) {
+    await recordAudit({
+      actor: 'auto-approve',
+      action: 'hooks.auto-approve.withheld',
+      plugin: name,
+      details: {
+        digest: staged.digest,
+        version: staged.version,
+        reasons: withheld,
+        codes: withheldReasons.map((reason) => reason.code),
+        requestedBy: actor,
+      },
+    });
+  }
+  await recordAudit({
+    actor,
+    action: 'plugin.update.awaiting-approval',
+    plugin: name,
+    details: {
+      from: plugin.version,
+      to: staged.version,
+      digest: staged.digest,
+      codes: approvalRequired.map((reason) => reason.code),
+      certSerial,
+    },
+  });
+  // What auto-approve withheld beyond the reasons themselves (an agent half
+  // that runs more as root); a secret turned plain is one of the reasons.
+  const notCovered = withheldReasons
+    .filter((withheldReason) => !approvalRequired.some((r) => r.code === withheldReason.code))
+    .map((reason) => reason.message);
+  await notifyAdminsBestEffort(
+    {
+      source: 'lamaste',
+      level: 'warning',
+      message:
+        `${name} ${staged.version} waits for your approval: ${approvalRequired.map((r) => r.reason).join('; ')}.` +
+        (notCovered.length > 0 ? ` Auto-approve does not cover it: ${notCovered.join('; ')}.` : ''),
+    },
+    logger,
+  );
+  return { pendingUpdate: pendingUpdateView(pendingUpdate) };
+}
+
 async function applyUpdate(op, { plugin, staged, approvedBy, actor, logger }) {
   const name = plugin.name;
   const oldRelay = installedRelayHooks(plugin);
@@ -577,6 +757,10 @@ async function applyUpdate(op, { plugin, staged, approvedBy, actor, logger }) {
 
   if (result.status === 'succeeded') op.revealOidcClientSecrets(createdSecrets);
 
+  // The agent half may have dropped values the new version retyped or no
+  // longer knows (and keeps that after a revert): the relay re-reads them.
+  if (hosted) await refreshPluginSettingsBestEffort(name, logger);
+
   // Hooks the new version no longer has: the old runner goes once the new
   // version is in place.
   if (result.status === 'succeeded' && oldRelay && !staged.relaySet) {