Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

52.3 KB
Raw Blame
import { PrincipalType, SystemRoles, partialWithoutDefaults } from 'librechat-data-provider';
import {
  logger,
  RoleConflictError,
  isConfigMoveRefused,
  isValidObjectIdString,
  BASE_CONFIG_PRINCIPAL_ID,
} from '@librechat/data-schemas';
import type {
  IRole,
  IUser,
  ConfigRecord,
  AdminMember,
  ISystemGrant,
  AuditSeverity,
  SystemGrantMove,
  ConfigMoveOptions,
} from '@librechat/data-schemas';
import type { FilterQuery, Types } from 'mongoose';
import type { Response } from 'express';
import type { z } from 'zod';
import type { ServerRequest } from '~/types/http';
import type { RecordAuditEntry } from './audit';
import type { CascadeStep } from './cascade';
import { createAdminAuditEmitter, diffRolePermissions, configTarget } from './audit';
import { cascadeStep, runCascade, invalidatingConfigStore } from './cascade';
import { getSafeErrorMetadata } from '~/utils/errors';
import { getActivePartition } from './partition';
import { parsePagination } from './pagination';

const systemRoleValues = new Set<string>(Object.values(SystemRoles));

/** Case-insensitive check — the legacy roles route uppercases params. */
function isSystemRoleName(name: string): boolean {
  return systemRoleValues.has(name.toUpperCase());
}

const MAX_NAME_LENGTH = 500;
const MAX_DESCRIPTION_LENGTH = 2000;
const CONTROL_CHAR_RE = /\p{Cc}/u;
/**
 * Role names that would create semantically ambiguous URLs.
 * e.g. GET /api/admin/roles/members — is that "list roles" or "get role named members"?
 * Express routing resolves this correctly (single vs multi-segment), but the URLs
 * are confusing for API consumers. Keep in sync with sub-path routes in routes/admin/roles.js.
 */
const RESERVED_ROLE_NAMES = new Set(['members', 'permissions']);

/**
 * Whether a role name keys its own config profile. The tenant-wide Base document is keyed
 * `role` / `__base__`, so a role by that name (reserved now, but one may predate that) must
 * never move or delete it: that would let `manage:roles` rewrite what every user gets, which
 * otherwise needs broad `manage:configs`.
 */
function hasOwnConfigProfile(roleName: string): boolean {
  return roleName !== BASE_CONFIG_PRINCIPAL_ID;
}

function validateNameParam(name: string): string | null {
  if (!name || typeof name !== 'string') {
    return 'name parameter is required';
  }
  if (name.length > MAX_NAME_LENGTH) {
    return `name must not exceed ${MAX_NAME_LENGTH} characters`;
  }
  if (CONTROL_CHAR_RE.test(name)) {
    return 'name contains invalid characters';
  }
  return null;
}

/** A rejected role name as the 400 body; a reserved name carries a code the client can map. */
interface RoleNameError {
  error: string;
  code?: 'ROLE_NAME_RESERVED';
}

function validateRoleName(name: unknown, required: boolean): RoleNameError | null {
  if (name === undefined) {
    return required ? { error: 'name is required' } : null;
  }
  if (typeof name !== 'string' || !name.trim()) {
    return { error: required ? 'name is required' : 'name must be a non-empty string' };
  }
  const trimmed = name.trim();
  if (trimmed.length > MAX_NAME_LENGTH) {
    return { error: `name must not exceed ${MAX_NAME_LENGTH} characters` };
  }
  if (CONTROL_CHAR_RE.test(trimmed)) {
    return { error: 'name contains invalid characters' };
  }
  if (RESERVED_ROLE_NAMES.has(trimmed)) {
    return { error: 'name is a reserved path segment', code: 'ROLE_NAME_RESERVED' };
  }
  if (!hasOwnConfigProfile(trimmed)) {
    return { error: 'name is reserved for the base config', code: 'ROLE_NAME_RESERVED' };
  }
  return null;
}

function validateDescription(description: unknown): string | null {
  if (description === undefined) {
    return null;
  }
  if (typeof description !== 'string') {
    return 'description must be a string';
  }
  if (description.length > MAX_DESCRIPTION_LENGTH) {
    return `description must not exceed ${MAX_DESCRIPTION_LENGTH} characters`;
  }
  return null;
}

interface RoleNameParams {
  name: string;
}

interface RoleMemberParams extends RoleNameParams {
  userId: string;
}

export type RoleListItem = { _id: Types.ObjectId | string; name: string; description?: string };

/**
 * Role ids are names every tenant reuses, so every role operation here addresses the role of the
 * caller's tenant partition and what it holds there (members, profile, grants and ACL entries):
 * the active tenant's, or for an admin without a tenant only the platform-level ones, never each
 * tenant's own role of the same name. The routes wire the data-schemas methods that keep to that
 * partition, and a member added or removed by id must be a user of it too.
 */
export interface AdminRolesDeps {
  /** The roles of the caller's tenant partition (`listRoles`). */
  listRoles: (options?: { limit?: number; offset?: number }) => Promise<RoleListItem[]>;
  countRoles: () => Promise<number>;
  /**
   * The role of exactly this name in the caller's tenant partition, read as stored
   * (`getPartitionRole`); a missing system role is created there.
   */
  getRoleByName: (name: string, fields?: string | string[] | null) => Promise<IRole | null>;
  createRoleByName: (roleData: Partial<IRole>) => Promise<IRole>;
  /** With `options.id`, updates only the role document with that `_id`. */
  updateRoleByName: (
    name: string,
    updates: Partial<IRole>,
    options?: { id?: string },
  ) => Promise<IRole | null>;
  updateAccessPermissions: (
    name: string,
    perms: Record<string, Record<string, boolean>>,
    roleData?: IRole,
  ) => Promise<void>;
  /** With `options.id`, deletes only the role that still has that `_id`, so a role recreated
   * under the same name is never removed by a request that targeted the original. Reassigns the
   * role's members in the caller's partition to USER. */
  deleteRoleByName: (name: string, options?: { id?: string }) => Promise<IRole | null>;
  findUser: (
    criteria: FilterQuery<IUser>,
    fields?: string | string[] | null,
  ) => Promise<IUser | null>;
  /** `expectedState` makes the write conditional: it resolves to null when the user no longer matches. */
  updateUser: (
    userId: string,
    data: Partial<IUser>,
    expectedState?: Record<string, unknown>,
  ) => Promise<IUser | null>;
  /** Moves the role's members in the caller's partition to `newRole` (a rename's migration). */
  updateUsersByRole: (oldRole: string, newRole: string) => Promise<void>;
  /** The ids of the role's members in the caller's partition. */
  findUserIdsByRole: (roleName: string) => Promise<string[]>;
  /** With `fromRole`, only users whose role is still that one change. */
  updateUsersRoleByIds: (
    userIds: string[],
    newRole: string,
    options?: { fromRole?: string },
  ) => Promise<void>;
  listUsersByRole: (
    roleName: string,
    options?: { limit?: number; offset?: number },
  ) => Promise<IUser[]>;
  countUsersByRole: (roleName: string) => Promise<number>;
  /** Removes the per-principal config override (keyed by type + name, not ObjectId). */
  deleteConfig: (
    principalType: PrincipalType,
    principalId: string | Types.ObjectId,
  ) => Promise<ConfigRecord | null>;
  /** Removes the role's ACL entries in the caller's partition (`deletePrincipalAclEntries`). */
  deleteAclEntries: (filter: {
    principalType: PrincipalType;
    principalId: string | Types.ObjectId;
  }) => Promise<void>;
  /** Drops cached prompt group access IDs; role deletion can remove PROMPTGROUP grants. */
  invalidatePromptGroupAccessContext?: () => Promise<void>;
  /** Removes the system capability grants this principal holds in one scope (exactly
   * `tenantId`, or platform-level ones without it) and returns the removed grants so each can be
   * audited. */
  deleteGrantsForPrincipal: (
    principalType: PrincipalType,
    principalId: string | Types.ObjectId,
    options?: { tenantId?: string },
  ) => Promise<ISystemGrant[]>;
  /** Snapshot source and restore sink for the config override removed by the role-deletion
   * cascade. Only the override is restored on failure: ACL entries and grants are never
   * re-inserted, since that could resurrect access a concurrent request revoked, and
   * their removal only narrows access. */
  /** Reads the grants before the cascade so their removal is audited even when it rejects after committing. */
  findGrantsForPrincipal?: (
    principalType: PrincipalType,
    principalId: string,
    options?: { tenantId?: string },
  ) => Promise<ISystemGrant[]>;
  /** A role's profile in the caller's tenant partition (platform-level without a tenant), the
   * partition `renameConfigPrincipal` moves in. */
  findConfigByPrincipal?: (
    principalType: PrincipalType,
    principalId: string,
    options?: { includeInactive?: boolean },
  ) => Promise<ConfigRecord | null>;
  /** Re-creates a deleted config document in full, only if none exists. Resolves
   * to whether it inserted. */
  restoreConfig?: (snapshot: ConfigRecord) => Promise<boolean>;
  /**
   * Role rename moves what is keyed by the role's name (this config profile, and the grants
   * and ACL entries below), so it follows the role instead of applying to nobody, and to any
   * later role that reuses the old name. Each move is undone if the rename cannot complete; a
   * dependent without its mover stays where it is.
   *
   * Moves the config profile within the caller's tenant partition (platform-level without a
   * tenant, never a tenant's role of the same name); `null` when there is none. Throws
   * `ConfigMoveRefusedError`, changing nothing, when the new name already has one in that
   * partition (`CONFIG_PRINCIPAL_EXISTS`) or either name is the Base principal id. With
   * `identity`, moves only that document, and resolves to `null` when the source holds another.
   */
  renameConfigPrincipal?: (
    principalType: PrincipalType,
    fromPrincipalId: string,
    toPrincipalId: string,
    options?: ConfigMoveOptions,
  ) => Promise<ConfigRecord | null>;
  /** Moves the system grants of exactly `tenantId`, or platform-level ones without it; returns what it changed. */
  moveGrantsToPrincipal?: (
    principalType: PrincipalType,
    fromPrincipalId: string,
    toPrincipalId: string,
    options?: { tenantId?: string },
  ) => Promise<SystemGrantMove>;
  /** Undoes exactly what `moveGrantsToPrincipal` returned it changed; a grant revoked since stays revoked. */
  restoreMovedGrants?: (
    principalType: PrincipalType,
    fromPrincipalId: string,
    toPrincipalId: string,
    move: SystemGrantMove,
  ) => Promise<void>;
  /** Moves the ACL entries of the request's tenant (platform-level ones without a tenant) and
   * returns their ids; with `ids`, moves only those (the undo). */
  moveAclEntriesToPrincipal?: (
    principalType: PrincipalType,
    fromPrincipalId: string,
    toPrincipalId: string,
    options?: { ids?: readonly string[] },
  ) => Promise<string[]>;
  /** Clears the merged-config caches (on every instance, with Redis) once a rename moved a
   * profile, or a deletion removed or restored one, before the response, as config writes do. */
  invalidateConfigCaches?: (tenantId?: string) => Promise<void>;
  /** Optional audit emission for role mutations and the grants removed by the
   * role-deletion cascade. Failure is logged unless `auditFailClosed` is set. */
  recordAuditEntry?: RecordAuditEntry;
  /** When true, a failed audit write surfaces as a 5xx after the mutation has
   * been persisted. Defaults to fail-open. */
  auditFailClosed?: boolean;
}

/** Account ids per entry, so a large role is audited in a few ordered writes. */
const AUDIT_MEMBER_CHUNK = 100;

/** Changing who holds ADMIN is the most sensitive membership change. */
function memberChangeSeverity(...roles: Array<string | undefined>): AuditSeverity {
  return roles.includes(SystemRoles.ADMIN) ? 'critical' : 'warning';
}

function roleTarget(name: string) {
  return { type: 'role', id: name, name };
}

/**
 * Whether a user belongs to the caller's tenant partition, the one a role name addresses. Outside
 * a tenant a user is found by id in any tenant, but a tenant user's `role` names that tenant's own
 * role, so the platform role's member routes never change it.
 */
function isPartitionUser(user: Pick<IUser, 'tenantId'>): boolean {
  return (user.tenantId || undefined) === getActivePartition();
}

/** The document a role was read as, so a write changes that role and no other of its name. */
function roleIdentity(role: Pick<IRole, '_id'>): { id: string } | undefined {
  return role._id != null ? { id: String(role._id) } : undefined;
}

/** What a role rename moved to the new name along with the role. */
interface RoleDependentsMoved {
  /** The profile as the new name now holds it; `null` when the role had none. */
  config: ConfigRecord | null;
  /** The grants that now apply under the new name: re-keyed, or already held there. */
  grants: ISystemGrant[];
  aclEntries: number;
}

type RoleRenameResult =
  | { ok: true; role: IRole; moved: RoleDependentsMoved }
  | { ok: false; code: 'ROLE_NOT_FOUND' | 'ROLE_CONFIG_CONFLICT' | 'ROLE_RENAME_FAILED' };

function renameFailureResponse(
  res: Response,
  code: Extract<RoleRenameResult, { ok: false }>['code'],
  newName: string,
): Response {
  if (code === 'ROLE_NOT_FOUND') {
    return res.status(404).json({ error: 'Role not found' });
  }
  if (code === 'ROLE_CONFIG_CONFLICT') {
    return res.status(409).json({
      error: `A config profile already exists for role "${newName}"`,
      code,
    });
  }
  return res.status(500).json({
    error: 'Failed to move the role profile, grants or permissions; the role was not renamed',
    code,
  });
}

export function createAdminRolesHandlers(deps: AdminRolesDeps): {
  listRoles: (req: ServerRequest, res: Response) => Promise<Response>;
  getRole: (req: ServerRequest, res: Response) => Promise<Response>;
  createRole: (req: ServerRequest, res: Response) => Promise<Response>;
  updateRole: (req: ServerRequest, res: Response) => Promise<Response>;
  updateRolePermissions: (req: ServerRequest, res: Response) => Promise<Response>;
  deleteRole: (req: ServerRequest, res: Response) => Promise<Response>;
  getRoleMembers: (req: ServerRequest, res: Response) => Promise<Response>;
  addRoleMember: (req: ServerRequest, res: Response) => Promise<Response>;
  removeRoleMember: (req: ServerRequest, res: Response) => Promise<Response>;
} {
  const {
    listRoles,
    countRoles,
    getRoleByName,
    createRoleByName,
    updateRoleByName,
    updateAccessPermissions,
    deleteRoleByName,
    findUser,
    updateUser,
    updateUsersByRole,
    findUserIdsByRole,
    updateUsersRoleByIds,
    listUsersByRole,
    countUsersByRole,
    deleteConfig,
    deleteAclEntries,
    deleteGrantsForPrincipal,
    restoreConfig,
    findConfigByPrincipal,
    findGrantsForPrincipal,
    renameConfigPrincipal,
    moveGrantsToPrincipal,
    restoreMovedGrants,
    moveAclEntriesToPrincipal,
    invalidateConfigCaches,
    recordAuditEntry,
    auditFailClosed,
    invalidatePromptGroupAccessContext,
  } = deps;

  const emitAudit = createAdminAuditEmitter({
    recordAuditEntry,
    failClosed: auditFailClosed,
    logPrefix: '[adminRoles]',
  });
  /** Role deletion revokes access, so its lifecycle entries are always fail-open. */
  const emitRevocationAudit = createAdminAuditEmitter({
    recordAuditEntry,
    logPrefix: '[adminRoles]',
  });

  /** Emits a `grant.removed` audit entry for each grant the role-deletion cascade
   * removed, so the cascade leaves the same forensic trail as an explicit revoke.
   * Sequential to keep the per-tenant hash chain ordered. */
  async function emitGrantRemovals(
    req: ServerRequest,
    roleName: string,
    grants: ISystemGrant[],
  ): Promise<void> {
    for (const grant of grants) {
      await emitRevocationAudit(req, {
        action: 'grant.removed',
        severity: 'warning',
        target: { type: PrincipalType.ROLE, id: roleName, name: roleName },
        metadata: { capability: grant.capability },
        /** Scope each entry to the removed grant's own tenant, so a removal
         * always lands in the chain of the tenant whose grant it was. */
        tenantId: grant.tenantId,
      });
    }
  }

  async function listRolesHandler(req: ServerRequest, res: Response) {
    try {
      const { limit, offset } = parsePagination(req.query);
      const [roles, total] = await Promise.all([listRoles({ limit, offset }), countRoles()]);
      return res.status(200).json({ roles, total, limit, offset });
    } catch (error) {
      logger.error('[adminRoles] listRoles error:', getSafeErrorMetadata(error));
      return res.status(500).json({ error: 'Failed to list roles' });
    }
  }

  async function getRoleHandler(req: ServerRequest, res: Response) {
    try {
      const { name } = req.params as RoleNameParams;
      const paramError = validateNameParam(name);
      if (paramError) {
        return res.status(400).json({ error: paramError });
      }
      const role = await getRoleByName(name);
      if (!role) {
        return res.status(404).json({ error: 'Role not found' });
      }
      return res.status(200).json({ role });
    } catch (error) {
      logger.error('[adminRoles] getRole error:', getSafeErrorMetadata(error));
      return res.status(500).json({ error: 'Failed to get role' });
    }
  }

  async function createRoleHandler(req: ServerRequest, res: Response) {
    try {
      const { name, description, permissions } = req.body as {
        name?: string;
        description?: string;
        permissions?: IRole['permissions'];
      };
      const nameError = validateRoleName(name, true);
      if (nameError) {
        return res.status(400).json(nameError);
      }
      const descError = validateDescription(description);
      if (descError) {
        return res.status(400).json({ error: descError });
      }
      if (
        permissions !== undefined &&
        (permissions === null || typeof permissions !== 'object' || Array.isArray(permissions))
      ) {
        return res.status(400).json({ error: 'permissions must be an object' });
      }
      const roleData: Partial<IRole> = {
        name: (name as string).trim(),
        permissions: permissions ?? {},
      };
      if (description !== undefined) {
        roleData.description = description;
      }
      const role = await createRoleByName(roleData);
      const changes = diffRolePermissions(undefined, role.permissions);
      await emitAudit(req, {
        action: 'role.created',
        target: roleTarget(role.name),
        metadata: { permissions: changes.join(', ') || null },
      });
      return res.status(201).json({ role });
    } catch (error) {
      logger.error('[adminRoles] createRole error:', getSafeErrorMetadata(error));
      if (error instanceof RoleConflictError) {
        return res.status(409).json({ error: error.message });
      }
      return res.status(500).json({ error: 'Failed to create role' });
    }
  }

  async function rollbackMigratedUsers(
    migratedIds: string[],
    currentName: string,
    newName: string,
  ): Promise<void> {
    if (migratedIds.length === 0) {
      return;
    }
    try {
      await updateUsersRoleByIds(migratedIds, currentName, { fromRole: newName });
    } catch (rollbackError) {
      logger.error(
        `[adminRoles] CRITICAL: rename rollback failed — ${migratedIds.length} users have dangling role "${newName}": [${migratedIds.join(', ')}]`,
        rollbackError,
      );
    }
  }

  /**
   * Puts the role document back under its old name (and description) after a failed rename.
   * The description goes back only while it is still the one this rename set, so an edit made
   * meanwhile is kept. A role stored without a description gets the schema default (`''`)
   * back: the update only sets fields, and an undefined one would be dropped, keeping the new
   * description.
   */
  async function revertRoleUpdate(
    existing: IRole,
    currentName: string,
    newName: string,
    extraUpdates?: Partial<IRole>,
  ): Promise<void> {
    const revert: Partial<IRole> = { name: currentName };
    if (extraUpdates?.description !== undefined) {
      const renamed = await getRoleByName(newName).catch(() => null);
      if (renamed?.description === extraUpdates.description) {
        revert.description = existing.description ?? '';
      }
    }
    try {
      await updateRoleByName(newName, revert, roleIdentity(existing));
    } catch (revertError) {
      logger.error(
        `[adminRoles] CRITICAL: rename rollback failed — role "${currentName}" is still named "${newName}"`,
        getSafeErrorMetadata(revertError),
      );
    }
  }

  /**
   * Moves what is keyed by the role's name, concurrently, and undoes every completed move when
   * any fails. `configConflict` reports that the new name already had a profile; any other
   * failure of the profile move (it kept changing, or a copy could not be withdrawn) is a
   * failed rename, not a conflict at the new name.
   */
  async function moveRoleDependents(
    currentName: string,
    newName: string,
    tenantId: string | undefined,
  ): Promise<
    | { ok: true; moved: RoleDependentsMoved }
    | { ok: false; code: 'ROLE_CONFIG_CONFLICT' | 'ROLE_RENAME_FAILED' }
  > {
    let configConflict = false;
    const steps: CascadeStep[] = [];
    if (renameConfigPrincipal && hasOwnConfigProfile(currentName)) {
      steps.push(
        cascadeStep(
          'config',
          async () => {
            try {
              return await renameConfigPrincipal(PrincipalType.ROLE, currentName, newName);
            } catch (error) {
              configConflict = isConfigMoveRefused(error, 'CONFIG_PRINCIPAL_EXISTS');
              throw error;
            }
          },
          async (moved: ConfigRecord | null) => {
            if (!moved) {
              return;
            }
            /** Only the profile this rename moved goes back, with any edit made to it since. */
            const restored = await renameConfigPrincipal(PrincipalType.ROLE, newName, currentName, {
              identity: moved._id,
            });
            if (!restored) {
              logger.warn(
                `[adminRoles] rename rollback left role "${newName}"'s profile in place: it is no longer the one the rename moved`,
              );
            }
          },
        ),
      );
    }
    if (moveGrantsToPrincipal) {
      steps.push(
        cascadeStep(
          'grants',
          () => moveGrantsToPrincipal(PrincipalType.ROLE, currentName, newName, { tenantId }),
          restoreMovedGrants
            ? (move: SystemGrantMove) =>
                restoreMovedGrants(PrincipalType.ROLE, currentName, newName, move)
            : undefined,
        ),
      );
    }
    if (moveAclEntriesToPrincipal) {
      steps.push(
        cascadeStep(
          'acl',
          () => moveAclEntriesToPrincipal(PrincipalType.ROLE, currentName, newName),
          async (ids: string[]) => {
            await moveAclEntriesToPrincipal(PrincipalType.ROLE, newName, currentName, { ids });
          },
        ),
      );
    }
    if (steps.length === 0) {
      return { ok: true, moved: { config: null, grants: [], aclEntries: 0 } };
    }
    const cascade = await runCascade(steps, '[adminRoles] rename');
    if (cascade.failed.length > 0) {
      await cascade.compensate();
      return { ok: false, code: configConflict ? 'ROLE_CONFIG_CONFLICT' : 'ROLE_RENAME_FAILED' };
    }
    const { config, grants, acl } = cascade.removed as {
      config?: ConfigRecord | null;
      grants?: SystemGrantMove;
      acl?: string[];
    };
    return {
      ok: true,
      moved: {
        config: config ?? null,
        grants: grants ? [...grants.moved, ...grants.superseded] : [],
        aclEntries: acl?.length ?? 0,
      },
    };
  }

  /**
   * Records a profile a rename moved in the config trail of both principals, so neither
   * chain starts or ends without a cause: deleted from the old name, created at the new one.
   */
  async function emitProfileMove(
    req: ServerRequest,
    previousName: string,
    newName: string,
    profile: ConfigRecord | null,
  ): Promise<void> {
    if (!profile) {
      return;
    }
    const from = configTarget(PrincipalType.ROLE, previousName);
    const to = configTarget(PrincipalType.ROLE, newName);
    await emitAudit(req, {
      action: 'config.deleted',
      target: from,
      metadata: { cause: 'role_renamed', movedTo: to.id },
    });
    await emitAudit(req, {
      action: 'config.created',
      target: to,
      metadata: {
        operation: 'move',
        cause: 'role_renamed',
        movedFrom: from.id,
        priority: profile.priority,
      },
    });
  }

  /** Clears what a rename's moves (or their undo) leave stale; failures are logged, not thrown. */
  async function invalidateRenamedRole(tenantId: string | undefined): Promise<void> {
    const results = await Promise.allSettled([
      invalidateConfigCaches?.(tenantId),
      invalidatePromptGroupAccessContext?.(),
    ]);
    for (const result of results) {
      if (result.status === 'rejected') {
        logger.error(
          '[adminRoles] cache invalidation after rename failed:',
          getSafeErrorMetadata(result.reason),
        );
      }
    }
  }

  /**
   * Renames a role: migrates its users, renames the role document, then moves the config
   * profile, grants and ACL entries keyed by the old name. A failure at any step undoes the
   * earlier ones, so the role is either fully renamed or left as it was.
   *
   * The ID snapshot from `findUserIdsByRole` is a point-in-time read. Users assigned
   * to `currentName` between the snapshot and the bulk `updateUsersByRole` write will
   * be moved to `newName` but will NOT be reverted on rollback. This window is narrow
   * and only relevant under concurrent admin operations during a rename.
   */
  async function renameRole(
    existing: IRole,
    currentName: string,
    newName: string,
    tenantId: string | undefined,
    extraUpdates?: Partial<IRole>,
  ): Promise<RoleRenameResult> {
    const migratedIds = await findUserIdsByRole(currentName);
    await updateUsersByRole(currentName, newName);
    let role: IRole | null;
    try {
      const updates: Partial<IRole> = { name: newName, ...extraUpdates };
      role = await updateRoleByName(currentName, updates, roleIdentity(existing));
    } catch (error) {
      await rollbackMigratedUsers(migratedIds, currentName, newName);
      throw error;
    }
    if (!role) {
      await rollbackMigratedUsers(migratedIds, currentName, newName);
      return { ok: false, code: 'ROLE_NOT_FOUND' };
    }
    const dependents = await moveRoleDependents(currentName, newName, tenantId);
    if (!dependents.ok) {
      await revertRoleUpdate(existing, currentName, newName, extraUpdates);
      await rollbackMigratedUsers(migratedIds, currentName, newName);
    }
    await invalidateRenamedRole(tenantId);
    return dependents.ok ? { ok: true, role, moved: dependents.moved } : dependents;
  }

  async function updateRoleHandler(req: ServerRequest, res: Response) {
    try {
      const { name } = req.params as RoleNameParams;
      const paramError = validateNameParam(name);
      if (paramError) {
        return res.status(400).json({ error: paramError });
      }
      const body = req.body as { name?: string; description?: string };
      const nameError = validateRoleName(body.name, false);
      if (nameError) {
        return res.status(400).json(nameError);
      }
      const descError = validateDescription(body.description);
      if (descError) {
        return res.status(400).json({ error: descError });
      }

      const trimmedName = body.name?.trim() ?? '';
      const isRename = trimmedName !== '' && trimmedName !== name;

      if (isRename && isSystemRoleName(name)) {
        return res.status(403).json({ error: 'Cannot rename system role' });
      }
      if (isRename && isSystemRoleName(trimmedName)) {
        return res.status(403).json({ error: 'Cannot use a reserved system role name' });
      }

      const existing = await getRoleByName(name);
      if (!existing) {
        return res.status(404).json({ error: 'Role not found' });
      }

      if (isRename) {
        const [duplicate, targetProfile] = await Promise.all([
          getRoleByName(trimmedName),
          renameConfigPrincipal && findConfigByPrincipal
            ? findConfigByPrincipal(PrincipalType.ROLE, trimmedName, { includeInactive: true })
            : null,
        ]);
        if (duplicate) {
          return res.status(409).json({ error: `Role "${trimmedName}" already exists` });
        }
        if (targetProfile) {
          return res.status(409).json({
            error: `A config profile already exists for role "${trimmedName}"`,
            code: 'ROLE_CONFIG_CONFLICT',
          });
        }
      }

      const updates: Partial<IRole> = {};
      if (isRename) {
        updates.name = trimmedName;
      }
      /** A description equal to the stored one is not a change: no write and no audit entry. */
      if (body.description !== undefined && body.description !== existing.description) {
        updates.description = body.description;
      }

      if (Object.keys(updates).length === 0) {
        return res.status(200).json({ role: existing });
      }

      if (isRename) {
        const descUpdate =
          updates.description !== undefined ? { description: updates.description } : undefined;
        const renamed = await renameRole(
          existing,
          name,
          trimmedName,
          req.user?.tenantId,
          descUpdate,
        );
        if (!renamed.ok) {
          return renameFailureResponse(res, renamed.code, trimmedName);
        }
        const { role, moved } = renamed;
        await emitAudit(req, {
          action: 'role.updated',
          target: roleTarget(trimmedName),
          metadata: {
            previousName: name,
            descriptionChanged: descUpdate !== undefined,
            configMoved: moved.config != null,
            grantsMoved: moved.grants.length,
            grantCapabilities: moved.grants.map((grant) => grant.capability).join(',') || null,
            aclEntriesMoved: moved.aclEntries,
          },
        });
        await emitProfileMove(req, name, trimmedName, moved.config);
        return res.status(200).json({ role });
      }

      const role = await updateRoleByName(name, updates, roleIdentity(existing));
      if (!role) {
        return res.status(404).json({ error: 'Role not found' });
      }
      await emitAudit(req, {
        action: 'role.updated',
        target: roleTarget(name),
        metadata: { descriptionChanged: true },
      });
      return res.status(200).json({ role });
    } catch (error) {
      if (error instanceof RoleConflictError) {
        return res.status(409).json({ error: error.message });
      }
      logger.error('[adminRoles] updateRole error:', getSafeErrorMetadata(error));
      return res.status(500).json({ error: 'Failed to update role' });
    }
  }

  /**
   * The re-fetch via `getRoleByName` after `updateAccessPermissions` reads the role as
   * stored (`getPartitionRole` reads no cache), so it returns what the update wrote.
   */
  async function updateRolePermissionsHandler(req: ServerRequest, res: Response) {
    try {
      const { name } = req.params as RoleNameParams;
      const paramError = validateNameParam(name);
      if (paramError) {
        return res.status(400).json({ error: paramError });
      }
      const { permissions } = req.body as {
        permissions: Record<string, Record<string, boolean>>;
      };

      if (!permissions || typeof permissions !== 'object' || Array.isArray(permissions)) {
        return res.status(400).json({ error: 'permissions object is required' });
      }

      const existing = await getRoleByName(name);
      if (!existing) {
        return res.status(404).json({ error: 'Role not found' });
      }

      await updateAccessPermissions(name, permissions, existing);
      const updated = await getRoleByName(name);
      if (!updated) {
        return res.status(404).json({ error: 'Role not found' });
      }
      const changes = diffRolePermissions(existing.permissions, updated.permissions);
      if (changes.length > 0) {
        await emitAudit(req, {
          action: 'role.permissions_updated',
          severity: 'warning',
          target: roleTarget(name),
          metadata: { changes: changes.join(', '), changeCount: changes.length },
        });
      }
      return res.status(200).json({ role: updated });
    } catch (error) {
      logger.error('[adminRoles] updateRolePermissions error:', getSafeErrorMetadata(error));
      return res.status(500).json({ error: 'Failed to update role permissions' });
    }
  }

  async function deleteRoleHandler(req: ServerRequest, res: Response) {
    /** Set once the deletion attempt is recorded; the outer catch uses it for unexpected failures. */
    let recordOutcome:
      | ((
          outcome: 'success' | 'failure',
          code?: string,
          metadata?: Record<string, number>,
        ) => Promise<void>)
      | undefined;
    let waitForAttempt: () => Promise<void> = async () => undefined;
    try {
      const { name } = req.params as RoleNameParams;
      const paramError = validateNameParam(name);
      if (paramError) {
        return res.status(400).json({ error: paramError });
      }
      if (isSystemRoleName(name)) {
        return res.status(403).json({ error: 'Cannot delete system role' });
      }

      const existing = await getRoleByName(name);
      if (!existing) {
        return res.status(404).json({ error: 'Role not found' });
      }

      /**
       * The attempt is recorded as `pending` before any removal so a crash mid-cascade still
       * leaves a trail. The write is started without being awaited, so audit latency never
       * delays the revocation; every later entry waits for it to keep the chain ordered.
       */
      const target = roleTarget(name);
      const attempt = emitRevocationAudit(req, {
        action: 'role.deleted',
        outcome: 'pending',
        severity: 'warning',
        target,
      });
      waitForAttempt = () => attempt;
      recordOutcome = async (outcome, code, metadata) => {
        await attempt;
        await emitRevocationAudit(req, {
          action: 'role.deleted',
          outcome,
          severity: 'warning',
          target,
          ...(code || metadata ? { metadata: { ...(code ? { code } : {}), ...metadata } } : {}),
        });
      };

      /**
       * Grants, ACL entries and config overrides are keyed by role name, so they
       * are removed before the role itself: if any removal fails the role stays
       * and the admin can retry, instead of a later role with the same name
       * inheriting the leftovers. Every removal is idempotent.
       */
      const tenantId = req.user?.tenantId;
      /** deleteRoleByName reassigns members to USER, so who held the role is read first. */
      const memberIds = await findUserIdsByRole(name);
      /** The grants as they were, so removals are audited even when a removal rejects after committing. */
      const grantSnapshot = findGrantsForPrincipal
        ? await findGrantsForPrincipal(PrincipalType.ROLE, name, { tenantId })
        : null;
      const { deleteConfig: removeProfile, restoreConfig: restoreProfile } =
        invalidatingConfigStore(
          { deleteConfig, restoreConfig },
          { invalidateConfigCaches, tenantId, logPrefix: '[adminRoles]' },
        );
      const configStep = cascadeStep(
        'config',
        () => removeProfile(PrincipalType.ROLE, name),
        restoreProfile
          ? async (config) => {
              if (!config) {
                return;
              }
              /** Insert-only: an override written after the snapshot is kept. */
              const restored = await restoreProfile(config);
              if (!restored) {
                logger.warn('[adminRoles] config restore skipped, override exists:', name);
              }
            }
          : undefined,
        findConfigByPrincipal
          ? () => findConfigByPrincipal(PrincipalType.ROLE, name, { includeInactive: true })
          : undefined,
      );
      const cascade = await runCascade(
        [
          ...(hasOwnConfigProfile(name) ? [configStep] : []),
          cascadeStep('acl', async () => {
            await deleteAclEntries({ principalType: PrincipalType.ROLE, principalId: name });
          }),
          cascadeStep('grants', () =>
            deleteGrantsForPrincipal(PrincipalType.ROLE, name, { tenantId }),
          ),
        ],
        '[adminRoles]',
      );

      /** The removed ACL entries can include PROMPTGROUP grants feeding the access
       * cache; the cache is stale after both a removal and a restore. */
      const invalidateAccess = async () => {
        try {
          await invalidatePromptGroupAccessContext?.();
        } catch (error) {
          /** The deletion already committed; a cache failure must not hide it from the audit trail. */
          logger.error(
            '[adminRoles] access cache invalidation failed:',
            getSafeErrorMetadata(error),
          );
        }
      };
      const cleanupFailedResponse = async () => {
        await recordOutcome?.('failure', 'ROLE_CLEANUP_FAILED');
        return res.status(500).json({
          error: 'Failed to remove the role grants and permissions; the role was not deleted',
          code: 'ROLE_CLEANUP_FAILED',
        });
      };

      /** Grants are never restored, so a failed delete still changed access and is audited. */
      const auditRemovedGrants = async () => {
        await waitForAttempt();
        let removed = cascade.removed.grants as ISystemGrant[] | undefined;
        if (!removed && grantSnapshot?.length && findGrantsForPrincipal) {
          /** The removal rejected and may have committed: audit what is no longer there. */
          const remaining = await findGrantsForPrincipal(PrincipalType.ROLE, name, {
            tenantId,
          }).then(
            (grants) => new Set(grants.map((g) => `${g.tenantId ?? ''}:${g.capability}`)),
            () => null,
          );
          removed = remaining
            ? grantSnapshot.filter((g) => !remaining.has(`${g.tenantId ?? ''}:${g.capability}`))
            : [];
        }
        await emitGrantRemovals(req, name, removed ?? []);
      };

      /** Reads the role again to learn whether it still is the one this request targeted. */
      const lookupRole = () =>
        getRoleByName(name).then(
          (role) => ({ known: true, role }),
          () => ({ known: false, role: null }),
        );
      /** A role recreated under the same name is a different role and must not inherit the
       * old one's dependents. */
      const isTargetedRole = (role: IRole | null) =>
        role != null &&
        (existing._id == null || role._id == null || String(existing._id) === String(role._id));

      if (cascade.failed.length > 0) {
        const lookup = await lookupRole();
        if (lookup.known && isTargetedRole(lookup.role)) {
          await cascade.compensate();
        } else {
          logger.warn('[adminRoles] config not restored, role changed during cleanup:', name);
        }
        await invalidateAccess();
        await auditRemovedGrants();
        return cleanupFailedResponse();
      }

      let deleted: IRole | null;
      try {
        deleted = await deleteRoleByName(name, {
          id: existing._id != null ? String(existing._id) : undefined,
        });
      } catch (error) {
        logger.error(
          '[adminRoles] deleteRole failed after cascade cleanup:',
          getSafeErrorMetadata(error),
        );
        /** The delete may have committed before it threw. Restoring dependents for a
         * role that is gone would orphan them for a later role with the same name. */
        const lookup = await lookupRole();
        if (lookup.known && isTargetedRole(lookup.role)) {
          await cascade.compensate();
          await invalidateAccess();
          await auditRemovedGrants();
          await recordOutcome('failure', 'ROLE_CLEANUP_FAILED');
          return res.status(500).json({ error: 'Failed to delete role' });
        }
        await invalidateAccess();
        if (!lookup.known || lookup.role) {
          await auditRemovedGrants();
          await recordOutcome('failure', 'ROLE_STATE_UNVERIFIABLE');
          logger.error('[adminRoles] dependents not restored, role state unverifiable:', name);
          return res.status(500).json({ error: 'Failed to delete role' });
        }
        /** Confirmed absent: the deletion did commit, so it is audited and reported as one. */
        deleted = existing;
      }
      await invalidateAccess();
      if (!deleted) {
        await auditRemovedGrants();
        await recordOutcome('failure', 'not_found');
        return res.status(404).json({ error: 'Role not found' });
      }
      const removedGrants = cascade.removed.grants as ISystemGrant[];
      await auditRemovedGrants();
      /** Each reassigned account is recorded (chunked) before the outcome entry. */
      const audited = memberIds;
      for (let i = 0; i < audited.length; i += AUDIT_MEMBER_CHUNK) {
        const chunk = audited.slice(i, i + AUDIT_MEMBER_CHUNK);
        await emitRevocationAudit(req, {
          action: 'role.member_removed',
          severity: memberChangeSeverity(name),
          target: roleTarget(name),
          metadata: {
            userIds: chunk.join(','),
            count: chunk.length,
            newRole: SystemRoles.USER,
            cause: 'role_deleted',
          },
        });
      }
      await recordOutcome('success', undefined, {
        grantsRemoved: removedGrants.length,
        membersReassigned: memberIds.length,
      });

      return res.status(200).json({ success: true });
    } catch (error) {
      logger.error('[adminRoles] deleteRole error:', getSafeErrorMetadata(error));
      await recordOutcome?.('failure', 'ROLE_DELETE_FAILED').catch(() => undefined);
      return res.status(500).json({ error: 'Failed to delete role' });
    }
  }

  async function getRoleMembersHandler(req: ServerRequest, res: Response) {
    try {
      const { name } = req.params as RoleNameParams;
      const paramError = validateNameParam(name);
      if (paramError) {
        return res.status(400).json({ error: paramError });
      }
      const existing = await getRoleByName(name);
      if (!existing) {
        return res.status(404).json({ error: 'Role not found' });
      }

      const { limit, offset } = parsePagination(req.query);

      const [users, total] = await Promise.all([
        listUsersByRole(name, { limit, offset }),
        countUsersByRole(name),
      ]);
      const members: AdminMember[] = users.map((u) => ({
        userId: u._id?.toString() ?? '',
        name: u.name ?? u._id?.toString() ?? '',
        email: u.email ?? '',
        avatarUrl: u.avatar,
      }));
      return res.status(200).json({ members, total, limit, offset });
    } catch (error) {
      logger.error('[adminRoles] getRoleMembers error:', getSafeErrorMetadata(error));
      return res.status(500).json({ error: 'Failed to get role members' });
    }
  }

  async function addRoleMemberHandler(req: ServerRequest, res: Response) {
    try {
      const { name } = req.params as RoleNameParams;
      const paramError = validateNameParam(name);
      if (paramError) {
        return res.status(400).json({ error: paramError });
      }
      const { userId } = req.body as { userId: string };

      if (!userId || typeof userId !== 'string') {
        return res.status(400).json({ error: 'userId is required' });
      }
      if (!isValidObjectIdString(userId)) {
        return res.status(400).json({ error: 'Invalid user ID format' });
      }

      if (isSystemRoleName(name) && name !== SystemRoles.ADMIN) {
        return res.status(403).json({ error: 'Cannot directly assign members to a system role' });
      }

      const existing = await getRoleByName(name);
      if (!existing) {
        return res.status(404).json({ error: 'Role not found' });
      }

      const user = await findUser({ _id: userId });
      if (!user || !isPartitionUser(user)) {
        return res.status(404).json({ error: 'User not found' });
      }

      if (user.role === name) {
        return res.status(200).json({ success: true });
      }

      if (user.role === SystemRoles.ADMIN && name !== SystemRoles.ADMIN) {
        const adminCount = await countUsersByRole(SystemRoles.ADMIN);
        if (adminCount <= 1) {
          return res.status(400).json({ error: 'Cannot remove the last admin user' });
        }
      }

      /** Conditional on the role read above: an overlapping identical request matches nothing,
       * so exactly one request records the transition. */
      const updated = await updateUser(userId, { role: name }, { role: user.role });
      if (!updated) {
        const current = await findUser({ _id: userId });
        if (!current) {
          return res.status(404).json({ error: 'User not found' });
        }
        if (current.role === name) {
          return res.status(200).json({ success: true });
        }
        return res.status(409).json({ error: 'User role changed concurrently' });
      }

      if (user.role === SystemRoles.ADMIN && name !== SystemRoles.ADMIN) {
        const postCount = await countUsersByRole(SystemRoles.ADMIN);
        if (postCount === 0) {
          try {
            await updateUser(userId, { role: SystemRoles.ADMIN });
          } catch (rollbackError) {
            logger.error(
              `[adminRoles] CRITICAL: admin rollback failed in addRoleMember for user ${userId}:`,
              rollbackError,
            );
          }
          return res.status(400).json({ error: 'Cannot remove the last admin user' });
        }
      }

      await emitAudit(req, {
        action: 'role.member_added',
        severity: memberChangeSeverity(name, user.role),
        target: roleTarget(name),
        metadata: { userId, previousRole: user.role ?? null },
      });
      /** The single-role write also ends the user's membership of the previous role. */
      if (user.role) {
        await emitAudit(req, {
          action: 'role.member_removed',
          severity: memberChangeSeverity(user.role),
          target: roleTarget(user.role),
          metadata: { userId, newRole: name },
        });
      }
      return res.status(200).json({ success: true });
    } catch (error) {
      logger.error('[adminRoles] addRoleMember error:', getSafeErrorMetadata(error));
      return res.status(500).json({ error: 'Failed to add role member' });
    }
  }

  async function removeRoleMemberHandler(req: ServerRequest, res: Response) {
    try {
      const { name, userId } = req.params as RoleMemberParams;
      const paramError = validateNameParam(name);
      if (paramError) {
        return res.status(400).json({ error: paramError });
      }
      if (!isValidObjectIdString(userId)) {
        return res.status(400).json({ error: 'Invalid user ID format' });
      }

      if (isSystemRoleName(name) && name !== SystemRoles.ADMIN) {
        return res.status(403).json({ error: 'Cannot remove members from a system role' });
      }

      const existing = await getRoleByName(name);
      if (!existing) {
        return res.status(404).json({ error: 'Role not found' });
      }

      const user = await findUser({ _id: userId });
      if (!user || !isPartitionUser(user)) {
        return res.status(404).json({ error: 'User not found' });
      }

      if (user.role !== name) {
        return res.status(400).json({ error: 'User is not a member of this role' });
      }

      if (name === SystemRoles.ADMIN) {
        const adminCount = await countUsersByRole(SystemRoles.ADMIN);
        if (adminCount <= 1) {
          return res.status(400).json({ error: 'Cannot remove the last admin user' });
        }
      }

      const removed = await updateUser(userId, { role: SystemRoles.USER }, { role: name });
      if (!removed) {
        const current = await findUser({ _id: userId });
        if (!current) {
          return res.status(404).json({ error: 'User not found' });
        }
        if (current.role !== name) {
          return res.status(400).json({ error: 'User is not a member of this role' });
        }
        return res.status(409).json({ error: 'User role changed concurrently' });
      }

      if (name === SystemRoles.ADMIN) {
        const postCount = await countUsersByRole(SystemRoles.ADMIN);
        if (postCount === 0) {
          try {
            await updateUser(userId, { role: SystemRoles.ADMIN });
          } catch (rollbackError) {
            logger.error(
              `[adminRoles] CRITICAL: admin rollback failed for user ${userId}:`,
              rollbackError,
            );
          }
          return res.status(400).json({ error: 'Cannot remove the last admin user' });
        }
      }

      await emitAudit(req, {
        action: 'role.member_removed',
        severity: memberChangeSeverity(name),
        target: roleTarget(name),
        metadata: { userId, newRole: SystemRoles.USER },
      });
      return res.status(200).json({ success: true });
    } catch (error) {
      logger.error('[adminRoles] removeRoleMember error:', getSafeErrorMetadata(error));
      return res.status(500).json({ error: 'Failed to remove role member' });
    }
  }

  return {
    listRoles: listRolesHandler,
    getRole: getRoleHandler,
    createRole: createRoleHandler,
    updateRole: updateRoleHandler,
    updateRolePermissions: updateRolePermissionsHandler,
    deleteRole: deleteRoleHandler,
    getRoleMembers: getRoleMembersHandler,
    addRoleMember: addRoleMemberHandler,
    removeRoleMember: removeRoleMemberHandler,
  };
}

export interface RolePermissionsUpdateDeps {
  getRoleByName: (name: string, fields?: string | string[] | null) => Promise<IRole | null>;
  updateRoleByName: (name: string, updates: Partial<IRole>) => Promise<IRole | null>;
  recordAuditEntry?: RecordAuditEntry;
  /** When true, a failed audit write surfaces as a 5xx after the update has
   * been persisted. Defaults to fail-open. */
  auditFailClosed?: boolean;
}

export interface RolePermissionsUpdateConfig {
  /** Zod object schema for one permission type; parsed as a partial update without its defaults. */
  schema: z.ZodObject<Record<string, z.ZodType<boolean, boolean | undefined>>>;
  permissionType: string;
  errorMessage: string;
}

/**
 * Builds the `PUT /api/roles/:roleName/<type>` handler for one permission type:
 * merges the validated partial update into the role's permissions and records
 * a `role.permissions_updated` audit entry when a flag actually changed.
 */
export function createRolePermissionsUpdateHandler(
  deps: RolePermissionsUpdateDeps,
  config: RolePermissionsUpdateConfig,
): (req: ServerRequest, res: Response) => Promise<Response> {
  const { getRoleByName, updateRoleByName, recordAuditEntry, auditFailClosed } = deps;
  const emitAudit = createAdminAuditEmitter({
    recordAuditEntry,
    failClosed: auditFailClosed,
    logPrefix: '[roles]',
  });

  return async function updateRolePermissions(req, res) {
    const { roleName } = req.params as { roleName: string };
    const parsed = partialWithoutDefaults(config.schema).safeParse(req.body);
    if (!parsed.success) {
      return res.status(400).send({ message: config.errorMessage, error: parsed.error.issues });
    }
    const parsedUpdates: Record<string, boolean | undefined> = parsed.data;

    try {
      const role = await getRoleByName(roleName);
      if (!role) {
        return res.status(404).send({ message: 'Role not found' });
      }

      const permissions = (role.permissions ?? {}) as Record<
        string,
        Record<string, boolean | undefined> | undefined
      >;
      const legacyPermissions = (role as unknown as Record<string, unknown>)[
        config.permissionType
      ] as Record<string, boolean | undefined> | undefined;
      const currentPermissions = permissions[config.permissionType] || legacyPermissions || {};

      const mergedPermissions = {
        ...permissions,
        [config.permissionType]: { ...currentPermissions, ...parsedUpdates },
      };
      const updatedRole = await updateRoleByName(roleName, {
        permissions: mergedPermissions as IRole['permissions'],
      });

      const changes = diffRolePermissions(
        { [config.permissionType]: currentPermissions },
        { [config.permissionType]: mergedPermissions[config.permissionType] },
      );
      if (updatedRole && changes.length > 0) {
        await emitAudit(req, {
          action: 'role.permissions_updated',
          severity: 'warning',
          target: roleTarget(roleName),
          metadata: { changes: changes.join(', '), changeCount: changes.length },
        });
      }
      return res.status(200).send(updatedRole);
    } catch (error) {
      logger.error(
        `[roles] ${config.permissionType} permission update failed:`,
        getSafeErrorMetadata(error),
      );
      return res.status(500).send({ message: 'Failed to update role permissions' });
    }
  };
}