@lamalibre/create-lamaste 4.4.1 → 4.6.0

package/vendor/serverd/src/routes/management/sites.js

@@ -11,9 +11,12 @@ import {
   updateSite,
   verifyDns,
   SiteError,
+  withTunnelLock,
 } from '@lamalibre/lamaste/server';
+import { AppError } from '../../lib/app-error.js';
+import { webSurfaceServing } from '../../lib/web-surface.js';
 import { getConfig } from '../../lib/config.js';
-import { readSites, writeSites, readTunnels } from '../../lib/state.js';
+import { readSites, writeSites, readTunnels, withSitesLock } from '../../lib/state.js';
 import { writeStaticSiteVhost, removeStaticSiteVhost } from '../../lib/nginx.js';
 import { updateAccessControl } from '../../lib/authelia.js';
 import { issueTunnelCert, getCertPath, issueSiteCert } from '../../lib/certbot.js';
@@ -134,6 +137,79 @@ function siteErrorStatus(code) {
   }
 }
 
+/**
+ * Run a site workflow that may give a site a hostname: under core's tunnel
+ * lock, then the sites lock — the order every such workflow takes them in
+ * (`withSitesLock`) — so no tunnel takes the name meanwhile.
+ *
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+function withHostnameLocks(fn) {
+  return withTunnelLock(() => withSitesLock(fn));
+}
+
+/**
+ * Refuse (409) a site a plugin owns: its files are the plugin's approved
+ * web tree and its settings follow the plugin — it is managed through the
+ * plugin's web surface, never here (and never by `lamaste-agent deploy`).
+ */
+function assertNotPluginOwned(site) {
+  if (site?.owner) {
+    throw new AppError(
+      `Site '${site.name}' is the web surface of plugin '${site.owner.plugin}' — manage it through the plugin`,
+      409,
+      { code: 'plugin_owned_site' },
+    );
+  }
+}
+
+/** The site `id`, refused when a plugin owns it; null when there is none. */
+async function siteForManagement(id) {
+  const site = (await readSites()).find((s) => s.id === id) ?? null;
+  assertNotPluginOwned(site);
+  return site;
+}
+
+/**
+ * Record the size of site `id` on disk in sites.json, re-reading the file
+ * under the sites lock — never a copy read before an upload, which would
+ * undo every change made meanwhile.
+ *
+ * @returns {Promise<number>} the size
+ */
+async function recordSiteSize(id) {
+  const totalSize = await getSiteSize(id);
+  await withSitesLock(async () => {
+    const sites = await readSites();
+    const site = sites.find((s) => s.id === id);
+    if (!site) return;
+    site.totalSize = totalSize;
+    await writeSites(sites);
+  });
+  return totalSize;
+}
+
+/**
+ * Sites as listed: a plugin-owned one with `webSurface: { served, reason }`
+ * — whether it serves its plugin's shell and API now, or answers 503 and why.
+ */
+async function withWebSurfaceState(sites) {
+  if (!sites.some((site) => site.owner)) return sites;
+  const tunnels = await readTunnels();
+  return Promise.all(
+    sites.map(async (site) => {
+      if (!site.owner) return site;
+      const serving = await webSurfaceServing(site.owner.plugin, tunnels);
+      return {
+        ...site,
+        webSurface: { served: serving.served, reason: serving.served ? null : serving.reason },
+      };
+    }),
+  );
+}
+
 function assertAgentSiteAccess(request, site) {
   if (request.certRole === 'agent') {
     const allowed = request.certAllowedSites || [];
@@ -191,7 +267,7 @@ export default async function sitesRoutes(fastify, _opts) {
       }
 
       const total = sites.length;
-      const windowed = sites.slice(offset, offset + limit);
+      const windowed = await withWebSurfaceState(sites.slice(offset, offset + limit));
 
       return { sites: windowed, total, limit, offset };
     },
@@ -214,22 +290,24 @@ export default async function sitesRoutes(fastify, _opts) {
       }
 
       try {
-        const result = await createSite({
-          name: body.name,
-          type: body.type,
-          customDomain: body.customDomain,
-          aliases: body.aliases,
-          spaMode: body.spaMode,
-          autheliaProtected: body.autheliaProtected,
-          domain: config.domain,
-          email: config.email,
-          nginx: nginxDeps,
-          certbot: certbotDeps,
-          files: filesDeps,
-          siteState: siteStateDeps,
-          tunnelState: tunnelReadDeps,
-          logger: request.log,
-        });
+        const result = await withHostnameLocks(() =>
+          createSite({
+            name: body.name,
+            type: body.type,
+            customDomain: body.customDomain,
+            aliases: body.aliases,
+            spaMode: body.spaMode,
+            autheliaProtected: body.autheliaProtected,
+            domain: config.domain,
+            email: config.email,
+            nginx: nginxDeps,
+            certbot: certbotDeps,
+            files: filesDeps,
+            siteState: siteStateDeps,
+            tunnelState: tunnelReadDeps,
+            logger: request.log,
+          }),
+        );
 
         const response = { ok: true, site: result.site };
         if (result.message) response.message = result.message;
@@ -261,12 +339,15 @@ export default async function sitesRoutes(fastify, _opts) {
       const { id } = IdParamSchema.parse(request.params);
 
       try {
-        await deleteSite({
-          id,
-          nginx: nginxDeps,
-          files: filesDeps,
-          siteState: siteStateDeps,
-          logger: request.log,
+        await withSitesLock(async () => {
+          await siteForManagement(id);
+          await deleteSite({
+            id,
+            nginx: nginxDeps,
+            files: filesDeps,
+            siteState: siteStateDeps,
+            logger: request.log,
+          });
         });
         return { ok: true };
       } catch (err) {
@@ -277,6 +358,7 @@ export default async function sitesRoutes(fastify, _opts) {
             details: err.message,
           });
         }
+        if (err instanceof AppError) throw err;
         request.log.error(err, 'Failed to delete site');
         return reply.code(500).send({
           error: 'Failed to delete site',
@@ -298,21 +380,24 @@ export default async function sitesRoutes(fastify, _opts) {
       const config = getConfig();
 
       try {
-        const result = await updateSite({
-          id,
-          spaMode: body.spaMode,
-          autheliaProtected: body.autheliaProtected,
-          allowedUsers: body.allowedUsers,
-          aliases: body.aliases,
-          domain: config.domain,
-          email: config.email,
-          serverIp: config.ip,
-          nginx: nginxDeps,
-          certbot: certbotDeps,
-          siteState: siteStateDeps,
-          tunnelState: tunnelReadDeps,
-          authelia: autheliaDeps,
-          logger: request.log,
+        const result = await withHostnameLocks(async () => {
+          await siteForManagement(id);
+          return updateSite({
+            id,
+            spaMode: body.spaMode,
+            autheliaProtected: body.autheliaProtected,
+            allowedUsers: body.allowedUsers,
+            aliases: body.aliases,
+            domain: config.domain,
+            email: config.email,
+            serverIp: config.ip,
+            nginx: nginxDeps,
+            certbot: certbotDeps,
+            siteState: siteStateDeps,
+            tunnelState: tunnelReadDeps,
+            authelia: autheliaDeps,
+            logger: request.log,
+          });
         });
         return result;
       } catch (err) {
@@ -330,6 +415,7 @@ export default async function sitesRoutes(fastify, _opts) {
             details: err.message,
           });
         }
+        if (err instanceof AppError) throw err;
         request.log.error(err, 'Failed to update site');
         return reply.code(500).send({
           error: 'Failed to update site configuration',
@@ -353,15 +439,18 @@ export default async function sitesRoutes(fastify, _opts) {
       const config = getConfig();
 
       try {
-        const result = await verifyDns({
-          id,
-          serverIp: config.ip,
-          domain: config.domain,
-          email: config.email,
-          nginx: nginxDeps,
-          certbot: certbotDeps,
-          siteState: siteStateDeps,
-          logger: request.log,
+        const result = await withHostnameLocks(async () => {
+          await siteForManagement(id);
+          return verifyDns({
+            id,
+            serverIp: config.ip,
+            domain: config.domain,
+            email: config.email,
+            nginx: nginxDeps,
+            certbot: certbotDeps,
+            siteState: siteStateDeps,
+            logger: request.log,
+          });
         });
         return result;
       } catch (err) {
@@ -371,6 +460,7 @@ export default async function sitesRoutes(fastify, _opts) {
             error: err.message,
           });
         }
+        if (err instanceof AppError) throw err;
         request.log.error(err, 'Failed to verify DNS');
         return reply.code(500).send({
           error: 'DNS verification failed',
@@ -390,8 +480,7 @@ export default async function sitesRoutes(fastify, _opts) {
       const { id } = IdParamSchema.parse(request.params);
       const { path: relativePath } = PathQuerySchema.parse(request.query);
 
-      const sites = await readSites();
-      const site = sites.find((s) => s.id === id);
+      const site = await siteForManagement(id);
       if (!site) {
         return reply.code(404).send({ error: 'Site not found' });
       }
@@ -417,8 +506,7 @@ export default async function sitesRoutes(fastify, _opts) {
       const { id } = IdParamSchema.parse(request.params);
       const config = getConfig();
 
-      const sites = await readSites();
-      const site = sites.find((s) => s.id === id);
+      const site = await siteForManagement(id);
       if (!site) {
         return reply.code(404).send({ error: 'Site not found' });
       }
@@ -450,13 +538,9 @@ export default async function sitesRoutes(fastify, _opts) {
 
       // Update site size
       try {
-        const totalSize = await getSiteSize(id);
-        const siteIndex = sites.findIndex((s) => s.id === id);
-        sites[siteIndex].totalSize = totalSize;
-
+        const totalSize = await recordSiteSize(id);
         if (totalSize > config.maxSiteSize) {
           // Don't block but warn
-          await writeSites(sites);
           return reply.code(200).send({
             ok: true,
             files: uploadedFiles,
@@ -464,8 +548,6 @@ export default async function sitesRoutes(fastify, _opts) {
             totalSize,
           });
         }
-
-        await writeSites(sites);
       } catch {
         // Non-critical — don't fail the upload
       }
@@ -483,8 +565,7 @@ export default async function sitesRoutes(fastify, _opts) {
     async (request, reply) => {
       const { id } = IdParamSchema.parse(request.params);
 
-      const sites = await readSites();
-      const site = sites.find((s) => s.id === id);
+      const site = await siteForManagement(id);
       if (!site) {
         return reply.code(404).send({ error: 'Site not found' });
       }
@@ -501,10 +582,7 @@ export default async function sitesRoutes(fastify, _opts) {
 
       // Update site size
       try {
-        const totalSize = await getSiteSize(id);
-        const siteIndex = sites.findIndex((s) => s.id === id);
-        sites[siteIndex].totalSize = totalSize;
-        await writeSites(sites);
+        await recordSiteSize(id);
       } catch {
         // Non-critical
       }

package/vendor/serverd/src/routes/management/tunnels.js

@@ -5,6 +5,15 @@
  * under the tunnel-state lock. Read-only endpoints and HTTP-specific auth
  * checks remain here; checks that depend on the tunnel's current state run
  * inside the lock through the workflows' `authorize` hook.
+ *
+ * A tunnel may serve agent-hosted plugins' user surfaces (slice 6, admin
+ * only; `lib/user-surface.js`):
+ *
+ *   PUT    /tunnels/:id/user-surface          { route } — bind
+ *   DELETE /tunnels/:id/user-surface/:route   unbind
+ *
+ * Listings carry the binding (`userSurface: { routes }`) and how each bound
+ * route is served (`userSurfaceStatus`).
  */
 import { z } from 'zod';
 import {
@@ -30,6 +39,14 @@ import { buildChiselArgs } from '../../lib/chisel-args.js';
 import { listAgentPluginAssignments } from '../../lib/plugin-hosting.js';
 import { pendingAgentJobs } from '../../lib/agent-jobs.js';
 import { recordAgentContact } from '../../lib/agent-presence.js';
+import { actorFromRequest } from '../../lib/actor.js';
+import {
+  auditDeletedTunnelUserSurface,
+  bindTunnelUserSurface,
+  unbindTunnelUserSurface,
+  userSurfaceDeps,
+  withUserSurfaceStatus,
+} from '../../lib/user-surface.js';
 import {
   tunnelNginxDeps,
   tunnelCertbotDeps,
@@ -39,6 +56,20 @@ import {
 
 const IdParamSchema = z.object({ id: z.string().uuid() });
 
+/** A plugin route, as a user surface is bound for it (core `isUserSurfaceRoute` decides the rest). */
+const UserSurfaceRouteSchema = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, 'route must be a plugin route');
+
+const UserSurfaceBodySchema = z.object({ route: UserSurfaceRouteSchema }).strict();
+
+const UserSurfaceParamsSchema = z.object({ id: z.string().uuid(), route: UserSurfaceRouteSchema });
+
+/** Binding and unbinding rewrite a vhost and reload nginx. */
+const USER_SURFACE_WRITE_RATE_LIMIT = { rateLimit: { max: 30, timeWindow: '1 minute' } };
+
 const TunnelPortSchema = z
   .number()
   .int('Port must be an integer')
@@ -189,10 +220,16 @@ function maxBodyCeiling(request) {
   return request.certRole === 'admin' ? TUNNEL_MAX_BODY_MB.max : TUNNEL_MAX_BODY_MB.agentMax;
 }
 
-/** A static site (or one of its aliases) that already answers on `fqdn`. */
+/**
+ * Core `createTunnel`'s `hostTaken`: the static site (or one of its
+ * aliases) that already answers on `fqdn` — two vhosts with one
+ * server_name make nginx pick silently. Asked under the tunnel lock, which
+ * every workflow giving a site a hostname holds too.
+ */
 async function siteServing(fqdn) {
   const sites = await readSites();
-  return sites.find((s) => s.fqdn === fqdn || (s.aliases ?? []).includes(fqdn)) ?? null;
+  const site = sites.find((s) => s.fqdn === fqdn || (s.aliases ?? []).includes(fqdn));
+  return site ? `by a static site ('${site.name}')` : null;
 }
 
 /**
@@ -215,11 +252,30 @@ function tunnelErrorStatus(code) {
       return 403;
     case 'NOT_FOUND':
       return 404;
+    case 'USER_SURFACE_CONFLICT':
+      return 409;
     default:
       return 500;
   }
 }
 
+/** A refused or failed user-surface change: the workflow's status, or a 500. */
+function sendUserSurfaceFailure(request, reply, err, fallback) {
+  if (err instanceof TunnelError) {
+    const status = tunnelErrorStatus(err.code);
+    return reply.code(status).send({
+      error: status === 500 ? fallback : err.message,
+      ...(status === 500 ? { details: err.message } : {}),
+      ...(err.code === 'USER_SURFACE_CONFLICT' ? { code: 'user_surface_conflict' } : {}),
+    });
+  }
+  if (Number.isInteger(err.statusCode)) {
+    return reply.code(err.statusCode).send({ error: err.message });
+  }
+  request.log.error(err, fallback);
+  return reply.code(500).send({ error: fallback, details: err.message });
+}
+
 export default async function tunnelRoutes(fastify, _opts) {
   const nginxDeps = tunnelNginxDeps;
   const certbotDeps = tunnelCertbotDeps;
@@ -348,7 +404,9 @@ export default async function tunnelRoutes(fastify, _opts) {
       });
 
       const total = tunnels.length;
-      const windowed = tunnels.slice(offset, offset + limit);
+      const windowed = await Promise.all(
+        tunnels.slice(offset, offset + limit).map((t) => withUserSurfaceStatus(t)),
+      );
 
       return { tunnels: windowed, total, limit, offset };
     },
@@ -444,16 +502,6 @@ export default async function tunnelRoutes(fastify, _opts) {
         });
       }
 
-      // A static site (or one of its aliases) may already answer on this
-      // hostname; two vhosts with one server_name make nginx pick silently.
-      const fqdn = `${subdomain}.${config.domain}`;
-      if (await siteServing(fqdn)) {
-        return reply.code(400).send({
-          error: 'Failed to create tunnel',
-          details: `Domain '${fqdn}' is already served by a static site`,
-        });
-      }
-
       try {
         const tunnel = await createTunnel({
           subdomain,
@@ -471,6 +519,7 @@ export default async function tunnelRoutes(fastify, _opts) {
           chisel: chiselDeps,
           state: stateDeps,
           agents: agentDeps,
+          hostTaken: siteServing,
           logger: request.log,
         });
         return reply.code(201).send({ ok: true, tunnel });
@@ -547,6 +596,8 @@ export default async function tunnelRoutes(fastify, _opts) {
           chisel: chiselDeps,
           state: stateDeps,
           agents: agentDeps,
+          userSurface: userSurfaceDeps,
+          hostTaken: siteServing,
           logger: request.log,
           authorize: authorizeFor(request, 'change'),
         });
@@ -577,7 +628,7 @@ export default async function tunnelRoutes(fastify, _opts) {
       const { id } = IdParamSchema.parse(request.params);
 
       try {
-        await deleteTunnel({
+        const { tunnel } = await deleteTunnel({
           id,
           nginx: nginxDeps,
           chisel: chiselDeps,
@@ -585,6 +636,11 @@ export default async function tunnelRoutes(fastify, _opts) {
           logger: request.log,
           authorize: authorizeFor(request, 'delete'),
         });
+        // Its user-surface bindings went with it.
+        await auditDeletedTunnelUserSurface(tunnel, {
+          actor: actorFromRequest(request),
+          logger: request.log,
+        });
         return { ok: true };
       } catch (err) {
         if (err instanceof TunnelError) {
@@ -603,6 +659,44 @@ export default async function tunnelRoutes(fastify, _opts) {
     },
   );
 
+  // PUT /api/tunnels/:id/user-surface — serve a plugin's user surface on this
+  // tunnel's host (from when its installed, approved version declares identity)
+  fastify.put(
+    '/tunnels/:id/user-surface',
+    { preHandler: fastify.requireRole(['admin']), config: USER_SURFACE_WRITE_RATE_LIMIT },
+    async (request, reply) => {
+      const { id } = IdParamSchema.parse(request.params);
+      const { route } = UserSurfaceBodySchema.parse(request.body);
+      try {
+        const { changed, tunnel } = await bindTunnelUserSurface(id, route, {
+          actor: actorFromRequest(request),
+          logger: request.log,
+        });
+        return { ok: true, changed, tunnel };
+      } catch (err) {
+        return sendUserSurfaceFailure(request, reply, err, 'Failed to bind the user surface');
+      }
+    },
+  );
+
+  // DELETE /api/tunnels/:id/user-surface/:route — stop serving it there
+  fastify.delete(
+    '/tunnels/:id/user-surface/:route',
+    { preHandler: fastify.requireRole(['admin']), config: USER_SURFACE_WRITE_RATE_LIMIT },
+    async (request, reply) => {
+      const { id, route } = UserSurfaceParamsSchema.parse(request.params);
+      try {
+        const { tunnel } = await unbindTunnelUserSurface(id, route, {
+          actor: actorFromRequest(request),
+          logger: request.log,
+        });
+        return { ok: true, tunnel };
+      } catch (err) {
+        return sendUserSurfaceFailure(request, reply, err, 'Failed to unbind the user surface');
+      }
+    },
+  );
+
   // GET /api/tunnels/agent-panel-status — check if agent has a panel tunnel
   fastify.get(
     '/tunnels/agent-panel-status',
@@ -652,14 +746,6 @@ export default async function tunnelRoutes(fastify, _opts) {
         });
       }
 
-      const fqdn = `${subdomain}.${config.domain}`;
-      if (await siteServing(fqdn)) {
-        return reply.code(400).send({
-          error: 'Failed to expose agent panel',
-          details: `Domain '${fqdn}' is already served by a static site`,
-        });
-      }
-
       // Check if a panel tunnel already exists for this agent
       const existing = await readTunnels();
       const existingPanel = existing.find((t) => t.type === 'panel' && t.subdomain === subdomain);
@@ -684,6 +770,7 @@ export default async function tunnelRoutes(fastify, _opts) {
           chisel: chiselDeps,
           state: stateDeps,
           agents: agentDeps,
+          hostTaken: siteServing,
           logger: request.log,
         });
         return reply.code(201).send({ ok: true, tunnel });