@lamalibre/create-lamaste 4.3.1 → 4.4.0

package/vendor/server-ui/dist/index.html

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Lamaste</title>
-    <script type="module" crossorigin src="/assets/index-BTlBt_cD.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-Bc5NCMSv.css">
+    <script type="module" crossorigin src="/assets/index-CESyyK8V.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-25wo_8av.css">
   </head>
   <body style="background-color: #09090b">
     <div id="root"></div>

package/vendor/serverd/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lamalibre/lamaste-serverd",
-  "version": "4.3.1",
+  "version": "4.4.0",
   "description": "Lamaste server daemon — REST API and plugin host",
   "license": "SEE LICENSE IN LICENSE.md",
   "publishConfig": {
@@ -29,7 +29,7 @@
     "@fastify/rate-limit": "^10.3.0",
     "@fastify/static": "^9.1.1",
     "@fastify/websocket": "^11.0.0",
-    "@lamalibre/lamaste": "^4.3.1",
+    "@lamalibre/lamaste": "^4.4.0",
     "bcryptjs": "^3.0.3",
     "execa": "^9.6.1",
     "fastify": "^5.8.4",

package/vendor/serverd/src/index.js

@@ -37,6 +37,7 @@ import {
   startHostedPluginHealthMonitor,
   stopHostedPluginHealthMonitor,
 } from './lib/plugin-hosting.js';
+import { refreshHostedPluginSettings } from './lib/plugin-settings.js';
 import { syncOidcClients } from './lib/plugin-oidc.js';
 import { ensureRelaySigningKey } from './lib/relay-signing.js';
 import { reconcileSiteVhosts, reconcileTunnelVhosts } from './lib/vhost-reconcile.js';
@@ -228,6 +229,14 @@ async function start() {
 
   // --- Health of hosted agent-hosted plugins (every 10s; idle without hostings) ---
   startHostedPluginHealthMonitor(server.log);
+  // The monitor resumes from the persisted health, so a plugin that stayed
+  // up across the restart sees no transition that would re-read its
+  // settings: read them once now — one plugin after another, best effort —
+  // so a change made while the panel was down is seen (and, when Lamaste
+  // did not make it, reported).
+  refreshHostedPluginSettings(server.log).catch((err) => {
+    server.log.warn({ err: err.message }, 'Startup refresh of plugin settings failed');
+  });
 
   // --- Periodic ticket instance liveness check (every 60s) ---
   const livenessInterval = setInterval(() => {

package/vendor/serverd/src/lib/agent-presence.js

@@ -0,0 +1,106 @@
+/**
+ * When each machine agent last contacted the relay — the hosting-agent
+ * state the panel shows next to a hosted plugin ("hosting agent offline
+ * since … — last sync …").
+ *
+ * An agent's sync timer calls `GET /api/tunnels/agent-config` every 30 s;
+ * that call records the agent here. The time is kept in memory and written
+ * to `agent_presence` at most once per {@link PRESENCE_PERSIST_INTERVAL_MS}
+ * per agent, so a restart of the panel loses at most that much — and the
+ * `agents` table, which the registry rewrites whole, is never touched.
+ */
+
+import { getStateDb } from './state-db.js';
+
+/** An agent's contact is written to state.db at most this often. */
+export const PRESENCE_PERSIST_INTERVAL_MS = 60_000;
+
+/** label → { seenAt, persistedAt } (epoch milliseconds); filled from the table once. */
+const presence = new Map();
+let loaded = false;
+let clock = () => Date.now();
+
+/** Replace the clock (tests); null restores `Date.now`. */
+export function setPresenceClockForTests(fn) {
+  clock = fn ?? (() => Date.now());
+}
+
+/** Forget what memory holds, as a restart of the panel would (tests). */
+export function forgetPresenceMemoryForTests() {
+  presence.clear();
+  loaded = false;
+}
+
+function loadOnce(db) {
+  if (loaded) return;
+  for (const row of db.prepare('SELECT label, last_seen_at FROM agent_presence').all()) {
+    const at = Date.parse(row.last_seen_at);
+    if (Number.isFinite(at) && !presence.has(row.label)) {
+      presence.set(row.label, { seenAt: at, persistedAt: at });
+    }
+  }
+  loaded = true;
+}
+
+/**
+ * Agent `label` contacted the relay now. Returns whether the contact was
+ * written to state.db (false while the last write is under a minute old).
+ *
+ * @param {string} label
+ * @returns {Promise<{ persisted: boolean }>}
+ */
+export async function recordAgentContact(label) {
+  const db = await getStateDb();
+  loadOnce(db);
+  const now = clock();
+  const entry = presence.get(label);
+  if (
+    entry &&
+    entry.persistedAt !== null &&
+    now >= entry.persistedAt &&
+    now - entry.persistedAt < PRESENCE_PERSIST_INTERVAL_MS
+  ) {
+    entry.seenAt = Math.max(entry.seenAt, now);
+    return { persisted: false };
+  }
+  db.prepare(
+    `INSERT INTO agent_presence (label, last_seen_at) VALUES (?, ?)
+     ON CONFLICT(label) DO UPDATE SET last_seen_at = excluded.last_seen_at`,
+  ).run(label, new Date(now).toISOString());
+  presence.set(label, { seenAt: now, persistedAt: now });
+  return { persisted: true };
+}
+
+/**
+ * When each agent last contacted the relay (ISO 8601), by label. Agents
+ * that never did are absent.
+ *
+ * @returns {Promise<Map<string, string>>}
+ */
+export async function agentPresenceMap() {
+  const db = await getStateDb();
+  loadOnce(db);
+  const out = new Map();
+  for (const [label, entry] of presence) out.set(label, new Date(entry.seenAt).toISOString());
+  return out;
+}
+
+/**
+ * When agent `label` last contacted the relay (ISO 8601), or null.
+ * @param {string} label
+ */
+export async function agentLastSeenAt(label) {
+  return (await agentPresenceMap()).get(label) ?? null;
+}
+
+/**
+ * Drop what is known of agent `label` — its certificate was revoked, and a
+ * later enrollment reusing the label must not inherit its last contact.
+ * @param {string} label
+ */
+export async function forgetAgentPresence(label) {
+  const db = await getStateDb();
+  loadOnce(db);
+  db.prepare('DELETE FROM agent_presence WHERE label = ?').run(label);
+  presence.delete(label);
+}

package/vendor/serverd/src/lib/hook-pipelines.js

@@ -40,6 +40,9 @@
  * plugin that owns it; a teardown acts only on the plugin's own.
  *
  * Hook outputs are passed forward in `outputs` (`relay:install:pre-tunnel`, …).
+ * Relay stages see the plugin's effective non-secret settings (the relay's
+ * cache, `plugin-settings.js`); agent stages see none — the agent half holds
+ * them. The cache goes once the hosting it describes is removed.
  */
 
 import {
@@ -79,6 +82,7 @@ import { installedAgentHalf, installedRelayHooks } from './plugin-hooks.js';
 import { forgetRetainedData, recordRetainedData } from './retained-data.js';
 import { runRelayHook } from './relay-hooks.js';
 import { recordAuditBestEffort } from './audit.js';
+import { deleteSettingsCache, relayHookSettings } from './plugin-settings.js';
 import {
   tunnelNginxDeps,
   tunnelCertbotDeps,
@@ -97,15 +101,19 @@ const TUNNEL_READY_POLL_MS = 3_000;
 // Stages
 // ---------------------------------------------------------------------------
 
-/** The pipeline-wide context: who, what, and the outputs so far. */
-function lifecycleInput(ctx, phase) {
+/**
+ * The pipeline-wide context: who, what, and the outputs so far. `settings`
+ * is the plugin's effective non-secret settings for a relay stage, `{}` for
+ * an agent stage.
+ */
+function lifecycleInput(ctx, phase, settings = {}) {
   return {
     plugin: ctx.plugin.name,
     version: ctx.version ?? ctx.plugin.version,
     ...(ctx.previousVersion ? { previousVersion: ctx.previousVersion } : {}),
     phase,
     agent: { label: ctx.agentLabel },
-    settings: {},
+    settings,
     outputs: { ...ctx.outputs },
     ...(ctx.port ? { port: ctx.port } : {}),
   };
@@ -132,7 +140,7 @@ async function relayStage(op, ctx, stage, phase) {
       plugin: ctx.plugin.name,
       stage,
       call: { kind: 'app' },
-      input: lifecycleInput(ctx, phase),
+      input: lifecycleInput(ctx, phase, await relayHookSettings(ctx.plugin)),
       timeoutMs: decl.timeoutMs,
       effects: ctx.relay.set.effects,
       logger: ctx.logger,
@@ -821,6 +829,14 @@ export async function runUninstallPipeline(op, ctx, { force = false } = {}) {
       : null;
   await runTeardown(op, ctx, { phase: 'uninstall', force });
   await cancelAgentJobs(ctx.route).catch(() => undefined);
+  // The relay's cache of the settings describes the hosting's agent half:
+  // with the hosting gone it describes nothing (a later hosting reads them
+  // afresh — from data the agent kept, or none).
+  if (!(await getPluginHosting(STATE_DIR, ctx.route))) {
+    await deleteSettingsCache(ctx.plugin.name).catch((err) =>
+      op.warn(`Could not drop the cached settings: ${err.message}`),
+    );
+  }
   await recordAuditBestEffort(
     {
       actor: op.actor ?? 'admin',

package/vendor/serverd/src/lib/migrations/state/0012_plugin_settings_and_presence.sql

@@ -0,0 +1,62 @@
+-- Plugin settings and the presence of hosting agents (4.3, slice 4).
+
+-- The manifest's `settings` block (JSON; NULL when the plugin declares
+-- none): the schema the panel checks an administrator's change against
+-- before sending it to the agent half, and the keys it keeps in the cache
+-- below. Settings are not part of the approval digest.
+ALTER TABLE plugins ADD COLUMN settings TEXT;
+
+-- The relay's cache of each plugin's settings. The agent half is the system
+-- of record (settings.json and secrets.json in its data directory); this row
+-- is refreshed from its `GET /admin/settings` after hosting, after an
+-- update, when the health monitor sees the plugin come up, and from its
+-- answer to every change — so the panel can show the settings, and whether
+-- the plugin still needs configuration, while the agent is offline.
+-- There is no column for a secret's value: a secret exists on the relay only
+-- in the memory of the request that carries it to the agent half.
+--   schema_version    the agent half's settings schema version
+--   revision          the agent half's revision (+1 per change)
+--   values_json       JSON {key: value} — the non-secret values the agent half
+--                     stored (no defaults), for keys the installed schema knows
+--   secrets_set_json  JSON {key: setAt} — which secrets are set, and when
+--   configured        1 when no required field lacks a value
+--   missing_json      JSON [key] — the required fields without a value
+--   synced_at         when the relay last read the agent half's state
+--   lamaste_revision  the agent half's revision as Lamaste last wrote it (its
+--                     answer to a change) or adopted it; NULL until the first
+--                     read. A refresh that finds another revision found a
+--                     change made outside Lamaste: audited and notified (key
+--                     names only), then adopted.
+--   unconfirmed_change_json
+--                     JSON {revision, actor, certSerial?, changed, cleared,
+--                     secretsSet, secretsCleared} — the key names of a change
+--                     whose answer never authenticated (a timeout, say), which
+--                     the agent half may have stored. A refresh that finds
+--                     exactly that revision, changed in those keys only,
+--                     records the change as Lamaste's.
+-- When the installed settings schema changes (an update or its revert), the
+-- values and secrets whose field changed type are pruned in the transaction
+-- that writes the plugin's row.
+-- Removed when the plugin's hosting is removed and when it is uninstalled.
+CREATE TABLE plugin_settings (
+  plugin                   TEXT PRIMARY KEY,
+  schema_version           INTEGER NOT NULL,
+  revision                 INTEGER NOT NULL,
+  values_json              TEXT NOT NULL,
+  secrets_set_json         TEXT NOT NULL,
+  configured               INTEGER NOT NULL,
+  missing_json             TEXT NOT NULL,
+  synced_at                TEXT NOT NULL,
+  lamaste_revision         INTEGER,
+  unconfirmed_change_json  TEXT
+);
+
+-- When each machine agent last contacted the relay: its sync's
+-- `GET /api/tunnels/agent-config`, every 30 s. Kept in memory and written
+-- here at most once a minute per agent — never through the `agents` table,
+-- which the registry rewrites whole. Tells how long a hosting agent has been
+-- gone. Removed when the agent's certificate is revoked.
+CREATE TABLE agent_presence (
+  label         TEXT PRIMARY KEY,
+  last_seen_at  TEXT NOT NULL
+);

package/vendor/serverd/src/lib/mtls.js

@@ -17,6 +17,7 @@ import {
   BASE_CAPABILITIES as CORE_BASE_CAPABILITIES,
   HostFactsSchema,
   PLUGIN_AGENT_CN_PREFIX as CORE_PLUGIN_AGENT_CN_PREFIX,
+  hostFactsHash,
 } from '@lamalibre/lamaste';
 import { addToRevocationList } from './revocation.js';
 import { releaseAgentTunnels, stripPluginCapabilities } from '@lamalibre/lamaste/server';
@@ -27,6 +28,7 @@ import {
   rotateChiselCredential as rotateChiselCredentialLib,
 } from './chisel-users.js';
 import { getStateDb } from './state-db.js';
+import { agentPresenceMap, forgetAgentPresence } from './agent-presence.js';
 import { randomCertSerial, signAgentCsr } from './pki-sign.js';
 
 const PKI_DIR = process.env.LAMALIBRE_LAMASTE_PKI_DIR || '/etc/lamalibre/lamaste/pki';
@@ -577,14 +579,17 @@ export async function generateAgentCert(label, logger, capabilities, allowedSite
 }
 
 /**
- * List all agent certificates with expiry status and the host facts each
- * agent last reported. `status` sums a certificate up for the panel:
- * `revoked`, `expired`, `expiring-soon` (within 30 days) or `active`.
+ * List all agent certificates with expiry status, the host facts each
+ * agent last reported and when it last contacted the relay (`lastSeenAt`:
+ * its sync's agent-config call; null when it never did since it enrolled).
+ * `status` sums a certificate up for the panel: `revoked`, `expired`,
+ * `expiring-soon` (within 30 days) or `active`.
  *
- * @returns {Promise<Array<{ label: string, serial: string, createdAt: string, expiresAt: string, revoked: boolean, expiringSoon: boolean, status: 'active' | 'expiring-soon' | 'expired' | 'revoked', hostFacts: object | null, hostFactsAt: string | null }>>}
+ * @returns {Promise<Array<{ label: string, serial: string, createdAt: string, expiresAt: string, revoked: boolean, expiringSoon: boolean, status: 'active' | 'expiring-soon' | 'expired' | 'revoked', hostFacts: object | null, hostFactsAt: string | null, lastSeenAt: string | null }>>}
  */
 export async function listAgentCerts() {
   const registry = await loadAgentRegistry();
+  const lastSeen = await agentPresenceMap();
   const now = Date.now();
 
   return registry.agents.map((agent) => {
@@ -612,6 +617,7 @@ export async function listAgentCerts() {
       // What the agent last reported about its host (null until it has).
       hostFacts: agent.hostFacts ?? null,
       hostFactsAt: agent.hostFactsAt ?? null,
+      lastSeenAt: agent.revoked ? null : (lastSeen.get(agent.label) ?? null),
     };
     if (isPluginAgent) {
       entry.certType = 'plugin-agent';
@@ -738,6 +744,34 @@ export function setAgentHostFacts(label, hostFacts) {
   });
 }
 
+/**
+ * The host facts agent `label` last reported, as stored on its enrolled,
+ * unrevoked record — null when it has none: it never reported, its record
+ * was replaced since (enrolled again on the label, a restored backup), or
+ * the stored facts no longer parse.
+ *
+ * @param {string} label
+ * @returns {Promise<import('@lamalibre/lamaste').HostFacts | null>}
+ */
+export async function getAgentHostFacts(label) {
+  const registry = await loadAgentRegistry();
+  return registry.agents.find((a) => a.label === label && !a.revoked)?.hostFacts ?? null;
+}
+
+/**
+ * The hash of the host facts stored for agent `label` — core's
+ * `hostFactsHash`, exactly what the agent computes over its own — or null
+ * when it has none ({@link getAgentHostFacts}). The agent's sync gets it in
+ * agent-config and reports its facts again when it is not theirs.
+ *
+ * @param {string} label
+ * @returns {Promise<string | null>}
+ */
+export async function getAgentHostFactsHash(label) {
+  const facts = await getAgentHostFacts(label);
+  return facts === null ? null : hostFactsHash(facts);
+}
+
 /**
  * Revoke an agent certificate by label.
  *
@@ -793,6 +827,12 @@ export async function revokeAgentCert(label, logger) {
     // 4. Save registry atomically (includes both the agent and cascade-revoked plugin-agents)
     await saveAgentRegistry(registry);
 
+    // When the agent last synced: a later enrollment reusing the label
+    // starts without it.
+    await forgetAgentPresence(label).catch((err) => {
+      logger.warn({ err: err.message, label }, 'Failed to forget the agent presence');
+    });
+
     // 5. Remove agent's key/cert/p12 files (lamaste owns the agents directory)
     await execa('rm', ['-rf', `${AGENTS_DIR}/${label}/`]).catch((err) => {
       logger.warn({ err, label }, 'Failed to remove agent certificate files');

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

@@ -10,7 +10,9 @@
  * tarball integrity, service and system packages. Approval is needed when
  * either exists. Lamaste runs relay hooks, hosts the plugin and installs its
  * agent half only while the installed version's digest is the approved
- * one.
+ * one. Settings are outside the digest, but an update that turns a secret
+ * setting into a plain one waits for an administrator's approval all the
+ * same (`plugin-lifecycle.js`): the same pending update, approved here.
  *
  * The runner is about the relay part alone: it holds a root-owned copy of
  * the approved module that lamaste-priv installed after checking its
@@ -281,22 +283,67 @@ export async function hookStatus(plugin) {
   };
 }
 
+/** Why an update waits: its approval digest is not the approved one. */
+export const DIGEST_UNAPPROVED = 'digest.unapproved';
+/** Why an update waits: it turns secret settings into plain ones. */
+export const SETTINGS_SECRET_TO_PLAIN = 'settings.secret-to-plain';
+
+/**
+ * The reason a staged version waits because what it brings — its relay
+ * hooks (`relay`), the agent half Lamaste installs (`agentHalf`); either
+ * truthy when it brings one — is not what was approved.
+ *
+ * @returns {{ code: string, reason: string }}
+ */
+export function digestUnapprovedReason({ relay, agentHalf }) {
+  const what =
+    relay && agentHalf
+      ? 'its relay hooks and agent half are'
+      : agentHalf
+        ? 'its agent half is'
+        : 'its relay hooks are';
+  return { code: DIGEST_UNAPPROVED, reason: `${what} not what was approved` };
+}
+
+/**
+ * Why a stored pending update waits for an administrator. A record staged
+ * before the reasons were stored waited for one reason only: its digest.
+ *
+ * @returns {Array<{ code: string, reason: string }>}
+ */
+function pendingApprovalRequired(pending) {
+  return (
+    pending.approvalRequired ?? [
+      digestUnapprovedReason({ relay: pending.preview, agentHalf: pending.agentHalf }),
+    ]
+  );
+}
+
 /**
  * A staged update waiting for approval as clients see it — in the hook
  * status and in the update response alike: its version, the digest to
- * approve it with, what it brings (its relay hook set and the agent half
- * Lamaste installs, each null when it brings none), and — when the plugin
- * has auto-approve on — why auto-approve did not cover it
- * (`autoApproveWithheld`, null otherwise). The stored record names the
- * relay hook set's preview `preview`.
+ * approve it with (null when it brings neither relay hooks nor an agent
+ * half Lamaste installs: it is approved by its version), what it brings
+ * (its relay hook set and the agent half Lamaste installs, each null when
+ * it brings none), how it changes the settings schema (`settings`:
+ * `{ added: [{ key, type }], removed: [{ key, type }], retyped: [{ key,
+ * from, to }], newRequired: [key], secretToPlain: [key] }`, null when
+ * neither version declares settings — not part of the digest), why it
+ * waits for an administrator (`approvalRequired`: `[{ code, reason }]`,
+ * `digest.unapproved` and `settings.secret-to-plain`; never empty), and —
+ * when the plugin has auto-approve on — why auto-approve did not cover it
+ * (`autoApproveWithheld`, sentences; null otherwise). The stored record
+ * names the relay hook set's preview `preview`.
  */
 export function pendingUpdateView(pending) {
   return {
     version: pending.version,
-    digest: pending.digest,
+    digest: pending.digest ?? null,
     stagedAt: pending.stagedAt,
     relay: pending.preview ?? null,
     agentHalf: pending.agentHalf ?? null,
+    settings: pending.settings ?? null,
+    approvalRequired: pendingApprovalRequired(pending),
     autoApproveWithheld: pending.autoApproveWithheld ?? null,
   };
 }
@@ -416,28 +463,71 @@ export async function restartRelayHookRunner(plugin, logger) {
 /**
  * An administrator approves what a plugin version brings — its relay hook
  * set and the agent half Lamaste installs — with the digest they were
- * shown. The digest must be the installed version's — or the pending
- * update's, in which case the caller applies the update. Recorded in the
- * audit log.
+ * shown: the installed version's, or a pending update's. A pending update
+ * is also approved by naming its `version`, with its digest when it has
+ * one — the only way to approve one that brings neither relay hooks nor an
+ * agent half (its digest is null), and what binds the approval of a
+ * settings change to the release that was shown.
  *
- * @returns {Promise<{ target: 'installed' | 'update', digest: string }>}
+ * The installed version's approval is recorded here, in the hook state and
+ * the audit log. A pending update's is checked against the update that is
+ * waiting and handed back for the caller to apply (`updatePlugin` with
+ * `approvedUpdate`): its version, its digest and the secret settings it
+ * turns plain as they were shown. It approves everything the update waits
+ * for (`approvalRequired`), its digest changed or not, and is audited when
+ * the update starts under it.
+ *
+ * @param {object} plugin the installed registry entry
+ * @param {string | null} digest
+ * @param {{ actor: string, certSerial: string | null, logger?: object, version?: string | null }} options
+ * @returns {Promise<{ target: 'installed', digest: string } | { target: 'update', digest: string | null, version: string, secretToPlain: string[] }>}
  */
-export async function approveHookSet(plugin, digest, { actor, certSerial, logger }) {
+export async function approveHookSet(
+  plugin,
+  digest,
+  { actor, certSerial, logger, version = null },
+) {
   const approval = installedApproval(plugin);
   const { relay } = approval;
   const state = await readHookState(plugin.name);
   const pending = state?.pendingUpdate ?? null;
   const now = new Date().toISOString();
 
-  if (pending && pending.digest === digest) {
-    await recordAudit({
-      actor,
-      action: 'hooks.approved',
-      plugin: plugin.name,
-      details: { digest, version: pending.version, for: 'update', certSerial },
-    });
-    return { target: 'update', digest };
+  if (version !== null) {
+    if (!pending) {
+      throw httpError(`Plugin "${plugin.name}" has no update waiting for approval`, 409);
+    }
+    if (pending.version !== version) {
+      throw httpError(
+        `The update waiting for approval is version ${pending.version}, not ${version} — review it again`,
+        409,
+      );
+    }
+    const pendingDigest = pending.digest ?? null;
+    if (digest === null && pendingDigest !== null) {
+      throw httpError(
+        `Version ${version} brings relay hooks or an agent half — approve it with the approval digest it shows`,
+        400,
+      );
+    }
+    if (digest !== pendingDigest) {
+      throw httpError(
+        `What version ${version} brings changed since it was shown — review it again`,
+        409,
+        {
+          currentDigest: pendingDigest,
+        },
+      );
+    }
+    return pendingUpdateApproval(pending);
   }
+  if (digest === null) {
+    throw httpError(
+      "Approving names the approval digest that was shown, or a pending update's version",
+      400,
+    );
+  }
+  if (pending && pending.digest === digest) return pendingUpdateApproval(pending);
   if (!approval.required) {
     throw httpError(
       `Plugin "${plugin.name}" has no relay hooks and no agent half Lamaste installs — nothing to approve`,
@@ -466,6 +556,16 @@ export async function approveHookSet(plugin, digest, { actor, certSerial, logger
   return { target: 'installed', digest };
 }
 
+/** What approving the pending update `pending` hands its caller to apply: the update as it was shown. */
+function pendingUpdateApproval(pending) {
+  return {
+    target: 'update',
+    digest: pending.digest ?? null,
+    version: pending.version,
+    secretToPlain: pending.settings?.secretToPlain ?? [],
+  };
+}
+
 /**
  * Record an approval of an applied update (by an admin or auto-approve):
  * `digest` is the version's approval digest (`installedApproval`).