@lamalibre/create-lamaste 4.4.1 → 4.6.0

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

@@ -1,6 +1,14 @@
 import { execa } from 'execa';
 import { access, lstat, readFile } from 'node:fs/promises';
 import path from 'node:path';
+import {
+  BACKEND_COOKIE_VARIABLE,
+  RELAY_PANEL_PORT,
+  USER_SURFACE_MAX_RESPONSE_SECONDS,
+  isUserSurfaceRoute,
+  userSurfaceApiPath,
+  WEB_TREE_CONTENT_TYPES,
+} from '@lamalibre/lamaste';
 
 const SITES_AVAILABLE = '/etc/nginx/sites-available';
 const SITES_ENABLED = '/etc/nginx/sites-enabled';
@@ -58,11 +66,41 @@ async function writeVhostFile(name, content) {
   await siteAction('write', name, content);
 }
 
+/** Site name of the panel's domain vhost (`panel.<domain>`). */
+export const PANEL_DOMAIN_VHOST = 'lamalibre-lamaste-panel-domain';
+
+/**
+ * Cleared in every location that proxies a browser's request to the panel
+ * itself: a relay assertion reaches the panel only from a user-surface
+ * location of a tunnel vhost, which sets it from Gatekeeper's answer — never
+ * one a client sent.
+ */
+const PANEL_ASSERTION_CLEARED = `
+        # A relay assertion comes only from Gatekeeper, on a plugin's user surface
+        proxy_set_header X-Lamalibre-Relay-Assertion "";`;
+
 /**
  * Write the panel domain vhost with mTLS and Let's Encrypt certs.
  */
 export async function writePanelVhost(domain) {
+  const { name, config } = renderPanelVhost(domain);
+  await writeVhostFile(name, config);
+  return path.join(SITES_AVAILABLE, name);
+}
+
+/**
+ * Render the panel domain vhost. Pure; the startup reconcile renders it on
+ * the certificate directory the installed vhost names.
+ *
+ * @param {string} domain
+ * @param {string} [certPath] - certificate directory (default: the panel's own lineage)
+ * @returns {{ name: string, fqdn: string, config: string }}
+ */
+export function renderPanelVhost(domain, certPath) {
   const fqdn = `panel.${domain}`;
+  assertLiteralHostname(fqdn);
+  let certDirClean = certPath || `/etc/letsencrypt/live/${fqdn}`;
+  while (certDirClean.endsWith('/')) certDirClean = certDirClean.slice(0, -1);
   const config = `# Rate limit zone for public enrollment endpoint (5 requests/minute per IP)
 limit_req_zone $binary_remote_addr zone=enroll_domain:1m rate=5r/m;
 
@@ -76,8 +114,8 @@ server {
     listen 443 ssl;
     server_name ${fqdn};
 
-    ssl_certificate /etc/letsencrypt/live/${fqdn}/fullchain.pem;
-    ssl_certificate_key /etc/letsencrypt/live/${fqdn}/privkey.pem;
+    ssl_certificate ${certDirClean}/fullchain.pem;
+    ssl_certificate_key ${certDirClean}/privkey.pem;
 
     # mTLS — same as IP-based access
     include /etc/nginx/snippets/lamalibre-lamaste-mtls.conf;
@@ -103,7 +141,7 @@ server {
         proxy_set_header Remote-User "";
         proxy_set_header Remote-Groups "";
         proxy_set_header Remote-Name "";
-        proxy_set_header Remote-Email "";
+        proxy_set_header Remote-Email "";${PANEL_ASSERTION_CLEARED}
 
         # Standard proxy headers
         proxy_set_header Host $host;
@@ -126,7 +164,7 @@ server {
         proxy_set_header Remote-User "";
         proxy_set_header Remote-Groups "";
         proxy_set_header Remote-Name "";
-        proxy_set_header Remote-Email "";
+        proxy_set_header Remote-Email "";${PANEL_ASSERTION_CLEARED}
 
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
@@ -146,7 +184,7 @@ server {
         proxy_set_header Remote-User "";
         proxy_set_header Remote-Groups "";
         proxy_set_header Remote-Name "";
-        proxy_set_header Remote-Email "";
+        proxy_set_header Remote-Email "";${PANEL_ASSERTION_CLEARED}
 
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
@@ -167,7 +205,7 @@ server {
         proxy_set_header Remote-User "";
         proxy_set_header Remote-Groups "";
         proxy_set_header Remote-Name "";
-        proxy_set_header Remote-Email "";
+        proxy_set_header Remote-Email "";${PANEL_ASSERTION_CLEARED}
 
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
@@ -187,7 +225,7 @@ server {
         proxy_set_header Remote-User "";
         proxy_set_header Remote-Groups "";
         proxy_set_header Remote-Name "";
-        proxy_set_header Remote-Email "";
+        proxy_set_header Remote-Email "";${PANEL_ASSERTION_CLEARED}
 
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
@@ -207,7 +245,7 @@ server {
         proxy_set_header Remote-User "";
         proxy_set_header Remote-Groups "";
         proxy_set_header Remote-Name "";
-        proxy_set_header Remote-Email "";
+        proxy_set_header Remote-Email "";${PANEL_ASSERTION_CLEARED}
 
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
@@ -232,7 +270,7 @@ server {
         proxy_set_header Remote-User "";
         proxy_set_header Remote-Groups "";
         proxy_set_header Remote-Name "";
-        proxy_set_header Remote-Email "";
+        proxy_set_header Remote-Email "";${PANEL_ASSERTION_CLEARED}
 
         # Standard proxy headers
         proxy_set_header Host $host;
@@ -247,8 +285,7 @@ server {
 }
 `;
 
-  await writeVhostFile('lamalibre-lamaste-panel-domain', config);
-  return path.join(SITES_AVAILABLE, 'lamalibre-lamaste-panel-domain');
+  return { name: PANEL_DOMAIN_VHOST, fqdn, config };
 }
 
 /**
@@ -351,7 +388,7 @@ server {
         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;
+        proxy_set_header X-Forwarded-Proto $scheme;${PANEL_ASSERTION_CLEARED}
     }
 
     # User access authorization — Authelia forward auth protects this endpoint
@@ -393,7 +430,7 @@ server {
         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;
+        proxy_set_header X-Forwarded-Proto $scheme;${PANEL_ASSERTION_CLEARED}
 
         error_page 401 =302 $redirection_url;
     }
@@ -446,6 +483,23 @@ export async function writeTunnelVhost(domain) {
   return path.join(SITES_AVAILABLE, 'lamalibre-lamaste-tunnel');
 }
 
+/**
+ * The `Cookie` a tunnel or agent backend receives: the browser's cookies
+ * without Authelia's session cookie. Authelia scopes that cookie to the base
+ * domain, so the browser sends it to every tunnel host; a backend that got
+ * it — any application on any agent, or whatever holds a tunnel port on the
+ * relay — could replay it as the visitor on every authenticated host and
+ * every plugin's user surface. `$lamaste_backend_cookie` is defined by the
+ * http-level map create-lamaste installs (core `renderBackendCookieMap`,
+ * `/etc/nginx/conf.d/lamalibre-lamaste-backend-cookie.conf`): every
+ * `authelia_session` pair removed, or no `Cookie` at all when one could not
+ * be. A vhost written before the map exists fails `nginx -t` and is rolled
+ * back — never served with the cookie.
+ */
+const BACKEND_COOKIE_HEADER = `
+        # Never Authelia's session cookie: the browser's other cookies only
+        proxy_set_header Cookie ${BACKEND_COOKIE_VARIABLE};`;
+
 /**
  * Request headers every tunnel location sends upstream.
  *
@@ -457,7 +511,8 @@ export async function writeTunnelVhost(domain) {
  * The client-certificate headers are cleared. The panel trusts
  * `X-SSL-Client-*` from nginx as proof of an mTLS client certificate; a
  * tunnel vhost must never pass client-supplied values through, whatever
- * listens on its port.
+ * listens on its port. Authelia's session cookie never reaches the backend
+ * ({@link BACKEND_COOKIE_HEADER}).
  */
 const TUNNEL_PROXY_HEADERS = `
         proxy_set_header Host $host;
@@ -469,6 +524,7 @@ const TUNNEL_PROXY_HEADERS = `
         proxy_set_header X-SSL-Client-Verify "";
         proxy_set_header X-SSL-Client-DN "";
         proxy_set_header X-SSL-Client-Serial "";
+${BACKEND_COOKIE_HEADER}
 
         # WebSocket support
         proxy_set_header Upgrade $http_upgrade;
@@ -485,10 +541,167 @@ const TUNNEL_PROXY_HEADERS = `
  */
 function bodySizeDirective(maxBodySizeMb) {
   if (maxBodySizeMb === undefined) return '';
+  assertBodySizeMb(maxBodySizeMb);
+  return `\n    client_max_body_size ${maxBodySizeMb}m;\n`;
+}
+
+/** A body limit in MiB, as the tunnel workflow allows it — interpolated into nginx configuration. */
+function assertBodySizeMb(maxBodySizeMb) {
   if (!Number.isInteger(maxBodySizeMb) || maxBodySizeMb < 1 || maxBodySizeMb > 10240) {
     throw new Error(`Invalid maxBodySizeMb for nginx vhost: ${maxBodySizeMb}`);
   }
-  return `\n    client_max_body_size ${maxBodySizeMb}m;\n`;
+}
+
+/**
+ * Request headers a user-surface location sends the panel. The panel's
+ * user-surface context trusts nothing but the relay assertion — but the
+ * panel serves other contexts on the same listener, so everything a browser
+ * could send that any of them trusts is cleared: no user request can pass
+ * for a client-certificate holder (`X-SSL-Client-*`), an Authelia user
+ * (`Remote-*`), a desktop session (`Authorization`) or an administrator's
+ * 2FA session (`Cookie`), nor name another host to the panel
+ * (`X-Forwarded-Host`). `X-Forwarded-For` is the client's address alone:
+ * the panel trusts one loopback hop (`trust-proxy.js`), so that is its
+ * `request.ip` — what the user surface's rate limit keys on. `Connection`
+ * cleared: the panel keeps the upstream connection alive (HTTP/1.1), and
+ * the user surface carries no WebSocket.
+ */
+const USER_SURFACE_PROXY_HEADERS = `
+        # Nothing else that any part of the panel trusts
+        proxy_set_header Cookie "";
+        proxy_set_header Authorization "";
+        proxy_set_header Remote-User "";
+        proxy_set_header Remote-Groups "";
+        proxy_set_header Remote-Name "";
+        proxy_set_header Remote-Email "";
+        proxy_set_header X-SSL-Client-Verify "";
+        proxy_set_header X-SSL-Client-DN "";
+        proxy_set_header X-SSL-Client-Serial "";
+        proxy_set_header X-Forwarded-Host "";
+
+        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;
+        proxy_set_header Connection "";`;
+
+/**
+ * The body of a tunnel vhost's Gatekeeper subrequest location,
+ * `/authz/<check>/<fqdn>`: the tunnel is named in the path, in
+ * `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'|'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;
+
+        proxy_set_header Content-Length "";
+        proxy_set_header Connection "";
+        proxy_set_header X-Original-Method $request_method;
+        proxy_set_header X-Original-URL ${originalUrl(fqdn)};
+        proxy_set_header X-Forwarded-For $remote_addr;${AUTHZ_CLEARED_HEADERS}
+        proxy_set_header Host ${fqdn};
+        proxy_set_header Cookie $http_cookie;
+
+        proxy_http_version 1.1;`;
+}
+
+/**
+ * The user-surface locations of a tunnel vhost — `/api/<route>/app` and
+ * everything under it for each plugin it serves (`opts.userSurface`), and
+ * the two internal locations they share:
+ *
+ * - `/internal/lamaste/user-surface-authz` asks Gatekeeper
+ *   (`/authz/user-surface/<fqdn>`, the tunnel named in the path and in
+ *   `X-Original-URL` and `Host`, as for the tunnel's own subrequest).
+ *   Gatekeeper authenticates the Authelia session — and, on a restricted
+ *   tunnel, checks its grant — then vouches for the user to the panel with
+ *   a relay assertion bound to the method and the raw request target. Never
+ *   cached: an assertion is single use.
+ * - `/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.
+ *
+ * Each route's locations pass the assertion, and nothing else of the
+ * browser's credentials ({@link USER_SURFACE_PROXY_HEADERS}), to the panel
+ * with `proxy_pass` naming no URI: the panel receives the request target
+ * exactly as the browser sent it — the target the assertion is bound to.
+ * The body limit is the plugin's (its internal tunnel's); the timeouts are
+ * the longest a user-surface response lives (`USER_SURFACE_MAX_RESPONSE_SECONDS`,
+ * one hour — the panel ends one still open then, and ends it at once when
+ * its user loses access), long enough for server-sent events, which the
+ * panel streams unbuffered.
+ *
+ * @param {string} fqdn
+ * @param {ReadonlyArray<{ route: string, maxBodySizeMb: number }>} userSurface
+ * @returns {string}
+ */
+function userSurfaceLocations(fqdn, userSurface) {
+  if (userSurface.length === 0) return '';
+  const routes = userSurface.map(({ route, maxBodySizeMb }) => {
+    if (!isUserSurfaceRoute(route)) {
+      throw new Error(`Invalid user-surface route for nginx vhost: ${route}`);
+    }
+    assertBodySizeMb(maxBodySizeMb);
+    const block = `{
+        auth_request /internal/lamaste/user-surface-authz;
+        auth_request_set $relay_assertion $upstream_http_x_lamalibre_relay_assertion;
+
+        # The user, vouched for by Gatekeeper to the panel for this one request
+        proxy_set_header X-Lamalibre-Relay-Assertion $relay_assertion;
+${USER_SURFACE_PROXY_HEADERS}
+
+        # No URI: the request target reaches the panel as the browser sent it
+        proxy_pass http://127.0.0.1:${RELAY_PANEL_PORT};
+        proxy_http_version 1.1;
+
+        client_max_body_size ${maxBodySizeMb}m;
+        # No response lives longer (the panel ends one then)
+        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
+        error_page 401 = /internal/lamaste/user-surface-401;
+    }`;
+    const apiPath = userSurfaceApiPath(route);
+    return `
+    # The user surface of plugin "${route}"
+    location = ${apiPath} ${block}
+
+    location ^~ ${apiPath}/ ${block}
+`;
+  });
+  return `
+    # The user surface of agent-hosted plugins on this host: Gatekeeper
+    # vouches for the session's user to the panel, for one request each.
+    location = /internal/lamaste/user-surface-authz {
+        ${gatekeeperSubrequest('user-surface', fqdn)}
+    }
+
+    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;
+
+        proxy_set_header Content-Length "";
+        proxy_set_header Cookie "";
+        proxy_set_header Authorization "";
+        # Gatekeeper's rate limit counts the client nginx saw, never one a client named
+        proxy_set_header X-Forwarded-For $remote_addr;
+
+        proxy_http_version 1.1;
+    }
+${routes.join('')}`;
 }
 
 /**
@@ -500,19 +713,30 @@ export async function writePublicVhost(
   domain,
   port,
   certPath,
-  { pathPrefix, maxBodySizeMb, enabled = true } = {},
+  { pathPrefix, maxBodySizeMb, userSurface, enabled = true } = {},
 ) {
   const { name, fqdn, config } = renderPublicVhost(subdomain, domain, port, certPath, {
     pathPrefix,
     maxBodySizeMb,
+    userSurface,
   });
   return safeWriteVhost(name, config, fqdn, { enabled });
 }
 
-function renderPublicVhost(subdomain, domain, port, certPath, { pathPrefix, maxBodySizeMb } = {}) {
+function renderPublicVhost(
+  subdomain,
+  domain,
+  port,
+  certPath,
+  { pathPrefix, maxBodySizeMb, userSurface } = {},
+) {
   if (pathPrefix && !/^[a-z0-9][a-z0-9._-]*$/.test(pathPrefix)) {
     throw new Error(`Invalid pathPrefix for nginx vhost: ${pathPrefix}`);
   }
+  // A public host has no signed-in user for Gatekeeper to vouch for.
+  if (userSurface && userSurface.length > 0) {
+    throw new Error("A public tunnel vhost cannot serve a plugin's user surface");
+  }
 
   const fqdn = `${subdomain}.${domain}`;
   const certDir = certPath || `/etc/letsencrypt/live/${fqdn}`;
@@ -536,14 +760,11 @@ ${bodySizeDirective(maxBodySizeMb)}
         proxy_set_header Remote-User "";
         proxy_set_header Remote-Groups "";
         proxy_set_header Remote-Name "";
-        proxy_set_header Remote-Email "";${
-          pathPrefix
-            ? `
-        # Nor a relay assertion: lamaste-agentd, which serves plugin routes,
-        # would otherwise be handed one a client sent.
-        proxy_set_header X-Lamalibre-Relay-Assertion "";`
-            : ''
-        }
+        proxy_set_header Remote-Email "";
+
+        # Nor a relay assertion: only Gatekeeper's, set on an authenticated
+        # vhost, may reach a backend (lamaste-agentd serves plugin routes)
+        proxy_set_header X-Lamalibre-Relay-Assertion "";
 ${TUNNEL_PROXY_HEADERS}
 
         ${pathPrefix ? `rewrite ^/?(.*)$ /${pathPrefix}/$1 break;\n        ` : ''}proxy_pass http://127.0.0.1:${port};
@@ -568,11 +789,12 @@ export async function writeAuthenticatedVhost(
   domain,
   port,
   certPath,
-  { pathPrefix, maxBodySizeMb, enabled = true } = {},
+  { 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 });
@@ -588,11 +810,12 @@ export async function writeRestrictedVhost(
   domain,
   port,
   certPath,
-  { pathPrefix, maxBodySizeMb, enabled = true } = {},
+  { pathPrefix, maxBodySizeMb, userSurface, enabled = true } = {},
 ) {
   const { name, fqdn, config } = renderGatekeeperTunnelVhost(subdomain, domain, port, certPath, {
     pathPrefix,
     maxBodySizeMb,
+    userSurface,
     restricted: true,
   });
   return safeWriteVhost(name, config, fqdn, { enabled });
@@ -603,7 +826,7 @@ function renderGatekeeperTunnelVhost(
   domain,
   port,
   certPath,
-  { pathPrefix, maxBodySizeMb, restricted },
+  { pathPrefix, maxBodySizeMb, userSurface, restricted },
 ) {
   if (pathPrefix && !/^[a-z0-9][a-z0-9._-]*$/.test(pathPrefix)) {
     throw new Error(`Invalid pathPrefix for nginx vhost: ${pathPrefix}`);
@@ -617,6 +840,7 @@ function renderGatekeeperTunnelVhost(
   const config = buildGatekeeperVhost(fqdn, certDirClean, port, domain, {
     pathPrefix,
     maxBodySizeMb,
+    userSurface,
     restricted,
   });
 
@@ -629,16 +853,27 @@ function renderGatekeeperTunnelVhost(
  * the generators produce today (see vhost-reconcile.js).
  *
  * @param {'public'|'authenticated'|'restricted'} accessMode
+ * @param {string} subdomain
+ * @param {string} 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 = {}) {
-  const { pathPrefix, maxBodySizeMb } = opts;
+  const { pathPrefix, maxBodySizeMb, userSurface } = opts;
   if (accessMode === 'public') {
-    return renderPublicVhost(subdomain, domain, port, certPath, { pathPrefix, maxBodySizeMb });
+    return renderPublicVhost(subdomain, domain, port, certPath, {
+      pathPrefix,
+      maxBodySizeMb,
+      userSurface,
+    });
   }
   return renderGatekeeperTunnelVhost(subdomain, domain, port, certPath, {
     pathPrefix,
     maxBodySizeMb,
+    userSurface,
     restricted: accessMode !== 'authenticated',
   });
 }
@@ -658,13 +893,18 @@ export function renderTunnelVhost(accessMode, subdomain, domain, port, certPath,
  * the one Gatekeeper authorized. Gatekeeper now refuses `/authz/check`: a
  * vhost the panel has not rewritten closes its tunnel instead of opening it.
  * The login redirect names this vhost for the same reason.
+ *
+ * The backend gets Gatekeeper's relay assertion on a plugin tunnel, and no
+ * relay assertion at all on any other — a client's is cleared. An app
+ * tunnel bound as plugins' user surface also carries their locations
+ * ({@link userSurfaceLocations}).
  */
 function buildGatekeeperVhost(
   fqdn,
   certDirClean,
   port,
   domain,
-  { pathPrefix, maxBodySizeMb, restricted } = {},
+  { pathPrefix, maxBodySizeMb, userSurface = [], restricted } = {},
 ) {
   const url = originalUrl(fqdn);
   return `server {
@@ -681,24 +921,11 @@ ${bodySizeDirective(maxBodySizeMb)}
     # Gatekeeper authorization subrequest (handles Authelia validation + grant check).
     # The tunnel is named in the path — never by the client's Host header.
     location /internal/lamaste/authz {
-        internal;
-
-        proxy_pass http://127.0.0.1:9294/authz/tunnel/${fqdn};
-        proxy_pass_request_body off;
-
-        proxy_set_header Content-Length "";
-        proxy_set_header Connection "";
-        proxy_set_header X-Original-Method $request_method;
-        proxy_set_header X-Original-URL ${url};
-        proxy_set_header X-Forwarded-For $remote_addr;${AUTHZ_CLEARED_HEADERS}
-        proxy_set_header Host ${fqdn};
-        proxy_set_header Cookie $http_cookie;
-
-        proxy_http_version 1.1;
+        ${gatekeeperSubrequest('tunnel', fqdn)}
         proxy_buffers 4 32k;
         proxy_next_upstream error timeout invalid_header http_500 http_502 http_503;
     }
-
+${userSurfaceLocations(fqdn, userSurface)}
     location / {
         auth_request /internal/lamaste/authz;
         auth_request_set $user $upstream_http_remote_user;
@@ -721,7 +948,11 @@ ${bodySizeDirective(maxBodySizeMb)}
         # The user, signed by Gatekeeper for this one request — lamaste-agentd,
         # which serves plugin routes, trusts no Remote-* header without it
         proxy_set_header X-Lamalibre-Relay-Assertion $relay_assertion;`
-            : ''
+            : `
+
+        # No relay assertion reaches an app: Gatekeeper signs one only for a
+        # plugin tunnel or the panel, never one a client sent
+        proxy_set_header X-Lamalibre-Relay-Assertion "";`
         }
 ${TUNNEL_PROXY_HEADERS}
 
@@ -936,6 +1167,269 @@ ${aliasBlock}`;
   return { name: `lamalibre-lamaste-site-${site.id}`, fqdn: site.fqdn, config };
 }
 
+/**
+ * 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 tunnel vhost `subdomain` 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
+ */
+export async function unlinkMovedAppVhost(subdomain) {
+  const name = `lamalibre-lamaste-app-${subdomain}`;
+  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}).
+ *
+ * @param {string} subdomain the tunnel's
+ * @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);
+}
+
 /**
  * Server block answering a site's aliases with a permanent redirect to the
  * primary hostname, on the same certificate (its lineage covers every alias).
@@ -1148,7 +1642,9 @@ export async function writeAgentPanelVhost(
  * reached without going through nginx, so a header proves nothing to it.
  *
  * `X-SSL-Client-*` still go upstream for agents older than 4.3, which read
- * them; lamaste-agentd from 4.3 removes them unread.
+ * them; lamaste-agentd from 4.3 removes them unread. Authelia's session
+ * 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} domain
@@ -1208,6 +1704,7 @@ export function renderAgentPanelVhost(subdomain, domain, port, certPath) {
         proxy_set_header Remote-Groups "";
         proxy_set_header Remote-Name "";
         proxy_set_header Remote-Email "";
+        proxy_set_header X-Lamalibre-Relay-Assertion "";
     }
 
     # Reject requests without valid client certificate
@@ -1236,6 +1733,7 @@ export function renderAgentPanelVhost(subdomain, domain, port, certPath) {
         proxy_set_header Remote-Groups "";
         proxy_set_header Remote-Name "";
         proxy_set_header Remote-Email "";
+${BACKEND_COOKIE_HEADER}
 
         # Standard proxy headers
         proxy_set_header Host $host;