@lamalibre/create-lamaste 4.4.1 → 4.6.0

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,26 +31,30 @@ import {
   derivePluginRoute,
   hasAgentHalf,
   hookEntrySha256,
+  identityChangeNeedsApproval,
+  identityDiff,
   relayHookSetNeedsEntry,
   relayHookSetOf,
   relayHookSetPreview,
   settingsSchemaDiff,
   validateManifest,
 } from '@lamalibre/lamaste';
-import { pluginHostingPhase } from '@lamalibre/lamaste/server';
+import { pluginHostingPhase, webTreeManifestOfDirectory } from '@lamalibre/lamaste/server';
 import { httpError } from './app-error.js';
 import { setPluginCapabilities } from './mtls.js';
 import {
   findPlugin,
   getPluginCapabilities,
+  identityOf,
   manifestPolicyError,
   replacePluginPackage,
   uninstallPlugin,
   writePluginRow,
 } from './plugins.js';
-import { pinAgentHalf, readRegistryPackage } from './plugin-packages.js';
+import { installedWebTreeDir, 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,32 @@ 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, its web tree) 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,
+            web: staged.webTree,
+          }),
+        ]),
     ...settingsApprovalRequired(settings),
+    ...identityApprovalRequired(identity),
   ];
 }
 
@@ -391,6 +448,10 @@ async function stageVersion(plugin, requestedVersion, record) {
     }
     entrySha256 = hookEntrySha256(moduleBytes);
   }
+  // A web surface's tree, read from the tarball: every rule checked now,
+  // its digest approved with the rest.
+  const webRoot = manifest.userSurface?.web?.root;
+  const webTree = webRoot ? await staged.readWebTree(webRoot) : null;
   // The staged version as a registry entry, so it is judged exactly as the
   // installed one will be.
   const entry = {
@@ -401,6 +462,9 @@ async function stageVersion(plugin, requestedVersion, record) {
     agent: manifest.agent,
     agentHalfPin,
     settings: manifest.settings,
+    identity: identityOf(manifest),
+    userSurface: manifest.userSurface,
+    webTreeSha256: webTree?.sha256 ?? null,
   };
   const approval = installedApproval(entry);
   return {
@@ -412,6 +476,10 @@ async function stageVersion(plugin, requestedVersion, record) {
     entrySha256,
     agentHalfPin,
     agentHalf: approval.agentHalf,
+    // The staged identity block, normalized (null: it declares none).
+    identity: approval.identity,
+    // The staged web tree's manifest (null: it declares no web surface).
+    webTree,
     // The relay hook set's own digest — what the runner holds.
     relayDigest: approval.relay?.digest ?? null,
     approvalRequired: approval.required,
@@ -439,6 +507,121 @@ 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) };
+}
+
+/**
+ * How a staged version changes the web tree, for the update's preview: the
+ * installed version's tree digest (`before`), the staged tree (`after`:
+ * its digest, file count and size) and what changes by path (`changes`,
+ * {@link webTreeChanges}) — null when neither version declares a web
+ * surface.
+ *
+ * @param {object} plugin the installed registry entry
+ * @param {{ webTree: import('@lamalibre/lamaste').WebTreeManifest | null }} staged
+ */
+async function webPreview(plugin, staged) {
+  const before = installedTreeSha256(plugin);
+  const after = staged.webTree
+    ? {
+        sha256: staged.webTree.sha256,
+        files: staged.webTree.files.length,
+        totalBytes: staged.webTree.totalBytes,
+      }
+    : null;
+  if (before === null && after === null) return null;
+  return { before, after, changes: await webTreeChanges(plugin, staged.webTree) };
+}
+
+/** The approved web tree of the installed version, or null when it declares none. */
+function installedTreeSha256(plugin) {
+  return plugin.userSurface?.web ? (plugin.webTreeSha256 ?? null) : null;
+}
+
+/** At most this many paths per list of a tree change (the counts are exact). */
+const WEB_CHANGE_LIST_MAX = 200;
+
+/**
+ * Files of a web tree an administrator should look at before approving: a
+ * document other than the shell's `index.html` (another page served on
+ * the relay's domain), an SVG (it runs script when opened), a manifest.
+ */
+function webFileNeedsReview(file) {
+  return (file.endsWith('.html') && file !== 'index.html') || /\.(?:svg|webmanifest)$/.test(file);
+}
+
+/**
+ * What a staged version's web tree changes against the installed one's,
+ * by path: added, removed, changed (each `{ count, paths }`, the paths
+ * capped), and `review` — the added or changed paths
+ * {@link webFileNeedsReview} names. Null when the staged version declares
+ * no web tree, or when the installed tree cannot be read (the digests
+ * still tell them apart).
+ *
+ * @param {object} plugin the installed registry entry
+ * @param {import('@lamalibre/lamaste').WebTreeManifest | null} stagedTree
+ */
+async function webTreeChanges(plugin, stagedTree) {
+  if (!stagedTree) return null;
+  let installed = new Map();
+  if (installedTreeSha256(plugin) !== null) {
+    try {
+      const dir = await installedWebTreeDir(plugin.packageName, plugin);
+      const tree = await webTreeManifestOfDirectory(dir);
+      installed = new Map(tree.files.map((f) => [f.path, f.sha256]));
+    } catch {
+      return null;
+    }
+  }
+  const added = [];
+  const changed = [];
+  for (const file of stagedTree.files) {
+    const was = installed.get(file.path);
+    if (was === undefined) added.push(file.path);
+    else if (was !== file.sha256) changed.push(file.path);
+  }
+  const staged = new Set(stagedTree.files.map((f) => f.path));
+  const removed = [...installed.keys()].filter((p) => !staged.has(p));
+  const list = (paths) => ({ count: paths.length, paths: paths.slice(0, WEB_CHANGE_LIST_MAX) });
+  return {
+    added: list(added),
+    removed: list(removed),
+    changed: list(changed),
+    review: [...added, ...changed].filter(webFileNeedsReview).slice(0, WEB_CHANGE_LIST_MAX),
+  };
+}
+
+/**
+ * Why auto-approve may not stand in for an administrator on a staged
+ * version's web tree: it changes (or appears) — publisher code served to
+ * every user of the plugin on the relay's own domain is approved by a
+ * person, as an identity change is.
+ */
+function webTreeWithheld(plugin, staged) {
+  const after = staged.webTree?.sha256 ?? null;
+  if (after === null || after === installedTreeSha256(plugin)) return [];
+  return [
+    {
+      code: 'web.changed',
+      message: "the web tree changes: a shell served to the plugin's users on the relay's domain",
+    },
+  ];
+}
+
 /**
  * Update plugin `name` to `requestedVersion` (an exact version or a
  * dist-tag; default `latest`). Returns `{ upToDate }`, `{ pendingUpdate }`
@@ -489,7 +672,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) {
@@ -497,13 +681,14 @@ export async function updatePlugin(
     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.
+    // when the agent half changes nothing that runs as root on the agent and
+    // the web tree does not change — and on nothing else: every other reason (a secret setting turned
+    // plain, a role added or removed, an attribute widened) withholds it.
     const digestChanged = approvalRequired.some((reason) => reason.code === DIGEST_UNAPPROVED);
     const withheldReasons = state?.autoApprove
       ? [
           ...(digestChanged ? agentHalfWithheld(installedAgentHalf(plugin), staged.agentHalf) : []),
+          ...(digestChanged ? webTreeWithheld(plugin, staged) : []),
           ...approvalRequired
             .filter((reason) => reason.code !== DIGEST_UNAPPROVED)
             .map(({ code, reason }) => ({ code, message: reason })),
@@ -514,6 +699,8 @@ export async function updatePlugin(
         plugin,
         staged,
         settings,
+        identity,
+        web: await webPreview(plugin, staged),
         approvalRequired,
         withheldReasons,
         actor,
@@ -592,6 +779,8 @@ async function awaitApproval({
   plugin,
   staged,
   settings,
+  identity,
+  web,
   approvalRequired,
   withheldReasons,
   actor,
@@ -609,6 +798,8 @@ async function awaitApproval({
       ? agentHalfPreview(derivePluginRoute(plugin.name), staged.agentHalf)
       : null,
     settings,
+    identity,
+    web,
     approvalRequired,
     ...(withheld.length > 0 ? { autoApproveWithheld: withheld } : {}),
   };
@@ -654,7 +845,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 +898,9 @@ async function applyUpdate(op, { plugin, staged, approvedBy, actor, logger }) {
         hooks: installed.manifest.hooks,
         hooksEntrySha256: installed.hooksEntrySha256,
         agent: installed.manifest.agent,
+        identity: identityOf(installed.manifest),
+        userSurface: installed.manifest.userSurface,
+        webTreeSha256: installed.webTreeSha256,
       };
       let approval;
       try {
@@ -719,6 +916,7 @@ async function applyUpdate(op, { plugin, staged, approvedBy, actor, logger }) {
         installed.manifest,
         installed.hooksEntrySha256,
         staged.agentHalfPin,
+        installed.webTreeSha256,
       );
       if (approval.required) {
         await recordApprovedSet(installedEntry, approval.digest, staged.version, approvedBy);
@@ -726,6 +924,13 @@ async function applyUpdate(op, { plugin, staged, approvedBy, actor, logger }) {
       setPluginCapabilities(await getPluginCapabilities());
       createdSecrets = await syncOidcBestEffort(logger);
     },
+    // The new version's tree served now, as part of the update: users of
+    // its site reach the new half without a gap, and a tree that cannot be
+    // served reverts the update rather than leave the site at 503.
+    serve: async () => {
+      const { syncWebSurfaceTree } = await import('./web-surface.js');
+      await syncWebSurfaceTree(plugin.route, { logger });
+    },
     revert: async ({ applied }) => {
       if (applied) {
         const restored = await replacePluginPackage(
@@ -739,6 +944,7 @@ async function applyUpdate(op, { plugin, staged, approvedBy, actor, logger }) {
           restored.manifest,
           restored.hooksEntrySha256,
           plugin.agentHalfPin ?? null,
+          restored.webTreeSha256,
         );
         await restoreHookState(name, priorHookState);
         setPluginCapabilities(await getPluginCapabilities());
@@ -760,6 +966,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.

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

@@ -8,6 +8,12 @@
  * manifest, so it must stay inside the package, be a regular file (not a
  * link) and be no larger than {@link HOOK_MODULE_MAX_BYTES}.
  *
+ * A web surface's tree (`userSurface.web.root`) is read the same two ways:
+ * from the staged tarball, so its digest can be approved, and from the
+ * installed package, which must hold the very same tree — every file a
+ * regular one, no link on the way (core `webTreeManifestOfTarball`,
+ * `webTreeManifestOfDirectory`).
+ *
  * An agent half Lamaste installs onto an agent is never fetched here: its
  * tarball's integrity is read from the registry ({@link pinAgentHalf}) and
  * pinned with the version, and the agent fetches the tarball itself and
@@ -26,8 +32,13 @@ import {
   hookEntrySha256,
   relayHookSetNeedsEntry,
   relayHookSetOf,
+  WebTreeError,
 } from '@lamalibre/lamaste';
-import { readTarballFiles } from '@lamalibre/lamaste/server';
+import {
+  readTarballFiles,
+  webTreeManifestOfDirectory,
+  webTreeManifestOfTarball,
+} from '@lamalibre/lamaste/server';
 import { httpError } from './app-error.js';
 import { withRegistryUserconfig } from './registry-credential.js';
 
@@ -88,6 +99,62 @@ export async function installedHookEntrySha256(packageName, manifest) {
   return hookEntrySha256(await readInstalledHookModule(dir, set.entry));
 }
 
+/**
+ * Run a web tree read, turning a broken rule into a 400 that names the
+ * version's tree.
+ *
+ * @template T
+ * @param {string} what — the package (and version) whose tree it is
+ * @param {() => T | Promise<T>} read
+ * @returns {Promise<T>}
+ */
+async function webTreeOrRefusal(what, read) {
+  try {
+    return await read();
+  } catch (err) {
+    if (err instanceof WebTreeError) {
+      throw httpError(`The web surface of ${what} cannot be served: ${err.message}`, 400, {
+        code: 'invalid_web_tree',
+      });
+    }
+    throw err;
+  }
+}
+
+/**
+ * The directory of an installed package's web tree (`userSurface.web.root`,
+ * already a relative path of safe segments — core `WebSurfaceBlockSchema`),
+ * refused when it leaves the package or reaches it through a link.
+ */
+export async function installedWebTreeDir(packageName, manifest) {
+  const root = manifest.userSurface?.web?.root;
+  if (!root) return null;
+  const packageDir = await installedPackageDir(packageName);
+  const resolved = path.resolve(packageDir, root);
+  if (!resolved.startsWith(`${packageDir}${path.sep}`)) {
+    throw httpError('The web surface lies outside its package', 400, { code: 'invalid_web_tree' });
+  }
+  const real = await realpath(resolved).catch(() => null);
+  if (real !== null && real !== resolved) {
+    throw httpError('The web surface path goes through a link', 400, { code: 'invalid_web_tree' });
+  }
+  return resolved;
+}
+
+/**
+ * For a validated manifest of an installed package: its web tree's digest
+ * (core `webTreeManifest`'s `sha256`), or null when it declares no web
+ * surface. Throws 400 when the tree breaks a rule.
+ */
+export async function installedWebTreeSha256(packageName, manifest) {
+  const dir = await installedWebTreeDir(packageName, manifest);
+  if (dir === null) return null;
+  const tree = await webTreeOrRefusal(`${packageName}@${manifest.version}`, () =>
+    webTreeManifestOfDirectory(dir),
+  );
+  return tree.sha256;
+}
+
 /**
  * Fetch `<package>@<version>` from the registry the panel installs from
  * (`npm pack` through {@link withRegistryUserconfig}: the configured
@@ -97,7 +164,7 @@ export async function installedHookEntrySha256(packageName, manifest) {
  *
  * @param {string} packageName bare `@lamalibre/<name>`
  * @param {string} version an exact version or a dist-tag (`latest`)
- * @returns {Promise<{ version: string, manifestRaw: unknown, readHookModule: (entry: string) => Buffer | null }>}
+ * @returns {Promise<{ version: string, manifestRaw: unknown, readHookModule: (entry: string) => Buffer | null, readWebTree: (root: string) => Promise<import('@lamalibre/lamaste').WebTreeManifest> }>}
  */
 export async function readRegistryPackage(packageName, version) {
   if (!PACKAGE_RE.test(packageName)) throw httpError('Invalid package name', 400);
@@ -157,6 +224,11 @@ export async function readRegistryPackage(packageName, version) {
           }).get(name) ?? null
         );
       },
+      readWebTree(root) {
+        return webTreeOrRefusal(`${packageName}@${info.version}`, () =>
+          webTreeManifestOfTarball(tgz, root),
+        );
+      },
     };
   } finally {
     await rm(dir, { recursive: true, force: true });