@lamalibre/create-lamaste 4.2.0 → 4.3.1

package/vendor/serverd/src/routes/management/agents.js

@@ -11,11 +11,24 @@ import {
   rotateAgentChiselCredential,
   getAgentCapabilities,
   getAgentAllowedSites,
+  setAgentHostFacts,
 } from '../../lib/mtls.js';
 import { z } from 'zod';
-import { AGENT_LABEL_REGEX } from '@lamalibre/lamaste';
+import {
+  AGENT_LABEL_REGEX,
+  AgentJobResultSchema,
+  HostFactsSchema,
+  pluginHostCapability,
+} from '@lamalibre/lamaste';
 import { RegistryCredentialError } from '@lamalibre/lamaste/server';
 import { acquireAgentToken } from '../../lib/registry-credential.js';
+import { agentPluginConfig, acknowledgeAgentPluginConfig } from '../../lib/plugin-hosting.js';
+import {
+  AGENT_JOB_RESULT_MAX_BYTES,
+  completeAgentJob,
+  findAgentJob,
+} from '../../lib/agent-jobs.js';
+import { relayVerifyKeys } from '../../lib/relay-signing.js';
 
 /**
  * An agent may rotate its own chisel credential at most this often. Every
@@ -24,6 +37,20 @@ import { acquireAgentToken } from '../../lib/registry-credential.js';
  */
 const SELF_ROTATE_MIN_INTERVAL_MS = 10 * 60 * 1000;
 
+const PluginRouteParamSchema = z.object({
+  route: z
+    .string()
+    .min(1)
+    .max(100)
+    .regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, 'Invalid plugin route'),
+});
+
+const AckBodySchema = z.object({
+  issuedAt: z.string().min(1).max(64),
+});
+
+const JobIdParamSchema = z.object({ id: z.string().uuid() });
+
 const LabelParamSchema = z.object({
   label: z
     .string()
@@ -32,6 +59,34 @@ const LabelParamSchema = z.object({
     .regex(/^[a-z0-9-]+$/, 'Invalid agent label'),
 });
 
+/**
+ * The plugin-config routes admit only a machine agent whose certificate
+ * carries the plugin's host capability. The admin master role passes every
+ * `requireRole` guard but has no agent identity to serve, so it is refused
+ * here too. Returns the reply when refused, undefined when admitted.
+ */
+function refuseUnlessHostingAgent(request, reply, route) {
+  if (request.certRole !== 'agent') {
+    return reply
+      .code(403)
+      .send({ error: 'Only the hosting agent certificate can read a plugin config' });
+  }
+  const label = request.certLabel;
+  if (!label || !AGENT_LABEL_REGEX.test(label)) {
+    return reply
+      .code(400)
+      .send({ error: 'Agent label could not be determined from client certificate' });
+  }
+  const required = pluginHostCapability(route);
+  if (!(request.certCapabilities || []).includes(required)) {
+    return reply.code(403).send({
+      error: 'Insufficient certificate capability',
+      details: { required, granted: request.certCapabilities || [] },
+    });
+  }
+  return undefined;
+}
+
 export default async function agentsRoutes(fastify, _opts) {
   // ------------------------------------------------------------------
   // GET /agents/me/chisel-credential
@@ -194,6 +249,175 @@ export default async function agentsRoutes(fastify, _opts) {
     },
   );
 
+  // ------------------------------------------------------------------
+  // GET /agents/me/plugin-config/:route
+  //
+  // The config of an agent-hosted plugin hosted on the calling agent: the
+  // port its agent half listens on and the installation secret (plus the
+  // previous secret during a rotation). Only the hosting agent can read it:
+  // its certificate must carry `plugin:<route>:host`, which hosting granted,
+  // and the hosting must name it. Identity comes strictly from the mTLS
+  // certificate.
+  // ------------------------------------------------------------------
+  fastify.get(
+    '/agents/me/plugin-config/:route',
+    {
+      preHandler: fastify.requireRole(['agent']),
+      config: { rateLimit: { max: 60, timeWindow: '1 minute' } },
+    },
+    async (request, reply) => {
+      const { route } = PluginRouteParamSchema.parse(request.params);
+      const refused = refuseUnlessHostingAgent(request, reply, route);
+      if (refused) return refused;
+      const config = await agentPluginConfig(request.certLabel, route);
+      if (!config) {
+        return reply.code(404).send({ error: `Plugin "${route}" is not hosted on this agent` });
+      }
+      return config;
+    },
+  );
+
+  // ------------------------------------------------------------------
+  // POST /agents/me/plugin-config/:route/ack
+  //
+  // The hosting agent confirms it holds the secret issued at `issuedAt`.
+  // From then on the panel's forwarder signs with it and drops the previous
+  // one. An `issuedAt` that is not the current secret's is answered with
+  // `acknowledged: false` and the current `secretIssuedAt`, so the agent
+  // fetches again.
+  // ------------------------------------------------------------------
+  fastify.post(
+    '/agents/me/plugin-config/:route/ack',
+    {
+      preHandler: fastify.requireRole(['agent']),
+      config: { rateLimit: { max: 60, timeWindow: '1 minute' } },
+    },
+    async (request, reply) => {
+      const { route } = PluginRouteParamSchema.parse(request.params);
+      const body = AckBodySchema.parse(request.body);
+      const refused = refuseUnlessHostingAgent(request, reply, route);
+      if (refused) return refused;
+      const result = await acknowledgeAgentPluginConfig(request.certLabel, route, body.issuedAt);
+      if (!result) {
+        return reply.code(404).send({ error: `Plugin "${route}" is not hosted on this agent` });
+      }
+      request.log.info(
+        { label: request.certLabel, plugin: route, acknowledged: result.acknowledged },
+        'Plugin config acknowledgement',
+      );
+      return { ok: true, ...result };
+    },
+  );
+
+  // ------------------------------------------------------------------
+  // POST /agents/me/jobs/:id/result
+  //
+  // The calling agent reports a job agent-config gave it. A hook job (a
+  // lifecycle hook call to its agent half): `{ ok: true, decision }`; an
+  // app job (install, activate or remove its agent half through the app
+  // host helper): `{ ok: true, app: { version, unit } }`; either:
+  // `{ ok: false, error }` (one line). The result must fit the job's kind
+  // (core `AgentJobResultSchema`). Only the machine agent the job is for,
+  // and only once. A hook job's agent must also hold the host capability of
+  // the job's plugin (it calls the hosted agent half); an app job's need
+  // not — purging the data an agent half left runs after the hosting, and
+  // the capability, are gone.
+  // ------------------------------------------------------------------
+  fastify.post(
+    '/agents/me/jobs/:id/result',
+    {
+      preHandler: fastify.requireRole(['agent']),
+      config: { rateLimit: { max: 60, timeWindow: '1 minute' } },
+      bodyLimit: AGENT_JOB_RESULT_MAX_BYTES,
+    },
+    async (request, reply) => {
+      const { id } = JobIdParamSchema.parse(request.params);
+      const result = AgentJobResultSchema.parse(request.body);
+      const job = await findAgentJob(id);
+      if (!job || job.agentLabel !== request.certLabel) {
+        return reply.code(404).send({ error: 'Job not found' });
+      }
+      if (job.kind === 'hook') {
+        const refused = refuseUnlessHostingAgent(request, reply, job.route);
+        if (refused) return refused;
+      } else if (request.certRole !== 'agent') {
+        return reply
+          .code(403)
+          .send({ error: 'Only the agent certificate the job is for can report it' });
+      }
+      const outcome = await completeAgentJob(request.certLabel, id, result);
+      if (outcome === 'not_found') return reply.code(404).send({ error: 'Job not found' });
+      if (outcome === 'not_pending') {
+        return reply.code(409).send({ error: 'The job is no longer pending' });
+      }
+      if (outcome === 'invalid') {
+        return reply.code(400).send({
+          error:
+            job.kind === 'hook'
+              ? 'A hook job reports { ok: true, decision } or { ok: false, error }'
+              : 'An app job reports { ok: true, app: { version, unit } } or { ok: false, error }',
+        });
+      }
+      request.log.info(
+        {
+          label: request.certLabel,
+          plugin: job.route,
+          kind: job.kind,
+          ...(job.stage ? { stage: job.stage } : {}),
+          ok: result.ok,
+        },
+        'Agent job reported',
+      );
+      return { ok: true };
+    },
+  );
+
+  // ------------------------------------------------------------------
+  // PUT /agents/me/host-facts
+  //
+  // The calling agent reports what the relay needs to know about its host
+  // to tell which plugins it can host (`agent.requires`, and whether
+  // Lamaste can install an agent half there): OS, distribution,
+  // architecture, Node.js, systemd and its app host helper — core
+  // `HostFactsSchema`. Its sync sends them when they change. Kept on the
+  // agent's registry record (`hostFacts`, `hostFactsAt`); identity comes
+  // strictly from the mTLS certificate.
+  // ------------------------------------------------------------------
+  fastify.put(
+    '/agents/me/host-facts',
+    {
+      preHandler: fastify.requireRole(['agent']),
+      // Sent on change (and once a day); this only stops a loop.
+      config: { rateLimit: { max: 10, timeWindow: '1 minute' } },
+      bodyLimit: 4 * 1024,
+    },
+    async (request, reply) => {
+      // requireRole lets the admin master role through every guard; an admin
+      // certificate has no host to report. A plugin-agent hosts nothing.
+      if (request.certRole !== 'agent') {
+        return reply.code(403).send({ error: 'Only an agent certificate can report host facts' });
+      }
+      const label = request.certLabel;
+      if (!label || !AGENT_LABEL_REGEX.test(label)) {
+        return reply
+          .code(400)
+          .send({ error: 'Agent label could not be determined from client certificate' });
+      }
+      const facts = HostFactsSchema.parse(request.body);
+      try {
+        await setAgentHostFacts(label, facts);
+      } catch (err) {
+        const status = err.statusCode || 500;
+        return reply.code(status).send({ error: err.message || 'Failed to store host facts' });
+      }
+      request.log.info(
+        { label, os: facts.os, arch: facts.arch, apphost: facts.apphost?.version ?? null },
+        'Agent reported host facts',
+      );
+      return { ok: true };
+    },
+  );
+
   // ------------------------------------------------------------------
   // GET /agents/me/capabilities
   //
@@ -234,6 +458,43 @@ export default async function agentsRoutes(fastify, _opts) {
     },
   );
 
+  // ------------------------------------------------------------------
+  // GET /agents/me/relay-keys
+  //
+  // The public keys relay assertions are signed with
+  // (`X-Lamalibre-Relay-Assertion`, see relay-assertion.ts), and the label
+  // this relay knows the calling agent by — the audience of the assertions
+  // made for it, which the agent's local registry name need not equal.
+  // lamaste-agentd fetches both over its pinned mTLS channel and accepts a
+  // request from the relay only with an assertion one of the keys verifies,
+  // made for that label. `sudo lamaste-agent apphost enable|pin` pins the
+  // first key, and the label, for the agent's root helper, which runs only
+  // the app jobs this relay signed with it (app-job-signature.ts). The keys
+  // are public material: any agent or admin certificate may read them
+  // (`agentLabel` is null for non-agent callers).
+  // ------------------------------------------------------------------
+  fastify.get(
+    '/agents/me/relay-keys',
+    {
+      preHandler: fastify.requireRole(['admin', 'agent']),
+      config: { rateLimit: { max: 60, timeWindow: '1 minute' } },
+    },
+    async (request, reply) => {
+      try {
+        return {
+          keys: await relayVerifyKeys(),
+          agentLabel: request.certRole === 'agent' ? request.certLabel : null,
+        };
+      } catch (err) {
+        request.log.error(
+          { err: err instanceof Error ? err.message : String(err) },
+          'Relay signing key unusable',
+        );
+        return reply.code(503).send({ error: 'Relay signing key unavailable' });
+      }
+    },
+  );
+
   // ------------------------------------------------------------------
   // POST /agents/:label/chisel-credential/rotate (admin only)
   //

package/vendor/serverd/src/routes/management/audit.js

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+import { listAudit } from '../../lib/audit.js';
+import { listNotifications, markNotificationsRead } from '../../lib/notifications.js';
+
+const AuditQuerySchema = z.object({
+  plugin: z
+    .string()
+    .regex(/^[a-z0-9-]{1,100}$/)
+    .optional(),
+  action: z
+    .string()
+    .regex(/^[a-z][a-z0-9.-]{0,99}$/)
+    .optional(),
+  before: z.coerce.number().int().positive().optional(),
+  limit: z.coerce.number().int().min(1).max(200).optional(),
+});
+
+const NotificationsQuerySchema = z.object({
+  unread: z.enum(['true', 'false']).optional(),
+  before: z.coerce.number().int().positive().optional(),
+  limit: z.coerce.number().int().min(1).max(200).optional(),
+});
+
+const MarkReadBodySchema = z.union([
+  z.object({ all: z.literal(true) }).strict(),
+  z.object({ ids: z.array(z.number().int().positive()).min(1).max(200) }).strict(),
+]);
+
+export default async function auditRoutes(fastify, _opts) {
+  // ------------------------------------------------------------------
+  // GET /audit — the audit log, newest first (?plugin, ?action — exact or
+  // a prefix ending in ".", ?before=<id>, ?limit)
+  // ------------------------------------------------------------------
+  fastify.get(
+    '/audit',
+    {
+      preHandler: fastify.requireRole(['admin']),
+    },
+    async (request) => {
+      const query = AuditQuerySchema.parse(request.query);
+      const entries = await listAudit(query);
+      return { entries };
+    },
+  );
+
+  // ------------------------------------------------------------------
+  // GET /notifications — panel notifications, newest first, and the
+  // unread count
+  // ------------------------------------------------------------------
+  fastify.get(
+    '/notifications',
+    {
+      preHandler: fastify.requireRole(['admin']),
+    },
+    async (request) => {
+      const query = NotificationsQuerySchema.parse(request.query);
+      return listNotifications({
+        unreadOnly: query.unread === 'true',
+        before: query.before,
+        limit: query.limit,
+      });
+    },
+  );
+
+  // ------------------------------------------------------------------
+  // POST /notifications/read — { ids: [...] } or { all: true }
+  // ------------------------------------------------------------------
+  fastify.post(
+    '/notifications/read',
+    {
+      preHandler: fastify.requireRole(['admin']),
+    },
+    async (request) => {
+      const body = MarkReadBodySchema.parse(request.body);
+      const changed = await markNotificationsRead(
+        'all' in body ? { all: true } : { ids: body.ids },
+      );
+      return { ok: true, changed };
+    },
+  );
+}

package/vendor/serverd/src/routes/management/certs.js

@@ -25,6 +25,7 @@ import { getConfig, updateConfig } from '../../lib/config.js';
 import { addToRevocationList } from '../../lib/revocation.js';
 import { agentOwnsInstanceForScope } from '../../lib/tickets.js';
 import * as nginx from '../../lib/nginx.js';
+import { actorFromRequest } from '../../lib/actor.js';
 
 const DomainParamSchema = z.object({
   domain: z
@@ -142,21 +143,6 @@ const DelegatedEnrollBodySchema = z.object({
     ),
 });
 
-/**
- * Derive a stable audit identifier for the calling principal.
- *
- * Returns the certificate CN form (`admin`, `agent:<label>`, `plugin-agent:...`)
- * so a journalctl reader can correlate cert lifecycle events with the
- * principal that initiated them. Returns `'unknown'` when middleware did not
- * populate cert metadata (e.g. dev mode shortcut on /api/health).
- */
-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';
-}
-
 /**
  * Parse certbot listing results into the unified cert response format.
  */