@lamalibre/create-lamaste 4.6.0 → 4.7.0

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

@@ -6,6 +6,7 @@ import {
   RELAY_PANEL_PORT,
   USER_SURFACE_MAX_RESPONSE_SECONDS,
   isUserSurfaceRoute,
+  labelUnder,
   userSurfaceApiPath,
   WEB_TREE_CONTENT_TYPES,
 } from '@lamalibre/lamaste';
@@ -288,6 +289,46 @@ server {
   return { name: PANEL_DOMAIN_VHOST, fqdn, config };
 }
 
+/** The site-name prefixes of the vhosts named by a hostname (lamaste-priv checks the same). */
+const APP_VHOST_PREFIX = 'lamalibre-lamaste-app-';
+const AGENT_PANEL_VHOST_PREFIX = 'lamalibre-lamaste-agent-panel-';
+const AUTH_VHOST_PREFIX = 'lamalibre-lamaste-auth-';
+
+/** Site name of an app or plugin tunnel's vhost: its full hostname. */
+export function appVhostName(fqdn) {
+  assertLiteralHostname(fqdn);
+  return `${APP_VHOST_PREFIX}${fqdn.toLowerCase()}`;
+}
+
+/** Site name of an agent panel tunnel's vhost: its full hostname. */
+export function agentPanelVhostName(fqdn) {
+  assertLiteralHostname(fqdn);
+  return `${AGENT_PANEL_VHOST_PREFIX}${fqdn.toLowerCase()}`;
+}
+
+/**
+ * Site names of tunnel vhosts before the multi-domain relay, by subdomain
+ * alone (one domain): the startup reconcile renames them
+ * (vhost-reconcile.js).
+ */
+export function legacyTunnelVhostName(type, subdomain) {
+  return `${type === 'panel' ? AGENT_PANEL_VHOST_PREFIX : APP_VHOST_PREFIX}${subdomain}`;
+}
+
+/**
+ * The label of tunnel hostname `fqdn` under `domain` — one label, as a
+ * tunnel's is — or a refusal.
+ */
+function assertHostUnderDomain(fqdn, domain) {
+  assertLiteralHostname(fqdn);
+  assertLiteralHostname(domain);
+  const label = labelUnder(fqdn, domain);
+  if (label === null || label.includes('.')) {
+    throw new Error(`Hostname ${fqdn} is not a subdomain of ${domain}`);
+  }
+  return label;
+}
+
 /**
  * A hostname written into a vhost as a literal. Where it names the vhost to
  * an authorization subrequest it must stay a literal — a `$` would make nginx
@@ -336,61 +377,69 @@ const AUTHZ_CLEARED_HEADERS = `
         proxy_set_header X-Forwarded-Uri "";
         proxy_set_header X-Forwarded-Method "";`;
 
+/** Site name of the auth portal vhost of `domain` (`auth.<domain>`). */
+export function authVhostName(domain) {
+  assertLiteralHostname(domain);
+  return `${AUTH_VHOST_PREFIX}${domain.toLowerCase()}`;
+}
+
+/** Site name of the auth portal vhost before the multi-domain relay (the primary's alone). */
+export const LEGACY_AUTH_VHOST = 'lamalibre-lamaste-auth';
+
 /**
- * Write the Authelia auth portal vhost.
+ * Write the Authelia auth portal vhost of one of the relay's domains
+ * (`primary`: the panel's — see {@link renderAuthVhost}).
+ *
+ * @param {string} domain
+ * @param {{ primary: boolean, enabled?: boolean }} opts
  */
-export async function writeAuthVhost(domain) {
-  const { name, config } = renderAuthVhost(domain);
-  await writeVhostFile(name, config);
+export async function writeAuthVhost(domain, { primary, enabled = true }) {
+  const { name, config } = renderAuthVhost(domain, undefined, { primary });
+  await safeWriteVhost(name, config, `auth.${domain}`, { enabled });
   return path.join(SITES_AVAILABLE, name);
 }
 
 /**
- * Render the Authelia auth portal vhost. Pure; the startup reconcile renders
- * it on the certificate directory the installed vhost names.
+ * Remove the auth portal vhost of a removed domain, then test and reload:
+ * `auth.<domain>` stops being served at once.
+ */
+export async function removeAuthVhost(domain) {
+  const name = authVhostName(domain);
+  await siteAction('remove', name);
+
+  const result = await testConfig();
+  if (!result.valid) {
+    throw new Error(`Nginx config test failed after removing vhost ${name}: ${result.error}`);
+  }
+
+  await reload();
+}
+
+/**
+ * Render the Authelia auth portal vhost of one domain. Pure; the startup
+ * reconcile renders it on the certificate directory the installed vhost
+ * names. Every domain's portal serves Authelia and the invitation page; only
+ * the primary's — the panel's domain, which the desktop's user login
+ * exchanges at — serves `/api/user-access/authorize` and declares its rate
+ * limit zone (an http-level name, declared once).
  *
  * @param {string} domain
  * @param {string} [certPath] - certificate directory (default: the portal's own lineage)
+ * @param {{ primary?: boolean }} [opts]
  * @returns {{ name: string, fqdn: string, config: string }}
  */
-export function renderAuthVhost(domain, certPath) {
+export function renderAuthVhost(domain, certPath, { primary = true } = {}) {
   const fqdn = `auth.${domain}`;
   let certDirClean = certPath || `/etc/letsencrypt/live/${fqdn}`;
   while (certDirClean.endsWith('/')) certDirClean = certDirClean.slice(0, -1);
-  const config = `# Rate limit zone for user access authorize endpoint (5 requests/minute per IP)
+  const zone = primary
+    ? `# Rate limit zone for user access authorize endpoint (5 requests/minute per IP)
 limit_req_zone $binary_remote_addr zone=user_access_auth:1m rate=5r/m;
 
-server {
-    listen 443 ssl;
-    server_name ${fqdn};
-
-    ssl_certificate ${certDirClean}/fullchain.pem;
-    ssl_certificate_key ${certDirClean}/privkey.pem;
-
-    ssl_protocols TLSv1.2 TLSv1.3;
-    ssl_ciphers HIGH:!aNULL:!MD5;
-    ssl_prefer_server_ciphers on;
-
-    proxy_set_header Host $host;
-    proxy_set_header X-Real-IP $remote_addr;
-    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_set_header X-Forwarded-Proto $scheme;
-
-    # Invitation page — static HTML
-    location /invite/ {
-        alias /var/www/lamaste/invite/;
-        try_files $uri /invite/index.html;
-    }
-
-    # Invitation API — proxied to panel server (no mTLS)
-    location /api/invite/ {
-        proxy_pass http://127.0.0.1:3100/api/invite/;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $remote_addr;
-        proxy_set_header X-Forwarded-Proto $scheme;${PANEL_ASSERTION_CLEARED}
-    }
-
+`
+    : '';
+  const userAccess = primary
+    ? `
     # User access authorization — Authelia forward auth protects this endpoint
     # so Remote-User header is set by Authelia on successful authentication.
     location /internal/authelia/authz {
@@ -434,15 +483,55 @@ server {
 
         error_page 401 =302 $redirection_url;
     }
+`
+    : '';
+  const config = `${zone}server {
+    listen 443 ssl;
+    server_name ${fqdn};
 
-    # Default — proxy to Authelia
+    ssl_certificate ${certDirClean}/fullchain.pem;
+    ssl_certificate_key ${certDirClean}/privkey.pem;
+
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+
+    # Invitation page — static HTML
+    location /invite/ {
+        alias /var/www/lamaste/invite/;
+        try_files $uri /invite/index.html;
+    }
+
+    # Invitation API — proxied to panel server (no mTLS)
+    location /api/invite/ {
+        proxy_pass http://127.0.0.1:3100/api/invite/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;${PANEL_ASSERTION_CLEARED}
+    }
+${userAccess}
+    # Default — proxy to Authelia. Authelia takes the OIDC issuer and the
+    # session cookie's domain from X-Forwarded-Host / -Proto: this portal's
+    # own name, never what the client sent. (A location that sets any
+    # header inherits none of the server's.)
     location / {
         proxy_pass http://127.0.0.1:9091;
+        proxy_set_header Host ${fqdn};
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Host ${fqdn};
+        proxy_set_header X-Forwarded-Proto https;
     }
 }
 `;
 
-  return { name: 'lamalibre-lamaste-auth', fqdn, config };
+  return { name: authVhostName(domain), fqdn, config };
 }
 
 /**
@@ -629,6 +718,11 @@ function gatekeeperSubrequest(check, fqdn) {
  * - `/internal/lamaste/user-surface-401` answers a request without a
  *   session with Gatekeeper's JSON 401 — an application's request is never
  *   redirected to the login page.
+ * - `/internal/lamaste/user-surface-403` answers a refused request with its
+ *   refusal as JSON: under `auth_request` nginx keeps only the subrequest's
+ *   status and headers, never its body, so Gatekeeper names the refusal in
+ *   `X-Lamalibre-Refusal` and the location answers `not_a_member` for that
+ *   value and `forbidden` for anything else.
  *
  * Each route's locations pass the assertion, and nothing else of the
  * browser's credentials ({@link USER_SURFACE_PROXY_HEADERS}), to the panel
@@ -654,6 +748,7 @@ function userSurfaceLocations(fqdn, userSurface) {
     const block = `{
         auth_request /internal/lamaste/user-surface-authz;
         auth_request_set $relay_assertion $upstream_http_x_lamalibre_relay_assertion;
+        auth_request_set $lamaste_refusal $upstream_http_x_lamalibre_refusal;
 
         # The user, vouched for by Gatekeeper to the panel for this one request
         proxy_set_header X-Lamalibre-Relay-Assertion $relay_assertion;
@@ -668,8 +763,9 @@ ${USER_SURFACE_PROXY_HEADERS}
         proxy_read_timeout ${USER_SURFACE_MAX_RESPONSE_SECONDS}s;
         proxy_send_timeout ${USER_SURFACE_MAX_RESPONSE_SECONDS}s;
 
-        # No session: a JSON 401, never a redirect
+        # No session: a JSON 401, never a redirect; refused: the refusal as JSON
         error_page 401 = /internal/lamaste/user-surface-401;
+        error_page 403 = /internal/lamaste/user-surface-403;
     }`;
     const apiPath = userSurfaceApiPath(route);
     return `
@@ -686,6 +782,17 @@ ${USER_SURFACE_PROXY_HEADERS}
         ${gatekeeperSubrequest('user-surface', fqdn)}
     }
 
+    location = /internal/lamaste/user-surface-403 {
+        internal;
+        default_type application/json;
+        add_header Cache-Control "no-store" always;
+        add_header X-Content-Type-Options "nosniff" always;
+        if ($lamaste_refusal = not_a_member) {
+            return 403 '{"error":"not_a_member"}';
+        }
+        return 403 '{"error":"forbidden"}';
+    }
+
     location = /internal/lamaste/user-surface-401 {
         internal;
         auth_request off;
@@ -709,13 +816,13 @@ ${routes.join('')}`;
  * Used for tunnels with accessMode='public'.
  */
 export async function writePublicVhost(
-  subdomain,
+  fqdn,
   domain,
   port,
   certPath,
   { pathPrefix, maxBodySizeMb, userSurface, enabled = true } = {},
 ) {
-  const { name, fqdn, config } = renderPublicVhost(subdomain, domain, port, certPath, {
+  const { name, config } = renderPublicVhost(fqdn, domain, port, certPath, {
     pathPrefix,
     maxBodySizeMb,
     userSurface,
@@ -724,7 +831,7 @@ export async function writePublicVhost(
 }
 
 function renderPublicVhost(
-  subdomain,
+  fqdn,
   domain,
   port,
   certPath,
@@ -738,7 +845,7 @@ function renderPublicVhost(
     throw new Error("A public tunnel vhost cannot serve a plugin's user surface");
   }
 
-  const fqdn = `${subdomain}.${domain}`;
+  assertHostUnderDomain(fqdn, domain);
   const certDir = certPath || `/etc/letsencrypt/live/${fqdn}`;
   let certDirClean = certDir;
   while (certDirClean.endsWith('/')) certDirClean = certDirClean.slice(0, -1);
@@ -776,63 +883,42 @@ ${TUNNEL_PROXY_HEADERS}
 }
 `;
 
-  return { name: `lamalibre-lamaste-app-${subdomain}`, fqdn, config };
-}
-
-/**
- * Write an authenticated vhost — Authelia via Gatekeeper, all authenticated users allowed.
- * Used for tunnels with accessMode='authenticated'.
- * Gatekeeper handles Authelia cookie validation and forwards identity headers.
- */
-export async function writeAuthenticatedVhost(
-  subdomain,
-  domain,
-  port,
-  certPath,
-  { pathPrefix, maxBodySizeMb, userSurface, enabled = true } = {},
-) {
-  const { name, fqdn, config } = renderGatekeeperTunnelVhost(subdomain, domain, port, certPath, {
-    pathPrefix,
-    maxBodySizeMb,
-    userSurface,
-    restricted: false,
-  });
-  return safeWriteVhost(name, config, fqdn, { enabled });
+  return { name: appVhostName(fqdn), fqdn, config };
 }
 
 /**
- * Write a restricted vhost — Authelia via Gatekeeper, only granted users/groups allowed.
- * Used for tunnels with accessMode='restricted'.
- * On 403, Gatekeeper returns the inline access-request HTML page.
+ * Write the vhost of an `authenticated` or `restricted` tunnel — one and
+ * the same: nginx asks Gatekeeper about every request, and Gatekeeper
+ * decides by the tunnel's access mode in tunnels.json (any member of the
+ * domain, or only those with a grant) and serves its refusal pages inline.
  */
-export async function writeRestrictedVhost(
-  subdomain,
+export async function writeGatekeeperVhost(
+  fqdn,
   domain,
   port,
   certPath,
   { pathPrefix, maxBodySizeMb, userSurface, enabled = true } = {},
 ) {
-  const { name, fqdn, config } = renderGatekeeperTunnelVhost(subdomain, domain, port, certPath, {
+  const { name, config } = renderGatekeeperTunnelVhost(fqdn, domain, port, certPath, {
     pathPrefix,
     maxBodySizeMb,
     userSurface,
-    restricted: true,
   });
   return safeWriteVhost(name, config, fqdn, { enabled });
 }
 
 function renderGatekeeperTunnelVhost(
-  subdomain,
+  fqdn,
   domain,
   port,
   certPath,
-  { pathPrefix, maxBodySizeMb, userSurface, restricted },
+  { pathPrefix, maxBodySizeMb, userSurface },
 ) {
   if (pathPrefix && !/^[a-z0-9][a-z0-9._-]*$/.test(pathPrefix)) {
     throw new Error(`Invalid pathPrefix for nginx vhost: ${pathPrefix}`);
   }
 
-  const fqdn = `${subdomain}.${domain}`;
+  assertHostUnderDomain(fqdn, domain);
   const certDir = certPath || `/etc/letsencrypt/live/${fqdn}`;
   let certDirClean = certDir;
   while (certDirClean.endsWith('/')) certDirClean = certDirClean.slice(0, -1);
@@ -841,10 +927,9 @@ function renderGatekeeperTunnelVhost(
     pathPrefix,
     maxBodySizeMb,
     userSurface,
-    restricted,
   });
 
-  return { name: `lamalibre-lamaste-app-${subdomain}`, fqdn, config };
+  return { name: appVhostName(fqdn), fqdn, config };
 }
 
 /**
@@ -853,28 +938,27 @@ function renderGatekeeperTunnelVhost(
  * the generators produce today (see vhost-reconcile.js).
  *
  * @param {'public'|'authenticated'|'restricted'} accessMode
- * @param {string} subdomain
- * @param {string} domain
+ * @param {string} fqdn the tunnel's hostname
+ * @param {string} domain the base domain it is under (its sign-in, `auth.<domain>`)
  * @param {number} port
  * @param {string} [certPath]
  * @param {{ pathPrefix?: string, maxBodySizeMb?: number, userSurface?: ReadonlyArray<{ route: string, maxBodySizeMb: number }> }} [opts]
  *   `userSurface`: the plugins' user surfaces the vhost serves (not on a public vhost)
  * @returns {{ name: string, fqdn: string, config: string }}
  */
-export function renderTunnelVhost(accessMode, subdomain, domain, port, certPath, opts = {}) {
+export function renderTunnelVhost(accessMode, fqdn, domain, port, certPath, opts = {}) {
   const { pathPrefix, maxBodySizeMb, userSurface } = opts;
   if (accessMode === 'public') {
-    return renderPublicVhost(subdomain, domain, port, certPath, {
+    return renderPublicVhost(fqdn, domain, port, certPath, {
       pathPrefix,
       maxBodySizeMb,
       userSurface,
     });
   }
-  return renderGatekeeperTunnelVhost(subdomain, domain, port, certPath, {
+  return renderGatekeeperTunnelVhost(fqdn, domain, port, certPath, {
     pathPrefix,
     maxBodySizeMb,
     userSurface,
-    restricted: accessMode !== 'authenticated',
   });
 }
 
@@ -882,7 +966,8 @@ export function renderTunnelVhost(accessMode, subdomain, domain, port, certPath,
  * Build a Gatekeeper-backed nginx vhost config string.
  * Both 'authenticated' and 'restricted' modes use this — the difference
  * is handled server-side by Gatekeeper based on the tunnel's accessMode.
- * For restricted mode, the 403 body from Gatekeeper is served inline.
+ * Gatekeeper's 403 body is served inline: a restricted tunnel's access
+ * request, or the refusal page of a user who is no member of the domain.
  *
  * The subrequest names the tunnel in its path, `/authz/tunnel/<fqdn>`,
  * written here as the agent-panel vhost writes its agent's label, and
@@ -904,7 +989,7 @@ function buildGatekeeperVhost(
   certDirClean,
   port,
   domain,
-  { pathPrefix, maxBodySizeMb, userSurface = [], restricted } = {},
+  { pathPrefix, maxBodySizeMb, userSurface = [] } = {},
 ) {
   const url = originalUrl(fqdn);
   return `server {
@@ -965,12 +1050,9 @@ ${TUNNEL_PROXY_HEADERS}
         # Authentication failure -> redirect to Authelia login, back to this vhost
         error_page 401 =302 https://auth.${domain}/?rd=${url};
 
-        ${
-          restricted
-            ? `# Authorization failure -> Gatekeeper serves inline access-request page
-        error_page 403 = /internal/lamaste/authz;`
-            : ''
-        }
+        # Authorization failure -> Gatekeeper's inline page: the access
+        # request of a restricted tunnel, or not a member of this domain
+        error_page 403 = /internal/lamaste/authz;
     }
 }
 `;
@@ -1084,7 +1166,8 @@ export async function writeStaticSiteVhost(site, certDir, domain) {
  * @param {object} site - as for writeStaticSiteVhost
  * @param {string} certDir
  * @param {string} [domain]
- * @returns {{ name: string, fqdn: string, config: string }}
+ * @returns {{ name: string, fqdn: string, config: string, closed: boolean }} `closed`: a
+ *   protected site under no domain, answering 403 to everyone
  */
 export function renderStaticSiteVhost(site, certDir, domain) {
   let certDirClean = certDir;
@@ -1094,8 +1177,13 @@ export function renderStaticSiteVhost(site, certDir, domain) {
 
   let autheliaBlock = '';
   let locationAuthDirectives = '';
+  // A protected site asks its domain's sign-in; one under none of the
+  // relay's domains has no sign-in that could admit anyone: it is closed,
+  // never served without authentication.
+  const gated = site.autheliaProtected && Boolean(domain);
+  const closed = site.autheliaProtected && !domain;
 
-  if (site.autheliaProtected && domain) {
+  if (gated) {
     autheliaBlock = `
     # Authelia forward authentication (AuthRequest implementation for nginx)
     location /internal/authelia/authz {
@@ -1115,6 +1203,23 @@ export function renderStaticSiteVhost(site, certDir, domain) {
         proxy_buffers 4 32k;
         proxy_next_upstream error timeout invalid_header http_500 http_502 http_503;
     }
+
+    # Signed in, refused (not a member of the site's domain, or not one of
+    # its users): Gatekeeper's page says so instead of nginx's bare 403
+    location = /internal/lamaste/refusal {
+        internal;
+        auth_request off;
+
+        proxy_pass http://127.0.0.1:9294/authz/refusal/${site.fqdn};
+        proxy_pass_request_body off;
+
+        proxy_set_header Content-Length "";
+        proxy_set_header Cookie "";
+        proxy_set_header Authorization "";
+        proxy_set_header X-Forwarded-For $remote_addr;
+
+        proxy_http_version 1.1;
+    }
 `;
     locationAuthDirectives = `
         # Clear client-supplied identity headers (Authelia re-injects on success)
@@ -1151,20 +1256,21 @@ export function renderStaticSiteVhost(site, certDir, domain) {
     add_header X-Content-Type-Options nosniff always;
 ${autheliaBlock}
     location / {${locationAuthDirectives}
-        ${tryFiles};
+        ${closed ? 'return 403' : tryFiles};
     }
 ${
-  site.autheliaProtected && domain
+  gated
     ? `
     # Redirect unauthenticated requests to Authelia login portal
     error_page 401 =302 $redirection_url;
+    error_page 403 = /internal/lamaste/refusal;
 `
     : ''
 }
 }
 ${aliasBlock}`;
 
-  return { name: `lamalibre-lamaste-site-${site.id}`, fqdn: site.fqdn, config };
+  return { name: `lamalibre-lamaste-site-${site.id}`, fqdn: site.fqdn, config, closed };
 }
 
 /**
@@ -1400,34 +1506,34 @@ async function handOverVhost(fromName, name, config, fqdn) {
 }
 
 /**
- * Unlink tunnel vhost `subdomain` when it is still enabled although a
+ * Unlink the vhost of tunnel `fqdn` when it is still enabled although a
  * plugin's site holds its hostname — a move the panel did not finish (it
  * wrote the state, then stopped before the handover). Does not reload:
  * the caller's next vhost install does, or it reloads itself. Returns
  * whether it unlinked.
  *
- * @param {string} subdomain the moved tunnel's
+ * @param {string} fqdn the moved tunnel's hostname
  */
-export async function unlinkMovedAppVhost(subdomain) {
-  const name = `lamalibre-lamaste-app-${subdomain}`;
+export async function unlinkMovedAppVhost(fqdn) {
+  const name = appVhostName(fqdn);
   if (!(await isSiteEnabled(name))) return false;
   await disableSite(name);
   return true;
 }
 
 /**
- * Serve a plugin's web surface on the hostname of tunnel vhost `subdomain`
- * in one reload (see {@link handOverVhost}).
+ * Serve a plugin's web surface on the hostname of tunnel `fqdn` in one
+ * reload (see {@link handOverVhost}).
  *
- * @param {string} subdomain the tunnel's
+ * @param {string} fqdn the tunnel's hostname
  * @param {{ id: string, fqdn: string }} site
  * @param {string} certDir
  * @param {string} domain
  * @param {{ route: string, served: boolean, maxBodySizeMb: number, treesDir: string }} opts
  */
-export async function moveAppVhostToWebSurface(subdomain, site, certDir, domain, opts) {
-  const { name, fqdn, config } = renderWebSurfaceVhost(site, certDir, domain, opts);
-  await handOverVhost(`lamalibre-lamaste-app-${subdomain}`, name, config, fqdn);
+export async function moveAppVhostToWebSurface(fqdn, site, certDir, domain, opts) {
+  const { name, config } = renderWebSurfaceVhost(site, certDir, domain, opts);
+  await handOverVhost(appVhostName(fqdn), name, config, site.fqdn);
 }
 
 /**
@@ -1488,10 +1594,10 @@ export async function removeStaticSiteVhost(siteId) {
  * Remove an app vhost from sites-available and sites-enabled, then test and reload nginx.
  * Idempotent: if files don't exist, proceeds silently.
  *
- * @param {string} subdomain - The subdomain name
+ * @param {string} fqdn - The tunnel hostname
  */
-export async function removeAppVhost(subdomain) {
-  const name = `lamalibre-lamaste-app-${subdomain}`;
+export async function removeAppVhost(fqdn) {
+  const name = appVhostName(fqdn);
   await siteAction('remove', name);
 
   const result = await testConfig();
@@ -1544,10 +1650,10 @@ export async function disableSite(name) {
 /**
  * Enable an app tunnel vhost (restore symlink), test and reload nginx.
  *
- * @param {string} subdomain - The subdomain name
+ * @param {string} fqdn - The tunnel hostname
  */
-export async function enableAppVhost(subdomain) {
-  const name = `lamalibre-lamaste-app-${subdomain}`;
+export async function enableAppVhost(fqdn) {
+  const name = appVhostName(fqdn);
   await enableSite(name);
 
   const result = await testConfig();
@@ -1563,10 +1669,10 @@ export async function enableAppVhost(subdomain) {
 /**
  * Disable an app tunnel vhost (remove symlink only, keep config), test and reload nginx.
  *
- * @param {string} subdomain - The subdomain name
+ * @param {string} fqdn - The tunnel hostname
  */
-export async function disableAppVhost(subdomain) {
-  const name = `lamalibre-lamaste-app-${subdomain}`;
+export async function disableAppVhost(fqdn) {
+  const name = appVhostName(fqdn);
   await disableSite(name);
 
   const result = await testConfig();
@@ -1612,19 +1718,13 @@ export async function enableIpVhost() {
  *
  * Written through safeWriteVhost (backup, test, rollback).
  *
- * @param {string} subdomain - The subdomain name (e.g., "agent-my-agent")
+ * @param {string} fqdn - The hostname (e.g., "agent-my-agent.example.com")
  * @param {string} domain - The base domain (e.g., "example.com")
  * @param {number} port - The local port to proxy to
  * @param {string} [certPath] - Optional cert directory path override (e.g. for wildcard certs)
  */
-export async function writeAgentPanelVhost(
-  subdomain,
-  domain,
-  port,
-  certPath,
-  { enabled = true } = {},
-) {
-  const { name, fqdn, config } = renderAgentPanelVhost(subdomain, domain, port, certPath);
+export async function writeAgentPanelVhost(fqdn, domain, port, certPath, { enabled = true } = {}) {
+  const { name, config } = renderAgentPanelVhost(fqdn, domain, port, certPath);
   return safeWriteVhost(name, config, fqdn, { enabled });
 }
 
@@ -1646,13 +1746,14 @@ export async function writeAgentPanelVhost(
  * cookie never does ({@link BACKEND_COOKIE_HEADER}): the agent panel's host
  * is under the base domain like every other.
  *
- * @param {string} subdomain - `agent-<label>`
+ * @param {string} fqdn - `agent-<label>.<domain>`
  * @param {string} domain
  * @param {number} port
  * @param {string} [certPath]
  * @returns {{ name: string, fqdn: string, config: string }}
  */
-export function renderAgentPanelVhost(subdomain, domain, port, certPath) {
+export function renderAgentPanelVhost(fqdn, domain, port, certPath) {
+  const subdomain = assertHostUnderDomain(fqdn, domain);
   if (!/^agent-[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/.test(subdomain)) {
     throw new Error(`Invalid agent panel subdomain for nginx vhost: ${subdomain}`);
   }
@@ -1660,7 +1761,6 @@ export function renderAgentPanelVhost(subdomain, domain, port, certPath) {
     throw new Error(`Invalid port for nginx vhost: ${port}`);
   }
   const label = subdomain.slice('agent-'.length);
-  const fqdn = `${subdomain}.${domain}`;
   const certDir = certPath || `/etc/letsencrypt/live/${fqdn}`;
   let certDirClean = certDir;
   while (certDirClean.endsWith('/')) certDirClean = certDirClean.slice(0, -1);
@@ -1750,7 +1850,7 @@ ${BACKEND_COOKIE_HEADER}
 }
 `;
 
-  return { name: `lamalibre-lamaste-agent-panel-${subdomain}`, fqdn, config };
+  return { name: agentPanelVhostName(fqdn), fqdn, config };
 }
 
 /**
@@ -1791,10 +1891,10 @@ export { safeWriteVhost as installVhost };
  * Remove an agent panel vhost from sites-available and sites-enabled, then test and reload nginx.
  * Idempotent: if files don't exist, proceeds silently.
  *
- * @param {string} subdomain - The subdomain name (e.g., "agent-my-agent")
+ * @param {string} fqdn - The agent panel hostname (e.g., "agent-my-agent.example.com")
  */
-export async function removeAgentPanelVhost(subdomain) {
-  const name = `lamalibre-lamaste-agent-panel-${subdomain}`;
+export async function removeAgentPanelVhost(fqdn) {
+  const name = agentPanelVhostName(fqdn);
   await siteAction('remove', name);
 
   const result = await testConfig();
@@ -1808,10 +1908,10 @@ export async function removeAgentPanelVhost(subdomain) {
 /**
  * Enable an agent panel vhost (restore symlink), test and reload nginx.
  *
- * @param {string} subdomain - The subdomain name
+ * @param {string} fqdn - The tunnel hostname
  */
-export async function enableAgentPanelVhost(subdomain) {
-  const name = `lamalibre-lamaste-agent-panel-${subdomain}`;
+export async function enableAgentPanelVhost(fqdn) {
+  const name = agentPanelVhostName(fqdn);
   await enableSite(name);
 
   const result = await testConfig();
@@ -1826,10 +1926,10 @@ export async function enableAgentPanelVhost(subdomain) {
 /**
  * Disable an agent panel vhost (remove symlink only, keep config), test and reload nginx.
  *
- * @param {string} subdomain - The subdomain name
+ * @param {string} fqdn - The tunnel hostname
  */
-export async function disableAgentPanelVhost(subdomain) {
-  const name = `lamalibre-lamaste-agent-panel-${subdomain}`;
+export async function disableAgentPanelVhost(fqdn) {
+  const name = agentPanelVhostName(fqdn);
   await disableSite(name);
 
   const result = await testConfig();
@@ -1840,3 +1940,81 @@ export async function disableAgentPanelVhost(subdomain) {
 
   await reload();
 }
+
+/** The file operations {@link renameVhosts} uses (tests pass stand-ins). */
+const renameFileOps = {
+  readInstalledVhost,
+  siteExists,
+  isSiteEnabled,
+  writeVhostFile,
+  enableSite,
+  disableSite,
+  removeSite: (name) => siteAction('remove', name),
+  testConfig,
+  reload,
+};
+
+/**
+ * Rename installed vhosts — `[{ from, to, serverName? }]` — in one nginx
+ * reload: each `from` that exists is written again under `to` with the same
+ * text and link state, and unlinked; then `nginx -t`. When it passes, nginx
+ * reloads and the old files go. When it fails — or a step does — every new
+ * file goes, every old link comes back, nothing reloads, and the error is
+ * thrown. The multi-domain relay's start-up migration of vhosts named by
+ * subdomain to vhosts named by hostname.
+ *
+ * A `from` whose `to` exists already — a migration a crash cut short — is
+ * finished, not skipped: `to` takes `from`'s link and `from` goes, so a
+ * stale old file never outlives its tunnel. `serverName`, when given, must
+ * be the old file's `server_name`: a file that serves another host is
+ * nobody's to rename.
+ *
+ * @param {ReadonlyArray<{ from: string, to: string, serverName?: string }>} renames
+ * @param {typeof renameFileOps} [ops]
+ * @returns {Promise<string[]>} the `to` names written or finished
+ */
+export async function renameVhosts(renames, ops = renameFileOps) {
+  const done = [];
+  try {
+    for (const { from, to, serverName } of renames) {
+      const text = await ops.readInstalledVhost(from);
+      if (text === null) continue;
+      if (serverName !== undefined && !servesHost(text, serverName)) continue;
+      const linked = await ops.isSiteEnabled(from);
+      if (await ops.siteExists(to)) {
+        const linkTo = linked && !(await ops.isSiteEnabled(to));
+        done.push({ from, to, linked, existed: true, linkedTo: linkTo });
+        if (linkTo) await ops.enableSite(to);
+        if (linked) await ops.disableSite(from);
+        continue;
+      }
+      done.push({ from, to, linked, existed: false, linkedTo: linked });
+      await ops.writeVhostFile(to, text);
+      if (linked) {
+        await ops.enableSite(to);
+        await ops.disableSite(from);
+      }
+    }
+    if (done.length === 0) return [];
+    const result = await ops.testConfig();
+    if (!result.valid) throw new Error(`nginx -t failed after renaming vhosts: ${result.error}`);
+    await ops.reload();
+  } catch (err) {
+    for (const { from, to, linked, existed, linkedTo } of done.reverse()) {
+      if (!existed) await ops.removeSite(to).catch(() => {});
+      else if (linkedTo) await ops.disableSite(to).catch(() => {});
+      if (linked) await ops.enableSite(from).catch(() => {});
+    }
+    throw err;
+  }
+  for (const { from } of done) {
+    await ops.removeSite(from).catch(() => {});
+  }
+  return done.map((d) => d.to);
+}
+
+/** True when vhost `text`'s first `server_name` is exactly `host`. */
+function servesHost(text, host) {
+  const match = /^\s*server_name\s+([^;\s]+)\s*;/m.exec(text);
+  return match !== null && match[1].toLowerCase() === host.toLowerCase();
+}