@lamalibre/create-lamaste 4.0.0 → 4.2.0

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

@@ -4,7 +4,7 @@
     <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-B0nWuUyL.js"></script>
+    <script type="module" crossorigin src="/assets/index-B5Wp8lu-.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-BqWWFlTU.css">
   </head>
   <body style="background-color: #09090b">

package/vendor/serverd/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lamalibre/lamaste-serverd",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "Lamaste server daemon — REST API and plugin host",
   "license": "SEE LICENSE IN LICENSE.md",
   "publishConfig": {
@@ -8,6 +8,9 @@
   },
   "type": "module",
   "main": "src/index.js",
+  "files": [
+    "src"
+  ],
   "scripts": {
     "dev": "node --watch src/index.js | pino-pretty",
     "build": "echo 'No build step for lamaste-serverd'",
@@ -26,7 +29,7 @@
     "@fastify/rate-limit": "^10.3.0",
     "@fastify/static": "^9.1.1",
     "@fastify/websocket": "^11.0.0",
-    "@lamalibre/lamaste": "^4.0.0",
+    "@lamalibre/lamaste": "^4.2.0",
     "bcryptjs": "^3.0.3",
     "execa": "^9.6.1",
     "fastify": "^5.8.4",

package/vendor/serverd/src/index.js

@@ -28,6 +28,7 @@ import userAccessSessionMiddleware from './middleware/user-access-session.js';
 import { getPluginCapabilities } from './lib/plugins.js';
 import { setPluginCapabilities } from './lib/mtls.js';
 import { startChiselReconciler } from './lib/chisel-reconcile.js';
+import { syncOidcClients } from './lib/plugin-oidc.js';
 import {
   loadTicketScopeCapabilities,
   checkInstanceLiveness,
@@ -76,6 +77,16 @@ async function start() {
   // it can.
   startChiselReconciler(server.log);
 
+  // Bring Authelia's OIDC clients (plugin manifests, the panel's own
+  // registry client) and the client-secret store in line with persisted
+  // state. Best effort: a failure is logged and the next lifecycle change
+  // retries. Only once onboarding has written Authelia's configuration.
+  if (config.onboarding.status === 'COMPLETED') {
+    syncOidcClients(server.log).catch((err) => {
+      server.log.warn({ err: err.message }, 'Startup OIDC client sync failed');
+    });
+  }
+
   // --- Plugins ---
   const ipOrigin = `https://${config.ip}:9292`;
   await server.register(cors, {

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

@@ -18,6 +18,7 @@ import {
   reloadAuthelia as reloadAutheliaCore,
   isAutheliaRunning as isAutheliaRunningCore,
   updateAutheliaAccessControl,
+  updateAutheliaOidcProvider,
   createUserFromInvitation as createUserFromInvitationCore,
   base32Encode,
   base32Decode,
@@ -73,6 +74,16 @@ export function updateAccessControl(sites) {
   return updateAutheliaAccessControl(sites, execa);
 }
 
+/**
+ * Make Authelia's OIDC provider serve exactly these clients.
+ * @param {string} domain
+ * @param {import('@lamalibre/lamaste/server').AutheliaOidcClient[]} clients
+ * @param {import('@lamalibre/lamaste/server').OidcProviderOptions} [options]
+ */
+export function updateOidcProvider(domain, clients, options = {}) {
+  return updateAutheliaOidcProvider(domain, clients, execa, options);
+}
+
 export function createUserFromInvitation(username, email, groups, hashedPassword) {
   return createUserFromInvitationCore(username, email, groups, hashedPassword, execa);
 }

package/vendor/serverd/src/lib/migrations/state/0005_plugin_hosting.sql

@@ -0,0 +1,3 @@
+-- Where a plugin's code runs (manifest `hosting`, 4.2). Rows written before
+-- the column existed are server plugins.
+ALTER TABLE plugins ADD COLUMN hosting TEXT NOT NULL DEFAULT 'server';

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

@@ -0,0 +1,233 @@
+/**
+ * OIDC clients → Authelia.
+ *
+ * Two sources declare clients on the relay's Authelia:
+ *
+ * - every installed plugin may declare them in its manifest (`oidcClients`,
+ *   see the core `ManifestSchema`); only the clients of enabled plugins are
+ *   served. Hosting does not matter: an agent-hosted plugin (`hosting:
+ *   "agent"`, never imported by the panel) registers its clients exactly as
+ *   a server plugin does — the manifest is all this reads;
+ * - 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)];
+}
+
+/**
+ * What Authelia should serve and which secrets the store should hold, from
+ * the stored state: every installed plugin's clients (an installed plugin
+ * keeps its confidential-client secret while disabled), the clients of
+ * enabled plugins served, and the panel's own scopes when its client is.
+ * Pure with respect to Authelia — nothing is written.
+ *
+ * @param {{ registryAuth?: { registryUrl: string } | null }} [overrides] see collectAllClients
+ * @returns {Promise<{
+ *   confidential: Array<{ id: string, plugin: string }>,
+ *   served: Array<import('@lamalibre/lamaste/server').AutheliaOidcClient>,
+ *   scopes: Record<string, { claims: readonly string[] }>,
+ * }>}
+ */
+export async function planOidcClients(overrides = {}) {
+  const all = await collectAllClients(overrides);
+  const served = all.filter((c) => c.enabled).map(({ enabled: _enabled, ...client }) => client);
+  return {
+    confidential: all.filter((c) => c.confidential).map((c) => ({ id: c.id, plugin: c.plugin })),
+    served,
+    scopes: served.some((c) => c.plugin === 'lamaste') ? LAMASTE_REGISTRY_OIDC_SCOPES : {},
+  };
+}
+
+/**
+ * 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 { confidential, served, scopes } = await planOidcClients(overrides);
+  const reconciled = await reconcileOidcClientSecrets(STATE_DIR, confidential);
+  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 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 { served, scopes } = await planOidcClients();
+    await updateOidcProvider(domain, served, { secretDigests: digests, 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

@@ -14,6 +14,7 @@ import path from 'node:path';
 import { z } from 'zod';
 import { execa } from 'execa';
 import {
+  DEFAULT_PLUGIN_HOSTING,
   RESERVED_API_PREFIXES,
   RESERVED_NAV_LABELS,
   derivePluginRoute,
@@ -60,8 +61,8 @@ async function getStmts() {
     insert: db.prepare(`
       INSERT INTO plugins
         (name, display_name, package_name, version, description, capabilities,
-         packages, panel, config, modes, status, installed_at, enabled_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         packages, panel, config, modes, hosting, status, installed_at, enabled_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `),
     deleteByName: db.prepare('DELETE FROM plugins WHERE name = ?'),
     deleteAll: db.prepare('DELETE FROM plugins'),
@@ -86,7 +87,10 @@ async function getStmts() {
 // JSON-encoded TEXT in storage. They round-trip through JSON.parse/stringify
 // so callers see the same shape the JSON-backed module returned — including
 // `undefined` for optional fields (mirroring the JSON object layout where
-// missing keys are absent rather than null).
+// missing keys are absent rather than null). `hosting` is plain TEXT
+// ('server' | 'agent'; rows from before 4.2 default to 'server'): an
+// agent-hosted plugin is installed (npm, manifest) like any other, but the
+// plugin host never imports it — see `pluginHostPlugin`.
 
 function rowToPlugin(row) {
   const entry = {
@@ -94,6 +98,7 @@ function rowToPlugin(row) {
     packageName: row.package_name,
     version: row.version,
     capabilities: row.capabilities ? JSON.parse(row.capabilities) : [],
+    hosting: row.hosting,
     status: row.status,
     installedAt: row.installed_at,
   };
@@ -155,6 +160,7 @@ export async function writePlugins(data) {
         nullableJson(p.panel),
         nullableJson(p.config),
         nullableJson(p.modes),
+        p.hosting ?? DEFAULT_PLUGIN_HOSTING,
         p.status,
         p.installedAt,
         nullableString(p.enabledAt),
@@ -210,6 +216,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
@@ -339,6 +365,7 @@ export function installPlugin(packageName, logger) {
       panel: manifest.panel,
       config: manifest.config,
       modes: manifest.modes,
+      hosting: manifest.hosting,
       status: 'disabled',
       installedAt: new Date().toISOString(),
     };
@@ -356,6 +383,7 @@ export function installPlugin(packageName, logger) {
         nullableJson(entry.panel),
         nullableJson(entry.config),
         nullableJson(entry.modes),
+        entry.hosting,
         entry.status,
         entry.installedAt,
         null,
@@ -367,7 +395,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 +465,7 @@ export function uninstallPlugin(name, logger) {
     }
 
     logger.info({ name }, 'Plugin uninstalled');
+    await syncOidcClientsBestEffort(logger);
     return { ok: true, name };
   });
 }
@@ -470,7 +500,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 +535,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
   //