@lamalibre/create-lamaste 4.4.1 → 4.5.0

package/vendor/server/src/commands/plugins.js

@@ -52,6 +52,13 @@
  *   configure <name> [--set key=value]... [--clear key]... [--secrets-stdin]
  *                        Change them (kept by its agent half); in a terminal without
  *                        flags, field by field — a secret never on the command line
+ *   identity <name>      The people of an agent-hosted plugin that declares identity:
+ *                        its roles and attributes, approval, readiness, the feed, erasures
+ *   audience <name>      Its members and the users who left, as its agent half is told
+ *   entitlements <name> [--user <u> | --group <g> --roles a,b] [--revoke --user|--group]
+ *                        Who holds which of its roles; give or take them away
+ *   identity-sync <name> [--reconcile]
+ *                        Sync its audience to its agent half now
  *
  * Every subcommand goes through the running panel (`/api/plugins/*`, admin
  * certificate): the panel owns the plugin registry (SQLite `state.db`), runs
@@ -69,10 +76,13 @@ import { PANEL_SERVICE } from '../config.js';
 import { panelRequest } from '../panel-api.js';
 import { emit, emitStep, emitError, emitComplete, emitLog } from '../ndjson.js';
 import { configureCmd, settingsCmd } from './plugin-settings.js';
+import { audienceCmd, entitlementsCmd, identityCmd, identitySyncCmd } from './plugin-identity.js';
 import { settingsDiffLines, terminalText } from '../plugin-settings.js';
 import {
   APPROVE_HOOKS_USAGE,
   approveHooksCommand,
+  identityBlockLines,
+  identityDiffLines,
   parseApproveArgs,
   pendingUpdateReasons,
 } from '../plugin-approval.js';
@@ -134,6 +144,14 @@ export async function runPlugins(args, { json }) {
       return settingsCmd(args.slice(1), { json });
     case 'configure':
       return configureCmd(args.slice(1), { json });
+    case 'identity':
+      return identityCmd(args[1], { json });
+    case 'audience':
+      return audienceCmd(args[1], { json });
+    case 'entitlements':
+      return entitlementsCmd(args.slice(1), { json });
+    case 'identity-sync':
+      return identitySyncCmd(args.slice(1), { json });
     default:
       printPluginUsage();
       process.exit(sub ? 1 : 0);
@@ -191,6 +209,16 @@ ${b('Subcommands:')}
                        --clear puts a field back to its default or clears a secret,
                        --secrets-stdin reads {"key": "value" | null} from stdin;
                        in a terminal without flags, asked field by field
+  ${c('identity <name>')}      People of a plugin that declares identity: its roles and attributes,
+                       approval, whether users reach it (and why not), the feed, erasures
+  ${c('audience <name>')}      Its members and the users who left, as its agent half is told
+  ${c('entitlements <name>')}  Who holds which of its roles (Gatekeeper grants with roles)
+  ${c('entitlements <name> --user <u> | --group <g> --roles a,b')}
+                       Give a user or a Lamaste group exactly these roles
+  ${c('entitlements <name> --revoke --user <u> | --group <g>')}
+                       Take every role away
+  ${c('identity-sync <name> [--reconcile]')}
+                       Sync its audience to its agent half now; --reconcile replays all of it
 `);
 }
 
@@ -725,9 +753,11 @@ function printRelayHookSet(relay, title) {
       `    request:  ${hook.stage} ${who} on ${hook.routes.join(', ')}${failOpen}` +
         d(` (body ${hook.bodyMaxBytes ?? 0} B, ${hook.timeoutMs} ms, onError ${hook.onError})`),
     );
-    if (hook.inactiveRoutes.length > 0) {
+    if (hook.userSurfaceRoutes.length > 0) {
       console.log(
-        d(`              not active until the user surface: ${hook.inactiveRoutes.join(', ')}`),
+        d(
+          `              runs on user-surface requests (plugins that declare identity): ${hook.userSurfaceRoutes.join(', ')}`,
+        ),
       );
     }
   }
@@ -757,15 +787,25 @@ function printAgentHalf(agentHalf, title) {
   );
 }
 
+/**
+ * Print an identity block — the roles a plugin's users hold and what it
+ * receives about each member.
+ */
+function printIdentityBlock(block, title) {
+  console.log(chalk.bold(`  ${title}`));
+  for (const line of identityBlockLines(block)) console.log(`    ${line}`);
+}
+
 /**
  * Print what a version brings that needs approval — the approval digest
  * (what `approve-hooks` takes; none for an update that brings neither
- * relay hooks nor an agent half Lamaste installs), its relay hook set and
- * the agent half Lamaste installs.
+ * relay hooks, nor an agent half Lamaste installs, nor an identity block),
+ * its relay hook set, the agent half Lamaste installs and its identity
+ * block.
  */
-function printApprovalContents({ digest, relay, agentHalf }) {
+function printApprovalContents({ digest, relay, agentHalf, identity = null }) {
   console.log(
-    `    approval digest: ${digest ? chalk.cyan(digest) : chalk.dim('none — no relay hooks, no agent half Lamaste installs')}`,
+    `    approval digest: ${digest ? chalk.cyan(digest) : chalk.dim('none — no relay hooks, no agent half Lamaste installs, no identity block')}`,
   );
   if (relay) {
     console.log('');
@@ -775,12 +815,45 @@ function printApprovalContents({ digest, relay, agentHalf }) {
     console.log('');
     printAgentHalf(agentHalf, 'Agent half — Lamaste installs it on the hosting agent');
   }
+  if (identity) {
+    console.log('');
+    printIdentityBlock(
+      identity,
+      'Identity — Lamaste sends its agent half the users entitled to these roles',
+    );
+  }
+}
+
+/**
+ * Print how an update changes the plugin's identity block (part of the
+ * digest): roles added or removed and attributes widened wait for an
+ * administrator whatever auto-approve says; the block it brings.
+ */
+function printIdentityChanges(diff) {
+  const shown = identityDiffLines(diff);
+  if (!shown) {
+    // Declared before and after, unchanged: still part of what is approved.
+    if (diff?.after) {
+      console.log('');
+      printIdentityBlock(diff.after, 'Identity — unchanged');
+    }
+    return;
+  }
+  console.log('');
+  console.log(chalk.bold(`  Identity — this version ${shown.headline}`));
+  for (const line of shown.lines) {
+    console.log(`    ${line.approval ? chalk.yellow(line.text) : line.text}`);
+  }
+  if (diff.after) {
+    for (const line of identityBlockLines(diff.after)) console.log(chalk.dim(`    ${line}`));
+  }
 }
 
 /**
  * Print an update that waits for approval under `title`: why it waits
- * (`approvalRequired` — a secret turned plain in red), what it brings
- * (its digest, relay hook set and agent half), how it changes the settings
+ * (`approvalRequired` — a secret turned plain in red, an identity change
+ * with its note), what it brings (its digest, relay hook set and agent
+ * half), how it changes the identity block, how it changes the settings
  * schema (outside the digest) — fields added and removed with their types,
  * retyped ones, newly required ones, and a warning for secrets that become
  * plain values — what auto-approve could not cover beyond the reasons, and
@@ -791,10 +864,16 @@ function printPendingUpdate(name, update, title) {
   console.log(chalk.bold(`  ${title}`));
   const { required, notCovered } = pendingUpdateReasons(update);
   for (const line of required) {
-    console.log(line.warning ? chalk.red(`    - ${line.text}`) : `    - ${line.text}`);
+    const text = line.warning ? chalk.red(`    - ${line.text}`) : `    - ${line.text}`;
+    console.log(line.note ? `${text}${chalk.dim(` (${line.note})`)}` : text);
   }
   console.log('');
-  printApprovalContents(update);
+  printApprovalContents({
+    digest: update.digest,
+    relay: update.relay,
+    agentHalf: update.agentHalf,
+  });
+  printIdentityChanges(update.identity);
   const lines = settingsDiffLines(update.settings);
   if (lines.length > 0) {
     console.log('');
@@ -837,7 +916,7 @@ async function hooksCmd(name, { json }) {
   console.log('');
   if (!approval.required && !hooks.agent && !hooks.pendingUpdate) {
     console.log(
-      `  Plugin ${chalk.cyan(name)} declares no lifecycle hooks and no agent half for Lamaste to install.\n`,
+      `  Plugin ${chalk.cyan(name)} declares no lifecycle hooks, no agent half for Lamaste to install and no identity.\n`,
     );
     return;
   }
@@ -853,6 +932,7 @@ async function hooksCmd(name, { json }) {
       digest: approval.digest,
       relay: hooks.relay,
       agentHalf: hooks.agentHalf,
+      identity: hooks.identity?.declared ? hooks.identity.block : null,
     });
     console.log(
       `\n    auto-approve for later versions: ${hooks.autoApprove ? chalk.yellow('on') : 'off'}`,
@@ -860,6 +940,13 @@ async function hooksCmd(name, { json }) {
     if (approval.state !== 'approved') {
       console.log(`\n    Approve with: ${approveCommand(name, { digest: approval.digest })}`);
     }
+    if (hooks.identity?.declared) {
+      console.log(
+        chalk.dim(
+          `    Its people (entitlements, audience, feed): lamaste-server plugins identity ${terminalText(name)}`,
+        ),
+      );
+    }
   }
   if (hooks.agent) {
     console.log(chalk.bold(`\n  Agent hooks (run by the agent half; no approval)`));
@@ -1174,6 +1261,7 @@ async function installPluginCmd(packageName, { json }) {
       digest: approval.digest,
       relay: result.hooks.relay,
       agentHalf: result.hooks.agentHalf,
+      identity: result.hooks.identity?.declared ? result.hooks.identity.block : null,
     });
     if (approval.state === 'pending') {
       console.log(

package/vendor/server/src/commands/registry-credential.js

@@ -8,7 +8,8 @@
  *       The panel authenticates as its own `lamaste-server` OIDC client on
  *       the relay's Authelia (client-credentials grant, Feria login). Nothing
  *       to paste; Feria's auth.json must grant the relay's lamaste-server client
- *       through a "workloads" rule on its groups issuer for the relay Authelia.
+ *       read and admin through a "workloads" rule on its groups issuer for the
+ *       relay Authelia.
  *   registry-credential set --url <registry> [--token-stdin]
  *       A long-lived Feria token, read from LAMASTE_REGISTRY_TOKEN or from
  *       stdin with --token-stdin. Never accepted as a command-line argument.

package/vendor/server/src/commands/tunnels.js

@@ -9,16 +9,28 @@
  *   assign <id> --agent <label>                   Move a tunnel to another agent
  *   configure <id> [--access-mode <m>] [--max-body-mb <n>]
  *                                                 Change access mode / body limit
+ *   bind-user-surface <tunnel> <plugin>           Serve an agent-hosted plugin's user
+ *                                                 surface (/api/<route>/app/*) on the
+ *                                                 tunnel's host
+ *   unbind-user-surface <tunnel> <plugin>         Stop serving it there
  *
  * List reads directly from the state file.
- * Create/delete/toggle use the panel REST API (which has the full
- * nginx/certbot/chisel dependency stack).
+ * Create/delete/toggle and the user-surface binding use the panel REST API
+ * (which has the full nginx/certbot/chisel dependency stack); a tunnel is
+ * named by its id, subdomain or FQDN there, a plugin by its name or route.
  */
 
 import chalk from 'chalk';
 import { readTunnels } from '../state.js';
 import { panelRequest } from '../panel-api.js';
 import { emit, emitError, emitComplete } from '../ndjson.js';
+import {
+  findHostTunnel,
+  findPluginByNameOrRoute,
+  parseUserSurfaceArgs,
+  userSurfaceStatusText,
+} from '../plugin-identity.js';
+import { terminalText } from '../plugin-settings.js';
 
 /**
  * @param {string[]} args
@@ -40,6 +52,9 @@ export async function runTunnels(args, { json }) {
       return assignTunnel(args.slice(1), { json });
     case 'configure':
       return configureTunnel(args.slice(1), { json });
+    case 'bind-user-surface':
+    case 'unbind-user-surface':
+      return userSurfaceCmd(sub, args.slice(1), { json });
     default:
       printTunnelUsage();
       process.exit(sub ? 1 : 0);
@@ -59,6 +74,13 @@ ${b('Subcommands:')}
   ${c('toggle')} <id> --enable|--disable                      Enable or disable a tunnel
   ${c('assign')} <id> --agent <label>                         Move a tunnel to another agent
   ${c('configure')} <id> [--access-mode <m>] [--max-body-mb <n>] Change access mode / body limit
+  ${c('bind-user-surface')} <tunnel> <plugin>                Serve an agent-hosted plugin's user surface
+                                                      (/api/<route>/app/*) on the tunnel's host
+  ${c('unbind-user-surface')} <tunnel> <plugin>              Stop serving it there
+
+  A tunnel is named by its id, subdomain or FQDN; a plugin by its name or route. A user
+  surface needs an enabled tunnel that is authenticated or restricted, carried by the
+  agent that hosts the plugin — it is served only while that agent carries the tunnel.
 
 ${b('Create options:')}
   --subdomain <name>    Tunnel subdomain (required)
@@ -108,6 +130,10 @@ async function listTunnels({ json }) {
     if (t.description) {
       console.log(`    ${d(t.description)}`);
     }
+    const userSurface = Array.isArray(t.userSurface?.routes) ? t.userSurface.routes : [];
+    if (userSurface.length > 0) {
+      console.log(`    ${d('user surface of:')} ${terminalText(userSurface.join(', '))}`);
+    }
     console.log(`    ${d(`id: ${t.id}  fqdn: ${t.fqdn}`)}`);
   }
   console.log('');
@@ -363,3 +389,77 @@ function getArg(args, name) {
   if (idx === -1 || idx + 1 >= args.length) return null;
   return args[idx + 1];
 }
+
+/**
+ * `bind-user-surface|unbind-user-surface <tunnel> <plugin>`: the tunnel's
+ * host serves (or stops serving) the plugin's `/api/<route>/app/*` — from
+ * when its installed, approved version declares identity; until then its
+ * requests go down the tunnel. Prints how each route bound to the tunnel is
+ * served afterwards.
+ *
+ * @param {'bind-user-surface' | 'unbind-user-surface'} sub
+ * @param {string[]} args
+ * @param {{ json: boolean }} options
+ */
+async function userSurfaceCmd(sub, args, { json }) {
+  const failWith = (message, code) => {
+    if (json) emitError(message, false, code ? { code } : {});
+    else console.error(`\n  ${chalk.red(terminalText(message))}\n`);
+    process.exit(1);
+  };
+  const parsed = parseUserSurfaceArgs(sub, args);
+  if (!parsed.ok) failWith(parsed.error);
+
+  const found = findHostTunnel(await readTunnels(), parsed.tunnel);
+  if (found.error) failWith(found.error);
+  const { tunnel } = found;
+
+  let plugins;
+  try {
+    ({ plugins = [] } = await panelRequest('GET', '/api/plugins'));
+  } catch (err) {
+    failWith(err.message, err.code);
+  }
+  const named = findPluginByNameOrRoute(plugins, parsed.plugin);
+  if (named.error) failWith(named.error);
+  const { route } = named.plugin;
+
+  const bind = sub === 'bind-user-surface';
+  const surfacePath = `/api/tunnels/${encodeURIComponent(tunnel.id)}/user-surface`;
+  let result;
+  try {
+    result = bind
+      ? await panelRequest('PUT', surfacePath, { route })
+      : await panelRequest('DELETE', `${surfacePath}/${encodeURIComponent(route)}`);
+  } catch (err) {
+    failWith(err.message, err.code);
+  }
+  if (json) {
+    emitComplete({ id: tunnel.id, route, ...result });
+    return;
+  }
+  const host = terminalText(result.tunnel?.fqdn ?? tunnel.fqdn);
+  if (bind) {
+    console.log(
+      result.changed
+        ? `\n  ${chalk.green('✓')} ${chalk.cyan(host)} serves the user surface of ${chalk.cyan(route)}`
+        : `\n  ${chalk.cyan(host)} already serves the user surface of ${chalk.cyan(route)}`,
+    );
+  } else {
+    console.log(
+      `\n  ${chalk.green('✓')} ${chalk.cyan(host)} no longer serves the user surface of ${chalk.cyan(route)} — its requests go down the tunnel`,
+    );
+  }
+  const statuses = Array.isArray(result.tunnel?.userSurfaceStatus)
+    ? result.tunnel.userSurfaceStatus
+    : [];
+  for (const status of statuses) {
+    const served = status.served === true;
+    const word = userSurfaceStatusText(status);
+    console.log(
+      `    ${terminalText(status.route)}: ${served ? chalk.green(word) : chalk.yellow(word)}` +
+        (served ? chalk.dim(`  https://${host}/api/${terminalText(status.route)}/app/`) : ''),
+    );
+  }
+  console.log('');
+}

package/vendor/server/src/commands/uninstall.js

@@ -190,11 +190,13 @@ async function removeServices() {
  * @param {Record<string, unknown> | null} _config
  */
 async function removeNginxConfigs(_config) {
-  // Remove lamaste-specific sites
+  // Remove lamaste-specific sites, then the snippets and http-level maps
+  // they use (the sites go first: a site naming a removed map fails nginx)
   const patterns = [
     '/etc/nginx/sites-enabled/lamalibre-lamaste-*',
     '/etc/nginx/sites-available/lamalibre-lamaste-*',
     '/etc/nginx/snippets/lamalibre-lamaste-*',
+    '/etc/nginx/conf.d/lamalibre-lamaste-*',
   ];
 
   for (const pattern of patterns) {