@lamalibre/create-lamaste 4.4.0 → 4.5.0

package/vendor/serverd/src/lib/gatekeeper-client.js

@@ -2,12 +2,14 @@
  * Tiny gatekeeper admin-API client for callers other than the
  * /api/gatekeeper/* proxy routes.
  *
- * Reads the shared secret on first use (cached for the process lifetime)
- * and forwards a request to http://127.0.0.1:9294/api/...
+ * Reads the shared secret on first use (cached for the process lifetime
+ * once found) and forwards a request to http://127.0.0.1:9294/api/...
  *
  * Used by the user-delete route to cascade-revoke grants belonging to a
- * deleted Authelia user, and by other internal callers that need to talk
- * to gatekeeper without going through the panel's own mTLS layer.
+ * deleted Authelia user, by the plugin audiences (grants and groups), the
+ * entitlements and the erasure of a removed user, and by other internal
+ * callers that need to talk to gatekeeper without going through the
+ * panel's own mTLS layer.
  */
 
 import { readFile } from 'node:fs/promises';
@@ -16,17 +18,31 @@ import { getConfigPath } from './config.js';
 
 const GATEKEEPER_BASE = 'http://127.0.0.1:9294';
 let cachedSecret = null;
-let secretLoaded = false;
+
+/** Replaces the HTTP exchange with Gatekeeper (tests: there is no Gatekeeper). */
+let transportOverride = null;
+
+/**
+ * Answer every Gatekeeper request with `transport(method, apiPath, body)`
+ * — a {@link GatekeeperResult} — instead of calling Gatekeeper (tests);
+ * `null` calls Gatekeeper again.
+ *
+ * @param {((method: string, apiPath: string, body?: unknown) => Promise<GatekeeperResult>) | null} transport
+ */
+export function setGatekeeperClientForTests(transport) {
+  transportOverride = transport;
+}
 
 /**
  * Load the gatekeeper API secret. Supports both the new JSON envelope
  * (`gatekeeper-secret.json`) written by the gatekeeper service and the
  * legacy plain-text file (`gatekeeper-secret`). Returns null if neither
- * exists — callers must treat this as "gatekeeper not installed".
+ * exists — callers must treat this as "gatekeeper not installed (yet)".
+ * Only a secret that was found is kept: Gatekeeper writes it when it first
+ * starts, which may be after the panel's first call.
  */
 async function loadSecret() {
-  if (secretLoaded) return cachedSecret;
-  secretLoaded = true;
+  if (cachedSecret) return cachedSecret;
 
   const configDir = path.dirname(getConfigPath());
 
@@ -53,8 +69,7 @@ async function loadSecret() {
     // No secret available
   }
 
-  cachedSecret = null;
-  return cachedSecret;
+  return null;
 }
 
 /**
@@ -78,6 +93,8 @@ async function loadSecret() {
  * @returns {Promise<GatekeeperResult>}
  */
 export async function gatekeeperRequest(method, apiPath, body) {
+  if (transportOverride) return transportOverride(method, apiPath, body);
+
   const secret = await loadSecret();
   if (!secret) {
     return {
@@ -133,3 +150,191 @@ export async function gatekeeperRequest(method, apiPath, body) {
 
   return { ok: true, statusCode: response.status, data };
 }
+
+// ---------------------------------------------------------------------------
+// Typed calls
+// ---------------------------------------------------------------------------
+
+/**
+ * A grant as Gatekeeper lists it.
+ *
+ * @typedef {object} GatekeeperGrant
+ * @property {string} grantId
+ * @property {'user' | 'group'} principalType
+ * @property {string} principalId
+ * @property {string} resourceType
+ * @property {string} resourceId
+ * @property {Record<string, unknown>} context
+ * @property {boolean} used
+ * @property {string} createdAt
+ */
+
+/**
+ * A Lamaste group as Gatekeeper lists it.
+ *
+ * @typedef {object} GatekeeperGroup
+ * @property {string} name
+ * @property {string} description
+ * @property {string[]} members usernames
+ */
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** A failed call as a result, for an answer that is not the shape Gatekeeper gives. */
+function malformed(what) {
+  return {
+    ok: false,
+    statusCode: 502,
+    error: `gatekeeper answered ${what} in an unexpected shape`,
+    reason: 'http-error',
+  };
+}
+
+function grantOf(raw) {
+  if (
+    !isRecord(raw) ||
+    typeof raw.grantId !== 'string' ||
+    (raw.principalType !== 'user' && raw.principalType !== 'group') ||
+    typeof raw.principalId !== 'string' ||
+    typeof raw.resourceType !== 'string' ||
+    typeof raw.resourceId !== 'string'
+  ) {
+    return null;
+  }
+  return {
+    grantId: raw.grantId,
+    principalType: raw.principalType,
+    principalId: raw.principalId,
+    resourceType: raw.resourceType,
+    resourceId: raw.resourceId,
+    context: isRecord(raw.context) ? raw.context : {},
+    used: raw.used === true,
+    createdAt: typeof raw.createdAt === 'string' ? raw.createdAt : '',
+  };
+}
+
+function groupOf(raw) {
+  if (!isRecord(raw) || typeof raw.name !== 'string' || !Array.isArray(raw.members)) return null;
+  return {
+    name: raw.name,
+    description: typeof raw.description === 'string' ? raw.description : '',
+    members: raw.members.filter((m) => typeof m === 'string'),
+  };
+}
+
+/**
+ * Every grant on plugin `route` (`resourceType: 'plugin'`, `resourceId:
+ * <route>`) — with roles or without.
+ *
+ * @param {string} route
+ * @returns {Promise<{ ok: true, grants: GatekeeperGrant[] } | Extract<GatekeeperResult, { ok: false }>>}
+ */
+export async function listPluginGrants(route) {
+  const qs = new URLSearchParams({ resourceType: 'plugin', resourceId: route }).toString();
+  const result = await gatekeeperRequest('GET', `/api/grants?${qs}`);
+  if (!result.ok) return result;
+  if (!isRecord(result.data) || !Array.isArray(result.data.grants)) return malformed('its grants');
+  const grants = result.data.grants.map(grantOf);
+  if (grants.some((g) => g === null)) return malformed('its grants');
+  // Gatekeeper filters by the query; a grant on anything else is not this plugin's.
+  return {
+    ok: true,
+    grants: grants.filter((g) => g.resourceType === 'plugin' && g.resourceId === route),
+  };
+}
+
+/**
+ * Every Lamaste group with its members.
+ *
+ * @returns {Promise<{ ok: true, groups: GatekeeperGroup[] } | Extract<GatekeeperResult, { ok: false }>>}
+ */
+export async function listGatekeeperGroups() {
+  const result = await gatekeeperRequest('GET', '/api/groups');
+  if (!result.ok) return result;
+  if (!isRecord(result.data) || !Array.isArray(result.data.groups)) return malformed('its groups');
+  const groups = result.data.groups.map(groupOf);
+  if (groups.some((g) => g === null)) return malformed('its groups');
+  return { ok: true, groups };
+}
+
+/**
+ * Create a grant. Gatekeeper refuses a duplicate (409: same principal,
+ * resource and context JSON) and a grant beyond its limit (503).
+ *
+ * @param {{ principalType: 'user' | 'group', principalId: string, resourceType: string, resourceId: string, context: Record<string, unknown> }} grant
+ * @returns {Promise<{ ok: true, grant: GatekeeperGrant } | Extract<GatekeeperResult, { ok: false }>>}
+ */
+export async function createGatekeeperGrant(grant) {
+  const result = await gatekeeperRequest('POST', '/api/grants', grant);
+  if (!result.ok) return result;
+  const created = isRecord(result.data) ? grantOf(result.data.grant) : null;
+  return created ? { ok: true, grant: created } : malformed('the grant it created');
+}
+
+/**
+ * Revoke one grant.
+ *
+ * @param {string} grantId
+ * @returns {Promise<GatekeeperResult>}
+ */
+export function revokeGatekeeperGrant(grantId) {
+  return gatekeeperRequest('DELETE', `/api/grants/${encodeURIComponent(grantId)}`);
+}
+
+/**
+ * Remove everything Gatekeeper holds under `username` — every grant naming
+ * the user (any resource type) and its membership of every group — in one
+ * transaction. Idempotent. The username goes in the body (a URL is what
+ * request logs keep).
+ *
+ * @param {string} username
+ * @returns {Promise<{ ok: true, grantsRemoved: number, groupsLeft: number } | Extract<GatekeeperResult, { ok: false }>>}
+ */
+export async function removeUserPrincipal(username) {
+  const result = await gatekeeperRequest('POST', '/api/principals/user/remove', { username });
+  if (!result.ok) return result;
+  const data = isRecord(result.data) ? result.data : {};
+  if (
+    !Number.isSafeInteger(data.grantsRemoved) ||
+    data.grantsRemoved < 0 ||
+    !Number.isSafeInteger(data.groupsLeft) ||
+    data.groupsLeft < 0
+  ) {
+    return malformed('the principal removal');
+  }
+  return { ok: true, grantsRemoved: data.grantsRemoved, groupsLeft: data.groupsLeft };
+}
+
+/**
+ * Drop Gatekeeper's cached session verdicts. Authelia ends every session
+ * when users.yml changes; without this a cached verdict would keep a
+ * disabled or deleted user in for up to the cache lifetime (30 s).
+ *
+ * @returns {Promise<{ ok: true } | Extract<GatekeeperResult, { ok: false }>>}
+ */
+export async function bustGatekeeperSessions() {
+  const result = await gatekeeperRequest('POST', '/api/cache/bust');
+  return result.ok ? { ok: true } : result;
+}
+
+/**
+ * Delete the access-request log rows of `username` (logged before
+ * `before`, an ISO 8601 time, when given) — part of erasing a removed user.
+ * The username goes in the body (a URL is what request logs keep).
+ *
+ * @param {string} username
+ * @param {{ before?: string }} [opts]
+ * @returns {Promise<{ ok: true, removed: number } | Extract<GatekeeperResult, { ok: false }>>}
+ */
+export async function purgeAccessLogForUser(username, { before } = {}) {
+  const result = await gatekeeperRequest('POST', '/api/access-log/purge', {
+    username,
+    ...(before ? { before } : {}),
+  });
+  if (!result.ok) return result;
+  const removed = isRecord(result.data) ? result.data.removed : undefined;
+  if (!Number.isSafeInteger(removed) || removed < 0) return malformed('the purge');
+  return { ok: true, removed };
+}

package/vendor/serverd/src/lib/hook-pipelines.js

@@ -83,6 +83,8 @@ import { forgetRetainedData, recordRetainedData } from './retained-data.js';
 import { runRelayHook } from './relay-hooks.js';
 import { recordAuditBestEffort } from './audit.js';
 import { deleteSettingsCache, relayHookSettings } from './plugin-settings.js';
+import { forgetIdentityHalf } from './identity-sync.js';
+import { refreshUserSurfaceVhosts } from './user-surface.js';
 import {
   tunnelNginxDeps,
   tunnelCertbotDeps,
@@ -620,6 +622,9 @@ export async function runPurgeRetainedData(op, { retained, logger }) {
     });
     assertRemoved(result, 'Purging the retained data');
     await forgetRetainedData(retained.agentLabel, retained.route);
+    // The last data of an uninstalled plugin: its identity ledger goes too.
+    const { dropIdentityLedgerIfNoData } = await import('./audience.js');
+    await dropIdentityLedgerIfNoData(retained.plugin, logger);
   });
   await recordAuditBestEffort(
     {
@@ -836,6 +841,14 @@ export async function runUninstallPipeline(op, ctx, { force = false } = {}) {
     await deleteSettingsCache(ctx.plugin.name).catch((err) =>
       op.warn(`Could not drop the cached settings: ${err.message}`),
     );
+    // So does what the relay knew of the half's identity feed: the next
+    // hosting's half answers protocol 1 before users reach it, and replays.
+    await forgetIdentityHalf(ctx.plugin.name).catch((err) =>
+      op.warn(`Could not forget the agent half's identity feed: ${err.message}`),
+    );
+    // Its user surface's locations no longer take the internal tunnel's
+    // body limit (best effort; the panel answers 503 until it is hosted).
+    await refreshUserSurfaceVhosts(ctx.route, ctx.logger);
   }
   await recordAuditBestEffort(
     {