@lamalibre/create-lamaste 4.5.0 → 4.6.0

package/vendor/serverd/src/routes/management/plugin-web-surface.js

@@ -0,0 +1,151 @@
+/**
+ * A plugin's web surface (slice 7): the site it owns, where the relay
+ * serves the shell its server package ships beside its user surface's API.
+ * Admin only. Business logic lives in `lib/web-surface.js`.
+ *
+ *   GET    /plugins/:name/web-surface        what the installed version declares, the
+ *                                            site, whether it is served, the trees, the offer
+ *   POST   /plugins/:name/web-surface        { subdomain?, accessMode? } — create the site
+ *   POST   /plugins/:name/web-surface/move   { tunnelId } — take over the bound tunnel's host
+ *   DELETE /plugins/:name/web-surface        delete the site and its trees
+ */
+
+import { z } from 'zod';
+import { WEB_SURFACE_ACCESS_MODES, derivePluginRoute } from '@lamalibre/lamaste';
+import { actorFromRequest } from '../../lib/actor.js';
+import { findPlugin } from '../../lib/plugins.js';
+import {
+  createWebSurface,
+  deleteWebSurface,
+  moveWebSurfaceFromTunnel,
+  webSurfaceStatus,
+} from '../../lib/web-surface.js';
+
+const PluginNameParamSchema = z.object({
+  name: z
+    .string()
+    .min(1)
+    .max(100)
+    .regex(/^[a-z0-9-]+$/, 'Plugin name must contain only lowercase letters, numbers, and hyphens'),
+});
+
+const CreateBodySchema = z
+  .object({
+    subdomain: z
+      .string()
+      .min(1)
+      .max(63)
+      .regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, 'subdomain is a DNS label')
+      .optional(),
+    accessMode: z.enum(WEB_SURFACE_ACCESS_MODES).optional(),
+  })
+  .strict();
+
+const MoveBodySchema = z.object({ tunnelId: z.string().min(1).max(64) }).strict();
+
+/** The refusal a library threw (its `statusCode`, message and `code`), or a 500. */
+function sendFailure(request, reply, err, fallback) {
+  if (Number.isInteger(err.statusCode) && err.statusCode < 500) {
+    return reply
+      .code(err.statusCode)
+      .send({ error: err.message, ...(err.code ? { code: err.code } : {}) });
+  }
+  request.log.error(err, fallback);
+  return reply
+    .code(Number.isInteger(err.statusCode) ? err.statusCode : 500)
+    .send({ error: fallback, details: err.message });
+}
+
+/**
+ * The route plugin `:name` holds: the installed plugin's, else the one its
+ * name derives — a site outlives its plugin, and its status and deletion
+ * stay reachable (creating or moving refuses without an installed plugin).
+ */
+async function routeOf(request) {
+  const { name } = PluginNameParamSchema.parse(request.params);
+  const plugin = await findPlugin(name);
+  return plugin?.route ?? derivePluginRoute(name);
+}
+
+export default async function pluginWebSurfaceRoutes(fastify, _opts) {
+  fastify.get(
+    '/plugins/:name/web-surface',
+    { preHandler: fastify.requireRole(['admin']) },
+    async (request, reply) => {
+      const route = await routeOf(request);
+      try {
+        return { webSurface: await webSurfaceStatus(route) };
+      } catch (err) {
+        return sendFailure(request, reply, err, 'Failed to read the web surface');
+      }
+    },
+  );
+
+  fastify.post(
+    '/plugins/:name/web-surface',
+    {
+      preHandler: fastify.requireRole(['admin']),
+      // Issues a certificate and reloads nginx.
+      config: { rateLimit: { max: 10, timeWindow: '1 minute' } },
+    },
+    async (request, reply) => {
+      const route = await routeOf(request);
+      const body = CreateBodySchema.parse(request.body ?? {});
+      try {
+        const webSurface = await createWebSurface(route, body, {
+          actor: actorFromRequest(request),
+          logger: request.log,
+        });
+        return reply.code(201).send({ webSurface });
+      } catch (err) {
+        return sendFailure(request, reply, err, 'Failed to create the web surface');
+      }
+    },
+  );
+
+  fastify.post(
+    '/plugins/:name/web-surface/move',
+    {
+      preHandler: fastify.requireRole(['admin']),
+      config: { rateLimit: { max: 10, timeWindow: '1 minute' } },
+    },
+    async (request, reply) => {
+      const route = await routeOf(request);
+      const { tunnelId } = MoveBodySchema.parse(request.body);
+      try {
+        return {
+          webSurface: await moveWebSurfaceFromTunnel(route, tunnelId, {
+            actor: actorFromRequest(request),
+            logger: request.log,
+          }),
+        };
+      } catch (err) {
+        return sendFailure(
+          request,
+          reply,
+          err,
+          'Failed to move the user surface to the web surface',
+        );
+      }
+    },
+  );
+
+  fastify.delete(
+    '/plugins/:name/web-surface',
+    {
+      preHandler: fastify.requireRole(['admin']),
+      config: { rateLimit: { max: 10, timeWindow: '1 minute' } },
+    },
+    async (request, reply) => {
+      const route = await routeOf(request);
+      try {
+        return await deleteWebSurface(route, {
+          actor: actorFromRequest(request),
+          logger: request.log,
+        });
+      } catch (err) {
+        return sendFailure(request, reply, err, 'Failed to delete the web surface');
+      }
+    },
+  );
+}

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

@@ -301,6 +301,8 @@ async function withHooks(plugin) {
       agent: status.agent !== null,
       // Lamaste installs the agent half (agent.package); false: none, or installed by hand.
       agentHalf: status.agentHalf !== null,
+      // The installed version declares a web surface (its tree is in the approval).
+      web: status.web.declared,
       approval: status.approval.state,
       autoApprove: status.autoApprove,
       failOpenCount: status.relay?.failOpenCount ?? 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

@@ -220,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;
 }
 
 /**
@@ -496,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,
@@ -523,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 });
@@ -600,6 +597,7 @@ export default async function tunnelRoutes(fastify, _opts) {
           state: stateDeps,
           agents: agentDeps,
           userSurface: userSurfaceDeps,
+          hostTaken: siteServing,
           logger: request.log,
           authorize: authorizeFor(request, 'change'),
         });
@@ -748,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);
@@ -780,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 });

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

@@ -13,6 +13,7 @@ import ticketRoutes from './management/tickets.js';
 import identityRoutes from './management/identity.js';
 import identityDirectoryRoutes from './management/identity-directory.js';
 import pluginIdentityRoutes from './management/plugin-identity.js';
+import pluginWebSurfaceRoutes from './management/plugin-web-surface.js';
 import storageRoutes from './management/storage.js';
 import gatekeeperProxyRoutes from './management/gatekeeper-proxy.js';
 import agentsRoutes from './management/agents.js';
@@ -37,6 +38,7 @@ export default async function managementRoutes(fastify, _opts) {
   await fastify.register(identityRoutes);
   await fastify.register(identityDirectoryRoutes);
   await fastify.register(pluginIdentityRoutes);
+  await fastify.register(pluginWebSurfaceRoutes);
   await fastify.register(storageRoutes);
   await fastify.register(gatekeeperProxyRoutes);
   await fastify.register(agentsRoutes);