@lamalibre/create-lamaste 4.4.1 → 4.6.0

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

@@ -5,14 +5,17 @@
  *
  * Approval binds bytes (see `hook-set.ts` in the core library): one digest
  * (`approvalDigest`) covers the relay hook set — the normalised relay
- * declarations and the SHA-256 of the relay entry module — and the agent
- * half Lamaste installs onto the hosting agent — its package, version,
- * 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. 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.
+ * declarations and the SHA-256 of the relay entry module — the agent half
+ * Lamaste installs onto the hosting agent — its package, version, tarball
+ * integrity, service and system packages — and the plugin's identity block
+ * — the roles its users hold and the attributes it receives about them.
+ * Approval is needed when any exists. Lamaste runs relay hooks, hosts the
+ * plugin, installs its agent half and sends it its users only while the
+ * installed version's digest is the approved 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`), and
+ * so does one that adds or removes a role or widens the attributes: 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
@@ -216,22 +219,44 @@ export function installedAgentHalf(plugin) {
 }
 
 /**
- * What approving a plugin version covers — its relay hook set and the
- * agent half Lamaste installs — and the digest the approval names. `digest`
- * is null when there is nothing to approve.
+ * The web tree a plugin version's approval covers: `{ treeSha256 }` when it
+ * declares a web surface (`userSurface.web`), null otherwise. A declared
+ * surface without the tree's digest cannot be approved.
+ */
+function installedWebTree(plugin) {
+  if (!plugin.userSurface?.web) return null;
+  if (typeof plugin.webTreeSha256 !== 'string') {
+    throw new Error(`Plugin "${plugin.name}" declares a web surface but its web tree is unknown`);
+  }
+  return { treeSha256: plugin.webTreeSha256 };
+}
+
+/**
+ * What approving a plugin version covers — its relay hook set, the agent
+ * half Lamaste installs, its identity block (normalized, as the registry
+ * stores it) and its web tree — and the digest the approval names.
+ * `digest` is null when there is nothing to approve. A plugin without an
+ * identity block or a web surface has the digest it had before they
+ * existed.
  */
 export function installedApproval(plugin) {
   const relay = installedRelayHooks(plugin);
   const agentHalf = installedAgentHalf(plugin);
-  const required = relay !== null || agentHalf !== null;
+  const identity = plugin.identity ?? null;
+  const web = installedWebTree(plugin);
+  const required = relay !== null || agentHalf !== null || identity !== null || web !== null;
   return {
     relay,
     agentHalf,
+    identity,
+    web,
     required,
     digest: required
       ? approvalDigest({
           relay: relay ? { set: relay.set, entrySha256: relay.entrySha256 } : null,
           agentHalf,
+          identity,
+          web,
         })
       : null,
   };
@@ -243,9 +268,10 @@ function isApproved(approval, state) {
 }
 
 /**
- * Whether the installed version is approved — it brings neither relay hooks
- * nor an agent half Lamaste installs, or its digest is the approved one.
- * Relay hooks run, and the plugin is hosted, only then.
+ * Whether the installed version is approved — it brings no relay hooks, no
+ * agent half Lamaste installs and no identity block, or its digest is the
+ * approved one. Relay hooks run, the plugin is hosted and its users are
+ * sent to it only then.
  */
 export async function installedVersionApproved(plugin) {
   const approval = installedApproval(plugin);
@@ -253,17 +279,40 @@ export async function installedVersionApproved(plugin) {
   return isApproved(approval, await readHookState(plugin.name));
 }
 
-/** What the panel shows about a plugin's hooks, its agent half and their approval. */
+/**
+ * What the panel shows about a plugin's hooks, its agent half, its identity
+ * (`identity`: whether the installed version declares it, whether that
+ * version is approved, and the normalized block) and their approval.
+ */
 export async function hookStatus(plugin) {
   const approval = installedApproval(plugin);
-  const { relay, agentHalf } = approval;
+  const { relay, agentHalf, identity, web } = approval;
   const agent = agentHookSetOf({ hooks: plugin.hooks });
   const state = await readHookState(plugin.name);
   const approved = isApproved(approval, state);
+  let pendingUpdate = null;
+  if (state?.pendingUpdate) {
+    const { withIdentityGrantImpact } = await import('./entitlements.js');
+    pendingUpdate = await withIdentityGrantImpact(
+      pendingUpdateView(state.pendingUpdate),
+      plugin.route,
+    );
+  }
   return {
     relay: relay ? relayHookSetPreview(relay.set, relay.entrySha256) : null,
     agent,
     agentHalf: agentHalf ? agentHalfPreview(derivePluginRoute(plugin.name), agentHalf) : null,
+    identity: {
+      declared: identity !== null,
+      approved: identity !== null && approved,
+      block: identity,
+    },
+    web: {
+      declared: web !== null,
+      approved: web !== null && approved,
+      treeSha256: web?.treeSha256 ?? null,
+      surface: plugin.userSurface?.web ?? null,
+    },
     approval: {
       required: approval.required,
       state: !approval.required ? 'not-required' : approved ? 'approved' : 'pending',
@@ -279,7 +328,7 @@ export async function hookStatus(plugin) {
       installedDigest: state?.installedDigest ?? null,
       current: relay !== null && approved && state?.installedDigest === relay.digest,
     },
-    pendingUpdate: state?.pendingUpdate ? pendingUpdateView(state.pendingUpdate) : null,
+    pendingUpdate,
   };
 }
 
@@ -287,22 +336,30 @@ export async function hookStatus(plugin) {
 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';
+/** Why an update waits: it adds or removes a role, or widens the attributes it receives. */
+export const IDENTITY_CHANGED = 'identity.changed';
 
 /**
  * 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.
+ * hooks (`relay`), the agent half Lamaste installs (`agentHalf`), its
+ * identity block (`identity`), its web tree (`web`); each 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` };
+export function digestUnapprovedReason({ relay, agentHalf, identity = null, web = null }) {
+  const parts = [
+    ...(relay || (!agentHalf && !identity && !web) ? ['relay hooks'] : []),
+    ...(agentHalf ? ['agent half'] : []),
+    ...(identity ? ['identity'] : []),
+    ...(web ? ['web surface'] : []),
+  ];
+  const named =
+    parts.length === 1
+      ? parts[0]
+      : `${parts.slice(0, -1).join(', ')} and ${parts[parts.length - 1]}`;
+  const verb = parts.length === 1 && parts[0] !== 'relay hooks' ? 'is' : 'are';
+  return { code: DIGEST_UNAPPROVED, reason: `its ${named} ${verb} not what was approved` };
 }
 
 /**
@@ -314,7 +371,12 @@ export function digestUnapprovedReason({ relay, agentHalf }) {
 function pendingApprovalRequired(pending) {
   return (
     pending.approvalRequired ?? [
-      digestUnapprovedReason({ relay: pending.preview, agentHalf: pending.agentHalf }),
+      digestUnapprovedReason({
+        relay: pending.preview,
+        agentHalf: pending.agentHalf,
+        identity: pending.identity?.after ?? null,
+        web: pending.web?.after ?? null,
+      }),
     ]
   );
 }
@@ -323,14 +385,21 @@ function pendingApprovalRequired(pending) {
  * 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 (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 —
+ * half Lamaste installs nor an identity block: 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),
+ * how it changes the identity block (`identity`: `{ before, after,
+ * rolesAdded, rolesRemoved, attributesAdded, attributesRemoved,
+ * labelsChanged }` with the normalized blocks, null when neither version
+ * declares one — part of the digest), its web tree (`web`: `{ before,
+ * after }`, the installed version's tree digest and the staged one's
+ * `{ sha256, files, totalBytes }`, null when neither declares a web
+ * surface — part of the digest), why it waits for an administrator
+ * (`approvalRequired`: `[{ code, reason }]`, `digest.unapproved`,
+ * `settings.secret-to-plain` and `identity.changed`; 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`.
@@ -343,6 +412,8 @@ export function pendingUpdateView(pending) {
     relay: pending.preview ?? null,
     agentHalf: pending.agentHalf ?? null,
     settings: pending.settings ?? null,
+    identity: pending.identity ?? null,
+    web: pending.web ?? null,
     approvalRequired: pendingApprovalRequired(pending),
     autoApproveWithheld: pending.autoApproveWithheld ?? null,
   };
@@ -462,12 +533,14 @@ 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 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.
+ * set, the agent half Lamaste installs and its identity block — with the
+ * digest they were 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 nor an identity block (its digest is
+ * null), and what binds the approval of a settings change to the release
+ * that was shown. Approving an installed version that declares identity
+ * computes its audience and sends it to its agent half.
  *
  * 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
@@ -506,7 +579,7 @@ export async function approveHookSet(
     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`,
+        `Version ${version} brings relay hooks, an agent half or an identity block — approve it with the approval digest it shows`,
         400,
       );
     }
@@ -530,7 +603,7 @@ export async function approveHookSet(
   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`,
+      `Plugin "${plugin.name}" has no relay hooks, no agent half Lamaste installs and no identity block — nothing to approve`,
       400,
     );
   }
@@ -553,6 +626,15 @@ export async function approveHookSet(
     details: { digest, version: plugin.version, for: 'installed', certSerial },
   });
   await ensureRelayHooksInstalled(plugin, logger);
+  // An approved identity block lets the plugin's users through: its
+  // audience is computed and sent to its agent half (when it is hosted), and
+  // the hosts its user surface is bound to start serving it.
+  if (approval.identity) {
+    const { refreshPluginIdentity } = await import('./identity-sync.js');
+    await refreshPluginIdentity(plugin.name, logger);
+    const { refreshUserSurfaceVhosts } = await import('./user-surface.js');
+    await refreshUserSurfaceVhosts(plugin.route, logger);
+  }
   return { target: 'installed', digest };
 }
 

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

@@ -69,6 +69,8 @@ import { recordAudit } from './audit.js';
 import { onHealthTransition } from './tunnel-hooks.js';
 import { agentLastSeenAt, agentPresenceMap } from './agent-presence.js';
 import { refreshPluginSettingsBestEffort } from './plugin-settings.js';
+import { refreshPluginIdentity } from './identity-sync.js';
+import { refreshUserSurfaceVhosts } from './user-surface.js';
 
 const STATE_DIR = process.env.LAMALIBRE_LAMASTE_STATE_DIR || '/etc/lamalibre/lamaste';
 
@@ -311,7 +313,7 @@ export async function hostPlugin(name, agentLabel, { actor, logger, sourceIp })
   }
   if (!(await installedVersionApproved(plugin))) {
     throw httpError(
-      `Plugin "${name}" brings relay hooks or an agent half that are not approved — review and approve them first`,
+      `Plugin "${name}" brings relay hooks, an agent half or an identity block that are not approved — review and approve them first`,
       409,
       { code: 'hooks_not_approved' },
     );
@@ -339,9 +341,17 @@ export async function hostPlugin(name, agentLabel, { actor, logger, sourceIp })
     logger,
     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);
+      if (result.status === 'succeeded') {
+        // The agent half starts without settings — or with those it kept on
+        // this agent from an earlier hosting: the relay's cache follows it.
+        await refreshPluginSettingsBestEffort(plugin.name, logger);
+        // A plugin that declares identity learns its users now: its first
+        // sync replays the whole audience.
+        await refreshPluginIdentity(plugin.name, logger);
+        // Its user surface's locations take the body limit of the internal
+        // tunnel the hosting brought.
+        await refreshUserSurfaceVhosts(plugin.route, logger);
+      }
       return result;
     },
   });
@@ -528,6 +538,9 @@ export async function purgeRetainedData(name, agentLabel, { actor, logger, sourc
       plugin: name,
       details: { agentLabel, route: retained.route, package: retained.package },
     });
+    // The last data of an uninstalled plugin: its identity ledger goes too.
+    const { dropIdentityLedgerIfNoData } = await import('./audience.js');
+    await dropIdentityLedgerIfNoData(name, logger);
     return { forgotten: retained };
   }
   if (!(await isActiveAgent(agentLabel))) {
@@ -613,7 +626,19 @@ export async function acknowledgeAgentPluginConfig(label, route, issuedAt) {
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve a route to a forward target (see `agentForwarderPlugin`).
+ * Resolve a route to a forward target — of the admin forwarder
+ * (`agentForwarderPlugin`) and the user surface alike.
+ *
+ * While the hosting's health is `down` — the monitor's probes found nothing
+ * on the relay-loopback port that answers with the installation secret —
+ * this refuses with `down` and the health's reason (`tunnel` or `app`), so
+ * nothing of an administrator's, an agent's or a user's request reaches
+ * whatever holds that port: the admin forwarder answers as for a dead
+ * tunnel (the `tunnel:down` fallback, or `502` with the reason), the user
+ * surface `503`. Lamaste's own calls — the health probe, settings, hooks,
+ * the identity feed — do not come this way, so the monitor still finds the
+ * agent half when it is back and the hosting comes up again.
+ *
  * @param {string} route
  */
 export async function resolveForwardTarget(route) {
@@ -623,6 +648,9 @@ export async function resolveForwardTarget(route) {
   if (plugin.status !== 'enabled') return { kind: 'disabled' };
   const record = await ownHosting(plugin);
   if (!record || pluginHostingPhase(record) !== 'active') return { kind: 'not_hosted' };
+  if (record.health?.state === 'down') {
+    return { kind: 'down', reason: record.health.reason === 'app' ? 'app' : 'tunnel' };
+  }
   const tunnels = await readTunnels();
   const tunnel = tunnels.find((t) => t.id === record.tunnelId);
   const maxBodyMb = tunnel?.maxBodySizeMb ?? TUNNEL_MAX_BODY_MB.default;