@lamalibre/create-lamaste 4.5.0 → 4.7.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(
@@ -816,12 +938,14 @@ async function applyUpdate(op, { plugin, staged, approvedBy, actor, logger }) {
           plugin.packageName,
           plugin.version,
           logger,
+          { restoring: true },
         );
         await writePluginRow(
           name,
           restored.manifest,
           restored.hooksEntrySha256,
           plugin.agentHalfPin ?? null,
+          restored.webTreeSha256,
         );
         await restoreHookState(name, priorHookState);
         setPluginCapabilities(await getPluginCapabilities());

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

@@ -19,6 +19,16 @@
  * `identity_providers.oidc` section is written; Authelia is restarted only
  * when the section actually changed.
  *
+ * Every client belongs to a domain — its plugin's (the panel's own: the
+ * registry credential's issuer domain): `{domain}` in its audience and
+ * redirect URIs is that domain, and a user-facing client has its own
+ * authorization policy (core `renderOidcClientPolicies`): that domain's
+ * members, and its external members granted the client (a Gatekeeper grant
+ * `resourceType: 'oidc-client'`, rendered by lib/domains.js into users.yml's
+ * owned groups). The provider is written under lib/domains.js
+ * `withDomainRendering` — the one writer of what members may do — with the
+ * domains read under it.
+ *
  * Best effort by design where a plugin lifecycle calls it: a failure here
  * must not fail the plugin operation — the caller logs it and the next
  * lifecycle change retries.
@@ -26,9 +36,11 @@
 
 import { readFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
-import { validateManifest } from '@lamalibre/lamaste';
+import { PromiseChainMutex, validateInstalledManifest } from '@lamalibre/lamaste';
 import {
   LAMASTE_REGISTRY_OIDC_SCOPES,
+  LAMASTE_SERVER_OIDC_CLIENT_ID,
+  registryIssuerDomain,
   lamasteServerOidcClient,
   listOidcClientSecrets,
   reconcileOidcClientSecrets,
@@ -36,32 +48,43 @@ import {
   rotateOidcClientSecret,
 } from '@lamalibre/lamaste/server';
 
-import { getConfig } from './config.js';
 import { updateOidcProvider } from './authelia.js';
+import { listGrantsOfType } from './gatekeeper-client.js';
+import { OIDC_CLIENT_RESOURCE, isUserFacingOidcClient } from './owned-groups.js';
+import { pluginDomainOr, primaryDomainName, withDomainRendering } from './domains.js';
 import { readPlugins } from './plugins.js';
 import { readRegistryCredentialConfig } from './registry-credential.js';
 
 const STATE_DIR = process.env.LAMALIBRE_LAMASTE_STATE_DIR || '/etc/lamalibre/lamaste';
 
+/** The domains a rendering read, as the OIDC provider's policies name them: name and group key. */
+const keyed = (domains) => domains.map(({ name, groupKey }) => ({ name, groupKey }));
+
 /**
  * The OIDC clients every installed plugin declares, tagged with the plugin
- * name and whether the plugin is enabled. Manifests are re-read from the
- * installed packages — the plugin registry does not store them.
+ * name, its domain and whether the plugin is enabled. Manifests are re-read
+ * from the installed packages — the plugin registry does not store them.
  * @returns {Promise<Array<import('@lamalibre/lamaste/server').AutheliaOidcClient & { enabled: boolean }>>}
  */
 export async function collectPluginOidcClients() {
   const require = createRequire(`${STATE_DIR}/`);
+  const primary = await primaryDomainName();
   const clients = [];
   for (const plugin of (await readPlugins()).plugins) {
     let manifest;
     try {
       const manifestPath = require.resolve(`${plugin.packageName}/lamaste-plugin.json`);
-      manifest = validateManifest(JSON.parse(await readFile(manifestPath, 'utf-8')));
+      manifest = validateInstalledManifest(JSON.parse(await readFile(manifestPath, 'utf-8')));
     } catch {
       continue; // an unreadable manifest contributes no clients
     }
     for (const client of manifest.oidcClients) {
-      clients.push({ ...client, plugin: manifest.name, enabled: plugin.status === 'enabled' });
+      clients.push({
+        ...client,
+        plugin: manifest.name,
+        domain: pluginDomainOr(plugin, primary),
+        enabled: plugin.status === 'enabled',
+      });
     }
   }
   return clients;
@@ -69,31 +92,77 @@ export async function collectPluginOidcClients() {
 
 /**
  * The panel's own client, when the registry credential (stored, or the
- * candidate being verified) uses it.
- * @param {{ registryUrl: string } | null | undefined} registryAuth
+ * candidate being verified) uses it — of the credential's issuer domain.
+ * @param {{ registryUrl: string, issuerDomain?: string } | null | undefined} registryAuth
  */
-function lamasteOwnClient(registryAuth) {
+async function lamasteOwnClient(registryAuth) {
   if (!registryAuth) return [];
-  return [{ ...lamasteServerOidcClient(registryAuth.registryUrl), enabled: true }];
+  const domain = registryIssuerDomain(
+    { kind: 'oidc', clientId: LAMASTE_SERVER_OIDC_CLIENT_ID, ...registryAuth },
+    await primaryDomainName(),
+  );
+  return [{ ...lamasteServerOidcClient(registryAuth.registryUrl, domain), enabled: true }];
+}
+
+/**
+ * A registry credential being set (`PUT /api/registry-credential`): its
+ * `registryAuth` while the panel's client is synced, the chain verified and
+ * the credential stored. Every sync that names no override serves it — the
+ * identity tick's every-minute sync included, which otherwise reads the
+ * stored credential, removes the client the candidate needs and restarts
+ * Authelia under the verification's token request. Every sync reads it under
+ * the one writer ({@link syncOidcClients}), so none can write a plan made
+ * before it was set.
+ * @type {{ registryUrl: string, issuerDomain?: string } | undefined}
+ */
+let registryCandidate;
+const registryCandidateMutex = new PromiseChainMutex();
+
+/**
+ * Run `fn` with `registryAuth` as the candidate registry credential
+ * (see {@link registryCandidate}); one candidate at a time. Without one
+ * (a pasted token), `fn` just runs.
+ * @template T
+ * @param {{ registryUrl: string, issuerDomain?: string } | undefined} registryAuth
+ * @param {() => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+export function withRegistryCandidate(registryAuth, fn) {
+  if (registryAuth === undefined) return fn();
+  return registryCandidateMutex.run(async () => {
+    registryCandidate = registryAuth;
+    try {
+      return await fn();
+    } finally {
+      registryCandidate = undefined;
+    }
+  });
 }
 
 /**
  * Everything Authelia should know, from the stored state.
- * @param {{ registryAuth?: { registryUrl: string } | null }} [overrides]
+ * @param {{ registryAuth?: { registryUrl: string, issuerDomain?: string } | null }} [overrides]
  *   `registryAuth` replaces the stored registry credential's say in the
- *   matter: `{ registryUrl }` while a candidate oidc credential is being
- *   verified, `null` to leave the panel's client out.
+ *   matter: `{ registryUrl, issuerDomain }` while a candidate oidc
+ *   credential is being verified, `null` to leave the panel's client out.
  */
 async function collectAllClients(overrides = {}) {
   let registryAuth;
   if (overrides.registryAuth !== undefined) {
     registryAuth = overrides.registryAuth;
+  } else if (registryCandidate !== undefined) {
+    registryAuth = registryCandidate;
   } else {
     const stored = await readRegistryCredentialConfig().catch(() => null);
     registryAuth =
-      stored && stored.auth.kind === 'oidc' ? { registryUrl: stored.registryUrl } : null;
+      stored && stored.auth.kind === 'oidc'
+        ? {
+            registryUrl: stored.registryUrl,
+            ...(stored.auth.issuerDomain ? { issuerDomain: stored.auth.issuerDomain } : {}),
+          }
+        : null;
   }
-  return [...(await collectPluginOidcClients()), ...lamasteOwnClient(registryAuth)];
+  return [...(await collectPluginOidcClients()), ...(await lamasteOwnClient(registryAuth))];
 }
 
 /**
@@ -103,7 +172,7 @@ async function collectAllClients(overrides = {}) {
  * enabled plugins served, and the panel's own scopes when its client is.
  * Pure with respect to Authelia — nothing is written.
  *
- * @param {{ registryAuth?: { registryUrl: string } | null }} [overrides] see collectAllClients
+ * @param {{ registryAuth?: { registryUrl: string, issuerDomain?: string } | null }} [overrides] see collectAllClients
  * @returns {Promise<{
  *   confidential: Array<{ id: string, plugin: string }>,
  *   served: Array<import('@lamalibre/lamaste/server').AutheliaOidcClient>,
@@ -123,37 +192,41 @@ export async function planOidcClients(overrides = {}) {
 /**
  * Sync Authelia's OIDC clients and the secret store with the plugins and
  * the registry credential. Returns what was done, or `null` when the panel
- * has no domain yet (onboarding).
+ * has no domain yet (onboarding). Plan, secrets and write all happen under
+ * the one writer: a sync that waited for it plans from what is true then,
+ * never from before another sync's change (a registry credential being
+ * set, a plugin moved).
  *
  * @param {import('pino').Logger} logger
- * @param {{ registryAuth?: { registryUrl: string } | null }} [overrides] see collectAllClients
  * @returns {Promise<{ changed: boolean, clients: string[], createdSecrets: Array<{ id: string, plugin: string, secret: string }> } | null>}
  */
-export async function syncOidcClients(logger, overrides = {}) {
-  let domain = null;
-  try {
-    domain = getConfig().domain;
-  } catch {
-    domain = null;
-  }
-  if (!domain) {
+export async function syncOidcClients(logger) {
+  if (!(await primaryDomainName())) {
     logger.debug('OIDC client sync skipped — no domain configured yet');
     return null;
   }
 
-  const { confidential, served, scopes } = await planOidcClients(overrides);
-  const reconciled = await reconcileOidcClientSecrets(STATE_DIR, confidential);
+  const { served, reconciled, result } = await withDomainRendering(
+    async (domains) => {
+      const plan = await planOidcClients();
+      const secrets = await reconcileOidcClientSecrets(STATE_DIR, plan.confidential);
+      return {
+        served: plan.served,
+        reconciled: secrets,
+        result: await updateOidcProvider(keyed(domains), plan.served, {
+          secretDigests: secrets.digests,
+          scopes: plan.scopes,
+        }),
+      };
+    },
+    { logger },
+  );
   if (reconciled.created.length > 0 || reconciled.removed.length > 0) {
     logger.info(
       { created: reconciled.created.map((c) => c.id), removed: reconciled.removed },
       'OIDC client secrets reconciled',
     );
   }
-
-  const result = await updateOidcProvider(domain, served, {
-    secretDigests: reconciled.digests,
-    scopes,
-  });
   if (result.changed) {
     logger.info({ clients: served.map((c) => c.id) }, 'Authelia OIDC provider updated');
   }
@@ -166,16 +239,37 @@ export async function syncOidcClients(logger, overrides = {}) {
 
 /**
  * Metadata of a plugin's OIDC clients: what the manifest declares, whether
- * it is served, and — for confidential clients — when the secret was
- * created and last rotated. Never the secret.
+ * it is served, whether it signs users in (`userFacing`) and — for those —
+ * the Gatekeeper grants on it (`grants`: who among the external members of
+ * its domain may sign in with it; members of the domain always may; null
+ * when Gatekeeper cannot be read), and — for confidential clients — when
+ * the secret was created and last rotated. Never the secret.
  * @param {string} pluginName
  */
 export async function listPluginOidcClients(pluginName) {
   const declared = (await collectPluginOidcClients()).filter((c) => c.plugin === pluginName);
   const secrets = new Map((await listOidcClientSecrets(STATE_DIR)).map((m) => [m.id, m]));
+  const grants = declared.some(isUserFacingOidcClient)
+    ? await listGrantsOfType(OIDC_CLIENT_RESOURCE)
+    : null;
   return declared.map((client) => {
     const secret = client.confidential ? (secrets.get(client.id) ?? null) : null;
     return {
+      userFacing: isUserFacingOidcClient(client),
+      ...(isUserFacingOidcClient(client)
+        ? {
+            grants: grants?.ok
+              ? grants.grants
+                  .filter((g) => g.resourceId === client.id)
+                  .map((g) => ({
+                    grantId: g.grantId,
+                    principalType: g.principalType,
+                    principalId: g.principalId,
+                    createdAt: g.createdAt,
+                  }))
+              : null,
+          }
+        : {}),
       id: client.id,
       name: client.name ?? null,
       confidential: client.confidential,
@@ -216,13 +310,21 @@ export async function rotatePluginOidcClientSecret(pluginName, clientId, logger)
   // The store is reconciled first so a client that was never synced (an
   // earlier Authelia failure) gets its record now.
   await syncOidcClients(logger);
-  const rotated = await rotateOidcClientSecret(STATE_DIR, clientId);
-  const digests = await readOidcClientSecretDigests(STATE_DIR);
-  if (client.enabled) {
-    const domain = getConfig().domain;
-    const { served, scopes } = await planOidcClients();
-    await updateOidcProvider(domain, served, { secretDigests: digests, scopes });
-  }
+  // Rotate, plan and write under the one writer (see syncOidcClients).
+  const rotated = await withDomainRendering(
+    async (domains) => {
+      const secret = await rotateOidcClientSecret(STATE_DIR, clientId);
+      if (client.enabled) {
+        const { served, scopes } = await planOidcClients();
+        await updateOidcProvider(keyed(domains), served, {
+          secretDigests: await readOidcClientSecretDigests(STATE_DIR),
+          scopes,
+        });
+      }
+      return secret;
+    },
+    { logger },
+  );
   logger.info({ plugin: pluginName, clientId }, 'OIDC client secret rotated');
   return {
     id: rotated.id,

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