@lamalibre/create-lamaste 4.4.0 → 4.5.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,27 @@ 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.
+ * What approving a plugin version covers — its relay hook set, the agent
+ * half Lamaste installs and its identity block (normalized, as the registry
+ * stores it) — and the digest the approval names. `digest` is null when
+ * there is nothing to approve. A plugin without an identity block has the
+ * digest it had before identity 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 required = relay !== null || agentHalf !== null || identity !== null;
   return {
     relay,
     agentHalf,
+    identity,
     required,
     digest: required
       ? approvalDigest({
           relay: relay ? { set: relay.set, entrySha256: relay.entrySha256 } : null,
           agentHalf,
+          identity,
         })
       : null,
   };
@@ -243,9 +251,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 +262,34 @@ 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 } = 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,
+    },
     approval: {
       required: approval.required,
       state: !approval.required ? 'not-required' : approved ? 'approved' : 'pending',
@@ -279,7 +305,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 +313,29 @@ 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`); 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 }) {
+  const parts = [
+    ...(relay || (!agentHalf && !identity) ? ['relay hooks'] : []),
+    ...(agentHalf ? ['agent half'] : []),
+    ...(identity ? ['identity'] : []),
+  ];
+  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 +347,11 @@ 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,
+      }),
     ]
   );
 }
@@ -323,14 +360,18 @@ 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), 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 +384,7 @@ export function pendingUpdateView(pending) {
     relay: pending.preview ?? null,
     agentHalf: pending.agentHalf ?? null,
     settings: pending.settings ?? null,
+    identity: pending.identity ?? null,
     approvalRequired: pendingApprovalRequired(pending),
     autoApproveWithheld: pending.autoApproveWithheld ?? null,
   };
@@ -462,12 +504,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 +550,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 +574,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 +597,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;

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

@@ -18,7 +18,11 @@
  *   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).
+ *   waits). The identity block is inside the digest; a version that adds or
+ *   removes a role or widens the attributes its users' records carry waits
+ *   for an administrator too, whatever auto-approve says
+ *   (`identity.changed`; `pendingUpdate.identity` shows the change), and
+ *   after the update the audiences are recomputed and the agent half told.
  */
 
 import {
@@ -27,6 +31,8 @@ import {
   derivePluginRoute,
   hasAgentHalf,
   hookEntrySha256,
+  identityChangeNeedsApproval,
+  identityDiff,
   relayHookSetNeedsEntry,
   relayHookSetOf,
   relayHookSetPreview,
@@ -39,6 +45,7 @@ import { setPluginCapabilities } from './mtls.js';
 import {
   findPlugin,
   getPluginCapabilities,
+  identityOf,
   manifestPolicyError,
   replacePluginPackage,
   uninstallPlugin,
@@ -47,6 +54,7 @@ import {
 import { pinAgentHalf, readRegistryPackage } from './plugin-packages.js';
 import {
   DIGEST_UNAPPROVED,
+  IDENTITY_CHANGED,
   SETTINGS_SECRET_TO_PLAIN,
   digestUnapprovedReason,
   installRunnerModule,
@@ -82,6 +90,8 @@ import { getConfig } from './config.js';
 import { recordAudit, recordAuditBestEffort } from './audit.js';
 import { notifyAdminsBestEffort } from './notifications.js';
 import { refreshPluginSettingsBestEffort, settingsBlockOf } from './plugin-settings.js';
+import { refreshPluginIdentity } from './identity-sync.js';
+import { refreshUserSurfaceVhosts } from './user-surface.js';
 
 /** Replaces the OIDC client sync (tests: there is no Authelia to write to). */
 let oidcSyncOverride = null;
@@ -163,6 +173,16 @@ export async function uninstallPluginWithHosting(
       }
       await op.step('remove the package', () => uninstallPlugin(name, logger));
       setPluginCapabilities(await getPluginCapabilities());
+      // With purge nothing of the plugin is kept — not who held its roles.
+      if (purge) {
+        const { revokePluginRoleGrants } = await import('./entitlements.js');
+        const revoked = await revokePluginRoleGrants(plugin, { actor, logger });
+        if (!revoked.ok) {
+          op.warn(
+            `The plugin's role grants were not revoked (${revoked.error}) — revoke them in Gatekeeper`,
+          );
+        }
+      }
       await recordAuditBestEffort(
         { actor, action: 'plugin.uninstalled', plugin: name, details: { operation: op.id } },
         logger,
@@ -261,6 +281,32 @@ export function settingsApprovalRequired(diff) {
   ];
 }
 
+/**
+ * Why a version waits for an administrator because of how it changes the
+ * plugin's identity block (`identity.changed`): it adds or removes a role —
+ * entitlements name roles, and a new role is a new power over its users —
+ * or widens the attributes it receives about them. Narrowing the
+ * attributes and editing labels only change the digest. Auto-approve never
+ * covers it.
+ *
+ * @param {(import('@lamalibre/lamaste').IdentityDiff & { before: object | null, after: object | null }) | null} identity
+ * @returns {Array<{ code: string, reason: string }>}
+ */
+function identityApprovalRequired(identity) {
+  if (!identity || !identityChangeNeedsApproval(identity)) return [];
+  const changes = [];
+  if (identity.rolesAdded.length > 0) {
+    changes.push(`adds roles (${identity.rolesAdded.join(', ')})`);
+  }
+  if (identity.rolesRemoved.length > 0) {
+    changes.push(`removes roles (${identity.rolesRemoved.join(', ')})`);
+  }
+  if (identity.attributesAdded.length > 0) {
+    changes.push(`receives more about its users (${identity.attributesAdded.join(', ')})`);
+  }
+  return [{ code: IDENTITY_CHANGED, reason: `it ${changes.join(' and ')}` }];
+}
+
 /**
  * Why a staged version waits for an administrator's approval (`[{ code,
  * reason }]`; empty: it needs none and runs at once) — what the approval of
@@ -268,21 +314,30 @@ export function settingsApprovalRequired(diff) {
  * 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}.
+ *   Lamaste installs, its identity block) is not what was approved;
+ * - `settings.secret-to-plain` — {@link settingsApprovalRequired};
+ * - `identity.changed` — {@link identityApprovalRequired}.
  *
- * @param {{ approvalRequired: boolean, digest: string | null, relaySet: object | null, agentHalf: object | null }} staged
+ * @param {{ approvalRequired: boolean, digest: string | null, relaySet: object | null, agentHalf: object | null, identity: object | null }} staged
  * @param {{ approvedDigest: string | null } | null} state
  * @param {import('@lamalibre/lamaste').SettingsSchemaDiff | null} settings
+ * @param {(import('@lamalibre/lamaste').IdentityDiff & { before: object | null, after: object | null }) | null} identity
  * @returns {Array<{ code: string, reason: string }>}
  */
-function approvalRequiredFor(staged, state, settings) {
+function approvalRequiredFor(staged, state, settings, identity) {
   const digestApproved = !staged.approvalRequired || state?.approvedDigest === staged.digest;
   return [
     ...(digestApproved
       ? []
-      : [digestUnapprovedReason({ relay: staged.relaySet, agentHalf: staged.agentHalf })]),
+      : [
+          digestUnapprovedReason({
+            relay: staged.relaySet,
+            agentHalf: staged.agentHalf,
+            identity: staged.identity,
+          }),
+        ]),
     ...settingsApprovalRequired(settings),
+    ...identityApprovalRequired(identity),
   ];
 }
 
@@ -401,6 +456,7 @@ async function stageVersion(plugin, requestedVersion, record) {
     agent: manifest.agent,
     agentHalfPin,
     settings: manifest.settings,
+    identity: identityOf(manifest),
   };
   const approval = installedApproval(entry);
   return {
@@ -412,6 +468,8 @@ async function stageVersion(plugin, requestedVersion, record) {
     entrySha256,
     agentHalfPin,
     agentHalf: approval.agentHalf,
+    // The staged identity block, normalized (null: it declares none).
+    identity: approval.identity,
     // The relay hook set's own digest — what the runner holds.
     relayDigest: approval.relay?.digest ?? null,
     approvalRequired: approval.required,
@@ -439,6 +497,23 @@ function settingsPreview(plugin, manifest) {
   return settingsSchemaDiff(installed, staged);
 }
 
+/**
+ * How a staged version changes the identity block, for the update's
+ * preview: both blocks, normalized (null: that version declares none), and
+ * core's `identityDiff` — roles added and removed, attributes added and
+ * removed, roles whose label or description changed. Null when neither
+ * version declares one.
+ *
+ * @param {object} plugin the installed registry entry
+ * @param {object} manifest the staged version's manifest
+ */
+function identityPreview(plugin, manifest) {
+  const before = plugin.identity ?? null;
+  const after = identityOf(manifest) ?? null;
+  if (!before && !after) return null;
+  return { before, after, ...identityDiff(before, after) };
+}
+
 /**
  * Update plugin `name` to `requestedVersion` (an exact version or a
  * dist-tag; default `latest`). Returns `{ upToDate }`, `{ pendingUpdate }`
@@ -489,7 +564,8 @@ export async function updatePlugin(
 
   const state = await readHookState(name);
   const settings = settingsPreview(plugin, staged.manifest);
-  const approvalRequired = approvalRequiredFor(staged, state, settings);
+  const identity = identityPreview(plugin, staged.manifest);
+  const approvalRequired = approvalRequiredFor(staged, state, settings, identity);
   let approvedBy = null;
   let autoApproved = false;
   if (approvedUpdate !== null) {
@@ -499,7 +575,7 @@ export async function updatePlugin(
     // 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.
+    // plain, a role added or removed, an attribute widened) withholds it.
     const digestChanged = approvalRequired.some((reason) => reason.code === DIGEST_UNAPPROVED);
     const withheldReasons = state?.autoApprove
       ? [
@@ -514,6 +590,7 @@ export async function updatePlugin(
         plugin,
         staged,
         settings,
+        identity,
         approvalRequired,
         withheldReasons,
         actor,
@@ -592,6 +669,7 @@ async function awaitApproval({
   plugin,
   staged,
   settings,
+  identity,
   approvalRequired,
   withheldReasons,
   actor,
@@ -609,6 +687,7 @@ async function awaitApproval({
       ? agentHalfPreview(derivePluginRoute(plugin.name), staged.agentHalf)
       : null,
     settings,
+    identity,
     approvalRequired,
     ...(withheld.length > 0 ? { autoApproveWithheld: withheld } : {}),
   };
@@ -654,7 +733,10 @@ async function awaitApproval({
     },
     logger,
   );
-  return { pendingUpdate: pendingUpdateView(pendingUpdate) };
+  const { withIdentityGrantImpact } = await import('./entitlements.js');
+  return {
+    pendingUpdate: await withIdentityGrantImpact(pendingUpdateView(pendingUpdate), plugin.route),
+  };
 }
 
 async function applyUpdate(op, { plugin, staged, approvedBy, actor, logger }) {
@@ -704,6 +786,7 @@ async function applyUpdate(op, { plugin, staged, approvedBy, actor, logger }) {
         hooks: installed.manifest.hooks,
         hooksEntrySha256: installed.hooksEntrySha256,
         agent: installed.manifest.agent,
+        identity: identityOf(installed.manifest),
       };
       let approval;
       try {
@@ -760,6 +843,14 @@ async function applyUpdate(op, { plugin, staged, approvedBy, actor, logger }) {
   // 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);
+  // The roles and attributes may have changed with the version (or back,
+  // after a revert); the agent half of the installed version must answer
+  // protocol 1 again before its users reach it.
+  await refreshPluginIdentity(name, logger);
+  // So may whether it declares identity at all: the hosts its user surface
+  // is bound to serve it from the version that does — a plugin's
+  // switch-over to the relay's user surface is this update.
+  await refreshUserSurfaceVhosts(plugin.route, logger);
 
   // Hooks the new version no longer has: the old runner goes once the new
   // version is in place.