@lamalibre/create-lamaste 4.5.0 → 4.7.0

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

@@ -10,7 +10,12 @@
  *                        Remove a plugin (must be disabled first); a hosted one
  *                        through its uninstall pipeline (an operation); --purge also
  *                        deletes the data of the agent half Lamaste installed
- *   oidc-clients <name>  The OIDC clients a plugin declares on Authelia
+ *   oidc-clients <name> [grants]
+ *                        The OIDC clients a plugin declares on Authelia, and who is
+ *                        granted each user-facing one
+ *   oidc-clients <name> grant|revoke <clientId> --user <u>|--group <g>
+ *                        Grant (or revoke) a user-facing client to a user or a Lamaste
+ *                        group: what admits an external member to its sign-in
  *   rotate-secret <name> <clientId>
  *                        New secret for a confidential OIDC client (shown once)
  *   hosting <name>       Which agent hosts an agent-hosted plugin's agent half
@@ -59,6 +64,11 @@
  *                        Who holds which of its roles; give or take them away
  *   identity-sync <name> [--reconcile]
  *                        Sync its audience to its agent half now
+ *   domain <name> [<domain>]   The domain a plugin belongs to; move it to another active one
+ *   web-surface <name> [create [--subdomain <s>] [--access-mode <m>] | move --tunnel <t> | delete [--yes]]
+ *                        The site an agent-hosted plugin owns for its web surface: what it
+ *                        declares, whether it is served, its trees; create, move a bound
+ *                        tunnel's host to it, delete it
  *
  * Every subcommand goes through the running panel (`/api/plugins/*`, admin
  * certificate): the panel owns the plugin registry (SQLite `state.db`), runs
@@ -77,6 +87,15 @@ 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 { webSurfaceCmd } from './plugin-web-surface.js';
+import { pluginDomainCmd } from './domains.js';
+import { fail as failPanel } from '../fail.js';
+import {
+  OIDC_CLIENT_RESOURCE,
+  findClientGrants,
+  parsePrincipal,
+  principalText,
+} from '../oidc-client-grants.js';
 import { settingsDiffLines, terminalText } from '../plugin-settings.js';
 import {
   APPROVE_HOOKS_USAGE,
@@ -85,6 +104,8 @@ import {
   identityDiffLines,
   parseApproveArgs,
   pendingUpdateReasons,
+  webSurfaceBlockLines,
+  webTreeDiffLines,
 } from '../plugin-approval.js';
 
 /** npm runs inside the panel for install and uninstall (its own limit is 120 s). */
@@ -109,7 +130,7 @@ export async function runPlugins(args, { json }) {
     case 'uninstall':
       return uninstallPluginCmd(args[1], args.slice(2), { json });
     case 'oidc-clients':
-      return oidcClientsCmd(args[1], { json });
+      return oidcClientsCmd(args[1], args.slice(2), { json });
     case 'rotate-secret':
       return rotateSecretCmd(args[1], args[2], { json });
     case 'hosting':
@@ -152,6 +173,10 @@ export async function runPlugins(args, { json }) {
       return entitlementsCmd(args.slice(1), { json });
     case 'identity-sync':
       return identitySyncCmd(args.slice(1), { json });
+    case 'web-surface':
+      return webSurfaceCmd(args.slice(1), { json });
+    case 'domain':
+      return pluginDomainCmd(args.slice(1), { json });
     default:
       printPluginUsage();
       process.exit(sub ? 1 : 0);
@@ -172,7 +197,11 @@ ${b('Subcommands:')}
   ${c('uninstall <name> [--force] [--purge]')}
                        Remove a disabled plugin (a hosted one through its uninstall pipeline;
                        --purge deletes the data of the agent half Lamaste installed)
-  ${c('oidc-clients <name>')}  OIDC clients the plugin declares on Authelia (no secrets)
+  ${c('oidc-clients <name> [grants]')}
+                       OIDC clients the plugin declares on Authelia (no secrets), with grants
+  ${c('oidc-clients <name> grant|revoke <clientId> --user <u>|--group <g>')}
+                       Admit (or no longer) an external member to a client's sign-in —
+                       members of the plugin's domain need no grant
   ${c('rotate-secret <name> <clientId>')}
                        Replace a confidential client's secret — printed once
   ${c('hosting <name>')}       Which agent hosts the plugin's agent half, port, health
@@ -219,6 +248,16 @@ ${b('Subcommands:')}
                        Take every role away
   ${c('identity-sync <name> [--reconcile]')}
                        Sync its audience to its agent half now; --reconcile replays all of it
+  ${c('domain <name> [<d>]')}  The domain a plugin belongs to (its OIDC sign-in, surfaces, audience);
+                       with <d>, move it to that active domain (refused while a surface is served)
+  ${c('web-surface <name>')}   The site a plugin owns for its web surface: what it declares, its site,
+                       whether it is served (and why not), its trees, the bound tunnel, the offer
+  ${c('web-surface <name> create [--subdomain <label>] [--access-mode authenticated|restricted]')}
+                       Give it its site (default: the subdomain and access mode it declares)
+  ${c('web-surface <name> move --tunnel <id | subdomain | fqdn>')}
+                       Hand the host of the tunnel bound as its user surface to its site
+  ${c('web-surface <name> delete [--yes]')}
+                       Delete its site, its trees and the grants on it (typed confirmation)
 `);
 }
 
@@ -796,16 +835,25 @@ function printIdentityBlock(block, title) {
   for (const line of identityBlockLines(block)) console.log(`    ${line}`);
 }
 
+/**
+ * Print a web surface — the web tree an approval covers and the site
+ * Lamaste offers for it (the hook status's `web`).
+ */
+function printWebSurfaceBlock(web, title) {
+  console.log(chalk.bold(`  ${title}`));
+  for (const line of webSurfaceBlockLines(web)) 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, nor an identity block),
- * its relay hook set, the agent half Lamaste installs and its identity
- * block.
+ * relay hooks, nor an agent half Lamaste installs, nor an identity block,
+ * nor a web surface), its relay hook set, the agent half Lamaste installs,
+ * its identity block and its web tree.
  */
-function printApprovalContents({ digest, relay, agentHalf, identity = null }) {
+function printApprovalContents({ digest, relay, agentHalf, identity = null, web = null }) {
   console.log(
-    `    approval digest: ${digest ? chalk.cyan(digest) : chalk.dim('none — no relay hooks, no agent half Lamaste installs, no identity block')}`,
+    `    approval digest: ${digest ? chalk.cyan(digest) : chalk.dim('none — no relay hooks, no agent half Lamaste installs, no identity block, no web surface')}`,
   );
   if (relay) {
     console.log('');
@@ -822,6 +870,27 @@ function printApprovalContents({ digest, relay, agentHalf, identity = null }) {
       'Identity — Lamaste sends its agent half the users entitled to these roles',
     );
   }
+  if (web?.declared) {
+    console.log('');
+    printWebSurfaceBlock(
+      web,
+      'Web surface — the relay serves this tree on the site the plugin owns',
+    );
+  }
+}
+
+/**
+ * Print how an update changes the plugin's web tree (part of the digest):
+ * the tree before and after, its file count and size.
+ */
+function printWebTreeChanges(web) {
+  const shown = webTreeDiffLines(web);
+  if (!shown) return;
+  console.log('');
+  console.log(chalk.bold(`  Web surface — this version ${shown.headline}`));
+  for (const line of shown.lines) {
+    console.log(`    ${shown.changed ? line : chalk.dim(line)}`);
+  }
 }
 
 /**
@@ -874,6 +943,7 @@ function printPendingUpdate(name, update, title) {
     agentHalf: update.agentHalf,
   });
   printIdentityChanges(update.identity);
+  printWebTreeChanges(update.web);
   const lines = settingsDiffLines(update.settings);
   if (lines.length > 0) {
     console.log('');
@@ -916,7 +986,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, no agent half for Lamaste to install and no identity.\n`,
+      `  Plugin ${chalk.cyan(name)} declares no lifecycle hooks, no agent half for Lamaste to install, no identity and no web surface.\n`,
     );
     return;
   }
@@ -933,6 +1003,7 @@ async function hooksCmd(name, { json }) {
       relay: hooks.relay,
       agentHalf: hooks.agentHalf,
       identity: hooks.identity?.declared ? hooks.identity.block : null,
+      web: hooks.web ?? null,
     });
     console.log(
       `\n    auto-approve for later versions: ${hooks.autoApprove ? chalk.yellow('on') : 'off'}`,
@@ -947,6 +1018,13 @@ async function hooksCmd(name, { json }) {
         ),
       );
     }
+    if (hooks.web?.declared) {
+      console.log(
+        chalk.dim(
+          `    Its site (served, trees, offer): lamaste-server plugins web-surface ${terminalText(name)}`,
+        ),
+      );
+    }
   }
   if (hooks.agent) {
     console.log(chalk.bold(`\n  Agent hooks (run by the agent half; no approval)`));
@@ -1262,6 +1340,7 @@ async function installPluginCmd(packageName, { json }) {
       relay: result.hooks.relay,
       agentHalf: result.hooks.agentHalf,
       identity: result.hooks.identity?.declared ? result.hooks.identity.block : null,
+      web: result.hooks.web ?? null,
     });
     if (approval.state === 'pending') {
       console.log(
@@ -1376,13 +1455,25 @@ async function uninstallPluginCmd(name, rest, { json }) {
  * @param {string | undefined} name
  * @param {{ json: boolean }} options
  */
-async function oidcClientsCmd(name, { json }) {
-  if (!name) {
-    const msg = 'Usage: lamaste-server plugins oidc-clients <name>';
+async function oidcClientsCmd(name, rest, { json }) {
+  const usage = () => {
+    const msg =
+      'Usage: lamaste-server plugins oidc-clients <name> [grants | grant|revoke <clientId> --user <u>|--group <g>]';
     if (json) emitError(msg);
     else console.error(`\n  ${msg}\n`);
     process.exit(1);
-  }
+  };
+  if (!name) return usage();
+  const [action, clientId, ...principalArgs] = rest;
+  if (action === 'grant' || action === 'revoke') {
+    const principal = parsePrincipal(principalArgs);
+    if (!clientId || !principal) return usage();
+    return action === 'grant'
+      ? grantOidcClientCmd(clientId, principal, { json })
+      : revokeOidcClientCmd(name, clientId, principal, { json });
+  }
+  if (action !== undefined && (action !== 'grants' || clientId !== undefined)) return usage();
+
   const result = await panelRequest('GET', `/api/plugins/${encodeURIComponent(name)}/oidc-clients`);
   if (json) {
     emit(result);
@@ -1402,7 +1493,7 @@ async function oidcClientsCmd(name, { json }) {
     const kind = c.confidential ? chalk.yellow('confidential') : chalk.green('public');
     const served = c.enabled ? '' : d(' (plugin disabled — not served)');
     console.log(`  ${chalk.cyan(c.id)}  ${kind}${served}`);
-    console.log(`    grants:   ${c.grantTypes.join(', ')}`);
+    console.log(`    flows:    ${c.grantTypes.join(', ')}`);
     console.log(`    scopes:   ${c.scopes.join(', ')}`);
     if (c.audience.length > 0) console.log(`    audience: ${c.audience.join(', ')}`);
     if (c.accessTokenClaims.length > 0) {
@@ -1415,10 +1506,80 @@ async function oidcClientsCmd(name, { json }) {
         }`,
       );
     }
+    if (c.userFacing) {
+      const granted = Array.isArray(c.grants)
+        ? c.grants.length > 0
+          ? c.grants.map(principalText).join(', ')
+          : d('none — external members do not sign in')
+        : chalk.yellow('unknown (Gatekeeper could not be read)');
+      console.log(`    granted:  ${granted}`);
+    }
   }
   console.log('');
 }
 
+/** Grant a user-facing client to a user or a Lamaste group (a Gatekeeper grant the panel checks). */
+async function grantOidcClientCmd(clientId, principal, { json }) {
+  let result;
+  try {
+    result = await panelRequest('POST', '/api/gatekeeper/grants', {
+      ...principal,
+      resourceType: OIDC_CLIENT_RESOURCE,
+      resourceId: clientId,
+    });
+  } catch (err) {
+    failPanel(err.message, json, err);
+  }
+  if (json) {
+    emitComplete(result);
+    return;
+  }
+  console.log(
+    `\n  ${chalk.green('✓')} ${principalText(principal)} may sign in with ${terminalText(clientId)}\n`,
+  );
+}
+
+/** Revoke the grant of a user-facing client to a user or a Lamaste group. */
+async function revokeOidcClientCmd(name, clientId, principal, { json }) {
+  let found;
+  try {
+    const { clients } = await panelRequest(
+      'GET',
+      `/api/plugins/${encodeURIComponent(name)}/oidc-clients`,
+    );
+    found = findClientGrants(clients ?? [], clientId, principal);
+  } catch (err) {
+    failPanel(err.message, json, err);
+  }
+  if ('error' in found) {
+    const reason = {
+      no_client: `Plugin ${name} declares no user-facing OIDC client ${clientId}`,
+      unreadable: "Gatekeeper's grants could not be read — try again",
+      no_grant: `${clientId} is not granted to ${principalText(principal)}`,
+    }[found.error];
+    failPanel(reason, json);
+  }
+  // Every grant naming the principal goes: one left behind would still let
+  // them sign in.
+  const results = [];
+  try {
+    for (const grantId of found.grantIds) {
+      results.push(
+        await panelRequest('DELETE', `/api/gatekeeper/grants/${encodeURIComponent(grantId)}`),
+      );
+    }
+  } catch (err) {
+    failPanel(err.message, json, err);
+  }
+  if (json) {
+    emitComplete({ revoked: found.grantIds.length, results });
+    return;
+  }
+  console.log(
+    `\n  ${chalk.green('✓')} ${principalText(principal)} no longer signs in with ${terminalText(clientId)}\n`,
+  );
+}
+
 /**
  * @param {string | undefined} name
  * @param {string | undefined} clientId

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

@@ -4,7 +4,7 @@
  * for agents.
  *
  *   registry-credential show
- *   registry-credential set --url <registry> --oidc
+ *   registry-credential set --url <registry> --oidc [--issuer-domain <domain>]
  *       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
@@ -35,7 +35,7 @@ export async function runRegistryCredential(args, { json }) {
       return clear({ json });
     default:
       process.stderr.write(
-        `Usage: lamaste-server registry-credential <show | set --url <registry> (--oidc | --token-stdin) | clear>\n`,
+        `Usage: lamaste-server registry-credential <show | set --url <registry> (--oidc [--issuer-domain <domain>] | --token-stdin) | clear>\n`,
       );
       process.exit(1);
   }
@@ -68,6 +68,7 @@ async function set(args, { json }) {
   let url;
   let tokenFromStdin = false;
   let oidc = false;
+  let issuerDomain;
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
     if (arg === '--url') {
@@ -78,6 +79,8 @@ async function set(args, { json }) {
       tokenFromStdin = true;
     } else if (arg === '--oidc') {
       oidc = true;
+    } else if (arg === '--issuer-domain') {
+      issuerDomain = args[++i]?.toLowerCase();
     } else if (arg === '--token' || arg.startsWith('--token=')) {
       throw new Error(
         'The token is never accepted on the command line — set LAMASTE_REGISTRY_TOKEN or use --token-stdin',
@@ -87,13 +90,17 @@ async function set(args, { json }) {
     }
   }
   if (!url) throw new Error('registry-credential set: --url <registry> is required');
+  if (issuerDomain !== undefined && !oidc) {
+    throw new Error('registry-credential set: --issuer-domain goes with --oidc');
+  }
   if (oidc && tokenFromStdin) {
     throw new Error('registry-credential set: choose --oidc or --token-stdin, not both');
   }
 
   let auth;
   if (oidc) {
-    auth = { kind: 'oidc' };
+    // The domain whose issuer (https://auth.<domain>) the registry trusts; the primary when absent.
+    auth = { kind: 'oidc', ...(issuerDomain ? { issuerDomain } : {}) };
   } else {
     let token = tokenFromStdin ? (await readStdin()).trim() : process.env.LAMASTE_REGISTRY_TOKEN;
     if (!token) {

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

@@ -7,6 +7,10 @@
  *   delete <id>                     Delete a site by ID
  *   aliases <id> --set <a,b|"">     Replace a custom site's redirect aliases
  *
+ * A site a plugin owns (its web surface) is marked in the list and managed
+ * through `lamaste-server plugins web-surface <plugin>`; the panel refuses
+ * to change or delete it here.
+ *
  * List reads directly from the state file.
  * Create/delete use the panel REST API (which has the full
  * nginx/certbot/directory dependency stack).
@@ -16,6 +20,7 @@ import chalk from 'chalk';
 import { readSites } from '../state.js';
 import { panelRequest } from '../panel-api.js';
 import { emit, emitError, emitComplete } from '../ndjson.js';
+import { siteOwnerTag } from '../plugin-web-surface.js';
 
 /**
  * @param {string[]} args
@@ -56,6 +61,7 @@ ${b('Create options:')}
   --type <type>         Site type: managed (default) or custom
   --custom-domain <d>   Custom domain (required if type is custom)
   --aliases <a,b>       Hostnames that redirect to the custom domain (e.g. www.<domain>)
+  --domain <domain>     A managed site's base domain, an active one (default: the primary)
   --spa                 Enable SPA mode (single-page application routing)
   --authelia            Enable Authelia protection
 `);
@@ -92,12 +98,21 @@ async function listSites({ json }) {
     const certStatus = s.certIssued ? g('cert issued') : y('no cert');
     const spaTag = s.spaMode ? d('[SPA]') : '';
     const authTag = s.autheliaProtected ? d('[protected]') : '';
+    const owner = siteOwnerTag(s);
+    const ownerTag = owner ? c(owner) : '';
 
     console.log(
-      `  ${c(s.name)}  ${d(s.fqdn)}  ${s.type}  ${dnsStatus}  ${certStatus} ${spaTag} ${authTag}`.trimEnd(),
+      `  ${c(s.name)}  ${d(s.fqdn)}  ${s.type}  ${dnsStatus}  ${certStatus} ${spaTag} ${authTag} ${ownerTag}`.trimEnd(),
     );
     console.log(`    ${d(`id: ${s.id}`)}`);
   }
+  if (sites.some((s) => siteOwnerTag(s) !== null)) {
+    console.log(
+      d(
+        '\n  A [plugin …] site is the web surface of that plugin: manage it with lamaste-server plugins web-surface <plugin>',
+      ),
+    );
+  }
   console.log('');
 }
 
@@ -110,6 +125,7 @@ async function createSite(args, { json }) {
   const type = getArg(args, 'type') || 'managed';
   const customDomain = getArg(args, 'custom-domain') || undefined;
   const aliasArg = getArg(args, 'aliases');
+  const domain = getArg(args, 'domain');
   const spaMode = args.includes('--spa');
   const autheliaProtected = args.includes('--authelia');
 
@@ -138,6 +154,7 @@ async function createSite(args, { json }) {
   const body = { name, type, spaMode, autheliaProtected };
   if (customDomain) body.customDomain = customDomain;
   if (aliasArg) body.aliases = splitAliases(aliasArg);
+  if (domain) body.domain = domain.toLowerCase();
 
   if (!json) process.stderr.write(`  Creating site ${chalk.cyan(name)}...`);
 

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

@@ -10,6 +10,8 @@ import { readConfigSafe, PANEL_SERVICE, GATEKEEPER_SERVICE, PKI_DIR } from '../c
 import { getMtlsCerts } from '@lamalibre/lamaste/server';
 import { exec } from '../exec.js';
 import { emit } from '../ndjson.js';
+import { panelRequest } from '../panel-api.js';
+import { domainRows } from '../domains.js';
 
 /**
  * @param {{ json: boolean }} options
@@ -20,6 +22,15 @@ export async function runStatus({ json }) {
 
   // Collect service statuses
   const panelStatus = await getServiceStatus(PANEL_SERVICE);
+  // The relay's domains, from the running panel — asked while the other
+  // checks run, briefly; none while it is down or not onboarded.
+  const domainsRequest =
+    domain && panelStatus.active
+      ? panelRequest('GET', '/api/domains', null, { timeoutMs: 4000 }).then(
+          (r) => r.domains ?? [],
+          () => null,
+        )
+      : Promise.resolve(null);
   const gatekeeperStatus = await getServiceStatus(GATEKEEPER_SERVICE);
   const nginxStatus = await getServiceStatus('nginx');
   const autheliaStatus = await getServiceStatus('authelia');
@@ -35,10 +46,12 @@ export async function runStatus({ json }) {
   // Collect system info
   const uptime = await getUptime();
   const memory = await getMemoryUsage();
+  const domains = await domainsRequest;
 
   if (json) {
     emit({
       domain,
+      domains,
       services: {
         panel: panelStatus,
         gatekeeper: gatekeeperStatus,
@@ -66,6 +79,12 @@ export async function runStatus({ json }) {
   if (domain) {
     console.log(`  ${b('Domain:')}     ${c(String(domain))}`);
   }
+  if (domains && domains.length > 1) {
+    console.log(`  ${b('Domains:')}`);
+    for (const row of domainRows(domains)) {
+      console.log(`    ${c(row.name)} ${d(`${row.state}, ${row.members} member(s)`)}`);
+    }
+  }
 
   if (uptime) {
     console.log(`  ${b('Uptime:')}     ${d(uptime)}`);

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

@@ -89,6 +89,7 @@ ${b('Create options:')}
   --description <text>  Optional description
   --access-mode <mode>  Access mode: public, authenticated, restricted (default: restricted)
   --max-body-mb <n>     Largest request body in MiB, 1-10240 (default: 10)
+  --domain <domain>     Base domain of the hostname, an active one (default: the primary)
 `);
 }
 
@@ -125,7 +126,7 @@ async function listTunnels({ json }) {
     const carrier = t.agentLabel ? d(`via ${t.agentLabel}`) : r('no agent');
     const bodyLimit = t.type !== 'panel' ? d(`${t.maxBodySizeMb ?? 1} MiB`) : '';
     console.log(
-      `  ${c(t.subdomain)} \u2192 :${t.port}  ${enabled} ${carrier} ${accessMode} ${bodyLimit} ${type}`.trimEnd(),
+      `  ${c(t.fqdn ?? t.subdomain)} \u2192 :${t.port}  ${enabled} ${carrier} ${accessMode} ${bodyLimit} ${type}`.trimEnd(),
     );
     if (t.description) {
       console.log(`    ${d(t.description)}`);
@@ -150,6 +151,7 @@ async function createTunnel(args, { json }) {
   const accessMode = getArg(args, 'access-mode') || undefined;
   const agentLabel = getArg(args, 'agent');
   const maxBodyStr = getArg(args, 'max-body-mb');
+  const domain = getArg(args, 'domain');
 
   if (!subdomain || !portStr || !agentLabel) {
     const msg = 'Error: --subdomain, --port and --agent are required';
@@ -180,6 +182,7 @@ async function createTunnel(args, { json }) {
   if (description) body.description = description;
   if (accessMode) body.accessMode = accessMode;
   if (maxBodySizeMb !== undefined) body.maxBodySizeMb = maxBodySizeMb;
+  if (domain) body.domain = domain.toLowerCase();
 
   if (!json) process.stderr.write(`  Creating tunnel ${chalk.cyan(subdomain)} \u2192 :${port}...`);
 

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

@@ -31,9 +31,11 @@
 
 import chalk from 'chalk';
 import { panelRequest } from '../panel-api.js';
-import { emit, emitComplete, emitError } from '../ndjson.js';
+import { emit, emitComplete } from '../ndjson.js';
+import { fail } from '../fail.js';
 import { parseUserArgs, warningLine } from '../plugin-identity.js';
 import { formatMoment, terminalText } from '../plugin-settings.js';
+import { membershipsText } from '../domains.js';
 
 /**
  * @param {string[]} args  Subcommand args: ['list'] | ['disable', '<u>'] | ...
@@ -78,21 +80,6 @@ ${b('Subcommands:')}
 `);
 }
 
-/**
- * Exit with a usage error or a refused request, as text or NDJSON (with
- * the refusal's `code`, e.g. `last_admin`, `user_not_removed`).
- *
- * @param {string} message
- * @param {boolean} json
- * @param {{ code?: string }} [err]
- * @returns {never}
- */
-function fail(message, json, err = {}) {
-  if (json) emitError(message, false, typeof err.code === 'string' ? { code: err.code } : {});
-  else console.error(`\n  ${chalk.red(terminalText(message))}\n`);
-  process.exit(1);
-}
-
 /** Print a change's warnings: what the panel could not complete beside it. */
 function printWarnings(warnings) {
   for (const warning of warnings ?? []) {
@@ -107,7 +94,8 @@ function statusCell(status) {
 
 /**
  * The rows `users list` prints: each user's username, status, directory id
- * (a dash until the directory has seen them) and groups, as terminal text.
+ * (a dash until the directory has seen them), groups and domain memberships
+ * (external ones marked), as terminal text.
  * Pure, exported for tests.
  *
  * @param {Array<Record<string, any>>} users  as `GET /api/users` lists them
@@ -118,6 +106,7 @@ export function userRows(users) {
     status: u.status === 'disabled' ? 'disabled' : 'active',
     userId: u.userId ? terminalText(u.userId) : '—',
     groups: terminalText((u.groups ?? []).join(', ')),
+    domains: membershipsText(u.domains),
   }));
 }
 
@@ -142,11 +131,11 @@ async function listUsers({ json }) {
   console.log('');
   console.log(chalk.bold('  Users'));
   console.log(
-    chalk.dim(`  ${'USERNAME'.padEnd(width)}  STATUS    ${'USER ID'.padEnd(36)}  GROUPS`),
+    chalk.dim(`  ${'USERNAME'.padEnd(width)}  STATUS    ${'USER ID'.padEnd(36)}  DOMAINS  GROUPS`),
   );
   for (const r of rows) {
     console.log(
-      `  ${chalk.cyan(r.username.padEnd(width))}  ${statusCell(r.status)}  ${r.userId.padEnd(36)}  ${chalk.dim(r.groups)}`,
+      `  ${chalk.cyan(r.username.padEnd(width))}  ${statusCell(r.status)}  ${r.userId.padEnd(36)}  ${r.domains}  ${chalk.dim(r.groups)}`,
     );
   }
   if (rows.some((r) => r.userId === '—')) {

package/vendor/server/src/domains.js

@@ -0,0 +1,92 @@
+/**
+ * The relay's domains as `lamaste-server domains` prints them — pure
+ * helpers, exported for tests (the command is src/commands/domains.js).
+ */
+
+import { terminalText } from './plugin-settings.js';
+
+/**
+ * One row per domain: name, state, members, what uses it — as terminal text.
+ *
+ * @param {Array<Record<string, any>>} domains  as `GET /api/domains` lists them
+ */
+export function domainRows(domains) {
+  return domains.map((d) => ({
+    name: terminalText(d.name),
+    state: d.status === 'active' ? (d.primary ? 'primary' : 'active') : 'pending',
+    members: Number.isInteger(d.members) ? d.members : 0,
+    externalMembers: Number.isInteger(d.externalMembers) ? d.externalMembers : 0,
+    usedBy: usageText(d.usedBy),
+  }));
+}
+
+/** What uses a domain, in one line (empty when nothing does). */
+export function usageText(usedBy) {
+  if (!usedBy) return '';
+  const parts = [];
+  const count = (label, items) => {
+    if (Array.isArray(items) && items.length > 0) parts.push(`${items.length} ${label}`);
+  };
+  count('tunnel(s)', usedBy.tunnels);
+  count('site(s)', usedBy.sites);
+  count('plugin(s)', usedBy.plugins);
+  if (usedBy.registry) parts.push('the registry credential');
+  return parts.join(', ');
+}
+
+/** `/api/domains/<name><rest>`. */
+export function domainPath(name, rest = '') {
+  return `/api/domains/${encodeURIComponent(name)}${rest}`;
+}
+
+/**
+ * A user's memberships in one line — `a.example, b.example (external)` —
+ * as terminal text; `—` for none. A bare name (an older panel's answer) is
+ * a member.
+ *
+ * @param {ReadonlyArray<string | { name: string, kind?: string }> | undefined} domains
+ */
+export function membershipsText(domains) {
+  const parts = (domains ?? []).flatMap((d) => {
+    const name = typeof d === 'string' ? d : d?.name;
+    if (typeof name !== 'string') return [];
+    return [terminalText(d?.kind === 'external' ? `${name} (external)` : name)];
+  });
+  return parts.length > 0 ? parts.join(', ') : '—';
+}
+
+/** Whether any of `domains` is an external membership. */
+export function isExternalAnywhere(domains) {
+  return (domains ?? []).some((d) => d?.kind === 'external');
+}
+
+/**
+ * What `domains members <domain> <action> <user> …` asks the panel, or
+ * null for a command line it does not take:
+ *
+ * - `add <user> [--external]` — a member (an external one with the flag);
+ * - `kind <user> member|external` — change the kind of a membership;
+ * - `remove <user>` — end it.
+ *
+ * `user` is a directory id or a username.
+ *
+ * @param {string} domain
+ * @param {string[]} rest  what follows `members <domain>`
+ * @returns {{ method: 'PUT' | 'DELETE', path: string, body: object | null, user: string, kind: 'member' | 'external' | null } | null}
+ */
+export function memberRequest(domain, rest) {
+  const [action, user, ...more] = rest;
+  if (!user) return null;
+  const path = domainPath(domain, `/members/${encodeURIComponent(user)}`);
+  if (action === 'remove' && more.length === 0) {
+    return { method: 'DELETE', path, body: null, user, kind: null };
+  }
+  if (action === 'add' && more.every((a) => a === '--external')) {
+    const kind = more.length > 0 ? 'external' : 'member';
+    return { method: 'PUT', path, body: { kind }, user, kind };
+  }
+  if (action === 'kind' && more.length === 1 && (more[0] === 'member' || more[0] === 'external')) {
+    return { method: 'PUT', path, body: { kind: more[0] }, user, kind: more[0] };
+  }
+  return null;
+}