@lamalibre/create-lamaste 4.5.0 → 4.7.0

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

@@ -6,7 +6,9 @@ import {
   RELAY_PANEL_PORT,
   USER_SURFACE_MAX_RESPONSE_SECONDS,
   isUserSurfaceRoute,
+  labelUnder,
   userSurfaceApiPath,
+  WEB_TREE_CONTENT_TYPES,
 } from '@lamalibre/lamaste';
 
 const SITES_AVAILABLE = '/etc/nginx/sites-available';
@@ -287,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
@@ -335,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 {
@@ -433,15 +483,55 @@ server {
 
         error_page 401 =302 $redirection_url;
     }
+`
+    : '';
+  const config = `${zone}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;
+    }
 
-    # Default — proxy to Authelia
+    # 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 };
 }
 
 /**
@@ -590,12 +680,14 @@ const USER_SURFACE_PROXY_HEADERS = `
  * `X-Original-URL` and in `Host` — never by the client's `Host` header (see
  * {@link originalUrl}) — and the session cookie is passed on.
  *
- * @param {'tunnel'|'user-surface'} check
+ * @param {'tunnel'|'user-surface'|'user-surface-shell'} check
  * @param {string} fqdn
  * @returns {string}
  */
 function gatekeeperSubrequest(check, fqdn) {
   return `internal;
+        # A subrequest is never authorized itself (a host may authorize at server level)
+        auth_request off;
 
         proxy_pass http://127.0.0.1:9294/authz/${check}/${fqdn};
         proxy_pass_request_body off;
@@ -626,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
@@ -651,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;
@@ -665,15 +763,16 @@ ${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 `
     # The user surface of plugin "${route}"
     location = ${apiPath} ${block}
 
-    location ${apiPath}/ ${block}
+    location ^~ ${apiPath}/ ${block}
 `;
   });
   return `
@@ -683,8 +782,20 @@ ${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;
 
         proxy_pass http://127.0.0.1:9294/authz/user-surface-unauthenticated;
         proxy_pass_request_body off;
@@ -705,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,
@@ -720,7 +831,7 @@ export async function writePublicVhost(
 }
 
 function renderPublicVhost(
-  subdomain,
+  fqdn,
   domain,
   port,
   certPath,
@@ -734,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);
@@ -772,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);
@@ -837,10 +927,9 @@ function renderGatekeeperTunnelVhost(
     pathPrefix,
     maxBodySizeMb,
     userSurface,
-    restricted,
   });
 
-  return { name: `lamalibre-lamaste-app-${subdomain}`, fqdn, config };
+  return { name: appVhostName(fqdn), fqdn, config };
 }
 
 /**
@@ -849,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',
   });
 }
 
@@ -878,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
@@ -900,7 +989,7 @@ function buildGatekeeperVhost(
   certDirClean,
   port,
   domain,
-  { pathPrefix, maxBodySizeMb, userSurface = [], restricted } = {},
+  { pathPrefix, maxBodySizeMb, userSurface = [] } = {},
 ) {
   const url = originalUrl(fqdn);
   return `server {
@@ -961,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;
     }
 }
 `;
@@ -1080,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;
@@ -1090,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 {
@@ -1111,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)
@@ -1147,22 +1256,286 @@ 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, closed };
+}
+
+/**
+ * The Content-Security-Policy of a plugin's web surface: its shell loads
+ * scripts, styles, fonts and images from its own host only and talks to its
+ * own host only (its user surface's API is there). Inline styles are
+ * allowed — frameworks set `style` attributes and insert component styles
+ * at run time — inline scripts never; no framing, no plugins, no foreign
+ * form targets.
+ */
+const WEB_SURFACE_CSP =
+  "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'self'; object-src 'none'";
+
+/**
+ * Response headers of the shell of a plugin's web surface, set in its
+ * locations — not at server level, where the API's answers (headed by the
+ * panel) would get a second copy. `no-cache`: a browser revalidates each file —
+ * a 304 while the tree is the same, the new file once an update switched
+ * it — so no page mixes two versions of the shell from its cache.
+ */
+const WEB_SURFACE_HEADERS = `
+        add_header Content-Security-Policy "${WEB_SURFACE_CSP}" always;
+        add_header X-Content-Type-Options nosniff always;
+        add_header X-Frame-Options DENY always;
+        add_header Referrer-Policy same-origin always;
+        add_header Cross-Origin-Opener-Policy same-origin always;
+        add_header Cross-Origin-Resource-Policy same-origin always;
+        add_header Cache-Control no-cache always;`;
+
+/**
+ * The content types of a web tree's files, by extension
+ * (`WEB_TREE_CONTENT_TYPES` — the only extensions a tree may hold).
+ */
+const WEB_SURFACE_TYPES = (() => {
+  const byType = new Map();
+  for (const [ext, type] of Object.entries(WEB_TREE_CONTENT_TYPES)) {
+    byType.set(type, [...(byType.get(type) ?? []), ext.slice(1)]);
+  }
+  const entries = [...byType].map(([type, exts]) => `            ${type} ${exts.join(' ')};`);
+  return `
+        types {
+${entries.join('\n')}
+        }`;
+})();
+
+/**
+ * The files a page still running the previous shell may ask for after an
+ * update — its scripts, styles, fonts and images — and nothing else: a
+ * document, an SVG or a manifest is never served from the previous tree.
+ */
+const WEB_SURFACE_SUBRESOURCE_RE = '[.](?:js|mjs|css|woff2?|ttf|otf|png|jpe?g|gif|webp|avif|ico)$';
+
+/**
+ * Service workers: never registered from a plugin's site. A worker outlives
+ * the tree that installed it — a revert, the site's deletion, the
+ * hostname's next owner — and answers in its place; asked for its script
+ * (`Service-Worker: script`), the site answers 404, which also
+ * unregisters a worker already installed at its next update check.
+ */
+const NO_SERVICE_WORKER = `
+        if ($http_service_worker) {
+            return 404;
+        }`;
+
+/**
+ * Render the vhost of a plugin's web surface — a site the plugin owns
+ * (`site.owner`). Pure; the startup reconcile renders it again to compare.
+ *
+ * While the plugin's surface is served (`opts.served`: its installed
+ * version approved, declaring identity and a web surface, hosted), the
+ * host serves two things under one Authelia session:
+ *
+ * - **the shell**: every path but the API, from the plugin's current tree
+ *   (`<treesDir>/current`), GET and HEAD only, each file under its own
+ *   content type (`WEB_SURFACE_TYPES`), never a service worker's script. Every request asks
+ *   Gatekeeper first (`/authz/user-surface-shell/<fqdn>`: a session in the
+ *   plugin's audience, and the site's grant when it is restricted) — a page
+ *   without a session goes to the login, a user without access gets the
+ *   access-request page. A script, style, font or image the current tree
+ *   lacks is looked for in the previous tree (a page still running the old
+ *   shell loads its lazy files after an update), else 404; any other
+ *   unknown path gets the current shell's `index.html`.
+ * - **the API**: `/api/<route>/app/*`, exactly as on a bound tunnel
+ *   ({@link userSurfaceLocations}).
+ *
+ * While it is not served the host answers every request with 503 — and,
+ * once its plugin is no longer installed (`opts.clearSiteData`), tells
+ * browsers to clear the site's storage.
+ *
+ * @param {{ id: string, fqdn: string }} site
+ * @param {string} certDir
+ * @param {string} domain
+ * @param {{ route: string, served: boolean, maxBodySizeMb: number, treesDir: string, clearSiteData?: boolean }} opts
+ * @returns {{ name: string, fqdn: string, config: string }}
+ */
+export function renderWebSurfaceVhost(site, certDir, domain, opts) {
+  const { route, served, maxBodySizeMb, treesDir, clearSiteData = false } = opts;
+  assertLiteralHostname(site.fqdn);
+  if (!isUserSurfaceRoute(route)) throw new Error(`Invalid web surface route: ${route}`);
+  if (!path.isAbsolute(treesDir) || !/^[A-Za-z0-9/._-]+$/.test(treesDir)) {
+    throw new Error(`Invalid web tree directory for nginx vhost: ${treesDir}`);
+  }
+  let certDirClean = certDir;
+  while (certDirClean.endsWith('/')) certDirClean = certDirClean.slice(0, -1);
+
+  const head = `server {
+    listen 443 ssl;
+    server_name ${site.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;
+`;
+
+  if (!served) {
+    // A plugin no longer installed: whatever comes next on this hostname is
+    // not its shell, so browsers drop what it left — its storage, caches
+    // and service workers. Never while the plugin is only unhosted or
+    // awaiting approval: its users' data stays.
+    const clear = clearSiteData
+      ? `
+        add_header Clear-Site-Data '"storage"' always;`
+      : '';
+    return {
+      name: `lamalibre-lamaste-site-${site.id}`,
+      fqdn: site.fqdn,
+      config: `${head}
+    # The web surface of plugin "${route}" is not served now (not installed,
+    # not approved, not hosted, or its version declares no web surface)
+    location / {${NO_SERVICE_WORKER}
+        add_header Cache-Control no-store always;${clear}
+        return 503;
+    }
+}
+`,
+    };
+  }
+
+  const url = originalUrl(site.fqdn);
+  const config = `${head}
+    root ${treesDir}/current;
+    index index.html;
+
+    # Every path of the shell: Gatekeeper first (the API's locations ask on their own)
+    auth_request /internal/lamaste/shell-authz;
+    error_page 401 =302 https://auth.${domain}/?rd=${url};
+    error_page 403 = /internal/lamaste/shell-authz;
+
+    location = /internal/lamaste/shell-authz {
+        ${gatekeeperSubrequest('user-surface-shell', site.fqdn)}
+    }
+${userSurfaceLocations(site.fqdn, [{ route, maxBodySizeMb }])}
+    # A script, style, font or image the current tree lacks: the previous
+    # tree's (a page still running the old shell), else 404
+    location ~* ${WEB_SURFACE_SUBRESOURCE_RE} {
+        if ($request_method !~ ^(GET|HEAD)$) {
+            return 405;
+        }${NO_SERVICE_WORKER}
+${WEB_SURFACE_HEADERS}${WEB_SURFACE_TYPES}
+        try_files $uri @previous;
+    }
+
+    # Everything else: the current tree's file, else the shell
+    location / {
+        if ($request_method !~ ^(GET|HEAD)$) {
+            return 405;
+        }${NO_SERVICE_WORKER}
+${WEB_SURFACE_HEADERS}${WEB_SURFACE_TYPES}
+        try_files $uri /index.html;
+    }
+
+    location @previous {
+${WEB_SURFACE_HEADERS}${WEB_SURFACE_TYPES}
+        root ${treesDir}/previous;
+        try_files $uri =404;
+    }
+}
+`;
   return { name: `lamalibre-lamaste-site-${site.id}`, fqdn: site.fqdn, config };
 }
 
+/**
+ * Write the vhost of a plugin's web surface (see {@link renderWebSurfaceVhost}).
+ *
+ * @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 writeWebSurfaceVhost(site, certDir, domain, opts) {
+  const { name, fqdn, config } = renderWebSurfaceVhost(site, certDir, domain, opts);
+  return safeWriteVhost(name, config, fqdn, { enabled: true });
+}
+
+/**
+ * Hand a hostname from one vhost to another in one nginx reload: vhost
+ * `fromName` is unlinked, `name` written with `config` and linked, the
+ * configuration tested and nginx reloaded once; `fromName` stays installed,
+ * unlinked. Until the reload nginx serves the old vhost, after it the new
+ * one; there is no moment in between. On any failure before the reload
+ * both are put back as they were.
+ *
+ * @param {string} fromName the vhost giving the hostname up (linked)
+ * @param {string} name a vhost that does not exist yet
+ * @param {string} config
+ * @param {string} fqdn
+ */
+async function handOverVhost(fromName, name, config, fqdn) {
+  if (await siteExists(name)) throw new Error(`Vhost ${name} exists already`);
+  const fromEnabled = await isSiteEnabled(fromName);
+  const restore = async () => {
+    await siteAction('remove', name).catch(() => {});
+    if (fromEnabled) await enableSite(fromName).catch(() => {});
+  };
+  try {
+    await disableSite(fromName);
+    await writeVhostFile(name, config);
+    await enableSite(name);
+    const result = await testConfig();
+    if (!result.valid) {
+      throw new Error(`Nginx config test failed handing ${fqdn} to ${name}: ${result.error}`);
+    }
+    await reload();
+  } catch (err) {
+    await restore();
+    throw err;
+  }
+  // `fromName` stays installed, only unlinked: the tunnel it served can be
+  // enabled again by hand once the new vhost is gone.
+}
+
+/**
+ * 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} fqdn the moved tunnel's hostname
+ */
+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 `fqdn` in one
+ * reload (see {@link handOverVhost}).
+ *
+ * @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(fqdn, site, certDir, domain, opts) {
+  const { name, config } = renderWebSurfaceVhost(site, certDir, domain, opts);
+  await handOverVhost(appVhostName(fqdn), name, config, site.fqdn);
+}
+
 /**
  * Server block answering a site's aliases with a permanent redirect to the
  * primary hostname, on the same certificate (its lineage covers every alias).
@@ -1221,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();
@@ -1277,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();
@@ -1296,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();
@@ -1345,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 });
 }
 
@@ -1379,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}`);
   }
@@ -1393,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);
@@ -1483,7 +1850,7 @@ ${BACKEND_COOKIE_HEADER}
 }
 `;
 
-  return { name: `lamalibre-lamaste-agent-panel-${subdomain}`, fqdn, config };
+  return { name: agentPanelVhostName(fqdn), fqdn, config };
 }
 
 /**
@@ -1524,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();
@@ -1541,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();
@@ -1559,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();
@@ -1573,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();
+}