@lamalibre/create-lamaste 4.2.0 → 4.3.1

package/vendor/serverd/src/lib/vhost-reconcile.js

@@ -0,0 +1,260 @@
+/**
+ * Startup: bring installed vhosts in line with what the generators in
+ * nginx.js produce today.
+ *
+ * A vhost is written when its tunnel or site is created or reconfigured, so a
+ * generator change never reached the ones that already existed. Two changes
+ * must:
+ *
+ * - from 4.3 lamaste-agentd accepts a request from the relay only with a
+ *   relay assertion, which only the current agent-panel vhost (signed by the
+ *   panel) and plugin vhosts (signed by Gatekeeper) forward;
+ * - the authorization subrequest of a Gatekeeper tunnel, of an
+ *   Authelia-protected static site and of the auth portal named the client's
+ *   `Host` header rather than the vhost's own hostname, so a request line for
+ *   one hostname sent with the `Host` of another was authorized for the other
+ *   (see `originalUrl` in nginx.js).
+ *
+ * Each installed vhost is rendered again from state, on the certificate
+ * directory the installed file names (a wildcard certificate stays a wildcard
+ * certificate), and rewritten only when the text differs — through the same
+ * backup / test / rollback path as any vhost write. A rewrite never links a
+ * vhost that is not linked now.
+ * A rewrite never adds or removes authentication: a vhost that disagrees with
+ * its state on that is reported and left alone. The one exception is the
+ * agent-panel vhost, whose mTLS check gains the panel's `auth_request`.
+ */
+
+import { withTunnelLock } from '@lamalibre/lamaste/server';
+import {
+  installVhost,
+  isSiteEnabled,
+  readInstalledVhost,
+  renderAgentPanelVhost,
+  renderAuthVhost,
+  renderStaticSiteVhost,
+  renderTunnelVhost,
+  vhostCertDir,
+} from './nginx.js';
+import { readSites, readTunnels } from './state.js';
+
+/** A subdomain or site id as it may appear in a site name. */
+const SITE_NAME_PART_RE = /^[A-Za-z0-9][A-Za-z0-9-]{0,62}$/;
+
+const AUTH_VHOST = 'lamalibre-lamaste-auth';
+
+/**
+ * The vhost a tunnel should have, rendered on `certDir`; null for tunnels
+ * without one (internal plugin tunnels) or whose state cannot be rendered.
+ *
+ * @param {object} tunnel
+ * @param {string} certDir
+ * @returns {{ name: string, fqdn: string, config: string } | null}
+ */
+export function expectedTunnelVhost(tunnel, certDir) {
+  if (!managedTunnelVhostName(tunnel) || typeof tunnel.fqdn !== 'string') return null;
+  if (!tunnel.fqdn.startsWith(`${tunnel.subdomain}.`)) return null;
+  const domain = tunnel.fqdn.slice(tunnel.subdomain.length + 1);
+  if (tunnel.type === 'panel') {
+    return renderAgentPanelVhost(tunnel.subdomain, domain, tunnel.port, certDir);
+  }
+  // As createTunnel and updateTunnel write it: the stored access mode
+  // (restricted when absent, as Gatekeeper reads it), the plugin route of a
+  // plugin tunnel, and a body limit only when the tunnel has one.
+  return renderTunnelVhost(
+    tunnel.accessMode ?? 'restricted',
+    tunnel.subdomain,
+    domain,
+    tunnel.port,
+    certDir,
+    {
+      ...(tunnel.type === 'plugin' && tunnel.pluginRoute ? { pathPrefix: tunnel.pluginRoute } : {}),
+      ...(tunnel.maxBodySizeMb !== undefined ? { maxBodySizeMb: tunnel.maxBodySizeMb } : {}),
+    },
+  );
+}
+
+/** Site name of a tunnel's vhost, or null for a tunnel without one. */
+function managedTunnelVhostName(tunnel) {
+  if (tunnel.exposure === 'internal' || typeof tunnel.subdomain !== 'string') return null;
+  if (!SITE_NAME_PART_RE.test(tunnel.subdomain)) return null;
+  if (tunnel.type === 'panel') return `lamalibre-lamaste-agent-panel-${tunnel.subdomain}`;
+  // Tunnels persisted before `type` existed are app tunnels.
+  if (tunnel.type === 'app' || tunnel.type === 'plugin' || tunnel.type === undefined) {
+    return `lamalibre-lamaste-app-${tunnel.subdomain}`;
+  }
+  return null;
+}
+
+/** True when a vhost asks for authorization before proxying or serving. */
+function authenticates(config) {
+  return /^\s*auth_request\s/m.test(config);
+}
+
+function newResult() {
+  return { rewritten: [], unchanged: 0, skipped: [], failed: [] };
+}
+
+/**
+ * Compare one installed vhost with what it should be and rewrite it when it
+ * differs; record the outcome in `result` under `label`.
+ *
+ * @param {object} p
+ * @param {string} p.name - site name in sites-available
+ * @param {string} p.label - how the result names it: the vhost's hostname
+ * @param {(certDir: string) => ({ name: string, fqdn: string, config: string } | null)} p.render
+ * @param {() => Promise<boolean>} p.enabled - whether the rewritten site is linked
+ * @param {boolean} [p.keepAuthentication] - refuse a rewrite that adds or removes `auth_request` (default true)
+ * @param {boolean} [p.reportMissing] - report a vhost that is not installed (default true)
+ * @param {ReturnType<typeof newResult>} result
+ * @param {{ readInstalledVhost: typeof readInstalledVhost, installVhost: typeof installVhost }} deps
+ */
+async function reconcileOne(
+  { name, label, render, enabled, keepAuthentication = true, reportMissing = true },
+  result,
+  deps,
+) {
+  try {
+    const installed = await deps.readInstalledVhost(name);
+    if (installed === null) {
+      if (reportMissing) result.skipped.push({ vhost: label, reason: 'no vhost installed' });
+      return;
+    }
+    const certDir = vhostCertDir(installed);
+    if (!certDir) {
+      result.skipped.push({ vhost: label, reason: 'installed vhost names no certificate' });
+      return;
+    }
+    const expected = render(certDir);
+    if (!expected) {
+      result.skipped.push({ vhost: label, reason: 'state cannot be rendered' });
+      return;
+    }
+    if (expected.config === installed) {
+      result.unchanged += 1;
+      return;
+    }
+    if (keepAuthentication && authenticates(expected.config) !== authenticates(installed)) {
+      result.skipped.push({
+        vhost: label,
+        reason:
+          'installed vhost and state disagree on whether it authenticates; reconfigure it to rewrite the vhost',
+      });
+      return;
+    }
+    await deps.installVhost(expected.name, expected.config, expected.fqdn, {
+      enabled: await enabled(),
+    });
+    result.rewritten.push(label);
+  } catch (err) {
+    result.failed.push({ vhost: label, error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+/**
+ * @param {{ info(o: object, m?: string): void, warn(o: object, m?: string): void, error(o: object, m?: string): void }} log
+ * @param {'tunnel' | 'site'} what - the vhosts the result is about, for the log messages
+ * @param {ReturnType<typeof newResult>} result
+ */
+function logResult(log, what, result) {
+  if (result.rewritten.length > 0) {
+    log.info({ rewritten: result.rewritten }, `Rewrote ${what} vhosts`);
+  }
+  if (result.skipped.length > 0) {
+    log.warn({ skipped: result.skipped }, `Left ${what} vhosts as they are`);
+  }
+  for (const failure of result.failed) {
+    log.error(failure, `Failed to rewrite ${what} vhost; the previous vhost was restored`);
+  }
+}
+
+const defaultTunnelDeps = { readTunnels, readInstalledVhost, installVhost, isSiteEnabled };
+
+/**
+ * Reconcile the vhost of every tunnel that has one: agent-panel, app and
+ * plugin tunnels. Runs under the tunnel lock, so no tunnel change
+ * interleaves. Call it once the panel listens: a rewritten agent-panel vhost
+ * asks the panel about every request.
+ *
+ * @param {Parameters<typeof logResult>[0]} log
+ * @param {typeof defaultTunnelDeps} [deps]
+ * @returns {Promise<ReturnType<typeof newResult>>}
+ */
+export async function reconcileTunnelVhosts(log, deps = defaultTunnelDeps) {
+  return withTunnelLock(async () => {
+    const result = newResult();
+    for (const tunnel of await deps.readTunnels()) {
+      const name = managedTunnelVhostName(tunnel);
+      if (!name) continue;
+      await reconcileOne(
+        {
+          name,
+          label: tunnel.fqdn ?? tunnel.subdomain,
+          render: (certDir) => expectedTunnelVhost(tunnel, certDir),
+          // Linked only when it is now and the tunnel is enabled: a rewrite of
+          // the text never publishes a vhost someone unlinked, and unlinks a
+          // disabled tunnel's.
+          enabled: async () => tunnel.enabled !== false && (await deps.isSiteEnabled(name)),
+          keepAuthentication: tunnel.type !== 'panel',
+        },
+        result,
+        deps,
+      );
+    }
+    logResult(log, 'tunnel', result);
+    return result;
+  });
+}
+
+const defaultSiteDeps = { readSites, readInstalledVhost, installVhost, isSiteEnabled };
+
+/**
+ * Reconcile the vhosts that ask Authelia directly: the auth portal
+ * (`auth.<domain>`) and every static site. Site changes take no lock, so call
+ * it before the panel listens — then nothing can change a site meanwhile.
+ *
+ * @param {Parameters<typeof logResult>[0]} log
+ * @param {string} domain
+ * @param {typeof defaultSiteDeps} [deps]
+ * @returns {Promise<ReturnType<typeof newResult>>}
+ */
+export async function reconcileSiteVhosts(log, domain, deps = defaultSiteDeps) {
+  const result = newResult();
+
+  await reconcileOne(
+    {
+      name: AUTH_VHOST,
+      label: `auth.${domain}`,
+      render: (certDir) => renderAuthVhost(domain, certDir),
+      enabled: () => deps.isSiteEnabled(AUTH_VHOST),
+    },
+    result,
+    deps,
+  );
+
+  let sites = [];
+  try {
+    sites = await deps.readSites();
+  } catch (err) {
+    result.failed.push({ vhost: 'sites', error: err instanceof Error ? err.message : String(err) });
+  }
+  for (const site of sites) {
+    if (typeof site.id !== 'string' || !SITE_NAME_PART_RE.test(site.id)) continue;
+    const name = `lamalibre-lamaste-site-${site.id}`;
+    await reconcileOne(
+      {
+        name,
+        label: site.fqdn ?? site.id,
+        render: (certDir) => renderStaticSiteVhost(site, certDir, domain),
+        enabled: () => deps.isSiteEnabled(name),
+        // A site still waiting for its DNS or certificate has no vhost yet.
+        reportMissing: site.certIssued === true,
+      },
+      result,
+      deps,
+    );
+  }
+
+  logResult(log, 'site', result);
+  return result;
+}

package/vendor/serverd/src/middleware/twofa-session.js

@@ -14,6 +14,15 @@ import {
  */
 const EXEMPT_PATHS = new Set(['/api/health', '/api/settings/2fa', '/api/settings/2fa/verify']);
 
+/**
+ * The agent-panel vhost's authorization subrequest
+ * (`/api/agent-panel/authz/<label>`). It is answered for a browser on
+ * `agent-<label>.<domain>`, which never carries the panel's host-only 2FA
+ * cookie; agent panels are guarded by the client certificate alone, as they
+ * were before the panel took part in their authorization.
+ */
+const AGENT_PANEL_AUTHZ_RE = /^\/api\/agent-panel\/authz\/[a-z0-9-]{1,63}$/;
+
 async function twofaSessionPlugin(fastify, _opts) {
   fastify.addHook('onRequest', async (request, reply) => {
     const config = getConfig();
@@ -30,7 +39,8 @@ async function twofaSessionPlugin(fastify, _opts) {
     }
 
     // Exempt paths
-    if (EXEMPT_PATHS.has(request.url) || EXEMPT_PATHS.has(request.url.split('?')[0])) {
+    const urlPath = request.url.split('?')[0];
+    if (EXEMPT_PATHS.has(urlPath) || AGENT_PANEL_AUTHZ_RE.test(urlPath)) {
       return;
     }
 

package/vendor/serverd/src/routes/agent-forwarder.js

@@ -0,0 +1,37 @@
+/**
+ * `/api/<route>/*` for agent-hosted plugins with an agent half — forwarded
+ * by the panel to the plugin's agent half over its internal tunnel, through
+ * the plugin's approved request hooks (`request:pre-forward` /
+ * `request:post-forward`) and, while it is down, its `tunnel:down` fallback.
+ * See `createHookedForwarder` in `@lamalibre/lamaste/server`.
+ *
+ * Registered after every other `/api` route: static routes win over its
+ * `/:route/*`, so only what nothing else answers arrives here, and a route
+ * that is no hosted plugin gets the panel's usual 404.
+ */
+import { createHookedForwarder } from '@lamalibre/lamaste/server';
+import { getConfig } from '../lib/config.js';
+import { resolveForwardTarget, authorizeForwardedCaller } from '../lib/plugin-hosting.js';
+import { requestHookRuntime } from '../lib/request-hooks.js';
+
+export default async function agentForwarderRoutes(fastify) {
+  const forwarder = createHookedForwarder({
+    resolveTarget: resolveForwardTarget,
+    authorize: authorizeForwardedCaller,
+    // Management routes answer 503 before onboarding completes; so does a
+    // hosted plugin's route (but a non-route stays a 404, as before).
+    guard: () => {
+      const config = getConfig();
+      if (config.onboarding.status !== 'COMPLETED') {
+        return {
+          status: 503,
+          body: { error: 'Onboarding not complete', onboardingStatus: config.onboarding.status },
+        };
+      }
+      return null;
+    },
+    logger: fastify.log,
+    hooks: requestHookRuntime,
+  });
+  await fastify.register(forwarder);
+}

package/vendor/serverd/src/routes/management/agent-panel-authz.js

@@ -0,0 +1,97 @@
+/**
+ * GET /api/agent-panel/authz/:label — the `auth_request` target of an
+ * agent-panel vhost (`agent-<label>.<domain>`).
+ *
+ * nginx calls it for every request on that vhost, with the client
+ * certificate's verification result in the `X-SSL-Client-*` headers (so the
+ * mTLS middleware refuses a revoked or unknown certificate, as for any panel
+ * route) and the request's method and target in `X-Original-Method` /
+ * `X-Original-URI`. On success it answers 200 with a relay assertion in
+ * `X-Lamalibre-Relay-Assertion`, which nginx forwards to the agent's
+ * lamaste-agentd — the only proof of the caller the daemon accepts from the
+ * relay. A 401/403 from here is what nginx answers the browser.
+ *
+ * Through the panel's own vhosts this route is reachable too, with
+ * client-chosen `X-Original-*`. That gains nothing: the assertion only ever
+ * names the caller's own, nginx-verified certificate, for a panel that
+ * certificate may use anyway.
+ */
+
+import { z } from 'zod';
+import { signRelayAssertion, RELAY_ASSERTION_HEADER } from '@lamalibre/lamaste';
+import { authorizeAgentPanelRequest } from '@lamalibre/lamaste/server';
+import { readTunnels } from '../../lib/state.js';
+import { relaySigner } from '../../lib/relay-signing.js';
+
+const LabelParamSchema = z.object({
+  label: z
+    .string()
+    .min(1)
+    .max(63)
+    .regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, 'Invalid agent label'),
+});
+
+/** @param {string | string[] | undefined} value */
+function single(value) {
+  return typeof value === 'string' ? value : undefined;
+}
+
+export default async function agentPanelAuthzRoutes(fastify, _opts) {
+  fastify.get(
+    '/agent-panel/authz/:label',
+    {
+      preHandler: fastify.requireRole(['admin', 'agent']),
+      // One call per request on an agent panel — its SPA's assets and API
+      // polling included — keyed by the browser's address (nginx sets
+      // X-Forwarded-For to $remote_addr on the subrequest). Well above what
+      // the daemon behind it serves (100/min), so it never is the limit.
+      config: { rateLimit: { max: 1200, timeWindow: '1 minute' } },
+    },
+    async (request, reply) => {
+      const { label } = LabelParamSchema.parse(request.params);
+      reply.header('Cache-Control', 'no-store');
+
+      const decision = authorizeAgentPanelRequest(
+        {
+          label,
+          certRole: request.certRole,
+          certLabel: request.certLabel,
+          method: single(request.headers['x-original-method']),
+          uri: single(request.headers['x-original-uri']),
+        },
+        await readTunnels(),
+      );
+      if (!decision.ok) {
+        request.log.info(
+          { label, certRole: request.certRole, reason: decision.reason },
+          'Agent panel request refused',
+        );
+        return reply.code(decision.status).send();
+      }
+
+      let key;
+      try {
+        key = await relaySigner.current();
+      } catch (err) {
+        request.log.error(
+          { err: err instanceof Error ? err.message : String(err) },
+          'Relay signing key unusable',
+        );
+        key = null;
+      }
+      if (!key) return reply.code(503).send();
+
+      const assertion = signRelayAssertion(
+        {
+          aud: decision.aud,
+          port: decision.port,
+          caller: decision.caller,
+          method: decision.method,
+          target: { path: decision.path },
+        },
+        key,
+      );
+      return reply.header(RELAY_ASSERTION_HEADER, assertion).code(200).send();
+    },
+  );
+}