@lamalibre/create-lamaste 4.4.1 → 4.5.0

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

@@ -1,20 +1,21 @@
 import crypto from 'node:crypto';
 import { z } from 'zod';
-import { readInvitations, writeInvitations } from '../../lib/state.js';
+import { USERNAME_MAX_LENGTH, USERNAME_MIN_LENGTH, USERNAME_REGEX } from '@lamalibre/lamaste';
+import { readInvitations, withInvitationsLock, writeInvitations } from '../../lib/state.js';
 import { readUsersRaw } from '../../lib/authelia.js';
 import { getConfig } from '../../lib/config.js';
 
 const IdParamSchema = z.object({ id: z.string().uuid() });
 
 const CreateInvitationSchema = z.object({
+  // Same rule as the users API (core's USERNAME_REGEX). A leading "-" would
+  // read as a flag to Authelia's CLI when a TOTP secret is stored for the user.
   username: z
     .string()
-    .min(2)
-    .max(32)
+    .min(USERNAME_MIN_LENGTH)
+    .max(USERNAME_MAX_LENGTH)
     .regex(
-      // Same rule as the users API. A leading "-" would read as a flag to
-      // Authelia's CLI when a TOTP secret is stored for the user.
-      /^[a-z0-9][a-z0-9_-]*$/,
+      USERNAME_REGEX,
       'Username must start with a lowercase letter or digit and may contain underscores or hyphens',
     ),
   email: z.string().email(),
@@ -67,50 +68,55 @@ export default async function invitationRoutes(fastify, _opts) {
         return reply.code(409).send({ error: 'Username already exists as an Authelia user' });
       }
 
-      // Check username doesn't already have a pending invitation
-      let invitations;
-      try {
-        invitations = await readInvitations();
-      } catch (err) {
-        request.log.error(err, 'Failed to read invitations');
-        return reply.code(500).send({ error: 'Failed to read invitations' });
-      }
+      // The pending-invitation check and the write hold the invitations
+      // lock: nothing else may rewrite the file between them.
+      const outcome = await withInvitationsLock(async () => {
+        let invitations;
+        try {
+          invitations = await readInvitations();
+        } catch (err) {
+          request.log.error(err, 'Failed to read invitations');
+          return { status: 500, body: { error: 'Failed to read invitations' } };
+        }
 
-      const now = new Date();
-      const existingPending = invitations.find(
-        (inv) => inv.username === body.username && !inv.used && new Date(inv.expiresAt) > now,
-      );
-      if (existingPending) {
-        return reply
-          .code(409)
-          .send({ error: 'A pending invitation already exists for this username' });
-      }
+        const now = new Date();
+        const existingPending = invitations.find(
+          (inv) => inv.username === body.username && !inv.used && new Date(inv.expiresAt) > now,
+        );
+        if (existingPending) {
+          return {
+            status: 409,
+            body: { error: 'A pending invitation already exists for this username' },
+          };
+        }
+
+        const expiresAt = new Date(now.getTime() + body.expiresInDays * 24 * 60 * 60 * 1000);
+        const invitation = {
+          id: crypto.randomUUID(),
+          token: crypto.randomBytes(32).toString('hex'),
+          username: body.username,
+          email: body.email,
+          groups: body.groups,
+          createdAt: now.toISOString(),
+          expiresAt: expiresAt.toISOString(),
+          used: false,
+          acceptedAt: null,
+        };
+        invitations.push(invitation);
+
+        try {
+          await writeInvitations(invitations);
+        } catch (err) {
+          request.log.error(err, 'Failed to write invitations');
+          return { status: 500, body: { error: 'Failed to save invitation' } };
+        }
+        return { status: 201, invitation };
+      });
+      if (outcome.status !== 201) return reply.code(outcome.status).send(outcome.body);
 
+      const { invitation } = outcome;
+      const { token } = invitation;
       const config = getConfig();
-      const token = crypto.randomBytes(32).toString('hex');
-      const expiresAt = new Date(now.getTime() + body.expiresInDays * 24 * 60 * 60 * 1000);
-
-      const invitation = {
-        id: crypto.randomUUID(),
-        token,
-        username: body.username,
-        email: body.email,
-        groups: body.groups,
-        createdAt: now.toISOString(),
-        expiresAt: expiresAt.toISOString(),
-        used: false,
-        acceptedAt: null,
-      };
-
-      invitations.push(invitation);
-
-      try {
-        await writeInvitations(invitations);
-      } catch (err) {
-        request.log.error(err, 'Failed to write invitations');
-        return reply.code(500).send({ error: 'Failed to save invitation' });
-      }
-
       const inviteUrl = config.domain ? `https://auth.${config.domain}/invite/${token}` : null;
 
       return reply.code(201).send({
@@ -138,27 +144,31 @@ export default async function invitationRoutes(fastify, _opts) {
     async (request, reply) => {
       const { id } = IdParamSchema.parse(request.params);
 
-      let invitations;
-      try {
-        invitations = await readInvitations();
-      } catch (err) {
-        request.log.error(err, 'Failed to read invitations');
-        return reply.code(500).send({ error: 'Failed to read invitations' });
-      }
-
-      const index = invitations.findIndex((inv) => inv.id === id);
-      if (index === -1) {
-        return reply.code(404).send({ error: 'Invitation not found' });
-      }
-
-      invitations.splice(index, 1);
-
-      try {
-        await writeInvitations(invitations);
-      } catch (err) {
-        request.log.error(err, 'Failed to write invitations');
-        return reply.code(500).send({ error: 'Failed to revoke invitation' });
-      }
+      const outcome = await withInvitationsLock(async () => {
+        let invitations;
+        try {
+          invitations = await readInvitations();
+        } catch (err) {
+          request.log.error(err, 'Failed to read invitations');
+          return { status: 500, body: { error: 'Failed to read invitations' } };
+        }
+
+        const index = invitations.findIndex((inv) => inv.id === id);
+        if (index === -1) {
+          return { status: 404, body: { error: 'Invitation not found' } };
+        }
+
+        invitations.splice(index, 1);
+
+        try {
+          await writeInvitations(invitations);
+        } catch (err) {
+          request.log.error(err, 'Failed to write invitations');
+          return { status: 500, body: { error: 'Failed to revoke invitation' } };
+        }
+        return { status: 200 };
+      });
+      if (outcome.status !== 200) return reply.code(outcome.status).send(outcome.body);
 
       return { ok: true };
     },

package/vendor/serverd/src/routes/management/plugin-identity.js

@@ -0,0 +1,221 @@
+/**
+ * A plugin's users (slice 6): what its identity block declares, who is
+ * entitled to it with which roles, its audience as the agent half is told,
+ * and the feed that tells it. Admin only. Business logic lives in
+ * `lib/entitlements.js`, `lib/audience.js` and `lib/identity-sync.js`.
+ *
+ *   GET    /plugins/:name/identity        declared block, approval, readiness,
+ *                                         sync state, audience counts, pending erasures
+ *   GET    /plugins/:name/audience        members and tombstones, in seq order
+ *   GET    /plugins/:name/entitlements    role grants (and how many grants carry no roles)
+ *   PUT    /plugins/:name/entitlements    { principalType, principalId, roles }
+ *   DELETE /plugins/:name/entitlements?principalType=&principalId=
+ *   POST   /plugins/:name/identity/sync   { reconcile? } — sync now
+ */
+
+import { z } from 'zod';
+import { USERNAME_MAX_LENGTH, USERNAME_MIN_LENGTH, USERNAME_REGEX } from '@lamalibre/lamaste';
+import { actorFromRequest } from '../../lib/actor.js';
+import { listAudience } from '../../lib/audience.js';
+import { listEntitlements, removeEntitlement, setEntitlement } from '../../lib/entitlements.js';
+import { identityView, syncPluginIdentity } from '../../lib/identity-sync.js';
+import { hookStatus } from '../../lib/plugin-hooks.js';
+import { findPlugin } from '../../lib/plugins.js';
+
+const PluginNameParamSchema = z.object({
+  name: z
+    .string()
+    .min(1)
+    .max(100)
+    .regex(/^[a-z0-9-]+$/, 'Plugin name must contain only lowercase letters, numbers, and hyphens'),
+});
+
+/** A user principal is a username, a group principal a Lamaste group name (Gatekeeper's rule). */
+const USER_PRINCIPAL = {
+  principalType: z.literal('user'),
+  principalId: z
+    .string()
+    .min(USERNAME_MIN_LENGTH)
+    .max(USERNAME_MAX_LENGTH)
+    .regex(USERNAME_REGEX, 'principalId is a username'),
+};
+const GROUP_PRINCIPAL = {
+  principalType: z.literal('group'),
+  principalId: z
+    .string()
+    .min(2)
+    .max(63)
+    .regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, 'principalId is a group name'),
+};
+/** Role ids are checked against the manifest by the library. */
+const ROLES = z.array(z.string().min(1).max(32)).min(1).max(32);
+
+const PrincipalSchema = z.discriminatedUnion('principalType', [
+  z.object(USER_PRINCIPAL).strict(),
+  z.object(GROUP_PRINCIPAL).strict(),
+]);
+
+const EntitlementBodySchema = z.discriminatedUnion('principalType', [
+  z.object({ ...USER_PRINCIPAL, roles: ROLES }).strict(),
+  z.object({ ...GROUP_PRINCIPAL, roles: ROLES }).strict(),
+]);
+
+const SyncBodySchema = z.object({ reconcile: z.boolean().optional() }).strict();
+
+/** The refusal a library threw (its `statusCode`, message and `code`), or a 500. */
+function sendFailure(request, reply, err, fallback) {
+  if (Number.isInteger(err.statusCode)) {
+    return reply.code(err.statusCode).send({
+      error: err.message,
+      ...(err.code ? { code: err.code } : {}),
+      ...(Array.isArray(err.unknown) ? { unknown: err.unknown } : {}),
+    });
+  }
+  request.log.error(err, fallback);
+  return reply.code(500).send({ error: fallback });
+}
+
+/** The installed plugin, answering 404 (not installed) or 400 `no_identity` (when it must declare identity). */
+async function pluginFor(request, reply, { requireIdentity }) {
+  const { name } = PluginNameParamSchema.parse(request.params);
+  const plugin = await findPlugin(name);
+  if (!plugin) {
+    reply.code(404).send({ error: `Plugin "${name}" not found` });
+    return null;
+  }
+  if (requireIdentity && !plugin.identity) {
+    reply
+      .code(400)
+      .send({ error: `Plugin "${name}" declares no identity (roles)`, code: 'no_identity' });
+    return null;
+  }
+  return plugin;
+}
+
+export default async function pluginIdentityRoutes(fastify, _opts) {
+  fastify.get(
+    '/plugins/:name/identity',
+    { preHandler: fastify.requireRole(['admin']) },
+    async (request, reply) => {
+      const plugin = await pluginFor(request, reply, { requireIdentity: false });
+      if (!plugin) return reply;
+      const [view, hooks] = await Promise.all([identityView(plugin.name), hookStatus(plugin)]);
+      return {
+        identity: {
+          ...view,
+          approval: { approved: hooks.identity.approved, state: hooks.approval.state },
+        },
+      };
+    },
+  );
+
+  fastify.get(
+    '/plugins/:name/audience',
+    { preHandler: fastify.requireRole(['admin']) },
+    async (request, reply) => {
+      const plugin = await pluginFor(request, reply, { requireIdentity: true });
+      if (!plugin) return reply;
+      const rows = await listAudience(plugin.name);
+      return {
+        head: rows.reduce((head, row) => Math.max(head, row.seq), 0),
+        audience: rows.map((row) => ({
+          userId: row.userId,
+          seq: row.seq,
+          version: row.version,
+          updatedAt: row.updatedAt,
+          change: row.change,
+        })),
+      };
+    },
+  );
+
+  fastify.get(
+    '/plugins/:name/entitlements',
+    { preHandler: fastify.requireRole(['admin']) },
+    async (request, reply) => {
+      const plugin = await pluginFor(request, reply, { requireIdentity: true });
+      if (!plugin) return reply;
+      try {
+        return await listEntitlements(plugin);
+      } catch (err) {
+        return sendFailure(request, reply, err, 'Failed to read the entitlements');
+      }
+    },
+  );
+
+  fastify.put(
+    '/plugins/:name/entitlements',
+    {
+      preHandler: fastify.requireRole(['admin']),
+      config: { rateLimit: { max: 30, timeWindow: '1 minute' } },
+    },
+    async (request, reply) => {
+      const plugin = await pluginFor(request, reply, { requireIdentity: true });
+      if (!plugin) return reply;
+      const body = EntitlementBodySchema.parse(request.body);
+      try {
+        const result = await setEntitlement(plugin, body, {
+          actor: actorFromRequest(request),
+          logger: request.log,
+        });
+        return {
+          ok: true,
+          entitlement: result.entitlement,
+          changed: result.changed,
+          ...(result.warnings.length > 0 ? { warnings: result.warnings } : {}),
+        };
+      } catch (err) {
+        return sendFailure(request, reply, err, 'Failed to set the entitlement');
+      }
+    },
+  );
+
+  fastify.delete(
+    '/plugins/:name/entitlements',
+    {
+      preHandler: fastify.requireRole(['admin']),
+      config: { rateLimit: { max: 30, timeWindow: '1 minute' } },
+    },
+    async (request, reply) => {
+      const plugin = await pluginFor(request, reply, { requireIdentity: true });
+      if (!plugin) return reply;
+      const principal = PrincipalSchema.parse(request.query ?? {});
+      try {
+        const result = await removeEntitlement(plugin, principal, {
+          actor: actorFromRequest(request),
+          logger: request.log,
+        });
+        return {
+          ok: true,
+          revoked: result.revoked,
+          ...(result.warnings.length > 0 ? { warnings: result.warnings } : {}),
+        };
+      } catch (err) {
+        return sendFailure(request, reply, err, 'Failed to remove the entitlement');
+      }
+    },
+  );
+
+  fastify.post(
+    '/plugins/:name/identity/sync',
+    {
+      preHandler: fastify.requireRole(['admin']),
+      config: { rateLimit: { max: 10, timeWindow: '1 minute' } },
+    },
+    async (request, reply) => {
+      const plugin = await pluginFor(request, reply, { requireIdentity: true });
+      if (!plugin) return reply;
+      const body = SyncBodySchema.parse(request.body ?? {});
+      const result = await syncPluginIdentity(plugin.name, {
+        reconcile: body.reconcile === true,
+        logger: request.log,
+      });
+      const view = await identityView(plugin.name);
+      return {
+        ok: result.status === 'synced' || result.status === 'up-to-date',
+        result,
+        sync: view?.sync ?? null,
+      };
+    },
+  );
+}

package/vendor/serverd/src/routes/management/registry-credential.js

@@ -4,7 +4,7 @@
  *   GET    /api/registry-credential   what is configured — never a token
  *   PUT    /api/registry-credential   store a credential after verifying the
  *                                     whole chain against the registry
- *                                     (admin scope required)
+ *                                     (read + admin scopes required)
  *   DELETE /api/registry-credential   remove it
  *
  * `auth.kind` is `token` (a pasted long-lived Feria token) or `oidc` (the

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

@@ -5,6 +5,15 @@
  * under the tunnel-state lock. Read-only endpoints and HTTP-specific auth
  * checks remain here; checks that depend on the tunnel's current state run
  * inside the lock through the workflows' `authorize` hook.
+ *
+ * A tunnel may serve agent-hosted plugins' user surfaces (slice 6, admin
+ * only; `lib/user-surface.js`):
+ *
+ *   PUT    /tunnels/:id/user-surface          { route } — bind
+ *   DELETE /tunnels/:id/user-surface/:route   unbind
+ *
+ * Listings carry the binding (`userSurface: { routes }`) and how each bound
+ * route is served (`userSurfaceStatus`).
  */
 import { z } from 'zod';
 import {
@@ -30,6 +39,14 @@ import { buildChiselArgs } from '../../lib/chisel-args.js';
 import { listAgentPluginAssignments } from '../../lib/plugin-hosting.js';
 import { pendingAgentJobs } from '../../lib/agent-jobs.js';
 import { recordAgentContact } from '../../lib/agent-presence.js';
+import { actorFromRequest } from '../../lib/actor.js';
+import {
+  auditDeletedTunnelUserSurface,
+  bindTunnelUserSurface,
+  unbindTunnelUserSurface,
+  userSurfaceDeps,
+  withUserSurfaceStatus,
+} from '../../lib/user-surface.js';
 import {
   tunnelNginxDeps,
   tunnelCertbotDeps,
@@ -39,6 +56,20 @@ import {
 
 const IdParamSchema = z.object({ id: z.string().uuid() });
 
+/** A plugin route, as a user surface is bound for it (core `isUserSurfaceRoute` decides the rest). */
+const UserSurfaceRouteSchema = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, 'route must be a plugin route');
+
+const UserSurfaceBodySchema = z.object({ route: UserSurfaceRouteSchema }).strict();
+
+const UserSurfaceParamsSchema = z.object({ id: z.string().uuid(), route: UserSurfaceRouteSchema });
+
+/** Binding and unbinding rewrite a vhost and reload nginx. */
+const USER_SURFACE_WRITE_RATE_LIMIT = { rateLimit: { max: 30, timeWindow: '1 minute' } };
+
 const TunnelPortSchema = z
   .number()
   .int('Port must be an integer')
@@ -215,11 +246,30 @@ function tunnelErrorStatus(code) {
       return 403;
     case 'NOT_FOUND':
       return 404;
+    case 'USER_SURFACE_CONFLICT':
+      return 409;
     default:
       return 500;
   }
 }
 
+/** A refused or failed user-surface change: the workflow's status, or a 500. */
+function sendUserSurfaceFailure(request, reply, err, fallback) {
+  if (err instanceof TunnelError) {
+    const status = tunnelErrorStatus(err.code);
+    return reply.code(status).send({
+      error: status === 500 ? fallback : err.message,
+      ...(status === 500 ? { details: err.message } : {}),
+      ...(err.code === 'USER_SURFACE_CONFLICT' ? { code: 'user_surface_conflict' } : {}),
+    });
+  }
+  if (Number.isInteger(err.statusCode)) {
+    return reply.code(err.statusCode).send({ error: err.message });
+  }
+  request.log.error(err, fallback);
+  return reply.code(500).send({ error: fallback, details: err.message });
+}
+
 export default async function tunnelRoutes(fastify, _opts) {
   const nginxDeps = tunnelNginxDeps;
   const certbotDeps = tunnelCertbotDeps;
@@ -348,7 +398,9 @@ export default async function tunnelRoutes(fastify, _opts) {
       });
 
       const total = tunnels.length;
-      const windowed = tunnels.slice(offset, offset + limit);
+      const windowed = await Promise.all(
+        tunnels.slice(offset, offset + limit).map((t) => withUserSurfaceStatus(t)),
+      );
 
       return { tunnels: windowed, total, limit, offset };
     },
@@ -547,6 +599,7 @@ export default async function tunnelRoutes(fastify, _opts) {
           chisel: chiselDeps,
           state: stateDeps,
           agents: agentDeps,
+          userSurface: userSurfaceDeps,
           logger: request.log,
           authorize: authorizeFor(request, 'change'),
         });
@@ -577,7 +630,7 @@ export default async function tunnelRoutes(fastify, _opts) {
       const { id } = IdParamSchema.parse(request.params);
 
       try {
-        await deleteTunnel({
+        const { tunnel } = await deleteTunnel({
           id,
           nginx: nginxDeps,
           chisel: chiselDeps,
@@ -585,6 +638,11 @@ export default async function tunnelRoutes(fastify, _opts) {
           logger: request.log,
           authorize: authorizeFor(request, 'delete'),
         });
+        // Its user-surface bindings went with it.
+        await auditDeletedTunnelUserSurface(tunnel, {
+          actor: actorFromRequest(request),
+          logger: request.log,
+        });
         return { ok: true };
       } catch (err) {
         if (err instanceof TunnelError) {
@@ -603,6 +661,44 @@ export default async function tunnelRoutes(fastify, _opts) {
     },
   );
 
+  // PUT /api/tunnels/:id/user-surface — serve a plugin's user surface on this
+  // tunnel's host (from when its installed, approved version declares identity)
+  fastify.put(
+    '/tunnels/:id/user-surface',
+    { preHandler: fastify.requireRole(['admin']), config: USER_SURFACE_WRITE_RATE_LIMIT },
+    async (request, reply) => {
+      const { id } = IdParamSchema.parse(request.params);
+      const { route } = UserSurfaceBodySchema.parse(request.body);
+      try {
+        const { changed, tunnel } = await bindTunnelUserSurface(id, route, {
+          actor: actorFromRequest(request),
+          logger: request.log,
+        });
+        return { ok: true, changed, tunnel };
+      } catch (err) {
+        return sendUserSurfaceFailure(request, reply, err, 'Failed to bind the user surface');
+      }
+    },
+  );
+
+  // DELETE /api/tunnels/:id/user-surface/:route — stop serving it there
+  fastify.delete(
+    '/tunnels/:id/user-surface/:route',
+    { preHandler: fastify.requireRole(['admin']), config: USER_SURFACE_WRITE_RATE_LIMIT },
+    async (request, reply) => {
+      const { id, route } = UserSurfaceParamsSchema.parse(request.params);
+      try {
+        const { tunnel } = await unbindTunnelUserSurface(id, route, {
+          actor: actorFromRequest(request),
+          logger: request.log,
+        });
+        return { ok: true, tunnel };
+      } catch (err) {
+        return sendUserSurfaceFailure(request, reply, err, 'Failed to unbind the user surface');
+      }
+    },
+  );
+
   // GET /api/tunnels/agent-panel-status — check if agent has a panel tunnel
   fastify.get(
     '/tunnels/agent-panel-status',