@lamalibre/create-lamaste 4.4.1 → 4.6.0

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

@@ -19,6 +19,7 @@ import {
   RESERVED_NAV_LABELS,
   derivePluginRoute,
   hasAgentHalf,
+  normalizeIdentityBlock,
   pluginHostCapability,
   validateManifest as coreValidateManifest,
 } from '@lamalibre/lamaste';
@@ -30,6 +31,7 @@ import { RegistryCredentialError } from '@lamalibre/lamaste/server';
 import {
   bareLamalibrePackageName,
   installedHookEntrySha256,
+  installedWebTreeSha256,
   pinAgentHalf,
 } from './plugin-packages.js';
 
@@ -71,10 +73,13 @@ async function getStmts() {
       INSERT INTO plugins
         (name, route, display_name, package_name, version, description, capabilities,
          packages, panel, config, modes, hosting, agent, hooks, hooks_entry_sha256,
-         agent_half_pin, settings, status, installed_at, enabled_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         agent_half_pin, settings, identity, user_surface, web_tree_sha256, status,
+         installed_at, enabled_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `),
     deleteByName: db.prepare('DELETE FROM plugins WHERE name = ?'),
+    // The plugin's audience and the state of its identity feed
+    // (lib/audience.js, lib/identity-sync.js) go with its row.
     // The relay's cache of the plugin's settings (lib/plugin-settings.js)
     // goes with its row, and follows its settings schema.
     deleteSettingsByName: db.prepare('DELETE FROM plugin_settings WHERE plugin = ?'),
@@ -137,6 +142,9 @@ function rowToPlugin(row) {
   if (row.hooks_entry_sha256 != null) entry.hooksEntrySha256 = row.hooks_entry_sha256;
   if (row.agent_half_pin != null) entry.agentHalfPin = JSON.parse(row.agent_half_pin);
   if (row.settings != null) entry.settings = JSON.parse(row.settings);
+  if (row.identity != null) entry.identity = JSON.parse(row.identity);
+  if (row.user_surface != null) entry.userSurface = JSON.parse(row.user_surface);
+  if (row.web_tree_sha256 != null) entry.webTreeSha256 = row.web_tree_sha256;
   if (row.enabled_at != null) entry.enabledAt = row.enabled_at;
   return entry;
 }
@@ -149,6 +157,29 @@ function nullableJson(value) {
   return value === undefined || value === null ? null : JSON.stringify(value);
 }
 
+/**
+ * A manifest's `identity` block as the registry stores it — normalized
+ * (core `normalizeIdentityBlock`: roles by id, attributes sorted, the
+ * default applied) — or undefined when it declares none. The stored block
+ * enters the approval digest.
+ *
+ * @param {{ identity?: import('@lamalibre/lamaste').IdentityBlockInput }} manifest
+ * @returns {import('@lamalibre/lamaste').NormalizedIdentityBlock | undefined}
+ */
+export function identityOf(manifest) {
+  return manifest.identity ? normalizeIdentityBlock(manifest.identity) : undefined;
+}
+
+/** Recompute the plugin audiences (lib/audience.js) beside other work — never throws. */
+async function recomputeAudiencesInBackground(logger) {
+  try {
+    const { recomputeAudiences } = await import('./audience.js');
+    void recomputeAudiences({ logger });
+  } catch (err) {
+    logger?.warn({ err: err.message }, 'Could not recompute the plugin audiences');
+  }
+}
+
 // --- Plugin registry persistence ---
 
 /**
@@ -196,6 +227,9 @@ export async function writePlugins(data) {
         nullableString(p.hooksEntrySha256),
         nullableJson(p.agentHalfPin),
         nullableJson(p.settings),
+        nullableJson(p.identity),
+        nullableJson(p.userSurface),
+        nullableString(p.webTreeSha256),
         p.status,
         p.installedAt,
         nullableString(p.enabledAt),
@@ -429,6 +463,17 @@ export function installPlugin(packageName, logger) {
       throw Object.assign(new Error(err.message), { statusCode: err.statusCode || 400 });
     }
 
+    // A web surface: its tree must be in the package and keep every rule of
+    // a web tree; its digest goes into the approval digest, and the relay
+    // serves only a copy that matches it.
+    let webTreeSha256 = null;
+    try {
+      webTreeSha256 = await installedWebTreeSha256(packageName, manifest);
+    } catch (err) {
+      await discardPackage();
+      throw Object.assign(new Error(err.message), { statusCode: err.statusCode || 400 });
+    }
+
     // An agent half Lamaste installs: its tarball's integrity is pinned now,
     // from the registry this install used — the approval covers it and the
     // agent installs only a tarball that matches it.
@@ -479,6 +524,9 @@ export function installPlugin(packageName, logger) {
       hooksEntrySha256,
       agentHalfPin,
       settings: manifest.settings,
+      identity: identityOf(manifest),
+      userSurface: manifest.userSurface,
+      webTreeSha256,
       status: 'disabled',
       installedAt: new Date().toISOString(),
     };
@@ -506,6 +554,9 @@ export function installPlugin(packageName, logger) {
         nullableString(entry.hooksEntrySha256),
         nullableJson(entry.agentHalfPin),
         nullableJson(entry.settings),
+        nullableJson(entry.identity),
+        nullableJson(entry.userSurface),
+        nullableString(entry.webTreeSha256),
         entry.status,
         entry.installedAt,
         null,
@@ -518,6 +569,13 @@ export function installPlugin(packageName, logger) {
 
     logger.info({ name: manifest.name, packageName }, 'Plugin installed');
     const oidcClients = await syncOidcClientsBestEffort(logger);
+    // Users already entitled to its route (grants that outlived an earlier
+    // installation) make up its audience from the start.
+    if (entry.identity) await recomputeAudiencesInBackground(logger);
+    // A new installation is served on no host (its version is not approved
+    // yet): a vhost still carrying the route from before goes in line.
+    const { refreshUserSurfaceVhosts } = await import('./user-surface.js');
+    await refreshUserSurfaceVhosts(entry.route, logger);
     return { ...entry, oidcClients };
   });
 }
@@ -591,6 +649,17 @@ export function uninstallPlugin(name, logger) {
       throw err;
     }
 
+    // Its identity ledger — everyone its agent halves were sent, and the
+    // erasures it owes — stays while an agent keeps its data (an uninstall
+    // without purge); with no data left anywhere it goes. A later install
+    // replays whatever is left of it at its first hosting.
+    try {
+      const { dropIdentityLedgerIfNoData } = await import('./audience.js');
+      await dropIdentityLedgerIfNoData(name, logger);
+    } catch (err) {
+      logger.warn({ name, err: err.message }, 'Could not settle the identity ledger on uninstall');
+    }
+
     // Sweep this plugin's capabilities off every agent so re-installing the
     // plugin later does NOT silently re-grant. Failure here is non-fatal
     // (the plugin is already gone), but logged loudly. A plugin without a
@@ -619,6 +688,11 @@ export function uninstallPlugin(name, logger) {
       );
     }
 
+    // Its user surface is unbound from every host, so a later install
+    // starts unbound (a plugin sharing another's route never held one).
+    const { releasePluginUserSurface } = await import('./user-surface.js');
+    await releasePluginUserSurface(plugin.route, { plugin: name, logger });
+
     logger.info({ name }, 'Plugin uninstalled');
     await syncOidcClientsBestEffort(logger);
     return { ok: true, name };
@@ -631,7 +705,7 @@ const updateRowSql = `
   UPDATE plugins SET
     display_name = ?, version = ?, description = ?, capabilities = ?, packages = ?, panel = ?,
     config = ?, modes = ?, hosting = ?, agent = ?, hooks = ?, hooks_entry_sha256 = ?,
-    agent_half_pin = ?, settings = ?
+    agent_half_pin = ?, settings = ?, identity = ?, user_surface = ?, web_tree_sha256 = ?
   WHERE name = ?`;
 
 /**
@@ -643,9 +717,18 @@ const updateRowSql = `
  * (`prunedSettingsCache`) — so no read pairs the new schema with values
  * stored for the old one: a value whose field became a secret never shows
  * beside it, and a secret whose field became a plain value is no longer
- * reported set.
+ * reported set. The identity block is stored normalized; the update's
+ * caller recomputes the audiences once the version is in place.
+ * `webTreeSha256` is the digest of the version's web tree, read from the
+ * installed package (null when it declares no web surface).
  */
-export async function writePluginRow(name, manifest, hooksEntrySha256, agentHalfPin) {
+export async function writePluginRow(
+  name,
+  manifest,
+  hooksEntrySha256,
+  agentHalfPin,
+  webTreeSha256 = null,
+) {
   const s = await getStmts();
   const { prunedSettingsCache } = await import('./plugin-settings.js');
   s.begin.run();
@@ -668,6 +751,9 @@ export async function writePluginRow(name, manifest, hooksEntrySha256, agentHalf
         nullableString(hooksEntrySha256),
         nullableJson(agentHalfPin),
         nullableJson(manifest.settings),
+        nullableJson(identityOf(manifest)),
+        nullableJson(manifest.userSurface),
+        nullableString(webTreeSha256),
         name,
       );
     const pruned = prunedSettingsCache(
@@ -695,7 +781,8 @@ export async function writePluginRow(name, manifest, hooksEntrySha256, agentHalf
 
 /**
  * Install `<packageName>@<version>` over the installed copy and read it
- * back: the validated manifest and its relay entry module's SHA-256. The
+ * back: the validated manifest, its relay entry module's SHA-256 and its
+ * web tree's digest. The
  * row is not touched — the caller compares the result with what was
  * reviewed and then writes it. Refuses a package whose manifest names
  * another plugin.
@@ -735,7 +822,8 @@ export function replacePluginPackage(name, packageName, version, logger) {
       );
     }
     const hooksEntrySha256 = await installedHookEntrySha256(packageName, manifest);
-    return { manifest, hooksEntrySha256 };
+    const webTreeSha256 = await installedWebTreeSha256(packageName, manifest);
+    return { manifest, hooksEntrySha256, webTreeSha256 };
   });
 }
 

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

@@ -96,7 +96,7 @@ async function oidcDeps(config) {
 
 /**
  * Verify a candidate credential end to end (for `oidc`: Authelia token
- * endpoint → Feria login → whoami with the admin scope). The
+ * endpoint → Feria login → whoami with the read and admin scopes). 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
@@ -158,14 +158,17 @@ export async function acquireAgentToken(agentLabel) {
 
 /**
  * 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).
+ * they were offboarded (`{ deleted: true }`: disabled or removed). Returns
+ * the number revoked, or `null` when nothing needed doing (no credential
+ * configured, or no feria group lost). The registry knows the user by
+ * username (`user:<username>`); the log line names them by `userId` alone.
  *
  * @param {string} username
  * @param {{ before: string[], after: string[] } | { deleted: true }} change
- * @param {import('pino').Logger} log
+ * @param {import('pino').Logger | undefined} log
+ * @param {{ userId?: string | null }} [who]
  */
-export async function revokeUserRegistryTokens(username, change, log) {
+export async function revokeUserRegistryTokens(username, change, log, { userId = null } = {}) {
   const config = await readRegistryCredentialConfig();
   if (!config) return null;
 
@@ -177,6 +180,6 @@ export async function revokeUserRegistryTokens(username, change, log) {
   const revoked = await revokeRegistryTokensForOwner(config, owner, {
     serviceToken: await serviceToken(config),
   });
-  log.info({ username, lost, revoked }, 'Revoked registry tokens after group change');
+  log?.info({ userId, lost, revoked }, 'Revoked a user’s registry tokens');
   return revoked;
 }

package/vendor/serverd/src/lib/request-logging.js

@@ -0,0 +1,19 @@
+/**
+ * How the panel logs its requests: one metadata line per request (core
+ * `logRequestMetadata`) instead of Fastify's own lines, which carry every
+ * URL with its query and the client address. The line has the method, the
+ * route pattern (never the URL a username or a query may be in), the
+ * status, the duration and the caller's certificate role; the client
+ * address only for certificate holders — administrators and agents, not
+ * people: never for a user of a plugin's user surface, the desktop's
+ * user-access calls or the public routes.
+ */
+
+/** Callers whose address a request line may carry: certificate holders, not people. */
+const CERT_ROLES_LOGGED_WITH_IP = new Set(['admin', 'agent', 'plugin-agent']);
+
+/** The options the panel passes to `logRequestMetadata`. */
+export const panelRequestLogOptions = Object.freeze({
+  fields: (request) => ({ certRole: request.certRole ?? null }),
+  logIp: (request) => CERT_ROLES_LOGGED_WITH_IP.has(request.certRole),
+});

package/vendor/serverd/src/lib/retained-data.js

@@ -38,18 +38,64 @@ function rowToRecord(row) {
  * agent package `pkg` of plugin `plugin`. A record that exists already keeps
  * its `since` — the data has been there since then.
  *
+ * With it goes how far the agent half's identity projection — part of that
+ * data — had applied the plugin's feed, as the half last answered (the
+ * plugin's feed state, read now, before the hosting's is forgotten): the
+ * erasures of the plugin's ledger after that cursor are pending on this
+ * agent (`pendingErasures` in `lib/identity-sync.js`). When the relay knows
+ * no position, a record that exists keeps the one it had — the projection
+ * did not move without a feed.
+ *
  * @param {{ agentLabel: string, route: string, plugin: string, package: string, operation?: string | null }} record
  */
 export async function recordRetainedData({ agentLabel, route, plugin, package: pkg, operation }) {
   const db = await getStateDb();
+  const feed = db
+    .prepare('SELECT directory_id, cursor FROM plugin_identity_sync WHERE plugin = ?')
+    .get(plugin);
+  const known = feed && feed.directory_id !== null && feed.cursor !== null;
   db.prepare(
-    `INSERT INTO retained_agent_data (agent_label, route, plugin, package, since, operation)
-     VALUES (?, ?, ?, ?, ?, ?)
+    `INSERT INTO retained_agent_data
+       (agent_label, route, plugin, package, since, operation, identity_directory_id, identity_cursor)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)
      ON CONFLICT(agent_label, route) DO UPDATE SET
        plugin = excluded.plugin,
        package = excluded.package,
-       operation = excluded.operation`,
-  ).run(agentLabel, route, plugin, pkg, new Date().toISOString(), operation ?? null);
+       operation = excluded.operation,
+       identity_directory_id = CASE WHEN excluded.identity_cursor IS NULL
+         THEN identity_directory_id ELSE excluded.identity_directory_id END,
+       identity_cursor = COALESCE(excluded.identity_cursor, identity_cursor)`,
+  ).run(
+    agentLabel,
+    route,
+    plugin,
+    pkg,
+    new Date().toISOString(),
+    operation ?? null,
+    known ? feed.directory_id : null,
+    known ? Number(feed.cursor) : null,
+  );
+}
+
+/**
+ * Where the identity projection in each record's data stands, for plugin
+ * `plugin`: `[{ agentLabel, directoryId, cursor }]` (both null when unknown).
+ *
+ * @param {string} plugin
+ */
+export async function retainedIdentityPositions(plugin) {
+  const db = await getStateDb();
+  return db
+    .prepare(
+      `SELECT agent_label, identity_directory_id, identity_cursor FROM retained_agent_data
+       WHERE plugin = ? ORDER BY since, agent_label`,
+    )
+    .all(plugin)
+    .map((row) => ({
+      agentLabel: row.agent_label,
+      directoryId: row.identity_directory_id,
+      cursor: row.identity_cursor === null ? null : Number(row.identity_cursor),
+    }));
 }
 
 /** Drop the record of the data agent `agentLabel` keeps for route `route` (purged, or taken back). */

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

@@ -1,5 +1,6 @@
 import { readFile, writeFile, rename, open } from 'node:fs/promises';
 import path from 'node:path';
+import { PromiseChainMutex } from '@lamalibre/lamaste';
 
 const STATE_DIR = process.env.LAMALIBRE_LAMASTE_STATE_DIR || '/etc/lamalibre/lamaste';
 
@@ -94,6 +95,24 @@ export async function writeSites(sites) {
   await rename(tmpPath, filePath);
 }
 
+/** Serializes every read-modify-write of sites.json in this process. */
+const sitesMutex = new PromiseChainMutex();
+
+/**
+ * Run `fn` holding the sites lock: a read of sites.json, the decisions made
+ * on it and the write that follows must not interleave with another. A
+ * workflow that gives a site a hostname (creating it, adding an alias,
+ * taking a tunnel's host) takes core's tunnel lock first, then this one —
+ * always in that order — so a site and a tunnel never take one name at once.
+ *
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+export function withSitesLock(fn) {
+  return sitesMutex.run(fn);
+}
+
 function invitationsPath() {
   return path.join(STATE_DIR, 'invitations.json');
 }
@@ -138,3 +157,20 @@ export async function writeInvitations(invitations) {
 
   await rename(tmpPath, filePath);
 }
+
+/** Serializes every read-modify-write of invitations.json in this process. */
+const invitationsMutex = new PromiseChainMutex();
+
+/**
+ * Run `fn` holding the invitations lock: a read of invitations.json, the
+ * decisions made on it and the write that follows must not interleave with
+ * another — creating, revoking, accepting an invitation, and purging a
+ * removed user's.
+ *
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+export function withInvitationsLock(fn) {
+  return invitationsMutex.run(fn);
+}

package/vendor/serverd/src/lib/tunnel-hooks.js

@@ -12,7 +12,8 @@
  * Whenever the plugin comes up — after a `down`, or first seen up — the
  * relay also re-reads its settings from the agent half: they may have
  * changed while the relay could not see it (a restore, a retyped field
- * dropped by a new version).
+ * dropped by a new version) — and, for a plugin that declares identity,
+ * sends its agent half the audience changes it missed while it was down.
  *
  * Calls for one plugin are serialised and run beside the monitor, which
  * does not wait for them.
@@ -27,6 +28,7 @@ import {
 import { runRelayHook } from './relay-hooks.js';
 import { rememberTunnelFallback } from './request-hooks.js';
 import { refreshPluginSettingsBestEffort } from './plugin-settings.js';
+import { syncPluginIdentity } from './identity-sync.js';
 
 const chains = new Map();
 
@@ -44,6 +46,7 @@ export function onHealthTransition(plugin, before, after, logger) {
     .then(async () => {
       if (after.state === 'up' && before?.state !== 'up') {
         await refreshPluginSettingsBestEffort(plugin, logger);
+        await syncPluginIdentity(plugin, { logger });
       }
     });
   chains.set(plugin, next);

package/vendor/serverd/src/lib/user-access-session.js

@@ -1,4 +1,5 @@
 import crypto from 'node:crypto';
+import { isIdentityUuid } from '@lamalibre/lamaste';
 
 const SESSION_MAX_AGE = 12 * 60 * 60; // 12 hours in seconds
 const INACTIVITY_TIMEOUT = 2 * 60 * 60; // 2 hours in seconds
@@ -21,19 +22,23 @@ function signPayload(payloadB64, secretHex) {
 }
 
 /**
- * Create a signed user-access session token.
+ * Create a signed user-access session token, bound to the user's directory
+ * id as well as their username: a later user given the same username never
+ * holds this session (the middleware checks the username's current holder).
  *
  * @param {string} sessionSecret - Hex-encoded session secret
- * @param {string} username - Authelia username to bind the session to
+ * @param {{ username: string, userId: string }} user - the Authelia username and its directory id
  * @returns {{ value: string, maxAge: number, expiresAt: string }}
  */
-export function createUserSession(sessionSecret, username) {
+export function createUserSession(sessionSecret, { username, userId }) {
+  if (!isIdentityUuid(userId)) throw new Error('A user session names a directory user id');
   const now = Math.floor(Date.now() / 1000);
   const payload = {
     iat: now,
     exp: now + SESSION_MAX_AGE,
     lastActivity: now,
     username,
+    userId,
     type: 'user-access',
   };
   const payloadB64 = Buffer.from(JSON.stringify(payload)).toString('base64url');
@@ -52,10 +57,12 @@ export function createUserSession(sessionSecret, username) {
  * @param {string} tokenValue - The token (payload.sig)
  * @param {string} sessionSecret - Hex-encoded session secret
  * @param {{ userEpochs?: Record<string, number> }} [options]
- *   userEpochs maps username → Unix-second epoch. If the session's `iat`
- *   is older than the user's epoch, the session is rejected as revoked.
- *   This is how Authelia user deletions invalidate live sessions whose
- *   HMAC signature is otherwise still valid.
+ *   userEpochs maps a directory user id → Unix-second epoch. If the
+ *   session's `iat` is older than its user's epoch, the session is rejected
+ *   as revoked. This is how offboarding (disable, delete) invalidates live
+ *   sessions whose HMAC signature is otherwise still valid. A session
+ *   without a user id (issued before 4.5) is rejected: it could not be
+ *   told from a later user's.
  * @returns {{ valid: boolean, payload?: object, reason?: string }}
  */
 export function validateUserSession(tokenValue, sessionSecret, options = {}) {
@@ -96,6 +103,10 @@ export function validateUserSession(tokenValue, sessionSecret, options = {}) {
     return { valid: false, reason: 'missing_username' };
   }
 
+  if (!isIdentityUuid(payload.userId)) {
+    return { valid: false, reason: 'missing_user_id' };
+  }
+
   const now = Math.floor(Date.now() / 1000);
 
   if (payload.exp && now > payload.exp) {
@@ -106,12 +117,11 @@ export function validateUserSession(tokenValue, sessionSecret, options = {}) {
     return { valid: false, reason: 'inactive' };
   }
 
-  // Per-user invalidation epoch (set when a user is deleted from Authelia).
-  // Reject sessions issued before that epoch — they belong to a user who no
-  // longer exists, even if a same-named user is later re-created.
+  // Per-user invalidation epoch (set when a user is offboarded). Reject
+  // sessions issued before it.
   const userEpochs = options.userEpochs;
   if (userEpochs && typeof userEpochs === 'object') {
-    const epoch = userEpochs[payload.username];
+    const epoch = userEpochs[payload.userId];
     if (typeof epoch === 'number' && typeof payload.iat === 'number' && payload.iat < epoch) {
       return { valid: false, reason: 'revoked' };
     }

package/vendor/serverd/src/lib/user-caller.js

@@ -0,0 +1,67 @@
+/**
+ * Who a person on a plugin's user surface is to the plugin — what the
+ * panel's user-surface context (core `userSurfacePlugin`,
+ * `resolveUserCaller`) signs into the caller assertion it forwards to the
+ * agent half's `/app/*`: `{ type: 'user', userId, username, roles }`.
+ *
+ * Gatekeeper attests only the username; everything else comes from here:
+ * the directory's user holding that username now, and their roles from the
+ * plugin's audience as last computed (`lib/audience.js`) — restricted to
+ * the roles the installed version declares. A disabled user is refused at
+ * once (the directory is written before Authelia restarts); a user the
+ * audience does not hold as an active member is not entitled, and neither
+ * is one whose username's earlier holder still has a principal in
+ * Gatekeeper to clear.
+ */
+
+import { isLamasteUsername } from '@lamalibre/lamaste';
+import { readAudienceRow } from './audience.js';
+import { findDirectoryUser, principalCleanupPending } from './directory.js';
+import { declaredRoleIds } from './entitlements.js';
+import { identityReadiness } from './identity-sync.js';
+import { findPluginByRoute } from './plugins.js';
+
+const NOT_ENTITLED = 'This user may not use this plugin';
+
+/**
+ * The user caller for `username` on the plugin at `route`, or why there is
+ * none: 404 when no installed plugin holds the route or it declares no
+ * identity; 503 when its identity is not ready (not approved, not hosted,
+ * or its agent half has not answered protocol 1 for the installed
+ * version); 403 when the user is disabled, removed, unknown or not
+ * entitled.
+ *
+ * @param {string} route
+ * @param {string} username the Authelia username Gatekeeper attested
+ * @returns {Promise<{ ok: true, caller: { type: 'user', userId: string, username: string, roles: string[] } } | { ok: false, status: 403 | 404 | 503, error: string }>}
+ */
+export async function resolveUserCaller(route, username) {
+  const plugin = await findPluginByRoute(route);
+  if (!plugin || !plugin.identity) return { ok: false, status: 404, error: 'Not found' };
+  const readiness = await identityReadiness(route);
+  if (!readiness.ready) {
+    return { ok: false, status: 503, error: 'The plugin is not ready for its users yet' };
+  }
+  if (!isLamasteUsername(username)) return { ok: false, status: 403, error: NOT_ENTITLED };
+  const user = await findDirectoryUser(username);
+  if (!user) return { ok: false, status: 403, error: NOT_ENTITLED };
+  // An earlier holder's grants may still be in Gatekeeper under this name.
+  if (await principalCleanupPending(username)) {
+    return { ok: false, status: 403, error: NOT_ENTITLED };
+  }
+  if (user.status !== 'active') return { ok: false, status: 403, error: 'This user is disabled' };
+  const row = await readAudienceRow(plugin.name, user.userId);
+  const member = row?.change?.kind === 'upsert' ? row.change.member : null;
+  if (!member || member.status !== 'active' || member.userId !== user.userId) {
+    return { ok: false, status: 403, error: NOT_ENTITLED };
+  }
+  const declared = declaredRoleIds(plugin.identity);
+  const roles = (Array.isArray(member.roles) ? member.roles : []).filter((role) =>
+    declared.has(role),
+  );
+  if (roles.length === 0) return { ok: false, status: 403, error: NOT_ENTITLED };
+  return {
+    ok: true,
+    caller: { type: 'user', userId: user.userId, username: user.username, roles },
+  };
+}