@lamalibre/create-lamaste 4.3.0 → 4.4.0

package/vendor/server/src/panel-identity.js

@@ -0,0 +1,165 @@
+/**
+ * The panel's IP listener, as `lamaste-server` verifies it.
+ *
+ * The CLI runs as root on the relay and sends the panel requests that carry
+ * the registry token, plugin settings and secrets, and the admin client
+ * certificate. It reaches the panel through nginx's IP vhost on port 9292
+ * (`lamalibre-lamaste-panel-ip`), which presents the self-signed certificate
+ * create-lamaste generated for the server's address
+ * (`<PKI_DIR>/self-signed.pem`; its key is 0600). Port 9292 is not a
+ * privileged port: whenever nginx does not hold it — panel 2FA switches the
+ * IP vhost off, nginx is stopped or failed to start — any local user can
+ * listen there. So the CLI never trusts whatever answers on it:
+ *
+ * - before connecting, it refuses when panel 2FA is on or the IP vhost is not
+ *   enabled, since nginx then does not listen on 9292 (`assertPanelListener`);
+ * - every request verifies the listener against exactly that certificate,
+ *   read from disk as root (`readPanelIdentity`, curl `--cacert`), never
+ *   `-k`. The TLS handshake fails before the CLI presents its client
+ *   certificate or sends a byte of the request (see `buildPanelCurlRequest`).
+ */
+
+import { X509Certificate, createHash } from 'node:crypto';
+import { lstat, readFile } from 'node:fs/promises';
+import net from 'node:net';
+import path from 'node:path';
+import { PKI_DIR } from './config.js';
+
+/** The port of nginx's IP vhost for the panel. */
+export const PANEL_IP_PORT = 9292;
+
+/** The certificate the IP vhost presents (create-lamaste, `tasks/nginx.js`). */
+export const PANEL_IP_CERT_PATH = path.join(PKI_DIR, 'self-signed.pem');
+
+/** The IP vhost's link in nginx's enabled sites (panel 2FA removes it). */
+export const PANEL_IP_SITE_ENABLED = '/etc/nginx/sites-enabled/lamalibre-lamaste-panel-ip';
+
+/** Where the CLI connects: the panel's own machine. */
+export const PANEL_LOOPBACK = '127.0.0.1';
+
+/**
+ * The IPv4 address a certificate is issued for: its first `IP Address`
+ * subject alternative name. create-lamaste (and the restore procedure in the
+ * docs) issue the IP vhost's certificate with `subjectAltName=IP:<address>`;
+ * curl checks the request's host against it. Pure, exported for tests.
+ *
+ * @param {X509Certificate} cert
+ * @returns {string}
+ */
+export function certifiedAddress(cert) {
+  const names = (cert.subjectAltName ?? '').split(', ');
+  for (const name of names) {
+    if (!name.startsWith('IP Address:')) continue;
+    const address = name.slice('IP Address:'.length).trim();
+    if (net.isIPv4(address)) return address;
+  }
+  throw new Error(
+    'The panel certificate names no IPv4 address (subjectAltName IP:<address>), so it cannot be verified',
+  );
+}
+
+/**
+ * The certificate's public-key pin: base64 SHA-256 of its SubjectPublicKeyInfo
+ * — curl's `--pinnedpubkey sha256//<pin>` form, the one agents and the
+ * desktop app store for the panel. Pure, exported for tests.
+ *
+ * @param {X509Certificate} cert
+ * @returns {string}
+ */
+export function publicKeyPin(cert) {
+  const spki = cert.publicKey.export({ type: 'spki', format: 'der' });
+  return createHash('sha256').update(spki).digest('base64');
+}
+
+/**
+ * Read the IP vhost's certificate: the identity every panel request is
+ * verified against. A link or a file others could write is refused — the
+ * CLI only trusts a certificate as much as the file that holds it. The file
+ * is read on every request, so a certificate regenerated by a full
+ * reinstall (or the restore procedure) is picked up as soon as nginx serves
+ * it.
+ *
+ * @param {string} [certPath]
+ * @returns {Promise<{ certPath: string, address: string, port: number, pin: string }>}
+ */
+export async function readPanelIdentity(certPath = PANEL_IP_CERT_PATH) {
+  let st;
+  try {
+    st = await lstat(certPath);
+  } catch (err) {
+    throw new Error(
+      `Cannot read the panel's TLS certificate ${certPath} (${err.code ?? err.message}); ` +
+        'lamaste-server verifies the panel against it and sends nothing without it',
+    );
+  }
+  if (!st.isFile()) {
+    throw new Error(`The panel's TLS certificate ${certPath} is not a regular file`);
+  }
+  if ((st.mode & 0o022) !== 0) {
+    throw new Error(
+      `The panel's TLS certificate ${certPath} is writable by group or others; refusing to trust it`,
+    );
+  }
+  let cert;
+  try {
+    cert = new X509Certificate(await readFile(certPath));
+  } catch {
+    throw new Error(`${certPath} does not hold a certificate`);
+  }
+  return {
+    certPath,
+    address: certifiedAddress(cert),
+    port: PANEL_IP_PORT,
+    pin: publicKeyPin(cert),
+  };
+}
+
+/**
+ * Why nothing verified listens on the IP vhost's port, or null when nginx
+ * should hold it. Pure, exported for tests.
+ *
+ * @param {{ panel2faEnabled: boolean, siteEnabled: boolean }} state
+ * @returns {string | null}
+ */
+export function panelListenerRefusal({ panel2faEnabled, siteEnabled }) {
+  if (panel2faEnabled) {
+    return (
+      'Panel 2FA is enabled: it switches off the panel listener on port 9292 that lamaste-server ' +
+      'talks to, and every admin request then needs a 2FA session the CLI cannot hold. Nothing was ' +
+      'sent. Use the panel in the browser, or turn 2FA off in its Settings to use this command.'
+    );
+  }
+  if (!siteEnabled) {
+    return (
+      'The panel listener on port 9292 is not enabled (nginx site lamalibre-lamaste-panel-ip), so ' +
+      'nginx does not hold the port and nothing was sent to it. Re-enable the site or re-run ' +
+      'create-lamaste.'
+    );
+  }
+  return null;
+}
+
+/**
+ * Refuse before connecting when nginx does not listen on the IP vhost's
+ * port: whatever answered there could only be someone else's listener.
+ *
+ * @param {Record<string, unknown> | null} config  panel.json
+ * @param {string} [siteEnabledPath]
+ * @returns {Promise<void>}
+ */
+export async function assertPanelListener(config, siteEnabledPath = PANEL_IP_SITE_ENABLED) {
+  let siteEnabled = true;
+  try {
+    // The link itself, not what it points to: nginx follows it.
+    await lstat(siteEnabledPath);
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+    siteEnabled = false;
+  }
+  const twofa = config?.panel2fa;
+  const refusal = panelListenerRefusal({
+    panel2faEnabled: typeof twofa === 'object' && twofa !== null && twofa.enabled === true,
+    siteEnabled,
+  });
+  if (refusal) throw new Error(refusal);
+}

package/vendor/server/src/plugin-approval.js

@@ -0,0 +1,78 @@
+/**
+ * `lamaste-server plugins hooks|update|approve-hooks`: why an update waits
+ * for approval, the command that approves it, and the arguments that
+ * command takes. Pure — no output — so they are tested as they are.
+ */
+
+import { terminalText } from './plugin-settings.js';
+
+const DIGEST_RE = /^[a-f0-9]{64}$/;
+const VERSION_RE = /^[0-9A-Za-z.+-]{1,64}$/;
+/** The reason an update turns secret settings into plain ones. */
+const SETTINGS_SECRET_TO_PLAIN = 'settings.secret-to-plain';
+
+/** How `approve-hooks` is called. */
+export const APPROVE_HOOKS_USAGE =
+  'Usage: lamaste-server plugins approve-hooks <name> --digest <sha256> [--version <v>] (what `hooks <name>` shows)';
+
+/**
+ * Why a pending update waits, as the terminal shows it: each reason of
+ * `approvalRequired` (`[{ code, reason }]`; a secret turned plain is a
+ * warning), and the sentences of `autoApproveWithheld` that do not repeat
+ * one of them — what auto-approve, when on, could not cover beyond that.
+ * Every text as {@link terminalText}.
+ *
+ * @param {{ approvalRequired?: unknown, autoApproveWithheld?: unknown }} update
+ * @returns {{ required: Array<{ text: string, warning: boolean }>, notCovered: string[] }}
+ */
+export function pendingUpdateReasons(update) {
+  const required = (Array.isArray(update?.approvalRequired) ? update.approvalRequired : [])
+    .filter((entry) => entry !== null && typeof entry === 'object')
+    .map((entry) => ({
+      text: terminalText(entry.reason),
+      warning: entry.code === SETTINGS_SECRET_TO_PLAIN,
+    }));
+  const said = new Set(required.map((line) => line.text));
+  const notCovered = (Array.isArray(update?.autoApproveWithheld) ? update.autoApproveWithheld : [])
+    .map((reason) => terminalText(reason))
+    .filter((text) => !said.has(text));
+  return { required, notCovered };
+}
+
+/**
+ * The command that approves what plugin `name` brings: the installed
+ * version by its digest (`{ digest }`), or a pending update by its version
+ * and — when it has one — its digest (`{ digest, version }`).
+ *
+ * @param {string} name
+ * @param {{ digest?: string | null, version?: string | null }} target
+ */
+export function approveHooksCommand(name, { digest = null, version = null }) {
+  return [
+    `lamaste-server plugins approve-hooks ${terminalText(name)}`,
+    ...(digest ? [`--digest ${terminalText(digest)}`] : []),
+    ...(version ? [`--version ${terminalText(version)}`] : []),
+  ].join(' ');
+}
+
+/**
+ * The arguments of `approve-hooks <name>` after the name: `--digest
+ * <sha256>` (the installed version's, or a pending update's) and
+ * `--version <v>` (a pending update's) — at least one; `--version` alone
+ * approves an update that brings neither relay hooks nor an agent half.
+ *
+ * @param {string[]} rest
+ * @returns {{ digest: string | null, version: string | null } | { error: string }}
+ */
+export function parseApproveArgs(rest) {
+  const valueOf = (flag) => {
+    const idx = rest.indexOf(flag);
+    return idx === -1 ? null : (rest[idx + 1] ?? '');
+  };
+  const digest = valueOf('--digest');
+  const version = valueOf('--version');
+  if (digest === null && version === null) return { error: APPROVE_HOOKS_USAGE };
+  if (digest !== null && !DIGEST_RE.test(digest)) return { error: APPROVE_HOOKS_USAGE };
+  if (version !== null && !VERSION_RE.test(version)) return { error: APPROVE_HOOKS_USAGE };
+  return { digest, version };
+}