@lamalibre/create-lamaste 4.3.0 → 4.3.1

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

@@ -4,35 +4,157 @@
  * Used by tunnel/site commands that need the full dependency stack
  * (nginx, certbot, chisel) which lives in the running panel server.
  * Authenticates via the admin mTLS client certificate.
+ *
+ * The panel is verified before anything is sent: the CLI talks to nginx's IP
+ * vhost on loopback only when it should be listening, and checks it presents
+ * the panel's own certificate, read from disk (see `panel-identity.js`) —
+ * port 9292 is one any local user could listen on when nginx does not.
+ *
+ * Nothing secret is ever an argument of curl: other local users can read a
+ * process's command line (`ps`, `/proc/<pid>/cmdline`). The P12 password is
+ * in a private `-K` config file, and a request body — which can carry a
+ * credential, such as the token of `registry-credential set --token-stdin`
+ * — reaches curl on stdin.
  */
 
-import { readFile, writeFile, unlink } from 'node:fs/promises';
-import crypto from 'node:crypto';
+import { rmSync } from 'node:fs';
+import { mkdtemp, open, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { execa } from 'execa';
-import { PKI_DIR } from './config.js';
+import { PKI_DIR, readConfig } from './config.js';
+import { PANEL_LOOPBACK, assertPanelListener, readPanelIdentity } from './panel-identity.js';
 
-const PANEL_URL = 'https://127.0.0.1:9292';
+/**
+ * TLS 1.2 cipher suites the CLI offers: forward-secret ones only. With RSA
+ * key exchange a client sends its certificate before the server has proved
+ * it holds the key of the certificate it presented — and the panel's
+ * certificate is public — so a listener on the panel's port could collect
+ * the admin client certificate from the handshake. With ECDHE (and with
+ * TLS 1.3) the server signs first, and an impostor fails before the client
+ * presents anything. nginx's `HIGH` list offers these suites.
+ */
+const FORWARD_SECRET_CIPHERS = 'ECDHE+AESGCM:ECDHE+CHACHA20';
+
+/** The signals that remove a request's private curl config before the CLI dies. */
+const CLEANUP_SIGNALS = ['SIGINT', 'SIGTERM'];
 
 /**
- * The curl argument vector for one panel request. Pure, exported for tests.
+ * One curl config directive, `name = "value"`, with backslashes and double
+ * quotes escaped for curl's quoted values. A value holding a line break or
+ * NUL is refused: curl reads its config line by line, so a line break would
+ * start a directive of the value's choosing. The error never repeats the
+ * value. Pure, exported for tests.
+ *
+ * @param {string} name
+ * @param {string} value
+ * @returns {string}
+ */
+export function curlConfigLine(name, value) {
+  if (/[\r\n\0]/.test(value)) {
+    throw new Error(`The curl config value of "${name}" contains a line break or NUL`);
+  }
+  return `${name} = "${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"\n`;
+}
+
+/**
+ * Run `fn` with the path of a curl config file holding `content`. The file
+ * is created exclusively (`wx`, 0600) in a fresh private directory
+ * (`mkdtemp`, 0700): the CLI runs as root and the shared temporary
+ * directory belongs to every local user, none of whom may read the file or
+ * put a file or a link at its path first. The directory is removed on every
+ * path — also when the CLI is interrupted (Ctrl-C) or terminated while the
+ * request runs: SIGINT and SIGTERM handlers, installed for exactly that long,
+ * remove it and then let the signal end the process as it would have
+ * (status 130 / 143 to the shell). The CLI has no other use for them.
+ *
+ * @template T
+ * @param {string} content
+ * @param {(configPath: string) => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+export async function withCurlConfig(content, fn) {
+  /** @type {string | undefined} */
+  let dir;
+  const onSignal = (signal) => {
+    if (dir !== undefined) {
+      try {
+        rmSync(dir, { recursive: true, force: true });
+      } catch {
+        // Nothing more can be done on the way out.
+      }
+    }
+    for (const sig of CLEANUP_SIGNALS) process.off(sig, onSignal);
+    // Without listeners the signal's default action applies again: re-raised,
+    // it ends the process. (A listener still installed — execa's, killing
+    // curl — re-raises it in turn once it is the last one.)
+    process.kill(process.pid, signal);
+  };
+  for (const sig of CLEANUP_SIGNALS) process.on(sig, onSignal);
+  try {
+    dir = await mkdtemp(join(tmpdir(), 'lamalibre-lamaste-curl-'));
+    const configPath = join(dir, 'curl.conf');
+    const fh = await open(configPath, 'wx', 0o600);
+    try {
+      await fh.writeFile(content, 'utf-8');
+    } finally {
+      await fh.close();
+    }
+    return await fn(configPath);
+  } finally {
+    for (const sig of CLEANUP_SIGNALS) process.off(sig, onSignal);
+    if (dir !== undefined) await rm(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The curl invocation for one panel request: its argument vector, and the
+ * JSON body curl reads on stdin (`--data-binary @-`; `undefined` without a
+ * body). The body is never an argument. Pure, exported for tests.
+ *
+ * The panel is verified as `identity` says (`readPanelIdentity`): curl
+ * trusts nothing but its certificate (`--cacert`), checks it is issued for
+ * the address in the request's URL, and connects to that address on
+ * loopback (`--connect-to`) — the certificate names the server's public
+ * address, and the CLI never leaves the machine. curl reads no `.curlrc`
+ * (`-q`, which must come first), which could switch verification off, and
+ * uses no proxy. Never `-k`.
  *
  * The JSON content type and the body travel together: a `Content-Type:
  * application/json` header on a body-less DELETE made Fastify answer 400
  * ("Body cannot be empty when content-type is set"), so `registry-credential
  * clear`, `tunnels delete` and `sites delete` never reached their routes.
  *
- * @param {{ method: string, path: string, body?: Record<string, unknown> | null, p12Path: string, configPath: string }} request
- * @returns {string[]}
+ * @param {{ identity: { certPath: string, address: string, port: number }, method: string, path: string, body?: Record<string, unknown> | null, p12Path: string, configPath: string }} request
+ * @returns {{ args: string[], input: string | undefined }}
  */
-export function buildPanelCurlArgs({ method, path, body = null, p12Path, configPath }) {
+export function buildPanelCurlRequest({
+  identity,
+  method,
+  path,
+  body = null,
+  p12Path,
+  configPath,
+}) {
+  const { certPath, address, port } = identity;
   const args = [
+    '-q', // No .curlrc — it must be the first argument
     '-K',
     configPath,
     '--cert-type',
     'P12',
     '--cert',
     p12Path,
-    '-k', // Server uses self-signed cert on localhost
+    '--cacert',
+    certPath,
+    '--connect-to',
+    `${address}:${port}:${PANEL_LOOPBACK}:${port}`,
+    '--ciphers',
+    FORWARD_SECRET_CIPHERS,
+    '--proto',
+    '=https',
+    '--noproxy',
+    '*',
     '-s', // Silent
     '-S', // Show errors
     '-X',
@@ -40,13 +162,66 @@ export function buildPanelCurlArgs({ method, path, body = null, p12Path, configP
     '-H',
     'Accept: application/json',
   ];
+  let input;
   if (body !== null && body !== undefined) {
-    args.push('-H', 'Content-Type: application/json', '-d', JSON.stringify(body));
+    args.push('-H', 'Content-Type: application/json', '--data-binary', '@-');
+    input = JSON.stringify(body);
   }
   // Append the HTTP status on its own line so an error response is not
   // mistaken for a result — the panel answers errors with a JSON body.
-  args.push('-w', '\n%{http_code}', `${PANEL_URL}${path}`);
-  return args;
+  args.push('-w', '\n%{http_code}', `https://${address}:${port}${path}`);
+  return { args, input };
+}
+
+/**
+ * The error for a curl run that did not complete, saying what went wrong in
+ * the panel's terms: curl's own last line, never its command line. Pure,
+ * exported for tests.
+ *
+ * @param {{ exitCode?: number, stderr?: string, timedOut?: boolean, code?: string }} failure
+ * @param {{ certPath: string, port: number }} identity
+ * @param {{ p12Path: string, timeoutMs: number }} request
+ * @returns {Error}
+ */
+export function curlFailure(failure, identity, { p12Path, timeoutMs }) {
+  const reason =
+    String(failure.stderr ?? '')
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .pop() ?? '';
+  const listener = `${PANEL_LOOPBACK}:${identity.port}`;
+  let message;
+  if (failure.timedOut) {
+    message = `The panel did not answer within ${Math.round(timeoutMs / 1000)} s`;
+  } else if (failure.code === 'ENOENT') {
+    message = 'curl is not installed';
+  } else {
+    switch (failure.exitCode) {
+      case 7:
+        message = `Nothing listens on ${listener} — is nginx running? (systemctl status nginx)`;
+        break;
+      // The TLS handshake failed: certificate not trusted, issued for another
+      // address, another key — or no suite in common with an impostor.
+      case 35:
+      case 51:
+      case 60:
+      case 90:
+        message =
+          `The listener on ${listener} did not prove it is the panel: it must present ` +
+          `${identity.certPath}. Nothing was sent to it. If the certificate was regenerated, ` +
+          `reload nginx (systemctl reload nginx).`;
+        break;
+      case 58:
+        message = `curl could not use the admin client certificate ${p12Path}`;
+        break;
+      default:
+        message = `curl failed${failure.exitCode === undefined ? '' : ` (exit ${failure.exitCode})`}`;
+    }
+  }
+  const err = new Error(reason ? `${message} (${reason})` : message);
+  if (typeof failure.exitCode === 'number') err.curlExitCode = failure.exitCode;
+  return err;
 }
 
 /**
@@ -113,14 +288,57 @@ export function parsePanelResponse(stdout, method, path) {
   return parsed;
 }
 
+/**
+ * Send one request to the panel with curl: the panel verified as
+ * `identity` says, the client certificate, its password in a private `-K`
+ * config file, and the body on stdin. Resolves and rejects as
+ * `panelRequest` does. `identity` is `readPanelIdentity()`'s (tests
+ * describe a local server).
+ *
+ * @param {{ identity: { certPath: string, address: string, port: number }, method: string, path: string, body?: Record<string, unknown> | null, p12Path: string, p12Password: string, timeoutMs?: number }} request
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export async function curlPanelRequest({
+  identity,
+  method,
+  path,
+  body = null,
+  p12Path,
+  p12Password,
+  timeoutMs = 30000,
+}) {
+  return withCurlConfig(curlConfigLine('pass', p12Password), async (configPath) => {
+    const { args, input } = buildPanelCurlRequest({
+      identity,
+      method,
+      path,
+      body,
+      p12Path,
+      configPath,
+    });
+    const result = await execa('curl', args, {
+      timeout: timeoutMs,
+      reject: false,
+      ...(input === undefined ? {} : { input }),
+    });
+    if (result.failed) {
+      throw curlFailure(result, identity, { p12Path, timeoutMs });
+    }
+    return parsePanelResponse(result.stdout, method, path);
+  });
+}
+
 /**
  * Make an authenticated API request to the local panel server.
  *
- * Uses curl with the admin client certificate (mTLS) and a temporary
- * config file for the P12 password (never in process args). Resolves with
- * the JSON body; rejects with an Error (`statusCode`, the panel's `error`
- * in the message, a refusal's `code`, `reasons` and `operationId`) for any
- * non-2xx answer.
+ * Refuses before connecting when nginx does not listen on the panel's port
+ * (panel 2FA on, IP vhost off), and verifies the listener against the
+ * panel's certificate (see the top of this file). Uses curl with the admin
+ * client certificate (mTLS); neither the P12 password nor the body is ever
+ * in curl's arguments. Resolves with the JSON body; rejects with an Error
+ * (`statusCode`, the panel's `error` in the message, a refusal's `code`,
+ * `reasons` and `operationId`) for any non-2xx answer, and with one that
+ * says why when the request could not be made.
  *
  * @param {string} method
  * @param {string} path  e.g. '/api/tunnels'
@@ -130,6 +348,17 @@ export function parsePanelResponse(stdout, method, path) {
  * @returns {Promise<Record<string, unknown>>}
  */
 export async function panelRequest(method, path, body = null, { timeoutMs = 30000 } = {}) {
+  let config;
+  try {
+    config = await readConfig();
+  } catch {
+    throw new Error(
+      'Cannot read panel.json. Ensure the server is properly installed and /etc/lamalibre/lamaste/panel.json exists.',
+    );
+  }
+  await assertPanelListener(config);
+  const identity = await readPanelIdentity();
+
   const p12Path = `${PKI_DIR}/client.p12`;
 
   // Read p12 password from the stored file
@@ -142,19 +371,5 @@ export async function panelRequest(method, path, body = null, { timeoutMs = 3000
     );
   }
 
-  // Write password to a temporary config file (never in process args)
-  const tmpConfigPath = `/tmp/lamalibre-lamaste-curl-${crypto.randomBytes(8).toString('hex')}`;
-  try {
-    await writeFile(tmpConfigPath, `--pass "${p12Password}"\n`, { mode: 0o600 });
-
-    const { stdout } = await execa(
-      'curl',
-      buildPanelCurlArgs({ method, path, body, p12Path, configPath: tmpConfigPath }),
-      { timeout: timeoutMs },
-    );
-
-    return parsePanelResponse(stdout, method, path);
-  } finally {
-    await unlink(tmpConfigPath).catch(() => {});
-  }
+  return curlPanelRequest({ identity, method, path, body, p12Path, p12Password, timeoutMs });
 }

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);
+}