@lamalibre/create-lamaste 4.2.0 → 4.3.0

package/vendor/serverd/src/lib/migrations/state/0006_plugin_agent.sql

@@ -0,0 +1,4 @@
+-- The `agent` block of an agent-hosted plugin's manifest (4.3): present
+-- when the plugin has an agent half Lamaste connects to. JSON text; NULL for
+-- server plugins and identity-only agent-hosted plugins.
+ALTER TABLE plugins ADD COLUMN agent TEXT;

package/vendor/serverd/src/lib/migrations/state/0007_audit_and_notifications.sql

@@ -0,0 +1,29 @@
+-- Lamaste's audit log and panel notifications (4.3, slice 2b).
+--
+-- audit_events: append-only record of administrative decisions and of what
+-- plugins' lifecycle hooks report through the `audit` effect. `details` is
+-- JSON metadata — never a request or response body, a secret or personal
+-- data. Pruned by age and count (lib/audit.js), never edited.
+CREATE TABLE audit_events (
+  id      INTEGER PRIMARY KEY AUTOINCREMENT,
+  at      TEXT NOT NULL,
+  actor   TEXT NOT NULL,
+  action  TEXT NOT NULL,
+  plugin  TEXT,
+  details TEXT NOT NULL DEFAULT '{}'
+);
+CREATE INDEX audit_events_plugin ON audit_events (plugin, id);
+CREATE INDEX audit_events_action ON audit_events (action, id);
+
+-- notifications: messages for the panel's administrators — the
+-- `notify-admins` hook effect and Lamaste's own events. Read state is
+-- shared: the panel has one administrator identity.
+CREATE TABLE notifications (
+  id      INTEGER PRIMARY KEY AUTOINCREMENT,
+  at      TEXT NOT NULL,
+  source  TEXT NOT NULL,
+  level   TEXT NOT NULL,
+  message TEXT NOT NULL,
+  read_at TEXT
+);
+CREATE INDEX notifications_unread ON notifications (read_at, id);

package/vendor/serverd/src/lib/migrations/state/0008_plugin_hooks.sql

@@ -0,0 +1,70 @@
+-- Lifecycle hooks of agent-hosted plugins (4.3, slice 2b).
+
+-- The manifest's `hooks` block (JSON; NULL when the plugin declares none)
+-- and the SHA-256 of its relay entry module, read when the package was
+-- installed. Together they give the relay hook set's digest without
+-- touching the package again.
+ALTER TABLE plugins ADD COLUMN hooks TEXT;
+ALTER TABLE plugins ADD COLUMN hooks_entry_sha256 TEXT;
+
+-- Approval of a plugin's relay hook set, and what the hook runner holds.
+--   approved_digest   the digest an administrator (or auto-approve) approved
+--   auto_approve      approve later hook-set changes automatically (audited)
+--   installed_digest  the digest lamaste-priv last installed into the runner
+--   pack_versions     JSON {pack: version} of the shared-hook rule packs last
+--                     recorded, to audit a rule update once per plugin
+--   pending_update    JSON {version, digest, ...} of a staged update waiting
+--                     for approval, or NULL
+--   tunnel_fallback   JSON fallback response the plugin's tunnel:down hook
+--                     returned, served while it is down; NULL otherwise
+-- Kept per plugin name; removed when the plugin is uninstalled.
+CREATE TABLE plugin_hook_sets (
+  plugin            TEXT PRIMARY KEY,
+  approved_digest   TEXT,
+  approved_version  TEXT,
+  approved_at       TEXT,
+  approved_by       TEXT,
+  auto_approve      INTEGER NOT NULL DEFAULT 0,
+  installed_digest  TEXT,
+  pack_versions     TEXT NOT NULL DEFAULT '{}',
+  pending_update    TEXT,
+  tunnel_fallback   TEXT
+);
+
+-- Long-running plugin operations (hosting, unhosting, update, uninstall):
+-- one running per plugin; steps and outcome kept for the panel. `steps` is
+-- JSON [{name, status, startedAt, finishedAt, error?}] — metadata only.
+CREATE TABLE plugin_operations (
+  id          TEXT PRIMARY KEY,
+  plugin      TEXT NOT NULL,
+  kind        TEXT NOT NULL,
+  actor       TEXT NOT NULL,
+  status      TEXT NOT NULL,
+  steps       TEXT NOT NULL DEFAULT '[]',
+  error       TEXT,
+  params      TEXT NOT NULL DEFAULT '{}',
+  started_at  TEXT NOT NULL,
+  finished_at TEXT
+);
+CREATE INDEX plugin_operations_plugin ON plugin_operations (plugin, started_at);
+
+-- Work for an agent's sync (agent-config `agentJobs`): calls the agent
+-- makes to its agent half on its own loopback (hook stages outside the
+-- tunnel), reported back with a result. `input` is the hook input (JSON
+-- metadata, no secrets); the agent signs the call with the installation
+-- secret it already holds.
+CREATE TABLE agent_jobs (
+  id           TEXT PRIMARY KEY,
+  agent_label  TEXT NOT NULL,
+  plugin       TEXT NOT NULL,
+  kind         TEXT NOT NULL,
+  stage        TEXT NOT NULL,
+  input        TEXT NOT NULL,
+  timeout_ms   INTEGER NOT NULL,
+  status       TEXT NOT NULL,
+  result       TEXT,
+  created_at   TEXT NOT NULL,
+  deadline_at  TEXT NOT NULL,
+  completed_at TEXT
+);
+CREATE INDEX agent_jobs_agent ON agent_jobs (agent_label, status);

package/vendor/serverd/src/lib/migrations/state/0009_plugin_agent_half.sql

@@ -0,0 +1,53 @@
+-- Agent halves Lamaste installs onto an agent (4.3, slice 3).
+
+-- The agent half pinned when the plugin's version was staged (install or
+-- update): JSON {package, version, integrity}, where `integrity` is the npm
+-- Subresource Integrity (sha512) of the agent package's tarball as the
+-- registry published it. The approval digest covers it and the agent
+-- installs only a tarball that matches it. NULL when Lamaste installs no
+-- agent half (no `agent.package` in the manifest).
+ALTER TABLE plugins ADD COLUMN agent_half_pin TEXT;
+
+-- Agent jobs gain kinds besides `hook`: `app-install`, `app-activate` and
+-- `app-remove` run the agent's root helper. Their parameters are `payload`
+-- (JSON: {spec} | {version, package} | {purge, package}); `stage` and
+-- `input` belong to hook jobs only, so they become nullable. SQLite cannot
+-- drop a NOT NULL constraint in place: the table is rebuilt with its rows.
+CREATE TABLE agent_jobs_v2 (
+  id           TEXT PRIMARY KEY,
+  agent_label  TEXT NOT NULL,
+  plugin       TEXT NOT NULL,
+  kind         TEXT NOT NULL,
+  stage        TEXT,
+  input        TEXT,
+  payload      TEXT,
+  timeout_ms   INTEGER NOT NULL,
+  status       TEXT NOT NULL,
+  result       TEXT,
+  created_at   TEXT NOT NULL,
+  deadline_at  TEXT NOT NULL,
+  completed_at TEXT
+);
+INSERT INTO agent_jobs_v2
+  (id, agent_label, plugin, kind, stage, input, payload, timeout_ms, status, result,
+   created_at, deadline_at, completed_at)
+SELECT id, agent_label, plugin, kind, stage, input, NULL, timeout_ms, status, result,
+       created_at, deadline_at, completed_at
+FROM agent_jobs;
+DROP TABLE agent_jobs;
+ALTER TABLE agent_jobs_v2 RENAME TO agent_jobs;
+CREATE INDEX agent_jobs_agent ON agent_jobs (agent_label, status);
+
+-- What an agent reports about its host (JSON HostFacts: OS, distribution,
+-- architecture, Node.js, systemd, the app host helper) and when it last
+-- did — checked against a plugin's `agent.requires` when it is hosted.
+ALTER TABLE agents ADD COLUMN host_facts TEXT;
+ALTER TABLE agents ADD COLUMN host_facts_at TEXT;
+
+-- An agent's push-install window and policy. The registry code has set both
+-- fields since push install exists, but the SQLite table (0004) had no
+-- columns for them, so an enabled window was never stored and the
+-- push-install gates could never pass. Hosting, updating and removing an
+-- agent half are gated on them.
+ALTER TABLE agents ADD COLUMN push_install_enabled_until TEXT;
+ALTER TABLE agents ADD COLUMN push_install_policy TEXT;

package/vendor/serverd/src/lib/migrations/state/0010_plugin_routes_and_retained_data.sql

@@ -0,0 +1,47 @@
+-- Plugin routes are unique; data an agent half leaves on an agent is kept
+-- on record (4.3, slice 3).
+
+-- A plugin's route — its name without a trailing "-server" or "-agent"
+-- (`derivePluginRoute`) — is what its API (`/api/<route>`), capabilities
+-- (`plugin:<route>:*`), OIDC client ids, hosting record and, on the agent,
+-- its agent half's account and directories are named after. Two installed
+-- plugins sharing one ("fx" and "fx-server") would act on each other's
+-- hosting and capabilities, so each route belongs to one installed plugin.
+ALTER TABLE plugins ADD COLUMN route TEXT;
+UPDATE plugins SET route = CASE
+  WHEN substr(name, -7) = '-server' THEN substr(name, 1, length(name) - 7)
+  WHEN substr(name, -6) = '-agent' THEN substr(name, 1, length(name) - 6)
+  ELSE name
+END;
+-- Plugins installed before the rule may already share a route: the one
+-- installed first keeps it; the others hold none (NULL) and can only be
+-- uninstalled — never hosted — until they are reinstalled under a route
+-- of their own.
+UPDATE plugins SET route = NULL WHERE EXISTS (
+  SELECT 1 FROM plugins AS other
+  WHERE other.route = plugins.route
+    AND other.name <> plugins.name
+    AND (other.installed_at < plugins.installed_at
+         OR (other.installed_at = plugins.installed_at AND other.name < plugins.name))
+);
+CREATE UNIQUE INDEX plugins_route ON plugins (route);
+
+-- The data an agent half leaves on an agent when it is removed without
+-- purge (unhost, uninstall, a rolled-back install): its data directory and
+-- service account, both named after the route. Kept here — not on the
+-- plugin row — because it outlives the plugin's uninstall and is keyed the
+-- way it exists on the agent: one record per agent and route. `package` is
+-- the agent package that owns it (the agent's helper refuses to install
+-- another package over it); `plugin` the plugin it belonged to. Removed when
+-- it is purged, or when the same agent half is installed there again and
+-- takes the data back.
+CREATE TABLE retained_agent_data (
+  agent_label  TEXT NOT NULL,
+  route        TEXT NOT NULL,
+  plugin       TEXT NOT NULL,
+  package      TEXT NOT NULL,
+  since        TEXT NOT NULL,
+  operation    TEXT,
+  PRIMARY KEY (agent_label, route)
+);
+CREATE INDEX retained_agent_data_plugin ON retained_agent_data (plugin);

package/vendor/serverd/src/lib/migrations/state/0011_agent_job_signature.sql

@@ -0,0 +1,14 @@
+-- App jobs are signed by the relay (4.3, slice 3).
+
+-- The agent's root helper runs an app job (`app-install`, `app-activate`,
+-- `app-remove`) only when the relay signed it, with the key the agent's
+-- operator pinned: JSON {envelope, sig} (core `app-job-signature.ts`),
+-- made with the relay's signing key when the job is created and listed with
+-- it in agent-config. NULL for hook jobs, which the helper never sees.
+ALTER TABLE agent_jobs ADD COLUMN signature TEXT;
+
+-- An app job left pending from before has no signature, and no agent would
+-- run it: it is cancelled rather than listed.
+UPDATE agent_jobs
+SET status = 'cancelled', completed_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+WHERE status = 'pending' AND kind != 'hook';

package/vendor/serverd/src/lib/mtls.js

@@ -15,10 +15,11 @@ import crypto from 'node:crypto';
 import { access, constants, mkdir } from 'node:fs/promises';
 import {
   BASE_CAPABILITIES as CORE_BASE_CAPABILITIES,
+  HostFactsSchema,
   PLUGIN_AGENT_CN_PREFIX as CORE_PLUGIN_AGENT_CN_PREFIX,
 } from '@lamalibre/lamaste';
 import { addToRevocationList } from './revocation.js';
-import { releaseAgentTunnels } from '@lamalibre/lamaste/server';
+import { releaseAgentTunnels, stripPluginCapabilities } from '@lamalibre/lamaste/server';
 import { tunnelNginxDeps, tunnelChiselDeps, tunnelStateDeps } from './tunnel-deps.js';
 import {
   addChiselCredential,
@@ -241,8 +242,9 @@ async function getStmts() {
     insert: db.prepare(`
       INSERT INTO agents
         (label, serial, capabilities, allowed_sites, enrollment_method,
-         delegated_by, created_at, expires_at, revoked, revoked_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         delegated_by, created_at, expires_at, revoked, revoked_at,
+         host_facts, host_facts_at, push_install_enabled_until, push_install_policy)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `),
 
     deleteAll: db.prepare('DELETE FROM agents'),
@@ -276,13 +278,51 @@ function rowToAgent(row) {
   };
   if (row.revoked_at != null) agent.revokedAt = row.revoked_at;
   if (row.delegated_by != null) agent.delegatedBy = row.delegated_by;
+  if (row.host_facts != null) agent.hostFacts = parseHostFacts(row.host_facts);
+  if (row.host_facts_at != null) agent.hostFactsAt = row.host_facts_at;
+  if (row.push_install_enabled_until != null) {
+    agent.pushInstallEnabledUntil = row.push_install_enabled_until;
+  }
+  if (row.push_install_policy != null) agent.pushInstallPolicy = row.push_install_policy;
   return agent;
 }
 
+/**
+ * Stored host facts, re-validated on the way out: a row that no longer
+ * parses as HostFacts (written by another version) reads as none, so
+ * eligibility asks the agent to report again instead of trusting it.
+ */
+function parseHostFacts(text) {
+  try {
+    const parsed = HostFactsSchema.safeParse(JSON.parse(text));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+
 function nullableString(value) {
   return value === undefined || value === null ? null : value;
 }
 
+/**
+ * Remove every `plugin:<route>:*` capability from every agent's stored
+ * record, under the registry lock — run when a plugin is uninstalled, so
+ * installing it again later does not silently re-grant what an admin gave
+ * the old installation. Returns the per-agent diff for the audit log.
+ *
+ * @param {string} route
+ * @returns {Promise<Array<{ label: string, removed: string[] }>>}
+ */
+export function revokePluginCapabilitiesFromAgents(route) {
+  return withRegistryLock(async () => {
+    const registry = await loadAgentRegistry();
+    const diffs = stripPluginCapabilities(registry.agents, route);
+    if (diffs.length > 0) await saveAgentRegistry(registry);
+    return diffs;
+  });
+}
+
 /**
  * Load the agent registry.
  * Returns `{ agents: [] }` if the table is empty.
@@ -340,6 +380,10 @@ export async function saveAgentRegistry(data) {
         a.expiresAt,
         a.revoked ? 1 : 0,
         nullableString(a.revokedAt),
+        a.hostFacts ? JSON.stringify(a.hostFacts) : null,
+        nullableString(a.hostFactsAt),
+        nullableString(a.pushInstallEnabledUntil),
+        nullableString(a.pushInstallPolicy),
       );
     }
     s.commit.run();
@@ -533,20 +577,24 @@ export async function generateAgentCert(label, logger, capabilities, allowedSite
 }
 
 /**
- * List all agent certificates with expiry status.
+ * List all agent certificates with expiry status and the host facts each
+ * agent last reported. `status` sums a certificate up for the panel:
+ * `revoked`, `expired`, `expiring-soon` (within 30 days) or `active`.
  *
- * @returns {Promise<Array<{ label: string, serial: string, createdAt: string, expiresAt: string, revoked: boolean, expiringSoon: boolean }>>}
+ * @returns {Promise<Array<{ label: string, serial: string, createdAt: string, expiresAt: string, revoked: boolean, expiringSoon: boolean, status: 'active' | 'expiring-soon' | 'expired' | 'revoked', hostFacts: object | null, hostFactsAt: string | null }>>}
  */
 export async function listAgentCerts() {
   const registry = await loadAgentRegistry();
+  const now = Date.now();
 
   return registry.agents.map((agent) => {
     let expiringSoon = false;
+    let expired = false;
     if (!agent.revoked && agent.expiresAt) {
-      const daysUntilExpiry = Math.floor(
-        (new Date(agent.expiresAt).getTime() - Date.now()) / (1000 * 60 * 60 * 24),
-      );
+      const expiresAt = new Date(agent.expiresAt).getTime();
+      const daysUntilExpiry = Math.floor((expiresAt - now) / (1000 * 60 * 60 * 24));
       expiringSoon = daysUntilExpiry <= 30;
+      expired = expiresAt <= now;
     }
     const isPluginAgent = agent.label.startsWith(PLUGIN_AGENT_CN_PREFIX);
     const entry = {
@@ -554,6 +602,16 @@ export async function listAgentCerts() {
       capabilities: agent.capabilities || (isPluginAgent ? [] : ['tunnels:read']),
       enrollmentMethod: agent.enrollmentMethod || 'p12',
       expiringSoon,
+      status: agent.revoked
+        ? 'revoked'
+        : expired
+          ? 'expired'
+          : expiringSoon
+            ? 'expiring-soon'
+            : 'active',
+      // What the agent last reported about its host (null until it has).
+      hostFacts: agent.hostFacts ?? null,
+      hostFactsAt: agent.hostFactsAt ?? null,
     };
     if (isPluginAgent) {
       entry.certType = 'plugin-agent';
@@ -657,6 +715,29 @@ export async function updateAgentAllowedSites(label, allowedSites) {
   });
 }
 
+/**
+ * Record what agent `label` reports about its host (validated
+ * `HostFacts`), under the registry lock. Only an enrolled, unrevoked
+ * agent has a record to keep them on.
+ *
+ * @param {string} label
+ * @param {import('@lamalibre/lamaste').HostFacts} hostFacts
+ * @returns {Promise<{ hostFactsAt: string }>}
+ */
+export function setAgentHostFacts(label, hostFacts) {
+  return withRegistryLock(async () => {
+    const registry = await loadAgentRegistry();
+    const agent = registry.agents.find((a) => a.label === label && !a.revoked);
+    if (!agent) {
+      throw Object.assign(new Error(`Agent certificate "${label}" not found`), { statusCode: 404 });
+    }
+    agent.hostFacts = hostFacts;
+    agent.hostFactsAt = new Date().toISOString();
+    await saveAgentRegistry(registry);
+    return { hostFactsAt: agent.hostFactsAt };
+  });
+}
+
 /**
  * Revoke an agent certificate by label.
  *