@lamalibre/create-lamaste 4.2.0 → 4.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lamalibre/create-lamaste",
-  "version": "4.2.0",
+  "version": "4.3.1",
   "description": "One-command setup for secure reverse tunnels with a management dashboard",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE.md",
@@ -43,7 +43,7 @@
     "mtls"
   ],
   "dependencies": {
-    "@lamalibre/lamaste": "^4.2.0",
+    "@lamalibre/lamaste": "^4.3.1",
     "chalk": "^5.3.0",
     "execa": "^9.0.0",
     "listr2": "^8.0.0"

package/scripts/bundle-vendor.js

@@ -12,6 +12,7 @@ import { existsSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { assertProductionBundle } from '../../../../scripts/assert-production-bundle.js';
 
 const thisDir = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(thisDir, '..');
@@ -61,6 +62,8 @@ async function main() {
     );
   }
 
+  await assertProductionBundle(clientDist, { label: 'lamaste-server-ui/dist', monorepoRoot });
+
   const clientDest = join(vendorDir, 'server-ui');
   await mkdir(join(clientDest, 'dist'), { recursive: true });
   await cp(clientDist, join(clientDest, 'dist'), { recursive: true });
@@ -70,15 +73,17 @@ async function main() {
   // --- gatekeeper: package.json + dist/ (compiled TypeScript) ---
   const gatekeeperSrc = join(monorepoRoot, 'packages', 'sdks', 'gatekeeper');
   const gatekeeperDist = join(gatekeeperSrc, 'dist');
-  if (existsSync(gatekeeperDist)) {
-    const gatekeeperDest = join(vendorDir, 'gatekeeper');
-    await mkdir(gatekeeperDest, { recursive: true });
-    await cp(join(gatekeeperSrc, 'package.json'), join(gatekeeperDest, 'package.json'));
-    await cp(gatekeeperDist, join(gatekeeperDest, 'dist'), { recursive: true });
-    console.error('Bundled vendor/gatekeeper (package.json + dist/)');
-  } else {
-    console.error('Skipped vendor/gatekeeper (dist/ not found — run "npm run build" first)');
+  // An installer without Gatekeeper cannot deploy it: refuse, never skip.
+  if (!existsSync(gatekeeperDist)) {
+    throw new Error(
+      `lamaste-gatekeeper/dist/ not found at ${gatekeeperDist}. Run "npm run build" first.`,
+    );
   }
+  const gatekeeperDest = join(vendorDir, 'gatekeeper');
+  await mkdir(gatekeeperDest, { recursive: true });
+  await cp(join(gatekeeperSrc, 'package.json'), join(gatekeeperDest, 'package.json'));
+  await cp(gatekeeperDist, join(gatekeeperDest, 'dist'), { recursive: true });
+  console.error('Bundled vendor/gatekeeper (package.json + dist/)');
 
   // --- docs: version-stamped markdown ---
   const docsStampScript = join(

package/scripts/lamaste-priv

@@ -17,6 +17,11 @@
  *   nginx-site remove <name>           delete <name>, its link and its backup
  *   authelia-totp <username>           stdin: base32 secret
  *   self-update <version>              run create-lamaste@<version> detached
+ *   hooks install <route> <sha256|none>  stdin: the plugin's approved relay hook
+ *                                      module (none: shared hooks only); start its runner
+ *   hooks activate <route> <sha256>    point the runner back at a module kept from before
+ *   hooks restart <route>              stop the plugin's hook runner (the socket stays)
+ *   hooks remove <route>               disable the runner and delete its modules
  *
  * Why vhosts are validated: nginx's master process runs as root and opens the
  * files a configuration names — `access_log /etc/cron.d/x` with a crafted
@@ -484,7 +489,7 @@ function isRegularFile(p) {
   }
 }
 
-function readStdin(maxBytes) {
+function readStdinBytes(maxBytes) {
   const chunks = [];
   let total = 0;
   const buf = Buffer.alloc(65536);
@@ -502,7 +507,11 @@ function readStdin(maxBytes) {
     if (total > maxBytes) throw new UsageError('input is too large');
     chunks.push(Buffer.from(buf.subarray(0, read)));
   }
-  return Buffer.concat(chunks).toString('utf8');
+  return Buffer.concat(chunks);
+}
+
+function readStdin(maxBytes) {
+  return readStdinBytes(maxBytes).toString('utf8');
 }
 
 // ---------------------------------------------------------------------------
@@ -668,6 +677,193 @@ function selfUpdate(version) {
   process.stdout.write(`${unit}\n`);
 }
 
+// ---------------------------------------------------------------------------
+// Relay hook runners
+// ---------------------------------------------------------------------------
+
+const HOOKS_DIR = '/opt/lamalibre/lamaste/hooks';
+const HOOKS_UNIT_PREFIX = 'lamalibre-lamaste-hooks';
+const SYSTEMCTL = '/usr/bin/systemctl';
+const HOOK_ROUTE_RE = /^[a-z0-9]([a-z0-9-]{0,98}[a-z0-9])?$/;
+const SHA256_RE = /^[a-f0-9]{64}$/;
+const MAX_HOOK_MODULE_BYTES = 4 * 1024 * 1024;
+
+function assertHookRoute(route) {
+  if (typeof route !== 'string' || !HOOK_ROUTE_RE.test(route)) {
+    throw new UsageError('invalid plugin route');
+  }
+}
+
+function assertSha256(digest) {
+  if (typeof digest !== 'string' || !SHA256_RE.test(digest)) {
+    throw new UsageError('digest must be a SHA-256 hex string');
+  }
+}
+
+/** Create `dir` (0755, root) unless it exists; refuse anything but a root-owned directory. */
+function ensureRootDirectory(dir) {
+  try {
+    fs.mkdirSync(dir, { mode: 0o755 });
+  } catch (err) {
+    if (err.code !== 'EEXIST') throw err;
+  }
+  const st = fs.lstatSync(dir);
+  if (!st.isDirectory() || st.uid !== 0) {
+    throw new Error(`${dir} is not a root-owned directory`);
+  }
+}
+
+function sha256(bytes) {
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+function systemctl(args, { allowFailure = false } = {}) {
+  const result = spawnSync(SYSTEMCTL, args, {
+    cwd: '/',
+    env: { PATH: '/usr/sbin:/usr/bin:/sbin:/bin' },
+    encoding: 'utf8',
+    timeout: 30_000,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0 && !allowFailure) {
+    throw new Error(
+      `systemctl ${args.join(' ')} exited with status ${result.status}: ${(result.stderr || '').trim()}`,
+    );
+  }
+}
+
+function runnerEnvPath(route) {
+  return path.join(HOOKS_DIR, route, 'runner.env');
+}
+
+/** The module the runner currently loads (from runner.env), or null. */
+function activeHookModule(route) {
+  let text;
+  try {
+    text = fs.readFileSync(runnerEnvPath(route), 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+  const m = /^LAMASTE_HOOK_RUNNER_ARGS=--entry (\S+)$/m.exec(text);
+  return m ? m[1] : null;
+}
+
+/**
+ * runner.env: the node flag that lets the runner read the module, and the
+ * runner flag that names it. Both empty when the plugin uses shared hooks
+ * only. Paths are built here, never taken from the caller.
+ */
+function writeRunnerEnv(route, modulePath) {
+  const nodeArgs = modulePath ? `--allow-fs-read=${modulePath}` : '';
+  const runnerArgs = modulePath ? `--entry ${modulePath}` : '';
+  atomicWrite(
+    runnerEnvPath(route),
+    `# Managed by lamaste-priv: the approved relay hook module of plugin ${route}.\n` +
+      `LAMASTE_HOOK_NODE_ARGS=${nodeArgs}\nLAMASTE_HOOK_RUNNER_ARGS=${runnerArgs}\n`,
+    0o644,
+  );
+}
+
+/** Keep the active module and the one before it (for `hooks activate`); delete the rest. */
+function pruneHookModules(route, keep) {
+  const dir = path.join(HOOKS_DIR, route);
+  for (const name of fs.readdirSync(dir)) {
+    if (!/^[a-f0-9]{64}\.mjs$/.test(name)) continue;
+    const file = path.join(dir, name);
+    if (!keep.includes(file)) unlinkIfPresent(file);
+  }
+}
+
+function restartRunner(route) {
+  // The socket stays; the next call starts a runner with the new module.
+  systemctl(['stop', `${HOOKS_UNIT_PREFIX}@${route}.service`]);
+}
+
+function hooksInstall(route, digest) {
+  assertHookRoute(route);
+  if (digest !== 'none') assertSha256(digest);
+  ensureRootDirectory(HOOKS_DIR);
+  ensureRootDirectory(path.join(HOOKS_DIR, route));
+  const previous = activeHookModule(route);
+
+  let modulePath = null;
+  if (digest !== 'none') {
+    const bytes = readStdinBytes(MAX_HOOK_MODULE_BYTES);
+    if (bytes.length === 0) throw new UsageError('the hook module arrives on stdin');
+    if (sha256(bytes) !== digest) {
+      throw new Error('the hook module does not match the approved digest');
+    }
+    modulePath = path.join(HOOKS_DIR, route, `${digest}.mjs`);
+    if (!isRegularFile(modulePath) || sha256(fs.readFileSync(modulePath)) !== digest) {
+      atomicWrite(modulePath, bytes, 0o644);
+    }
+  }
+  writeRunnerEnv(route, modulePath);
+  pruneHookModules(route, [modulePath, previous].filter(Boolean));
+  systemctl(['enable', '--now', `${HOOKS_UNIT_PREFIX}@${route}.socket`]);
+  restartRunner(route);
+}
+
+function hooksActivate(route, digest) {
+  assertHookRoute(route);
+  assertSha256(digest);
+  const modulePath = path.join(HOOKS_DIR, route, `${digest}.mjs`);
+  if (!isRegularFile(modulePath) || sha256(fs.readFileSync(modulePath)) !== digest) {
+    throw new Error('no kept hook module has that digest');
+  }
+  const previous = activeHookModule(route);
+  writeRunnerEnv(route, modulePath);
+  pruneHookModules(route, [modulePath, previous].filter(Boolean));
+  systemctl(['enable', '--now', `${HOOKS_UNIT_PREFIX}@${route}.socket`]);
+  restartRunner(route);
+}
+
+function hooksRestart(route) {
+  assertHookRoute(route);
+  restartRunner(route);
+}
+
+function hooksRemove(route) {
+  assertHookRoute(route);
+  systemctl(['disable', '--now', `${HOOKS_UNIT_PREFIX}@${route}.socket`], { allowFailure: true });
+  systemctl(['stop', `${HOOKS_UNIT_PREFIX}@${route}.service`], { allowFailure: true });
+  const dir = path.join(HOOKS_DIR, route);
+  let st = null;
+  try {
+    st = fs.lstatSync(dir);
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  if (st) {
+    if (!st.isDirectory() || st.uid !== 0) throw new Error(`${dir} is not a root-owned directory`);
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function hooks(action, rest) {
+  switch (action) {
+    case 'install':
+      if (rest.length !== 2) throw new UsageError('usage: hooks install <route> <sha256|none>');
+      hooksInstall(rest[0], rest[1]);
+      return;
+    case 'activate':
+      if (rest.length !== 2) throw new UsageError('usage: hooks activate <route> <sha256>');
+      hooksActivate(rest[0], rest[1]);
+      return;
+    case 'restart':
+      if (rest.length !== 1) throw new UsageError('usage: hooks restart <route>');
+      hooksRestart(rest[0]);
+      return;
+    case 'remove':
+      if (rest.length !== 1) throw new UsageError('usage: hooks remove <route>');
+      hooksRemove(rest[0]);
+      return;
+    default:
+      throw new UsageError(`unknown hooks action: ${action ?? '(none)'}`);
+  }
+}
+
 function main(argv) {
   if (typeof process.getuid !== 'function' || process.getuid() !== 0) {
     throw new UsageError('must run as root (via sudo)');
@@ -687,6 +883,10 @@ function main(argv) {
       if (rest.length !== 1) throw new UsageError('usage: self-update <version>');
       selfUpdate(rest[0]);
       return;
+    case 'hooks':
+      if (rest.length < 1) throw new UsageError('usage: hooks <action> <route> [...]');
+      hooks(rest[0], rest.slice(1));
+      return;
     default:
       throw new UsageError(`unknown operation: ${op ?? '(none)'}`);
   }
@@ -708,5 +908,8 @@ if (require.main === module) {
     PANEL_SITE_RE,
     UsageError,
     AUTHELIA_CLI_ENV,
+    assertHookRoute,
+    HOOK_ROUTE_RE,
+    main,
   };
 }

package/src/index.js

@@ -14,6 +14,7 @@ import chalk from 'chalk';
 import { execa } from 'execa';
 import { detectOS, detectIP, checkRoot } from './lib/env.js';
 import { printSummary } from './lib/summary.js';
+import { readPanelKeyPin } from './lib/panel-pin.js';
 import { hardenTasks } from './tasks/harden.js';
 import { nodeTasks } from './tasks/node.js';
 import { mtlsTasks } from './tasks/mtls.js';
@@ -85,7 +86,7 @@ ${b('SYSTEM MODIFICATIONS')}
     • Hardens SSH (disables password authentication)
 
   ${y('Packages')}
-    • Installs Node.js 20, nginx, certbot
+    • Installs Node.js 22, nginx, certbot
 
   ${y('Certificates')}
     • Generates mTLS CA, server, and client certificates
@@ -330,7 +331,7 @@ ${chalk.cyan.bold('│')}  The following changes will be made:
 ${chalk.cyan.bold('│')}                                                             ${chalk.cyan.bold('│')}
 ${chalk.cyan.bold('│')}    ${chalk.yellow('•')} Reset UFW firewall (allow ports 22, 80, 443, 9292)     ${chalk.cyan.bold('│')}
 ${chalk.cyan.bold('│')}    ${chalk.yellow('•')} Harden SSH (disable password authentication)           ${chalk.cyan.bold('│')}
-${chalk.cyan.bold('│')}    ${chalk.yellow('•')} Install fail2ban, Node.js 20, nginx, certbot           ${chalk.cyan.bold('│')}
+${chalk.cyan.bold('│')}    ${chalk.yellow('•')} Install fail2ban, Node.js 22, nginx, certbot           ${chalk.cyan.bold('│')}
 ${chalk.cyan.bold('│')}    ${chalk.yellow('•')} Generate mTLS certificates for browser access          ${chalk.cyan.bold('│')}
 ${chalk.cyan.bold('│')}    ${chalk.yellow('•')} Create lamaste user and systemd service               ${chalk.cyan.bold('│')}
 ${chalk.cyan.bold('│')}    ${chalk.yellow('•')} Deploy panel to /opt/lamalibre/lamaste/               ${chalk.cyan.bold('│')}
@@ -556,7 +557,7 @@ export async function main() {
         // nginx, certbot and openssl. Its hardening subtasks (UFW, fail2ban,
         // SSH) skip themselves — the same as the interactive install.
         { key: 'harden_system', title: 'Hardening operating system', fn: hardenTasks },
-        { key: 'install_node', title: 'Installing Node.js 20', fn: nodeTasks },
+        { key: 'install_node', title: 'Installing Node.js 22', fn: nodeTasks },
         { key: 'generate_certs', title: 'Generating mTLS certificates', fn: mtlsTasks },
         { key: 'configure_nginx', title: 'Configuring nginx', fn: nginxTasks },
         { key: 'deploy_panel', title: 'Deploying Lamaste panel', fn: panelTasks },
@@ -574,7 +575,7 @@ export async function main() {
             task: (_ctx, task) => hardenTasks(ctx, task),
           },
           {
-            title: 'Installing Node.js 20',
+            title: 'Installing Node.js 22',
             task: (_ctx, task) => nodeTasks(ctx, task),
           },
           {
@@ -630,6 +631,7 @@ export async function main() {
   }
 
   if (flags.json) {
+    const panelServerPubkeySha256 = await readPanelKeyPin(ctx.pkiDir);
     emitJson({
       event: 'complete',
       server: {
@@ -637,6 +639,8 @@ export async function main() {
         panelUrl: `https://${ctx.ip}:9292`,
         p12Path: `${ctx.pkiDir}/client.p12`,
         p12PasswordPath: `${ctx.pkiDir}/.p12-password`,
+        // The key pin of the panel's IP certificate, for the desktop app.
+        ...(panelServerPubkeySha256 ? { panelServerPubkeySha256 } : {}),
       },
     });
   } else {

package/src/lib/node-version.js

@@ -0,0 +1,114 @@
+import { execa } from 'execa';
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+/** The Node.js line the relay runs, from NodeSource. */
+export const NODE_MAJOR = 22;
+
+/**
+ * The oldest Node.js the relay accepts: 22.5 brought `node:sqlite`
+ * (lamaste-serverd's state database) and 22.13 the stable permission model
+ * (`--permission`), which sandboxes the relay hook runner. NodeSource's 22.x
+ * line moves on its own, so the minor is checked, not only the major.
+ */
+export const MIN_NODE_VERSION = '22.13.0';
+
+/**
+ * lamaste-serverd's `engines` stops below 25: Node 25 adds network
+ * permissions to `--permission`, which the hook runner's unit does not grant.
+ */
+export const MAX_NODE_MAJOR_EXCLUSIVE = 25;
+
+/** The binary every Lamaste unit runs (`ExecStart=/usr/bin/node …`). */
+export const NODE_BIN = '/usr/bin/node';
+
+/** `v22.13.1` → [22, 13, 1]; null when it is not a version. */
+function parseNodeVersion(version) {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(String(version).trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+/** Whether `version` is at least {@link MIN_NODE_VERSION} and below {@link MAX_NODE_MAJOR_EXCLUSIVE}. */
+export function nodeVersionSupported(version) {
+  const v = parseNodeVersion(version);
+  const min = parseNodeVersion(MIN_NODE_VERSION);
+  if (!v || !min) return false;
+  if (v[0] >= MAX_NODE_MAJOR_EXCLUSIVE) return false;
+  for (let i = 0; i < 3; i++) {
+    if (v[i] !== min[i]) return v[i] > min[i];
+  }
+  return true;
+}
+
+/** Whether `version` is too new to be installed over (only an operator should downgrade). */
+export function nodeVersionTooNew(version) {
+  const v = parseNodeVersion(version);
+  return v !== null && v[0] >= MAX_NODE_MAJOR_EXCLUSIVE;
+}
+
+/** The refusal of a {@link nodeVersionTooNew} Node.js. */
+export function nodeTooNewError(version) {
+  return new Error(
+    `Node.js ${version} at ${NODE_BIN} is not supported: Lamaste needs ${MIN_NODE_VERSION} or later, below ${MAX_NODE_MAJOR_EXCLUSIVE}.`,
+  );
+}
+
+/** The version of {@link NODE_BIN}, or null when it is missing. */
+export async function installedNodeVersion() {
+  try {
+    const { stdout } = await execa(NODE_BIN, ['--version']);
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Install or upgrade Node.js from NodeSource's {@link NODE_MAJOR}.x line.
+ *
+ * The setup script runs as root, so it is downloaded into a directory of
+ * its own (`mkdtemp`, 0700) — never a fixed path in the shared /tmp, where
+ * another user could have put a file or a link first — and the directory
+ * goes on every path.
+ *
+ * @param {(line: string) => void} report
+ * @param {{ exec?: typeof execa, tmpRoot?: string }} [options] - replaces the commands and the
+ *   temporary directory's parent (tests)
+ */
+export async function installNodeFromNodeSource(report, options = {}) {
+  const exec = options.exec ?? execa;
+  const dir = await mkdtemp(path.join(options.tmpRoot ?? os.tmpdir(), 'lamaste-nodesource-'));
+  const setupScript = path.join(dir, 'nodesource_setup.sh');
+  try {
+    report('Downloading the NodeSource setup script...');
+    try {
+      await exec('curl', [
+        '-fsSL',
+        `https://deb.nodesource.com/setup_${NODE_MAJOR}.x`,
+        '-o',
+        setupScript,
+      ]);
+    } catch (error) {
+      throw new Error(
+        `Failed to download the NodeSource setup script. Check your internet connection.\n${error.stderr || error.message}`,
+      );
+    }
+    report('Running the NodeSource setup...');
+    try {
+      await exec('bash', [setupScript]);
+    } catch (error) {
+      throw new Error(`NodeSource setup script failed.\n${error.stderr || error.message}`);
+    }
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+  report('Running apt-get install nodejs...');
+  try {
+    await exec('apt-get', ['install', '-y', 'nodejs']);
+  } catch (error) {
+    throw new Error(
+      `Failed to install Node.js. Try running 'apt-get update' manually and retrying.\n${error.stderr || error.message}`,
+    );
+  }
+}

package/src/lib/panel-pin.js

@@ -0,0 +1,41 @@
+/**
+ * The key pin of the panel's IP certificate, for the installer's JSON
+ * `complete` event: the desktop app's local install stores it with the
+ * server and verifies `https://<ip>:9292` by it from its first call on —
+ * no trust on first use.
+ */
+
+import { X509Certificate, createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Base64 SHA-256 of the certificate's SubjectPublicKeyInfo — curl's
+ * `--pinnedpubkey sha256//<pin>` form, the one agents and the desktop app
+ * store (`panelServerPubkeySha256`).
+ *
+ * @param {string | Buffer} certificatePem
+ * @returns {string}
+ */
+export function panelKeyPin(certificatePem) {
+  const spki = new X509Certificate(certificatePem).publicKey.export({
+    type: 'spki',
+    format: 'der',
+  });
+  return createHash('sha256').update(spki).digest('base64');
+}
+
+/**
+ * The pin of `<pkiDir>/self-signed.pem` (written by `tasks/nginx.js`), or
+ * undefined when it cannot be read — the desktop then pins on first use.
+ *
+ * @param {string} pkiDir
+ * @returns {Promise<string | undefined>}
+ */
+export async function readPanelKeyPin(pkiDir) {
+  try {
+    return panelKeyPin(await readFile(join(pkiDir, 'self-signed.pem')));
+  } catch {
+    return undefined;
+  }
+}

package/src/lib/relay-services.js

@@ -17,9 +17,14 @@ import {
   AUTHELIA_USER,
   CHISEL_GROUP,
   CHISEL_UNIT_PATH,
+  HOOKS_DIR,
+  HOOKS_SERVICE_UNIT_PATH,
+  HOOKS_SOCKET_UNIT_PATH,
   WEB_ROOT,
   generateAutheliaUnit,
   generateChiselUnit,
+  generateHooksServiceUnit,
+  generateHooksSocketUnit,
 } from './service-config.js';
 
 async function writeIfChanged(path, content) {
@@ -44,7 +49,7 @@ async function writeIfChanged(path, content) {
  * `systemctl daemon-reload` and restarts what changed. Onboarding enables
  * and starts chisel and Authelia on a fresh install.
  *
- * @param {{ configDir: string, pkiDir: string }} ctx
+ * @param {{ configDir: string, pkiDir: string, installDir: string }} ctx
  * @param {(line: string) => void} report
  * @returns {Promise<{ chiselChanged: boolean, autheliaChanged: boolean }>}
  *   whether the binary or unit of each changed (a running service needs a
@@ -100,6 +105,15 @@ export async function provisionRelayServices(ctx, report) {
   const chiselUnitChanged = await writeIfChanged(CHISEL_UNIT_PATH, generateChiselUnit(ctx));
   const autheliaUnitChanged = await writeIfChanged(AUTHELIA_UNIT_PATH, generateAutheliaUnit());
 
+  // Relay hook runners: template units only. lamaste-priv enables an
+  // instance per plugin and places its approved module under HOOKS_DIR,
+  // which stays root's; a running runner picks a new unit up when it next
+  // starts (it exits when idle).
+  report('Writing the relay hook runner units...');
+  await ensureDirectory(HOOKS_DIR, { uid: 0, gid: 0, mode: 0o755 });
+  await writeIfChanged(HOOKS_SOCKET_UNIT_PATH, generateHooksSocketUnit());
+  await writeIfChanged(HOOKS_SERVICE_UNIT_PATH, generateHooksServiceUnit(ctx));
+
   return {
     chiselChanged: chisel.changed || chiselUnitChanged,
     autheliaChanged: authelia.changed || autheliaUnitChanged || autheliaDir.migrated,

package/src/lib/service-config.js

@@ -301,6 +301,119 @@ WantedBy=multi-user.target
 `;
 }
 
+/**
+ * Relay hook runners — one per plugin that brings relay lifecycle hooks
+ * (`lamalibre-lamaste-hooks@<route>`). The panel never imports plugin code;
+ * it calls the plugin's runner over a Unix socket, and the runner runs the
+ * plugin's approved hook module in the sandbox below. Template units, written
+ * by create-lamaste; `lamaste-priv hooks install|remove|restart <route>`
+ * enables an instance and places its approved module under
+ * {@link HOOKS_DIR}/<route>/ (root-owned). Must match the server subpath's
+ * `HOOK_RUNNER_SOCKET_DIR` in @lamalibre/lamaste.
+ */
+export const HOOKS_UNIT_PREFIX = 'lamalibre-lamaste-hooks';
+export const HOOKS_SOCKET_UNIT_PATH = `/etc/systemd/system/${HOOKS_UNIT_PREFIX}@.socket`;
+export const HOOKS_SERVICE_UNIT_PATH = `/etc/systemd/system/${HOOKS_UNIT_PREFIX}@.service`;
+export const HOOKS_SOCKET_DIR = '/run/lamalibre-lamaste-hooks';
+export const HOOKS_DIR = '/opt/lamalibre/lamaste/hooks';
+
+/**
+ * The hook runner's socket: created by systemd, reachable by the panel's
+ * group only. The first connection starts the runner (socket activation),
+ * which exits when idle.
+ *
+ * @returns {string}
+ */
+export function generateHooksSocketUnit() {
+  return `[Unit]
+Description=Lamaste relay hook runner socket (plugin %i)
+
+[Socket]
+ListenStream=${HOOKS_SOCKET_DIR}/%i.sock
+SocketUser=root
+SocketGroup=lamaste
+SocketMode=0660
+DirectoryMode=0755
+RemoveOnStop=yes
+Accept=no
+Backlog=64
+
+[Install]
+WantedBy=sockets.target
+`;
+}
+
+/**
+ * The hook runner: Lamaste's runner program and one plugin's approved hook
+ * module, in a sandbox — a dynamic user with nothing of the relay's, a
+ * read-only file system with the panel's state, Authelia, certificates and
+ * nginx out of reach, no network (Unix sockets only, its own network
+ * namespace), and Node's permission model allowing reads of the runner and
+ * the module only (no child processes, workers, addons or writes).
+ * Standard output and error are discarded so nothing a hook prints — it sees
+ * application data — reaches the journal. `runner.env`, written by
+ * lamaste-priv, names the module.
+ *
+ * @param {{ installDir: string }} ctx
+ * @returns {string}
+ */
+export function generateHooksServiceUnit(ctx) {
+  const lib = `${ctx.installDir}/serverd/node_modules/@lamalibre/lamaste/dist/hooks`;
+  return `[Unit]
+Description=Lamaste relay hook runner (plugin %i)
+Requires=${HOOKS_UNIT_PREFIX}@%i.socket
+After=${HOOKS_UNIT_PREFIX}@%i.socket
+ConditionPathExists=${HOOKS_DIR}/%i/runner.env
+
+[Service]
+Type=simple
+EnvironmentFile=${HOOKS_DIR}/%i/runner.env
+ExecStart=/usr/bin/node --permission --allow-fs-read=${lib}/* --max-old-space-size=160 $LAMASTE_HOOK_NODE_ARGS ${lib}/runner.js --plugin %i --listen-fd 3 $LAMASTE_HOOK_RUNNER_ARGS
+Restart=no
+TimeoutStopSec=2
+StandardOutput=null
+StandardError=null
+
+DynamicUser=yes
+UMask=0077
+NoNewPrivileges=yes
+CapabilityBoundingSet=
+AmbientCapabilities=
+ProtectSystem=strict
+ProtectHome=yes
+PrivateTmp=yes
+PrivateDevices=yes
+PrivateIPC=yes
+PrivateNetwork=yes
+ProtectHostname=yes
+ProtectClock=yes
+ProtectKernelTunables=yes
+ProtectKernelModules=yes
+ProtectKernelLogs=yes
+ProtectControlGroups=yes
+ProtectProc=invisible
+ProcSubset=pid
+RestrictNamespaces=yes
+RestrictRealtime=yes
+RestrictSUIDSGID=yes
+LockPersonality=yes
+RemoveIPC=yes
+RestrictAddressFamilies=AF_UNIX
+IPAddressDeny=any
+SystemCallArchitectures=native
+SystemCallFilter=@system-service
+SystemCallFilter=~@privileged
+SystemCallErrorNumber=EPERM
+TemporaryFileSystem=/run:ro /var:ro /srv:ro /mnt:ro /media:ro
+InaccessiblePaths=-/etc/lamalibre -/etc/authelia -/etc/letsencrypt -/etc/nginx -/etc/ssh -/etc/sudoers.d -/etc/sudoers -/etc/shadow -/etc/gshadow
+MemoryMax=256M
+MemorySwapMax=0
+CPUQuota=50%
+TasksMax=32
+LimitNOFILE=1024
+`;
+}
+
 /** sites-available name of the port-80 catch-all. */
 export const HTTP_REDIRECT_SITE = 'lamalibre-lamaste-http-redirect';