@lamalibre/create-lamaste 4.5.0 → 4.6.0

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

@@ -39,7 +39,7 @@ import {
   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 {
@@ -51,7 +51,7 @@ import {
   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,
@@ -314,7 +314,8 @@ function identityApprovalRequired(identity) {
  * in for an administrator on the first reason alone:
  *
  * - `digest.unapproved` — what it brings (relay hooks, the agent half
- *   Lamaste installs, its identity block) is not what was approved;
+ *   Lamaste installs, its identity block, its web tree) is not what was
+ *   approved;
  * - `settings.secret-to-plain` — {@link settingsApprovalRequired};
  * - `identity.changed` — {@link identityApprovalRequired}.
  *
@@ -334,6 +335,7 @@ function approvalRequiredFor(staged, state, settings, identity) {
             relay: staged.relaySet,
             agentHalf: staged.agentHalf,
             identity: staged.identity,
+            web: staged.webTree,
           }),
         ]),
     ...settingsApprovalRequired(settings),
@@ -446,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 = {
@@ -457,6 +463,8 @@ async function stageVersion(plugin, requestedVersion, record) {
     agentHalfPin,
     settings: manifest.settings,
     identity: identityOf(manifest),
+    userSurface: manifest.userSurface,
+    webTreeSha256: webTree?.sha256 ?? null,
   };
   const approval = installedApproval(entry);
   return {
@@ -470,6 +478,8 @@ async function stageVersion(plugin, requestedVersion, record) {
     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,
@@ -514,6 +524,104 @@ function identityPreview(plugin, manifest) {
   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 }`
@@ -573,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
+    // 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 })),
@@ -591,6 +700,7 @@ export async function updatePlugin(
         staged,
         settings,
         identity,
+        web: await webPreview(plugin, staged),
         approvalRequired,
         withheldReasons,
         actor,
@@ -670,6 +780,7 @@ async function awaitApproval({
   staged,
   settings,
   identity,
+  web,
   approvalRequired,
   withheldReasons,
   actor,
@@ -688,6 +799,7 @@ async function awaitApproval({
       : null,
     settings,
     identity,
+    web,
     approvalRequired,
     ...(withheld.length > 0 ? { autoApproveWithheld: withheld } : {}),
   };
@@ -787,6 +899,8 @@ async function applyUpdate(op, { plugin, staged, approvedBy, actor, logger }) {
         hooksEntrySha256: installed.hooksEntrySha256,
         agent: installed.manifest.agent,
         identity: identityOf(installed.manifest),
+        userSurface: installed.manifest.userSurface,
+        webTreeSha256: installed.webTreeSha256,
       };
       let approval;
       try {
@@ -802,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);
@@ -809,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(
@@ -822,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());

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 });

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

@@ -31,6 +31,7 @@ import { RegistryCredentialError } from '@lamalibre/lamaste/server';
 import {
   bareLamalibrePackageName,
   installedHookEntrySha256,
+  installedWebTreeSha256,
   pinAgentHalf,
 } from './plugin-packages.js';
 
@@ -72,8 +73,9 @@ async function getStmts() {
       INSERT INTO plugins
         (name, route, display_name, package_name, version, description, capabilities,
          packages, panel, config, modes, hosting, agent, hooks, hooks_entry_sha256,
-         agent_half_pin, settings, identity, status, installed_at, enabled_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         agent_half_pin, settings, identity, user_surface, web_tree_sha256, status,
+         installed_at, enabled_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `),
     deleteByName: db.prepare('DELETE FROM plugins WHERE name = ?'),
     // The plugin's audience and the state of its identity feed
@@ -141,6 +143,8 @@ function rowToPlugin(row) {
   if (row.agent_half_pin != null) entry.agentHalfPin = JSON.parse(row.agent_half_pin);
   if (row.settings != null) entry.settings = JSON.parse(row.settings);
   if (row.identity != null) entry.identity = JSON.parse(row.identity);
+  if (row.user_surface != null) entry.userSurface = JSON.parse(row.user_surface);
+  if (row.web_tree_sha256 != null) entry.webTreeSha256 = row.web_tree_sha256;
   if (row.enabled_at != null) entry.enabledAt = row.enabled_at;
   return entry;
 }
@@ -224,6 +228,8 @@ export async function writePlugins(data) {
         nullableJson(p.agentHalfPin),
         nullableJson(p.settings),
         nullableJson(p.identity),
+        nullableJson(p.userSurface),
+        nullableString(p.webTreeSha256),
         p.status,
         p.installedAt,
         nullableString(p.enabledAt),
@@ -457,6 +463,17 @@ export function installPlugin(packageName, logger) {
       throw Object.assign(new Error(err.message), { statusCode: err.statusCode || 400 });
     }
 
+    // A web surface: its tree must be in the package and keep every rule of
+    // a web tree; its digest goes into the approval digest, and the relay
+    // serves only a copy that matches it.
+    let webTreeSha256 = null;
+    try {
+      webTreeSha256 = await installedWebTreeSha256(packageName, manifest);
+    } catch (err) {
+      await discardPackage();
+      throw Object.assign(new Error(err.message), { statusCode: err.statusCode || 400 });
+    }
+
     // An agent half Lamaste installs: its tarball's integrity is pinned now,
     // from the registry this install used — the approval covers it and the
     // agent installs only a tarball that matches it.
@@ -508,6 +525,8 @@ export function installPlugin(packageName, logger) {
       agentHalfPin,
       settings: manifest.settings,
       identity: identityOf(manifest),
+      userSurface: manifest.userSurface,
+      webTreeSha256,
       status: 'disabled',
       installedAt: new Date().toISOString(),
     };
@@ -536,6 +555,8 @@ export function installPlugin(packageName, logger) {
         nullableJson(entry.agentHalfPin),
         nullableJson(entry.settings),
         nullableJson(entry.identity),
+        nullableJson(entry.userSurface),
+        nullableString(entry.webTreeSha256),
         entry.status,
         entry.installedAt,
         null,
@@ -684,7 +705,7 @@ const updateRowSql = `
   UPDATE plugins SET
     display_name = ?, version = ?, description = ?, capabilities = ?, packages = ?, panel = ?,
     config = ?, modes = ?, hosting = ?, agent = ?, hooks = ?, hooks_entry_sha256 = ?,
-    agent_half_pin = ?, settings = ?, identity = ?
+    agent_half_pin = ?, settings = ?, identity = ?, user_surface = ?, web_tree_sha256 = ?
   WHERE name = ?`;
 
 /**
@@ -698,8 +719,16 @@ const updateRowSql = `
  * beside it, and a secret whose field became a plain value is no longer
  * reported set. The identity block is stored normalized; the update's
  * caller recomputes the audiences once the version is in place.
+ * `webTreeSha256` is the digest of the version's web tree, read from the
+ * installed package (null when it declares no web surface).
  */
-export async function writePluginRow(name, manifest, hooksEntrySha256, agentHalfPin) {
+export async function writePluginRow(
+  name,
+  manifest,
+  hooksEntrySha256,
+  agentHalfPin,
+  webTreeSha256 = null,
+) {
   const s = await getStmts();
   const { prunedSettingsCache } = await import('./plugin-settings.js');
   s.begin.run();
@@ -723,6 +752,8 @@ export async function writePluginRow(name, manifest, hooksEntrySha256, agentHalf
         nullableJson(agentHalfPin),
         nullableJson(manifest.settings),
         nullableJson(identityOf(manifest)),
+        nullableJson(manifest.userSurface),
+        nullableString(webTreeSha256),
         name,
       );
     const pruned = prunedSettingsCache(
@@ -750,7 +781,8 @@ export async function writePluginRow(name, manifest, hooksEntrySha256, agentHalf
 
 /**
  * Install `<packageName>@<version>` over the installed copy and read it
- * back: the validated manifest and its relay entry module's SHA-256. The
+ * back: the validated manifest, its relay entry module's SHA-256 and its
+ * web tree's digest. The
  * row is not touched — the caller compares the result with what was
  * reviewed and then writes it. Refuses a package whose manifest names
  * another plugin.
@@ -790,7 +822,8 @@ export function replacePluginPackage(name, packageName, version, logger) {
       );
     }
     const hooksEntrySha256 = await installedHookEntrySha256(packageName, manifest);
-    return { manifest, hooksEntrySha256 };
+    const webTreeSha256 = await installedWebTreeSha256(packageName, manifest);
+    return { manifest, hooksEntrySha256, webTreeSha256 };
   });
 }
 

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

@@ -95,6 +95,24 @@ export async function writeSites(sites) {
   await rename(tmpPath, filePath);
 }
 
+/** Serializes every read-modify-write of sites.json in this process. */
+const sitesMutex = new PromiseChainMutex();
+
+/**
+ * Run `fn` holding the sites lock: a read of sites.json, the decisions made
+ * on it and the write that follows must not interleave with another. A
+ * workflow that gives a site a hostname (creating it, adding an alias,
+ * taking a tunnel's host) takes core's tunnel lock first, then this one —
+ * always in that order — so a site and a tunnel never take one name at once.
+ *
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+export function withSitesLock(fn) {
+  return sitesMutex.run(fn);
+}
+
 function invitationsPath() {
   return path.join(STATE_DIR, 'invitations.json');
 }

package/vendor/serverd/src/lib/user-surface.js

@@ -45,8 +45,11 @@ import {
   RELAY_PANEL_AUDIENCE,
   RELAY_PANEL_PORT,
   isAgentHostedPlugin,
+  siteUserSurfaceRoute,
   tunnelUserSurfaceRoutes,
+  userSurfaceHostServing,
   userSurfaceHostingAgent,
+  userSurfaceHosts,
   verifyRelayAssertion,
 } from '@lamalibre/lamaste';
 import {
@@ -62,7 +65,7 @@ import { getConfig } from './config.js';
 import { installedVersionApproved } from './plugin-hooks.js';
 import { findPluginByRoute } from './plugins.js';
 import { relaySigner } from './relay-signing.js';
-import { readTunnels } from './state.js';
+import { readSites, readTunnels } from './state.js';
 import { tunnelCertbotDeps, tunnelNginxDeps, tunnelStateDeps } from './tunnel-deps.js';
 
 /**
@@ -102,7 +105,7 @@ export const USER_SURFACE_ROUTE_CONFIG = Object.freeze({
  * @param {readonly object[]} tunnels
  * @returns {Promise<string | null>}
  */
-async function hostingAgentOf(plugin, tunnels) {
+export async function hostingAgentOf(plugin, tunnels) {
   if (!plugin.route) return null;
   const { ownHosting } = await import('./plugin-hosting.js');
   const record = await ownHosting(plugin);
@@ -160,7 +163,7 @@ async function routeServing(route, agentLabel, tunnels) {
  * @param {object} plugin
  * @param {readonly object[]} tunnels the tunnel state
  */
-async function internalTunnelBodyLimit(plugin, tunnels) {
+export async function internalTunnelBodyLimit(plugin, tunnels) {
   const { ownHosting } = await import('./plugin-hosting.js');
   const record = await ownHosting(plugin);
   if (!record) return TUNNEL_MAX_BODY_MB.default;
@@ -287,6 +290,14 @@ async function assertBindableRoute(route) {
       'INVALID_SETTING',
     );
   }
+  // A route is served on one host at most: the plugin's own site, when it
+  // has one, is that host.
+  if ((await readSites()).some((site) => siteUserSurfaceRoute(site) === route)) {
+    throw new TunnelError(
+      `Plugin "${plugin.name}" has a web surface — its user surface is served there`,
+      'INVALID_SETTING',
+    );
+  }
 }
 
 /** Whether an installed agent-hosted plugin holds `route`. */
@@ -413,7 +424,8 @@ export async function refreshTunnelUserSurfaceVhosts(ids, logger) {
  * Whether plugin `route`'s user surface is served may have changed — its
  * version was approved, updated or reverted, it was hosted or unhosted (the
  * body limit is its internal tunnel's): bring the vhosts of the tunnels it
- * is bound to in line. Best effort — logged, never thrown; the panel's
+ * is bound to in line, and its web surface — the approved tree served, the
+ * vhost of the site it owns (`lib/web-surface.js`). Best effort — logged, never thrown; the panel's
  * start reconciles every vhost again.
  *
  * @param {string | null | undefined} route
@@ -429,6 +441,9 @@ export async function refreshUserSurfaceVhosts(route, logger) {
       'Could not bring the user-surface vhosts of a plugin in line',
     );
   }
+  // Its web surface too: the approved tree served, the site's vhost in line.
+  const { refreshWebSurface } = await import('./web-surface.js');
+  await refreshWebSurface(route, logger);
 }
 
 /**
@@ -491,6 +506,10 @@ export async function releasePluginUserSurface(route, { plugin, logger }) {
       'Could not release the user surface of an uninstalled plugin',
     );
   }
+  // The site it owns stays, answering 503 until the plugin is back (or an
+  // administrator deletes it): its vhost goes in line.
+  const { refreshWebSurface } = await import('./web-surface.js');
+  await refreshWebSurface(route, logger);
 }
 
 // ---------------------------------------------------------------------------
@@ -560,33 +579,35 @@ export async function verifyUserSurfaceRelay(request) {
 }
 
 /**
- * The enabled tunnel whose host serves `route`'s user surface, or null:
- * bound to the route, and carried by the agent hosting its plugin — the
- * check of every request, whatever a vhost not yet re-rendered still
- * routes here.
+ * The enabled host that serves `route`'s user surface, or null — the check
+ * of every request, whatever a vhost not yet re-rendered still routes here:
+ * a tunnel bound to the route and carried by the agent hosting its plugin,
+ * or the site the plugin owns while its web surface is served
+ * (`lib/web-surface.js`). Read with core `userSurfaceHosts`, as Gatekeeper
+ * reads it, so a route two hosts would serve is served by neither.
  *
  * @param {string} route
+ * @returns {Promise<import('@lamalibre/lamaste').UserSurfaceHost | null>}
  */
-async function servedUserSurfaceTunnel(route) {
-  const tunnels = await readTunnels();
-  const tunnel =
-    tunnels.find(
-      (t) =>
-        t.enabled !== false &&
-        typeof t.fqdn === 'string' &&
-        tunnelUserSurfaceRoutes(t).includes(route),
-    ) ?? null;
-  if (!tunnel) return null;
+async function servedUserSurfaceHost(route) {
+  const [tunnels, sites] = await Promise.all([readTunnels(), readSites()]);
+  const host = userSurfaceHostServing(userSurfaceHosts(tunnels, sites), route);
+  if (!host) return null;
+  if (host.kind === 'site') {
+    const { webSurfaceServing } = await import('./web-surface.js');
+    return (await webSurfaceServing(route, tunnels)).served ? host : null;
+  }
   const plugin = await findPluginByRoute(route);
   if (!plugin) return null;
+  const tunnel = tunnels.find((t) => t.id === host.id);
   const hosting = await hostingAgentOf(plugin, tunnels);
-  return hosting !== null && tunnel.agentLabel === hosting ? tunnel : null;
+  return hosting !== null && tunnel?.agentLabel === hosting ? host : null;
 }
 
 /**
  * The forward target of `route`'s user surface (core `userSurfacePlugin`'s
- * `resolveTarget`): null when no enabled tunnel its hosting agent carries
- * is bound to it, else what the admin forwarder resolves — the hosting's
+ * `resolveTarget`): null when no host serves it (see
+ * {@link servedUserSurfaceHost}), else what the admin forwarder resolves — the hosting's
  * internal tunnel, or why not (not found, disabled, not hosted) — and
  * `down` while the hosting's health is down: nothing of a user's request
  * reaches the relay-loopback port then (503).
@@ -594,7 +615,7 @@ async function servedUserSurfaceTunnel(route) {
  * @param {string} route
  */
 export async function resolveUserSurfaceTarget(route) {
-  if (!(await servedUserSurfaceTunnel(route))) return null;
+  if (!(await servedUserSurfaceHost(route))) return null;
   const { resolveForwardTarget } = await import('./plugin-hosting.js');
   return resolveForwardTarget(route);
 }
@@ -602,15 +623,15 @@ export async function resolveUserSurfaceTarget(route) {
 /**
  * The origin a request that may change something on `route`'s user surface
  * must come from (core `userSurfacePlugin`'s `originFor`): the bound host,
- * as the tunnel state names it — never the request's `Host`. Null when no
- * enabled tunnel its hosting agent carries is bound to the route.
+ * as the state names it — never the request's `Host`. Null when no host
+ * serves the route.
  *
  * @param {string} route
  * @returns {Promise<string | null>}
  */
 export async function userSurfaceOrigin(route) {
-  const tunnel = await servedUserSurfaceTunnel(route);
-  return tunnel ? `https://${tunnel.fqdn.toLowerCase()}` : null;
+  const host = await servedUserSurfaceHost(route);
+  return host ? `https://${host.fqdn}` : null;
 }
 
 // ---------------------------------------------------------------------------
@@ -702,7 +723,7 @@ export async function sweepOpenUserSurfaceResponses(logger) {
       const { route, caller } = response;
       let verdict;
       try {
-        if (!served.has(route)) served.set(route, (await servedUserSurfaceTunnel(route)) !== null);
+        if (!served.has(route)) served.set(route, (await servedUserSurfaceHost(route)) !== null);
         const key = `${route}\n${caller.username}`;
         if (!callers.has(key)) callers.set(key, await resolveUserCaller(route, caller.username));
         const resolution = callers.get(key);