@lamalibre/create-lamaste 4.2.0 → 4.3.0

package/vendor/server-ui/dist/index.html

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Lamaste</title>
-    <script type="module" crossorigin src="/assets/index-B5Wp8lu-.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-BqWWFlTU.css">
+    <script type="module" crossorigin src="/assets/index-DBp3cmaU.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-Bc5NCMSv.css">
   </head>
   <body style="background-color: #09090b">
     <div id="root"></div>

package/vendor/serverd/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lamalibre/lamaste-serverd",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "Lamaste server daemon — REST API and plugin host",
   "license": "SEE LICENSE IN LICENSE.md",
   "publishConfig": {
@@ -29,7 +29,7 @@
     "@fastify/rate-limit": "^10.3.0",
     "@fastify/static": "^9.1.1",
     "@fastify/websocket": "^11.0.0",
-    "@lamalibre/lamaste": "^4.2.0",
+    "@lamalibre/lamaste": "^4.3.0",
     "bcryptjs": "^3.0.3",
     "execa": "^9.6.1",
     "fastify": "^5.8.4",

package/vendor/serverd/src/index.js

@@ -17,6 +17,7 @@ import healthRoutes from './routes/health.js';
 import onboardingRoutes from './routes/onboarding/index.js';
 import managementRoutes from './routes/management.js';
 import pluginRouter from './routes/plugin-router.js';
+import agentForwarderRoutes from './routes/agent-forwarder.js';
 import inviteRoutes from './routes/invite.js';
 import enrollmentRoutes from './routes/enrollment.js';
 import {
@@ -25,10 +26,20 @@ import {
   userAccessProtectedRoutes,
 } from './routes/user-access.js';
 import userAccessSessionMiddleware from './middleware/user-access-session.js';
-import { getPluginCapabilities } from './lib/plugins.js';
+import { getPluginCapabilities, readPlugins } from './lib/plugins.js';
+import { markInterruptedOperations } from './lib/plugin-operations.js';
+import { trustLocalNginxHop } from './lib/trust-proxy.js';
+import { reconcileRelayHooks } from './lib/plugin-hooks.js';
+import { loadTunnelFallbacks } from './lib/request-hooks.js';
 import { setPluginCapabilities } from './lib/mtls.js';
 import { startChiselReconciler } from './lib/chisel-reconcile.js';
+import {
+  startHostedPluginHealthMonitor,
+  stopHostedPluginHealthMonitor,
+} from './lib/plugin-hosting.js';
 import { syncOidcClients } from './lib/plugin-oidc.js';
+import { ensureRelaySigningKey } from './lib/relay-signing.js';
+import { reconcileSiteVhosts, reconcileTunnelVhosts } from './lib/vhost-reconcile.js';
 import {
   loadTicketScopeCapabilities,
   checkInstanceLiveness,
@@ -61,9 +72,10 @@ async function start() {
 
   const server = Fastify({
     logger: true,
-    // Behind nginx: trust exactly one proxy hop so request.ip reflects the real client IP
-    // from nginx's $remote_addr, not a spoofed X-Forwarded-For value from upstream.
-    trustProxy: 1,
+    // Behind the local nginx: trust exactly that one loopback hop, so
+    // request.ip is the client address nginx appended to X-Forwarded-For —
+    // not a value the client sent, and nothing from a non-local peer.
+    trustProxy: trustLocalNginxHop,
   });
 
   // Wire ticket module to the Fastify root logger so any load-time warnings
@@ -87,6 +99,11 @@ async function start() {
     });
   }
 
+  // The key relay assertions to agents' lamaste-agentd are signed with —
+  // created here when missing, before Gatekeeper (which signs with it too)
+  // needs it.
+  await ensureRelaySigningKey(server.log);
+
   // --- Plugins ---
   const ipOrigin = `https://${config.ip}:9292`;
   await server.register(cors, {
@@ -158,6 +175,9 @@ async function start() {
     app.register(managementRoutes, { prefix: '/api' });
     app.register(userAccessAdminRoutes, { prefix: '/api' });
     app.register(pluginRouter, { prefix: '/api' });
+    // Last: agent-hosted plugins with an agent half, forwarded over their
+    // internal tunnels. Only what no other /api route answers reaches it.
+    app.register(agentForwarderRoutes, { prefix: '/api' });
   });
 
   // --- User-access session-protected routes (Bearer token, no mTLS) ---
@@ -176,8 +196,39 @@ async function start() {
   });
 
   // --- Start ---
+
+  // The auth portal and static site vhosts an older version wrote name the
+  // client's Host header, not their own hostname, to Authelia. Before listen:
+  // site changes take no lock, and none can arrive until the panel listens.
+  if (config.onboarding.status === 'COMPLETED' && config.domain) {
+    await reconcileSiteVhosts(server.log, config.domain).catch((err) => {
+      server.log.error({ err: err.message }, 'Startup site vhost reconcile failed');
+    });
+  }
+
   await server.listen({ host: '127.0.0.1', port: 3100 });
 
+  // --- Lifecycle hooks: operations a restart cut short, the runners of
+  // approved relay hook sets (a redeploy may have reset them), fallbacks ---
+  await markInterruptedOperations(server.log);
+  await loadTunnelFallbacks();
+  readPlugins()
+    .then(({ plugins }) => reconcileRelayHooks(plugins, server.log))
+    .catch((err) => server.log.error({ err: err.message }, 'Relay hook reconciliation failed'));
+
+  // Tunnel vhosts written by an older version: agent-panel and plugin vhosts
+  // do not forward relay assertions, without which lamaste-agentd refuses the
+  // relay, and Gatekeeper vhosts name the client's Host header to Gatekeeper.
+  // After listen: a rewritten agent-panel vhost asks this server at once.
+  if (config.onboarding.status === 'COMPLETED') {
+    reconcileTunnelVhosts(server.log).catch((err) => {
+      server.log.error({ err: err.message }, 'Startup tunnel vhost reconcile failed');
+    });
+  }
+
+  // --- Health of hosted agent-hosted plugins (every 10s; idle without hostings) ---
+  startHostedPluginHealthMonitor(server.log);
+
   // --- Periodic ticket instance liveness check (every 60s) ---
   const livenessInterval = setInterval(() => {
     checkInstanceLiveness(server.log).catch((err) => {
@@ -190,6 +241,7 @@ async function start() {
   const shutdown = async (signal) => {
     server.log.info({ signal }, 'Received signal, shutting down gracefully');
     clearInterval(livenessInterval);
+    stopHostedPluginHealthMonitor();
     clearRateLimitInterval();
     await server.close();
     process.exit(0);

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

@@ -0,0 +1,24 @@
+/**
+ * Derive a stable audit identifier for the calling principal.
+ *
+ * Returns the certificate CN form (`admin`, `agent:<label>`, `plugin-agent:...`)
+ * so a reader of the journal or the audit log can correlate events with the
+ * principal that initiated them. Returns `'unknown'` when middleware did not
+ * populate cert metadata (e.g. dev mode shortcut on /api/health).
+ */
+export function actorFromRequest(request) {
+  if (request.certRole === 'admin') return 'admin';
+  if (request.certRole === 'agent' && request.certLabel) return `agent:${request.certLabel}`;
+  if (request.certRole === 'plugin-agent' && request.certLabel) return request.certLabel;
+  return 'unknown';
+}
+
+/**
+ * The client certificate serial nginx reported, for audit entries: every
+ * administrator shares the `admin` identity, so the serial is what tells two
+ * admin certificates apart. Not secret. Null when absent (development mode).
+ */
+export function certSerialFromRequest(request) {
+  const serial = request.headers?.['x-ssl-client-serial'];
+  return typeof serial === 'string' && /^[0-9A-Fa-f]{1,64}$/.test(serial) ? serial : null;
+}

package/vendor/serverd/src/lib/agent-jobs.js

@@ -0,0 +1,330 @@
+/**
+ * Agent jobs — the panel's way to have an agent do something on its own
+ * machine and report back. The panel cannot reach an agent (agents connect
+ * out, behind NAT); an agent's sync timer fetches `agent-config` every 30 s,
+ * which lists the agent's pending jobs, runs them, and posts each result to
+ * `POST /api/agents/me/jobs/:id/result`.
+ *
+ * The kinds (core `agent-jobs.ts` has the result contract both ends check):
+ *
+ * - `hook` — call the agent half's `POST /admin/hooks/<stage>` on the
+ *   agent's loopback, for the lifecycle stages that run while the internal
+ *   tunnel is not there (the agent's `install:pre-tunnel` before it is
+ *   granted, `uninstall:post-teardown` after it is removed). The agent
+ *   signs that call with the installation secret it already holds.
+ * - `app-install` (`spec`: the pinned agent half), `app-activate`
+ *   (`version`, `package`) and `app-remove` (`purge`, `package`) — install,
+ *   switch or remove the agent half through the agent's root helper
+ *   `lamaste-apphost`. The agent fetches the package itself and installs it
+ *   only when its tarball matches the pinned integrity.
+ *
+ * The helper runs as root and does only what the relay signed: every app
+ * job is signed with the relay's signing key when it is created (core
+ * `app-job-signature.ts`; the envelope names the agent, route, job id, kind
+ * and payload, and expires at the job's deadline) and listed with its
+ * signature. No app job is created while the key is unusable.
+ *
+ * A job carries no secret. It has a deadline (its timeout plus delivery
+ * slack); an unfinished job past it expires. Waiting is event-driven within
+ * this process, with the database as the record.
+ */
+
+import crypto from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import {
+  AGENT_APP_JOB_TIMEOUTS,
+  AgentAppJobResultSchema,
+  AgentHookJobResultSchema,
+  appJobPayload,
+  signAppJob,
+} from '@lamalibre/lamaste';
+import { relaySigner } from './relay-signing.js';
+import { getStateDb } from './state-db.js';
+
+/** Two sync intervals and a margin: how long delivery may take on top of the hook's own timeout. */
+export const AGENT_JOB_DELIVERY_SLACK_MS = 90_000;
+
+/** Largest result an agent may post. */
+export const AGENT_JOB_RESULT_MAX_BYTES = 64 * 1024;
+
+/** The app job kinds and how long the agent has for each (the helper's work, not delivery). */
+export const AGENT_APP_JOB_KINDS = Object.freeze({
+  'app-install': AGENT_APP_JOB_TIMEOUTS.install,
+  'app-activate': AGENT_APP_JOB_TIMEOUTS.activate,
+  'app-remove': AGENT_APP_JOB_TIMEOUTS.remove,
+});
+
+const events = new EventEmitter();
+events.setMaxListeners(0);
+
+/** An app job could not be signed: the relay's signing key is missing or unusable. */
+export class AppJobSigningError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'AppJobSigningError';
+  }
+}
+
+function rowToJob(row) {
+  return {
+    id: row.id,
+    agentLabel: row.agent_label,
+    route: row.plugin,
+    kind: row.kind,
+    stage: row.stage,
+    input: row.input ? JSON.parse(row.input) : null,
+    payload: row.payload ? JSON.parse(row.payload) : null,
+    signature: row.signature ? JSON.parse(row.signature) : null,
+    timeoutMs: row.timeout_ms,
+    status: row.status,
+    result: row.result ? JSON.parse(row.result) : null,
+    createdAt: row.created_at,
+    deadlineAt: row.deadline_at,
+    completedAt: row.completed_at,
+  };
+}
+
+/**
+ * Insert a pending job: `stage` and `input` for a hook job, `payload` (and
+ * `sign`, which makes its signature) for an app job; null otherwise. Its
+ * deadline leaves delivery {@link AGENT_JOB_DELIVERY_SLACK_MS} on top of
+ * `timeoutMs`.
+ *
+ * @param {object} job
+ * @param {((timing: { id: string, issuedAt: string, expiresAt: string }) => object) | null} [job.sign]
+ * @returns {Promise<string>} the job id
+ */
+async function insertJob({ agentLabel, plugin, kind, stage, input, payload, timeoutMs, sign }) {
+  const db = await getStateDb();
+  const id = crypto.randomUUID();
+  const now = Date.now();
+  const createdAt = new Date(now).toISOString();
+  const deadlineAt = new Date(now + timeoutMs + AGENT_JOB_DELIVERY_SLACK_MS).toISOString();
+  const signature = sign ? sign({ id, issuedAt: createdAt, expiresAt: deadlineAt }) : null;
+  db.prepare(
+    `INSERT INTO agent_jobs (id, agent_label, plugin, kind, stage, input, payload, signature, timeout_ms, status, created_at, deadline_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?)`,
+  ).run(
+    id,
+    agentLabel,
+    plugin,
+    kind,
+    stage,
+    input,
+    payload,
+    signature === null ? null : JSON.stringify(signature),
+    timeoutMs,
+    createdAt,
+    deadlineAt,
+  );
+  return id;
+}
+
+/**
+ * A `hook` job: call the agent half's `stage` hook on the agent's loopback.
+ *
+ * @param {{ agentLabel: string, plugin: string, stage: string, input: object, timeoutMs: number }} job
+ * @returns {Promise<string>} the job id
+ */
+export async function createAgentJob({ agentLabel, plugin, stage, input, timeoutMs }) {
+  return insertJob({
+    agentLabel,
+    plugin,
+    kind: 'hook',
+    stage,
+    input: JSON.stringify(input),
+    payload: null,
+    timeoutMs,
+    sign: null,
+  });
+}
+
+/**
+ * The relay's signing key for an app job; throws {@link AppJobSigningError}
+ * when there is none to use — the agent's helper would refuse the job.
+ */
+async function appJobSigningKey() {
+  let key;
+  try {
+    key = await relaySigner.current();
+  } catch (err) {
+    throw new AppJobSigningError(
+      `The relay's signing key is unusable (${err instanceof Error ? err.message : String(err)}), ` +
+        "so it cannot sign the job the agent's app host helper would run",
+    );
+  }
+  if (!key) {
+    throw new AppJobSigningError(
+      "The relay has no signing key, so it cannot sign the job the agent's app host helper would run",
+    );
+  }
+  return key;
+}
+
+/**
+ * An app job: install (`spec`), activate (`version`, `package`) or remove
+ * (`purge`, `package`) the plugin's agent half through the agent's root
+ * helper — signed with the relay's key for the agent and the job's
+ * deadline. Throws {@link AppJobSigningError} (nothing is created) when the
+ * key is unusable, a TypeError for parameters that are not the kind's.
+ *
+ * @param {{ agentLabel: string, plugin: string, kind: 'app-install' | 'app-activate' | 'app-remove', spec?: object, version?: string, purge?: boolean, package?: string }} job
+ * @returns {Promise<string>} the job id
+ */
+export async function createAppJob({ agentLabel, plugin, kind, ...params }) {
+  if (!Object.hasOwn(AGENT_APP_JOB_KINDS, kind)) {
+    throw new TypeError(`Unknown app job kind "${kind}"`);
+  }
+  const payload = appJobPayload(kind, params);
+  const key = await appJobSigningKey();
+  return insertJob({
+    agentLabel,
+    plugin,
+    kind,
+    stage: null,
+    input: null,
+    payload: JSON.stringify(payload),
+    timeoutMs: AGENT_APP_JOB_KINDS[kind],
+    sign: ({ id, issuedAt, expiresAt }) =>
+      signAppJob(
+        { agent: agentLabel, route: plugin, jobId: id, kind, payload, issuedAt, expiresAt },
+        key,
+      ),
+  });
+}
+
+/** Finish the pending jobs `rows` as `status` (expired, cancelled) and wake their waiters. */
+function finishPending(db, rows, status, now) {
+  const finish = db.prepare(
+    "UPDATE agent_jobs SET status = ?, completed_at = ? WHERE id = ? AND status = 'pending'",
+  );
+  for (const { id } of rows) {
+    finish.run(status, now, id);
+    events.emit(id);
+  }
+}
+
+/** Expire jobs past their deadline. */
+async function expireOverdue(db) {
+  const now = new Date().toISOString();
+  const overdue = db
+    .prepare("SELECT id FROM agent_jobs WHERE status = 'pending' AND deadline_at <= ?")
+    .all(now);
+  finishPending(db, overdue, 'expired', now);
+  // Finished jobs are kept a day for the record, then dropped.
+  const cutoff = new Date(Date.now() - 86_400_000).toISOString();
+  db.prepare("DELETE FROM agent_jobs WHERE status != 'pending' AND created_at < ?").run(cutoff);
+}
+
+/**
+ * The agent-config `agentJobs` of agent `label`: pending, not yet overdue.
+ * A `hook` job carries `stage` and `input`; an app job its parameters
+ * (`spec`; `version` and `package`; `purge` and `package`) and the relay's
+ * `signature` over them.
+ */
+export async function pendingAgentJobs(label) {
+  const db = await getStateDb();
+  await expireOverdue(db);
+  return db
+    .prepare(
+      "SELECT * FROM agent_jobs WHERE agent_label = ? AND status = 'pending' ORDER BY created_at",
+    )
+    .all(label)
+    .map((row) => {
+      const job = rowToJob(row);
+      const base = { id: job.id, route: job.route, kind: job.kind };
+      const timing = { timeoutMs: job.timeoutMs, deadlineAt: job.deadlineAt };
+      return job.kind === 'hook'
+        ? { ...base, stage: job.stage, input: job.input, ...timing }
+        : { ...base, ...timing, ...job.payload, signature: job.signature };
+    });
+}
+
+/** One job by id, or null. */
+export async function findAgentJob(id) {
+  const db = await getStateDb();
+  const row = db.prepare('SELECT * FROM agent_jobs WHERE id = ?').get(id);
+  return row ? rowToJob(row) : null;
+}
+
+/**
+ * The agent reports a job's result. Only the agent the job is for may, and
+ * only once. The result must fit the job's kind (core `AgentJobResultSchema`):
+ * a hook job's `{ ok: true, decision }`, an app job's
+ * `{ ok: true, app: { version, unit } }`, or `{ ok: false, error }` (one
+ * line). What is stored is the validated result.
+ *
+ * @returns {Promise<'recorded' | 'not_found' | 'not_pending' | 'invalid'>}
+ */
+export async function completeAgentJob(label, id, result) {
+  const db = await getStateDb();
+  const row = db
+    .prepare('SELECT * FROM agent_jobs WHERE id = ? AND agent_label = ?')
+    .get(id, label);
+  if (!row) return 'not_found';
+  if (row.status !== 'pending') return 'not_pending';
+  const schema = row.kind === 'hook' ? AgentHookJobResultSchema : AgentAppJobResultSchema;
+  const parsed = schema.safeParse(result);
+  if (!parsed.success) return 'invalid';
+  const changes = db
+    .prepare(
+      "UPDATE agent_jobs SET status = 'done', result = ?, completed_at = ? WHERE id = ? AND status = 'pending'",
+    )
+    .run(JSON.stringify(parsed.data), new Date().toISOString(), id).changes;
+  if (Number(changes) === 0) return 'not_pending';
+  events.emit(id);
+  return 'recorded';
+}
+
+/**
+ * Wait for a job to finish. Resolves the job's result — `{ ok: true, decision }`
+ * (hook) or `{ ok: true, app }` (app job) — `{ ok: false, error }` (the
+ * agent reported a failure), or `{ ok: false, error, expired: true }` when
+ * the deadline passed (or the job was cancelled): the outcome is unknown.
+ */
+export async function waitForAgentJob(id) {
+  const db = await getStateDb();
+  for (;;) {
+    const row = db.prepare('SELECT * FROM agent_jobs WHERE id = ?').get(id);
+    if (!row) return { ok: false, error: 'The job no longer exists' };
+    if (row.status === 'done') {
+      const result = JSON.parse(row.result);
+      return result && typeof result === 'object'
+        ? result
+        : { ok: false, error: 'Malformed result' };
+    }
+    if (row.status === 'expired' || row.status === 'cancelled') {
+      return {
+        ok: false,
+        expired: true,
+        error:
+          row.status === 'expired'
+            ? 'The agent did not report the job before its deadline (offline, or its sync is not running)'
+            : 'The job was cancelled',
+      };
+    }
+    const untilDeadline = Date.parse(row.deadline_at) - Date.now();
+    if (untilDeadline <= 0) {
+      await expireOverdue(db);
+      continue;
+    }
+    await new Promise((resolve) => {
+      const timer = setTimeout(done, Math.min(untilDeadline + 10, 5_000));
+      function done() {
+        clearTimeout(timer);
+        events.off(id, done);
+        resolve();
+      }
+      events.once(id, done);
+    });
+  }
+}
+
+/** Cancel a plugin's pending jobs (its operation ended). */
+export async function cancelAgentJobs(plugin) {
+  const db = await getStateDb();
+  const rows = db
+    .prepare("SELECT id FROM agent_jobs WHERE plugin = ? AND status = 'pending'")
+    .all(plugin);
+  finishPending(db, rows, 'cancelled', new Date().toISOString());
+}

package/vendor/serverd/src/lib/app-error.js

@@ -12,3 +12,13 @@ export class AppError extends Error {
     this.isOperational = true;
   }
 }
+
+/**
+ * A plain Error carrying the HTTP `statusCode` a route answers with, and
+ * whatever `extra` names beyond the message (a refusal's `code`,
+ * `reasons`, …). Not an {@link AppError}: the error middleware treats those
+ * as operational.
+ */
+export function httpError(message, statusCode, extra = {}) {
+  return Object.assign(new Error(message), { statusCode, ...extra });
+}

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

@@ -0,0 +1,145 @@
+// Lamaste's audit log — an append-only record in state.db of administrative
+// decisions (hook approvals, auto-approve changes, hostings, plugin updates)
+// and of what plugins' lifecycle hooks report through the `audit` effect.
+//
+// Entries hold metadata only. `details` is a flat-ish JSON object capped at
+// AUDIT_DETAILS_MAX_BYTES; strings in it are truncated. Nothing here is ever
+// a request or response body or a secret — callers pass identifiers, counts
+// and reasons. The log is pruned by age and count, never edited.
+
+import { getStateDb } from './state-db.js';
+
+export const AUDIT_RETENTION_DAYS = 180;
+export const AUDIT_MAX_ROWS = 50_000;
+export const AUDIT_DETAILS_MAX_BYTES = 4096;
+const AUDIT_STRING_MAX = 300;
+const PRUNE_EVERY = 500;
+
+const ACTION_RE = /^[a-z][a-z0-9.-]{0,99}$/;
+const ACTOR_RE = /^[A-Za-z0-9:._@-]{1,200}$/;
+const PLUGIN_RE = /^[a-z0-9-]{1,100}$/;
+
+let insertsSincePrune = 0;
+
+function sanitize(value, depth = 0) {
+  if (value === null || typeof value === 'boolean') return value;
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+  if (typeof value === 'string') {
+    return value.length > AUDIT_STRING_MAX ? `${value.slice(0, AUDIT_STRING_MAX)}…` : value;
+  }
+  if (depth >= 3) return null;
+  if (Array.isArray(value)) return value.slice(0, 50).map((v) => sanitize(v, depth + 1));
+  if (typeof value === 'object') {
+    const out = {};
+    for (const [key, v] of Object.entries(value).slice(0, 50)) {
+      if (v !== undefined) out[String(key).slice(0, 64)] = sanitize(v, depth + 1);
+    }
+    return out;
+  }
+  return null;
+}
+
+/** Serialise `details`, dropping everything when it would exceed the cap. */
+function encodeDetails(details) {
+  const json = JSON.stringify(sanitize(details ?? {}) ?? {});
+  if (Buffer.byteLength(json) <= AUDIT_DETAILS_MAX_BYTES) return json;
+  return JSON.stringify({ truncated: true });
+}
+
+/**
+ * Append one entry.
+ *
+ * @param {{ actor: string, action: string, plugin?: string | null, details?: object }} entry
+ *   `actor` — `admin`, `agent:<label>`, `plugin:<route>` (a hook's effect),
+ *   `lamaste` (the panel itself), `auto-approve`; `action` — dotted lower case
+ *   (`hooks.approved`, `plugin.updated`, `hook.secret-scan.redacted`).
+ */
+export async function recordAudit({ actor, action, plugin = null, details = {} }) {
+  if (!ACTOR_RE.test(actor)) throw new Error(`Invalid audit actor "${actor}"`);
+  if (!ACTION_RE.test(action)) throw new Error(`Invalid audit action "${action}"`);
+  if (plugin !== null && !PLUGIN_RE.test(plugin)) throw new Error('Invalid audit plugin');
+  const db = await getStateDb();
+  const at = new Date().toISOString();
+  const result = db
+    .prepare('INSERT INTO audit_events (at, actor, action, plugin, details) VALUES (?, ?, ?, ?, ?)')
+    .run(at, actor, action, plugin, encodeDetails(details));
+  insertsSincePrune++;
+  if (insertsSincePrune >= PRUNE_EVERY) {
+    insertsSincePrune = 0;
+    pruneAudit(db);
+  }
+  return { id: Number(result.lastInsertRowid), at };
+}
+
+/**
+ * Append, logging instead of throwing — for paths where the audited action
+ * already happened and a full disk must not turn it into an error.
+ */
+export async function recordAuditBestEffort(entry, logger) {
+  try {
+    return await recordAudit(entry);
+  } catch (err) {
+    logger?.error?.({ err: err.message, action: entry.action }, 'Failed to write audit entry');
+    return null;
+  }
+}
+
+function pruneAudit(db) {
+  const cutoff = new Date(Date.now() - AUDIT_RETENTION_DAYS * 86_400_000).toISOString();
+  db.prepare('DELETE FROM audit_events WHERE at < ?').run(cutoff);
+  db.prepare(
+    'DELETE FROM audit_events WHERE id <= (SELECT id FROM audit_events ORDER BY id DESC LIMIT 1 OFFSET ?)',
+  ).run(AUDIT_MAX_ROWS);
+}
+
+function rowToEntry(row) {
+  let details;
+  try {
+    details = JSON.parse(row.details);
+  } catch {
+    details = {};
+  }
+  return {
+    id: row.id,
+    at: row.at,
+    actor: row.actor,
+    action: row.action,
+    plugin: row.plugin,
+    details,
+  };
+}
+
+/**
+ * Newest first. `before` pages backwards by id; `action` matches exactly or,
+ * ending in `.`, as a prefix (`hooks.`).
+ */
+export async function listAudit({ plugin, action, before, limit = 50 } = {}) {
+  const db = await getStateDb();
+  const where = [];
+  const args = [];
+  if (plugin) {
+    where.push('plugin = ?');
+    args.push(plugin);
+  }
+  if (action) {
+    if (action.endsWith('.')) {
+      where.push('substr(action, 1, ?) = ?');
+      args.push(action.length, action);
+    } else {
+      where.push('action = ?');
+      args.push(action);
+    }
+  }
+  if (before) {
+    where.push('id < ?');
+    args.push(before);
+  }
+  const sql = `SELECT id, at, actor, action, plugin, details FROM audit_events${
+    where.length ? ` WHERE ${where.join(' AND ')}` : ''
+  } ORDER BY id DESC LIMIT ?`;
+  args.push(Math.min(Math.max(1, limit), 200));
+  return db
+    .prepare(sql)
+    .all(...args)
+    .map(rowToEntry);
+}