@lamalibre/create-lamaste 4.0.0 → 4.1.0

package/vendor/serverd/src/lib/plugin-oidc.js

@@ -0,0 +1,216 @@
+/**
+ * OIDC clients → Authelia.
+ *
+ * Two sources declare clients on the relay's Authelia:
+ *
+ * - every installed server plugin may declare them in its manifest
+ *   (`oidcClients`, see the core `ManifestSchema`); only the clients of
+ *   enabled plugins are served;
+ * - the panel itself declares the confidential `lamaste-server` client
+ *   when the registry credential uses `auth.kind: 'oidc'`.
+ *
+ * After any plugin lifecycle change, or a registry-credential change, the
+ * set is recomputed, the secrets of confidential clients are reconciled
+ * (`oidc-clients.json`: minted on first appearance, deleted when a client is
+ * gone — a secret belongs to an installed plugin, enabled or not, so
+ * disabling a plugin does not rotate it) and Authelia's
+ * `identity_providers.oidc` section is written; Authelia is restarted only
+ * when the section actually changed.
+ *
+ * Best effort by design where a plugin lifecycle calls it: a failure here
+ * must not fail the plugin operation — the caller logs it and the next
+ * lifecycle change retries.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { validateManifest } from '@lamalibre/lamaste';
+import {
+  LAMASTE_REGISTRY_OIDC_SCOPES,
+  lamasteServerOidcClient,
+  listOidcClientSecrets,
+  reconcileOidcClientSecrets,
+  readOidcClientSecretDigests,
+  rotateOidcClientSecret,
+} from '@lamalibre/lamaste/server';
+
+import { getConfig } from './config.js';
+import { updateOidcProvider } from './authelia.js';
+import { readPlugins } from './plugins.js';
+import { readRegistryCredentialConfig } from './registry-credential.js';
+
+const STATE_DIR = process.env.LAMALIBRE_LAMASTE_STATE_DIR || '/etc/lamalibre/lamaste';
+
+/**
+ * The OIDC clients every installed plugin declares, tagged with the plugin
+ * name and whether the plugin is enabled. Manifests are re-read from the
+ * installed packages — the plugin registry does not store them.
+ * @returns {Promise<Array<import('@lamalibre/lamaste/server').AutheliaOidcClient & { enabled: boolean }>>}
+ */
+export async function collectPluginOidcClients() {
+  const require = createRequire(`${STATE_DIR}/`);
+  const clients = [];
+  for (const plugin of (await readPlugins()).plugins) {
+    let manifest;
+    try {
+      const manifestPath = require.resolve(`${plugin.packageName}/lamaste-plugin.json`);
+      manifest = validateManifest(JSON.parse(await readFile(manifestPath, 'utf-8')));
+    } catch {
+      continue; // an unreadable manifest contributes no clients
+    }
+    for (const client of manifest.oidcClients) {
+      clients.push({ ...client, plugin: manifest.name, enabled: plugin.status === 'enabled' });
+    }
+  }
+  return clients;
+}
+
+/**
+ * The panel's own client, when the registry credential (stored, or the
+ * candidate being verified) uses it.
+ * @param {{ registryUrl: string } | null | undefined} registryAuth
+ */
+function lamasteOwnClient(registryAuth) {
+  if (!registryAuth) return [];
+  return [{ ...lamasteServerOidcClient(registryAuth.registryUrl), enabled: true }];
+}
+
+/**
+ * Everything Authelia should know, from the stored state.
+ * @param {{ registryAuth?: { registryUrl: string } | null }} [overrides]
+ *   `registryAuth` replaces the stored registry credential's say in the
+ *   matter: `{ registryUrl }` while a candidate oidc credential is being
+ *   verified, `null` to leave the panel's client out.
+ */
+async function collectAllClients(overrides = {}) {
+  let registryAuth;
+  if (overrides.registryAuth !== undefined) {
+    registryAuth = overrides.registryAuth;
+  } else {
+    const stored = await readRegistryCredentialConfig().catch(() => null);
+    registryAuth =
+      stored && stored.auth.kind === 'oidc' ? { registryUrl: stored.registryUrl } : null;
+  }
+  return [...(await collectPluginOidcClients()), ...lamasteOwnClient(registryAuth)];
+}
+
+/**
+ * Sync Authelia's OIDC clients and the secret store with the plugins and
+ * the registry credential. Returns what was done, or `null` when the panel
+ * has no domain yet (onboarding).
+ *
+ * @param {import('pino').Logger} logger
+ * @param {{ registryAuth?: { registryUrl: string } | null }} [overrides] see collectAllClients
+ * @returns {Promise<{ changed: boolean, clients: string[], createdSecrets: Array<{ id: string, plugin: string, secret: string }> } | null>}
+ */
+export async function syncOidcClients(logger, overrides = {}) {
+  let domain = null;
+  try {
+    domain = getConfig().domain;
+  } catch {
+    domain = null;
+  }
+  if (!domain) {
+    logger.debug('OIDC client sync skipped — no domain configured yet');
+    return null;
+  }
+
+  const all = await collectAllClients(overrides);
+  const reconciled = await reconcileOidcClientSecrets(
+    STATE_DIR,
+    all.filter((c) => c.confidential).map((c) => ({ id: c.id, plugin: c.plugin })),
+  );
+  if (reconciled.created.length > 0 || reconciled.removed.length > 0) {
+    logger.info(
+      { created: reconciled.created.map((c) => c.id), removed: reconciled.removed },
+      'OIDC client secrets reconciled',
+    );
+  }
+
+  const served = all.filter((c) => c.enabled).map(({ enabled: _enabled, ...client }) => client);
+  const scopes = served.some((c) => c.plugin === 'lamaste') ? LAMASTE_REGISTRY_OIDC_SCOPES : {};
+  const result = await updateOidcProvider(domain, served, {
+    secretDigests: reconciled.digests,
+    scopes,
+  });
+  if (result.changed) {
+    logger.info({ clients: served.map((c) => c.id) }, 'Authelia OIDC provider updated');
+  }
+  return {
+    changed: result.changed,
+    clients: served.map((c) => c.id),
+    createdSecrets: reconciled.created,
+  };
+}
+
+/**
+ * Metadata of a plugin's OIDC clients: what the manifest declares, whether
+ * it is served, and — for confidential clients — when the secret was
+ * created and last rotated. Never the secret.
+ * @param {string} pluginName
+ */
+export async function listPluginOidcClients(pluginName) {
+  const declared = (await collectPluginOidcClients()).filter((c) => c.plugin === pluginName);
+  const secrets = new Map((await listOidcClientSecrets(STATE_DIR)).map((m) => [m.id, m]));
+  return declared.map((client) => {
+    const secret = client.confidential ? (secrets.get(client.id) ?? null) : null;
+    return {
+      id: client.id,
+      name: client.name ?? null,
+      confidential: client.confidential,
+      grantTypes: client.grantTypes,
+      scopes: client.scopes,
+      audience: client.audience,
+      accessTokenClaims: client.accessTokenClaims,
+      enabled: client.enabled,
+      secretCreatedAt: secret?.createdAt ?? null,
+      secretRotatedAt: secret?.rotatedAt ?? null,
+    };
+  });
+}
+
+/**
+ * Replace the secret of one of a plugin's confidential clients and write
+ * the new digest to Authelia. Returns the new secret — the only time it is
+ * shown. Throws with `statusCode` 404 for an unknown client and 400 for a
+ * public one.
+ * @param {string} pluginName
+ * @param {string} clientId
+ * @param {import('pino').Logger} logger
+ */
+export async function rotatePluginOidcClientSecret(pluginName, clientId, logger) {
+  const client = (await collectPluginOidcClients()).find(
+    (c) => c.plugin === pluginName && c.id === clientId,
+  );
+  if (!client) {
+    throw Object.assign(new Error(`Plugin "${pluginName}" declares no OIDC client "${clientId}"`), {
+      statusCode: 404,
+    });
+  }
+  if (!client.confidential) {
+    throw Object.assign(new Error(`OIDC client "${clientId}" is public and has no secret`), {
+      statusCode: 400,
+    });
+  }
+  // The store is reconciled first so a client that was never synced (an
+  // earlier Authelia failure) gets its record now.
+  await syncOidcClients(logger);
+  const rotated = await rotateOidcClientSecret(STATE_DIR, clientId);
+  const digests = await readOidcClientSecretDigests(STATE_DIR);
+  if (client.enabled) {
+    const domain = getConfig().domain;
+    const all = await collectAllClients();
+    const served = all.filter((c) => c.enabled).map(({ enabled: _enabled, ...c }) => c);
+    await updateOidcProvider(domain, served, {
+      secretDigests: digests,
+      scopes: served.some((c) => c.plugin === 'lamaste') ? LAMASTE_REGISTRY_OIDC_SCOPES : {},
+    });
+  }
+  logger.info({ plugin: pluginName, clientId }, 'OIDC client secret rotated');
+  return {
+    id: rotated.id,
+    plugin: rotated.plugin,
+    secret: rotated.secret,
+    rotatedAt: rotated.rotatedAt,
+  };
+}

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

@@ -210,6 +210,26 @@ function assertSafeLamalibrePackage(packageName) {
   }
 }
 
+/**
+ * After a lifecycle change, bring Authelia's OIDC clients and the secret
+ * store in line with the installed plugins. Best effort — logged, never
+ * thrown — so a plugin operation does not fail because Authelia could not
+ * be restarted. Returns the secrets of confidential clients this change
+ * created (`[{ id, secret }]`), shown to the admin exactly once.
+ * @param {import('pino').Logger} logger
+ * @returns {Promise<Array<{ id: string, secret: string }>>}
+ */
+async function syncOidcClientsBestEffort(logger) {
+  try {
+    const { syncOidcClients } = await import('./plugin-oidc.js');
+    const result = await syncOidcClients(logger);
+    return (result?.createdSecrets ?? []).map(({ id, secret }) => ({ id, secret }));
+  } catch (err) {
+    logger.warn({ err: err.message }, 'Failed to sync plugin OIDC clients to Authelia');
+    return [];
+  }
+}
+
 export function installPlugin(packageName, logger) {
   return withPluginLock(async () => {
     // Validate package scope
@@ -367,7 +387,8 @@ export function installPlugin(packageName, logger) {
     }
 
     logger.info({ name: manifest.name, packageName }, 'Plugin installed');
-    return entry;
+    const oidcClients = await syncOidcClientsBestEffort(logger);
+    return { ...entry, oidcClients };
   });
 }
 
@@ -436,6 +457,7 @@ export function uninstallPlugin(name, logger) {
     }
 
     logger.info({ name }, 'Plugin uninstalled');
+    await syncOidcClientsBestEffort(logger);
     return { ok: true, name };
   });
 }
@@ -470,7 +492,8 @@ export function enablePlugin(name, logger) {
     }
 
     logger?.info({ name }, 'Plugin enabled');
-    return { ok: true, name, status: 'enabled' };
+    const oidcClients = await syncOidcClientsBestEffort(logger);
+    return { ok: true, name, status: 'enabled', oidcClients };
   });
 }
 
@@ -504,6 +527,7 @@ export function disablePlugin(name, logger) {
     }
 
     logger?.info({ name }, 'Plugin disabled');
+    await syncOidcClientsBestEffort(logger);
     return { ok: true, name, status: 'disabled' };
   });
 }

package/vendor/serverd/src/lib/registry-credential.js

@@ -0,0 +1,145 @@
+/**
+ * Registry credential (Feria) — daemon shim over `@lamalibre/lamaste/server`.
+ *
+ * Binds the core module to this daemon's state directory and holds the
+ * per-process state the core keeps pure:
+ *
+ * - the panel's own registry token (`RegistryServiceTokenCache`): a pasted
+ *   token as is, or — with `auth.kind: 'oidc'` — a Feria token obtained
+ *   through Authelia's client-credentials grant and reused until five
+ *   minutes before it expires;
+ * - one brokered token per agent (`AgentTokenBroker`), reused for every
+ *   install within the hour and limited to ten new tokens per agent per
+ *   hour.
+ *
+ * Also the one piece of policy that belongs here: when a user loses a
+ * `feria-*` group or is deleted, their registry tokens are revoked (best
+ * effort, never blocks the user operation).
+ */
+
+import {
+  readRegistryCredentialConfig as readCore,
+  writeRegistryCredentialConfig as writeCore,
+  clearRegistryCredentialConfig as clearCore,
+  verifyRegistryCredential as verifyCore,
+  brokerAgentRegistryToken,
+  revokeRegistryTokensForOwner,
+  lostFeriaGroups,
+  readOidcClientSecret,
+  RegistryServiceTokenCache,
+  AgentTokenBroker,
+  RegistryCredentialError,
+  LAMASTE_SERVER_OIDC_CLIENT_ID,
+} from '@lamalibre/lamaste/server';
+
+import { getConfig } from './config.js';
+
+const STATE_DIR = process.env.LAMALIBRE_LAMASTE_STATE_DIR || '/etc/lamalibre/lamaste';
+
+const serviceTokens = new RegistryServiceTokenCache();
+const agentTokens = new AgentTokenBroker();
+
+export function readRegistryCredentialConfig() {
+  return readCore(STATE_DIR);
+}
+
+/** Store a credential and forget every token obtained with the previous one. */
+export async function writeRegistryCredentialConfig(config) {
+  await writeCore(STATE_DIR, config);
+  resetRegistryTokenState();
+}
+
+export async function clearRegistryCredentialConfig() {
+  const removed = await clearCore(STATE_DIR);
+  resetRegistryTokenState();
+  return removed;
+}
+
+/** Drop the cached service token and every agent's cached token and issuance record. */
+export function resetRegistryTokenState() {
+  serviceTokens.invalidate();
+  agentTokens.reset();
+}
+
+/**
+ * What the core needs to run the OIDC chain for a credential: the relay
+ * domain and the `lamaste-server` client secret. Pasted-token credentials
+ * need nothing.
+ * @param {{ auth: { kind: string } }} config
+ */
+async function oidcDeps(config) {
+  if (config.auth.kind !== 'oidc') return {};
+  const domain = getConfig().domain;
+  if (!domain) {
+    throw new RegistryCredentialError(
+      'the panel has no domain yet — complete onboarding first',
+      503,
+    );
+  }
+  const clientSecret = await readOidcClientSecret(STATE_DIR, LAMASTE_SERVER_OIDC_CLIENT_ID);
+  if (!clientSecret) {
+    throw new RegistryCredentialError(
+      `the ${LAMASTE_SERVER_OIDC_CLIENT_ID} OIDC client has no secret yet — set the registry credential again`,
+      500,
+    );
+  }
+  return { oidc: { domain, clientSecret } };
+}
+
+/**
+ * Verify a candidate credential end to end (for `oidc`: Authelia token
+ * endpoint → Feria login → whoami with the admin scope). The
+ * `lamaste-server` client must already be in Authelia — the route syncs it
+ * first.
+ * @param {{ registryUrl: string, auth: { kind: 'token', token: string } | { kind: 'oidc', clientId: string } }} candidate
+ */
+export async function verifyRegistryCredential(candidate) {
+  return verifyCore(candidate, await oidcDeps(candidate));
+}
+
+/** The panel's registry token for the stored credential (cached per process). */
+async function serviceToken(config) {
+  return (await serviceTokens.resolve(config, await oidcDeps(config))).token;
+}
+
+/**
+ * The calling agent's registry token: the cached one when it is still good
+ * for an install, otherwise a freshly brokered one-hour token — unless the
+ * agent already had ten new tokens this hour. `null` when no credential is
+ * configured. Throws RegistryCredentialError (with `statusCode`) when the
+ * registry refuses.
+ * @param {string} agentLabel
+ * @returns {Promise<import('@lamalibre/lamaste/server').AgentTokenAcquisition | null>}
+ */
+export async function acquireAgentToken(agentLabel) {
+  const config = await readRegistryCredentialConfig();
+  if (!config) return null;
+  return agentTokens.acquire(agentLabel, async () =>
+    brokerAgentRegistryToken(config, agentLabel, { serviceToken: await serviceToken(config) }),
+  );
+}
+
+/**
+ * Revoke a user's registry tokens after their `feria-*` groups changed or
+ * they were deleted. Returns the number revoked, or `null` when nothing
+ * needed doing (no credential configured, or no feria group lost).
+ *
+ * @param {string} username
+ * @param {{ before: string[], after: string[] } | { deleted: true }} change
+ * @param {import('pino').Logger} log
+ */
+export async function revokeUserRegistryTokens(username, change, log) {
+  const config = await readRegistryCredentialConfig();
+  if (!config) return null;
+
+  const lost =
+    'deleted' in change ? ['(deleted)'] : lostFeriaGroups(change.before ?? [], change.after ?? []);
+  if (lost.length === 0) return null;
+
+  const owner = `user:${username}`;
+  const revoked = await revokeRegistryTokensForOwner(config, owner, {
+    serviceToken: await serviceToken(config),
+  });
+  log.info({ username, lost, revoked }, 'Revoked registry tokens after group change');
+  return revoked;
+}

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

@@ -14,6 +14,8 @@ import {
 } from '../../lib/mtls.js';
 import { z } from 'zod';
 import { AGENT_LABEL_REGEX } from '@lamalibre/lamaste';
+import { RegistryCredentialError } from '@lamalibre/lamaste/server';
+import { acquireAgentToken } from '../../lib/registry-credential.js';
 
 /**
  * An agent may rotate its own chisel credential at most this often. Every
@@ -113,6 +115,85 @@ export default async function agentsRoutes(fastify, _opts) {
     },
   );
 
+  // ------------------------------------------------------------------
+  // GET /agents/me/registry-credential
+  //
+  // Brokers a one-hour, read-only npm registry token for the calling agent
+  // so it can `npm install` a plugin from the Lamalibre registry (Feria)
+  // without ever holding a long-lived credential. Identity comes strictly
+  // from the mTLS cert; the token is owned by `agent:<label>` on the
+  // registry, so its audit log says which agent installed what.
+  //
+  // The token is cached per agent until five minutes before it expires, so
+  // repeated installs within the hour get the same one; an agent may be
+  // issued at most ten new tokens per hour (429 + Retry-After beyond that).
+  // The per-IP limit stays as a backstop.
+  //
+  // 404 when the panel has no registry credential configured — the agent
+  // then installs from the public registry as before.
+  // ------------------------------------------------------------------
+  fastify.get(
+    '/agents/me/registry-credential',
+    {
+      preHandler: fastify.requireRole(['agent']),
+      // One token per install is the expected rate; this only stops a loop.
+      config: { rateLimit: { max: 30, timeWindow: '1 minute' } },
+    },
+    async (request, reply) => {
+      // requireRole lets the admin master role through every guard; an admin
+      // certificate has no agent identity to broker for. Plugin-agents pass
+      // here and are answered 400 below.
+      if (request.certRole !== 'agent' && request.certRole !== 'plugin-agent') {
+        return reply
+          .code(403)
+          .send({ error: 'Only an agent certificate can obtain a registry credential' });
+      }
+      const label = request.certLabel;
+      if (!label) {
+        return reply.code(400).send({
+          error: 'Agent label could not be determined from client certificate',
+        });
+      }
+      if (!AGENT_LABEL_REGEX.test(label)) {
+        return reply.code(400).send({ error: 'Plugin-agents do not install plugins' });
+      }
+      try {
+        const acquired = await acquireAgentToken(label);
+        if (!acquired) {
+          return reply.code(404).send({
+            error: 'No registry credential is configured on this panel',
+            hint: 'lamaste-server registry-credential set --url <registry> --oidc',
+          });
+        }
+        if (!acquired.ok) {
+          request.log.warn(
+            { label, retryAfterSeconds: acquired.retryAfterSeconds },
+            'Agent exceeded its registry token issuance limit',
+          );
+          return reply.code(429).header('Retry-After', String(acquired.retryAfterSeconds)).send({
+            error: 'This agent has been issued its hourly share of registry tokens',
+            retryAfterSeconds: acquired.retryAfterSeconds,
+          });
+        }
+        const { credential } = acquired;
+        request.log.info(
+          {
+            label,
+            tokenId: credential.tokenId,
+            expiresAt: credential.expiresAt,
+            cached: acquired.cached,
+          },
+          acquired.cached ? 'Reused registry token for agent' : 'Brokered registry token for agent',
+        );
+        return credential;
+      } catch (err) {
+        const status = err instanceof RegistryCredentialError ? err.statusCode : 502;
+        request.log.warn({ label, err: err.message }, 'Failed to broker registry token');
+        return reply.code(status).send({ error: err.message || 'Failed to broker registry token' });
+      }
+    },
+  );
+
   // ------------------------------------------------------------------
   // GET /agents/me/capabilities
   //

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

@@ -8,6 +8,7 @@ import {
   getPluginCapabilities,
 } from '../../lib/plugins.js';
 import { setPluginCapabilities, loadAgentRegistry } from '../../lib/mtls.js';
+import { listPluginOidcClients, rotatePluginOidcClientSecret } from '../../lib/plugin-oidc.js';
 import {
   readPushInstallConfig,
   readPushInstallSessions,
@@ -31,6 +32,14 @@ const PluginNameParamSchema = z.object({
     .regex(/^[a-z0-9-]+$/, 'Plugin name must contain only lowercase letters, numbers, and hyphens'),
 });
 
+const OidcClientIdParamSchema = z.object({
+  clientId: z
+    .string()
+    .min(1)
+    .max(100)
+    .regex(/^[a-z0-9][a-z0-9-]*$/, 'Client id must be lowercase letters, numbers and hyphens'),
+});
+
 const InstallBodySchema = z.object({
   packageName: z
     .string()
@@ -188,10 +197,12 @@ export default async function pluginRoutes(fastify, _opts) {
       const body = InstallBodySchema.parse(request.body);
 
       try {
-        const plugin = await installPlugin(body.packageName, request.log);
+        // `oidcClients` carries the secrets of confidential OIDC clients this
+        // install created — shown once, never stored in the registry row.
+        const { oidcClients, ...plugin } = await installPlugin(body.packageName, request.log);
         // Refresh in-memory capability list so new plugin caps are valid immediately
         setPluginCapabilities(await getPluginCapabilities());
-        return { ok: true, plugin };
+        return { ok: true, plugin, oidcClients };
       } catch (err) {
         const statusCode = err.statusCode || 500;
         return reply.code(statusCode).send({
@@ -273,6 +284,58 @@ export default async function pluginRoutes(fastify, _opts) {
     },
   );
 
+  // ------------------------------------------------------------------
+  // GET /plugins/:name/oidc-clients — the OIDC clients a plugin declares
+  //
+  // Metadata only: a confidential client's secret is shown by the install
+  // or enable response that created it, and by rotate-secret — never here.
+  // ------------------------------------------------------------------
+  fastify.get(
+    '/plugins/:name/oidc-clients',
+    {
+      preHandler: fastify.requireRole(['admin']),
+    },
+    async (request, reply) => {
+      const params = PluginNameParamSchema.parse(request.params);
+      const registry = await readPlugins();
+      if (!registry.plugins.some((p) => p.name === params.name)) {
+        return reply.code(404).send({ error: `Plugin "${params.name}" not found` });
+      }
+      return { clients: await listPluginOidcClients(params.name) };
+    },
+  );
+
+  // ------------------------------------------------------------------
+  // POST /plugins/:name/oidc-clients/:clientId/rotate-secret
+  //
+  // Replaces a confidential client's secret in the store and in Authelia.
+  // The new secret is in the response and nowhere else.
+  // ------------------------------------------------------------------
+  fastify.post(
+    '/plugins/:name/oidc-clients/:clientId/rotate-secret',
+    {
+      preHandler: fastify.requireRole(['admin']),
+      config: { rateLimit: { max: 10, timeWindow: '1 minute' } },
+    },
+    async (request, reply) => {
+      const params = PluginNameParamSchema.parse(request.params);
+      const { clientId } = OidcClientIdParamSchema.parse(request.params);
+      const registry = await readPlugins();
+      if (!registry.plugins.some((p) => p.name === params.name)) {
+        return reply.code(404).send({ error: `Plugin "${params.name}" not found` });
+      }
+      try {
+        const rotated = await rotatePluginOidcClientSecret(params.name, clientId, request.log);
+        return { ok: true, ...rotated };
+      } catch (err) {
+        const statusCode = err.statusCode || 500;
+        return reply.code(statusCode).send({
+          error: err.message || 'Failed to rotate the client secret',
+        });
+      }
+    },
+  );
+
   // ===========================================================================
   // Push install routes
   // ===========================================================================