@lamalibre/create-lamaste 4.4.1 → 4.6.0

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/plugin-web-surface.js

@@ -0,0 +1,151 @@
+/**
+ * A plugin's web surface (slice 7): the site it owns, where the relay
+ * serves the shell its server package ships beside its user surface's API.
+ * Admin only. Business logic lives in `lib/web-surface.js`.
+ *
+ *   GET    /plugins/:name/web-surface        what the installed version declares, the
+ *                                            site, whether it is served, the trees, the offer
+ *   POST   /plugins/:name/web-surface        { subdomain?, accessMode? } — create the site
+ *   POST   /plugins/:name/web-surface/move   { tunnelId } — take over the bound tunnel's host
+ *   DELETE /plugins/:name/web-surface        delete the site and its trees
+ */
+
+import { z } from 'zod';
+import { WEB_SURFACE_ACCESS_MODES, derivePluginRoute } from '@lamalibre/lamaste';
+import { actorFromRequest } from '../../lib/actor.js';
+import { findPlugin } from '../../lib/plugins.js';
+import {
+  createWebSurface,
+  deleteWebSurface,
+  moveWebSurfaceFromTunnel,
+  webSurfaceStatus,
+} from '../../lib/web-surface.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'),
+});
+
+const CreateBodySchema = z
+  .object({
+    subdomain: z
+      .string()
+      .min(1)
+      .max(63)
+      .regex(/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/, 'subdomain is a DNS label')
+      .optional(),
+    accessMode: z.enum(WEB_SURFACE_ACCESS_MODES).optional(),
+  })
+  .strict();
+
+const MoveBodySchema = z.object({ tunnelId: z.string().min(1).max(64) }).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) && err.statusCode < 500) {
+    return reply
+      .code(err.statusCode)
+      .send({ error: err.message, ...(err.code ? { code: err.code } : {}) });
+  }
+  request.log.error(err, fallback);
+  return reply
+    .code(Number.isInteger(err.statusCode) ? err.statusCode : 500)
+    .send({ error: fallback, details: err.message });
+}
+
+/**
+ * The route plugin `:name` holds: the installed plugin's, else the one its
+ * name derives — a site outlives its plugin, and its status and deletion
+ * stay reachable (creating or moving refuses without an installed plugin).
+ */
+async function routeOf(request) {
+  const { name } = PluginNameParamSchema.parse(request.params);
+  const plugin = await findPlugin(name);
+  return plugin?.route ?? derivePluginRoute(name);
+}
+
+export default async function pluginWebSurfaceRoutes(fastify, _opts) {
+  fastify.get(
+    '/plugins/:name/web-surface',
+    { preHandler: fastify.requireRole(['admin']) },
+    async (request, reply) => {
+      const route = await routeOf(request);
+      try {
+        return { webSurface: await webSurfaceStatus(route) };
+      } catch (err) {
+        return sendFailure(request, reply, err, 'Failed to read the web surface');
+      }
+    },
+  );
+
+  fastify.post(
+    '/plugins/:name/web-surface',
+    {
+      preHandler: fastify.requireRole(['admin']),
+      // Issues a certificate and reloads nginx.
+      config: { rateLimit: { max: 10, timeWindow: '1 minute' } },
+    },
+    async (request, reply) => {
+      const route = await routeOf(request);
+      const body = CreateBodySchema.parse(request.body ?? {});
+      try {
+        const webSurface = await createWebSurface(route, body, {
+          actor: actorFromRequest(request),
+          logger: request.log,
+        });
+        return reply.code(201).send({ webSurface });
+      } catch (err) {
+        return sendFailure(request, reply, err, 'Failed to create the web surface');
+      }
+    },
+  );
+
+  fastify.post(
+    '/plugins/:name/web-surface/move',
+    {
+      preHandler: fastify.requireRole(['admin']),
+      config: { rateLimit: { max: 10, timeWindow: '1 minute' } },
+    },
+    async (request, reply) => {
+      const route = await routeOf(request);
+      const { tunnelId } = MoveBodySchema.parse(request.body);
+      try {
+        return {
+          webSurface: await moveWebSurfaceFromTunnel(route, tunnelId, {
+            actor: actorFromRequest(request),
+            logger: request.log,
+          }),
+        };
+      } catch (err) {
+        return sendFailure(
+          request,
+          reply,
+          err,
+          'Failed to move the user surface to the web surface',
+        );
+      }
+    },
+  );
+
+  fastify.delete(
+    '/plugins/:name/web-surface',
+    {
+      preHandler: fastify.requireRole(['admin']),
+      config: { rateLimit: { max: 10, timeWindow: '1 minute' } },
+    },
+    async (request, reply) => {
+      const route = await routeOf(request);
+      try {
+        return await deleteWebSurface(route, {
+          actor: actorFromRequest(request),
+          logger: request.log,
+        });
+      } catch (err) {
+        return sendFailure(request, reply, err, 'Failed to delete the web surface');
+      }
+    },
+  );
+}

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

@@ -301,6 +301,8 @@ async function withHooks(plugin) {
       agent: status.agent !== null,
       // Lamaste installs the agent half (agent.package); false: none, or installed by hand.
       agentHalf: status.agentHalf !== null,
+      // The installed version declares a web surface (its tree is in the approval).
+      web: status.web.declared,
       approval: status.approval.state,
       autoApprove: status.autoApprove,
       failOpenCount: status.relay?.failOpenCount ?? 0,

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