@lamalibre/create-lamaste 4.0.0

package/src/lib/accounts.js

@@ -0,0 +1,86 @@
+import { execa } from 'execa';
+import { AUTHELIA_USER, CHISEL_GROUP } from './service-config.js';
+
+/**
+ * Service accounts create-lamaste manages. All functions are idempotent and
+ * run as root.
+ */
+
+async function groupExists(name) {
+  try {
+    await execa('getent', ['group', name]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function userExists(name) {
+  try {
+    await execa('getent', ['passwd', name]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create the group the chisel server runs as and add the lamaste user to it.
+ * Run after the lamaste user exists and before the panel service (re)starts —
+ * the service unit names the group in SupplementaryGroups=, and the panel
+ * writes the chisel authfile and key with it.
+ *
+ * @returns {Promise<{ created: boolean }>}
+ */
+export async function ensureChiselGroup() {
+  let created = false;
+  if (!(await groupExists(CHISEL_GROUP))) {
+    await execa('groupadd', ['--system', CHISEL_GROUP]);
+    created = true;
+  }
+  await execa('usermod', ['--append', '--groups', CHISEL_GROUP, 'lamaste']);
+  return { created };
+}
+
+/**
+ * Create the system account Authelia runs as. Authelia is reachable from
+ * the internet (auth.<domain>), so it runs as neither root nor lamaste: it
+ * can read its configuration (group lamaste-authelia) and write only its
+ * database, notification file and log.
+ *
+ * @returns {Promise<{ created: boolean }>}
+ */
+export async function ensureAutheliaUser() {
+  if (await userExists(AUTHELIA_USER)) return { created: false };
+  if (!(await groupExists(AUTHELIA_USER))) {
+    await execa('groupadd', ['--system', AUTHELIA_USER]);
+  }
+  await execa('useradd', [
+    '--system',
+    '--gid',
+    AUTHELIA_USER,
+    '--no-create-home',
+    '--home-dir',
+    '/nonexistent',
+    '--shell',
+    '/usr/sbin/nologin',
+    '--comment',
+    'Lamaste Authelia',
+    AUTHELIA_USER,
+  ]);
+  return { created: true };
+}
+
+/**
+ * Numeric uid/gid of a user (primary group) or of a group.
+ *
+ * @param {'user'|'group'} kind
+ * @param {string} name
+ * @returns {Promise<number>}
+ */
+export async function lookupId(kind, name) {
+  const { stdout } = await execa('getent', [kind === 'user' ? 'passwd' : 'group', name]);
+  const id = Number.parseInt(stdout.split(':')[2] ?? '', 10);
+  if (!Number.isInteger(id)) throw new Error(`Cannot resolve ${kind} ${name}`);
+  return id;
+}

package/src/lib/binaries.js

@@ -0,0 +1,137 @@
+import { execa } from 'execa';
+import { mkdtemp, rename, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  AUTHELIA_RELEASE,
+  CHISEL_RELEASE,
+  curlDownloadArgs,
+  downloadVerifiedAuthelia,
+  downloadVerifiedChisel,
+  isPinnedChiselVersion,
+  normaliseAutheliaVersion,
+} from '@lamalibre/lamaste';
+import { AUTHELIA_BIN, CHISEL_BIN } from './service-config.js';
+
+/**
+ * Install the pinned chisel and Authelia releases under /usr/local/bin.
+ *
+ * Downloads are verified against the SHA-256 digests pinned in
+ * @lamalibre/lamaste before anything is unpacked, staged in a root-private
+ * temporary directory, and moved into place with a rename, so a running
+ * service never sees a half-written binary. Runs as root; the panel never
+ * installs a binary.
+ */
+
+const CHISEL_ARCH = { x64: 'linux_amd64', arm64: 'linux_arm64' };
+const AUTHELIA_ARCH = { x64: 'linux-amd64', arm64: 'linux-arm64' };
+
+function archFor(table, what) {
+  const arch = table[process.arch];
+  if (!arch) throw new Error(`Unsupported architecture for ${what}: ${process.arch}`);
+  return arch;
+}
+
+async function fetchToFile(url, outPath) {
+  await execa('curl', curlDownloadArgs(url, outPath));
+}
+
+/** Put `src` at `dest` as a root-owned 0755 executable, atomically. */
+async function installExecutable(src, dest) {
+  const staged = `${dest}.lamaste-new`;
+  await execa('install', ['-o', 'root', '-g', 'root', '-m', '0755', src, staged]);
+  await rename(staged, dest);
+}
+
+async function versionOutput(bin, args) {
+  if (!existsSync(bin)) return null;
+  try {
+    const { stdout, stderr } = await execa(bin, args, { timeout: 15_000 });
+    return (stdout || stderr || '').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Install the pinned chisel release unless it is already installed.
+ *
+ * @returns {Promise<{ changed: boolean, version: string, previous: string | null }>}
+ */
+export async function installPinnedChisel() {
+  const previous = await versionOutput(CHISEL_BIN, ['--version']);
+  if (isPinnedChiselVersion(previous)) {
+    return { changed: false, version: CHISEL_RELEASE.version, previous };
+  }
+  const work = await mkdtemp(join(tmpdir(), 'lamaste-chisel-'));
+  try {
+    const bin = join(work, 'chisel');
+    await downloadVerifiedChisel(
+      archFor(CHISEL_ARCH, 'chisel'),
+      join(work, 'chisel.gz'),
+      bin,
+      fetchToFile,
+    );
+    await installExecutable(bin, CHISEL_BIN);
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+  const installed = await versionOutput(CHISEL_BIN, ['--version']);
+  if (!isPinnedChiselVersion(installed)) {
+    throw new Error(
+      `chisel was installed but reports ${installed ?? 'nothing'}, expected ${CHISEL_RELEASE.version}`,
+    );
+  }
+  return { changed: true, version: CHISEL_RELEASE.version, previous };
+}
+
+function compareVersions(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
+/**
+ * Install the pinned Authelia release unless it (or a newer release) is
+ * already installed. A newer Authelia is kept: its database may already use
+ * a schema the pinned release cannot read, and Authelia refuses to start on
+ * a database newer than itself.
+ *
+ * @returns {Promise<{ changed: boolean, version: string, previous: string | null, keptNewer: boolean }>}
+ */
+export async function installPinnedAuthelia() {
+  const previousOutput = await versionOutput(AUTHELIA_BIN, ['--version']);
+  const previous = previousOutput ? normaliseAutheliaVersion(previousOutput) : null;
+  if (previous !== null && compareVersions(previous, AUTHELIA_RELEASE.version) >= 0) {
+    return {
+      changed: false,
+      version: previous,
+      previous,
+      keptNewer: previous !== AUTHELIA_RELEASE.version,
+    };
+  }
+  const work = await mkdtemp(join(tmpdir(), 'lamaste-authelia-'));
+  try {
+    const tgz = join(work, 'authelia.tar.gz');
+    await downloadVerifiedAuthelia(archFor(AUTHELIA_ARCH, 'Authelia'), tgz, fetchToFile);
+    // The tarball holds the binary at its top level, named `authelia`, next
+    // to upstream packaging files (units, sysusers, a config template).
+    await execa('tar', ['-xzf', tgz, '-C', work, '--no-same-owner', 'authelia']);
+    await installExecutable(join(work, 'authelia'), AUTHELIA_BIN);
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+  const installedOutput = await versionOutput(AUTHELIA_BIN, ['--version']);
+  const installed = installedOutput ? normaliseAutheliaVersion(installedOutput) : null;
+  if (installed !== AUTHELIA_RELEASE.version) {
+    throw new Error(
+      `Authelia was installed but reports ${installed ?? 'nothing'}, expected ${AUTHELIA_RELEASE.version}`,
+    );
+  }
+  return { changed: true, version: AUTHELIA_RELEASE.version, previous, keptNewer: false };
+}

package/src/lib/cert-help-page.js

@@ -0,0 +1,160 @@
+/**
+ * Generates the static HTML page shown when a browser visits without a client certificate.
+ * nginx serves this via error_page 495/496 so the user sees helpful instructions
+ * instead of a raw "400 Bad Request".
+ *
+ * @param {{ ip: string, pkiDir: string }} ctx - Installer context with IP and PKI path.
+ * @returns {string} Complete HTML document.
+ */
+export function generateCertHelpPage(ctx) {
+  const ip = ctx.ip;
+  const scpCmd = `scp root@${ip}:${ctx.pkiDir}/client.p12 .`;
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Lamaste — Certificate Required</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+      background: #09090b; color: #a1a1aa;
+      min-height: 100vh; display: flex; align-items: center; justify-content: center;
+      padding: 1.5rem;
+    }
+    .card {
+      background: #18181b; border: 1px solid #27272a; border-radius: 0.75rem;
+      max-width: 640px; width: 100%; padding: 2.5rem;
+    }
+    .icon { text-align: center; font-size: 3rem; margin-bottom: 1rem; }
+    h1 { color: #f4f4f5; font-size: 1.25rem; text-align: center; margin-bottom: 0.5rem; }
+    .subtitle { text-align: center; margin-bottom: 2rem; font-size: 0.875rem; }
+    .step { margin-bottom: 1.75rem; }
+    .step-header {
+      display: flex; align-items: center; gap: 0.625rem;
+      margin-bottom: 0.625rem;
+    }
+    .step-num {
+      background: #22d3ee; color: #09090b; font-weight: 700;
+      width: 1.5rem; height: 1.5rem; border-radius: 50%;
+      display: flex; align-items: center; justify-content: center;
+      font-size: 0.75rem; flex-shrink: 0;
+    }
+    .step-title { color: #e4e4e7; font-size: 0.9375rem; font-weight: 600; }
+    .step-body { margin-left: 2.125rem; font-size: 0.8125rem; line-height: 1.6; }
+    code {
+      background: #09090b; border: 1px solid #27272a; border-radius: 0.375rem;
+      padding: 0.625rem 0.875rem; display: block; margin: 0.5rem 0;
+      color: #22d3ee; font-size: 0.8125rem; word-break: break-all;
+      cursor: pointer; position: relative;
+    }
+    code:hover { border-color: #22d3ee; }
+    code::after {
+      content: 'click to copy'; position: absolute; right: 0.625rem; top: 50%;
+      transform: translateY(-50%); color: #52525b; font-size: 0.6875rem;
+    }
+    code.copied::after { content: 'copied!'; color: #22d3ee; }
+    .platform { margin-bottom: 0.375rem; }
+    .platform strong { color: #e4e4e7; }
+    .note {
+      background: #1c1917; border: 1px solid #422006; border-radius: 0.5rem;
+      padding: 0.875rem 1rem; margin-top: 1.5rem; font-size: 0.8125rem;
+      line-height: 1.5;
+    }
+    .note strong { color: #fbbf24; }
+    .refresh {
+      display: block; width: 100%; margin-top: 1.5rem;
+      background: #22d3ee; color: #09090b; font-weight: 700;
+      border: none; border-radius: 0.5rem; padding: 0.75rem;
+      font-size: 0.875rem; cursor: pointer; font-family: inherit;
+    }
+    .refresh:hover { background: #06b6d4; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <div class="icon">\u{1f510}</div>
+    <h1>Client Certificate Required</h1>
+    <p class="subtitle">
+      This Lamaste panel is protected by mTLS.<br>
+      Import your client certificate to continue.
+    </p>
+
+    <div class="step">
+      <div class="step-header">
+        <span class="step-num">1</span>
+        <span class="step-title">Download your certificate</span>
+      </div>
+      <div class="step-body">
+        Run this on your local machine:
+        <code id="scp-cmd">${escapeHtml(scpCmd)}</code>
+      </div>
+    </div>
+
+    <div class="step">
+      <div class="step-header">
+        <span class="step-num">2</span>
+        <span class="step-title">Import into your browser</span>
+      </div>
+      <div class="step-body">
+        <div class="platform">
+          <strong>macOS:</strong> Double-click <code style="display:inline;padding:0.125rem 0.375rem;cursor:default" class="no-copy">client.p12</code>
+          &rarr; Keychain Access opens &rarr; <strong style="color:#e4e4e7">select &ldquo;System&rdquo; keychain</strong> (not &ldquo;login&rdquo;)
+          &rarr; enter the password from the installer output &rarr; authenticate with your Mac password.
+          If you see an &ldquo;Unable to import&rdquo; error for Local Items, ignore it &mdash; the System import succeeds.
+          Then find the certificate in the <strong style="color:#e4e4e7">System</strong> keychain &rarr;
+          double-click it &rarr; expand <strong style="color:#e4e4e7">Trust</strong> &rarr; set to <strong style="color:#e4e4e7">Always Trust</strong> &rarr; close and authenticate.
+        </div>
+        <div class="platform">
+          <strong>Linux (Chrome):</strong> Settings &rarr; Privacy &amp; Security &rarr; Security &rarr; Manage certificates &rarr; Import
+        </div>
+        <div class="platform">
+          <strong>Windows:</strong> Double-click the file &rarr; Certificate Import Wizard &rarr; enter the password
+        </div>
+      </div>
+    </div>
+
+    <div class="step">
+      <div class="step-header">
+        <span class="step-num">3</span>
+        <span class="step-title">Reload this page</span>
+      </div>
+      <div class="step-body">
+        After importing, your browser will present the certificate automatically.
+        You may need to restart your browser first.
+      </div>
+    </div>
+
+    <div class="note">
+      <strong>Where is the password?</strong> The certificate password was printed
+      in your terminal when the installer finished. It is also stored on the server
+      at <code style="display:inline;padding:0.125rem 0.375rem;color:#fbbf24;cursor:default" class="no-copy">${escapeHtml(ctx.pkiDir)}/.p12-password</code>
+    </div>
+
+    <button class="refresh" onclick="location.reload()">
+      Reload Page
+    </button>
+  </div>
+
+  <script>
+    document.querySelectorAll('code:not(.no-copy)').forEach(function(el) {
+      el.addEventListener('click', function() {
+        navigator.clipboard.writeText(el.textContent.trim());
+        el.classList.add('copied');
+        setTimeout(function() { el.classList.remove('copied'); }, 2000);
+      });
+    });
+  </script>
+</body>
+</html>`;
+}
+
+function escapeHtml(str) {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}

package/src/lib/env.js

@@ -0,0 +1,132 @@
+import { readFile } from 'node:fs/promises';
+import { execa } from 'execa';
+
+/**
+ * Parse /etc/os-release and validate that we are on Ubuntu 24.04.
+ * @returns {{ id: string, versionId: string, prettyName: string }}
+ */
+export async function detectOS() {
+  let content;
+  try {
+    content = await readFile('/etc/os-release', 'utf8');
+  } catch {
+    throw new Error('Could not read /etc/os-release. Lamaste requires Ubuntu 24.04.');
+  }
+
+  const fields = {};
+  for (const line of content.split('\n')) {
+    const match = line.match(/^(\w+)=(.*)$/);
+    if (match) {
+      // Strip surrounding quotes if present
+      fields[match[1]] = match[2].replace(/^"|"$/g, '');
+    }
+  }
+
+  const id = fields.ID || '';
+  const versionId = fields.VERSION_ID || '';
+  const prettyName = fields.PRETTY_NAME || `${id} ${versionId}`;
+
+  if (id !== 'ubuntu' || !versionId.startsWith('24.04')) {
+    throw new Error(`Lamaste requires Ubuntu 24.04. Detected: ${prettyName}`);
+  }
+
+  return { id, versionId, prettyName };
+}
+
+/**
+ * Detect the public IP address of this machine.
+ * Tries the DigitalOcean metadata API first, falls back to hostname -I.
+ * When allowPrivate is true (--dev mode), accepts RFC 1918 addresses.
+ * @param {{ allowPrivate?: boolean }} options
+ * @returns {string} The IPv4 address.
+ */
+export async function detectIP({ allowPrivate = false } = {}) {
+  const isAcceptable = (ip) => (allowPrivate ? isValidIPv4(ip) : isPublicIP(ip));
+
+  // Try DigitalOcean metadata API first
+  try {
+    const { stdout } = await execa('curl', [
+      '-s',
+      '--max-time',
+      '2',
+      'http://169.254.169.254/metadata/v1/interfaces/public/0/ipv4/address',
+    ]);
+    const ip = stdout.trim();
+    if (ip && isAcceptable(ip)) {
+      return ip;
+    }
+  } catch {
+    // Metadata API not available, fall back
+  }
+
+  // Fallback: hostname -I
+  try {
+    const { stdout } = await execa('hostname', ['-I']);
+    const addresses = stdout.trim().split(/\s+/);
+    for (const addr of addresses) {
+      if (isAcceptable(addr)) {
+        return addr;
+      }
+    }
+  } catch {
+    // hostname -I failed
+  }
+
+  throw new Error(
+    'Could not detect a public IP address. Lamaste must be installed on a server with a public IP.',
+  );
+}
+
+/**
+ * Check whether the given string is a valid IPv4 address (any routable address, not loopback/link-local).
+ * @param {string} ip
+ * @returns {boolean}
+ */
+function isValidIPv4(ip) {
+  const parts = ip.split('.');
+  if (parts.length !== 4) return false;
+
+  const octets = parts.map(Number);
+  if (octets.some((o) => Number.isNaN(o) || o < 0 || o > 255)) return false;
+
+  const [a, b] = octets;
+
+  // Reject loopback, link-local, and 0.0.0.0
+  if (a === 127) return false;
+  if (a === 169 && b === 254) return false;
+  if (octets.every((o) => o === 0)) return false;
+
+  return true;
+}
+
+/**
+ * Check whether the given IPv4 address is public (not RFC 1918 / loopback / link-local).
+ * @param {string} ip
+ * @returns {boolean}
+ */
+function isPublicIP(ip) {
+  if (!isValidIPv4(ip)) return false;
+
+  const [a, b] = ip.split('.').map(Number);
+
+  // 10.0.0.0/8
+  if (a === 10) return false;
+  // 172.16.0.0/12
+  if (a === 172 && b >= 16 && b <= 31) return false;
+  // 192.168.0.0/16
+  if (a === 192 && b === 168) return false;
+
+  return true;
+}
+
+/**
+ * Verify the process is running as root.
+ * @throws {Error} if not root
+ */
+export function checkRoot() {
+  if (process.getuid() !== 0) {
+    throw new Error(
+      'Lamaste installer must be run as root. Try: sudo npx @lamalibre/create-lamaste',
+    );
+  }
+}

package/src/lib/http-redirect.js

@@ -0,0 +1,38 @@
+import { execa } from 'execa';
+import { readFile, rm, symlink, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { HTTP_REDIRECT_SITE, generateHttpRedirectVhost } from './service-config.js';
+
+const AVAILABLE = `/etc/nginx/sites-available/${HTTP_REDIRECT_SITE}`;
+const ENABLED = `/etc/nginx/sites-enabled/${HTTP_REDIRECT_SITE}`;
+
+/**
+ * Install or refresh the port-80 → HTTPS redirect site, test nginx, and
+ * reload it. Idempotent. Run as root. On a failed `nginx -t` the previous
+ * state is restored and the error is thrown.
+ *
+ * @param {{ reload?: boolean }} [options] - reload nginx afterwards (default true)
+ * @returns {Promise<{ changed: boolean }>}
+ */
+export async function ensureHttpRedirect({ reload = true } = {}) {
+  const content = generateHttpRedirectVhost();
+  const previous = existsSync(AVAILABLE) ? await readFile(AVAILABLE, 'utf8') : null;
+  const wasEnabled = existsSync(ENABLED);
+  if (previous === content && wasEnabled) return { changed: false };
+
+  await writeFile(AVAILABLE, content, { mode: 0o644 });
+  if (!wasEnabled) await symlink(AVAILABLE, ENABLED);
+
+  try {
+    await execa('nginx', ['-t']);
+  } catch (err) {
+    if (previous === null) await rm(AVAILABLE, { force: true });
+    else await writeFile(AVAILABLE, previous, { mode: 0o644 });
+    if (!wasEnabled) await rm(ENABLED, { force: true });
+    throw new Error(
+      `nginx rejected the HTTP → HTTPS redirect site; left as it was:\n${err.stderr || err.message}`,
+    );
+  }
+  if (reload) await execa('systemctl', ['reload', 'nginx']);
+  return { changed: true };
+}