@lamalibre/create-lamaste 4.5.0 → 4.6.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-DSaDPJaw.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-D-fer5ef.css">
+    <script type="module" crossorigin src="/assets/index-BvEfCZYS.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BZwQ_aQc.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.5.0",
+  "version": "4.6.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.5.0",
+    "@lamalibre/lamaste": "^4.6.0",
     "bcryptjs": "^3.0.3",
     "execa": "^9.6.1",
     "fastify": "^5.8.4",

package/vendor/serverd/src/index.js

@@ -45,6 +45,7 @@ import { startIdentityServices, stopIdentityServices } from './lib/identity-sync
 import { syncOidcClients } from './lib/plugin-oidc.js';
 import { ensureRelaySigningKey } from './lib/relay-signing.js';
 import { reconcileSiteVhosts, reconcileTunnelVhosts } from './lib/vhost-reconcile.js';
+import { reconcileWebSurfaces } from './lib/web-surface.js';
 import {
   loadTicketScopeCapabilities,
   checkInstanceLiveness,
@@ -217,7 +218,7 @@ async function start() {
 
   // The auth portal and static site vhosts an older version wrote name the
   // client's Host header, not their own hostname, to Authelia. Before listen:
-  // site changes take no lock, and none can arrive until the panel listens.
+  // no site change can arrive until the panel listens.
   if (config.onboarding.status === 'COMPLETED' && config.domain) {
     await reconcileSiteVhosts(server.log, config.domain).catch((err) => {
       server.log.error({ err: err.message }, 'Startup site vhost reconcile failed');
@@ -239,9 +240,13 @@ async function start() {
   // relay, and Gatekeeper vhosts name the client's Host header to Gatekeeper.
   // After listen: a rewritten agent-panel vhost asks this server at once.
   if (config.onboarding.status === 'COMPLETED') {
-    reconcileTunnelVhosts(server.log).catch((err) => {
-      server.log.error({ err: err.message }, 'Startup tunnel vhost reconcile failed');
-    });
+    reconcileTunnelVhosts(server.log)
+      .catch((err) => {
+        server.log.error({ err: err.message }, 'Startup tunnel vhost reconcile failed');
+      })
+      // Plugins' web surfaces: each approved tree served (a redeploy may
+      // have reset the web root), each site's vhost in line.
+      .then(() => reconcileWebSurfaces(server.log));
   }
 
   // --- Health of hosted agent-hosted plugins (every 10s; idle without hostings) ---

package/vendor/serverd/src/lib/chisel-runtime.js

@@ -30,17 +30,29 @@ export function chiselReloadsAuthfile() {
 }
 
 /**
- * Restart chisel if the change requires it. `try-restart` leaves a stopped
- * chisel stopped (see chisel-reconcile.js: a server that failed to reconcile
- * keeps chisel down until it succeeds).
+ * Whether an authfile change must restart chisel: a grant withdrawn (so
+ * live sessions drop the binding) — unless `keepLiveSessions` — or any
+ * change a chisel too old to reload its authfile would not see.
+ *
+ * @param {{ changed: boolean, revoked: boolean }} change
+ * @param {{ keepLiveSessions?: boolean }} [opts]
+ */
+export function authfileChangeNeedsRestart(change, { keepLiveSessions = false } = {}) {
+  return (change.revoked && !keepLiveSessions) || (change.changed && !runningPinnedRelease);
+}
+
+/**
+ * Restart chisel if the change requires it ({@link authfileChangeNeedsRestart}).
+ * `try-restart` leaves a stopped chisel stopped (see chisel-reconcile.js: a
+ * server that failed to reconcile keeps chisel down until it succeeds).
  *
  * @param {{ changed: boolean, revoked: boolean }} change
  * @param {import('pino').Logger} [logger]
+ * @param {{ keepLiveSessions?: boolean }} [opts]
  * @returns {Promise<{ restartOk: boolean, restartError?: string }>}
  */
-export async function applyAuthfileChange(change, logger) {
-  const needsRestart = change.revoked || (change.changed && !runningPinnedRelease);
-  if (!needsRestart) return { restartOk: true };
+export async function applyAuthfileChange(change, logger, opts = {}) {
+  if (!authfileChangeNeedsRestart(change, opts)) return { restartOk: true };
   const result = await reloadChiselAuth(execa, logger);
   return result.ok ? { restartOk: true } : { restartOk: false, restartError: result.error };
 }

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

@@ -71,10 +71,18 @@ export function getChiselStatus() {
  * grant, chisel is restarted so live sessions drop the binding. Call only
  * after the tunnel state has been written. Throws if the restart fails,
  * since a withdrawn grant would otherwise stay live.
+ *
+ * `keepLiveSessions`: withdraw the grant for new sessions only, without the
+ * restart — which drops every session, the hosting agents' internal plugin
+ * tunnels with them. Only for a port nothing routes to any more, whose
+ * agent drops the binding at its next sync (a tunnel moved to a plugin's
+ * web surface).
+ *
+ * @param {{ keepLiveSessions?: boolean }} [opts]
  */
-export async function syncChisel() {
+export async function syncChisel(opts = {}) {
   const change = await syncChiselAuthfile();
-  const { restartOk, restartError } = await applyAuthfileChange(change);
+  const { restartOk, restartError } = await applyAuthfileChange(change, undefined, opts);
   if (!restartOk) {
     throw new Error(`Chisel restart failed after withdrawing a port grant: ${restartError}`);
   }

package/vendor/serverd/src/lib/gatekeeper-client.js

@@ -225,26 +225,37 @@ function groupOf(raw) {
 }
 
 /**
- * Every grant on plugin `route` (`resourceType: 'plugin'`, `resourceId:
- * <route>`) — with roles or without.
+ * Every grant on one resource (`resourceType`, `resourceId`).
  *
- * @param {string} route
+ * @param {string} resourceType
+ * @param {string} resourceId
  * @returns {Promise<{ ok: true, grants: GatekeeperGrant[] } | Extract<GatekeeperResult, { ok: false }>>}
  */
-export async function listPluginGrants(route) {
-  const qs = new URLSearchParams({ resourceType: 'plugin', resourceId: route }).toString();
+export async function listResourceGrants(resourceType, resourceId) {
+  const qs = new URLSearchParams({ resourceType, resourceId }).toString();
   const result = await gatekeeperRequest('GET', `/api/grants?${qs}`);
   if (!result.ok) return result;
   if (!isRecord(result.data) || !Array.isArray(result.data.grants)) return malformed('its grants');
   const grants = result.data.grants.map(grantOf);
   if (grants.some((g) => g === null)) return malformed('its grants');
-  // Gatekeeper filters by the query; a grant on anything else is not this plugin's.
+  // Gatekeeper filters by the query; a grant on anything else is not this resource's.
   return {
     ok: true,
-    grants: grants.filter((g) => g.resourceType === 'plugin' && g.resourceId === route),
+    grants: grants.filter((g) => g.resourceType === resourceType && g.resourceId === resourceId),
   };
 }
 
+/**
+ * Every grant on plugin `route` (`resourceType: 'plugin'`, `resourceId:
+ * <route>`) — with roles or without.
+ *
+ * @param {string} route
+ * @returns {Promise<{ ok: true, grants: GatekeeperGrant[] } | Extract<GatekeeperResult, { ok: false }>>}
+ */
+export function listPluginGrants(route) {
+  return listResourceGrants('plugin', route);
+}
+
 /**
  * Every Lamaste group with its members.
  *

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

@@ -871,8 +871,10 @@ export async function runUninstallPipeline(op, ctx, { force = false } = {}) {
 /**
  * The install pipeline around an upgrade of the relay package (the agent
  * half is already running; its stages go through the tunnel). `apply` is
- * Lamaste's step — install the new package and its hook module; `revert`
- * restores the previous ones. Agent and relay stages see `phase: "upgrade"`.
+ * Lamaste's step — install the new package and its hook module; `serve`,
+ * when given, is the last step (the new version's web tree served, once
+ * every stage passed);
+ * `revert` restores the previous ones. Agent and relay stages see `phase: "upgrade"`.
  *
  * A hosted plugin whose agent half Lamaste installs gets the new version of
  * it first (after the agent's pre stage): the agent's helper installs it
@@ -880,7 +882,7 @@ export async function runUninstallPipeline(op, ctx, { force = false } = {}) {
  * tunnel. A failure after that switch activates the version that ran
  * before (`ctx.previousAgentHalfVersion`).
  */
-export async function runUpgradePipeline(op, ctx, { apply, revert, hosted }) {
+export async function runUpgradePipeline(op, ctx, { apply, serve, revert, hosted }) {
   let applied = false;
   try {
     if (hosted) {
@@ -906,6 +908,9 @@ export async function runUpgradePipeline(op, ctx, { apply, revert, hosted }) {
       await agentStageOrSkip(op, ctx, 'install:post-tunnel', 'upgrade', 'tunnel');
       await relayStageOrSkip(op, ctx, 'install:post-tunnel', 'upgrade');
     }
+    // What the new version serves its users from the relay (its web tree):
+    // the last step, once every stage passed — a failure still reverts.
+    if (serve) await op.step('serve the new web tree', serve);
   } catch (err) {
     op.warn(`Reverting: ${String(err.message ?? err).slice(0, 300)}`);
     try {

package/vendor/serverd/src/lib/migrations/state/0015_plugin_web_surface.sql

@@ -0,0 +1,14 @@
+-- A plugin's web surface (4.6, slice 7).
+--
+-- user_surface is the manifest's `userSurface` block as the installed
+-- version declares it (JSON; NULL when it declares none): its `web` names
+-- the default subdomain and access mode Lamaste offers for the plugin's own
+-- site and the directory of the server package that holds the shell.
+--
+-- web_tree_sha256 is the digest of that directory's web tree (core
+-- `webTreeManifest`), read from the installed package: it enters the
+-- approval digest, and the relay serves a copy of the tree only when the
+-- copy's own digest equals it. NULL when the version declares no web
+-- surface.
+ALTER TABLE plugins ADD COLUMN user_surface TEXT;
+ALTER TABLE plugins ADD COLUMN web_tree_sha256 TEXT;

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

@@ -7,6 +7,7 @@ import {
   USER_SURFACE_MAX_RESPONSE_SECONDS,
   isUserSurfaceRoute,
   userSurfaceApiPath,
+  WEB_TREE_CONTENT_TYPES,
 } from '@lamalibre/lamaste';
 
 const SITES_AVAILABLE = '/etc/nginx/sites-available';
@@ -590,12 +591,14 @@ const USER_SURFACE_PROXY_HEADERS = `
  * `X-Original-URL` and in `Host` — never by the client's `Host` header (see
  * {@link originalUrl}) — and the session cookie is passed on.
  *
- * @param {'tunnel'|'user-surface'} check
+ * @param {'tunnel'|'user-surface'|'user-surface-shell'} check
  * @param {string} fqdn
  * @returns {string}
  */
 function gatekeeperSubrequest(check, fqdn) {
   return `internal;
+        # A subrequest is never authorized itself (a host may authorize at server level)
+        auth_request off;
 
         proxy_pass http://127.0.0.1:9294/authz/${check}/${fqdn};
         proxy_pass_request_body off;
@@ -673,7 +676,7 @@ ${USER_SURFACE_PROXY_HEADERS}
     # The user surface of plugin "${route}"
     location = ${apiPath} ${block}
 
-    location ${apiPath}/ ${block}
+    location ^~ ${apiPath}/ ${block}
 `;
   });
   return `
@@ -685,6 +688,7 @@ ${USER_SURFACE_PROXY_HEADERS}
 
     location = /internal/lamaste/user-surface-401 {
         internal;
+        auth_request off;
 
         proxy_pass http://127.0.0.1:9294/authz/user-surface-unauthenticated;
         proxy_pass_request_body off;
@@ -1163,6 +1167,269 @@ ${aliasBlock}`;
   return { name: `lamalibre-lamaste-site-${site.id}`, fqdn: site.fqdn, config };
 }
 
+/**
+ * The Content-Security-Policy of a plugin's web surface: its shell loads
+ * scripts, styles, fonts and images from its own host only and talks to its
+ * own host only (its user surface's API is there). Inline styles are
+ * allowed — frameworks set `style` attributes and insert component styles
+ * at run time — inline scripts never; no framing, no plugins, no foreign
+ * form targets.
+ */
+const WEB_SURFACE_CSP =
+  "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'self'; object-src 'none'";
+
+/**
+ * Response headers of the shell of a plugin's web surface, set in its
+ * locations — not at server level, where the API's answers (headed by the
+ * panel) would get a second copy. `no-cache`: a browser revalidates each file —
+ * a 304 while the tree is the same, the new file once an update switched
+ * it — so no page mixes two versions of the shell from its cache.
+ */
+const WEB_SURFACE_HEADERS = `
+        add_header Content-Security-Policy "${WEB_SURFACE_CSP}" always;
+        add_header X-Content-Type-Options nosniff always;
+        add_header X-Frame-Options DENY always;
+        add_header Referrer-Policy same-origin always;
+        add_header Cross-Origin-Opener-Policy same-origin always;
+        add_header Cross-Origin-Resource-Policy same-origin always;
+        add_header Cache-Control no-cache always;`;
+
+/**
+ * The content types of a web tree's files, by extension
+ * (`WEB_TREE_CONTENT_TYPES` — the only extensions a tree may hold).
+ */
+const WEB_SURFACE_TYPES = (() => {
+  const byType = new Map();
+  for (const [ext, type] of Object.entries(WEB_TREE_CONTENT_TYPES)) {
+    byType.set(type, [...(byType.get(type) ?? []), ext.slice(1)]);
+  }
+  const entries = [...byType].map(([type, exts]) => `            ${type} ${exts.join(' ')};`);
+  return `
+        types {
+${entries.join('\n')}
+        }`;
+})();
+
+/**
+ * The files a page still running the previous shell may ask for after an
+ * update — its scripts, styles, fonts and images — and nothing else: a
+ * document, an SVG or a manifest is never served from the previous tree.
+ */
+const WEB_SURFACE_SUBRESOURCE_RE = '[.](?:js|mjs|css|woff2?|ttf|otf|png|jpe?g|gif|webp|avif|ico)$';
+
+/**
+ * Service workers: never registered from a plugin's site. A worker outlives
+ * the tree that installed it — a revert, the site's deletion, the
+ * hostname's next owner — and answers in its place; asked for its script
+ * (`Service-Worker: script`), the site answers 404, which also
+ * unregisters a worker already installed at its next update check.
+ */
+const NO_SERVICE_WORKER = `
+        if ($http_service_worker) {
+            return 404;
+        }`;
+
+/**
+ * Render the vhost of a plugin's web surface — a site the plugin owns
+ * (`site.owner`). Pure; the startup reconcile renders it again to compare.
+ *
+ * While the plugin's surface is served (`opts.served`: its installed
+ * version approved, declaring identity and a web surface, hosted), the
+ * host serves two things under one Authelia session:
+ *
+ * - **the shell**: every path but the API, from the plugin's current tree
+ *   (`<treesDir>/current`), GET and HEAD only, each file under its own
+ *   content type (`WEB_SURFACE_TYPES`), never a service worker's script. Every request asks
+ *   Gatekeeper first (`/authz/user-surface-shell/<fqdn>`: a session in the
+ *   plugin's audience, and the site's grant when it is restricted) — a page
+ *   without a session goes to the login, a user without access gets the
+ *   access-request page. A script, style, font or image the current tree
+ *   lacks is looked for in the previous tree (a page still running the old
+ *   shell loads its lazy files after an update), else 404; any other
+ *   unknown path gets the current shell's `index.html`.
+ * - **the API**: `/api/<route>/app/*`, exactly as on a bound tunnel
+ *   ({@link userSurfaceLocations}).
+ *
+ * While it is not served the host answers every request with 503 — and,
+ * once its plugin is no longer installed (`opts.clearSiteData`), tells
+ * browsers to clear the site's storage.
+ *
+ * @param {{ id: string, fqdn: string }} site
+ * @param {string} certDir
+ * @param {string} domain
+ * @param {{ route: string, served: boolean, maxBodySizeMb: number, treesDir: string, clearSiteData?: boolean }} opts
+ * @returns {{ name: string, fqdn: string, config: string }}
+ */
+export function renderWebSurfaceVhost(site, certDir, domain, opts) {
+  const { route, served, maxBodySizeMb, treesDir, clearSiteData = false } = opts;
+  assertLiteralHostname(site.fqdn);
+  if (!isUserSurfaceRoute(route)) throw new Error(`Invalid web surface route: ${route}`);
+  if (!path.isAbsolute(treesDir) || !/^[A-Za-z0-9/._-]+$/.test(treesDir)) {
+    throw new Error(`Invalid web tree directory for nginx vhost: ${treesDir}`);
+  }
+  let certDirClean = certDir;
+  while (certDirClean.endsWith('/')) certDirClean = certDirClean.slice(0, -1);
+
+  const head = `server {
+    listen 443 ssl;
+    server_name ${site.fqdn};
+
+    ssl_certificate ${certDirClean}/fullchain.pem;
+    ssl_certificate_key ${certDirClean}/privkey.pem;
+
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+`;
+
+  if (!served) {
+    // A plugin no longer installed: whatever comes next on this hostname is
+    // not its shell, so browsers drop what it left — its storage, caches
+    // and service workers. Never while the plugin is only unhosted or
+    // awaiting approval: its users' data stays.
+    const clear = clearSiteData
+      ? `
+        add_header Clear-Site-Data '"storage"' always;`
+      : '';
+    return {
+      name: `lamalibre-lamaste-site-${site.id}`,
+      fqdn: site.fqdn,
+      config: `${head}
+    # The web surface of plugin "${route}" is not served now (not installed,
+    # not approved, not hosted, or its version declares no web surface)
+    location / {${NO_SERVICE_WORKER}
+        add_header Cache-Control no-store always;${clear}
+        return 503;
+    }
+}
+`,
+    };
+  }
+
+  const url = originalUrl(site.fqdn);
+  const config = `${head}
+    root ${treesDir}/current;
+    index index.html;
+
+    # Every path of the shell: Gatekeeper first (the API's locations ask on their own)
+    auth_request /internal/lamaste/shell-authz;
+    error_page 401 =302 https://auth.${domain}/?rd=${url};
+    error_page 403 = /internal/lamaste/shell-authz;
+
+    location = /internal/lamaste/shell-authz {
+        ${gatekeeperSubrequest('user-surface-shell', site.fqdn)}
+    }
+${userSurfaceLocations(site.fqdn, [{ route, maxBodySizeMb }])}
+    # A script, style, font or image the current tree lacks: the previous
+    # tree's (a page still running the old shell), else 404
+    location ~* ${WEB_SURFACE_SUBRESOURCE_RE} {
+        if ($request_method !~ ^(GET|HEAD)$) {
+            return 405;
+        }${NO_SERVICE_WORKER}
+${WEB_SURFACE_HEADERS}${WEB_SURFACE_TYPES}
+        try_files $uri @previous;
+    }
+
+    # Everything else: the current tree's file, else the shell
+    location / {
+        if ($request_method !~ ^(GET|HEAD)$) {
+            return 405;
+        }${NO_SERVICE_WORKER}
+${WEB_SURFACE_HEADERS}${WEB_SURFACE_TYPES}
+        try_files $uri /index.html;
+    }
+
+    location @previous {
+${WEB_SURFACE_HEADERS}${WEB_SURFACE_TYPES}
+        root ${treesDir}/previous;
+        try_files $uri =404;
+    }
+}
+`;
+  return { name: `lamalibre-lamaste-site-${site.id}`, fqdn: site.fqdn, config };
+}
+
+/**
+ * Write the vhost of a plugin's web surface (see {@link renderWebSurfaceVhost}).
+ *
+ * @param {{ id: string, fqdn: string }} site
+ * @param {string} certDir
+ * @param {string} domain
+ * @param {{ route: string, served: boolean, maxBodySizeMb: number, treesDir: string }} opts
+ */
+export async function writeWebSurfaceVhost(site, certDir, domain, opts) {
+  const { name, fqdn, config } = renderWebSurfaceVhost(site, certDir, domain, opts);
+  return safeWriteVhost(name, config, fqdn, { enabled: true });
+}
+
+/**
+ * Hand a hostname from one vhost to another in one nginx reload: vhost
+ * `fromName` is unlinked, `name` written with `config` and linked, the
+ * configuration tested and nginx reloaded once; `fromName` stays installed,
+ * unlinked. Until the reload nginx serves the old vhost, after it the new
+ * one; there is no moment in between. On any failure before the reload
+ * both are put back as they were.
+ *
+ * @param {string} fromName the vhost giving the hostname up (linked)
+ * @param {string} name a vhost that does not exist yet
+ * @param {string} config
+ * @param {string} fqdn
+ */
+async function handOverVhost(fromName, name, config, fqdn) {
+  if (await siteExists(name)) throw new Error(`Vhost ${name} exists already`);
+  const fromEnabled = await isSiteEnabled(fromName);
+  const restore = async () => {
+    await siteAction('remove', name).catch(() => {});
+    if (fromEnabled) await enableSite(fromName).catch(() => {});
+  };
+  try {
+    await disableSite(fromName);
+    await writeVhostFile(name, config);
+    await enableSite(name);
+    const result = await testConfig();
+    if (!result.valid) {
+      throw new Error(`Nginx config test failed handing ${fqdn} to ${name}: ${result.error}`);
+    }
+    await reload();
+  } catch (err) {
+    await restore();
+    throw err;
+  }
+  // `fromName` stays installed, only unlinked: the tunnel it served can be
+  // enabled again by hand once the new vhost is gone.
+}
+
+/**
+ * Unlink tunnel vhost `subdomain` when it is still enabled although a
+ * plugin's site holds its hostname — a move the panel did not finish (it
+ * wrote the state, then stopped before the handover). Does not reload:
+ * the caller's next vhost install does, or it reloads itself. Returns
+ * whether it unlinked.
+ *
+ * @param {string} subdomain the moved tunnel's
+ */
+export async function unlinkMovedAppVhost(subdomain) {
+  const name = `lamalibre-lamaste-app-${subdomain}`;
+  if (!(await isSiteEnabled(name))) return false;
+  await disableSite(name);
+  return true;
+}
+
+/**
+ * Serve a plugin's web surface on the hostname of tunnel vhost `subdomain`
+ * in one reload (see {@link handOverVhost}).
+ *
+ * @param {string} subdomain the tunnel's
+ * @param {{ id: string, fqdn: string }} site
+ * @param {string} certDir
+ * @param {string} domain
+ * @param {{ route: string, served: boolean, maxBodySizeMb: number, treesDir: string }} opts
+ */
+export async function moveAppVhostToWebSurface(subdomain, site, certDir, domain, opts) {
+  const { name, fqdn, config } = renderWebSurfaceVhost(site, certDir, domain, opts);
+  await handOverVhost(`lamalibre-lamaste-app-${subdomain}`, name, config, fqdn);
+}
+
 /**
  * Server block answering a site's aliases with a permanent redirect to the
  * primary hostname, on the same certificate (its lineage covers every alias).

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

@@ -218,28 +218,45 @@ export function installedAgentHalf(plugin) {
   return { ...declaration, version: pin.version, integrity: pin.integrity };
 }
 
+/**
+ * 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 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.
+ * 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 identity = plugin.identity ?? null;
-  const required = relay !== null || agentHalf !== null || 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,
   };
@@ -269,7 +286,7 @@ export async function installedVersionApproved(plugin) {
  */
 export async function hookStatus(plugin) {
   const approval = installedApproval(plugin);
-  const { relay, agentHalf, identity } = approval;
+  const { relay, agentHalf, identity, web } = approval;
   const agent = agentHookSetOf({ hooks: plugin.hooks });
   const state = await readHookState(plugin.name);
   const approved = isApproved(approval, state);
@@ -290,6 +307,12 @@ export async function hookStatus(plugin) {
       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',
@@ -319,16 +342,17 @@ 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`), its
- * identity block (`identity`); each truthy when it brings one — is not what
- * was approved.
+ * 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, identity = null }) {
+export function digestUnapprovedReason({ relay, agentHalf, identity = null, web = null }) {
   const parts = [
-    ...(relay || (!agentHalf && !identity) ? ['relay hooks'] : []),
+    ...(relay || (!agentHalf && !identity && !web) ? ['relay hooks'] : []),
     ...(agentHalf ? ['agent half'] : []),
     ...(identity ? ['identity'] : []),
+    ...(web ? ['web surface'] : []),
   ];
   const named =
     parts.length === 1
@@ -351,6 +375,7 @@ function pendingApprovalRequired(pending) {
         relay: pending.preview,
         agentHalf: pending.agentHalf,
         identity: pending.identity?.after ?? null,
+        web: pending.web?.after ?? null,
       }),
     ]
   );
@@ -369,7 +394,10 @@ function pendingApprovalRequired(pending) {
  * 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
+ * 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
@@ -385,6 +413,7 @@ export function pendingUpdateView(pending) {
     agentHalf: pending.agentHalf ?? null,
     settings: pending.settings ?? null,
     identity: pending.identity ?? null,
+    web: pending.web ?? null,
     approvalRequired: pendingApprovalRequired(pending),
     autoApproveWithheld: pending.autoApproveWithheld ?? null,
   };