@lamalibre/create-lamaste 4.2.0 → 4.3.0

package/vendor/serverd/src/lib/relay-hooks.js

@@ -0,0 +1,100 @@
+/**
+ * Calling one relay hook: the runner round trip, validation of the
+ * decision, the effects it asks for, and the runner restart a timeout calls
+ * for. Every pipeline (install, uninstall, request, tunnel state) calls
+ * relay hooks through {@link runRelayHook}.
+ *
+ * What is logged is metadata: plugin, stage, outcome, duration. A failing
+ * request-stage hook's message is never logged — it is plugin text and may
+ * quote the request or response it saw.
+ */
+
+import { SHARED_HOOK_EFFECTS } from '@lamalibre/lamaste/hooks';
+import {
+  callRelayHook,
+  decisionEffects,
+  hookRunnerSocketPath,
+  validateHookDecision,
+} from '@lamalibre/lamaste/server';
+import { performHookEffects } from './hook-effects.js';
+import { hookSocketDir, restartRelayHookRunner } from './plugin-hooks.js';
+
+function isRequestStage(stage) {
+  return stage === 'request:pre-forward' || stage === 'request:post-forward';
+}
+
+/**
+ * @param {{
+ *   plugin: string,
+ *   stage: import('@lamalibre/lamaste/hooks').HookStage,
+ *   call: import('@lamalibre/lamaste/hooks').HookCallTarget,
+ *   input: Record<string, unknown>,
+ *   body?: { bytes: Buffer, contentType: string | null } | null,
+ *   timeoutMs: number,
+ *   effects: ReadonlyArray<string>,
+ *   logger?: import('pino').Logger,
+ * }} params
+ *   `effects` — the effect types the plugin declared (for its own hooks;
+ *   a shared hook uses Lamaste's list).
+ * @returns {Promise<
+ *   | { ok: true, decision: object, body: Buffer | null, bodyIsText: boolean, durationMs: number }
+ *   | { ok: false, kind: string, message: string, durationMs: number }
+ * >}
+ */
+export async function runRelayHook({
+  plugin,
+  stage,
+  call,
+  input,
+  body,
+  timeoutMs,
+  effects,
+  logger,
+}) {
+  const outcome = await callRelayHook(hookRunnerSocketPath(hookSocketDir(), plugin), {
+    plugin,
+    stage,
+    call,
+    input,
+    body: body ?? null,
+    timeoutMs,
+  });
+  const requestStage = isRequestStage(stage);
+  if (!outcome.ok) {
+    if (outcome.kind === 'timeout') void restartRelayHookRunner(plugin, logger);
+    logger?.warn(
+      {
+        plugin,
+        stage,
+        hook: call.kind === 'shared' ? call.name : 'plugin',
+        kind: outcome.kind,
+        durationMs: outcome.durationMs,
+        ...(requestStage ? {} : { error: outcome.message }),
+      },
+      'Relay hook failed',
+    );
+    return {
+      ok: false,
+      kind: outcome.kind,
+      message: requestStage ? '' : outcome.message,
+      durationMs: outcome.durationMs,
+    };
+  }
+  const validated = validateHookDecision(stage, outcome.decision);
+  if (!validated.ok) {
+    logger?.warn(
+      { plugin, stage, error: validated.error },
+      'Relay hook returned an invalid decision',
+    );
+    return { ok: false, kind: 'invalid', message: validated.error, durationMs: outcome.durationMs };
+  }
+  const allowed = new Set(call.kind === 'shared' ? SHARED_HOOK_EFFECTS[call.name] : effects);
+  await performHookEffects(plugin, stage, decisionEffects(validated.decision), allowed, logger);
+  return {
+    ok: true,
+    decision: validated.decision,
+    body: outcome.body,
+    bodyIsText: outcome.bodyIsText,
+    durationMs: outcome.durationMs,
+  };
+}

package/vendor/serverd/src/lib/relay-signing.js

@@ -0,0 +1,43 @@
+/**
+ * The relay's assertion signing key (`<stateDir>/relay-signing-key.json`,
+ * 0600). The panel creates it at startup and signs agent-panel requests
+ * with it, and every app job it gives an agent's root helper
+ * (`agent-jobs.js`); Gatekeeper reads the same file to sign for plugin
+ * tunnels. Agents fetch the public half from `GET /api/agents/me/relay-keys`.
+ * See `relay-assertion.ts` and `app-job-signature.ts` in the core library.
+ */
+
+import path from 'node:path';
+import { createRelaySigner, relayVerifyKeyOf, RELAY_SIGNING_KEY_FILE } from '@lamalibre/lamaste';
+
+const STATE_DIR = process.env.LAMALIBRE_LAMASTE_STATE_DIR || '/etc/lamalibre/lamaste';
+
+export const relaySigner = createRelaySigner(path.join(STATE_DIR, RELAY_SIGNING_KEY_FILE), {
+  create: true,
+});
+
+/**
+ * Create the key if it does not exist yet, so Gatekeeper finds it, and log
+ * its id. A key that exists but cannot be used (permissions, content) is an
+ * error the operator must fix: nothing is signed with it, so the agent-panel
+ * and plugin tunnels are refused until then.
+ *
+ * @param {{ info(o: object, m?: string): void, error(o: object, m?: string): void }} log
+ */
+export async function ensureRelaySigningKey(log) {
+  try {
+    const key = await relaySigner.current();
+    if (key) log.info({ kid: key.kid }, 'Relay assertion signing key ready');
+  } catch (err) {
+    log.error(
+      { err: err instanceof Error ? err.message : String(err) },
+      'Relay assertion signing key unusable — agent panels and plugin tunnels are refused',
+    );
+  }
+}
+
+/** The public keys agents verify relay assertions with (current key only). */
+export async function relayVerifyKeys() {
+  const key = await relaySigner.current();
+  return key ? [relayVerifyKeyOf(key)] : [];
+}

package/vendor/serverd/src/lib/request-hooks.js

@@ -0,0 +1,79 @@
+/**
+ * The panel's request hook runtime for the forwarder
+ * (`createHookedForwarder` in @lamalibre/lamaste/server): which request
+ * hooks a plugin has, how one runs, and the fallback while it is down.
+ *
+ * Only an approved relay hook set runs. A plugin whose installed set is not
+ * the approved one has its forwarded traffic refused (503) — letting it past
+ * hooks that do not run would be a bypass.
+ */
+
+import { findPlugin } from './plugins.js';
+import { installedRelayHooks, installedVersionApproved } from './plugin-hooks.js';
+import { runRelayHook } from './relay-hooks.js';
+import { getStateDb } from './state-db.js';
+
+/** plugin → the fallback its `tunnel:down` hook returned, while it is down. */
+const fallbacks = new Map();
+
+/** plugin → declared effect types of its relay hooks (from the last `hooksFor`). */
+const declaredEffects = new Map();
+
+/** Load the persisted fallbacks (start-up). */
+export async function loadTunnelFallbacks() {
+  const db = await getStateDb();
+  fallbacks.clear();
+  for (const row of db
+    .prepare(
+      'SELECT plugin, tunnel_fallback FROM plugin_hook_sets WHERE tunnel_fallback IS NOT NULL',
+    )
+    .all()) {
+    try {
+      fallbacks.set(row.plugin, JSON.parse(row.tunnel_fallback));
+    } catch {
+      // A malformed row serves no fallback.
+    }
+  }
+}
+
+/** Keep the in-memory fallback in step with the persisted one (tunnel-hooks.js). */
+export function rememberTunnelFallback(plugin, fallback) {
+  if (fallback) fallbacks.set(plugin, fallback);
+  else fallbacks.delete(plugin);
+}
+
+/** @type {import('@lamalibre/lamaste/server').RequestHookRuntime} */
+export const requestHookRuntime = {
+  async hooksFor(plugin) {
+    const entry = await findPlugin(plugin);
+    const relay = entry ? installedRelayHooks(entry) : null;
+    if (!relay) return { hooks: [] };
+    if (!(await installedVersionApproved(entry))) {
+      return {
+        refuse: `The relay hooks of plugin "${plugin}" are not approved — an administrator approves them in the panel`,
+      };
+    }
+    declaredEffects.set(plugin, relay.set.effects);
+    return { hooks: relay.set.request };
+  },
+
+  async run(plugin, hook, input, body) {
+    const result = await runRelayHook({
+      plugin,
+      stage: `request:${hook.stage}`,
+      call: hook.use
+        ? { kind: 'shared', name: hook.use, settings: hook.settings }
+        : { kind: 'app' },
+      input,
+      body,
+      timeoutMs: hook.timeoutMs,
+      effects: declaredEffects.get(plugin) ?? [],
+    });
+    if (!result.ok) return { ok: false };
+    return { ok: true, decision: result.decision, body: result.body };
+  },
+
+  fallbackFor(plugin) {
+    return fallbacks.get(plugin) ?? null;
+  },
+};

package/vendor/serverd/src/lib/retained-data.js

@@ -0,0 +1,99 @@
+/**
+ * Data an agent half leaves on an agent. Removing an agent half without
+ * purge (an unhost, an uninstall, a rolled-back install) keeps its data
+ * directory and service account on the agent, both named after the route;
+ * the relay keeps a record of it so an administrator can purge it later —
+ * after the plugin is gone, too — and so another agent package is never
+ * installed over it.
+ *
+ * One record per agent and route (`retained_agent_data`, migration 0010),
+ * the way the data exists on the agent. A record goes when the data is
+ * purged, or when the same agent package is installed there again and
+ * takes the data back.
+ */
+
+import { APPHOST_PATHS, appServiceUser } from '@lamalibre/lamaste';
+import { getStateDb } from './state-db.js';
+
+/**
+ * A record as the API shows it: what the table keeps, and what a purge
+ * deletes on the agent — the data directory and the account, both derived
+ * from the route — so a panel or CLI confirmation can name them.
+ */
+function rowToRecord(row) {
+  return {
+    agentLabel: row.agent_label,
+    route: row.route,
+    plugin: row.plugin,
+    package: row.package,
+    since: row.since,
+    operation: row.operation,
+    dataDir: APPHOST_PATHS.dataDir(row.route),
+    serviceUser: appServiceUser(row.route),
+  };
+}
+
+/**
+ * Record that agent `agentLabel` keeps the data of route `route`, owned by
+ * agent package `pkg` of plugin `plugin`. A record that exists already keeps
+ * its `since` — the data has been there since then.
+ *
+ * @param {{ agentLabel: string, route: string, plugin: string, package: string, operation?: string | null }} record
+ */
+export async function recordRetainedData({ agentLabel, route, plugin, package: pkg, operation }) {
+  const db = await getStateDb();
+  db.prepare(
+    `INSERT INTO retained_agent_data (agent_label, route, plugin, package, since, operation)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(agent_label, route) DO UPDATE SET
+       plugin = excluded.plugin,
+       package = excluded.package,
+       operation = excluded.operation`,
+  ).run(agentLabel, route, plugin, pkg, new Date().toISOString(), operation ?? null);
+}
+
+/** Drop the record of the data agent `agentLabel` keeps for route `route` (purged, or taken back). */
+export async function forgetRetainedData(agentLabel, route) {
+  const db = await getStateDb();
+  return Number(
+    db
+      .prepare('DELETE FROM retained_agent_data WHERE agent_label = ? AND route = ?')
+      .run(agentLabel, route).changes,
+  );
+}
+
+/** The record for agent `agentLabel` and route `route`, or null. */
+export async function findRetainedData(agentLabel, route) {
+  const db = await getStateDb();
+  const row = db
+    .prepare('SELECT * FROM retained_agent_data WHERE agent_label = ? AND route = ?')
+    .get(agentLabel, route);
+  return row ? rowToRecord(row) : null;
+}
+
+/**
+ * Records, oldest first — all of them, those of plugin `plugin` (by the name
+ * it had; it may be uninstalled), or those on agent `agentLabel`.
+ *
+ * @param {{ plugin?: string, agentLabel?: string }} [filter]
+ */
+export async function listRetainedData({ plugin, agentLabel } = {}) {
+  const db = await getStateDb();
+  const where = [];
+  const args = [];
+  if (plugin) {
+    where.push('plugin = ?');
+    args.push(plugin);
+  }
+  if (agentLabel) {
+    where.push('agent_label = ?');
+    args.push(agentLabel);
+  }
+  return db
+    .prepare(
+      `SELECT * FROM retained_agent_data${where.length ? ` WHERE ${where.join(' AND ')}` : ''}
+       ORDER BY since, agent_label, route`,
+    )
+    .all(...args)
+    .map(rowToRecord);
+}

package/vendor/serverd/src/lib/trust-proxy.js

@@ -0,0 +1,34 @@
+/**
+ * Which proxy hop the panel trusts for a request's client address — the
+ * Fastify `trustProxy` function.
+ *
+ * The panel listens on 127.0.0.1 only; every request reaches it through the
+ * relay's nginx (the panel vhost, the IP-based panel on :9292), which
+ * appends the address it accepted the connection from to
+ * `X-Forwarded-For` (`proxy_set_header X-Forwarded-For
+ * $proxy_add_x_forwarded_for`). The panel trusts exactly that one hop, and
+ * only when it comes from loopback: `request.ip` is then the address nginx
+ * saw — what push-install IP policies, rate limits and logs see — never an
+ * `X-Forwarded-For` entry the client wrote itself (those sit further left),
+ * and never a header from a peer that is not local should the panel ever
+ * listen elsewhere.
+ */
+
+import net from 'node:net';
+
+/** Whether `address` is a loopback address (IPv4 127/8, `::1`, or IPv4-mapped 127/8). */
+export function isLoopbackAddress(address) {
+  if (typeof address !== 'string') return false;
+  const v4 = address.startsWith('::ffff:') ? address.slice(7) : address;
+  if (net.isIPv4(v4)) return v4.split('.')[0] === '127';
+  return net.isIPv6(address) && (address === '::1' || /^(0{1,4}:){7}0{0,3}1$/.test(address));
+}
+
+/**
+ * Fastify / proxy-addr trust function: `hop` 0 is the connection's own peer.
+ * @param {string} address
+ * @param {number} hop
+ */
+export function trustLocalNginxHop(address, hop) {
+  return hop === 0 && isLoopbackAddress(address);
+}

package/vendor/serverd/src/lib/tunnel-hooks.js

@@ -0,0 +1,88 @@
+/**
+ * The tunnel-state pipeline on the relay: when the health monitor sees a
+ * hosted plugin go down (the tunnel, or the application behind it) or come
+ * back, Lamaste runs the plugin's `tunnel:down` / `tunnel:up` relay hook.
+ * What `tunnel:down` returns as `fallback` is what the forwarder answers
+ * while the plugin is down, instead of a bare 502; `tunnel:up` clears it.
+ *
+ * `tunnel:up` runs only after a `down` — not when a hosting is first seen
+ * up, or after a restart of the panel. The agent side of the pipeline runs
+ * on the agent (its sync follows the relay's view of the tunnel).
+ *
+ * Calls for one plugin are serialised and run beside the monitor, which
+ * does not wait for them.
+ */
+
+import { findPlugin } from './plugins.js';
+import {
+  installedRelayHooks,
+  installedVersionApproved,
+  setTunnelFallback,
+} from './plugin-hooks.js';
+import { runRelayHook } from './relay-hooks.js';
+import { rememberTunnelFallback } from './request-hooks.js';
+
+const chains = new Map();
+
+/**
+ * React to a persisted health transition of `plugin` (`before` → `after`).
+ * Never throws; failures are logged.
+ */
+export function onHealthTransition(plugin, before, after, logger) {
+  const previous = chains.get(plugin) ?? Promise.resolve();
+  const next = previous
+    .then(() => runTunnelHook(plugin, before, after, logger))
+    .catch((err) => {
+      logger?.error({ plugin, err: err?.message }, 'Tunnel-state hook pipeline failed');
+    });
+  chains.set(plugin, next);
+  next.finally(() => {
+    if (chains.get(plugin) === next) chains.delete(plugin);
+  });
+  return next;
+}
+
+async function runTunnelHook(plugin, before, after, logger) {
+  let stage;
+  if (after.state === 'down') stage = 'tunnel:down';
+  else if (after.state === 'up' && before?.state === 'down') stage = 'tunnel:up';
+  else return;
+
+  const entry = await findPlugin(plugin);
+  const relay = entry ? installedRelayHooks(entry) : null;
+  const decl = relay?.set.stages.find((s) => s.stage === stage) ?? null;
+  if (stage === 'tunnel:up') {
+    // Whatever happens next, the plugin is up: no fallback.
+    await setTunnelFallback(plugin, null);
+    rememberTunnelFallback(plugin, null);
+  }
+  if (!decl) return;
+  if (!(await installedVersionApproved(entry))) return;
+
+  const result = await runRelayHook({
+    plugin,
+    stage,
+    call: { kind: 'app' },
+    input: {
+      state: after.state,
+      ...(after.reason ? { reason: after.reason } : {}),
+      since: after.since,
+      ...(after.lastError ? { lastError: after.lastError.slice(0, 300) } : {}),
+    },
+    timeoutMs: decl.timeoutMs,
+    effects: relay.set.effects,
+    logger,
+  });
+  if (!result.ok) return;
+  if (stage === 'tunnel:down') {
+    const fallback = result.decision.fallback ?? null;
+    await setTunnelFallback(plugin, fallback);
+    rememberTunnelFallback(plugin, fallback);
+    logger?.info(
+      { plugin, reason: after.reason, fallback: fallback !== null },
+      'Ran tunnel:down hook',
+    );
+  } else {
+    logger?.info({ plugin }, 'Ran tunnel:up hook');
+  }
+}